summaryrefslogtreecommitdiff
path: root/impl/antlr/libantlr3c-3.4/doxygen/atsections.dox
diff options
context:
space:
mode:
Diffstat (limited to 'impl/antlr/libantlr3c-3.4/doxygen/atsections.dox')
-rw-r--r--impl/antlr/libantlr3c-3.4/doxygen/atsections.dox143
1 files changed, 0 insertions, 143 deletions
diff --git a/impl/antlr/libantlr3c-3.4/doxygen/atsections.dox b/impl/antlr/libantlr3c-3.4/doxygen/atsections.dox
deleted file mode 100644
index bd4ea12..0000000
--- a/impl/antlr/libantlr3c-3.4/doxygen/atsections.dox
+++ /dev/null
@@ -1,143 +0,0 @@
-/// \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