1XS(1) General Commands Manual XS(1)
2
6 xs - extensible shell
7
9 xs [-silevxnpod] [-c FRAGMENT | SCRIPT [ARGUMENTS]]
10
12 Xs is a command interpreter for Linux. Xs allows programming in a
13 functional style and has a simple, consistent syntax.
14 Xs provides hooks to customize many of its internal operations, includ‐
16 ing primitives for exception handling and lexical and dynamic control
17 flow.
18 A significant portion of xs is implemented in xs.
20 Xs is a descendant of rc(1) and es(1); the three implementations are
22 not interoperable.
23
25 -s Read commands from standard input; pass the first argu‐
26 ment to xs rather than taking the argument as the name of
27 a file to source.
28 -i Force xs to be an interactive shell even if commands do
29 not come from standard input via a terminal.
30 -l Cause xs to be a login shell, as if it had been invoked
31 as -xs.
32 -e Exit if any command (apart from those appearing as tests
33 in conditional forms or as arguments to logical opera‐
34 tors) returns a false status.
35 -v Echo input to standard error.
36 -x Print commands to standard error.
37 -n Disable command execution.
38 -p Don't initialize functions from the environment.
39 -o If any of file descriptors 0, 1 or 2 are inherited
40 closed, leave them closed rather than open on /dev/null.
41 -d Don't trap SIGQUIT or SIGTERM.
42 -c FRAGMENT Execute the FRAGMENT. (See Program fragments, below.)
43
45 Lexically, an xs program consists of words and punctuation. (See FOOT‐
46 NOTE.)
47 Words
49 In its simplest form, a word is a sequence of non-special characters.
50 The special characters are:
51 # $ & ' ( ) ; < > \ ^ ` { | } space tab newline
53 The empty word is denoted by ''.
55 Words are indivisible and immutable.
57 Escapes
59 A special character may escaped by preceeding it with a backslash (\);
60 this defeats the character's special meaning, allowing the character to
61 be (part of) a word.
62 Other escapes denote control characters:
64 \a alert (bell)
66 \b backspace
68 \e escape
69 \f form feed
70 \n newline
71 \r return
72 \t tab
73 A character octet may be denoted by its hexadecimal or octal code
75 point:
76 \xnn Character octet nn, for n in {0..0, a..f, A..F}
78 \mnn Character octet mnn, for m in {0..3} and n in {0..7}
79 A UTF-8 octet sequence may be denoted using the escape sequence:
81 \u'n...' UTF-8 character having codepoint n..., for one to six
83 n in {0..9, a..f, A..F}
84 Xs does not allow scripts to contain a NUL character; thus the follow‐
86 ing are all invalid:
87 \000, \x00 and \u'0'.
89 A backslash must not be followed by a sequence of characters other than
91 as described above.
92 Quoted words
94 A sequence of characters enclosed by apostrophes (') is a word; the
95 bounding ' are not part of the word. We refer to this form as a quoted
96 word.
97 An apostrophe is written within a quoted word by doubling it, e.g.,
99 'Sam''s word' .
101 All other special characters lose their meaning within a quoted word.
103 Commands
105 A command is a sequence of words separated by whitespace. The first
106 word is always the name of an executable program on $path, an xs func‐
107 tion, or a lambda (defined below). Subsequent words are arguments;
108 these are subject to evaluation, expansion and substitution. Because
109 the arguments are passed as a list, any argument that yields () will
110 "disappear" (see Lists).
111 Command separator
113 A command must occupy one logical line. Commands are separated by new‐
114 lines or semicolons (;).
115 Program fragments
117 A program fragment (henceforth fragment) is a sequence of zero or more
118 commands enclosed in braces:
119 {command*} .
121 A fragment may span multiple physical lines.
123 The value of a fragment is the result code returned by the last command
125 executed. An empty fragment ({}) has a result of zero. A fragment
126 containing a pipeline (see Pipes) returns a list of results: one for
127 each function or executable in the pipeline; the list is true in the
128 aggregate only if each element is true (see Truth values).
129 A fragment appearing as a parameter of a function or executable is
131 treated as a single word. Fragments are indivisible and immutable.
132 The braces may be elided if the command is a single word having no
134 arguments.
135 Comments
137 The hash mark (#) introduces a comment which ends at newline.
138 Line continuation
140 Program text may be split across physical lines by ending each logical
141 line with a backslash (\). The backslash and the immediately following
142 newline are read as a space.
143 Lists
145 A list is a space-separated sequence of words. The empty list is
146 denoted by (). All lists are flat in xs; balanced parentheses may be
147 written for grouping, but they do not create a tree. Thus
148 this is a list of seven words
150 and
152 this (is a list) ((of) () (seven words)) ()
154 are identical.
156 A list enclosed in parentheses may span multiple lines without need of
158 line continuation characters.
159 Concatenation
161 Lists may be joined using the concatenation operator, caret (^).
162 A list of length one is a word. Concatenating two words creates a new
164 word.
165 When either list has length greater than one, the result of concatena‐
167 tion is the cross product of the lists.
168 When either list is empty, the result of concatenation is the empty
170 list.
171 Variable names
173 Letters, digits, all UTF-8 characters encoded as at least two octets
174 (i.e., code points greater than \u'7f') and the characters percent (%),
175 star (*), hyphen (-) and underscore (_) may be used in variable names.
176 These characters may appear in any order or combination.
177 The xs special characters (see Words) may also appear in a variable
179 name if quoted or escaped. Likewise, character escapes (see Escapes)
180 may be part of a variable name.
181 Variable names having the prefix fn- or var- have special meaning; see
183 Functions and Settors, respectively.
184 Assignment
186 A variable is assigned a list value using the notation
187 var = list .
189 The spaces around = are mandatory.
191 A variable becomes undefined by assigning an empty list as its value.
193 While
194 var = ()
196 is valid, the preferred form is
198 var = .
200 The value of an assignment is its assigned value.
202 Variables
204 All variables are exported to the environment unless declared within a
205 local, let or for form (described below).
206 A variable's value is retrieved by writing $ before its name, like $var
208 . Indirection (multiple $) is allowed.
209 An undefined variable yields the empty list when referenced.
211 A variable name may be constructed at runtime. Parentheses must
213 enclose expressions used to construct a name.
214 Subscripted reference
216 Specific list elements may be selected via subscripting. This takes
217 the form
218 $var(subscripts) .
220 List elements are indexed starting at one. A subscript less than 1 is
222 an error. A subscript greater than the number of list elements yields
223 the empty list.
224 a = w x y z; echo $a(2 3 4 4 3)
226 prints x y z z y .
227 Subscripts may be specified as ranges by separating the range endpoints
229 with ... . The range operator must be separated from its arguments by
230 spaces.
231 Either end of the range may be left unspecified.
233 $var(... 7)
235 yields elements 1 through 7 of the list.
236 $var(3 ...)
238 yields elements 3 through the end of the list.
239 Reversing the endpoints of a range returns the values in reversed
241 order:
242 a = s d r a w k c a b; $a(5 ... 2)
244 yeilds the list w a r d .
245 If subscripts is an empty list, the result is empty.
247 Multiple assignment
249 A list of variables may be specified on the left side of an assignment.
250 Parentheses are mandatory around the list of variables.
251 Corresponding list elements on the right side are assigned to variables
253 on the left. If the right side has more elements than there are vari‐
254 ables on the left, the rightmost variable is assigned the list value of
255 the remaining elements. If there are more variables than list ele‐
256 ments, the excess variables are assigned the empty list.
257 Variable names may not be computed or subscripted on the left side of a
259 multiple assignment.
260 List length
262 The length of a list assigned to a variable is given by
263 $#var .
265 Flattening
267 A list may be flattened to a single word using the $^ operator. This
268 yields a word composed of the words of the given list, with a single
269 space between each pair of words. As with the subscript operator, this
270 applies only to a variable (not literal) list.
271 Free carets
273 Concatenation may be written implicitly (rather than using the ^ opera‐
274 tor) in certain situations. If a word is followed by another word, $
275 or ` without intervening whitespace, then xs inserts a caret between
276 them.
277 Wildcard patterns
279 A pattern is a word which may contain wildcards.
280 * Matches zero or more characters.
282 ? Matches exactly one character.
284 [class]
286 Matches any of the characters specified by the class, following
287 the same rules as those for ed(1), except that class negation is
288 denoted by ~ since ^ has another interpretation in xs.
289 Pathname expansion
291 Where a word may be treated as a pathname, xs expands wildcards.
292 The pathname separator, /, is never matched by *. The ? wildcard never
294 matches a dot at the beginning of a pathname component.
295 A tilde (~) alone or followed by a slash (/) is replaced by the value
297 of $home. A tilde followed by a username is replaced with the home
298 directory path of that user. (See getpwent(3).)
299 A quoted wildcard loses its meaning as a wildcard.
301 Pattern matching
303 The pattern matching operator (~) returns true when a subject matches
304 any of the given patterns:
305 ~ subject pattern ... .
307 A subject may be a list. If composed of individual words or expres‐
309 sions, the subject list must be enclosed by parentheses.
310 Pattern wildcards are never expanded with pathnames from the filesys‐
312 tem.
313 Pattern extraction
315 The pattern extraction operator (~~) returns the parts of each subject
316 that match a wildcard in the patterns:
317 ~~ subject pattern ... .
319 Subjects and patterns are the same as for the pattern matching opera‐
321 tor.
322 Arithmetic substitution
324 An infix arithmetic expression may be evaluated to produce a single
325 word representing its value:
326 `(expression) .
328 The expression consists of numeric values and the infix operators +, -,
330 *, /, % (modulus), and ** (exponentiation); these obey the usual prece‐
331 dence and associativity rules and may be otherwise grouped using paren‐
332 theses.
333 A value is either a numeric constant or a variable reference yielding a
335 numeric value. Numbers may be integer or floating-point; the latter
336 are stored with limited precision (usually six significant digits).
337 Integer overflow does not signal an exception.
339 If an expression involves any floating-point value, the result will be
341 floating-point.
342 Division of integers produces an integer result via truncation. Modu‐
344 lus behaves as fmod(3) if either argument is floating-point.
345 An undefined variable (a variable reference yielding value ()) is
347 treated as zero within an arithmetic expression.
348 Variables having subscripted or constructed names may not be used in an
350 arithmetic expression. Variable names in an expression may not be
351 spelled using the characters which denote the arithmetic operators.
352 Pipes
354 The standard output of one fragment may be piped to the standard input
355 of another:
356 fragment1 | fragment2 .
358 Other file descriptors may be connected:
360 fragment1 |[fd1=fd2] fragment2 .
362 The form
364 fragment1 |[fd1] fragment2
366 is identical to
368 fragment2 |[fd1=0] fragment2 .
370 Command substitution
372 The backquote form creates a list from the standard output of a frag‐
373 ment:
374 `fragment .
376 Words are parsed from the standard output using the separators defined
378 by $ifs.
379 This variant backquote form binds $ifs to the given list of separators:
381 `` separators fragment .
383 Functions
385 Xs has two forms by which a function is defined:
386 fn name fragment
388 and
390 fn-name = fragment .
392 The former is normally used for top-level and nested definitions; the
394 latter must be used when binding a function for local use. Because the
395 latter is an assignment, the spaces around = are mandatory.
396 Lambdas
398 A lambda is an unnamed function. In xs, a lambda is written as a frag‐
399 ment in which the first element may be a lambda list (see below). A
400 lambda without a lambda list is a lambda with no arguments.
401 Lambda list
403 A lambda list binds names to function arguments. Its form is:
404 |name ...| .
406 Arguments are bound to names left-to-right. Excess arguments bind in a
408 list to the last name. Excess names are bound to ().
409 A lambda list may only appear as the first element of a fragment.
411 Truth values
413 The values 0, '' and () are all treated as true; everything else
414 (including 0.0) is false. A list of true values is true; a list con‐
415 taining an untrue value is false.
416 The keywords true and false are equivalent to result 0 and result 1,
418 respectively.
419 Return values
421 The value of evaluating a fragment is the return value of the last
422 function or executable evaluated before leaving the fragment.
423 A specific result may be returned by:
425 result list .
427 Logical operators
429 The following operators apply to truth values:
430 value1 && value2
432 True if both value1 and value2 are true.
433 value1 || value2
435 True if value1 is true or if value1 is false and value2
436 is true.
437 ! value
439 True if value is false.
440 The && and || operators evaluate their arguments from left to right,
442 stopping when the value of the expression is determined.
443 Relational operators
445 Numbers and strings may be compared using the relational operators:
446 value1 :lt value2
448 True if value1 is less than value2.
449 value1 :le value2
451 True if value1 is less than or equal to value2.
452 value1 :gt value2
454 True if value1 is greater than value2.
455 value1 :ge value2
457 True if value1 is greater than or equal to value2.
458 value1 :eq value2
460 True if value1 is equal to value2.
461 value1 :ne value2
463 True if value1 is not equal to value2.
464 If either argument is non-numeric, the arguments are compared according
466 to the current locale's collation order.
467 Input and output
469 Input may be redirected from a file to standard input:
470 <filename fragment
472 or
474 fragment <filename .
476 It is an error if the file does not exist or is not readable.
478 Output may be redirected from standard output to a file:
480 fragment >filename
482 or
484 >filename fragment .
486 The file is created if it does not exist. If the file already exists,
488 its contents are replaced. It is an error for the file to not be
489 writable.
490 Other file descriptors may be specified:
492 fragment >[ofd]filename
494 and
496 fragment <[ifd]filename .
498 A file descriptor may be duplicated using the form:
500 >[fd1=fd2] .
502 This causes output to fd1 to be written instead to fd2. Thus,
504 fragment >filename >[2=1]filename
506 causes both standard output and standard error to be written to the
508 same file.
509 Other redirection operators have their own semantics:
511 >>filename
513 Append to an existing file; the file is created if nonex‐
514 istent.
515 <>filename
517 Open a file for reading and writing (on standard input
518 unless otherwise specified).
519 <>>filename
521 Open a file for reading and appending (on standard input
522 unless otherwise specified).
523 ><filename
525 Truncate a file and open it for reading and writing (on
526 standard output unless otherwise specified).
527 >><filename
529 Open a file for reading and appending (on standard output
530 unless otherwise specified).
531 Files opened for reading must be readable. Files opened for writing or
533 appending must be writable.
534 An open file descriptor is closed using this form:
536 >[fd=] .
538 File descriptors must be integer constants.
540 Literal input
542 Multiple lines of input may be read from a script using a "here docu‐
543 ment":
544 fragment <<eof-marker
546 or
548 fragment <<'eof-marker' .
550 The eof-marker is a word which must appear on a line by itself immedi‐
552 ately following the final newline of textual data taken as input.
553 The first form (with the unquoted eof-marker) replaces variables within
555 the textual data. (Only simple variables; indirection, subscripts and
556 constructed names are not allowed.) A $ can be emitted literally by
557 writing $$. To emit the value of a variable followed immediately by a
558 literal word, write: $var^word . The caret (^) is taken literally
559 elsewhere in a here document.
560 The second form (with the quoted eof-marker) copies the textual data
562 without substitution of any kind.
563 Text may also provide the content of a readable file via a "here
565 string":
566 <<<'text' .
568 The text may span lines. No substitution is performed within a here
570 string.
571 A here string may also be created using a variable for the content,
573 like <<<$var .
574 Process substitution
576 Process substitution allows for the output of a command to be read from
577 a file descriptor or for data written to a file descriptor to be read
578 by a command, using the forms:
579 <{command+}
581 and
583 >{command+} .
585 The files created by process substitution are implemented using pipes,
587 which are not seekable.
588 Multiple commands may appear within the braces.
590 Note that the braces are an essential part of this syntax; these are
592 not >fragment and <fragment .
593 Local variables
595 Local variables exist only during execution of their binding form:
596 local (binding ...) fragment ,
598 where binding is either name = value or just name (and value is taken
600 as ()). Multiple bindings are separated by ;.
601 While bound by local, variables are accessible within the environment.
603 Lexical variables
605 Lexical variables are bound by the form:
606 let (binding ...) fragment ,
608 where binding is either name = value or just name (and value is taken
610 as ()). Multiple bindings are separated by ;.
611 A lexical variable is accessible only within fragment. Furthermore, a
613 lexical variable persists across executions of a function which is
614 defined within the let form. A lexical binding is stored as a closure
615 in the environment. The binding is not accessible as an environment
616 variable.
617 Conditionals
619 Xs has two main conditional forms:
620 if condition fragment else fragment ,
622 where condition is a boolean expression and the else branch is
624 optional, and
625 switch var cases ,
627 where cases is a list of word fragment, each representing the code to
629 be executed for a specific value of var, followed by a fragment to be
630 executed when none of the words match var.
631 Loops
633 Xs has these looping forms:
634 while condition fragment
636 until condition fragment
637 for vars-and-values fragment
638 forever fragment
639 The while form executes fragment while condition is true.
641 The until form executes fragment until condition is false.
643 The for form executes fragment with variables bound to consecutive val‐
645 ues in vars-and-values, which is a sequence of one or more var list
646 forms separated by ;. This continues until the longest list is
647 exhausted; shorter lists are implicitly padded with () to match the
648 length of the longest list.
649 The forever fragment form loops forever, like while true fragment.
651 Settors
653 A settor function is a variable like set-var.
654 When var is assigned, set-var is called as a function, passing the
656 value to be assigned. $0 is bound to the name of the variable being
657 assigned. The result of the settor function is used as the assign‐
658 ment's value.
659 A settor is never invoked on a lexical variable.
661 Exceptions
663 Exceptions in xs are used for non-lexical control transfer. An excep‐
664 tion is passed up the call chain to the most recently established
665 catcher. The catcher may handle the exception, retry the code which
666 caused the exception or throw the exception to the next catcher.
667 An exception is a list. The first word denotes the exception type, one
669 of:
670 eof Raised by the xs parser at end of input.
672 error The following words are the source (typically a descrip‐
674 tive name such as the name of the function which sig‐
675 nalled the error) and a message. xs provides a last-
676 resort catcher to print the message.
677 exit The next word is an optional numeric return code
679 (default: 0). This exception, when caught by xs, exits
680 the shell with the given return code.
681 retry When raised by a catcher, this causes the body of the
683 catch form to run again. Note that the catcher must have
684 done something to clear the cause of the exception; oth‐
685 erwise retry will cause an infinite loop.
686 The catch form executes its body in the context of a catcher:
688 catch catcher body .
690 The catcher and body are fragments.
692 Upward funargs
694 An "upward funarg" is a function returned from another function.
695 Because a returned function may be executed in a different lexical con‐
696 text, all free variables referenced by the function must be captured in
697 a let binding. In other words, an upward funarg must be let-bound.
698 A fragment or lambda may be returned instead of a closure only in the
700 case where the code references no free variables. This practice is
701 discouraged as it will cause your code to fail should a free variable
702 be added later.
703
705 These dynamic variables form a part of the programming interface to xs.
706 * The arguments passed to xs. Individual arguments may be refer‐
708 enced via subscripts or as $1, $2, $3, etc.
709 0 At the top level, this variable (i.e., $0) is the value of xs's
711 argv[0] or the name of a sourced file. Within an executing
712 function, the name of the function.
713 apid The ID of the most recently started background process.
715 history
717 The pathname of the file to which xs appends commands read by
718 the toplevel loop. This may be left undefined.
719 home The path to the current user's home directory. $home and $HOME
721 are aliased to each other.
722 ifs The input field separator, used by backquote (`) to split com‐
724 mand output into words. The initial value is the list
725 space tab newline .
726 max-eval-depth
728 Sets an upper bound on the size of the interpreter's evaluation
729 stack.
730 noexport
732 A list of dynamic variable names which xs will not export to the
733 environment.
734 path A list of directories to be searched for executable programs.
736 The current directory is denoted by the empty word (''). $path
737 and $PATH are aliased to each other, with appropriate syntactic
738 adjustments.
739 pid The process ID of the running xs.
741 prompt $prompt(1) is printed before reading a command. $prompt(2) is
743 printed before reading a continuation line. The default, ';'
744 '', facilitates copy-paste from a terminal session into a script
745 file. $prompt may contain ANSI terminal control characters and
746 sequences.
747 signals
749 A list of signals trapped by xs. For each signal name on $sig‐
750 nals, xs raises a correspondingly-named exception upon trapping
751 the signal. A signal's disposition is determined by an optional
752 prefix to its name:
753 - Ignore the signal, here and in child processes.
755 / Ignore the signal here, but take its default behavior in
757 child processes.
758 . (for sigint and sigwinch)
760 Perform normal processing (i.e., print an extra newline
761 upon receipt of sigint; note the new window size upon
762 receipt of sigwinch).
763 none Default behavior.
765 The initial value of $signals is
767 .sigint /sigquit /sigterm -sigxcpu .sigwinch -sigpwr
769 plus any signals ignored (/) when xs started. xs recognizes
771 that sigxcpu and sigpwr are used by its garbage collector and
772 intentionally ignores them to avoid disrupting the collector's
773 operation.
774 Xs maintains $SHLVL for interoperability with other shells.
776
778 These commands are built into xs, and execute within the xs process.
779 . [-einvx] file [args...]
781 Sources file. The options are a subset of those recognized by
782 xs; see Options.
783 access [-n name] [-1e] [-rwx] [-fdcblsp] path...
785 Tests paths for accessibility. Without the -1, -e and -n
786 options, access returns true for paths which are accessible as
787 specified. A printable error message (which evaluates as false;
788 see Truth values) is returned for paths which are not accessi‐
789 ble. The default test (no options) returns true if a path
790 exists, regardless of mode or type. These options determine the
791 test to apply to the paths:
792 -r Is the path readable?
794 -w Is the path writable?
795 -x Is the path executable?
796 -f Is the path a plain file?
797 -d Is the path a directory?
798 -c Is the path a character device?
799 -b Is the path a block device?
800 -l Is the path a symbolic link?
801 -s Is the path a socket?
802 -p Is the path a named pipe?
803 With the -n name option, the paths are applied to name, produc‐
805 ing a list of test results.
806 With -1, access returns the first path to satisfy the test. If
808 no path satisfies the test, return the empty list unless -e was
809 specified, in which case not having a satisfied test causes an
810 error to be raised.
811 alias name expansion...
813 Define a function with expansion as its body. The first word of
814 expansion is replaced with its whats value to prevent the recur‐
815 sion that would occur if name and the first word of expansion
816 are the same.
817 catch catcher body
819 Run body. If an exception is raised, run catcher. The excep‐
820 tion is passed as an argument to catcher.
821 cd [directory]
823 Set the working directory to directory. With no argument, this
824 is the same as cd $home.
825 dirs [-c]
827 Show the directory stack (see pushd and popd). With -c, clear
828 the directory stack.
829 echo [-n] [--] args...
831 Print args to standard output, separated by spaces. The output
832 ends with a newline unless suppressed by -n. Arguments follow‐
833 ing -- are taken literally.
834 escape lambda
836 Run lambda, a function of one argument. The argument names a
837 function (like fn-somename) which, when evaluated within lambda,
838 transfers control to just after the escape form. Arguments of
839 the escape function are returned as the value of the form.
840 eval list
842 Convert list to a word and pass it to the xs interpreter for
843 parsing and execution.
844 Lexical bindings are not available to eval. The following code
846 prints "dyn":
847 x = dyn
849 let (x = lex) {
850 eval 'echo $x'
851 }
852 exec cmd
854 Replace xs with cmd. If cmd has only redirections, then apply
855 the redirections to the current xs.
856 exit [status]
858 Cause xs to exit with the given status, or with zero if status
859 is not given.
860 false Identical to result 1.
862 for vars-and-values... fragment
864 See Loops.
865 forever fragment
867 See Loops.
868 fork command
870 Run command in a subshell.
871 history [#|-c|-d #|-n|-y]
873 Without arguments, show command history. # shows the most
874 recent # history entries. -c clears the history. -d # deletes
875 history entry #. -n and -y disable and enable history record‐
876 ing.
877 if condition fragment [else fragment]
879 See Conditionals.
880 jobs List background jobs.
882 limit [-h] [resource [value]]
884 Display or alter process resource limits. -h for hard limits.
885 Value is either unlimited or a number. Numbers representing
886 size allow the suffixes k (kilobyte), m (megabyte), and g (giga‐
887 byte). Numbers representing time allow the suffixes s (sec‐
888 onds), m (minutes), and h (hours) as well as durations like
889 hh:mm:ss and mm:ss.
890 map action list
892 Apply action individually to each element of list; collect the
893 results as map's result.
894 omap action list
896 Like map, but collect a list of the outputs of action.
897 popd Pop the directory stack to set the working directory, and print
899 the new stack. The command is ignored if the directory stack is
900 empty.
901 printf format args...
903 Print args on standard output according to format. Valid format
904 conversions are those of printf(3p), except that there must be a
905 one-to-correspondence between format specs (excluding %%) and
906 arguments: positional argument specs, variable width and preci‐
907 sion, and excess arguments are all disallowed. Escapes must be
908 unquoted in format.
909 pushd [dir]
911 Push dir's absolute path onto the directory stack, set the work‐
912 ing directory to dir and show the new stack. If dir is omitted
913 and the stack is at least two deep, then alternate between the
914 two top directories.
915 read Read from standard input and return a single word containing a
917 line of text (without the newline). Return () upon end-of-file.
918 result value...
920 Return values.
921 switch value [case action]... [default-action]
923 See Conditionals.
924 throw exception arg...
926 See Exceptions.
927 time command arg...
929 Execute command with args. Print consumed real, user and system
930 time to standard error.
931 true Identical to result 0.
933 umask [mask]
935 Set or show the umask.
936 until test body
938 See Loops.
939 unwind-protect body cleanup
941 Execute body; when it completes or raises an exception, run
942 cleanup.
943 var var...
945 Print definition of var(s).
946 vars [-vfs] [-epi]
948 Print definition of all variables which satisfy the given
949 options:
950 -v variables (not functions or settors). This is the default
952 if none of -v, -f or -s is given.
953 -f functions
954 -s settors
955 -e exported. This is the default if none of -e, -p or -i is
956 given.
957 -p private (not exported)
958 -i internal (predefined and builtin)
959 -a all of the above
960 wait [pid]
962 Wait for a child process denoted by its pid to exit. If no pid
963 is given, wait for any child process.
964 whats command...
966 Identify command(s) by pathname, primitive, or fragment.
967 while test body
969 See Loops.
970
972 The following functions implement specific parts of xs semantics; a
973 hook function can be rewritten to provide special behaviors. Hook
974 functions are normally called as a result of xs translating programs
975 into an internal form. See CANONICAL FORM.
976 %and command...
978 Execute command(s) from left to right, stopping at the command
979 that first yields a false value. The false value is returned by
980 %and.
981 %append fd file command
983 Run command with fd open in append mode on file.
984 %background command
986 Run command as a background process. If xs is an interactive
987 shell, print the background process ID.
988 %backquote separators command
990 Run command as a child process, splitting standard output into
991 words at any character in separators.
992 %close fd command
994 Run command with the closed file descriptor fd.
995 %cmp word1 word2
997 Compare word1 to word2 and return -1, 0 or 1 if word1 is respec‐
998 tively less than, equal to or greater than word2. If either
999 argument is non-numeric, then a lexicographic comparison is done
1000 based upon the locale's collation order.
1001 %count list
1003 Return the number of words in list.
1004 %create fd file command
1006 Run command with fd open for writing on file.
1007 %dup newfd oldfd command
1009 Run command with oldfd copied to newfd.
1010 %exit-on-false command
1012 Run command; exit xs if any part of command (outside of condi‐
1013 tional tests and arguments to logical operators) returns a false
1014 value.
1015 %flatten separator list
1017 Concatenate the words of list, interposing separator.
1018 %here fd word... command
1020 Run command with words passed as an input file on fd.
1021 %not command
1023 Run command and invert the boolean sense of its result.
1024 %one list
1026 Return list if it contains exactly one word; otherwise raise a
1027 "too many files in redirection" error.
1028 %open fd file command
1030 Run command with file open for reading on fd.
1031 %open-append fd file command
1033 Run command with file open for reading and appending on fd.
1034 %open-create fd file command
1036 Run command with file open for reading and writing on fd. If
1037 the file exists, truncate it.
1038 %open-write fd file command
1040 Run command with file open for reading and writing on fd.
1041 %openfile mode fd file command
1043 Run command with file open on fd with the given mode.
1044 %or command...
1046 Execute command(s) from left to right, stopping at the command
1047 that first yields a true value. The true value is returned by
1048 %or.
1049 %pathsearch program
1051 If program exists in a directory on $path, return the full path
1052 to program. Otherwise raise an error.
1053 %pipe command1 [outfd infd command2] ...
1055 Run commands with outfd of command1 connected via a pipe to infd
1056 of command2. Additional commands may be added to the pipeline.
1057 %readfrom var input command
1059 Run command with var bound to the name of a file containing the
1060 standard output produced by the command input.
1061 %seq command...
1063 Run commands in order, from left to right.
1064 %whats program...
1066 Return the pathname, primitive, or fragment of each program.
1067 %writeto var output command
1069 Run command with var bound to the name of a file containing the
1070 standard input to be consumed by the command output.
1071
1073 These functions also define xs behavior, but are less useful for cus‐
1074 tomization:
1075 %apids Return the process IDs of all background processes for which xs
1077 has not yet waited.
1078 %fsplit separators arg...
1080 Split each arg word at any separators character, producing a
1081 list. Repeated instances of separators in args create empty
1082 words ('') in the result.
1083 %is-interactive
1085 Return true if the innermost toploop is interactive.
1086 %is-login
1088 Return true if this is a login shell.
1089 %newfd Return a file descriptor that the shell believes is not other‐
1091 wise used.
1092 %run program argv0 args...
1094 Run program, which must be an absolute pathname, passing argv0
1095 as the program's name and args as its arguments.
1096 %split separators arg...
1098 Like %fsplit, but repeated instances of a separators character
1099 in args are coalesced.
1100 %var var...
1102 Return the definition of each var.
1103
1105 Primitives provide the underlying behaviors for many hooks and
1106 builtins, and may not be redefined.
1107 │
1108 Primitive │ Implements
1109 ──────────────────┼────────────────────────────────────────────────
1110 $&access │ access
1111 $&apids │ %apids
1112 $&background │ used by %background
1113 $&backquote │ used by %backquote
1114 $&batchloop │ %batch-loop
1115 $&catch │ catch
1116 $&cd │ used by cd
1117 $&close │ %close
1118 $&cmp │ %cmp
1119 $&collect │ invokes GC
1120 $&count │ %count
1121 $&dot │ .
1122 $&dup │ %dup
1123 $&echo │ echo
1124 $&exec │ exec
1125 $&exitonfalse │ %exit-on-false
1126 $&flatten │ %flatten
1127 $&forever │ forever
1128 $&fork │ fork
1129 $&fsplit │ %fsplit
1130 $&here │ %here
1131 $&home │ %home
1132 $&if │ if
1133 $&internals │ used by vars
1134 $&isinteractive │ %is-interactive
1135 $&islogin │ %is-login
1136 $&len │ count chars in word(s)
1137 $&limit │ limit
1138 $&newfd │ %newfd
1139 $&newpgrp │ newpgrp
1140 $&openfile │ %openfile
1141 $&parse │ %parse
1142 $&pipe │ %pipe
1143 $&primitives │ list xs primitives
1144 $&printf │ printf
1145 $&random │ random integer
1146 $&read │ %read
1147 $&readfrom │ %readfrom
1148 $&resetterminal │ used to keep readline(3) in sync with terminal
1149 $&result │ result
1150 $&run │ %run
1151 $&seq │ %seq
1152 $&sethistory │ set-history
1153 $&setmaxevaldepth │ set-max-eval-depth
1154 $&setnoexport │ set-noexport
1155 $&setsignals │ set-signals
1156 $&split │ %split
1157 $&throw │ throw
1158 $&time │ time
1159 $&umask │ umask
1160 $&var │ %var
1161 $&vars │ used by vars
1162 $&version │ version info
1163 $&wait │ wait
1164 $&whats │ %whats
1166 $&wid │ count character cells in word(s)
1167 $&writeto │ %writeto
1168
1170 A toploop repeatedly reads and executes a command and prints its
1171 result. Xs has two toploops, one of which is selected depending upon
1172 xs options.
1173 %batch-loop
1175 This is the toploop for a non-interactive shell and for the dot
1176 (.) and eval commands when their input is non-interactive.
1177 %batch-loop returns upon catching an exception.
1178 %interactive-loop
1180 This is the toploop for an interactive shell and for the dot (.)
1181 and eval commands when their input is interactive. %interac‐
1182 tive-loop returns upon catching an eof exception.
1183 The %interactive-loop has a hook function, %before-interactive-
1185 prompt; if defined, this is called — passing the return code of
1186 the prior command — after %prompt but before printing the ini‐
1187 tial prompt.
1188 Xs binds one of the following functions to fn-%dispatch for use by the
1190 toploop. The choice of function is determined by whether the shell is
1191 interactive and by the -n and -x options.
1192 %eval-noprint command
1194 %eval-print command
1195 %noeval-noprint command
1196 %noeval-print command
1197 These functions handle command input for the shell:
1199 %parse prompt1 prompt2
1201 Read input after printing prompt1 initially and prompt2 for con‐
1202 tinuation lines. Return a fragment suitable for execution.
1203 Raise an eof exception at end of input.
1204 %prompt Xs calls this hook immediately before %parse. A common use is
1206 to update the value of $prompt.
1207
1209 Xs rewrites surface syntax in terms of hook functions.
1210 Control flow
1212 ! command %not {command}
1213 command & %background {command}
1214 command1 ; command2 %seq {command1} {command2}
1215 command1 && command2 %and {command1} {command2}
1216 command1 || command2 %or {command1} {command2}
1217 fn name {|arg...| command} fn-^name = {|arg...| command}
1218 Input/output
1220 command < file %open 0 file {command}
1221 command > file %create 1 file {command}
1222 command >[n] file %create n file {command}
1223 command >> file %append 1 file {command}
1224 command <> file %open-write 0 file {command}
1225 command <>> file %open-append 0 file {command}
1226 command >< file %open-create 1 file {command}
1227 command >>< file %open-append 1 file {command}
1228 command >[n=] %close n {command}
1229 command >[m=n] %dup m n {command}
1230 command << tag input tag %here 0 input {command}
1231 command <<< word %here 0 word {command}
1232 command1 | command2 %pipe {command1} 1 0 {command2}
1233 command1 |[m=n] command2 %pipe {command1} m n {command2}
1234 command1 >{ command2 } %writeto var {command2} {command1 $var}
1235 command1 <{ command2 } %readfrom var {command2} {command1 $var}
1236 Expressions
1238 $#var <={%count %var}
1239 $^var <={%flatten ' ' $var}
1241 `{ command arg... } <={%backquote <={%flatten '' $ifs} {command
1242 arg...}}
1243 `` ifs { command arg... } <={%backquote <={%flatten '' ifs} {command
1244 arg...}}
1245 Relational operators
1247 a :lt b {~ {%cmp a b} -1}
1248 a :le b {~ {%cmp a b} -1 0}
1249 a :gt b {~ {%cmp a b} 1}
1250 a :ge b {~ {%cmp a b} 1 0}
1251 a :eq b {~ {%cmp a b} 0}
1252 a :ne b {~ {%cmp a b} -1 1}
1253
1255 Input editing is provided by readline(3) and configured by ~/.inputrc.
1256 The ~/.inputrc file may contain definitions specifically for xs, and
1257 not other readline(3)-aware programs, through use of the conditional
1258 construct $if xs.
1259
1261 These files are read and interpreted when xs starts:
1262 ~/.xsrc
1264 when xs is a login shell
1265 ~/.xsin
1267 when xs is an interactive shell
1268 When both ~/.xsrc and ~/.xsin are read, ~/.xsrc is read first.
1270
1272 Additional documentation is installed in prefix/share/doc/xs . Prefix
1273 is typically /usr or /usr/local.
1274
1276 The following forms are deprecated and should not be used for new xs
1277 code.
1278 \unnnn UTF-8 character having codepoint nnnn, for n in
1280 {0..9, a..f, A..F}
1281 \Unnnnnnnn UTF-8 character having codepoint nnnnnnnn, for n in
1282 {0..9, a..f, A..F}
1283 NOTICE: Deprecated features, syntax and behaviors are preserved only
1285 until the next major release of xs.
1286
1288 The shell does not support job control.
1289 The interpreter does not implement tail recursion.
1291 Xs reserves the octets \001 and \002 to annotate variables stored in
1293 the environment. This may present problems for interchange of vari‐
1294 ables with another program that stores these octets in the environment.
1295 Please report issues at <https://github.com/TieDyedDevil/XS>.
1297
1299 The git(1) source repository is at <https://github.com/TieDyed‐
1300 Devil/XS>.
1301
1303 Xs is packaged for Fedora. The xs 1.1 release first appeared in Fedora
1304 27.
1305
1307 Xs 1.1 and later is maintained by David B. Lamkins <david@lamkins.net>.
1308 Xs 1.0 (self-reporting as 0.1) was maintained by Frederic Koehler
1310 <fkfire@gmail.com>.
1311 Es to 0.9-beta was maintained by Soren Dayton <csday‐
1313 ton@cs.uchicago.edu>. Es up through 0.84 was maintained by Paul Haar
1314 <haahr@adobe.com> and Byron Rakitzis <byron@netapp.com>.
1315 The rc shell for Plan 9 was written at Bell Labs by Tom Duff. The Unix
1317 port was written by Byron Rakitizis and maintained by Toby Goodwin.
1318 See <http://tobold.org/article/rc>.
1319 Other contributors may be found in the CHANGES file and in the commit
1321 log.
1322
1324 Yes, and of course whitespace. Some things should be left unsaid.
1325 2018 - v1.2 XS(1)