*** UK-INTRO.TXT   BY K.C.GOLDIE-MORRISON  7.MAR 1983 *************************


History and Acknowledgments.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
STOIC was written in 1977 by J.Sachs and his team at
the M.I.T. Harvard Biomedical Engineering Centre. It was
implemented on a Nova minicomputer with sequential tape
back-up, which dictated the file system.

The program was released into the Public Domain, cross-
assembled for the 8080 CPU and rudimentary modifications
made by Wink Saville, of Sorento Valley Associates, to
run under CP/M. It was then issued as Volume 23 in the
U.S. CP/M Users Group Library.

The CP/M mods were only sufficient to enable the minimum
program to be assembled by ASM and then to read and com-
pile the program extensions which are written in STOIC
source form. No mods were made to the file system, so it
was unable to read or write data files, or write program
files. Thus the excellent editor was also unuseable.

Andrew Clarke, the Editor of the U.K. CP/M Users Group
Journal, then rewrote the original file system to run,
in its original mode, under CP/M. He also wrote a new
program which fully implemented integration with CP/M.
He then amended the Editor to run with both of the above
filing systems. So, for the first time the whole gamut of
this very comprehensive system was available.

The original KERNEL of the program was intended to be in
ROM and for it to compile the rest of the program as
described above. The piecemeal changeover to CP/M has 
left a somewhat illogical construction with a number of
redundant or duplicated procedures which the writer is
now working to streamline, and to speed-up the file hand-
ling by using the CP/M Random Access facilities.

The files on this disc thus owe their origin to many
sources, my contribution being to edit and rewrite
this pleonasm into homogenity. The files have been con-
figured for CP/M 2.2 and the TUSCAN micro but can be 
simply adapted to any CP/M compatible machine.

The DOC files are edited versions of the originals, 
with some errors corrected. The .TXT files have been 
written by me.


INTRODUCTION TO STOIC.

Contrary to popular belief, STOIC is not a difficult
language to learn, provided you are prepared to under-
stand how it operates. Then so-called difficulties,
such as working in Reversed Polish Notation, seem quite
natural.

Most languages, high or low level, have a fairly limited
vocabulary of reserved words, but often quite severe
rules over their use and the punctuation required with
them. STOIC has a very large vocabulary but simple and 
few rules and virtually no punctuation.

STOIC consists of one big DICTIONARY of named functions
or subroutines called Stoic WORDS. Programming is the pro-
cess of defining new WORDS on a heirarchical basis, until
the last one is the program!  So there is no clear div-
ision between the "compiler" and the "object" program.

You start with a DICTIONARY with whatever collection of
WORDS you need, and finish with a bigger one. It will also
contain within it the data variables and arrays.

This new enlarged DICTIONARY can then be Saved under
CP/M as a .COM file with an appropriate name, then
rapidly entered as a CP/M transient. Alternatively, the
extensions to the DICTIONARY can be written in STOIC
source language (STC), as an uncompiled file and then
read in and compiled on the end of a basic DICTIONARY.

The DICTIONARY can grow to any size and hold any number
of "programs" simultaneously. This is how the language
was built up from a small DICTIONARY called the KERNEL.
To this was added an extension (STOICBAS.STC) which had
about 500 WORDS necessary for universal use. This has
been Saved as UKSTOICB.COM.

Further files giving special facilities are on this disc
in .STC form, fully annotated, and in some cases with
appropriate .DOC files. These can be added to UKSTOICB as
required. All of them could be compiled into one big
DICTIONARY - if you have sufficient memory!  But
however you go, you will always finish up with a stan-
dard STOIC DICTIONARY obeying a standard set of rules.

UKSTOICE.COM is the compilation of STOICB plus the
CP/M filing program, the Editor and a file of useful
WORDS called UKMISC.STC. It is advisable to use this
DICTIONARY at all times, memory permitting, because
any of the other .STC files may be added, and full
developement work carried out using the Editor.

The second peculiarity of STOIC is that it uses the
STACK in preference to variables to pass the parameters
between WORDS . In fact, four stacks are used, but only
the parameter stack (STACK) need concern us now.

Numbers or data are pushed onto the STACK. The WORDS
pop the numbers they require off the STACK, operate on
them, and then push the results on the STACK for the
next WORD. This is why reversed polish notation (RPN)
is used. The parameters must be entered first, then
the operator. Because of this, very few variables need
to be declared in STOIC and the definition of recursive
procedures is greatly simplified.

The DICTIONARY is searched from the most recently def-
ined WORD backwards. Therefore any WORD may be renamed
or redefined and the new definition will then be found
although all previously defined WORDS which used the
old name will be unaffected.

A further facility is that STOIC can have any number
of different VOCABULARIES, each tracing a different
thread through the DICTIONARY, with its own starting
point. UKSTOICE has three VOCABULARIES, STOIC< - the
default one to which all others return, ASSEMBLER<
and EDITOR<. New ones may be added at will and called
as required by the program. The same name can thus be 
used by different WORDS in different VOCABULARIES.

For example, L is the L Register in the CPU in
ASSEMBLER<, but means "move cursor n lines" in
EDITOR<.

The ASSEMBLER and the EDITOR are, of course, written
in STOIC so they are able to use STOIC WORDS as pro-
cedures and addresses while they are running, and
local macros may be defined within them .

Finally, not only can new words be defined, but new
classes of words which, when called, can allow subclasses
to be defined with common characteristics.

Every byte of the DICTIONARY is accessable to the
programmer, because addresses may be manipulated as
easily as data. The boundary between program and data
is blurred because areas of DICTIONARY may be named
as reserved for data, enabling programs to be inter-
laced without conflict of storage areas.

STOIC is perforce highly structured and easily transport-
able. This gives a very compact, fast and powerful
package. There is a price to pay for this versatility -
less tolerance to error. The system can be crashed
although there are built in safety measures and error
reporting. STOIC can operate in any RADIX, decimal,
hex and octal being named options, thus it is easy
to mix up the RADIX when mixing programs.

All entries to STOIC are compiled into a compile
buffer. If the line is a command, it is then executed
and deleted. If it is a definition it is transferred
to the DICTIONARY instead of execution. Thus all
looking up, checking and compiling is done at entry
time, not at run time, hence the high speed.

For those concerned with software security, it is
interesting to note that disassembly of STOIC is
extremely difficult.



***EOF***