TreeNodeStream.as revision 324c4644fee44b9898524c09511bd33c3f12e2df 
1/*
2[The "BSD licence"]
3Copyright (c) 2005-2006 Terence Parr
4All rights reserved.
5
6Redistribution and use in source and binary forms, with or without
7modification, are permitted provided that the following conditions
8are met:
91. Redistributions of source code must retain the above copyright
10notice, this list of conditions and the following disclaimer.
112. Redistributions in binary form must reproduce the above copyright
12notice, this list of conditions and the following disclaimer in the
13documentation and/or other materials provided with the distribution.
143. The name of the author may not be used to endorse or promote products
15derived from this software without specific prior written permission.
16
17THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
18IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
19OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
20IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
21INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
22NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
23DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
24THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27*/
28package org.antlr.runtime.tree {
29	import org.antlr.runtime.IntStream;
30	import org.antlr.runtime.TokenStream;
31
32	/** A stream of tree nodes, accessing nodes from a tree of some kind */
33	public interface TreeNodeStream extends IntStream {
34		/** Get a tree node at an absolute index i; 0..n-1.
35		 *  If you don't want to buffer up nodes, then this method makes no
36		 *  sense for you.
37		 */
38		function getNode(i:int):Object;
39
40		/** Get tree node at current input pointer + i ahead where i=1 is next node.
41		 *  i<0 indicates nodes in the past.  So LT(-1) is previous node, but
42		 *  implementations are not required to provide results for k < -1.
43		 *  LT(0) is undefined.  For i>=n, return null.
44		 *  Return null for LT(0) and any index that results in an absolute address
45		 *  that is negative.
46		 *
47		 *  This is analogus to the LT() method of the TokenStream, but this
48		 *  returns a tree node instead of a token.  Makes code gen identical
49		 *  for both parser and tree grammars. :)
50		 */
51		function LT(k:int):Object;
52
53		/** Where is this stream pulling nodes from?  This is not the name, but
54		 *  the object that provides node objects.
55		 */
56		function get treeSource():Object;
57
58		/** If the tree associated with this stream was created from a TokenStream,
59		 *  you can specify it here.  Used to do rule $text attribute in tree
60		 *  parser.  Optional unless you use tree parser rule text attribute
61		 *  or output=template and rewrite=true options.
62		 */
63		function get tokenStream():TokenStream;
64
65		/** What adaptor can tell me how to interpret/navigate nodes and
66		 *  trees.  E.g., get text of a node.
67		 */
68		function get treeAdaptor():TreeAdaptor;
69
70		/** As we flatten the tree, we use UP, DOWN nodes to represent
71		 *  the tree structure.  When debugging we need unique nodes
72		 *  so we have to instantiate new ones.  When doing normal tree
73		 *  parsing, it's slow and a waste of memory to create unique
74		 *  navigation nodes.  Default should be false;
75		 */
76		function set hasUniqueNavigationNodes(uniqueNavigationNodes:Boolean):void;
77
78		/** Return the text of all nodes from start to stop, inclusive.
79		 *  If the stream does not buffer all the nodes then it can still
80		 *  walk recursively from start until stop.  You can always return
81		 *  null or "" too, but users should not access $ruleLabel.text in
82		 *  an action of course in that case.
83		 */
84		function toStringWithRange(start:Object, stop:Object):String;
85
86		// REWRITING TREES (used by tree parser)
87
88		/** Replace from start to stop child index of parent with t, which might
89		 *  be a list.  Number of children may be different
90		 *  after this call.  The stream is notified because it is walking the
91		 *  tree and might need to know you are monkeying with the underlying
92		 *  tree.  Also, it might be able to modify the node stream to avoid
93		 *  restreaming for future phases.
94		 *
95		 *  If parent is null, don't do anything; must be at root of overall tree.
96		 *  Can't replace whatever points to the parent externally.  Do nothing.
97		 */
98		function replaceChildren(parent:Object, startChildIndex:int, stopChildIndex:int, t:Object):void;
99
100	}
101
102}