.\" Copyright (c) Stichting Mathematisch Centrum, Amsterdam, 1984.
.Du START
.sp 1
.in 0
.ce 99
DESCRIPTION OF B

Lambert Meertens
Steven Pemberton

CWI
Amsterdam

April 1984
.ce 0
.Co
.ds Sn Contents
.bp
.in 15
.nf
.ps 8
.vs 10
CONTENTS

0.\0INTRODUCTION
1.\0VALUES IN B
2.\0SYNTAX DESCRIPTION METHOD
3.\0REPRESENTATIONS
4.\0UNITS
        4.1.\0HOW-TO-UNITS
        4.2.\0YIELD-UNITS
        4.3.\0TEST-UNITS
        4.4.\0REFINEMENTS
        4.5.\0COMMAND-SUITES
5.\0COMMANDS
        5.1.\0\0SIMPLE-COMMANDS
                5.1.1.\0\0CHECK-COMMANDS
                5.1.2.\0\0WRITE-COMMANDS
                5.1.3.\0\0READ-COMMANDS
                5.1.4.\0\0PUT-COMMANDS
                5.1.5.\0\0DRAW-COMMANDS
                5.1.6.\0\0CHOOSE-COMMANDS
                5.1.7.\0\0SET-RANDOM-COMMANDS
                5.1.8.\0\0REMOVE-COMMANDS
                5.1.9.\0\0INSERT-COMMANDS
                5.1.10.\0DELETE-COMMANDS
                5.1.11.\0QUIT-COMMAND
                5.1.12.\0RETURN-COMMANDS
                5.1.13.\0SUCCEED-COMMAND
                5.1.14.\0FAIL-COMMAND
                5.1.15.\0USER-DEFINED-COMMANDS
                5.1.16.\0REFINED-COMMANDS
        5.2.\0CONTROL-COMMANDS
                5.2.1.\0IF-COMMANDS
                5.2.2.\0SELECT-COMMANDS
                5.2.3.\0WHILE-COMMANDS
                5.2.4.\0FOR-COMMANDS
6.\0EXPRESSIONS, TARGETS AND TESTS
        6.1.\0EXPRESSIONS
                6.1.1.\0NUMERIC-CONSTANTS
                6.1.2.\0TARGET-CONTENTS
                6.1.3.\0TRIMMED-TEXTS
                6.1.4.\0TABLE-SELECTIONS
                6.1.5.\0DISPLAYS
                6.1.6.\0FORMULAS
                        Formulas with user-defined functions
                        Formulas with predefined functions
                6.1.7.\0REFINED-EXPRESSIONS
        6.2.\0TARGETS
                6.2.1.\0IDENTIFIERS
                6.2.2.\0TRIMMED-TEXT-TARGETS
                6.2.3.\0TABLE-SELECTION-TARGETS
        6.3.\0TESTS
                6.3.1.\0ORDER-TESTS
                6.3.2.\0PROPOSITIONS
                        Propositions with user-defined predicates
                        Propositions with predefined predicates
                6.3.3.\0REFINED-TESTS
                6.3.4.\0CONJUNCTIONS
                6.3.5.\0DISJUNCTIONS
                6.3.6.\0NEGATIONS
                6.3.7.\0QUANTIFICATIONS
