[ysh] io->evalToDict() respects dollar0, pos_args, vars

[doc/ref] Update docs for io->eval() and others

Fix the name conflict between the eval builtin, and io->eval()

Author: Andy C

builtin/method_io.py

@@ -41,6 +41,14 @@ def _CheckPosArgs(pos_args_raw, blame_loc):
 
 
 class EvalExpr(vm._Callable):
+    """io->evalExpr(ex) evaluates an expression 
+
+    Notes compared with io->eval(cmd):
+    - there is no evalToDict variant - doesn't make sense
+    - Does it need in_captured_frame=true?
+      - That is for "inline procs" like cd, but doesn't seem to be necessary
+        for expressions.  Unless we had mutations in expressions.
+    """
 
     def __init__(self, expr_ev):
         # type: (expr_eval.ExprEvaluator) -> None
@@ -71,21 +79,23 @@ def Call(self, rd):
         return result
 
 
-def _PrintFrame(prefix, frame):
-    # type: (str, Dict[str, Cell]) -> None
-    print('%s %s' % (prefix, ' '.join(frame.keys())))
+if 0:
+
+    def _PrintFrame(prefix, frame):
+        # type: (str, Dict[str, Cell]) -> None
+        print('%s %s' % (prefix, ' '.join(frame.keys())))
 
-    rear = frame.get('__E__')
-    if rear:
-        rear_val = rear.val
-        if rear_val.tag() == value_e.Frame:
-            r = cast(value.Frame, rear_val)
-            _PrintFrame('--> ' + prefix, r.frame)
+        rear = frame.get('__E__')
+        if rear:
+            rear_val = rear.val
+            if rear_val.tag() == value_e.Frame:
+                r = cast(value.Frame, rear_val)
+                _PrintFrame('--> ' + prefix, r.frame)
 
 
 class EvalInFrame(vm._Callable):
     """
-    For making "inline procs"
+    DEPRECATED, replaced by eval(b, in_captured_frame=true)
     """
 
     def __init__(self, mem, cmd_ev):
@@ -140,46 +150,38 @@ def Call(self, rd):
         unused = rd.PosValue()
         bound = rd.PosCommand()
 
-        frag = typed_args.GetCommandFrag(bound)
-
         dollar0 = rd.NamedStr("dollar0", None)
         pos_args_raw = rd.NamedList("pos_args", None)
         vars_ = rd.NamedDict("vars", None)
         in_captured_frame = rd.NamedBool("in_captured_frame", None)
         rd.Done()
 
+        frag = typed_args.GetCommandFrag(bound)
+
         pos_args = _CheckPosArgs(pos_args_raw, rd.LeftParenToken())
 
-        # TODO: Add debug_frame here, with ctx_Eval or ctx_EvalDebugFrame
         with state.ctx_TokenDebugFrame(self.mem, rd.LeftParenToken()):
             if self.which == EVAL_NULL:
-                # _PrintFrame('[captured]', captured_frame)
-                with state.ctx_EnclosedFrame(self.mem,
-                                             bound.captured_frame,
-                                             bound.module_frame,
-                                             None,
-                                             inside=in_captured_frame):
-                    # _PrintFrame('[new]', self.cmd_ev.mem.var_stack[-1])
-                    with state.ctx_Eval(self.mem, dollar0, pos_args, vars_):
-                        unused_status = self.cmd_ev.EvalCommandFrag(frag)
-                return value.Null
-
+                bindings = None  # type: Optional[Dict[str, value_t]]
             elif self.which == EVAL_DICT:
-                # TODO: dollar0, pos_args, vars_ not supported
-                #
-                # Does ctx_EnclosedFrame has different scoping rules?  For "vars"?
-
-                bindings = NewDict()  # type: Dict[str, value_t]
-                with state.ctx_EnclosedFrame(self.mem,
-                                             bound.captured_frame,
-                                             bound.module_frame,
-                                             bindings,
-                                             inside=in_captured_frame):
+                bindings = NewDict()
+            else:
+                raise AssertionError()
+
+            # _PrintFrame('[captured]', captured_frame)
+            with state.ctx_EnclosedFrame(self.mem,
+                                         bound.captured_frame,
+                                         bound.module_frame,
+                                         bindings,
+                                         inside=in_captured_frame):
+                # _PrintFrame('[new]', self.cmd_ev.mem.var_stack[-1])
+                with state.ctx_Eval(self.mem, dollar0, pos_args, vars_):
                     unused_status = self.cmd_ev.EvalCommandFrag(frag)
