Chapter 1. Using the command line interface (CLI)

1 . Introduction

The easiest way to call MorganaXProc-III from the command line is to use a batch file. This approcach takes away a lot of the complexity and typing from calling MorganaXProc's JAR-file directly. If you look into the folder containing the JAR-file, you will find two files named “Morgana.bat” or “MorganaEE.bat” (for Windows) and “Morgana.sh” or “MorganaEE.sh” (for MacOS and other UNIX based operating systems). Using these batch files to start MorganaXProc-III requires significantly less typing on the command line:

  |cd /users/me/MorganaXProc
  |sh Morgana.sh pipeline.xpl
  |=================================
  |MorganaXProc-IIIse 1.3.6
  |Copyright 2011-2024 by <xml-project /> Achim Berndzen
  |=================================
  | 
  |Hello world. This is an XProc 3.0 pipeline running.

This was easy, wasn't it? By inspecting the batch file you can also see how to call MorganaXProc-III directly and how to set up configuration for your special purposes.

2 . Running a pipeline from the command line

Running an XProc pipeline might be very complex because you do not only want to tell MorganaXProc-III the pipeline's place in the file system. You may also want to control which documents appear on the different input ports of your pipeline and where the document appearing on the output ports should be stored. And then there are option and static options in your pipeline you might wish to give values for. Let us see how to do this and thereby understand in more detail how MorganaXProc-III interprets the tokens appearing on the command line.

