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