| /* Copyright (c) 2012-2017 The ANTLR Project. All rights reserved. |
| * Use of this file is governed by the BSD 3-clause license that |
| * can be found in the LICENSE.txt file in the project root. |
| */ |
| using Antlr4.Runtime; |
| using Antlr4.Runtime.Sharpen; |
| |
| namespace Antlr4.Runtime |
| { |
| /// <summary>A simple stream of symbols whose values are represented as integers.</summary> |
| /// <remarks> |
| /// A simple stream of symbols whose values are represented as integers. This |
| /// interface provides <em>marked ranges</em> with support for a minimum level |
| /// of buffering necessary to implement arbitrary lookahead during prediction. |
| /// For more information on marked ranges, see |
| /// <see cref="Mark()"/> |
| /// . |
| /// <p><strong>Initializing Methods:</strong> Some methods in this interface have |
| /// unspecified behavior if no call to an initializing method has occurred after |
| /// the stream was constructed. The following is a list of initializing methods:</p> |
| /// <ul> |
| /// <li> |
| /// <see cref="LA(int)"/> |
| /// </li> |
| /// <li> |
| /// <see cref="Consume()"/> |
| /// </li> |
| /// <li> |
| /// <see cref="Size()"/> |
| /// </li> |
| /// </ul> |
| /// </remarks> |
| public interface IIntStream |
| { |
| /// <summary>Consumes the current symbol in the stream.</summary> |
| /// <remarks> |
| /// Consumes the current symbol in the stream. This method has the following |
| /// effects: |
| /// <ul> |
| /// <li><strong>Forward movement:</strong> The value of |
| /// <see cref="Index()">index()</see> |
| /// before calling this method is less than the value of |
| /// <c>index()</c> |
| /// after calling this method.</li> |
| /// <li><strong>Ordered lookahead:</strong> The value of |
| /// <c>LA(1)</c> |
| /// before |
| /// calling this method becomes the value of |
| /// <c>LA(-1)</c> |
| /// after calling |
| /// this method.</li> |
| /// </ul> |
| /// Note that calling this method does not guarantee that |
| /// <c>index()</c> |
| /// is |
| /// incremented by exactly 1, as that would preclude the ability to implement |
| /// filtering streams (e.g. |
| /// <see cref="CommonTokenStream"/> |
| /// which distinguishes |
| /// between "on-channel" and "off-channel" tokens). |
| /// </remarks> |
| /// <exception cref="System.InvalidOperationException"> |
| /// if an attempt is made to consume the the |
| /// end of the stream (i.e. if |
| /// <c>LA(1)==</c> |
| /// <see cref="IntStreamConstants.EOF">EOF</see> |
| /// before calling |
| /// <c>consume</c> |
| /// ). |
| /// </exception> |
| void Consume(); |
| |
| /// <summary> |
| /// Gets the value of the symbol at offset |
| /// <paramref name="i"/> |
| /// from the current |
| /// position. When |
| /// <c>i==1</c> |
| /// , this method returns the value of the current |
| /// symbol in the stream (which is the next symbol to be consumed). When |
| /// <c>i==-1</c> |
| /// , this method returns the value of the previously read |
| /// symbol in the stream. It is not valid to call this method with |
| /// <c>i==0</c> |
| /// , but the specific behavior is unspecified because this |
| /// method is frequently called from performance-critical code. |
| /// <p>This method is guaranteed to succeed if any of the following are true:</p> |
| /// <ul> |
| /// <li> |
| /// <c>i>0</c> |
| /// </li> |
| /// <li> |
| /// <c>i==-1</c> |
| /// and |
| /// <see cref="Index()">index()</see> |
| /// returns a value greater |
| /// than the value of |
| /// <c>index()</c> |
| /// after the stream was constructed |
| /// and |
| /// <c>LA(1)</c> |
| /// was called in that order. Specifying the current |
| /// <c>index()</c> |
| /// relative to the index after the stream was created |
| /// allows for filtering implementations that do not return every symbol |
| /// from the underlying source. Specifying the call to |
| /// <c>LA(1)</c> |
| /// allows for lazily initialized streams.</li> |
| /// <li> |
| /// <c>LA(i)</c> |
| /// refers to a symbol consumed within a marked region |
| /// that has not yet been released.</li> |
| /// </ul> |
| /// <p>If |
| /// <paramref name="i"/> |
| /// represents a position at or beyond the end of the stream, |
| /// this method returns |
| /// <see cref="IntStreamConstants.EOF"/> |
| /// .</p> |
| /// <p>The return value is unspecified if |
| /// <c>i<0</c> |
| /// and fewer than |
| /// <c>-i</c> |
| /// calls to |
| /// <see cref="Consume()">consume()</see> |
| /// have occurred from the beginning of |
| /// the stream before calling this method.</p> |
| /// </summary> |
| /// <exception cref="System.NotSupportedException"> |
| /// if the stream does not support |
| /// retrieving the value of the specified symbol |
| /// </exception> |
| int LA(int i); |
| |
| /// <summary> |
| /// A mark provides a guarantee that |
| /// <see cref="Seek(int)">seek()</see> |
| /// operations will be |
| /// valid over a "marked range" extending from the index where |
| /// <c>mark()</c> |
| /// was called to the current |
| /// <see cref="Index()">index()</see> |
| /// . This allows the use of |
| /// streaming input sources by specifying the minimum buffering requirements |
| /// to support arbitrary lookahead during prediction. |
| /// <p>The returned mark is an opaque handle (type |
| /// <c>int</c> |
| /// ) which is passed |
| /// to |
| /// <see cref="Release(int)">release()</see> |
| /// when the guarantees provided by the marked |
| /// range are no longer necessary. When calls to |
| /// <c>mark()</c> |
| /// / |
| /// <c>release()</c> |
| /// are nested, the marks must be released |
| /// in reverse order of which they were obtained. Since marked regions are |
| /// used during performance-critical sections of prediction, the specific |
| /// behavior of invalid usage is unspecified (i.e. a mark is not released, or |
| /// a mark is released twice, or marks are not released in reverse order from |
| /// which they were created).</p> |
| /// <p>The behavior of this method is unspecified if no call to an |
| /// <see cref="IIntStream">initializing method</see> |
| /// has occurred after this stream was |
| /// constructed.</p> |
| /// <p>This method does not change the current position in the input stream.</p> |
| /// <p>The following example shows the use of |
| /// <see cref="Mark()">mark()</see> |
| /// , |
| /// <see cref="Release(int)">release(mark)</see> |
| /// , |
| /// <see cref="Index()">index()</see> |
| /// , and |
| /// <see cref="Seek(int)">seek(index)</see> |
| /// as part of an operation to safely work within a |
| /// marked region, then restore the stream position to its original value and |
| /// release the mark.</p> |
| /// <pre> |
| /// IntStream stream = ...; |
| /// int index = -1; |
| /// int mark = stream.mark(); |
| /// try { |
| /// index = stream.index(); |
| /// // perform work here... |
| /// } finally { |
| /// if (index != -1) { |
| /// stream.seek(index); |
| /// } |
| /// stream.release(mark); |
| /// } |
| /// </pre> |
| /// </summary> |
| /// <returns> |
| /// An opaque marker which should be passed to |
| /// <see cref="Release(int)">release()</see> |
| /// when the marked range is no longer required. |
| /// </returns> |
| int Mark(); |
| |
| /// <summary> |
| /// This method releases a marked range created by a call to |
| /// <see cref="Mark()">mark()</see> |
| /// . Calls to |
| /// <c>release()</c> |
| /// must appear in the |
| /// reverse order of the corresponding calls to |
| /// <c>mark()</c> |
| /// . If a mark is |
| /// released twice, or if marks are not released in reverse order of the |
| /// corresponding calls to |
| /// <c>mark()</c> |
| /// , the behavior is unspecified. |
| /// <p>For more information and an example, see |
| /// <see cref="Mark()"/> |
| /// .</p> |
| /// </summary> |
| /// <param name="marker"> |
| /// A marker returned by a call to |
| /// <c>mark()</c> |
| /// . |
| /// </param> |
| /// <seealso cref="Mark()"/> |
| void Release(int marker); |
| |
| /// <summary> |
| /// Return the index into the stream of the input symbol referred to by |
| /// <c>LA(1)</c> |
| /// . |
| /// <p>The behavior of this method is unspecified if no call to an |
| /// <see cref="IIntStream">initializing method</see> |
| /// has occurred after this stream was |
| /// constructed.</p> |
| /// </summary> |
| int Index |
| { |
| get; |
| } |
| |
| /// <summary> |
| /// Set the input cursor to the position indicated by |
| /// <paramref name="index"/> |
| /// . If the |
| /// specified index lies past the end of the stream, the operation behaves as |
| /// though |
| /// <paramref name="index"/> |
| /// was the index of the EOF symbol. After this method |
| /// returns without throwing an exception, the at least one of the following |
| /// will be true. |
| /// <ul> |
| /// <li> |
| /// <see cref="Index()">index()</see> |
| /// will return the index of the first symbol |
| /// appearing at or after the specified |
| /// <paramref name="index"/> |
| /// . Specifically, |
| /// implementations which filter their sources should automatically |
| /// adjust |
| /// <paramref name="index"/> |
| /// forward the minimum amount required for the |
| /// operation to target a non-ignored symbol.</li> |
| /// <li> |
| /// <c>LA(1)</c> |
| /// returns |
| /// <see cref="IntStreamConstants.EOF"/> |
| /// </li> |
| /// </ul> |
| /// This operation is guaranteed to not throw an exception if |
| /// <paramref name="index"/> |
| /// lies within a marked region. For more information on marked regions, see |
| /// <see cref="Mark()"/> |
| /// . The behavior of this method is unspecified if no call to |
| /// an |
| /// <see cref="IIntStream">initializing method</see> |
| /// has occurred after this stream |
| /// was constructed. |
| /// </summary> |
| /// <param name="index">The absolute index to seek to.</param> |
| /// <exception cref="System.ArgumentException"> |
| /// if |
| /// <paramref name="index"/> |
| /// is less than 0 |
| /// </exception> |
| /// <exception cref="System.NotSupportedException"> |
| /// if the stream does not support |
| /// seeking to the specified index |
| /// </exception> |
| void Seek(int index); |
| |
| /// <summary> |
| /// Returns the total number of symbols in the stream, including a single EOF |
| /// symbol. |
| /// </summary> |
| /// <remarks> |
| /// Returns the total number of symbols in the stream, including a single EOF |
| /// symbol. |
| /// </remarks> |
| /// <exception cref="System.NotSupportedException"> |
| /// if the size of the stream is |
| /// unknown. |
| /// </exception> |
| int Size |
| { |
| get; |
| } |
| |
| /// <summary>Gets the name of the underlying symbol source.</summary> |
| /// <remarks> |
| /// Gets the name of the underlying symbol source. This method returns a |
| /// non-null, non-empty string. If such a name is not known, this method |
| /// returns |
| /// <see cref="IntStreamConstants.UnknownSourceName"/> |
| /// . |
| /// </remarks> |
| string SourceName |
| { |
| get; |
| } |
| } |
| |
| public static class IntStreamConstants |
| { |
| /// <summary> |
| /// The value returned by |
| /// <see cref="IIntStream.LA(int)">LA()</see> |
| /// when the end of the stream is |
| /// reached. |
| /// </summary> |
| public const int EOF = -1; |
| |
| /// <summary> |
| /// The value returned by |
| /// <see cref="IIntStream.SourceName"/> |
| /// when the actual name of the |
| /// underlying source is not known. |
| /// </summary> |
| public const string UnknownSourceName = "<unknown>"; |
| } |
| } |
