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 addsy
as a separator between eachx
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 morex
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