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
-
JavaCC generates top-down (recursive descent) parsers as opposed to bottom-up parsers generated by YACC-like tools. This allows the use of more general grammars, although left-recursion is disallowed. Top-down parsers have a number of other advantages (besides more general grammars) such as being easier to debug, having the ability to parse to any non-terminal in the grammar, and also having the ability to pass values (attributes) both up and down the parse tree during parsing.
-
By default, JavaCC generates an
LL(1)parser. However, there may be portions of grammar that are notLL(1). JavaCC offers the capabilities of syntactic and semantic lookahead to resolve shift-shift ambiguities locally at these points. For example, the parser isLL(k)only at such points, but remainsLL(1)everywhere else for better performance. Shift-reduce and reduce-reduce conflicts are not an issue for top-down parsers. -
JavaCC generates parsers that are 100% pure Java, so there is no runtime dependency on JavaCC and no special porting effort required to run on different machine platforms.
-
JavaCC allows extended BNF specifications - such as
(A)*,(A)+etc - within the lexical and the grammar specifications. Extended BNF relieves the need for left-recursion to some extent. In fact, extended BNF is often easier to read as inA ::= y(x)*versusA ::= Ax|y. -
The lexical specifications (such as regular expressions, strings) and the grammar specifications (the BNF) are both written together in the same file. It makes grammars easier to read since it is possible to use regular expressions inline in the grammar specification, and also easier to maintain.
-
The lexical analyzer of JavaCC can handle full Unicode input, and lexical specifications may also include any Unicode character. This facilitates descriptions of language elements such as Java identifiers that allow certain Unicode characters (that are not ASCII), but not others.
-
JavaCC offers Lex-like lexical state and lexical action capabilities. Specific aspects in JavaCC that are superior to other tools are the first class status it offers concepts such as
TOKEN,MORE,SKIPand state changes. This allows cleaner specifications as well as better error and warning messages from JavaCC. -
Tokens that are defined as special tokens in the lexical specification are ignored during parsing, but these tokens are available for processing by the tools. A useful application of this is in the processing of comments.
-
Lexical specifications can define tokens not to be case-sensitive either at the global level for the entire lexical specification, or on an individual lexical specification basis.
-
JavaCC comes with JJTree, an extremely powerful tree building pre-processor.
-
JavaCC also includes JJDoc, a tool that converts grammar files to documentation files, optionally in HTML.
-
JavaCC offers many options to customize its behavior and the behavior of the generated parsers. Examples of such options are the kinds of Unicode processing to perform on the input stream, the number of tokens of ambiguity checking to perform etc.
-
JavaCC error reporting is among the best in parser generators. JavaCC generated parsers are able to clearly point out the location of parse errors with complete diagnostic information.
-
Using options
DEBUG_PARSER,DEBUG_LOOKAHEAD, andDEBUG_TOKEN_MANAGER, users can get in-depth analysis of the parsing and the token processing steps. -
The JavaCC release includes a wide range of examples including Java and HTML grammars. The examples, along with their documentation, are a great way to get acquainted with JavaCC.
Example
This 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
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() ] "}"
}
Output
$ java Example
{{}}<return>
$ 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)
$ 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
Follow the steps here to get started with JavaCC.
This guide will walk you through locally building the project, running an existing example, and setup to start developing and testing your own JavaCC application.
Download & Installation
JavaCC 7.0.10 is our latest stable release.
- JavaCC 7.0.10 - (Source (zip), Source (tar.gz), Binaries, Javadocs, Release Notes)
All JavaCC releases are available via GitHub and Maven including checksums and cryptographic signatures.
For all previous releases, please see stable releases.
The GitHub 8.0 branch contains the next generation of JavaCC that splits the frontend -- the JavaCC parser -- from the backends -- the code generator targeted for Java, C++ &and C# --. Status of JavaCC is experimental and not production ready.
Installation
To install JavaCC, navigate to the download directory and type:
$ unzip javacc-7.0.10.zip
or
$ tar xvf javacc-7.0.10.tar.gz
Then place the binary javacc-7.0.10.jar in a new target/ folder, and rename to javacc.jar.
Once you have completed installation add the scripts/ directory in the JavaCC installation 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.10/ directory:
chmod +x scripts/javacc
Building JavaCC from Source
The source contain the JavaCC, JJTree and JJDoc sources, launcher scripts, example grammars and documentation. It also contains a bootstrap version of JavaCC needed to build JavaCC.
Prerequisites for building JavaCC:
- Git
- Ant (we require version 1.5.3 or above - you can get ant from http://ant.apache.org)
- Maven
- Java 8 (Java 9 and 10 are not yet supported)
$ git clone https://github.com/javacc/javacc.git
$ cd javacc
$ ant
This will build the javacc.jar file in the target/ directory
Developing JavaCC
Minimal requirements for an IDE are:
- Support for Java
- Support for Maven with Java
IntelliJ IDEA
The IntelliJ IDE supports Maven out of the box and offers a plugin for JavaCC development.
- IntelliJ download: https://www.jetbrains.com/idea/
- IntelliJ JavaCC Plugin: https://plugins.jetbrains.com/plugin/11431-javacc/
Eclipse IDE
- Eclipse download: https://www.eclipse.org/ide/
- Eclipse JavaCC Plugin: https://marketplace.eclipse.org/content/javacc-eclipse-plug
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
- Dos Reis, Anthony J., Compiler Construction Using Java, JavaCC, and Yacc., Wiley-Blackwell 2012. ISBN 0-4709495-9-7 (book, pdf).
- Copeland, Tom, Generating Parsers with JavaCC., Centennial Books, 2007. ISBN 0-9762214-3-8 (book).
Tutorials
- JavaCC tutorials.
- Introduction to JavaCC by Theodore S. Norvell.
- Incorporating language processing into Java applications: a JavaCC tutorial by Viswanathan Kodaganallur.
Articles
- Looking for lex and yacc for Java? You don't know Jack by Chuck Mcmanis.
- Build your own languages with JavaCC by Oliver Enseling.
- Writing an Interpreter Using JavaCC by Anand Rajasekar.
- Building a lexical analyzer with JavaCC by Keyvan Akbary.
Parsing theory
- Alfred V. Aho, Monica S. Lam, Ravi Sethi and Jeffrey D. Ullman, Compilers: Principles, Techniques, and Tools, 2nd Edition, Addison-Wesley, 2006, ISBN 0-3211314-3-6 (book, pdf).
- Charles N. Fischer and Richard J. Leblanc, Jr., Crafting a Compiler with C., Pearson, 1991. ISBN 0-8053216-6-7 (book).
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.
500 Dec 18, 2022
874 Dec 15, 2022
4.5k Jan 8, 2023
153 Nov 17, 2022
25.1k Dec 31, 2022
73 Dec 13, 2022
13.6k Dec 28, 2022
41 Dec 18, 2022
6k Jan 8, 2023
62 Oct 13, 2022
324 Dec 31, 2022
469 Dec 30, 2022
46 Jan 3, 2023
4 Dec 30, 2021
7.5k Jan 8, 2023
4k Jan 6, 2023
442 Jan 3, 2023
11 Nov 14, 2022
4 Jan 13, 2022