buildrec.dox revision 324c4644fee44b9898524c09511bd33c3f12e2df 
1/// \page buildrec How to build Generated C Code
2///
3/// \section generated Generated Files
4///
5/// The antlr tool jar, run against a grammar file that targets the C language, will generate the following files 
6/// according to whether your grammar file contains a lexer, parser, combined or treeparser specification. 
7/// Your grammar file name and the subject of the grammar line in your file are expected to match. Here the generic name G is used:
8///
9/// <table>
10/// <tr>
11/// <th> Suffix </th>
12/// <th> Generated files </th>
13/// </tr>
14/// <tr>
15/// <td> lexer grammar (G.g3l) </td>
16/// <td> GLexer.c GLexer.h</td>
17/// </tr>
18/// <tr>
19/// <td> parser grammar (G.g3p) </td>
20/// <td> GParser.c GParser.h </td>
21/// </tr>
22/// <tr>
23/// <td> grammar G (G.g3pl) </td>
24/// <td> GParser.c GParser.h GLexer.c GLexer.h</td>
25/// </tr>
26/// <tr>
27/// <td> tree grammar G; (G.g3t) </td>
28/// <td> G.c G.h </td>
29/// </tr>
30/// </table>
31///
32/// The generated .c files reference the .h files using <G.h>, so you must use <code>-I.</code> on your compiler command line 
33/// (or include the current directory in your include paths in Visual Studio). Additionally, the generated .h files reference 
34/// <code>antlr3.h</code>, so you must use <code>-I/path/to/antlr/include</code> (E.g. <code>-I /usr/local/include</code>) to reference the standard ANTLR include files.
35///
36/// In order to reference the library file at compile time (you can/should only reference one) you need to use the 
37/// <code>-L/path/to/antlr/lib</code> (E.g. <code>-L /usr/local/lib</code>) on Unix, or add the path to your "Additional Library Path" in 
38/// Visual Studio. You also need to specify the library using <code>-L</code> on Unix (E.g. <code>-L /usr/local/lib -l antlr3c</code>) or add <code>antlr3c_dll.lib</code>
39/// to your Additional Library Dependencies in Visual Studio.
40///
41/// In case it isn't obvious, the generated files may be used to produce either a library or an executable (.EXE on Windows) file.
42///
43/// If you use the shared version of the libraries, DLL or .so/.so/.a then you must ship the library with your 
44/// application must run in an environment whereby the library can be found by the runtime linker/loader. 
45/// This usually involves specifying the directory in which the library lives to an environment variable. 
46/// On Windows, X:{yourwininstalldir}\system32 will be searched automatically.
47///
48/// \section invoke Invoking Your Generated Recognizer
49///
50/// In order to run your lexer/parser/tree parser combination, you will need a small function (or main)
51/// function that controls the sequence of events, from reading the input file or string, through to
52/// invoking the tree parser(s) and retrieving the results. See "Using the ANTLR3C C Target" for more
53/// detailed instructions, but if you just want to get going as fast as possible, study the following
54/// code example.
55///
56/// \code
57///
58/// // You may adopt your own practices by all means, but in general it is best
59/// // to create a single include for your project, that will include the ANTLR3 C
60/// // runtime header files, the generated header files (all of which are safe to include
61/// // multiple times) and your own project related header files. Use <> to include and
62/// // -I on the compile line (which vs2005 now handles, where vs2003 did not).
63/// //
64/// #include    <treeparser.h>
65/// 
66/// // Main entry point for this example
67/// //
68/// int ANTLR3_CDECL
69/// main	(int argc, char *argv[])
70/// {
71///     // Now we declare the ANTLR related local variables we need.
72///     // Note that unless you are convinced you will never need thread safe
73///     // versions for your project, then you should always create such things
74///     // as instance variables for each invocation.
75///     // -------------------
76/// 
77///     // Name of the input file. Note that we always use the abstract type pANTLR3_UINT8
78///     // for ASCII/8 bit strings - the runtime library guarantees that this will be
79///     // good on all platforms. This is a general rule - always use the ANTLR3 supplied
80///     // typedefs for pointers/types/etc.
81///     //
82///     pANTLR3_UINT8	    fName;
83/// 
84///     // The ANTLR3 character input stream, which abstracts the input source such that
85///     // it is easy to privide inpput from different sources such as files, or 
86///     // memory strings.
87///     //
88///     // For an 8Bit/latin-1/etc memory string use:
89///     //	    input = antlr3New8BitStringInPlaceStream (stringtouse, (ANTLR3_UINT32) length, NULL);
90///     //
91///     // For a UTF16 memory string use:
92///     //	    input = antlr3NewUTF16StringInPlaceStream (stringtouse, (ANTLR3_UINT32) length, NULL);
93///     //
94///     // For input from a file, see code below
95///     //
96///     // Note that this is essentially a pointer to a structure containing pointers to functions.
97///     // You can create your own input stream type (copy one of the existing ones) and override any
98///     // individual function by installing your own pointer after you have created the standard 
99///     // version.
100///     //
101///     pANTLR3_INPUT_STREAM	    input;
102/// 
103///     // The lexer is of course generated by ANTLR, and so the lexer type is not upper case.
104///     // The lexer is supplied with a pANTLR3_INPUT_STREAM from whence it consumes its
105///     // input and generates a token stream as output. This is the ctx (CTX macro) pointer
106///		// for your lexer.
107///     //
108///     pLangLexer			    lxr;
109/// 
110///     // The token stream is produced by the ANTLR3 generated lexer. Again it is a structure based
111///     // API/Object, which you can customise and override methods of as you wish. a Token stream is
112///     // supplied to the generated parser, and you can write your own token stream and pass this in
113///     // if you wish.
114///     //
115///     pANTLR3_COMMON_TOKEN_STREAM	    tstream;
116/// 
117///     // The Lang parser is also generated by ANTLR and accepts a token stream as explained
118///     // above. The token stream can be any source in fact, so long as it implements the 
119///     // ANTLR3_TOKEN_SOURCE interface. In this case the parser does not return anything
120///     // but it can of course specify any kind of return type from the rule you invoke
121///     // when calling it. This is the ctx (CTX macro) pointer for your parser.
122///     //
123///     pLangParser			    psr;
124/// 
125///     // The parser produces an AST, which is returned as a member of the return type of
126///     // the starting rule (any rule can start first of course). This is a generated type
127///     // based upon the rule we start with.
128///     //
129///     LangParser_decl_return	    langAST;
130/// 
131/// 
132///     // The tree nodes are managed by a tree adaptor, which doles
133///     // out the nodes upon request. You can make your own tree types and adaptors
134///     // and override the built in versions. See runtime source for details and
135///     // eventually the wiki entry for the C target.
136///     //
137///     pANTLR3_COMMON_TREE_NODE_STREAM	nodes;
138/// 
139///     // Finally, when the parser runs, it will produce an AST that can be traversed by the 
140///     // the tree parser: c.f. LangDumpDecl.g3t This is the ctx (CTX macro) pointer for your
141///		// tree parser.
142///     //
143///     pLangDumpDecl		    treePsr;
144/// 
145///     // Create the input stream based upon the argument supplied to us on the command line
146///     // for this example, the input will always default to ./input if there is no explicit
147///     // argument.
148///     //
149/// 	if (argc < 2 || argv[1] == NULL)
150/// 	{
151/// 		fName	=(pANTLR3_UINT8)"./input"; // Note in VS2005 debug, working directory must be configured
152/// 	}
153/// 	else
154/// 	{
155/// 		fName	= (pANTLR3_UINT8)argv[1];
156/// 	}
157/// 
158///     // Create the input stream using the supplied file name
159///     // (Use antlr38BitFileStreamNew for UTF16 input).
160///     //
161///     input	= antlr38BitFileStreamNew(fName);
162/// 
163///     // The input will be created successfully, providing that there is enough
164///     // memory and the file exists etc
165///     //
166///     if ( input == NULL )
167///     {
168/// 			ANTLR3_FPRINTF(stderr, "Unable to open file %s due to malloc() failure1\n", (char *)fName);
169///     }
170/// 
171///     // Our input stream is now open and all set to go, so we can create a new instance of our
172///     // lexer and set the lexer input to our input stream:
173///     //  (file | memory | ?) --> inputstream -> lexer --> tokenstream --> parser ( --> treeparser )?
174///     //
175///     lxr	    = LangLexerNew(input);	    // CLexerNew is generated by ANTLR
176/// 
177///     // Need to check for errors
178///     //
179///     if ( lxr == NULL )
180///     {
181/// 			ANTLR3_FPRINTF(stderr, "Unable to create the lexer due to malloc() failure1\n");
182/// 			exit(ANTLR3_ERR_NOMEM);
183///     }
184/// 
185///     // Our lexer is in place, so we can create the token stream from it
186///     // NB: Nothing happens yet other than the file has been read. We are just 
187///     // connecting all these things together and they will be invoked when we
188///     // call the parser rule. ANTLR3_SIZE_HINT can be left at the default usually
189///     // unless you have a very large token stream/input. Each generated lexer
190///     // provides a token source interface, which is the second argument to the
191///     // token stream creator.
192///     // Note tha even if you implement your own token structure, it will always
193///     // contain a standard common token within it and this is the pointer that
194///     // you pass around to everything else. A common token as a pointer within
195///     // it that should point to your own outer token structure.
196///     //
197///     tstream = antlr3CommonTokenStreamSourceNew(ANTLR3_SIZE_HINT, lxr->pLexer->tokSource);
198/// 
199///     if (tstream == NULL)
200///     {
201/// 		ANTLR3_FPRINTF(stderr, "Out of memory trying to allocate token stream\n");
202/// 		exit(ANTLR3_ERR_NOMEM);
203///     }
204/// 
205///     // Finally, now that we have our lexer constructed, we can create the parser
206///     //
207///     psr	    = LangParserNew(tstream);  // CParserNew is generated by ANTLR3
208/// 
209///     if (psr == NULL)
210///     {
211/// 		ANTLR3_FPRINTF(stderr, "Out of memory trying to allocate parser\n");
212/// 		exit(ANTLR3_ERR_NOMEM);
213///     }
214/// 
215///     // We are all ready to go. Though that looked complicated at first glance,
216///     // I am sure, you will see that in fact most of the code above is dealing
217///     // with errors and there isn;t really that much to do (isn;t this always the
218///     // case in C? ;-).
219///     //
220///     // So, we now invoke the parser. All elements of ANTLR3 generated C components
221///     // as well as the ANTLR C runtime library itself are pseudo objects. This means
222///     // that they are represented as pointers to structures, which contain any
223///     // instance data they need, and a set of pointers to other interfaces or
224///     // 'methods'. Note that in general, these few pointers we have created here are
225///     // the only things you will ever explicitly free() as everything else is created
226///     // via factories, that allocate memory efficiently and free() everything they use
227///     // automatically when you close the parser/lexer/etc.
228///     //
229///     // Note that this means only that the methods are always called via the object
230///     // pointer and the first argument to any method, is a pointer to the structure itself.
231///     // It also has the side advantage, if you are using an IDE such as VS2005 that can do it
232///     // that when you type ->, you will see a list of all the methods the object supports.
233///     //
234///     langAST = psr->decl(psr);
235/// 
236///     // If the parser ran correctly, we will have a tree to parse. In general I recommend
237///     // keeping your own flags as part of the error trapping, but here is how you can
238///     // work out if there were errors if you are using the generic error messages
239///     //
240/// 	if (psr->pParser->rec->errorCount > 0)
241/// 	{
242/// 		ANTLR3_FPRINTF(stderr, "The parser returned %d errors, tree walking aborted.\n", psr->pParser->rec->errorCount);
243/// 
244/// 	}
245/// 	else
246/// 	{
247/// 		nodes	= antlr3CommonTreeNodeStreamNewTree(langAST.tree, ANTLR3_SIZE_HINT); // sIZE HINT WILL SOON BE DEPRECATED!!
248/// 
249/// 		// Tree parsers are given a common tree node stream (or your override)
250/// 		//
251/// 		treePsr	= LangDumpDeclNew(nodes);
252/// 
253/// 		treePsr->decl(treePsr);
254/// 		nodes   ->free  (nodes);	    nodes	= NULL;
255/// 		treePsr ->free  (treePsr);	    treePsr	= NULL;
256/// 	}
257/// 
258/// 	// We did not return anything from this parser rule, so we can finish. It only remains
259/// 	// to close down our open objects, in the reverse order we created them
260/// 	//
261/// 	psr	    ->free  (psr);		psr		= NULL;
262/// 	tstream ->free  (tstream);	tstream	= NULL;
263/// 	lxr	    ->free  (lxr);	    lxr		= NULL;
264/// 	input   ->close (input);	input	= NULL;
265/// 
266///     return 0;
267/// }
268/// \endcode
269/// 
270