Saxonica.com

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:output

where 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:output

For 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:

java  -jar dir/saxon9.jar [options] [params]

Note, however, that this does not work if you need to load user-written extension functions or other classes from the classpath. It will therefore not work if your stylesheet uses extension functions, or if you are using other modules such as the Saxon JDOM or XOM interfaces. It also does not work if you are using Saxon-SA, because the license file needs to be on the classpath.

The options are as follows (in any order):

-a

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.

-c:filename

Indicates that the a compiled stylesheet is to be loaded from the given filename. The stylesheet must have been previously compiled as described in Compiling a Stylesheet. If this option is used then the -xsl:filename option should be omitted.

-cr:classname

Use the specified CollectionURIResolver to process collection URIs passed to the collection() function. The CollectionURIResolver is a user-defined class that implements the net.sf.saxon.CollectionURIResolver interface.

-dtd:(on|off)

Setting -dtd:on requests DTD-based validation of the source file and of any files read using the document() function. Requires an XML parser that supports validation. The setting -dtd:off (which is the default) suppresses DTD validation. Note that any external DTD is likely to be read even if not used for validation, because DTDs can contain definitions of entities.

-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 -expand:off suppresses this. (This might not work with all XML parsers)

-explain[:filename]

Display an execution plan for the stylesheet. This is a representation of the expression tree after rewriting by the optimizer. It compbines 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 a tree in XML format.

-ext:(on|off)

If ext:off is specified, suppress calls on external Java functions, other than system-supplied Saxon and EXSLT extension functions. This option is useful when loading an untrusted stylesheet, perhaps from a remote site using an http:// URL; it ensures that the stylesheet cannot call Java methods and thereby gain privileged access to resources on your machine.

-im:modename

Selects the initial mode for the transformation. If this is namespaced, it can be written as {uri}localname

-it:template

Selects the initial named template to be executed. If this is namespaced, it can be written as {uri}localname. When this option is used, you do not need to supply a source file, but if you do, you must supply it using the -s option.

-l[:(on|off)]

If -l or -l:on is specified, causes line and column numbers to be maintained for source documents. These are accessible using the extension functions saxon:line-number() and saxon:column-number(). Line numbers are useful when the purpose of the stylesheet is to find errors or anomalies in the source XML file. Without this option, line numbers are available while source documents are being parsed and validated, but they are not retained in the tree representation of the document.

-m:classname

Use the specified Receiver to process the output from xsl:message. The class must implement the net.sf.saxon.event.Receiver class. This interface is similar to a SAX ContentHandler, it takes a stream of events to generate output. In general the content of a message is an XML fragment. By default the standard XML emitter is used, configured to write to the standard error stream, and to include no XML declaration. Each message is output as a new document.

The sequence of calls to this Receiver is as follows: there is a single open() call at the start of the transformation, and a single close() call at the end; and each evaluation of an xsl:message instruction starts with a startDocument() call and ends with endDocument(). The startDocument() event has a properties argument indicating whether terminate="yes" was specified, and the locationId on calls such as startElement() and characters() can be used to identify the location in the stylesheet where the message data originated (this is achieved by passing the supplied locationId in a call to getPipelineConfiguration().getLocator().getSystemId(locationId), or to getLineNumber() on the same object).

Select the class net.sf.saxon.event.MessageWarner to have xsl:message output notified to the JAXP ErrorListener, as described in the JAXP documentation.

-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 xsl:result-document instruction; this filename acts as the base URI for the href attribute of this instruction. In the absence of this option, secondary output files are written relative to the current working directory.

-or:classname

Use the specified OutputURIResolver to process output URIs appearing in the href attribute of xsl:result-document. The OutputURIResolver is a user-defined class that implements the net.sf.saxon.OutputURIResolver interface.

-outval:(recover|fatal)

Normally, if validation of result documents is requested, a validation error is fatal. Setting the option -outval:recover causes such validation failures to be treated as warnings. The validation message is written both to the standard error stream, and (where possible) as a comment in the result document itself.

