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
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
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
Diagram(
Terminal( 'My Terminal Text', '#link', 'My Terminal Text Title', 'custom-class1 custom-class2' )
)
Implicit Example
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
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
Diagram(
Comment( 'My Comment Text', '#link', 'My Comment Text Title', 'custom-class1 custom-class2' )
)
Skip
This leaf represents an empty line.
Skip()
Example
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
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
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
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
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
ComplexDiagram(
MultipleChoice(1, 'any', 'Vanilla', 'Chocolate', 'Strawberry')
)
all Example
ComplexDiagram(
MultipleChoice(1, 'all', 'Bacon', 'Lettuce', 'Tomato')
)
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
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
ComplexDiagram(
Optional('Add butter')
)
With skip Example
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
ComplexDiagram(
OneOrMore('Laugh')
)
With repeat Example
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
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
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
ComplexDiagram(
Group( Sequence( 'Salmon', 'Tuna', 'Flounder' ))
)
With a Bare String Label Example
ComplexDiagram(
Group(
Sequence( 'Pike', 'Kirk', 'Picard' ),
'Awesome Captains'
)
)
With a Comment Label Example
ComplexDiagram(
Group(
Sequence( 'A-wing', 'X-wing', 'TIE' ),
Comment('Starfighters', 'https://en.wikipedia.org/wiki/List_of_Star_Wars_starfighters', 'Star Wars starfighters')
)
)