[j-nsp] understand "version" and "ns"(namespace) statements in SLAX scripts

[Phil Shafer]

Martin T writes:
>While I understand the idea of namespace in XML, then what is the
>point of those statements in SLAX scripts? In addition, how does the
>"version" statement work?

The version statement indicates the version of SLAX being used.  It
also confirms that the input is in fact a slax script.

There are currently three minor revisions of SLAX: 1.0, 1.1, and 1.2.
1.2 is completely backward compatible with 1.0 and 1.1, and 1.1 is
completely backward compatible with 1.0.

SLAX-1.1 adds all XSLT concepts directly to SLAX, where in 1.0 one
had to use the "xsl" namespace to access them (e.g. <xsl:element>),
as well as a debugger.  Details are in:

    https://github.com/Juniper/libslax/wiki/NewIn1-1

I don't have as nice a write up for 1.2, but it adds two key things:
JSON-style data and data as arguments.  These allow code like:

    var $x = {
        "this": "that",
        "one": 1
    }
    call my-template($rpc = <get-interface-information>);

There also a "main" statement that allows one to say:

    main <op-script-results> {
        call emit-my-output();
    }

Note that the "--write-version" option to slaxproc can be used
to convert between versions:

    % cat /tmp/foo.slax
    version 1.2;
    
    main <op-script-results> {
        var $x = {
            "this": "that",
            "one": 1
        }
        call my-template($rpc = <get-interface-information>);
    }
    % slaxproc --format --write-version 1.0 /tmp/foo.slax
    version 1.0;
    
    match / {
        <op-script-results> {
            var $x = {
                <this> "that";
                <one type="number"> "1";
            }
            var $slax-temp-arg-1 = <get-interface-information>;
    
            call my-template($rpc = slax-ext:node-set($slax-temp-arg-1));
        }
    }

>ns junos = "http://xml.juniper.net/junos/*/junos";
>ns xnm = "http://xml.juniper.net/xnm/1.1/xnm";
>ns jcs = "http://xml.juniper.net/junos/commit-scripts/1.0";
>ns ext = "http://xmlsoft.org/XSLT/namespace";

The "ns" statement defines XML namespaces using the xmlns attribute.
The SLAX docs for it are here:

    http://juniper.github.io/libslax/slax-manual.html#ns

and the XSLT docs are here:

    http://www.w3.org/TR/xml-names11/#concepts

Note that the junos namespace is a bit "magic", in that when the
jcs:invoke and jcs:execute functions read data, they convert between
the version-specific namespace used by JUNOS into the "/*/" value
used above in the "ns junos" statement.  This removes the burden/pain
of namespaces and makes them much more useful.

Also in SLAX-1.2, namespaces are a bit simplified, so a script does
not need to explicitly name a namespace that implements extension
functions, since the extension function libraries will record their
information when they are installed.  For example, the "curl" and "bit"
namespaces (used to access libraries that ship with libslax) are automatically
discovered without the need for an explicit "ns" statement.  You
can see these discovered values using "slaxproc --format":

    % cat /tmp/foo.slax
    version 1.2;
    
    main <op-script-results> {
        expr bit:from-int(32, 10);
    }
    % slaxproc --format /tmp/foo.slax
    version 1.2;
    
    ns bit extension = "http://xml.libslax.org/bit";
    
    main <op-script-results> {
        expr bit:from-int(32, 10);
    }

The full docs for slax are available as part of the libslax
project on github:

   http://juniper.github.io/libslax/slax-manual.html

The "juise" project adds the juniper-specific libraries and a
program (called juise) that simplifies invoking op scripts
against a junos box.

Thanks,
 Phil