Instructions

The Railroad Diagram Code is a series of nested objects whose properties are the components of the diagram. The name of the object determines how its properties will be used. The root object is either Diagram or ComplexDiagram. Any Leaf or Container object can be used inside either root object.

Diagram Complexity

When you use the more advanced Objects, you will note that you do not have much control over the specifics of how the paths are drawn in the diagram. If you want to change the order that the Leaves and Containers appear or the exact way the path is drawn, you can try changing the order that you have placed the Objects in your code.

The concept of a Straight or Happy Path

Because larger Diagrams are complex and can be visually confusing, a rule of thumb to assist your viewers is to keep the straight, or "happy", path the one that will be followed most frequently. Paths that are infrequent options or are for error handling are best shown as alternate paths to the side of the main path.

Root Diagrams

These objects are the two objects that can be used to start a diagram.

Diagram

This is one of the two root objects. It is identical to ComplexDiagram except that it has slightly different start/end shapes, in the same manner that JSON.org uses to distinguish between "leaf" types like number (Diagram) and "container" types like Array (ComplexDiagram). It can also be used to distinguish between diagrams that contain references to other Diagrams (ComplexDiagram) or a diagram that has no references to other diagrams (Diagram).

Diagram(...children)

Example

ImageTextCode

Diagram('Text')

ComplexDiagram

This is one of the two root objects. It is identical to Diagram except that it has slightly different start/end shapes, in the same manner that JSON.org uses to distinguish between "leaf" types like number (Diagram) and "container" types like Array (ComplexDiagram). It can also be used to distinguish between diagrams that contain references to other Diagrams (ComplexDiagram) or a diagram that has no references to other diagrams (Diagram).

ComplexDiagram(...children)

Example

ImageTextCode

ComplexDiagram('Text')

Components

Components are either leaves or containers. They hold both the text that is displayed and define the specifics of how the text is to be displayed.

Leaves

As used by this Railroad Diagram Generator, a Leaf is an Object that holds the final displayed text.

Terminal

This leaf represents literal text.

It can either be explicitly coded: Terminal( text, [ href, title, class ] ) or implicitly coded by using a bare string.

Properties

• text is the character string to be displayed in the leaf.
• href (optional) makes the text a hyperlink with the given URL.
• title (optional) adds an SVG <title> element to the leaf, giving it "hover text" and a description for screen-readers and other assistive technologies.
• class (optional) is for applying additional classes to the leaf. For example, if you add the class 'optional-path', a different color will be used for the background. See the Cascading Style Sheets page explaining the four provided classes.

Explicit Example

ImageTextCode

Diagram(
  Terminal( 'My Terminal Text', '#link', 'My Terminal Text Title', 'custom-class1 custom-class2' )
)

Implicit Example

ImageTextCode

Diagram( 'My Terminal Text' )

NonTerminal

This leaf represents an instruction or an object whose literal contents are defined in a separate Diagram, explanatory text, or is considered to be well understood by the viewer.

NonTerminal( text, [ href, title, class ] )

Properties

• text is the character string to be displayed in the leaf.
• href (optional) makes the text a hyperlink with the given URL.
• title (optional) adds an SVG <title> element to the leaf, giving it "hover text" and a description for screen-readers and other assistive technologies.
• class (optional) is for applying additional classes to the leaf. For example, if you add the class 'optional-path', a different color will be used for the background. See the Cascading Style Sheets page explaining the four provided classes.

Example

ImageTextCode

Diagram(
  NonTerminal( 'My NonTerminal Text', '#link', 'My NonTerminal Text Title', 'custom-class1 custom-class2' )
)

Comment

This leaf represents a comment.

Comment( text, [ href, title, class ] )

Properties

• text is the character string to be displayed in the leaf.
• href (optional) makes the text a hyperlink with the given URL.
• title (optional) adds an SVG <title> element to the leaf, giving it "hover text" and a description for screen-readers and other assistive technologies.
• class (optional) is for applying additional classes to the leaf.

Example

ImageTextCode

Diagram(
  Comment( 'My Comment Text', '#link', 'My Comment Text Title', 'custom-class1 custom-class2' )
)

Skip

This leaf represents an empty line.

Skip()

Example

ImageTextCode

Diagram(
  Skip()
)

Containers

As used by this Railroad Diagram Generator, a Container is an Object that is used to hold the Leaves and display them according to the rules of the specified Container.

Sequence

This container represents a simple series of objects.

Sequence(...children)

Example

ImageTextCode

ComplexDiagram(
  Sequence('Apple', 'Orange', 'Pear')
)

Stack

This container is identical to a Sequence, but the items are stacked vertically rather than horizontally. Best used when a simple Sequence would be too wide; instead, you can break the items up into a Stack of Sequences of an appropriate width.

Stack(...children)

Example

ImageTextCode

ComplexDiagram(
  Stack('Honda', 'Ford', 'Duesenberg')
)

OptionalSequence

This container is a Sequence where every item is individually optional, but at least one item must be chosen.

OptionalSequence(...children)

Example

ImageTextCode

ComplexDiagram(
  OptionalSequence('Earth', 'Venus', 'Mars')
)

Choice

This container represents when one of the children must be chosen.

Choice(index, ...children)

Properties

