1. Manuals
  2. Tumbleweed
  3. saxon10-scripts
  4. gizmo10(1)

Scroll to navigation

SAXON10.GIZMO(1) User Commands SAXON10.GIZMO(1)

NAME

gizmo - Saxon command-line interactive or batch-mode utility

SYNOPSIS

gizmo [options]

DESCRIPTION

Saxon (from 10.0) provides the Gizmo command line utility, which can be used interactively or in batch mode, to perform simple operations such as examining the content of a document, renaming or deletion of selected elements in the document, or performing simple XSLT transformation and XSD validation.

The utility can be started from the command line using the Java entry-point class net.sf.saxon.Gizmo, and its actions are controlled by sub-commands entered one per line, either on the standard input, or in a file named in the -q option.

OPTIONS

Defines the source document supplied as the input to the pipeline of sub-commands. If omitted, input is taken from standard input.
Identifies a filename containing sub-commands to be executed, one per line. By default, sub-commands are taken from standard input.

COMMANDS

Each line of input is a sub-command. The various sub-commands are listed in the following sections.

At any point in the processing, there is (or is not) a current document. On entry, the current document is the source document identified in the -s option, if specified. Many of the sub-commands change the current document. The current document may be inspected using the show sub-command, and may be saved to filestore using the save sub-command.

Most of the sub-commands select nodes within the current document using an XPath expression. If unprefixed element names appear within the expression, they match nodes in the source document by local-name alone. (That is, X means *:X). If you only want to select no-namespace names, use the form Q{}X.

Within XPath expressions, content completion is available for (a) recognized XPath keywords such as “following-sibling”, and (b) the names of elements and attributes appearing in the current source document when it was first loaded.

Some of the sub-commands also have a second argument which is a query. Generally this will be an XQuery element constructor such as <a>Title: {string(.)}<a/>. It is evaluated with the context item set to each item selected by the first expression, in turn.

Deletes everything other than the nodes selected by the expression; returns a new document containing only the selected nodes. Note that if the expression selects multiple elements, the new document will not be a well-formed XML document (it will be a "fragment").

The result of the operation can be inspected using the command show.

Example

The command:

        copy //img

returns a document containing as its children copies of all the img elements in the source.

Executes the script contained in the specified file.

The script shares the context with the calling script. It has access to the variables and namespaces declared in the calling script, and any variables and namespaces that it declared are available to the caller on return.

The selected nodes (elements, attributes, or namespaces) are deleted, along with their children and descendants.

The result of the operation can be inspected using the command show.

Example

Given a source document:

        <cities>
          <city name="Berlin" country="DE"/>
          <city name="Paris" country="FR"/>
          <city name="Rome" country="IT"/>
        </cities>

The command:

        delete //city[@name='Rome']

produces the document:

        <cities>
          <city name="Berlin" country="DE"/>
          <city name="Paris" country="FR"/>
        </cities>
After each node N selected by the expression, the query is evaluated (with N as the context item), and its result is inserted as an immediate following sibling of N. Both the expression and the query must return nodes that are capable of having siblings: that is, element, text, comment, or processing instruction nodes. But if the query returns an atomic value, it is treated as a text node with the same string value.

The result of the operation can be inspected using the command show.

Examples

The command:

        follow //img with <caption/>

inserts an empty C<caption/>> element after every img element in the document.

Given a source document:

        <cities>
          <city name="Berlin" country="DE"/>
          <city name="Paris" country="FR"/>
          <city name="Rome" country="IT"/>
        </cities>

The command:

        follow //city[@name='Paris'] with <city name="Lyon" country="{@country}"/>

produces the document:

        <cities>
          <city name="Berlin" country="DE"/>
          <city name="Paris" country="FR"/>
          <city name="Lyon" country="FR"/>
          <city name="Rome" country="IT"/>
        </cities>
If the keyword is the name of a command, a brief summary of the syntax and purpose of the command is displayed.

If the keyword is omitted, a list of available commands is displayed.

Outputs a representation of the result of the expression.

If a node is selected, it is shown as a path (for example DOC/SECTION[3]/PARA[2]), preceded by a line number if one is available.

If an atomic value is selected, its string value is displayed.

Line numbers are available in documents loaded directly from filestore, but not in documents constructed using commands such as rename or delete.

Example

Given a source document:

        <cities>
          <city name="Berlin" country="DE"/>
          <city name="Paris" country="FR"/>
          <city name="Rome" country="IT"/>
        </cities>

The command:

        list //city[@name='Paris']

displays:

        Line 3: /cities/city[2]
