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 57