Clapham

Clapham is an open-source railroad diagram generator.

Railroad diagrams are a graphical way of representing the grammar of a computer language. When a computer language is large, even people who use the language day-to-day have trouble remembering its nuances. A railroad diagram represents the grammar visually, and is easier to understand by non- or semi-technical users.

For example, the following charts explain the syntax of a column definition in the dialect of SQL implemented by the LucidDB database engine:

Railroad charts are time-consuming to create and maintain by hand, and most computer languages generate a parser from a grammar using a parser generator, so it makes sense to automate creation. That is what Clapham does.

How Clapham works

Clapham is a batch program. It has an input file, a few options, and generates output files.

Input

The main input to Clapham is a definition of the grammar. Clapham supports two meta-grammars (languages for specifying grammars):

• Wirth Syntax Notation (WSN)
• Extended Backus-Naur Form (BNF)

Output

Clapham can output:

• Railroad diagrams in PNG format
• Railroad diagrams in SVG format
• An HTML page, index.html, containing a table of all symbols

Options

There aren't many options right now. It does what it does. See the roadmap for some preferences we'd like to add.

Command line

Clapham is a Java program that you invoke from the command line. For example, if you invoke it like this:

java net.hydromatic.clapham.Clapham -d grammar grammar.bnf

it will read grammar.bnf and generate a symbol.png and symbol.svg for each symbol in the grammar file. It will generate those files, and an HTML index file index.html, to the grammar directory.

The --help option prints the command line options:

Clapham - Railroad diagram generator
Usage:
  clapham [ options ] filename

Options:
  --help       Print this help
  -d directory Specify output directory
  filename     Name of file containing grammar

Examples

Example #1: Wirth Syntax Notation (WSN)

Clapham generated railroad diagrams for the Wirth Syntax Notation. This is one of the two grammar notations accepted by Clapham, so Clapham is essentially documenting itself.

The grammar wirth.bnf is as follows:

SYNTAX     ::= ( PRODUCTION )*
PRODUCTION ::= IDENTIFIER <EQUALS> EXPRESSION "."
EXPRESSION ::= TERM ( <BAR> TERM )*
TERM       ::= FACTOR+
FACTOR     ::= IDENTIFIER
             | LITERAL
             | <LBRACKET> EXPRESSION <RBRACKET>
             | <LPAREN> EXPRESSION <RPAREN>
             | <LBRACE> EXPRESSION <RBRACE>
IDENTIFIER ::= <LETTER>
LITERAL    ::= <QUOT> <CHARACTER>+ <QUOT>

Use Clapham's command line tool to generate the diagrams:

CP=
for i in lib/*.jar; do CP=$CP:$i; done
java -cp $CP net.hydromatic.clapham.Clapham -d wirth testsrc/net/hydromatic/clapham/example/wirth.bnf

The following diagrams are generated:

Each syntax chart is a PNG file, but you can click through to an image in SVG format.

Example #2. LucidDB SQL grammar

LucidDB is an open-source database released by the Eigenbase Foundation. Its SQL grammar is specified in JavaCC. Clapham does not read JavaCC grammar files (yet), but JavaCC has a utility jjdoc that generates a web page in BNF, and Clapham can read that.

Here are some of the charts generated.  The full set is here.

Roadmap

Clapham is alpha. It does most of the things that it should, but not particularly well, and there are bugs. In short, it needs work. (Contributions welcome!)

Here are some of the things we'd like to make it do:

• Read JavaCC as an input format.
• Generate a text file for each chart, containing the rules on that chart in BNF or other meta-grammar. This could be displayed alongside the chart to aid searchability.
• Generate HTML <map> and <area> elements for each chart. This allows symbols in a chart to act as hyperlinks, and other effects such as text boxes on mouseover.
• Combine multiple charts into one.
• Chart definition file. As the number options available for each chart increases, it will not be possible to specify them all on the command line. We cannot add extra content to the grammar file, so we need to store the extra information in an auxiliary file. (The current workaround to this problem is to store the information in code. See how net.hydromatic.clapham.example.WirthExample loads a grammar, sets some preferences, then generates each chart individually.)
• Specify that certain symbols should be inlined. Grammar authors sometimes create symbols to make the grammar maintainable, or to resolve conflicts in the grammar, but these symbols are meaningless to the end-user. For example, the Farrago SQL grammar would be more readable if GroupOpt and HavingOpt were expanded inline in the SqlSelect chart.
• Allow symbols to have spaces and other punctuation in their name. (This may already be possible, but I haven't tested it.)
• Fine-tune the layout of the charts. The title of the chart should be optional. Text isn't always properly aligned, or isn't always the right size for the box. And so forth.
• Wrap large charts over multiple lines.
• Preferences for chart layout. Whether to wrap a particular chart, and if so, where to wrap. Which chart optimizations to perform, specified globally, but can be overridden for a particular chart.

Getting started

1. Download the source distribution from SourceForge, and unzip. (Or to get the latest, use svn and checkout trunk.)
2. Install JDK 1.6.0 or later, and ant 1.7.0 or later.
3. To build, type 'ant jar' in the root directory of the source distribution.
4. Run the wirth.bnf example described above.
5. Write your own grammar, and try Clapham on that.

Resources

• Home page
• Clapham project at SourceForge.net
• If you have comments or questions, post to the Open Discussion forum.
• Julian's blog
• API javadoc

Acknowledgements

I was inspired by EBNF Visualizer, written by Stefan Schoergenhumer and Markus Dopler supported by Hanspeter Moessenboeck, University of Linz, but I wanted a tool that ran in batch mode. I used some of their code for the graph package, and had fun translating it from C# to Java.

Clapham Railroad Diagram Generator
Copyright (C) 2009-2009 Julian Hyde
$Id: index.html 3 2009-05-11 08:11:57Z jhyde $