Railroad Diagrams from EBNF

October 10, 2011

I am playing with a new query language. I am defining the grammar as EBNF, but I want to show railroad diagrams for those readers that are more graphical and less familiar with BNF. I’ve found limited support for generating syntax diagrams from EBNF.

I’ve found a few tools, some working better than others:

  • Ebnf2ps (Haskell). This is the only tool I have not been able to get to work. I seem to be missing AFM fonts in my TeX installation and I am not sure I want to spend time figuring out how to generate the AFM files.
  • SQLite bubble generator (Tk/Tcl). Strictly this tool does not consume EBNF grammars, but a custom DSL. If I didn't care about EBNF, this would be the best tool
  • node-ebnf-diagram (Javascript). Although it works, I have to issues with it. One is that it can only generate PNG files. That would not be too bad if it weren't for the second issue: the tool does not automatically resize the canvas, and it requires explicit width and height input. If I don't find anything else, I'll probably end up using it.
  • ebnf2ps.el (Emacs Lisp). It works as advertised. The only issue I found is that the diagrams generated have a small white gap on the lines on the right hand side.
  • ANTLRWorks (Java). Bundled with antlr, it fits the task. Once you are in the game of defining the grammar in Java, why not just go ahead and use the same tool to generate not only the parser but the diagrams? This is what the tool does. Even if you are not doing a Java parser/lexer, this is a good tool to use for documentation purposes.

I am using ANTLRWorks, generating all the diagrams from the command line as part of my markdown transform pipeline:

java -cp antlrworks-1.1.4.jar org.antlr.works.Console -f yql.g -o output/ -sd eps

It works very well.

blog comments powered by Disqus