gitweb.ps.run Git - toc/blob - antlr4-cpp-runtime-4.9.2-source/runtime/src/Vocabulary.h

   1 /* Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
   2  * Use of this file is governed by the BSD 3-clause license that
   3  * can be found in the LICENSE.txt file in the project root.
   4  */
   5
   6 #pragma once
   7
   8 #include "antlr4-common.h"
   9
  10 namespace antlr4 {
  11 namespace dfa {
  12
  13   /// This class provides a default implementation of the <seealso cref="Vocabulary"/>
  14   /// interface.
  15   class ANTLR4CPP_PUBLIC Vocabulary {
  16   public:
  17     /// Gets an empty <seealso cref="Vocabulary"/> instance.
  18     ///
  19     /// <para>
  20     /// No literal or symbol names are assigned to token types, so
  21     /// <seealso cref="#getDisplayName(int)"/> returns the numeric value for all tokens
  22     /// except <seealso cref="Token#EOF"/>.</para>
  23     static const Vocabulary EMPTY_VOCABULARY;
  24
  25     Vocabulary() {}
  26     Vocabulary(Vocabulary const&) = default;
  27     virtual ~Vocabulary();
  28
  29     /// <summary>
  30     /// Constructs a new instance of <seealso cref="Vocabulary"/> from the specified
  31     /// literal and symbolic token names.
  32     /// </summary>
  33     /// <param name="literalNames"> The literal names assigned to tokens, or {@code null}
  34     /// if no literal names are assigned. </param>
  35     /// <param name="symbolicNames"> The symbolic names assigned to tokens, or
  36     /// {@code null} if no symbolic names are assigned.
  37     /// </param>
  38     /// <seealso cref= #getLiteralName(int) </seealso>
  39     /// <seealso cref= #getSymbolicName(int) </seealso>
  40     Vocabulary(const std::vector<std::string> &literalNames, const std::vector<std::string> &symbolicNames);
  41
  42     /// <summary>
  43     /// Constructs a new instance of <seealso cref="Vocabulary"/> from the specified
  44     /// literal, symbolic, and display token names.
  45     /// </summary>
  46     /// <param name="literalNames"> The literal names assigned to tokens, or {@code null}
  47     /// if no literal names are assigned. </param>
  48     /// <param name="symbolicNames"> The symbolic names assigned to tokens, or
  49     /// {@code null} if no symbolic names are assigned. </param>
  50     /// <param name="displayNames"> The display names assigned to tokens, or {@code null}
  51     /// to use the values in {@code literalNames} and {@code symbolicNames} as
  52     /// the source of display names, as described in
  53     /// <seealso cref="#getDisplayName(int)"/>.
  54     /// </param>
  55     /// <seealso cref= #getLiteralName(int) </seealso>
  56     /// <seealso cref= #getSymbolicName(int) </seealso>
  57     /// <seealso cref= #getDisplayName(int) </seealso>
  58     Vocabulary(const std::vector<std::string> &literalNames, const std::vector<std::string> &symbolicNames,
  59                    const std::vector<std::string> &displayNames);
  60
  61     /// <summary>
  62     /// Returns a <seealso cref="Vocabulary"/> instance from the specified set of token
  63     /// names. This method acts as a compatibility layer for the single
  64     /// {@code tokenNames} array generated by previous releases of ANTLR.
  65     ///
  66     /// <para>The resulting vocabulary instance returns {@code null} for
  67     /// <seealso cref="#getLiteralName(int)"/> and <seealso cref="#getSymbolicName(int)"/>, and the
  68     /// value from {@code tokenNames} for the display names.</para>
  69     /// </summary>
  70     /// <param name="tokenNames"> The token names, or {@code null} if no token names are
  71     /// available. </param>
  72     /// <returns> A <seealso cref="Vocabulary"/> instance which uses {@code tokenNames} for
  73     /// the display names of tokens. </returns>
  74     static Vocabulary fromTokenNames(const std::vector<std::string> &tokenNames);
  75
  76     /// <summary>
  77     /// Returns the highest token type value. It can be used to iterate from
  78     /// zero to that number, inclusively, thus querying all stored entries. </summary>
  79     /// <returns> the highest token type value </returns>
  80     virtual size_t getMaxTokenType() const;
  81
  82     /// <summary>
  83     /// Gets the string literal associated with a token type. The string returned
  84     /// by this method, when not {@code null}, can be used unaltered in a parser
  85     /// grammar to represent this token type.
  86     ///
  87     /// <para>The following table shows examples of lexer rules and the literal
  88     /// names assigned to the corresponding token types.</para>
  89     ///
  90     /// <table>
  91     ///  <tr>
  92     ///   <th>Rule</th>
  93     ///   <th>Literal Name</th>
  94     ///   <th>Java String Literal</th>
  95     ///  </tr>
  96     ///  <tr>
  97     ///   <td>{@code THIS : 'this';}</td>
  98     ///   <td>{@code 'this'}</td>
  99     ///   <td>{@code "'this'"}</td>
 100     ///  </tr>
 101     ///  <tr>
 102     ///   <td>{@code SQUOTE : '\'';}</td>
 103     ///   <td>{@code '\''}</td>
 104     ///   <td>{@code "'\\''"}</td>
 105     ///  </tr>
 106     ///  <tr>
 107     ///   <td>{@code ID : [A-Z]+;}</td>
 108     ///   <td>n/a</td>
 109     ///   <td>{@code null}</td>
 110     ///  </tr>
 111     /// </table>
 112     /// </summary>
 113     /// <param name="tokenType"> The token type.
 114     /// </param>
 115     /// <returns> The string literal associated with the specified token type, or
 116     /// {@code null} if no string literal is associated with the type. </returns>
 117     virtual std::string getLiteralName(size_t tokenType) const;
 118
 119     /// <summary>
 120     /// Gets the symbolic name associated with a token type. The string returned
 121     /// by this method, when not {@code null}, can be used unaltered in a parser
 122     /// grammar to represent this token type.
 123     ///
 124     /// <para>This method supports token types defined by any of the following
 125     /// methods:</para>
 126     ///
 127     /// <ul>
 128     ///  <li>Tokens created by lexer rules.</li>
 129     ///  <li>Tokens defined in a <code>tokens{}</code> block in a lexer or parser
 130     ///  grammar.</li>
 131     ///  <li>The implicitly defined {@code EOF} token, which has the token type
 132     ///  <seealso cref="Token#EOF"/>.</li>
 133     /// </ul>
 134     ///
 135     /// <para>The following table shows examples of lexer rules and the literal
 136     /// names assigned to the corresponding token types.</para>
 137     ///
 138     /// <table>
 139     ///  <tr>
 140     ///   <th>Rule</th>
 141     ///   <th>Symbolic Name</th>
 142     ///  </tr>
 143     ///  <tr>
 144     ///   <td>{@code THIS : 'this';}</td>
 145     ///   <td>{@code THIS}</td>
 146     ///  </tr>
 147     ///  <tr>
 148     ///   <td>{@code SQUOTE : '\'';}</td>
 149     ///   <td>{@code SQUOTE}</td>
 150     ///  </tr>
 151     ///  <tr>
 152     ///   <td>{@code ID : [A-Z]+;}</td>
 153     ///   <td>{@code ID}</td>
 154     ///  </tr>
 155     /// </table>
 156     /// </summary>
 157     /// <param name="tokenType"> The token type.
 158     /// </param>
 159     /// <returns> The symbolic name associated with the specified token type, or
 160     /// {@code null} if no symbolic name is associated with the type. </returns>
 161     virtual std::string getSymbolicName(size_t tokenType) const;
 162
 163     /// <summary>
 164     /// Gets the display name of a token type.
 165     ///
 166     /// <para>ANTLR provides a default implementation of this method, but
 167     /// applications are free to override the behavior in any manner which makes
 168     /// sense for the application. The default implementation returns the first
 169     /// result from the following list which produces a non-{@code null}
 170     /// result.</para>
 171     ///
 172     /// <ol>
 173     ///  <li>The result of <seealso cref="#getLiteralName"/></li>
 174     ///  <li>The result of <seealso cref="#getSymbolicName"/></li>
 175     ///  <li>The result of <seealso cref="Integer#toString"/></li>
 176     /// </ol>
 177     /// </summary>
 178     /// <param name="tokenType"> The token type.
 179     /// </param>
 180     /// <returns> The display name of the token type, for use in error reporting or
 181     /// other user-visible messages which reference specific token types. </returns>
 182     virtual std::string getDisplayName(size_t tokenType) const;
 183
 184   private:
 185     std::vector<std::string> const _literalNames;
 186     std::vector<std::string> const _symbolicNames;
 187     std::vector<std::string> const _displayNames;
 188     const size_t _maxTokenType = 0;
 189   };
 190
 191 } // namespace atn
 192 } // namespace antlr4