document the leval command

Signed-off-by: Steve Bennett <steveb@workware.net.au>

1 files changed, 39 insertions, 0 deletions

diff --git a/jim_tcl.txt b/jim_tcl.txt
index 9cfa6f8..191128d 100644
--- a/jim_tcl.txt
+++ b/jim_tcl.txt
@@ -63,6 +63,7 @@ Changes since 0.82
 7. Add support for hinting with `history hints`
 8. Support for `proc` statics by reference (lexical closure) rather than by value
 9. `regsub` now supports '-command' (per Tcl 8.7)
+10. New `leval` command to create lists using subst-style substitution
 
 Changes between 0.81 and 0.82
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3120,6 +3121,44 @@ than variables, a list of unassigned elements is returned.
     a=1,b=2
 ----
 
+leval
+~~~~
+
++*leval* 'string'+
+
+This command is similar to `list` in that it creates a list, but uses
+the same rules as scripts when constructing the elements of the list.
+It is somewhat similar to `subst` except it produces a list instead of a string.
+
+This means that variables are substituted, commands are evaluated, backslashes are
+interpreted, the expansion operator is applied and comments are skipped.
+
+Consider the following example.
+
+---
+    set x 1
+    set y {2 3}
+    set z 3
+    leval {
+        # This is a list with interpolation
+        $x; # The x variable
+        {*}$y; # The y variable expanded
+        [string cat a b c]; # A command
+        {*}[list 4 5]; # A list expanded into multiple elements
+        "$z$z"; # A string with interpolation
+    }
+---
+
+The result of `leval` is the following list with 7 elements.
+
+---
+    1 2 3 abc 4 5 33
+---
+
+This is particularly useful when constructing a list (or dict)
+as a data structure as it easily allows for comments and variable and command
+substitution.
+
 local
 ~~~~~
 +*local* 'cmd ?arg\...?'+