testautoa 0.4.0.pre16

data/test-server/instrumentation-backend/src/org/antlr/runtime/tree/TreeAdaptor.java

@@ -0,0 +1,263 @@
+/*
+ [The "BSD license"]
+ Copyright (c) 2005-2009 Terence Parr
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+ 1. Redistributions of source code must retain the above copyright
+     notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+ 3. The name of the author may not be used to endorse or promote products
+     derived from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.antlr.runtime.tree;
+
+import org.antlr.runtime.Token;
+import org.antlr.runtime.TokenStream;
+import org.antlr.runtime.RecognitionException;
+
+/** How to create and navigate trees.  Rather than have a separate factory
+ *  and adaptor, I've merged them.  Makes sense to encapsulate.
+ *
+ *  This takes the place of the tree construction code generated in the
+ *  generated code in 2.x and the ASTFactory.
+ *
+ *  I do not need to know the type of a tree at all so they are all
+ *  generic Objects.  This may increase the amount of typecasting needed. :(
+ */
+public interface TreeAdaptor {
+	// C o n s t r u c t i o n
+
+	/** Create a tree node from Token object; for CommonTree type trees,
+	 *  then the token just becomes the payload.  This is the most
+	 *  common create call.
+	 *
+	 *  Override if you want another kind of node to be built.
+	 */
+	public Object create(Token payload);
+
+	/** Duplicate a single tree node.
+	 *  Override if you want another kind of node to be built.
+	 */
+	public Object dupNode(Object treeNode);
+
+	/** Duplicate tree recursively, using dupNode() for each node */
+	public Object dupTree(Object tree);
+
+	/** Return a nil node (an empty but non-null node) that can hold
+	 *  a list of element as the children.  If you want a flat tree (a list)
+	 *  use "t=adaptor.nil(); t.addChild(x); t.addChild(y);"
+	 */
+	public Object nil();
+
+	/** Return a tree node representing an error.  This node records the
+	 *  tokens consumed during error recovery.  The start token indicates the
+	 *  input symbol at which the error was detected.  The stop token indicates
+	 *  the last symbol consumed during recovery.
+	 *
+	 *  You must specify the input stream so that the erroneous text can
+	 *  be packaged up in the error node.  The exception could be useful
+	 *  to some applications; default implementation stores ptr to it in
+	 *  the CommonErrorNode.
+	 *
+	 *  This only makes sense during token parsing, not tree parsing.
+	 *  Tree parsing should happen only when parsing and tree construction
+	 *  succeed.
+	 */
+	public Object errorNode(TokenStream input, Token start, Token stop, RecognitionException e);
+
+	/** Is tree considered a nil node used to make lists of child nodes? */
+	public boolean isNil(Object tree);
+
+	/** Add a child to the tree t.  If child is a flat tree (a list), make all
+	 *  in list children of t.  Warning: if t has no children, but child does
+	 *  and child isNil then you can decide it is ok to move children to t via
+	 *  t.children = child.children; i.e., without copying the array.  Just
+	 *  make sure that this is consistent with have the user will build
+	 *  ASTs.  Do nothing if t or child is null.
+	 */
+	public void addChild(Object t, Object child);
+
+	/** If oldRoot is a nil root, just copy or move the children to newRoot.
+	 *  If not a nil root, make oldRoot a child of newRoot.
+	 *
+	 *    old=^(nil a b c), new=r yields ^(r a b c)
+	 *    old=^(a b c), new=r yields ^(r ^(a b c))
+	 *
+	 *  If newRoot is a nil-rooted single child tree, use the single
+	 *  child as the new root node.
+	 *
+	 *    old=^(nil a b c), new=^(nil r) yields ^(r a b c)
+	 *    old=^(a b c), new=^(nil r) yields ^(r ^(a b c))
+	 *
+	 *  If oldRoot was null, it's ok, just return newRoot (even if isNil).
+	 *
+	 *    old=null, new=r yields r
+	 *    old=null, new=^(nil r) yields ^(nil r)
+	 *
+	 *  Return newRoot.  Throw an exception if newRoot is not a
+	 *  simple node or nil root with a single child node--it must be a root
+	 *  node.  If newRoot is ^(nil x) return x as newRoot.
+	 *
+	 *  Be advised that it's ok for newRoot to point at oldRoot's
+	 *  children; i.e., you don't have to copy the list.  We are
+	 *  constructing these nodes so we should have this control for
+	 *  efficiency.
+	 */
+	public Object becomeRoot(Object newRoot, Object oldRoot);
+
+	/** Given the root of the subtree created for this rule, post process
+	 *  it to do any simplifications or whatever you want.  A required
+	 *  behavior is to convert ^(nil singleSubtree) to singleSubtree
+	 *  as the setting of start/stop indexes relies on a single non-nil root
+	 *  for non-flat trees.
+	 *
+	 *  Flat trees such as for lists like "idlist : ID+ ;" are left alone
+	 *  unless there is only one ID.  For a list, the start/stop indexes
+	 *  are set in the nil node.
+	 *
+	 *  This method is executed after all rule tree construction and right
+	 *  before setTokenBoundaries().
+	 */
+	public Object rulePostProcessing(Object root);
+
+	/** For identifying trees.
+	 *
+	 *  How to identify nodes so we can say "add node to a prior node"?
+	 *  Even becomeRoot is an issue.  Use System.identityHashCode(node)
+	 *  usually.
+	 */
+	public int getUniqueID(Object node);
+
+
+	// R e w r i t e  R u l e s
+
+	/** Create a node for newRoot make it the root of oldRoot.
+	 *  If oldRoot is a nil root, just copy or move the children to newRoot.
+	 *  If not a nil root, make oldRoot a child of newRoot.
+	 *
+	 *  Return node created for newRoot.
+	 *
+	 *  Be advised: when debugging ASTs, the DebugTreeAdaptor manually
+	 *  calls create(Token child) and then plain becomeRoot(node, node)
+	 *  because it needs to trap calls to create, but it can't since it delegates
+	 *  to not inherits from the TreeAdaptor.
+	 */
+	public Object becomeRoot(Token newRoot, Object oldRoot);
+
+	/** Create a new node derived from a token, with a new token type.
+	 *  This is invoked from an imaginary node ref on right side of a
+	 *  rewrite rule as IMAG[$tokenLabel].
+	 *
+	 *  This should invoke createToken(Token).
+	 */
+	public Object create(int tokenType, Token fromToken);
+
+	/** Same as create(tokenType,fromToken) except set the text too.
+	 *  This is invoked from an imaginary node ref on right side of a
+	 *  rewrite rule as IMAG[$tokenLabel, "IMAG"].
+	 *
+	 *  This should invoke createToken(Token).
+	 */
+	public Object create(int tokenType, Token fromToken, String text);
+
+	/** Create a new node derived from a token, with a new token type.
+	 *  This is invoked from an imaginary node ref on right side of a
+	 *  rewrite rule as IMAG["IMAG"].
+	 *
+	 *  This should invoke createToken(int,String).
+	 */
+	public Object create(int tokenType, String text);
+
+
+	// C o n t e n t
+
+	/** For tree parsing, I need to know the token type of a node */
+	public int getType(Object t);
+
+	/** Node constructors can set the type of a node */
+	public void setType(Object t, int type);
+
+	public String getText(Object t);
+
+	/** Node constructors can set the text of a node */
+	public void setText(Object t, String text);
+
+	/** Return the token object from which this node was created.
+	 *  Currently used only for printing an error message.
+	 *  The error display routine in BaseRecognizer needs to
+	 *  display where the input the error occurred. If your
+	 *  tree of limitation does not store information that can
+	 *  lead you to the token, you can create a token filled with
+	 *  the appropriate information and pass that back.  See
+	 *  BaseRecognizer.getErrorMessage().
+	 */
+	public Token getToken(Object t);
+
+	/** Where are the bounds in the input token stream for this node and
+	 *  all children?  Each rule that creates AST nodes will call this
+	 *  method right before returning.  Flat trees (i.e., lists) will
+	 *  still usually have a nil root node just to hold the children list.
+	 *  That node would contain the start/stop indexes then.
+	 */
+	public void setTokenBoundaries(Object t, Token startToken, Token stopToken);
+
+	/** Get the token start index for this subtree; return -1 if no such index */
+	public int getTokenStartIndex(Object t);
+
+	/** Get the token stop index for this subtree; return -1 if no such index */
+	public int getTokenStopIndex(Object t);
+
+
+	// N a v i g a t i o n  /  T r e e  P a r s i n g
+
+	/** Get a child 0..n-1 node */
+	public Object getChild(Object t, int i);
+
+	/** Set ith child (0..n-1) to t; t must be non-null and non-nil node */
+	public void setChild(Object t, int i, Object child);
+
+	/** Remove ith child and shift children down from right. */
+	public Object deleteChild(Object t, int i);
+
+	/** How many children?  If 0, then this is a leaf node */
+	public int getChildCount(Object t);
+
+	/** Who is the parent node of this node; if null, implies node is root.
+	 *  If your node type doesn't handle this, it's ok but the tree rewrites
+	 *  in tree parsers need this functionality.
+	 */
+	public Object getParent(Object t);
+	public void setParent(Object t, Object parent);
+
+	/** What index is this node in the child list? Range: 0..n-1
+	 *  If your node type doesn't handle this, it's ok but the tree rewrites
+	 *  in tree parsers need this functionality.
+	 */
+	public int getChildIndex(Object t);
+	public void setChildIndex(Object t, int index);
+
+	/** Replace from start to stop child index of parent with t, which might
+	 *  be a list.  Number of children may be different
+	 *  after this call.
+	 *
+	 *  If parent is null, don't do anything; must be at root of overall tree.
+	 *  Can't replace whatever points to the parent externally.  Do nothing.
+	 */
+	public void replaceChildren(Object parent, int startChildIndex, int stopChildIndex, Object t);
+}

