https://github.com/matthijsgroen/ebnf2railroad
📔 Create beautiful documentation for EBNF
https://github.com/matthijsgroen/ebnf2railroad
ebnf railroad-diagrams
Last synced: 3 months ago
JSON representation
📔 Create beautiful documentation for EBNF
- Host: GitHub
- URL: https://github.com/matthijsgroen/ebnf2railroad
- Owner: matthijsgroen
- License: mit
- Created: 2018-10-27T18:17:19.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-11-26T11:43:47.000Z (8 months ago)
- Last Synced: 2025-03-29T17:06:51.737Z (4 months ago)
- Topics: ebnf, railroad-diagrams
- Language: JavaScript
- Homepage: https://matthijsgroen.github.io/ebnf2railroad/
- Size: 2.12 MB
- Stars: 63
- Watchers: 3
- Forks: 10
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# EBNF 2 RailRoad
[](http://npm.im/ebnf2railroad)
[](https://github.com/prettier/prettier)
[](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]
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