• index specifies which child is the "normal" choice and should go in the middle. It is Zero based.

Example

ImageTextCode

ComplexDiagram(
  Choice(1, 'Mickey', 'Donald', 'Goofy')
)

MultipleChoice

This container represents when one or more of the children must be chosen.

MultipleChoice(index, type, ...children)

Properties

• index specifies which child is the "normal" choice and should go in the middle. It is Zero based.
• type must be either "any" (1+ branches can be taken) or "all" (all branches must be taken).

any Example

ImageTextCode

ComplexDiagram(
  MultipleChoice(1, 'any', 'Vanilla', 'Chocolate', 'Strawberry')
)

all Example

ImageTextCode

</ditextareav></p> </div> <div class="tabbed-block"> <div class="highlight"><pre><span></span><code><span class="no">ComplexDiagram</span><span class="p">(</span> <span class="w"> </span><span class="no">MultipleChoice</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="s1">'all'</span><span class="p">,</span><span class="w"> </span><span class="s1">'Bacon'</span><span class="p">,</span><span class="w"> </span><span class="s1">'Lettuce'</span><span class="p">,</span><span class="w"> </span><span class="s1">'Tomato'</span><span class="p">)</span> <span class="p">)</span> </code></pre></div> </div> </div> </div> </div> <h4 id="horizontalchoice">HorizontalChoice</h4> <p>This container is identical to Choice, but the items are stacked horizontally rather than vertically. There's no "straight-line" choice, so it just takes a list of children. Best used when a simple Choice would be too tall; instead, you can break up the items into a HorizontalChoice of Choices of an appropriate height.</p> <p><code>HorizontalChoice(...children)</code></p> <div class="admonition example"> <p class="admonition-title">Example</p> <div class="tabbed-set tabbed-alternate" data-tabs="14:3"><input checked="checked" id="__tabbed_14_1" name="__tabbed_14" type="radio" /><input id="__tabbed_14_2" name="__tabbed_14" type="radio" /><input id="__tabbed_14_3" name="__tabbed_14" type="radio" /><div class="tabbed-labels"><label for="__tabbed_14_1">Image</label><label for="__tabbed_14_2">Text</label><label for="__tabbed_14_3">Code</label></div> <div class="tabbed-content"> <div class="tabbed-block"> <p><div id="rr-horizontalchoice"></div></p> </div> <div class="tabbed-block"> <p><textarea id="text-horizontalchoice" class="instructions-textarea" readonly>

ComplexDiagram(
  HorizontalChoice('Grilled', 'Fried')
)

Optional

This container is a shorthand for Choice(1, Skip(), child).

Optional(child, [ skip ] )

Properties

• skip (optional) specifies if child is put in the straight-line path. If it is set to 'skip', then the child is not placed in the straight-line path.

Without skip Example

ImageTextCode

ComplexDiagram(
  Optional('Add butter')
)

With skip Example

ImageTextCode

ComplexDiagram(
  Optional('Hold the onions', 'skip')
)

OneOrMore

This container represents when the children can be repeated one or more times.

OneOrMore(child, [ repeat ] )

Properties

• repeat (optional) specifies something that must go between the repetitions (usually a Comment, but sometimes things like ",", etc.).

Without repeat Example

ImageTextCode

ComplexDiagram(
  OneOrMore('Laugh')
)

With repeat Example

ImageTextCode

ComplexDiagram(
  OneOrMore('Laugh', 'Smile')
)

ZeroOrMore

This container is shorthand for Optional(OneOrMore(child, repeat), skip), this represents when the children can be repeated one or more times.

ZeroOrMore(child, [ repeat, skip ] )

Properties

• repeat (optional) specifies something that must go between the repetitions (usually a Comment, but sometimes things like ",", etc.). This is the same as in OneOrMore.
• skip (optional) specifies if child is put in the straight-line path. If it is set to 'skip', then the child is not placed in the straight-line path. This is the same as in Optional.

Example

ImageTextCode

ComplexDiagram(
  ZeroOrMore('Growl', 'Bark')
)

AlternatingSequence

This container is similar to OneOrMore, where you must alternate between the two choices, but allows you to start and end with either element. OneOrMore requires you to start and end with the "child" node.

AlternatingSequence(option1, option2)

Example

ImageTextCode

ComplexDiagram(
  AlternatingSequence('Tisket', 'Tasket')
)

Group

This container highlights its child with a dashed outline, and optionally labels it.

Group(child, [ label ] )

Properties

• label (optional) constructs a Comment Leaf if it is a bare string, or you can build a Comment leaf yourself (to give an href, title or class).

Without a Label Example

ImageCode

ComplexDiagram(
  Group( Sequence( 'Salmon', 'Tuna', 'Flounder' ))
)

With a Bare String Label Example

ImageCode

ComplexDiagram(
  Group( 
    Sequence( 'Pike', 'Kirk', 'Picard' ), 
    'Awesome Captains'
  )
)

With a Comment Label Example

ImageCode

ComplexDiagram(
  Group(
    Sequence( 'A-wing', 'X-wing', 'TIE' ), 
    Comment('Starfighters', 'https://en.wikipedia.org/wiki/List_of_Star_Wars_starfighters', 'Star Wars starfighters')
  )
)