1buildrec(3)                         ANTLR3C                        buildrec(3)
2
3
4

NAME

6       buildrec - How to build Generated C Code
7
8

Generated Files

10       The antlr tool jar, run against a grammar file that targets the C
11       language, will generate the following files according to whether your
12       grammar file contains a lexer, parser, combined or treeparser
13       specification. Your grammar file name and the subject of the grammar
14       line in your file are expected to match. Here the generic name G is
15       used:
16
17       Suffix  Generated files   lexer grammar (G.g3l)  GLexer.c GLexer.h
18       parser grammar (G.g3p)  GParser.c GParser.h   grammar G (G.g3pl)
19       GParser.c GParser.h GLexer.c GLexer.h  tree grammar G; (G.g3t)  G.c G.h
20
21       The generated .c files reference the .h files using <G.h>, so you must
22       use -I. on your compiler command line (or include the current directory
23       in your include paths in Visual Studio). Additionally, the generated .h
24       files reference antlr3.h, so you must use -I/path/to/antlr/include
25       (E.g. -I /usr/local/include) to reference the standard ANTLR include
26       files.
27
28       In order to reference the library file at compile time (you can/should
29       only reference one) you need to use the -L/path/to/antlr/lib (E.g. -L
30       /usr/local/lib) on Unix, or add the path to your 'Additional Library
31       Path' in Visual Studio. You also need to specify the library using -L
32       on Unix (E.g. -L /usr/local/lib -l antlr3c) or add antlr3c_dll.lib to
33       your Additional Library Dependencies in Visual Studio.
34
35       In case it isn't obvious, the generated files may be used to produce
36       either a library or an executable (.EXE on Windows) file.
37
38       If you use the shared version of the libraries, DLL or .so/.so/.a then
39       you must ship the library with your application must run in an
40       environment whereby the library can be found by the runtime
41       linker/loader. This usually involves specifying the directory in which
42       the library lives to an environment variable. On Windows,
43       X:{yourwininstalldir}\system32 will be searched automatically.
44

Invoking Your Generated Recognizer

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