[builtin/use] Implement use --extern

Add spec tests

Start documenting the 'use' command

builtin/func_reflect.py

@@ -40,6 +40,7 @@ class Id(vm._Callable):
 
     I guess only mutable objects can have IDs then
     """
+
     def __init__(self):
         # type: () -> None
         vm._Callable.__init__(self)

builtin/meta_oils.py

@@ -368,7 +368,13 @@ def _Use(self, cmd_val):
         import $LIB_YSH/stdlib
 
         """
-        _, arg_r = flag_util.ParseCmdVal('use', cmd_val)
+        attrs, arg_r = flag_util.ParseCmdVal('use', cmd_val)
+        arg = arg_types.use(attrs.attrs)
+
+        # Accepts any args
+        if arg.extern_:  # use --extern grep  # no-op for static analysis
+            return 0
+
         path_arg, path_loc = arg_r.ReadRequired2('requires a module path')
         # TODO on usage:
         # - typed arg is value.Place

builtin/pure_ysh.py

@@ -206,9 +206,9 @@ def Run(self, cmd_val):
         # type: (cmd_value.Argv) -> int
 
         # This means we ignore -- , which is consistent
-        arg, arg_r = flag_util.ParseCmdVal('append',
-                                           cmd_val,
-                                           accept_typed_args=True)
+        _, arg_r = flag_util.ParseCmdVal('append',
+                                         cmd_val,
+                                         accept_typed_args=True)
 
         rd = typed_args.ReaderForProc(cmd_val)
         val = rd.PosValue()

doc/ref/chap-builtin-cmd.md

@@ -353,13 +353,22 @@ Use it like this:
 
 ### use
 
-TODO
+Import code from other files, creating an `Obj` that acts like a namespace.
 
-Reuse code from other files, respecting namespaces.
+    use my-dir/my-module.ysh
 
-    use lib/foo.ysh  # foo myproc, $[foo.attr]
-                     # implicit $_this_dir aka relative import
+    echo $[my_module.my_integer]  # the module Obj has attributes
+    my_module myproc              # the module Obj is invokable
 
+The evaluation of such files is cached, so it won't be re-evaluated if `use` is called again.
+
+<!--
+# TODO: implicit $_this_dir aka relative import?
+
+That makes scripts callable from elsewhere?
+-->
+
+<!--
 Bind a specific name:
 
     use lib/foo.ysh (&myvar)  # makes 'myvar' available
@@ -376,10 +385,12 @@ Maybe:
       pick log (&mylog)
       pick die (&mydie)
     }
+-->
 
-Also a declaration
+The `--extern` flag make the invocation do nothing.  It can be used be tools to
+analyze what names are in the file.
 
-    use --extern grep sed
+    use --extern grep sed awk
 
 ## I/O
 

doc/ref/toc-ysh.md

@@ -116,10 +116,13 @@ X [Wok]           _field()
                   shvar                  Temporary modify global settings
                   ctx                    Share and update a temporary "context"
                   push-registers         Save registers like $?, PIPESTATUS
-  [Modules]       runproc                Run a proc; use as main entry point
+  [Introspection] runproc                Run a proc; use as main entry point
+                X extern                 Run an external command, with an ENV
+                X invoke                 Control which "invokables" are run
+  [Modules]       
                   source-guard           guard against duplicate 'source'
                   is-main                false when sourcing a file
-                X use                    use names,
+                  use                    create a module Obj from a source file
   [I/O]           ysh-read               flags --all, -0
                   ysh-echo               no -e -n with simple_echo
                   write                  Like echo, with --, --sep, --end

frontend/args.py

@@ -105,6 +105,11 @@ def Set(self, name, val):
 
         # debug-completion -> debug_completion
         name = name.replace('-', '_')
+
+        # similar hack to avoid C++ keyword in frontend/flag_gen.py
+        if name == 'extern':
+            name = 'extern_'
+
         self.attrs[name] = val
 
         if 0:

spec/ysh-builtin-module.test.sh

@@ -38,6 +38,50 @@ stdin
 status=0
 ## END
 
+#### use builtin usage
+
+use
+echo no-arg=$?
+
+use foo
+echo one-arg=$?
+
+use --extern foo
+echo extern=$?
+
+use --bad-flag
+echo bad-flag=$?
+
+use too many
+echo too-many=$?
+
+use ///no-builtin
+echo no-builtin=$?
+
+
+## STDOUT:
+no-arg=2
+one-arg=1
+extern=0
+bad-flag=2
+too-many=2
+no-builtin=1
+## END
+
+
+#### use --extern is a no-op, for static analysis
+
+use --extern grep sed awk
+echo status=$?
+
+use --extern zzz
+echo status=$?
+
+## STDOUT:
+status=0
+status=0
+## END
+
 #### use foo.ysh creates a value.Obj, and it's cached on later invocations
 
 shopt --set ysh:upgrade
@@ -97,33 +141,3 @@ util die 'hello'
 ## STDOUT:
 ## END
 
-#### use builtin usage
-
-use
-echo no-arg=$?
-
-use foo
-echo one-arg=$?
-
-use --extern foo
-echo extern=$?
-
-use --bad-flag
-echo bad-flag=$?
-
-use too many
-echo too-many=$?
-
-use ///no-builtin
-echo no-builtin=$?
-
-
-## STDOUT:
-no-arg=2
-one-arg=1
-extern=1
-bad-flag=2
-too-many=2
-no-builtin=1
-## END
-