1<?php
2
3declare(strict_types=1);
4
5namespace Antlr\Antlr4\Runtime;
6
7/**
8 * This interface provides information about the vocabulary used by a
9 * recognizer.
10 *
11 * @see Recognizer::getVocabulary()
12 */
13interface Vocabulary
14{
15    /**
16     * Returns the highest token type value. It can be used to iterate from zero
17     * to that number, inclusively, thus querying all stored entries.
18     *
19     * @return int The highest token type value.
20     */
21    public function getMaxTokenType() : int;
22
23    /**
24     * Gets the string literal associated with a token type. The string returned
25     * by this method, when not `null`, can be used unaltered in a parser grammar
26     * to represent this token type.
27     *
28     * The following table shows examples of lexer rules and the literal names
29     * assigned to the corresponding token types.
30     *
31     * Rule             | Literal Name | Java String Literal
32     * -----------------|--------------|---------------------
33     * `THIS : 'this';` | `'this'`     | `"'this'"`
34     * `SQUOTE : '\'';` | `'\''`       | `"'\\''"`
35     * `ID : [A-Z]+;`   | n/a          | `null`
36     *
37     * @param int $tokenType The token type.
38     *
39     * @return string The string literal associated with the specified token type,
40     *                or `null` if no string literal is associated with the type.
41     */
42    public function getLiteralName(int $tokenType) : ?string;
43
44    /**
45     * Gets the symbolic name associated with a token type. The string returned
46     * by this method, when not `null`, can be used unaltered in a parser grammar
47     * to represent this token type.
48     *
49     * This method supports token types defined by any of the following methods:
50     *
51     * - Tokens created by lexer rules.
52     * - Tokens defined in a `tokens{}` block in a lexer or parser grammar.
53     * - The implicitly defined `EOF` token, which has the token type {@see Token::EOF()}.
54     *
55     * The following table shows examples of lexer rules and the literal names
56     * assigned to the corresponding token types.
57     *
58     * Rule             | Symbolic Name
59     * -----------------|--------------
60     * `THIS : 'this';` | `THIS`
61     * `SQUOTE : '\'';` | `SQUOTE`
62     * `ID : [A-Z]+;`   | `ID`
63     *
64     * @param int $tokenType The token type.
65     *
66     * @return string The symbolic name associated with the specified token type,
67     *                or `null` if no symbolic name is associated with the type.
68     */
69    public function getSymbolicName(int $tokenType) : ?string;
70
71    /**
72     * Gets the display name of a token type.
73     *
74     * ANTLR provides a default implementation of this method, but applications
75     * are free to override the behavior in any manner which makes sense
76     * for the application. The default implementation returns the first result
77     * from the following list which produces a non-null result.
78     *
79     * @param int $tokenType The token type.
80     *
81     * @return string The display name of the token type, for use in
82     *                error reporting or other user-visible messages
83     *                which reference specific token types.
84     */
85    public function getDisplayName(int $tokenType) : string;
86}
87