Text elements¶

Text elements are single elements on the diagram and the base building blocks. They are either Expression, Terminal, NonTerminal, Comment, Arrow or Skip.

Expression¶

An expression is either a sub-diagram for a bigger diagram (typically, a clause in a grammar, which will appear as non-terminal in another part of the grammar), or something that the EBNF parser couldn't handle on its own (and will need a little help rewriting).

For exemple, the W3C blindfold grammar for EBNF is specified as follows:

grammar ::= clause*                   # A grammar is zero or more clauses
clause  ::= clauseName "::=" pattern  # A clause associates a name with a pattern
pattern ::= branch ("|" branch)*      # A pattern has one or more branches (alternatives)
branch  ::= term+                     # A branch is one or more terms
term    ::=                           # A term is:  
            string                    #  a string in single or double quotes
          | charset                   #  a character set (as in perl: [a-z0-9], etc) 
          | "(" pattern ")"           #  a pattern, in parentheses 
          | clauseName                #  a clauseName, matching a pattern by name
          | term [*+?]                #  a term followed by a "*", "+", or "?" operator

There are five expressions in that grammar, and running py-railroad on it produces the following diagrams:

grammar

clause

pattern

branch

term

In the last expression, the last element is [*+?] because the parser treated it as a character range and couldn't tell whether it was a finite list of characters (a Choice) or an actual range (ie. "all characters from a to z").

Syntax¶

DSLJSONYAML

Basic syntax:

Expression: my text

With a href:

Expression "https://github.com": github

Basic syntax:

{
    "element": "Expression",
    "text": "my expression"
}

With href:

{
    "element": "Expression",
    "text": "github",
    "href": "https://github.com"
}

With additional options:

{
    "element": "Expression",
    "text": "github",
    "href": "https://github.com",
    "title": "This is a link",
    "cls": "custom_terminal"
}

Basic:

element: Expression
text: my expression

With href

element: Expression
text: github
href: https://github.com

With additional options:

element: Expression
text: github
href: https://github.com
title: This is a link
cls: custom_terminal

Properties¶

Output¶

Expression

Expression with href

Expression with additional options

Terminal¶

Terminal represents literal text. The Terminal element has a required property text, and three optional properties href, title and cls. The last two properties are only available with the JSON and YAML parsers.

Syntax¶

DSLJSONYAML

Basic syntax:

Terminal: my text

With a href:

Terminal"https://github.com": github

Basic syntax:

{
    "element": "Terminal",
    "text": "my text"
}

With href:

{
    "element": "Terminal",
    "text": "github",
    "href": "https://github.com"
}

With additional options:

{
    "element": "Terminal",
    "text": "github",
    "href": "https://github.com",
    "title": "This is a link",
    "cls": "custom_terminal"
}

Without a label:

element: Terminal
text: my text

With href

element: Terminal
text: github
href: https://github.com

With additional options:

element: Terminal
text: github
href: https://github.com
title: This is a link
cls: custom_terminal

Properties¶

text: string, required
href: string, optional
title: string, optional, only available with the JSON and YAML parsers
cls: string, optional, only available with the JSON and YAML parsers

Output¶

Simple Terminal

With href

With additional options (hover for the title)

NonTerminal¶

NonTerminal represents another production or diagram. The NonTerminal element has a required property text, and three optional properties href, title and cls. The last two properties are only available with the JSON and YAML parsers.

Syntax¶

DSLJSONYAML

Basic syntax:

NonTerminal: my text

With a href:

NonTerminal "https://github.com": github

Basic syntax:

{
    "element": "NonTerminal",
    "text": "my text"
}

With href:

{
    "element": "NonTerminal",
    "text": "github",
    "href": "https://github.com"
}

With additional options:

{
    "element": "NonTerminal",
    "text": "github",
    "href": "https://github.com",
    "title": "This is a link",
    "cls": "custom_terminal"
}

Without a label:

element: NonTerminal
text: my text

With href

element: NonTerminal
text: github
href: https://github.com

With additional options:

element: NonTerminal
text: github
href: https://github.com
title: This is a link
cls: custom_terminal

Properties¶

text: string, required
href: string, optional
title: string, optional, only available with the JSON and YAML parsers
cls: string, optional, only available with the JSON and YAML parsers

Output¶

Simple Terminal

With href

With additional options (hover for the title)

Comment¶

Represents a comment. The Comment element has a required property text, and three optional properties href, title and cls. The last two properties are only available with the JSON and YAML parsers.

Syntax¶

DSLJSONYAML

Basic syntax:

Comment: my text

With a href:

Comment "https://github.com": github

Basic syntax:

{
    "element": "Comment",
    "text": "my text"
}

With href:

{
    "element": "Comment",
    "text": "github",
    "href": "https://github.com"
}

With additional options:

{
    "element": "Comment",
    "text": "github",
    "href": "https://github.com",
    "title": "This is a link",
    "cls": "custom_terminal"
}

Without a label:

element: Comment
text: my text

With href

element: Comment
text: github
href: https://github.com

With additional options:

element: Comment
text: github
href: https://github.com
title: This is a link
cls: custom_terminal

Properties¶

text: string, required
href: string, optional
title: string, optional, only available with the JSON and YAML parsers
cls: string, optional, only available with the JSON and YAML parsers

Output¶

Simple Comment

With href

With additional options (hover for the title)

Arrow¶

Syntax¶

DSLJSONYAML

Arrow right:

Arrow:

With a direction:

Arrow: left|right

Undirected:

Arrow: undirected

Arrow right:

{
    "element": "Arrow"
}

With a direction:

{
    "element": "Arrow",
    "direction": "left|right"
}

Undirected (draws a line):

{
    "element": "Arrow",
    "direction": "undirected"
}

Arrow right:

element: Arrow

With a direction:

element: Arrow
direction: left|right

Undirected:

element: Arrow
direction: undirected

Properties¶

direction: optional string, can be left or right to orient the arrow left or right, or any other string to draw a plain line instead.

Output¶

Arrow left

Arrow right

Undirected: a line

Skip¶

An empty line. Used for vertical blocks like Stack.

Syntax¶

DSLJSONYAML

Basic syntax:

Skip:

Basic syntax:

{
    "element": "Skip"
}

Basic syntax:

element: Skip

Properties¶

This element has no properties.

Output¶

Stack without Skip

Stack with Skip