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.
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:
index.html, containing a table of all symbols
There aren't many options right now. It does what it does. See the roadmap for some preferences we'd like to add.
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.svg for each symbol in the grammar file. It will
generate those files, and an HTML index file
index.html, to 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
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.
wirth.bnf is as follows:
SYNTAX ::= ( PRODUCTION )*
PRODUCTION ::= IDENTIFIER <EQUALS> EXPRESSION "."
EXPRESSION ::= TERM ( <BAR> TERM )*
TERM ::= FACTOR+
FACTOR ::= IDENTIFIER
| <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:
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.
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:
net.hydromatic.clapham.example.WirthExampleloads a grammar, sets some preferences, then generates each chart individually.)
HavingOptwere expanded inline in the
ant jar' in the root directory of the source distribution.
wirth.bnfexample described above.
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 $