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.

Note

When you get into 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 the Leaves and Containers appear or the exact way the path is drawn, you can try changing the order you have written the objects in your code.

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

ResultCode

Diagram('1')

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

ResultCode

ComplexDiagram('1')

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 element, giving it "hover text" and a description for screen-readers and other assistive technologies.
• class (optional) is additional classes to apply to the element. Terminal will also have the 'terminal' class added. If you add the class 'optional-path' here, a different color will be used for the background.

Explicit Example

ResultCode

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

Implicit Example

ResultCode

Diagram( '1' )

NonTerminal

This leaf represents an instruction or an object whose literal contents are defined in a separate Diagram or explanatory text.

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 element, giving it "hover text" and a description for screen-readers and other assistive technologies.
• class (optional) is additional classes to apply to the element. NonTerminal will also have the 'non-terminal' class added. If you add the class 'optional-path' here, a different color will be used for the background.

Example

ResultCode

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 element, giving it "hover text" and a description for screen-readers and other assistive technologies.
• class3 (optional) is additional classes to apply to the element. Comment will also have the 'comment' class added.

Example

ResultCode

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

Skip

This leaf represents an empty line.

Skip()

Example

ResultCode

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

ResultCode

ComplexDiagram(
  Sequence('1', '2', '3')
)

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

ResultCode

ComplexDiagram(
  Stack('1', '2', '3')
)

OptionalSequence

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

OptionalSequence(...children)

Example

ResultCode

ComplexDiagram(
  OptionalSequence('1', '2', '3')
)

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

ResultCode

ComplexDiagram(
  Choice(1, '1', '2', '3')
)

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

ResultCode

ComplexDiagram(
  MultipleChoice(1, 'any', '1', '2', '3')
)

all Example

ResultCode

ComplexDiagram(
  MultipleChoice(1, 'all', '1', '2', '3')
)

HorizontalChoice

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.

HorizontalChoice(...children)

Example

ResultCode

ComplexDiagram(
  HorizontalChoice('1', '2')
)

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

ResultCode

ComplexDiagram(
  Optional('1')
)

With skip Example

ResultCode

ComplexDiagram(
  Optional('1', '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

ResultCode

ComplexDiagram(
  OneOrMore('1')
)

With repeat Example

ResultCode

ComplexDiagram(
  OneOrMore('1', 'My Repeat Text')
)

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

ResultCode

ComplexDiagram(
  ZeroOrMore('1', 'My Repeat Text')
)

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

ResultCode

ComplexDiagram(
  AlternatingSequence('1', '2')
)

Group

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

Group(child, [ label ] )

Properties

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

Example

ResultCode

ComplexDiagram(
  Group('1', 'My Label' )
)