Name
cx:railroad — Draws railroad diagrams.
Synopsis
The cx:railroad step generates railroad diagrams with
Gunther Rademacher’s
Railroad Diagram Generator.
| Input port | Primary | Sequence | Content types |
|---|---|---|---|
| source | ✔ | text |
| Output port | Primary | Sequence | Content types |
|---|---|---|---|
| result | ✔ | ✔ | image/svg+xml |
| html | html |
| Option name | Type | Default value |
|---|---|---|
| color | xs:string? | '#FFDB4D' |
| color-offset | xs:integer | 0 |
| eliminate-recursion | xs:boolean | true() |
| factoring | xs:boolean | true() |
| inline-literals | xs:boolean | true() |
| keep-epsilon-nonterminals | xs:boolean | true() |
| nonterminal | xs:string? | () |
| padding | xs:integer? | () |
| stroke-width | xs:integer? | () |
| transform-links | XPathExpression | "'#' || $p:nonterminal" |
| width | xs:integer | 992 |
Declaration
1 |<p:declare-step xmlns:p="http://www.w3.org/ns/xproc">
| <p:input port="source" content-types="text"/>
| <p:output port="result"
| content-types="image/svg+xml"
5 | primary="true"
| sequence="true"/>
| <p:output port="html" content-types="html"/>
| <p:option name="nonterminal" as="xs:string?"/>
| <p:option xmlns:e="http://www.w3.org/1999/XSL/Spec/ElementSyntax"
10 | name="transform-links"
| as="xs:string"
| e:type="XPathExpression"
| select=""'#' || $p:nonterminal""/>
| <p:option name="color" as="xs:string?" select="'#FFDB4D'"/>
15 | <p:option name="color-offset" as="xs:integer" select="0"/>
| <p:option name="padding" as="xs:integer?"/>
| <p:option name="stroke-width" as="xs:integer?"/>
| <p:option name="width" as="xs:integer" select="992"/>
| <p:option name="eliminate-recursion" as="xs:boolean" select="true()"/>
20 | <p:option name="factoring" as="xs:boolean" select="true()"/>
| <p:option name="inline-literals" as="xs:boolean" select="true()"/>
| <p:option name="keep-epsilon-nonterminals" as="xs:boolean" select="true()"/>
|</p:declare-step>Errors
| Code | Description |
|---|---|
cxerr:XC0007 | It
is a dynamic error (cxerr:XC0007) if the color offset is not a value
between 0 and 359. |
cxerr:XC0008 | It
is a dynamic error (cxerr:XC0008) if the color value is not one of the named
colors or a valid hex RGB color specification. |
cxerr:XC0010 | It is a dynamic
error (cxerr:XC0010) if the specified nonterminal does not appear in the
grammar. |
cxerr:XC0011 | It
is a dynamic error (cxerr:XC0011) if the width is less than or equal to 0. |
Description
Railroad diagrams are a way to visually represent grammars. See the section called “Example”.
The Railroad Daigram Generator produces a single XHTML page containing all
of the diagrams; this appears on the html port. The
cx:railroad step also extracts each individual SVG diagram;
these appear on the result port.
The nonterminal option allows you to select a single SVG
diagram from a grammar. It is a dynamic
error (cxerr:XC0010) if the specified nonterminal does not appear in the
grammar. It is also possible to filter the diagrams with their document
properties, see the section called “Document properties”.
The transform-links option controls how cross reference
links are transformed in the individual SVG diagrams. It is an XPath expression.
On each link element, the transform-links expression will be
evaluated with the linked nonterminal in the $p:nonterminal
attribute. The result of the expression is used in the link.
The default value leaves the links unchanged, but you could add a prefix or
a suffix. For example, "'#pfx-' || $p:nonterminal" would transform
the link #name into #pfx-name. Setting
the transform-links option to the empty string removes the
links entirely.
The other step options correspond directly to the options on the generator.
The color must be one of the standard Java AWT color names (black, blue,
cyan, darkGray, gray, green, lightGray, magenta, orange, pink, red, white, or
yellow) or an RGB color of the form “#RRGGBB”.
It
is a dynamic error (cxerr:XC0008) if the color value is not one of the named
colors or a valid hex RGB color specification.
The color-offset is a direction in the hue-saturation-lightness
color space used to make the element colors distinct.
It
is a dynamic error (cxerr:XC0007) if the color offset is not a value
between 0 and 359.
It
is a dynamic error (cxerr:XC0011) if the width is less than or equal to 0.
XML Calabash is built with version 2.1 of the railroad diagram generator.
Document properties
For each diagram, additional metadata is provided in the document properties: The name of the production, its EBNF summary, and the list of other productions that reference it.
Example 2, “Document properties for the Number diagram” shows an example of the document properties.
Example
A simple grammar like the one shown in Example 1, “Example railroad source” has three productions. They can be rendered as shown in Figure 1, “The Expression production”, Figure 2, “The Number production”, and Figure 3, “The op production”.
Expression ::= Number op Number | "(" Expression ")"
Number ::= [0-9]+
op ::= "+" | "-" | "×" | "÷"
{
"cx:referenced-by": [ "Expression" ],
"cx:nonterminal": "Number",
"content-type": "image/svg+xml",
"base-uri": "file://…/railroad-002.xpl",
"cx:ebnf": <div xmlns="http://www.w3.org/1999/xhtml" class="ebnf"><code>…</code>…</div>
}