1/*
2 [The "BSD license"]
3 Copyright (c) 2005-2009 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 */
28package org.antlr.runtime.tree;
29
30import org.antlr.runtime.Token;
31
32import java.util.List;
33
34/** What does a tree look like?  ANTLR has a number of support classes
35 *  such as CommonTreeNodeStream that work on these kinds of trees.  You
36 *  don't have to make your trees implement this interface, but if you do,
37 *  you'll be able to use more support code.
38 *
39 *  NOTE: When constructing trees, ANTLR can build any kind of tree; it can
40 *  even use Token objects as trees if you add a child list to your tokens.
41 *
42 *  This is a tree node without any payload; just navigation and factory stuff.
43 */
44public interface Tree {
45	public static final Tree INVALID_NODE = new CommonTree(Token.INVALID_TOKEN);
46
47	Tree getChild(int i);
48
49	int getChildCount();
50
51	// Tree tracks parent and child index now > 3.0
52
53	public Tree getParent();
54
55	public void setParent(Tree t);
56
57    /** Is there is a node above with token type ttype? */
58    public boolean hasAncestor(int ttype);
59
60    /** Walk upwards and get first ancestor with this token type. */
61    public Tree getAncestor(int ttype);
62
63    /** Return a list of all ancestors of this node.  The first node of
64     *  list is the root and the last is the parent of this node.
65     */
66    public List getAncestors();
67
68    /** This node is what child index? 0..n-1 */
69	public int getChildIndex();
70
71	public void setChildIndex(int index);
72
73	/** Set the parent and child index values for all children */
74	public void freshenParentAndChildIndexes();
75
76	/** Add t as a child to this node.  If t is null, do nothing.  If t
77	 *  is nil, add all children of t to this' children.
78	 */
79	void addChild(Tree t);
80
81	/** Set ith child (0..n-1) to t; t must be non-null and non-nil node */
82	public void setChild(int i, Tree t);
83
84	public Object deleteChild(int i);
85
86	/** Delete children from start to stop and replace with t even if t is
87	 *  a list (nil-root tree).  num of children can increase or decrease.
88	 *  For huge child lists, inserting children can force walking rest of
89	 *  children to set their childindex; could be slow.
90	 */
91	public void replaceChildren(int startChildIndex, int stopChildIndex, Object t);
92
93	/** Indicates the node is a nil node but may still have children, meaning
94	 *  the tree is a flat list.
95	 */
96	boolean isNil();
97
98	/**  What is the smallest token index (indexing from 0) for this node
99	 *   and its children?
100	 */
101	int getTokenStartIndex();
102
103	void setTokenStartIndex(int index);
104
105	/**  What is the largest token index (indexing from 0) for this node
106	 *   and its children?
107	 */
108	int getTokenStopIndex();
109
110	void setTokenStopIndex(int index);
111
112	Tree dupNode();
113
114	/** Return a token type; needed for tree parsing */
115	int getType();
116
117	String getText();
118
119	/** In case we don't have a token payload, what is the line for errors? */
120	int getLine();
121
122	int getCharPositionInLine();
123
124	String toStringTree();
125
126	String toString();
127}
128