1atsections(3) ANTLR3C atsections(3)
2
6 atsections - .TH "atsections" 3 "Wed Oct 13 2010" "Version 3.1.2"
7 "ANTLR3C"
8
10 atsections - .SH "Introduction"
11 A C targeted grammar can make use of special annotations within a
13 grammar file, which are prefixed with the @ character. These sections
14 cause the the placement of their contents within the generated code at
15 defined points such as within the generated C header file.
16 The general form of these annotations is:
18 section
20 : '@' (( 'parser' | 'lexer' ) '::')? SECTIONNAME '{' yourcode '}'
21 ;
22 If the 'parser' or lexer keywords are left out of the specification,
24 then the ANTLR tool assumes a lexer target for a lexer grammar, a
25 parser target for a parser or tree parser grammar, and a parser target
26 for a combined lexer/parser grammar. You are advised as a matter of
27 course to include the parser or lexer target keyword.
28 Documentation regarding the @sections available for a grammar targeted
30 at C now follows.
31 Sections @init and @declarations
33 Java targeted grammars allow the special section @init to be placed
34 after the declaration of a rule (lexer, parser and tree parser rules).
35 This allows you to both declare and initialize variables that are local
36 to the code generated for that rule. You can then reference them within
37 your rule action code.
38 With the C target, the generated code is subject to the restrictions of
40 C semantics and this means that you must declare any local variables,
41 then assign to them afterwards. As well as the @init section, which C
42 programmers should use to initialize their local variables, the C
43 target provides the @declarations section, which is also a rule based
44 section. This section is where the C programmer should declare the
45 local variables, thus separating their declaration from their
46 initialization. Here is an example:
47 translation_unit
49 @declarations
50 {
51 pANTLR3_BOOLEAN hasUsing;
52 }
53 @init
54 {
55 // Assume no Using directives
57 //
58 hasUsing = ANTLR3_FALSE;
59 }
61 : rulea ruleb ...
62 Using the @declarations and @init sections guarantees that your
64 generated code will compile correctly on any standard C compiler
65 (assuming, of course, that you type in valid C code.)
66 @header section.
68 The @parser::header or @lexer::header annotations cause the code they
69 encapsulate to be placed at the start of each generated file,
70 regardless of whether it is a .c or .h file. This can be useful for
71 inserting copyright information and so on in all your generated files.
72 : Be careful not to confuse this concept with placing code in the
74 generated .h header file. The name choice is unfortunate, but was
75 already used in the Java target to allow the placement of imports
76 statements in generated java classes. We have therefore kept the intent
77 of this section the same.
78 Here is an example:
80 @lexer::header
82 {
83 // Copyright (c) Jim Idle 2007 - All your grammar are belong to us.
84 }
85 @parser::header
87 {
88 // Copyright (c) Jim Idle 2007 - All your grammar are belong to us.
89 }
90 @includes section
92 The @parser::includes or @lexer::includes annotations cause the code
93 they encapsulate to be placed in the generated .h file, after the
94 standard includes required by the ANTLR generated code.
95 Here you could for instance place a #include statement to cause your
97 grammar code to include some standard definitions. Because you may use
98 multiple parsers and lexers in your solution, you should probably not
99 place define statements here, but in the @postinclude section. Then you
100 may create different #defines for different recognizers.
101 Here is an example:
103 @lexer::includes
105 {
106 #include 'myprojectcommondefs.h'
107 }
108 @parser::includes
110 {
111 #include 'myprojectcommondefs.h'
112 }
113 @preincludes section
115 The @parser::preincludes or @lexer::preincludes annotations cause the
116 code they encapsulate to be placed in the generated .h file, before the
117 standard includes required by the ANTLR generated code.
118 You should use this section when you wish to place defines and other
120 definitions in the code before the standard ANTLR runtime includes
121 defined them. This allows you to override any predefined symbols and
122 options that the includes otherwise take defaults for. For instance, if
123 you have built a version of the runtime with a special version of
124 malloc, you can #define ANTLR3_MALLOC to match the definition you used
125 for the ANTLR runtime library.
126 @postinclude section
128 The @parser::postinclude or @lexer::postinclude annotations cause the
129 code they encapsulate to be placed in the generated .C file, after the
130 generated include file (which includes the standard ANTLR3C library
131 includes.
132 Code you place here then will be subject to any macros defined by your
134 own includes, by the generated include and by the standard ANTLR3
135 includes. This is a good place to #undef anything that you don;t like
136 the default values of, but cannot override before the includes define
137 them.
138 This is also a good place to define any macros you may wish to use in
140 the generated .c file. As you can include multiple parsers in your
141 projects, you will need to include the generated .h file of each of
142 them, possibly globally, but almost certainly in a context where you
143 are including more than one .h file simultaneously. Hence if you
144 commonly use the same macro names for accessing structures and so on,
145 and they change from grammar to grammar, you should define them here to
146 avoid creating conflicting definitions in the header files.
147Version 3.1.2 Wed Oct 13 2010 atsections(3)