[main] --eval stops on normal errors

AND when $? is non-zero after evaluating a file.  (This matters only for
OSH.)

[doc/ref] Document --eval

Improve osh --help and ysh --help.

Author: Andy C

core/main_loop.py

@@ -446,7 +446,7 @@ def EvalFile(
         cmd_ev,  # type: cmd_eval.CommandEvaluator
         lang,  # type: str
 ):
-    # type: (...) -> bool
+    # type: (...) -> Tuple[bool, int]
     """Evaluate a disk file, for --eval --eval-pure
 
     Copied and adapted from the 'source' builtin in builtin/meta_oils.py.
@@ -463,7 +463,7 @@ def EvalFile(
     except (IOError, OSError) as e:
         print_stderr("%s: Couldn't open %r for --eval: %s" %
                      (lang, fs_path, posix.strerror(e.errno)))
-        return False
+        return False, -1
 
     line_reader = reader.FileLineReader(f, cmd_ev.arena)
     c_parser = parse_ctx.MakeOshParser(line_reader)
@@ -477,8 +477,8 @@ def EvalFile(
             src = source.MainFile(fs_path)
             with alloc.ctx_SourceCode(cmd_ev.arena, src):
                 # May raise util.UserExit
-                was_parsed, unused = Batch2(cmd_ev, c_parser, cmd_ev.errfmt)
+                was_parsed, status = Batch2(cmd_ev, c_parser, cmd_ev.errfmt)
                 if not was_parsed:
-                    return False
+                    return False, -1
 
-    return True
+    return True, status

core/shell.py

@@ -962,15 +962,22 @@ def Main(
     for path, is_pure in attrs.eval_flags:
         # TODO: respect is_pure
         try:
-            ok = main_loop.EvalFile(path, fd_state, parse_ctx, cmd_ev, lang)
+            ok, status = main_loop.EvalFile(path, fd_state, parse_ctx, cmd_ev,
+                                            lang)
         except util.UserExit as e:
             # Doesn't seem like we need this, and verbose_errexit isn't the right option
             #if exec_opts.verbose_errexit():
             #    print-stderr('oils: --eval exit')
             return e.status
-        if not ok:  # parse error or I/O error was already printed
+
+        # I/O error opening file, parse error.  Message was # already printed.
+        if not ok:
             return 1
 
+        # Runtime error
+        if status != 0:
+            return status
+
     #
     # Is the shell interactive?
     #

core/util.py

@@ -160,6 +160,10 @@ def HelpFlag(loader, topic_id, f):
     # Note: could assert this in C++ too
     assert found, 'Missing %s' % topic_id
 
+    found = PrintEmbeddedHelp(loader, 'shell-flags', f)
+    # Note: could assert this in C++ too
+    assert found, 'Missing %s' % topic_id
+
 
 def VersionFlag(loader, f):
     # type: (pyutil._ResourceLoader, mylib.Writer) -> None

doc/ref/chap-front-end.md

@@ -31,8 +31,9 @@ This chapter describes command line usage and lexing.
 ```
 bin/oils-for-unix is an executable that contains OSH, YSH, and more.
 
-Usage: oils-for-unix MAIN_NAME ARG*
-       MAIN_NAME ARG*
+Usage:
+    oils-for-unix MAIN_NAME ARG*
+    MAIN_NAME ARG*
 
 It behaves like busybox.  The command name can be passed as the first argument:
 
@@ -54,25 +55,16 @@ behave like that command:
 ```
 bin/osh is compatible with POSIX shell, bash, and other shells.
 
-Usage: osh FLAG* SCRIPT ARG*
-       osh FLAG* -c COMMAND ARG*
-       osh FLAG*
-
-The command line accepted by `bin/osh` is compatible with /bin/sh and bash.
+Usage:
+   osh FLAG* SCRIPT ARG*
+   osh FLAG* -c COMMAND ARG*
+   osh FLAG*
 
+Examples:
     osh -c 'echo hi'
     osh myscript.sh
     echo 'echo hi' | osh
 
-It also has a few enhancements:
-
-    osh -n -c 'hello'                    # pretty-print the AST
-    osh --ast-format text -n -c 'hello'  # print it full
-
-osh accepts POSIX sh flags, with these additions:
-
-    -n             parse the program but don't execute it.  Print the AST.
-    --ast-format   what format the AST should be in
 ```
 
 <h3 id="ysh-usage" class="ysh-topic" oils-embed="1">
@@ -84,23 +76,47 @@ osh accepts POSIX sh flags, with these additions:
 ```
 bin/ysh is the shell with data tYpes, influenced by pYthon, JavaScript, ...
 
-Usage: ysh FLAG* SCRIPT ARG*
-       ysh FLAG* -c COMMAND ARG*
-       ysh FLAG*
+Usage:
+    ysh FLAG* SCRIPT ARG*
+    ysh FLAG* -c COMMAND ARG*
+    ysh FLAG*
 
 Examples:
-
     ysh -c 'echo hi'
     ysh myscript.ysh
     echo 'echo hi' | ysh
 
-bin/ysh is the same as bin/osh with a the ysh:all option group set.  So bin/ysh
-also accepts shell flags.  Examples:
+Note that bin/ysh is the same as bin/osh with the ysh:all option group set:
+    osh -o ysh:all -c 'echo hi'  # Same as YSH
+```
+
+<h3 id="shell-flags" oils-embed="1">
+  shell-flags
+</h3>
 
+```
+osh and ysh accept standard POSIX shell flags, like:
+
+    bin/osh -o errexit -c 'false'
     bin/ysh -n myfile.ysh
     bin/ysh +o errexit -c 'false; echo ok'
-```
 
+They also accept these flags:
+
+    -n                Parse the program but don't execute it.  Print the AST.
+    --ast-format FMT  The format for the AST (text|text-abbrev)
+    --eval FILE       Evaluate the given file, similar to the 'source' builtin.
+                      Specify it multiple times to run multiple files.  The
+                      shell stops on normal errors, as well as when $? is
+                      non-zero after evaluating a file (even if errexit is
+                      off).
+    --tool            Run a tool instead of the shell (cat-em|syntax-tree)
+
+Examples:
+
+    osh -n -c 'hello'                    # pretty-print the AST
+    ysh --ast-format text -n -c 'hello'  # print it full
+```
 
 <h3 id="config" class="osh-ysh-topic">config</h3>
 
@@ -123,7 +139,10 @@ Pass --norc to disable the startup directory.
 
 <h3 id="startup" class="osh-ysh-topic">startup</h3>
 
-History is read?
+TODO:
+
+1. History is read
+1. ...
 
 <h3 id="line-editing" class="osh-ysh-topic">line-editing</h3>
 
@@ -302,6 +321,16 @@ Print files embedded in the `oils-for-unix` binary to stdout.  Example:
 
     osh --tool cat-em stdlib/math.ysh stdlib/other.ysh
 
+### syntax-tree
+
+Print the syntax tree in a debug format.
+
+    osh --tool syntax-tree stdlib/ysh/math.ysh
+
+The `-n` flag is a shortcut:
+
+    osh -n stdlib/ysh/math.ysh
+
 
 ## Help Chapters
 

doc/ref/toc-osh.md

@@ -91,8 +91,9 @@ X [Unsupported]   enable
 </h2>
 
 ```chapter-links-front-end
-  [Usage]         oils-usage   osh-usage             config
-                  startup      line-editing          exit-codes
+  [Usage]         oils-usage   osh-usage             shell-flags
+                  config       startup               line-editing          
+                  exit-codes
   [Lexing]        comment #    line-continuation \   ascii-whitespace [ \t\r\n]
 ```
 

doc/ref/toc-ysh.md

@@ -220,10 +220,12 @@ X [External Lang] BEGIN   END   when (awk)
 </h2>
 
 ```chapter-links-front-end
-  [Usage]         oils-usage                   ysh-usage
-  [Lexing]        ascii-whitespace [ \t\r\n]
-                  doc-comment ###              multiline-command ...
-  [Tools]         cat-em
+  [Usage]         oils-usage   ysh-usage             shell-flags
+                  config       startup               line-editing          
+                  exit-codes
+  [Lexing]        comment #    line-continuation \   ascii-whitespace [ \t\r\n]
+  [Lexing]        doc-comment ###                    multiline-command ...
+  [Tools]         cat-em                             syntax-tree
 ```
 
 <h2 id="cmd-lang">

spec/hay.test.sh

@@ -1,4 +1,4 @@
-## oils_failures_allowed: 4
+## oils_failures_allowed: 5
 
 # Hay: Hay Ain't YAML
 
@@ -811,3 +811,48 @@ json write (_hay().children[0].attrs)
 }
 ## END
 
+
+#### Using Hay with --eval flags
+shopt --set ysh:all
+
+echo 'hay define Package' >pre.ysh 
+
+echo '
+Package cpython {
+  version = "3.12"
+  url = "https://python.org/"
+  if (false) {
+  proc build {
+    echo $version
+  }
+}
+}
+' >def.hay
+
+# TODO:
+# - nullify_fields=true - well some of them aren't fields
+# - nullify=true
+# - errors='null'
+# - on_error=null
+# - drop_with='error' drop_with='null'
+# - degrade_to_null=true
+# - replace_with_null=true
+# - null_replace=true
+# - null_replacer=true  # replacer can be a function?
+# - errors=false  # too vague?
+# 
+# JavaScript has a second "replacer" arg, which can be a function, or an array
+# I guess you can specify replacer=null
+
+echo 'json write (_hay())' > post.ysh
+
+... $[ENV.SH] -o ysh:all
+  --eval pre.ysh
+  --eval def.hay
+  --eval post.ysh
+  -c ''
+  ;
+
+## STDOUT:
+a
+## END

spec/sh-usage.test.sh

@@ -92,3 +92,32 @@ $SH --login -c 'exit 0'
 ## OK dash status: 2
 ## OK mksh status: 1
 
+
+#### osh --eval 
+case $SH in bash|dash|mksh|zsh) exit ;; esac
+
+echo 'echo one "$@"' > one.sh
+echo 'echo fail "$@"; ( exit 42 )' > fail.sh
+
+$SH --eval one.sh \
+  -c 'echo flag -c "$@"' dummy x y z
+echo
+
+# Even though errexit is off, the shell exits if the last status of an --eval
+# file was non-zero.
+
+$SH --eval one.sh --eval fail.sh \
+  -c 'echo flag -c "$@"' dummy x y z
+echo status=$?
+
+## STDOUT:
+one x y z
+flag -c x y z
+
+one x y z
+fail x y z
+status=42
+## END
+
+## N-I bash/dash/mksh/zsh STDOUT:
+## END

spec/ysh-usage.test.sh

@@ -82,9 +82,9 @@ echo 'echo flag --eval; false; echo bye' >bad.ysh
 
 $[ENV.SH] --eval bad.ysh -c 'echo flag -c'
 
+## status: 1
 ## STDOUT:
 flag --eval
-flag -c
 ## END
 
 #### ysh --eval exit status