Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Understanding the SLAX Processor (slaxproc)

 

slaxproc Overview

The libslax distribution contains the libslax library, which incorporates a SLAX writer and SLAX parser, a debugger, a profiler, and the SLAX processor (slaxproc). The SLAX processor is a command-line tool that can validate SLAX script syntax, convert between SLAX and XSLT formats, and format, debug, or run SLAX scripts.

The SLAX processor is invoked on the command line using the slaxproc command. The slaxproc command accepts command-line arguments that specify the mode of the processor, any behavioral options, and required input and output files.

The syntax for the slaxproc command is:

The slaxproc mode defines what function the processor performs. slaxproc options include file options and common options. File options are used to specify the script file, input file, output file, and trace file. Common options include additional functionality provided by the SLAX processor such as verbose debugging output.

You can access the slaxproc help by issuing the slaxproc command with the --help or -h option.

For more information about the SLAX processor, see slaxproc: The SLAX Processor.

slaxproc Modes

The slaxproc mode defines what function the processor performs. The default mode is --run or -r. If you do not explicitly specify a mode, the SLAX processor executes a script. Table 1 outlines the slaxproc modes and their functions.

Table 1: Slaxproc Modes

Mode

Description

--check

 -c

Perform a syntax and content check on a SLAX script, reporting any errors. This mode is useful for off-box syntax checks before installing or uploading scripts to a device running Junos OS.

--format

 -F

Format a SLAX script, correcting indentation and spacing to the preferred style.

--json-to-xml

Transform JSON input into XML using the conventions defined in http://juniper.github.io/libslax/slax-manual.html#json-elements.

--run

 -r

Run a SLAX script. This is the default mode. The script name, input filename, and output filename can be provided using command-line options, positional arguments, or a mix of both. Input defaults to standard input, and output defaults to standard output.

--show-select

Show an XPath selection from the input document. This mode is used to extract out selections from a script for external consumption. This enables the consumer to avoid a SLAX parser but still have visibility into the contents of the script.

--show-variable

Show the contents of a global variable. This mode is used to extract static variable contents for external consumption. This enables the consumer of the data to avoid a SLAX parser but still have access to the static contents of global variables, such as the $arguments variable.

--slax-to-xslt

 -x

Convert a SLAX script into XSLT format. The script filename and output filename are provided using command-line options, positional arguments, or a mix of both.

--xml-to-json

Convert XML into JSON using the conventions defined in http://juniper.github.io/libslax/slax-manual.html#json-elements.

--xpath xpath

 -X xpath

Select data from the input document that matches the given XPath expression.

--xslt-to-slax

 -s

Convert an XSLT script into SLAX format. The script filename and output filename are provided using command-line options, positional arguments, or a mix of both.

slaxproc Options

The slaxproc options include file options and common options. File options are used specify the script file, input file, output file, and trace file. Common options include additional functionality and options provided by the SLAX processor such as verbose debugging output. Table 2 lists the slaxproc common options and file options.

Table 2: slaxproc Common Options and File Options

Option

Description

--debug

 -d

Enable the SLAX/XSLT debugger.

--empty

 -E

Provide an empty document as the input data set. This is useful for scripts that do not expect or need meaningful input.

--expression <expr>

Convert a SLAX expression to an XPATH expression, or vice versa, depending on the presence of --slax-to-xslt or --xslt-to-slax.

--exslt

 -e

Enable the EXSLT library, which provides a set of standard extension functions. See http://www.exslt.org for more information.

--help

 -h

Display the help message and exit.

--html

 -H

Parse input data using the HTML parser, which differs from XML.

--ignore-arguments

Do not process any further arguments. This can be combined with #! to enable distinct styles of argument parsing.

--include <dir>

 -I <dir>

Add a directory to the list of directories searched when using include and import files. Alternatively, you can define the SLAXPATH environment variable to specify a colon-delimited list of directories to search.

--indent

 -g

Indent output. This option is identical to the behavior triggered by output-method { indent 'true'; }.

--input <file>

 -i <file>

Read input from the specified file.

--json-tagging

Tag JSON elements with the 'json' attribute as the input is converted to XML. This enables you to use the --format mode to transform the data back into JSON format.

--keep-text

When building a script from mini templates, do not add a template to discard normal text. By default, XSLT displays unmatched text data. This option preserves the default behavior instead of replacing it with the discard action.

--lib <dir>

 -L <dir>

Adds a directory to the list of directories searched when using extension libraries.

Alternatively, you can define the SLAXEXTPATH environment variable to specify a colon-delimited list of extension library locations to search.

--log <file>

Write log data to the given file.

--mini-template <code>

 -m <code>

Pass a simple script in through the command line. The argument is typically a template, such as a named or match template.

--name <file>

 -n <file>

Read the SLAX script from the specified file.

--no-json-types <dir>

Omit type attributes when using slaxproc mode --json-to-xml to transform JSON input into XML.

--no-randomize

Do not initialize the random number generator. This is useful if you want the script to return identical data for a series of invocations. This option is typically only used during testing.

--no-tty

Do not use tty for the SLAX debugger and other tty-related input needs.

--output <file>

 -o <file>

Write output to the specified file.

--param <name> <value>

 -a <name> <value>

Pass a parameter to the script using the name and value pair provided. All parameters are string parameters, so normal quoting rules apply.

--partial

 -p

Allow the input data to contain a partial SLAX script, which can be used with the ‑‑slax‑to‑xslt or -x mode to perform partial transformations.

--slax-output

 -S

Write the results using SLAX-style XML.

--trace <file>

 -t <file>

Write trace data to the specified file.

--verbose

 -v

Add verbose internal debugging output to the trace data output, including calls to the slaxLog() function.

--version

 -V

Show version information and exit.

--write-version <version>

 -w <version>

Write the specified version number to the output file when converting a script using the --xslt-to-slax or -s mode.

This option can be used to limit the conversion to only use features in certain versions of SLAX. Acceptable values are 1.0, 1.1, 1.2. If this option is not specified, the SLAX script version defaults to the latest version.

slaxproc File Argument Handling

For all modes except check, you have the option to reference file arguments positionally or use the file options to specify input and output files. If you use the file options, the files can be referenced in any order on the command line, and the file options can be interspersed among other command-line options.

If no input file is required, use the -E option to indicate an empty input document. Additionally, if the input or output option argument has the value "‑", the standard input or standard output file is used. When using standard input, press Ctrl+d to signal the end-of-file.

To reference files positionally on the command line, specify the script file first if it is required for that mode, then specify the input file, and lastly specify the output file. Referencing the files positionally allows slaxproc to be plug compatible with xsltproc.

To reference files using explicit file option values, include --name or -n, --input or -i, and --output or -o, to specify the SLAX script file, and the input and output files, respectively.

If a file option is not provided, the filename is parsed positionally. In the following command, the input and output filenames are specified using the file options, but the script filename is referenced positionally:

To execute a script that requires no input file, include the -E option to indicate an empty input document.

slaxproc UNIX Scripting Support

SLAX supports the shebang construct (#!), allowing the first line of a script to begin with the characters "#" and "!" followed by a path to the executable that runs the script and a set of command-line arguments. For example:

The operating system adds the name of the scripts and any command-line arguments to the command line that follows the "#!". Adding the ‑n option allows additional arguments to be passed in on the command line. Flexible argument parsing allows aliases. For example, if the first line of the script is:

additional arguments can be provided:

and the resulting command becomes:

If the input or output argument has the value "‑", the standard input or standard output file is used. This enables slaxproc to be used as a traditional UNIX filter.