SH(2)                                                       SH(2)

     NAME
          Sh - module interface to the shell

     SYNOPSIS
          include "sh.m";
          sh := load Sh Sh->PATH;
          Context, Listnode: import sh;

          system:           fn(drawctxt: ref Draw->Context, cmd: string): string;
          run:              fn(drawctxt: ref Draw->Context, argv: list of string): string;
          parse:            fn(s: string): (ref Cmd, string);
          cmd2string:       fn(c: ref Cmd): string;
          list2stringlist:  fn(nl: list of ref Listnode): list of string;
          stringlist2list:  fn(sl: list of string): list of ref Listnode;

          Context: adt {
                  new:            fn(drawcontext: ref Draw->Context): ref Context;
                  get:            fn(c: self ref Context,
                                     name: string): list of ref Listnode;
                  set:            fn(c: self ref Context,
                                     name: string,
                                     value: list of ref Listnode);
                  setlocal:       fn(c: self ref Context,
                                     name: string,
                                     value: list of ref Listnode);
                  envlist:        fn(c: self ref Context):
                                       list of (string, list of ref Listnode);
                  push, pop:      fn(c: self ref Context);
                  copy:           fn(c: self ref Context, copyenv: int): ref Context;
                  run:            fn(c: self ref Context,
                                     args: list of ref Listnode,
                                     last: int): string;
                  addmodule:      fn(c: self ref Context, name: string,
                                     mod: Shellbuiltin);
                  addbuiltin:     fn(c: self ref Context, name: string,
                                     mod: Shellbuiltin);
                  removebuiltin:  fn(c: self ref Context, name: string,
                                     mod: Shellbuiltin);
                  addsbuiltin:    fn(c: self ref Context, name: string,
                                     mod: Shellbuiltin);
                  removesbuiltin: fn(c: self ref Context, name: string,
                                     mod: Shellbuiltin);
                  fail:           fn(c: self ref Context, ename, msg: string);
                  options:        fn(c: self ref Context): int;
                  setoptions:     fn(c: self ref Context, flags, on: int): int;
          };

          Listnode: adt {
                  cmd:    ref Cmd;
                  word:   string;

     Page 1                       Plan 9            (printed 12/21/24)

     SH(2)                                                       SH(2)

          };

          Cmd: adt {
                  # private data
          };

          Shellbuiltin: module {
                  initbuiltin:    fn(ctxt: ref Context, sh: Sh): string;
                  whatis:         fn(ctxt: ref Sh->Context, sh: Sh,
                                     name: string, wtype: int): string;
                 runbuiltin:     fn(ctxt: ref Context, sh: Sh,
                                     cmd: list of ref Listnode,
                                     last: int): string;
                  runsbuiltin:    fn(ctxt: ref Context, sh: Sh,
                                     cmd: list of ref Listnode): list of ref Listnode;
                  getself:        fn(): Shellbuiltin;
          };

     DESCRIPTION
          Sh is a command-line interpreter and a scripting language;
          it also presents a module interface to allow Limbo modules
          to access its functionality at a lower level.  The Sh module
          can be used in several different ways.  At the simplest
          level, it can be run as a command-line program; for details
          of this, see sh(1). The simplest access at the Limbo level
          is through the system function, which given a draw Context
          (see draw-context(2)) and a string executes the sh command
          contained in s and returns its result. It catches any excep-
          tions raised by the command.  Almost as simple is exec,
          which runs argv as a command, taking the first word as the
          command to be executed (it can be a braced block) and giving
          the rest as arguments, catching any exceptions raised.

          Although program arguments are passed to external programs
          as lists of strings, at the Sh module level, an argument
          list is held as a list of ref Listnode.  A Listnode holds
          either a simple string, or a braced block that has been
          parsed by the shell. Sometimes it can hold both; in this
          case the string and the block both represent the same thing.
          Parse converts from a string to a Cmd (a braced block). It
          returns a tuple (cmd, error) where cmd holds the parsed
          block, and error is non-empty if an error has occurred doing
          so.  Cmd2string performs the opposite conversion; it returns
          a string that when parsed will yield the same command block
          it was passed.  The utility functions List2stringlist and
          stringlist2list convert from and to a list of ref Listnode
          to or from a list of string respectively.

          A Context holds all the state information needed by a cur-
          rently running sh process; this adt holds current values of
          environment variables and a list of currently loaded modules

     Page 2                       Plan 9            (printed 12/21/24)

     SH(2)                                                       SH(2)

          and builtin commands.  It is specific to the process within
          which it was created.  If it is desired to run sh commands
          in a newly spawned process, a new Context must be created,
          or a copy of an existing Context made (making sure to syn-
          chronise access until the copy has been made).

          Context.new(drawcontext)
                    New creates a new context.  Drawcontext represents
                    the current graphics context within which sh com-
                    mands will be run (see draw-context(2)).

          ctxt.get(name)
                    Get retrieves the value of environment variable
                    name from ctxt. It is retrieved from the innermost
                    scope in which a value for name has been set.

          ctxt.set(name, value)
                    Set sets the value of environment variable name in
                    ctxt to value. It is set in the innermost scope in
                    which a value for name has been set, or the outer-
                    most level if it has not been set.

          ctxt.setlocal(name, value)
                    Similar to set() except that the value is set in
                    the innermost scope that has been pushed.

          ctxt.envlist()
                    Envlist retrieves the list of all the environment
                    variables currently in scope, and their values.
                    It returns a list of (name, value) tuples, where
                    name is the name of the variable and value is its
                    value.

          ctxt.push()
                    Push creates a new innermost environment variable
                    scope.

          ctxt.pop()
                    Pop discards the current innermost scope, losing
                    the values of all variables that have been defined
                    there.  It is an error to pop a context that has
                    not been pushed.  Care must be taken to ensure
                    that a push is always matched by a pop.  In par-
                    ticular, exceptions should be caught, the context
                    popped, and the exception re-raised.

          ctxt.copy(copyenv)
                    The shell's Context is associated with a particu-
                    lar process; copy returns a copy of ctxt associ-
                    ated with the current process. If copyenv is non-
                    zero, the whole environment will be copied - this
                    should be set if the new process is to run

     Page 3                       Plan 9            (printed 12/21/24)

     SH(2)                                                       SH(2)

                    asynchronously - i.e.  if there is a chance that
                    there might be two processes accessing the context
                    in parallel. It is an error to copy a context if
                    not within a new process.

          ctxt.run(args, last)
                    Run executes a sh command.  Last should be non-
                    zero if this is the last time that run will be
                    called, so sh does not have to spawn a new process
                    in order to hide file redirection side-effects.

          ctxt.addmodule(name, mod)
                    Addmodule adds the Shellbuiltin module mod to its
                    list of builtin modules.  The module will be ini-
                    tialised as described in ``Builtin modules'',
                    below.

          ctxt.addbuiltin(name, mod)
                    Addbuiltin may be called by a module that has pre-
                    viously been loaded by addmodule or by the load sh
                    command to add a new builtin command to the shell.
                    Any subsequent invocation of name within ctxt will
                    result in a call of runbuiltin() to mod. Any
                    attempt to redefine the command ``builtin'' will
                    be ignored.

          ctxt.removebuiltin(name, mod)
                    Removebuiltin removes name from the list of buil-
                    tin commands in ctxt. If name had not previously
                    been defined by mod, or had subsequently been
                    replaced, then this function does nothing.

          ctxt.addsbuiltin(name, mod)
                    Addsbuiltin may be called by a module that has
                    previously been loaded by addmodule or by the load
                    sh command to add a new builtin substitution oper-
                    ator to the shell.  Any subsequent invocation of
                    ${name} within ctxt will result in a call of
                    runsbuiltin() to mod.

          ctxt.removesbuiltin(name, mod)
                    Removesbuiltin removes name from the list of buil-
                    tin substitution operators in ctxt. If name had
                    not previously been defined by mod, or had subse-
                    quently been replaced, then this function does
                    nothing.

          ctxt.fail(ename, msg)
                    Fail prints msg to the standard error if message
                    printing is currently enabled, and raises the
                    exception fail:ename.

     Page 4                       Plan 9            (printed 12/21/24)

     SH(2)                                                       SH(2)

          ctxt.options()
                    Options returns a bitmask of the options currently
                    enabled in ctxt. The bits are defined by constants
                    declared within Context.  They include:

                    ctxt.INTERACTIVE
                         Sh is currently being run from an interactive
                         command-line.

                    ctxt.VERBOSE
                         Message printing is currently enabled.

                    ctxt.EXECPRINT
                         Commands are printed to standard error as
                         they are executed.

                    ctxt.ERROREXIT
                         An exception will be raised when the first
                         simple command returns an error status.

                    Options are defined in the innermost scope of ctxt
                    and will be lost when it is popped.

          ctxt.setoptions(flags, on)
                    Setoptions sets the specified flags within ctxt.
                    Flags is a bitmask of options, as described in
                    options, above. If on is non-zero, the specified
                    bits will be set; otherwise they will be reset.
                    Setoptions returns the previously set options bit-
                    mask.

        Builtin modules
          Shellbuiltin specifies the interface to a loadable sh buil-
          tin module. Any Limbo module mod adhering to this interface
          may be loaded into the shell.

          mod->initbuiltin(ctxt, sh)
                    Initbuiltin is called when sh loads mod either via
                    the load command, or via the loadmodule() func-
                    tion.  Ctxt is the context within which the buil-
                    tin has been loaded, and sh is the Sh module
                    itself. When initbuiltin is called, mod is
                    expected to call ctxt.addbuiltin and
                    ctxt.addsbuiltin to define any builtin commands
                    and builtin substitution operators that it wants.
                    If an error occurs on initialisation, initbuiltin
                    should return a non-nil value; this will cause the
                    load to fail.

          mod->runbuiltin(ctxt, sh, cmd, last)
                    Runbuiltin is invoked when sh executes a command
                    that has previously been defined as a builtin

     Page 5                       Plan 9            (printed 12/21/24)

     SH(2)                                                       SH(2)

                    command by mod. Ctxt is the current execution con-
                    text (which may not be the original context passed
                    to initbuiltin()), sh is the running Sh module,
                    and cmd is the command to be executed.  Last is
                    true if this is the last command to be executed in
                    the current process; it can be passed to
                    ctxt.run() as appropriate.  The name of the com-
                    mand can be found in (hd cmd).word.  Runbuiltin
                    returns its exit status; by convention this is the
                    exit status of the last command executed.  A non-
                    nil exit status is usually treated as false.  By
                    convention, if an invalid set of arguments are
                    passed to a builtin command, a usage exception is
                    raised by calling ctxt.fail with usage and an
                    explanatory usage message as arguments.

          mod->runsbuiltin(ctxt, sh, cmd)
                    Similar to runbuiltin, runsbuiltin is called when
                    sh encounters a builtin substitution operator that
                    has previously been defined by mod. It returns the
                    list of values that will be substituted in place
                    of the operator.

          mod->getself()
                    Getself should return the Shellbuiltin module han-
                    dle for mod, usually obtained by invoking load
                    $self.  N.B. it is important that the value
                    returned by getself is the same as that passed to
                    addbuiltin or addsbuiltin.  As the Limbo load
                    operator returns a different value each time, the
                    value to be returned by getself() should be ini-
                    tialised once, during the call to initbuiltin().

          mod->whatis(ctxt, sh, name, wtype)
                    Whatis is called by the shell's whatis command to
                    query the definition of a name.  Wtype gives the
                    type of name that is being asked about; it can be
                    BUILTIN (conventional commands), SBUILTIN (substi-
                    tution builtins), or OTHER (any other names that
                    the module defines).  Return nil to get the usual
                    default behaviour. The std module, for example,
                    uses this feature to display the definition of a
                    shell function correctly.

        Exceptions
          The exceptions used within sh are exactly the same as those
          used within Limbo, except that all exceptions generated by
          the shell are prefixed by the string ``fail:'', and any
          exception caught with the prefix fail: has its first 5 char-
          acters removed before being made available to the sh script.
          This adheres to the convention defined by other shells
          within Inferno that a process that raises an exception with

     Page 6                       Plan 9            (printed 12/21/24)

     SH(2)                                                       SH(2)

          a fail: prefix is just returning a non-zero exit status, and
          should not be left in a Broken state.  It also means that
          the number of bytes available for the exception string is
          reduced by 5 (to 59). Care must therefore be taken to avoid
          generating an exception with a name that is too long; sh
          takes the pragmatic approach of truncating any exception
          string that is too long.

     FILES
          /prog/pid/wait
                    The file used by the shell to wait for dead child
                    processes.

     SOURCE
          /appl/cmd/sh/sh.y

     SEE ALSO
          sh(1), sh-std(1), sh-expr(1), sh-tk(1), sys-exception(2)

     Page 7                       Plan 9            (printed 12/21/24)