Documentation

Woefully incomplete, to be sure, but at least something exists now.

What is it?

Calabash is an implementation of XProc: An XML Pipeline Language

Prerequisites

Calabash is built with Java 1.8 on top of Saxon. Recent releases rely on Maven to download dependencies so I've removed the often out-of-date list that used to be here.

Some features rely on the “professional” edition of Saxon (XSD validation, for example). Some steps rely on additional, sometimes commercial, libraries.

Calabash also implements several extension steps. These are not part of the XProc core language standard and cannot be expected to reliably interoperate with other implementations. These are documented in the reference documentation.

How do I use it?

Download the latest release. Inside the archive you'll find calabash.jar. Make sure that jar file and the prerequisites are on your class path. Then you can run it from the command line:

java com.xmlcalabash.drivers.Main options pipeline.xpl

For example:

$ java com.xmlcalabash.drivers.Main xpl/pipe.xpl
<doc xmlns:p="http://www.w3.org/ns/xproc">
Congratulations! You've run your first pipeline!
</doc>

You can use -iport=file to change the inputs and -oport=file> to change the output location.

For example:

$ java com.xmlcalabash.drivers.Main -isource=pipe.xpl -oresult=/tmp/out.xml xpl/pipe.xpl

That will run pipe.xpl using pipe.xpl as the input and writing the result to /tmp/out.xml.

If you run java com.xmlcalabash.drivers.Main with no options, it will print a short usage summary.

Simple pipelines from the command-line

Starting with version 0.9.18, XML Calabash supports simple, linear pipelines on the command-line. The basic idea is that you list each of the steps with the -s option. You can precede each step with its inputs and parameters and follow it with its options.

For example, to run an XSLT step, you could do something like this:

$ java com.xmlcalabash.drivers.Main \
       -isource=doc.xml -istylesheet=style.xsl -s p:xslt

To validate the input then process it with XSLT, like this:

$ java com.xmlcalabash.drivers.Main \
       -isource=doc.xml -ischema=schema.xsd -s p:validate-with-xml-schema \
       -istylesheet=style.xsl -s p:xslt

The way this works is by constructing a literal pipeline from the steps passed on the command-line and then running that pipeline.

If you run with the --debug option, you can see the pipeline that was constructed.

If you load a library or libraries with --library option, you can refer to those steps in your pipeline, but each step must have a single primary input and a single primary output.

Reference documentation

See XML Calabash Reference.

What do I do if it all goes wrong?

Tell Norm.