File saxon10.saxon.pod of Package saxon10.31763

Overview Repositories Revisions Requests Users Attributes Meta

File saxon10.saxon.pod of Package saxon10.31763

=encoding utf8

=head1 NAME

saxon10 - Saxon XSLT 3.0 processor

=head1 SYNOPSIS

saxon10 [I<options>] [I<params>]

=head1 DESCRIPTION

An XSLT processor, which can be used from the command line, or invoked from an
application, using a supplied API. Saxon implements the XSLT 3.0
Recommendation. The product can also be used to run XSLT 2.0 stylesheets, or
XSLT 1.0 stylesheets in backwards compatibility mode.

=head1 OPTIONS

=over

=item B<-a>[:(C<on>|C<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 L<Using the B<-a>
option|https://www.saxonica.com/documentation10/index.html#!using-xsl/commandline/aoption>.

=item B<-catalog>:I<filenames>

I<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 L<Using XML
Catalogs|https://www.saxonica.com/documentation10/index.html#!sourcedocs/xml-catalogs>.

=item B<-config>:I<filename>

Indicates that configuration information should be taken from the supplied
L<configuration
file|https://www.saxonica.com/documentation10/index.html#!configuration/configuration-file>.
Any options supplied on the command line override options specified in the
configuration file.

=item B<-dtd>:(C<on>|C<off>|C<recover>)

Setting B<-dtd>:C<on> requests DTD-based validation of the source file and of
any files read using the C<document()> function. Requires an XML parser that
supports validation. The setting B<-dtd>:C<off> (which is the default)
suppresses DTD validation. The setting B<-dtd>:C<recover> performs DTD
validation but treats the error as non-fatal if it fails. Note that any
external DTD is likely to be read even if not used for validation, because DTDs
can contain definitions of entities.

=item B<-ea>:(C<on>|C<off>)

Setting B<-ea>:C<on> enables assertions both at compile time and at run time.
Assertions (defined using the XSLT 3.0 C<xsl:assert> instruction) are disabled
by default at compile time, and enabled by default at run-time provided they
were enabled at compile time.

=item B<-expand>:(C<on>|C<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
B<-expand>:C<off> suppresses this. (In the case of DTD-defined defaults, this
might not work with all XML parsers. It does work with the Xerces parser
(default for Java) and the Microsoft parser (default for .NET).)

=item B<-explain>[:I<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.

=item B<-export>:I<filename>

Export the compiled stylesheet, in a form suitable for subsequent execution.
For more details, see L<Compiling a
Stylesheet|https://www.saxonica.com/documentation10/index.html#!using-xsl/compiling>.

=item B<-ext>:(C<on>|C<off>)

If B<-ext>:C<off> is specified, suppress calls on dynamically-loaded external
Java functions. This does not affect calls on integrated extension functions,
including Saxon and EXSLT extension functions. This option is useful when
loading an untrusted stylesheet, perhaps from a remote site using an C<http://>
URL; it ensures that the stylesheet cannot call arbitrary Java methods and
thereby gain privileged access to resources on your machine.

=item B<-im>:I<modename>

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

=item B<-init>:I<initializer>

The value is the name of a user-supplied class that implements the interface
C<Initializer>; this initializer will be called during the initialization
process, and may be used to set any options required on the C<Configuration>
programmatically.

=item B<-it>[:I<template-name>]

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

=item B<-jit>:(C<on>|C<off>)

Determines whether just-in-time compilation of template rules is in force. The
default is on, unless the nogo or explain option is set. When JIT is enabled,
the body of a template rule is not compiled until the rule first fires. This
gives faster compilation when a stylesheet has been written to handle a large
XML vocabulary, but the source document only uses a fraction of the vocabulary.
The drawback is that static errors in the stylesheet may go undetected.

=item B<-l>[:(C<on>|C<off>)]

If B<-l> or B<-l>:C<on> is specified, causes line and column numbers to be
maintained for source documents. These are accessible using the extension
functions C<saxon:line-number()> and C<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.

=item B<-lib>:I<filenames>

A list of filenames containing library packages. The filenames are separated by
“C<;>” on Windows systems, or “C<:>” on Linux and Mac. Each filename must
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.

=item B<-license>:(C<on>|C<off>)

Relevant only when SaxonJ-PE or SaxonJ-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 B<-license>:C<off> is specified, Saxon will not look for a license unless it
is needed, and will fall back silently if none is found (this means that the
transformation might succeed, but without taking advantage of Saxon-EE
optimizations). The option B<-license>:C<off> is useful to suppress warnings in
the case where it is known that a compiled stylesheet containing an embedded
license key is being executed.

=item B<-m>:I<classname>

Use the specified C<Receiver> to process the output from C<xsl:message>. The
class must implement the C<Receiver> interface, and it must have a public
zero-argument constructor. 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 C<open()> call at the start of the
transformation, and a single C<close()> call at the end; and each evaluation of
an C<xsl:message> instruction starts with a C<startDocument()> call and ends
with C<endDocument()>. The C<startDocument()> event has a properties argument
indicating whether C<terminate="yes"> was specified, and the locationId on
calls such as C<startElement()> and C<characters()> can be used to identify the
location in the stylesheet where the message data originated (this is achieved
by passing the supplied C<locationId> in a call to
C<getPipelineConfiguration().getLocator().getSystemId(locationId)>, or to
C<getLineNumber()> on the same object).

Select the class C<MessageWarner> to have C<xsl:message> output notified to the
JAXP ErrorListener, as described in the JAXP documentation.

=item B<-nogo>

If set, the stylesheet is analysed for errors, and any requested B<-explain> or
B<-export> output is generated, but the stylesheet is not executed.

=item B<-now>:I<yyyy-mm-ddThh:mm:ss+hh:mm>

Sets the value of C<current-dateTime()> (and C<implicit-timezone()>) for the
transformation. This is designed for testing, to enable repeatable results to
be obtained for comparison with reference results, or to test that stylesheets
can handle significant dates and times such as end-of-year processing.

=item B<-ns>:(C<uri>|C<##any>|C<##html5>)

Defines the handling of unprefixed element names appearing as name tests in
path expressions and match patterns in the stylesheet.

=over

=item ·

Supplying a URI sets the default namespace for elements and types (effectively
a default value for C<xpath-default-namespace> — note that an explicit value
for this attribute takes precedence).

=item ·

The value C<##any> declares that unprefixed names are treated as a test on the
local name of the element only: they will match regardless of namespace.

=item ·

The value C<##html5> declares that an unprefixed element name will match either
a name in the XHTML namespace, or a name in no namespace. This option is
intended primarily for use when generating stylesheets to run under Saxon-JS in
the browser, since the resulting behavior is close to that defined by the
special rules in the HTML5 specification for XSLT and XPath running against an
HTML5 DOM.

=back

=item B<-o>:I<filename>

Send output to named file.

If the source (B<-s>) 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.

In other cases, this option has two effects: it defines the file where the
principal output of the transformation will be written, and it defines the base
URI used for resolving the value of the C<xsl:result-document/@href> attribute
when secondary result documents are written.

In the absence of this option, (a) the principal output is written to the
standard output stream, and (b) secondary output file locations are resolved
relative to the current working directory.

Output files are created if they do not already exist; any necessary
directories will also be created. If a file does already exist, it is generally
overwritten, though this will not necessarily happen if the transformation
fails.

=item B<-opt>:[C<->]I<flags>

Allows individual optimizations to be enabled or disabled selectively. There is
a set of single-letter flags identifying particular optimizations:

=over

=item C<c>:

generate bytecode

=item C<d>:

detect void path expressions

=item C<e>:

cache regular expressions

=item C<f>:

inline functions

=item C<g>:

extract global variables

=item C<j>:

just-in-time compilation of template rules

=item C<k>:

create keys

=item C<l>:

loop lifting

=item C<m>:

miscellaneous

=item C<n>:

constant folding

=item C<r>:

template rule-sets

=item C<s>:

extract common subexpressions

=item C<t>:

tail call optimization

=item C<v>:

inline variables

=item C<w>:

create switch statements

=item C<x>:

index predicates

=back

A value such as B<-opt>:C<gs> runs with only the selected optimizations;
B<-opt>:C<-gs> runs with the selected optimizations disabled and all others
enabled. The value B<-opt>:C<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.) Disabling
optimizations may in some cases prevent streamed evaluation. For example, some
expressions only become streamable because the optimizer is able to work out
that sorting nodes into document order is unnecessary. Most of these flags
enable optimizations that cause extra work at compile time to improve run-time
performance. The C<j> option is an exception: enabling this option shifts work
from compile time to run time.

=item B<-or>:I<classname>

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

=item B<-outval>:(C<recover>|C<fatal>)

Normally, if validation of result documents is requested, a validation error is
fatal. Setting the option B<-outval>:C<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.

This option does not by itself cause result documents to be validated; that
happens only as a consequence of the type or validation attribute on an
C<xsl:result-document> instruction. The only effect of the option is to
determine what happens when validation fails.

Validating result documents can be very useful while debugging a stylesheet,
because it provides instant feedback when the output is incorrect. However, it
can sometimes be frustrating during development when you know that parts of the
code have not yet been written. The option B<-outval>:C<recover> is designed to
give you the best of both worlds: it tells you that the output is wrong, but
still enables you to see the complete result document that your code is
producing.

=item B<-p>[:(C<on>|C<off>)]

Enable recognition of query parameters (such as C<xinclude=yes>) in the
C<StandardURIResolver>. This option is available in Saxon-PE and Saxon-EE only.
It cannot be used in conjunction with the B<-r> option, and it automatically
switches on the B<-u> and B<-sa> options. The effect is that Saxon-specific
query parameters are recognized in a URI. One query parameter that is
recognized is C<val>. This may take the values C<strict>, C<lax>, or C<strip>.
For example, C<source.xml?val=strict> loads a document with strict schema
validation.

=item B<-quit>:(C<on>|C<off>)

With the default setting, on, the command will quit the Java VM and return an
exit code if a failure occurs. This is useful when running from an operating
system shell. With the setting B<-quit>:C<off> the command instead throws a
C<RunTimeException>, which is more useful when the command is invoked from
another Java application such as Ant.

=item B<-r>:I<classname>

Use the specified C<URIResolver> to process all URIs. The C<URIResolver> is a
user-defined class, that implements the C<javax.xml.transform.URIResolver>
interface, whose function is to take a URI supplied as a string, and return a
SAX Source object. It is invoked to process URIs used in the C<document()>
function, in the C<xsl:include> and C<xsl:import> elements, and (if B<-u> is
also specified) to process the URIs of the source file and stylesheet file
provided on the command line.

=item B<-relocate>:(C<on>|C<off>)

Used with B<-export> to produce an export package which can be deployed to a
different location, with a different base URI. If on, then C<static-base-uri()>
represents the deployed location of the package, rather than its compile time
location. The default is off.

The practical effect of this is that if B<-relocate:>C<off> (the default) is
specified, then the generated SEF file will contain references to the
stylesheet’s original location as its static base URI, and run-time operations
that are relative to this base URI (for example, calling C<doc()> with a
relative URI) will retrieve resources exactly as if the stylesheet had not been
exported. By contrast, if B<-relocate>:C<on> is specified, the SEF file will
contain no reference to the original location of the source stylesheet, and
operations such as C<doc()> will be relative to the location from which the SEF
file was loaded.

=item B<-repeat>:I<integer>

Performs the transformation I<N> times, where I<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.

=item B<-s>:I<filename>

Identifies the source file or directory. Mandatory unless the B<-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.

The filename can be given as “C<->” to take the source from standard input,
in which case the base URI is taken from that of the current directory.

If the name identifies a directory, all the files in the directory will be
processed individually. In this case the B<-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.

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

=item B<-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 B<-val>:C<strict>) or (b) the stylesheet contains an
C<xsl:import-schema> declaration.

=item B<-scmin>:I<filename>

Loads a precompiled schema component model from the given file. The file should
be generated in a previous run of C<com.saxonica.Validate> using the B<-export>
option. When this option is used, the B<-xsd> option should not be present.
Schemas loaded from an SCM file are assumed to be valid, without checking.

This option is retained for compatibility. From Saxon 9.7, SCM files can also
be supplied in the B<-xsd> option.

=item B<-strip>:(C<all>|C<none>|C<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 C<document()> function). The default is ignorable: all ignorable whitespace
is stripped. Whitespace text nodes are ignorable if they appear in elements
defined in the DTD or schema as having element-only content. Specifying all
strips all whitespace text nodes from source documents before any further
processing, regardless of any C<xsl:strip-space> declarations in the
stylesheet, or any C<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 C<xsl:strip-space>
declarations in the stylesheet, or any C<xml:space> attributes in the source
document. Specifying none suppresses all whitespace stripping unless requested
elsewhere, for example using C<xsl:strip-space>.

=item B<-t>

Display version and timing information to the standard error output. The output
also traces the files that are read and written, and extension modules that are
loaded.

=item B<-T>[:I<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 C<TraceListener>.
If the classname is omitted, a system-supplied trace listener is used. For
performance profiling, set classname to
C<net.sf.saxon.trace.TimingTraceListener>. 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
L<Performance
Analysis|https://www.saxonica.com/documentation10/index.html#!using-xsl/performanceanalysis>.

=item B<-target>:(C<EE>|C<PE>|C<HE>|C<JS>)

Relevant only when B<-export> is specified, identifies the target platform on
which the exported stylesheet is to run. When exporting for Saxon-JS, the value
“C<JS>” must be specified, because this adds information to the SEF file that
is required by Saxon-JS. Specifying “C<JS>” means the SEF is produced in JSON
format for use with Saxon-JS 2.x. (To generate SEF files for Saxon-JS 1.x, you
need to revert to Saxon-EE 9.9). In principle, specifying “C<HE>” or “C<PE>”
will inhibit optimizations that generate code which Saxon-HE/Saxon-PE cannot
execute; however, this is not fully tested.

=item B<-TB>:I<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.

=item B<-threads>:I<N>

Used only when the B<-s> option specifies a directory. Controls the number of
threads used to process the files in the directory. Each transformation runs in
a single thread.

=item B<-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.

=item B<-Tlevel>:(C<none>|C<low>|C<normal>|C<high>)

Controls the level of detail of the tracing produced by the B<-T> option. The
values are:

=over

=item C<none>

effectively switches tracing off.

=item C<low>

traces function and template calls.

=item C<normal>

traces execution of instructions.

=item C<high>

traces execution of finer-grained expressions.

=back

=item B<-Tout>:I<filename>

Directs the output of tracing to a specified file (assuming that B<-T> is
enabled).

=item B<-TP>:I<filename>

This is equivalent to setting B<-T>:C<net.sf.saxon.trace.TimedTraceListener>
and B<-traceout>:I<filename>; that is, it causes trace profile information to
be set to the specified file. This output file can subsequently be analyzed to
give an execution time profile for the stylesheet. See L<Performance
Analysis|https://www.saxonica.com/documentation10/index.html#!using-xsl/performanceanalysis>.

=item B<-traceout>:I<filename>

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

=item B<-tree>:(C<linked>|C<tiny>|C<tinyc>)

Selects the implementation of the internal tree model: C<tiny> selects the
“tiny tree” model (the default), C<linked> selects the linked tree model,
C<tinyc> selects the “condensed tiny tree” model. See L<Choosing a tree
model|https://www.saxonica.com/documentation10/index.html#!sourcedocs/choosingmodel>.

=item B<-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 C<http:>,
C<https:>, C<file:> or C<classpath:>, in which case they are taken as URLs.

=item B<-val>[:(C<strict>|C<lax>)]

Requests schema-based validation of the source file and of any files read using
the C<document()> or similar functions. Validation is available only with
Saxon-EE, and this flag automatically switches on the B<-sa> option. Specify
B<-val> or B<-val>:C<strict> to request strict validation, or B<-val>:C<lax>
for lax validation.

=item B<-warnings>:(C<silent>|C<recover>|C<fatal>)

Indicates the policy for handling recoverable errors in the stylesheet:
C<silent> means recover silently, C<recover> means recover after writing a
warning message to the system error output, C<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.

=item B<-x>:I<classname>

Use the specified SAX parser for the source file and any files loaded using the
C<document()> function. The parser must be the fully-qualified class name of a
Java class that implements the C<org.xml.sax.XMLReader> or
C<javax.xml.parsers.SAXParserFactory> interface, and it must be instantiable
using a zero-argument public constructor. One use of this option is to select
an HTML parser such as John Cowan’s TagSoup rather than an XML parser. In this
case, the TagSoup JAR file must be on the classpath, and the class name to use
is C<org.ccil.cowan.tagsoup.Parser>. Another common use is to specify
C<org.apache.xml.resolver.tools.ResolvingXMLReader>. This parser is provided by
the Apache commons project, and it customizes the default parser by using an
C<EntityResolver> that resolves external entity references (note the reference
to an external DTD in a DOCTYPE declaration) by reference to an OASIS catalog
file. This can be used to avoid repeated calls to external web servers (such as
the W3C server) for commonly used DTDs such as the XHTML DTD. The option to
supply a C<SAXParserFactory> was introduced in 9.6 for the benefit of the Aalto
parser, whose C<XMLReader> implementation cannot be directly instantiated; this
parser can therefore be requested by nominating its factory class,
C<com.fasterxml.aalto.sax.SAXParserImpl>.

=item B<-xi>:(C<on>|C<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 on the SaxonJ platform (but not on .NET).

=item B<-xmlversion>:(C<1.0>|C<1.1>)

If B<-xmlversion>:C<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.

=item B<-xsd>:I<file1>;I<file2>;I<file3>…

Loads additional schema documents. The declarations in these schema documents
are available when validating source documents (or for use by the C<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
C<xsl:import-schema> declaration gives the target namespace of the schema but
not its location.

=item B<-xsdversion>:(C<1.0>|C<1.1>)

If B<-xsdversion>:C<1.1> is specified (the default), allows schema documents
using XML Schema 1.1 to be read, and XML Schema 1.1 constructs such as
assertions.

=item B<-xsiloc>:(C<on>|C<off>)

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

=item B<-xsl>:I<filename>

Specifies the file containing the principal stylesheet module. Mandatory unless
the B<-a> option is used. The value “C<->” identifies the standard input
stream, in which case the static base URI is taken from that of the current
directory. If the B<-u> option is specified then the value must be a URI rather
than a filename.

The selected file can contain either XSLT source code, or a compiled version of
the stylesheet (a SEF file) as produced using the B<-export> option.

=item B<-y>:I<classname>

Use the specified SAX parser for stylesheet files, including any loaded using
C<xsl:include> or C<xsl:import>. The supplied classname must be the
fully-qualified class name of a Java class that implements the
C<org.xml.sax.XMLReader> or C<javax.xml.parsers.SAXParserFactory> interface,
and it must be instantiable using a zero-argument public constructor.

=item B<--feature>:I<value>

Set a feature defined in the C<Configuration> interface. The names of features
are defined in the Javadoc for class Feature (alternatively see L<Configuration
Features|https://www.saxonica.com/documentation10/index.html#!configuration/config-features>):
the value used here is the part of the name after the last “C</>”, for example
B<--allow-external-functions>:C<off>. Only features accepting a string or
boolean may be set; for booleans the values C<true>/C<false>, C<on>/C<off>,
C<yes>/C<no>, and C<1>/C<0> are recognized.

=item B<-?>

Display command syntax.

=item B<--?>

Display a list of features that are available using the B<--feature>:I<value>
syntax.

=back

=head2 COMMAND LINE PARAMETERS

A param takes the form I<name>=I<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 C<$>I<name> syntax, provided they
are declared using a top-level C<xsl:param> element. If there is no such
declaration, the supplied parameter value is silently ignored. If the
C<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
C<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 (C<?>) is interpreted as an XPath
expression. For example, C<?time=current-dateTime()> sets the value of the
stylesheet parameter $time to the value of the current date and time, as an
instance of C<xs:dateTime>, while C<?debug=false()> sets the value of the
parameter C<$debug> to the boolean value false. If the parameter has a required
type (for example C<E<lt>xsl:param name="p" as="xs:date"/E<gt>>), 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 C<xs>, C<fn>, C<xsi>, and C<saxon>. The static base URI
(used when calling the C<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 (C<!>) is interpreted as an
output parameter. For example, C<!indent=yes> requests indented output. This is
equivalent to specifying the attribute C<indent="yes"> on an C<xsl:output>
declaration in the stylesheet. An output parameter specified on the command
line overrides one specified within the stylesheet. For parameters
C<doctype-system>, C<doctype-public>, and C<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. If you are using the bash shell, you will need
to escape “C<!>” as “C<\!>”.

A param preceded by a leading plus sign (C<+>) 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, C<+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 F<lookup.xml>.

Under most operating systems it is possible to supply a value containing spaces
by enclosing it in double quotes, for example C<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 C<"name=John
Smith">.)

If the parameter name is in a non-null namespace, the parameter can be given a
value using the syntax C<{>I<uri>C<}>I<localname>=I<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
C<!{http://saxon.sf.net/}indent-spaces=4>. In this case, however, lexical
QNames using the prefix saxon are also recognized, for example
C<!saxon:indent-spaces=4>. See also L<Additional serialization
parameters|https://www.saxonica.com/documentation10/index.html#!extensions/output-extras>.

=head1 SEE ALSO

L<https://www.saxonica.com/documentation10/index.html>, L<gizmo10(1)>,
L<saxon10q(1)>, L<xsltproc(1)>.

=head1 AUTHOR

Michael H. Kay E<lt>L<mike@saxonica.com>E<gt>

Places

File saxon10.saxon.pod of Package saxon10.31763

Places