##APG - An ABNF Parser Generator
Version: 6.3
Description:
- APG is an acronym for "ABNF Parser Generator"
- generates parsers in C or C++
- generates language parsers and translators from a superset of the Augmented Backus-Naur Form (ABNF RFC5234) grammar syntax
- accepts valid ABNF grammars
- accepts
AND&NOTsyntactic predicate operators for conditional parsing based on specified, look-ahead phrases - accepts User-Defined Terminals (UDTs) which allow user-written, non-Context-Free phrase recognition operators
- runs on both 32- and 64-bit operating systems
- input language strings may be represented with 8-, 16-, 32- or 64-bit character codes
- user-written callback functions provide complete monitoring and flow control of the parser
- optional generation of an Abstract Syntax Tree (AST)
- translation of the AST with user-written callback functions
- extensive tracing facilities
- statistics gathering for a full picture of parse tree node coverage
- extensive attribute generation for an overview of the grammar's characteristics
| directories/files: | description |
|---|---|
| ApgLib/ | - the APG runtime library, required by the generator and all generated parsers |
| ApgUtilities/ | - optional but useful utilities, especially for formatted display of APG's data structures |
| Generator/ | - the main() function here is the parser generator |
| CppDemo/ | - example of how to set up and run a C++ parser |
| Demo/ | - a simple example which demonstrates most of the APG features including UDTs |
| MEGACO/ | - a C++ parser for the Media Gateway Control protocol (RFC3525) |
| SIP/ | - an extensive timing test demonstrating the power of UDTs for the Session Initiation Protocol (RFC3261) |
| WideCharacters/ | - demonstrates parsing 32-bit character coded input strings |
| LICENSE | - Version 2 of the GNU General Public License |
| README.md | - this file |
| Doxyfile | - documentation generation (Doxygen) configuration file |
| DoxyHeader.html | - documentation header file |
| DoxyFooter.html | - documentation footer file |
| other | - automake files |
Each of the directories Generator, CppDemo, Demo, MEGACO, SIP and WideCharacters has two bash scripts: runtests and generateGrammars.
runtests will run one or more tests on the optimized and debug builds.
generateGrammars will re-generate all of the parser files from the included grammar (.bnf) files.
Linux Installation:
The automake installation uses the "subdir-objects" option. This option has changed with automake >=1.14. It is recommended with version 1.14 and will be mandatory in automake 2.0. Consequently, APG and the examples are now built with a single Makefile.am file and recursion into subdirectories has been eliminated. This has the feature of putting all of the object files in the same directories where the respective the source files reside. A couple of tricks will be demonstrated here to get rid of the clutter if you find this annoying.
a) the basic build:
clone or unzip apg-6.3
cd (repo directory)
./configure
make
sudo make install
This will make all targets (see b) below) and install the optimized version of apg in:
/usr/local/bin/apg
apg is the parser generator. For usage, execute "apg --help".
To change the install location use, for example:
./configure --prefix=/mydir installs to /mydir/bin/apg
Note that apg may conflict with a program name already installed (Automated Password Generator, for example.) To change the name of the installed program use, for example:
./configure --program-prefix=my installs /usr/local/bin/myapg
or
./configure --program-suffix=en installs /usr/local/bin/apgen
b) the build targets:
| optimized target | debug target | description |
|---|---|---|
| apg | apg_dbg | APG - the ABNF Parser Generator |
| cppdemo | cppdemo_dbg | basic demonstration of building and using a C++ parser |
| demo | demo_dbg | basic demonstration of most of the APG features |
| megaco | megaco_dbg | sample C++, MEGAGO parser |
| sip | sip_dbg | extensive timing tests for variously optimized SIP parsers |
| wide | wide_dbg | example of using 32-bit wide grammar alphabet characters |
Note that individual programs can be built by specifying the target names. e.g.
make apg ; build only the optimized version of apg
make sip sip_dbg ; build both the optimized and debug versions of the SIP example
c) (recommended) put all object files and executables in a separate directory:
clone or unzip apg-6.3
cd (repo directory)
mkdir build
cd build
../configure
make
sudo make install
When using this configuration it will be necessary to supply the build directory as a parameter to the test scripts, runtests and generateGrammars, that exist in each target directory. For example, with the build above, to test the generator (apg)
cd ../Generator
./runtests ../build
./generateGrammars ../build
d) clean up:
make mostlyclean ; remove all object files but not the executable programs
make maintainer-clean ; remove everything make created
Documentation:
Install Doxygen. From the repo directory run
doxygen
Open ./documentation/index.html in any web browser. Or visit the APG website.
Copyright:
Copyright © 2005 - 2012 Lowell D. Thomas, all rights reserved
License:
APG Version 6.3 is released under Version 2.0 or higher of the
GNU General Public License.