1XS(1) General Commands Manual XS(1)
2
6 xs - extensible shell
7
9 xs [-silevxnpo] [-c command | file] [arguments]
10
12 Xs is a command interpreter and programming language which combines the
13 features of other Unix shells and the features of a functional program‐
14 ming language such as Scheme. The syntax is derived from rc(1). The
15 xs shell is simply an extension of the es(1) shell in this goal. Xs is
16 intended for use both as an interactive shell and a programming lan‐
17 guage for scripts.
18 Xs is an extremely customizable language. The semantics can be altered
20 radically by redefining functions that are called to implement internal
21 operations. This manual page describes the default, initial configura‐
22 tion. See the section entitled Hook Functions for details on entry
23 points which can be redefined to give the shell extended semantics.
24
26 Xs is an interpreter which reads commands and executes them. The sim‐
27 plest form of command in xs is a sequence of words separated by white
28 space (space and tab) characters. A word is either a string or a pro‐
29 gram fragment (see below). The first word is the command to be exe‐
30 cuted; the remaining words are passed as arguments to that command. If
31 the first word is a string, it is a interpreted as the name of a pro‐
32 gram or shell function to run. If the name is the name of a shell
33 function, that function is executed. Otherwise, the name is used as
34 the name of an executable file. If the name begins with /, ./, or ../,
35 then it is used as the absolute path name of a file; if not, xs looks
36 for an executable file in the directories named by $path.
37 Commands are terminated by newline or semicolon (;). A command may
39 also be terminated by an ampersand (&), which causes the command to be
40 run in the background: the shell does not wait for the command to fin‐
41 ish before continuing execution. Background processes have an implicit
42 redirection of /dev/null as their standard input that may be overridden
43 by an explicit redirection.
44 Quoting
46 Xs gives several characters special meaning; special characters auto‐
47 matically terminate words. The following characters, along with space,
48 tab, and newline, are special:
49 # $ & ´ ( ) ; < : = > \ ^ ` { | }
51 The single quote (') prevents special treatment of any character other
53 than itself. Any characters between single quotes, including newlines,
54 backslashes, and control characters, are treated as an uninterpreted
55 string. A quote character itself may be quoted by placing two quotes
56 in a row. A single quote character is therefore represented by the
57 sequence ''''. The empty string is represented by ''. Thus:
58 echo 'What''s the plan, Stan?'
60 prints out
62 What's the plan, Stan?
64 The backslash (\) quotes the immediately following character, if it is
66 one of the special characters, except for newline. In addition, xs
67 recognizes backslash sequences similar to those used in C strings:
68 \a alert (bell)
70 \b backspace
72 \e escape
74 \f form-feed
76 \n newline
78 \r carriage return
80 \t tab
82 \xnn hexadecimal character nn
84 \nnn octal character nnn
86 Comments
88 The number sign (#) begins a comment in xs. All characters up to but
89 not including the next newline are ignored.
90 Line continuation
92 A long logical line may be continued over several physical lines by
93 terminating each line (except the last) with a backslash (\). The
94 backslash-newline sequence is treated as a space. Note that line con‐
95 tinuation does not work in comments, where the backslash is treated as
96 part of the comment, and inside quoted strings, where the backslash and
97 newline are quoted.
98 Lists
100 The primary data structure in xs is the list, which is a sequence of
101 words. Parentheses are used to group lists. The empty list is repre‐
102 sented by (). Lists have no hierarchical structure; a list inside
103 another list is expanded so that the outer list contains all the ele‐
104 ments of the inner list. (This is the same as perl's "list interpola‐
105 tion".) Thus, the following are all equivalent:
106 one two three
108 (one two three)
109 ((one) () ((two three)))
110 Note that the null string, '', and the empty list, (), are two very
112 different things. Assigning the null string to variable is a valid
113 operation, but it does not remove its definition.
114 Since lists can span multiple lines without explicit line continua‐
116 tions, they are ideal for long commands. For example:
117 switch $x \
119 error { result 1 } \
120 warning { break } \
121 good { echo no problem }
122 switch $x (
124 error { result 1 }
125 warning { break }
126 good { echo no problem }
127 )
128 Finally, note that there are some uses of parentheses not following
130 ordinary list rules: in let/local/%closure bindings, and in assignments
131 Concatenation
133 Two lists may be joined by the concatenation operator (^). A single
134 word is a list of length one, so
135 echo foo^bar
137 produces the output
139 foobar
141 For lists of more than one element, concatenation produces the cross
143 (Cartesian) product of the elements in both lists:
144 echo (a- b- c-)^(1 2)
146 produces the output
148 a-1 a-2 b-1 b-2 c-1 c-2
150 Variables
152 A list may be assigned to a variable, using the notation
153 var = list
155 Unfortunately, whitespace is required around the assignment operator,
157 this allows it to be treated as a normal string character normally.
158 This is true also for assignment in let-forms and the like. Any
159 sequence of non-special characters, except a sequence including only
160 digits, may be used as a variable name. Xs exports all user-defined
161 variables into the environment unless it is explicitly told not to.
162 The value of a variable is referenced with the notation:
164 $var
166 Any variable which has not been assigned a value returns the empty list
168 when referenced. In addition, multiple references are allowed:
169 a = foo
171 b = a
172 echo $$b
173 prints
175 foo
177 A variable's definition may also be removed by assigning the empty list
179 to a variable:
180 var=
182 Multiple variables may be assigned with a single assignment statment.
184 The left hand side of the assignment operation consists of a list of
185 variables which are assigned, one by one, to the values in the list on
186 the right hand side. If there are more variables than values in the
187 list, the empty list is assigned to the remaining variables. If there
188 are fewer variables than elements in the list, the last variable is
189 bound to all the remaining list values.
190 For example,
192 (a b) = 1 2 3
194 has the same effect as
196 a = 1
198 b = 2 3
199 and
202 (a b c) = 1 2
204 is the same as
206 a = 1
208 b = 2
209 c =
210 Note that when assigning values to more than one variable,
213 the list of variables must be enclosed in parentheses.
214 For ``free careting'' (see below) to work correctly,
216 xs
217 must make certain assumptions
218 about what characters may appear in a variable name.
219 Xs
220 assumes that a variable name consists only of alphanumeric characters,
221 percent
222 (%),
223 star
224 (*),
225 dash
226 (-),
227 and underscore
228 (_).
229 To reference a variable with other
230 characters in its name, quote the variable name.
231 Thus:
232 echo $'we$Irdriab!le'
234 A variable name produced by some complex operation, such as concatena‐
236 tion, should be enclosed in parentheses:
237 $(var)
239 Thus:
241 Good-Morning = Bonjour
243 Guten = Good
244 Morgen = Morning
245 echo $($Guten^-^$Morgen)
246 prints
248 Bonjour
250 Each element of the list in parentheses is treated as an independent
252 variable and expanded separately. Thus, given the above definitions,
253 echo $(Guten Morgen)
255 prints
257 Good Morning
259 To count the number of elements in a variable, use
261 $#var
263 This returns a single-element list with the number of elements in $var.
265 Subscripting
267 Variables may be indexed with the notation
268 $var(n)
270 where n is a list of integers or ranges. Subscript indexes are based
272 at one. The list of subscripts need not be in order or even unique.
273 Thus, if
274 a = one two three
276 then
278 echo $a(3 3 3)
280 prints
282 three three three
284 Subscript indices which refer to nonexistent elements expand to the
286 empty list. Thus, given the definition above
287 echo $a(3 1 4 1 5 9 2 6 5)
289 prints
291 three one one two
293 Subscript ranges are of the form lo...hi and refer to all the elements
295 between lo and hi. If lo is omitted, then 1 is used as a default
296 value; if hi is omitted, the length of the list is used. Thus
297 * = $*(2 ...)
299 removes the first element of *, similar to the effect of shift in rc(1)
301 or sh(1).
302 The notation $n, where n is an integer, is a shorthand for $*(n).
304 Thus, xs's arguments may be referred to as $1, $2, and so on.
305 Note that the list of subscripts may be given by any xs expression, so
307 $var(`{awk 'BEGIN{for(i=1;i<=10;i++)print i;exit }'})
309 returns the first 10 elements of $var.
311 Free Carets
313 Xs inserts carets (concatenation operators) for free in certain situa‐
314 tions, in order to save some typing on the user's behalf. For example,
315 the following are all equivalent:
316 cc -O -g -c malloc.c alloca.c
318 cc -^(O g c) (malloc alloca)^.c
319 opts=O g c; files=malloc alloca; cc -$opts $files.c
320 Xs inserts a free-caret between the ``-'' and $opts, as well as between
322 $files and .c. The rule for free carets is as follows: if a word or
323 keyword is immediately followed by another word, keyword, dollar-sign
324 or backquote without any intervening spaces, then xs inserts a caret
325 between them.
326 Flattened Lists
328 To create a single-element list from a multi-element list, with the
329 components space-separated, use
330 $^var
332 Flattening is useful when the normal list concatenation rules need to
334 be bypassed. For example, to append a single period at the end of
335 $path, use:
336 echo $^path.
338 Wildcard Expansion
340 Xs expands wildcards in filenames if possible. When the characters *,
341 [ or ? occur in an argument or command, xs looks at the argument as a
342 pattern for matching against files. (Contrary to the behavior some
343 other shells exhibit, xs will only perform pattern matching if a
344 metacharacter occurs unquoted and literally in the input. Thus,
345 foo = '*'
347 echo $foo
348 will always echo just a star. In order for non-literal metacharacters
350 to be expanded, an eval statement must be used in order to rescan the
351 input.) Pattern matching occurs according to the following rules: a *
352 matches any number (including zero) of characters. A ? matches any
353 single character, and a [ followed by a number of characters followed
354 by a ] matches a single character in that class. The rules for charac‐
355 ter class matching are the same as those for ed(1), with the exception
356 that character class negation is achieved with the tilde (~), not the
357 caret (^), since the caret already means something else in xs. The
358 filename component separator, slash (/), must appear explicitly in pat‐
359 terns. * and ? do not match a dot character (.) at the beginning of
360 a filename component.
361 A tilde (~) as the first character of an argument is used to refer to
363 home directories. A tilde alone or followed by a slash (/) is replaced
364 by the value of $home, which is usually the home directory of the cur‐
365 rent user. A tilde followed by a username is replaced with the home
366 directory of that user, according to getpwent(3).
367 Pattern Matching
369 The tilde (~) operator is used in xs for matching strings against wild‐
370 card patterns. The command
371 ~ subject pattern pattern ...
373 returns a true value if and only if the subject matches any of the pat‐
375 terns. The matching follows the same rules as wildcard expansion,
376 except that slashes (/) are not considered significant, leading dots
377 (.) do not have to be matched explicitly, and home directory expansion
378 does not occur. Thus
379 ~ foo f*
381 returns zero (true), while
383 ~ (bar baz) f*
385 returns one (false). The null list is matched by the null list, so
387 ~ $foo ()
389 checks to see whether $foo is empty or not. This may also be achieved
391 by the test
392 ~ $#foo 0
394 Note that inside a ~ command xs does not match patterns against file
396 names, so it is not necessary to quote the characters *, [ and ?. How‐
397 ever, xs does expand the subject against filenames if it contains
398 metacharacters. Thus, the command
399 ~ * ?
401 returns true if any of the files in the current directory have a sin‐
403 gle-character name. Note that if the ~ command is given a list as its
404 first argument, then a successful match against any of the elements of
405 that list will cause ~ to return true. For example:
406 ~ (foo goo zoo) z*
408 is true.
410 Pattern Extraction
412 The double-tilde (~~) operator is used in xs for extracting the parts
413 of strings that match patterns. The command
414 ~~ subject pattern pattern ...
416 returns the parts of each matching subject which correspond to the
418 wildcards.
419 Each subject is checked in order against each pattern; if it matches
421 the pattern, the parts of the subject which matched each *, ?, or []
422 character range are extracted, and processing moves on to the next sub‐
423 ject. If the subject does not match, the next pattern is tried.
424 For example, the result of the extraction operation
426 ~~ (foo.c foo.x bar.h) *.[ch]
428 is the list (foo c bar h).
430 Arithmetic Substitution
432 A single list element can be formed from an infix arithmetical expres‐
433 sion like so:
434 ( expression )
436 The expression can use any of the
437 +, -, * and / operators, and use variable substitution of the form
438 $var. Parentheses can be used in normal infix fashion for order of
439 evaluation. Numbers can be entered in floating-point or integer, but
440 are always decimal. Calculation rules are similar to C - any operation
441 involving floats produces a float, any operation with integers produces
442 an integer; this includes division, so
443 .Cr "echo :(1 / 2)"
445 .Cr "echo :(1.0 / 2)"
446 produce 0 and 0.5 (with trailing zeros) respectively. Integers will
447 wrap around at the same point as the native platform's int, and floats
448 at the same point as the native platform's double.
449 Command Substitution
451 A list may be formed from the output of a command by using backquote
452 substitution:
453 `{ command }
455 returns a list formed from the standard output of the command in
457 braces. The characters stored in the variable $ifs (for ``input field
458 separator'') are used to split the output into list elements. By
459 default, $ifs has the value space-tab-newline. The braces may be omit‐
460 ted if the command is a single word. Thus `ls may be used instead of
461 `{ls}. This last feature is useful when defining functions that expand
462 to useful argument lists. A frequent use is:
463 fn src { echo *.[chy] }
465 followed by
467 wc `src
469 (This will print out a word-count of all C and Yacc source files in the
471 current directory.)
472 In order to override the value of $ifs for a single command substitu‐
474 tion, use:
475 `` ifs-list { command }
477 $ifs will be temporarily ignored and the command's output will be split
479 as specified by the list following the double backquote. For example:
480 `` :\n {cat /etc/passwd}
482 splits up /etc/passwd into fields.
484 Return Values
486 The return value of a command is obtained with the construct
487 <={ command }
489 The return value of an external program is its exit status (which in
491 other shells can be found in special variables such as $? or $status),
492 as either a small integer or the name of signal. Thus
493 echo <={test -f /etc/motd} <={test -w /vmunix} <=a.out
495 might produce the output
497 0 1 sigsegv+core
499 along with any output or error messages from the programs.
501 Xs functions and primitives can produce ``rich return values,'' that
503 is, arbitrary lists as return values.
504 When return values are interpreted as truth values, an extension of the
506 normal shell conventions apply. If any element of a list is not equal
507 to ``0'' (or the empty string), that list is considered false.
508 The return value of an assignment operation is the assigned value.
510 Logical Operators
512 There are a number of operators in Xs which depend on the exit status
513 of a command.
514 command1 && command2
516 executes the first command and then executes the second command if and
518 only if the first command has a ``true'' return value.
519 command1 || command2
521 executes the first command and then executes the second command if and
523 only if the first command has a ``false'' return value.
524 ! command
526 inverts the truth value of the exit status of a command.
528 Input and output
530 The standard output of a command may be redirected to a file with
531 command > file
533 and the standard input may be taken from a file with
535 command < file
537 File descriptors other than 0 and 1 may be specified also. For exam‐
539 ple, to redirect standard error to a file, use:
540 command >[2] file
542 In order to duplicate a file descriptor, use >[n=m]. Thus to redirect
544 both standard output and standard error to the same file, use
545 command > file >[2=1]
547 To close a file descriptor that may be open, use >[n=]. For example,
549 to close file descriptor 7:
550 command >[7=]
552 In order to place the output of a command at the end of an already
554 existing file, use:
555 command >> file
557 If the file does not exist, then it is created.
559 To open a file for reading and writing, use the <> redirection opera‐
561 tor; for reading and appending, use <>>. Both of these operators use
562 file descriptor 0 (standard input) by default. Similarly, >< truncates
563 a file and opens it for reading and writing, and >>< opens a file for
564 reading and appending; these operators use file descriptor 1 by
565 default.
566 ``Here documents'' are supported as in sh(1) with the use of
568 command << 'eof-marker'
570 If the end-of-file marker is quoted, then no variable substitution
572 occurs inside the here document. Otherwise, every variable is substi‐
573 tuted by its space-separated-list value (see Flat Lists, below), and if
574 a ^ character follows a variable name, it is deleted. This allows the
575 unambiguous use of variables adjacent to text, as in
576 $variable^follow
578 To include a literal $ in a here document created with an unquoted end-
580 of-file marker, use $$.
581 Additionally, xs supports ``here strings'', which are like here docu‐
583 ments, except that input is taken directly from a string on the command
584 line. Its use is illustrated here:
585 cat <<< 'this is a here string' | wc
587 (This feature enables xs to export functions that use here documents.)
589 Pipes
591 Two or more commands may be combined in a pipeline by placing the ver‐
592 tical bar (|) between them. The standard output (file descriptor 1) of
593 the command on the left is tied to the standard input (file descriptor
594 0) of the command on the right. The notation |[n=m] indicates that
595 file descriptor n of the left process is connected to file descriptor m
596 of the right process. |[n] is a shorthand for |[n=0]. As an example,
597 to pipe the standard error of a command to wc(1), use:
598 command |[2] wc
600 The exit status of a pipeline is considered true if and only if every
602 command in the pipeline exits true.
603 Input/Output Substitution
605 Some commands, like cmp(1) or diff(1), take their input from named
606 files on the command line, and do not use standard input. It is conve‐
607 nient sometimes to build nonlinear pipelines so that a command like cmp
608 can read the output of two commands at once. Xs does it like this:
609 cmp <{command1} <{command2}
611 compares the output of the two commands. Note: on some systems, this
613 form of redirection is implemented with pipes, and since one cannot
614 lseek(2) on a pipe, commands that use lseek will hang. For example,
615 most versions of diff seek on their inputs.
616 Data can be sent down a pipe to several commands using tee(1) and the
618 output version of this notation:
619 echo hi there | tee >{sed 's/^/p1 /'} >{sed 's/^/p2 /'}
621 Program Fragments
623 Xs allows the intermixing of code with strings. A program fragment,
624 which is a group of commands enclosed in braces ({ and }), may be used
625 anywhere a word is expected, and is treated as an indivisible unit.
626 For example, a program fragment may be passed as an argument, stored in
627 a variable, or written to a file or pipe. If a program fragment
628 appears as the first word in a command, it is executed, and any argu‐
629 ments are ignored. Thus the following all produce the same output:
630 { echo hello, world }
632 { echo hello, world } foo bar
633 xs -c { echo hello, world }
634 x = { echo hello, world }; $x
635 echo { echo hello, world } | xs
636 echo { echo hello, world } > foo; xs < foo
637 Since program fragments in the first position in a command are exe‐
639 cuted, braces may be used as a grouping mechanism for commands. For
640 example, to run several commands, with output from all of them redi‐
641 rected to the same file, one can do
642 { date; ps agux; who } > snapshot
644 In addition, program fragments can continue across multiple physical
646 lines without explicit line continuations, so the above command could
647 also be written:
648 {
650 date
651 ps agux
652 who
653 } > snapshot
654 A lambda is a variant on a program fragment which takes arguments. A
656 lambda has the form
657 { | parameters | commands }
659 The parameters are one or more variable names, to which arguments of
661 the lambda are assigned while the commands are run. The first argument
662 is assigned to the first variable, the second to the second, and so on.
663 If there are more arguments than parameters, the last named variable is
664 assigned all the remaining arguments; if there are fewer, the parame‐
665 ters for which there are no arguments are bound to the empty list.
666 Lambdas, like other program fragments, can appear anywhere in a list.
668 A more complicated example in the same spirit:
669 { |cmd arg| $cmd $arg } { |*| echo $* } hi
671 This command executes a lambda which runs its first argument, named
673 cmd, using its second argument, named arg, as the argument for the
674 first. The first argument of this function is another lambda, seen
675 previously, and the second argument is the word hi.
676 These lambda expressions
678 { |a b c| echo $c $b $a } 1 2
680 { |a b c| echo $c $b $a } 1 2 3 4 5
681 produce this output:
683 2 1
685 3 4 5 2 1
686 Functions
688 A function in xs is introduced with the syntax
689 fn name parameters { commands }
691 If the function name appears as the first word of a command, the com‐
693 mands are run, with the named parameters bound to the arguments to the
694 function.
695 The similarity between functions and lambdas is not coincidental. A
697 function in xs is a variable of the form fn-name. If name for which
698 the appropriate fn- variable exists is found in the first position of a
699 command, the value of the variable is substituted for the first word.
700 The above syntax for creating functions is equivalent to the variable
701 assignment
702 fn-name = { | parameters | commands }
704 Functions may be deleted with the syntax
706 fn name
708 which is equivalent to the assignment
710 fn-name=
712 If, as the most common case, a function variable is bound to a lambda,
714 when the function is invoked, the variable $0 is bound (dynamically,
715 see below) to the name of the function.
716 Lambdas are just another form of code fragment, and, as such, can be
718 exported in the environment, passed as arguments, etc. The central
719 difference between the two forms is that lambdas bind their arguments,
720 while simple brace-enclosed groups just ignore theirs.
721 Local Variables
723 Variable assignments may be made local to a set of commands with the
724 local construct:
725 local (var = value; var = value ...) command
727 The command may be a program fragment, so for example:
729 local (path = /bin /usr/bin; ifs = ) {
731 ...
732 }
733 sets path to a minimal useful path and removes ifs for the duration of
735 one long compound command.
736 Local-bound variables are exported into the environment, and will
738 invoke appropriately named settor functions (see below).
739 Lexically Scoped Variables
741 In addition to local variables, xs supports a different form of tempo‐
742 rary variable binding, using let-bound, or ``lexically scoped,'' vari‐
743 ables. (Lexical scoping is the form of binding used by most compiled
744 programming languages, such as C or Scheme.) A lexically scoped vari‐
745 able is introduced with a let statement:
746 let (var = value; var = value ...) command
748 (Also, the "= value" can be left out with same effect as "var =")
750 All references to any of the variables defined in a let statement by
752 any code located lexically (that is, textually) within the command por‐
753 tion of the statement will refer to the let-bound variable rather than
754 any environment or local-bound variable; the immediate text of the let
755 statement is the complete extent of that binding. That is, lexically
756 bound variables surrounding code fragments follow those code fragments
757 around.
758 An example best shows the difference between let and local (also known
760 as ``dynamic'') binding: (note that ``; '' is xs's default prompt.)
761 ; x = foo
763 ; let (x = bar) {
764 echo $x
765 fn lexical { echo $x }
766 }
767 bar
768 ; local (x = baz) {
769 echo $x
770 fn dynamic { echo $x }
771 }
772 baz
773 ; lexical
774 bar
775 ; dynamic
776 foo
777 ;
778 Lexically bound variables are not exported into the environment, and
780 never cause the invocation of settor functions. Function (lambda)
781 parameters are lexically bound to their values.
782 For loops
784 The command
785 for var list { command }
787 Runs the command once for each element of the list, with the named
789 variable bound lexically to each element of the list, in order. Note
790 that if list consists of more than a single term, for example (a b c)
791 it must be parenthesized.
792 If multiple bindings are given in the for statement, the looping occurs
794 in parallel and stops when all lists are exhausted. When one list is
795 finished before the others, the corresponding variable is bound to the
796 empty list for the remaining iterations. Thus the loop
797 for i (a b c); j (x y) { echo $#i $i $#j $j}
799 produces the output
801 1 a 1 x
803 1 b 1 y
804 1 c 0
805 Settor Functions
807 A settor function is a variable of the form set-var, which is typically
808 bound to a lambda. Whenever a value is assigned to the named variable,
809 the lambda is invoked with its arguments bound to the new value. While
810 the settor function is running, the variable $0 is bound to the name of
811 the variable being assigned. The result of the settor function is used
812 as the actual value in the assignment.
813 For example, the following settor function is used to keep the shell
815 variables home and HOME synchronized.
816 set-HOME = { |*|
818 local (set-home = )
819 home = $*
820 result $*
821 }
822 This settor function is called when any assignment is made to the vari‐
824 able HOME. It assigns the new value to the variable home, but disables
825 any settor function for home to prevent an infinite recursion. Then it
826 returns its argument unchanged for use in the actual assignment to
827 HOME.
828 Settor functions do not apply to lexically bound variables.
830 Primitives
832 Primitives are internal xs operations that cannot or should not (for
833 reasons of performance) be written in the interpreter's language. The
834 set of primitives makes up the run-time library for xs.
835 Primitives can be used with the syntax
837 $&name
839 A primitive can be used anywhere a lambda is expected. The list of
841 primitives is returned as the result of running the primitive $&primi‐
842 tives.
843 For details on specific primitives, see the section entitled PRIMITIVES
845 below.
846 Exceptions
848 Exceptions in xs are used for many forms of non-structured control
849 flow, notably error reporting, signals, and flow of control constructs
850 such as escape.
851 Exceptions are passed up the call chain to catching routines. A
853 catcher may decide to intercept an exception, retry the code that
854 caused the exception, or pass the exception along. There can only be
855 one exception raised at any time.
856 Exceptions are represented by lists. The first word of an exception
858 is, by convention, the type of exception being raised. The following
859 exceptions are known:
860 eof Raised by %parse when the end of input is reached.
862 error source message
864 A run-time error. Almost all shell errors are reported with the
865 error exception. The default interactive loop and the outermost
866 level of the interpreter catch this exception and print the mes‐
867 sage. Source is the name of the routine (typically a primitive)
868 which raised the error.
869 retry When raised from a signal catcher, causes the body of the catch
871 clause to be run again.
872 signal signame
874 Raised when the shell itself receives a signal, and the signal
875 is listed in the variable signals. Signame is the name of the
876 signal that was raised.
877 See the builtin commands catch and throw for details on how to manipu‐
879 late exceptions.
880
882 Several variables are known to xs and are treated specially. Redefin‐
883 ing these variables can change interpreter semantics. Note that only
884 dynamically bound (top-level or local-bound) variables are interpreted
885 in this way; the names of lexically bound variables are unimportant.
886 * The argument list of xs. $1, $2, etc. are the same as $*(1),
888 $*(2), etc.
889 $0 Holds the value of argv[0] with which xs was invoked. Addition‐
891 ally, $0 is set to the name of a function for the duration of
892 the execution of that function, and $0 is also set to the name
893 of the file being interpreted for the duration of a . command.
894 apid The process ID of the last process started in the background.
896 history
898 The name of a file to which commands are appended as xs reads
899 them. This facilitates the use of a stand-alone history program
900 (such as history(1)) which parses the contents of the history
901 file and presents them to xs for reinterpretation. If history
902 is not set (the default), then xs does not append commands to
903 any file.
904 home The current user's home directory, used in tilde (~) expansion,
906 as the default directory for the builtin cd command, and as the
907 directory in which xs looks to find its initialization file,
908 .esrc, if xs has been started up as a login shell. Like path
909 and PATH, home and HOME are aliased to each other.
910 ifs The default input field separator, used for splitting up the
912 output of backquote commands for digestion as a list. The ini‐
913 tial value of ifs is space-tab-newline.
914 noexport
916 A list of variables which xs will not export. All variables
917 except for the ones on this list and lexically bound variables
918 are exported.
919 path This is a list of directories to search in for commands. The
921 empty string stands for the current directory. Note also that
922 an assignment to path causes an automatic assignment to PATH,
923 and vice-versa. If neither path nor PATH are set at startup
924 time, path assumes a default value suitable for your system.
925 This is typically /usr/ucb /usr/bin /bin ''.
926 pid The process ID of the currently running xs.
928 prompt This variable holds the two prompts (in list form) that xs
930 prints. $prompt(1) is printed before each command is read, and
931 $prompt(2) is printed when input is expected to continue on the
932 next line. (See %parse for details.) xs sets $prompt to ('; '
933 '') by default. The reason for this is that it enables an xs
934 user to grab commands from previous lines using a mouse, and to
935 present them to xs for re-interpretation; the semicolon prompt
936 is simply ignored by xs. The null $prompt(2) also has its jus‐
937 tification: an xs script, when typed interactively, will not
938 leave $prompt(2)'s on the screen, and can therefore be grabbed
939 by a mouse and placed directly into a file for use as a shell
940 script, without further editing being necessary.
941 signals
943 Contains a list of the signals which xs traps. Any signal name
944 which is added to this list causes that signal to raise an xs
945 exception. For example, to run some commands and make sure some
946 cleanup routine is called even if the user interrupts or discon‐
947 nects during the script, one can use the form:
948 local (signals = $signals sighup sigint) {
950 catch { |e|
951 cleanup
952 throw $e
953 } {
954 ...
955 }
956 }
957 A signal name prefixed by a hyphen (-) causes that signal to be
959 ignored by xs and all of its child processes, unless one of them
960 resets its handler. A signal prefixed by a slash (/) is ignored
961 in the current shell, but retains default behavior in child pro‐
962 cesses. In addition, the signal sigint may be preceeded by the
963 prefix (.) to indicate that normal shell interrupt processing
964 (i.e., the printing of an extra newline) occurs. By default xs
965 starts up with the values
966 .sigint /sigquit /sigterm
968 in $signals; other values will be on the list if the shell
970 starts up with some signals ignored.
971 The values of path and home are derived from the environment values of
973 PATH and HOME if those values are present. This is for compatibility
974 with other Unix programs, such as sh(1). $PATH is assumed to be a
975 colon-separated list.
976
978 xs internally rewrites much of the syntax presented thus far in terms
979 of calls to shell functions. Most features of xs that resemble tradi‐
980 tional shell features are included in this category. This rewriting
981 occurs at parse time, as commands are recognized by the interpreter.
982 The shell functions that are the results of rewriting are some of the
983 hook functions documented below.
984 The following tables list all of the major rewriting which xs does,
986 with the forms typically entered by the user on the left and their
987 internal form on the right. There is no reason for the user to avoid
988 using the right-hand side forms, except that they are usually less con‐
989 venient. To see the internal form of a specific command, a user can
990 run xs with the -n and -x options; when invoked in this way, the shell
991 prints the internal form of its commands rather than executing them.
992 Control Flow
994 ! cmd %not {cmd}
995 cmd & %background {cmd}
996 cmd1 ; cmd2 %seq {cmd1} {cmd2}
997 cmd1 && cmd2 %and {cmd1} {cmd2}
998 cmd1 || cmd2 %or {cmd1} {cmd2}
999 fn name args { cmd } fn-^name = { |args| cmd}
1000 Input/Output Commands
1002 cmd < file %open 0 file {cmd}
1003 cmd > file %create 1 file {cmd}
1004 cmd >[n] file %create n file {cmd}
1005 cmd >> file %append 1 file {cmd}
1006 cmd <> file %open-write 0 file {cmd}
1007 cmd <>> file %open-append 0 file {cmd}
1008 cmd >< file %open-create 1 file {cmd}
1009 cmd >>< file %open-append 1 file {cmd}
1010 cmd >[n=] %close n {cmd}
1011 cmd >[m=n] %dup m n {cmd}
1012 cmd << tag input tag %here 0 input {cmd}
1013 cmd <<< string %here 0 string {cmd}
1014 cmd1 | cmd2 %pipe {cmd1} 1 0 {cmd2}
1015 cmd1 |[m=n] cmd2 %pipe {cmd1} m n {cmd2}
1016 cmd1 >{ cmd2 } %writeto var {cmd2} {cmd1 $var}
1017 cmd1 <{ cmd2 } %readfrom var {cmd2} {cmd1 $var}
1018 Expressions
1020 $#var <={%count $var}
1021 $^var <={%flatten ' ' $var}
1022 `{cmd args} <={%backquote <={%flatten '' $ifs} {cmd args}}
1023 ``ifs {cmd args} <={%backquote <={%flatten '' ifs} {cmd args}}
1024
1026 Builtin commands are shell functions that exist at shell startup time.
1027 Most builtins are indistinguishable from external commands, except that
1028 they run in the context of the shell itself rather than as a child
1029 process. Many builtins are implemented with primitives (see above).
1030 Some builtin functions have names that begin with a percent character
1032 (%). These are commands with some special meaning to the shell, or are
1033 meant for use only by users customizing the shell. (This distinction
1034 is somewhat fuzzy, and the decisions about which functions have %-names
1035 are somewhat arbitrary.)
1036 All builtins can be redefined and extended by the user.
1038 Builtin Commands
1040 . [-einvx] file [args ...]
1041 Reads file as input to xs and executes its contents. The
1042 options are a subset of the invocation options for the shell
1043 (see below).
1044 access [-n name] [-1e] [-rwx] [-fdcblsp] path ...
1046 Tests if the named paths are accessible according to the options
1047 presented. Normally, access returns zero (true) for files which
1048 are accessible and a printable error message (which evaluates as
1049 false, according to shell rules) for files which are not acces‐
1050 sible. If the -1 option is used, the name of the first file
1051 which the test succeeds for is returned; if the test succeeds
1052 for no file, the empty list is returned. However, if the -e
1053 option was used, access raises an error exception. If the -n
1054 option is used, the pathname arguments are treated as a list of
1055 directories, and the name option argument is used as a file in
1056 those directories (i.e., -n is used for path searching).
1057 The default test is whether a file exists. These options change
1059 the test:
1060 -r Is the file readable (by the current user)?
1062 -w Is the file writable?
1064 -x Is the file executable?
1066 -f Is the file a plain file?
1069 -d Is the file a directory?
1071 -c Is the file a character device?
1073 -b Is the file a block device?
1075 -l Is the file a symbolic link?
1077 -s Is the file a socket?
1079 -p Is the file a named pipe (FIFO)?
1081 alias alias-name expansion...
1083 Define a new function, alias-name , which calls expansion The
1084 first command in expansion is replaced with it's whatis value to
1085 prevent recursion. This can be used to serve a somewhat similar
1086 purpose as in bash. For example, the following will force ls to
1087 use color, and make l be ls in long form, with color (due to
1088 previous alias):
1089 alias ls ls --color=yes
1091 alias l ls -l
1092 break value
1094 Exits the current loop. Value is used as the return value for
1095 the loop command.
1096 catch catcher body
1098 Runs body. If it raises an exception, catcher is run and passed
1099 the exception as an argument.
1100 cd [directory]
1102 Changes the current directory to directory. With no argument,
1103 cd changes the current directory to $home.
1104 echo [-n] [--] args ...
1106 Prints its arguments to standard output, terminated by a new‐
1107 line. Arguments are separated by spaces. If the first argument
1108 is -n no final newline is printed. If the first argument is --,
1109 then all other arguments are echoed literally; this is used for
1110 echoing a literal -n.
1111 escape lambda
1113 Run lambda with one argument, an escape block which when
1114 evaulated will return to the point after this escape. This is
1115 more formally refered to as an escape continuation. In fact,
1116 it's behaviour is a simple subset of exceptions, and is imple‐
1117 mented fairly simply using catch. Escape is useful to replace
1118 return/break like constructs; for example
1119 fn f { escape |fn-return| {
1121 ...; return 0;
1122 ...
1123 }
1124 will exit the function with result 0 when it reached the return.
1126 eval list
1128 Concatenates the elements of list with spaces and feeds the
1129 resulting string to the interpreter for rescanning and execu‐
1130 tion.
1131 exec cmd
1133 Replaces xs with the given command. If the exec contains only
1134 redirections, then these redirections apply to the current shell
1135 and the shell does not exit. For example,
1136 exec {>[2] err.out}
1138 places further output to standard error in the file err.out.
1140 Unlike some other shells, xs requires that redirections in an
1141 exec be enclosed in a program fragment.
1142 exit [status]
1144 Causes the current shell to exit with the given exit status. If
1145 no argument is given, zero (true) is used. (This is different
1146 from other shells, that often use the status of the last command
1147 executed.)
1148 false Always returns a false (non-zero) return value.
1150 forever cmd
1152 Runs the command repeatedly, until the shell exits or the com‐
1153 mand raises an exception. This is equivalent to a while {true}
1154 {cmd} loop except that forever does not catch any exceptions,
1155 including break.
1156 fork cmd
1158 Runs a command in a subshell. This insulates the parent shell
1159 from the effects of state changing operations such as cd and
1160 variable assignments. For example:
1161 fork {cd ..; make}
1163 runs make(1) in the parent directory (..), but leaves the shell
1165 in the current directory.
1166 if [test then-action] [else else-action]
1168 Evaluates the command test. If the result is true, the command
1169 then is run and if completes. If the result of the test is
1170 false, the else command is run. The else-action doesn't require
1171 braces no matter the number of actions, so one can write code
1172 like:
1173 ... } else if {~ $a $b} { ... }
1175 Note that:
1176 ...}
1178 else if {~ $a $b} { ... }
1179 , with the else on a seperate line, will only work if the if-
1180 command has parentheses wrapping it's body and else-statements.
1181 limit [-h] [resource [value]]
1183 Similar to the csh(1) limit builtin, this command operates upon
1184 the resource limits of a process. With no arguments, limit
1185 prints all the current limits; with one argument, limit prints
1186 the named limit; with two arguments, it sets the named limit to
1187 the given value. The -h flag displays/alters the hard limits.
1188 The resources which can be shown or altered are cputime, file‐
1189 size, datasize, stacksize, coredumpsize and memoryuse. For
1190 example:
1191 limit coredumpsize 0
1193 disables core dumps.
1195 The limit values must either be the word ``unlimited'' or a num‐
1197 ber with an optional suffix indicating units. For size limits,
1198 the suffixes k (kilobytes), m (megabytes), and g (gigabytes) are
1199 recognized. For time limits, s (seconds), m (minutes), and h
1200 (hours) are known; in addition, times of the form hh:mm:ss and
1201 mm:ss are accepted. See getrlimit(2) for details on resource
1202 limit semantics.
1203 map action list
1205 Call action with a single argument for each element of list.
1206 Since lists auto-expand, list contains the rest of the arguments
1207 to the command. Returns the list of results of each action. If
1208 action returns a list, it is expanded inside into a new process
1209 group. This builtin is useful for making xs behave like a job-
1210 control shell in a hostile environment. One example is the NeXT
1211 Terminal program, which implicitly assumes that each shell it
1212 forks will put itself into a new process group. Note that the
1213 controlling tty for the process must be on standard error (file
1214 descriptor 2) when this operation is run.
1215 omap action list
1217 Like map , but return the list of the outputs of action, in the
1218 same form as if `` '' action were called.
1219 popd cd into the directory that was last pushed by pushd , popping
1221 the directory off of an internal stack. If it's internal stack
1222 is empty (for example, if pushd has not been called), then stays
1223 in the current directory. Also prints out the stack, starting
1224 from the top.
1225 pushd [dir]
1227 Add directory's absolute path onto popd 's stack. Also outputs
1228 the stack.
1229 result value ...
1231 Returns its arguments. This is xs's identity function.
1232 switch value [case1 action1]...[default-action]
1234 Go through the list of cases, testing if they are equal to
1235 value. The matching action of the first case which matches is
1236 executed. The break exception can be used to manually exit the
1237 switch, but is not necessary to signify the end of an action
1238 (unlike in C).
1239 until test body
1241 Identical to while, except test is negated
1242 throw exception arg ...
1244 Raise the named exception, passing all of the arguments to throw
1245 to the enclosing exception handler.
1246 time cmd arg ...
1248 Prints, on the shell's standard error, the real, user, and sys‐
1249 tem time consumed by executing the command.
1250 true Always returns a true (zero) return value.
1252 umask [mask]
1254 Sets the current umask (see umask(2)) to the octal mask. If no
1255 argument is present, the current mask value is printed.
1256 unwind-protect body cleanup
1258 Runs body and, when it completes or raises an exception, runs
1259 cleanup.
1260 var var ...
1262 Prints definitions of the named variables, suitable for being
1263 used as input to the shell.
1264 vars [-vfs] [-epi]
1266 Prints all shell variables, functions, and settor functions (in
1267 a form suitable for use as shell input), which match the crite‐
1268 ria specified by the options.
1269 -v variables (that are not functions or settor functions)
1271 -f functions
1273 -s settor functions
1275 -e exported values
1278 -p private (not exported) values
1280 -i internal (predefined and builtin) values
1282 -a all of the above
1285 If none of -v, -f, or -s are specified, -v is used. If none of
1287 -e, -p, or -i are specified, -e is used.
1288 wait [pid]
1290 Waits for the specified pid, which must have been started by xs.
1291 If no pid is specified, waits for any child process to exit.
1292 whatis progam ...
1294 For each named program, prints the pathname, primitive, lambda,
1295 or code fragment which would be run if the program appeared as
1296 the first word of a command.
1297 while test body
1299 Evaluates the test and, if it is true, runs the body and
1300 repeats.
1301 %read Reads from standard input and returns either the empty list (in
1303 the case of end-of-file) or a single element string with up to
1304 one line of data, including possible redirections. This func‐
1305 tion reads one character at a time in order to not read more
1306 data out of a pipe than it should. The terminating newline (if
1307 present) is not included in the returned string.
1308 Hook Functions
1310 A subset of the %-named functions are known as ``hook functions.'' The
1311 hook functions are called to implement some internal shell operations,
1312 and are available as functions in order that their values can be
1313 changed. Typically, a call to a hook function is from code generated
1314 by the syntactic sugar rewritings.
1315 %and cmd ...
1317 Runs the commands in order, stopping after the first one that
1318 has a false return value. Returns the result of the last com‐
1319 mand run.
1320 %append fd file cmd
1322 Runs the command with file descriptor fd set up to append to the
1323 file.
1324 %background cmd
1326 Runs the command in the background. The shell variable apid
1327 contains the process ID of the background process, which is
1328 printed if the shell is interactive (according to %is-interac‐
1329 tive).
1330 %backquote separator cmd
1332 Runs the command in a child process and returns its standard
1333 output as a list, separated (with the same rules used in %split)
1334 into elements according to separator.
1335 %batch-loop
1337 Parses commands from the current input source and passes the
1338 commands to the function %dispatch, which is usually a dynami‐
1339 cally bound identifier. This function catches the exception eof
1340 which causes it to return. This function is invoked by the
1341 shell on startup and from the dot (.) and eval commands, when
1342 the input source is not interactive. (See also %interactive-
1343 loop.)
1344 %close fd cmd
1346 Runs the command with the given file descriptor closed.
1347 %count list
1349 Returns the number of arguments to the primitive.
1350 %create fd file cmd
1352 Runs the command with file descriptor fd set up to write to the
1353 file.
1354 %dup newfd oldfd cmd
1356 Runs the command with the file descriptor oldfd copied (via
1357 dup(2)) to file descriptor newfd.
1358 %eval-noprint cmd
1360 Run the command. (Passed as the argument to %batch-loop and
1361 %interactive-loop.)
1362 %eval-print cmd
1364 Print and run the command. (Passed as the argument to %batch-
1365 loop and %interactive-loop when the -x option is used.)
1366 %exec-failure file argv0 args ...
1368 This function, if it exists, is called in the context of a child
1369 process if an executable file was found but execve(2) could not
1370 run it. If the function returns, an error message is printed
1371 and the shell exits, but the function can exec a program if it
1372 thinks it knows what to do. Note that the name of the program
1373 appears twice in the arguments to %exec-failure, once as a file‐
1374 name and once as the first element of the argv array; in some
1375 cases the two will be identical, but in others the former will
1376 be a full pathname and the latter will just be the basename.
1377 Some versions of xs may provide a builtin version of this func‐
1378 tion to handle #!-style shell scripts if the kernel does not.
1379 %exit-on-false cmd
1381 Runs the command, and exits if any command (except those execut‐
1382 ing as the tests of conditional statements) returns a non-zero
1383 status. (This function is used as an argument to %batch-loop
1384 and %interactive-loop when the shell is invoked with the -e
1385 option.)
1386 %flatten separator list
1388 Concatenate the elements of list into one string, separated by
1389 the string separator.
1390 %here fd word ... cmd
1392 Runs the command with the words passed as input on file descrip‐
1393 tor fd.
1394 %home [user]
1396 Returns the home directory of the named user, or $home if there
1397 are no arguments.
1398 %interactive-loop
1400 Prompts, parses commands from the current input source and
1401 passes the commands to the function %dispatch, which is usually
1402 a dynamically bound identifier. This function catches the
1403 exception eof which causes it to return. This function is
1404 invoked by the shell on startup and from the dot (.) commands,
1405 when the input source is interactive. (See also %batch-loop.)
1406 %noeval-noprint cmd
1408 Do nothing. (Passed as the argument to %batch-loop and %inter‐
1409 active-loop when the -n option is used.)
1410 %noeval-print cmd
1412 Print but don't run the command. (Passed as the argument to
1413 %batch-loop and %interactive-loop when the -x and -n options are
1414 used.)
1415 %not cmd
1417 Runs the command and returns false if its exit status was true,
1418 otherwise returns true.
1419 %one list
1421 If list is one element long, %one returns its value; otherwise
1422 it raises an exception. %one is used to ensure that redirection
1423 operations get passed exactly one filename.
1424 %open fd file cmd
1426 Runs the command with file open for reading on file descriptor
1427 fd.
1428 %open-append fd file cmd
1430 Runs the command with file open for reading and appending on
1431 file descriptor fd.
1432 %open-create fd file cmd
1434 Runs the command with file open for reading and writing on file
1435 descriptor fd. If the file already exists, it is truncated.
1436 %open-write fd file cmd
1438 Runs the command with file open for reading and writing on file
1439 descriptor fd.
1440 %openfile mode fd file cmd
1442 Runs the command with file opened according to mode on file
1443 descriptor fd. The modes (r, w, a, r+, w+, and a+) have the
1444 same meanings in %openfile as they do in fopen(3). %openfile is
1445 invoked by the redirection hook functions: %append, %create,
1446 %open, %open-append, %open-create, and %open-write.
1447 %or cmd ...
1449 Runs the commands in order, stopping after the first one that
1450 has a true return value. Returns the result of the last command
1451 run.
1452 %parse prompt1 prompt2
1454 Reads input from the current input source, printing prompt1
1455 before reading anything and prompt2 before reading continued
1456 lines. Returns a code fragment suitable for execution. Raises
1457 the exception eof on end of input.
1458 %pathsearch program
1460 Looks for an executable file named program in the directories
1461 listed in $path. If such a file is found, it is returned; if
1462 one is not found, an error exception is raised.
1463 %pipe cmd [outfd infd cmd] ...
1465 Runs the commands, with the file descriptor outfd in the left-
1466 hand process connected by a pipe to the file descriptor infd in
1467 the right-hand process. If there are more than two commands, a
1468 multi-stage pipeline is created.
1469 %prompt
1471 Called by %interactive-loop before every call to %parse. This
1472 function allows the user to provide any actions that he or she
1473 may wish to have executed before being prompted (e.g., updating
1474 the value of the prompt variable to contain all or part of the
1475 current working directory).
1476 %readfrom var input cmd
1478 Runs cmd with the variable var locally bound to the name of a
1479 file which contains the output of running the command input.
1480 %seq cmd ...
1482 Runs the commands, in order.
1483 %whatis program ...
1485 For each named program, returns the pathname, primitive, lambda,
1486 or code fragment which would be run if the program appeared as
1487 the first word of a command.
1488 %writeto var output cmd
1490 Runs cmd with the variable var locally bound to the name of a
1491 file which is used as the input for the command output.
1492 Utility Functions
1494 These functions are useful for people customizing the shell, may be
1495 used by other builtin commands, and probably don't make much sense to
1496 replace, though that is always possible.
1497 %apids Returns the process IDs of all background processes that the
1499 shell has not yet waited for.
1500 %fsplit separator [args ...]
1502 Splits its arguments into separate strings at every occurrence
1503 of any of the characters in the string separator. Repeated
1504 instances of separator characters cause null strings to appear
1505 in the result. (This function is used by some builtin settor
1506 functions.)
1507 %is-interactive
1509 Returns true if the current interpreter context is interactive;
1510 that is, if shell command input is currently coming from an
1511 interactive user. More precisely, this is true if the innermost
1512 enclosing read-eval-print loop is %interactive-loop rather than
1513 %batch-loop.
1514 %newfd Returns a file descriptor that the shell thinks is not currently
1516 in use.
1517 %run program argv0 args ...
1519 Run the named program, which is not searched for in $path, with
1520 the argument vector set to the remaining arguments. This
1521 builtin can be used to set argv[0] (by convention, the name of
1522 the program) to something other than file name.
1523 %split separator [args ...]
1525 Splits its arguments into separate strings at every occurrence
1526 of any of the characters in the string separator. Repeated
1527 instances of separator characters are coalesced. Backquote sub‐
1528 stitution splits with the same rules.
1529 %var var ...
1531 For each named variable, returns a string which, if interpreted
1532 by xs would assign to the variable its current value.
1533
1535 Primitives exist in xs so that, in the presence of spoofing and redefi‐
1536 nitions, there is a way to refer to built-in behaviors. This ability
1537 is necessary for the shell to be able to unambiguously refer to itself,
1538 but is also useful for users who have otherwise made their environment
1539 unnecessary but don't want to kill the current shell.
1540 Primitives are referenced with the
1542 $&name
1544 notation. In this section, the ``$&'' prefixes will be omitted when
1546 primitive names are mentioned. Note that, by convention, primitive
1547 names follow C identifier names where xs variable and function names
1548 often contain ``%'' and ``-'' characters.
1549 The following primitives directly implement the builtin functions with
1551 the same names:
1552 access forever throw
1554 catch fork umask
1555 echo if wait
1556 exec newpgrp
1557 exit result
1558 In addition, the primitive dot implements the ``.'' builtin function.
1560 The cd primitive is used in the implementation of the cd builtin, but
1562 does not understand no arguments to imply $home. The vars and inter‐
1563 nals primitives are used by the implementation of the vars builtin.
1564 The following primitives implement the hook functions of the same
1566 names, with ``%'' prefixes:
1567 apids here read
1569 close home run
1570 count newfd seq
1571 dup openfile split
1572 flatten parse var
1573 fsplit pipe whatis
1574 The following primitives implement the similar named hook functions,
1576 with ``%'' prefixes and internal hyphens:
1577 batchloop exitonfalse isinteractive
1579 The background primitive is used to implement the %background hook
1581 function, but does not print the process ID of the background process
1582 or set $apid. The backquote primitive is used to implement the %back‐
1583 quote hook function, but returns the exit status of the child as the
1584 first value of its result instead of setting $bqstatus to it.
1585 The following primitives implement the similarly named settor func‐
1587 tions:
1588 sethistory setnoexport setsignals
1590 Some primitives are included in xs conditionally, based on compile-time
1592 configuration options. Those primitives, and the functions to which
1593 they are bound, are
1594 execfailure %exec-failure
1596 limit limit
1597 readfrom %readfrom
1598 time time
1599 writeto %writeto
1600 The primitive resetterminal is if xs is compiled with support for the
1602 readline or editline libraries. It is used in the implementation of
1603 settor functions of the TERM and TERMCAP variables to notify the line
1604 editing packages that the terminal configuration has changed.
1605 Several primitives are not directly associated with other function.
1607 They are:
1608 $&collect
1610 Invokes the garbage collector. The garbage collector in xs runs
1611 rather frequently; there should be no reason for a user to issue
1612 this command.
1613 $&noreturn lambda args ...
1615 Call the lambda, but in such a way that it does not catch the
1616 return exception. This primitive exists in order that some con‐
1617 trol-flow operations in xs (e.g., while and &&) can be imple‐
1618 mented as lambdas rather than primitives.
1619 $&primitives
1621 Returns a list of the names of xs primitives.
1622 $&version
1624 Returns the current version number and release date for xs.
1625
1627 -c Run the given command, placing the rest of the arguments to xs
1628 in $*.
1629 -s Read commands from standard input; i.e., put the first argument
1631 to xs in $* rather than using it as the name of a file to
1632 source.
1633 -i Force xs to be an interactive shell. Normally xs is only inter‐
1635 active if it is run with commands coming from standard input and
1636 standard input is connected to a terminal.
1637 -l Run $home/.esrc on startup, i.e., be a login shell. -l is
1639 implied if the name the shell was run under (that is, argv[0])
1640 starts with a dash (-).
1641 -e Exit if any command (except those executing as the tests of con‐
1643 ditional statements) returns a non-zero status.
1644 -v Echo all input to standard error.
1646 Exit if any command (except those executing as the tests of
1648 conditional statements) returns a non-zero status.
1649 -v Echo all input to standard error.
1651 -x Print commands to standard error before executing them.
1653 -n Turn off execution of commands. This can be used for checking
1655 the syntax of scripts. When combined with -x, xs prints the
1656 entered command based on the internal (parsed) representation.
1657 -p Don't initialize functions from the environment. This is used
1659 to help make scripts that don't break unexpectedly when the
1660 environment contains functions that would override commands used
1661 in the script.
1662 -o Don't open /dev/null on file descriptors 0, 1, and 2, if any of
1664 those descriptors are inherited closed.
1665 -d Don't trap SIGQUIT or SIGTERM. This is used for debugging.
1667
1669 As with any other shell scripting language, process forking takes up
1670 the majority of time:
1671 x = 0; while {!~ $x 4000} { x = :(x + 1) }
1673 is several magnitudes faster than:
1674 x = 0; while {test $x -ne 4000} { x = :(x + 1) }
1676 Even though xs's arithmetic code is rather slow, in this case the cost
1677 of fork+exec far outweighs it.
1678 Elaborate tricks involving stringifying closures and unstringying them
1680 later will probably not work. In general, trying to manipulate the
1681 scope of variables through similar techniques will probably not do what
1682 one expects.
1683
1685 $home/.xsrc, /dev/null
1686
1688 The interpreter should be properly tail recursive; that is, tail calls
1689 should not consume stack space.
1690 break and return should have lexical scope.
1692 Woe betide the environment string set by some other program to contain
1694 either the character control-a or the sequence control-b followed by
1695 control-a or control-b.
1696 -x is not nearly as useful as it should be.
1698 Too many creatures have fept in.
1700 Please send bug reports to fkfire@gmail.com.
1702
1704 history(1), es(1), rc(1), sh(1), execve(2), getrlimit(2), fopen(3),
1705 getpwent(3)
1706 Paul Haahr and Byron Rakitzis, Es — A shell with higher-order func‐
1708 tions, Proceedings of the Winter 1993 Usenix Conference, San Diego, CA.
1709 Tom Duff, Rc — A Shell for Plan 9 and UNIX Systems, Unix Research Sys‐
1711 tem, 10th Edition, Volume 2. (Saunders College Publishing)
1712 5 March 1992 XS(1)