Linux repositories inspector

xs(1)

2017 - v1.1
5 March 1992

xs

Shell supporting functional programming

NAME

xs - extensible shell

SYNOPSIS

xs [-silevxnpodV] [-c command | file] [arguments]

DESCRIPTION

Xs is a command interpreter and programming language which combines the features of other Unix shells and the features of a functional programming language such as Scheme. Xs is a descendant of rc(1) and es(1); the three implementations are similar in scope and style, but not compatible with each other.
Xs is intended for use both as an interactive shell and a programming language for scripts.
Xs is an extremely customizable language. The semantics can be altered radically by redefining functions that are called to implement internal operations. This manual page describes the default, initial configuration. See the section entitled Hook Functions for details on entry points which can be redefined to give the shell extended semantics.

LANGUAGE

Xs is an interpreter which reads commands and executes them. The simplest form of command in xs is a sequence of words separated by white space (space and tab) characters. A word is either a string or a program fragment (see below). The first word is the command to be executed; the remaining words are passed as arguments to that command. If the first word is a string, it is a interpreted as the name of a program or shell function to run. If the name is the name of a shell function, that function is executed. Otherwise, the name is used as the name of an executable file. If the name begins with or then it is used as the absolute path name of a file; if not, xs looks for an executable file in the directories named by
Commands are terminated by newline or semicolon A command may also be terminated by an ampersand which causes the command to be run in the background: the shell does not wait for the command to finish before continuing execution. Background processes have an implicit redirection of as their standard input that may be overridden by an explicit redirection.

Quoting

Xs gives several characters special meaning; special characters automatically terminate words. The following characters, along with space, tab, and newline, are special:

The single quote prevents special treatment of any character other than itself. Any characters between single quotes, including newlines, backslashes, and control characters, are treated as an uninterpreted string. A quote character itself may be quoted by placing two quotes in a row. A single quote character is therefore represented by the sequence The empty string is represented by Thus:

prints out

The backslash quotes the immediately following character, if it is one of the special characters, except for newline. In addition, xs recognizes backslash sequences similar to those used in C strings:
alert (bell)
backspace
escape
form-feed
newline
carriage return
tab
hexadecimal character
nn, for n in {0..9, a..f, A..F}
octal character mnn, for m in {0..3} and n in {0..7}
Unicode character nnnn, for n in {0..9, a..f, A..F}
Unicode character
nnnnnnnn, for n in {0..9, a..f, A..F}
The character escapes may be used with to create characters from codepoints at runtime.

Comments

The number sign begins a comment in xs. All characters up to but not including the next newline are ignored.

Line continuation

A long logical line may be continued over several physical lines by terminating each line (except the last) with a backslash The backslash-newline sequence is treated as a space. Note that line continuation does not work in comments, where the backslash is treated as part of the comment, and inside quoted strings, where the backslash and newline are quoted.

Lists

The primary data structure in xs is the list, which is a sequence of words. Parentheses are used to group lists. The empty list is represented by Lists have no hierarchical structure; a list inside another list is expanded so that the outer list contains all the elements of the inner list. (This is the same as perl’s "list interpolation".) Thus, the following are all equivalent:

Note that the null string, and the empty list, are two very different things. Assigning the null string to variable is a valid operation, but it does not remove its definition.
Since lists can span multiple lines without explicit line continuations, they are ideal for long commands. For example:


Finally, note that there are some uses of parentheses not following ordinary list rules: in let/local/%closure bindings, and in assignments.

Concatenation

Two lists may be joined by the concatenation operator A single word is a list of length one, so

produces the output

For lists of more than one element, concatenation produces the cross (Cartesian) product of the elements in both lists:

produces the output

Variables

A list may be assigned to a variable, using the notation

Whitespace is required around the assignment operator; this allows it to be treated as a normal string character. This is true also for assignment in let-forms and the like. Any sequence of non-special characters, except a sequence including only digits, may be used as a variable name. Xs exports all user-defined variables into the environment unless it is explicitly told not to.
The value of a variable is referenced with the notation:

Any variable which has not been assigned a value returns the empty list when referenced. In addition, multiple references are allowed:

prints

A variable’s definition may be removed by assigning the empty list to a variable:

Multiple variables may be assigned with a single assignment statment. The left hand side of the assignment operation consists of a list of variables which are assigned, one by one, to the values in the list on the right hand side. If there are more variables than values in the list, the empty list is assigned to the remaining variables. If there are fewer variables than elements in the list, the last variable is bound to all the remaining list values.
For example,

has the same effect as


and
is the same as

Note that when assigning values to more than one variable, the list of variables must be enclosed in parentheses.
For ‘‘free careting’’ (see below) to work correctly, xs must make certain assumptions about what characters may appear in a variable name. Xs assumes that a variable name consists only of alphanumeric characters, percent star dash and underscore To reference a variable with other characters in its name, quote the variable name. Thus:

A variable name produced by some complex operation, such as concatenation, should be enclosed in parentheses:

Thus:

prints

Each element of the list in parentheses is treated as an independent variable and expanded separately. Thus, given the above definitions,

prints

