1 files changed, 417 insertions, 0 deletions
diff --git a/man/1/sh-alphabet b/man/1/sh-alphabet
new file mode 100644
index 00000000..fd73e20f
--- /dev/null
+++ b/man/1/sh-alphabet
@@ -0,0 +1,417 @@
+.TH SH-ALPHABET 1
+.SH NAME
+alphabet, typeset, declare, import, type, define, autodeclare,
+autoconvert, -, rewrite, modules, types, usage, info, clear \- typed shell interface
+.SH SYNOPSIS
+.B load alphabet
+
+.B type
+.IR qname ...
+.br
+.B declare
+.I name
+[
+.I usage
+]
+.br
+.B undeclare
+.IR name ...
+.br
+.B define
+.I name
+.I expr
+.br
+.B import
+.IR qname ...
+.br
+.B typeset
+.I qname
+.br
+.B autoconvert
+.I srctype dsttype expr
+.br
+.B autodeclare
+.BR "" 0 | 1
+.br
+.B -
+.BI { expression }
+.br
+.B ${rewrite {\fIexpression\fP}
+[
+.I dsttype
+]
+.B }
+.br
+.B ${modules}
+.br
+.B ${types
+.I typeset
+.B }
+.br
+.B ${usage
+.I qname
+.B }
+.br
+.B info
+.br
+.B clear
+.SH DESCRIPTION
+.I Alphabet
+is a loadable
+.IR sh (1)
+module providing an interface to a simple, experimental, typed shell.
+It initially provides a small set of basic types, which can be added
+to by loading new
+.IR typeset s.
+Types are atomic;
+.I alphabet
+provides no support for higher-order
+types.
+The
+.IR "root typeset" ,
+named
+.BR / ,
+consists of the following kinds of value:
+.TP 10
+.B string
+A simple string literal, represented by itself,
+or quoted according to the usual shell quoting rules.
+.TP
+.B cmd
+A shell command or uninterpreted
+.I alphabet
+expression, represented by the syntax \f5"{\fIblock\f5}\fR.
+.TP
+.B fd
+A file open for reading.
+.TP
+.B wfd
+A file open for reading and writing.
+.TP
+.B status
+The status of a completed command.
+.PP
+Each typeset implements a set of
+types, and has an associated set of
+.IR module s.
+Initially, types may only be referred to by their
+.IR "qualified name" s,
+consisting of the name of the type prefixed with
+the name of its typeset; for instance
+.B /string
+for the string type,
+or
+.B /grid/data
+for a type named
+.B data
+in the typeset
+.BR /grid .
+An
+.I "unqualified name"
+is the qualified name without the typeset prefix;
+for instance
+.B string
+or
+.BR data .
+.PP
+To make a type available as its unqualified name,
+use the
+.B type
+command, which imports the type named
+by the qualified name
+.I qname
+from its parent typeset.
+This is a no-op if the type has previously been imported
+from the same typeset; an error is raised if the type
+has previously been imported from a different typeset.
+.PP
+.B Declare
+declares the module
+.IR name
+with type
+.IR usage .
+If
+.I name
+is a qualified name, the module must exist in the
+specified typeset and be compatible with the specified usage.
+If
+.I usage
+is not given, the module itself will be loaded and queried
+to find it out.
+If
+.I name
+is not qualified, the declaration is
+.IR virtual :
+the module cannot actually be used, but is available
+for typechecking and expression rewriting.
+.B Declare
+is a no-op if the module has already been declared
+with a compatible usage, otherwise an error is raised.
+The syntax of
+.I usage
+is similar to the usage messages printed by normal
+shell commands, and defines the argument types expected
+by a module. For example:
+.IP
+.EX
+declare /foo/bar '[-a] [-x string] fd string [string...] -> fd'
+.EE
+.PP
+The above declares the module
+.B bar
+from typeset
+.BR /foo ,
+which takes
+two possible options (one of which requires a single
+associated argument of type
+.BR string ),
+two mandatory arguments,
+of type
+.B fd
+and
+.B string
+respectively,
+and any number of additional arguments of
+type
+.BR string .
+The module returns a value of type
+.BR fd .
+.PP
+When first loaded,
+.I alphabet
+is lax about declaration requirements:
+if a module is referred to by its qualified name,
+and is not currently declared, the module will automatically
+be declared and used as appropriate (as long as the module
+actually exists).
+Use
+.B autodeclare
+to change this behaviour.
+.B "Autodeclare 0"
+turns off all automatic declaration: all modules used in an
+expression must have previously been declared;
+.B "autodeclare 1"
+reverts to the original behaviour.
+.PP
+Once a module is declared, it may be referred to
+by its qualified name.
+.B Import
+makes the module available under its unqualified name.
+It is an error if a module of the same name has
+already been imported from a different typeset.
+For instance:
+.IP
+.EX
+declare /read 'string -> fd'
+import /read
+.EE
+.PP
+This would declare a module named
+.B read
+from the root typeset (checking that it
+accepts a single string argument and returns a file),
+and make it available under the name
+.BR read .
+.PP
+.B Undeclare
+removes the previously declared
+.IR name .
+Note that an imported module has two names:
+its qualified name and its unqualified name.
+.PP
+.B Typeset
+loads the new typeset
+.IR qname .
+Typesets are hierarchical in the same
+way that types and modules are: a typeset adds some
+types to its parent typeset, and has an associated set of
+modules that provide transformations between those types
+and between those of its parent.
+.PP
+.B Autoconvert
+specifies an automatic conversion between
+.I srctype
+and
+.IR dsttype ,
+i.e. whereever a module expects an argument
+of type
+.IR dsttype ,
+and the argument is actually of type
+.IR srctype ,
+the module block (see below for definition)
+.I expr
+(which must be compatible with type
+.IB srctype -> dsttype\fR),
+will be invoked to convert between the two.
+Several conversions will be applied
+atop one another if necessary.
+It is an error if adding the auto-conversion
+creates an ambiguous conversion path
+between two types.
+As a convenience,
+.I expr
+may simply be the name of a module,
+in which case the expression will be rewritten as
+its identity module block: \f5{(\fIsrctype\fP); \fIexpr\fP}\fR.
+.PP
+The
+.B -
+command evaluates the
+.I alphabet
+.IR expression ,
+of the form:
+.IP
+.EX
+{\fIcommand arg\fR...\f5}
+.EE
+.PP
+Usually,
+.I command
+is the name of a previously declared module,
+which must also have been imported if it is not a qualified name.
+The arguments must conform to those expected by
+the module. Each argument is either a literal string or shell-command,
+as described earlier, or a subexpression of the same form as above.
+All subexpressions are evaluated fully before
+.I command
+is invoked.
+The result of the outermost expression must be convertible to the type
+.BR /status ;
+the shell status of the
+.B -
+command will reflect this when the command has completed.
+.PP
+As a convenience,
+.I alphabet
+provides a pipe-like syntax. It will rewrite any expression of the
+form \fIm1 m1args\f5|\fIm2 m2args\fR
+as \fIm2 \f5{\fIm1 m1args\f5}\fIm2args\fR.
+This occurs before any auto-conversions have been applied.
+.PP
+.I Command
+may also be a
+.IR "module block" ,
+of the form:
+.IP
+.EX
+{(\fIargtype\fR...\f5); \fIcommand arg\fR...\f5}
+.EE
+.PP
+The
+.I argtype
+values given in the brackets
+specify the types of the arguments expected by the module block;
+these can be referred to in the arguments to
+.I command
+(and subexpressions thereof) with values of the form
+.BR $1 ,
+.BR $2 ,
+etc.
+For instance,
+.IP
+.EX
+{(/string); echo $1} hello}
+.EE
+.PP
+is exactly equivalent to:
+.IP
+.EX
+{echo hello}
+.EE
+.PP
+In a module block with no arguments, the argument declaration
+section may be omitted.
+.PP
+.B Define
+defines a new module in terms of previously declared
+modules.
+.I Name
+(which must be an unqualified name)
+gives the name of the
+module to define, and
+.I expr
+is a module block giving the expression to evaluate when
+.I name
+is used. The usage of the module is taken from the types declared
+in the module block; its return type is inferred from the return type
+of
+.IR expr .
+All modules used in the evaluation of
+.I expr
+are evaluated when the definition takes place, so evaluation of
+.I name
+is unaffected if any modules it uses are later undeclared.
+.PP
+To show the complete form of an expression, after pipe
+transformations and auto-conversions have been applied, and
+module definitions expanded, use
+.BR ${rewrite} ,
+which returns the expression's canonical form
+without actually executing it.
+If
+.I dsttype
+is given, auto-conversions will be applied to try to
+convert the result of
+.I expression
+to
+.IR dsttype .
+.B Rewrite
+raises an error if it finds any declarations incompatible with
+.IR expression
+or if the final type cannot be converted successfully.
+.PP
+.I Alphabet
+also provides some shell operations that give information
+on its current state:
+.B ${modules}
+yields a list of all the currently declared module names
+(including entries for both qualified and unqualified names);
+.B ${types}
+yields a list of all currently available types
+(giving only the types in
+.I typeset
+if specified);
+and
+.B ${usage}
+provides usage information on module
+.IR qname ,
+which need not be declared.
+Additionally,
+.B info
+searches the module directories on all currently loaded typesets,
+and prints usage information for everything it can find there,
+along with information on all currently installed auto-conversions.
+.PP
+Finally,
+.B clear
+clears all existing declarations and definitions, and starts again
+with a clean slate.
+.SH EXAMPLE
+.EX
+load alphabet
+type /string
+type /fd
+type /status
+import /cat /filter
+autoconvert string fd /read
+autoconvert fd status {(fd); /print $1 1}
+define wc {(fd); /filter $1 "{wc}}
+- {cat /lib/polyhedra /dis/sh.dis | wc}
+echo ${rewrite {cat /lib/polyhedra /dis/sh.dis | wc} status}
+.EE
+.SH SOURCE
+.B /appl/alphabet/*.b
+.br
+.B /appl/alphabet/*/*.b
+.SH BUGS
+.I Alphabet
+expressions involving external typesets and file descriptors cannot have
+their I/O
+redirected at the shell level. Unfortunately it is not possible
+to provide a diagnostic when this occurs.
+.SH SEE ALSO
+.IR sh (1),
+.IR alphabet (2),
+.IR alphabet-main (1),
+.IR alphabet-fs (1),
+.IR alphabet-grid (1)