data/test-server/instrumentation-backend/src/org/antlr/runtime/tree/TreeFilter.java

@@ -0,0 +1,135 @@
+/*
+ [The "BSD license"]
+ Copyright (c) 2005-2009 Terence Parr
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+ 1. Redistributions of source code must retain the above copyright
+     notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+ 3. The name of the author may not be used to endorse or promote products
+     derived from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.antlr.runtime.tree;
+
+import org.antlr.runtime.RecognizerSharedState;
+import org.antlr.runtime.RecognitionException;
+import org.antlr.runtime.TokenStream;
+
+/**
+ Cut-n-paste from material I'm not using in the book anymore (edit later
+ to make sense):
+
+ Now, how are we going to test these tree patterns against every
+subtree in our original tree?  In what order should we visit nodes?
+For this application, it turns out we need a simple ``apply once''
+rule application strategy and a ``down then up'' tree traversal
+strategy.  Let's look at rule application first.
+
+As we visit each node, we need to see if any of our patterns match. If
+a pattern matches, we execute the associated tree rewrite and move on
+to the next node. In other words, we only look for a single rule
+application opportunity (we'll see below that we sometimes need to
+repeatedly apply rules). The following method applies a rule in a @cl
+TreeParser (derived from a tree grammar) to a tree:
+
+here is where weReferenced code/walking/patterns/TreePatternMatcher.java
+
+It uses reflection to lookup the appropriate rule within the generated
+tree parser class (@cl Simplify in this case). Most of the time, the
+rule will not match the tree.  To avoid issuing syntax errors and
+attempting error recovery, it bumps up the backtracking level.  Upon
+failure, the invoked rule immediately returns. If you don't plan on
+using this technique in your own ANTLR-based application, don't sweat
+the details. This method boils down to ``call a rule to match a tree,
+executing any embedded actions and rewrite rules.''
+
+At this point, we know how to define tree grammar rules and how to
+apply them to a particular subtree. The final piece of the tree
+pattern matcher is the actual tree traversal. We have to get the
+correct node visitation order.  In particular, we need to perform the
+scalar-vector multiply transformation on the way down (preorder) and
+we need to reduce multiply-by-zero subtrees on the way up (postorder).
+
+To implement a top-down visitor, we do a depth first walk of the tree,
+executing an action in the preorder position. To get a bottom-up
+visitor, we execute an action in the postorder position.  ANTLR
+provides a standard @cl TreeVisitor class with a depth first search @v
+visit method. That method executes either a @m pre or @m post method
+or both. In our case, we need to call @m applyOnce in both. On the way
+down, we'll look for @r vmult patterns. On the way up,
+we'll look for @r mult0 patterns.
+ */
+public class TreeFilter extends TreeParser {
+    public interface fptr {
+        public void rule() throws RecognitionException;
+    }
+
+    protected TokenStream originalTokenStream;
+    protected TreeAdaptor originalAdaptor;
+
+    public TreeFilter(TreeNodeStream input) {
+        this(input, new RecognizerSharedState());
+    }
+    public TreeFilter(TreeNodeStream input, RecognizerSharedState state) {
+        super(input, state);
+        originalAdaptor = input.getTreeAdaptor();
+        originalTokenStream = input.getTokenStream();
+    }
+
+    public void applyOnce(Object t, fptr whichRule) {
+        if ( t==null ) return;
+        try {
+            // share TreeParser object but not parsing-related state
+            state = new RecognizerSharedState();
+            input = new CommonTreeNodeStream(originalAdaptor, t);
+            ((CommonTreeNodeStream)input).setTokenStream(originalTokenStream);
+            setBacktrackingLevel(1);
+            whichRule.rule();
+            setBacktrackingLevel(0);
+        }
+        catch (RecognitionException e) { ; }
+    }
+
+    public void downup(Object t) {
+        TreeVisitor v = new TreeVisitor(new CommonTreeAdaptor());
+        TreeVisitorAction actions = new TreeVisitorAction() {
+            public Object pre(Object t)  { applyOnce(t, topdown_fptr); return t; }
+            public Object post(Object t) { applyOnce(t, bottomup_fptr); return t; }
+        };
+        v.visit(t, actions);
+    }
+        
+    fptr topdown_fptr = new fptr() {
+        public void rule() throws RecognitionException {
+            topdown();
+        }
+    };
+
+    fptr bottomup_fptr = new fptr() {
+        public void rule() throws RecognitionException {
+            bottomup();
+        }
+    };
+
+    // methods the downup strategy uses to do the up and down rules.
+    // to override, just define tree grammar rule topdown and turn on
+    // filter=true.
+    public void topdown() throws RecognitionException {;}
+    public void bottomup() throws RecognitionException {;}
+}

