Skip to content

matthijsgroen/ebnf2railroad

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

EBNF 2 RailRoad

npm code style: prettier license

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
  • Table of contents indicating root elements, character sets, common elements and recursion
  • Generation of large overview diagrams for root elements

Installation

npm install -g ebnf2railroad

Usage from command line

Usage: ebnf2railroad [options] <file>

Converts an ISO/IEC 14977 EBNF file to a HTML/Markdown 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-overview-diagram  skip creating overview diagrams for root elements
  --no-diagram-wrap      does not wrap diagrams for width minimization
  --no-text-formatting   does not format the output text version (becomes single line)
  --dump-ast             dump EBNF file AST to target destination for further processing
  --read-ast             input file is in the AST format
  -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.

Optimizations

The following optimizations are applied:

  • Ungrouping of groups that do not affect meaning of syntax
  • Untangling of nested choice elements
  • Duplicate choices are removed
  • Pretty printing of original syntax, with wrapping, column alignment

View html result online View source View markdown result

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