Pep version 0.4: an Earley parser in Java, Copyright (C) 2007 Scott Martin.

Pep is free software distributed under the terms of the GNU Lesser General Public License. See the COPYING file for details.

Author: Scott Martin (http://www.ling.osu.edu/~scott/)

The name `Pep' stands for "Pep is an Earley Parser" and is an example of direct left recursion. Pep can both recognize and parse strings of any context-free grammar (CFG). For the parsing case, Pep provides all possible parses of a given string according to a given grammar. Several sample grammars are provided in the ./samples directory. For an example of how to use Pep as a library, see the command-line front end implemented in edu/osu/ling/pep/Pep.java (found in the ./src directory).

Acknowledgments

Thanks to Detmar Meurers for providing the `tiny' grammar, to Jim Slattery for pointing out that ParseTree.children is much better represented as a java.util.List than a java.util.Set, and to Harun Resit Zafer for noticing that GrammarParser should really be public.

Requirements

Running
	Java Runtime Environment >= 1.5
	http://java.sun.com/

Building
	Ant >= 1.6.1
	http://ant.apache.org/

Testing
	JUnit >= 3.8.1
	http://www.junit.org/

Running

1. Set the environment variable PEP_HOME to the directory where Pep is unpacked. For example, with Pep's directory as the current directory, do:

   $ export PEP_HOME=pwd

   on Linux systems.

2. Invoke Pep using the shell script in $PEP_HOME/bin/pep. The location of the grammar to use, seed category, and string to parse must be specified. Example (again from $PEP_HOME on a Linux machine):

   $ ./bin/pep -v -g samples/miniscule.xml -s S the boy left

   or equivalently (reading from standard input):

   $ echo the boy left | ./bin/pep -v -g samples/miniscule.xml -s S -

   This command will parse the string the boy left' using the grammar in samples/miniscule.xml for the seed category S'. Pep can show more or less information about what it is doing depending on the level of verbosity, as specified by the flag "-v n" (where n is the verbosity level, and 1 is assumed for n if it is omittied). For more help on Pep's options, invoke pep as above with -h' or --help' among the arguments.

   The $PEP_HOME/samples directory contains several sample grammars. Each grammar is specified in its own XML file, and example sentences are listed. The file etc/grammar.xsd contains an XML schema describing the format of Pep's grammar files.

Building

An ant build file (build.xml) is included for building Pep from source. To compile Pep's source to Java bytecode, just run ant with the `compile' target:

$ ant compile

The packaged Pep library can also be recreated using the `package' task.

Testing

The ant build file (as discussed above in Building') contains a target for compiling and running the JUnit tasks that test Pep. To run all unit tests, just run ant with the test' target.

Documentation

Javadoc API documentation for Pep can be generated using the `document' task, which will place the API docs in $PEP_HOME/docs/api.