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.7
|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 -input
s 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 ofxs: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
orxs: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 can be used to control the running behaviour of MorganaXProc-III. They can 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
orstd:err
. The standard target isstd:out
but by setting-error-stream
tostd:err
, you can choose another stream. Providing any other value will selectstd: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
andxsl:message
on the console output, MorganaXProc-III outputs a prefix before the text ofxsl: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.