README.extentions

Escaping of References and Inventory Queries
============================================

Reference and inventory queries can be escaped to produce literal strings, for example:

parameters:   
  colour: Blue
  unescaped: The colour is ${colour}
  escaped: The colour is \${colour}  
  double_escaped: The colour is \\${colour}


This would produce:           

parameters:   
  colour: Blue
  unescaped: The colour is Blue   
  escaped: The colour is ${colour}   
  double_escaped: The colour is \Blue



Merging Referenced Lists and Dictionaries
=========================================

Referenced lists or dicts can now be merged:

# nodes/test.yml
classes: 
  - test1
  - test2  
parameters:
  one:  
    a: 1
    b: 2
  two:  
    c: 3
    d: 4
  three:
    e: 5

# classes/test1.yml
parameters:    
  three: ${one}

# classes/test2.yml
parameters:    
  three: ${two}

running reclass.py --nodeinfo node1 then gives:

parameters:
  one:
    a: 1
    b: 2
  three:
    a: 1
    b: 2
    c: 3
    d: 4
    e: 5
  two:
    c: 3
    d: 4

This first sets the parameter three to the value of parameter one (class test1) then merges parameter two into
parameter three (class test2) and finally merges the parameter three definition given in the node definition into



Nested References
=================

References can now be nested, for example:

# nodes/node1.yml
parameters:
  alpha:
    one: ${beta:${alpha:two}}
    two: a
  beta:
    a: 99

reclass.py --nodeinfo node1 then gives:

parameters:
  alpha:
    one: 99
    two: a
  beta:
    a: 99

The ${beta:${alpha:two}} construct first resolves the ${alpha:two} reference to the value 'a', then resolves
the reference ${beta:a} to the value 99.



Inventory Queries
=================

Inventory querying works using a new key type - exports to hold values which other node definitions can read using a $[] query, for example with:

# nodes/node1.yml
exports:
  test_zero: 0
  test_one:
    name: ${name}
    value: 6
  test_two: ${dict}

parameters:
  name: node1
  dict:
    a: 1
    b: 2
  exp_value_test: $[ exports:test_two ]
  exp_if_test0: $[ if exports:test_zero == 0 ]
  exp_if_test1: $[ exports:test_one if exports:test_one:value == 7 ]
  exp_if_test2: $[ exports:test_one if exports:test_one:name == self:name ]

# nodes/node2.yml
exports:
  test_zero: 0
  test_one:
    name: ${name}
    value: 7
  test_two: ${dict}

parameters:
  name: node2
  dict:
    a: 11
    b: 22


running reclass.py --nodeinfo node1 gives (listing only the exports and parameters):

exports:
  test_one:
    name: node1
    value: 6
  test_two:
    a: 1
    b: 2
parameters:
  dict:
    a: 1
    b: 2
  exp_if_test0:
    - node1
    - node2
  exp_if_test1:
    node2:
      name: node2
      value: 7
  exp_if_test2:
    node1:
      name: node1
      value: 6
  exp_value_test:
    node1:
      a: 1
      b: 2
    node2:
      a: 11
      b: 22
  name: node1


Exports defined for a node can be a simple value or a reference to a parameter in the node definition.
The $[] inventory queries are calculated for simple value expressions, $[ exports:key ], by returning
a dictionary with an element ({ node_name: key value }) for each node which defines 'key' in the exports
section. For tests with a preceeding value, $[ exports:key if exports:test_key == test_value ], the
element ({ node_name: key value }) is only added to the returned dictionary if the test_key defined in
the node exports section equals the test value. For tests without a preceeding value,
$[ if exports:test_key == test_value ], a list of nodes which pass the test is returned. For either test
form the test value can either be a simple value or a node parameter. And as well as an equality test
a not equals test (!=) can also be used.

**Inventory query options**

By default inventory queries only look at nodes in the same environment as the querying node. This can be
overriden using the +AllEnvs option:

  $[ +AllEnvs exports:test ]

Any errors in rendering the export parameters for a node will give an error for the inventory query as a whole.
This can be overriden using the +IgnoreErrors option:

  $[ +IgnoreErrors exports:test ]

With the +IgnoreErrors option nodes which generate an error evaluating exports:test will be ignored.

Inventory query options can be combined:

  $[ +AllEnvs +IgnoreErrors exports:test ]

**Logical operators and/or**

The logical operators and/or can be used in inventory queries:

  $[ exports:test_value if exports:test_zero == 0 and exports:test_one == self:value ]

The individual elements of the if statement are evaluated and combined with the logical operators starting from the
left and working to the right.