[manual index][section index]

NAME

std, if, while, ~, no, !, apply, getlines, status, pctl, fn, and, or, raise, rescue, hd, tl, index, split, join, pid, parse, pctl, 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 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.

FILES

/tmp/pipe.*d
Temporary placeholder directory for named pipes.
/tmp/pipes/*
Mount point for named pipes.

SOURCE

/appl/cmd/sh/std.b

SEE ALSO

sh(1), sh-expr(1), sh-tk(1)

SH-STD(1 ) Rev:  Tue Nov 27 18:20:36 GMT 2007