data/test-server/instrumentation-backend/src/org/antlr/runtime/tree/TreeIterator.java

@@ -0,0 +1,132 @@
+/*
+ [The "BSD license"]
+ Copyright (c) 2005-2009 Terence Parr
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+ 1. Redistributions of source code must retain the above copyright
+     notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+ 3. The name of the author may not be used to endorse or promote products
+     derived from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.antlr.runtime.tree;
+
+import org.antlr.runtime.Token;
+import org.antlr.runtime.CommonToken;
+import org.antlr.runtime.misc.FastQueue;
+
+import java.util.Iterator;
+
+/** Return a node stream from a doubly-linked tree whose nodes
+ *  know what child index they are.  No remove() is supported.
+ *
+ *  Emit navigation nodes (DOWN, UP, and EOF) to let show tree structure.
+ */
+public class TreeIterator implements Iterator {
+    protected TreeAdaptor adaptor;
+    protected Object root;
+    protected Object tree;
+    protected boolean firstTime = true;
+
+    // navigation nodes to return during walk and at end
+    public Object up;
+    public Object down;
+    public Object eof;
+
+    /** If we emit UP/DOWN nodes, we need to spit out multiple nodes per
+     *  next() call.
+     */
+    protected FastQueue nodes;
+
+    public TreeIterator(Object tree) {
+        this(new CommonTreeAdaptor(),tree);
+    }
+
+    public TreeIterator(TreeAdaptor adaptor, Object tree) {
+        this.adaptor = adaptor;
+        this.tree = tree;
+        this.root = tree;
+        nodes = new FastQueue();
+        down = adaptor.create(Token.DOWN, "DOWN");
+        up = adaptor.create(Token.UP, "UP");
+        eof = adaptor.create(Token.EOF, "EOF");
+    }
+
+    public void reset() {
+        firstTime = true;
+        tree = root;
+        nodes.clear();
+    }
+
+    public boolean hasNext() {
+        if ( firstTime ) return root!=null;
+        if ( nodes!=null && nodes.size()>0 ) return true;
+        if ( tree==null ) return false;
+        if ( adaptor.getChildCount(tree)>0 ) return true;
+        return adaptor.getParent(tree)!=null; // back at root?
+    }
+
+    public Object next() {
+        if ( firstTime ) { // initial condition
+            firstTime = false;
+            if ( adaptor.getChildCount(tree)==0 ) { // single node tree (special)
+                nodes.add(eof);
+                return tree;
+            }
+            return tree;
+        }
+        // if any queued up, use those first
+        if ( nodes!=null && nodes.size()>0 ) return nodes.remove();
+
+        // no nodes left?
+        if ( tree==null ) return eof;
+
+        // next node will be child 0 if any children
+        if ( adaptor.getChildCount(tree)>0 ) {
+            tree = adaptor.getChild(tree, 0);
+            nodes.add(tree); // real node is next after DOWN
+            return down;
+        }
+        // if no children, look for next sibling of tree or ancestor
+        Object parent = adaptor.getParent(tree);
+        // while we're out of siblings, keep popping back up towards root
+        while ( parent!=null &&
+                adaptor.getChildIndex(tree)+1 >= adaptor.getChildCount(parent) )
+        {
+            nodes.add(up); // we're moving back up
+            tree = parent;
+            parent = adaptor.getParent(tree);
+        }
+        // no nodes left?
+        if ( parent==null ) {
+            tree = null; // back at root? nothing left then
+            nodes.add(eof); // add to queue, might have UP nodes in there
+            return nodes.remove();
+        }
+
+        // must have found a node with an unvisited sibling
+        // move to it and return it
+        int nextSiblingIndex = adaptor.getChildIndex(tree) + 1;
+        tree = adaptor.getChild(parent, nextSiblingIndex);
+        nodes.add(tree); // add to queue, might have UP nodes in there
+        return nodes.remove();
+    }
+
+    public void remove() { throw new UnsupportedOperationException(); }
+}

