1atsections(3)                       ANTLR3C                      atsections(3)
2
3
4

NAME

6       atsections - Using Sections Within Grammar Files
7
8

Introduction

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