gitweb.ps.run Git - toc/blob - antlr4-cpp-runtime-4.9.2-source/runtime/src/TokenSource.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 "TokenFactory.h"
   9
  10 namespace antlr4 {
  11
  12   /// <summary>
  13   /// A source of tokens must provide a sequence of tokens via <seealso cref="#nextToken()"/>
  14   /// and also must reveal it's source of characters; <seealso cref="CommonToken"/>'s text is
  15   /// computed from a <seealso cref="CharStream"/>; it only store indices into the char
  16   /// stream.
  17   /// <p/>
  18   /// Errors from the lexer are never passed to the parser. Either you want to keep
  19   /// going or you do not upon token recognition error. If you do not want to
  20   /// continue lexing then you do not want to continue parsing. Just throw an
  21   /// exception not under <seealso cref="RecognitionException"/> and Java will naturally toss
  22   /// you all the way out of the recognizers. If you want to continue lexing then
  23   /// you should not throw an exception to the parser--it has already requested a
  24   /// token. Keep lexing until you get a valid one. Just report errors and keep
  25   /// going, looking for a valid token.
  26   /// </summary>
  27   class ANTLR4CPP_PUBLIC TokenSource {
  28   public:
  29     virtual ~TokenSource();
  30
  31     /// Return a <seealso cref="Token"/> object from your input stream (usually a
  32     /// <seealso cref="CharStream"/>). Do not fail/return upon lexing error; keep chewing
  33     /// on the characters until you get a good one; errors are not passed through
  34     /// to the parser.
  35     virtual std::unique_ptr<Token> nextToken() = 0;
  36
  37     /// <summary>
  38     /// Get the line number for the current position in the input stream. The
  39     /// first line in the input is line 1.
  40     /// </summary>
  41     /// <returns> The line number for the current position in the input stream, or
  42     /// 0 if the current token source does not track line numbers. </returns>
  43     virtual size_t getLine() const = 0;
  44
  45     /// <summary>
  46     /// Get the index into the current line for the current position in the input
  47     /// stream. The first character on a line has position 0.
  48     /// </summary>
  49     /// <returns> The line number for the current position in the input stream, or
  50     /// (sze_t)-1 if the current token source does not track character positions. </returns>
  51     virtual size_t getCharPositionInLine() = 0;
  52
  53     /// <summary>
  54     /// Get the <seealso cref="CharStream"/> from which this token source is currently
  55     /// providing tokens.
  56     /// </summary>
  57     /// <returns> The <seealso cref="CharStream"/> associated with the current position in
  58     /// the input, or {@code null} if no input stream is available for the token
  59     /// source. </returns>
  60     virtual CharStream* getInputStream() = 0;
  61
  62     /// <summary>
  63     /// Gets the name of the underlying input source. This method returns a
  64     /// non-null, non-empty string. If such a name is not known, this method
  65     /// returns <seealso cref="IntStream#UNKNOWN_SOURCE_NAME"/>.
  66     /// </summary>
  67     virtual std::string getSourceName() = 0;
  68
  69     /// <summary>
  70     /// Set the <seealso cref="TokenFactory"/> this token source should use for creating
  71     /// <seealso cref="Token"/> objects from the input.
  72     /// </summary>
  73     /// <param name="factory"> The <seealso cref="TokenFactory"/> to use for creating tokens. </param>
  74     template<typename T1>
  75     void setTokenFactory(TokenFactory<T1> * /*factory*/) {}
  76
  77     /// <summary>
  78     /// Gets the <seealso cref="TokenFactory"/> this token source is currently using for
  79     /// creating <seealso cref="Token"/> objects from the input.
  80     /// </summary>
  81     /// <returns> The <seealso cref="TokenFactory"/> currently used by this token source. </returns>
  82     virtual TokenFactory<CommonToken>* getTokenFactory() = 0;
  83   };
  84
  85 } // namespace antlr4