20060303-partial

1 files changed, 635 insertions, 0 deletions

diff --git a/man/1/mash b/man/1/mash
new file mode 100644
index 00000000..ed305553
--- /dev/null
+++ b/man/1/mash
@@ -0,0 +1,635 @@
+.TH MASH 1
+.SH NAME
+mash \- programmable shell
+.SH SYNOPSIS
+.B mash
+[
+.B -denx
+][
+.BI -c command
+] [
+.I file
+[
+.I arg ...
+]]
+.SH DESCRIPTION
+.I Mash
+is an older alternative to the original Inferno shell
+(now
+.IR tiny (1)).
+.I Mash
+is a programmable shell that also allows the definition of simple dependency
+rules, resembling those of Unix
+.IR make .
+It executes commands read from standard input 
+or a file or, with the
+.B -c
+flag, from
+.IR mash 's
+argument list. Its syntax and 
+semantics are similar to that of Plan 9's
+.IR rc .
+
+.SS Invocation
+If
+.I mash
+is started with no arguments it reads commands from standard 
+input. Otherwise its first non-flag argument is the name of a file from 
+which to read commands (but see
+.B -c
+below). Subsequent arguments 
+become the initial value of
+.BR $args .
+Mash accepts the following 
+command-line flags.
+.PD 0
+.TF "-c string"
+.TP
+.BI -c " string"
+Commands are read from string.
+.TP
+.B -d
+Dump parsed commands before execution.
+.TP
+.B -e
+Fail if a top level command does. 
+.TP
+.B -n 
+Parse but do not execute. 
+.TP
+.B -x 
+Print each simple command before executing it.
+.PD
+.PP
+If invoked without arguments
+.I mash
+first runs the commands found in
+.BR /lib/mashinit .
+
+.SS "Command Lines"
+Each command is terminated with an ampersand or a semicolon (& or ;). 
+When reading from
+.B /dev/cons
+a newline 
+not escaped with a backslash (\\) is treated as a semicolon.
+.I Mash
+does not 
+wait for a command followed by
+.B &
+to finish executing before starting the 
+following command. 
+.PP
+A number-sign (#) and any following characters up to (but not including) the next newline are 
+ignored, except in quotation marks. 
+
+.SS "Simple Commands"
+A simple command is a sequence of words interspersed with I/O 
+redirections. If the first word is the name of a
+.I mash
+function or of one of 
+.IR mash 's
+built-in commands, it is executed by
+.IR mash .
+Otherwise, if the name 
+starts with a slash
+.RB ( / ),
+it must be the path name of a Dis
+file to be loaded 
+and executed. Names containing no initial slash are searched for in the 
+current directory and then in
+.BR /dis .
+The
+.B .dis
+extension need not be 
+supplied. 
+.PP
+The keywords are
+.EX
+	case else fn for hd if in len rescue tl while 
+.EE
+
+.SS Words and Variables
+A number of constructions may be used where
+.IR mash 's
+syntax requires a 
+word to appear. In many cases a construction's value will be a list of 
+strings rather than a single string. 
+.PP
+The simplest kind of word is the unquoted word: a sequence of one or 
+more characters none of which is a blank, tab, newline, or any of the 
+following:
+.EX
+	# : ; ! ~ @ & | ^ $ = " ` ' { } ( ) < > 
+.EE
+An unquoted word that contains any of the characters
+.BR * ,\  ?
+or
+.B [
+is a pattern 
+for matching against file names. The character
+.B *
+matches any sequence of 
+characters,
+.B ?
+matches any single character, and
+.B [
+.I class
+.B ]
+matches any 
+character in the class. The class may also contain pairs of characters 
+separated by
+.BR \- ,
+standing for all characters lexically between the two. The 
+character
+.B /
+must appear explicitly in a pattern. A pattern is replaced by a 
+list of words, one for each path name matched, except that a pattern 
+matching no names is not replaced by the empty list, but rather stands for 
+itself. Pattern matching is done after all other operations. Thus,
+.EX
+	x=/tmp; echo $x^/*.c; 
+.EE
+matches
+.BR /tmp/*.c ,
+rather than matching
+.B /*.c
+and then prefixing
+.BR /tmp . 
+.PP
+A quoted word is a sequence of characters surrounded by single quotes 
+.RB ( ' ).
+A single quote is escaped with a backslash. 
+.PP
+Each of the following is a word.
+.PD 0
+.HP
+.BI $ identifier 
+.br
+The identifier after the
+.B $
+is the name of a variable whose value is 
+substituted. Variable values are lists of strings. It is an error if the 
+named variable has never been assigned a value.
+.HP
+.BI $ number 
+.br
+See the description of rules for the 
+.IR mash-make (1)
+builtin.
+.HP
+.B $"\c
+.I identifier
+.br
+The value is a single string containing the components of the named 
+variable separated by spaces.
+.HP
+.BI `{ commands }
+.br
+.I mash
+executes the commands and reads the standard output, splitting 
+it into a list of words, using the whitespace characters (space, tab,
+newline and carriage return) as separators.
+.HP
+.B
+"{\c
+.IB commands }
+.br
+.I mash
+executes the commands and reads the standard output, splitting 
+it into a list of words, using the whitespace characters (space, tab,
+newline and carriage return) as separators.
+.HP
+.BI <{ commands }
+.HP
+.BI >{ commands }
+.br
+The commands are executed asynchronously with their standard 
+output or standard input connected to a pipe. The value of the word 
+is the name of a file referring to the other end of the pipe. This 
+allows the construction of non-linear pipelines. For example, the 
+following runs two commands
+.B old
+and
+.B new
+and uses
+.B cmp
+to compare their outputs
+.EX
+	cmp <{old} <{new}; 
+.EE
+.TP
+.BI ( expr )
+.I mash
+evaluates
+.I expr
+as an expression. The value is a (possibly null) list of words.
+Expressions are described in detail below.
+.HP
+.IB word ^ word
+.br
+The
+.B ^
+operator concatenates its two operands. If either operand is a 
+singleton, the concatenation is distributive. Otherwise the lists are 
+concatenated pairwise.
+
+.PD
+.SS Free Carets
+In most circumstances,
+.I mash
+will insert the
+.B ^
+operator automatically 
+between words that are not separated by white space. Whenever one of
+.B $ 
+.BR ' or
+.B `
+(dollar, single quote or back quote)
+follows a quoted or unquoted word or an unquoted word follows a 
+quoted word with no intervening blanks or tabs, a
+.B ^
+is inserted between 
+the two. If an unquoted word immediately follows a
+.B $
+and contains a 
+character other than an alphanumeric, or underscore, a
+.B ^
+is inserted before 
+the first such character. Thus 
+.IP
+.B limbo -$flags $stem.b
+.LP
+is equivalent to 
+.IP
+.B limbo -^$flags $stem^.b 
+
+.SS I/O Redirections
+The sequence
+.BI > file
+redirects the standard output file (file descriptor 1, 
+normally
+.BR /dev/cons )
+to the named
+.IR file ;
+.BI >> file
+appends standard 
+output to the file. The standard input file (file descriptor 0, also normally 
+.BR /dev/cons )
+may be redirected from a file by the sequence
+.BR <file .
+The 
+sequence
+.B <>file
+opens the file for read/write and associates both file 
+descriptor 0 and 1 with it.
+
+.SH Compound Commands
+A pair of commands separated by a pipe operator
+.RB ( | )
+is a command. The 
+standard output of the left command is sent through a pipe to the 
+standard input of the right command. 
+.PP
+Each of the following is a command.
+.PD 0
+.HP
+.B if (
+.I expr
+.B )
+.I command1
+.HP
+.B if (
+.I expr
+.B )
+.I command1
+.B else
+.I command2
+.br
+The
+.I expr
+ is evaluated and if the result is not null, then 
+.I command1
+is executed. In the second form
+.I command2
+is executed if 
+the result is null.
+.HP
+.B for (
+.I name
+.B in
+.I list
+.BI ) command
+.br
+The
+.I command
+is executed once for each word in
+.I list
+with that 
+word assigned to
+.IR name .
+.HP
+.B while (
+.I expr
+.B )
+.I command
+.br
+The
+.I expr
+is evaluated repeatedly until its value is null. Each time it 
+evaluates to non-null, the command is executed.
+.HP
+.B case
+.I expr
+.B {
+.I pattern-list
+.B =>
+.I command ...
+.B }
+.br
+.HP
+.B case
+.I expr-list
+.B {
+.I pattern
+.B =>
+.I command ...
+.B }
+.br
+In the first form of the command the
+.I expr
+is matched against a series of lists of regular expressions (See
+.IR regex (2)).
+The command associated with the matching expression is executed.
+In the second form the
+.I command
+associated with the first pattern to match one of the words in
+.I expr-list
+is executed. An
+.I expr-list
+will never match a
+.IR pattern-list .
+.HP
+.BI { commands }
+.HP
+.BI @{ commands }
+.br
+Braces serve to alter the grouping of commands implied by operator 
+priorities. The body is a sequence of commands separated by
+.B &
+or
+.BR ; . 
+The second form is executed with a new scope. Either form can be 
+followed by redirections.
+.HP
+.BI fn name { list }
+.HP
+.BI fn name
+.br
+The first form defines a function with the given
+.IR name .
+Subsequently, 
+whenever a command whose first word is
+.I name
+is encountered, the 
+current value of the remainder of the command's word list will be 
+assigned to the local variable
+.BR args ,
+in a new scope, and
+.I mash
+will  execute the list. The second form removes
+.IR name 's
+function definition.
+.HP
+.IB name = list
+.HP
+.IB name := list
+.br
+The first form is an assignment to a variable. If the name is currently 
+defined as a local variable its value will be updated. Otherwise a 
+global variable with the given name will be defined or updated. The 
+second form is an explicit definition or update of a local variable.
+.HP
+.IB list : list
+.HP
+.IB list : list { commands }
+.HP
+.IB word :~ word { commands }
+.br
+These forms define dependencies and rules for the
+.I make
+loadable 
+builtin. The first form defines a simple dependency, the second a 
+dependency with an explicit rule. The third form defines an implicit 
+rule where the left-hand word is a file pattern, the right-hand word is 
+the prerequisite. The right-hand word and the commands can 
+contain references to the characters matched by the
+.B *
+meta-character 
+in the pattern
+.RB ( $1
+evaluates to the characters matched by the first
+.BR * , 
+.B $2
+the second and so on;
+.B $0
+is the entire match). 
+.PD
+
+.SS Expressions
+Expressions evaluate to possibly null lists of strings. A word is an 
+expression. An expression may take one of the following forms
+.PD 0
+.HP
+.BI ( " expr " )
+.br
+Parentheses are used for grouping.
+.HP
+.BI hd " expr"
+.HP
+.BI tl " expr"
+.HP
+.BI len " expr"
+.HP
+.BI ! " expr"
+.br
+.I hd
+is the first element of a list,
+.I tl
+the remainder.
+.I len
+is the length of 
+a list. Both evaluate to the null list if their operand is a null list.
+.B !
+is the not operator and evaluates to true for a null list or to a null list 
+otherwise.
+.HP
+.IB expr " ^ " expr
+.HP
+.IB expr " :: " expr
+.HP
+.IB expr " == " expr
+.HP
+.IB expr " != " expr
+.HP
+.IB expr " ~ " expr
+.br
+.B ^
+is concatenation (as defined above),
+.B ::
+is list concatenation,
+.B ==
+and 
+.B !=
+are the equality operators evaluating to true or the null list, 
+depending on the equality or inequality of the two operands.
+.B ~
+is the match operator, true if a singleton string matches one of a list of 
+regular expressions, or one of a list of strings matches a regular 
+expression. (If neither operand is a singleton it evaluates to the null 
+list.)
+.B ^
+has the highest precedence, followed by
+.B ::
+followed by the 
+other three. All associate to the left except
+.BR :: .
+
+.SS Built-in Commands
+
+.I Mash
+supports loadable modules of builtins. The
+.I Mashbuiltin
+module definition and description is in
+.BR mash.m .
+One such module,
+.IR builtins ,
+is loaded before
+.I mash
+begins parsing. This module defines the following commands
+.PD 0
+.HP
+.B env
+.br
+Print global and local variables. Global variables are displayed using a
+.IB name = value
+format, and local variables using a
+.IB name := value
+format.
+.HP
+.B eval
+.br
+Concatenate arguments and use as mash input.
+.HP
+.B exit
+.br
+Cause
+.I mash
+to raise an
+.B "exit"
+exception.
+.HP
+.B load
+.I file
+.br
+Load a builtin module. The
+.I file
+must be a module with type
+.BR Mashbuiltin .
+The argument
+.I file
+is assumed to contain a path to the loadable module. If no such module
+is found then the string
+.B /dis/lib/mash/
+is prepended to
+.I file
+and the load is retried.
+.HP
+.B prompt
+.HP
+.BI prompt text
+.HP
+.BI prompt "text contin"
+.br
+When called with no arguments causes the current value of the
+.I mash
+prompt to be printed to standard output. The default value is
+.BR mash% .
+The second form sets a new prompt. The final form sets a new prompt
+and additionally a continuation string. Initially the continuation
+string is set to a single tab character.
+.I Mash
+uses the continuation string in place of the prompt string to indicate that
+the preceding line has been continued by escaping with a final backslash
+.RB ( \e )
+character.
+.HP
+.BI quote args...
+.br
+Print arguments quoted as input for
+.IR mash . 
+.HP
+.BI "run -" [ denx "] file [arg...]"
+.br
+Interpret a file as input to
+.IR mash .
+.HP
+.BI time "cmd [arg...]"
+.br
+Time the execution of a command. The total execution time is reported
+in seconds and on standard error when the command completes.
+.HP
+.BI whatis name
+.br
+Print variable, function or builtin. The object given by
+.I name
+is described on standard output in a format that reflects its type.
+.PP
+The
+.I make
+loadable builtin provides `make` functionality.
+The
+.I tk
+loadable builtin provides control over some of the visual elements of a
+.I mash
+window.
+
+.SS Adding Builtins
+New builtins can be added to
+.I mash
+by creating a
+.I Dis
+module that can be loaded with a
+.B Mashbuiltin
+module interface (defined in mash.m).
+The new module is loaded with the builtin
+.B load
+command which calls its
+.B mashinit
+function to initialise it with an argument containing the
+.B load
+command line. The function should use this call to register the set of builtins
+that the module will provide using the
+.B Env.defbuiltin
+function. Thereafter, each time one of the registered builtins is invoked
+the module's
+.B mashcmd
+function is called passing as an argument a list containing the invoked
+builtin name and its arguments. See the examples in
+.BR mash/builtins.b ,
+.BR mash/make.b ", and"
+.BR mash/tk.b .
+.SH FILES
+.B /lib/mashinit
+.br
+.B /dis/lib/mash
+.SH SOURCE
+.B /appl/cmd/mash 
+.SH SEE ALSO
+.IR mash-tk (1),
+.IR mash-make (1),
+.IR regex (2)
+.PP
+Tom Duff,
+``Rc  \- The Plan 9 Shell'', in the
+.I "Plan 9 Programmer's Manual", Second Edition,
+Volume 2.