The current document is discarded, and a new current document is loaded from the specified file.

If the filename is relative, it is taken as being relative to the current working directory.

The user’s home directory can be referred to as ~.

Content completion is available: use the tab key to suggest possible names at each level.

Binds a namespace prefix to a URI. QNames using this prefix may be used in subsequent XPath expressions within the script.

Note that the conventional prefixes xml, xsl, saxon, xs, xsi, fn, math, map, and array are already bound to the conventional namespace URIs.

In path expressions, unprefixed names match by local name only, so it is usually possible to select elements without binding a namespace prefix.

Outputs a list of the distinct element paths that exist in the current source document. They are output in order of first appearance, when scanning the tree in document order.

This command is useful to get an overview of the structure of the source document, especially if it is too large to display comfortably.

Example

For example, given the books.xml data file included with the Saxon resources download, the output would be:

      Found 16 items
      /BOOKLIST
      /BOOKLIST/BOOKS
      /BOOKLIST/BOOKS/ITEM
      /BOOKLIST/BOOKS/ITEM/TITLE
      /BOOKLIST/BOOKS/ITEM/AUTHOR
      /BOOKLIST/BOOKS/ITEM/PUBLISHER
      /BOOKLIST/BOOKS/ITEM/PUB-DATE
      /BOOKLIST/BOOKS/ITEM/LANGUAGE
      /BOOKLIST/BOOKS/ITEM/PRICE
      /BOOKLIST/BOOKS/ITEM/QUANTITY
      /BOOKLIST/BOOKS/ITEM/ISBN
      /BOOKLIST/BOOKS/ITEM/PAGES
      /BOOKLIST/BOOKS/ITEM/DIMENSIONS
      /BOOKLIST/BOOKS/ITEM/WEIGHT
      /BOOKLIST/CATEGORIES
      /BOOKLIST/CATEGORIES/CATEGORY
Before each node N selected by the expression, the query is evaluated (with N as the context item), and its result is inserted as an immediate preceding sibling of N. Both the expression and the query must return nodes that are capable of having siblings: that is, element, text, comment, or processing instruction nodes. But if the query returns an atomic value, it is treated as a text node with the same string value.

The result of the operation can be inspected using the command show.

Examples

The command:

        precede //img with <caption/>

inserts an empty <caption/> element before every img element in the document.

Given a source document:

        <cities>
          <city name="Berlin" country="DE"/>
          <city name="Munich" country="DE"/>
          <city name="Paris" country="FR"/>
          <city name="Lyon" country="FR"/>
          <city name="Rome" country="IT"/>
        </cities>

The command:

        precede //city[not(@country=preceding-sibling::*[1]/@country)] with <country name="{@country}"/>

produces the document:

        <cities>
          <country name="DE"/>
          <city name="Berlin" country="DE"/>
          <city name="Munich" country="DE"/>
          <country name="FR"/>
          <city name="Paris" country="FR"/>
          <city name="Lyon" country="FR"/>
          <country name="IT"/>
          <city name="Rome" country="IT"/>
        </cities>
For every node N selected by the expression, the query is evaluated (with N as the context item), and its result is inserted as the first child of N. The expression must return nodes that are capable of having children (that is document or element nodes). The query must return nodes that are capable of having siblings (that is, element, text, comment, or processing instruction nodes). But if the query returns an atomic value, it is treated as a text node with the same string value.

As a special case, if the query returns an attribute node, it is added as an attribute of the selected element, replacing any existing attribute with the same name.

The result of the operation can be inspected using the command show.

Examples

The command:

        prefix //section with <head>{data(@title)}</head>

copies the value of the title attribute of every section element into a new head element appearing as the first child of the section.

Given a source document:

        <cities>
          <city name="Berlin" country="DE"/>
          <city name="Munich" country="DE"/>
          <city name="Paris" country="FR"/>
          <city name="Lyon" country="FR"/>
          <city name="Rome" country="IT"/>
        </cities>

The command:

        prefix //city with <country name="{@country}"/>

produces the document:

        <cities>
          <city name="Berlin" country="DE">
                <country name="DE"/>
          </city>  
          <city name="Munich" country="DE">
                <country name="DE"/>
          </city>  
          <city name="Paris" country="FR">
                <country name="FR"/>
          </city>  
          <city name="Lyon" country="FR">
                <country name="FR"/>
          </city>  
          <city name="Rome" country="IT">
                <country name="FR"/>
          </city>  
        </cities>

With the same document, the command:

        prefix //city with attribute{'id'}{count(preceding-sibling::*)+1}

