1#ifndef	ANTLR3REWRITESTREAM_H
2#define	ANTLR3REWRITESTREAM_H
3
4// [The "BSD licence"]
5// Copyright (c) 2005-2009 Jim Idle, Temporal Wave LLC
6// http://www.temporal-wave.com
7// http://www.linkedin.com/in/jimidle
8//
9// All rights reserved.
10//
11// Redistribution and use in source and binary forms, with or without
12// modification, are permitted provided that the following conditions
13// are met:
14// 1. Redistributions of source code must retain the above copyright
15//    notice, this list of conditions and the following disclaimer.
16// 2. Redistributions in binary form must reproduce the above copyright
17//    notice, this list of conditions and the following disclaimer in the
18//    documentation and/or other materials provided with the distribution.
19// 3. The name of the author may not be used to endorse or promote products
20//    derived from this software without specific prior written permission.
21//
22// THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
23// IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
24// OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
25// IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
26// INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
27// NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
31// THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32
33#include    <antlr3defs.h>
34#include    <antlr3collections.h>
35#include    <antlr3commontreeadaptor.h>
36#include	<antlr3baserecognizer.h>
37
38#ifdef __cplusplus
39extern "C" {
40#endif
41
42/// A generic list of elements tracked in an alternative to be used in
43/// a -> rewrite rule.
44///
45/// In the C implementation, all tree oriented streams return a pointer to
46/// the same type: pANTLR3_BASE_TREE. Anything that has subclassed from this
47/// still passes this type, within which there is a super pointer, which points
48/// to it's own data and methods. Hence we do not need to implement this as
49/// the equivalent of an abstract class, but just fill in the appropriate interface
50/// as usual with this model.
51///
52/// Once you start next()ing, do not try to add more elements.  It will
53/// break the cursor tracking I believe.
54///
55///
56/// \see #pANTLR3_REWRITE_RULE_NODE_STREAM
57/// \see #pANTLR3_REWRITE_RULE_ELEMENT_STREAM
58/// \see #pANTLR3_REWRITE_RULE_SUBTREE_STREAM
59///
60/// TODO: add mechanism to detect/puke on modification after reading from stream
61///
62typedef struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct
63{
64
65    /// Cursor 0..n-1.  If singleElement!=NULL, cursor is 0 until you next(),
66    /// which bumps it to 1 meaning no more elements.
67    ///
68    ANTLR3_UINT32		  cursor;
69
70    /// Track single elements w/o creating a list.  Upon 2nd add, alloc list
71    ///
72    void			* singleElement;
73
74    /// The list of tokens or subtrees we are tracking
75    ///
76    pANTLR3_VECTOR		  elements;
77
78    /// Indicates whether we should free the vector or it was supplied to us
79    ///
80    ANTLR3_BOOLEAN		  freeElements;
81
82    /// The element or stream description; usually has name of the token or
83    /// rule reference that this list tracks.  Can include rulename too, but
84    /// the exception would track that info.
85    ///
86    void				* elementDescription;
87
88	/// Pointer to the tree adaptor in use for this stream
89	///
90    pANTLR3_BASE_TREE_ADAPTOR	  adaptor;
91
92	/// Once a node / subtree has been used in a stream, it must be dup'ed
93	/// from then on.  Streams are reset after sub rules so that the streams
94	/// can be reused in future sub rules.  So, reset must set a dirty bit.
95	/// If dirty, then next() always returns a dup.
96	///
97	ANTLR3_BOOLEAN				dirty;
98
99	// Pointer to the recognizer shared state to which this stream belongs
100	//
101	pANTLR3_BASE_RECOGNIZER		rec;
102
103    //   Methods
104
105    /// Reset the condition of this stream so that it appears we have
106    ///  not consumed any of its elements.  Elements themselves are untouched.
107    ///
108    void		(*reset)				(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream);
109
110    /// Add a new pANTLR3_BASE_TREE to this stream
111    ///
112    void		(*add)					(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream, void *el, void (ANTLR3_CDECL *freePtr)(void *));
113
114    /// Return the next element in the stream.  If out of elements, throw
115    /// an exception unless size()==1.  If size is 1, then return elements[0].
116    ///
117	void *					(*next)					(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream);
118    pANTLR3_BASE_TREE		(*nextTree)				(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream);
119    void *					(*nextToken)			(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream);
120    void *					(*_next)				(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream);
121
122    /// When constructing trees, sometimes we need to dup a token or AST
123    ///	subtree.  Dup'ing a token means just creating another AST node
124    /// around it.  For trees, you must call the adaptor.dupTree().
125    ///
126    void *		(*dup)					(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream, void * el);
127
128    /// Ensure stream emits trees; tokens must be converted to AST nodes.
129    /// AST nodes can be passed through unmolested.
130    ///
131    pANTLR3_BASE_TREE	(*toTree)		(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream, void * el);
132
133    /// Returns ANTLR3_TRUE if there is a next element available
134    ///
135    ANTLR3_BOOLEAN	(*hasNext)			(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream);
136
137    /// Treat next element as a single node even if it's a subtree.
138    /// This is used instead of next() when the result has to be a
139    /// tree root node.  Also prevents us from duplicating recently-added
140    /// children; e.g., ^(type ID)+ adds ID to type and then 2nd iteration
141    /// must dup the type node, but ID has been added.
142    ///
143    /// Referencing to a rule result twice is ok; dup entire tree as
144    /// we can't be adding trees; e.g., expr expr.
145    ///
146    pANTLR3_BASE_TREE	(*nextNode)		(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream);
147
148    /// Number of elements available in the stream
149    ///
150    ANTLR3_UINT32	(*size)				(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream);
151
152    /// Returns the description string if there is one available (check for NULL).
153    ///
154    void *			(*getDescription)	(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream);
155
156    void		(*free)					(struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct * stream);
157
158}
159    ANTLR3_REWRITE_RULE_ELEMENT_STREAM;
160
161/// This is an implementation of a token stream, which is basically an element
162///  stream that deals with tokens only.
163///
164typedef struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct ANTLR3_REWRITE_RULE_TOKEN_STREAM;
165
166/// This is an implementation of a subtree stream which is a set of trees
167///  modelled as an element stream.
168///
169typedef struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct ANTLR3_REWRITE_RULE_SUBTREE_STREAM;
170
171/// This is an implementation of a node stream, which is basically an element
172///  stream that deals with tree nodes only.
173///
174typedef struct ANTLR3_REWRITE_RULE_ELEMENT_STREAM_struct ANTLR3_REWRITE_RULE_NODE_STREAM;
175
176#ifdef __cplusplus
177}
178#endif
179
180#endif
181