key

Syntax

key name {
    match pattern;
    value expression;
}

Description

Define a key for use with the key() XPath function. Keys are an alternative to IDs and are used to index the nodes within an XML document. The key must be defined as a top-level statement in the script. A key definition consists of the key identifier, the nodes to index, and the value that is paired with the key name to reference the matching nodes. The key() function is then used to locate the appropriate nodes.

The key() function works with the XML document of the current node and uses the specified key definition to retrieve nodes that are referenced by a particular name and value. The function arguments are the key name and the desired key’s value. The return value is a node set that includes all nodes referenced by that key name and value. If the desired key value is provided as a node set, rather than a string, the returned node set is a union of all the referenced nodes for the key values expressed by the nodes within the node set.

For example, if you define the key:

key func {
    match prototype;
    value @name;
}

the following code would select <prototype> elements that have a name attribute with a value of "trace", and then output the value of the child element <return-type>:

for-each ( key("func", "trace") ) {
    <out> return-type/.;
}

Attributes

SLAX Example

The following op script creates two key definitions, protocol and next-hop, which are used to retrieve and display all static routes and all routes with a next hop of ge-0/0/0.0 on a device. The script invokes the Junos XML API get-route-information command to obtain the route information for the device. The for-each( $results ) statement changes the current node to the $results XML document. The subsequent for-each loops use the keys to retrieve all nodes that are indexed according to the key names and values.

The for-each( key( "protocol", "Static" ) statement uses the protocol key definition, which matches on route-table/rt elements, to retrieve the desired nodes. The rt-entry/protocol-name key value matches the <protocol-name> child elements that have the value "Static". The code block executes using <rt> as the context node. For each match, the script outputs the value of the <rt-destination> element.

The for-each( key( "next-hop", "ge-0/0/0.0" ) statement uses the "next-hop" key definition, which matches on route-table/rt elements, to retrieve the desired nodes. The rt-entry/nh/via key value matches the <via> child elements that have the value "ge-0/0/0.0". The code block executes using <rt> as the context node. For each match, the script outputs the value of the <rt-destination> element.

version 1.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";

key protocol {
  match route-table/rt;
  value   rt-entry/protocol-name;
}
key next-hop {
  match route-table/rt;
  value   rt-entry/nh/via;
}

match / {
    <op-script-results> {
        var $results = jcs:invoke("get-route-information");  
        
        for-each( $results ) {
           /* Display all static routes */
           <output> "Static routes: ";
           for-each( key( "protocol", "Static" ) ) {
              <output> rt-destination;
           }
           /* Display all routes with next-hop of ge-0/0/0.0 */
           <output> "Next-hop ge-0/0/0.0: ";
           for-each( key( "next-hop", "ge-0/0/0.0" ) ) {
               <output> rt-destination;
           }
        }
    }
}

Release Information

Statement introduced in version 1.1 of the SLAX language, which is supported in Junos OS Release 12.2 and later releases.