produces:

        <cities>
          <city name="Berlin" country="DE" id="1"/>
          <city name="Munich" country="DE" id="2"/>
          <city name="Paris" country="FR" id="3"/>
          <city name="Lyon" country="FR" id="4"/>
          <city name="Rome" country="IT" id="5"/>
        </cities>
Quits the application.

If “now” is specified, the command exits immediately. Otherwise, if the current document has been modified since it was read from filestore, the command prompts the user asking whether the document should first be saved. (See the save command).

Nodes (elements or attributes) selected by the first expression are renamed; the new name is given by computing the expression in the second argument.

The second expression is evaluated with the existing node as the context item. If the result of the expression is a string, then this string is used as the new name of the node (if it contains a prefix, this must first be declared using the namespace command). If the result of the expression is a QName, then it defines the expanded name of the new element or attribute in its entirety. New namespace declarations will be added to the output document if required; existing namespace declarations are not removed, unless new bindings are defined for existing prefixes.

Examples

        rename //NOTE as "COMMENT"

renames all NOTE elements as COMMENT elements.

        rename //@* as lower-case(name())

renames all attributes by converting the existing name to lower-case.

The nodes (elements or attributes) selected by the given expression are replaced by the result of evaluating the query.

Note that it is the entire node that is replaced, not just its content. To replace the content of an element or attribute node, rather than replacing the entire node, use the command update.

The result of the operation can be inspected using the command show.

Examples

Given a source document:

        <cities>
          <city name="Berlin" country="DE"/>
          <city name="Munich" country="DE"/>
          <city name="Paris" country="FR"/>
          <city name="Lyon" country="FR"/>
          <city name="Rome" country="IT"/>
        </cities>

The command:

        replace //city[@country="DE"] with <stadt @Name="{@name}"/>

produces the document:

        <cities>
          <stadt Name="Berlin"/>
          <stadt Name="Munich"/>
          <city name="Paris" country="FR"/>
          <city name="Lyon" country="FR"/>
          <city name="Rome" country="IT"/>
        </cities>

Given a source document:

        <cities>
          <city><name>Berlin</name><country>DE</country></city>
          <city><name>Munich</name><country>DE</country></city>
          <city><name>Paris</name><country>FR</country></city>
          <city><name>Lyon</name><country>FR</country></city>
          <city><name>Rome</name><country>IT</country></city>
        </cities>

The command:

        replace //city/name[.="Munich"]/text() with "München"

produces the document:

        <cities>
          <city><name>Berlin</name><country>DE</country></city>
          <city><name>München</name><country>DE</country></city>
          <city><name>Paris</name><country>FR</country></city>
          <city><name>Lyon</name><country>FR</country></city>
          <city><name>Rome</name><country>IT</country></city>
        </cities>

With the same source document, the command:

        replace //name with {.}

produces the document:

        <cities>
          <city><cityName><name>Berlin</name></cityName><country>DE</country></city>
          <city><cityName><name>Munich</name></cityName><country>DE</country></city>
          <city><cityName><name>Paris</name></cityName><country>FR</country></city>
          <city><cityName><name>Lyon</name></cityName><country>FR</country></city>
          <city><cityName><name>Rome</name></cityName><country>IT</country></city>
        </cities>

Note that in this expression, {.} follows the XQuery rules rather than the XSLT rules: it copies the whole element, rather than extract its string value.

Saves the current document to filestore, with the serialization parameters specified.

If the file already exists, Gizmo asks “Overwrite existing file? (Y|N)” and proceeds only if the answer is “Y” or “y”.

If the filename is relative, it is taken as being relative to the current working directory.

The user’s home directory can be referred to as ~.

Content completion is available: use the tab key to suggest possible names at each level.

Examples

The command:

        save updated-data.xml method=xml indent=yes

saves the document to filestore using the XML output method with indentation.

Requires Saxon-EE

Loads an XSD schema from the specified location.

The filename is handled in the same way as the load command.

The schema definitions are available for use in validate commands issued subsequently in the session. The command is additive; the schema components are added to the collection of schema components that are already loaded, which means an error will be reported if the definitions conflict. It is not possible to unload schema definitions once loaded, except by closing the session and starting a new one.

The first form binds a variable to the value of the expression. The variable name may be written as a simple NCName, or as a lexical QName, or as an EQName in Q{uri}local format; it may also be preceded by a “$” sign (which is ignored).

The variable may be used in XPath expressions and queries appearing later in the script.

The second form: set . = expression may be used to set the current document. In this case the expression must evaluate to a single document node. For example:

        set . = doc('books.xml')

