Java APG

Version: 1.1.0

Note: Version 1.1.0 updates version 1.0 in a couple of ways. Primarily, the license is changed to the more permissive 2-Clause BSD license. Also, in the installation section below are instructions on how to include Java APG in a maven project. I want to thank Raviteja Lokineni (@bond-) for suggesting these changes and especially Stephen Sill II (@ssill2) for his friendly and expert nudging of me up the maven learning curve. (See issue #6.)

Description:

• Java APG is APG - an ABNF Parser Generator written completely in the Java language.
• generates parsers in Java
• generates language parsers and translators from a superset of the Augmented Backus-Naur Form (RFC5234 and RFC7405) grammar syntax
• accepts valid ABNF grammars
• accepts AND & NOT syntactic 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
• user-written callback functions provide complete monitoring and flow control of the parser
• accept case-sensitive literal strings in single quotes
• accept multiple input ABNF grammar files
• 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

For more details see the documentation or visit the APG website.

Directories/files:	description
src/apg	Java APG, the generator and the runtime library required by all generated parsers.
src/examples/	Examples to demonstrate how to set up and use a Java APG parser. The main function here is the driver for running any and all of the following examples. See javadoc examples.Main for a complete list of the tests that it runs.
src/examples/anbn	Comparisons the CFG and UDT parsers for the anbn, n > 0, grammar.
src/examples/anbncn	Comparisons the CFG and UDT parsers for the anbncn, n > 0, grammar.
src/examples/demo	Demonstrates many of the main features of Java APG including UDTs.
src/examples/expressions	Comparisons the CFG and UDT parsers for the expressions grammar.
src/examples/inifile	Comparisons the CFG and UDT parsers for the inifile grammar.
src/examples/mailbox	Comparisons the CFG and UDT parsers for the mailbox grammar ().
src/examples/testudtlib	Comparisons the CFG and UDT parsers for the suite of UdtLib UDTs.
build/	Scripts and files for compiling and documenting Java APG.
LICENSE.md	2-Clause BSD license.
README.md	This file.

Installation: The build/ directory has scripts and files for compiling and documenting Java APG.
To compile all source code and create the package .jar files:

git clone https://github.com/ldthomas/apg-java.git
cd apg-java/build
./make-jars

This will create apg.jar and examples.jar. To test apg.jar run:

java -jar apg.jar /version

To test examples.jar run:

java -jar examples.jar /test=all

Maven: For maven development, install apg.jar in the local repository.

mvn install:install-file -DgroupId=com.sabnf -DartifactId=apg -Dversion=1.1-SNAPSHOT -Dpackaging=jar -Dfile=apg.jar -DgeneratePom=true

Then modify the project's pom.xml file to include,

<dependencies>
    <dependency>
        <groupId>com.sabnf</groupId>
        <artifactId>apg</artifactId>
        <version>1.1-SNAPSHOT</version>
        <scope>compile</scope>
    </dependency>
</dependencies>

See the maven.md for details on how to run the examples in a NetBeans maven project.

NOTE: A second branch, maven, has been added which is a complete maven project for apg and the examples. It was created by Stephen Sill II on his apg-java fork. It has updates to satisfy some of the security items flagged by Fortify security scans. The Fortify updates have not been integrated into the master branch.

Documentation:
To see the documentation run:

./make-javadoc

Open ../javadoc/index.html in any web browser. Or visit the APG website.

Copyright:
Copyright © 2021 Lowell D. Thomas, all rights reserved

License:
Java APG Version 1.1.0 is released under the 2-Clause BSD license.