| blob | 1c19c3671df2763615ddd52630a487811fcf4c6f |
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 ASCII/latin-1 memory string use:
89 /// // input = antlr3NewAsciiStringInPlaceStream (stringtouse, (ANTLR3_UINT32) length, NULL);
90 /// //
91 /// // For a UCS2 (16 bit) memory string use:
92 /// // input = antlr3NewUCS2StringInPlaceStream (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 antlr3AsciiFileStreamNew for UCS2/16bit input).
160 /// //
161 /// input = antlr3AsciiFileStreamNew(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 ///