https://github.com/lukaslueg/railroad_dsl

A small DSL to generate syntax diagrams
https://github.com/lukaslueg/railroad_dsl

Last synced: about 2 months ago
JSON representation

A small DSL to generate syntax diagrams

• Host: GitHub
• URL: https://github.com/lukaslueg/railroad_dsl
• Owner: lukaslueg
• License: mit
• Created: 2018-08-12T15:36:26.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2024-07-26T19:13:01.000Z (about 2 months ago)
• Last Synced: 2024-07-26T20:57:06.187Z (about 2 months ago)
• Language: Rust
• Size: 512 KB
• Stars: 32
• Watchers: 5
• Forks: 7
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-starred - lukaslueg/railroad_dsl - A small DSL to generate syntax diagrams (others)

README

        
A small DSL to generate syntax diagrams using [this library](https://github.com/lukaslueg/railroad).

[![Crates.io Version](https://img.shields.io/crates/v/railroad_dsl.svg)](https://crates.io/crates/railroad_dsl)

[![Build status](https://github.com/lukaslueg/railroad_dsl/actions/workflows/check.yml/badge.svg)](https://github.com/lukaslueg/railroad_dsl/actions/workflows/check.yml)

* `{...}` is a horizontal stack of connected elements

* `[...]` is a vertical sequence of connected elements

* `<...>` is a choice of multiple options, exactly one of which has to be picked

* `"foobar"` is a terminal

* `'foobar'` is a non-terminal

* `` `foobar` `` is a comment

* `...?` is an optional element

* `...*...` is a repeated element

* `!` is the empty element

Quotes (and backslashes) can be escaped using backslashes.

For example:

```raw

{["CONSTRAINT" "name"]?,

 <["PRIMARY" "KEY"  'conflict-clause' ],

  ["NOT" "NULL" 'conflict-clause'],

  ["UNIQUE" 'conflict-clause'],

  ["CHECK" "(" 'expr' ")"],

  ["DEFAULT" <'signed-number', 'literal-value', ["(" 'expr' ")"]>],

  ["COLLATE" "collation-name"],

  'foreign-key-clause'>}

```

![diagram for constraint syntax](https://raw.githubusercontent.com/lukaslueg/railroad_dsl/master/examples/column_constraint.jpeg)

```raw

{[`create-table-stmt` "CREATE" #`Table will be dropped when connection closes`> "TABLE"],

 [[["IF" "NOT" "EXISTS"]#`If table exists, do nothing`]? [[["schema-name" "."]#`...in a foreign database`]? "table-name"]#`The table's name`],

 [<["(" ['column-def'*","]#`One or more column-definitions` [!*[['table-constraint' ","]#`primary key and stuff`]]#`Zero or more table-constraints` ")" ],

   ["AS" 'select-stmt']#`Create table definition and content directly from a query`>]}

```

![diagram for create-table syntax](https://raw.githubusercontent.com/lukaslueg/railroad_dsl/master/examples/create_table_stmt.jpeg)

Run `cargo run --example example_diagrams` for more examples.

---

```raw

A small DSL to generate syntax-diagrams.

If no input files are given, act as a pipe from stdin to stdout. Otherwise, process each input file into an output file with the file extension replaced

Usage: railroad [OPTIONS] [INPUTS]...

Arguments:

  [INPUTS]...

          

Options:

      --css 

          Alternative CSS file

      --format 

          Output format

          

          [default: svg]

          [possible values: svg, png]

      --max-width 

          Maximum width of the final image

      --max-height 

          Maximum height of the final image

      --theme 

          Theme to use

          

          [default: light]

          [possible values: light, dark]

  -h, --help

          Print help (see a summary with '-h')

  -V, --version

          Print version

```