-p[:(on|off)]

Use the PTreeURIResolver. This option is available in Saxon-SA only. It cannot be used in conjunction with the -r option, and it automatically switches on the -u and -sa options. The effect is twofold. Firstly, Saxon-specific file extensions are recognized in URIs (including the URI of the source document on the command line). Currently the only Saxon-specific file extension is .ptree, which indicates that the source document is supplied in the form of a Saxon PTree. This is a binary representation of an XML document, designed for speed of loading. Secondly, Saxon-specific query parameters are recognized in a URI. Currently the only query parameter that is recognized is val. This may take the values strict, lax, or strip. For example, source.xml?val=strict loads a document with strict schema validation.

-r:classname

Use the specified URIResolver to process all URIs. The URIResolver is a user-defined class, that extends the net.sf.saxon.URIResolver class, whose function is to take a URI supplied as a string, and return a SAX InputSource. It is invoked to process URIs used in the document() function, in the xsl:include and xsl:import elements, and (if -u is also specified) to process the URIs of the source file and stylesheet file provided on the command line.

-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 -it option is used. The source file is parsed to create a tree, and the document node of this tree acts as the initial context item for the transformation.

If the name identifies a directory, all the files in the directory will be processed individually. In this case the -o option is mandatory, and must also identify a directory, to contain the corresponding output files. A directory must be specified as a filename, not as a URL.

The source-document can be specified as "-" to take the source from standard input.

For backwards compatibility the source filename can also be specified immediately before the stylesheet filename, without the -s flag, provided that the -it option is not present.

-sa

Invoke a schema-aware transformation. Requires Saxon-SA to be installed.

-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 document() function. The default is none: no whitespace stripping.

Specifying all strips all whitespace text nodes from source documents before any further processing, regardless of any xsl:strip-space declarations in the stylesheet, or any xml:space attributes in the source document.

Specifying ignorable strips all ignorable whitespace text nodes from source documents before any further processing, regardless of any xsl:strip-space declarations in the stylesheet, or any xml:space attributes in the source document. Whitespace text nodes are ignorable if they appear in elements defined in the DTD or schema as having element-only content.

-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 net.sf.saxon.trace.TraceListener. If the classname is omitted, a system-supplied trace listener is used.

For performance profiling, set classname to net.sf.saxon.trace.TimedTraceListener. This creates an output file giving timings for each instruction executed. This output file can subsequently be analyzed to give an execution time profile for the stylesheet. See Performance Analysis.

-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.

-traceout:filename

Indicates that the output of the trace() function should be directed to a specified file. Alternatively, specify #out to direct the output to System.out, #err to send it to System.err (the default), or #null to have it discarded. This option is ignored when a trace listener is in use: in that case, trace() output goes to the registered trace listener.

-tree:[linked|tiny]

Selects the implementation of the internal tree model. -tree:tiny the "tiny tree" model (the default). -tree:linked selects the linked tree model. See Choosing a 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 "http:" or "file:", in which case they are taken as URLs

-val[:(strict|lax)]

Requests schema-based validation of the source file and of any files read using the document() or similar functions. This option is available only with Saxon-SA, and it automatically switches on the -sa option. Specify -val or -val:strict to request strict validation, or -val:lax for lax validation.

-versmsg:[on|off]

If versmsg:off is specified, suppress version warnings. This suppresses the warning message that is normally issued (as required by the W3C specification) when running an XSLT 2.0 processor against a stylesheet that specifies version="1.0".

-warnings:[silent|recover|fatal]

Indicates the policy for handling recoverable errors in the stylesheet: silent means recover silently, recover means recover after writing a warning message to the system error output, fatal means signal the error and do not attempt recovery. (Note, this does not currently apply to all errors that the XSLT recommendation describes as recoverable). The default is recover.

-x:classname

Use specified SAX parser for source file and any files loaded using the document() function. The parser must be the fully-qualified class name of a Java class that implements the org.xml.sax.Parser or org.xml.sax.XMLReader interface

