SH-ALPHABET(1) SH-ALPHABET(1)
NAME
alphabet, typeset, declare, import, type, define,
autodeclare, autoconvert, -, rewrite, modules, types, usage,
info, clear - typed shell interface
SYNOPSIS
load alphabet
type qname...
declare name [ usage ]
undeclare name...
define name expr
import qname...
typeset qname
autoconvert srctype dsttype expr
autodeclare
- {expression}
${rewrite {expression} [ dsttype ] }
${modules}
${types typeset }
${usage qname }
info
clear
DESCRIPTION
Alphabet is a loadable sh(1) module providing an interface
to a simple, experimental, typed shell. It initially pro-
vides a small set of basic types, which can be added to by
loading new typesets. Types are atomic; alphabet provides no
support for higher-order types. The root typeset, named /,
consists of the following kinds of value:
string A simple string literal, represented by itself, or
quoted according to the usual shell quoting rules.
cmd A shell command or uninterpreted alphabet expres-
sion, represented by the syntax "{block}.
fd A file open for reading.
wfd A file open for reading and writing.
status The status of a completed command.
Each typeset implements a set of types, and has an associ-
ated set of modules. Initially, types may only be referred
to by their qualified names, consisting of the name of the
type prefixed with the name of its typeset; for instance
/string for the string type, or /grid/data for a type named
data in the typeset /grid. An unqualified name is the
Page 1 Plan 9 (printed 12/22/24)
SH-ALPHABET(1) SH-ALPHABET(1)
qualified name without the typeset prefix; for instance
string or data.
To make a type available as its unqualified name, use the
type command, which imports the type named by the qualified
name 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.
Declare declares the module name with type usage. If name is
a qualified name, the module must exist in the specified
typeset and be compatible with the specified usage. If
usage is not given, the module itself will be loaded and
queried to find it out. If name is not qualified, the dec-
laration is virtual: the module cannot actually be used, but
is available for typechecking and expression rewriting.
Declare is a no-op if the module has already been declared
with a compatible usage, otherwise an error is raised. The
syntax of usage is similar to the usage messages printed by
normal shell commands, and defines the argument types
expected by a module. For example:
declare /foo/bar '[-a] [-x string] fd string [string...] -> fd'
The above declares the module bar from typeset /foo, which
takes two possible options (one of which requires a single
associated argument of type string), two mandatory argu-
ments, of type fd and string respectively, and any number of
additional arguments of type string. The module returns a
value of type fd.
When first loaded, alphabet is lax about declaration
requirements: if a module is referred to by its qualified
name, and is not currently declared, the module will auto-
matically be declared and used as appropriate (as long as
the module actually exists). Use autodeclare to change this
behaviour. Autodeclare 0 turns off all automatic declara-
tion: all modules used in an expression must have previously
been declared; autodeclare 1 reverts to the original
behaviour.
Once a module is declared, it may be referred to by its
qualified name. 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:
declare /read 'string -> fd'
import /read
This would declare a module named read from the root typeset
Page 2 Plan 9 (printed 12/22/24)
SH-ALPHABET(1) SH-ALPHABET(1)
(checking that it accepts a single string argument and
returns a file), and make it available under the name read.
Undeclare removes the previously declared name. Note that an
imported module has two names: its qualified name and its
unqualified name.
Typeset loads the new typeset qname. Typesets are hierarchi-
cal 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.
Autoconvert specifies an automatic conversion between
srctype and dsttype, i.e. whereever a module expects an
argument of type dsttype, and the argument is actually of
type srctype, the module block (see below for definition)
expr (which must be compatible with type srctype->dsttype),
will be invoked to convert between the two. Several conver-
sions 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, expr
may simply be the name of a module, in which case the
expression will be rewritten as its identity module block:
{(srctype); expr}.
The - command evaluates the alphabet expression, of the
form:
{command arg...}
Usually, command is the name of a previously declared mod-
ule, which must also have been imported if it is not a qual-
ified 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 command is invoked. The result of the outer-
most expression must be convertible to the type /status; the
shell status of the - command will reflect this when the
command has completed.
As a convenience, alphabet provides a pipe-like syntax. It
will rewrite any expression of the form m1 m1args|m2 m2args
as m2 {m1 m1args}m2args. This occurs before any auto-
conversions have been applied.
Command may also be a module block, of the form:
{(argtype...); command arg...}
The argtype values given in the brackets specify the types
Page 3 Plan 9 (printed 12/22/24)
SH-ALPHABET(1) SH-ALPHABET(1)
of the arguments expected by the module block; these can be
referred to in the arguments to command (and subexpressions
thereof) with values of the form $1, $2, etc. For instance,
{(/string); echo $1} hello}
is exactly equivalent to:
{echo hello}
In a module block with no arguments, the argument declara-
tion section may be omitted.
Define defines a new module in terms of previously declared
modules. Name (which must be an unqualified name) gives the
name of the module to define, and expr is a module block
giving the expression to evaluate when 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 expr. All modules used in the evaluation of expr are
evaluated when the definition takes place, so evaluation of
name is unaffected if any modules it uses are later unde-
clared.
To show the complete form of an expression, after pipe
transformations and auto-conversions have been applied, and
module definitions expanded, use ${rewrite}, which returns
the expression's canonical form without actually executing
it. If dsttype is given, auto-conversions will be applied
to try to convert the result of expression to dsttype.
Rewrite raises an error if it finds any declarations incom-
patible with expression or if the final type cannot be con-
verted successfully.
Alphabet also provides some shell operations that give
information on its current state: ${modules} yields a list
of all the currently declared module names (including
entries for both qualified and unqualified names); ${types}
yields a list of all currently available types (giving only
the types in typeset if specified); and ${usage} provides
usage information on module qname, which need not be
declared. Additionally, info searches the module directo-
ries on all currently loaded typesets, and prints usage
information for everything it can find there, along with
information on all currently installed auto-conversions.
Finally, clear clears all existing declarations and defini-
tions, and starts again with a clean slate.
EXAMPLE
load alphabet
type /string
Page 4 Plan 9 (printed 12/22/24)
SH-ALPHABET(1) SH-ALPHABET(1)
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}
SOURCE
/appl/alphabet/*.b
/appl/alphabet/*/*.b
BUGS
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 diag-
nostic when this occurs.
SEE ALSO
sh(1), alphabet(2), alphabet-main(1), alphabet-fs(1),
alphabet-grid(1)
Page 5 Plan 9 (printed 12/22/24)