Lucene.Net/QueryParser/CharStream.cs

   1 using System;
   2
   3 namespace Lucene.Net.QueryParsers
   4 {
   5         /// <summary>
   6         /// This interface describes a character stream that maintains line and
   7         /// column number positions of the characters.  It also has the capability
   8         /// to backup the stream to some extent.  An implementation of this
   9         /// interface is used in the TokenManager implementation generated by
  10         /// JavaCCParser.
  11         ///
  12         /// All the methods except backup can be implemented in any fashion. backup
  13         /// needs to be implemented correctly for the correct operation of the lexer.
  14         /// Rest of the methods are all used to get information like line number,
  15         /// column number and the String that constitutes a token and are not used
  16         /// by the lexer. Hence their implementation won't affect the generated lexer's
  17         /// operation.
  18         /// </summary>
  19         public interface CharStream
  20         {
  21
  22                 /// <summary>
  23                 /// Returns the next character from the selected input.  The method
  24                 /// of selecting the input is the responsibility of the class
  25                 /// implementing this interface.  Can throw any java.io.IOException.
  26                 /// </summary>
  27                 /// <returns></returns>
  28                 char ReadChar();
  29
  30                 /// <summary>
  31                 /// Returns the column position of the character last read.
  32                 /// <seealso cref="GetEndColumn"/>
  33                 /// </summary>
  34                 /// <returns></returns>
  35                 /// <remarks>deprecated </remarks>
  36                 int GetColumn();
  37
  38                 /// <summary>
  39                 /// Returns the line number of the character last read.
  40                 /// <see cref="GetEndLine"/>
  41                 /// </summary>
  42                 /// <returns></returns>
  43                 /// <remarks>deprecated</remarks>
  44                 int GetLine();
  45
  46                 /// <summary>
  47                 /// Returns the column number of the last character for current token (being
  48                 /// matched after the last call to BeginToken).
  49                 /// </summary>
  50                 /// <returns></returns>
  51                 int GetEndColumn();
  52
  53                 /// <summary>
  54                 /// Returns the line number of the last character for current token (being
  55                 /// matched after the last call to BeginToken).
  56                 /// </summary>
  57                 /// <returns></returns>
  58                 int GetEndLine();
  59
  60                 /// <summary>
  61                 /// Returns the column number of the first character for current token (being
  62                 /// matched after the last call to BeginToken).
  63                 /// </summary>
  64                 /// <returns></returns>
  65                 int GetBeginColumn();
  66
  67                 /// <summary>
  68                 /// Returns the line number of the first character for current token (being
  69                 /// matched after the last call to BeginToken).
  70                 /// </summary>
  71                 /// <returns></returns>
  72                 int GetBeginLine();
  73
  74                 /// <summary>
  75                 /// Backs up the input stream by amount steps. Lexer calls this method if it
  76                 /// had already read some characters, but could not use them to match a
  77                 /// (longer) token. So, they will be used again as the prefix of the next
  78                 /// token and it is the implemetation's responsibility to do this right.
  79                 /// </summary>
  80                 /// <param name="amount"></param>
  81                 void Backup(int amount);
  82
  83                 /// <summary>
  84                 /// Returns the next character that marks the beginning of the next token.
  85                 /// All characters must remain in the buffer between two successive calls
  86                 /// to this method to implement backup correctly.
  87                 /// </summary>
  88                 /// <returns></returns>
  89                 char BeginToken();
  90
  91                 /// <summary>
  92                 /// Returns a string made up of characters from the marked token beginning
  93                 /// to the current buffer position. Implementations have the choice of returning
  94                 /// anything that they want to. For example, for efficiency, one might decide
  95                 /// to just return null, which is a valid implementation.
  96                 /// </summary>
  97                 String GetImage();
  98
  99                 /// <summary>
 100                 /// Returns an array of characters that make up the suffix of length 'len' for
 101                 /// the currently matched token. This is used to build up the matched string
 102                 /// for use in actions in the case of MORE. A simple and inefficient
 103                 /// implementation of this is as follows :
 104                 ///
 105                 ///   {
 106                 ///      String t = GetImage();
 107                 ///      return t.Substring(t.Length - len, t.Length).ToCharArray();
 108                 ///   }
 109                 ///
 110                 /// </summary>
 111                 char[] GetSuffix(int len);
 112
 113                 /// <summary>
 114                 /// The lexer calls this function to indicate that it is done with the stream
 115                 /// and hence implementations can free any resources held by this class.
 116                 /// Again, the body of this function can be just empty and it will not
 117                 /// affect the lexer's operation.
 118                 /// </summary>
 119                 void Done();
 120         }
 121 }