Name

cx:railroad — Draws railroad diagrams.

Synopsis

The cx:railroad step generates railroad diagrams with Gunther Rademacher’s Railroad Diagram Generator.

Input portPrimarySequenceContent types
source✔  text 
Output portPrimarySequenceContent types
result✔ ✔ image/svg+xml 
html  html 
Option nameTypeDefault value
colorxs:string?'#FFDB4D'
color-offsetxs:integer0
eliminate-recursionxs:booleantrue()
factoringxs:booleantrue()
inline-literalsxs:booleantrue()
keep-epsilon-nonterminalsxs:booleantrue()
nonterminalxs:string?()
paddingxs:integer?()
stroke-widthxs:integer?()
transform-linksXPathExpression"'#' || $p:nonterminal"
widthxs:integer992
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="&#34;'#' || $p:nonterminal&#34;"/>
   |   <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
CodeDescription
cxerr:XC0007It is a dynamic error (cxerr:XC0007) if the color offset is not a value between 0 and 359.
cxerr:XC0008It 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:XC0010It is a dynamic error (cxerr:XC0010) if the specified nonterminal does not appear in the grammar.
cxerr:XC0011It 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 ::= "+" | "-" | "×" | "÷"
Example 1Example railroad source
Number op Number ( Expression )
Figure 1The Expression production
Figure 2The Number production
Figure 3The op production
{
  "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>
}
Example 2Document properties for the Number diagram