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 ///