To count the number of elements in a variable, use

This returns a single-element list with the number of elements in

Subscripting

Variables may be indexed with the notation

where n is a list of integers or ranges. Subscript indexes are based at one. The list of subscripts need not be in order or even unique. Thus, if

then

prints

Subscript indices which refer to nonexistent elements expand to the empty list. Thus, given the definition above

prints

Subscript ranges are of the form and refer to all the elements between lo and hi. If lo is omitted, then is used as a default value; if hi is omitted, the length of the list is used. Thus

removes the first element of similar to the effect of in rc(1) or sh(1).
If lo is greater than hi, the elements in the result are listed from hi to lo.
The notation where n is an integer, is a shorthand for Thus, xs’s arguments may be referred to as and so on.
Note that the list of subscripts may be given by any xs expression, so

returns the first 10 elements of
Constructed variables, such as may not be subscripted.
Subscripted variables may not be used on the left-hand side of the assignment operator.

Free Carets

Xs inserts carets (concatenation operators) for free in certain situations, in order to save some typing on the user’s behalf. For example, the following are all equivalent:

Xs inserts a free-caret between the and as well as between and The rule for free carets is as follows: if a word or keyword is immediately followed by another word, keyword, dollar-sign or backquote without any intervening spaces, then xs inserts a caret between them.

Flattened Lists

To create a single-element list from a multi-element list, with the components space-separated, use

Flattening is useful when the normal list concatenation rules need to be bypassed. For example, to append a single period at the end of use:

Wildcard Expansion

Xs expands wildcards in filenames if possible. When the characters or occur in an argument or command, xs looks at the argument as a pattern for matching against files. (Contrary to the behavior some other shells exhibit, xs will only perform pattern matching if a metacharacter occurs unquoted and literally in the input. Thus,

will always echo just a star. In order for non-literal metacharacters to be expanded, an statement must be used in order to rescan the input.)
Pattern matching occurs according to the following rules: a matches any number (including zero) of characters. A matches any single character, and a followed by a number of characters followed by a matches a single character in that class. The rules for character class matching are the same as those for ed(1), with the exception that character class negation is achieved with the tilde not the caret since the caret already means something else in xs. The filename component separator, slash must appear explicitly in patterns. and do not match a dot character at the beginning of a filename component.
A tilde as the first character of an argument is used to refer to home directories. A tilde alone or followed by a slash is replaced by the value of which is usually the home directory of the current user. A tilde followed by a username is replaced with the home directory of that user, according to getpwent(3).

Pattern Matching

The tilde operator is used in xs for matching strings against wildcard patterns. The command

returns a true value if and only if the subject matches any of the patterns. The matching follows the same rules as wildcard expansion, except that slashes are not considered significant, leading dots do not have to be matched explicitly, and home directory expansion does not occur. Thus

returns zero (true), while

returns one (false). The null list is matched by the null list, so

checks to see whether is empty or not. This may also be achieved by the test

Note that inside a command xs does not match patterns against file names, so it is not necessary to quote the characters and However, xs does expand the subject against filenames if it contains metacharacters. Thus, the command

returns true if any of the files in the current directory have a single-character name. Note that if the command is given a list as its first argument, then a successful match against any of the elements of that list will cause to return true. For example:

is true.

Pattern Extraction

The double-tilde operator is used in xs for extracting the parts of strings that match patterns. The command

returns the parts of each matching subject which correspond to the wildcards.
Each subject is checked in order against each pattern; if it matches the pattern, the parts of the subject which matched each or character range are extracted, and processing moves on to the next subject. If the subject does not match, the next pattern is tried.
For example, the result of the extraction operation

is the list

Arithmetic Substitution

A single list element can be formed from an infix arithmetical expression like so:

The expression can use any of the and operators, and use variable substitution of the form Variable names containing or are not allowed within an arithmetic expression.
Parentheses can be used in normal infix fashion to alter order of evaluation. Absent parentheses, evaluation follows the usual precedence.
Numbers can be written as floating-point or integer, but are always decimal. Scientific notation (e.g. 1.23e11) will be used to print very large and small floating-point values, but is not allowed in literal numbers.
Any arithmetic operation involving floats produces a float; any operation with only integers produces an integer.
Integers have the behavior of the native platform’s Floats have the behavior of the native platform’s
xs’s floats are stored with limited (typically 6 signicant digits) precision.

Command Substitution

A list may be formed from the output of a command by using backquote substitution:

returns a list formed from the standard output of the command in braces. The characters stored in the variable (for ‘‘input field separator’’) are used to split the output into list elements. By default, has the value space-tab-newline. The braces may be omitted if the command is a single word. Thus may be used instead of This last feature is useful when defining functions that expand to useful argument lists. A frequent use is:

followed by

(This will print out a word-count of all C and Yacc source files in the current directory.)
In order to override the value of for a single command substitution, use:

will be temporarily ignored and the command’s output will be split as specified by the list following the double backquote. For example:

splits up into fields.

Return Values

The return value of a command is obtained with the construct

