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 // Interface Vocabulary
34 /**
35  * @uml
36  * This interface provides information about the vocabulary used by a
37  * ecognizer.
38  *
39  *  @see Recognizer#getVocabulary()
40  *  @author Sam Harwell
41  */
42 interface Vocabulary
43 {
44 
45     /**
46      * @uml
47      * Returns the highest token type value. It can be used to iterate from
48      * zero to that number, inclusively, thus querying all stored entries.
49      *  @return the highest token type value
50      */
51     public int getMaxTokenType();
52 
53     /**
54      * @uml
55      * Gets the string literal associated with a token type. The string returned
56      * by this method, when not {@code null}, can be used unaltered in a parser
57      * grammar to represent this token type.
58      *
59      * <p>The following table shows examples of lexer rules and the literal
60      * names assigned to the corresponding token types.</p>
61      *
62      * <table>
63      *  <tr>
64      *   <th>Rule</th>
65      *   <th>Literal Name</th>
66      *   <th>Java String Literal</th>
67      *  </tr>
68      *  <tr>
69      *   <td>{@code THIS : 'this';}</td>
70      *   <td>{@code 'this'}</td>
71      *   <td>{@code "'this'"}</td>
72      *  </tr>
73      *  <tr>
74      *   <td>{@code SQUOTE : '\'';}</td>
75      *   <td>{@code '\''}</td>
76      *   <td>{@code "'\\''"}</td>
77      *  </tr>
78      *  <tr>
79      *   <td>{@code ID : [A-Z]+;}</td>
80      *   <td>n/a</td>
81      *   <td>{@code null}</td>
82      *  </tr>
83      * </table>
84      *
85      *  @param tokenType The token type.
86      *
87      *  @return The string literal associated with the specified token type, or
88      *  {@code null} if no string literal is associated with the type.
89      */
90     public string getLiteralName(int tokenType);
91 
92     /**
93      * @uml
94      * Gets the symbolic name associated with a token type. The string returned
95      * by this method, when not {@code null}, can be used unaltered in a parser
96      * grammar to represent this token type.
97      *
98      * <p>This method supports token types defined by any of the following
99      * methods:</p>
100      *
101      * <ul>
102      *  <li>Tokens created by lexer rules.</li>
103      *  <li>Tokens defined in a <code>tokens{}</code> block in a lexer or parser
104      *  grammar.</li>
105      *  <li>The implicitly defined {@code EOF} token, which has the token type
106      *  {@link Token#EOF}.</li>
107      * </ul>
108      *          *
109      * <p>The following table shows examples of lexer rules and the literal
110      * names assigned to the corresponding token types.</p>
111      *
112      * <table>
113      *  <tr>
114      *   <th>Rule</th>
115      *   <th>Symbolic Name</th>
116      *  </tr>
117      *  <tr>
118      *   <td>{@code THIS : 'this';}</td>
119      *   <td>{@code THIS}</td>
120      *  </tr>
121      *  <tr>
122      *   <td>{@code SQUOTE : '\'';}</td>
123      *   <td>{@code SQUOTE}</td>
124      *  </tr>
125      *  <tr>
126      *   <td>{@code ID : [A-Z]+;}</td>
127      *   <td>{@code ID}</td>
128      *  </tr>
129      * </table>
130      *
131      *  @param tokenType The token type.
132      *
133      *  @return The symbolic name associated with the specified token type, or
134      *  {@code null} if no symbolic name is associated with the type.
135      */
136     public string getSymbolicName(int tokenType);
137 
138     /**
139      * @uml
140      * Gets the display name of a token type.
141      *
142      * <p>ANTLR provides a default implementation of this method, but
143      * applications are free to override the behavior in any manner which makes
144      * sense for the application. The default implementation returns the first
145      * result from the following list which produces a non-{@code null}
146      * result.</p>
147      *
148      * <ol>
149      * <li>The result of {@link #getLiteralName}</li>
150      * <li>The result of {@link #getSymbolicName}</li>
151      * <li>The result of {@link Integer#toString}</li>
152      * </ol>
153      *
154      *  @param tokenType The token type.
155      *
156      *  @return The display name of the token type, for use in error reporting or
157      *  other user-visible messages which reference specific token types.
158      */
159     public string getDisplayName(int tokenType);
160 
161 }