Home | History | Annotate | Download | only in tree 
      1 /*
      2 [The "BSD licence"]
      3 Copyright (c) 2005-2006 Terence Parr
      4 All rights reserved.
      5 
      6 Redistribution and use in source and binary forms, with or without
      7 modification, are permitted provided that the following conditions
      8 are met:
      9 1. Redistributions of source code must retain the above copyright
     10 notice, this list of conditions and the following disclaimer.
     11 2. Redistributions in binary form must reproduce the above copyright
     12 notice, this list of conditions and the following disclaimer in the
     13 documentation and/or other materials provided with the distribution.
     14 3. The name of the author may not be used to endorse or promote products
     15 derived from this software without specific prior written permission.
     16 
     17 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
     18 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     19 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
     20 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
     21 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
     22 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
     23 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
     24 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
     25 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
     26 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     27 */
     28 package 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 }