As we have already seen, you specify the name of the XProc pipeline you want to run by simply writing its name as the first (or –as we shall see later– the second) token. The token either may take the form of a URI (like file:///users/me/MorganaXProc/pipeline.xpl) or as a file path (either in the Windows form if you are on Windows or the UNIX form if your operating system is Unix like). If the pipeline's path is relative, it will be resolved against the current working directory.

After the pipeline name you can specify the bindings for input ports, output port, option and static options in random order.

2.1 . Binding an input port

To specify a binding for an input port you have to use -input:port-name=uri-or-path. For example you could type “-input:source=doc.xml” to bind the document in file “doc.xml” in your current working directory to a pipeline's input port called “source”. Here again, like with the XProc pipeline, you might either give a URI or a path in your file system. If it is relative, it will be resolved against the current working directory. If you want to bind more than one document to a (sequence) port, just add more -input on the command line. The order in which these documents appear on the sequence port is the same as the one you give the -inputs on the command line.

2.2 . Specifying target for an output port

To specify where the documents appearing on an output port should be stored, use -output:port-name=uri-or-path. The mechanism for resolving a relative URI or path is the same as for the pipeline or -input: The current working directory is used.

If you do not specify a -output for an output port declared in your XProc pipeline, the document(s) appearing on this port will be written to you command line shell. There are three tricky things with -output worth to remember:

If more than one document appears on an output port for which a -output setting is given, all documents are written to the specified resource in the order they appear on the port. As a consequence, the resource content will not be well-formed.
Any existing content in a resource named with -output will be overridden without warning, so please be careful.
MorganaXProc-III will not create any non-existing folder/directory named in the path. If you specify a path or URI with one or more non-existing folders, an error will be raised. See below about -cp to see how to change this behaviour.

2.3 . Binding values to options

Additionally to input and output ports, an XProc pipeline may also specify options you might want to set using the command line interface. To do this use -option:option-name=string-or-XPathExpression. Here are some examples:

  |-option:opt=value
  |-option:Q{http://some-namespace}opt=5+3
  |-option:map=map{'key':'value'}
  |-option:date=2020-03-28T13:53:00
  |-option:name=Q{http://some-namespace}name
  |-option:numbers='(1, 1+1, 2+1)'
  |-option:numbers=(1,1+1,2+1,2+2)

As you can see from the examples, the option's name can either be a simple string (if the name of the option to be set is in no namespace) or be given using the Q{}-notation to name an option in a namespace. How the string after “=” is interpreted depends on the option's type:

If the option in the pipeline is declared without a type, the string following “=” is taken as parameter of xs:untypedAtomic().
If the option's type is an atomic type (optionally with occurrence indicator “?”) the processor will try to cast the given string to an instance of the option's type.
If the option's type is xs:QName or xs:QName? you can use the Q{}-notation.
In all other cases the processor will try to interpret the string as an XPath expression, evaluate it and cast the resulting sequence to an instance the option's type.

Caveat: Please remember that the command line processor splits up the command line into tokens using “ ” (space) as a separator. As a consequence you can not have a “ ” in the string specifying the option's value. If you want to use a “ ” you have to put quotes around the whole string. See the last but one example above and compare it to the last one.

One last thing: If you want to load a document (XML, text, or JSON) from a file, use the corresponding XPath function.

2.4 . Setting static options

In XProc 3.0 a pipeline may declare static options which are supplied to pipeline's static analysis. As static options are a special kind of option, MorganaXProc-III uses the same syntax to parse the command line. The only difference is, that you have to use “-static” instead of “-option”.

Unlike ordinary or dynamic options, static options can also be set from a document. This can be handy if you want to run your pipeline with different sets of basic configurations, say one for debugging and one for production. To load a set of values for your pipeline's static options, use -statics=uri-or-path. If the URI or path is relative, it will be resolved against the current working directory. Please see the file “static-defs.xml in your distribution for an example. Your will notice that configuration is cascading because one configuration file can hold a reference to another configuration file to be loaded.

MorganaXProc-III will process -static and -statics from left to right so the later settings will override earlier settings for a static option with the same name.

3 . Switches

Switches on the command line could be used to control the running behaviour of MorganaXProc-III. They could appear anywhere on the command line after the specification of the pipeline to run. Currently the following switches are available:

-cp

As said above, MorganaXProc-III usually does not create any folder necessary to store documents appearing on an output port to a specific location in your file system. This behaviour can be overridden by using switch -cp (read: “create paths”).

-debug

Turns on debugging information of running the compiled XProc 3.0 pipeline in MoPL. It displays every message send in the running MoPL pipeline together with it's sender and it's receiver. This is currently only used for internal debugging purposes of MorganaXProc-III and might not be useful to the public.

-dump-binary

In the standard configuration MorganaXProc-III does not output binary documents on standard output. Information about the document is printed instead. To enable output of binary documents on standard output use -dump-binary.

-error-stream

This switch determines whether <c:errors/> documents resulting from a pipeline will be send to std:out or std:err. The standard target is std:out but by setting -error-stream to std:err, you can choose another stream. Providing any other value will select std:out.

-graph

If you use this switch on the command line, you get a textual representation of the execution graph created by the XProc 3.0 compiler. This might be helpful if your pipeline has an unexpected behaviour. For every step's input and output port it is listed how they are connected. Of course the current format is not the last word on this. Some graphical representation might surely be more useful.

-indent-errors

This switch will turn on indentation for dynamic errors printed on the console.

-mopl

Using this switch will output the MoPL pipeline generated by the XProc 3.0 compiler on the console. This is currently a purely debugging feature and might not be of public interest.

-mopl-mode

Under Java 8 this switch can be used to control which runner is used to execute the generated MoPL pipeline. The default runner is “quasar” will try to make more use of your processor power by executing independend steps in parallel. A side effect of this strategy is increased memory load. If you need a memory preserving execution of you pipeline, running Java 8 you can use this switch with “linear” (-mopl-mode=linear): Your pipeline will need less memory, but as one step is executed at one time, execution time will increase. On Java versions other than version 8, this switch has currently no effect.

-no-run

Tells the XProc processor just to perform a static analysis of the supplied pipeline, but not to run it. This switch can be handy if you just want to check whether your pipeline is correct, but not start a long execution process.

-no-timestamps

Switches off timestamps to be written before [p:]message.

-silent

If you use -silent on the command line, no additional information will be written to the console while running the pipeline. This might be handy if you want to pipe the console output to a file containing just the document(s) appearing on an output port.

-split-sequence

Binding on output port to a path or URI on the CLI means that the content of the respective port is written to a file. This can be inconvenient if a sequence appears on the port. By using -split-sequence you can advice the CLI to create a new file for each document appearing on a sequence port. The CLI will take the path or URI given with -output:port= as a blueprint to create the effective file name: If the path contains a ., -x is inserted before the dot. (x here stands for the number of the respective document in the sequence, counting from 1). If there is no dot, -x is simply attached to the path.

xslt-message-prefix

In order to differentiate outputs from [p:]message and xsl:message on the console output, MorganaXProc-III outputs a prefix before the text of xsl:message. The standard text is "[XSLT Message] ". To change this text, simply use -xslt-message-prefix="This is my prefix: " or whatever else text you prefer. If you do not want any prefix at all, just associate the switch with an empty string. Instead of a command line switch you can also use the respective element name in your MorganaXProc-III configuration document.

-warning-recorder

Some technologies used in XProc steps create warning messages not mapped to the specification of the actual step. One example is p:xslt when used with SaxonEE, a warning might be raised to tell you, that one of the template rules has a match pattern that can never be matched according to the imported schema. This is not an error, but an information that might be important to stylesheet developers.

To see these warning messages you can use the switch -warning-recorder to create a text file containing all the warnings raised during a pipeline run. The place of the text file is controlled by the value associated with the switch. If the value ends with a "/" it is taken to be a path to a folder. If it is relative, it is made absolute against the current working directory. In this folder (with is created if it does not exist) the warnings are recorded in a file named "xproc-warnings" followed by the current date-time, e.g. "xproc-warnings-2024-01-02-16-52-16.txt".

If the string does not end with "/" it is understand as a relative or absolute path to a file. All folders not existing will be created. If the file path contains one or more dots, the filename will be split before the last dot. The current date-time will be appended to the first part and then the second part is added. Therefor "warnings.log" will result in e.g. "Warnings-2021-12-31-09-03-54.log". If there is no dot, a date-time string will be added to produce the effective file name.

4 . Exit codes for shell scripts

When running in a shell script, it is common for an application to return some exit code to reflect the results of processing. As expected, MorganaXProc-III returns "0" if pipeline call was successfull. All values other then "0" reflects an error occured during execution.

exit-code=1: Interface error: Error occurred during processing of command line parameters or configuration file.
exit-code=2: Static error: Error occurred during static analysis of the pipeline.
exit-code=3: Dynamic error: Error occurred during dynamic execution of the pipeline.
exit-code=99: Other error.

A negative exit code is only returned by MorganaXProc-IIIee and hints to an error with (processing) the licence certificate.