FreeBSD Manual Pages
ES(1) General Commands Manual ES(1) NAME es - extensible shell SYNOPSIS es [-silevxnpo] [-c command | file] [arguments] DESCRIPTION Es is a command interpreter and programming language which combines the features of other Unix shells and the features of a functional program- ming language such as Scheme. The syntax is derived from rc(1). Es is intended for use both as an interactive shell and a programming lan- guage for scripts. Es 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 configura- tion. See the section entitled Hook Functions for details on entry points which can be redefined to give the shell extended semantics. LANGUAGE Es is an interpreter which reads commands and executes them. The sim- plest form of command in es is a sequence of words separated by white space (space and tab) characters. A word is either a string or a pro- gram fragment (see below). The first word is the command to be exe- cuted; 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 pro- gram 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 /,0 ./,0 or ../,0 then it is used as the absolute path name of a file; if not, es looks for an executable file in the directories named by $path.0 Commands are terminated by newline or semicolon (;).0 A command may also be terminated by an ampersand (&),0 which causes the command to be run in the background: the shell does not wait for the command to fin- ish before continuing execution. Background processes have an implicit redirection of /dev/null0 as their standard input that may be overrid- den by an explicit redirection. Quoting Es gives several characters special meaning; special characters auto- matically terminate words. The following characters, along with space, tab, and newline, are special: # $ & ' ( ) ; < = > \ ^ ` { | }0 The single quote (')0 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 se- quence ''''.0 The empty string is represented by ''.0 Thus: echo 'What''s the plan, Stan?'0 prints out What's the plan, Stan?0 The backslash (\)0 quotes the immediately following character, if it is one of the special characters, except for newline. In addition, es recognizes backslash sequences similar to those used in C strings: \a0 alert (bell) \b0 backspace \e0 escape \f0 form-feed \n0 newline \r0 carriage return \t0 tab \xnn0 hexadecimal character nn \nnn0 octal character nnn Comments The number sign (#)0 begins a comment in es. 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 (\).0 The backslash-newline sequence is treated as a space. Note that line con- tinuation 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 es is the list, which is a sequence of words. Parentheses are used to group lists. The empty list is repre- sented by ().0 Lists have no hierarchical structure; a list inside an- other list is expanded so that the outer list contains all the elements of the inner list. Thus, the following are all equivalent: one two three0 (one two three)0 ((one) () ((two three)))0 Note that the null string, '',0 and the empty list, (),0 are two very different things. Assigning the null string to variable is a valid op- eration, but it does not remove its definition. Concatenation Two lists may be joined by the concatenation operator (^).0 A single word is a list of length one, so echo foo^bar0 produces the output foobar0 For lists of more than one element, concatenation produces the cross (Cartesian) product of the elements in both lists: echo (a- b- c-)^(1 2)0 produces the output a-1 a-2 b-1 b-2 c-1 c-20 Variables A list may be assigned to a variable, using the notation: var = list0 Any sequence of non-special characters, except a sequence including only digits, may be used as a variable name. Es exports all user-de- fined variables into the environment unless it is explicitly told not to. The value of a variable is referenced with the notation: $var0 Any variable which has not been assigned a value returns the empty list when referenced. In addition, multiple references are allowed: a = foo0 b = a0 echo $$b0 prints foo0 A variable's definition may also be removed by assigning the empty list to a variable: var=0 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, (a b) = 1 2 30 has the same effect as a = 10 b = 2 30 and (a b c) = 1 20 is the same as a = 10 b = 20 c =0 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, es must make certain assumptions about what characters may appear in a variable name. Es assumes that a variable name consists only of alphanumeric characters, percent (%),0 star (*),0 dash (-),0 and underscore (_).0 To reference a variable with other characters in its name, quote the variable name. Thus: echo $'we$Irdriab!le'0 A variable name produced by some complex operation, such as concatena- tion, should be enclosed in parentheses: $(var)0 Thus: Good-Morning = Bonjour0 Guten = Good0 Morgen = Morning0 echo $($Guten^-^$Morgen)0 prints Bonjour0 Each element of the list in parentheses is treated as an independent variable and expanded separately. Thus, given the above definitions, echo $(Guten Morgen)0 prints Good Morning0 To count the number of elements in a variable, use $#var0 This returns a single-element list with the number of elements in $var.0 Subscripting Variables may be indexed with the notation $var(n)0 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 a = one two three0 then echo $a(3 3 3)0 prints three three three0 Subscript indices which refer to nonexistent elements expand to the empty list. Thus, given the definition above echo $a(3 1 4 1 5 9 2 6 5)0 prints three one one two0 Subscript ranges are of the form lo...hi0 and refer to all the elements between lo and hi. If lo is omitted, then 10 is used as a default value; if hi is omitted, the length of the list is used. Thus * = $*(2 ...)0 removes the first element of *,0 similar to the effect of shift0 in rc(1) or sh(1). The notation $n,0 where n is an integer, is a shorthand for $*(n).0 Thus, es's arguments may be referred to as $1,0 $2,0 and so on. Note that the list of subscripts may be given by any es expression, so $var(`{awk 'BEGIN{for(i=1;i<=10;i++)print i;exit }'})0 returns the first 10 elements of $var.0 Free Carets Es inserts carets (concatenation operators) for free in certain situa- tions, in order to save some typing on the user's behalf. For example, the following are all equivalent: cc -O -g -c malloc.c alloca.c0 cc -^(O g c) (malloc alloca)^.c0 opts=O g c; files=malloc alloca; cc -$opts $files.c0 Es inserts a free-caret between the ``-''0 and $opts,0 as well as be- tween $files0 and .c.0 The rule for free carets is as follows: if a word or keyword is immediately followed by another word, keyword, dol- lar-sign or backquote without any intervening spaces, then es inserts a caret between them. Flattened Lists To create a single-element list from a multi-element list, with the components space-separated, use $^var0 Flattening is useful when the normal list concatenation rules need to be bypassed. For example, to append a single period at the end of $path,0 use: echo $^path.0 Wildcard Expansion Es expands wildcards in filenames if possible. When the characters *,0 [0 or ?0 occur in an argument or command, es looks at the argument as a pattern for matching against files. (Contrary to the behavior some other shells exhibit, es will only perform pattern matching if a metacharacter occurs unquoted and literally in the input. Thus, foo = '*'0 echo $foo0 will always echo just a star. In order for non-literal metacharacters to be expanded, an eval0 statement must be used in order to rescan the input.) Pattern matching occurs according to the following rules: a *0 matches any number (including zero) of characters. A ?0 matches any single character, and a [0 followed by a number of characters followed by a ]0 matches a single character in that class. The rules for char- acter class matching are the same as those for ed(1), with the excep- tion that character class negation is achieved with the tilde (~),0 not the caret (^),0 since the caret already means something else in es. The filename component separator, slash (/),0 must appear explicitly in patterns. *0 and ?0 do not match a dot character (.)0 at the beginning of a filename component. A tilde (~)0 as the first character of an argument is used to refer to home directories. A tilde alone or followed by a slash (/)0 is re- placed by the value of $home,0 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 (~)0 operator is used in es for matching strings against wildcard patterns. The command ~ subject pattern pattern ...0 returns a true value if and only if the subject matches any of the pat- terns. The matching follows the same rules as wildcard expansion, ex- cept that slashes (/)0 are not considered significant, leading dots (.)0 do not have to be matched explicitly, and home directory expansion does not occur. Thus ~ foo f*0 returns zero (true), while ~ (bar baz) f*0 returns one (false). The null list is matched by the null list, so ~ $foo ()0 checks to see whether $foo0 is empty or not. This may also be achieved by the test ~ $#foo 00 Note that inside a ~0 command es does not match patterns against file names, so it is not necessary to quote the characters *,0 [0 and ?.0 However, es does expand the subject against filenames if it contains metacharacters. Thus, the command ~ * ?0 returns true if any of the files in the current directory have a sin- gle-character name. Note that if the ~0 command is given a list as its first argument, then a successful match against any of the elements of that list will cause ~0 to return true. For example: ~ (foo goo zoo) z*0 is true. Pattern Extraction The double-tilde (~~)0 operator is used in es for extracting the parts of strings that match patterns. The command ~~ subject pattern pattern ...0 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 *,0 ?,0 or []0 character range are extracted, and processing moves on to the next sub- ject. If the subject does not match, the next pattern is tried. For example, the result of the extraction operation ~~ (foo.c foo.x bar.h) *.[ch]0 is the list (foo c bar h).0 Command Substitution A list may be formed from the output of a command by using backquote substitution: `{ command }0 returns a list formed from the standard output of the command in braces. The characters stored in the variable $ifs0 (for ``input field separator'') are used to split the output into list elements. By de- fault, $ifs0 has the value space-tab-newline. The braces may be omit- ted if the command is a single word. Thus `ls0 may be used instead of `{ls}.0 This last feature is useful when defining functions that expand to useful argument lists. A frequent use is: fn src { echo *.[chy] }0 followed by wc `src0 (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 $ifs0 for a single command substitu- tion, use: `` ifs-list { command }0 $ifs0 will be temporarily ignored and the command's output will be split as specified by the list following the double backquote. For ex- ample: `` :\n {cat /etc/passwd}0 splits up /etc/passwd0 into fields. Return Values The return value of a command is obtained with the construct <={ command }0 The return value of an external program is its exit status (which in other shells can be found in special variables such as $?0 or $sta- tus),0 as either a small integer or the name of signal. Thus echo <={test -f /etc/motd} <={test -w /vmunix} <=a.out0 might produce the output 0 1 sigsegv+core0 along with any output or error messages from the programs. Es 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 ``0''0 (or the empty string), that list is considered false. The return value of an assignment operation is the assigned value. Logical Operators There are a number of operators in es which depend on the exit status of a command. command1 && command20 executes the first command and then executes the second command if and only if the first command has a ``true'' return value. command1 || command20 executes the first command and then executes the second command if and only if the first command has a ``false'' return value. ! command0 inverts the truth value of the exit status of a command. Input and output The standard output of a command may be redirected to a file with command > file0 and the standard input may be taken from a file with command < file0 File descriptors other than 0 and 1 may be specified also. For exam- ple, to redirect standard error to a file, use: command >[2] file0 In order to duplicate a file descriptor, use >[n=m].0 Thus to redirect both standard output and standard error to the same file, use command > file >[2=1]0 To close a file descriptor that may be open, use >[n=].0 For example, to close file descriptor 7: command >[7=]0 In order to place the output of a command at the end of an already ex- isting file, use: command >> file0 If the file does not exist, then it is created. To open a file for reading and writing, use the <>0 redirection opera- tor; for reading and appending, use <>>.0 Both of these operators use file descriptor 0 (standard input) by default. Similarly, ><0 trun- cates a file and opens it for reading and writing, and >><0 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 command << 'eof-marker'0 If the end-of-file marker is quoted, then no variable substitution oc- curs inside the here document. Otherwise, every variable is substi- tuted by its space-separated-list value (see Flat Lists, below), and if a ^0 character follows a variable name, it is deleted. This allows the unambiguous use of variables adjacent to text, as in $variable^follow0 To include a literal $0 in a here document created with an unquoted end-of-file marker, use $$.0 Additionally, es supports ``here strings'', which are like here docu- ments, except that input is taken directly from a string on the command line. Its use is illustrated here: cat <<< 'this is a here string' | wc0 (This feature enables es to export functions that use here documents.) Pipes Two or more commands may be combined in a pipeline by placing the ver- tical bar (|)0 between them. The standard output (file descriptor 1) of the command on the left is tied to the standard input (file descrip- tor 0) of the command on the right. The notation |[n=m]0 indicates that file descriptor n of the left process is connected to file de- scriptor m of the right process. |[n]0 is a shorthand for |[n=0].0 As an example, to pipe the standard error of a command to wc(1), use: command |[2] wc0 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 conve- nient sometimes to build nonlinear pipelines so that a command like cmp can read the output of two commands at once. Es does it like this: cmp <{command1} <{command2}0 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: echo hi there | tee >{sed 's/^/p1 /'} >{sed 's/^/p2 /'}0 Program Fragments Es allows the intermixing of code with strings. A program fragment, which is a group of commands enclosed in braces ({ and }),0 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 ap- pears as the first word in a command, it is executed, and any arguments are ignored. Thus the following all produce the same output: { echo hello, world }0 { echo hello, world } foo bar0 es -c { echo hello, world }0 x = { echo hello, world }; $x0 echo { echo hello, world } | es0 echo { echo hello, world } > foo; es < foo0 Since program fragments in the first position in a command are exe- cuted, braces may be used as a grouping mechanism for commands. For example, to run several commands, with output from all of them redi- rected to the same file, one can do { date; ps agux; who } > snapshot0 In addition, program fragments can continue across multiple physical lines without explicit line continuations, so the above command could also be written: {0 date0 ps agux0 who0 } > snapshot0 A lambda is a variant on a program fragment which takes arguments. A lambda has the form @ parameters { commands }0 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 parame- ters for which there are no arguments are bound to the empty list. If no parameters are listed, the variable named *0 is assigned all the ar- guments of the lambda. Note that @0 is a keyword and not a special character in es, so it must be separated by whitespace from other words. As a small example, @ { echo $* } hi0 is a complicated way of producing the output hi.0 The first word is a function which echoes its arguments, and the second word is the argu- ment to the function, the word hi.0 Lambdas, like other program fragments, can appear anywhere in a list. A more complicated example in the same spirit: @ cmd arg { $cmd $arg } @ { echo $* } hi0 This command executes a lambda which runs its first argument, named cmd,0 using its second argument, named arg,0 as the argument for the first. The first argument of this function is another lambda, seen previously, and the second argument is the word hi.0 These lambda expressions @ a b c { echo $c $b $a } 1 20 @ a b c { echo $c $b $a } 1 2 3 4 50 produce this output: 2 10 3 4 5 2 10 Functions A function in es is introduced with the syntax fn name parameters { commands }0 If the function name appears as the first word of a command, the com- mands 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 es is a variable of the form fn-name.0 If name for which the appropriate fn-0 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 fn-name = @ parameters { commands }0 Functions may be deleted with the syntax fn name0 which is equivalent to the assignment fn-name=0 If, as the most common case, a function variable is bound to a lambda, when the function is invoked, the variable $00 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 central difference between the two forms is that lambdas bind their arguments, while simple brace-enclosed groups just ignore theirs. Local Variables Variable assignments may be made local to a set of commands with the local0 construct: local (var = value; var = value ...) command0 The command may be a program fragment, so for example: local (path = /bin /usr/bin; ifs = ) {0 ...0 }0 sets path0 to a minimal useful path and removes ifs0 for the duration of one long compound command. Local-bound variables are exported into the environment, and will in- voke appropriately named settor functions (see below). Lexically Scoped Variables In addition to local variables, es supports a different form of tempo- rary variable binding, using let-bound, or ``lexically scoped,'' vari- ables. (Lexical scoping is the form of binding used by most compiled programming languages, such as C or Scheme.) A lexically scoped vari- able is introduced with a let0 statement: let (var = value; var = value ...) command0 All references to any of the variables defined in a let0 statement by any code located lexically (that is, textually) within the command por- tion of the statement will refer to the let-bound variable rather than any environment or local-bound variable; the immediate text of the let0 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 let0 and local0 (also known as ``dynamic'') binding: (note that ``; ''0 is es's default prompt.) ; x = foo0 ; let (x = bar) {0 echo $x0 fn lexical { echo $x }0 }0 bar0 ; local (x = baz) {0 echo $x0 fn dynamic { echo $x }0 }0 baz0 ; lexical0 bar0 ; dynamic0 foo0 ; 0 Lexically bound variables are not exported into the environment, and never cause the invocation of settor functions. Function (lambda) pa- rameters are lexically bound to their values. For loops The command for (var = list) command0 Runs the command once for each element of the list, with the named variable bound lexically to each element of the list, in order. If multiple bindings are given in the for0 statement, the looping oc- curs 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 for (i = a b c; j = x y) echo $#i $i $#j $j0 produces the output 1 a 1 x0 1 b 1 y0 1 c 00 Settor Functions A settor function is a variable of the form set-var,0 which is typi- cally 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 $00 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 home0 and HOME0 synchronized. set-HOME = @ {0 local (set-home = )0 home = $*0 result $*0 }0 This settor function is called when any assignment is made to the vari- able HOME.0 It assigns the new value to the variable home,0 but dis- ables any settor function for home0 to prevent an infinite recursion. Then it returns its argument unchanged for use in the actual assignment to HOME.0 Settor functions do not apply to lexically bound variables. Primitives Primitives are internal es 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 es. Primitives can be used with the syntax $&name0 A primitive can be used anywhere a lambda is expected. The list of primitives is returned as the result of running the primitive $&primi- tives.0 For details on specific primitives, see the section entitled PRIMITIVES below. Exceptions Exceptions in es are used for many forms of non-structured control flow, notably error reporting, signals, and flow of control constructs such as break0 and return.0 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: break value0 Exit from a loop. The return value of the loop is the argument to the exception. eof0 Raised by %parse0 when the end of input is reached. error source message0 A run-time error. Almost all shell errors are reported with the error0 exception. The default interactive loop and the outer- most level of the interpreter catch this exception and print the message. Source is the name of the routine (typically a primi- tive) which raised the error. retry0 When raised from a signal catcher, causes the body of the catch0 clause to be run again. return value0 Causes the current function to exit, with value as the return value (exit status). signal signame0 Raised when the shell itself receives a signal, and the signal is listed in the variable signals.0 Signame is the name of the signal that was raised. See the builtin commands catch0 and throw0 for details on how to manip- ulate exceptions. SPECIAL VARIABLES Several variables are known to es and are treated specially. Redefin- ing these variables can change interpreter semantics. Note that only dynamically bound (top-level or local-bound)0 variables are interpreted in this way; the names of lexically bound variables are unimportant. *0 The argument list of es. $1, $2,0 etc. are the same as $*(1),0 $*(2),0 etc. $00 Holds the value of argv[0]0 with which es was invoked. Addi- tionally, $00 is set to the name of a function for the duration of the execution of that function, and $00 is also set to the name of the file being interpreted for the duration of a . com- mand.0 apid0 The process ID of the last process started in the background. history0 The name of a file to which commands are appended as es reads them. This facilitates the use of a stand-alone history program (such as history(1)) which parses the contents of the history file and presents them to es for reinterpretation. If history0 is not set, then es does not append commands to any file. home0 The current user's home directory, used in tilde (~)0 expansion, as the default directory for the builtin cd0 command, and as the directory in which es looks to find its initialization file, .esrc,0 if es has been started up as a login shell. Like path0 and PATH,0 home0 and HOME0 are aliased to each other. ifs0 The default input field separator, used for splitting up the output of backquote commands for digestion as a list. The ini- tial value of ifs0 is space-tab-newline. noexport0 A list of variables which es will not export. All variables ex- cept for the ones on this list and lexically bound variables are exported. path0 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 path0 causes an automatic assignment to PATH,0 and vice-versa. If neither path0 nor PATH0 are set at startup time, path0 assumes a default value suitable for your system. This is typically /usr/ucb /usr/bin /bin ''.0 pid0 The process ID of the currently running es. prompt0 This variable holds the two prompts (in list form) that es prints. $prompt(1)0 is printed before each command is read, and $prompt(2)0 is printed when input is expected to continue on the next line. (See %parse0 for details.) es sets $prompt0 to ('; ' '')0 by default. The reason for this is that it enables an es user to grab commands from previous lines using a mouse, and to present them to es for re-interpretation; the semicolon prompt is simply ignored by es. The null $prompt(2)0 also has its jus- tification: an es script, when typed interactively, will not leave $prompt(2)'s0 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. signals0 Contains a list of the signals which es traps. Any signal name which is added to this list causes that signal to raise an es exception. For example, to run some commands and make sure some cleanup routine is called even if the user interrupts or discon- nects during the script, one can use the form: local (signals = $signals sighup sigint) {0 catch @ e {0 cleanup0 throw $e0 } {0 ...0 }0 }0 A signal name prefixed by a hyphen (-)0 causes that signal to be ignored by es and all of its child processes, unless one of them resets its handler. A signal prefixed by a slash (/)0 is ig- nored in the current shell, but retains default behavior in child processes. In addition, the signal sigint0 may be pre- ceeded by the prefix (.)0 to indicate that normal shell inter- rupt processing (i.e., the printing of an extra newline) occurs. By default es starts up with the values .sigint /sigquit /sigterm0 in $signals;0 other values will be on the list if the shell starts up with some signals ignored. The values of path0 and home0 are derived from the environment values of PATH0 and HOME0 if those values are present. This is for compati- bility with other Unix programs, such as sh(1). $PATH0 is assumed to be a colon-separated list. SYNTACTIC SUGAR Es internally rewrites much of the syntax presented thus far in terms of calls to shell functions. Most features of es that resemble tradi- tional 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 es does, with the forms typically entered by the user on the left and their in- ternal form on the right. There is no reason for the user to avoid us- ing the right-hand side forms, except that they are usually less conve- nient. To see the internal form of a specific command, a user can run es with the -n0 and -x0 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}} 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 (%).0 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 %-names0 are somewhat arbitrary.) All builtins can be redefined and extended by the user. Builtin Commands . [-einvx] file [args ...]0 Reads file as input to es and executes its contents. The op- tions are a subset of the invocation options for the shell (see below). access [-n name] [-1e] [-rwx] [-fdcblsp] path ...0 Tests if the named paths are accessible according to the options presented. Normally, access0 returns zero (true) for files which are accessible and a printable error message (which evalu- ates as false, according to shell rules) for files which are not accessible. If the -10 option is used, the name of the first file which the test succeeds for is returned; if the test suc- ceeds for no file, the empty list is returned. However, if the -e0 option was used, access0 raises an error0 exception. If the -n0 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 (i.e., -n0 is used for path searching). The default test is whether a file exists. These options change the test: -r0 Is the file readable (by the current user)? -w0 Is the file writable? -x0 Is the file executable? -f0 Is the file a plain file? -d0 Is the file a directory? -c0 Is the file a character device? -b0 Is the file a block device? -l0 Is the file a symbolic link? -s0 Is the file a socket? -p0 Is the file a named pipe (FIFO)? break value0 Exits the current loop. Value is used as the return value for the loop command. catch catcher body0 Runs body. If it raises an exception, catcher is run and passed the exception as an argument. cd [directory]0 Changes the current directory to directory. With no argument, cd0 changes the current directory to $home.0 echo [-n] [--] args ...0 Prints its arguments to standard output, terminated by a new- line. Arguments are separated by spaces. If the first argument is -n0 no final newline is printed. If the first argument is --,0 then all other arguments are echoed literally; this is used for echoing a literal -n.0 eval list0 Concatenates the elements of list with spaces and feeds the re- sulting string to the interpreter for rescanning and execution. exec cmd0 Replaces es with the given command. If the exec0 contains only redirections, then these redirections apply to the current shell and the shell does not exit. For example, exec {>[2] err.out}0 places further output to standard error in the file err.out. Unlike some other shells, es requires that redirections in an exec0 be enclosed in a program fragment. exit [status]0 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.) false0 Always returns a false (non-zero) return value. forever cmd0 Runs the command repeatedly, until the shell exits or the com- mand raises an exception. This is equivalent to a while {true} {cmd}0 loop except that forever0 does not catch any exceptions, including break.0 fork cmd0 Runs a command in a subshell. This insulates the parent shell from the effects of state changing operations such as cd0 and variable assignments. For example: fork {cd ..; make}0 runs make(1) in the parent directory (..),0 but leaves the shell in the current directory. if [test then] ... [else]0 Evaluates the command test. If the result is true, the command then is run and if0 completes. If the result of the test is false, the next test-then pair is checked, until one where the test is true is found. If none of the tests are true, the else command is run. limit [-h] [resource [value]]0 Similar to the csh(1) limit0 builtin, this command operates upon the resource limits of a process. With no arguments, limit0 prints all the current limits; with one argument, limit0 prints the named limit; with two arguments, it sets the named limit to the given value. The -h0 flag displays/alters the hard limits. The resources which can be shown or altered are cputime,0 file- size,0 datasize,0 stacksize,0 coredumpsize0 and memoryuse.0 For example: limit coredumpsize 00 disables core dumps. The limit values must either be the word ``unlimited''0 or a number with an optional suffix indicating units. For size lim- its, the suffixes k0 (kilobytes), m0 (megabytes), and g0 (giga- bytes) are recognized. For time limits, s0 (seconds), m0 (min- utes), and h0 (hours) are known; in addition, times of the form hh:mm:ss0 and mm:ss0 are accepted. See getrlimit(2) for details on resource limit semantics. newpgrp0 Puts es into a new process group. This builtin is useful for making es behave like a job-control shell in a hostile environ- ment. One example is the NeXT Terminal program, which implic- itly 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 opera- tion is run. result value ...0 Returns its arguments. This is es's identity function. return value0 Causes the current function to exit, returning the named value. throw exception arg ...0 Raise the named exception, passing all of the arguments to throw0 to the enclosing exception handler. time cmd arg ... 0 Prints, on the shell's standard error, the real, user, and sys- tem time consumed by executing the command. true0 Always returns a true (zero) return value. umask [mask]0 Sets the current umask (see umask(2)) to the octal mask. If no argument is present, the current mask value is printed. unwind-protect body cleanup0 Runs body and, when it completes or raises an exception, runs cleanup. var var ...0 Prints definitions of the named variables, suitable for being used as input to the shell. vars [-vfs] [-epi]0 Prints all shell variables, functions, and settor functions (in a form suitable for use as shell input), which match the crite- ria specified by the options. -v0 variables (that are not functions or settor functions) -f0 functions -s0 settor functions -e0 exported values -p0 private (not exported) values -i0 internal (predefined and builtin) values -a0 all of the above If none of -v,0 -f, or0 -s0 are specified, -v0 is used. If none of -e,0 -p, or0 -i0 are specified, -e0 is used. wait [pid]0 Waits for the specified pid, which must have been started by es. If no pid is specified, waits for any child process to exit. whatis progam ...0 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. while test body0 Evaluates the test and, if it is true, runs the body and re- peats. %read0 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 func- tion 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. Hook Functions A subset of the %-named0 functions are known as ``hook functions.'' The hook functions are called to implement some internal shell opera- tions, 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. %and cmd ...0 Runs the commands in order, stopping after the first one that has a false return value. Returns the result of the last com- mand run. %append fd file cmd0 Runs the command with file descriptor fd set up to append to the file. %background cmd0 Runs the command in the background. The shell variable apid0 contains the process ID of the background process, which is printed if the shell is interactive (according to %is-interac- tive).0 %backquote separator cmd0 Runs the command in a child process and returns its standard output as a list, separated (with the same rules used in %split)0 into elements according to separator. %batch-loop0 Parses commands from the current input source and passes the commands to the function %dispatch, which is usually a dynami- cally bound identifier. This function catches the exception eof0 which causes it to return. This function is invoked by the shell on startup and from the dot (.)0 and eval0 commands, when the input source is not interactive. (See also %interactive- loop.)0 %close fd cmd0 Runs the command with the given file descriptor closed. %count list0 Returns the number of arguments to the primitive. %create fd file cmd0 Runs the command with file descriptor fd set up to write to the file. %dup newfd oldfd cmd0 Runs the command with the file descriptor oldfd copied (via dup(2)) to file descriptor newfd. %eval-noprint cmd0 Run the command. (Passed as the argument to %batch-loop0 and %interactive-loop.)0 %eval-print cmd0 Print and run the command. (Passed as the argument to %batch- loop0 and %interactive-loop0 when the -x0 option is used.) %exec-failure file argv0 args ...0 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 exec0 a program if it thinks it knows what to do. Note that the name of the program appears twice in the arguments to %exec-failure,0 once as a filename and once as the first element of the argv0 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 base- name. Some versions of es may provide a builtin version of this function to handle #!-style0 shell scripts if the kernel does not. %exit-on-false cmd0 Runs the command, and exits if any command (except those execut- ing as the tests of conditional statements) returns a non-zero status. (This function is used as an argument to %batch-loop0 and %interactive-loop0 when the shell is invoked with the -e0 option.) %flatten separator list0 Concatenate the elements of list into one string, separated by the string separator. %here fd word ... cmd0 Runs the command with the words passed as input on file descrip- tor fd. %home [user]0 Returns the home directory of the named user, or $home0 if there are no arguments. %interactive-loop0 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 ex- ception eof0 which causes it to return. This function is in- voked by the shell on startup and from the dot (.)0 commands, when the input source is interactive. (See also %batch-loop.)0 %noeval-noprint cmd0 Do nothing. (Passed as the argument to %batch-loop0 and %inter- active-loop0 when the -n0 option is used.) %noeval-print cmd0 Print but don't run the command. (Passed as the argument to %batch-loop0 and %interactive-loop0 when the -x0 and -n0 options are used.) %not cmd0 Runs the command and returns false if its exit status was true, otherwise returns true. %one list0 If list is one element long, %one0 returns its value; otherwise it raises an exception. %one0 is used to ensure that redirec- tion operations get passed exactly one filename. %open fd file cmd0 Runs the command with file open for reading on file descriptor fd. %open-append fd file cmd0 Runs the command with file open for reading and appending on file descriptor fd. %open-create fd file cmd0 Runs the command with file open for reading and writing on file descriptor fd. If the file already exists, it is truncated. %open-write fd file cmd0 Runs the command with file open for reading and writing on file descriptor fd. %openfile mode fd file cmd0 Runs the command with file opened according to mode on file de- scriptor fd. The modes (r,0 w,0 a,0 r+,0 w+,0 and a+)0 have the same meanings in %openfile0 as they do in fopen(3). %openfile0 is invoked by the redirection hook functions: %append,0 %cre- ate,0 %open,0 %open-append,0 %open-create,0 and %open-write.0 %or cmd ...0 Runs the commands in order, stopping after the first one that has a true return value. Returns the result of the last command run. %parse prompt1 prompt20 Reads input from the current input source, printing prompt1 be- fore reading anything and prompt2 before reading continued lines. Returns a code fragment suitable for execution. Raises the exception eof0 on end of input. %pathsearch program0 Looks for an executable file named program in the directories listed in $path.0 If such a file is found, it is returned; if one is not found, an error0 exception is raised. %pipe cmd [outfd infd cmd] ...0 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. %prompt0 Called by %interactive-loop0 before every call to %parse.0 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 prompt0 variable to contain all or part of the current working directory). %readfrom var input cmd0 Runs cmd with the variable var locally bound to the name of a file which contains the output of running the command input. %seq cmd ...0 Runs the commands, in order. %whatis program ...0 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. %writeto var output cmd0 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. %apids0 Returns the process IDs of all background processes that the shell has not yet waited for. %fsplit separator [args ...]0 Splits its arguments into separate strings at every occurrence of any of the characters in the string separator. Repeated in- stances of separator characters cause null strings to appear in the result. (This function is used by some builtin settor func- tions.) %is-interactive0 Returns true if the current interpreter context is interactive; that is, if shell command input is currently coming from an in- teractive user. More precisely, this is true if the innermost enclosing read-eval-print loop is %interactive-loop0 rather than %batch-loop.0 %newfd0 Returns a file descriptor that the shell thinks is not currently in use. %run program argv0 args ...0 Run the named program, which is not searched for in $path,0 with the argument vector set to the remaining arguments. This builtin can be used to set argv[0]0 (by convention, the name of the program) to something other than file name. %split separator [args ...]0 Splits its arguments into separate strings at every occurrence of any of the characters in the string separator. Repeated in- stances of separator characters are coalesced. Backquote sub- stitution splits with the same rules. %var var ...0 For each named variable, returns a string which, if interpreted by es would assign to the variable its current value. PRIMITIVES Primitives exist in es so that, in the presence of spoofing and redefi- nitions, 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 $&name0 notation. In this section, the ``$&''0 prefixes will be omitted when primitive names are mentioned. Note that, by convention, primitive names follow C identifier names where es variable and function names often contain ``%''0 and ``-''0 characters. The following primitives directly implement the builtin functions with the same names: access forever throw catch fork umask echo if wait exec newpgrp exit result In addition, the primitive dot0 implements the ``.''0 builtin function. The cd0 primitive is used in the implementation of the cd0 builtin, but does not understand no arguments to imply $home.0 The vars0 and inter- nals0 primitives are used by the implementation of the vars0 builtin. The following primitives implement the hook functions of the same names, with ``%''0 prefixes: apids here read close home run count newfd seq dup openfile split flatten parse var fsplit pipe whatis The following primitives implement the similar named hook functions, with ``%''0 prefixes and internal hyphens: batchloop exitonfalse isinteractive The background0 primitive is used to implement the %background0 hook function, but does not print the process ID of the background process or set $apid.0 The backquote0 primitive is used to implement the %back- quote0 hook function, but returns the exit status of the child as the first value of its result instead of setting $bqstatus0 to it. The following primitives implement the similarly named settor func- tions: sethistory setnoexport setsignals Some primitives are included in es 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 resetterminal0 is if es is compiled with support for the readline or editline libraries. It is used in the implementation of settor functions of the TERM0 and TERMCAP0 variables to notify the line editing packages that the terminal configuration has changed. Several primitives are not directly associated with other function. They are: $&collect0 Invokes the garbage collector. The garbage collector in es runs rather frequently; there should be no reason for a user to issue this command. $&noreturn lambda args ...0 Call the lambda, but in such a way that it does not catch the return0 exception. This primitive exists in order that some control-flow operations in es (e.g., while0 and &&)0 can be im- plemented as lambdas rather than primitives. $&primitives0 Returns a list of the names of es primitives. $&version0 Returns the current version number and release date for es. OPTIONS -c0 Run the given command, placing the rest of the arguments to es in $*.0 -s0 Read commands from standard input; i.e., put the first argument to es in $*0 rather than using it as the name of a file to source. -i0 Force es to be an interactive shell. Normally es is only inter- active if it is run with commands coming from standard input and standard input is connected to a terminal. -l0 Run $home/.esrc0 on startup, i.e., be a login shell. -l0 is im- plied if the name the shell was run under (that is, argv[0])0 starts with a dash (-).0 -e0 Exit if any command (except those executing as the tests of con- ditional statements) returns a non-zero status. -v0 Echo all input to standard error. -x0 Print commands to standard error before executing them. -n0 Turn off execution of commands. This can be used for checking the syntax of scripts. When combined with -x,0 es prints the entered command based on the internal (parsed) representation. -p0 Don't initialize functions from the environment. This is used to help make scripts that don't break unexpectedly when the en- vironment contains functions that would override commands used in the script. -o0 Don't open /dev/null0 on file descriptors 0, 1, and 2, if any of those descriptors are inherited closed. -d0 Don't trap SIGQUIT0 or SIGTERM.0 This is used for debugging. FILES $home/.esrc,0 /dev/null0 BUGS Lexical scope which is shared by two variables (or closures) in a par- ent shell is split in child shells. The interpreter should be properly tail recursive; that is, tail calls should not consume stack space. break0 and return0 should have lexical scope. 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. -x0 is not nearly as useful as it should be. Line numbers in error messages refer to the last line parsed, rather than something more useful. Too many creatures have fept in. Please send bug reports to haahr@adobe.com0 and byron@netapp.com.0 SEE ALSO history(1), rc(1), sh(1), execve(2), getrlimit(2), fopen(3), getp- went(3) Paul Haahr and Byron Rakitzis, Es -- A shell with higher-order func- tions, Proceedings of the Winter 1993 Usenix Conference, San Diego, CA. Tom Duff, Rc -- A Shell for Plan 9 and UNIX Systems, Unix Research Sys- tem, 10th Edition, Volume 2. (Saunders College Publishing) 5 March 1992 ES(1)
NAME | SYNOPSIS | DESCRIPTION | LANGUAGE | SPECIAL VARIABLES | SYNTACTIC SUGAR | BUILTINS | PRIMITIVES | OPTIONS | FILES | BUGS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=es&sektion=1&manpath=FreeBSD+Ports+15.0.quarterly>