thirdparty/libantlr3c-3.2/doxygen/atsections.dox

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