ebnf2railroad/README.md

EBNF to Railroad diagram

# EBNF 2 RailRoad

[![npm](https://badgen.now.sh/npm/v/ebnf2railroad?icon=npm)](http://npm.im/ebnf2railroad)
[![code style: prettier](https://badgen.now.sh/badge/code%20style/prettier/ff69b4)](https://github.com/prettier/prettier)
[![license](https://badgen.now.sh/github/license/matthijsgroen/ebnf2railroad)](https://github.com/matthijsgroen/ebnf2railroad)

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.

- EBNF `ebnf2railroad examples/ebnf.ebnf --title EBNF`
  [View html result online][example-ebnf] [View source](./examples/ebnf.ebnf)
- JSON `ebnf2railroad examples/json.ebnf --title JSON`
  [View html result online][example-json] [View source](./examples/json.ebnf)

### 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][example-optimizations] [View source](./examples/optimizations.ebnf)
[View markdown result](./examples/optimizations.md)

## Usage as module

```javascript
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](CONTRIBUTING.md)

## Acknowledgements

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

[example-ebnf]: https://htmlpreview.github.io/?https://github.com/matthijsgroen/ebnf2railroad/blob/master/examples/ebnf.html
[example-json]: https://htmlpreview.github.io/?https://github.com/matthijsgroen/ebnf2railroad/blob/master/examples/json.html
[example-optimizations]: https://htmlpreview.github.io/?https://github.com/matthijsgroen/ebnf2railroad/blob/master/examples/optimizations.html