| /// \page atsections Using Sections Within Grammar Files |
| /// |
| /// \section intro Introduction |
| /// |
| /// A C targeted grammar can make use of special annotations within a grammar |
| /// file, which are prefixed with the <b>\@</b> character. These sections cause the |
| /// the placement of their contents within the generated code at defined points |
| /// such as within the generated C header file. |
| /// |
| /// The general form of these annotations is: |
| /// |
| /// \code |
| /// section |
| /// : '@' (( 'parser' | 'lexer' ) '::')? SECTIONNAME '{' yourcode '}' |
| /// ; |
| /// \endcode |
| /// |
| /// If the 'parser' or lexer keywords are left out of the specification, then the |
| /// ANTLR tool assumes a lexer target for a lexer grammar, a parser target for a parser |
| /// or tree parser grammar, and a parser target for a combined lexer/parser grammar. You |
| /// are advised as a matter of course to include the parser or lexer target keyword. |
| /// |
| /// Documentation regarding the \@sections available for a grammar targeted at C now |
| /// follows. |
| /// |
| /// \subsection psrinit Sections \@init and \@declarations |
| /// |
| /// Java targeted grammars allow the special section <code>\@init</code> to be placed after the declaration |
| /// of a rule (lexer, parser and tree parser rules). This allows you to both declare and initialize |
| /// variables that are local to the code generated for that rule. You can then reference them within |
| /// your rule action code. |
| /// |
| /// With the C target, the generated code is subject to the restrictions of C semantics and this |
| /// means that you must declare any local variables, then assign to them afterwards. As well as the |
| /// <code>\@init</code> section, which C programmers should use to initialize their local variables, the C |
| /// target provides the <code>\@declarations</code> section, which is also a rule based section. This section |
| /// is where the C programmer should declare the local variables, thus separating their declaration |
| /// from their initialization. Here is an example: |
| /// |
| /// \code |
| /// translation_unit |
| /// @declarations |
| /// { |
| /// pANTLR3_BOOLEAN hasUsing; |
| /// } |
| /// @init |
| /// { |
| /// |
| /// // Assume no Using directives |
| /// // |
| /// hasUsing = ANTLR3_FALSE; |
| /// |
| /// } |
| /// : rulea ruleb ... |
| /// |
| /// \endcode |
| /// |
| /// Using the <code>\@declarations</code> and <code>\@init</code> sections guarantees that your generated code will |
| /// compile correctly on any standard C compiler (assuming, of course, that you type in valid C code.) |
| /// |
| /// \subsection psrheader \@header section. |
| /// |
| /// The <code>\@parser::header</code> or <code>\@lexer::header</code> annotations cause the code they encapsulate |
| /// to be placed at the start of each generated file, regardless of whether it is a .c or .h file. This can |
| /// be useful for inserting copyright information and so on in all your generated files. |
| /// |
| /// \bNOTE: Be careful not to confuse this concept with placing code in the generated .h header file. The name choice is |
| /// unfortunate, but was already used in the Java target to allow the placement of \c imports statements |
| /// in generated java classes. We have therefore kept the intent of this section the same. |
| /// |
| /// Here is an example: |
| //// |
| /// \code |
| /// @lexer::header |
| /// { |
| /// // Copyright (c) Jim Idle 2007 - All your grammar are belong to us. |
| /// } |
| /// |
| /// @parser::header |
| /// { |
| /// // Copyright (c) Jim Idle 2007 - All your grammar are belong to us. |
| /// } |
| /// \endcode |
| /// |
| /// |
| /// \subsection hdrinclude \@includes section |
| /// |
| /// The <code>\@parser::includes</code> or <code>\@lexer::includes</code> annotations cause |
| /// the code they encapsulate to be placed in the generated .h file, \b after the standard |
| /// includes required by the ANTLR generated code. |
| /// |
| /// Here you could for instance place a <code>\#include</code> |
| /// statement to cause your grammar code to include some standard definitions. Because you |
| /// may use multiple parsers and lexers in your solution, you should probably not place |
| /// <code>#define</code> statements here, but in the <code>\@postinclude</code> section. Then you |
| /// may create different <code>\#defines</code> for different recognizers. |
| /// |
| /// Here is an example: |
| //// |
| /// \code |
| /// @lexer::includes |
| /// { |
| /// #include "myprojectcommondefs.h" |
| /// } |
| /// |
| /// @parser::includes |
| /// { |
| /// #include "myprojectcommondefs.h" |
| /// } |
| /// \endcode |
| /// |
| /// |
| /// \subsection hdrpreinclude \@preincludes section |
| /// |
| /// The <code>\@parser::preincludes</code> or <code>\@lexer::preincludes</code> annotations cause |
| /// the code they encapsulate to be placed in the generated .h file, \b before the standard |
| /// includes required by the ANTLR generated code. |
| /// |
| /// You should use this section when you wish to place #defines and other definitions |
| /// in the code before the standard ANTLR runtime includes defined them. This allows you |
| /// to override any predefined symbols and options that the includes otherwise take |
| /// defaults for. For instance, if you have built a version of the runtime with a |
| /// special version of malloc, you can <code>\#define</code> #ANTLR3_MALLOC to match the definition |
| /// you used for the ANTLR runtime library. |
| /// |
| /// \subsection hdrpostinclude \@postinclude section |
| /// |
| /// The <code>\@parser::postinclude</code> or <code>\@lexer::postinclude</code> annotations cause |
| /// the code they encapsulate to be placed in the generated <b>.C</b> file, after the generated include |
| /// file (which includes the standard ANTLR3C library includes. |
| /// |
| /// Code you place here then will be subject to any macros defined by your own includes, by the |
| /// generated include and by the standard ANTLR3 includes. This is a good place to <code>\#undef</code> |
| /// anything that you don;t like the default values of, but cannot override before the includes |
| /// define them. |
| /// |
| /// This is also a good place to <code>#define</code> any macros you may wish to use in the generated |
| /// .c file. As you can include multiple parsers in your projects, you will need to include the |
| /// generated .h file of each of them, possibly globally, but almost certainly in a context where you |
| /// are including more than one .h file simultaneously. Hence if you commonly use the same macro |
| /// names for accessing structures and so on, and they change from grammar to grammar, you should |
| /// define them here to avoid creating conflicting definitions in the header files. |
| /// |