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.


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


Clapham can output:


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
  clapham [ options ] filename

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


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:

TERM       ::= FACTOR+
             | LITERAL

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

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.


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:

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.



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 $