Running XSLT from the Command Line
A command is available to apply a given stylesheet to a given source XML document. For simple transformations on the Java platform, use the command:
java net.sf.saxon.Transform -s:source -xsl:stylesheet -o:outputwhere source, stylesheet, and output are the source XML file, the XSLT stylesheet, and the output file respectively.
For the .NET platform, the command is simply:
Transform -s:source -xsl:stylesheet -o:outputFor a schema-aware transformation, specify the option -sa
, or (on the Java
platform only) use the alternate entry point com.saxonica.Transform
. For more
details see Schema-Aware
Transformations.
For backwards compatibility with previous releases, the prefixes -s:
and
-xsl:
can be omitted provided that the source document and the stylesheet
are the last two options before any keyword=value parameters.
More generally, the arguments consist of a number of options prefixed with "-", then optionally (for backwards compatibility) the source filename and/or stylesheet filename, then a number of parameters provided as keyword=value pairs. The options must come first, then the file names if present, then the parameters.
For this to work, all the necessary Java components must be available on the classpath. See Installation for details of how to set up the classpath.
If you are are not using any additional Java libraries, you can use the simpler form of command (this example is for the Home Edition):
java -jar dir/saxon9he.jar [options] [params]Note, however, that this does not work if you need to load user-written extension functions or other classes (such as the ICU localization library) from the classpath. It will therefore not work if your stylesheet uses extension functions or other plug-in components such as parsers or URI resolvers.
Command line options
The options are as follows (in any order). Square brackets indicate an optional value.
-a[:(on|off)] |
Use the xml-stylesheet processing instruction in the source document to identify
the stylesheet to be used. The stylesheet argument must not be present on the
command line. For more details see Using the
|
-catalog:filenames |
filenames is either a file name or a list of file names separated by semicolons; the files are OASIS XML catalogs used to define how public identifiers and system identifiers (URIs) used in a source document, stylesheet, or schema are to be redirected, typically to resources available locally. For more details see Using XML Catalogs. |
-config:filename |
Indicates that configuration information should be taken from the supplied configuration file. Any options supplied on the command line override options specified in the configuration file. |
-cr:classname |
Use the specified |
-dtd:(on|off|recover) |
Setting |
-ea:(on|off) |
Setting |
-expand:(on|off) |
Normally, if validation using a DTD or schema is requested, any fixed or default
values defined in the DTD or schema will be expanded. Specifying
|
-explain[:filename] |
Display an execution plan and other diagnostic information for the stylesheet. This is a representation of the expression tree after rewriting by the optimizer. It combines the XSLT instructions and the XPath expressions into a single tree. If no file name is specified the output is sent to the standard error stream. The output is in XML format. |
-export:filename |
Export the compiled stylesheet, in a form suitable for subsequent execution. For more details, see Compiling a Stylesheet. |
-ext:(on|off) |
If |
-im:modename |
Selects the initial mode for the transformation. If this is namespaced, it can be
written as |
-init:initializer |
The value is the name of a user-supplied class that implements the interface Initializer; this
initializer will be called during the initialization process, and may be used to
set any options required on the |
-it[:template-name] |
Selects the initial named template to be executed. If this is namespaced, it can
be written as |
-l[:(on|off)] |
If |
-lib:filenames |
A list of filenames containing library packages. The filenames are separated by ";" on Windows systems, or ":" on Linux and Mac. Each filename must be identify either (a) a top-level module in a source XSLT package, or (b) a SEF file containing an exported library package. There is no constraint on the order of the packages. |
-license:(on|off) |
Relevant only when Saxon-PE or Saxon-EE software is loaded. By default, Saxon will
look for a license and report a warning if none is found, which escalates to a fatal
error if licenseable features (such as schema-awareness) are used. If |
-m:classname |
Use the specified |
-nogo |
If set, the stylesheet is analysed for errors, and any requested
|
-now:yyyy-mm-ddThh:mm:ss+hh:mm |
Sets the value of |
-o:filename |
Send output to named file. In the absence of this option, the results go to
standard output. If the source argument identifies a directory, this option is
mandatory and must also identify a directory; on completion it will contain one
output file for each file in the source directory. If the stylesheet writes
secondary output files using the |
-opt:[-]flags |
Allows individual optimizations to be enabled or disabled selectively. There is a set of single-letter flags identifying particular optimizations (c: generate bytecode; f: inline functions; g: extract global variables; j: just-in-time compilation of template rules; k: create keys; l: loop lifting; m: miscellaneous; r: template rule-sets; s: extract common subexpressions; v: inline variables; w: create switch statements; x: index predicates). A value such as opt:gs runs with only the selected optimizations; opt:-gs runs with the selected optimizations disabled and all others enabled. The value opt:0 suppresses all optimizations. The default is full optimization; this feature allows optimization to be suppressed in cases where reducing compile time is important, or where optimization gets in the way of debugging, or causes extension functions with side-effects to behave unpredictably. (Note however, that even with no optimization, lazy evaluation may still cause the evaluation order to be not as expected.) |
-or:classname |
Use the specified |
-outval:(recover|fatal) |
Normally, if validation of result documents is requested, a validation error is
fatal. Setting the option |
-p[:(on|off)] |
Use the PTreeURIResolver. This option is available in Saxon-PE and Saxon-EE only.
It cannot be used in conjunction with the |
-quit:(on|off) |
With the default setting, |
-r:classname |
Use the specified |
-relocate:(on|off) |
Used with The practical effect of this is that if |
-repeat:integer |
Performs the transformation N times, where N is the specified integer. This option is useful for performance measurement, since timings for the first transformation are often dominated by Java warm-up time. |
-s:filename |
Identifies the source file or directory. Mandatory unless the |
-sa |
Invoke a schema-aware transformation. Requires Saxon-EE to be installed. This
option is not needed if either (a) another option implying schema-awareness is
present (for example |
-scmin:filename |
Loads a precompiled schema component model from the given file. The file should be
generated in a previous run using the
This option is retained for compatibility. From Saxon 9.7, SCM files can also be
supplied in the |
-strip:(all|none|ignorable) |
Specifies what whitespace is to be stripped from source documents
(applies both to the principal source document and to any documents loaded for
example using the |
-t |
Display version and timing information to the standard error output. The output also traces the files that are read and writing, and extension modules that are loaded. |
-T[:classname] |
Display stylesheet tracing information. This traces execution of each
instruction in the stylesheet, so the output can be quite voluminous. Also
switches line numbering on for the source document. If a classname is specified,
it is a user-defined class, which must implement TraceListener. If the classname is
omitted, a system-supplied trace listener is used. For performance profiling, set
classname to |
-target:(EE|PE|HE|JS) |
Relevant only when |
-TB:filename |
Monitors generation of hot-spot bytecode and produces an XML report on the given filename giving, for each expression that was a candidate for bytecode generation and that was actually executed, data about the number of times and speed of execution in the interpreter, the number of times and speed of execution in compiled form, and the cost of compilation. Note that if an expression A contains an expression B and both are candidates for bytecode generation, then the statistics for B relate only to the time before A was compiled in its own right. |
-threads:N |
Used only when the |
-TJ |
Switches on tracing of the binding of calls to external Java methods. This is useful when analyzing why Saxon fails to find a Java method to match an extension function call in the stylesheet, or why it chooses one method over another when several are available. |
-TP:filename |
This is equivalent to setting
|
-traceout:filename |
Indicates that the output of the |
-tree:(linked|tiny|tinyc) |
Selects the implementation of the internal tree model: |
-u |
Indicates that the names of the source document and the stylesheet document are
URLs; otherwise they are taken as filenames, unless they start with
|
-val[:(strict|lax)] |
Requests schema-based validation of the source file and of any files read using
the |
-warnings:(silent|recover|fatal) |
Indicates the policy for handling recoverable errors in the stylesheet:
|
-x:classname |
Use the specified SAX parser for the source file and any files loaded using the
|
-xi:(on|off) |
Apply XInclude processing to all source XML documents (but not to schema and stylesheet modules). This currently only works when documents are parsed using the Xerces parser, which is the default in JDK 1.5 and later. |
-xmlversion:(1.0|1.1) |
If |
-xsd:file1;file2;file3... |
Loads additional schema documents. The declarations in these schema documents are
available when validating source documents (or for use by the
|
-xsdversion:(1.0|1.1) |
If |
-xsiloc:(on|off) |
If set to |
-xsl:filename |
Specifies the file containing the principal stylesheet module. Mandatory unless
the If the stylesheet uses XSLT 3.0 packages, then the option can include a list of locations separated by semicolons (on Windows) or colons (on Unix). The first filename identifies the location of the principal stylesheet module, the others identify the locations of (source code) for packages that are used by the principal module, directly or indirectly. The relevant files can contain either XSLT source code, or a compiled version of
the stylesheet as produced using the |
-y:classname |
Use the specified SAX parser for stylesheet files, including any loaded using
|
--feature:value |
Set a feature defined in the |
-? |
Display command syntax. |
Command line parameters
A param takes the form name=value
, name being the name of the
parameter, and value the value of the parameter. These parameters are accessible
within the stylesheet as normal variables, using the $name
syntax, provided
they are declared using a top-level xsl:param
element. If there is no such
declaration, the supplied parameter value is silently ignored. If the
xsl:param
element has an as
attribute indicating the required
type, then the string value supplied on the command line is cast to this type: this may
result in an error, for example if an integer is required and the supplied value cannot be
converted to an integer. If the parameter is declared with the option
static="yes"
(new in XSLT 3.0) then the value is supplied as a static
parameter value.
A param preceded by a leading question mark (?
) is interpreted as an
XPath expression. For example, ?time=current-dateTime()
sets the value of the
stylesheet parameter $time
to the value of the current date and time, as an
instance of xs:dateTime
, while ?debug=false()
sets the value of
the parameter $debug
to the boolean value false
. If the parameter
has a required type (for example <xsl:param name="p" as="xs:date"/>
),
then the supplied value must be compatible with this type according to the standard rules
for converting variable values and function arguments. The static context for this XPath
expression includes only the standard namespaces conventionally bound to the prefixes
xs
, fn
, xsi
, and saxon
. The static
base URI (used when calling the doc()
function) is the current directory. The
dynamic context contains no context item, position, or size, and no variables.
A param preceded by a leading exclamation mark (!
) is interpreted as an
output parameter. For example, !indent=yes
requests indented output. This is
equivalent to specifying the attribute indent="yes"
on an
xsl:output
declaration in the stylesheet. An output parameter specified on
the command line overrides one specified within the stylesheet. For parameters
doctype-system
, doctype-public
, and
saxon:next-in-chain
, a zero-length value is treated as "absent", that is,
the effect is to cancel any value that was set within the stylesheet.
A param preceded by a leading plus sign (+
) is interpreted as a
filename or directory. The content of the file is parsed as XML, and the resulting document
node is passed to the stylesheet as the value of the parameter. If the parameter value is a
directory, then all the immediately contained files are parsed as XML, and the resulting
sequence of document nodes is passed as the value of the parameter. For example,
+lookup=lookup.xml
sets the value of the stylesheet parameter
lookup
to the document node at the root of the tree representing the parsed
contents of the file lookup.xml
.
Under most operating systems it is possible to supply a value containing spaces by
enclosing it in double quotes, for example name="John Smith"
. This is a
feature of the operating system shell, not something Saxon does, so it may not work the
same way under every operating system or command processor. (In the jEdit console plugin,
for example, it has to be written as "name=John Smith"
.)
If the parameter name is in a non-null namespace, the parameter can be given a value using
the syntax {uri}localname=value
. Here uri
is the namespace URI of
the parameter's name, and localname
is the local part of the name.
This applies also to output parameters. For example, you can set the indentation level to 4
by using the parameter !{http://saxon.sf.net/}indent-spaces=4
. In this case,
however, lexical QNames using the prefix saxon
are also recognized, for
example !saxon:indent-spaces=4
. See also Additional serialization parameters.