• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * [The "BSD licence"]
3  * Copyright (c) 2005-2008 Terence Parr
4  * All rights reserved.
5  *
6  * Conversion to C#:
7  * Copyright (c) 2008-2009 Sam Harwell, Pixel Mine, Inc.
8  * All rights reserved.
9  *
10  * Redistribution and use in source and binary forms, with or without
11  * modification, are permitted provided that the following conditions
12  * are met:
13  * 1. Redistributions of source code must retain the above copyright
14  *    notice, this list of conditions and the following disclaimer.
15  * 2. Redistributions in binary form must reproduce the above copyright
16  *    notice, this list of conditions and the following disclaimer in the
17  *    documentation and/or other materials provided with the distribution.
18  * 3. The name of the author may not be used to endorse or promote products
19  *    derived from this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
23  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
25  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
26  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 
33 namespace Antlr.Runtime.Tree
34 {
35     /** <summary>A stream of tree nodes, accessing nodes from a tree of some kind</summary> */
36     public interface ITreeNodeStream : IIntStream
37     {
38         /** <summary>
39          *  Get a tree node at an absolute index i; 0..n-1.
40          *  If you don't want to buffer up nodes, then this method makes no
41          *  sense for you.
42          *  </summary>
43          */
44         object this[int i]
45         {
46             get;
47         }
48 
49         /** <summary>
50          * Get tree node at current input pointer + {@code k} ahead where
51          * {@code k==1} is next node. {@code k<0} indicates nodes in the past. So
52          * {@code LT(-1)} is previous node, but implementations are not required to
53          * provide results for {@code k < -1}. {@code LT(0)} is undefined. For
54          * {@code k<=n}, return {@code null}. Return {@code null} for {@code LT(0)}
55          * and any index that results in an absolute address that is negative.
56          *  </summary>
57          *
58          *  <remarks>
59          * This is analogous to {@link TokenStream#LT}, but this returns a tree node
60          * instead of a {@link Token}. Makes code generation identical for both
61          * parser and tree grammars.
62          *  </remarks>
63          */
LT( int k )64         object LT( int k );
65 
66         /** <summary>
67          *  Where is this stream pulling nodes from?  This is not the name, but
68          *  the object that provides node objects.
69          *  </summary>
70          */
71         object TreeSource
72         {
73             get;
74         }
75 
76         /** <summary>
77          * If the tree associated with this stream was created from a
78          * {@link TokenStream}, you can specify it here. Used to do rule
79          * {@code $text} attribute in tree parser. Optional unless you use tree
80          * parser rule {@code $text} attribute or {@code output=template} and
81          * {@code rewrite=true} options.
82          *  </summary>
83          */
84         ITokenStream TokenStream
85         {
86             get;
87         }
88 
89         /** <summary>
90          *  What adaptor can tell me how to interpret/navigate nodes and
91          *  trees.  E.g., get text of a node.
92          *  </summary>
93          */
94         ITreeAdaptor TreeAdaptor
95         {
96             get;
97         }
98 
99         /** <summary>
100          * As we flatten the tree, we use {@link Token#UP}, {@link Token#DOWN} nodes
101          * to represent the tree structure. When debugging we need unique nodes so
102          * we have to instantiate new ones. When doing normal tree parsing, it's
103          * slow and a waste of memory to create unique navigation nodes. Default
104          * should be {@code false}.
105          *  </summary>
106          */
107         bool UniqueNavigationNodes
108         {
109             get;
110             set;
111         }
112 
113         /** <summary>
114          * Return the text of all nodes from {@code start} to {@code stop},
115          * inclusive. If the stream does not buffer all the nodes then it can still
116          * walk recursively from start until stop. You can always return
117          * {@code null} or {@code ""} too, but users should not access
118          * {@code $ruleLabel.text} in an action of course in that case.
119          *  </summary>
120          */
ToString( object start, object stop )121         string ToString( object start, object stop );
122 
123 
124         #region REWRITING TREES (used by tree parser)
125 
126         /** <summary>
127          * Replace children of {@code parent} from index {@code startChildIndex} to
128          * {@code stopChildIndex} with {@code t}, which might be a list. Number of
129          * children may be different after this call. The stream is notified because
130          * it is walking the tree and might need to know you are monkeying with the
131          * underlying tree. Also, it might be able to modify the node stream to
132          * avoid restreaming for future phases.
133          *  </summary>
134          *
135          *  <remarks>
136          * If {@code parent} is {@code null}, don't do anything; must be at root of
137          * overall tree. Can't replace whatever points to the parent externally. Do
138          * nothing.
139          *  </remarks>
140          */
ReplaceChildren( object parent, int startChildIndex, int stopChildIndex, object t )141         void ReplaceChildren( object parent, int startChildIndex, int stopChildIndex, object t );
142 
143         #endregion
144 
145     }
146 }
147