diff options
Diffstat (limited to 'impl/antlr/libantlr3c-3.4/doxygen/atsections.dox')
| -rw-r--r-- | impl/antlr/libantlr3c-3.4/doxygen/atsections.dox | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/impl/antlr/libantlr3c-3.4/doxygen/atsections.dox b/impl/antlr/libantlr3c-3.4/doxygen/atsections.dox new file mode 100644 index 0000000..bd4ea12 --- /dev/null +++ b/impl/antlr/libantlr3c-3.4/doxygen/atsections.dox @@ -0,0 +1,143 @@ +/// \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. +///
\ No newline at end of file |