added support for advanced substitution expressions

2 files changed, 61 insertions, 0 deletions

diff --git a/doc/lib.txt b/doc/lib.txt
index 775223fc1..46c403ed5 100755
--- a/doc/lib.txt
+++ b/doc/lib.txt
@@ -108,6 +108,9 @@ String handling
 * `matchers <matchers.html>`_
   This module contains various string matchers for email addresses, etc.
 
+* `subexes <subexes.html>`_
+  This module implements advanted string substitution operations.
+
 
 Generic Operating System Services
 ---------------------------------
diff --git a/doc/subexes.txt b/doc/subexes.txt
new file mode 100644
index 000000000..6d865e4b6
--- /dev/null
+++ b/doc/subexes.txt
@@ -0,0 +1,58 @@
+================================
+Substitution Expressions (subex)
+================================
+
+A *subex* (*Substitution Expression*) represents an advanted string 
+substitution. In contrast to a `regex`:idx: which deals with string analysis, a
+*subex* deals with string synthesis.
+
+Thanks to its conditional construct ``$[0|1|2|else]`` it supports 
+`internationalization`:idx: of format string literals quite well.
+
+
+=====================   =====================================================
+Notation                meaning
+=====================   =====================================================
+``$#``                  use first or next argument
+``$name``               use named argument
+``$1``                  use first argument
+``$-1``                 use last argument
+``${1..3}``             use arguments 1 to 3
+``${..}``               use all arguments
+``${#..}``              use all remaining arguments
+``${..-2}``             use all arguments except the last argument
+``${$1}``               use argument X where ``X = parseInt(arg[1])``
+``${$1..$2}``           use arguments X to Y where ``X = parseInt(arg[1])``
+                        and ``Y = parseInt(arg[2])``
+``$','{1..3}``          use arguments 1 to 3 and join them with ','
+``$','80c'\n'{..}``     use all arguments, join them with ','. Insert '\n'
+                        before the resulting string exceeds 80 chars.
+``$','8i'\n'{..}``      use all arguments, join them with ','. Insert '\n'
+                        after every 8th item.
+``$' '~{1..3}``         use arguments 1 to 3 with a leading space if the
+                        concatenation of ``1..3`` is not the empty string
+``$[zero|one|def]1``    use ``X = parseInt(arg[1])`` to determine which
+                        branch to use. If ``X == 0`` the 'zero' branch is
+                        selected, if ``X == 1`` the 'one' branch is
+                        selected, etc. Otherwise the 'def' branch is 
+                        selected. ``$x`` is interpreted in branches too.
+                        If a branch needs to contain ``|``, ``]`` put
+                        them in single quotes. To produce a verbatim single
+                        quote, use ``''``.
+=====================   =====================================================
+
+Examples
+========
+
+.. code-block:: nimrod
+
+  subex"$1($', '{2..})" % ["f", "a", "b", "c"] == "f(a, b, c)"
+  
+  subex"$1 $[files|file|files]{1} copied" % ["1"] == "1 file copied"
+  
+  subex"$['''|'|''''|']']#" % "0" == "'|"
+  
+  subex("type\n  TEnum = enum\n    $', '40c'\n    '{..}") % [
+    "fieldNameA", "fieldNameB", "fieldNameC", "fieldNameD"]
+    
+