This plugin provides a <$railroad> widget for generating railroad diagrams as SVG images.

Alternatively, the diagram notation can be stored in a dedicated tiddler with its type field set to text/vnd.tiddlywiki.railroad, and that tiddler can simply be transcluded to wherever it is needed.

The plugin is based on a library by Tab Atkins, and has been extended to make it more flexible, including allowing components of a diagram to function as links or be transcluded from other tiddlers.

The railroad widget uses a special notation to construct the components defined below.

x and y here stand for any component.

Names (as opposed to quoted strings) are available when a value starts with a letter and contains only letters, digits, underscores, dots and hyphens.

sequence

• A sequence of components
• The <- and -> delimiters allow you to force a single component to be treated as a sequence. This is occasionally useful for spacing a diagram out

examples

x y z			sequence

<-x y z->		explicit sequence

optional

• A component that can be omitted
• The colon makes x appear straight ahead

examples

[:x]			optional, normally included

[x]				optional, normally omitted

repeated

• A list of one or more x
• The + suffix adds y as a separator between each x and the next

examples

{x}				one or more

{x +","}		one or more, comma-separated

optional repeated

• An optional list of x, i.e. a list of zero or more x

examples

[{:x}]			zero or more, normally included

[{:x +","}]		zero or more, comma-separated, normally included

[{x}]			zero or more, normally omitted

[{x +","}]		zero or more, comma-separated, normally omitted

choice

• A set of alternatives
• The colon indicates which branch appears straight ahead. By default, it's the first branch

examples

(x|y|z)			alternatives

(x|:y|z)		alternatives, normally y

string / terminal

• A literal or terminal component
• This follows the normal TiddlyWiki rules for quoted strings

examples

"x"				terminal

nonterminal

• A nonterminal component, i.e. the name of another diagram

examples

<"x">			nonterminal

comment

• A comment

examples

/ "comment" /		comment

dummy

• The absence of a component

examples

-		dummy

link

• A link to the tiddler title or URI given by the string or name

examples

[[x|"tiddler"]]		link

transclusion

• Treats the content of another tiddler as diagram syntax and transcludes it into the current diagram

examples

{{"$:/plugins/tiddlywiki/railroad/example-transclusion"}}		transclusion

// "railroad transclusion example" text		<- text in the tidlder

arrow pragma

• Controls whether repeat paths have an arrow on them
• Can be toggled on and off in mid-diagram, if desired

examples

<$railroad text="""
\arrow yes
[{:x}]
"""/>

<$railroad text="""
\arrow no
[{:x}]
"""/>

debug pragma

• Causes the diagram to display its parse tree

examples

\debug
x

Root
  Nonterminal: x

start/end pragma

• Controls the style of the diagram's startpoint or endpoint

examples

\start none x

\start double 
\end double
 x