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 exceptions
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
command
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 substitution 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 variable.
- 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 innermost
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 connected: if
the argument is
from,
its standard output is connected; if the argument is
to,
its standard input is connected; 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
deprecated 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.