Gestalt Command-line usage and options

 PreviousNext

How to invoke gestalt

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

The last form is not yet supported.

Stylesheet and source documents

The stylesheet and source documents can be written either as URIs or as names in the local file system. Gestalt 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 gestalt to interpret it as a file name by writing it as --file=my/file.name.

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

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, gestalt 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 an xml-stylesheet processing instruction within that source document, and use that to find the stylesheet.

Use of the xml-stylesheet processing instruction is not yet implemented

Gestalt has to parse the source document twice. Once to find the processing instructiuon, 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.

--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. If the name is not in the default namespace, then enclose the namespace URI in curly brackets, preceding the local name.

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. If the name is not in the default namespace, then enclose the namespace URI in curly brackets, preceding the local name.

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

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

You cannot use this option if you also supply the --template=<initial-template-name> option, and omit the source document, as then the XPath expression will have no context.

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.

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.
--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 in 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 usually result in slower execution, except for very simple tranformations, such as the identity transform, where it may actually improve execution speed.

This seems to have a memory leak at the moment, so it is probably best to avoid using it.

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.

Miscellaneous

--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.
Copyright © 2004, Colin Adams and others
mailto:colin@colina.demon.co.uk
http://www.gobosoft.com
Last Updated: Sunday, September 5th, 2004
HomeTocPreviousNext