Skip to content

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:

py-railroad dsl diagram_source.dsl diagram_output.svg

Generate a diagram using the simple style:

py-railroad dsl diagram_source.dsl diagram_output.svg --simple

Generate a standalone diagram:

py-railroad dsl diagram_source.dsl diagram_output.svg --standalone

Basic usage (default parameters):

py-railroad json diagram_source.json diagram_output.svg

Usage with a parameters file:

py-railroad json diagram_source.json diagram_output.svg custom_parameters.json

Basic usage (default parameters):

py-railroad yaml diagram_source.json diagram_output.svg

Usage with a parameters file:

py-railroad yaml diagram_source.yaml diagram_output.svg my_parameters.yaml

Basic usage:

py-railroad ebnf grammar.ebnf output_dir

Usage with a parameters file:

py-railroad ebnf grammar.ebnf output_dir my_parameters.json

Usage with a parameters file, write JSON files instead of SVG:

py-railroad ebnf --to-json grammar.ebnf output_dir my_parameters.json

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.