SH-STD(1)SH-STD(1)NAME
std, if, while, ~, no, !, apply, getlines, status, pctl, fn, and, or,
raise, rescue, hd, tl, index, split, join, pid, parse, pipe, env -
standard shell builtins module.
SYNOPSIS
load std
! command
~ value [ pattern... ]
no [ arg... ]
and command...
apply command [ arg... ]
getlines [ separators ] command
flag f [ +- ]
for var in [ arg... ] command
fn name command
if condition action [ condition action ]... [ elseaction ]
or command...
pctl flag...
raise name
rescue pattern rescueblock command
status value
subfn name command
while condition command
${hd list}
${index number list}
${pid}
${split [ separators ] arg}
${join separator list}
${tl list}
${parse arg]
${pipe ( from | to | fdnum ) command}
${env}
DESCRIPTION
Std is a loadable module for sh(1) that provides the equivalent of a
``standard library'' for the shell, including a set of control-flow
constructs and some other miscellaneous commands. In the following
descriptions, if an argument is executed, then it should be a braced
block suitable for executing by sh. A true exit status is defined to
be nil; any non-nil exit status is false. Unless otherwise stated, the
return value of a command is that of the last command that it executed.
If invalid arguments are passed to any command, a usage exception is
raised, and a message printed to stderr.
Each of the looping commands for, apply, while, and getlines installs
an exception handler for the duration of the loop to catch the excep‐
tions break and continue. If a break exception is caught, the loop is
terminated; if a continue exception is caught, the loop will continue
executing as usual. The commands are as follows:
! ! inverts the exit status of a command (non-null is changed
to null, null is changed to non-null).
~ ~ matches value against each pattern in turn, returning true
if any of them match and false otherwise. The patterns are
of the same form as those accepted by the shell for filename
pattern matching except that / is not treated specially. (see
filepat(2)). Patterns must be quoted to stop the shell from
interpreting them.
no True if there are no arguments. Useful for testing if there
are any items in a list without counting the items with $#.
and And evaluates each command in turn until one returns false.
apply Apply evaluates command once for each arg, passing it in the
variable $1.
getlines Getlines reads lines from the standard input, executing com‐
mand for each line, setting the environment variable $line to
the line read, with any terminating character removed. If
separators is given, a line is terminated when any character
in separators is found; the default separator string is a
single newline character.
flag Either set (+), clear (-), or test (neither + or -) the flag
f, where f is a single character, one of the command line
flags to sh (see sh(1)).
fn Fn defines a new builtin command named name; when run, this
command evaluates command. The command is stored in the
environment variable fn-name; any variables of this form
found when when std is loaded will be defined in this way.
If command is not given, then the builtin will be removed.
subfn Subfn is similar to fn except that it defines a new substitu‐
tion builtin name. When name is invoked, it creates a new
local variable result and executes command. The value of
$result when command has terminated is the value yielded by
the substitution builtin name. Command is stored in and
restored from the environment in a similar way to fn, except
that sfn-name is used as the name of the environment vari‐
able.
if If executes condition; if it returns true, then action is
executed, otherwise each of the next condition-action pairs
is evaluated in the same way; if no condition is satisfied,
then elseaction will be executed, if present.
for For is similar to apply; it runs command once for each arg,
but it performs a local assignment of arg to var each time.
or Or evaluates each command in turn until one returns true.
pctl Pctl is an interface to the Inferno system call sys-pctl(2);
each argument specifies one bit in the bitmask passed to that
function. The possible flags are newfd, forkfd, newns,
forkns, newpgrp and nodevs. See sys-pctl(2) for details of
the meaning of these flags. Pctl returns true.
raise Raise raises the exception name; name will be truncated if it
is longer than that allowed by raise (128 bytes in utf(6)
representation). Control will be transferred to the inner‐
most rescue block in the same process that matches name. If
there is no rescue block in place, the current process will
exit, yielding name as its exit status. If no name is given,
the exception named in $exception is raised; if this is null,
a bad raise context exception is raised. The default command
prompt catches all exceptions.
rescue Rescue executes command with an exception handler installed
for the duration of the call. It will catch all exceptions
with a name matching pattern, where pattern is of the same
form accepted by Limbo's exception handling statement.
Specifically, the pattern is a string that matches literally,
except that a trailing `*' character will match any sequence
of characters. If an exception is caught, rescue executes
rescueblock, setting $exception to the name of the exception
raised.
status returns its first argument word as its exit status, or nil if
none is given.
while While repeatedly executes condition and then action until
condition does not return true.
${env} Env yields a list of the names of all currently set non-nil
environment variables.
${hd} Hd yields the first of its arguments, or nil if there are no
arguments.
${index} Index yields the n'th element in its argument list, indexed
from 1. N must be a decimal integer.
${join} Join yields a single element which is the concatenation of
all the elements in list separated by separator. If there
are no elements in list, it yields an empty string. The
shell operator $"var is exactly equivalent to ${join ' '
$var}.
${parse} Parse parses arg according to the usual syntax rules, raising
a parse error exception if it fails. Arg must be a well-
formed command block surrounded by braces. Parse yields a
functionally equivalent version of arg.
${pid} Pid yields the process id of the current process.
${pipe} Pipe runs command asynchronously, with one of its file
descriptors connected to a bidirectional pipe. The first
argument to pipe determines which file descriptor is con‐
nected: if the argument is from, its standard output is con‐
nected; if the argument is to, its standard input is con‐
nected; otherwise file descriptor fdnum is connected. Pipe
yields the name of a file that can be opened to access the
other end of the pipe. Note that this command is now depre‐
cated in favour of the <{} redirection operator built in to
the shell.
${split} Split splits arg into list elements at every point where one
or more characters in separators appear. If separators is not
given, the value of $ifs is used.
${tl} Tl yields all but the first of its arguments, or nil if there
are no arguments.
Syntactic considerations
It is worth being aware of a few pitfalls that await the user of some
of these commands. Unlike other shells, the syntax of sh does not
include the syntax of the control flow commands, so it is important to
be aware of the rules that govern the gathering of the arguments for a
command. In particular, the following code, written to print a message
a filename ends in .b will not work: it will always print ``file is
Limbo source''.
and
{~ $filename '*.b'}
{echo file is Limbo source}
This is because newlines separate shell commands, so the above code
first invokes and with no arguments, and then each of the braced block
commands on each subsequent line. It is usual to use round brackets in
order to group together arguments on separate lines, e.g.
and (
{~ $filename '*.b'}
{echo file is Limbo source}
)
This has the originally intended meaning.
FILES
/tmp/pipe.*d
Temporary placeholder directory for named pipes.
/tmp/pipes/*
Mount point for named pipes.
SOURCE
/appl/cmd/sh/std.b
SEE ALSOsh(1), sh-expr(1), sh-tk(1)SH-STD(1)