achieves the same effect as:

        load books.xml

Note that all updating commands (such as delete, rename etc.) create a new copy of the current document. Variables that were set before the updating command continue to reference the document in the state it was in before the update.

To display the value of a variable, use the show or list commands.

Outputs a representation of the result of the expression.

If a node is selected, it is shown as an XML serialization of the content of the node.

If an atomic value is selected, its string value is displayed.

The expression may be omitted, and defaults to /, which displays the current document.

The document is always shown with indentation enabled, so it is not necessarily the same as the document that will be written to filestore by the save command.

Examples

        show

Displays the current document, with indentation.

        show //TITLE

Displays selected elements, for example:

        <title>Pride and Prejudice</title>
        <title>Sense and Sensibility</title>
        <title>Emma</title>
        <title>Northanger Abbey</title>
        show count(//TITLE), sort(//TITLE)

Displays the result of an arbitrary XPath expression.

The effect is the same as: 

        delete //text()[not(normalize-space())]

That is, all text nodes consisting entirely of whitespace are removed from the document.

For every node N selected by the expression, the query is evaluated (with N as the context item), and its result is inserted as the last child of N. The expression must return nodes that are capable of having children (that is document or element nodes). The query must return nodes that are capable of having siblings (that is, element, text, comment, or processing instruction nodes). But if the query returns an atomic value, it is treated as a text node with the same string value.

Example

The command:

        suffix //page with <copyright>Copyright (c) Saxonica 2020</page>

injects a copyright element at the end of every page.

Transforms the current document using the XSLT stylesheet contained in the specified file.

The filename is handled in the same way as the load command.

On completion, the result of the transformation becomes the new current document.

Note: it is not currently possible to specify parameters to the transformation.

Reverts the most recent changes.

The current document is returned to the state it was in before the most recent copy, delete, follow, load, precede, prefix, rename, replace, strip, suffix, transform, update, or validate command.

It will also undo the effect of:

        set . = expression

that is, it reverts to the previous current document.

It is not possible to undo the effect of save or schema commands.

The content of the nodes selected by the given expression is replaced by the result of evaluating the query:
·
When an element or document node is selected, the existing children are deleted, and replaced with the result of the expression.
·
When the selected element is a node kind that cannot have children, for example a comment, text node, or attribute, then its content is replaced with the string value of the query result.

Examples

Given the source document:

        <cities>
          <city name="Berlin" country="DE"/>
          <city name="Munich" country="DE"/>
          <city name="Paris" country="FR"/>
          <city name="Lyon" country="FR"/>
          <city name="Rome" country="IT"/>
        </cities>

The command:

        update //@country[.='IT'] with "ITALIA"

produces:

        <cities>
          <city name="Berlin" country="DE"/>
          <city name="Munich" country="DE"/>
          <city name="Paris" country="FR"/>
          <city name="Lyon" country="FR"/>
          <city name="Rome" country="ITALIA"/>
        </cities>

Given a source document:

        <cities>
          <city><name>Berlin</name><country>DE</country></city>
          <city><name>Munich</name><country>DE</country></city>
          <city><name>Paris</name><country>FR</country></city>
          <city><name>Lyon</name><country>FR</country></city>
          <city><name>Rome</name><country>IT</country></city>
        </cities>

The command:

        update //city/name[.="Munich"] with "München"

produces the document:

        <cities>
          <city><name>Berlin</name><country>DE</country></city>
          <city><name>München</name><country>DE</country></city>
          <city><name>Paris</name><country>FR</country></city>
          <city><name>Lyon</name><country>FR</country></city>
          <city><name>Rome</name><country>IT</country></city>
        </cities>

With the same source document, the command:

        update //@country with lower-case(.)

produces:

        <cities>
          <city><name>Berlin</name><country>de</country></city>
          <city><name>Munich</name><country>de</country></city>
          <city><name>Paris</name><country>fr</country></city>
          <city><name>Lyon</name><country>fr</country></city>
          <city><name>Rome</name><country>it</country></city>
        </cities>
Requires Saxon-EE

Validates the current document using the XSD schema(s) previously loaded using the schema command, supplemented with any schema found via an xsi:schemaLocation or xsi:noNamespaceSchemaLocation attribute in the source document.

On completion, the validated result (complete with type annotations) becomes the new current document. Any expressions and queries executed against a typed document are treated as schema-aware.

If validation fails, the validation error messages are output, and the current document remains unchanged.

SEE ALSO

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

AUTHOR

Michael H. Kay <mike@saxonica.com>

2023-09-27 saxon10 10.9