thirdparty/libantlr3c-3.2/doxygen/using.dox

   1 /// \page using Using the ANTLR3 C Target
   2 ///
   3 /// \section intro Introduction
   4 ///
   5 /// Using the ANTLR target involves gaining knowledge of a number of elements:
   6 ///
   7 /// -# Writing ANTLR grammars (not covered in this manual);
   8 /// -# How ANTLR works (not covered in this manual);
   9 /// -# How to use the \@sections with the C target
  10 /// -# Interoperation with the runtime within rule actions;
  11 /// -# Implementing custom versions of the standard library methods;
  12 ///
  13 /// If you are as yet unfamiliar with how ANTLR works in general, then
  14 /// it is suggested that you read the various <a href="http://www.antlr.org/wiki">wiki pages</a> concerned with
  15 /// getting started. However there are a few things that you should note:
  16 ///
  17 /// - The lexer is independent of the parser. You \b cannot control the lexer from within the parser;
  18 /// - The tree parser is independent of the parser. You \b cannot control the parser from within the tree parser(s);
  19 /// - Each tree parser is independent of other tree parsers.
  20 ///
  21 /// This means that your lexer runs first and consumes all the input stream until
  22 /// you stop it programmatically, or it reaches the end of the input stream. It produces
  23 /// a complete stream of tokens, which the parser then consumes.
  24 ///
  25 /// \section Using \@sections in a C Targeted Grammar
  26 ///
  27 /// Within a grammar file there are a number of special sections you can add that cause the
  28 /// code within them to be placed at strategic points in the generated code such as
  29 /// before or after the #include statements in the .c file, within the generated header file
  30 /// or within the constructor for the recognizer.
  31 ///
  32 /// Many of the \@sections used within a Java targeted grammar have some equivalent function within a
  33 /// C targeted grammar, but their use may well be subtly different. There are also additional sections
  34 /// that have meaning only within a grammar targeted for the C runtime.
  35 ///
  36 /// Detailed documentation of these sections is given here: \subpage atsections
  37 ///
  38 /// \section interop Interoperation Within Rule Actions
  39 ///
  40 /// Rule actions have a limited number of elements they can access by name, independently of the
  41 /// target language generated. These are elements such as $line, $pos, $text and so on. Where the
  42 /// $xxx returns a basic type such as \c int, then you can use these in C as you would in the Java
  43 /// target, but where a reference returns a string, you will get a pointer to the C runtime
  44 /// string implementation #pANTLR3_STRING. This will give you access to things like token text
  45 /// but also provides some convenience methods such as #pANTLR3_STRING->substring() and #pANTLR3_STRING->toUTF8().
  46 ///
  47 /// The generated code provides a number of C MACROs, which make it easier to access runtime
  48 /// components. Always use these macros when available, to protect your action code from changes
  49 /// to the underlying implementation.
  50 ///
  51 /// Detailed documentation of macros and rule action interoperation is given here: \subpage interop
  52 ///
  53 /// \section Custom Implementing Customized Methods
  54 ///
  55 /// Unless you wish to create your own tree structures using the built in ANTLR AST rewriting
  56 /// notation, you will rarely need to override the default implementation of runtime methods. The
  57 /// exception to this will be the syntax err reporting method, which is essentially a stub function
  58 /// that you will usually want to provide your own implementation for. You should consider the built in function
  59 /// displayRecognitionError() as an example of where to start as there can be no really useful
  60 /// generic error message display.
  61 ///
  62 ///