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 nameTypeValuesDefault value
colorxs:string? '#FFDB4D'
color-offsetxs:integer 0
eliminate-recursionxs:boolean true()
factoringxs:boolean true()
inline-literalsxs:boolean true()
keep-epsilon-nonterminalsxs:boolean true()
nonterminalxs:string? ()
notationxs:string?('abnf', 'antlr_3', 'antlr_4', 'bison', 'gold', 'instaparse', 'ixml', 'javacc', 'jison', 'pegjs', 'phythia', 'pss', 'rex_5_9', 'w3c', 'xtext') ()
paddingxs:integer? ()
stroke-widthxs:integer? ()
transform-linksXPathExpression "'#' || $p:nonterminal"
widthxs:integer 992
This is an extension step; to use it, your pipeline must include its declaration. For example, by including the extension library with an import at the top of your pipeline:
<p:import href="https://xmlcalabash.com/ext/library/railroad.xpl"/>
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:option name="notation"
   |             as="xs:string?"
25 |             values="('abnf', 'antlr_3', 'antlr_4', 'bison', 'gold', 'instaparse', 'ixml',                      'javacc', 'jison', 'pegjs', 'phythia', 'pss', 'rex_5_9', 'w3c', 'xtext')"/>
   |</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.
cxerr:XC0022It is a dynamic error (cxerr:XC0022) if the grammar conversion fails.

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.

There are many flavors of EBNF, the Railroad Diagram Generator uses the W3C EBNF format. There’s a related step, cx:ebnf-convert, that can convert many different varieties of EBNF to the W3C format. As a convenience, the notation option can be used to indicate that some other variety is being used as input. The EBNF converter will be called automatically to perform the conversion before attempting to build the diagram.

If no notation is specified, the step will attempt to determine the grammar format by inspection. If this fails, specify the format. If the factoring option is true, the conversion is performed with “full-left” factoring. If the eliminate-recursion option is true, “full” recursion elimination is used. If you need more control over the conversion, use the cx:ebnf-convert step beforehand and pass the results to cx:railroad.

It is a dynamic error (cxerr:XC0022) if the grammar conversion fails.

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 1. Example railroad source
Number op Number ( Expression )
Figure 1. The Expression production
Figure 2. The Number production
Figure 3. The 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 2. Document properties for the Number diagram

Dependencies

This step is included in the XML Calabash application. If you are getting XML Calabash from Maven, you will also need to include the extension dependency:

  • com.xmlcalabash:railroad:3.0.0-alpha23

The following third-party dependencies will also be included transitively:

  • de.bottlecaps.rr:rr-lib:2.1
  • de.bottlecaps.ebnf-convert:ebnf-convert-lib:0.70