1buildrec(3) ANTLR3C buildrec(3)
2
6 buildrec - How to build Generated C Code
7
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 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 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 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 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 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
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 // 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 // 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 // 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 // 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 // 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 // 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 // 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 // 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 // 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 // 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 // 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 // Create the input stream using the supplied file name
154 // (Use antlr38BitFileStreamNew for UTF16 input).
155 //
156 input = antlr38BitFileStreamNew(fName);
157 // 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 // 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 // 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 // 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 if (tstream == NULL)
195 {
196 ANTLR3_FPRINTF(stderr, "Out of memory trying to allocate token stream0);
197 exit(ANTLR3_ERR_NOMEM);
198 }
199 // Finally, now that we have our lexer constructed, we can create the parser
201 //
202 psr = LangParserNew(tstream); // CParserNew is generated by ANTLR3
203 if (psr == NULL)
205 {
206 ANTLR3_FPRINTF(stderr, "Out of memory trying to allocate parser0);
207 exit(ANTLR3_ERR_NOMEM);
208 }
209 // 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 // 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 }
240 else
241 {
242 nodes = antlr3CommonTreeNodeStreamNewTree(langAST.tree, ANTLR3_SIZE_HINT); // sIZE HINT WILL SOON BE DEPRECATED!!
243 // Tree parsers are given a common tree node stream (or your override)
245 //
246 treePsr = LangDumpDeclNew(nodes);
247 treePsr->decl(treePsr);
249 nodes ->free (nodes); nodes = NULL;
250 treePsr ->free (treePsr); treePsr = NULL;
251 }
252 // 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 return 0;
262 }
263Version 3.3.1 Fri May 3 2019 buildrec(3)