Gobo Eiffel XSLT Command-line usage and options PreviousNext

How to invoke gexslt

Gexslt is invoked from the command line. The general form is:

Stylesheet and source documents

The stylesheet and source documents can be written either as URIs or as names in the local file system. Gexslt will attempt to convert a local file name into a URI, if it detects such a name is not already a URI.

If you want to use a file name that starts with --, or includes = as a character in the name, or might look to the system like a URI (e.g. if http://foo/bar is a valid file name on your system), then you can force gexslt to interpret it as a file name by writing it as --file=my/file.name.

If you want to ensure that gexslt treats a name as a URI (necessary if it starts with -- or includes =), then you can write it as --uri=my:strange=uri.

Fragment identifiers

If the URI for a source document includes a fragment identifier, then gexslt will parse the document as normal, but will attempt to set the initial context node to be that specified by the fragment (according to the semantics for the particular media type). Note, that in this case, the initial context node will not necessarily match the pattern /, so the initial template may vary according to the fragment identifier. Note also, that the document root and document element are exactly the same nodes as they would be if no fragment identifier is supplied.

Gexslt recognizes the following media types:

If the resolver is unable to supply the media type, then application/xml is assumed, except for stylesheet modules, where application/xslt+xml is assumed (since the latter is defined to have identical fragment identifier semantics to the former, there is no significance to this difference).

Only shorthand pointers are supported for stylesheets. In this case, the shorthand pointer must point to an ID attribute (and the DTD must be available), or an xml:id attribute, on the xsl:transform or xsl:stylesheet element.

Parameters

To set a global parameter on a stylesheet (as defined by a top-level xsl:param declaration), you may set it via an option. However, gexslt provides a more convenient syntax for the most common usage pattern, string-valued parameters:

Note that single quotes are only needed to avoid mis-interpretation by the command shell.

These string parameters may, in principle, appear anywhere within the command line, although it is conventional to put them at the end.

If you wish to pass general XPath expressions to the stylesheet, you have to use the --xpath-param option.

Options

The following is a list of the options that can be given on the command-line:

Stylesheet control

The following options control stylesheet execution:

--use-pi
Interpret the first file or URI argument as a source document, rather than a stylesheet. Search for one or more xml-stylesheet processing instructions within that source document, and use them to find the stylesheet.

Gexslt has to parse the source document twice. Once to find the processing instruction, and again, after the stylesheet has been compiled (as it may contain xsl:preserve-space or xsl:strip-space commands). Although the first parse is quick (as the processing instruction must occur in the prolog of the XML document), this does mean that a stream that can only be read once may not be used with this option.

There are additional options that further control the interpretation of the xml-stylesheet processing instructions:

--medium={medium-name}
The target medium. This must be a single word, consisting solely of the characters [a-z][A-z][0-9][-]. Only processing instructions that contain this medium name (or the special name "all") within their media pseudo-attribute will be selected. The default is "screen", both for this parameter and the processing instruction media pseudo-attribute. Case is significant. The word "all" is not permitted.
--title={preference}
The preferred style. This may be any text string (leading and trailing double quotes will be removed, so you may include spaces). Only processing instructions that have this style name for their title pseudo-attribute will be selected, along with any persistent stylesheets (those that do not specify the title pseudo-attribute). If this parameter is omitted, then the first preferred stylesheet for the medium (that is, one that supplies the title pseudo-attribute and does not supply the alternate pseudo-attribute with a value of "yes") will also be selected. Case is significant.

--output=<local-file-name>
Names the destination for the transformation results. If omitted, the results are written to the standard output stream.
--mode=[<namespace-uri>#]<local-name>
Specifies an initial mode. This is a QName. If the name is qualified by a prefix within the stylesheet, then prefix the local name with the namespace URI followed by #.

If this parameter is omitted (the usual situation), then the default mode is used.

--template=[<namespace-uri>#]<local-name>
Specifies a named template to be invoked. This is a QName. If the name is qualified by a prefix within the stylesheet, then prefix the local name with the namespace URI followed by #.

If this parameter is omitted (the usual situation), then the initial template is the one that matches the initial context node, normally the document node, of the source document. If this parameter is supplied, then the source document may be omitted.

--context=<name>=<XPath expression>
Specifies an XPath expression to be applied to the source document in order to determine the initial context node. This parameter must be omitted if a source document is not supplied. It is a non-recoverable error is the supplied expression does not select a single node.

If this parameter is omitted (the usual situation), then the initial context node is the document node of the source document.

--param=<name>=<string-value>
Sets a string-valued global parameter on the stylesheet. Enclose the value in single quotes if it includes embedded blanks.
--xpath-param=<name>=<XPath expression>
Sets a global parameter on the stylesheet, passing an XPath expression as the value. Enclose the value in single quotes if it includes embedded blanks.
--default-template-warning
Issues a warning message when a built-in template is invoked.

The default-template-warning and suppress-default-action options are mutually exclusive. If both are selected, one will be arbitrarily ignored.

--suppress-default-action
Suppresses all invocations of built-in templates.

Use of this option gives non-compliant behaviour.

The default-template-warning and suppress-default-action options are mutually exclusive. If both are selected, one will be arbitrarily ignored.

Tracing

The following options control stylesheet execution tracing:

--trace[=<trace-file>]
Turn on stylesheet tracing.

Set the destination for trace output to be "trace-file". If "trace-file" is omitted, then trace output is sent to the standard output stream.

If neither this option nor the timed-trace option is given, then no trace output is produced.

--timed-trace[=<trace-file>]
Turn on stylesheet tracing with timings.

Set the destination for trace output to be "trace-file". If "trace-file" is omitted, then trace output is sent to the standard output stream.

--suppress-xpath-tracing
Suppress output from the XPath fn:trace() function.

Errors and warnings

The following options control issuing of error and warning messages:

--secure
Operate in secure mode. Any attempt by an xsl:document instruction to write to any destination other than the standard output stream or an in-memory string will result in a fatal error.
--warnings=[<warning-file>]
Set the destination for warnings to be "warning-file". If "warning-file" is omitted, then all warning messages are ignored.

If this parameter is not given, then warnings are sent to the standard error stream.

--errors=[<error-file>]
Set the destination for error messages to be "error-file". If "error-file" is omitted, then all error messages are ignored.

If this parameter is not given, then error messages are sent to the standard error stream.

--errors-and-warnings=[<error-file>]
Set the destination for both error and warning messages to be "error-file". If "error-file" is omitted, then all such messages are ignored.
--no-line-numbers
By default, diagnostics will include the line number where the error was detected. This option turns off this facility.

The intention is to save memory when processing very large files.

--warning-threshold=<number>
Do not display any warning messages once more than <number> warnings have been displayed. The default value is 25.

Setting this value to a negative number means that all warning messages will be displayed. Setting it to zero means that no warning messages will ever be displayed.

--treat-warnings-as-errors
Treat warnings as if they were recoverable errors.
--recover-silently
When a recoverable error occurs, take the appropriate recovery action, but do not issue any diagnostic message.

The default is to take the appropriate recovery action and issue a diagnostic message.

--do-not-recover
Treat all recoverable errors as fatal errors.

The default is to take the appropriate recovery action and issue a diagnostic message.

--error-threshold=<number>
Do not display any messages for recoverable errors once more than <number> recoverable errors have been displayed. The default value is 25.

Setting this value to a negative number means that all recoverable error messages will be displayed.

OASIS Entity Resolution Technical Committee XML catalogs

The following options control the use of OASIS ETRC XML catalogs

--no-catalogs
Do not use OASIS ERTC XML catalogs for entity resolution or URI reference resolution.
--no-default-catalog
Do not use the system default catalog.

In this case, only catalogs specified by the environment variable XM_CATALOG_FILES, plus any per-document-catalogs named in oasis-xml-catalog processing instructions, are searched.

--prefer-system
Prefer SYSTEM ids to PUBLIC ids when both are given. The catalog resolver only attempts to match on PUBLIC ids when there is either no SYSTEM id given, or else the catalog resolver fails to find a match for the SYSTEM id.

In the latter case, when this option is given, PUBLIC entries are only considered for a match if they were defined when prefer="system" was in effect.

The default is to always consider PUBLIC ids, when no match is found for the SYSTEM id.

If no SYSTEM id is given, then this option has no effect.

--no-catalog-pi
Ignore any oasis-xml-catalog processing instructions in source documents and stylesheets.
--catalog-debug-level=<0-10>
Set the level of debugging messages produced by the catalog resolver. 0 means no messages. 10 Means maximum verbosity.

Performance

The following options are available for performance tuning:

--no-gc
Disables garbage collection. This might improve performance under some circumstances. Or it might make it worse.
--tiny-tree
The source document is built using the tiny-tree model, rather than the standard tree model. This saves on memory, but will often result in slower execution. But with some tranformations, such as the identity transform, it may actually improve execution speed.
--report-document-statistics
Report statistics about the source document (and for each document read by the doc() and document() functions). This only applies when the tiny-tree option is selected.

This option is useful for choosing values for the nodes, attributes, namespaces and characters options.

--nodes=[estimated-node-count]
The estimated number of nodes (excluding attributes and namespaces) in the source document (and for each document read by the doc() and document() functions). This only applies when the tiny-tree option is selected.

If omitted, this defaults to 4000.

--attributes=[estimated-attribute-count]
The estimated number of attributes in the source document (and for each document read by the doc() and document() functions). This only applies when the tiny-tree option is selected.

If omitted, this defaults to 100.

--namespaces=[estimated-namespace-count]
The estimated number of namespaces in the source document (and for each document read by the doc() and document() functions). This only applies when the tiny-tree option is selected.

If omitted, this defaults to 20.

--characters=[estimated-character-count]
The estimated number of content characters in the source document (and for each document read by the doc() and document() functions). This only applies when the tiny-tree option is selected.

If omitted, this defaults to 4000.

Media types and URI fragment identifiers

The following options affect the mapping of URIs onto media-types, for interpretation of fragment identifies:

--html-text-ok
By default, gexslt assumes that a web server is serving up XHTML documents as media type text/html (to get round the fact that MSIE does not recognize application/xhtml+xml). So if it sees a media type of text/html, it pretends that it is actually application/xhtml+xml. Using this option means it respects the media type as text/html. The result is that this is a media type that the program chooses not to recognize, so you will get recoverable error XTRE1160.

Without this option, it might be argued that gexslt is non-compliant. Apart from that, it doesn't serve any useful purpose.

Extensions

The following options control the availability of extensions:

--no-output-extensions
Disables use of QNames for the value of the xsl:output method attribute.
--no-extension-functions
Disables use of extension functions.

Miscellaneous

--time
Print timing information for each phase on standard error stream.
--suppress-dtd
Prevent the XML parser from reading external DTDs. This applies to the fn:document(), fn:doc() and fn:collection() functions, as well to the principal source document and all transformation modules.
--force-explaining
Act as if the principal stylesheet module had a gexslt:explain="all" attribute coded.
--digits=[maximum_decimal_digits]
Maximum number of digits permitted in xs:decimal and xs:integer values. Default (and minimum) is 18.
--user
User name for HTTP basic authentication.
--password
Password for HTTP basic authentication.
--no-network-protocols
Disables use of any URI schemes that imply access to the outside world (e.g. http, ftp and telnet) that might otherwise be registered.

Execution phases

--stop-after-compilation
Compile the stylesheet, but do not parse the principal source document, and do not execute the transformation.
--stop-after-source-document
Compile the stylesheet, and parse the principal source document, but do not execute the transformation.

Copyright © 2004, Colin Adams and others
mailto:colin@colina.demon.co.uk
http://www.gobosoft.com
Last Updated: Sunday, September 5th, 2004
HomeTocPreviousNext