1 /** Interface for an ANTLR3 common tree which is what gets
2 * passed around by the AST producing parser.
5 #ifndef _ANTLR3_COMMON_TREE_H
6 #define _ANTLR3_COMMON_TREE_H
9 // Copyright (c) 2005-2009 Jim Idle, Temporal Wave LLC
10 // http://www.temporal-wave.com
11 // http://www.linkedin.com/in/jimidle
13 // All rights reserved.
15 // Redistribution and use in source and binary forms, with or without
16 // modification, are permitted provided that the following conditions
18 // 1. Redistributions of source code must retain the above copyright
19 // notice, this list of conditions and the following disclaimer.
20 // 2. Redistributions in binary form must reproduce the above copyright
21 // notice, this list of conditions and the following disclaimer in the
22 // documentation and/or other materials provided with the distribution.
23 // 3. The name of the author may not be used to endorse or promote products
24 // derived from this software without specific prior written permission.
26 // THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
27 // IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
28 // OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
29 // IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
30 // INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
31 // NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
35 // THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37 #include <antlr3defs.h>
38 #include <antlr3basetree.h>
39 #include <antlr3commontoken.h>
45 typedef struct ANTLR3_COMMON_TREE_struct
48 /// Not used by ANTLR, but if a super structure is created above
49 /// this structure, it can be used to point to the start of the super
50 /// structure, where additional data and function pointers can be stored.
54 /// Start token index that encases this tree
56 ANTLR3_MARKER startIndex;
58 /// End token that encases this tree
60 ANTLR3_MARKER stopIndex;
62 /// A single token, this is the payload for the tree
64 pANTLR3_COMMON_TOKEN token;
66 /// Points to the node that has this node as a child.
67 /// If this is NULL, then this is the root node.
69 pANTLR3_COMMON_TREE parent;
71 /// What index is this particular node in the child list it
74 ANTLR3_INT32 childIndex;
76 /// Pointer to the tree factory that manufactured this
77 /// token. This can be used by duplication methods and so on
78 /// to manufacture another auto-tracked common tree structure
80 pANTLR3_ARBORETUM factory;
82 /// An encapsulated BASE TREE structure (NOT a pointer)
83 /// that performs a lot of the dirty work of node management
84 /// To this we add just a few functions that are specific to the
85 /// payload. You can further abstract common tree so long
86 /// as you always have a baseTree pointer in the top structure
87 /// and copy it from the next one down.
88 /// So, lets say we have a structure JIMS_TREE.
89 /// It needs an ANTLR3_BASE_TREE that will support all the
90 /// general tree duplication stuff.
91 /// It needs a ANTLR3_COMMON_TREE structure embedded or completely
92 /// provides the equivalent interface.
93 /// It provides it's own methods and data.
94 /// To create a new one of these, the function provided to
95 /// the tree adaptor (see comments there) should allocate the
96 /// memory for a new JIMS_TREE structure, then call
97 /// antlr3InitCommonTree(<addressofembeddedCOMMON_TREE>)
98 /// antlr3BaseTreeNew(<addressofBASETREE>)
99 /// The interfaces for BASE_TREE and COMMON_TREE will then
100 /// be initialized. You then call and you can override them or just init
101 /// JIMS_TREE (note that the base tree in common tree will be ignored)
102 /// just the top level base tree is used). Codegen will take care of the rest.
104 ANTLR3_BASE_TREE baseTree;
109 /// \brief ANTLR3 Tree factory interface to create lots of trees efficiently
110 /// rather than creating and freeing lots of little bits of memory.
112 typedef struct ANTLR3_ARBORETUM_struct
114 /// Pointers to the array of tokens that this factory has produced so far
116 pANTLR3_COMMON_TREE *pools;
118 /// Current pool tokens we are allocating from
120 ANTLR3_INT32 thisPool;
122 /// The next token to throw out from the pool, will cause a new pool allocation
123 /// if this exceeds the available tokenCount
125 ANTLR3_UINT32 nextTree;
127 /// Trick to initialize tokens and their API quickly, we set up this token when the
128 /// factory is created, then just copy the memory it uses into the new token.
130 ANTLR3_COMMON_TREE unTruc;
132 /// Pointer to a vector factory that is used to create child list vectors
133 /// for any child nodes that need them. This means that we auto track the
134 /// vectors and auto free them when we close the factory. It also means
135 /// that all rewriting trees can use the same tree factory and the same
136 /// vector factory and we do not dup any nodes unless we must do so
137 /// explicitly because of context such as an empty rewrite stream and
138 /// ->IMAGINARY[ID] so on. This makes memory tracking much simpler and
139 /// tempts no errors.
141 pANTLR3_VECTOR_FACTORY vFactory;
143 /// A resuse stack for reclaiming Nil nodes that were used in rewrites
144 /// and are now dead. The nilNode() method will eat one of these before
145 /// creating a new node.
147 pANTLR3_STACK nilStack;
149 /// Pointer to a function that returns a new tree
151 pANTLR3_BASE_TREE (*newTree) (struct ANTLR3_ARBORETUM_struct * factory);
152 pANTLR3_BASE_TREE (*newFromTree) (struct ANTLR3_ARBORETUM_struct * factory, pANTLR3_COMMON_TREE tree);
153 pANTLR3_BASE_TREE (*newFromToken) (struct ANTLR3_ARBORETUM_struct * factory, pANTLR3_COMMON_TOKEN token);
155 /// Pointer to a function the destroys the factory
157 void (*close) (struct ANTLR3_ARBORETUM_struct * factory);