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
33namespace Antlr.Runtime.Tree {
34    using System.Collections.Generic;
35
36    /** <summary>
37     *  What does a tree look like?  ANTLR has a number of support classes
38     *  such as CommonTreeNodeStream that work on these kinds of trees.  You
39     *  don't have to make your trees implement this interface, but if you do,
40     *  you'll be able to use more support code.
41     *  </summary>
42     *
43     *  <remarks>
44     *  NOTE: When constructing trees, ANTLR can build any kind of tree; it can
45     *  even use Token objects as trees if you add a child list to your tokens.
46     *
47     *  This is a tree node without any payload; just navigation and factory stuff.
48     *  </remarks>
49     */
50    public interface ITree {
51
52        ITree GetChild(int i);
53
54        int ChildCount {
55            get;
56        }
57
58        // Tree tracks parent and child index now > 3.0
59
60        ITree Parent {
61            get;
62            set;
63        }
64
65        /** <summary>Is there is a node above with token type ttype?</summary> */
66        bool HasAncestor(int ttype);
67
68        /** <summary>Walk upwards and get first ancestor with this token type.</summary> */
69        ITree GetAncestor(int ttype);
70
71        /** <summary>
72         *  Return a list of all ancestors of this node.  The first node of
73         *  list is the root and the last is the parent of this node.
74         *  </summary>
75         */
76        IList<ITree> GetAncestors();
77
78        /** <summary>This node is what child index? 0..n-1</summary> */
79        int ChildIndex {
80            get;
81            set;
82        }
83
84        /** <summary>Set the parent and child index values for all children</summary> */
85        void FreshenParentAndChildIndexes();
86
87        /** <summary>
88         *  Add t as a child to this node.  If t is null, do nothing.  If t
89         *  is nil, add all children of t to this' children.
90         *  </summary>
91         */
92        void AddChild(ITree t);
93
94        /** <summary>Set ith child (0..n-1) to t; t must be non-null and non-nil node</summary> */
95        void SetChild(int i, ITree t);
96
97        object DeleteChild(int i);
98
99        /** <summary>
100         *  Delete children from start to stop and replace with t even if t is
101         *  a list (nil-root tree).  num of children can increase or decrease.
102         *  For huge child lists, inserting children can force walking rest of
103         *  children to set their childindex; could be slow.
104         *  </summary>
105         */
106        void ReplaceChildren(int startChildIndex, int stopChildIndex, object t);
107
108        /** <summary>
109         *  Indicates the node is a nil node but may still have children, meaning
110         *  the tree is a flat list.
111         *  </summary>
112         */
113        bool IsNil {
114            get;
115        }
116
117        /** <summary>
118         *  What is the smallest token index (indexing from 0) for this node
119         *  and its children?
120         *  </summary>
121         */
122        int TokenStartIndex {
123            get;
124            set;
125        }
126
127        /** <summary>
128         *  What is the largest token index (indexing from 0) for this node
129         *  and its children?
130         *  </summary>
131         */
132        int TokenStopIndex {
133            get;
134            set;
135        }
136
137        ITree DupNode();
138
139        /** <summary>Return a token type; needed for tree parsing</summary> */
140        int Type {
141            get;
142        }
143
144        string Text {
145            get;
146        }
147
148        /** <summary>In case we don't have a token payload, what is the line for errors?</summary> */
149        int Line {
150            get;
151        }
152
153        int CharPositionInLine {
154            get;
155        }
156
157        string ToStringTree();
158
159        string ToString();
160    }
161}
162