# HG changeset patch
# User Franz Glasner <f.glasner@feldmann-mg.com>
# Date 1692198254 -7200
# Node ID c17a4e30ebbfdcce7b10d71298eef2105d47768d
# Parent  ea1a6beadc6c4f97f469a8351147a7fd0fd1702e
Docs for nested filters

diff -r ea1a6beadc6c -r c17a4e30ebbf configmix/_speedups.c
--- a/configmix/_speedups.c	Wed Aug 16 16:28:42 2023 +0200
+++ b/configmix/_speedups.c	Wed Aug 16 17:04:14 2023 +0200
@@ -1154,7 +1154,7 @@
             return NULL;
         }
         if (end != (s_len - 3)) {
-            PyErr_SetString(PyExc_ValueError, "`{{|' global filter interpolation must end with `|}}'");
+            PyErr_SetString(PyExc_ValueError, "`{{|' nested filter interpolation must end with `|}}'");
             return NULL;
         }
         /*
diff -r ea1a6beadc6c -r c17a4e30ebbf configmix/config.py
--- a/configmix/config.py	Wed Aug 16 16:28:42 2023 +0200
+++ b/configmix/config.py	Wed Aug 16 17:04:14 2023 +0200
@@ -1031,7 +1031,7 @@
                 and (s[2] == _FILTER_SEPARATOR)
                 and (start == 0)):
             if s.find(_ENDTOK_FILTER, 3) != (len_s - 3):
-                raise ValueError("`{{|' global filter interpolation must end with `|}}'")
+                raise ValueError("`{{|' nested filter interpolation must end with `|}}'")
             new_s, filters = _split_filters(s[3:-3], -1)
             try:
                 varvalue = self.py_interpolate_variables(new_s)
diff -r ea1a6beadc6c -r c17a4e30ebbf docs/introduction.rst
--- a/docs/introduction.rst	Wed Aug 16 16:28:42 2023 +0200
+++ b/docs/introduction.rst	Wed Aug 16 17:04:14 2023 +0200
@@ -518,6 +518,31 @@
 return with :py:obj:`None` or an empty string.
 
 
+Nested Interpolation (Filtering Only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generally, nested interpolation does *not* work. Something like
+``{{{{variable}}}}`` does not work.
+
+Also something like ``{{{{path-variable|Empty}}/subdir|normpath}}`` does not
+work as expected: `path-variable` would not get interpolated and `Empty`
+not be applied.
+
+But -- as a special case -- a simplified form of nested evaluation is
+implemented for filters only. Instead of using the start tag ``{{`` and end
+tag ``}}`` it uses the special start tag ``{{|`` and end tag ``|}}``.
+
+
+With the syntax::
+
+      {{|<expression with variables>|filter1[,filter2...]|}}
+
+The expression above can be expressed as
+``{{|{{path-variable|Empty}}/subdir|normpath|}}``
+and yields the expected result -- with `normpath` applied to the now
+interpolated expression.
+
+
 Examples
 ~~~~~~~~
 
diff -r ea1a6beadc6c -r c17a4e30ebbf tests/test.py
--- a/tests/test.py	Wed Aug 16 16:28:42 2023 +0200
+++ b/tests/test.py	Wed Aug 16 17:04:14 2023 +0200
@@ -2418,7 +2418,7 @@
             cfg.getvar,
             u("intl.cache"))
 
-    def test_global_filter_wrong_syntax(self):
+    def test_nested_filter_wrong_syntax(self):
         cfg = configmix.load()
         try:
             y = getattr(cfg, self.interpolate_meth)(u"{{|{{not-existing}}|None}}")
@@ -2427,22 +2427,22 @@
         else:
             self.fail("`ValueError' should have been raised")
 
-    def test_global_filter_None(self):
+    def test_nested_filter_None(self):
         cfg = configmix.load()
         y = getattr(cfg, self.interpolate_meth)(u"{{|{{not-existing}}|None|}}")
         self.assertTrue(y is None)
 
-    def test_global_filter_empty(self):
+    def test_nested_filter_empty(self):
         cfg = configmix.load()
         y = getattr(cfg, self.interpolate_meth)(u"{{|{{not-existing}}|Empty|}}")
         self.assertEqual(u(""), y)
 
-    def test_global_nested_filter_empty(self):
+    def test_nested_nested_filter_empty(self):
         cfg = configmix.load()
         y = getattr(cfg, self.interpolate_meth)(u"{{|pre-{{not-existing|Empty}}-post|upper|}}")
         self.assertEqual(u("PRE--POST"), y)
 
-    def test_global_filter_upper(self):
+    def test_nested_filter_upper(self):
         cfg1 = {
             u("key-1"): u("Value for key-1")
         }
@@ -2450,7 +2450,7 @@
         y = getattr(cfg, self.interpolate_meth)(u"{{|pre_{{key-1}}_post|upper|}}")
         self.assertEqual(u("PRE_VALUE FOR KEY-1_POST"), y)
 
-    def test_global_filter_normpath(self):
+    def test_nested_filter_normpath(self):
         cfg1 = {
             u("path1"): u("a\\b\\c"),
             u("path2"): u("{{|{{path1}}/../d|normpath|}}")