Home | History | Annotate | Download | only in include 
      1 /** Interface for an ANTLR3 common tree which is what gets
      2  *  passed around by the AST producing parser.
      3  */
      4 
      5 #ifndef	_ANTLR3_COMMON_TREE_H
      6 #define	_ANTLR3_COMMON_TREE_H
      7 
      8 // [The "BSD licence"]
      9 // Copyright (c) 2005-2009 Jim Idle, Temporal Wave LLC
     10 // http://www.temporal-wave.com
     11 // http://www.linkedin.com/in/jimidle
     12 //
     13 // All rights reserved.
     14 //
     15 // Redistribution and use in source and binary forms, with or without
     16 // modification, are permitted provided that the following conditions
     17 // are met:
     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.
     25 //
     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.
     36 
     37 #include    <antlr3defs.h>
     38 #include    <antlr3basetree.h>
     39 #include    <antlr3commontoken.h>
     40 
     41 #ifdef __cplusplus
     42 extern "C" {
     43 #endif
     44 
     45 typedef struct ANTLR3_COMMON_TREE_struct
     46 {
     47 
     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.
     51     ///
     52     void					* super;
     53 
     54     /// Start token index that encases this tree
     55     ///
     56     ANTLR3_MARKER			  startIndex;
     57 
     58     /// End token that encases this tree
     59     ///
     60     ANTLR3_MARKER			  stopIndex;
     61 
     62     /// A single token, this is the payload for the tree
     63     ///
     64     pANTLR3_COMMON_TOKEN      token;
     65 
     66 	/// Points to the node that has this node as a child.
     67 	/// If this is NULL, then this is the root node.
     68 	///
     69 	pANTLR3_COMMON_TREE		  parent;
     70 
     71 	/// What index is this particular node in the child list it
     72 	/// belongs to?
     73 	///
     74 	ANTLR3_INT32			  childIndex;
     75 
     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
     79 	///
     80 	pANTLR3_ARBORETUM	factory;
     81 
     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.
    103     ///
    104     ANTLR3_BASE_TREE	    baseTree;
    105 
    106 }
    107     ANTLR3_COMMON_TREE;
    108 
    109 /// \brief ANTLR3 Tree factory interface to create lots of trees efficiently
    110 ///  rather than creating and freeing lots of little bits of memory.
    111 ///
    112 typedef	struct ANTLR3_ARBORETUM_struct
    113 {
    114     /// Pointers to the array of tokens that this factory has produced so far
    115     ///
    116     pANTLR3_COMMON_TREE    *pools;
    117 
    118     /// Current pool tokens we are allocating from
    119     ///
    120     ANTLR3_INT32			thisPool;
    121 
    122     /// The next token to throw out from the pool, will cause a new pool allocation
    123     ///  if this exceeds the available tokenCount
    124     ///
    125     ANTLR3_UINT32			nextTree;
    126 
    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.
    129     ///
    130     ANTLR3_COMMON_TREE	    unTruc;
    131 
    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.
    140     ///
    141     pANTLR3_VECTOR_FACTORY   vFactory;
    142 
    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.
    146     ///
    147     pANTLR3_STACK           nilStack;
    148 
    149     /// Pointer to a function that returns a new tree
    150     ///
    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);
    154 
    155     /// Pointer to a function the destroys the factory
    156     ///
    157     void		    (*close)	    (struct ANTLR3_ARBORETUM_struct * factory);
    158 }
    159     ANTLR3_ARBORETUM;
    160 
    161 #ifdef __cplusplus
    162 }
    163 #endif
    164 
    165 #endif
    166 
    167 
    168