antlr.v4.runtime.Vocabulary source code

1 /*
2  * [The "BSD license"]
3  *  Copyright (c) 2016 Terence Parr
4  *  Copyright (c) 2016 Sam Harwell
5  *  All rights reserved.
6  *
7  *  Redistribution and use in source and binary forms, with or without
8  *  modification, are permitted provided that the following conditions
9  *  are met:
10  *
11  *  1. Redistributions of source code must retain the above copyright
12  *     notice, this list of conditions and the following disclaimer.
13  *  2. Redistributions in binary form must reproduce the above copyright
14  *     notice, this list of conditions and the following disclaimer in the
15  *     documentation and/or other materials provided with the distribution.
16  *  3. The name of the author may not be used to endorse or promote products
17  *     derived from this software without specific prior written permission.
18  *
19  *  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
20  *  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21  *  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22  *  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
23  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24  *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28  *  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 
31 module antlr.v4.runtime.Vocabulary;
32 
33 /**
34  * @uml
35  * This interface provides information about the vocabulary used by a
36  * ecognizer.
37  *
38  *  @see Recognizer#getVocabulary()
39  *  @author Sam Harwell
40  */
41 interface Vocabulary
42 {
43 
44     /**
45      * @uml
46      * Returns the highest token type value. It can be used to iterate from
47      * zero to that number, inclusively, thus querying all stored entries.
48      *  @return the highest token type value
49      */
50     public int getMaxTokenType();
51 
52     /**
53      * @uml
54      * Gets the string literal associated with a token type. The string returned
55      * by this method, when not {@code null}, can be used unaltered in a parser
56      * grammar to represent this token type.
57      *
58      * <p>The following table shows examples of lexer rules and the literal
59      * names assigned to the corresponding token types.</p>
60      *
61      * <table>
62      *  <tr>
63      *   <th>Rule</th>
64      *   <th>Literal Name</th>
65      *   <th>Java String Literal</th>
66      *  </tr>
67      *  <tr>
68      *   <td>{@code THIS : 'this';}</td>
69      *   <td>{@code 'this'}</td>
70      *   <td>{@code "'this'"}</td>
71      *  </tr>
72      *  <tr>
73      *   <td>{@code SQUOTE : '\'';}</td>
74      *   <td>{@code '\''}</td>
75      *   <td>{@code "'\\''"}</td>
76      *  </tr>
77      *  <tr>
78      *   <td>{@code ID : [A-Z]+;}</td>
79      *   <td>n/a</td>
80      *   <td>{@code null}</td>
81      *  </tr>
82      * </table>
83      *
84      *  @param tokenType The token type.
85      *
86      *  @return The string literal associated with the specified token type, or
87      *  {@code null} if no string literal is associated with the type.
88      */
89     public string getLiteralName(int tokenType);
90 
91     /**
92      * @uml
93      * Gets the symbolic name associated with a token type. The string returned
94      * by this method, when not {@code null}, can be used unaltered in a parser
95      * grammar to represent this token type.
96      *
97      * <p>This method supports token types defined by any of the following
98      * methods:</p>
99      *
100      * <ul>
101      *  <li>Tokens created by lexer rules.</li>
102      *  <li>Tokens defined in a <code>tokens{}</code> block in a lexer or parser
103      *  grammar.</li>
104      *  <li>The implicitly defined {@code EOF} token, which has the token type
105      *  {@link Token#EOF}.</li>
106      * </ul>
107      *          *
108      * <p>The following table shows examples of lexer rules and the literal
109      * names assigned to the corresponding token types.</p>
110      *
111      * <table>
112      *  <tr>
113      *   <th>Rule</th>
114      *   <th>Symbolic Name</th>
115      *  </tr>
116      *  <tr>
117      *   <td>{@code THIS : 'this';}</td>
118      *   <td>{@code THIS}</td>
119      *  </tr>
120      *  <tr>
121      *   <td>{@code SQUOTE : '\'';}</td>
122      *   <td>{@code SQUOTE}</td>
123      *  </tr>
124      *  <tr>
125      *   <td>{@code ID : [A-Z]+;}</td>
126      *   <td>{@code ID}</td>
127      *  </tr>
128      * </table>
129      *
130      *  @param tokenType The token type.
131      *
132      *  @return The symbolic name associated with the specified token type, or
133      *  {@code null} if no symbolic name is associated with the type.
134      */
135     public string getSymbolicName(int tokenType);
136 
137     /**
138      * @uml
139      * Gets the display name of a token type.
140      *
141      * <p>ANTLR provides a default implementation of this method, but
142      * applications are free to override the behavior in any manner which makes
143      * sense for the application. The default implementation returns the first
144      * result from the following list which produces a non-{@code null}
145      * result.</p>
146      *
147      * <ol>
148      * <li>The result of {@link #getLiteralName}</li>
149      * <li>The result of {@link #getSymbolicName}</li>
150      * <li>The result of {@link Integer#toString}</li>
151      * </ol>
152      *
153      *  @param tokenType The token type.
154      *
155      *  @return The display name of the token type, for use in error reporting or
156      *  other user-visible messages which reference specific token types.
157      */
158     public string getDisplayName(int tokenType);
159 
160 }