-xi

Apply XInclude processing to all input XML documents (including schema and stylesheet modules as well as source documents). 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 -xmlversion:1.1 is specified, allows XML 1.1 and XML Namespaces 1.1 constructs. This option must be set if source documents using XML 1.1 are to be read, or if result documents are to be serialized as XML 1.1. This option also enables use of XML 1.1 constructs within the stylesheet itself.

-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 validate{} expression). This option may also be used to supply the locations of schema documents that are imported into the stylesheet, in the case where the xsl:import-schema declaration gives the target namespace of the schema but not its location.

-xsdversion:[1.0|1.1]

If -xsdversion:1.1 is specified, allows XML Schema 1.1 constructs such as assertions. This option must be set if schema documents using XML Schema 1.1 are to be read.

-xsiloc:on|off

If set to "on" (the default) the schema processor attempts to load any schema documents referenced in xsi:schemaLocation and xsi:noNamespaceSchemaLocation attributes in the instance document, unless a schema for the specified namespace (or non-namespace) is already available. If set to "off", these attributes are ignored.

-xsl:filename

Specifies the file containing the principal stylesheet module. Mandatory unless the -a option or -c option is used; for backwards compatibility the stylesheet can also be specified as the last option before the parameters, without the preceding "-xsl:". The value "-" identifies the standard input stream. If the -u option is specified then the value must be a URI rather than a filename.

-y:classname

Use specified SAX parser for stylesheet file, including any loaded using xsl:include or xsl:import. The parser must be the fully-qualified class name of a Java class that implements the org.xml.sax.Parser or org.xml.sax.XMLReader interface

-?

Display command syntax

stylesheet

Identifies the stylesheet. Mandatory unless the -a option is used. If the -c option is used, this argument identifies a compiled stylesheet. The stylesheet argument can be specified as "-" to read the stylesheet from standard input.

The following options are also available for backwards compatibility, but are likely to be withdrawn at some time in the future. Also, where previous releases allowed an option and a value to be separated by a space rather than a colon (for example -r uriresolver), this syntax should still work for the time being.

-ds | -dt

  • -dt is equivalent to -tree:tiny

  • -ds is equilvalent to -tree:linked

-l

Switches line numbering on for the source document. Line numbers are accessible through the extension function saxon:line-number(), or from a trace listener.

-noext

Equivalent to external:off

-novw

Equivalent to versionmsg:off

-sall

Equivalent to -strip:all

-signorable

Equivalent to -strip:ignorable

-snone

Equivalent to -strip:none

-TL classname

Equivalent to -T:classname

-TP

Equivalent to -T:net.sf.saxon.trace.TimedTraceListener

-v

Equivalent to -dtdval:on

-val

Equivalent to -val:strict

-vlax

Equivalent to -val:lax

-vw

Equivalent to -outval:recover

-w0, w1, or w2

Equivalent to -warnings:silent, -warnings:recover, and -warnings:fatal respectively

-1.1

Equivalent to -xmlversion:1.1

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.

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.

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. See also Additional attributes for xsl:output.

If the -a option is used, the name of the stylesheet is omitted. The source document must contain a <?xml-stylesheet?> processing instruction before the first element start tag; this processing instruction must have a pseudo-attribute href that identifies the relative or absolute URL of the stylsheet document, and a pseudo-attribute type whose value is text/xml, application/xml, or text/xsl. For example:

<?xml-stylesheet type="text/xsl" href="../style3.xsl" ?>

It is also possible to refer to a stylesheet embedded within the source document, provided it has an id attribute and the id attribute is declared in the DTD as being of type ID. For example: 


<?xml-stylesheet type="text/xsl" href="#style1" ?>
<!DOCTYPE BOOKLIST SYSTEM "books.dtd"
  <!ATTLIST xsl:transform id ID #IMPLIED>
<
<BOOKLIST>
  ...
  <xsl:transform id="style1" version="1.0" xmlns:xsl="...">
  ...
  </xsl:transform>
</BOOKLIST>

Next