data/test-server/instrumentation-backend/src/org/antlr/runtime/tree/TreeNodeStream.java

@@ -0,0 +1,106 @@
+/*
+ [The "BSD license"]
+ Copyright (c) 2005-2009 Terence Parr
+ All rights reserved.
+
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions
+ are met:
+ 1. Redistributions of source code must retain the above copyright
+     notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+ 3. The name of the author may not be used to endorse or promote products
+     derived from this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+ IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+ INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+ NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.antlr.runtime.tree;
+
+import org.antlr.runtime.IntStream;
+import org.antlr.runtime.TokenStream;
+
+/** A stream of tree nodes, accessing nodes from a tree of some kind */
+public interface TreeNodeStream extends IntStream {
+	/** Get a tree node at an absolute index i; 0..n-1.
+	 *  If you don't want to buffer up nodes, then this method makes no
+	 *  sense for you.
+	 */
+	public Object get(int i);
+
+	/** Get tree node at current input pointer + i ahead where i=1 is next node.
+	 *  i<0 indicates nodes in the past.  So LT(-1) is previous node, but
+	 *  implementations are not required to provide results for k < -1.
+	 *  LT(0) is undefined.  For i>=n, return null.
+	 *  Return null for LT(0) and any index that results in an absolute address
+	 *  that is negative.
+	 *
+	 *  This is analogus to the LT() method of the TokenStream, but this
+	 *  returns a tree node instead of a token.  Makes code gen identical
+	 *  for both parser and tree grammars. :)
+	 */
+	public Object LT(int k);
+
+	/** Where is this stream pulling nodes from?  This is not the name, but
+	 *  the object that provides node objects.
+	 */
+	public Object getTreeSource();
+
+	/** If the tree associated with this stream was created from a TokenStream,
+	 *  you can specify it here.  Used to do rule $text attribute in tree
+	 *  parser.  Optional unless you use tree parser rule text attribute
+	 *  or output=template and rewrite=true options.
+	 */
+	public TokenStream getTokenStream();
+
+	/** What adaptor can tell me how to interpret/navigate nodes and
+	 *  trees.  E.g., get text of a node.
+	 */
+	public TreeAdaptor getTreeAdaptor();
+
+	/** As we flatten the tree, we use UP, DOWN nodes to represent
+	 *  the tree structure.  When debugging we need unique nodes
+	 *  so we have to instantiate new ones.  When doing normal tree
+	 *  parsing, it's slow and a waste of memory to create unique
+	 *  navigation nodes.  Default should be false;
+	 */
+	public void setUniqueNavigationNodes(boolean uniqueNavigationNodes);
+
+    /** Reset the tree node stream in such a way that it acts like
+     *  a freshly constructed stream.
+     */
+    public void reset();
+
+	/** Return the text of all nodes from start to stop, inclusive.
+	 *  If the stream does not buffer all the nodes then it can still
+	 *  walk recursively from start until stop.  You can always return
+	 *  null or "" too, but users should not access $ruleLabel.text in
+	 *  an action of course in that case.
+	 */
+	public String toString(Object start, Object stop);
+
+
+	// REWRITING TREES (used by tree parser)
+
+	/** Replace from start to stop child index of parent with t, which might
+	 *  be a list.  Number of children may be different
+	 *  after this call.  The stream is notified because it is walking the
+	 *  tree and might need to know you are monkeying with the underlying
+	 *  tree.  Also, it might be able to modify the node stream to avoid
+	 *  restreaming for future phases.
+	 *
+	 *  If parent is null, don't do anything; must be at root of overall tree.
+	 *  Can't replace whatever points to the parent externally.  Do nothing.
+	 */
+	public void replaceChildren(Object parent, int startChildIndex, int stopChildIndex, Object t);
+}