EBNF 2 RailRoad

A command line tool to create great documentation including railroad diagrams based on the ISO/IEC 14977 specification

Features

Creates optimized visual syntax diagrams based on the EBNF syntax
Quick navigation using references of used declarations
Nice comment markup using markdown
Validates if document is complete and has no duplicate declarations
Shows pretty printed text syntax in the document
Pretty printing of the sourcefile

Installation

npm install -g ebnf2railroad

Usage from command line

Usage: ebnf2railroad [options] <file>

Converts an ISO/IEC 14977 EBNF file to a HTML file with SVG railroad diagrams

Options:
  -V, --version          output the version number
  -q, --quiet            suppress output to STDOUT
  -o, --target [target]  output the file to target destination.
  --no-target            skip writing output HTML
  -t, --title [title]    title to use for HTML document
  --lint                 exit with status code 2 if EBNF document has warnings
  --write-style          rewrites the source document with styled text
  --no-optimizations     does not try to optimize the diagrams
  --no-text-formatting   does not format the output text version (becomes single line)
  -h, --help             output usage information

Examples

To generate HTML documentation of the EBNF file:

ebnf2railroad --title 'My Title' inputfile.ebnf -o outputfile.html

To only verify the EBNF file:

ebnf2railroad --lint inputfile.ebnf --no-target

To prettify the source EBNF file:

ebnf2railroad --write-style inputfile.ebnf --no-target

Online examples

Check the examples folder for an example input file and the generated result page.

EBNF ebnf2railroad examples/ebnf.ebnf --title EBNF View online
JSON ebnf2railroad examples/json.ebnf --title JSON View online

Usage as module

const { parseEbnf, createDocumentation } = require("ebnf2railroad");

const ebnf = "definition = 'a', other, { other } | item, 'b';";
const ast = parseEbnf(ebnf); // can throw parse error exceptions
const htmlOutput = createDocumentation(ast);

Licence

The code is licensed under MIT (see LICENSE file).

Contributing

Thanks for your interest in contributing! There are many ways to contribute to this project. Get started here

Acknowledgements

All railroad diagrams are generated through: https://github.com/tabatkins/railroad-diagrams
The EBNF parser is generated by http://zaa.ch/jison/
All markdown is parsed with http://showdownjs.com/

agladysh / ebnf2railroad