Understanding the SLAX Processor (slaxproc)

The SLAX processor is a command-line tool that can format SLAX scripts; validate SLAX script syntax; run or debug SLAX scripts; and convert between SLAX and XSLT formats.

slaxproc Overview

The libslax library 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 enables you to perform the following functions:

Format SLAX scripts
Validate SLAX script syntax
Run and debug SLAX scripts
Convert between SLAX and XSLT formats

You use the slaxproc command to invoke the SLAX processor on the command line. The slaxproc command accepts command-line arguments that specify the processor's mode, 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. The 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.

The following sections discuss the available modes and options in more detail. For additional information about the SLAX processor, see slaxproc: The SLAX Processor.

slaxproc Modes

The slaxproc mode defines the function that 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 Junos device.
`--‍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`	(Default) Run a SLAX script. You can provide the script name, input filename, and output filename using command-line options, positional arguments, or a mix of both. Input defaults to standard input (stdin), and output defaults to standard output (stdout).
`--‍show-‍select`	Show an XPath selection from the input document. This mode extracts selections from a script for external consumption. Thus, the consumer has visibility into the contents of the script without using a SLAX parser.
`--show-‍variable`	Show the contents of a global variable. This mode extracts static variable contents for external consumption. Thus, the consumer of the data has access to the static contents of global variables, such as the `$arguments` variable, without using a SLAX parser.
`--‍slax-‍to-‍xslt` `-x`	Convert a SLAX script into XSLT format. You can provide the script filename and output filename 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.
`--xml-to-yaml`	Convert XML into YAML. This mode is introduced in SLAX version 1.3.
`--‍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. You can provide the script filename and output filename 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. Use this option 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 https://exslt.github.io/ 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. You can combine this option 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'; }`.
`--‍indent-width <spaces>`	Specify the number of spaces to use for code indentation when you format a SLAX script using the `format` mode. The default is four spaces. The SLAX processor adds the appropriate indentation for each line of the script. This option is introduced in SLAX version 1.3.
`--‍input <file>` `-i <file>`	Read input from the specified file.
`--‍json`	Emit the script output in JSON. This option is introduced in SLAX version 1.3.
`--‍json-‍tagging`	Tag JSON elements with the 'json' attribute as the input is converted to XML. By tagging the elements, you can 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. Use this option if you want the script to return identical data for a series of invocations. You typically only use this option 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.
(All SLAX versions) `--‍param <name> <value>` `-a <name> <value>` (SLAX 1.3 and later) `--‍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. Starting in SLAX version 1.3, you can also use the `<name>=<value>` syntax.
`--‍partial` `-p`	Allow the input data to contain a partial SLAX script. Use this option with the `‑‑slax‑to‑xslt` or `-x` mode to perform partial transformations.
`--profile <file>`	Run the profiler and save the output to the given file. This option is introduced in SLAX version 1.3.
`--profile-mode <mode>`	Run the profiler using the given mode, for example, `brief`. By default, the output is written to the file profile.output. To specify a different output file, include the `--profile <file>` option. This option is introduced in SLAX version 1.3.
`--‍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`	Print version information and exit. The output includes version information for SLAX, libslax, libxml, libxslt, and libexslt. The output includes the SLAX version starting in SLAX version 1.3.
`--version-only`	Print the SLAX version only. This option is introduced in SLAX version 1.3.
`--width <characters>`	Specify the maximum number of characters for the line length before wrapping when you format a SLAX script using the `format` mode. The formatter attempts to limit lines to this width. However, lengthy tokens might exceed the limit. This option is introduced in SLAX version 1.3.
`--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. Use this option to limit the conversion to only use features in certain versions of SLAX. If you do not specify this option, the SLAX script version defaults to the latest version supported on the device.

slaxproc Argument Handling

Starting with libslax 3.1.6 (SLAX version 1.3), slaxproc uses the getopts_long function for processing arguments. This change enables you to better handle multiple arguments and provides additional syntax for single arguments. Table 3 outlines the changes.

Table 3: Argument Handling in Different SLAX Versions
SLAX Version 1.2	SLAX Version 1.3 and later
Provide multiple options as separate arguments (`-E -g -d`)	Provide multiple options as separate arguments (-E -g -d) or Combine multiple options into a single argument (`-Egd`)
`--option value`	`--option value` or `--option=value`
`-o value`	`-o value` or `-ovalue`
`--param name value`	`--param name value` or `--param name=value`

For example, the following commands are identical. The second command combines the options into a single argument and uses the --option=value syntax.

The following commands, which format a partial SLAX script, are also identical. In the second command, the -i option omits the space between the flag and its value.

The following commands provide the max parameter and its value to the script.

slaxproc File Argument Handling

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

If the script does not require an input file, use the -E option to indicate an empty input document. Additionally, if the input or output argument has the value "‑", the processor uses stdin or stdout. When using stdin, press Ctrl+d to signal the end-of-file.

To reference files positionally, 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 the file options, 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 you do not provide a file option, slaxproc parses the filename positionally. The following command uses file options to specify the input and output filenames and references the script filename 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 (#!) to specify the executable path. The first line of the script begins with the characters "#!" followed by a path to the executable that runs the script and a set of command-line arguments. For example:

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

You can provide additional arguments as follows:

The resulting command becomes:

If the input or output argument has the value "‑", slaxproc uses stdin or stdout. Using stdin and stdout enables you to use slaxproc as a traditional UNIX filter.

ON THIS PAGE