-                return value.Dict(bindings)
 
+            if self.which == EVAL_NULL:
+                return value.Null
             else:
-                raise AssertionError()
+                return value.Dict(bindings)
 
 
 class CaptureStdout(vm._Callable):

doc/ref/chap-builtin-cmd.md

@@ -859,7 +859,7 @@ and OSH.
 [cat-em]: chap-front-end.html#cat-em
 
 
-### eval
+### cmd/eval
 
     eval ARG+
 

doc/ref/chap-index.md

@@ -39,6 +39,16 @@ The name `clear` can refer to:
 [List/clear]: chap-type-method.html#List/clear
 [Dict/clear]: chap-type-method.html#Dict/clear
 
+### eval
+
+The name `eval` can refer to:
+
+- The [eval builtin][cmd/eval]
+- The [io method eval][io/eval]
+
+[cmd/eval]: chap-builtin-cmd.html#cmd/eval
+[io/eval]: chap-type-method.html#io/eval
+
 ### false
 
 The name `false` can refer to:

doc/ref/chap-type-method.md

@@ -709,10 +709,6 @@ The `Command` value is bound to a stack frame.  This frame will be pushed as an
 
 [block-arg]: chap-cmd-lang.html#block-arg
 
-### CommandFrag
-
-A command that's not bound to a stack frame.
-
 ### Expr
 
 A value of type `Expr` represents an unevaluated expression.  There are **three**
@@ -750,22 +746,11 @@ The `Expr` value is bound to a stack frame.  This frame will be pushed as an
 
 [expr-literal]: chap-expr-lang.html#expr-lit
 
-<!--
-
-### ExprFrag
-
-An expression command that's not bound to a stack frame.
-
-(TODO)
-
--->
-
 ### Frame
 
-A value that represents a stack frame.  It can be bound to a `CommandFrag`,
-producing a `Command`.
+A value that represents a stack frame.
 
-Likewise, it can be found to a `ExprFrag`, producing an `Expr`.
+You can turn it into a Dict with `dict(myframe)`.
 
 ### DebugFrame
 
@@ -850,19 +835,22 @@ Note that these expressions that have effects:
 - `^[ myplace->setValue(42) ]` - memory operation
 - `^[ $(echo 42 > hi) ]` - I/O operation
 
-### eval()
+### io/eval()
 
-Evaluate a command, and return `null`.
+Given a `Command` value (e.g. a block argument), execute it, and return `null`.
 
     var cmd = ^(echo hi)
-    call io->eval(cmd)
+    call io->eval(cmd)  # => hi
 
-It's similar to the `eval` builtin, and is meant to be used in pure functions.
+This method is more principled and flexible than shell's [eval][] builtin.
+It's especially useful in pure functions.
+
+[eval]: chap-builtin-cmd.html#cmd/eval
 
 It accepts optional args that let you control name binding:
 
-- `pos_args` for `$1 $2 $3`
 - `dollar0` for `$0`
+- `pos_args` for `$1 $2 $3`
 - `vars` for named variables
 
 Example:
@@ -871,6 +859,25 @@ Example:
     call io->eval(cmd, dollar0="z", pos_args=['one'], vars={x: "x"})
     # => zero z, one one, named x
 
+Scoping rules:
+
+- The frame that contains the `Command`, e.g.  `^(echo hi)` or `p { echo hi }`,
+  is called the *captured* frame.
+- Normally, a `Command` is evaluated in a new stack frame, which "encloses" the
+  captured frame.  That is, a `Command` is a *closure*.
+
+The `in_captured_frame` argument changes this behavior:
+
+    call io->eval(cmd, in_captured_frame=true)
+
+In this case, the captured frame becomes the local frame.  It's useful for
+creating procs that behave like builtins:
+
+    my-cd /tmp {           # my-cd is a proc, which pushes a new stack frame
+      var listing = $(ls)  # This variable is created in the captured frame
+    }
+    echo $listing          # It's still visible after the proc returns
+
 <!--
 TODO: document in_captured_frame=true
 -->
@@ -880,10 +887,12 @@ TODO: document in_captured_frame=true
 The `evalToDict()` method is like the `eval()` method, but it returns a
 Dict of bindings.
 
-It pushes a new "enclosed frame", and executes the given code.
+By default:
 
-Then it copies the frame's bindings into a Dict, and returns it.  Only the
-names that don't end with an underscore `_` are copied.
+1. It pushes a new stack frame, enclosing the captured frame
+1. Executes the given block of code (`Command`)
+1. Copies the top frame's bindings into a Dict, and returns it.
+   - Only the names that don't end with an underscore `_` are copied.
 
 Example:
 
