Documentation updates
diff --git a/README-extentions.rst b/README-extentions.rst
new file mode 100644
index 0000000..31458b6
--- /dev/null
+++ b/README-extentions.rst
@@ -0,0 +1,289 @@
+Escaping of References and Inventory Queries
+--------------------------------------------
+
+Reference and inventory queries can be escaped to produce literal strings, for example:
+
+.. code-block:: yaml
+
+ parameters:
+ colour: Blue
+ unescaped: The colour is ${colour}
+ escaped: The colour is \${colour}
+ double_escaped: The colour is \\${colour}
+
+
+This would produce:
+
+.. code-block:: yaml
+
+ parameters:
+ colour: Blue
+ unescaped: The colour is Blue
+ escaped: The colour is ${colour}
+ double_escaped: The colour is \Blue
+
+
+
+Ignore class not found
+----------------------
+
+At some cases (bootstrapping, development) it can be convenient to ignore some missing classes.
+To control the feature there are two options available:
+
+.. code-block:: yaml
+
+ ignore_class_notfound: False
+ ignore_class_regexp: ['*']
+
+If you set regexp pattern to ``service.*`` all missing classes starting 'service.' will be logged with warning, but will not
+fail to return rendered reclass. Assuming all parameter interpolation passes.
+
+
+
+Merging Referenced Lists and Dictionaries
+-----------------------------------------
+
+Referenced lists or dicts can now be merged:
+
+.. code-block:: yaml
+
+ # 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:
+
+.. code-block:: yaml
+
+ 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
+the final value.
+
+
+
+Nested References
+-----------------
+
+References can now be nested, for example:
+
+.. code-block:: yaml
+
+ # nodes/node1.yml
+ parameters:
+ alpha:
+ one: ${beta:${alpha:two}}
+ two: a
+ beta:
+ a: 99
+
+``reclass.py --nodeinfo node1`` then gives:
+
+.. code-block:: yaml
+
+ 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:
+
+.. code-block:: yaml
+
+ # 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):
+
+.. code-block:: yaml
+
+ 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.
+
+
+**Inventory query example**
+
+Defining a cluster of machines using an inventory query, for example to open access to a database server to a
+group of nodes. Given exports/parameters for nodes of the form:
+
+.. code-block:: yaml
+
+# for all nodes requiring access to the database server
+exports:
+ host:
+ ip_address: aaa.bbb.ccc.ddd
+ cluster: _some_cluster_name_
+
+.. code-block:: yaml
+
+# for the database server
+parameters:
+ cluster_name: production-cluster
+ postgresql:
+ server:
+ clients: $[ exports:host:ip_address if exports:cluster == self:cluster_name ]
+
+This will generate a dictionary with an entry for node where the export:cluster key for a node is equal to the
+parameter:cluster_name key of the node on which the inventory query is run on. Each entry in the generated dictionary
+will contain the value of the exports:host:ip_address key. The output dictionary (depending on node definitions)
+would look like:
+
+.. code-block:: yaml
+
+node1:
+ ip_address: aaa.bbb.ccc.ddd
+node2:
+ ip_address: www.xxx.yyy.zzz
+
+For nodes where exports:cluster key is not defined or where the key is not equal to self:cluster_name no entry is made
+in the output dictionary.
+
+In practise the exports:cluster key can be set using a parameter reference:
+
+.. code-block:: yaml
+
+exports:
+ cluster: ${cluster_name}
+parameters:
+ cluster_name: production-cluster
+
+The above exports and parameter definitions could be put into a separate class and then included by nodes which require
+access to the database and included by the database server as well.
diff --git a/README.rst b/README.rst
index e88c135..99de5f6 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,26 @@
-reclass README
-==============
+Reclass README
+=========================
-The documentation for **reclass** is available from
-http://reclass.pantsfullofunix.net.
+This is the fork of original **reclass** that is available at:
+https://github.com/madduck/reclass
+
+Extentions
+==========
+
+List of the core features:
+
+* Escaping of References and Inventory Queries
+* Merging Referenced Lists and Dictionaries
+* Nested References
+* Inventory Queries
+* Ignore class notfound/regexp option
+
+
+.. include:: ./README-extensions.rst
+
+
+Documentation
+=============
+
+Documentation covering the original version is in the doc directory.
+See the README-extensions.rst file for documentation on the extentions.
diff --git a/reclass/version.py b/reclass/version.py
index a2aa99a..90c2cb7 100644
--- a/reclass/version.py
+++ b/reclass/version.py
@@ -7,12 +7,12 @@
# Released under the terms of the Artistic Licence 2.0
#
RECLASS_NAME = 'reclass'
-DESCRIPTION = 'merge data by recursive descent down an ancestry hierarchy'
-VERSION = '1.4.1'
-AUTHOR = 'martin f. krafft'
-AUTHOR_EMAIL = 'reclass@pobox.madduck.net'
-MAINTAINER = 'Jason Ritzke (@Rtzq0)'
-MAINTAINER_EMAIL = 'jasonritzke@4loopz.com'
-COPYRIGHT = 'Copyright © 2007–14 ' + AUTHOR
+DESCRIPTION = 'merge data by recursive descent down an ancestry hierarchy (forked extended version)'
+VERSION = '1.5.2'
+AUTHOR = 'martin f. krafft / Andrew Pickford / salt-formulas community'
+AUTHOR_EMAIL = 'salt-formulas@freelists.org'
+MAINTAINER = 'salt-formulas community'
+MAINTAINER_EMAIL = 'salt-formulas@freelists.org'
+COPYRIGHT = 'Copyright © 2007–14 martin f. krafft, extensions © 2017 Andrew Pickford, extensions © salt-formulas community'
LICENCE = 'Artistic Licence 2.0'
-URL = 'https://github.com/madduck/reclass'
+URL = 'https://github.com/salt-formulas/reclass'
diff --git a/releasenotes/config.yaml b/releasenotes/config.yaml
new file mode 100644
index 0000000..6a6923d
--- /dev/null
+++ b/releasenotes/config.yaml
@@ -0,0 +1,66 @@
+---
+# Usage:
+#
+# reno -qd .releasenotes list
+# reno -qd .releasenotes new slug-title --edit
+# reno -qd .releasenotes report --no-show-source
+
+# Change prelude_section_name to 'summary' from default value prelude
+prelude_section_name: summary
+show_source: False
+sections:
+ - [summary, Summary]
+ - [features, New features]
+ - [fixes, Bug fixes]
+ - [others, Other notes]
+template: |
+ ---
+ # Author the following sections or remove the section if it is not related.
+ # Use one release note per a feature.
+ #
+ # If you miss a section from the list below, please first submit a review
+ # adding it to .releasenotes/config.yaml.
+ #
+ # Format content with reStructuredText (RST).
+ # **Formatting examples:**
+ # - |
+ # This is a brief description of the feature. It may include a
+ # number of components:
+ #
+ # * List item 1
+ # * List item 2.
+ # This code block below will appear as part of the list item 2:
+ #
+ # .. code-block:: yaml
+ #
+ # classes:
+ # - system.class.to.load
+ #
+ # The code block below will appear on the same level as the feature
+ # description:
+ #
+ # .. code-block:: text
+ #
+ # provide model/formula pillar snippets
+
+
+ summary: >
+ This section is not mandatory. Use it to highlight the change.
+
+ features:
+ - Use the list to record summary of **NEW** features
+ - Provide detailed description of the feature indicating the use cases
+ when users benefit from using it
+ - Provide steps to deploy the feature (if the procedure is complicated
+ indicate during what stage of the deployment workflow it should be
+ deployed).
+ - Provide troubleshooting information, if any.
+
+ fixes:
+ - Use the list to record summary of a bug fix for blocker, critical.
+ - Provide a brief summary of what has been fixed.
+
+ others:
+ - Author any additional notes. Use this section if note is not related to
+ any of the common sections above.
+
diff --git a/releasenotes/notes/escaping-references-e76699d8ca010013.yaml b/releasenotes/notes/escaping-references-e76699d8ca010013.yaml
new file mode 100644
index 0000000..41845ee
--- /dev/null
+++ b/releasenotes/notes/escaping-references-e76699d8ca010013.yaml
@@ -0,0 +1,3 @@
+---
+others:
+ - The escaping of references changes how the constructs '\${xxx}' and '\\${xxx}' are rendered.