Command Line Interface¶
Using PyRailroad¶
Usage: py-railroad [OPTIONS] COMMAND [ARGS]...
Options: --help
: shows the help message.
Commands:
dsl
: parses a DSL FILE for railroad diagrams, based on significant whitespace and writes it into TARGET file.json
: parses a JSON FILE for railroad diagrams and writes it into TARGET file.yaml
: parses a YAML FILE for railroad diagrams and writes it into TARGET file.ebnf
: parses a grammar FILE in EBNF format and writes all the definitions in separate files in the TARGET directory.
For both json
, yaml
and ebnf
, various parameters of the diagram engine can be specified in a PARAMETERS file. For dsl
, two additional options exist:
--simple
: draws the diagram using the "simple" style.--standalone
: embeds a default stylesheet inside the output for rendering.
Both styles are named so in the original code and haven't been changed (yet).
For ebnf
, there is another option:
--to-json
: writes the diagrams into JSON files instead of SVG files.
Examples:
Basic usage:
Generate a diagram using the simple style:
Generate a standalone diagram:
Basic usage (default parameters):
Usage with a parameters file:
Basic usage (default parameters):
Usage with a parameters file:
DSL support was initially developed by tabatkins in railroadparser.py and extended to support all the elements from railroad-diagrams that were missing. While complete in terms of elements, customization is limited to simple/complex styles and standalone or not. Several customizations of the diagram and of elements themselves are only available using the JSON or YAML parser.
Diagram syntax¶
Diagrams are written in files using one of DSL, JSON or YAML languages. In this section we'll go over the various elements that go in a diagram and the output obtained. Unless otherwise noted, the output show is done using the simple style and no other parameter changed.
There are three categories of elements:
EBNF Grammar¶
Unfortunately, there is too much to say and too many variants to explain. This program assumes that you know what you are doing if using EBNF as input.
If you wish to learn more, the Wikipedia article might be useful, as well as this article by Federico Tomassetti
This program will attempt to guess the correct EBNF grammar for you, but you might have to rewrite a few clauses/items, or in the worst case, dig into the code and submit a bug report or better yet, a pull request to add the missing grammar.