View Javadoc

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