gitweb.ps.run Git - toc/blob - antlr4-cpp-runtime-4.9.2-source/runtime/src/TokenStream.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 "IntStream.h"
   9
  10 namespace antlr4 {
  11
  12   /// <summary>
  13   /// An <seealso cref="IntStream"/> whose symbols are <seealso cref="Token"/> instances.
  14   /// </summary>
  15   class ANTLR4CPP_PUBLIC TokenStream : public IntStream {
  16     /// <summary>
  17     /// Get the <seealso cref="Token"/> instance associated with the value returned by
  18     /// <seealso cref="#LA LA(k)"/>. This method has the same pre- and post-conditions as
  19     /// <seealso cref="IntStream#LA"/>. In addition, when the preconditions of this method
  20     /// are met, the return value is non-null and the value of
  21     /// {@code LT(k).getType()==LA(k)}.
  22     /// </summary>
  23     /// <seealso cref= IntStream#LA </seealso>
  24   public:
  25     virtual ~TokenStream();
  26
  27     virtual Token* LT(ssize_t k) = 0;
  28
  29     /// <summary>
  30     /// Gets the <seealso cref="Token"/> at the specified {@code index} in the stream. When
  31     /// the preconditions of this method are met, the return value is non-null.
  32     /// <p/>
  33     /// The preconditions for this method are the same as the preconditions of
  34     /// <seealso cref="IntStream#seek"/>. If the behavior of {@code seek(index)} is
  35     /// unspecified for the current state and given {@code index}, then the
  36     /// behavior of this method is also unspecified.
  37     /// <p/>
  38     /// The symbol referred to by {@code index} differs from {@code seek()} only
  39     /// in the case of filtering streams where {@code index} lies before the end
  40     /// of the stream. Unlike {@code seek()}, this method does not adjust
  41     /// {@code index} to point to a non-ignored symbol.
  42     /// </summary>
  43     /// <exception cref="IllegalArgumentException"> if {code index} is less than 0 </exception>
  44     /// <exception cref="UnsupportedOperationException"> if the stream does not support
  45     /// retrieving the token at the specified index </exception>
  46     virtual Token* get(size_t index) const = 0;
  47
  48     /// Gets the underlying TokenSource which provides tokens for this stream.
  49     virtual TokenSource* getTokenSource() const = 0;
  50
  51     /// <summary>
  52     /// Return the text of all tokens within the specified {@code interval}. This
  53     /// method behaves like the following code (including potential exceptions
  54     /// for violating preconditions of <seealso cref="#get"/>, but may be optimized by the
  55     /// specific implementation.
  56     ///
  57     /// <pre>
  58     /// TokenStream stream = ...;
  59     /// String text = "";
  60     /// for (int i = interval.a; i <= interval.b; i++) {
  61     ///   text += stream.get(i).getText();
  62     /// }
  63     /// </pre>
  64     /// </summary>
  65     /// <param name="interval"> The interval of tokens within this stream to get text
  66     /// for. </param>
  67     /// <returns> The text of all tokens within the specified interval in this
  68     /// stream.
  69     /// </returns>
  70     /// <exception cref="NullPointerException"> if {@code interval} is {@code null} </exception>
  71     virtual std::string getText(const misc::Interval &interval) = 0;
  72
  73     /// <summary>
  74     /// Return the text of all tokens in the stream. This method behaves like the
  75     /// following code, including potential exceptions from the calls to
  76     /// <seealso cref="IntStream#size"/> and <seealso cref="#getText(Interval)"/>, but may be
  77     /// optimized by the specific implementation.
  78     ///
  79     /// <pre>
  80     /// TokenStream stream = ...;
  81     /// String text = stream.getText(new Interval(0, stream.size()));
  82     /// </pre>
  83     /// </summary>
  84     /// <returns> The text of all tokens in the stream. </returns>
  85     virtual std::string getText() = 0;
  86
  87     /// <summary>
  88     /// Return the text of all tokens in the source interval of the specified
  89     /// context. This method behaves like the following code, including potential
  90     /// exceptions from the call to <seealso cref="#getText(Interval)"/>, but may be
  91     /// optimized by the specific implementation.
  92     /// </p>
  93     /// If {@code ctx.getSourceInterval()} does not return a valid interval of
  94     /// tokens provided by this stream, the behavior is unspecified.
  95     ///
  96     /// <pre>
  97     /// TokenStream stream = ...;
  98     /// String text = stream.getText(ctx.getSourceInterval());
  99     /// </pre>
 100     /// </summary>
 101     /// <param name="ctx"> The context providing the source interval of tokens to get
 102     /// text for. </param>
 103     /// <returns> The text of all tokens within the source interval of {@code ctx}. </returns>
 104     virtual std::string getText(RuleContext *ctx) = 0;
 105
 106     /// <summary>
 107     /// Return the text of all tokens in this stream between {@code start} and
 108     /// {@code stop} (inclusive).
 109     /// <p/>
 110     /// If the specified {@code start} or {@code stop} token was not provided by
 111     /// this stream, or if the {@code stop} occurred before the {@code start}
 112     /// token, the behavior is unspecified.
 113     /// <p/>
 114     /// For streams which ensure that the <seealso cref="Token#getTokenIndex"/> method is
 115     /// accurate for all of its provided tokens, this method behaves like the
 116     /// following code. Other streams may implement this method in other ways
 117     /// provided the behavior is consistent with this at a high level.
 118     ///
 119     /// <pre>
 120     /// TokenStream stream = ...;
 121     /// String text = "";
 122     /// for (int i = start.getTokenIndex(); i <= stop.getTokenIndex(); i++) {
 123     ///   text += stream.get(i).getText();
 124     /// }
 125     /// </pre>
 126     /// </summary>
 127     /// <param name="start"> The first token in the interval to get text for. </param>
 128     /// <param name="stop"> The last token in the interval to get text for (inclusive). </param>
 129     /// <returns> The text of all tokens lying between the specified {@code start}
 130     /// and {@code stop} tokens.
 131     /// </returns>
 132     /// <exception cref="UnsupportedOperationException"> if this stream does not support
 133     /// this method for the specified tokens </exception>
 134     virtual std::string getText(Token *start, Token *stop) = 0;
 135   };
 136
 137 } // namespace antlr4