@@ -894,9 +903,10 @@ Example:
 
     pp (d)  # => {a: 42, b: 11}
 
-<!--
-TODO: support pos_args
--->
+It supports the same optional arguments as `io->eval()`:
+
+- `dollar0 pos_args vars`
+- `in_captured_frame`
 
 ### captureStdout()
 

doc/ref/toc-osh.md

@@ -55,21 +55,21 @@ preserve_anchor_case: yes
 </h2>
 
 ```chapter-links-builtin-cmd
-  [I/O]           read        echo      printf
+  [I/O]           read        echo       printf
                   readarray   mapfile
-  [Run Code]      source .    eval      trap
+  [Run Code]      source .    cmd/eval   trap
   [Set Options]   set         shopt
-  [Working Dir]   cd          pwd       pushd     popd         dirs
-  [Completion]    complete    compgen   compopt   compadjust   compexport
+  [Working Dir]   cd          pwd        pushd     popd         dirs
+  [Completion]    complete    compgen    compopt   compadjust   compexport
   [Shell Process] exec      X logout 
-                  umask       ulimit    times
+                  umask       ulimit     times
   [Child Process] jobs        wait
-                  fg        X bg      X kill        X disown 
+                  fg        X bg       X kill        X disown 
   [External]      test [      getopts
   [Conditional]   cmd/true    cmd/false               colon :
-  [Introspection] help        hash      cmd/type    X caller
+  [Introspection] help        hash       cmd/type    X caller
   [Word Lookup]   command     builtin
-  [Interactive]   alias       unalias   history     X fc     X bind
+  [Interactive]   alias       unalias    history     X fc     X bind
 X [Unsupported]   enable
 ```
 

doc/ref/toc-ysh.md

@@ -66,12 +66,11 @@ error handling, and more.
   [Objects]        Obj         __invoke__       new
                              X __call__       __index__         X __str__
   [Reflection]     Command
-                   CommandFrag
                    Expr
                    Frame
                    DebugFrame  toString()
                    io          stdin            evalExpr()
-                               eval()           evalToDict()
+                               io/eval()        evalToDict()
                                captureStdout()
                                promptVal()
                              X time()         X strftime()      X glob()

spec/ysh-builtin-eval.test.sh

@@ -318,6 +318,85 @@ p param
 (Dict)   {"foo":42,"g":"-global","p":"-param","L":"-local"}
 ## END
 
+#### io->evalToDict() with dollar0, pos_args, vars
+
+proc Dict ( ; out; ; block) {
+  var d = io->evalToDict(block, dollar0='zero', pos_args=:|a b c|,
+                         vars={X: 'X', _Y: '_Y'})
+  call out->setValue(d)
+}
+
+var global = 'global'
+
+Dict (&d) {
+  foo = global
+  z = $0
+  one = $1
+  two = ${2}
+  three = "+$3"
+  # Note: X does NOT appear in the output, ctx_Eval makes it work.
+  x = X
+  y = _Y
+}
+
+json write (d)
+
+## STDOUT:
+{
+  "foo": "global",
+  "z": "zero",
+  "one": "a",
+  "two": "b",
+  "three": "+c",
+  "x": "X",
+  "y": "_Y"
+}
+## END
+
+#### io->evalToDict() with in_captured_frame=true
+
+proc Dict ( ; out; ; block) {
+  var d = io->evalToDict(block, dollar0='zero', pos_args=:|a b c|,
+                         vars={X: 'X', _Y: '_Y'}, in_captured_frame=true)
+  call out->setValue(d)
+}
+
+var global = 'global'
+
+func makeDict() {
+  var var_in_p_frame = 'p'
+
+  Dict (&d) {
+    foo = global
+    z = $0
+    one = $1
+    two = ${2}
+    three = "+$3"
+    # Note: X does NOT appear in the output, ctx_Eval makes it work.
+    x = X
+    y = _Y
+  }
+
+  return (d)
+}
+
+var d = makeDict()
+json write (d)
+
+## STDOUT:
+{
+  "var_in_p_frame": "p",
+  "foo": "global",
+  "z": "zero",
+  "one": "a",
+  "two": "b",
+  "three": "+c",
+  "x": "X",
+  "y": "_Y"
+}
+## END
+
+
 #### parseCommand then io->evalToDict() - in global scope
 
 var g = 'global'