Java Compiler Compiler (JavaCC) is the most popular parser generator for use with Java applications, and it allows generating C+= and C# parsers since version 8.

A parser generator is a tool that reads a grammar specification (in plain text) and converts it to a program (of some programming language) 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:

Contents

What is JavaCC

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)

Starting using JavaCC

Contents

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

Use JavaCC within an IDE

Minimal requirements for an IDE are:

Depending on the build environment of the user choice: support for Ant or Maven or Gradle with Java

IntelliJ IDEA

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

Eclipse IDE

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

Maven

Add the following specialized plugin to your pom.xml file, under the build / reporting plugins, or under one or more profiles.

(Note that you can use the well known Apache Exec Plugin to run JavaCC, with appropriate jars in the classpath, the main entry point and standard arguments passing - but you will not benefit from the specialized plugin features.)

Maven with version 8

(For version 8 you must use the javacc-maven-plugin from the JavaCC organization, not from others. Note that version 8.1.0 benefits from a bunch of improvements over previous versions and the configuration is a little different.)

Adapt the versions (in the examples below it is set to 3.8.0 and8.1.0), the execution(s) (goals javacc and/or jjtree-javacc) and the codeGenerator setting for the generator (java, cpp, csharp).
Also add the configuration settings for those you want to use a non default value.

See the JavaCC Maven Plugin web site (in the Apache Maven format) or the JavaCC Maven Plugin GitHub repository for full explanations of parameters, inheritance, intermediate directories, debug…

          <plugin>
              <groupId>org.javacc.plugin</groupId>
              <artifactId>javacc-maven-plugin</artifactId>
              <version>3.8.0</version>
              <executions>
                  <!-- as many executions as different sets of grammars similar configurations -->
                  <!-- here we use a non standard layout: 
                        ("my cc" and "gen-src" instead of "src" and "generated-sources") -->
                  <execution>
                      <id>jjtree-javacc</id>
                      <phase>generate-sources</phase>
                      <goals>
                          <goal>jjtree-javacc</goal>
                      </goals>
                      <configuration>
                        <includes>
                          <include>...</include> <!-- default is *.jjt for JJTree -->
                        </includes>
                        <excludes>
                          <exclude>...</exclude> <!-- default is nothing -->
                        </excludes>
                        <keepIntermediateDirectory>false</keepIntermediateDirectory> <!-- the default -->
                        <skip>false</skip> <!-- the default -->
                        <sourceDirectory>my cc</sourceDirectory>
                        <jjtreeCmdLineArgs>
                          <arg>-JJTREE_OUTPUT_DIRECTORY="${project.build.directory}/gen-src/jjtree"</jjtod>
                          <arg>-CODE_GENERATOR="Java"</arg>
                          <arg>-MULTI=true</arg>
                        </jjtreeCmdLineArgs>
                        <javaccCmdLineArgs>
                          <arg>-OUTPUT_DIRECTORY="${project.build.directory}/gen-src/javacc"</jjod>
                          <arg>-CODE_GENERATOR="Java"</arg>
                          <arg>-STATIC:false</arg>
                        </javaccCmdLineArgs>
                      </configuration>
                  </execution>
              </executions>
              <dependencies>
                  <!-- declare all used generators artifacts;  the core may be omited,
                        as it is a dependency of the generators -->
                  <!--            <dependency>-->
                  <!--              <groupId>org.javacc</groupId>-->
                  <!--              <artifactId>core</artifactId>-->
                  <!--              <version>8.1.0</version>-->
                  <!--              <scope>runtime</scope>-->
                  <!--            </dependency>-->
                  <dependency>
                      <groupId>org.javacc.generator</groupId>
                      <artifactId>java</artifactId>
                      <version>8.1.0</version>
                      <scope>runtime</scope>
                  </dependency>
                </dependencies>
            </plugin>
Maven with version 7

(You can use the javacc-maven-plugin from MojoHaus or the javacc-maven-plugin from the JavaCC organization.)

Same as above, with a single different dependency, and without the codeGenerator setting, and with named parameters in the configuration (like <static>true</static>).

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

Gradle

Gradle with version 8

Courtesy of JSqlParser

The following entries will provide you with the tasks javacc:compileJavacc, javacc:compileJjtree and javacc:jjdoc which will be executed automatically before compileJava:

plugins {
   id "org.javacc.javacc" version "latest.release"
}
repositories {
    gradlePluginPortal()
    mavenLocal()
    mavenCentral()

    // Sonatype OSSRH Snapshots
    maven {
        url = uri('https://s01.oss.sonatype.org/content/repositories/snapshots/')
    }
}
dependencies {
    javacc 'org.javacc:core:8.1.0'
    javacc 'org.javacc.generator:java:8.1.0'
}
Gradle with version 7

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'
}

Use JavaCC from the command line

Download

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

Download version 8

Download the core and the generator(s) you are going to use:

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

Download version 7

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

For all previous releases, please see stable releases.

Install

Install version 8

TODO to be written. Help welcomed!

Install version 7

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

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

Then create a new target directory under the installation directory, and copy or move the binary file javacc-7.0.13.jar under this target directory, and copy or rename it to javacc.jar.

Then add the scripts/ directory under 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.

Quick migration guide from v7 to v8

Customizing your generated code

You can customize the generated code in some areas, those that are driven by template files: in the generators there are src/main/resources/templates folders that contain different .template files (you can get them by downloading them from the GitHub repository).

Of course you need to understand what you should not alter (signatures of methods called by other generated methods…) and what you can change (output messages…) in the template files.

Then in order to use your modified template file, you have to integrate it in the classpath in the step(s) you use for generating the parser:

Rebuilding JavaCC

For more details and information, see README_BUILD.

Versions

The RECOMMENDED version is version 8.1.0.
It separates the parser (the core) from the generators (for the different languages); development and maintenance effort will be mainly on this version.
This version lies on different Git repositories / Java & Maven projects / jars:

After cloning, the expected folder structure would look like:

ls -d *
javacc-8/  javacc-8-core/  javacc-8-java/ javacc-8-cpp/ javacc-8-csharp/

The previous versions (4, 5, 6, 7) are widely spread; effort to migrate to version 8 should be minimum.
Their last versions lie on a single Git repository / Java & Maven project / jar:

Differences between v8 versus v7: very small at the grammar level, more important at the generated sources level:

Building JavaCC

See Building JavaCC if you want to hack or contribute to JavaCC.

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, Francis Andre and Marc Mazas.

Support

Open an issue if you think you found a bug in JavaCC.

If you use version 8 and generate for Java, and you do not know to which part it is related (the base or the core or the generator), open it here in the generator;
same for C++: here;
same for C#: here.
If you are sure of the project it is related to, open it in the issues section of the project.

If you use version 7, open it here.

Create a new discussion (in the Discussions tab) if you have some general question - do not create an issue for a question.
But 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.

For questions relating to development please join our Slack channel.

Contributing

This is an active open-source project. We are always open to people who want to use the system or contribute to it.
Contact us through the repository discussions area if you are looking for implementation tasks that fit your skills.

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 3.0.
The JavaCC project was originally developed at Sun Microsystems Inc. by Sreeni Viswanadha and Sriram Sankar.


Top