Draft README-extensions.md

Author: simu

README-extensions.md

@@ -0,0 +1,49 @@
+# reclass-rs Extensions
+
+Initially, reclass-rs only implemented features present in [kapicorp-reclass], including extensions introduced by kapicorp-reclass.
+This document covers extensions that are currently unique to reclass-rs.
+
+## Non-compatible `compose_node_name` option
+
+Reclass-rs supports the `compose_node_name` option.
+By default, in contrast to kapicorp-reclass, reclass-rs preserves literal dots in composed node names.
+For example, given the following inventory, the node's internal path is parsed as `['path', 'to', 'the.node']`:
+
+```
+.
+├── classes
+│   ├── cls1.yml
+│   └── cls2.yml
+└── nodes
+    └── path
+        └── to
+            └── the.node.yml
+```
+
+However, optionally, reclass-rs can be configured to handle `compose_node_name` the same way that kapicorp-reclass does, by naively splitting node names on each dot.
+To enable this compatibility mode, set `compat_flags: ['ComposeNodeNameLiteralDots']` in your inventory's `reclass-config.yml`.
+In compatibility mode, the node's internal path for the previous inventory is `['path', 'to', 'the', 'node']`.
+
+## Default values for references
+
+> [!INFO]
+> This feature is currently experimental and may change at any time.
+
+Reclass-rs supports specifying default (fallback) values for references.
+The format for specifying a default value is `${some:reference:path::the_default_value}`.
+We chose `::` as the separator between the reference path and the default value, because `::` can't appear in references in valid kapicorp-reclass inventories (due to [kapicorp/kapitan#1171](https://github.com/kapicorp/kapitan/issues/1171)).
+Reclass-rs first resolves nested references in the reference path and default value and then splits the reference contents into the path and default value.
+References with default values can be used everywhere that references are supported, including class includes.
+
+> [!NOTE]
+> Currently, default values are only applied once all nested references have been successfully resolved.
+> A missing nested reference without its own default value will result in an error even if the top-level reference specifies a default value.
+
+For further processing, the default value is parsed as YAML.
+Incomplete YAML flow values will be raised as errors.
+
+> [!NOTE]
+> While it's generally possible to specify arbitrarily complex YAML default values inline, we recommend specifying complex default values through a nested reference.
+> When providing complex default values inline, it may be necessary to carefully escape characters of the YAML value in order to ensure the reference parser keeps the YAML value intact.
+
+[kapicorp-reclass]: https://github.com/kapicorp/reclass