INDEX
.ps 10
.vs 12
.in 0
.ds Sn Introduction
.bp
.St 0 INTRODUCTION
.fi
.Tx
\*B is a simple but powerful new programming language, designed for use in
personal computing.
(Note: the name ``\*B'' is only a temporary working title,
and the new language bears no relation to the predecessor of
C.)\ 
The foremost aim in the design of \*B has been the ease of use for
programmers who want to produce working programs without having
to master a complex tool.
An implementation of \*B is available from the \*B group at
the CWI, currently only under UNIX* or its look-alikes, but soon
(scheduled early 1985) also for the IBM-PC under MS-DOS.
Remarks concerning the implementation appear in this description
between double braces {{ and }}.
.sp 0.6v
This description of \*B originated from a text, prepared by
the first author, for use in teaching \*B during the Fall
term of 1982 at New York University.
The aim is to provide a reference book for the users of \*B that is more
accessible than the somewhat formal ``Draft Proposal'' [2].
While it is not a text book, it should also be useful
to people who already have ample programming
experience and want to learn \*B.
A text book for beginners is also available from the CWI [1].
.sp 0.6v
In this description we have tried to remain close to the Draft Proposal
in order to facilitate cross-referencing. To this end, all section numbers
from section 4 onwards are the same as in the Draft Proposal.
However there are some changes in terminology.
Some minor differences are
.sp 0.6v
.ta 2m \w'mmTYPE-TYPES-expressionmm'u \w'mmTYPE-TYPES-expressionmm'u+\w'multiple-expressionmm'u
.nf
\&	Draft Proposal:	This description:
.sp 0.4v
\&	textual-display	text-display
\&	textual-body	text-body
\&	LIST-body	optional-list-body
\&	TABLE-body	optional-table-filler-series
.fi
.sp 0.6v
But the main difference is perhaps in the treatment of ``collateral'':
.sp 0.6v
.nf
\&	Draft Proposal:	This description:	Examples
.sp 0.4v
\&	collateral-expression	expression	\*(<:a   (a, b)   a, b\*(:>
\&	TYPE-expression	single-expression	\*(<:a   (a, b)\*(:>
\&	TYPE-TYPES-expression	multiple-expression	\*(<:             a, b\*(:>
.fi
.sp 0.6v
Whereas these are purely descriptional differences,
there are also a few differences in content.
Where the Draft Proposal has the keyword \*(<:ALLOW\*(:>,
\*B now has the keyword \*(<:SHARE\*(:>;
a command \*(<:READ\*(:>\ ...\ \*(<:RAW\*(:> has been added;
and approximate-constants may no longer consist of just an exponent-part:
\*(<:E-1\*(:> must now be written \*(<:1E-1\*(:>.
.sp 0.6v
References
.sp 0.5v
.in +\w'[1]\ 'u
.ti 0
[1]\ \fIComputer Programming for Beginners, Introducing the B Language,
Part 1\fP,
.br
Leo Geurts, CWI, Amsterdam, 1984
.sp 0.5v
.ti 0
[2]\ \fIDraft Proposal for the B Programming Language\fP,
.br
Lambert Meertens, CWI, Amsterdam, 1981
.sp 0.6v
.in 0
*\ \s-2Unix is a trademark of Bell Laboratories.\s0
.fi
.SN 1
.bp
.St 1 "VALUES IN \*B"
.de tY
.sp 1
.ne 5
.in \w'Compounds\0\0'u
.ta \w'Compounds\0\0'u
.ti 0
\\$1\t\c
..
.Xx number
.Xx exact number
.Xx approximate number
.Xx text
.Xx character
.Xx order
.Xx compound
.Xx field
.Xx list
.Xx entry
.Xx list entry
.Xx table
.Xx table entry
.Xx key
.Xx associate
.Tx
\*B has two basic types of values: numbers and texts, and three ways of making
new types of values from existing ones: compounds, lists and tables.
The built-in functions for operating on these values are described
in section 6.1.6 entitled ``Formulas with predefined functions''.
.tY Numbers
Numbers come in two kinds: exact and approximate.
Exact numbers are rational numbers.
For example, \*(<:1.25\*(:> = \*(<:5/4\*(:>, and \*(<:(1/3)*3\*(:> = \*(<:1\*(:>.
There is no restriction on the size of numerator and denominator.
Approximate numbers are implemented by whatever the hardware has to offer
for fast but approximate arithmetic (floating point).
.br
The arithmetic operations and many other functions give an exact result
when their operands are exact,
and an approximate result otherwise,
but the function \*(<:sin\*(:>, for example, always returns an approximate number.
.br
An exact number can be made approximate with the \*(<:~\*(:> function
(e.g. \*(<:~1.25\*(:>);
the functions \*(<:round\*(:>, \*(<:floor\*(:> and \*(<:ceiling\*(:> can be used to convert
an approximate number to an exact one.
.br
Exact and approximate numbers may be mixed in arithmetic, as in \*(<:4 * atan 1\*(:>.
.tY Texts
Texts (strings) are composed of printable ASCII characters.
They are variable length, and are ordered in the usual lexicographic way:
\&\*(<:'a' < 'aa' < 'b'\*(:>.
There is no type ``character'': a text of length one will do.
.br
The printable characters
are the 95 characters represented on the lines below,
where the blank space preceding `\*(<:!\*(:>' stands for the
(otherwise invisible) space character:
.Di 5
\*(<: !"#$%&'()*+,-./0123456789:;<=>?
@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_
`abcdefghijklmnopqrstuvwxyz{|}~\*(:>
.br
.Ed
The ordering
on the characters is the ASCII collating order, which is the order
in which the characters are displayed above.
.tY Compounds
A compound consists of a sequence of other values, its ``fields''.
For example,
the number \*(<:3\*(:> and the text \*(<:'xyz'\*(:> may be combined to give the
compound \*(<:3, 'xyz'\*(:>.
Compounds are also ordered lexicographically.
.br
For example, \*(<:(3, 'xyz') < (3, 'yz') < (pi, 'aaa')\*(:>.
For this to be meaningful, the compounds that are compared must
be of the same type.
This means that they have the
same number of fields, and that corresponding fields are of the same type.
.br
The only way to obtain the individual fields of a compound is to put it
in a multiple-target with the right number of components, as in
.Di 1
\*(<:PUT name IN last'name, first'name, middle'name\*(:>.
.Ed
.tY Lists
A list is a \fIsorted\fP sequence of values, its ``entries''.
All entries of a list must be of the same type, and this determines
the type of the list.
The length of a list may vary without influencing its type.
When an entry is inserted in a list (with an \*(<:INSERT\*(:> command), it is automatically
inserted in the list in the proper position in the sorting order.
A list may contain duplicates of the same entry.
Entries may be removed with the \*(<:REMOVE\*(:> command.
Again, lists themselves are ordered lexicographically.
.tY Tables
A table consists of a (sorted) sequence of ``table entries''.
Each table entry is a pair of two values: a \fIkey\fP and an \fIassociate\fP.
All keys of a table must be of the same type; similarly, all associates must
also be of the same type (but that type may be different to
that of the keys).
A table may not contain duplicate keys.
If \*(<:k\*(:> is a key of the table \*(<:t\*(:>, then \*(<:t[k]\*(:>
gives the associate corresponding to \*(<:k\*(:>.
New entries can be made, or existing entries modified, by putting the
associate value in the table after selecting with the key value, as
in \*(<:PUT a IN t[k]\*(:>.
Entries can be deleted with the \*(<:DELETE\*(:> command, as in \*(<:DELETE t[k]\*(:>.
The ordering is again lexicographic.
.St 2 "SYNTAX DESCRIPTION METHOD"
.Tx
The syntax of \*B is given in the following form:
each rule starts with the name of the thing being defined followed by a colon;
following this are one or more alternatives,
each marked with a \(bu in front.
Each alternative is composed of symbols that stand for
themselves, or the names of other rules.
These other rules are then defined elsewhere in the grammar,
or possibly in the same rule.
As an example, here is a simple grammar for a small part of English:
.Sy  4
.Pn  sentence 3
.Al
declarative
.Al
declarative \*(<:,\*(:> connective\0sentence
.Pn  declarative 3
.Al
collective-noun\0verb\0collective-noun
.Al
collective-noun \*(<:do not\*(:> verb\0collective-noun
.Pn collective-noun 2
.Al
\*(<:cats\*(:>
.Al
\*(<:dogs\*(:>
.Al
\*(<:people\*(:>
.Al
\*(<:the police\*(:>
.Pn verb 2
.Al
\*(<:love\*(:>
.Al
\*(<:hate\*(:>
.Al
\*(<:eat\*(:>
.Al
\*(<:hassle\*(:>
.Pn connective 2
.Al
\*(<:and\*(:>
.Al
\*(<:but\*(:>
.Al
\*(<:although\*(:>
.Al
\*(<:because\*(:>
.Al
\*(<:yet\*(:>
.Tx
This produces sentences like:
.Di 4
.in -6
\*(<:dogs do not love the police\*(:>
\*(<:the police hassle dogs\*(:>
\*(<:cats do not hate cats , but cats hate dogs , because dogs hate cats\*(:>
\*(<:people eat dogs , yet dogs love people\*(:>
.in +6
.Ed
.in 0
You will notice that the names of rules are in a different
typeface to words that stand for themselves.
In the grammar of \*B that follows, furthermore, rule names
are all in lower-case letters, while words that stand for themselves are all
in upper-case letters, so they are easily distinguished.
.sp
It often happens that a part of an alternative is optional.
There is a special rule for this:
.Sy  4
.Pr empty 2
.Al
.br
.Pr optional-ANYTHING 3
.Al
empty
.Al
ANYTHING
.Tx
The ``optional'' rule is included to save many rules in the definition.
For example, it stands for a rule
.Pn  optional-comment 3
.Al
empty
.Al
comment
.Tx
and similar rules.
(Empty produces an empty result.)
.St 3 REPRESENTATIONS
.Xx indentation
.Xx increase-indentation
.Xx decrease-indentation
.Xx new-line-proper
.Xx keyword
.Xx tag
.Pr new-line 2
.Sl
optional-comment\0new-line-proper\0indent
.Ps
A \*B program consists of indented lines.
A new-line-proper marks a transition to a new line.
An indent stands for the left margin blank offset.
Initially, the left margin has zero width.
The indentation is increased by an increase-indentation
and decreased again by a decrease-indentation.
These always come in pairs and serve for grouping, just as BEGIN-END pairs
do in other programming languages.
An increase-indentation is always preceded by a line ending with a colon
(possibly followed by comment).
.Pr comment 3
.Al
optional-new-line-proper\0optional-spaces
\*(<:\\\*(:> comment-body\0optional-further-comment
.Pr further-comment 3
.Al
new-line-proper\0optional-spaces
\*(<:\\\*(:> comment-body\0optional-further-comment
.Pr spaces 2
.Sl
space\0optional-spaces
.Ps
Comments may be placed at the end of a line or may stand alone
on a line.
No comment may precede the first line of a unit (see section 4).
.br
A comment-body may be any sequence of printable characters.
.Sx 2 comment:
\*(<:\\modified 6/4/84 to reject passwords of length < 6\*(:>
.Tx
Keywords are composed of CAPITAL letters (\*(<:A\*(:> to \*(<:Z\*(:>), digits,
and quotes (\*(<:'\*(:> and \*(<:"\*(:>).
A keyword must start with a letter.
For example, \*(<:A3'B"\*(:> is a keyword.
.Tx
Tags are composed of lower-case letters (\*(<:a\*(:> to \*(<:z\*(:>), digits, 
and quotes (\*(<:'\*(:> and \*(<:"\*(:>).
A tag must start with a letter.
For example, \*(<:a3'b"\*(:> is a tag.
.Tx
Some other signs are composite: \*(<:..\*(:>, \*(<:**\*(:>, \*(<:*/\*(:>, \*(<:/*\*(:>, \*(<:^^\*(:>,
\*(<:<<\*(:>, \*(<:><\*(:>, \*(<:>>\*(:>, \*(<:<=\*(:>, \*(<:<>\*(:> and \*(<:>=\*(:>.
Spaces are freely allowed between symbols, but not
within keywords, tags,  numeric-constants and composite signs.
Sometimes spaces are required to separate keywords and tags from following
symbols.
For example, \*(<:cos y\*(:> is not the same as \*(<:cosy\*(:>: the latter is
taken to be one tag.
.St 4 UNITS 
.Xx work-space
.Sy  4
.Pr unit 4
.Al
how-to-unit
.Al
yield-unit
.Al
test-unit
.Ps
Units are the building blocks of a \*B ``program''.
Users can define new commands, functions and predicates by writing a unit.
These units reside in a work-space.
.Pr refinement-suite 2
.Al
new-line\0refinement\0optional-refinement-suite
.Ps
When writing a unit, the specification of some parts
(commands, expressions and tests) may be deferred by
using a ``refinement''.
These refinements are then specified at the end of the unit.
.Se 3  4.1 HOW-TO-UNITS
.Xx keyword
.Xx user-defined-command
.Sy  3
.Pr how-to-unit 3
.Al
\*(<:HOW'TO\*(:> formal-user-defined-command\*(<::\*(:>
.br
command-suite
.br
optional-refinement-suite
.Pr formal-user-defined-command 2
.Sl
keyword\0optional-formal-tail
.Ps 
The first keyword of a formal-user-defined-command must be unique, i.e.,
different from the first keywords of all predefined and other
user-defined commands.
So it is impossible to redefine the built-in commands of \*B.
It may also not be \*(<:HOW'TO\*(:>, \*(<:YIELD\*(:>, \*(<:TEST\*(:>, \*(<:SHARE\*(:> or \*(<:ELSE\*(:>.
Otherwise, it may be chosen freely.
There are no restrictions on the second and further keywords.
.Pr formal-tail 3
.Al
formal-parameter\0optional-formal-trailer
.Al
formal-trailer
.Pr formal-trailer 2
.Sl
keyword\0optional-formal-tail
.Pr formal-parameter 1
.Sl
tag
.Ps
Note that, although actual-parameters (section 5.1.16)
and formal-operands (section 4.2) may be composite,
formal-parameters must be simple tags.
.Sx 5 \k1how-to-unit:
\*(<:HOW'TO PUSH value ON stack:
    PUT value IN stack[#stack+1]\*(:>
.Tx
A how-to-unit defines the meaning of a new command
(see ``user-defined-commands'', section 5.1.16).
The above unit defines a \*(<:PUSH\*(:>\ ...\ \*(<:ON\*(:>\ ... command.
Once the command has been defined, it may be used in the
same way as the built-in commands.
Other user-defined commands may be used in the body of a unit
even if they have not yet been defined,
though they must be defined by the time the unit is invoked.
.Xe
.Sa
quit-command (5.1.11),
share-heading (4.5),
user-defined-commands (5.1.16).
.Se 3  4.2 YIELD-UNITS
.Xx "overloading of functions and predicates"
.Xx user-defined functions
.Xx formula
.Xx function
.Xx predicate
.Xx zeroadic
.Xx monadic
.Xx dyadic
.Sy  3
.Pr yield-unit 3
.Al
\*(<:YIELD\*(:> formal-formula\*(<::\*(:>
.br
command-suite
.br
optional-refinement-suite
.Pr formal-formula 4
.Al
formal-zeroadic-formula
.Al
formal-monadic-formula
.Al
formal-dyadic-formula
.Pr formal-zeroadic-formula 2
.Sl
zeroadic-function
.Pr formal-monadic-formula 2
.Sl
monadic-function\0formal-operand
.Pr formal-dyadic-formula 2
.Al
formal-operand\0dyadic-function\0formal-operand
.Ps 
Functions must not be ``overloaded'' (multiply defined),
and a user-defined function must be represented by a tag.
However, a given tag may be used, at the same time, for
a dyadic-function and either a zeroadic- or a monadic-function or -predicate.
(In other words, you may not have a function that is both monadic
and zeroadic, for otherwise it would be impossible to decide what was meant
in cases such as \*(<:f + 1\*(:>,
where \*(<:f\*(:> could be either zeroadic or monadic, and the restrictions
also apply to combinations of functions and predicates.)
.Pr formal-operand 2
.Sl
single-identifier
.Sx 5 \k1yield-unit:
\*(<:YIELD (a, b) over (c, d):
    PUT c*c+d*d IN rr
    RETURN (a*c+b*d)/rr, (-a*d+b*c)/rr\*(:>
.Xe
.Tx
A yield-unit defines the meaning of a new function
(see ``Formulas with user-defined functions'', section 6.1.6).
The example given above defines complex division.
(Complex numbers are not a built-in type of \*B.)
.br
Functions may be zeroadic (no operands), monadic (one trailing operand)
or dyadic (two operands, one at the left and one at the right).
.Sa
return-commands (5.1.12),
share-headings (4.5),
formulas with user-defined functions (6.1.6).
.Se 3  4.3 TEST-UNITS
.Xx "overloading of functions and predicates"
.Xx user-defined-predicates
.Xx test
.Xx formula
.Xx function
.Xx predicate
.Xx proposition
.Xx zeroadic
.Xx monadic
.Xx dyadic
.Sy  3
.Pr test-unit 3
.Al
\*(<:TEST\*(:> formal-proposition\*(<::\*(:>
.br
command-suite
.br
optional-refinement-suite
.Pr formal-proposition 4
.Al
formal-zeroadic-proposition
.Al
formal-monadic-proposition
.Al
formal-dyadic-proposition
.Pr formal-zeroadic-proposition 2
.Sl
zeroadic-predicate
.Pr formal-monadic-proposition 2
.Al
monadic-predicate\0formal-operand
.Pr formal-dyadic-proposition 2
.Al
formal-operand\0dyadic-predicate\0formal-operand
.Ps 
Like functions, predicates must not be ``overloaded'',
though a given tag may be used, at the same time, for
a dyadic-predicate and either a zeroadic- or a monadic-function or -predicate.
.Sx 5 \k1test-unit:
\*(<:TEST a subset b:
    REPORT EACH x IN a HAS x in b\*(:>
.Xe
.Tx
A test-unit defines the meaning of a new predicate
(see ``Propositions with user-defined predicates'', section 6.3.2).
Like functions, predicates may be zeroadic, monadic or dyadic.
.br
Tests do not return a value, but succeed or fail via the \*(<:REPORT\*(:>,
\*(<:SUCCEED\*(:> and \*(<:FAIL\*(:> commands.
.Sa
report-commands (5.1.13),
succeed-command (5.1.14),
fail-command (5.1.15),
share-headings (4.5),
propositions with user-defined predicates (6.3.2).
.Se 4  4.4 REFINEMENTS
.Xx keyword
.Sy  4
.Pr refinement 4
.Al
command-refinement
.Al
expression-refinement
.Al
test-refinement
.Pr command-refinement 2
.Sl
keyword\*(<::\*(:> command-suite
.Ps
The keyword of a command-refinement must be different from the first keywords
of all predefined commands,
and it may also not be \*(<:HOW'TO\*(:>, \*(<:YIELD\*(:>, \*(<:TEST\*(:>, \*(<:SHARE\*(:> or \*(<:ELSE\*(:>.
It may, however, be the same as the first keyword of a user-defined-command.
.Sx 4 \k1command-refinement:
\*(<:SELECT'TASK:
    PUT min tasks IN task
    REMOVE task FROM tasks\*(:>
.Pr expression-refinement 2
.Sl
tag\*(<::\*(:> command-suite
.Sx 4 expression-refinement:
\*(<:stack'pointer:
    IF stack = {}: RETURN 0
    RETURN max keys stack\*(:>
.Pr test-refinement 2
.Sl
tag\*(<::\*(:> command-suite
.Sx 4 test-refinement:
\*(<:special'case:
    REPORT position+d = line'length\*(:>
.Xe
.Tx
Refinements support the method of ``top-down'' programming, also
known as programming by ``stepwise refinement''.
The body of a unit may be written using refined-commands, -expressions
and -tests that reflect the appropriate, coarse-grained, level of
abstraction for expressing the algorithmic intention.
In subsequent refinements, these may be refined to
the necessary detail, possibly in several steps.
As with units, there are three kinds of refinements.
The differences with units are:
.in (\w'\(em\ 'u+3m)u
.ti 3m
\(em\ refinements are bound to a unit and may not be invoked
from other units;
.ti 3m
\(em\ all tags known inside the unit are also known inside the
refinement;
.ti 3m
\(em\ no parameters or operands can be passed when the
refinement is invoked.
.in 0
{{Currently, refinements may only occur within unit bodies, and not
in ``immediate commands''.}}
.Sa
refined-commands (5.1.17),
refined-expressions (6.1.7),
refined-tests (6.3.3).
.Se 4  4.5 COMMAND-SUITES
.Xx target
.Xx local
.Xx global
.Xx work-space
.Xx permanent environment
.Xx yield-unit
.Xx expression-refinement
.Xx return-command
.Xx test-unit
.Xx test-refinement
.Xx report-command
.Xx succeed-command
.Xx fail-command
.Sy  4
.Pr command-suite 4
.Al
simple-command
.Al
increase-indentation\0optional-share-heading
optional-command-sequence\0decrease-indentation
.Ps
A command-suite may only follow the preceding colon on the same line
if it is a simple-command.
Otherwise, it starts on a new line, with
all lines of the command-suite indented.
.Sx 4 command-suite
\*(<:SHARE name'list, abbreviation'table
IF name in keys abbreviation'table:
    PUT abbreviation'table[name] IN name
IF name not'in name'list:
    INSERT name IN name'list\*(:>
.Xe
.Pr share-heading 3
.Al
new-line \*(<:SHARE\*(:> identifier\0optional-share-heading
.Ps 
Tags used as targets (variables) in a unit
(except those that are formal-parameters)
are by default local to the unit.
If a target should be shared between several units,
this can be indicated by listing the tag
in a share-heading at the start of the unit body.
It stands then for a global target of the work-space.
The global targets together with their contents are also called the ``permanent
environment'', because they survive on logging out.
.br
A share-heading may only occur in the command-suite of a unit (and not
of a refinement or compound-command).
.Sx 2 share-heading
\*(<:SHARE name'list, abbreviation'table\*(:>
.Xe
.Pr command-sequence 2
.Al
new-line\0command\0optional-command-sequence
.Ps 
The execution of the command-suite of a yield-unit or
expression-refinement must end in a return-command, and return-commands
may only occur within such command-suites.
.Ps 
The execution of the command-suite of a test-unit or
test-refinement must end in a report-, succeed- or fail-command, and these
may only occur within such command-suites.
.Sx 3 command-sequence
\*(<:IF name in keys abbreviation'table:
    PUT abbreviation'table[name] IN name
IF name not'in name'list:
    INSERT name IN name'list\*(:>
.Xe
.St 5 COMMANDS
.Xx immediate command
.Xx global
.Xx interrupt key
.Tx
Commands may be given as ``immediate commands'', directly from
the terminal, or may be part of a unit.
If commands are given as immediate commands, they are obeyed
directly.
Any targets in the command are then interpreted as global targets
from the permanent environment.
Within a unit, targets are local, unless they have been listed
in a share-heading (see above).
.br
If the user presses the interrupt key while a command is executing,
execution is aborted, and the user is prompted for another immediate command.
.Sy  3
.Pr command 3
.Al
simple-command
.Al
control-command
.Se 3  5.1 SIMPLE-COMMANDS
.Sy  3
.Pr simple-command 3
.Al
check-command
.Al
write-command
.Al
read-command
.Al
put-command
.Al
draw-command
.Al
choose-command
.Al
set-random-command
.Al
remove-command
.Al
insert-command
.Al
delete-command
.Al
terminating-command
.Al
user-defined-command
.Al
refined-command
.Pr terminating-command 3
.Al
quit-command
.Al
return-command
.Al
report-command
.Al
succeed-command
.Al
fail-command
.Se 2  5.1.1 CHECK-COMMANDS
.Sy  2
.Pr check-command 2
.Sl
\*(<:CHECK\*(:> test
.Sx 3 \k1check-command:
\*(<:CHECK i >= 0 AND j >= 0 AND i+j <= n\*(:>
.Xe
.Tx
When a check-command is executed, its test is tested.
If the test fails, an error is reported and execution halts.
Otherwise, no message is given and execution continues.
Check-commands may be used, for example, to check the requirements of
parameters or operands on entry to a unit.
The liberal use of check-commands helps to get programs correct quickly.
.Se 3  5.1.2 WRITE-COMMANDS
.Xx convert to a text
.Xx permanent environment
.Xx interrupt key
.Sy  3
.Pr write-command 3
.Al
\*(<:WRITE\*(:> new-liners
.Al
\*(<:WRITE\*(:> optional-new-liners\0expression\0optional-new-liners
.Pr new-liners 2
.Sl
\*(<:/\*(:> optional-new-liners
.Ex 3
\k1write-commands:
\h'|\n1u'\*(<:WRITE //\*(:>
\h'|\n1u'\*(<:WRITE // 'Give a value in the range 1 through `n`: '\*(:>
.Tx
The expression is converted to a text and written to the screen.
Each \*(<:/\*(:> gives a transition to a new line.
Note that you write no comma before or after the \*(<:/\*(:>s.
.br
With the exception of adjacent texts,
values that are adjacent are written separated by a space.
Compounds within other values (within lists, tables or other compounds)
are written with commas between their fields,
and where necessary, the whole surrounded by brackets.
Similarly, inner texts are written enclosed by quotes.
Compounds and texts not within other values are output without commas,
brackets and quotes.
Thus,
.Di 2
\*(<:WRITE 0, 1, ',', 2, '!', '!', 3
WRITE {1; 2}, {['a','b']:('b','a'); ['b','a']:('a','b')} /\*(:>
.Ed
gives
.Di 1
\*(<:0 1 , 2 !! 3 {1; 2} {['a', 'b']: ('b', 'a'); ['b', 'a']: ('a', 'b')}\*(:>
.Ed
For formatting purposes, see the operators \*(<:>>\*(:>, \*(<:<<\*(:>, and \*(<:><\*(:>
in section 6.1.6, ``Functions on Texts'',
and the conversions in text-displays in section 6.1.5, ``Displays''.
.Se 3  5.1.3 READ-COMMANDS
.Sy  3
.Pr read-command 4
.Al
\*(<:READ\*(:> target \*(<:EG\*(:> expression
.Al
\*(<:READ\*(:> target \*(<:RAW\*(:>
.Ex 3
read-commands:
\*(<:READ n, s EG 0, ''
READ line RAW\*(:>
.Xe
.Tx
The execution of a read-command prompts the user
to supply one input line.
.br
If an \*(<:EG\*(:> part is present, the input is interpreted as an
\fIexpression\fP of the same type as the expression following \*(<:EG\*(:>.
(Usually, the example expression will consist of constants,
but other expressions are also allowed.)
The input expression is evaluated in the permanent environment
(so local tags of units cannot be used) and put in the target.
To input a text-display (literal), text quotes are required.
.br
If \*(<:RAW\*(:> is specified, the target must be a text target.
The input line is put in the target literally.
No text quotes are needed.
.br
If the user presses the interrupt key instead of supplying a value,
the read-command, and in fact the whole program, is aborted.
This is useful for entering a sequence of data of unspecified length.
.Se 3  5.1.4 PUT-COMMANDS
.Xx target
.Xx location
.Xx type
.Sy  3
.Pr put-command 3
.Sl
\*(<:PUT\*(:> expression \*(<:IN\*(:> target
.Sx 3 \k1put-command:
\*(<:PUT a+1, ({}, {1..a}) IN a, b\*(:>
.Xe
.Tx
The value of the expression is put in the target.
This means that the value will be held in a location
for the target, until a different value is put in the target,
or the target is deleted.
If no such location exists already, it is created on
the spot.
Here, as in other cases, the types must agree.
{{This is currently not checked in general.}}
See also the sections on various kinds of targets below (section 6.2).
.Se 2  5.1.5 DRAW-COMMANDS
.Xx random
.Xx number
.Sy  2
.Pr draw-command 2
.Sl
\*(<:DRAW\*(:> target
.Sx 3 \k1draw-command:
\*(<:DRAW r\*(:>
.Xe
.Tx
A random approximate number
(from \*(<:~0\*(:> up to, but not including, \*(<:~1\*(:>)
is drawn and put in the target.
.Se 4  5.1.6 CHOOSE-COMMANDS
.Xx text, list or table
.Xx random
.Xx character
.Xx list entry
.Xx associate
.Sy  4
.Pr choose-command 4
.Sl
\*(<:CHOOSE\*(:> target \*(<:FROM\*(:> expression
.Sx 3 \k1choose-command:
\*(<:CHOOSE exit FROM exits[current'room]\*(:>
.Xe
.Tx
The expression must have a text, list or table as value.
This value must not be empty.
An item is drawn at random from the value
(characters from a text, entries from a list and associates
from a table)
and put in the target.
The item is not removed from the value.
.Se 2  5.1.7 SET-RANDOM-COMMANDS
.Xx random
.Sy  2
.Pr set-random-command 2
.Sl
\*(<:SET'RANDOM\*(:> expression
.Sx 3 \k1set-random-command:
\*(<:SET'RANDOM 'Monte Carlo', run\*(:>
.Xe
.Tx
The (pseudo-)random sequence
used for draw- and choose-commands
is reset to a point, depending on the
value of the expression.
.Se 3  5.1.8 REMOVE-COMMANDS
.Xx list entry
.Sy  3
.Pr remove-command 3
.Sl
\*(<:REMOVE\*(:> expression \*(<:FROM\*(:> target
.Sx 3 \k1remove-command:
\*(<:REMOVE task FROM tasks\*(:>
.Xe
.Tx
The target must hold a list, and the value of the expression must be
an entry of that list.
The entry is removed.
If it was present more than once, only one instance is removed.
.Se 3  5.1.9 INSERT-COMMANDS
.Xx list entry
.Sy  3
.Pr insert-command 3
.Sl
\*(<:INSERT\*(:> expression \*(<:IN\*(:> target
.Sx 3 \k1insert-command:
\*(<:INSERT new'task IN tasks\*(:>
.Xe
.Tx
The target must hold a list.
The value of the expression is inserted as a list entry.
If that entry was already present, one more instance will be present.
.Se 2  5.1.10 DELETE-COMMANDS
.Xx location
.Xx table entry
.Xx table-selection-target
.Sy  2
.Pr delete-command 2
.Sl
\*(<:DELETE\*(:> target
.Sx 3 \k1delete-command:
\*(<:DELETE t[i], u[i, j]\*(:>
.Xe
.Tx
The location for the target ceases to exist.
If a multiple-target is given, all its single-targets are deleted.
If a table-selection-target is given, the table must contain the key
that is used as selector.
The table entry with that key is then deleted from the table.
It is an error to delete a trimmed-text-target (e.g., \*(<:t@2\*(:>).
.Se 2  5.1.11 QUIT-COMMAND
.Xx how-to-unit
.Xx command-refinement
.Xx immediate-command
.Xx permanent environment
.Sy  2
.Pr quit-command 2
.Sl
\*(<:QUIT\*(:>
.Ps 
A quit-command may only occur in the command-suite of a
how-to-unit or command-refinement, or as an immediate command.
.Sx 3 \k1quit-command:
\*(<:QUIT\*(:>
.Xe
.Tx
The execution of a quit-command causes the termination of the execution
of the how-to-unit or command-refinement in whose command-suite
it occurs.
If it occurs in a command-refinement, the execution of
the invoking refined-command is thereby terminated and the further
execution continues as if the refined-command had terminated normally.
Otherwise, the execution of
the invoking user-defined-command is terminated and the further
execution continues similarly.
.br
Given as an immediate command, \*(<:QUIT\*(:> terminates the current
session.
All units and targets in the permanent environment
survive and can be used again at the next session.
.Se 2  5.1.12 RETURN-COMMANDS
.Xx expression-refinement
.Xx user-defined-function
.Xx refined-expression
.Xx yield-unit
.Sy  2
.Pr return-command 2
.Sl
\*(<:RETURN\*(:> expression
.Sx 3 \k1return-command:
\*(<:RETURN (a*c+b*d)/rr, (-a*d+b*c)/rr\*(:>
.Xe
.Tx
The execution of a return-command causes the termination of the execution
of the yield-unit or expression-refinement in whose command-suite
it occurs.
The value of the expression is returned as the value of the invoking
user-defined function or refined-expression.
Return-commands may only occur within the command-suite of a
yield-unit or expression-refinement.
.Se 2  5.1.13 REPORT-COMMANDS
.Xx test-unit
.Xx test-refinement
.Xx user-defined-predicate
.Xx refined-test
.Xx bound tags
.Pr report-command 2
.Sl
\*(<:REPORT\*(:> test
.Sx 3 \k1report-command:
\*(<:REPORT i in keys t\*(:>
.Xe
.Tx
The execution of a report-command causes the termination of the execution
of the test-unit or test-refinement in whose command-suite
it occurs.
The invoking user-defined predicate or refined-test
succeeds/fails if the test of the report-command succeeds/fails.
If the invoker is a test-refinement,
any bound tags set by a for-command (see section 5.2.4) or
a quantification (section 6.3.7) will temporarily survive,
as described under REFINED-TESTS (section 6.3.3).
.br
Report-commands may only occur within the command-suite of a
test-unit or test-refinement.
.br
The command ``\*(<:REPORT\*(:> test'' is equivalent to
.Di 3
\*(<:SELECT:
    \*(:>test\*(<:: SUCCEED
    ELSE: FAIL\*(:>
.Ed
.Se 2  5.1.14 SUCCEED-COMMAND
.Xx test-unit
.Xx test-refinement
.Xx user-defined-predicate
.Xx refined-test
.Xx bound tags
.Sy  2
.Pr succeed-command 2
.Sl
\*(<:SUCCEED\*(:>
.Sx 3 \k1succeed-command:
\*(<:SUCCEED\*(:>
.Xe
.Tx
The execution of a succeed-command causes the termination of the execution
of the test-unit or test-refinement in whose command-suite
it occurs.
The invoking user-defined predicate or refined-test succeeds.
As with report-commands, bound tags temporarily survive.
.br
Succeed-commands may only occur within the command-suite of a
test-unit or test-refinement.
.br
The command \*(<:SUCCEED\*(:> is equivalent to \*(<:REPORT 0 = 0\*(:>.
.Se 2  5.1.15 FAIL-COMMAND
.Xx test-unit
.Xx test-refinement
.Xx user-defined-predicate
.Xx refined-test
.Xx bound tags
.Sy  2
.Pr fail-command 2
.Sl
\*(<:FAIL\*(:>
.Sx 3 \k1fail-command:
\*(<:FAIL\*(:>
.Xe
.Tx
The execution of a fail-command causes the termination of the execution
of the test-unit or test-refinement in whose command-suite
it occurs.
The invoking user-defined predicate or refined-test fails.
As with report-commands, bound tags temporarily survive.
.br
Fail-commands may only occur within the command-suite of a
test-unit or test-refinement.
.br
The command \*(<:FAIL\*(:> is equivalent to \*(<:REPORT 0 = 1\*(:>.
.Se 2  5.1.16 USER-DEFINED-COMMANDS
.Xx keyword
.Xx how-to-unit
.Xx quit-command
.Sy  2
.Pr user-defined-command 2
.Sl
keyword\0optional-actual-parameter\0optional-trailer
.Pr trailer 2
.Sl
keyword\0optional-actual-parameter\0optional-trailer
.Pr actual-parameter 2
.Al
identifier
.Al
target
.Al
expression
.Ps 
The keywords and actual-parameters must correspond one to one to those
of the formal-user-defined-command of one unique how-to-unit.
.Ex 6
\k1user-defined-commands:
\h'|\n1u'\*(<:CLEAN'UP\*(:>
\h'|\n1u'\*(<:DRINK me\*(:>
\h'|\n1u'\*(<:TURN a UPSIDE DOWN\*(:>
\h'|\n1u'\*(<:PUSH v ON operand'stack\*(:>
.Xe
.Tx
A user-defined-command is executed in the following steps:
.in \w'2.\ 'u
.ti 0
1.\ Any local tags in the how-to-unit that might clash with tags currently
in use are systematically replaced by other tags that do not cause conflict.
.ti 0
2.\ Each actual-parameter is placed between parentheses \*(<:(\*(:> and \*(<:)\*(:>
and then
substituted throughout the unit for the corresponding formal-parameter.
.ti 0
3.\ The command-suite of the unit, thus modified, is executed.
.in 0
The execution of the user-defined-command is complete when the execution
of this command-suite terminates (normally, or because of the execution
of a quit-command).
After the execution is complete,
the local tags of the unit are no longer accessible.
.Se 2  5.1.17 REFINED-COMMANDS
.Xx keyword
.Xx command-refinement
.Xx quit-command
.Sy  2
.Pr refined-command 2
.Sl
keyword
.Ps 
The keyword of a refined-command must occur as the keyword of one
command-refinement in the unit
in which it occurs.
That command-refinement specifies the meaning of the refined-command.
.Sx 3 \k1refined-command:
\*(<:REMOVE'MULTIPLES\*(:>
.Xe
.Tx
A refined-command is executed by executing
the command-suite of the corresponding command-refinement.
The execution of the refined-command is complete when the execution
of this command-suite terminates
(normally, or because of the execution of a quit-command).
.Se 5  5.2 CONTROL-COMMANDS
.Sy  5
.Pr control-command 5
.Al
if-command
.Al
select-command
.Al
while-command
.Al
for-command
.Se 2  5.2.1 IF-COMMANDS
.Sy  2
.Pr if-command 2
.Sl
\*(<:IF\*(:> test\*(<::\*(:> command-suite
.Sx 3 \k1if-command:
\*(<:IF i < 0: PUT -i, -j IN i, j\*(:>
.Xe
.Tx
The test is tested.
If it succeeds, the command-suite is executed;
if it fails, the command-suite is not executed.
.br
(If something should be executed on failure too, or there are
more alternatives, you should use a select-command instead.)
.br
The command
``\*(<:IF\*(:> test\*(<::\*(:> command-suite''
is equivalent to:
.Di 3
\*(<:SELECT:
    \*(:>test\*(<:: \*(:>command-suite\*(<:
    ELSE: \\do nothing.\*(:>
.Ed
.Se 2  5.2.2 SELECT-COMMANDS
.Sy  2
.Pr select-command 2
.Sl
\*(<:SELECT:\*(:> alternative-suite
.Pr alternative-suite 3
.Al
increase-indentation\0new-line\0alternative-sequence\0decrease-indentation
.Pr alternative-sequence 4
.Al
single-alternative
.Al
else-alternative
.Al
single-alternative\0new-line\0alternative-sequence
.Pr single-alternative 2
.Sl
test\*(<::\*(:> command-suite
.Pr else-alternative 2
.Sl
\*(<:ELSE:\*(:> command-suite
.Eo 5 select-commands:\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\k2\":
\h'|\n1u'\*(<:SELECT:\*(:> \h'|\n2u'\*(<:SELECT:\*(:>
\h'|\n1u'\*(<:    a < 0: RETURN -a\*(:> \h'|\n2u'\*(<:    a < 0: RETURN -a\*(:>
\h'|\n1u'\*(<:    a >= 0: RETURN a\*(:> \h'|\n2u'\*(<:    ELSE: RETURN a\*(:>
.Xe
.Tx
The tests of the alternatives are tested one by one,
starting with the first and proceeding downwards, until one
is found that succeeds.
The corresponding command-suite is then executed.
\*(<:ELSE\*(:> may be used in the final alternative as a test that always succeeds.
If all the tests fail, an error is reported.
.Se 2  5.2.3 WHILE-COMMANDS
.Xx terminating command
.Sy  2
.Pr while-command 2
.Sl
\*(<:WHILE\*(:> test\*(<::\*(:> command-suite
.Sx 3 \k1while-command:
\*(<:WHILE x > 1: PUT x/10, c+1 IN x, c\*(:>
.Xe
.Tx
If the test succeeds, the command-suite is executed, and the
while-command is repeated, and so on, until the test fails,
or until an escape is forced by a terminating command.
If the test fails the very first time, the command-suite is
not executed at all.
.Se 3  5.2.4 FOR-COMMANDS
.Xx text, list or table
.Xx character
.Xx list entry
.Xx associate
.Xx target
.Xx bound tags
.Sy  3
.Pr for-command 3
.Sl
\*(<:FOR\*(:> in-ranger\*(<::\*(:> command-suite
.Pr in-ranger 2
.Sl
identifier \*(<:IN\*(:> expression
.Sx 3 \k1for-command:
\*(<:FOR i, j IN keys t: PUT t[i, j] IN t'[j, i]\*(:>
.Xe
.Tx
The value of the expression must be a text, list or table.
One by one, each item of that value
(characters for a text, list entries for a list and associates for a table)
is put in the identifier, and the command-suite executed.
For example,
.Di 1
\*(<:FOR c IN 'ABC': WRITE 'letter is', c /\*(:>
.Ed
is equivalent to
.Di 3
\*(<:WRITE 'letter is', 'A' /
WRITE 'letter is', 'B' /
WRITE 'letter is', 'C' /\*(:>
.Ed
If \*(<:t\*(:> is a table, then
``\*(<:FOR a IN t: TREAT a\*(:>''
treats the associates of \*(<:t\*(:> in the same way as
.Di 3
\*(<:FOR k IN keys t:
    PUT t[k] IN a
    TREAT a\*(:>
.Ed
The tags of the identifier of a for-command may not be used as targets
or target-contents
outside such a for-command.
They are ``bound tags'', and lose their meaning outside the
for-command.
There is one exception to this rule:
if a for-command is used in a test-refinement, and within
the for-command a report-, succeed- or fail-command is
executed, the currently bound tags will temporarily survive
as described under REFINED-TESTS (section 6.3.3).
.Sa
quantifications (6.3.7).