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