gitweb.ps.run Git - toc/blob - antlr4-cpp-runtime-4.9.2-source/runtime/src/IntStream.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
  12   /// <summary>
  13   /// A simple stream of symbols whose values are represented as integers. This
  14   /// interface provides <em>marked ranges</em> with support for a minimum level
  15   /// of buffering necessary to implement arbitrary lookahead during prediction.
  16   /// For more information on marked ranges, see <seealso cref="#mark"/>.
  17   /// <p/>
  18   /// <strong>Initializing Methods:</strong> Some methods in this interface have
  19   /// unspecified behavior if no call to an initializing method has occurred after
  20   /// the stream was constructed. The following is a list of initializing methods:
  21   ///
  22   /// <ul>
  23   ///   <li><seealso cref="#LA"/></li>
  24   ///   <li><seealso cref="#consume"/></li>
  25   ///   <li><seealso cref="#size"/></li>
  26   /// </ul>
  27   /// </summary>
  28   class ANTLR4CPP_PUBLIC IntStream {
  29   public:
  30 #if __cplusplus >= 201703L
  31     static constexpr size_t EOF = std::numeric_limits<size_t>::max();
  32 #else
  33     enum : size_t {
  34       EOF = static_cast<size_t>(-1), // std::numeric_limits<size_t>::max(); doesn't work in VS 2013
  35     };
  36 #endif
  37
  38     /// The value returned by <seealso cref="#LA LA()"/> when the end of the stream is
  39     /// reached.
  40     /// No explicit EOF definition. We got EOF on all platforms.
  41     //static const size_t _EOF = std::ios::eofbit;
  42
  43     /// <summary>
  44     /// The value returned by <seealso cref="#getSourceName"/> when the actual name of the
  45     /// underlying source is not known.
  46     /// </summary>
  47     static const std::string UNKNOWN_SOURCE_NAME;
  48
  49     virtual ~IntStream();
  50
  51     /// <summary>
  52     /// Consumes the current symbol in the stream. This method has the following
  53     /// effects:
  54     ///
  55     /// <ul>
  56     ///   <li><strong>Forward movement:</strong> The value of <seealso cref="#index index()"/>
  57     ///         before calling this method is less than the value of {@code index()}
  58     ///         after calling this method.</li>
  59     ///   <li><strong>Ordered lookahead:</strong> The value of {@code LA(1)} before
  60     ///         calling this method becomes the value of {@code LA(-1)} after calling
  61     ///         this method.</li>
  62     /// </ul>
  63     ///
  64     /// Note that calling this method does not guarantee that {@code index()} is
  65     /// incremented by exactly 1, as that would preclude the ability to implement
  66     /// filtering streams (e.g. <seealso cref="CommonTokenStream"/> which distinguishes
  67     /// between "on-channel" and "off-channel" tokens).
  68     /// </summary>
  69     /// <exception cref="IllegalStateException"> if an attempt is made to consume the the
  70     /// end of the stream (i.e. if {@code LA(1)==}<seealso cref="#EOF EOF"/> before calling
  71     /// {@code consume}). </exception>
  72     virtual void consume() = 0;
  73
  74     /// <summary>
  75     /// Gets the value of the symbol at offset {@code i} from the current
  76     /// position. When {@code i==1}, this method returns the value of the current
  77     /// symbol in the stream (which is the next symbol to be consumed). When
  78     /// {@code i==-1}, this method returns the value of the previously read
  79     /// symbol in the stream. It is not valid to call this method with
  80     /// {@code i==0}, but the specific behavior is unspecified because this
  81     /// method is frequently called from performance-critical code.
  82     /// <p/>
  83     /// This method is guaranteed to succeed if any of the following are true:
  84     ///
  85     /// <ul>
  86     ///   <li>{@code i>0}</li>
  87     ///   <li>{@code i==-1} and <seealso cref="#index index()"/> returns a value greater
  88     ///     than the value of {@code index()} after the stream was constructed
  89     ///     and {@code LA(1)} was called in that order. Specifying the current
  90     ///     {@code index()} relative to the index after the stream was created
  91     ///     allows for filtering implementations that do not return every symbol
  92     ///     from the underlying source. Specifying the call to {@code LA(1)}
  93     ///     allows for lazily initialized streams.</li>
  94     ///   <li>{@code LA(i)} refers to a symbol consumed within a marked region
  95     ///     that has not yet been released.</li>
  96     /// </ul>
  97     ///
  98     /// If {@code i} represents a position at or beyond the end of the stream,
  99     /// this method returns <seealso cref="#EOF"/>.
 100     /// <p/>
 101     /// The return value is unspecified if {@code i<0} and fewer than {@code -i}
 102     /// calls to <seealso cref="#consume consume()"/> have occurred from the beginning of
 103     /// the stream before calling this method.
 104     /// </summary>
 105     /// <exception cref="UnsupportedOperationException"> if the stream does not support
 106     /// retrieving the value of the specified symbol </exception>
 107     virtual size_t LA(ssize_t i) = 0;
 108
 109     /// <summary>
 110     /// A mark provides a guarantee that <seealso cref="#seek seek()"/> operations will be
 111     /// valid over a "marked range" extending from the index where {@code mark()}
 112     /// was called to the current <seealso cref="#index index()"/>. This allows the use of
 113     /// streaming input sources by specifying the minimum buffering requirements
 114     /// to support arbitrary lookahead during prediction.
 115     /// <p/>
 116     /// The returned mark is an opaque handle (type {@code int}) which is passed
 117     /// to <seealso cref="#release release()"/> when the guarantees provided by the marked
 118     /// range are no longer necessary. When calls to
 119     /// {@code mark()}/{@code release()} are nested, the marks must be released
 120     /// in reverse order of which they were obtained. Since marked regions are
 121     /// used during performance-critical sections of prediction, the specific
 122     /// behavior of invalid usage is unspecified (i.e. a mark is not released, or
 123     /// a mark is released twice, or marks are not released in reverse order from
 124     /// which they were created).
 125     /// <p/>
 126     /// The behavior of this method is unspecified if no call to an
 127     /// <seealso cref="IntStream initializing method"/> has occurred after this stream was
 128     /// constructed.
 129     /// <p/>
 130     /// This method does not change the current position in the input stream.
 131     /// <p/>
 132     /// The following example shows the use of <seealso cref="#mark mark()"/>,
 133     /// <seealso cref="#release release(mark)"/>, <seealso cref="#index index()"/>, and
 134     /// <seealso cref="#seek seek(index)"/> as part of an operation to safely work within a
 135     /// marked region, then restore the stream position to its original value and
 136     /// release the mark.
 137     /// <pre>
 138     /// IntStream stream = ...;
 139     /// int index = -1;
 140     /// int mark = stream.mark();
 141     /// try {
 142     ///   index = stream.index();
 143     ///   // perform work here...
 144     /// } finally {
 145     ///   if (index != -1) {
 146     ///     stream.seek(index);
 147     ///   }
 148     ///   stream.release(mark);
 149     /// }
 150     /// </pre>
 151     /// </summary>
 152     /// <returns> An opaque marker which should be passed to
 153     /// <seealso cref="#release release()"/> when the marked range is no longer required. </returns>
 154     virtual ssize_t mark() = 0;
 155
 156     /// <summary>
 157     /// This method releases a marked range created by a call to
 158     /// <seealso cref="#mark mark()"/>. Calls to {@code release()} must appear in the
 159     /// reverse order of the corresponding calls to {@code mark()}. If a mark is
 160     /// released twice, or if marks are not released in reverse order of the
 161     /// corresponding calls to {@code mark()}, the behavior is unspecified.
 162     /// <p/>
 163     /// For more information and an example, see <seealso cref="#mark"/>.
 164     /// </summary>
 165     /// <param name="marker"> A marker returned by a call to {@code mark()}. </param>
 166     /// <seealso cref= #mark </seealso>
 167     virtual void release(ssize_t marker) = 0;
 168
 169     /// <summary>
 170     /// Return the index into the stream of the input symbol referred to by
 171     /// {@code LA(1)}.
 172     /// <p/>
 173     /// The behavior of this method is unspecified if no call to an
 174     /// <seealso cref="IntStream initializing method"/> has occurred after this stream was
 175     /// constructed.
 176     /// </summary>
 177     virtual size_t index() = 0;
 178
 179     /// <summary>
 180     /// Set the input cursor to the position indicated by {@code index}. If the
 181     /// specified index lies past the end of the stream, the operation behaves as
 182     /// though {@code index} was the index of the EOF symbol. After this method
 183     /// returns without throwing an exception, the at least one of the following
 184     /// will be true.
 185     ///
 186     /// <ul>
 187     ///   <li><seealso cref="#index index()"/> will return the index of the first symbol
 188     ///     appearing at or after the specified {@code index}. Specifically,
 189     ///     implementations which filter their sources should automatically
 190     ///     adjust {@code index} forward the minimum amount required for the
 191     ///     operation to target a non-ignored symbol.</li>
 192     ///   <li>{@code LA(1)} returns <seealso cref="#EOF"/></li>
 193     /// </ul>
 194     ///
 195     /// This operation is guaranteed to not throw an exception if {@code index}
 196     /// lies within a marked region. For more information on marked regions, see
 197     /// <seealso cref="#mark"/>. The behavior of this method is unspecified if no call to
 198     /// an <seealso cref="IntStream initializing method"/> has occurred after this stream
 199     /// was constructed.
 200     /// </summary>
 201     /// <param name="index"> The absolute index to seek to.
 202     /// </param>
 203     /// <exception cref="IllegalArgumentException"> if {@code index} is less than 0 </exception>
 204     /// <exception cref="UnsupportedOperationException"> if the stream does not support
 205     /// seeking to the specified index </exception>
 206     virtual void seek(size_t index) = 0;
 207
 208     /// <summary>
 209     /// Returns the total number of symbols in the stream, including a single EOF
 210     /// symbol.
 211     /// </summary>
 212     /// <exception cref="UnsupportedOperationException"> if the size of the stream is
 213     /// unknown. </exception>
 214     virtual size_t size() = 0;
 215
 216     /// <summary>
 217     /// Gets the name of the underlying symbol source. This method returns a
 218     /// non-null, non-empty string. If such a name is not known, this method
 219     /// returns <seealso cref="#UNKNOWN_SOURCE_NAME"/>.
 220     /// </summary>
 221     virtual std::string getSourceName() const = 0;
 222   };
 223
 224 } // namespace antlr4