JavaCC

Java Compiler Compiler (JavaCC) is the most popular parser generator for use with Java applications.

A parser generator is a tool that reads a grammar specification and converts it to a Java program that can recognize matches to the grammar.

In addition to the parser generator itself, JavaCC provides other standard capabilities related to parser generation such as tree building (via a tool called JJTree included with JavaCC), actions and debugging.

All you need to run a JavaCC parser, once generated, is a Java Runtime Environment (JRE).

This README is meant as a brief overview of the core features and how to set things up to get yourself started with JavaCC. For a fully detailed documentation, please see https://javacc.github.io/javacc/.

Contents

Introduction

Features

An example

The following JavaCC grammar example recognizes matching braces followed by zero or more line terminators and then an end of file.

Examples of legal strings in this grammar are:

{}, }}} // … etc

Examples of illegal strings are:

{}{}, }{}}, { }, {x} // … etc

Its grammar
PARSER_BEGIN(Example)

/** Simple brace matcher. */
public class Example {

  /** Main entry point. */
  public static void main(String args[]) throws ParseException {
    Example parser = new Example(System.in);
    parser.Input();
  }

}

PARSER_END(Example)

/** Root production. */
void Input() :
{}
{
  MatchedBraces() ("\n"|"\r")* <EOF>
}

/** Brace matching production. */
void MatchedBraces() :
{}
{
  "{" [ MatchedBraces() ] "}"
}
Some executions and outputs
gives no error
$ java Example
<return>
{x gives a Lexical error
$ java Example
{x<return>
Lexical error at line 1, column 2.  Encountered: "x"
TokenMgrError: Lexical error at line 1, column 2.  Encountered: "x" (120), after : ""
        at ExampleTokenManager.getNextToken(ExampleTokenManager.java:146)
        at Example.getToken(Example.java:140)
        at Example.MatchedBraces(Example.java:51)
        at Example.Input(Example.java:10)
        at Example.main(Example.java:6)
gives a ParseException
$ java Example
{}}<return>
ParseException: Encountered "}" at line 1, column 3.
Was expecting one of:
    <EOF>
    "\n" ...
    "\r" ...
        at Example.generateParseException(Example.java:184)
        at Example.jj_consume_token(Example.java:126)
        at Example.Input(Example.java:32)
        at Example.main(Example.java:6)

Getting Started

You can use JavaCC either from the command line or through an IDE.

Use JavaCC from the command line

Download

Download the latest stable release (at least the source and the binaries) in a so called download directory:

All JavaCC releases are available via GitHub and Maven including checksums and cryptographic signatures.

For all previous releases, please see stable releases.

Install

Once you have downloaded the files, navigate to the download directory and unzip the source file, this creating a so called JavaCC installation directory:

$ unzip javacc-7.0.13.zip
or
$ tar xvf javacc-7.0.13.tar.gz

Then move the binary file javacc-7.0.13.jar under the download directory in a new target/ directory under the installation directory, and rename it to javacc.jar.

Then add the scripts/ directory in the JavaCC installation directory to your PATH. The JavaCC, JJTree, and JJDoc invocation scripts/executables reside in this directory.

On UNIX based systems, the scripts may not be executable immediately. This can be solved by using the command from the javacc-7.0.13/ directory:

chmod +x scripts/javacc

Write your grammar and generate your parser

You can then create and edit a grammar file with your favorite text editor.

Then use the appropriate script for generating your parser from your grammar.

Use JavaCC within an IDE

Minimal requirements for an IDE are:

IntelliJ IDEA

The IntelliJ IDE supports Maven out of the box and offers a plugin for JavaCC development.

Eclipse IDE

Maven

Add the following dependency to your pom.xml file.

<dependency>
    <groupId>net.java.dev.javacc</groupId>
    <artifactId>javacc</artifactId>
    <version>7.0.13</version>
</dependency>

Gradle

Add the following to your build.gradle file.

repositories {
    mavenLocal()
    maven {
        url = 'https://mvnrepository.com/artifact/net.java.dev.javacc/javacc'
    }
}

dependencies {
    compile group: 'net.java.dev.javacc', name: 'javacc', version: '7.0.13'
}

Rebuilding JavaCC

From the source installation directory

The source installation directory contains the JavaCC, JJTree and JJDoc sources, launcher scripts, example grammars and documentation, and also a bootstrap version of JavaCC needed to build JavaCC.

Prerequisites for building JavaCC with this method:

Use the ant build script:

$ cd javacc
$ ant

This will build the javacc.jar file in the target/ directory

After cloning the JavaCC GitHub repository

This is the preferred method for contributing to JavaCC.

Prerequisites for building JavaCC with this method:

Just clone the repository and then use the ant build script:

$ git clone https://github.com/javacc/javacc.git
$ cd javacc
$ ant

This will build the javacc.jar file in the target/ directory

Community

JavaCC is by far the most popular parser generator used with Java applications with an estimated user base of over 1,000 users and more than 100,000 downloads to date.

It is maintained by the developer community which includes the original authors and Chris Ainsley, Tim Pizney and Francis Andre.

Support

Don’t hesitate to ask!

Contact the developers and community on the Google user group or email us at JavaCC Support if you need any help.

Open an issue if you found a bug in JavaCC.

For questions relating to development please join our Slack channel.

Documentation

The documentation of JavaCC is located on the website https://javacc.github.io/javacc/ and in the docs/ directory of the source code on GitHub.

It includes detailed documentation for JavaCC, JJTree, and JJDoc.

Resources

Books
Tutorials
Articles
Parsing theory

Powered by JavaCC

JavaCC is used in many commercial applications and open source projects.

The following list highlights a few notable JavaCC projects that run interesting use cases in production, with links to the relevant grammar specifications.

User Use Case Grammar File(s)
Apache ActiveMQ Parsing JMS selector statements SelectorParser.jj, HyphenatedParser.jj
Apache Avro Parsing higher-level languages into Avro Schema idl.jj
Apache Calcite Parsing SQL statements Parser.jj
Apache Camel Parsing stored SQL templates sspt.jj
Apache Jena Parsing queries written in SPARQL, ARQ, SSE, Turtle and JSON sparql_10, sparql_11, arq.jj, sse.jj, turtle.jj, json.jj
Apache Lucene Parsing search queries QueryParser.jj
Apache Tomcat Parsing Expression Language (EL) and JSON ELParser.jjt, JSONParser.jj
Apache Zookeeper Optimising serialisation/deserialisation of Hadoop I/O records rcc.jj
Java Parser Parsing Java language files java.jj

License

JavaCC is an open source project released under the BSD License 2.0. The JavaCC project was originally developed at Sun Microsystems Inc. by Sreeni Viswanadha and Sriram Sankar.


Top