The return value of an external program is its exit status (which in other shells can be found in special variables such as or as either a small integer or the name of signal. Thus

might produce the output

along with any output or error messages from the programs.
If the command is a pipeline, lists the return value of each program.
Xs functions and primitives can produce ‘‘rich return values,’’ that is, arbitrary lists as return values.
When return values are interpreted as truth values, an extension of the normal shell conventions apply. If any element of a list is not equal to (or the empty string), that list is considered false.
The return value of an assignment operation is the assigned value. Thus, assigns the same value to both

Logical Operators

There are a number of operators in Xs which depend on the exit status of a command.

executes the first command and then executes the second command if and only if the first command has a ‘‘true’’ return value.

executes the first command and then executes the second command if and only if the first command has a ‘‘false’’ return value.

inverts the truth value of the exit status of a command.

Relational Operators

Xs has the usual complement of relational operators. To avoid confusion with redirection or assignment, the relops are spelled: :lt, :le, :gt, :ge, :eq and :ne. The relational operators are built upon %cmp and return a boolean value.

Input and output

The standard output of a command may be redirected to a file with

and the standard input may be taken from a file with

File descriptors other than 0 and 1 may be specified also. For example, to redirect standard error to a file, use:

In order to duplicate a file descriptor, use Thus to redirect both standard output and standard error to the same file, use

To close a file descriptor that may be open, use For example, to close file descriptor 7:

In order to place the output of a command at the end of an already existing file, use:

If the file does not exist, then it is created.
To open a file for reading and writing, use the redirection operator; for reading and appending, use Both of these operators use file descriptor 0 (standard input) by default. Similarly, truncates a file and opens it for reading and writing, and opens a file for reading and appending; these operators use file descriptor 1 by default.
‘‘Here documents’’ are supported as in sh(1) with the use of

If the end-of-file marker is quoted, then no variable substitution occurs inside the here document. Otherwise, every variable is substituted by its space-separated-list value (see Flat Lists, below), and if a character follows a variable name, it is deleted. This allows the unambiguous use of variables adjacent to text, as in

To include a literal in a here document created with an unquoted end-of-file marker, use
Additionally, xs supports ‘‘here strings’’, which are like here documents, except that input is taken directly from a string on the command line. Its use is illustrated here:

(This feature enables xs to export functions that use here documents.)
Subscripted and constructed variables are not supported in here documents and here strings.

Pipes

Two or more commands may be combined in a pipeline by placing the vertical bar between them. The standard output (file descriptor 1) of the command on the left is tied to the standard input (file descriptor 0) of the command on the right. The notation indicates that file descriptor n of the left process is connected to file descriptor m of the right process. is a shorthand for As an example, to pipe the standard error of a command to wc(1), use:

The exit status of a pipeline is considered true if and only if every command in the pipeline exits true.

Input/Output Substitution

Some commands, like cmp(1) or diff(1), take their input from named files on the command line, and do not use standard input. It is convenient sometimes to build nonlinear pipelines so that a command like cmp can read the output of two commands at once. Xs does it like this:

compares the output of the two commands. Note: on some systems, this form of redirection is implemented with pipes, and since one cannot lseek(2) on a pipe, commands that use lseek will hang. For example, most versions of diff seek on their inputs.
Data can be sent down a pipe to several commands using tee(1) and the output version of this notation:

Program Fragments

Xs allows the intermixing of code with strings. A program fragment, which is a group of commands enclosed in braces may be used anywhere a word is expected, and is treated as an indivisible unit. For example, a program fragment may be passed as an argument, stored in a variable, or written to a file or pipe. If a program fragment appears as the first word in a command, it is executed, and any arguments are ignored. Thus the following all produce the same output:

Since program fragments in the first position in a command are executed, braces may be used as a grouping mechanism for commands. For example, to run several commands, with output from all of them redirected to the same file, one can do

In addition, program fragments can continue across multiple physical lines without explicit line continuations, so the above command could also be written:

A lambda is a variant on a program fragment which takes arguments. A lambda has the form

The parameters are one or more variable names, to which arguments of the lambda are assigned while the commands are run. The first argument is assigned to the first variable, the second to the second, and so on. If there are more arguments than parameters, the last named variable is assigned all the remaining arguments; if there are fewer, the parameters for which there are no arguments are bound to the empty list.
Lambdas, like other program fragments, can appear anywhere in a list. A more complicated example in the same spirit:

This command executes a lambda which runs its first argument, named using its second argument, named as the argument for the first. The first argument of this function is another lambda, seen previously, and the second argument is the word
These lambda expressions

produce this output:

Functions

A function in xs is introduced with the syntax

If the function name appears as the first word of a command, the commands are run, with the named parameters bound to the arguments to the function.
The similarity between functions and lambdas is not coincidental. A function in xs is a variable of the form If name for which the appropriate variable exists is found in the first position of a command, the value of the variable is substituted for the first word. The above syntax for creating functions is equivalent to the variable assignment

Functions may be deleted with the syntax

which is equivalent to the assignment

If, as the most common case, a function variable is bound to a lambda, when the function is invoked, the variable is bound (dynamically, see below) to the name of the function.
Lambdas are just another form of code fragment, and, as such, can be exported in the environment, passed as arguments, etc. The difference between the two forms is that lambdas bind their arguments, while simple brace-enclosed groups ignore theirs.

Local Variables

Variable assignments may be made local to a set of commands with the construct:

The command may be a program fragment, so for example:

sets to a minimal useful path and removes for the duration of one long compound command.
Local-bound variables are exported into the environment, and will invoke appropriately named settor functions (see below).

Lexically Scoped Variables

In addition to local variables, xs supports a different form of temporary variable binding, using let-bound, or ‘‘lexically scoped,’’ variables. (Lexical scoping is the form of binding used by most compiled programming languages, such as C or Scheme.) A lexically scoped variable is introduced with a statement:

The "= value" can be left out with same effect as "var =".
All references to any of the variables defined in a statement by any code located lexically (that is, textually) within the command portion of the statement will refer to the let-bound variable rather than any environment or local-bound variable; the immediate text of the statement is the complete extent of that binding. That is, lexically bound variables surrounding code fragments follow those code fragments around.
An example best shows the difference between and (also known as ‘‘dynamic’’) binding: (note that is xs’s default prompt.)

Lexically bound variables are not exported into the environment, and never cause the invocation of settor functions. Function (lambda) parameters are lexically bound to their values.

For loops

The command

Runs the command once for each element of the list, with the named variable bound lexically to each element of the list, in order. Note that if list consists of more than a single term, for example (a b c) it must be parenthesized.
If multiple bindings are given in the statement, the looping occurs in parallel and stops when all lists are exhausted. When one list is finished before the others, the corresponding variable is bound to the empty list for the remaining iterations. Thus the loop

produces the output

Settor Functions

A settor function is a variable of the form which is typically bound to a lambda. Whenever a value is assigned to the named variable, the lambda is invoked with its arguments bound to the new value. While the settor function is running, the variable is bound to the name of the variable being assigned. The result of the settor function is used as the actual value in the assignment.
For example, the following settor function is used to keep the shell variables and synchronized.

This settor function is called when any assignment is made to the variable It assigns the new value to the variable but disables any settor function for to prevent an infinite recursion. Then it returns its argument unchanged for use in the actual assignment to
Settor functions do not apply to lexically bound variables.

Primitives

Primitives are internal xs operations that cannot or should not (for reasons of performance) be written in the interpreter’s language. The set of primitives makes up the run-time library for xs.
Primitives can be used with the syntax

A primitive can be used anywhere a lambda is expected. The list of primitives is returned as the result of the primitive
For details on specific primitives, see the section entitled PRIMITIVES below.

Exceptions

Exceptions in xs are used for many forms of non-structured control flow, notably error reporting, signals, and flow of control constructs such as
Exceptions are passed up the call chain to catching routines. A catcher may decide to intercept an exception, retry the code that caused the exception, or pass the exception along. There can only be one exception raised at any time.
Exceptions are represented by lists. The first word of an exception is, by convention, the type of exception being raised. The following exceptions are known:
Raised by when the end of input is reached.
A run-time error.
Almost all shell errors are reported with the exception. The default interactive loop and the outermost level of the interpreter catch this exception and print the message. Source is the name of the routine (typically a primitive) which raised the error.
Exits
xs with or with if is not specified.
When raised from a signal catcher, causes the body of the clause to be run again. If the cause of the caught signal is not resolved, invoking will create an uninterruptible loop.
Raised when the shell itself receives a signal,
and the signal is listed in the variable Signame is the name of the signal that was raised.
See the builtin commands and for details on how to manipulate exceptions.

SPECIAL VARIABLES

Several variables are known to xs and are treated specially. Redefining these variables can change interpreter semantics. Note that only dynamically bound (top-level or variables are interpreted in this way; the names of lexically bound variables are unimportant.
The argument list of xs. etc. are the same as etc.
Holds the value of with which xs was invoked. Additionally, is set to the name of a function for the duration of the execution of that function, and is also set to the name of the file being interpreted for the duration of a
The process ID of the last process started in the background.
The name of a file to which commands are appended as
xs reads them. The history builtin uses this file, if defined. To use an external program (such as history(1)), delete or redefine the xs history function. If is not set (the default), then xs does not append commands to any file.
The current user’s home directory, used in tilde expansion, as the default directory for the builtin command, and as the directory in which xs looks to find its initialization file, if xs has been started up as a login shell, and if xs is an interactive shell. Like and and are aliased to each other.
The default input field separator, used for splitting up the output of backquote commands for digestion as a list. The initial value of is space-tab-newline.
This sets a limit on how many levels deep the interpreter’s evaluation
stack may become.
A list of variables which
xs will not export. All variables except for the ones on this list and lexically bound variables are exported.
This is a list of directories to search in for commands. The empty string stands for the current directory. Note also that an assignment to causes an automatic assignment to and vice-versa. If neither nor are set at startup time, assumes a default value suitable for your system. This is typically
The process ID of the currently running xs.
This variable holds the two prompts (in list form) that xs prints. is printed before each command is read, and is printed when input is expected to continue on the next line. (See for details.)
xs sets to by default. The reason for this is that it enables an xs user to grab commands from previous lines using a mouse, and to present them to xs for re-interpretation; the semicolon prompt is simply ignored by xs. The null also has its justification: an xs script, when typed interactively, will not leave on the screen, and can therefore be grabbed by a mouse and placed directly into a file for use as a shell script, without further editing being necessary.
Contains a list of the signals which
xs traps. Any signal name which is added to this list causes that signal to raise an xs exception. For example, to run some commands and make sure some cleanup routine is called even if the user interrupts or disconnects during the script, one can use the form:
A signal name prefixed by a hyphen causes that signal to be ignored by xs and all of its child processes, unless one of them resets its handler. A signal prefixed by a slash is ignored in the current shell, but retains default behavior in child processes. In addition, the signal may be preceeded by the prefix to indicate that normal shell interrupt processing (i.e., the printing of an extra newline) occurs. By default xs starts up with the values
in other values will be on the list if the shell starts up with some signals ignored.
The values of and are derived from the environment values of and if those values are present. This is for compatibility with other Unix programs, such as sh(1). is assumed to be a colon-separated list.
Also for compatibility, xs maintains the value of the variable, creating it with a value of if needed and incrementing the value when a new xs is spawned. Unlike the other variables in this section, the value of has no influence upon the behavior of the interpreter.

SYNTACTIC SUGAR

xs internally rewrites much of the syntax presented thus far in terms of calls to shell functions. Most features of xs that resemble traditional shell features are included in this category. This rewriting occurs at parse time, as commands are recognized by the interpreter. The shell functions that are the results of rewriting are some of the hook functions documented below.
The following tables list all of the major rewriting which xs does, with the forms typically entered by the user on the left and their internal form on the right. There is no reason for the user to avoid using the right-hand side forms, except that they are usually less convenient. To see the internal form of a specific command, a user can run xs with the and options; when invoked in this way, the shell prints the internal form of its commands rather than executing them.

Control Flow

! cmd                  %not {cmd}
cmd &                  %background {cmd}
cmd1 ; cmd2            %seq {cmd1} {cmd2}
cmd1 && cmd2           %and {cmd1} {cmd2}
cmd1 || cmd2           %or {cmd1} {cmd2}
fn name {|args| cmd}   fn-^name = {|args| cmd}

Input/Output Commands

cmd < file             %open 0 file {cmd}
cmd > file             %create 1 file {cmd}
cmd >[n] file          %create n file {cmd}
cmd >> file            %append 1 file {cmd}
cmd <> file            %open-write 0 file {cmd}
cmd <>> file           %open-append 0 file {cmd}
cmd >< file            %open-create 1 file {cmd}
cmd >>< file           %open-append 1 file {cmd}
cmd >[n=]              %close n {cmd}
cmd >[m=n]             %dup m n {cmd}
cmd << tag input tag   %here 0 input {cmd}
cmd <<< string         %here 0 string {cmd}
cmd1 | cmd2            %pipe {cmd1} 1 0 {cmd2}
cmd1 |[m=n] cmd2       %pipe {cmd1} m n {cmd2}
cmd1 >{ cmd2 }         %writeto var {cmd2} {cmd1 $var}
cmd1 <{ cmd2 }         %readfrom var {cmd2} {cmd1 $var}

Expressions

$#var                  <={%count $var}
$^var                  <={%flatten ’ ’ $var}
`{cmd args}            <={%backquote <={%flatten ’’ $ifs} {cmd args}}
``ifs {cmd args}       <={%backquote <={%flatten ’’ ifs} {cmd args}}

Relational Operators

a :lt b                {~ {%cmp a b} -1}
a :le b                {~ {%cmp a b} -1 0}
a :gt b                {~ {%cmp a b} 1}
a :ge b                {~ {%cmp a b} 1 0}
a :eq b                {~ {%cmp a b} 0}
a :ne b                {~ {%cmp a b} -1 1}

BUILTINS

Builtin commands are shell functions that exist at shell startup time. Most builtins are indistinguishable from external commands, except that they run in the context of the shell itself rather than as a child process. Many builtins are implemented with primitives (see above).
Some builtin functions have names that begin with a percent character These are commands with some special meaning to the shell, or are meant for use only by users customizing the shell. (This distinction is somewhat fuzzy, and the decisions about which functions have are somewhat arbitrary.)
All builtins can be redefined and extended by the user.

Builtin Commands

Reads
file as input to xs and executes its contents. The options are a subset of the invocation options for the shell (see below).
Tests if the named paths are accessible according to the options presented.
Normally, returns zero (true) for files which are accessible and a printable error message (which evaluates as false, according to shell rules) for files which are not accessible. If the option is used, the name of the first file which the test succeeds for is returned; if the test succeeds for no file, the empty list is returned. However, if the option was used, raises an exception. If the option is used, the pathname arguments are treated as a list of directories, and the name option argument is used as a file in those directories is used for path searching).
The default test is whether a file exists. These options change the test:
Is the file readable (by the current user)?
Is the file writable?
Is the file executable?
Is the file a plain file?
Is the file a directory?
Is the file a character device?
Is the file a block device?
Is the file a symbolic link?
Is the file a socket?
Is the file a named pipe (FIFO)?
Define a new function,
alias-name , which calls expansion The first command in expansion is replaced with it’s whatis value to prevent recursion. This can be used to serve a somewhat similar purpose as in bash. For example, the following will force ls to use color, and make l be ls in long form, with color (due to previous alias):
Runs
body. If it raises an exception, catcher is run and passed the exception as an argument.
Changes the current directory to
directory. With no argument, changes the current directory to
Displays the directory stack. (See
pushd and popd.) With the option, clear the directory stack.
Prints its arguments to standard output, terminated by a newline.
Arguments are separated by spaces. If the first argument is no final newline is printed. If the first argument is then all other arguments are echoed literally; this is used for echoing a literal
Run lambda with one argument, an escape block
which when evaluated will return to the point after this escape. This is more formally refered to as an escape continuation. In fact, it’s behaviour is a simple subset of exceptions, and is implemented fairly simply using catch. Escape is useful to replace return/break like constructs; for example
will exit the function with result 0 when it reaches the return.
Concatenates the elements of
list with spaces and feeds the resulting string to the interpreter for rescanning and execution.
Replaces
xs with the given command. If the contains only redirections, then these redirections apply to the current shell and the shell does not exit. For example,
places further output to standard error in the file err.out. Unlike some other shells, xs requires that redirections in an be enclosed in a program fragment.
Causes the current shell to exit with the given exit
status. If no argument is given, zero (true) is used. (This is different from other shells, that often use the status of the last command executed.)
Always returns a false (non-zero) return value.
Runs the command repeatedly, until the shell exits or the
command raises an exception. This is equivalent to a loop except that does not catch any exceptions.
Runs a command in a subshell.
This insulates the parent shell from the effects of state changing operations such as and variable assignments. For example:
runs make(1) in the parent directory but leaves the shell in the current directory.
Display or modify the history list. (See the
history variable in SPECIAL VARIABLES.) With no options, the entire history list is displayed. A numeric option limits the display to the specified number of most recent entries. The -c option clears the history list, while -d # deletes the #’th history item. History recording may temporarily be turned off and on with the -n and -y options. When history has been turned off using the -n option, it may only be turned back on using the -y option in the same shell; not in a subshell.
Evaluates the command
test. If the result is true, the command then is run and completes. If the result of the test is false, the else command is run. The else-action doesn’t require braces no matter the number of actions, so one can write code like:
Note that:
with the else on a separate line, will only work if the if-command has parentheses wrapping its body and else-statements.
Display background job information.
Similar to the
csh(1) builtin, this command operates upon the resource limits of a process. With no arguments, prints all the current limits; with one argument, prints the named limit; with two arguments, it sets the named limit to the given value. The flag displays/alters the hard limits. The resources which can be shown or altered are and For example:
disables core dumps.
The limit values must either be the word or a number with an optional suffix indicating units. For size limits, the suffixes (kilobytes), (megabytes), and (gigabytes) are recognized. For time limits, (seconds), (minutes), and (hours) are known; in addition, times of the form and are accepted. See getrlimit(2) for details on resource limit semantics.
Call
action with a single argument for each element of list. Since lists auto-expand, list contains the rest of the arguments to the command. Returns the list of results of each action. If action returns a list, it is expanded inside into a new process group. This builtin is useful for making xs behave like a job-control shell in a hostile environment. One example is the NeXT Terminal program, which implicitly assumes that each shell it forks will put itself into a new process group. Note that the controlling tty for the process must be on standard error (file descriptor 2) when this operation is run.
Like
map , but return the list of the outputs of action, in the same form as if ‘‘ ’’ action (i.e. with an empty input field separator list) were called.
cd into the directory on top of the directory stack and pop the stack. If the stack is empty (for example, if pushd has not been called), then stay in the current directory. Also displays the remaining stack.
Print formatted text. Valid conversions are those of
printf(3p), including floating-point conversions. Length modifiers are not supported. Backslash escapes in the format are not interpreted by printf.
Add directory’s absolute path onto the directory stack,
cd into the directory and display the new stack. If dir is not provided and the stack is at least two deep, then alternate between the top two directories.
Reads from standard input and returns either the empty list (in the case of end-of-file) or a single element string with up to one line of data, including possible redirections. This function reads one character at a time in order to not read more data out of a pipe than it should. The terminating newline (if present) is not included in the returned string.
Returns its arguments.
This is xs’s identity function.
While may be used to return a lambda from a function, a closure associated with the function will not work. In other words, xs does not support upward funargs.
Go through the list of cases,
testing if they are equal to value. The matching action of the first case which matches is executed.
Raise the named exception, passing all of the arguments to
to the enclosing exception handler.
Prints, on the shell’s standard error,
the real, user, and system time consumed by executing the command.
Always returns a true (zero) return value.
Sets the current umask (see
umask(2)) to the octal mask. If no argument is present, the current mask value is printed.
Identical to while, except test is negated
Runs
body and, when it completes or raises an exception, runs cleanup.
Prints definitions of the named variables,
suitable for being used as input to the shell.
Prints all shell variables, functions, and settor functions
(in a form suitable for use as shell input), which match the criteria specified by the options.
variables (that are not functions or settor functions)
functions
settor functions
exported values
private (not exported) values
internal (predefined and builtin) values
all of the above
If none of are specified, is used. If none of are specified, is used.
Waits for the specified
pid, which must have been started by xs. If no pid is specified, waits for any child process to exit.
For each named
program, prints the pathname, primitive, lambda, or code fragment which would be run if the program appeared as the first word of a command.
Evaluates the
test and, if it is true, runs the body and repeats.

Hook Functions

A subset of the functions are known as ‘‘hook functions.’’ The hook functions are called to implement some internal shell operations, and are available as functions in order that their values can be changed. Typically, a call to a hook function is from code generated by the syntactic sugar rewritings.
Runs the commands in order, stopping after the first one
that has a false return value. Returns the result of the last command run.
Runs the command with file descriptor
fd set up to append to the file.
Runs the command in the background.
The shell variable contains the process ID of the background process, which is printed if the shell is interactive (according to
Runs the command in a child process and returns its
standard output as a list, separated (with the same rules used in into elements according to separator.
Parses commands from the current input source and
passes the commands to the function %dispatch, which is usually a dynamically bound identifier. This function catches the exception which causes it to return. This function is invoked by the shell on startup and from the dot and commands, when the input source is not interactive. (See also
Runs the command with the given file descriptor closed.
Compares its arguments and returns -1, 0 or 1 if
a is respectively less than, equal to or greater than b. If either argument is non-numeric, then the arguments are compared lexicographically, honoring the locale’s collation order.
The result is not defined for list arguments, except that comparisons may be made against the empty list. The result in this case is 0 if both arguments are either an empty list or an empty string, and nonzero otherwise.
Returns the number of arguments to the primitive.
Runs the command with file descriptor
fd set up to write to the file.
Runs the command with the file descriptor
oldfd copied (via dup(2)) to file descriptor newfd.
Run the command.
(Passed as the argument to and
Print and run the command.
(Passed as the argument to and when the option is used.)
This function, if it exists, is called in the context of a
child process if an executable file was found but execve(2) could not run it. If the function returns, an error message is printed and the shell exits, but the function can a program if it thinks it knows what to do. Note that the name of the program appears twice in the arguments to once as a filename and once as the first element of the array; in some cases the two will be identical, but in others the former will be a full pathname and the latter will just be the basename. Some versions of xs may provide a builtin version of this function to handle shell scripts if the kernel does not.
Runs the command, and exits if any command
(except those executing as the tests of conditional statements) returns a non-zero status. (This function is used as an argument to and when the shell is invoked with the option.)
Concatenate the elements of
list into one string, separated by the string separator.
Runs the command with the
words passed as input on file descriptor fd.
Returns the home directory of the named user, or
if there are no arguments.
Prompts,
parses commands from the current input source and passes the commands to the function %dispatch, which is usually a dynamically bound identifier. This function catches the exception which causes it to return. This function is invoked by the shell on startup and from the dot commands, when the input source is interactive. (See also
Do nothing.
(Passed as the argument to and when the option is used.)
Print but don’t run the command.
(Passed as the argument to and when the and options are used.)
Runs the command and returns false if its exit status was true,
otherwise returns true.
If
list is one element long, returns its value; otherwise it raises an exception. is used to ensure that redirection operations get passed exactly one filename.
Runs the command with
file open for reading on file descriptor fd.
Runs the command with
file open for reading and appending on file descriptor fd.
Runs the command with
file open for reading and writing on file descriptor fd. If the file already exists, it is truncated.
Runs the command with
file open for reading and writing on file descriptor fd.
Runs the command with
file opened according to mode on file descriptor fd. The modes and have the same meanings in as they do in fopen(3). is invoked by the redirection hook functions: and
Runs the commands in order, stopping after the first one
that has a true return value. Returns the result of the last command run.
Reads input from the current input source, printing
prompt1 before reading anything and prompt2 before reading continued lines. Returns a code fragment suitable for execution. Raises the exception on end of input.
Looks for an executable file named
program in the directories listed in If such a file is found, it is returned; if one is not found, an exception is raised.
Runs the commands, with the file descriptor
outfd in the left-hand process connected by a pipe to the file descriptor infd in the right-hand process. If there are more than two commands, a multi-stage pipeline is created.
Called by
before every call to This function allows the user to provide any actions that he or she may wish to have executed before being prompted (e.g., updating the value of the variable to contain all or part of the current working directory).
Runs
cmd with the variable var locally bound to the name of a file which contains the output of running the command input.
Runs the commands, in order.
For each named
program, returns the pathname, primitive, lambda, or code fragment which would be run if the program appeared as the first word of a command.
Runs
cmd with the variable var locally bound to the name of a file which is used as the input for the command output.

Utility Functions

These functions are useful for people customizing the shell, may be used by other builtin commands, and probably don’t make much sense to replace, though that is always possible.
Returns the process IDs of all background processes that the shell
has not yet waited for.
Splits its arguments into separate strings at every occurrence
of any of the characters in the string separator. Repeated instances of separator characters cause null strings to appear in the result. (This function is used by some builtin settor functions.)
Returns true if the current interpreter context is interactive;
that is, if shell command input is currently coming from an interactive user. More precisely, this is true if the innermost enclosing read-eval-print loop is rather than
Returns a file descriptor that the shell thinks is not currently in use.
Run the named program, which is not searched for in
with the argument vector set to the remaining arguments. This builtin can be used to set (by convention, the name of the program) to something other than file name.
Splits its arguments into separate strings at every occurrence
of any of the characters in the string separator. Repeated instances of separator characters are coalesced. Backquote substitution splits with the same rules.
For each named variable,
returns a string which, if interpreted by xs would assign to the variable its current value.

PRIMITIVES

Primitives exist in xs so that, in the presence of spoofing and redefinitions, there is a way to refer to built-in behaviors. This ability is necessary for the shell to be able to unambiguously refer to itself, but is also useful for users who have otherwise made their environment unnecessary but don’t want to kill the current shell.
Primitives are referenced with the

notation. In this section, the prefixes will be omitted when primitive names are mentioned. Note that, by convention, primitive names follow C identifier names where xs variable and function names often contain and characters.
The following primitives directly implement the builtin functions with the same names:
access           fork             throw
catch            if               umask
echo             newpgrp          wait
exec             printf           
forever          result           
In addition, the primitive implements the builtin function.
The primitive is used in the implementation of the builtin, but does not understand no arguments to imply The and primitives are used by the implementation of the builtin.
The following primitives implement the hook functions of the same names, with prefixes:
apids            here             run
close            home             seq
cmp              newfd            split
count            openfile         var
dup              parse            whatis
flatten          pipe
fsplit           read
The following primitives implement the similar named hook functions, with prefixes and internal hyphens:
batchloop        exitonfalse      isinteractive
The primitive is used to implement the hook function, but does not print the process ID of the background process or set The primitive is used to implement the hook function, but returns the exit status of the child as the first value of its result instead of setting to it.
The following primitives implement the similarly named settor functions:
sethistory       setnoexport      setsignals
The primitive implements the settor function for the variable, which is used to limit the depth of the interpreter’s evaluation stack.
Some primitives are included in xs conditionally, based on compile-time configuration options. Those primitives, and the functions to which they are bound, are
execfailure         %exec-failure
limit               limit
readfrom            %readfrom
time                time
writeto             %writeto
The primitive is present if xs is compiled with support for the readline library. It is used in the implementation of settor functions of the and variables to notify the line editing packages that the terminal configuration has changed.
Several primitives are not directly associated with other function. They are:
Invokes the garbage collector.
The garbage collector in xs runs rather frequently; there should be no reason for a user to issue this command.
Returns a list of the names of xs primitives.
Returns a random integer.
Returns the version string of
xs.

OPTIONS

Run the given command, placing the rest of the arguments to xs in
Read commands from standard input; i.e., put the first argument to xs in rather than using it as the name of a file to source.
Force xs to be an interactive shell after loading Normally xs is only interactive if it is run with commands coming from standard input and standard input is connected to a terminal.
Run on startup, i.e., be a login shell. is implied if the name the shell was run under (that is, starts with a dash
Exit if any command (except those executing as the tests of conditional statements) returns a non-zero status.
Echo all input to standard error.
Print commands to standard error before executing them.
Turn off execution of commands.
This can be used for checking the syntax of scripts. When combined with xs prints the entered command based on the internal (parsed) representation.
Don’t initialize functions from the environment. This is used to help make scripts that don’t break unexpectedly when the environment contains functions that would override commands used in the script.
Don’t open on file descriptors 0, 1, and 2, if any of those descriptors are inherited closed.
Don’t trap or This is used for debugging.

HISTORY AND EDITING

When built with the readline library, command and history editing is provided by the libary.

MISC NOTES

As with any other shell scripting language, process forking takes up the majority of time:

is several magnitudes faster than:

Even though xs’s arithmetic code is rather slow, in this case the cost of fork+exec far outweighs it.
Elaborate tricks involving stringifying closures and unstringying them later will probably not work. In general, trying to manipulate the scope of variables through similar techniques will probably not do what one expects.

BUGS

The interpreter should be properly tail recursive; that is, tail calls should not consume stack space.
Woe betide the environment string set by some other program to contain either the character control-a or the sequence control-b followed by control-a or control-b.
is not nearly as useful as it should be.
Too many creatures have fept in.
Please submit issues and pull requests at

SEE ALSO

history(1), readline(1), es(1), rc(1), sh(1), execve(2), getrlimit(2), fopen(3), getpwent(3), printf(3p)
Paul Haahr and Byron Rakitzis, Es — A shell with higher-order functions, Proceedings of the Winter 1993 Usenix Conference, San Diego, CA.
Tom Duff, Rc — A Shell for Plan 9 and UNIX Systems, Unix Research System, 10th Edition, Volume 2. (Saunders College Publishing)
⇧ Top