Name

cx:plantuml — Draws diagrams with PlantUML.

Synopsis

This step constructs diagrams with PlantUML.

Input portPrimarySequenceContent types
source✔  text 
Output portPrimarySequenceContent types
result✔   
Option nameTypeDefault value
formatxs:string?'png'
parametersmap(xs:QName, item()*)?()
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/diagramming.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"/>
  |   <p:option name="format" as="xs:string?" select="'png'"/>
5 |   <p:option name="parameters" as="map(xs:QName, item()*)?"/>
  |</p:declare-step>

Description

The cx:plantuml step constructs diagrams with PlantUML. PlantUML supports a wide variety of diagrams, not just UML diagrams.

The mapping from output formats to content types isn’t 1:1, so you must specify the format explicitly. Available formats (at the time of writing) are:

FormatContent type
atxttext/plain
base64text/plain;charset=x-user-defined
braille-pngimage/png
debugtext/plain
epsapplication/postscript
eps-textapplication/postscript
graphmlapplication/graphml+xml
htmltext/html
html5text/html
latexapplication/x-latex
latex-no-preambleapplication/x-latex
pdfapplication/pdf
pngimage/png
preproctext/plain
rawimage/raw
scxmlapplication/scxml+xml
svgimage/svg+xml
utxttext/plain;charset=UTF-8
vdxapplication/vnd.visio.xml
xmi-argoapplication/vnd.xmi+xml
xmi-scriptapplication/vnd.xmi+xml
xmi-standardapplication/vnd.xmi+xml
xmi-starapplication/vnd.xmi+xml

XML Calabash uses 1.2025.0 of the PlantUML library.

Examples

The PlantUML user guide includes many examples. The UML source in Example 1, “UML source” renders to the image show in Figure 1, “UML diagram”.

@startuml
skinparam backgroundColor #FFFFF8
 
class BaseClass
 
namespace net.dummy #DDDDDD {
    .BaseClass <|-- Person
    Meeting o-- Person
 
    .BaseClass <|- Meeting
}
 
namespace net.foo {
  net.dummy.Person  <|- Person
  .BaseClass <|-- Person
 
  net.dummy.Meeting o-- Person
}
 
BaseClass <|-- net.unused.Person
 
@enduml
Example 1. UML source
Figure 1. UML diagram

Another example shows how JSON can be rendered. The object in Example 2, “JSON source” renders to the image show in Figure 2, “JSON diagram”. (Note the use of pragmas for highlighting.)

@startjson
skinparam backgroundColor #FFFFF8
 
#highlight "lastName"
#highlight "address" / "city"
#highlight "phoneNumbers" / "0" / "number"
{
  "firstName": "John",
  "lastName": "Smith",
  "isAlive": true,
  "age": 28,
  "address": {
    "streetAddress": "21 2nd Street",
    "city": "New York",
    "state": "NY",
    "postalCode": "10021-3100"
  },
  "phoneNumbers": [
    {
      "type": "home",
      "number": "212 555-1234"
    },
    {
      "type": "office",
      "number": "646 555-4567"
    }
  ],
  "children": [],
  "spouse": null
}
@endjson
Example 2. JSON source
Figure 2. JSON diagram

A final example (but by no means an exhaustive list of all of the possible examples) shows the PlantUML EBNF for PlantUML. The EBNF in Example 3, “JSON source” renders to the image show in Figure 3, “EBNF diagram”. (Note the use of pragmas for highlighting.)

@startebnf
skinparam backgroundColor #FFFFF8
 
grammar = { rule };
rule = lhs , "=" (* definition *) , rhs , ";" (* termination *);
lhs = identifier ;
rhs = identifier
     | terminal
     | "[" , rhs (* optional *) , "]"
     | "{" , rhs (* repetition *), "}"
     | "(" , rhs (* grouping *) , ")"
     | "(*" , string (* comment *) , "*)"
     | "?" , rhs (* special sequence, aka notation *) , "?"
     | rhs , "|" (* alternation *) , rhs
     | rhs , "," (* concatenation *), rhs ;
identifier = letter , { letter | digit | "_" } ;
terminal = "'" , character , { character } , "'"
         | '"' , character , { character } , '"' ;
character = letter | digit | symbol | "_" ;
symbol = "[" | "]" | "{" | "}" | "(" | ")" | "<" | ">"
       | "'" | '"' | "=" | "|" | "." | "," | ";" ;
digit = ? 0-9 ? ;
letter = ? A-Z or a-z ? ;
@endebnf
Example 3. JSON source
Figure 3. EBNF 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:diagramming:3.0.0-alpha23

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

  • net.sourceforge.plantuml:plantuml:1.2025.0
  • de.rototor.jeuclid:jeuclid-core:3.1.14
  • ditaa0.9.jar, included in the XML Calabash extension because it’s not available through Maven.