diff options
Diffstat (limited to 'antlr/libantlr3c-3.4/doxygen')
| -rw-r--r-- | antlr/libantlr3c-3.4/doxygen/atsections.dox | 143 | ||||
| -rw-r--r-- | antlr/libantlr3c-3.4/doxygen/build.dox | 207 | ||||
| -rw-r--r-- | antlr/libantlr3c-3.4/doxygen/buildrec.dox | 269 | ||||
| -rw-r--r-- | antlr/libantlr3c-3.4/doxygen/changes31.dox | 56 | ||||
| -rw-r--r-- | antlr/libantlr3c-3.4/doxygen/doxygengroups.dox | 243 | ||||
| -rw-r--r-- | antlr/libantlr3c-3.4/doxygen/generate.dox | 57 | ||||
| -rw-r--r-- | antlr/libantlr3c-3.4/doxygen/interop.dox | 327 | ||||
| -rw-r--r-- | antlr/libantlr3c-3.4/doxygen/knownissues.dox | 3 | ||||
| -rw-r--r-- | antlr/libantlr3c-3.4/doxygen/mainpage.dox | 104 | ||||
| -rw-r--r-- | antlr/libantlr3c-3.4/doxygen/runtime.dox | 35 | ||||
| -rw-r--r-- | antlr/libantlr3c-3.4/doxygen/using.dox | 62 |
11 files changed, 1506 insertions, 0 deletions
diff --git a/antlr/libantlr3c-3.4/doxygen/atsections.dox b/antlr/libantlr3c-3.4/doxygen/atsections.dox new file mode 100644 index 0000000..bd4ea12 --- /dev/null +++ b/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 diff --git a/antlr/libantlr3c-3.4/doxygen/build.dox b/antlr/libantlr3c-3.4/doxygen/build.dox new file mode 100644 index 0000000..05c3c66 --- /dev/null +++ b/antlr/libantlr3c-3.4/doxygen/build.dox @@ -0,0 +1,207 @@ +/// \page build Building From Source +/// +/// The C runtime is provided in source code form only as there are too many binary +/// versions to sensibly maintain binaries on www.antlr.org. +/// +/// The runtime code is provided with .sln and .vcproj files for Visual Studio 2005 and 2008, +/// and \b configure files for building and installation on UNIX or other systems that support this tool. If your +/// system is neither Windows nor \b configure compatible, then you should find it +/// reasonable to build the code manually (see section "Building Manually".) +/// +/// \section src Source Code Organization +/// +/// The source code expands from a tar/zip file to give you the following +/// directories: +/// +/// - <b>./</b> The location of the configure script and the antlr3config.h file +/// generated by the running the configure script.This directory also +/// contains the solution and project files for visual studio 2005 and +/// 2008. +/// - <b>./src</b> The location of all the C files in the project. +/// - <b>./include</b> The location of all the header files for the project +/// - <b>./doxygen</b> The location of documentation files such as the one that generates this page +/// - Other ancillary directories used by the build or documentation process. +/// +/// \section winbuild Building for Windows +/// +/// If you are building for Cygwin, or a similar UNIX on Windows System, follow the "Building With Configure" instructions below. +/// +/// Note that the runtime is no longer compatible with the VC6 Microsoft compiler. If you absolutely need to build with +/// this compiler, you can probably hack the source code to deall with the pieces that VC6 cannot handle such as the +/// ULL suffix for constants. +/// +/// If you wish to build the binaries for Windows using Visual Studio 2005, or 2008 you may build using the IDE: +/// -# Open the C.sln file +/// -# Select batch Build from the Build menu +/// -# Select all configurations and press the build button. +/// +/// If you wish or need to build the libraries from the command line, then you must +/// use a Windows command shell configured for access to VS2005/VS2008 compilers, such as the one that is +/// started from: +/// +/// <i>Start->Microsoft Visual Studio 2005->Visual Studio Tools->Visual Studio 2005 Command Prompt</i> +/// +/// There appears to be no way to build all targets at once in a batch mode from the command line, +/// so you may build one or all of the following: +/// \verbatim + C:\antlrsrc\code\antlr\main\runtime\C> DEVENV C.sln /Build ReleaseDLL + C:\antlrsrc\code\antlr\main\runtime\C> DEVENV C.sln /Build Release + C:\antlrsrc\code\antlr\main\runtime\C> DEVENV C.sln /Build DebugDLL + C:\antlrsrc\code\antlr\main\runtime\C> DEVENV C.sln /Build Debug +\endverbatim +/// +/// After the build is complete you will find the \c.\cDLL and \c.\cLIB files under the directory containing C.sln, +/// in a subdirectory named after the /Build target. In the Release and Debug targets, you will find that there is only a \c.\cLIB archive file, +/// which you can link directly into your own projects if you wish to avoid the DLL. In \c ReleaseDLL and \c DebugDLL you will find both a +/// \c .LIB file which you should link your projects with and a DLL. The library and names on Windows are as follows: +/// +/// \verbatim + - ReleaseDLL : ANTLR3C.DLL and ANTLR3C_DLL.LIB + - DebugDLL : ANTLR3CD.DLL and ANTLR3CD_DLL.LIB + - Release : ANTLR3C.LIB + - Debug : ANTLR3CD.LIB +\endverbatim +/// +/// There currently no .msi modules or other installs built for Windows, so you must place the DLLs in a directory referenced +/// by the PATH environment variable and make the include directory available to your project configurations. +/// +/// +/// \section configure Building with configure +/// +/// Before starting, make sure that you are using a source code distribution and not the source code directly from the +/// Perforce repository. If you use the source from the perforce tree directly, you will find that there is no configure +/// script as this is generated as part of the distribution build by the maintainers. If you feel the need to build from +/// the distribution tree then you must have all the autobuild packages available on your system and can generate the +/// configure script using autoreconf. If you are not familiar with these tools, then please use the tgz files in the +/// dist subdirectory (or downloaded from the ANTLR web site). +/// +/// The source code file should be expanded in a directory of your choice (probably your working directory) using the command: +/// +/// \verbatim +gzip -dc antlrtgzname.tar.gz | tar xvf - +\endverbatim +/// +/// Where: <b>antlrtgzname.tar.gz</b> is of course the name of the tar when you downloaded it. You should find a \b configure script in the sub directory thus created. +/// +/// The configure script accepts the usual options, such as --prefix= but the default is to build in the source directory and to place libraries in +/// <b>/usr/local/lib</b> and include files (for building your recognizers) in <b>/usr/local/include</b>. There are also a number of antlr specific options, which you may wish to utilize. The command: +/// \verbatim +./configure --help +\endverbatim +/// +/// Will document the latest incarnations of these options in case this documentation is ever out of date. At this time the options are: +/// +/// \verbatim + --enable-debuginfo Compiles debug info into the library (default no) + --enable-64bit Turns on flags that produce 64 bit object code if + any are required (default no) +\endverbatim +/// +/// Unless you need 64 bit builds, or a change in library types, you will generally use the configure command without options: +/// +/// Here is a sample configure output: +/// +/// \verbatim +[jimi@localhost dist]$ tar zvxf libantlr3c-3.0.0-rc8.tar.gz + +libantlr3c-3.0.0-rc8/ +libantlr3c-3.0.0-rc8/antlr3config.h +libantlr3c-3.0.0-rc8/src/ +libantlr3c-3.0.0-rc8/src/antlr3stringstream.c +... +libantlr3c-3.0.0-rc8/antlr3config.h.in +\endverbatim +/// \verbatim +[jimi@localhost dist]$ cd libantlr3c-3.0.0-rc +\endverbatim +/// \verbatim +[jimi@localhost libantlr3c-3.0.0-rc8]$ ./configure + +checking for a BSD-compatible install... /usr/bin/install -c +checking whether build environment is sane... yes +checking for a thread-safe mkdir -p... /bin/mkdir -p +checking for gawk... gawk +checking whether make sets $(MAKE)... yes +checking for xlc... no +checking for aCC... no +checking for gcc... gcc +... +checking for strdup... yes +configure: creating ./config.status +config.status: creating Makefile +config.status: creating antlr3config.h +config.status: antlr3config.h is unchanged +config.status: executing depfiles commands +\endverbatim +/// +/// Having configured the library successfully, you need only make it, and install it: +/// +/// \verbatim +[jimi@localhost libantlr3c-3.0.0-rc8]$ make +\endverbatim +/// \verbatim +make all-am +make[1]: Entering directory `/home/jimi/antlrsrc/code/antlr/main/runtime/C/dist/libantlr3c-3.0.0-rc8' +/bin/sh ./libtool --tag=CC --mode=compile gcc -DHAVE_CONFIG_H -I. -Iinclude -Iinclude -O2 -MT antlr3baserecognizer.lo -MD -MP -MF .deps/antlr3baserecognizer.Tpo -c -o antlr3baserecognizer.lo `test -f 'src/antlr3baserecognizer.c' || echo './'`src/antlr3baserecognizer.c +... +gcc -shared .libs/antlr3baserecognizer.o .libs/antlr3basetree.o .libs/antlr3basetreeadaptor.o .libs/antlr3bitset.o .libs/antlr3collections.o .libs/antlr3commontoken.o .libs/antlr3commontree.o .libs/antlr3commontreeadaptor.o .libs/antlr3commontreenodestream.o .libs/antlr3cyclicdfa.o .libs/antlr3encodings.o .libs/antlr3exception.o .libs/antlr3filestream.o .libs/antlr3inputstream.o .libs/antlr3intstream.o .libs/antlr3lexer.o .libs/antlr3parser.o .libs/antlr3string.o .libs/antlr3stringstream.o .libs/antlr3tokenstream.o .libs/antlr3treeparser.o .libs/antlr3rewritestreams.o .libs/antlr3ucs2inputstream.o -Wl,-soname -Wl,libantlr3c.so -o .libs/libantlr3c.so +ar cru .libs/libantlr3c.a antlr3baserecognizer.o antlr3basetree.o antlr3basetreeadaptor.o antlr3bitset.o antlr3collections.o antlr3commontoken.o antlr3commontree.o antlr3commontreeadaptor.o antlr3commontreenodestream.o antlr3cyclicdfa.o antlr3encodings.o antlr3exception.o antlr3filestream.o antlr3inputstream.o antlr3intstream.o antlr3lexer.o antlr3parser.o antlr3string.o antlr3stringstream.o antlr3tokenstream.o antlr3treeparser.o antlr3rewritestreams.o antlr3ucs2inputstream.o +ranlib .libs/libantlr3c.a +creating libantlr3c.la + +(cd .libs && rm -f libantlr3c.la && ln -s ../libantlr3c.la libantlr3c.la) +make[1]: Leaving directory `/home/jimi/antlrsrc/code/antlr/main/runtime/C/dist/libantlr3c-3.0.0-rc8' +\endverbatim +/// \verbatim +[jimi@localhost libantlr3c-3.0.0-rc8]$ sudo make install +\endverbatim +/// \verbatim +make[1]: Entering directory `/home/jimi/antlrsrc/code/antlr/main/runtime/C/dist/libantlr3c-3.0.0-rc8' +test -z "/usr/local/lib" || /bin/mkdir -p "/usr/local/lib" + /bin/sh ./libtool --mode=install /usr/bin/install -c 'libantlr3c.la' '/usr/local/lib/libantlr3c.la' +/usr/bin/install -c .libs/libantlr3c.so /usr/local/lib/libantlr3c.so +/usr/bin/install -c .libs/libantlr3c.lai /usr/local/lib/libantlr3c.la +/usr/bin/install -c .libs/libantlr3c.a /usr/local/lib/libantlr3c.a +... + /usr/bin/install -c -m 644 'include/antlr3stringstream.h' '/usr/local/include/antlr3stringstream.h' +... + /usr/bin/install -c -m 644 'antlr3config.h' '/usr/local/include/antlr3config.h' +make[1]: Leaving directory `/home/jimi/antlrsrc/code/antlr/main/runtime/C/dist/libantlr3c-3.0.0-rc8' + +[jimi@localhost libantlr3c-3.0.0-rc8]$ +\endverbatim +/// +/// You are now ready to generate C recognizers and compile and link them with the ANTLR 3 C Runtime. +/// +/// +/// \section buildman Building Manually +/// +/// The only step that configure performs that cannot be done +/// manually (without effort) is to produce the header file +/// \c antlr3config.h, which contains typedefs of the fundamental types +/// that your local C compiler supports. The easiest way to produce +/// this file for your system, if you cannot port \b automake and \b configure +/// to the system is: +/// +/// -# Run configure on a system that does support configure +/// -# Copy the generated \c antlr3config.h file to the target system +/// -# Edit the file locally and change any types that differ on this +/// system to the target systems. There are only a few types and you should +/// find this relatively easy. +/// +/// Having produced a compatible antlr3config.h file, then you should be able to +/// compile the source files in the \c ./src subdirectory, providing an include path +/// to the location of \c antlr3config.h and the \c ./include subdirectory. Something akin +/// to: +/// \verbatim + +~/C/src: cc -c -O -I.. -I../include *.c + +\endverbatim +/// +/// Having produced the .o (or equivalent) files for the local system you can then +/// build an archive or shared library for the C runtime. +/// +/// When you wish to build and link with the C runtime, specify the path to the +/// supplied header files, and the path to the library that you built. +///
\ No newline at end of file diff --git a/antlr/libantlr3c-3.4/doxygen/buildrec.dox b/antlr/libantlr3c-3.4/doxygen/buildrec.dox new file mode 100644 index 0000000..816a845 --- /dev/null +++ b/antlr/libantlr3c-3.4/doxygen/buildrec.dox @@ -0,0 +1,269 @@ +/// \page buildrec How to build Generated C Code +/// +/// \section generated Generated Files +/// +/// The antlr tool jar, run against a grammar file that targets the C language, will generate the following files +/// according to whether your grammar file contains a lexer, parser, combined or treeparser specification. +/// Your grammar file name and the subject of the grammar line in your file are expected to match. Here the generic name G is used: +/// +/// <table> +/// <tr> +/// <th> Suffix </th> +/// <th> Generated files </th> +/// </tr> +/// <tr> +/// <td> lexer grammar (G.g3l) </td> +/// <td> GLexer.c GLexer.h</td> +/// </tr> +/// <tr> +/// <td> parser grammar (G.g3p) </td> +/// <td> GParser.c GParser.h </td> +/// </tr> +/// <tr> +/// <td> grammar G (G.g3pl) </td> +/// <td> GParser.c GParser.h GLexer.c GLexer.h</td> +/// </tr> +/// <tr> +/// <td> tree grammar G; (G.g3t) </td> +/// <td> G.c G.h </td> +/// </tr> +/// </table> +/// +/// The generated .c files reference the .h files using <G.h>, so you must use <code>-I.</code> on your compiler command line +/// (or include the current directory in your include paths in Visual Studio). Additionally, the generated .h files reference +/// <code>antlr3.h</code>, so you must use <code>-I/path/to/antlr/include</code> (E.g. <code>-I /usr/local/include</code>) to reference the standard ANTLR include files. +/// +/// In order to reference the library file at compile time (you can/should only reference one) you need to use the +/// <code>-L/path/to/antlr/lib</code> (E.g. <code>-L /usr/local/lib</code>) on Unix, or add the path to your "Additional Library Path" in +/// Visual Studio. You also need to specify the library using <code>-L</code> on Unix (E.g. <code>-L /usr/local/lib -l antlr3c</code>) or add <code>antlr3c_dll.lib</code> +/// to your Additional Library Dependencies in Visual Studio. +/// +/// In case it isn't obvious, the generated files may be used to produce either a library or an executable (.EXE on Windows) file. +/// +/// If you use the shared version of the libraries, DLL or .so/.so/.a then you must ship the library with your +/// application must run in an environment whereby the library can be found by the runtime linker/loader. +/// This usually involves specifying the directory in which the library lives to an environment variable. +/// On Windows, X:{yourwininstalldir}\system32 will be searched automatically. +/// +/// \section invoke Invoking Your Generated Recognizer +/// +/// In order to run your lexer/parser/tree parser combination, you will need a small function (or main) +/// function that controls the sequence of events, from reading the input file or string, through to +/// invoking the tree parser(s) and retrieving the results. See "Using the ANTLR3C C Target" for more +/// detailed instructions, but if you just want to get going as fast as possible, study the following +/// code example. +/// +/// \code +/// +/// // You may adopt your own practices by all means, but in general it is best +/// // to create a single include for your project, that will include the ANTLR3 C +/// // runtime header files, the generated header files (all of which are safe to include +/// // multiple times) and your own project related header files. Use <> to include and +/// // -I on the compile line (which vs2005 now handles, where vs2003 did not). +/// // +/// #include <treeparser.h> +/// +/// // Main entry point for this example +/// // +/// int ANTLR3_CDECL +/// main (int argc, char *argv[]) +/// { +/// // Now we declare the ANTLR related local variables we need. +/// // Note that unless you are convinced you will never need thread safe +/// // versions for your project, then you should always create such things +/// // as instance variables for each invocation. +/// // ------------------- +/// +/// // Name of the input file. Note that we always use the abstract type pANTLR3_UINT8 +/// // for ASCII/8 bit strings - the runtime library guarantees that this will be +/// // good on all platforms. This is a general rule - always use the ANTLR3 supplied +/// // typedefs for pointers/types/etc. +/// // +/// pANTLR3_UINT8 fName; +/// +/// // The ANTLR3 character input stream, which abstracts the input source such that +/// // it is easy to privide inpput from different sources such as files, or +/// // memory strings. +/// // +/// // For an 8Bit/latin-1/etc memory string use: +/// // input = antlr3New8BitStringInPlaceStream (stringtouse, (ANTLR3_UINT32) length, NULL); +/// // +/// // For a UTF16 memory string use: +/// // input = antlr3NewUTF16StringInPlaceStream (stringtouse, (ANTLR3_UINT32) length, NULL); +/// // +/// // For input from a file, see code below +/// // +/// // Note that this is essentially a pointer to a structure containing pointers to functions. +/// // You can create your own input stream type (copy one of the existing ones) and override any +/// // individual function by installing your own pointer after you have created the standard +/// // version. +/// // +/// pANTLR3_INPUT_STREAM input; +/// +/// // The lexer is of course generated by ANTLR, and so the lexer type is not upper case. +/// // The lexer is supplied with a pANTLR3_INPUT_STREAM from whence it consumes its +/// // input and generates a token stream as output. This is the ctx (CTX macro) pointer +/// // for your lexer. +/// // +/// pLangLexer lxr; +/// +/// // The token stream is produced by the ANTLR3 generated lexer. Again it is a structure based +/// // API/Object, which you can customise and override methods of as you wish. a Token stream is +/// // supplied to the generated parser, and you can write your own token stream and pass this in +/// // if you wish. +/// // +/// pANTLR3_COMMON_TOKEN_STREAM tstream; +/// +/// // The Lang parser is also generated by ANTLR and accepts a token stream as explained +/// // above. The token stream can be any source in fact, so long as it implements the +/// // ANTLR3_TOKEN_SOURCE interface. In this case the parser does not return anything +/// // but it can of course specify any kind of return type from the rule you invoke +/// // when calling it. This is the ctx (CTX macro) pointer for your parser. +/// // +/// pLangParser psr; +/// +/// // The parser produces an AST, which is returned as a member of the return type of +/// // the starting rule (any rule can start first of course). This is a generated type +/// // based upon the rule we start with. +/// // +/// LangParser_decl_return langAST; +/// +/// +/// // The tree nodes are managed by a tree adaptor, which doles +/// // out the nodes upon request. You can make your own tree types and adaptors +/// // and override the built in versions. See runtime source for details and +/// // eventually the wiki entry for the C target. +/// // +/// pANTLR3_COMMON_TREE_NODE_STREAM nodes; +/// +/// // Finally, when the parser runs, it will produce an AST that can be traversed by the +/// // the tree parser: c.f. LangDumpDecl.g3t This is the ctx (CTX macro) pointer for your +/// // tree parser. +/// // +/// pLangDumpDecl treePsr; +/// +/// // Create the input stream based upon the argument supplied to us on the command line +/// // for this example, the input will always default to ./input if there is no explicit +/// // argument. +/// // +/// if (argc < 2 || argv[1] == NULL) +/// { +/// fName =(pANTLR3_UINT8)"./input"; // Note in VS2005 debug, working directory must be configured +/// } +/// else +/// { +/// fName = (pANTLR3_UINT8)argv[1]; +/// } +/// +/// // Create the input stream using the supplied file name +/// // (Use antlr38BitFileStreamNew for UTF16 input). +/// // +/// input = antlr38BitFileStreamNew(fName); +/// +/// // The input will be created successfully, providing that there is enough +/// // memory and the file exists etc +/// // +/// if ( input == NULL ) +/// { +/// ANTLR3_FPRINTF(stderr, "Unable to open file %s due to malloc() failure1\n", (char *)fName); +/// } +/// +/// // Our input stream is now open and all set to go, so we can create a new instance of our +/// // lexer and set the lexer input to our input stream: +/// // (file | memory | ?) --> inputstream -> lexer --> tokenstream --> parser ( --> treeparser )? +/// // +/// lxr = LangLexerNew(input); // CLexerNew is generated by ANTLR +/// +/// // Need to check for errors +/// // +/// if ( lxr == NULL ) +/// { +/// ANTLR3_FPRINTF(stderr, "Unable to create the lexer due to malloc() failure1\n"); +/// exit(ANTLR3_ERR_NOMEM); +/// } +/// +/// // Our lexer is in place, so we can create the token stream from it +/// // NB: Nothing happens yet other than the file has been read. We are just +/// // connecting all these things together and they will be invoked when we +/// // call the parser rule. ANTLR3_SIZE_HINT can be left at the default usually +/// // unless you have a very large token stream/input. Each generated lexer +/// // provides a token source interface, which is the second argument to the +/// // token stream creator. +/// // Note tha even if you implement your own token structure, it will always +/// // contain a standard common token within it and this is the pointer that +/// // you pass around to everything else. A common token as a pointer within +/// // it that should point to your own outer token structure. +/// // +/// tstream = antlr3CommonTokenStreamSourceNew(ANTLR3_SIZE_HINT, lxr->pLexer->tokSource); +/// +/// if (tstream == NULL) +/// { +/// ANTLR3_FPRINTF(stderr, "Out of memory trying to allocate token stream\n"); +/// exit(ANTLR3_ERR_NOMEM); +/// } +/// +/// // Finally, now that we have our lexer constructed, we can create the parser +/// // +/// psr = LangParserNew(tstream); // CParserNew is generated by ANTLR3 +/// +/// if (psr == NULL) +/// { +/// ANTLR3_FPRINTF(stderr, "Out of memory trying to allocate parser\n"); +/// exit(ANTLR3_ERR_NOMEM); +/// } +/// +/// // We are all ready to go. Though that looked complicated at first glance, +/// // I am sure, you will see that in fact most of the code above is dealing +/// // with errors and there isn;t really that much to do (isn;t this always the +/// // case in C? ;-). +/// // +/// // So, we now invoke the parser. All elements of ANTLR3 generated C components +/// // as well as the ANTLR C runtime library itself are pseudo objects. This means +/// // that they are represented as pointers to structures, which contain any +/// // instance data they need, and a set of pointers to other interfaces or +/// // 'methods'. Note that in general, these few pointers we have created here are +/// // the only things you will ever explicitly free() as everything else is created +/// // via factories, that allocate memory efficiently and free() everything they use +/// // automatically when you close the parser/lexer/etc. +/// // +/// // Note that this means only that the methods are always called via the object +/// // pointer and the first argument to any method, is a pointer to the structure itself. +/// // It also has the side advantage, if you are using an IDE such as VS2005 that can do it +/// // that when you type ->, you will see a list of all the methods the object supports. +/// // +/// langAST = psr->decl(psr); +/// +/// // If the parser ran correctly, we will have a tree to parse. In general I recommend +/// // keeping your own flags as part of the error trapping, but here is how you can +/// // work out if there were errors if you are using the generic error messages +/// // +/// if (psr->pParser->rec->errorCount > 0) +/// { +/// ANTLR3_FPRINTF(stderr, "The parser returned %d errors, tree walking aborted.\n", psr->pParser->rec->errorCount); +/// +/// } +/// else +/// { +/// nodes = antlr3CommonTreeNodeStreamNewTree(langAST.tree, ANTLR3_SIZE_HINT); // sIZE HINT WILL SOON BE DEPRECATED!! +/// +/// // Tree parsers are given a common tree node stream (or your override) +/// // +/// treePsr = LangDumpDeclNew(nodes); +/// +/// treePsr->decl(treePsr); +/// nodes ->free (nodes); nodes = NULL; +/// treePsr ->free (treePsr); treePsr = NULL; +/// } +/// +/// // We did not return anything from this parser rule, so we can finish. It only remains +/// // to close down our open objects, in the reverse order we created them +/// // +/// psr ->free (psr); psr = NULL; +/// tstream ->free (tstream); tstream = NULL; +/// lxr ->free (lxr); lxr = NULL; +/// input ->close (input); input = NULL; +/// +/// return 0; +/// } +/// \endcode +/// diff --git a/antlr/libantlr3c-3.4/doxygen/changes31.dox b/antlr/libantlr3c-3.4/doxygen/changes31.dox new file mode 100644 index 0000000..d1793db --- /dev/null +++ b/antlr/libantlr3c-3.4/doxygen/changes31.dox @@ -0,0 +1,56 @@ +/// \page changes31 Changes in 3.1 from 3.0 +/// +/// The following changes have taken place from 3.0 to 3.1. Some of +/// them may require minor changes to your grammar files or the +/// programs that invoke your grammar. Please take the time to read +/// through this list as it may save you time later. +/// +/// \section returns Constructor Return Values +/// +/// In previous releases the return value from both the generated constructors and +/// built in constructor functions would return a value of -1 or -2 if a problem +/// occurred. However, the only problem that can really occur is lack of memory, +/// hence to avoid the remote change that some memory allocation scheme would return +/// an address of -1 for a pointer, the return address is now NULL if there was +/// no memory available. The old macros for this mechanism have been removed which +/// will force you to read this information. You now need only check the return +/// address for NULL, or you could not bother doing that and join with 95% of the world's +/// C code. +/// +/// \section trees Tree Parser Rewrites +/// +/// The 3.1 runtime now supports tree rewrites from tree parsers. See the main ANTLR +/// documentation for more details. This beta version contains \subpage knownissues regarding +/// the release of mmeory allocated to tree nodes when they are rewritten in some combinations +/// of re-writing tree parsers. These issues will be corrected before release. +/// +/// \section debugger ANTLRWorks Debugger +/// +/// The ANTLRWorks debugger is now fully supported by this version of the runtime. It +/// supports remote debugging only (you cannot generate C, compile and debug it from the +/// ANTLRWorks IDE.) However both parser and tree parser debugging is supported providing +/// you are using a version of ANTLRWorks that supports tree parser debugging. Generate +/// the C code with the -debug option of the ANTLR tool, as per any other target. +/// +/// Note that when you invoke your debugging version of the parser, it will appear to hang +/// but is in fact waiting on a local TCP socket connection from the ANTLRWorks debugger. As the +/// target environment is unknown, it is not prudent to generate notification status messages +/// using something like printf, as the target environment may not have a console or implement +/// printf. +/// +/// \section macros Macro Changes +/// +/// Prior to the 3.1 release, accessing the token source of a lexer required knowledge of where +/// the token source pointer was located wihtin the lexer. In 3.1, the token source was burried +/// further in the innards of the C runtime and such knowledge is considerd irreleavant and confusing. +/// Hence, when creating a token stream from a token source, it is now mandatory to use the new +/// C macro TOKENSOURCE(lxr), which will expand to point at the token source interface. This MACRO +/// will be maintained across future versions. You can see how to use it in the downloadable +/// examples, avaiable from the downloads page of the ANTLR web site. Here is the relevant code +/// for creating a token stream, extracted from those examples: +/// +/// \code +/// tstream = antlr3CommonTokenStreamSourceNew(ANTLR3_SIZE_HINT, TOKENSOURCE(lxr)); +/// \endcode +/// + diff --git a/antlr/libantlr3c-3.4/doxygen/doxygengroups.dox b/antlr/libantlr3c-3.4/doxygen/doxygengroups.dox new file mode 100644 index 0000000..de259f3 --- /dev/null +++ b/antlr/libantlr3c-3.4/doxygen/doxygengroups.dox @@ -0,0 +1,243 @@ +// Definitions of documentation groups so we can organize the API and +// usage documentation nicely. + +/// \defgroup apiclasses API Classes +/// +/// The API classes are divided into the typdefs (and their underlying structs) +/// that are the containers for each 'object' within the ANTLR3C runtime, and +/// their implementations (the functions that are installed by default in to +/// these structures when you create them.) +/// +/// The typedefs contain data and function pointers, which together define +/// the object. The implementation functions are the default implementations +/// of the 'methds' encapsulated by the typdef structures.You may override +/// any of the methods once their objects are created by installing a pointer to +/// your own function. Some of these methods create other 'objects' (instances of +/// typedef structures), which allows you install your own method and create your +/// own implementation of these. +/// + + /// \defgroup apistructures API Typedefs and Structs + /// \ingroup apiclasses + /// + /// These structures (and the typedefs that you use to reference them + /// and their pointers) are the C equivalent of objects. They correspond + /// (roughly) to the Java runtime system classes and contain all the + /// data elements for a particular interface as well as all the pointers + /// to functions that implement these interfaces. + /// + /// There are constructor functions exported from the C runtime, which you + /// use to create a default implementation of one of these 'classes'. You can + /// then override any part of the implementation by installing your own + /// function pointers, before using the interface 'object' you have created. + /// + /// For instance, you can override the default error message reporting function + /// by replacing the standard (example) implementation of this function with + /// your own. In your grammar, you would place the following + /// + /// \code + /// @parser::apifuncs + /// { + /// // Install custom error message display + /// // + /// RECOGNIZER->displayRecognitionError = produceError; + /// } + /// \endcode + /// + /// The special section @parser::apiFuncs is guaranteed to be generated after + /// the RECONGIZER 'object' has already be created and initialized, so you may + /// install your own implementations of the #ANTLR3_BASE_RECOGNIZER interface + /// functions. The error display function is likely to be the only one you are + /// interested in replacing. + /// + /// Some typedef structures contain either pointers to 'inherited' objects (usual) + /// or embedded structures/typedefs (unusual). In some cases, the pointers passed + /// around by the paresr or tree parser are actually the pointers to these embedded + /// structures (such as #pANTLR3_BASE_TREE), and these embedded 'objects' contain + /// pointers to their encapsulating objects. This is the equivalent of passing + /// interface objects around in object oriented languages. + /// + + /// \defgroup ANTLR3_BASE_RECOGNIZER ANTLR3_BASE_RECOGNIZER - Base Recognizer Class Definition + /// \ingroup apistructures + /// + /// This is the definition of the base recognizer interface, instantiations + /// of which are referred to via #pANTLR3_BASE_RECOGNIZER. + /// + /// In general you will not refer to one of these structures directly as a + /// a #pANTLR3_BASE_RECOGNIZER will be embedded within a higher level + /// object such as #pANTLR3_PARSER + /// + /// \defgroup ANTLR3_RECOGNIZER_SHARED_STATE ANTLR3_RECOGNIZER_SHARED_STATE Recognizer Shared State Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_BITSET ANTLR3_BITSET - Bitset Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_TOKEN_FACTORY ANTLR3_TOKEN_FACTORY - Token Factory Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_COMMON_TOKEN ANTLR3_COMMON_TOKEN - Common Token Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_EXCEPTION ANTLR3_EXCEPTION - Exception Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_HASH_BUCKET ANTLR3_HASH_BUCKET - Hash Table Bucket Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_HASH_ENTRY ANTLR3_HASH_ENTRY - Hash Table Entry Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_HASH_ENUM ANTLR3_HASH_ENUM - Hash Table Enumerator Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_HASH_TABLE ANTLR3_HASH_TABLE - Hash Table Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_LIST ANTLR3_LIST - List Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_VECTOR_FACTORY ANTLR3_VECTOR_FACTORY - Vector Factory Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_VECTOR ANTLR3_VECTOR - Vector Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_STACK ANTLR3_STACK - Stack Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_INPUT_STREAM ANTLR3_INPUT_STREAM - Input Stream Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_LEX_STATE ANTLR3_LEX_STATE - Lexer State Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_STRING_FACTORY ANTLR3_STRING_FACTORY - String Factory Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_STRING ANTLR3_STRING - String Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_TOKEN_SOURCE ANTLR3_TOKEN_SOURCE - Token Source Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_TOKEN_STREAM ANTLR3_TOKEN_STREAM - Token Stream Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_COMMON_TOKEN_STREAM ANTLR3_COMMON_TOKEN_STREAM - Common Token Stream Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_CYCLIC_DFA ANTLR3_CYCLIC_DFA - Cyclic DFA Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_LEXER ANTLR3_LEXER - Lexer Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_PARSER ANTLR3_PARSER - Parser Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_BASE_TREE ANTLR3_BASE_TREE - Base Tree Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_COMMON_TREE ANTLR3_COMMON_TREE - Common Tree Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_ARBORETUM ANTLR3_ARBORETUM - Tree Factory Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_PARSE_TREE ANTLR3_PARSE_TREE - Parse Tree Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_TREE_NODE_STREAM ANTLR3_TREE_NODE_STREAM - Tree Node Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_COMMON_TREE_NODE_STREAM ANTLR3_COMMON_TREE_NODE_STREAM - Common Tree Node Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_TREE_WALK_STATE ANTLR3_TREE_WALK_STATE - Tree Walk State Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_BASE_TREE_ADAPTOR ANTLR3_BASE_TREE_ADAPTOR - Base Tree Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_COMMON_TREE_ADAPTOR ANTLR3_COMMON_TREE_ADAPTOR - Common Tree Adaptor Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_TREE_PARSER ANTLR3_TREE_PARSER - Tree Parser Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_INT_TRIE ANTLR3_INT_TRIE - Trie Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_REWRITE_RULE_ELEMENT_STREAM ANTLR3_REWRITE_RULE_ELEMENT_STREAM - Token Rewrite Stream Class Definition + /// \ingroup apistructures + /// \defgroup ANTLR3_DEBUG_EVENT_LISTENER ANTLR3_DEBUG_EVENT_LISTENER - Debugger Class Definition + /// \ingroup apistructures + + /// \defgroup apiimplementations API Implementation functions + /// \ingroup apiclasses + /// + /// API implementation functions are the default implementation of each of the + /// methods in a particular typedef structure. + /// + /// They are generally grouped together in the same source code file. + /// For instance the default implementations of the + /// methods contained by a #pANTLR3_BASE_RECOGNIZER will be found in the file + /// antlr3baserecognizer.c + /// + /// A source file that provides the default implementations of functions will usually + /// also supply the public (exported from the .DLL or code library) 'constructor' functions + /// that create and initialize the typedef structure that they implement. For instance, + /// in the antlr3baserecognizer.c file, you will find the function antlr3BaseRecognizerNew() + /// + + /// \defgroup pANTLR3_BASE_RECOGNIZER pANTLR3_BASE_RECOGNIZER Base Recognizer Implementation + /// \ingroup apiimplementations + /// + /// The base recognizer interface is implemented by all higher level recognizers + /// such as #pANTLR3_PARSER and provides methods common to all recognizers. + /// + /// \defgroup pANTLR3_RECOGNIZER_SHARED_STATE pANTLR3_RECOGNIZER_SHARED_STATE - Recognizer Shared State Implementation + /// \ingroup apiimplementations + /// + /// The recognizer shared state class does not have an implementation because it contains only + /// data fields, documented at #ANTLR3_RECOGNIZER_SHARED_STATE + /// + /// \defgroup pANTLR3_BITSET pANTLR3_BITSET - Bitset Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_TOKEN_FACTORY pANTLR3_TOKEN_FACTORY - Token Factory Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_COMMON_TOKEN pANTLR3_COMMON_TOKEN - Common Token Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_EXCEPTION pANTLR3_EXCEPTION - Exception Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_HASH_BUCKET pANTLR3_HASH_BUCKET - Hash Table Bucket Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_HASH_ENTRY pANTLR3_HASH_ENTRY - Hash Table Entry Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_HASH_ENUM pANTLR3_HASH_ENUM - Hash Table Enumerator Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_HASH_TABLE pANTLR3_HASH_TABLE - Hash Table Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_LIST pANTLR3_LIST - List Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_VECTOR_FACTORY pANTLR3_VECTOR_FACTORY - Vector Factory Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_VECTOR pANTLR3_VECTOR - Vector Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_STACK pANTLR3_STACK - Stack Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_INPUT_STREAM pANTLR3_INPUT_STREAM - Input Stream Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_LEX_STATE pANTLR3_LEX_STATE - Lexer State Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_STRING_FACTORY pANTLR3_STRING_FACTORY - String Factory Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_STRING pANTLR3_STRING - String Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_TOKEN_SOURCE pANTLR3_TOKEN_SOURCE - Token Source Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_TOKEN_STREAM pANTLR3_TOKEN_STREAM - Token Stream Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_COMMON_TOKEN_STREAM pANTLR3_COMMON_TOKEN_STREAM - Common Token Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_CYCLIC_DFA pANTLR3_CYCLIC_DFA - Cyclic DFA Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_LEXER pANTLR3_LEXER - Lexer Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_PARSER pANTLR3_PARSER - Parser Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_BASE_TREE pANTLR3_BASE_TREE - Base Tree Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_COMMON_TREE pANTLR3_COMMON_TREE - Common Tree Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_ARBORETUM pANTLR3_ARBORETUM - Tree Factory Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_PARSE_TREE pANTLR3_PARSE_TREE - Parse Tree Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_TREE_NODE_STREAM pANTLR3_TREE_NODE_STREAM - Tree Node Stream Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_COMMON_TREE_NODE_STREAM pANTLR3_COMMON_TREE_NODE_STREAM - Common Tree Node Stream Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_TREE_WALK_STATE pANTLR3_TREE_WALK_STATE - Tree Walk State Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_BASE_TREE_ADAPTOR pANTLR3_BASE_TREE_ADAPTOR - Base Tree Adaptor Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_COMMON_TREE_ADAPTOR pANTLR3_COMMON_TREE_ADAPTOR - Common Tree Adaptor Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_TREE_PARSER pANTLR3_TREE_PARSER - Tree ParserImplementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_INT_TRIE pANTLR3_INT_TRIE - Trie Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_REWRITE_RULE_ELEMENT_STREAM pANTLR3_REWRITE_RULE_ELEMENT_STREAM - Token Rewrite Stream Implementation + /// \ingroup apiimplementations + /// \defgroup pANTLR3_DEBUG_EVENT_LISTENER pANTLR3_DEBUG_EVENT_LISTENER - Debugger Implementation + /// \ingroup apiimplementations +
\ No newline at end of file diff --git a/antlr/libantlr3c-3.4/doxygen/generate.dox b/antlr/libantlr3c-3.4/doxygen/generate.dox new file mode 100644 index 0000000..0173d78 --- /dev/null +++ b/antlr/libantlr3c-3.4/doxygen/generate.dox @@ -0,0 +1,57 @@ +/// \page generate Generating Code for the C Target +/// +/// \section generate Generating C +/// +/// Before discussing how we compile or call the generated C code, we need to know how to invoke the C code generator. +/// This is achieved within the grammar file itself, using the language option: +/// +/// \verbatim +options { language = C;} +\endverbatim +/// +/// The code generator consists of a single .java file within the standard ANTLR tool jar, and a code generation template, +/// used by the StringTemplate engine, which drives code generation for all language targets. In fact you can make copies of the C.stg +/// and AST.stg templates and make changes to them (though you are encouraged not to, as it is better to provide bug fixes or +/// enhancements which we are happy to receive requests for and will do out best to incorporate. +/// +/// If you are working in the Windows environment, with Visual Studio 2005 or later, you may wish to utilize the custom rulefile +/// provided in the C source code distribution under the <code>./vs2005</code> directory for this purpose. If you are using a pre-built +/// library then you can also download this rule file directly from the FishEye source code browser for ANTLR3. +/// +/// In order to use the rulefile, you must adopt the following suffixes for your grammar files, though they are otherwise optional: +/// +/// <table> +/// +/// <tr> +/// <th> Suffix </th> +/// <th> Grammar should contain... </th> +/// </tr> +/// <tr> +/// <td> .g3l </td> +/// <td> A lexer grammar specification only. </td> +/// </tr> +/// <tr> +/// <td> .g3p </td> +/// <td> A parser grammar specification only. </td> +/// </tr> +/// <tr> +/// <td> .g3pl </td> +/// <td> A combined lexer and parser specification. </td> +/// </tr> +/// <tr> +/// <td> .g3t </td> +/// <td> A tree grammar specification. </td> +/// </tr> +/// +/// </table> +/// +/// You may also wish to use these suffixes if you are building your projects using Makefiles, as this makes the output deterministic. +/// However in this case a much better solution is probably to utilize the -depend option of the Antlr tool, which should tell your +/// Makefile what the grammar files generates, irrespective of its suffix. ANTLR does not care about the actual suffix you use for +/// your grammar file, so building for multiple platforms is relatively easy. +/// +/// <b>NOTE:</b> Your grammar source, regardless of suffix must be named the same as the grammar statement within it. Grammar xyz +/// must be contained within a file called xyz.<i>anything</i> +/// +/// + diff --git a/antlr/libantlr3c-3.4/doxygen/interop.dox b/antlr/libantlr3c-3.4/doxygen/interop.dox new file mode 100644 index 0000000..3401539 --- /dev/null +++ b/antlr/libantlr3c-3.4/doxygen/interop.dox @@ -0,0 +1,327 @@ +/// \page interop Interacting with the Generated Code +/// +/// \section intro Introduction +/// +/// The main way to interact with the generated code is via action code placed within <code>{</code> and +/// <code>}</code> characters in your rules. In general, you are advised to keep the code you embed within +/// these actions, and the grammar itself to an absolute minimum. Rather than embed code directly in your +/// grammar, you should construct an API, that is called from the actions within your grammar. This way +/// you will keep the grammar clean and maintainable and separate the code generators or other code +/// from the definition of the grammar itself. +/// +/// However, when you wish to call your API functions, or insert small pieces of code that do not +/// warrant external functions, you will need to access elements of tokens, return elements from +/// parser rules and perhaps the internals of the recognizer itself. The C runtime provides a number +/// of MACROs that you can use within your action code. It also provides a number of performant +/// structures that you may find useful for building symbol tables, lists, tries, stacks, arrays and so on (all +/// of which are managed so that your memory allocation problems are minimized.) +/// +/// \section rules Parameters and Returns from Parser Rules +/// +/// The C target does not differ from the Java target in any major ways here, and you should consult +/// the standard documentation for the use of parameters on rules and the returns clause. You should +/// be aware though, that the rules generate C function calls and therefore the input and returns +/// clauses are subject to the constraints of C scoping. +/// +/// You should note that if your parser rule returns more than a single entity, then the return +/// type of the generated rule function is a struct, which is returned by value. This is also the case +/// if your rule is part of a tree building grammar (uses the <code>output=AST;</code> option. +/// +/// Other than the notes above, you can use any pre-declared type as an input or output parameter +/// for your rule. +/// +/// \section memory Memory Management +/// +/// You are responsible for allocating and freeing any memory used by your own +/// constructs, ANTLR will track and release any memory allocated internally for tokens, trees, stacks, scopes +/// and so on. This memory is returned to the malloc pool when you call the free method of any +/// ANTLR3 produced structure. +/// +/// For performance reasons, and to avoid thrashing the malloc allocation system, memory for amy elements +/// of your generated parser is allocated in chunks and parcelled out by factories. For instance memory +/// for tokens is created as an array of tokens, and a token factory hands out the next available slot +/// to the lexer. When you free the lexer, the allocated memory is returned to the pool. The same applies +/// to 'strings' that contain the token text and various other text elements accessed within the lexer. +/// +/// The only side effect of this is that after your parse and analysis is complete, if you wish to retain +/// anything generated automatically, you must copy it before freeing the recognizer structures. In practice +/// it is usually practical to retain the recognizer context objects until your processing is complete or +/// to use your own allocation scheme for generating output etc. +/// +/// The advantage of using object factories is of course that memory leaks and accessing de-allocated +/// memory are bugs that rarely occur within the ANTLR3 C runtime. Further, allocating memory for +/// tokens, trees and so on is very fast. +/// +/// \section ctx The CTX Macro +/// +/// The CTX macro is a fundamental parameter that is passed as the first parameter to any generated function +/// concerned with your lexer, parser, or tree parser. The is is the context pointer for your generated +/// recognizer and is how you invoke the generated functions, and access the data embedded within your generated +/// recognizer. While you can use it to directly access stacks, scopes and so on, this is not really recommended +/// as you should use the $xxx references that are available generically within ANTLR grammars. +/// +/// The context pointer is used because this removes the need for any global/static variables at all, either +/// within the generated code, or the C runtime. This is of course fundamental to creating free threading +/// recognizers. Wherever a function call or rule call required the ctx parameter, you either reference it +/// via the CTX macro, or the ctx parameter is in fact the return type from calling the 'constructor' +/// function for your parser/lexer/tree parser (see code example in "How to build Generated Code" .) +/// +/// \section macros Pre-Defined convenience MACROs +/// +/// While the author is not fond of using C MACROs to hide code or structure access, in the case of generated +/// code, they serve two useful purposes. The first is to simplify the references to internal constructs, +/// the second is to facilitate the change of any internal interface without requiring you to port grammars +/// from earlier versions (just regenerate and recompile). As of release 3.1, these macros are stable and +/// will only change their usage interface in the event of bugs being discovered. You are encouraged to +/// use these macros in your code, rather than access the raw interface. +/// +/// \bNB: Macros that act like statements must be terminated with a ';'. The macro body does not +/// supply this, nor should it. Macros that call functions are declared with () even if they +/// have no parameters, macros that reference fields do not have a () declaration. +/// +/// \section lexermacros Lexer Macros +/// +/// There are a number of macros that are useful exclusively within lexer rules. There are additional +/// macros, common to all recognizer, and these are documented in the section Common Macros. +/// +/// \subsection lexer LEXER +/// +/// The <code>LEXER</code> macro returns a pointer to the base lexer object, which is of type #pANTLR3_LEXER. This is +/// not the pointer to your generated lexer, which is supplied by the CTX macro, +/// but to the common implementation of a lexer interface, +/// which is supplied to all generated lexers. +/// +/// \subsection lexstate LEXSTATE +/// +/// Provides a pointer to the lexer shared state structure, which is where the tokens for a +/// rule are constructed and the status elements of the lexer are kept. This pointer is of type +/// #pANTLR3_RECOGNIZER_SHARED_STATE.In general you should only access elements of this structure +/// if there is not already another MACRO or standard $xxxx antlr reference that refers to it. +/// +/// \subsection la LA(n) +/// +/// The <code>LA</code> macro returns the character at index n from the current input stream index. The return +/// type is #ANTLR3_UINT32. Hence <code>LA(1)</code> returns the character at the current input position (the +/// character that will be consumed next), <code>LA(-1)</code> returns the character that has just been consumed +/// and so on. The <code>LA(n)</code> macro is useful for constructing semantic predicates in lexer rules. The +/// reference <code>LA(0)</code> is undefined and will cause an error in your lexer. +/// +/// \subsection getcharindex GETCHARINDEX() +/// +/// The <code>GETCHARINDEX</code> macro returns the index of the current character position as a 0 based +/// offset from the start of the input stream. It returns a value type of #ANTLR3_UINT32. +/// +/// \subsection getline GETLINE() +/// +/// The <code>GETLINE</code> macro returns the line number of current character (<code>LA(1)</code> in the input +/// stream. It returns a value type of #ANTLR3_UINT32. Note that the line number is incremented +/// automatically by an input stream when it sees the input character '\n'. The character that causes +/// the line number to increment can be changed by calling the SetNewLineChar() method on the input +/// stream before invoking the lexer and after creating the input stream. +/// +/// \subsection gettext GETTEXT() +/// +/// The <code>GETTEXT</code> macro returns the text currently matched by the lexer rule. In general you should use the +/// generic $text reference in ANTLR to retrieve this. The return type is a reference type of #pANTLR3_STRING +/// which allows you to manipulate the text you have retrieved (\b NB this does not change the input stream +/// only the text you copy from the input stream when you use this MACRO or $text). +/// +/// The reference $text->chars or GETTEXT()->chars will reference a pointer to the '\\0' terminated character +/// string that the ANTLR3 #pANTLR3_STRING represents. String space is allocated automatically as well as +/// the structure that holds the string. The #pANTLR3_STRING_FACTORY associated with the lexer handles this +/// and when you close the lexer, it will automatically free any space allocated for strings and their structures. +/// +/// \subsection getcharpositioninline GETCHARPOSITIONINLINE() +/// +/// The <code>GETCHARPOSITIONINLINE</code> returns the zero based offset of character <code>LA(1)</code> +/// from the start of the current input line. See the macro <code>GETLINE</code> for details on what the +/// line number means. +/// +/// \subsection emit EMIT() +/// +/// The macro <code>EMIT</code> causes the text range currently matched to the lexer rule to be emitted +/// immediately as the token for the rule. Subsequent text is matched but ignored. The type used for the +/// the token is the name of the lexer rule or, if you have change this by using $type = XXX;, the type +/// XXX is used. +/// +/// \subsection emitnew EMITNEW(t) +/// +/// The macro <code>EMITNEW</code> causes the supplied token reference <code>t</code> to be used as the +/// token emitted by the rule. The parameter <code>t </code> must be of type #pANTLR3_COMMON_TOKEN. +/// +/// \subsection index INDEX() +/// +/// The <code>INDEX</code> macro returns the current input position according to the input stream. It is not +/// guaranteed to be the character offset in the input stream but is instead used as a value +/// for marking and rewinding to specific points in the input stream. Use the macro <code>GETCHARINDEX()</code> +/// to find out the position of the <code>LA(1)</code> in the input stream. +/// +/// \subsection pushstream PUSHSTREAM(str) +/// +/// The <code>PUSHSTREAM</code> macro, in conjunction with the <code>POPSTREAM</code> macro (called internally in the runtime usually) +/// can be used to stack many input streams to the lexer, and implement constructs such as the C pre-processor +/// \#include directive. +/// +/// An input stream that is pushed on to the stack becomes the current input stream for the lexer and +/// the state of the previous stream is automatically saved. The input stream will be automatically +/// popped from the stack when it is exhausted by the lexer. You may use the macro <code>POPSTREAM</code> +/// to return to the previous input stream prior to exhausting the currently stacked input stream. +/// +/// Here is an example of using the macro in a lexer to implement the C \#include pre-processor directive: +/// +/// \code +/// fragment +/// STRING_GUTS : (~('\\'|'"') )* ; +/// +/// LINE_COMMAND +/// : '#' (' ' | '\t')* +/// ( +/// 'include' (' ' | '\t')+ '"' file = STRING_GUTS '"' (' ' | '\t')* '\r'? '\n' +/// { +/// pANTLR3_STRING fName; +/// pANTLR3_INPUT_STREAM in; +/// +/// // Create an initial string, then take a substring +/// // We can do this by messing with the start and end +/// // pointers of tokens and so on. This shows a reasonable way to +/// // manipulate strings. +/// // +/// fName = $file.text; +/// printf("Including file '\%s'\n", fName->chars); +/// +/// // Create a new input stream and take advantage of built in stream stacking +/// // in C target runtime. +/// // +/// in = antlr38BitFileStreamNew(fName->chars); +/// PUSHSTREAM(in); +/// +/// // Note that the input stream is not closed when it EOFs, I don't bother +/// // to do it here, but it is up to you to track streams created like this +/// // and destroy them when the whole parse session is complete. Remember that you +/// // don't want to do this until all tokens have been manipulated all the way through +/// // your tree parsers etc as the token does not store the text it just refers +/// // back to the input stream and trying to get the text for it will abort if you +/// // close the input stream too early. +/// // +/// +/// } +/// | (('0'..'9')=>('0'..'9'))+ ~('\n'|'\r')* '\r'? '\n' +/// ) +/// {$channel=HIDDEN;} +/// ; +/// \endcode +/// +/// \subsection popstream POPSTREAM() +/// +/// Assuming that you have stacked an input stream using the PUSHSTREAM macro, you can +/// remove it from the stream stack and revert to the previous input stream. You should be careful +/// to pop the stream at an appropriate point in your lexer action, so you do not match characters +/// from one stream with those from another in the same rule (unless this is what you want to do) +/// +/// \subsection settext SETTEXT(str) +/// +/// A token manufactured by the lexer does not actually physically store the text from the +/// input stream to which it matches. The token string is instead created only if you ask for +/// the text. However if you wish to change the text that the token represents you can use +/// this macro to set it explicitly. Note that this does not change the input stream text +/// but associates the supplied #pANTLR3_STRING with the token. This string is then returned +/// when parser and tree parser reference the tokens via the $xxx.text reference. +/// +/// \subsection user1 USER1 USER2 USER3 and CUSTOM +/// +/// While you can create your own custom token class and have the lexer deal with this, this +/// is a lot of work compared to the trivial inheritance that can be achieved in the Java target. +/// In many cases though, all that is needed is the addition of a few data items such as an +/// integer or a pointer. Rather than require C programmers to create complicated structures +/// just to add a few data items, the C target provides a few custom fields in the standard +/// token, which will fulfil the needs of most lexers and parsers. +/// +/// The token fields user1, user2, and user3 are all value types of #ANTLR_UINT32. In the +/// parser you can reference these fields directly from the token: <code>x=TOKNAME { $x->user1 ...</code> +/// but when you are building the token in the lexer, you must assign to the fields using the +/// macros <code>USER1</code>, <code>USER2</code>, or <code>USER3</code>. As in: +/// +/// \code +/// LEXTOK: 'AAAAA' { USER1 = 99; } ; +/// \endcode +/// +/// +/// \section parsermacros Parser and Tree Parser Macros +/// +/// \subsection parser PARSER +/// +/// The <code>PARSER</code> macro returns a pointer to the base parser or tree parser object, which is of type #pANTLR3_PARSER +/// or #pANTLR3_TREE_PARSER . This is not the pointer to your generated parser, which is supplied by the <code>CTX</code> macro, +/// but to the common implementation of a parser or tree parser interface, which is supplied to all generated parsers. +/// +/// \subsection index INDEX() +/// +/// When used in the parser, the <code>INDEX</code> macro returns the position of the current +/// token ( LT(1) ) in the input token stream. It can be used for <code>MARK</code> and <code>REWIND</code> +/// operations. +/// +/// \subsection lt LT(n) and LA(n) +/// +/// In the parser, the macro <code>LT(n)</code> returns the #pANTLR3_COMMON_TOKEN at offset <code>n</code> from +/// the current token stream input position. The macro <code>LA(n)</code> returns the token type of the token +/// at position <code>n</code>. The value <code>n</code> cannot be zero, and such a reference will return +/// <code>NULL</code> and possibly cause an error. <code>LA(1)</code> is the token that is about to be +/// recognized and <code>LA(-1)</code> is the token that has just been recognized. Values of n that exceed the +/// limits of the token stream boundaries will return <code>NULL</code>. +/// +/// \subsection psrstate PSRSTATE +/// +/// Returns the shared state pointer of type #pANTLR3_RECOGNIZER_SHARED_STATE. This is not generally +/// useful to the grammar programmer as the useful elements have generic $xxx references built in to +/// ANTLR. +/// +/// \subsection adaptor ADAPTOR +/// +/// When building an AST via a parser, the work of constructing and manipulating trees is done +/// by a supplied adaptor class. The default class is usually fine for most tree operations but +/// if you wish to build your own specialized linked/tree structure, then you may need to reference +/// the adaptor you supply directly. The <code>ADAPTOR</code> macro returns the reference to the tree adaptor +/// which is always of type #pANTLR3_BASE_TREE_ADAPTOR, even if it is your custom adapter. +/// +/// \section commonmacros Macros Common to All Recognizers +/// +/// \subsection recognizer RECOGNIZER +/// +/// Returns a reference type of #pANTRL3_BASE_RECOGNIZER, which is the base functionality supplied +/// to all recognizers, whether lexers, parsers or tree parsers. You can override methods in this +/// interface by installing your own function pointers (once you know what you are doing). +/// +/// \subsection input INPUT +/// +/// Returns a reference to the input stream of the appropriate type for the recognizer. In a lexer +/// this macro returns a reference type of #pANTLR3_INPUT_STREAM, in a parser this is type +/// #pANTLR3_TOKEN_STREAM and in a tree parser this is type #pANTLR3_COMMON_TREE_NODE_STREAM. +/// You can of course provide your own implementations of any of these interfaces. +/// +/// \subsection mark MARK() +/// +/// This macro will cause the input stream for the current recognizer to be marked with a +/// checkpoint. It will return a value type of #ANTLR3_MARKER which you can use as the +/// parameter to a <code>REWIND</code> macro to return to the marked point in the input. +/// +/// If you know you will only ever rewind to the last <code>MARK</code>, then you can ignore the return +/// value of this macro and just use the <code>REWINDLAST</code> macro to return to the last <code>MARK</code> that +/// was set in the input stream. +/// +/// \subsection rewind REWIND(m) +/// +/// Rewinds the appropriate input stream back to the marked checkpoint returned from a prior +/// MARK macro call and supplied as the parameter <code>m</code> to the <code>REWIND(m)</code> +/// macro. +/// +/// \subsection rewindlast REWINDLAST() +/// +/// Rewinds the current input stream (character, tokens, tree nodes) back to the last checkpoint +/// marker created by a <code>MARK</code> macro call. Fails silently if there was no prior +/// <code>MARK</code> call. +/// +/// \subsection seek SEEK(n) +/// +/// Causes the input stream to position itself directly at offset <code>n</code> in the stream. Works for all +/// input stream types, both lexer, parser and tree parser. +/// diff --git a/antlr/libantlr3c-3.4/doxygen/knownissues.dox b/antlr/libantlr3c-3.4/doxygen/knownissues.dox new file mode 100644 index 0000000..733c405 --- /dev/null +++ b/antlr/libantlr3c-3.4/doxygen/knownissues.dox @@ -0,0 +1,3 @@ +/// \page knownissues Known Issues +/// +/// The following issues
\ No newline at end of file diff --git a/antlr/libantlr3c-3.4/doxygen/mainpage.dox b/antlr/libantlr3c-3.4/doxygen/mainpage.dox new file mode 100644 index 0000000..ed52b5e --- /dev/null +++ b/antlr/libantlr3c-3.4/doxygen/mainpage.dox @@ -0,0 +1,104 @@ +// Main page documentation for ANTLR3C runtime. Contains +// doxygen things only. +// + +/// \mainpage ANTLR3 C Runtime API and Usage Guide. +/// +/// \section version Version 3.3.1 +/// +/// This documentation is specifically for the C rutime version 3.1.x.x, which is +/// specifically for use with version 3.1.x.x of the ANTLR recognizer generation +/// tool. While some of the documentation may well apply to prior or future versions +/// you should consult the manuals for the correct version whenever possible. +/// +/// \section chchchchangeesss Changes from 3.2 to 3.3.1 +/// +/// Some changes in 3.3.1 may require small changes in your invoking programs or +/// in the grammar itself. Please read about them here before emailing the user group, +/// where you will be told to come and read about them here, unless they were missed +/// from this list. +/// +/// - \subpage changes331 Check here for API changes +/// +/// \section intro Introduction +/// +/// The ANTLR3 recognizer generation tool is written in Java, but allows the generation +/// of code targeted for a number of other languages. Each target language provides a code +/// generation template for the tool and a runtime library for use by generated recognizers. +/// The C runtime tracks the Java runtime releases and in general when a new version of the +/// tool is released, a new version of the C runtime will be released at the same time. +/// +/// The documentation here is in three parts: +/// +/// - \subpage build Building the runtime itself from source code; +/// - \subpage generate How to tell ANTLR to generate code for the C target; +/// - \subpage buildrec How to build the generated code +/// - \subpage using Using the runtime and the libraries and so on; +/// - \subpage runtime The documentation of the runtime code and functions; +/// +/// \section background Background Information +/// +/// The ANTLR 3 C runtime and code generation templates were written by <a href="http://www.linkedin.com/in/jimidle"> Jim Idle</a> +/// (jimi|at|temporal-wave|dott/com) of <a href="http://www.temporal-wave.com">Temporal Wave LLC</a>. +/// +/// The C runtime and therefore the code generated to utilize the runtime reflects the object model of the +/// Java version of the runtime as closely as a language without class structures and inheritance can. +/// Compromises have only been made where performance would be adversely affected such as minimizing the +/// number of pointer to pointer to pointer to function type structures that could ensue through trying to +/// model inheritance too exactly. Other differences include the use of token and string factories to minimize +/// the number of calls to system functions such as calloc().This model was adopted so that overriding any +/// default implementation of a function is relatively simple for the grammar programmer. +/// +/// The generated code is free threading (subject to the systems calls used on any particular platform +/// being likewise free threading.) +/// +/// \subsection model Runtime Model +/// +/// As there is no such thing as an object reference in C, the runtime defines a number of typedef structs that reflect +/// the calling interface chosen by Terence Parr for the Java version of the same. The initialization of a parser, +/// lexer, input stream or other internal structure therefore consists of allocating the memory required for +/// an instance of the typedef struct that represents the interface, initializing any counters, and buffers etc, +/// then populating a number of pointers to functions that implement the equivalent of the methods in the Java class. +/// +/// The use and initialization of the C versions of a parser is therefore similar to the examples given for Java, +/// but with a bent towards C of course. You may need to be aware of memory allocation and freeing operations +/// in certain environments such as Windows, where you cannot allocate memory in one DLL and free it in another. +/// +/// The runtime provides a number of structures and interfaces that the author has found useful when writing action and +/// processing code within java parsers, and furthermore were required by the C runtime code if it was not to +/// depart too far from the logical layout of the Java model. These include the C equivalents of String, List, +/// Hashtable, Vector and Trie, implemented by pointers to structures. These are freely available for your own programming needs. +/// +/// A goal of the generated code was to minimize the tracking, allocation and freeing of memory for reasons of both +/// performance and reliability. In essence any memory used by a lexer, parser or tree parser is automatically tracked and +/// freed when the instance of it is released. There are therefore factory functions for tokens and so on such that they +/// can be allocated in blocks and parceled out as they are required. They are all then freed in one go, minimizing the +/// risk of memory leaks and alloc/free thrashing. This has only one side effect, being that if you wish to preserve some structure generated by +/// the lexer, parser or tree parser, then you must make a copy of it before freeing those structures, and track it yourself +/// after that. In practice, it is easy enough just not to release the antlr generated components until you are +/// finished with their results. +/// +/// \section targets Target Platforms +/// +/// The C project is constructed such that it will compile on any reasonable ANSI C compiler in either 64 or 32 bit mode, +/// with all warnings turned on. This is true of both the runtime code and the generated code and has been summarily tested +/// with Visual Studio .Net (2003, 2005 and 2008) and later versions of gcc on Redhat Linux, as well as on AIX 5.2/5.3, Solaris 9/10, +/// HPUX 11.xx, OSX (PowerPC and Intel) and Cygwin. +/// +/// \b Notes +/// - The C runtime is constructed such that the library can be integrated as an archive library, or a shared library/DLL. +/// - The C language target code generation templates are distributed with the source code for the ANTLR tool itself. +/// +/// \section performance Performance +/// +/// It is C :-). Basic testing of performance against the Java runtime, +/// using the JDK1.6 java source code, and the Java parser provided in the examples (which is a tough test as it includes +/// backtracking and memoization) show that the C runtime uses about half the memory and is between 2 and 3 times the speed. +/// Tests of non-backtracking, non-memoizing parsers, indicate results significantly better than this. +/// +/// \section examples Downloading Examples +/// +/// The <a href="http://www.antlr.org/download.html">downloads page</a> of the ANTLR web site contains a downloadable +/// zip/tar of examples projects for use with the C runtime model. It contains .sln files and source code for a +/// number of example grammars and helps to see how to invoke and call the generated recognizers. +///
\ No newline at end of file diff --git a/antlr/libantlr3c-3.4/doxygen/runtime.dox b/antlr/libantlr3c-3.4/doxygen/runtime.dox new file mode 100644 index 0000000..2d23403 --- /dev/null +++ b/antlr/libantlr3c-3.4/doxygen/runtime.dox @@ -0,0 +1,35 @@ +/// \page runtime Navigating the C Runtime Documentation +/// +/// If you are familiar with Doxygen generated documentation, then the layout of the files, typedefs +/// and so on will be familiar to you. However there is also additional structure applied that helps +/// the programmer to see how the runtime is made up. +/// +/// \section modules Modules +/// +/// Under the Modules menu tree you will find the entry API Classes. This section is further +/// divided into typedefs and structs and the standard runtime supplied interface implementation +/// methods. +/// +/// The typedefs are the types that you declare in your code and which are returned by the +/// 'constructors' such as antlr38BitFileStreamNew(). The underlying structures document +/// the data elements of the type and what a function pointer installed in any particular +/// slot should do. +/// +/// The default implementations are the static methods within the default implementation file +/// for a 'class', which are installed by the runtime when a default instance of one the +/// typedefs (classes) is created. +/// +/// When navigating the source code, find the typedef you want to consult and inspect the documentation +/// for its function pointers, then look at the documentation for the default methods that implement +/// that 'method'. +/// +/// For example, under "API Typedefs and Structs" you will find "Base Recognizer Definition", which tells +/// you all the methods that belong to this interface. Under "API Implementation Functions", you will +/// find "Base Recognizer Implementation", which documents the actual functions that are installed +/// to implement the class methods. +/// +/// From here, the documentation should be obvious. If it is not, then you could try reading +/// the actual source code, but please don't email the author directly, use the ANTLR Interest +/// email group, which you should probably have signed up for if you have read this far into the +/// C runtime documentation. +///
\ No newline at end of file diff --git a/antlr/libantlr3c-3.4/doxygen/using.dox b/antlr/libantlr3c-3.4/doxygen/using.dox new file mode 100644 index 0000000..fb8424a --- /dev/null +++ b/antlr/libantlr3c-3.4/doxygen/using.dox @@ -0,0 +1,62 @@ +/// \page using Using the ANTLR3 C Target +/// +/// \section intro Introduction +/// +/// Using the ANTLR target involves gaining knowledge of a number of elements: +/// +/// -# Writing ANTLR grammars (not covered in this manual); +/// -# How ANTLR works (not covered in this manual); +/// -# How to use the \@sections with the C target +/// -# Interoperation with the runtime within rule actions; +/// -# Implementing custom versions of the standard library methods; +/// +/// If you are as yet unfamiliar with how ANTLR works in general, then +/// it is suggested that you read the various <a href="http://www.antlr.org/wiki">wiki pages</a> concerned with +/// getting started. However there are a few things that you should note: +/// +/// - The lexer is independent of the parser. You \b cannot control the lexer from within the parser; +/// - The tree parser is independent of the parser. You \b cannot control the parser from within the tree parser(s); +/// - Each tree parser is independent of other tree parsers. +/// +/// This means that your lexer runs first and consumes all the input stream until +/// you stop it programmatically, or it reaches the end of the input stream. It produces +/// a complete stream of tokens, which the parser then consumes. +/// +/// \section Using \@sections in a C Targeted Grammar +/// +/// Within a grammar file there are a number of special sections you can add that cause the +/// code within them to be placed at strategic points in the generated code such as +/// before or after the #include statements in the .c file, within the generated header file +/// or within the constructor for the recognizer. +/// +/// Many of the \@sections used within a Java targeted grammar have some equivalent function within a +/// C targeted grammar, but their use may well be subtly different. There are also additional sections +/// that have meaning only within a grammar targeted for the C runtime. +/// +/// Detailed documentation of these sections is given here: \subpage atsections +/// +/// \section interop Interoperation Within Rule Actions +/// +/// Rule actions have a limited number of elements they can access by name, independently of the +/// target language generated. These are elements such as $line, $pos, $text and so on. Where the +/// $xxx returns a basic type such as \c int, then you can use these in C as you would in the Java +/// target, but where a reference returns a string, you will get a pointer to the C runtime +/// string implementation #pANTLR3_STRING. This will give you access to things like token text +/// but also provides some convenience methods such as #pANTLR3_STRING->substring() and #pANTLR3_STRING->toUTF8(). +/// +/// The generated code provides a number of C MACROs, which make it easier to access runtime +/// components. Always use these macros when available, to protect your action code from changes +/// to the underlying implementation. +/// +/// Detailed documentation of macros and rule action interoperation is given here: \subpage interop +/// +/// \section Custom Implementing Customized Methods +/// +/// Unless you wish to create your own tree structures using the built in ANTLR AST rewriting +/// notation, you will rarely need to override the default implementation of runtime methods. The +/// exception to this will be the syntax err reporting method, which is essentially a stub function +/// that you will usually want to provide your own implementation for. You should consider the built in function +/// displayRecognitionError() as an example of where to start as there can be no really useful +/// generic error message display. +/// +///
\ No newline at end of file |