thirdparty/libantlr3c-3.2/doxygen/changes31.dox

   1 /// \page changes31 Changes in 3.1 from 3.0
   2 ///
   3 /// The following changes have taken place from 3.0 to 3.1. Some of
   4 /// them may require minor changes to your grammar files or the
   5 /// programs that invoke your grammar. Please take the time to read
   6 /// through this list as it may save you time later.
   7 ///
   8 /// \section returns Constructor Return Values
   9 ///
  10 /// In previous releases the return value from both the generated constructors and
  11 /// built in constructor functions would return a value of -1 or -2 if a problem
  12 /// occurred. However, the only problem that can really occur is lack of memory,
  13 /// hence to avoid the remote change that some memory allocation scheme would return
  14 /// an address of -1 for a pointer, the return address is now NULL if there was
  15 /// no memory available. The old macros for this mechanism have been removed which
  16 /// will force you to read this information. You now need only check the return
  17 /// address for NULL, or you could not bother doing that and join with 95% of the world's
  18 /// C code.
  19 ///
  20 /// \section trees Tree Parser Rewrites
  21 ///
  22 /// The 3.1 runtime now supports tree rewrites from tree parsers. See the main ANTLR
  23 /// documentation for more details. This beta version contains \subpage knownissues regarding
  24 /// the release of mmeory allocated to tree nodes when they are rewritten in some combinations
  25 /// of re-writing tree parsers. These issues will be corrected before release.
  26 ///
  27 /// \section debugger ANTLRWorks Debugger
  28 ///
  29 /// The ANTLRWorks debugger is now fully supported by this version of the runtime. It
  30 /// supports remote debugging only (you cannot generate C, compile and debug it from the
  31 /// ANTLRWorks IDE.) However both parser and tree parser debugging is supported providing
  32 /// you are using a version of ANTLRWorks that supports tree parser debugging. Generate
  33 /// the C code with the -debug option of the ANTLR tool, as per any other target.
  34 ///
  35 /// Note that when you invoke your debugging version of the parser, it will appear to hang
  36 /// but is in fact waiting on a local TCP socket connection from the ANTLRWorks debugger. As the
  37 /// target environment is unknown, it is not prudent to generate notification status messages
  38 /// using something like printf, as the target environment may not have a console or implement
  39 /// printf.
  40 ///
  41 /// \section macros Macro Changes
  42 ///
  43 /// Prior to the 3.1 release, accessing the token source of a lexer required knowledge of where
  44 /// the token source pointer was located wihtin the lexer. In 3.1, the token source was burried
  45 /// further in the innards of the C runtime and such knowledge is considerd irreleavant and confusing.
  46 /// Hence, when creating a token stream from a token source, it is now mandatory to use the new
  47 /// C macro TOKENSOURCE(lxr), which will expand to point at the token source interface. This MACRO
  48 /// will be maintained across future versions. You can see how to use it in the downloadable
  49 /// examples, avaiable from the downloads page of the ANTLR web site. Here is the relevant code
  50 /// for creating a token stream, extracted from those examples:
  51 ///
  52 /// \code
  53 /// tstream = antlr3CommonTokenStreamSourceNew(ANTLR3_SIZE_HINT, TOKENSOURCE(lxr));
  54 /// \endcode
  55 ///
  56