C/C++ Users Group Library 1996 July/C-C++ Users Group Library July 1996.iso/vol_200/230_01/docs.bun

Text File | 1987-05-25 | 114.9 KB | 3,730 lines

: To unbundle, sh this file
echo unbundling READ_ME 1>&2
cat >READ_ME <<'End'
Some of the material in this subdirectory is now out of date- having been
superceded by the material in the book A Little Smalltalk, published by
Addiso-Wesley.  So everybody run out and buy a copy of the book, ok?

End
echo unbundling Makefile 1>&2
cat >Makefile <<'End'
TROFF = vtroff
DITROFF = vtroff
FILES = READ_ME Makefile macros books BUGS INDEX \
install userman apndx1 st.1 syntax

INDEX: books
    invert books

installguide:
    $(TROFF) -ms install

manbody: INDEX
    bib userman | tbl | $(TROFF) -ms

appendix1: apndx1 macros
    tbl apndx1 | $(TROFF) -ms

appendix2:
    $(TROFF) -man man

appendix3:
    pic syntax | $(DITROFF) -ms

bundle: $(FILES)
    bundle $(FILES) >../docs.bundle

End
echo unbundling macros 1>&2
cat >macros <<'End'
.\" macros for producing descriptions of classes
.ds CM
.de Nm
.ds LH
.bp
.Im 0 \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8
.ds LH class \\fB\\$\\n(.$\\fP (continued)
.in 0
..
.de Im
.in \\$1
.if 2=\\n(.$ .ft B
\\$2
.if 2<\\n(.$ .Im \\$1+2m \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
..
.de Rs  \" respondsTo:
.ne 4v
.IP \\fI\\$2\\fP\\h'2m-\\w'\\fI\\$2\\fI'u'\\$1 15m
..
.de Ex   \" Examples
.br
.ne 10v
.SH
Examples
.LP
.if 0=\\n(.$ .ta 4i
.el .ta \\$1
     Printed result
.sp
.nf
..
.de Sx
.SH
\\$1
.IP
..

End
echo unbundling books 1>&2
cat >books <<'End'
%T Smalltalk-80, The Language and It's Implementation
%A Adele Goldberg
%A David Robson
%I Addison-Wesley
%D 1983
%K blue

%T Smalltalk-80 The Interactive Programming Environment
%A Adele Goldberg
%I Addison-Wesley
%D 1984
%K orange

%T Smalltalk-80 Bits of History, Words of Advice
%A Glenn Krasner
%I Addison-Wesley
%D 1983
%K green
End
echo unbundling BUGS 1>&2
cat >BUGS <<'End'
KNOWN BUGS

1/1/85 assigning a block to a variable will usually cause memory reference
    cycles, resulting in the number of increments and decrements not
    being equal following execution.
    (not really a bug, caused by the implementation - blocks need to
    access the context, which includes the local variables, which
    includes the block, which needs to access the context ... )

1/1/85    The stack size allocated by the parser is fixed.  It should be
    computed by the parser and varied for different methods.

1/1/85  system should be modified to allow execution on system with no
    ``system()'' system call (whew!).  This would involve using two
    programs - a parser to take class descriptions and turn them into
    internal form, and the smalltalk system.  Should be easy to do,
    however.

2/1/85    fast loading does not work on the HP9000

4/1/85    if you modify the class Smalltalk (and thereby the pseudo variable
    smalltalk) the pseudo variable does not get properly initialized.

4/1/85    Because of bootstrapping peculiarities, a few classes (such as
    Object or Symbol or String) do not respond to the message ``variables''
    correctly.
End
echo unbundling INDEX 1>&2
cat >INDEX <<'End'
1983 :books 0/122 234/101
1984 :books 123/110
addiso :books 0/122 123/110 234/101
adele :books 0/122 123/110
advice :books 234/101
bits :books 234/101
blue :books 0/122
david :books 0/122
enviro :books 123/110
glenn :books 234/101
goldbe :books 0/122 123/110
green :books 234/101
histor :books 234/101
implem :books 0/122
intera :books 123/110
its :books 0/122
krasne :books 234/101
langua :books 0/122
orange :books 123/110
progra :books 123/110
robson :books 0/122
smallt :books 0/122 123/110 234/101
words :books 234/101
End
echo unbundling install 1>&2
cat >install <<'End'
.ce
\fBLittle Smalltalk Installation Notes\fP
.sp
.NH
Installation Notes
.PP
There are four basic steps involved in installing the Little Smalltalk
system.  The four steps are; unbundling the sources, editing the sources to
tailor them to the target installation, compiling the sources, and moving
the final binary to the local executables directory.  Each of these four
steps are described in following paragraphs and in succeeding sections.
.ds RF \(DY
.PP
As distributed, the Little Smalltalk source consists of a small number of
files in ``bundle'' format.  A shell script, \fBunbundle\fP, is provided
that creates the various subdirectories used by the system and unbundles
the distribution files into their component parts.  To execute this shell
script, type, in a directory containing all the files in the distribution,
the following command:
.DS I
sh unbundle
.DE
.LP
A large amount of output should follow, indicating files have been
unbundled into subdirectories /sources, /parser, /prelude, /tests, /docs
and /bin.
.PP
There are a small number of editing changes required to tailor the system to
various different environments.  Section 2 describes these changes in detail for
various types of machines and operating systems.
.PP
Once the necessary tailoring has been performed, the system can then be
compiled by typing the command:
.DS I
make install
.DE
.LP
in the base directory (the original directory from which the source was
unbundled).  This command will then invoke further make commands which
produce the parser, the executable system, and the standard prelude.
In addition various self checks for correctness are provided.  Should it be
necessary, various subcomponents of the system can be individually produced
by typing the ``make install'' commands in the appropriate subdirectory.
These commands produce a considerable amount of output.
.PP
Once the system has been compiled and successfully passed all self tests,
the executable file in /bin/st should be linked or moved to the appropriate
location for local executables on the target system.
Finally, the object files for all compilations can be removed by typing
``make clean''.
.NH 1
Specific Machine Installation Instructions
.PP
A single source form and command syntax cannot be used for all combinations of
machine / operating systems, because of differences in library routine syntax
or function availability.  An attempt has been made to surround the occurrences
of such features with conditional compilation directives, so that by defining
or not defining a symbol the correct result can be produced on different
systems.  These commands have all been collected in the include file
parser/env.h, so for the most part this should be the principle file needing
to be edited.  In addition, ``meta-defines'' are provided for many systems to
which the Little Smalltalk system has already been ported.  By defining one
of these ``meta-defines'', correct values are given for the remainder of the
symbols.
.PP
Similarly, the ``standard'' set of flags necessary to use the compiler and/or
loader differ from system to system.  These are given by the two defined
strings, CFLAGS and LFLAGS, in sources/Makefile and parser/Makefile.
.PP
As distributed, the Little Smalltalk system expects the various
subdirectories to remain in the relationship in which they are unbundled.
If desired, however, they can be moved (say to place the sources in one
place, the libraries in another, and the binary in a third).  Each makefile
may contain one of either the strings BINDIR or PARSEDIR at the beginning.
If the binary or parser sources directory is moved, relative the the
directory containing the makefile,
these strings should be changed.  Otherwise, if the
relative positions of the directories remain as they were unbundled, the
default values for these strings can be used.
.PP
There are a few places where path specifications must be given in either
the Makefiles or in C sources.  These are described in the following sections.
.PP
Finally, bytecodes are kept in the form of ``unsigned characters''; that is,
characters containing numbers from 0-255.  These may or may not be
supported on various machines.  The file parser/env.h contains a typedef
for the type `uchar' and two macros for converting from unsigned characters
to integers and back again.  These should be defined in such a manner that
the appearance of unsigned characters is achieved, whether or not they are
actually supported.  A simple test program, called uchar.c, is provided in
/parser.  This program can be used to test the correctness of the macros
defined in env.h.
Generally, either the model of the VAX-780 or the PDP11/70 should be sufficient.
.NH 2
Bringing Little Smalltalk Up on a New System
.PP
If the system you are attempting to port to is not one of the systems described
in the following sections, a certain amount of experimentation will probably be
necessary to successfully install the system.  This section will describe some
of the major changes required; what other changes may be necessary is
generally unpredictable.
.PP
The strings CFLAGS and LFLAGS in sources/Makefile and parser/Makefile should
be set to the appropriate values for ``normal'' compiles and loads of
C programs.
.PP
The file prelude/Makefile contains a hard path in the string PREPATH.
This should be set to the path to the prelude directory.
.PP
The file parser/env.h contains various hard paths, which are described in
that file.  Also in that file, the following symbols should be defined or
left undefined, depending upon the availability of various features.
.IP CURSES 1i
This symbol should be defined if it is desired to provide the simple ascii
graphics given by the curses and termcap packages.  See section on
graphics below.
.IP ENVSAVE 1i
This symbol should be defined if it is necessary to save the value of the
global varible \fIenviron\fP during a fastload.
This is necessary on the 11/70, IBM PC, possibly other machines.
.IP FACTMAX 1i
This symbol should be defined to be the largest integer for which the factorial
can be computed by repeated multiplication without overflow.
This value is generally 12 for 32 bit machines and 8 for 16 bit machines.
.IP FASTDEFAULT 1i
This symbol should be defined if the default behavior of the system should
be to perform a fast load on the standard prelude (see section 3).
.IP FLUSHREQ 1i
If defined a fflush() is given after every call to printf.
.IP GAMMA 1i
This symbol should be defined if the gamma() function is part of the standard
math library, left undefined otherwise.
.IP INLINE 1i
This symbol should be defined if in-line code is desired for object increments
and decrements.  In line code is generally slightly faster, although the code
size is slightly larger.  If this symbol is not defined subroutine calls
will be generated for object increments and decrements.
.IP NOSYSTEM 1i
This symbol should be defined on non-unix systems for which the
``system()'' call is not supported.  As this seriously limits functionality
(i.e. class descriptions cannot be modified during execution) is should not
be used unless necessary.
.IP OPEN3ARG 1i
This symbol should be defined if Berkeley 4.2 style open
statements (3 arguments)
are used.  If the older, 2 argument, format is used this symbol should be left
undefined.
.IP PLOT3 1i
This symbol should be defined if you have terminals for which the plot(3)
routines can write directly to the screen, rather than requiring a
postprocessing filter.  See section on graphics below.
.IP SETJUMP 1i
This symbol should be defined if the setjump/longjump facility is
available.  This is used ONLY in the file sources/process.c to implement
recovery when the user has typed an interrupt character.
.IP SHORTDATA 1i
If this symbol is defined various heuristics are used to reduce the data
segment size, at the expense of functionality or execution speed.  Should
only be defined if absolutely necessary.
.IP SIGS
This symbol should be defined if the signals facility is available.  This
is used ONLY in the file sources/process.c to implement recovery when the
user has typed an interrupt character.
.PP
Also in parser/env.h, defines are provided to implement the datatype
``unsigned character''.  These were described in the last section.  Generally,
either following the model of the VAX-780 or the PDP11/70 should be sufficient
for most machines.
.NH 2
Berkeley lookalikes
.PP
It has been reported that following the directions for Berkeley 4.2
(below) is also sufficient for the following systems:
.DS I
Ahmdal / System V
Pyramid 90x / System V
Sequent Balance 8000
.DE
.NH 2
Berkeley near-lookalikes
.PP
It has also been reported that following the directions for Berkeley 4.2 is
sufficient for installation on the following systems, with the
one change that the symbol ENVSAVE should be defined in parser/env.h.
Note that on these systems, and other systems sharing the same
characteristics, the only indication that ENVSAVE should be defined will be
an obscure error message (usually ``-f: is not an identifier'') produced by the
shell if an attempt is made to load a class description following a
fast-load.
.DS I
Plexus P/35
Tektronix 6130 (presumably other Tek 61xx and 62xx machines).
.DE
.NH 2
AT&T 3B2, System V
.PP
The 3B2 does not have floating point hardware, and thus requires floating
point simulation software being linked in.  This is accomplished by adding
``\-f'' to CFLAGS \fIand\fP LFALGS in the makefiles in /sources and
/parser.  Other than for this change, the instructions for Berkeley 4.2 can
be used for the installation.
.NH 2
Dec Professional 350
.PP
In parser/Makefile the strings CFLAGS and LFLAGS should be left blank.
In sources/Makefile, however, the string CFLAGS should be defined to be ``\-m'',
to indicate the use of the code-mapping feature.  The normal construction rule
for the executable file st should be commented out, and the more complicated
loader instruction inserted in its place.  The appropriate rule is given in
a comment in the Makefile.
.PP
The string PREPATH in prelude/Makefile should be defined to be the path to
the prelude directory (this can be discovered by typing ``pwd'' in the
prelude directory).
.PP
In parser/env.h the ``meta-define'' DECPRO should be given, and any other
meta-defines removed.
Also in env.h the paths in the strings TEMPFILE, PARSER and PRELUDE should
be defined.  Note that /usr/tmp is not standard on Venix systems, and /tmp
should be used instead.
.PP
Because of the severe memory limitations on this machine, only Smalltalk
programs that produce a relatively small number of objects can be executed.
In fact, some of the later self tests fail with ``can't happen 1'' (out of
memory space).
Also, as more primitives are added to the system the size of primitive.o
keeps creeping towards the magic 8K limit on object file sizes for the code
mapping feature.  Eventually it may be necessary to split primitive.c into
two files in order to avoid this problem.
.NH 2
HP 9000 / HP-UX
.PP
Follow the instructions for the VAX 780 / Berkeley 4.2 (below) with the
exception that the meta-define should be given as HP9000 instead of BERK42.
Note that in the filenames in env.h that /usr has been changed to /users,
except for /usr/tmp, which hasn't (a foolish consistency is the hobgoblin
of little minds).
The fastsave routines have not been adapted to the HP extended memory
system, and thus fastsave should not be used.
.NH 2
IBM PC-XT
.PP
It has been reported that the instructions given for the PDP 11/70 (below)
are also sufficient for the IBM PC-XT running PC/IX.
.NH 2
PDP 11/70 (also 11/44)
.PP
In sources/Makefile and parser/Makefile the string CFLAGS should be left blank,
however LFLAGS should be set to ``\-i'' to indicate the use of
separate instruction and data spaces.
.PP
The string PREPATH in prelude/Makefile should be defined to be the path to
the prelude directory (this can be discovered by typing ``pwd'' in the
prelude directory).
.PP
In parser/env.h the ``meta-define'' PDP1170 should be given, and any other
meta-defines removed.
Also in env.h the paths in the strings TEMPFILE, PARSER and PRELUDE should
be defined.
.NH 2
Perkin Elmer
.PP
The Perkin Elmer supports unsigned characters the same as the VAX, however
it does not have the gamma function in the standard library.  Follow the
instructions for the VAX/4.2, using the meta-define PERKELM.
.NH 2
RIDGE / ROS 3.0
.PP
Follow the instructions for the VAX 780 /Berkeley 4.2 (below),
with the exception that the
meta-define should be given as RIDGE instead of BERK42.
The fast save feature does not work on the Ridge.
.NH 2
VAX 780 / Berkeley 4.2
.PP
In parser/Makefile and sources/Makefile the strings CFLAGS and LFLAGS should
both be left blank.
.PP
The string PREPATH in prelude/Makefile should be defined to be the path to
the prelude directory (this can be discovered by typing ``pwd'' in the
prelude directory).
.PP
In parser/env.h the ``meta-define'' BERK42 should be given, and any other
meta-defines removed.
Also in env.h the paths in the strings TEMPFILE, PARSER and PRELUDE should
be defined.
.PP
(VAX only) If the \-g flag is used the define FLUSHREQ need not be given
(although it
will work if it is present), otherwise FLUSHREQ should be defined in order
for input and output to interleave correctly.
.PP
As distributed, the system does not perform a fastload (see next section)
automatically.  If fastload works this can be made default by defining the
symbol FASTDEFAULT.
.PP
These instructions appear to work also for the SUN workstation; of course,
if you have a SUN workstation you can run the Xerox system.
.NH
Fast Loading
.PP
The Little Smalltalk system has the ability to save and restore a user
environment by basically moving a copy of all of the users data space into
a file.  Although this produces rather large files, the savings in time
permitted by not having to recreate a specific environment can be
substantial.  Because this is such an unusual thing to do, it is probably
wise, if installing the system on a new machine/operating system, to first
comment out the define for FASTDEFAULT in parser/env.h,
which will install a system which will not default to doing a fast load.
.PP
Once such a system has been created and passed all self tests, you can
experiment with fast loading by executing the st command with the argument
\-f.  For test cases you can use the programs in /tests.  If it appears to
be successful, then (by defining the variable FASTDEFAULT) you should
regenerate the system so that the default behavior is to do a fast loading.
(When regenerating the system, sources/main.c should be the only file
needing to be recompiled).
.PP
Fastloading does not currently work on the HP-9000.
It may not work on other machines as well.
.NH
Protections
.PP
The directories /sources and /parser need not be readable by casual users.
The directory /prelude contains files, however, which must be loaded by
the Little Smalltalk system prior to every execution.  The protection of this
directory, and on the files in it, should therefore be such that all users
have READ access.
Although the /tests directory is only used during system installation,
users may want to refer to it for examples of class descriptions and to see
how various problems (8 queens, dinning philosophers) have been solved in
Smalltalk.
Allowing all users access to the /docs directory will permit a kind of
on-line access, however users should not be allowed to modify any files in
any directory.
.NH
Non-UNIX systems
.PP
Non-UNIX\s-2\u*\d\s+2
.FS
* UNIX is a trademark of AT&T Bell Laboratories.
.FE
systems which do not support multiple user processes, and thus the
system() call, cannot at current run Little Smalltalk.  There are plans,
however, to at some time in the future support such systems.  This section
will describe, in broad terms, the changes required.  The detailed changed
are, of course, at the moment not known.
.PP
First, the defined value NOSYSTEM must be given in parser/env.h.  This
will cause all occurrences of the ``system()'' call to be commented out,
and in most cases be replaced by error messages.
.PP
Next, the parser must be modified to place its output in a file (presumably
the file given as argument with .st replaced by .p) instead of the standard
output.  This is a trivial, although probably system specific, change.
.PP
In use, the user would then be required to ``compile'' all class
descriptions by running the parser (which therefore would have to be user
accessible program) before running the Little Smalltalk system.  Little
Smalltalk could not be used to edit class descriptions on the fly \- the
user would have to leave the system, perform the edit, and return to the
system.  This would seriously limit functionality and utility, but that is
cost of not running UNIX!
.NH
Graphics
.PP
The nice bit-mapped graphics display of the Smalltalk-80 system is,
unfortunately, not very portable to conventional machines running
conventional ascii terminals.
Two mutually exclusive approaches have been furnished
for providing \fBvery\fP rudimentary but
nevertheless relatively device-independent graphics capabilities.
.PP
The first approach used the curses(3) and termlib(3) routines to provide
simple ascii (character-level) graphics.
To use these, define
the symbol CURSES in parser/env.h, and modify the Makefile in /sourses
adding the libraries -lcurses and -ltermlib (or termcap, whichever is
appropriate) to the symbol LIB.
.PP
The functionality so provided can be described as follows:
.IP clearScreen 1i
This message is accepted by the pseudo-variable smalltalk and clears the
screen.
.IP printAt: 1i
This message is accepted by instances of class String.  The argument must
be a point, representing a line@column pair.  The string is printed at the
point.
.PP
In addition, there is a class \fBForm\fP found in /prelude, which is an
attempt at providing simple graphics forms.  Instances of \fBForm\fP also
repond to printAt:.  A sample program plane.st can be found in /tests
illustrating some of the features of forms.
Refer to the Makesfiles in /prelude and /tests for more information.
.PP
The second approach uses the plot(3) routines.  On some terminals
(the Tektronix 4014, for example) these routines can be set up to
write directly to the terminal screen, rather than going through a
postprocessing filter.  If such a device is available, the symbol PLOT3
should be defined in parser/env.h, in addition appropriate loader commands
(-l4014, for example) should be added to the symbol LIB in
sources/Makefile.
.PP
The functionality so provided is the ability to produce lines, circles and
arcs.  Various classes (Pen, PenSave and Form) for doing this are provided
in the /prelude subdirectory, consult the Makefile for details.
A test program (penshow) is provided in the /tests subdirectory.
.NH
Troubleshooting
.PP
Here are a few of the problems you might run into, and possible solutions:
.PP
The first thing to suspect if you observe strange behavior is the
fastloading feature.  Try running the system with the \-m flag, which will
turn off fastloading.  For example, on the 11/70 fastloading will inhibit
the )i command from working correctly, but no error messages will be
generated.  The appearance of a message such as ``\fIxxx\fP: is not
an identifier'', or of can't happen message number 23
is also a clue that fastloading does not work and should be disabled.
Similarly, the appearance of the message ``no such context as:
\fIxxx\fP/stdsave'' during startup is an indication that the file
containing the saved binary form of the standard prelude either does not
exist or is unreadable, or that the path given in parser/env.h is wrong.
.PP
The appearence of the message ``xxx: not an identifier'' following a fast
load or a )l command may be a sign that the environment pointer is being
trashed.   Try defining the symbol ENVSAVE and recreating the system.
.PP
Solutions to problems with fastloading are to try to
to recreate the stdsave file in /prelude, or as a last resort to remove the
definition for FASTDEFAULT from /parser/env.h, ``make clean''
and recompile everything.
This latter step will configure a system that will not attempt fastloading
unless explicitly called for.
.PP
If the function _gamma is undefined following load for st.  Solution: remove
the definition for the symbol GAMMA, ``make clean'' and recompile.
.PP
\&``Cant't happen number 1''.  If you are running on a machine with small
memory, your program creates too many objects and runs out of memory.  If
you are running on a vax or other large machine - your application is
creating cycles or many many objects, probably a programming error.
.PP
No output appears when you start the program, and if you type control-D all
the output appears.  Solution: define the symbol FLUSHREQ and recompile.
.PP
Can't happen number 22 - either TEMPFILE is unreadable, or
/prelude/standard does not exist.
.PP
Systems that have trouble with long lines may have difficulty with the file
syms.c in /sources (there is one line in that file over 300 characters long).
If necessary, this file can (and will be) automatically reconstructed from
other files in the directory.
.PP
Receiving error number 129 whenever any non-primitive class method is
called may be a symptom of a clash of variable names.  On older systems the
variables runningProcess and runningInterpreter would clash on systems that
did not support long variable names.  The variable runningInterpreter (in
process.c) has since been changed to presentInterpreter, so this problem
should not occur in software taken from more recent distribution tapes.
.PP
129 errors can also be caused by bad preludes.  Try removing all the .p
files from /prelude and remaking standard.
(Frequently, if you receive an error when first building the prelude, some
of the .p files will be incorrect).
.PP
Note that /sources and /prelude have make instructions ``make clean'' which
remove object files and are useful in insuring the files are in a clean
state before starting a reconstruction of the system.
.NH
Further Distribution
.PP
The Little Smalltalk system is public domain, and may be distributed
further as long as proper attribution is given in all published references.
.PP
In the interests of keeping the distribution up to date and as error free
as possible, we wish to keep track of known sites using the
system.  People interested in being placed on the mailing list for future
bug announcements and new version announcements should contact Professor
Budd, at the address listed below.  Changes, modifications, or improvements
to the code or the standard library can be submitted also, and will be
considered for inclusion in future distributions.
.NH
What to do with BUGS
.PP
Observed irregularities in Little Smalltalk behavior during execution
(hereafter known as ``Bugs'') should be reported to:
.DS I
Professor Tim Budd
Little Smalltalk Distribution
Department of Computer Science
Oregon State University
Corvallis, Oregon 97331 USA

CSNET address:  [e-mail]
UUCP  address:  [e-mail]
.DE
.LP
The report of the bug should indicate whether it is reproducible, and if so
how it is manifested.  If it is available, a description of the fix for the
bug should be given, and it will be incorporated into future distributions.
Periodically, a listing of known bug fixes will be mailed to known sites.
.PP
The Little Smalltalk system is distributed without responsibility for the
performance of the system and without any guarantee of maintenance.
End
echo unbundling userman 1>&2
cat >userman <<'End'
.ds CM
.TL
A Little Smalltalk
User Manual
.AU
Timothy A. Budd
.po +0.2i
.nr PO +0.2i
.NH 1
Introduction
.PP
This manual is intended as an aid in using the Little Smalltalk system.
It is not intended to be used as an introduction to the Smalltalk
language.
Little Smalltalk is largely (with exceptions listed in a later section)
a subset of the Smalltalk-80\s-2\u*\d\s+2 language described
.FS
* Smalltalk-80 is a trademark of the Xerox Corporation.
.FE
in [.Smalltalk blue.].
A complete description of the classes included in the Little Smalltalk system
and the messages they accept is given in Appendix 1.
.NH 1
Running the system
.PP
The Little Smalltalk system is invoked by typing the command \fBst\fP.
The system is interactive \- that is, the user types an expression at the
keyboard and the system responds by evaluating the expression and typing
the result.
For example,
typing the expression \fB3 + 4\fP results in the value \fB7\fP being
displayed on
the output.  Execution is terminated by typing control\-D.  A sample
execution session is shown in Figure 1.
.KF
.sp
.DS B
% st
Little Smalltalk
    3 + 4
7
    ^D
%
.DE
.sp
.ce
\fBFigure 1:\fP A Sample Little Smalltalk Session
.sp
.KE
.PP
Instance variables for the command level can be created by
assigning a value to a new variable name.  Thereafter that variable can
be used at the command level, although it is not known within the scope
of any method.  The variable ``last'' always contains the value
returned by the last expression typed.
Figure 2 shows the creation of a variable.
Note that the assignment arrow is formed as a two character sequence.
.KF
.sp
.DS B
.ta 5m
    newvar <\(mi 2 / 3
    newvar
0.666667
    2 raisedTo: newvar + (4 / 3)
4
    last
4
.DE
.sp
.ce
\fBFigure 2:\fP Creating Variables
.sp
.KE
.PP
The default behavior is for the value of expressions,
with the exception of assignments, to be typed
automatically as they are evaluated.
This behavior can be modified either by using the \-d flag
(see Appendix 2), or by passing a message to the pseudo
variable \fBsmalltalk\fP (see Appendix 1).
.PP
Class descriptions must be read in from files, they cannot be entered
interactively.  Class descriptions are entered using a system directive.
For example, to include a class description contained in a file named
\fBnewclass.st\fP, the following system directive should be issued:
.sp
.ce
)i newclass.st
.sp
A list of files containing class descriptions can also be given as
arguments to the st command.  The command
.DS B
%st file\s-2\d1\u\s+2 ... file\s-2\dn\u\s+2
.DE
is equivalent to the sequence
.DS B
.ta 5m
%st
Little Smalltalk
    )i file\s-2\d1\u\s+2
    ...
    )i file\s-2\dn\u\s+2
.DE
.PP
A table of system directives is given in Figure 3.
.KF
.sp
.TS
center box;
l lw(4.5i).

)e filename    T{
Edit the named file.  The Little Smalltalk system will suspend, leaving
the user in an editor for making changes to the named file.  Upon leaving
the editor the named file will automatically be included, as if the )i
directive had been typed.
T}

)g filename    T{
Search for an entry in the system library area matching the filename.
If found, the class descriptions in the library entry are included.
This command is useful for including commonly used classes that are not
part of the standard prelude, such as classes for statistics applications
or graphics.
T}

)i filename    T{
Include the named file.  The file must contain one or more class descriptions.
The class descriptions are parsed, and if syntactically legal new
instances of class \fBClass\fP are added to the Smalltalk system.
T}

)l filename    T{
Load a previously saved environment from the named file.
The current values of all variables are overridden.
The file must have been created using the )s directive (below).
T}

)r filename    T{
Read the named file.  The file must contain Smalltalk statements, as
would be typed at the keyboard.  The effect is just as if the lines
of the file had been typed at the keyboard.  The file cannot contain
class descriptions.
T}

)s filename    T{
Save the current state in the named file.  The values of all variables
are saved, and can later be reloaded using the )l directive (above).
T}

)!string    T{
Execute the remainder of the line following the exclamation point
as a Unix\s-2\u*\d\s+2 command.  Nothing is done with the output of the command,
nor is the returning status of the command recorded.
T}

.TE
.sp
.ce
\fBFigure 3:\fP System Directives
.sp
.KE
.PP
Note that the )e system directive invokes an editor on a file
containing class descriptions, and then automatically includes the file
when the editor is exited.
Classes also respond to the message \fBedit\fP, which will have the same
effect as the )e directive applied to the file containing the class
description.
Thus the typical debug/edit/debug cycle
involves repeated uses of the )e directive or the \fBedit\fP message
until a desired outcome is achieved.
The editor invoked by the )e directive can be changed by setting
the EDITOR variable in the users environment.
.NH 1
Differences between Little Smalltalk and the Smalltalk-80 system
.PP
This section describes the differences between the language accepted by
the Little Smalltalk system and the language described in
[.Smalltalk blue.].  The principal reasons for these changes are
as follows:
.IP size 6.5m
Classes which are largely unnecessary, or which could be easily
simulated by other classes (e.g. Association, SortedCollection) have
been eliminated in the interest of keeping the size of the standard
library as small as possible.  Similarly, indexed instance variables are
not supported, since to do so would increase the size of every object in
the system, and they can be easily simulated in those classes in which
they are important (see below).
.IP portability
Classes which depend upon particular hardware (e.g. BitBlt) are not included
as part of the Little Smalltalk system.  The basic system assumes nothing
more than ascii terminals.
.IP representation
The need for a textual representation for class descriptions required some
small additions to the syntax for class methods (see Appendix 3).
Similarly, the fact that classes and subclasses can be separately parsed,
in either order, forced some changes in the scoping rules for instance
variables.
.PP
The following sections describe these changes in more detail.
.NH 2
No Browser
.PP
The Smalltalk-80 Programming Environment described in [.Smalltalk orange.]
is not included as part of the Little Smalltalk system.  The Little
Smalltalk system is designed to be little, easily portable, and to
rely on nothing more than basic terminal capabilities.
.NH 2
Internal Representation Different
.PP
The internal representations of objects, including processes, interpreters,
and bytecodes, is entirely different in the Little Smalltalk system from
the Smalltalk-80 system described in [.Smalltalk blue.].
.FS
* Unix is a trademark of Bell Laboratories.
.FE
.NH 2
Fewer Classes
.PP
Many of the classes described in [.Smalltalk blue.] are not included as
part of the Little Smalltalk basic system.  Some of these are not
necessary because of the decision not to include the editor, browser,
and so on as part of the basic system.  Others are omitted in the interest
of keeping the standard library of classes small.  A complete list
of included classes for the Little Smalltalk system is given in Appendix 1.
.NH 2
No Class Protocol
.PP
Protocol for all classes is defined as part of class \fBClass\fP.
It is not possible to redefine class protocol as part of a class description,
only instance protocol.
The notion of metaclasses is not supported.
.NH 2
Cascades Different
.PP
The semantics of cascades has been simplified and generalized.
The result of a cascaded expression is always the result of the expression
to the left of the first semicolon, which is also the receiver for each
subsequent continuation.  Continuations can include multiple messages.
A rather nonsensical, but illustrative, example is the following:
.DS B
2 + 3 ; \(mi 7 + 3 ; * 4
.DE
.LP
The result of this expression is 5 (the value yielded by 2 + 3).  5 is also
the receiver for the message \(mi 7, and that result (\(mi2) is in turn the
receiver for the message + 3.  This last result is thrown away.  5 is then
again used as the receiver for the message * 4, the result of which is also
thrown away.
.NH 2
Instance Variable Name Scope
.PP
In the language described in [.Smalltalk blue.], an instance variable is
known not only to the class protocol in which it is declared, but is also
valid in methods defined for any subclasses of that class.
In the Little Smalltalk system an instance variable can be referenced only
within the protocol for the class in which it is declared.
.NH 2
Indexed Instance Variables
.PP
Implicitly defined indexed instance variables are not supported.
In any class for which these are desired they can be easily simulated by
including an additional instance variable, containing an Array, and
including the following methods:
.DS B
.ta 4m 8m
Class Whatever
| indexVars |
[
    new: size
        indexVars <\(mi Array new: size

|    at: location
        \(ua indexVars at: location

|    at: location put: value
        indexVars at: location put: value

    ...
.sp
.DE
.PP
The message new: can be used with any class, with an effect similar to
new.  That is, if a new instance of the class is created by sending the
message new: to the class variable, the message is immediately passed
on to the new instance, and the result returned is used as the result of
the creation message.
.NH 2
No Pool Variables
.PP
The concepts of pool variables, global variables, or class variables are
not supported.
In their place there is a new pseudo-variable, \fBsmalltalk\fP, which
responds to the messages \fBat:\fP and \fBat:put:\fP.
The keys for this collection can be arbitrary.
Although this facility is available, its use is often a sign of poor
program design, and should be avoided.
.NH 2
No Associations
.PP
The class Dictionary stores keys and values separately, rather than
as instances of Association.  The class Association, and all messages
referring to Associations have been removed.
.NH 2
Generators in place of Streams
.PP
The notion of stream has been replaced by the slightly different notion of
\fIgenerators\fP, in particular the use of the messages \fIfirst\fP
and \fInext\fP in subclasses of \fBCollection\fP.
External files are supported by an explicit class \fBFile\fP.
.NH 2
Primitives Different
.PP
Both the syntax and the use of primitives has been changed.
Primitives provide an interface between the Smalltalk world and the
underlying system, permitting the execution of operations that cannot be
specified in Smalltalk.  In Little Smalltalk, primitives cannot fail and
must return a value (although they may, in error situations, print an error
message and return \fBnil\fP).
The syntax for primitives has been altered to permit the specification of
primitives with an arbitrary number of arguments.  The format for a
primitive call is as follows:
.DS B
<primitive \fBnumber\fP \fIargumentlist\fP >
.DE
Where \fBnumber\fP is the number of the primitive to be executed
(which must be a value between 1 and 255),
and \fIargumentlist\fP is a list of Smalltalk primary expressions (see
Appendix 2).  Appendix 4 lists the meanings of each of the currently
recognized primitive numbers.
.NH 2
Byte Arrays
.PP
A new syntax has been created for defining an array composed entirely of
unsigned integers in the range 0-255.  These arrays are given a very
tight encoding.  The syntax is a pound sign, followed by a left square
brace, followed by a sequence of numbers in the range 0 to 255, followed by
a right square brace.
.DS B
#[ \fInumbers\fP ]
.DE
.LP
Byte Arrays are used extensively internally.
.NH 2
New Pseudo Variables
.PP
In addition to the pseudo variable \fBsmalltalk\fP already mentioned,
another pseudo variable, \fBselfProcess\fP, has beed added to the Little
Smalltalk system.  \fBselfProcess\fP returns the currently executing process,
which can then be passed as an argument to a semaphore, or
be used as a receiver for a message valid for class \fBProcess\fP.
Like \fBself\fP and \fBsuper\fP, \fBselfProcess\fP cannot be used at
the command level.
.NH 2
No Dependency
.PP
The notion of dependency, and automatic dependency updating, is not
included in Little Smalltalk.
.[]
.ds CH
.bp
.SH
.ce 2
Appendix 1
Class Descriptions
.PP
The messages accepted by the classes included in the Little Smalltalk
standard library are described in the following pages.
A list of the classes
defined, where indentation is used to imply subclassing, is given below:
.DS I
.ta 3m 6m 9m 12m 15m
Object
    UndefinedObject
    Symbol
    Boolean
        True
        False
    Magnitude
        Char
        Number
            Integer
            Float
        Radian
        Point
    Random
    Collection
        Bag
        Set
        KeyedCollection
            Dictionary
                Smalltalk
            File
            SequenceableCollection
                Interval
                LinkedList
                    Semaphore
                File
                ArrayedCollection
                    Array
                    ByteArray
                    String
    Block
    Class
    Process
.DE
.PP
In the descriptions of each message the following notes may occur:
.IP \fId\fP
Indicates the effect of the message differs slightly from that given
in [.Smalltalk blue.].
.IP \fIn\fP
Indicates the message is not included as part of the language defined
in [.Smalltalk blue.].
.IP \fIr\fP
Indicates the protocol for the message overrides a protocol given in
some superclass.  Only where the logical effect of this overriding is
important is the message given a second time; some messages, such as
copy, are overridden in many classes but are not described in the documentation
because the logical effect remains the same.
.bp
.SH
.ce 2
Appendix 2
Man Page
.PP
A Unix man page for the st command is given on the following page.
.bp
.SH
.ce 2
Appendix 3
Syntax Charts
.PP
Syntax charts for the language accepted by the Little Smalltalk system
are described on the following pages.
The following is an example class description:
.DS B
Class Set :Collection
| dict |
[
        new
                dict <\(mi Dictionary new

|       add: newElement
                dict at: newElement
                     ifAbsent: [dict at: newElement put: 1]

|       remove: oldElement ifAbsent: exceptionBlock
        dict removeKey: oldElement ifAbsent: exceptionBlock

|       size
                \(ua dict size

|       occurrencesOf: anElement
                \(ua dict at: anElement ifAbsent: [0]

|       first
                dict first.
        \(ua dict currentKey

|       next
                dict next.
        \(ua dict currentKey

]
.DE
.bp
.SH
.ce 2
Appendix 4
Primitive Numbers
.PP
The following chart gives the function performed by each primitive in the
Little Smalltalk system.
.SH
Information about objects
.IP 0
(not used )
.IP 1
class of an object
.IP 2
superobject of an object
.IP 3
test if class responds to new
.IP 4
size of object
.IP 5
hash value
.IP 6
test if two built-in objects are of the same type
.IP 7
object equality testing ( == )
.IP 8
various switch toggles
.IP 9
numerical generality testing
.SH
Integer manipulation
.IP 10
integer addition (both args must be integer)
.IP 11
integer subtraction
.IP 12
integer < test
.IP 13
integer > test
.IP 14
integer \(<= test
.IP 15
integer \(>= test
.IP 16
integer = test
.IP 17
integer ~= test
.IP 18
integer multiplication
.IP 19
integer //
.SH
Bit manipulation and other integer valued functions
.IP 20
gcd:
.IP 21
bitAt:
.IP 22
bitOr:
.IP 23
bitAnd:
.IP 24
bitXor:
.IP 25
bitShift:
.IP 26
radix:
.IP 27
not used
.IP 28
integer quo:
.IP 29
integer rem:
.SH
Other integer functions
.IP 30
doPrimitive:withArguments:
.IP 31
not used
.IP 32
convert random integer to random float
.IP 33
bitInvert
.IP 34
highBit
.IP 35
randomNumber (argument is seed )
.IP 36
asCharacter
.IP 37
asString
.IP 38
factorial
.IP 39
asFloat
.SH
Character manipulation
.IP 40
not used
.IP 41.
not used
.IP 42
character < test
.IP 43
character > test
.IP 44
character \(<= test
.IP 45
character \(>= test
.IP 46
character = test
.IP 47
character ~= test
.IP 48
not used
.IP 49
not used
.SH
Character unary functions
.IP 50
digitValue
.IP 51
isVowel
.IP 52
isLetter
.IP 53
isLowerCase
.IP 54
isUpperCase
.IP 55
isSeparator
.IP 56
isAlphaNumeric
.IP 57
caseShift
.IP 58
asString
.IP 59
asciiValue
.SH
Floating point manipulation
.IP 60
floating point addition (both args must be float)
.IP 61
floating point subtraction
.IP 62
floating point < test
.IP 63
floating point > test
.IP 64
floating point \(<= test
.IP 65
floating point \(>= test
.IP 66
floating point = test
.IP 67
floating point ~= test
.IP 68
floating point multiplication
.IP 69
floating point division
.SH
Other floating point operations
.IP 70
ln
.IP 71
sqrt
.IP 72
floor
.IP 73
ceiling
.IP 74
not used
.IP 75
integerPart
.IP 76
fractionalPart
.IP 77
gamma
.IP 78
asString
.IP 79
exp
.SH
Other numerical functions
.IP 80
normalize number to be within 0 and 2\(*p.
.IP 81
sin
.IP 82
cos
.IP 83
not used
.IP 84
arcSin
.IP 85
arcCos
.IP 86
arcTan
.IP 87
not used
.IP 88
raisedTo:
.IP 89
radix:
.SH
Symbol Commands
.IP 90.
not used
.IP 91
symbol comparison, returns true or false.
.IP 92
printString
.IP 93
asString
.IP 94
print (used internally)
.IP 95
not used
.IP 96
not used
.IP 97
build a new class, arguments are class name, superclass name, instance
variables, messages, methods, context size.
.IP 98
insert an object into class dictionary, first argument is symbol,
second argument is class definition
.IP 99
find an object in class dictionary.  argument is symbol.
.SH
String operations
.IP 100
string length
.IP 101
string compare, case important \- return \(mi1, 0 or 1.
.IP 102
string compare, case not important
.IP 103
string catenation
.IP 104
string at:
.IP 105
string at:put:
.IP 106
copyFrom:length:
.IP 107
copy (new string with same chars)
.IP 108
asSymbol
.IP 109
string printString
.SH
Array manipulation
.IP 110
build an untyped object of given size, argument is integer size.
.IP 111
index variable get (first argument is object, second is index)
.IP 112
index variable put (first argument is object, second is index,
third argument is expression)
.IP 113
object grow (returns a new object with same instance variable values
as first argument, but with second argument tacked on end as new instance variable)
.IP 114
build an instance of \fBArray\fP of the given size.
.IP 115
new string of given size
.IP 116
ByteArray new:
.IP 117
ByteArray size
.IP 118
ByteArray at:
.IP 119
ByteArray at:put:
.SH
Output and error messages
.IP 120
print string with no return
.IP 121
print string with return
.IP 122
general error - first argument is receiver, second is error string
.IP 123
print string on error output (with return)
.IP 124
not used
.IP 125
unix system call
.IP 126
print a string at a specific point on the terminal
.IP 127
block return without surrounding context
.IP 128
reference count less than zero, first argument is guilty object
.IP 129
does not respond error, first argument is receiver, second is message.
.SH
File operations
.IP 130
file open, first argument is name, second argument is mode
.IP 131
file read
.IP 132
file write
.IP 133
set file mode, first argument is file, second is mode indicator (anInteger)
.IP 134
compute file size in bytes
.IP 135
file set location (at:) second argument is location (anInteger)
.IP 136
return current file offset in bytes
.IP 137
not used
.IP 138
not used
.IP 139
not used
.SH
Process management
.IP 140
block execute (trapped by interpreter)
.IP 141
new process (withArguments:)
.IP 142
terminate a process
.IP 143
perform:withArguments: (trapped by interpreter)
.IP 144.
not used
.IP 145
set state
.IP 146
return state
.IP 148
start atomic action
.IP 149
end atomic action
.SH
Operations on classes
.IP 150
class edit
.IP 151
superclass of a class
.IP 152
class name (a Symbol)
.IP 153
new instance of a class
.IP 154
list all commands class responds to
.IP 155
respondsTo: , second argument is a symbol
.IP 156
class view (drop into editor, but no include)
.IP 157
class list
.IP 158
variables (returns an array of symbols)
.IP 159
not used
.SH
Date and Time
.IP 160
current date and time as string
.IP 161
seconds time counter
.IP 162
clear the screen
.SH
Plot(3) interface
.IP 170
clear the screen
.IP 171
move the cursor (move(x,y))
.IP 172
draw a line (cont(x,y))
.IP 173
draw a point (point(x,y))
.IP 174
draw a circle (circle(x,y,r))
.IP 175
draw an arc (arc(x,y,x0,y0,x1,y1))
.IP 176
establish the coordinate space (space(a,b,c,d))
.IP 177
draw a line (line(a,b,c,d))
.IP 178
print a label (label(s))
.IP 179
establish a line type (linemod(s))
End
echo unbundling apndx1 1>&2
cat >apndx1 <<'End'
.so macros
.nh
.ds CF
.ds CH
.ps +0.2i
.nr PO +0.2i
.Nm Object
.PP
The class \fBObject\fP is a superclass of all classes in the system, and is
used to provide a consistent basic functionality and default behavior.
Many methods in class \fBObject\fP are overridden in subclasses.
.SH
Responds to
.Rs ==
Return true if receiver and argument are the
same object, false otherwise.
.Rs ~~
Inverse of ==.
.Rs asString
Return a string representation of the receiver,
by default this is the same as \fIprintString\fP, although one or the
other is redefined in many subclasses.
.Rs asSymbol
Return a symbol representing the receiver.
.Rs class
Return object representing the class of the receiver.
.Rs copy
Return shallowCopy of receiver.
Many subclasses redefine shallowCopy.
.Rs deepCopy
Return the receiver.  This method is redefined in many sub\%classes.
.Rs do: d
The argument must be a one argument block.
Execute the block on every element of the receiver collection.
Elements in the receiver collection are listed using \fIfirst\fP and \fInext\fP
(below), so the default behavior is merely to execute the block using the
receiver as argument.
.Rs error:
Argument must be a String.  Print argument string as error message.
Return \fBnil\fP.
.Rs first n
Return first item in sequence, which is by default simply the receiver.
See \fInext\fP, below.
.Rs isKindOf:
Argument must be a \fBClass\fP.  Return true if class of receiver, or any
superclass thereof, is the same as argument.
.Rs isMemberOf:
Argument must be a \fBClass\fP.  Return true if receiver is instance of
argument class.
.Rs isNil
Test whether receiver is object \fBnil\fP.
.Rs next n
Return next item in sequence, which is by default \fBnil\fP.  This message is
redefined in classes which represent sequences, such as \fBArray\fP
or \fBDictionary\fP.
.Rs notNil
Test if receiver is not object \fBnil\fP.
.Rs print
Display print image of receiver on the standard output.
.Rs printString
Return a string representation of receiver.
Objects which do not redefine printString, and which therefore do not have
a printable representation, return their class name as a string.
.Rs respondsTo:
Argument must be a symbol.  Return true if receiver will respond to
the indicated message.
.Rs shallowCopy
Return the receiver.  This method is redefined in many sub\%classes.
.Ex
7 ~~ 7.0    True
7 asSymbol    #7
7 class    Integer
7 copy    7
7 isKindOf: Number    True
7 isMemberOf: Number    False
7 isNil    False
7 respondsTo: #+    True
.Nm Object UndefinedObject
.PP
The pseudo variable \fBnil\fP is an instance (usually the only instance) of the
class \fBUndefinedObject\fP.  \fBnil\fP is used to represent undefined values,
and is
also typically returned in error situations.  \fBnil\fP is also used as a terminator
in sequences, as for example in response to the message \fInext\fP when there are
no further elements in a sequence.
.SH
Responds to
.Rs isNil r
Overrides method found in Object.  Return true.
.Rs notNil r
Overrides method found in Object.  Return false.
.Rs printString r
Return 'nil'.
.Ex
nil isNil    True
.Nm Object Symbol
.PP
Instances of the class \fBSymbol\fP are created either by their literal
representation, which is a pound sign followed by a string of nonspace
characters (for example #aSymbol ),
or by the message \fIasSymbol\fP being passed to an object.
Symbols cannot be created using \fInew\fP.  Symbols are guaranteed to have
unique representations; that is, two symbols representing the same
characters will always test equal to each other.  Inside of literal
arrays, the leading pound signs on symbols can be eliminated, for example:
#(these are symbols).
.SH
Responds to
.Rs == r
Return true if the two symbols represent the same characters,
false otherwise.
.Rs asString r
Return a String representation of the symbol without the leading pound
sign.
.Rs printString r
Return a String representation of the symbol, including the leading pound
sign.
.Ex
#abc == #abc    True
#abc == #ABC    False
#abc ~~ #ABC    True
#abc printString    #abc
\&'abc' asSymbol    #abc
.Nm Object Boolean
.PP
The class \fBBoolean\fP provides protocol for manipulating true and false values.
The pseudo variables \fBtrue\fP and \fBfalse\fP are instances of the subclasses of
\fBBoolean\fP; \fBTrue\fP and \fBFalse\fP, respectively.
The subclasses \fBTrue\fP and \fBFalse\fP, in combination with blocks, are used to
implement conditional control structures.  Note, however, that the
bytecodes may optimize conditional tests by generating
code in-line, rather than using message passing.
Note that bit-wise boolean operations are provided by class \fBInteger\fP.
.SH
Responds To
.Rs &
The argument must be a boolean.  Return the logical conjunction (and)
of the two values.
.Rs |
The argument must be a boolean.  Return the logical disjunction (or)
of the two values.
.Rs and:
The argument must be a block.  Return the logical conjunction (and)
of the two values.  If the receiver is false the second argument is not
used, otherwise the result is the value yielded in evaluating the argument
block.
.Rs or:
The argument must be a block.  Return the logical disjunction (or)
of the two values.  If the receiver is true the second argument is not
used, otherwise the result is the value yielded in evaluating the argument
block.
.Rs eqv:
The argument must be a boolean.  Return the logical equivalence (eqv)
of the two values.
.Rs xor:
The argument must be a boolean.  Return the logical exclusive or (xor)
of the two values.
.Ex
(1 > 3) & (2 < 4)    False
(1 > 3) | (2 < 4)    True
(1 > 3) and: [2 < 4]    False
.Nm Object Boolean True
.PP
The pseudo variable \fBtrue\fP is an instance (usually the only instance) of
the class \fBTrue\fP.
.SH
Responds To
.Rs ifTrue:
Return the result of evaluating the argument block.
.Rs ifFalse:
Return \fBnil\fP.
.Rs ifTrue:ifFalse:
Return the result of evaluating the first argument block.
.Rs ifFalse:ifTrue:
Return the result of evaluating the second argument block.
.Rs not
Return \fBfalse\fP.
.Ex
(3 < 5) not    False
(3 < 5) ifTrue: [17]    17
.Nm Object Boolean False
.PP
The pseudo variable \fBfalse\fP is an instance (usually the only instance) of
the class \fBFalse\fP.
.Rs ifTrue:
Return \fBnil\fP.
.Rs ifFalse:
Return the result of evaluating the argument block.
.Rs ifTrue:ifFalse:
Return the result of evaluating the second argument block.
.Rs ifFalse:ifTrue:
Return the result of evaluating the first argument block.
.Rs not
Return \fBtrue\fP.
.Ex
(1 < 3) ifTrue: [17]    17
(1 < 3) ifFalse: [17]    nil
.Nm Object Magnitude
.PP
The class \fBMagnitude\fP provides protocol for those subclasses possessing
a linear ordering.  For the sake of efficiency, most subclasses redefine
some or all of the relational messages.  All methods are defined in
terms of the basic messages <, = and >, which are in turn defined
circularly in terms of each other.  Thus each subclass of \fBMagnitude\fP
must redefine at least one of these messages.
.Rs <
Relational less than test.  Returns a boolean.
.Rs <=
Relational less than or equal test.
.Rs =
Relational equal test.  Note that this differs from ==, which is
an object equality test.
.Rs ~=
Relational not equal test, opposite of =.
.Rs >=
Relational greater than or equal test.
.Rs >
Relational greater than test.
.Rs between:and:
Relational test for inclusion.
.Rs max:
Return the maximum of the receiver and argument value.
.Rs min:
Return the minimum of the receiver and argument value.
.Ex
$A max: $a    $a
4 between: 3.1 and: (17/3)    True
.Nm Object Magnitude Char
.PP
This class defines protocol for objects with character values.
Characters possess an ordering given by the underlying representation,
however arithmetic is not defined for character values.
Characters are written literally by preceding the character desired with
a dollar sign, for example: $a \0 $B \0 $$.
.SH
Responds to
.Rs == r
Object equality test.  Two instances of the same character always test equal.
.Rs asciiValue
Return an \fBInteger\fP representing the ascii value of the receiver.
.Rs asLowercase
If the receiver is an uppercase letter returns the same letter in lowercase,
otherwise returns the receiver.
.Rs asUppercase
If the receiver is a lowercase letter returns the same letter in uppercase,
otherwise returns the receiver.
.Rs asString r
Return a length one string containing the receiver.
Does not contain leading dollar sign, compare to \fIprintString\fP.
.Rs digitValue
If the receiver represents a number (for example $9) return the digit value
of the number.  If the receiver is an uppercase letter (for example $B) return
the position of the number in the uppercase letters + 10, ($B returns 11, for
example).  If the receiver is neither a digit nor an uppercase letter an
error is given and \fBnil\fP returned.
.Rs isAlphaNumeric
Respond true if receiver is either digit or letter, false otherwise.
.Rs isDigit
Respond true if receiver is a digit, false otherwise.
.Rs isLetter
Respond true if receiver is a letter, false otherwise.
.Rs isLowercase
Respond true if receiver is a lowercase letter, false otherwise.
.Rs isSeparator
Respond true if receiver is a space, tab or newline, false otherwise.
.Rs isUppercase
Respond true if receiver is an uppercase letter, false otherwise.
.Rs isVowel
Respond true if receiver is $a, $e, $i, $o or $u, in either
upper or lower case.
.Rs printString r
Respond with a string representation of the character value.
Includes leading dollar sign, compare to \fIasString\fP, which does not include $.
.Ex
$A < $0    False
$A asciiValue    65
$A asString    A
$A printString    $A
$A isVowel    True
$A digitValue    10
.Nm Object Magnitude Number
.PP
The class \fBNumber\fP is an abstract superclass for \fBInteger\fP and \fBFloat\fP.
Instances of \fBNumber\fP cannot be created directly.
Relational messages and many arithmetic messages are redefined in each
subclass for arguments of the appropriate type.  In general, an error message
is given and \fBnil\fP returned for illegal arguments.
.SH
Responds To
.Rs +
Mixed type addition.
.Rs \(mi
Mixed type subtraction.
.Rs *
Mixed type multiplication
.Rs /
Mixed type division.
.Rs \(ua n
Exponentiation, same as raisedTo: .
.Rs @
Construct a point with coordinates being the receiver and the argument.
.Rs abs
Absolute value of the receiver.
.Rs exp
e raised to the power.
.Rs gamma n
Return the gamma function (generalized factorial) evaluated at the
receiver.
.Rs ln
Natural logarithm of the receiver.
.Rs log:
Logarithm in the given base.
.Rs negated
The arithmetic inverse of the receiver.
.Rs negative
True if the receiver is negative.
.Rs pi n
Return the approximate value of the receiver multiplied by \*(p (3.1415926...).
.Rs positive
True if the receiver is positive.
.Rs radians n
Argument converted into radians.
.Rs raisedTo:
The receiver raised to the argument value.
.Rs reciprocal
The arithmetic reciprocal of the receiver.
.Rs roundTo:
The receiver rounded to units of the argument.
.Rs sign
Return \(mi1, 0 or 1 depending upon whether the receiver is negative, zero or
positive.
.Rs sqrt
Square root.  nil if receiver is less than zero.
.Rs squared
Return the receiver multiplied by itself.
.Rs strictlyPositive
True if the receiver is greater than zero.
.Rs to:
Interval from receiver to argument value with step of 1.
.Rs to:by:
Interval from receiver to argument in given steps.
.Rs truncatedTo:
The receiver truncated to units of the argument.
.Ex
3 < 4.1    True
3 + 4.1    7.1
3.14159 exp    23.1406
9 gamma    40320
5 reciprocal    0.2
0.5 radians    0.5 radians
13 roundTo: 5    15
13 truncateTo: 5    10
.Nm Object Magnitude Number Integer
.PP
The class \fBInteger\fP provides protocol for objects with integer values.
.SH
Responds To
.Rs == r
Object equality test.  Two integers representing the same value are
considered to be the same object.
.Rs //
Integer quotient, truncated towards negative infinity (compare to \fIquo:\fP).
.Rs \e\e
Integer remainder, truncated towards negative infinity (compare to \fIrem:\fP).
.Rs allMask:
Argument must be \fBInteger\fP.  Treating receiver and argument as bit strings,
return \fBtrue\fP if all bits with 1 value in argument correspond to bits with 1
values in the receiver.
.Rs anyMask:
Argument must be \fBInteger\fP.  Treating receiver and argument as bit strings,
return true if any bit with 1 value in argument corresponds to a bit with
1 value in the receiver.
.Rs asCharacter
Return the Char with the same underlying ascii representation as the low
order eight bits of the receiver.
.Rs asFloat
Floating point value with same magnitude as receiver.
.Rs bitAnd:
Argument must be \fBInteger\fP.  Treating the receiver and argument as bit strings,
return logical \fBand\fP of values.
.Rs bitAt:
Argument must be \fBInteger\fP greater than 0 and less than underlying word size.
Treating receiver as a bit string, return the bit value at the given position,
numbering from low order (or rightmost) position.
.Rs bitInvert
Return the receiver with all bit positions inverted.
.Rs bitOr:
Return logical \fBor\fP of values.
.Rs bitShift:
Treating the receiver as a bit string, shift bit values by amount indicated
in argument.  Negative values shift right, positive left.
.Rs bitXor:
Return logical \fBexclusive-or\fP of values.
.Rs even
Return true if receiver is even, false otherwise.
.Rs factorial
Return the factorial of the receiver.  Return as Float for large numbers.
.Rs gcd:
Argument must be \fBInteger\fP.  Return the greatest common divisor of the
receiver and argument.
.Rs highBit
Return the location of the highest 1 bit in the receiver.
Return \fBnil\fP for receiver zero.
.Rs lcm:
Argument must be \fBInteger\fP.  Return least common multiple of receiver and
argument.
.Rs noMask:
Argument must be \fBInteger\fP.  Treating receiver and argument as bit strings,
return true if no 1 bit in the argument corresponds to a 1 bit in the receiver.
.Rs odd
Return true if receiver is odd, false otherwise.
.Rs quo:
Return quotient of receiver divided by argument.
.Rs radix:
Return a string representation of the receiver value, printed in the base
represented by the argument.  Argument value must be less than 36.
.Rs rem:
Remainder after receiver is divided by argument value.
.Rs timesRepeat:
Repeat argument block the number of times given by the receiver.
.Ex
5 + 4    7
5 allMask: 4    True
4 allMask: 5    False
5 anyMask: 4    True
5 bitAnd: 3    1
5 bitOr: 3    7
5 bitInvert    \(mi6
254 radix: 16    16rFE
\(mi5 // 4    \(mi2
\(mi5 quo: 4    \(mi1
\(mi5 \e\e 4    1
\(mi5 rem: 4    \(mi1
8 factorial    40320
.Nm Object Magnitude Number Float
.PP
The class \fBFloat\fP provides protocol for objects with floating point values.
.SH
Responds To
.Rs == r
Object equality test.  Return true if the receiver and argument
represent the same floating point value.
.Rs \(ua n
Floating exponentiation.
.Rs arcCos
Return a \fBRadian\fP representing the arcCos of the receiver.
.Rs arcSin
Return a \fBRadian\fP representing the arcSin of the receiver.
.Rs arcTan
Return a \fBRadian\fP representing the arcTan of the receiver.
.Rs  asFloat
Return the receiver.
.Rs ceiling
Return the Integer ceiling of the receiver.
.Rs coerce:
Coerce the argument into being type Float.
.Rs exp
Return e raised to the receiver value.
.Rs floor
Return the Integer floor of the receiver.
.Rs fractionPart
Return the fractional part of the receiver.
.Rs gamma n
Return the value of the gamma function applied to the receiver value.
.Rs integerPart
Return the integer part of the receiver.
.Rs ln
Return the natural log of the receiver.
.Rs radix:
Return a string containing the printable representation of the receiver
in the given radix.  Argument must be an Integer less than 36.
.Rs rounded
Return the receiver rounded to the nearest integer.
.Rs sqrt
Return the square root of the receiver.
.Rs truncated
Return the receiver truncated to the nearest integer.
.Ex
4.2 * 3    12.6
2.1 \(ua 4    19.4481
2.1 raisedTo: 4    19.4481
0.5 arcSin    0.523599 radians
2.1 reciprocal    0.47619
4.3 sqrt    2.07364
.Nm Object Magnitude Radian
.PP
The class \fBRadian\fP is used to represent radians.  Radians are a unit of
measurement, independent of other numbers.
Only radians will responds to the trigonometric functions
such as \fIsin\fP and \fIcos\fP.
Numbers can be converted into
radians by passing them the message \fIradians\fP.  Similarly, radians
can be converted into numbers by sending them the message \fIasFloat\fP.
Notice that only a limited range of arithmetic operations are permitted on
Radians.
Radians are normalized to be between 0 and 2\(*p.
.SH
Responds to
.Rs +
Argument must be a Radian.  Add the two radians together and return the
normalized result.
.Rs \(mi
Argument must be a Radian.  Subtract the argument from the receiver and
return the normalized result.
.Rs *
Argument must be a Number.  Multiply the receiver by the argument amount
and return the normalized result.
.Rs /
Argument must be a Number.  Divide the receiver by the argument amount
and return the normalized result.
.Rs asFloat
Return the receiver as a floating point number.
.Rs cos
Return a floating point number representing the cosine of the
receiver.
.Rs sin
Return a floating point number representing the sine of the receiver.
.Rs tan
Return a floating point number representing the tangent of the receiver.
.Ex
0.5236 radians sin    0.5
0.5236 radians cos    0.866025
0.5236 radians tan    0.577352
0.5 arcSin asFloat    0.523599
.Nm Object Magnitude Point
.PP
\fBPoint\fPs are used to represent pairs of quantities, such as coordinate
pairs.
.SH
Responds To
.Rs <
True if both values of the receiver are less than the corresponding values
in the argument.
.Rs <=
True if the first value is less than or equal to the corresponding value in
the argument, and the second value is less than the corresponding value in
the argument.
.Rs >=
True if both values of the receiver are greater than or equal to the
corresponding values in the argument.
.Rs *
Return a new point with coordinates multiplied by the argument value.
.Rs /
Return a new point with coordinates divided by the argument value.
.Rs //
Return a new point with coordinates divided by the argument value.
.Rs +
Return a new point with coordinates offset by the corresponding values in
the argument.
.Rs abs
Return a new point with coordinates having the absolute value of the
receiver.
.Rs dist:
Return the Euclidean distance between the receiver and the argument
point.
.Rs max:
The argument must be a \fBPoint\fP.
Return the lower right corner of the rectangle defined by the receiver and
the argument.
.Rs min:
The argument must be a \fBPoint\fP.
Return the upper left corner of the rectangle defined by the receiver and
the argument.
.Rs transpose
Return a new point with coordinates being the transpose of the receiver.
.Rs x
Return the first coordinate of the receiver.
.Rs x:
Set the first coordinate of the receiver.
.Rs x:y:
Sets both coordinates of the receiver.
.Rs y
Return the second coordinate of the receiver.
.Rs y:
Set the second coordinate of the receiver.
.Ex
(10@12) < (11@14)    True
(10@12) < (11@11)    False
(10@12) max: (11@11)    11@12
(10@12) min: (11@11)    10@11
(10@12) dist: (11@14)    2.23607
(10@12) transpose    12@10
.Nm Object Random
.PP
The class \fBRandom\fP provides protocol for random number generation.  Sending
the message \fInext\fP to an instance of \fBRandom\fP results in a \fBFloat\fP
between 0.0 and 1.0, randomly distributed.
By default, the pseudo random sequence is the same for each object in class
\fBRandom\fP.  This can be altered using the message \fIrandomize\fP.
.SH
Responds To
.Rs between:and: n
Return a random number uniformly distributed between the two arguments.
.Rs first n
Return a random number between 0.0 and 1.0.
This message merely provides consistency with protocol for other sequences,
such as Arrays or Intervals.
.Rs next
Return a random number between 0.0 and 1.0.
.Rs next: d
Return an \fBArray\fP containing the next n random numbers, where n
is the argument value.
.Rs randInteger: n
The argument must be an integer.  Return a random integer between 1 and the
value given.
.Rs randomize n
Change the pseudo-random number generator seed by a time dependent value.
.Ex
i \(<- Random new
i next    0.759
i next    0.157
i next: 3    #( 0.408 0.278 0.547 )
i randInteger: 12    5
i between: 4 and: 17.5    10.0
.Nm Object Collection
.PP
The class \fBCollection\fP provides protocol for groups of objects, such as
\fBArray\fPs or \fBSet\fPs.
The different forms of collections are distinguished by several
characteristics, among them whether the size of the collection is fixed
or unbounded, the presence or absence of an ordering, and their insertion
or access method.  For example, an \fBArray\fP is a collection with a
fixed size and ordering, indexed by integer keys.  A \fBDictionary\fP, on the
other hand, has no fixed size or ordering, and can be indexed by
arbitrary elements.  Nevertheless, \fBArrays\fP and \fBDictionarys\fP share many
features in common, such as their access method (\fIat:\fP and \fPat:put:\fP),
and the ability to respond to \fIcollect:\fP, \fIselect:\fP, and many other
messages.
.PP
The table below lists some of the characteristics of several forms of
collections:
.TS
center box;
l c c c c c.

Name    Creation    Size    Ordered?    Insertion    Access
    Method    fixed?        method    method

_

Bag/Set    new    no    no    add:    includes:

Dictionary    new    no    no    at:put:    at:

Interval    n to: m    yes    yes    none    at:

List    new    no    yes    addFirst:    first
                addLast:    last

Array    new:    yes    yes    at:put:    at:

String    new:    yes    yes    at:put:    at:

.TE
.PP
The list below shows messages that are shared in common by all collections.
.SH
Responds to
.Rs addAll:
The argument must be a \fBCollection\fP.
Add all the elements of the argument collection to the receiver collection.
.Rs asArray
Return a new collection of type \fBArray\fP containing the elements from
the receiver collection.  If the receiver was ordered, the elements will
be in the same order in the new collection, otherwise the elements will
be in an arbitrary order.
.Rs asBag
Return a new collection of type \fBBag\fP containing the elements from
the receiver collection.
.Rs asList n
Return a new collection of type \fBList\fP containing the elements from
the receiver collection.  If the receiver was ordered, the elements will
be in the same order in the new collection, otherwise the elements will
be in an arbitrary order.
.Rs asSet
Return a new collection of type \fBSet\fP containing the elements from
the receiver collection.
.Rs asString
Return a new collection of type \fBString\fP containing the elements from the
receiver collection.  The elements to be included must all be of type
\fBCharacter\fP.  If the receiver was ordered, the elements will be in the same
order in the new collection, otherwise the elements will be listed in an
arbitrary order.
.Rs coerce:
The argument must be a collection.
Return a collection, of the same type as the receiver, containing elements
from the argument collection.  This message is redefined in most subclasses
of collection.
.Rs collect:
The argument must be a one argument block.
Return a new collection, like the receiver, containing the result of
evaluating the argument block on each element of the receiver collection.
.Rs detect:
The argument must be a one argument block.
Return the first element in the receiver collection for which the
argument block evaluates true.  Report an error and return \fBnil\fP if
no such element exists.
Note that in unordered collections (such as \fBBags\fP or \fBDictionarys\fP) the first
element to be encountered that will satisfy the condition may not be
easily predictable.
.Rs detect:ifAbsent:
Return the first element in the receiver collection for which the
first argument block evaluates true.  Return the result of evaluating
the second argument if no such element exists.
.Rs do:
The argument must be a one argument block.
Evaluate the argument block on each element in the receiver collection.
.Rs includes:
Return true if the receiver collection contains the argument.
.Rs inject:into:
The first argument must be a value, the second a two argument block.
The second argument is evaluated once for each element in the receiver
collection, passing as arguments the result of the previous evaluation
(starting with the first argument) and the element.
The value returned is the final value generated.
.Rs isEmpty
Return true if the receiver collection contains no elements.
.Rs occurrencesOf:
Return the number of times the argument occurs in the receiver collection.
.Rs remove:
Remove the argument from the receiver collection.  Report an error
if the element is not contained in the receiver collection.
.Rs remove:ifAbsent:
Remove the first argument from the receiver collection.  Evaluate the second
argument if not present.
.Rs reject:
The argument must be a one argument block.
Return a new collection like the receiver containing all elements for
which the argument block returns false.
.Rs select:
The argument must be a one argument block.
Return a new collection like the receiver containing all elements for
which the argument block returns true.
.Rs size
Return the number of elements in the receiver collection.
.Ex
i \(<- 'abacadabra'
i size    10
i asArray    #( $a $b $a $c $a $d $a $b $r $a )
i asBag    Bag ( $a $a $a $a $a $r $b $b $c $d)
i asSet    Set ( $a $r $b $c $d )
i occurrencesOf: $a    5
i reject: [:x | x isVowel]    bcdbr
.Nm Object Collection Bag/Set
.PP
\fBBags\fP and \fBSets\fP are each
unordered collections of elements.
Elements in the collections do not have keys, but are added and removed
directly.
The difference between a \fBBag\fP and a \fBSet\fP is that each element can occur
any number of times in a \fBBag\fP, whereas only one copy is inserted into
a \fBSet\fP.
.SH
Responds to
.Rs add:
Add the indicated element to the receiver collection.
.Rs add:withOccurences:
(\fBBag\fP only) Add the indicated element to the receiver \fBBag\fP the given number
of times.
.Rs first n
Return the first element from the receiver collection.
As the collection is unordered, the first element
depends upon certain values in the internal representation, and is
not guaranteed to be any specific element in the collection.
.Rs next n
Return the next element in the collection.
In conjunction with \fIfirst\fP, this can be used to access each
element of the collection in turn.
.Ex
i \(<- (1 to: 6) asBag    Bag ( 1 2 3 4 5 6 )
i size    6
i select: [:x | (x \e\e 2) strictlyPositive]    Bag ( 1 3 5 )
i collect: [:x | x \e\e 3]    Bag ( 0 0 1 1 2 2 )
j \(<- ( i collect: [:x | x \e\e 3] ) asSet    Set ( 0 1 2 )
j size    3
.LP
\fBNote:\fP Since \fBBags\fP and \fBSets\fP are unordered, there is no way to
establish a mapping between the elements of the Bag i in the example above
and the corresponding elements in the collection that resulted from the
message collect: [:x | x \e\e 3].
.Nm Object Collection KeyedCollection
.PP
The class \fBKeyedCollection\fP provides protocol for collections with keys,
such as \fBDictionarys\fP and \fBArrays\fP.
Since each entry in the collection has both a key and value, the
method \fIadd:\fP is no longer appropriate.  Instead, the method
\fIat:put:\fP, which provides both a key and a value, must be used.
.SH
Responds to
.Rs asDictionary
Return a new collection of type \fBDictionary\fP containing the elements
from the receiver collection.
.Rs at:
Return the item in the receiver collection whose key matches the argument.
Produces and error message, and returns nil, if no item is currently in
the receiver collection under the given key.
.Rs at:ifAbsent:
Return the element stored in the dictionary under the key given by the
first argument.  Return the result of evaluating the second argument if
no such element exists.
.Rs atAll:put:
The first argument must be a collection containing keys valid for the
receiver.  At each location given by a key in the first argument place
the second argument.
.Rs binaryDo:
The argument must be a two argument block.  This message is similar to \fIdo:\fP,
however both the key and the element value are passed as argument to the
block.
.Rs includesKey:
Return true if the indicated key is valid for the receiver collection.
.Rs indexOf:
Return the key value of the first element in the receiver collection matching
the argument.
Produces an error message if no such element exists.
Note that, as with the message \fIdetect:\fP, in unordered collections the
first element may not be related in any way to the order in which elements
were placed into the collection, but is rather implementation dependent.
.Rs indexOf:ifAbsent:
Return the key value of the first element in the receiver collection matching
the argument.
Return the result of evaluating the second argument if no such element
exists.
.Rs keys
Return a Set containing the keys for the receiver collection.
.Rs keysDo:
The argument must be a one argument block.
Similar to \fIdo:\fP, except that the values passed to the block are the keys
of the receiver collection.
.Rs keysSelect:
Similar to \fIselect\fP, except that the selection is made on the basis of keys
instead of values.
.Rs removeKey:
Remove the object with the given key from the receiver collection.
Print an error message, and return \fBnil\fP, if no such object exists.
Return the value of the deleted item.
.Rs removeKey:ifAbsent:
Remove the object with the given key from the receiver collection.
Return the result of evaluating the second argument if no such object
exists.
.Rs values
Return a Bag containing the values from the receiver collection.
.Ex
i \(<- 'abacadabra'
i atAll: (1 to: 7 by: 2) put: $e    ebecedebra
i indexOf: $r    9
i atAll: i keys put: $z    zzzzzzzzzz
i keys    Set ( 1 2 3 4 5 6 7 8 9 10 )
i values    Bag ( $z $z $z $z $z $z $z $z $z $z )
#(how odd) asDictionary    Dictionary ( 1 @ #how 2 @ odd )
.Nm Object Collection KeyedCollection Dictionary
.PP
A \fBDictionary\fP is an unordered collection of elements, as are \fBBags\fP
and \fBSets\fP.
However, unlike these collections, elements inserted and removed from
a \fBDictionary\fP must reference an explicit key.  Both the key and value
portions of an element can be any object, although commonly the keys are
instances of \fBSymbol\fP or \fBNumber\fP.
.SH
Responds to
.Rs at:put:
Place the second argument into the receiver collection under the key given
by the first argument.
.Rs currentKey
Return the key of the last element yielded in response to a \fIfirst\fP or
\fInext\fP request.
.Rs first n
Return the first element of the receiver collection.
Return nil if the receiver collection is empty.
.Rs next n
Return the next element of the receiver collection, or nil if no such element
exists.
.Ex
.ta 3i
i \(<- Dictionary new
i at: #abc put: #def
i at: #pqr put: #tus
i at: #xyz put: #wrt
i print    Dictionary ( #abc @ #def #pqr @ #tus #xyz @ #wrt )
i size    3
i at: #pqr    #tus
i indexOf: #tus    #pqr
i keys    Set ( #abc #pqr #xyz )
i values    Bag ( #wrt #def # tus )
i collect: [:x | x asString at: 2]    Dictionary ( #abc @ $e #pqr @ $u #xyz @ $r)
.Nm Object Collection KeyedCollection Dictionary Smalltalk
.PP
The class \fBSmalltalk\fP provides protocol for the pseudo variable
\fBsmalltalk\fP.
Since it is a subclass of Dictionary, this variable can be used to store
information, and thus provide a means of communication between objects.
Other messages modify various parameters used by the Little Smalltalk system.
.SH
Responds To
.Rs date n
Return the current date and time as a string.
.Rs display n
Set execution display to display the result of every expression typed, but
not for assignments.
Note that the display behavior can also be modified using the \-d argument
on the command line.
.Rs displayAssign n
Set execution display to display the result of every expression typed,
including assignment statements.
.Rs doPrimitive:withArguments: n
Execute the indicated primitive with arguments given by the second array.
A few primitives (such as those dealing with process management) cannot be
executed in this manner.
.Rs noDisplay n
Turn off execution display - no results will be displayed unless explicitly
requested by the user.
.Rs perform:withArguments: d
Send indicated message to the receiver, using the arguments given.
The first value in the argument array is taken to be the receiver of
the message.
Unpredictable results if the number of arguments is not appropriate for
the given message.
.Rs sh: n
The argument, which must be a string, is executed as a Unix command by the
shell.  The value returned is the termination status of the shell.
.Rs time: n
The argument must be a block.  The block is executed, and the number of
seconds elapsed during execution returned.  Time is only accurate to within
about one second.
.Ex
smalltalk date    Fri Apr 12 16:15:42 1985
smalltalk perform: #+ withArguments: #(2 5)    7
smalltalk doPrimitive: 10 withArguments: #(2 5)    7
.Nm Object Collection KeyedCollection SequenceableCollection
.PP
The class \fBSequenceableCollection\fP contains protocol for collections that have
a definite sequential ordering and are indexed by integer keys.
Since there is a fixed order for elements, it is possible to refer to the
last element in a \fBSequenceableCollection\fP.
.SH
Responds to
.Rs ,
Appends the argument collection to the receiver collection, returning a new
collection of the same type as the receiver.
.Rs copyFrom:to:
Return a new collection, like the receiver, containing the designated
subportion of the receiver collection.
.Rs copyWith:
Return a new collection, like the receiver, with the argument added to
the end.
.Rs copyWithout:
Return a new collection, like the receiver, with all occurrences of
the argument removed.
.Rs equals:startingAt:
The first argument must be a \fBSequenceableCollection\fP.
Return true if each element of the receiver collection is equal to the
corresponding element in the argument offset by the amount given in
the second argument.
.Rs findFirst:
Find the key for the first element whose value satisfies the
argument block.
Produce an error message if no such element exists.
.Rs findFirst:ifAbsent:
Both arguments must be blocks.
Find the key for the first element whose value satisfies the first argument block.
If no such element exists return the value of the
second argument.
.Rs findLast:
Find the key for the last element whose value satisfies the argument block.
Produce an error message if no such element exists.
.Rs findLast:ifAbsent:
Both arguments must be blocks.
Find the key for the last element whose value satisfies the first argument block.
If no such element exists return the value of the second argument block.
.Rs firstKey
Return the first key valid for the receiver collection.
.Rs indexOfSubCollection:startingAt:
.br
Starting at the position given by the second argument, find the next
block of elements in the receiver collection which match the collection
given by the first argument, and return the index for the start of that block.
Produce an error message if no such position
exists.
.Rs indexOfSubCollection:startingAt:ifAbsent:
.br
Similar to \fIindexOfSubCollection:startingAt:\fP, except that the result of the
exception block is produced if no position exists matching the pattern.
.Rs last
Return the last element in the receiver collection.
.Rs lastKey
Return the last key valid for the receiver collection.
.Rs replaceFrom:to:with:
Replace the elements in the receiver collection in the positions indicated
by the first two arguments with values taken from the collection given
by the third argument.
.Rs replaceFrom:to:with:startingAt:
.br
Replace the elements in the receiver collection in the positions indicated
by the first two arguments with values taken from the collection given
in the third argument, starting at the position given by the fourth
argument.
.Rs reversed n
Return a collection, like the receiver, with elements reversed.
.Rs reverseDo:
Similar to \fIdo\fP:, except that the items are presented in reverse order.
.Rs sort n
Return a collection, like the receiver, with the elements sorted
using the comparison <=.  Elements must be able to respond to the binary
message <=.
.Rs sort: n
The argument must be a two argument block which yields a boolean.
Return a collection, like the receiver, sorted using the argument
to compare elements for the purpose of ordering.
.Rs with:do:
The second argument must be a two argument block.
Present one element from the receiver collection and from the collection
given by the first argument in turn to the second argument block.
An error message is given if the collections do not have the same number of
elements.
.Ex
i \(<- 'abacadabra'
i copyFrom: 4 to: 8    cadab
i copyWith: $z    abacadabraz
i copyWithout: $a    bcdbr
i findFirst: [:x | x > $m]    9
i indexOfSubCollection: 'dab' startingAt: 1    6
i reversed    arbadacaba
i , i reversed    abacadabraarbadacaba
i sort: [:x :y | x >= y]    rdcbbaaaaa
.Nm Object Collection KeyedCollection SequenceableCollection Interval
.PP
The class \fBInterval\fP represents a sequence of numbers in an arithmetic
sequence, either ascending or descending.  Instances of \fBInterval\fP are
created by numbers in response to the message \fIto:\fP or \fIto:by:\fP.
In conjunction with the message \fIdo:\fP, \fBIntervals\fP create a control
structure similar to do or for loops in Algol like languages.  For example:
.DS B
.sp
(1 to: 10) do: [:x | x print]
.sp
.DE
will print the numbers 1 through 10.
Although they are a collection, \fBIntervals\fP cannot be added to.
They can, however, be accessed randomly using the message \fIat\fP:.
.SH
Responds to
.Rs first
Produce the first element from the interval.  In conjunction with
\fIlast\fP, this message may be used to produce each element from the
interval in turn.  Note that \fBIntervals\fP also respond to the message
\fIat:\fP, which can be used to produce elements in an arbitrary order.
.Rs from:to:by:
Initialize the upper and lower bounds and the step size for the receiver.
(This is used principally internally by the method for number to create new
Intervals).
.Rs next
Produce the next element from the interval.
.Rs size
Return the number of elements that will be generated in producing the
interval.
.Ex
(7 to: 13 by: 3) asArray    #( 7 10 13 )
(7 to: 13 by: 3) at: 2    10
(1 to: 10) inject: 0 into: [:x :y | x + y]    55
(7 to: 13) copyFrom: 2 to: 5    #( 8 9 10 11 )
(3 to: 5) copyWith: 13    #( 3 4 5 13 )
(3 to: 5) copyWithout: 4    #( 3 5 )
(2 to: 4) equals: (1 to: 4) startingAt: 2    True
.Nm Object Collection KeyedCollection SequenceableCollection List
.PP
Lists represent collections with a fixed order, but indefinite
size.  No keys are used, and elements are added or removed from one end of
the other.
Used in this way, Lists
can perform as \fIstacks\fP or as \fIqueues\fP.  The table below
illustrates how stack and queue operations can be implemented in terms
of messages to instances of List.
.TS
center;
l s | l s
l l | l l.
\fIstack operations\fP    \fIqueue operations\fP

_
push    addLast:    add    addLast:
pop    removeLast    first in queue    first
top    last    remove first in queue    removeFirst
test empty    isEmpty    test empty    isEmpty
.TE
.SH
Responds to
.Rs add:
Add the element to the beginning of the receiver collection.  This is the same
as \fIaddFirst:\fP.
.Rs addAllFirst:
The argument must be a SequenceableCollection.  The elements of the argument
are added, in order, to the front of the receiver collection.
.Rs addAllLast:
The argument must be a SequenceableCollection.  The elements of the argument
are added, in order, to the end of the receiver collection.
.Rs addFirst:
The argument is added to the front of the receiver collection.
.Rs addLast:
The argument is added to the back of the receiver collection.
.Rs removeFirst
Remove the first element from the receiver collection, returning the
removed value.
.Rs removeLast
Remove the last element from the receiver collection, returning the
removed value.
.Ex
i \(<- List new
i addFirst: 2 / 3    List ( 0.6666 )
i add: $A
i addAllLast: (12 to: 14 by: 2)
i print    List ( 0.6666 $A 12 14 )
i first    0.6666
i removeLast    14
i print    List ( 0.6666 $A 12 )
.Nm Object Collection KeyedCollection SequenceableCollection List Semaphore
.PP
Semaphores are used to synchronize concurrently running \fBProcesses\fP.
.SH
Responds To
.Rs new:
If created using \fInew\fP, a \fBSemaphore\fP starts out with zero excess
signals.  Alternatively, a \fBSemaphore\fP can be created with an arbitrary
number of excess signals by giving it an argument to \fInew\fP:.
.Rs signal
If there is a process blocked on the semaphore is it scheduled for
execution, otherwise
the number of excess signals is incremented by one.
.Rs wait
If there are excess signals associated with the semaphore the number of
signals is decremented by one, otherwise
the current process is placed on the semaphore queue.
.Nm Object Collection KeyedCollection SequenceableCollection File
.PP
A \fBFile\fP is a type of collection where the elements of the collection are
stored on an external medium, typically a disk.
For this reason, although most operations on collections are defined for
files, many can be quite slow in execution.
A file can be opened on one of three \fImodes\fP:
In \fIcharacter\fP mode every read returns a single character from the
file.
In \fIinteger\fP mode every read returns a single word, as an integer value.
In \fIstring\fP mode every read returns a single line, as a \fBString\fP.
For writing, character and string modes will write the string representation
of the argument, while integer mode must write only a single integer.
.SH
Responds To
.Rs at:
Return the object stored at the indicated position.  Position is given as a
character count from the start of the file.
.Rs at:put:
Place the object at the indicated position in the file.  Position is given
as a character count from the start of the file.
.Rs characterMode
Set the mode of the receiver file to \fIcharacter\fP.
.Rs currentKey
Return the current position in the file, as a character count from the
start of the file.
.Rs integerMode
Set the mode of the receiver file to \fIinteger\fP.
.Rs open:
Open the indicated file for reading.
The argument must be a \fBString\fP.
.Rs open:for:
The \fIfor:\fP argument must be one of 'r', 'w' or 'r+'
(see fopen(3) in the Unix programmers
manual).  Open the file in the indicated mode.
.Rs read
Return the next object from the file.
.Rs size
Return the size of the file, in character counts.
.Rs stringMode
Set the mode of the receiver file to \fIstring\fP.
.Rs write:
Write the argument into the file.
.Nm Object Collection KeyedCollection SequenceableCollection ArrayedCollection
.PP
The class \fBArrayedCollection\fP provides protocol for collections with a
Fixed size and integer keys.
Unlike other collections, which are created using the message \fInew\fP,
instances of \fBArrayedCollection\fP must be created using the one argument
message \fInew:\fP.  The argument given with this message must be a positive
integer, representing the size of the collection to be created.
In addition to the protocol shown, many of the methods inherited
from superclasses are redefined in this class.
.SH
Responds to
.Rs =
The argument must also be an \fBArray\fP.  Test whether the receiver and the
argument have equal elements listed in the same order.
.Rs at:ifAbsent:
Return the element stored with the given key.  Return the result
of evaluating the second argument if the key is not valid for the
receiver collection.
.Rs padTo: n
Return an array like the received that is at least as long as the argument
value.  Returns the receiver if it is already longer than the argument.
.Ex
\&'small' = 'small'    True
\&'small' = 'SMALL'    False
\&'small' asArray    #( $s $m $a $l $l)
\&'small' asArray = 'small'    True
#(1 2 3) padTo: 5    #(1 2 3 nil nil)
#(1 2 3) padTo: 2    #(1 2 3)
.Nm Object Collection KeyedCollection SequenceableCollection ArrayedCollection Array
.PP
Instances of the class \fBArray\fP are perhaps the most commonly used
data structure in Smalltalk programs.
\fBArrays\fP are represented textually by a pound sign preceding the list of
array elements.
.SH
Responds to
.Rs at:
Return the item stored in the position given by the argument.
An error message is produced, and \fBnil\fP returned, if the argument is not
a valid key.
.Rs at:put:
Store the second argument in the position given by the first argument.
An error message is produced, and \fBnil\fP returned, if the argument is not
a valid key.
.Rs grow:
Return a new array one element larger than the receiver, with the argument
value attached to the end.  This is a slightly more efficient command than
\fIcopyWith:\fP, although the effect is the same.
.Ex
i \(<- #(110 101 97)
i size    3
i \(<- i grow: 116    #( 110 101 97 116)
i \(<- i collect: [:x | x asCharacter]    #( #n #e #a #t )
i asString    neat
.Nm Object Collection KeyedCollection SequenceableCollection ArrayedCollection ByteArray
.PP
A \fBByteArray\fP is a special form of array in which the elements must be
numbers in the range 0-255.  Instances of \fBByteArray\fP are given a very
compact encoding, and are used extensively internally in the Little
Smalltalk system.
A \fBByteArray\fP can be represented textually by a pound sign preceding
the list of array elements surrounded by a pair of square braces.
.SH
Responds to
.Rs at:
Return the item stored in the position given by the argument.
An error message is produced, and \fBnil\fP returned, if the argument is not
a valid key.
.Rs at:put:
Store the second argument in the position given by the first argument.
An error message is produced, and \fBnil\fP returned, if the argument is not
a valid key.
.Ex
i \(<- #[110 101 97]
i size    3
i \(<- i copyWith: 116    #[ 110 101 97 116 ]
i \(<- i asArray collect: [:x | x asCharacter]    #( #n #e #a #t )
i asString    neat
.Nm Object Collection KeyedCollection SequenceableCollection ArrayedCollection String
.PP
Instances of the class \fBString\fP are similar to \fBArrays\fP, except
that the individual elements
must be \fBCharacter\fP.  \fBStrings\fP are represented literally by placing single
quote marks around the characters making up the string.
\fBStrings\fP also differ from \fBArrays\fP in that
Strings possess an ordering, given by the underlying ascii sequence.
.SH
Responds to
.Rs ,
Concatenates the argument to the
receiver string, producing a new string.
If the argument is not a \fBString\fP it is first converted
using \fIprintString\fP.
.Rs <
The argument must be a \fBString\fP.  Test if the receiver is lexically
less than the argument.  For the purposes of comparison case differences
are ignored.
.Rs <=
Test if the receiver is lexically less than or equal to the
argument.
.Rs >=
Test if the receiver is lexically greater than or equal to the argument.
.Rs >
Test if the receiver is lexically greater than the argument.
.Rs asSymbol r
Return a \fBSymbol\fP with characters given by the receiver string.
.Rs at:
Return the character stored at the position given by the argument.
Produce and error message, and return \fBnil\fP, if the argument does not represent
a valid key.
.Rs at:put:
Store the character given by second argument at the location given by
the first argument.  Produce an error message, and return \fBnil\fP, if either
argument is invalid.
.Rs copyFrom:length: n
Return a substring of the receiver.  The substring is taken from the
indicated starting position in the receiver and extends for the given length.
Produce an error message, and return \fBnil\fP, if the given positions are
not legal.
.Rs copyFrom:to: r
Return a substring of the receiver.  The substring is taken from the
indicated positions.
Produce an error message, and return \fBnil\fP, if the given positions are
not legal.
.Rs printAt: n
The argument must be a \fBPoint\fP which describes a location on the
terminal screen.  The string is printed at the specified location.
.Rs size
Return the number of characters stored in the string.
.Rs sameAs:
Return true if the receiver and argument string match with the exception of
case differences.  Note that the boolean message = , inherited from
ArrayedCollection, can be used to see if two strings are the same including
case differences.
.Ex
\&'example' at: 2    $x
\&'bead' at: 1 put: $r    read
\&'small' > 'BIG'    True
\&'small' sameAs: 'SMALL'    True
\&'tary' sort    arty
\&'Rats live on no evil Star' reversed    ratS live on no evil staR
.Nm Object Block
.PP
Although it is easy for the programmer to think of blocks as a syntactic
construct, or a control structure, they are actually objects, and share
attributes of all other objects in the Smalltalk system, such as the
ability to respond to messages.
.SH
Responds to
.Rs fork
Start the block executing as a \fBProcess\fP.
The value \fBnil\fP is immediately returned,
and the \fBProcess\fP created from the block
is scheduled to run in parallel with the current process.
.Rs forkWith:
Similar to \fIfork\fP, except that the array is passed as arguments to the
receiver block prior to scheduling for execution.
.Rs newProcess
A new \fBProcess\fP is created for the block, but is not
scheduled for execution.
.Rs newProcessWith: n
Similar to \fInewProcess\fP, except that the array is passed as arguments to the
receiver block prior to it being made into a process.
.Rs value
Evaluates the receiver block.  Produces an error message, and returns nil,
if the receiver block required arguments.  Return the value yielded by
the block.
.Rs value:
Evaluates the receiver block.  Produces an error message, and returns nil,
if the receiver block did not require a single argument.  Return the
value yielded by the block.
.Rs value:value:
Two argument block evaluation.
.Rs value:value:value:
Three argument block evaluation.
.Rs value:value:value:value:
Four argument block evaluation.
.Rs value:value:value:value:value:
.br
Five argument block evaluation.
.Rs whileTrue:
The receiver block is repeatedly evaluated.  While it evaluates to true,
the argument block is also evaluated.  Return nil when the receiver block
no longer evaluates to true.
.Rs whileTrue
The receiver block is repeatedly evaluated until it returns a value that is
not true.
.Rs whileFalse:
The receiver block is repeatedly evaluated.  While it evaluates to false,
the argument block is also evaluated.  Return nil when the receiver block
no longer evaluates to false.
.Rs whileFalse
The receiver block is repeatedly evaluated until it returns a value that is
not false.
.Ex
['block indeed'] value    block indeed
[:x :y | x + y + 3] value: 5 value: 7    15
.Nm Object Class
.PP
The class \fBClass\fP provides protocol for manipulating class instances.
An instance of class \fBClass\fP is generated for each class in the Smalltalk
system.  New instances of this class are then formed by sending messages
to the class instance.
.SH
Responds to
.Rs deepCopy: n
The argument must be an instance of the receiver class.  A deepCopy
of the argument is returned.
.Rs edit n
The user is placed into a editor editing the file from which the class
description was originally obtained.  When the editor terminates, the class
description will be reparsed and will override the previous description.
See also \fIview\fP (below).
.Rs list n
Lists all subclasses of the given class recursively.
In particular, \fBObject\fP \fIlist\fP will list the names of all the
classes in the system.
.Rs new
A new instance of the receiver class is returned.  If the methods for
the receiver contain protocol for \fInew\fP, the new instance will
first be passed this message.
.Rs new:
A new instance of the receiver class is returned.  If the methods for
the receiver contain protocol for \fInew:\fP, the new instance will
first be passed this message.
.Rs respondsTo n
List all the messages that the current class will respond to.
.Rs respondsTo: d
The argument must be a Symbol.  Return true if the receiver class,
or any of its superclasses, contains a method
for the indicated message. Return false otherwise.
.Rs shallowCopy: n
The argument must be an instance of the receiver class.  A shallowCopy
of the argument is returned.
.Rs superClass n
Return the superclass of the receiver class.
.Rs variables n
Return an array containing the names of the instance variables used in
the receiver class.
.Rs view n
Place the user into an editor viewing the class description from which the
class was created.  Changes made to the file will not, however, affect the
current class representation.
.Ex
Array new: 3    #( nil nil nil )
Bag respondsTo: #add:    True
SequenceableCollection superClass    KeyedCollection
.Nm Object Process
.PP
Processes are created by the system, or by passing the message \fInewProcess\fP
or \fIfork\fP to a block; they cannot be created directly by the user.
.SH
Responds To
.Rs block
The receiver process is marked as being blocked.  This is usually
the result of a semaphore wait.
Blocked processes are not executed.
.Rs resume
If the receiver process has been \fIsuspend\fPed, it is rescheduled for
execution.
.Rs suspend
If the receiver process is scheduled for execution, it is marked as
suspended.  Suspended processes are not executed.
.Rs state
The current state of the receiver process is returned as a Symbol.
.Rs terminate
The receiver process is terminated.  Unlike a blocked or suspended process,
a terminated process cannot be restarted.
.Rs unblock
If the receiver process is currently blocked, it is scheduled for
execution.
.Rs yield
Returns \fBnil\fP.  As a side effect, however,
if there are pending processes the current process is
placed back on the process queue and another process started.
End
echo unbundling st.1 1>&2
cat >st.1 <<'End'
.TH st 1 "local"
.SH NAME
st \- a Little Smalltalk
.SH SYNOPSIS
st [options] [files]
.SH DESCRIPTION
.PP
\fBst\fP is an interpreter for a Smalltalk-like language.  For a complete
description of the language accepted by the interpreter see the user manual.
Options accepted by the command are as follows:
.IP \-a
If the \-a option is given statistics on the number of memory allocations
will be displayed following execution.
.IP \-d\fIdigit\fP
If the \fIdigit\fP is zero only those results explicitly requested by the
user will be printed.  If 1, the values of expressions typed at the
keyboard will be displayed (this is the default).
If 2, the values of expressions and the values
assigned in assignment statements will be displayed.
.IP \-f
The \-f option indicates fast loading should be used, which loads a binary
save image (see ``)s'' below) for the standard library.
.IP \-g
The next argument is taken to be the name of an additional library stored
in the system library area.  The library is loaded following the standard
prelude, just as if a ``)g'' directive were given at the beginning of
execution (see below).
.IP \-l
The next argument is taken to be the name of a file containing a binary
image saved using the )s directive (see below).  This binary image is
loaded prior to execution.
.IP \-m
Do not perform fast loading.  (Used when fastloading is the default).
.IP \-n
The \-n option, if given, suppresses the loading
of the standard library.
As this gives you a system with almost no functionality, it is seldom
useful except during debugging.
.IP \-r
The next argument is taken to be the name of a file of
Smalltalk commands.  The file is included prior to execution, just
as if a ``)r'' directive were given at the beginning of execution (see below).
.IP \-s
In normal operation, at the end of execution the number of reference
count increments and decrements is printed just prior to exit.
In the absence of cycles these two
figures should be equal.  Since cycles can cause large chunks of memory to
become unreachable, and seriously degrade performance, this information is
often useful in debugging.
The \-s option, if given, suppresses the printing of this information.
.PP
The files, if given, must contain class descriptions.  Consult the
reference manual for the syntax for class descriptions.  The classes
defined are included along with the standard library of classes before
execution begins.
.PP
Once execution begins, the cursor will tab over 8 spaces to indicate that
a command can be entered.
A command consists of a valid Smalltalk expression, without a terminating
period.
As each expression is entered it is executed by the Little Smalltalk
interpreter, and the results displayed.
.PP
The following system directives can be entered in place of commands:
.IP ")e filename"
Edit the named file, which must contain only class descriptions.
The Little Smalltalk system will suspend, leaving the user in an editor
for making changes to the named file.  Upon exiting the editor, the named
file will automatically be included, as with the )i directive (below).
The editor chosen by this command is taken from the variable EDITOR in the
user's environment.
.IP ")g filename"
Search for a file with the given name in the system library area.
If found, load the library in with the users classes.  This is useful for
creating libraries of commonly used classes which are not part of the
standard prelude, such as classes for statistics applications or for
graphics.
.IP ")i filename"
Include the named file.  The File must contain one or more class
descriptions.  The class descriptions are parsed, and if syntactically
legal new instances of class \fBClass\fP are added to the Smalltalk system.
.IP ")l filename"
Load a saved binary environment.  The file must have been previously
created using the )s directive (below).  The values of all variables are
overridden.
.IP ")r filename"
Read the named file.  The effect is just as if the lines in the file
had been typed at the keyboard.  The file cannot contain class
descriptions.
.IP ")s filename"
Save the current environment in the named file.  The values of all
variables will be saved, and can later be restored using the )l directive
(above).
.IP ")!string"
.br
Execute the string following the exclamation point as
a Unix command.
.SH "Author"
Tim Budd, Department of Computer Science, Oregon State University
.SH "See Also"
Timothy A. Budd,
\fIA Little Smalltalk\fP, published by Addison Wesley.
.SH Bugs
Not all the Smalltalk-80 Language described in the Blue Book is supported;
see the user manual for details.
(Smalltalk-80 is a trademark of Xerox Corporation).
End
echo unbundling syntax 1>&2
cat >syntax <<'End'
.so macros
.ds CH
.Sx "Class Description"
.PS
ellipsewid = 1.3i
arrow
A: ellipse "class heading"
arc -> cw
arc
ellipse "instance variables"
arc ->
arc cw
B: ellipse "protocol"
arrow
arrow from A.e to B.w
.PE
.Sx "Class Heading"
.PS
arrow
circle "\fBClass\fP"
arrow
ellipse "variable"
arrow right 3i
move left 3i
move right 0.1i
arc -> cw
arc
ellipse "colon variable"
arc ->
arc cw
.PE
.IP
\fBvariable\fP defines the class name, must begin with an upper case letter.
.br
\fBcolon variable\fP defines the superclass name, superclass is \fBObject\fP
if not given.
.Sx "Instance Variables"
.PS
arrow
circle "|"
arrow
A: ellipse "variable"
arc -> cw
arc cw
arrow left 1.3i
arc cw
arc cw
move to A.e
arrow
circle "|"
arrow
.PE
.IP
Instance variables must begin with a lower case letter.
.Sx "Protocol"
.PS
arrow
circle "["
arrow
A: ellipse "method"
arc -> cw
line down 0.2i
arc cw
arrow left 0.4i
circle "|"
arrow left 0.4i
arc cw
line up 0.2i
arc cw
move to A.e
arrow
circle "]"
arrow
.PE
.IP
Vertical bar separating methods \fBmust\fP be placed in column 1.
.Sx "Method"
.PS
arrow
A: ellipse "method pattern"
arc -> cw
arc
ellipse "temporary variables"
arc ->
arc cw
C: ellipse "statements"
arrow
arrow from A.e to C.w
.PE
.bp
.Sx "Method Pattern"
.PS
A: arrow
ellipse "unary selector"
arrow right 3i
move to A
arc -> cw
line down 0.1i
B: arc
ellipse "binary selector"
arrow
ellipse "argument variable"
arc ->
line up 0.1i
arc -> cw
move to start of B
line down 0.6i
arc
ellipse "keyword selector"
arrow
C: ellipse "argument variable"
arc
line up 0.6i
move to C.e
right
arc -> cw
arc cw
arrow left 3.1i
arc -> cw
arc cw
.PE
.IP
Argument variables must begin with a lower case letter,
and must be distinct from instance variables.
.Sx "Temporary Variables"
.PS
arrow
circle "|"
arrow
A: ellipse "variable"
arc -> cw
arc cw
arrow left 1.3i
arc cw
arc cw
move to A.e
arrow
circle "|"
arrow
.PE
.IP
temporary variables must begin with lower case letters,
and must be distinct from both instance and argument variables.
.Sx "Statements"
.PS
arrow
A: line right 1.5i
move to start of A
arc -> cw
arc
circle "\s+6\(ua\s-6"
arc ->
arc cw
B: ellipse "expression"
arrow right 2.5i
move to B.e
move right 0.5i
arc -> cw
arc
circle "."
arc ->
arc cw
move to B.e
arc -> cw
line down 0.4i
arc -> cw
circle "."
arrow left 2.5i
arc cw
arrow up 0.4i
arc cw
.PE
.Sx "Expression"
.PS
A: arrow right 3.3i
move to start of A
arc -> cw
arc
ellipse "variable"
arrow
B: circle "<\(mi"
arc ->
arc cw
C: ellipse "cascaded expression"
arrow
move to B.e
arc -> cw
arc cw
arrow left 2.3i
arc -> cw
arc cw
.PE
.bp
.Sx "Cascaded Expression"
.PS
arrow
ellipse "simple expression"
arrow right 3.5i
move left 0.5i
right
arc -> cw
arc cw
circle ";"
arrow
ellipse "continuation"
arc -> cw
arc cw
.PE
.Sx "Simple Expression"
.PS
arrow
A: ellipse "binary"
arrow
move to A.e
arc -> cw
line down 0.2i
arc cw
ellipse "keyword"
arc -> cw
line up 0.2i
arc cw
.PE
.Sx "Binary"
.PS
arrow
A: ellipse "unary"
arrow
move to A.e
arc -> cw
B: line down 0.2i
arc cw
ellipse "binary selector"
arc -> cw
line up 0.2i
arc cw
.PE
.Sx "Unary"
.PS
arrow
A: ellipse "primary"
B: line right 2i
arc -> cw
arc cw
ellipse "unary selector"
arc -> cw
arc cw
move to B.e
arrow right
.PE
.Sx "Primitive"
.PS
arrow right 0.2i
circle "<primitive" wid 0.7i
arrow right 0.2i
ellipse "unsigned integer"
A: line right 1.7i
arc -> cw
arc cw
ellipse "primary"
arc -> cw
arc cw
move to A.e
arrow right
circle ">"
arrow right
.PE
.IP
Unsigned integer must be a number in the range 0-255.
.bp
.Sx "Primary"
.PS
A: arrow right 2i
ellipse "variable"
arrow right 2i
move to start of A
move right 0.5i
arc -> cw
B: line down 0.1i
arc
arrow right 1i
ellipse "literal"
arrow right 1i
arc ->
line up 0.1i
arc cw
move to end of B
C: arrow down 0.6i
arc
arrow right 1i
ellipse "block"
arrow right 1i
arc ->
line up 0.6i
move to end of C
Z: arrow down 0.6i
arc
arrow right 1i
ellipse "primitive"
arrow right 1i
arc ->
line up 0.6i
move to end of Z
arrow down 0.6i
arc
circle "("
arrow
ellipse "cascaded expression"
arrow
circle ")"
arc ->
line up 0.6i
.PE
.IP
If variable begins with an upper case letter it is a class name, otherwise
variable must be instance, argument or temporary variable or pseudo variable
name.
.Sx "Continuation"
.PS
A: arrow
arrow right 1.5i
ellipse "unary selector"
Z: line right 1.5i
arrow right 0.5i
move to end of Z
arc -> cw
arrow down 2i
arc -> cw
arrow left 4.5i
arc -> cw
arrow up 2i
arc -> cw
move to end of A
arc -> cw
C: arrow down 0.4i
arc
ellipse "binary selector"
arrow
ellipse "unary"
arc ->
line up 0.4i
arc cw
move to end of C
arrow down 0.6i
arc
ellipse "keyword"
arrow
D: ellipse "binary"
arc ->
line up 0.6i
move to D.e
right
arc -> cw
arc cw
arrow left 3.1i
arc cw
arc -> cw
.PE
.bp
.Sx "Block"
.PS
arrow
A: circle "["
arrow right 2.2i
ellipse "statements"
arrow
circle "]"
arrow
move to A.e
arc -> cw
arc
ellipse "block arguments" width 1.2i
arc ->
arc cw
.PE
.IP
The last statement cannot be followed by a period.
.Sx "Block Arguments"
.PS
arrow
A: ellipse "colon variable"
arrow
circle "|"
arrow
move to A.e
arc -> cw
arc cw
arrow left 1.3i
arc cw
arc cw
.PE
.Sx "Literal"
.PS
arrow right 1i
A: arrow
ellipse "number"
arrow right 1.5i
move to start of A
arc -> cw
B: line down 0.1i
arc
ellipse "symbol"
arc ->
line up 0.1i
arc cw
move to end of B
C: arrow down 0.6i
arc
ellipse "string"
arc ->
line up 0.6i
move to end of C
D: arrow down 0.6i
arc
ellipse "character constant"
arc ->
line up 0.6i
move to end of D
H: arrow down 0.6i
arc
ellipse "bytearray"
arc ->
line up 0.6i
move to end of H
E: arrow down 0.6i
arc
ellipse "array constant"
arc ->
line up 0.6i
.PE
.bp
.Sx "Number"
.PS
A: arrow right 3.6i
move to start of A
arc -> cw
arc
ellipse "base" width 0.8i
arc ->
arc cw
arc -> cw
arc
ellipse "sign" width 0.8i
arc ->
arc cw
ellipse "unsigned number"
arrow
.PE
.Sx "Base"
.PS
arrow
ellipse "unsigned integer"
arrow
circle "r"
arrow
.PE
.Sx "Sign"
.PS
A: arrow
arrow right 3i
move to end of A
B: arc cw
arc
circle "+"
arc
arc cw
move to end of B
arrow down 0.6i
arc
circle "\(mi"
arc
arrow up 0.6i
.PE
.Sx "Unsigned Number"
.PS
arrow
A: ellipse "unsigned fraction"
arc -> cw
arc
circle "e"
arrow right 0.25i
ellipse "sign" width 0.8i
arrow right 0.25i
ellipse "unsigned integer"
arc ->
arc cw
move to A.e
arrow right 4.2i
.PE
.Sx "Unsigned Fraction"
.PS
arrow
A: ellipse "unsigned integer"
arc -> cw
arc
circle "."
arrow
ellipse "unsigned integer"
arc ->
arc cw
move to A.e
arrow right 4i
.PE
.Sx "Unsigned Integer"
.PS
arrow
A: circle "digit"
arrow
move to A.e
arc -> cw
arc cw
arrow left 0.5i
arc -> cw
arc cw
.PE
.bp
.Sx "Symbol"
.PS
arrow
circle "#"
arrow
A: circle "char"
arrow
move to A.e
arc cw
arc cw
arrow left 0.5i
arc cw
arc cw
.PE
.IP
char is any non-space character that is not one of period, parenthesis
or square braces.
.Sx "String"
.PS
arrow
circle "'"
arrow
A: circle "char"
arrow
circle "'"
arrow
move to A.e
arc cw
arc cw
arrow left 0.5i
arc cw
arc cw
.PE
.IP
To include a quote mark in a string, use two adjacent quote marks.
.Sx "Character Constant"
.PS
arrow
circle "$"
arrow
circle "char"
arrow
.PE
.Sx "Bytearray"
.PS
arrow
circle "#"
arrow
circle "["
arrow
A: ellipse "unsigned integer"
arrow
circle "]"
arrow
move to A.e
arc -> cw
arc cw
line left 1.3i
arc -> cw
arc cw
.PE
.IP
Integer must be in the range 0 through 255.
.Sx "Array Constant"
.PS
arrow
circle "#"
arrow
ellipse "array"
arrow
.PE
.bp
.Sx "Array"
.PS
arrow
circle "("
arrow
A: arc -> cw
arc
ellipse "number"
arc ->
arc cw
B: arrow
circle ")"
arrow
move to start of A
arrow right 2.5i
move to end of A
C: arrow down 0.6i
arc
ellipse "symbol"
arc ->
arrow up 0.6i
move to end of C
D: arrow down 0.6i
arc
ellipse "string"
arc ->
arrow up 0.6i
move to end of D
E: arrow down 0.6i
arc
ellipse "character constant"
arc ->
arrow up 0.6i
move to end of E
arrow down 0.6i
arc
ellipse "array"
arc ->
arrow up 0.6i
move to start of B
right
arc -> cw
arrow down 3i
arc -> cw
arrow left 2.4i
arc -> cw
arrow up 3i
arc -> cw
.PE
.IP
The leading sharp sign can be omitted in symbols and arrays inside of
an array list.
Binary selectors, keywords, and other strings are treated as Symbols inside
of arrays.
End