

                Macros for names in the documentation













\input texinfo
@setfilename ci86.lina.texinfo
@afourpaper
@settitle ciforth manual
@setchapternewpage odd

@titlepage
@title ciforth manual
A close-to-ISO/common intel/computer intelligence/CH+ forth.

This is a standard-ISO Forth (mostly, see the section portability)
for the configuration called lina:
@itemize @bullet
@item
version 4.0.6 
@item
32-bits protected mode 
@item
running under Linux 

@item
contains security words 
@item
kernel contains the full ISO CORE set
@item
headers with source fields

@end itemize

@author Albert van der Horst
Dutch Forth Workshop


@page
@c @vskip Opt plus 1fill
Copyright @copyright{} 2000 Dutch Forth Workshop

Permission is granted to copy with attribution.
Program is protected by the GNU Public License.
@end titlepage

@page
@node Top, Gentle Introduction, Glossary,
@chapter Overview
Forth is an interactive programming system.
ciforth is a family of
Forth's that can be generated in many different version
for many different operation systems.
It is sufficiently close to the ISO standard to run most programs intended
to be portable. It deviates where less used features where
objectionable to implement. @xref{Manual}, Section Portability.

This file documents what you as a user needs to know for using this
particular version of ciforth called ``lina'' once it is installed on your system.

ciforth consists of three files:
@itemize @bullet
@item
   @file{lina}    : the program

@item
@file{ciforth.ps} @file{ciforth.html} : the documentation
@item
@file{forth.lab} : source library for auxiliary programs
@end itemize

These files are generated together by a generic system from the file
@file{fig86.gnr} .
The documentation applies to the ciforth with which it goes.

If your Forth doesn't fit the description below get a new version.
The information below allows an expert to reconstruct how to
generate a corresponding version. Not all of it may make
sense to you. Tell him whether you want to
fit the Forth to the description or vice versa
(@pxref{Rationale & legalese}).

These are the features:

All ciforth's are @dfn{case sensitive}
@cindex case sensitive
.
This is version 4.0.6 .
It is running in protected mode.     
It is running under Linux.          A number has a precision of 32 bits.  It calls linux system from Forth directly.  It has compiler security, sacrificing some bizarre ISO
compatibity. It doesn't use @code{>IN}
@findex >IN
 exactly in the way prescribed by ISO.   It contains the full ISO CORE in the kernel,
more than is needed to make it self contained. It contains a field in the header to point to source. It is indirect threaded.

@iftex
If you are new to Forth you may want to read the Gentle Introduction,
otherwise you better skip it. The third chapter most users will not
be interested in.
@end iftex

@menu
* Gentle Introduction:: For newbies to Forth. You don't want to read this.
* Rationale & legalese:: For experts. You don't want to read this.
* Manual::         User manual
* Assembler::      The assemblers
* Errors::  What means @samp{ ciforth ERROR ###}?
* Documentation::  Some references
* Glossary::       Description of Forth words
* Glossary Index:: Find a Forth words in the glossary
* Forth Word Index:: All references to Forth words
* Concept Index::
@end menu

@node Gentle Introduction, Rationale & legalese, top, top
@chapter Gentle introduction
A Forth system is a database of small programs.
The database is called the dictionary.
The programs are called @dfn{word}
@cindex word
's, or definitions.
The explanation of words from the dictionary is called
a glossary.

First of all, a Forth system is an environment that you enter by
running it: @* @samp{lina} @* Like
in a Disk Operating System a @dfn{word}
@cindex word
 is executed
by typing its name, but unlike in a DOS several programs
can be specified on the same line, interspersed with
numbers. Also names can be anything, as long as they don't
contain spaces.

A program may leave one or more
results, and the next program can use it.
The latest result is used up first, hence the name lifo buffer.
(last in, first out).

For example:

@example
@iftex
@cartouche
albert@@apple:~/forth/fig86 > lina

80386 ciforth beta $RCSfile: ci86.gnr,v $ $Revision: 3.275 $

1 2 + 7 *
 OK
.
21  OK 
@end cartouche
@end iftex
@ifinfo
albert@@apple:~/forth/fig86 > lina

80386 ciforth beta $RCSfile: ci86.gnr,v $ $Revision: 3.275 $

1 2 + 7 *
 OK
.
21  OK 
@end ifinfo
@end example

1 2 and 7 are numbers and are just remembered as they are typed in.
@samp{OK} and @samp{21 OK} are the answer of the
computer.
@code{+}
@findex +
 is a small program with an appropriate name.
It adds the two numbers that were entered the latest, in this
case 1 and 2. The result 3 remains, but 1 and 2 are consumed.
Note that a name can be anything, as long as it doesn't contain
spaces.
The program @code{*}
@findex *
 multiplies the 3 and the 7 and the result is 21.
The program @code{.}
@findex .
 prints this results. It could have
been put on the same line equally easily.

Programs can be added to the database by special programs: the so
called @dfn{defining word}
@cindex defining word
's. A defining word generally gets the name of the
new word from the input line.

For example: a constant is just a program that leaves always
the same value.
A constant is created in this way, by the defining word @code{CONSTANT}
@findex CONSTANT
 :

@example
@iftex
@cartouche
127 CONSTANT MONKEY   12 .
12 OK
@end cartouche
@end iftex
@ifinfo
127 CONSTANT MONKEY   12 .
12 OK
@end ifinfo
@end example

You may get @samp{ constant ? ciforth ERROR # 12 : NOT RECOGNIZED }.
That is because you didn't type in what I said.
lina is case sensitive.
If you want to change that consult the section "Common problems".
(@pxref{Errors}).

This must not be read like:
@*
 a number, two programs and again a number etc.... ,
@*
but as:
@*
a number, a program and a name that is consumed,
@*
and after that
life goes on. The @samp{12 .} we put there for demonstration purposes,
to show that @code{CONSTANT}
@findex CONSTANT
 reads ahead only one word.
On this single line we do two things, defining @samp{MONKEY} and printing the
number 12.
We see that @code{CONSTANT}
@findex CONSTANT
 like any other program consumes some
data, in this case the 127 that serves as an initial value for
the constant called  @samp{MONKEY} .

A very important defining word is @code{:}
@findex :
, with its closure
@code{;}
@findex ;
.

@example
@iftex
@cartouche
: TEST 1 2 + 7 * ;     12 .
12 OK 
@end cartouche
@end iftex
@ifinfo
: TEST 1 2 + 7 * ;     12 .
12 OK 
@end ifinfo
@end example


In this case not only the name @samp{TEST} is consumed, but none
of the remaining numbers and programs are executed, up till the
semicolon @code{;}
@findex ;
.
Instead they form a specification of what @samp{TEST} must do.
This state, where Forth is building up a definition, is called
@dfn{compilation mode}
@cindex compilation mode
 .
After the semicolon life continues as usual.
Note that @code{;}
@findex ;
 is a program in itself too.
But it doesn't become part of @code{TEST}
@findex TEST
 . Instead it is executed
immediately.
It does little more than turning off compilation mode.

@example
@iftex
@cartouche
TEST TEST + .
42  OK
: TEST+1 TEST 1 + . ;  TEST+1
22 OK
@end cartouche
@end iftex
@ifinfo
TEST TEST + .
42  OK
: TEST+1 TEST 1 + . ;  TEST+1
22 OK
@end ifinfo
@end example

We see that @samp{TEST} behaves as a shorthand for the line up till
the semi colon, and that in its turn it can be used as a building
block.

The colon allows the Forth programmer to add new programs
easily and test them easily, by typing them at the keyboard.
It is considered bad style if a program is longer than
a couple of lines.
Indeed the inventor of Forth Chuck Moore has written splendid
applications with an average program length of about one line.
Cathedrals were built by laying stone upon stone,
never carved out of one rock.

The implementation of the language Forth you look at is old
fashioned, but simple. You as a user have to deal with only three
parts/files : this documentation, the executable program, and the
library file, a heap of small programs in source form.
There may be several documentation files, but they contain the
same information in a different format.

There is an ISO standard for Forth and this Forth doesn't fully
comply to it. Still by restricting yourself to the definitions marked
as ISO in the glossary, it is quite possible to write an application
that will run on any ISO-compliant system.

Because of the way Forth remembers numbers
you can always interrupt your work and continue.
For example
@example
@iftex
@cartouche
: TEST-AGAIN
1 2 + [ 3 4 * . ]
12 OK
7 * ;
OK 
@end cartouche
@end iftex
@ifinfo
: TEST-AGAIN
1 2 + [ 3 4 * . ]
12 OK
7 * ;
OK 
@end ifinfo
@end example
What happened here is that
some one asked you to calculate  ``3 times 4'' while you
were busy with our test example. No sweat!
You switch from compilation mode
to normal (interpret) mode by @code{[}
@findex [
 , and back
by @code{]}
@findex ]
.
In the meantime, as long as you don't leave numbers behind,
you can do anything.
(This doesn't apply to adding definitions, as you are
in the process of adding one already.)


@node Rationale & legalese, Manual, Gentle Introduction, top
@chapter  Rationale & legalese
@section                        Legalese
This application currently is copyright by Albert van der Horst.
This Forth is called ciforth and is made available by the
D.F.W..
All publications of the D.F.W. are available under GPL, the GNU public license.
The file @file{COPYING} containing the legal expression of these
lines must accompany it.

Because Forth is ``programming by extending the language'' the GPL
could be construed to mean that systems based on ciforth
always are legally obliged to make the source available.
But we consider this ``fair use in the Forth sense'' as
expressed by the following statement.

In addition to the GPL Albert van der Horst grants the following rights
in writing:

The GPL is interpreted in the sense that a system based on ciforth
and intended to serve a particular purpose, that purpose not being a
``general purpose Forth system'', is fair use of the system, even if it
could accomplish everything ciforth could, under the condition that the
ciforth it is based on is available in accordance to the GPL rules,
and this is made known to the user of the derived system.

@section                         Rationale

This Forth is meant to be simple.
What you find here is a Forth for the Intel 86.
You need just the executable to work.
You choose the format you prefer for the documentation.
They all have the same content.
You can use the example
file with blocks,
you have the assembler source for your Forth,
but you can ignore both.

@section                         Source
In practice the GPL
 means (: this is an explanation and has no legal value!)

They may be
further reproduced and distributed subject to the following conditions:

The three files comprising it must be kept together and in particular
the reference section with the World Wide Web sites.


The latest version of lina is found at
@*
@samp{http://home.hccnet.nl/a.w.m.van.der.horst/ciforth.html}.

Via that link you can also download ciforth's for other OS's and
the generic system, if you want to make important modifications.
Also you can see how you can contact the author.
Otherwise in case of questions about this ciforth, contact the person or
organisation that generated it for you.

This Forth builds on fig-Forth. It is based on the work of
Charlie Krajewski and Thomas Newman, Hayward, Ca. still
available via taygeta. The acknowledgments for systems that
serves as a base, in particular the original fig-Forth, are
found in the generic documentation, including detailed
information how these systems can be obtained.

@b{Important:}
@* If you just want to use a Forth,
you most certainly do not want the generic system.
Great effort is expended in making sure that this
manual contains all that you need, and nothing that might
confuse you. The generic system on the contrary contains lots
that you don't need, and is confusing as hell.

If you are interested in subjects like history of Forth,
the rationale behind the design and such you might want to read the
manual for the generic Forth.
@section The Generic System this Forth is based on.

The source and executable of this ciforth was generated, out of at
least dozens of possibilities, by a generic system.
You can configure
the operating system, memory sizes, file names and minor issues like
security policy. You can select between a 16 and 32 bit word size.
You may undertake more fundamental changes by adapting one or more of
the macro header files.
An important goal
was to generate exactly fitting documentation, that contains only
relevant information and with some care your configuration will have
that too.
This generic system can be obtained via
@samp{http://home.hccnet.nl/a.w.m.van.der.horst/ciforth.html}.
                                                              `


@node Manual, Assembler, Rationale & legalese, top



@chapter Manual
@section Getting started

@subsection Hello world!

Type @samp{lina} to get into your interactive Forth system.
You will see a signon message.
While sitting in your interactive Forth doing a ``hello world'' is easy:
@example
@iftex
@cartouche
"Hello world!" TYPE
Hello world! OK 
@end cartouche
@end iftex
@ifinfo
"Hello world!" TYPE
Hello world! OK 
@end ifinfo
@end example
@*
Making it into an interactively usable program is also easy:
@example
@iftex
@cartouche
: HELLO "Hello world!" TYPE CR ;
OK
HELLO
Hello world!
OK 
@end cartouche
@end iftex
@ifinfo
: HELLO "Hello world!" TYPE CR ;
OK
HELLO
Hello world!
OK 
@end ifinfo
@end example
This means you type the command @samp{HELLO} while you
are in lina. As soon as you leave lina, this command
is gone.

@*
In order to make a stand alone program to say hello you have to
save the source to a file, such as @file{hello.frt}.
It just contains the definition we typed earlier:
@example
@iftex
@cartouche
 : HELLO "Hello world!" TYPE CR ;
@end cartouche
@end iftex
@ifinfo
 : HELLO "Hello world!" TYPE CR ;
@end ifinfo
@end example
Now build the program by
@*
lina -c hello.frt
@*
(That is @kbd{c} for compile.)
The result is a file @file{hello} .
For the compiler to run you must have the library correctly
installed.

If that failed, or anything else fails, you will
get a message with at least @samp{ ciforth ERROR ###}
and hopefully some more or less helpful text as well.
The @samp{###} is an error number. @xref{Errors}, Section Explanations.

Note for the old hands. Indeed the quoted strings are not ISO.
They surely are a Forth-like extension. Read up on denotations,
and the definition of @code{"}
@findex "
 .

In lina you never have to worry about those quoted strings,
they are allocated in the dictionary and are permanent.

@subsection The library.

If you want to run a program written on some other Forth, it
may use facilities that are not available in lina's kernel,
but they may be available in the @dfn{library}
@cindex library
.
A library is a store with facilities, available on demand.
Forth as such doesn't have a library mechanism,
but lina does.

lina uses the @dfn{blocks}
@cindex blocks
 as a library
by addition of the word @code{REQUIRED}
@findex REQUIRED
 and a convention.
Starting with @samp{lina -r} or most any option you have this
facility available. If you are already in lina, you can
type @samp{1 LOAD}.
 The extension of @samp{.lab} in
@file{forth.lab} means Library Addressable by Block.

Now we will add @code{DO-DEBUG}
@findex DO-DEBUG
 using this library mechanism.
It is used immediately.
It is handy during development, after every line it
shows you what numbers Forth remembers for you.
Also from now on
the header of each
block that is @code{LOAD}
@findex LOAD
-ed is shown. @*
Type (@samp{1 LOAD} may not be necessary):
@example
@iftex
@cartouche
1 LOAD
"DO-DEBUG" REQUIRED
OK
DO-DEBUG

S[ ] OK 1

S[ 1 ] OK
@end cartouche
@end iftex
@ifinfo
1 LOAD
"DO-DEBUG" REQUIRED
OK
DO-DEBUG

S[ ] OK 1

S[ 1 ] OK
@end ifinfo
@end example
You can turn @code{DO-DEBUG}
@findex DO-DEBUG
 off with @code{NO-DEBUG}
@findex NO-DEBUG
 .

If you try to @code{INCLUDE}
@findex INCLUDE
 a program, you may
get errors like @samp{TUCK? ciforth ERROR # 12 : NOT RECOGNIZED}.
@xref{Errors}, Section Explanations.
Apparently, lina doesn't know about a forth word named
@code{TUCK}
@findex TUCK
, but after @samp{"TUCK" REQUIRED} maybe
it does. You may try again.

The convention about the way the library file must be
organized for @code{REQUIRED}
@findex REQUIRED
 to find something is
simple. It is divided into blocks of 16 lines.
The first line is the header of the block. If the word
we are looking for is mentioned in the header, that
block is compiled.

The library file contains examples for you
to load using @code{REQUIRE}
@findex REQUIRE
 .
Try
@example
@iftex
@cartouche
REQUIRE SIEVE
LIM # 4 ISN'T UNIQUE
OK
10 SIEVE
KEY FOR NEXT SCREEN
ERATOSTHENES SIEVE -- PRIMES LESS THAN 10 000
0 002 003 ...
(lots of prime numbers.)
@end cartouche
@end iftex
@ifinfo
REQUIRE SIEVE
LIM # 4 ISN'T UNIQUE
OK
10 SIEVE
KEY FOR NEXT SCREEN
ERATOSTHENES SIEVE -- PRIMES LESS THAN 10 000
0 002 003 ...
(lots of prime numbers.)
@end ifinfo
@end example

@subsection Development.

If you want to try things out, or write a program -- as
opposed to just running a ready made program -- you best
start up lina by @samp{lina -e}.
That is @kbd{e} for elective. That name means
that you 
 can configure this screen 5 to suit your particular needs.
@*
You will have available:
@enumerate
@item
@code{REQUIRED}
@findex REQUIRED
 and @code{REQUIRE}
@findex REQUIRE
 .
@samp{REQUIRE xxx} is equivalent to
@samp{"xxx" REQUIRED} , but it is more convenient.
@item
 @code{DH.}
@findex DH.
 @code{H.}
@findex H.
 @code{B.}
@findex B.
 @code{DUMP}
@findex DUMP
 @code{FARDUMP}
@findex FARDUMP

For showing numbers in hex and parts of memory.
 
@item
 @code{CRACK}
@findex CRACK

To analyse words, showing the source code of compiled words.
 
@item
 @code{LOCATE}
@findex LOCATE

To show the block of the library file where a word is located.
 
 
@item
@code{OS-IMPORT}
@findex OS-IMPORT

 
To be able to type shell-commands from within Forth as if you
were in a terminal window.
 .
 .
 .
@end enumerate
 
Because this ciforth is ``hosted'', meaning that it is started from
an operating system, you can develop in a convenient way.
Start lina in a window, and use a separate window to start your
editor. Try out things in lina. If they work, paste the code into
your editor. If a word works, but its source has scrolled off the screen,
you can recover the source using @code{CRACK}
@findex CRACK
 .
If you have constructed a part or all of your program,
you can save it from your editor to a file. Then by the command
@samp{INCLUDE <file-name> } load the program in lina
and do some further testing.

You are not obliged to work with separate windows.
Suppose your favorite editor
is called @file{vi}. After


@example
@iftex
@cartouche
 "vi" OS-IMPORT vi 
@end cartouche
@end iftex
@ifinfo
 "vi" OS-IMPORT vi 
@end ifinfo
@end example

you can start editing a file in the same way as from
 the shell.
Of course you now have to switch between editing a file
and lina. But at least you need not set up your Forth again,
until your testing causes your Forth to crash.
 

@subsection Finding things out.
If you want to find things out
you must
start up lina again by @samp{lina -e}.
The sequence
@example
@iftex
@cartouche
REQUIRE TUCK
LOCATE TUCK
@end cartouche
@end iftex
@ifinfo
REQUIRE TUCK
LOCATE TUCK
@end ifinfo
@end example
shows you the source for TUCK if it is in the library somewhere.
@example
@iftex
@cartouche
REQUIRE TUCK
CRACK TUCK
@end cartouche
@end iftex
@ifinfo
REQUIRE TUCK
CRACK TUCK
@end ifinfo
@end example
show you the source for TUCK if it is in the library or in the kernel,
but without comment or usage information.

@section Configuring
For configuring your lina, without enlarging the dictionary,
you may use the following sequence
@example
@iftex
@cartouche
 S" myforth.lab" BLOCK-FILE $! \ Or any config
1 LOAD
REQUIRE SAVE-SYSTEM
: DOIT
    'CONTAINS 'FORTH FORGET-VOC
    'CONTAINS >NFA @ DP !
    "newforth" SAVE-SYSTEM BYE ;
DOIT 
@end cartouche
@end iftex
@ifinfo
 S" myforth.lab" BLOCK-FILE $! \ Or any config
1 LOAD
REQUIRE SAVE-SYSTEM
: DOIT
    'CONTAINS 'FORTH FORGET-VOC
    'CONTAINS >NFA @ DP !
    "newforth" SAVE-SYSTEM BYE ;
DOIT 
@end ifinfo
@end example
Here @samp{DOIT} trims the dictionary just before the saving your system into a new
file.
You can use a similar sequence for expanding the system without
building in the @code{SAVE-SYSTEM}
@findex SAVE-SYSTEM
 command as well.

@code{FAR-DP}
@findex FAR-DP
 allows have a disposable part of the
dictionary. This may be occasionally useful, but make sure to
@code{FORGET}
@findex FORGET
 always the disposed off words.


@section Concepts

A forth user is well aware of how the memory of his
computer is organised. He allocates it for certain purposes,
and frees it again at will.

The last-in first-out buffer that remembers data for us is called
the @dfn{data stack}
@cindex data stack
 or sometimes @dfn{computation stack}
@cindex computation stack
.
There are other stacks around,
but if there is no confusion it is often called just the @dfn{stack}
@cindex stack
.
Every stack is in fact a buffer and needs also a @dfn{stack pointer}
@cindex stack pointer
to keep track of how far it has been filled.
It is just the address where the last data item has been stored in the buffer.

The @dfn{dictionary}
@cindex dictionary
 is the part of the memory where the @dfn{word}'s are
(@pxref{DICTIONARY}).
Each word owns a part of the dictionary, starting with its name and
ending where the name of the next word starts.
This structure is called a @dfn{dictionary entry}
@cindex dictionary entry
.
Its address is called a @dfn{dictionary entry address}
@cindex dictionary entry address
or @dfn{DEA}
@cindex DEA
. In ciforth's this address is used for external
reference in a consistent way. For example it is used as the
@dfn{execution token}
@cindex execution token
 of a word in the ISO sense.
In building a word the boundary between the dictionary and the free space shifts up.
This process is called @dfn{allocating}
@cindex allocating
, and the boundary is marked by
a @dfn{dictionary pointer}
@cindex dictionary pointer
 called @code{DP}
@findex DP
 .
A word can be executed by typing its name.
Each word in the dictionary belongs to precisely one @dfn{word list}
@cindex word list
,
or as we will say here vocabulary.
Apart from the name, a word contains data and executable code,
(interpreted or not) and linking information
(@pxref{VOCABULARY}).

The concept word list is part of the ISO standard, but we will
use @dfn{vocabulary}
@cindex vocabulary
. A vocabulary is much more
convenient, being a word list with a name, created by
@code{VOCABULARY}
@findex VOCABULARY
 . ISO merely knows
@dfn{word list identifier}
@cindex word list identifier
 's, a kind of handle,
abbreviated as @dfn{WID}
@cindex WID
. A new word list is
created by the use of @code{VOCABULARY}
@findex VOCABULARY
, and
by executing the vocabulary word the associated
word list is pushed
to the front of the search order.
In fact in ciforth's every DEA can serve as a WID. It defines a
wordlist consisting of itself and all earlier words in the same
vocabulary.
If needed you can
always derive the WID from the DEA of a vocabulary.

A word that is defined using @code{:}
@findex :
 is often called a
@dfn{colon definition}
@cindex colon definition
. Its code is called
@dfn{high level}
@cindex high level
 code.

A high level word, one defined by @code{:}
@findex :
 , is little more than a
sequence of addresses of other words. The @dfn{inner interpreter}
@cindex inner interpreter
takes care to execute these words in order.
It acts by fetching the address pointed by @samp{HIP} , storing
this value in register @samp{W}. It then jumps to the address
pointed to by the address pointed to by @samp{W}. @samp{W} points to the code field of a definition which contains the address of
the code which executes for that definition. This usage of indirect
threaded code is a major contributor to the power, portability, and
extensibility of Forth.

If the inner interpreter must execute another high level word,
while it is interpreting, it must remember the old value of
@samp{HIP}, and this so called @dfn{nesting}
@cindex nesting
 could go several
levels deep.
Keeping this on the data stack would interfere with the data the
words are expecting, so they are kept on a separate stack, the
@dfn{return stack}
@cindex return stack
.
The usage of two stacks is another hall mark of Forth.

A word that generates a new entry in the dictionary is called a
@dfn{defining word}
@cindex defining word
 (@pxref{DEFINING}).
The new word is created in the @code{CURRENT}
@findex CURRENT
 word list .

Each processor has a natural size for the information. (This is
sometimes called a machine word). For an Pentium processor this is
32 bit, for the older Intel 8086 it is 16 bit.
The pendant in Forth is called a @dfn{cell}
@cindex cell
 and its size
may deviate from the processor you are running on.
For this ciforth it is 32,
It applies to the data remembered in the data stack, the
return addresses on the return stack,
memory accesses @code{@@}
@findex @@
 and @code{!}
@findex !
 , the size of @code{VARIABLE}
@findex VARIABLE
' s
and @code{CONSTANT}
@findex CONSTANT
' s.
In Forth a cell has no hair. It is interpreted by you as a
signed integer, a bit-map, a memory address or an unsigned number.
The operator @code{+}
@findex +
 can be used to add numbers, to set a bit in
a bitmap or advance a pointer a couple of bytes.
In accordance with this there are no errors such as overflow given.

Sometimes we use data of two cells, a @dfn{double}
@cindex double
.
The high-order cell are most accessible on the stack and if stored in
memory, it is highest.

The code for a high level word can be typed in from the
terminal, but it can also fed into Forth by redirection from a
file, @code{INCLUDED}
@findex INCLUDED
 from a file or you can
@dfn{load}
@cindex load
 it from the file @file{forth.lab},
because you can load a piece of this library at will once you
know the block number. This file is divided into
@dfn{blocks}
@cindex blocks
 of 1 Kbyte. They may contain any data, but
a most important application is containing source code. A block
contain source code is called a @dfn{screen}
@cindex screen
. It
consists of 16 lines of 64 characters. In ciforth the 64-th
character is @kbd{^J} such that they may be edited in a
normal way with some editors. To @dfn{load}
@cindex load
 such a
screen has the same effect as typing its content from the
terminal.
The extension lab stands for @dfn{Library Addressable by Block}
@cindex Library Addressable by Block
,

Traditionally Forthers have things called
@dfn{number}
@cindex number
's, words that are present in the source be
it interpreted or compiled, and are thought of not as being
executed but rather being a description of something to be put
on the stack directly. In early implementations the word @samp{NUMBER}
was a catch-all for anything not found in the dictionary, and
could be adapted to the application.
For such an extensible language as
Forth, and in particular where strings and floating point
numbers play an increasing role, numbers must be generalised to
the concept of @dfn{denotation}
@cindex denotation
's.
The need for a way to
catch those is as present as it was in those early days.
Denotations put a
constant object on the stack without the need to define it
first. Naturally they look, and in fact are, the same in both
modes. Here we adopt a practice of selecting a type of the denotations
based on the first letter. This is quite practical and familiar.
Examples of this are (some from C, some from assemblers, some
from this Forth) :
@example
@iftex
@cartouche
10
'a'
^A
0DEAD
$8000403A
#3487
0177
"Arpeggio"
"JAMES BROWN IS DEAD"
" JK "
'DROP
' DROP
@end cartouche
@end iftex
@ifinfo
10
'a'
^A
0DEAD
$8000403A
#3487
0177
"Arpeggio"
"JAMES BROWN IS DEAD"
" JK "
'DROP
' DROP
@end ifinfo
@end example
These examples demonstrate
that a denotation may contain spaces, and still are easy to scan.
And yes, I insist that @samp{' DROP} is a denotation.
But @samp{'DROP} is clearer,
because it can only be interpreted as such;
it is not a valid word.

Of course a sensible programmer will not define a word that looks like
a denotation :
@example
@iftex
@cartouche
 : 7 CR "This must be my lucky day" TYPE ; ( DON'T DO THIS) 
@end cartouche
@end iftex
@ifinfo
 : 7 CR "This must be my lucky day" TYPE ; ( DON'T DO THIS) 
@end ifinfo
@end example
@section Portability
If you build your words from the words defined in the ISO standard,
and are otherwise careful, your programs may run on other systems that
are ISO standard.

There are no gratuitous deviations from the standard.
However a few things are not quite conforming.
@enumerate
@item
The error system uses @code{CATCH}
@findex CATCH
 and @code{THROW}
@findex THROW
 in a conforming way.
However the codes are not assigned according to the table
in the standard. Instead positive numbers are ciforth errors
and documented in this manual.
ciforth's errors identify a problem more precisely than the
standard allows. An error condition that is not detected
has no number assigned to it.
Negative numbers are identical
to the numbers used by the host operating system.
No attempt is made to do better than reproduce the messages
belonging to the number as given by strerror. 
@item
It is not possible to catch the following words :
@code{ABORT"}
@findex ABORT"
 @code{ABORT}
@findex ABORT
 @code{QUIT}
@findex QUIT
 .
@item
There is no @code{REFILL}
@findex REFILL
 . This is a matter of
philosophy in the background. You may not notice it.
@*
Consequences are that @code{BLK}
@findex BLK
 is not inspected for every
word interpreted, but that blocks in use are locked.
Files are not read line by line, but read in full and
evaluated.

@item
It doesn't use @code{>IN}
@findex >IN
 exactly in the way prescribed by ISO.
The @code{>IN}
@findex >IN
 that is there is a fake, that can only be
read, not changed.
 @item
Vocabularies are wordlists with a name. However they push the wordlist
to the search order, instead of replacing the topmost one.
In this sense @code{FORTH}
@findex FORTH
 and @code{ASSEMBLER}
@findex ASSEMBLER
 words are not
strictly conforming.
@item
This is not strictly non-conforming, but worth mentioning here.
In fact lina contains only one state-smart word
besides @code{SLITERAL}
@findex SLITERAL
 (that word is @code{."}
@findex ."
 ).
All denotations are state-smart,
but the result is correct ISO behaviour for numbers.
Knowledge of this is used freely in the libraries of ciforth;
it is the right of a system developer to do so.
The library is not a supposedly ISO-conforming program.
It tends to rely on
ciforth-specific and lina-specific -- but hopefully documented -- behaviour.
Understanding it requires some study of non-portable facilities.
@end enumerate

Here we will explain how you must read the glossary of lina,
in relation to terminology in the ISO standard.

Whenever the glossary specifies under which conditions a word may
 @dfn{crash}
@cindex crash
, then you will see the euphemism @dfn{ambiguous condition}
@cindex ambiguous condition
 in
the ISO standard.

For example:
@*
Using @code{HOLD} other than between
@code{<#} and @code{#>} leads to a crash.

Whenever we explicitly mention ciforth in a sentence that appears
in a glossary entry,
the behaviour may not apply to other ISO standard systems.
This is called @dfn{ciforth specific behaviour}
@cindex ciforth specific behaviour
. If it mentions ``this ciforth'' or ``lina'', you cannot even trust that
behaviour to be the same on other ciforth systems.
Often this is called an ``implementation defined'' behaviour in the standard.
Indeed we are obliged to specify this behaviour in our glossary,
or we don't comply to the standard.
The behaviour of the other system may very well be a crash.
In that case the standard probably declares this an ``ambiguous condition''.

For example:
@*
On this ciforth @code{OUT} is set to zero whenever @code{CR} is executed.

The bottom line is that you never want to write code where
lina may crash.
And that if you want your code to run on some other system,
you do not want to rely on @dfn{ciforth specific behaviour}
@cindex ciforth specific behaviour
.
If you couldn't get around that,
you must keep the specific code separate.
That part has to be checked carefully against the documentation
of any other system,
where you want your code to run on.

By using @code{CELL+}
@findex CELL+
 it is easy to keep your code 16/32 bit clean.
This means that it runs on 16 and 32 bits systems.
@section Saving a new system
We have said it before: ``Programming Forth is extending the Forth language.''.
A facility to save your system after it has been extended is of the essential.
It can be argued that if you don't have that, you ain't have no Forth.
It is used for two purposes, that are in fact the same.
Make a customised Forth, like @b{you} want to have it.
Make a customised environment, like a customer wants to have it.
Such a ``customised environment'', for example a game, is often
called a @dfn{turnkey system}
@cindex turnkey system
 in Forth parlance.
It hides the normal working of the underlying Forth.

In fact this is what in other languages would be called ``just compiling'',
but compiling in Forth means adding definitions to an interactive Forth.
In ciforth ``just compiling'' is as easy as in any language
(@pxref{Manual}, Hello world!).
Of course, whether you have a
hosted system like this one  or
a booted system , it is clear that some
system-dependant information goes into accomplishing this.

This has all been sorted out for you. Just use
@code{SAVE-SYSTEM}
@findex SAVE-SYSTEM
 .
This accepts a string, the name you want the
program-file to have.

In the following it is explained.
We use the naming convention of ISO about cells.
A cell is the fundamental unit of storage for the Forth engine.
Here it is 32 bits (4 bytes).

The change of the boot-up parameters at
@code{+ORIGIN}
@findex +ORIGIN
, in combination with storing an image on disk
goes a long way to extending the system.
This proceeds as follows:
@enumerate
@item
All user variables are saved by copying them from @samp{U0 @@}
to @samp{0 +ORIGIN}.
The user variable @code{U0}
@findex U0
 points to the start of the user area. The length of the area is 0x40 cells.
If in doubt check out the variable @samp{US} in the assembler code.
@item
If all user variables are to be initialised to what they are in this live system
skip the next step.
@item
Adjust any variables to what you want them to be in the
saved system in the @code{+ORIGIN}
@findex +ORIGIN
 area.
The initialisation for user variable @samp{Q} can be found at
    @samp{' Q >DFA @@ +ORIGIN}.
@item
Adjust
version information (if needed)
@item
Copy your lina to a new file using @code{PUT-FILE}
@findex PUT-FILE
 .
The difficult part is to add to the system specific header information
about the new size of the system, which is
the area from @code{BM}
@findex BM
 to @code{HERE}
@findex HERE
.
The command @samp{REQUIRE SAVE-SYSTEM} loads
a version that does that correctly for your hosted system.
@end enumerate

@section Memory organization

A running ciforth has 3 distinct memory areas.

They occur sequentially from low memory to high.
@itemize @bullet
@item
The dictionary
@item
Free memory, available for dictionary, from below, and stacks, from above
@item
Stacks, disk block buffers  and terminal
input buffer.
@end itemize
The lowest part of the free memory is used as a scratch area.



The program as residing on disk may contain startup code, but that is
of no concern for the usage.

The dictionary area is the only part that is initialised,
the other parts are just allocated.
Logically the Forth system consists of these 7 parts.
@itemize @bullet
@item
Boot-up parameters
@item
Machine code definitions
@item
Installation dependant code
@item
High level standard definitions
@item
High level user definitions
@item
System tools (optional)
@item
RAM memory workspace
@end itemize

@subsection Boot-up Parameters

The boot-up area contains initial
values for the registers needed for the Forth engine,
like stack pointers, the pointers to the special memory area's,
and the very important dictionary pointer @code{DP}
@findex DP
that determines the boundary between the dictionary and free space.

Instead they are copied to a separate area the @dfn{user area}
@cindex user area
 ,
each time Forth is started.
The bootup area itself is not changed, but the variables in the user
area are.
By having several user area's, and switching between them,
ciforth could support multitasking.
When you have made extensions to your system, like for instance you
have loaded an editor, you can make these permanent by updating the
initial values in the boot-area and saving the result to disk as an
executable program.
The boot-up parameters
extends from @samp{0 +ORIGIN} and has initial value for all
of the user area.
This is the image for the @dfn{user area}
@cindex user area
.

So in ciforth the bootup parameters are more or less the data field of the
@code{+ORIGIN}
@findex +ORIGIN
 word.
Executing @samp{0 +ORIGIN} leaves a pointer in this area.


@subsection                     Installation Dependent Code

@code{KEY}
@findex KEY
 @code{EMIT}
@findex EMIT
 @code{KEY?}
@findex KEY?
 @code{CR}
@findex CR
 and
@code{R/W}
@findex R/W
 are indeed different for different I/O models.
This is of little concern to you as a user,
because these are perfectly normal dictionary entries and the different
implementations serves to make them behave similarly.
There will however be more differences between the different configurations for
ciforth for these words than habitually.

@subsection                      Machine Code Definitions

The machine executable code definitions
play an important role because they
convert your computer into a standard Forth stack computer.
It is clear that although you can define words by other words,
you will hit a lowest level.
The @dfn{code word}
@cindex code word
's as these lowest level programs are called,
execute machine code directly, if you invoke them from
the terminal or from some other definition.
The other definitions, called @dfn{high level}
@cindex high level
 code,
ultimately execute a sequence of the machine executable code words.
The Forth @dfn{inner interpreter}
@cindex inner interpreter
 takes care that
these code words are executed in turn.

In the assembler source (if you care to look at it)
you will see that they are interspersed with the
high level Forth definitions.
In fact it is quite common to decide to rewrite a code definition in high level
Forth, or the other way around.

Again code words are perfectly normal dictionary entries.
@subsection                      High-level Standard Definitions

The high level standard definitions add all
the colon-definitions, user variables, constants, and variables that
must be available in a
"Forth stack computer" according to the ISO standard.
They comprise the bulk of
the system, enabling you to execute and compile from the terminal,
execute and
@dfn{load}
@cindex load
 code from disk to add definitions
etc.
Changes here will result in deviations from the standard,
so you probably want to leave this area alone.
Again these words are perfectly normal dictionary entries.
The technique described for the next section,
forget and recompile,
is not always possible here because of circular references.
That is in fact no problem with an assembler listing,
but it is if you load Forth code.

Again standard definitions words are perfectly normal dictionary entries.
@subsection                    User definitions

The user definitions
contain primarily definitions involving user interaction:
compiling aids, finding, forgetting, listing, and number formating.
Some of these are fixed by the ISO standard too.
These definitions are placed above the standard definitions to
facilitate modification.
That is you may @code{FORGET}
@findex FORGET
 part of
the high-level and re-compile altered definitions from disc.
This applies even to the ISO standard words from the
@samp{TOOLS} wordset like @code{DUMP}
@findex DUMP
 (show a memory area as
numbers and text) and @code{.S}
@findex .S
 (show the data stack).

Again these words are perfectly normal dictionary entries.
A number of entries that could easily be made loadable
are integrated in the assembler source of this ciforth version.
You can forget them, and load your own version from files or blocks.

Again user definitions words are perfectly normal dictionary entries.
@subsection                    System Tools

The boundary between categories are vague. A system tools is
contrary to a user tool, a larger set of cooperating words.
A text editor and machine code assembler are the first tools
normally available.
An assembler is
not part of ciforth as delivered, but it
is available after @samp{REQUIRE ASSEMBLERi86}.
It automatically loads the proper 32-bits version.
You can load a more elaborate assembler. @xref{Assembler}, Section Overview.
They are among the first candidates to be integrated into
your system by @code{SAVE-SYSTEM}
@findex SAVE-SYSTEM
 .

An editor is not part of ciforth as delivered.
Development in Linux uses the there available editors.
Even without tools, code can be
tested by piping it into Forth, then commanding Forth to
look to the console, as follows :
@*
@samp{ (echo 8 LOAD; cat pascal.frt - )| lina }
@*
Primitive and preliminary as this may seem,
it has been used for quite substantial developments like the
80386 assembler.
@*
More advanced is using Your Favorite Editor, followed by
including files:
@*
@samp{ "vim mysrc.frt" SYSTEM }
@*
@samp{ "mysrc.frt" INCLUDED }
@*
@xref{Manual}, Section Getting Started.

386 and a 8086
Forth assemblers are available in @file{forth.lab}.
They are loaded in accordance with the system that is run.

It is essential that you regard lina as just a way to get started
with Forth.
Forth is an extensible language, and you can set it to your hand.
But that also means that you must not hesitate to throw
away parts of the system you don't like, and rebuilt them
even in conflict with standards.
Additions and changes must be planned and
tested at the usual Forth high level.
Later you can rewrite them as code words.

Again words belonging to tools are perfectly normal dictionary entries.
@subsection                    RAM Workspace
The RAM workspace contains the compilation space for the dictionary,
disc buffers,  the computation and return stacks, the user area,
and the terminal input buffer,
From the fig-Forth user manual
@quotation
For a single user system, at least 2k bytes must be available above the
compiled system (the dictionary). A 16k byte total system is most typical.
@end quotation
It is indeed possible to do useful work,
like factoring numbers of a few hundred digits, in a workspace of 2k bytes.
More typical a workspace is several megabytes to over hundred megabytes.


32 bits system are set at 64Mbyte but this is arbitrary and could be set much
higher or lower without consequences for system load or whatever.
Before long we will put the dictionary space on I86-Linux to 4G minus
something and forget about this issue forver. 

The boundary between this area and the previous one is pretty sharp,
it is where @code{DP}
@findex DP
 points.
The other areas are not clearly separated at all.
But even this boundary constantly changes as you add and forget definitions.
@section Specific layouts
@subsection The layout of a dictionary entry

We will divide the dictionary in entries.
A @dfn{dictionary entry}
@cindex dictionary entry
 is a part of the dictionary that
belongs to a specific word.
A @dfn{dictionary entry address}
@cindex dictionary entry address
, abbreviated
@dfn{DEA}
@cindex DEA
 is a pointer to the header of
a dictionary entry.
In
ciforth a header extends from the lowest address of the entry, where the code
field is to the @dfn{past header address}
@cindex past header address
, just after the last field address.
A @dfn{dictionary entry} apart from the header owns a part of
the dictionary space that can extend before the header (mostly the
name of the entry) or after it (mostly data and code).

A dictionary entry has fields, and the addresses of fields directly
offset from the dictionary entry address, are called
@dfn{field address}
@cindex field address
. This is a bit strange terminology, but
it makes a distinction between those addresses and other addresses.
For example, this allows to make the distinction between a
@dfn{data field address}
@cindex data field address
, that is always present, and a
@dfn{data field}
@cindex data field
 in the ISO sense that has only a
(differing) meaning for
@code{CREATE}
@findex CREATE
 @code{DOES> }
@findex DOES> 
 definitions.
Typically, a field address contains a pointer. A
@dfn{data field address}
@cindex data field address
 contains a pointer to
near the @dfn{data field}
@cindex data field
, whenever the latter exists.

They go from lowest in memory to highest:
@enumerate
@item
The code field. This is one cell.
A pointer to such a field is called a @dfn{code field address}
@cindex code field address
.
It contains the address of the code to be executed for this word.
@item
The data field, of the DEA, not in the ISO sense.
This is one cell.
A pointer to such a field is called a @dfn{data field address}
@cindex data field address
.
It contains a pointer to an area owned by this definition.
@item
The flag field. This is one cell.
A pointer to such a field is called a @dfn{flag field address}
@cindex flag field address
.
For the meaning of the bits of the flag field sea below.
@item
The link field. This is one cell.
A pointer to such a field is called a @dfn{link field address}
@cindex link field address
.
It contains the
dictionary entry address of the last word that was
defined in the same @dfn{word list}
@cindex word list
 before this one.
@item
The name field. This is one cell.
This contains a pointer to a string.
A pointer to such a field is called a @dfn{name field address}
@cindex name field address
.
The name itself is stored outside of the dictionary header
in a regular string, i.e. a one cell count followed by as many characters.
Unfortunately, @dfn{name field address}
@cindex name field address
 is
sometimes used, where a @dfn{dictionary entry address}
@cindex dictionary entry address
 would
be more correct, especially in older documentation.
This came about because the
name was lowest in memory. That they happen to be the same is
no reason to confuse two completely different concepts. In this
Forth the code field address and the dictionary address are the
same, but not accidentally so. 
@item
The source field. This is one cell.
This can be used to hold a reference to the source,
a block number or a pointer to a string.
It has not been filled in, in the kernel system.
@item
Past the header . This is actually not a field, but the
free roaming dictionary. However, most of the time the part of
the dictionary space owned by a dictionary entry starts here. A
pointer to such a field is called a @dfn{past header
address}
@cindex past header
address
.
Mostly a @dfn{data field address}
@cindex data field address
 contains a
pointer to just this address.
@end enumerate

Note that the entries are not only in alphabetic order, they
are in order of essentiality. They are accessed by
@code{>CFA}
@findex >CFA
 @code{>DFA}
@findex >DFA
 @code{>FFA}
@findex >FFA
 @code{>LFA}
@findex >LFA
 @code{>NFA}
@findex >NFA
 @code{>SFA}
@findex >SFA
 .

Note @dfn{data field}
@cindex data field
 has a specific meaning in the ISO
standard. It is accessed through @code{>BODY}
@findex >BODY
 from the
@dfn{execution token}
@cindex execution token
 while a data field address is
accessed through @code{>DFA}
@findex >DFA
 from the
@dfn{dictionary entry address}
@cindex dictionary entry address
. It is in fact one cell
behind where the @dfn{data field address}
@cindex data field address
 pointer points
to.

The most important flag bits currently defined are:
@itemize @bullet
@item
The INVISIBLE bit = 1 when @dfn{smudge}
@cindex smudge
d, and will prevent a
match by @code{(FIND)}
@findex (FIND)
.
@item
The IMMEDIATE bit = 1 for IMMEDIATE definitions; it is called the
 @dfn{immediate bit}
@cindex immediate bit
.
@item
The DUMMY bit =1 for a dictionary header contained in the
data of a vocabulary. This indicates that it should not be executed.
@item
The DENOTATION bit =1 for a prefix word.
This means that it is a short word used as a prefix
that can parse
all @dfn{denotation}
@cindex denotation
's (numbers) that start with that prefix, e.g. 7 or & .
Usually it is a one letter word, but not necessarily.
All built-in prefix words are part of the minimum search order.
@item
After the last letter follow zero bytes up till the next cell boundary.
@end itemize
@code{(CREATE)}
@findex (CREATE)
 takes care to generate this data structure;
it is called by all defining words.

For all @dfn{colon definition}
@cindex colon definition
's the code field contains
a pointer to the same code, the @dfn{inner interpreter}
@cindex inner interpreter
, called
@samp{DOCOL}.
For all words defined via @samp{CREATE ... DOES>} the code field
contains the same code, @samp{DODOES}.

At the @dfn{data field address}
@cindex data field address
 we find a pointer to an area with a
length and content that depends on the type of the word.
@itemize @bullet
@item
For a code word, it contains machine code.
The code field of this word points to it too.
@item
For a word defined by
@code{VARIABLE}
@findex VARIABLE
, @code{USER}
@findex USER
, or @code{CONSTANT}
@findex CONSTANT
 it has a width of one cell, and contains data.
@item
For all @dfn{colon definition}
@cindex colon definition
's the data field address
contains a pointer to an area with a variable length. It contains the
compiled high level code, a sequence of @dfn{code field
address}
@cindex code field
address
es.
@item
For a word defined via @samp{CREATE ... DOES>} the first
cell of this area contains a pointer to the
@dfn{high level}
@cindex high level
 code defined by @code{DOES>}
@findex DOES>
 and the remainder is
data. A pointer to the data is passed to this
@code{DOES>}
@findex DOES>
 code.
@end itemize

A @dfn{dictionary entry address}
@cindex dictionary entry address
 can be turned into any
of these fields by words that are in the vocabulary
@samp{DICTIONARY}. @xref{DICTIONARY},, for those field words. They
customarily start with @kbd{>}.

A dictionary falls apart into the
@enumerate
@item
Headers, with their fields.
@item
Names, pointed to by some @dfn{name field address}
@cindex name field address
.
@item
Data, pointed to by some @dfn{data field address}
@cindex data field address
.
This includes high level code, that is merely data fed into
the high level interpreter.
@item
Code, pointed to by some @dfn{code field address}
@cindex code field address
.
This is directly executable machine code.
@end enumerate
@subsection Details of memory layout

The disc buffers are mainly needed for source code that is fetched
from disk were it resides in a file.

The disc buffer area is at the upper bound of RAM memory, So it ends at @code{EM}
@findex EM
 .  

It is comprised of
an integral number of buffers, each @code{B/BUF}
@findex B/BUF
 bytes plus two cells.
@code{B/BUF}
@findex B/BUF
 is the number of bytes read from the disc in one go,
originally thought of as one sector.
In ciforth's @code{B/BUF}
@findex B/BUF
 is always the size of one screen according to ISO :
1024 bytes.
The constant @code{FIRST}
@findex FIRST
 has the value of the address of the start of the first
buffer.
 @code{LIMIT}
@findex LIMIT
 has the value of the first address beyond the top buffer.
The distance between @code{FIRST}
@findex FIRST
 and @code{LIMIT}
@findex LIMIT
 is a multiple of
@code{B/BUF CELL+ CELL+}
@findex B/BUF CELL+ CELL+
 bytes.

For this ciforth the number of disk buffers is configured
at 8  . The minimum possible is approximately 8 because nesting and locking
requires that much blocks available at the same time.

The user area is configured to contain 0x40 cells, most of it unused.
User variables can be added by the word @code{USER}
@findex USER
 , but you have
to keep track yourself which offset in the user area can be used.
 The user area is just under the disc
buffers. So it ends at @code{FIRST}
@findex FIRST
 .   

The terminal input buffer  and the return stack share an area configured at a
size of 0x10000 bytes.
The lower half is intended for the terminal input buffer, and the higher part
is used for the return stack, growing down from the end.
The initial stack pointer is in variable @code{R0}
@findex R0
.
The return stack grows downward from the user area toward the terminal
buffer.

The computation stack grows downward from the terminal buffer toward the
dictionary which grows upward.
The initial stack pointer is in variable @code{S0}
@findex S0
.

During a cold start, the user variables are initialised from the bootup parameters
to contain the addresses of the above memory assignments.

They can be changed.
@xref{+ORIGIN}, for the bootup area.
But take care. You probably need to study the source for how and when they
take effect.

If you need multi-tasking you have to allocate a
separate user area for each task, as well as a separate return
stack area and a separate data stack area. A task that asks for
input, also needs an extra terminal input buffer.
@subsection  Terminal I/O and vectoring.
It is useful to be able to change the behaviour of I/O words such
that they put their output to a different channel.
For instance they must output to the
printer instead of to the console.
In general this is called @dfn{vectoring}
@cindex vectoring
.
Remember that in normal Forth system,
all printing of numbers is to the terminal,
not to a file or even a buffer.
 (On a linux system something like it
can be accomplished
by the redirection facilities available.)


For this reason character output @code{CR}
@findex CR
, @code{EMIT}
@findex EMIT
 and
@code{TYPE}
@findex TYPE
 all go through a common word that can be changed.
For lina it is @code{TYPE}
@findex TYPE
  .
Because this is defined in high level code it can temporarily be replaced
by other code. This @dfn{revectoring}
@cindex revectoring
 is possible for all high level
words in ciforth,
such that we need no special measures to make @dfn{vectoring}
@cindex vectoring
 possible.
As an example we replace @code{TYPE}
@findex TYPE
 by @code{MYTYPE}
@findex MYTYPE
 .
@* @samp{' MYTYPE >DFA @ ' TYPE >DFA !} @*
And back to default:
@* @samp{' TYPE >PHA ' TYPE >DFA !} @*
Be careful not to define @code{MYTYPE}
@findex MYTYPE
 in terms of @code{TYPE}
@findex TYPE
 , as a
recursive tangle will result.
This method works in all versions of ciforth and is called @dfn{revectoring}
@cindex revectoring
.

A similar technique is not so useful on the input side,
because keys entered during @code{EXPECT}
@findex EXPECT
 are subject to correction
until <RET> has been pressed.
On lina @code{EXPECT}
@findex EXPECT
 is left to the
operating system, such that inputting to lina has the same
look and feel as other input.
Text can be pasted in with the mouse, etc.
Consequently @code{RUBOUT}
@findex RUBOUT
 is not used.


@section Libraries and options

In ciforth there is no notion of object (i.e. compiled) libraries,
only of source libraries.
A Forth @dfn{library}
@cindex library
 is a block file adorned with one convention.
This is that the words defined in a screen are
mentioned on the first line of that screen,
the @dfn{index line}
@cindex index line
.
This is of course quite established as a habit.
The word @code{REQUIRED}
@findex REQUIRED
 takes a string and loads the
first screen where that name occurs in the index line. For
convenience also @code{REQUIRE}
@findex REQUIRE
 is there that looks ahead
in the input stream.
These words are not in the kernel but are in screen 17, that
corresponds to the @samp{-r} option.

Screen 0 and screen 1 to 31 are reserved.

When a Forth is started up with
a first parameter that is a one-letter option, the corresponding
screen is to be executed. So @samp{-a} or @samp{-A} is
equivalent to @samp{1 LOAD} and @samp{-z} or
 @samp{-Z} is equivalent to @samp{26 LOAD}.
 In fact all options are mapped onto screen 0..31 by a bitwise and.
@subsection Options
ciforth is a primitive system, and can interpret just one option on the
command line. If the first argument is not starting with @kbd{-} 
ciforth returns with error code 3.
However the option @samp{-l} can bootstrap it into
more sophisticated behaviour.

The following options can be passed to lina on the command line:

@itemize @bullet

@item
@samp{-a}

Make sure @code{REQUIRED}
@findex REQUIRED
 is available.
This is a copy of the @samp{-r} command
because it is easier to remember @samp{1 LOAD} if the screen
must be loaded manually.
In addition the signon message is suppressed.

@item
@samp{-c name}

Compile the file @file{name} to an executable binary. The name of the binary
is @file{name} without the trailing @samp{.frt} or else @file{a.out}.
Upon invocation of the binary the word defined latest is executed, then Forth goes
 @code{BYE}
@findex BYE
 .
 @file{name} is a regular source file, not a block file.
Also @code{REQUIRED}
@findex REQUIRED
 is made available.

@item
@samp{-e}

Load the elective screen, screen 5. This contains @dfn{preferences}
@cindex preferences
,
the tools you want to have available running an interactive Forth.
The  default library file contans system wide default preferences.
See the @samp{-l} option if the default preferences don't suite you.
In a elective screen you just put
commands you want to be executed after Forth starts up, such as 
@samp{ "fortune -f /usr/lib/forthcookies" SYSTEM }
 or 
@samp{ REQUIRE EDIT }

@item
@samp{-f forthcode}

Execute the @samp{forthcode} in the order present.
Beware of the special characters in the shell. Also
the shell will collapse multiple spaces into one.

@item
@samp{-g number name}

Expand the system by @samp{number} Megabytes, then save it
under the name @samp{name}.
@samp{number} may be negative, and in that case the system
is made smaller.

@item
@samp{-h}

Print overview of options.

@item
@samp{-i binpath libpath [shellpath]}

Install the forth in @samp{binpath} and the library in @samp{libpath} .
If the @samp{shellpath} parameter is specified,
it will be installed as the command interpreter used for @code{SYSTEM}
@findex SYSTEM
.
All of them must be full path names, not just directories.
The ciforth that is running is copied to @file{binpath}, and the block file
is copied to @file{libpath}.


For system wide installation on a modern large system the following
is recommended:
@example
@iftex
@cartouche

    su
    ./lina -g 60 lina+
    ./lina+ -i /usr/bin/lina /usr/lib/forth.lab
    chmod 755 /usr/bin/lina
    chmod 644 /usr/lib/forth.lab
@end cartouche
@end iftex
@ifinfo

    su
    ./lina -g 60 lina+
    ./lina+ -i /usr/bin/lina /usr/lib/forth.lab
    chmod 755 /usr/bin/lina
    chmod 644 /usr/lib/forth.lab
@end ifinfo
@end example

For a smallish system you may expand by 0 Mbyte @samp{-g 0}.
If the system has no swap space, and less than 8 Mbyte of memory,
use @samp{-g -3}, diminish from 4 to 1 Mbyte.



@item
@samp{--help}
@samp{--version}
@samp{--}
@samp{-m}

In ciforth all options are mapped onto a letter. All options
that start with @kbd{-} are mapped onto @kbd{m}.
The result is the combination of -h and -v , so both help and
version information is printed.
This conforms to the FSF-conventions.

@item
@samp{-l name [more]}

Use a library @samp{name}.
Restart Forth with as a block file @file{name} and as options the remainder
of the line shifted, such that
@samp{-l name} disappears and the next option becomes the first.
A file specified via @samp{-l} is opened for reading and
writing.
Options ara again handled as as described in the begining of this section.
In this way options may be added or reconfigured for personal use.

Note that the default file is opened for reading only.



@item
@samp{-r}

Make sure @code{REQUIRED}
@findex REQUIRED
 is available.


@item
@samp{-s script}

Load the file @file{script} , but ignore its first line.
This is intended to be used for scripts, i.e. a piece of code to be
interpreted rather than compiled.
The first line is probably
@samp{#!lina -s} or some such as 
@samp{#!lina -l /usr/lib/forth/cgi/forth.lab -s}.
In a script @code{REQUIRED}
@findex REQUIRED
 is available and
you can use standard in and standard out.

@item
@samp{-t sourcefile}

Try to load the file @file{script} automatically, by possibly unsafe means.
Report facilities that were required.
This is a first step in a porting activity.
Redefinition messages are issued on the error channel that
can be redirected to /dev/nul leaving the report.

@item
@samp{-v}

Print version and copy right information.

@end itemize

The remaining screens are available for options to be added at a later time,
or for user defined options in a private library.

@subsection Private libraries

Working with source in files is quite comfortable using the default block library, especially
if sufficient tools have been added to it. In principle all ISO words should be
made available via @code{REQUIRED}
@findex REQUIRED
 .

In order to customize the forth library, you have to make a
copy of the default
@file{/usr/lib/ciforth/forth.lab} to your home directory, preferably to a lib
subdirectory.
Then you can start up using a @samp{-l} option, or make a customized lina.
@xref{Manual}, Subsection Configuring.


Most shells allow you to redefine commands, such as e.g. in bash:
@* alias lina='lina -l $HOME/lib/forth.lab' @*




Note that the @samp{-l} option hides itself, such that
such an alias can be used completely identical to the original
with respect to all options, including @samp{-l}.
Analysing arguments passed to lina in your programs can remain
the same.

@subsection Turnkey applications.
Turnkey application are made using the word @code{TURNKEY}
@findex TURNKEY
 .
They take a word, that is to be done, and a string with the file name.
Mostly it is much easier to just use the @samp{-c} option.
@xref{Manual}, Getting Started Subsection Hello World!
A turnkey application should decide what to do with the library file that is default
opened in @code{COLD}
@findex COLD
 . Make sure to @code{CATCH}
@findex CATCH
 errors from
@code{BLOCK-EXIT}
@findex BLOCK-EXIT
 and ignore them.


@node Assembler, Errors, Manual, top


@chapter Assembler

The assembler is described in this manual,
because it is not feasable to use it from the description in the source.


@menu
* A2:: Introduction
* A3:: Reliability
* A4:: Principle of operation
* A5:: The 8080 assembler
* A6:: Opcode sheets
* A7:: Details about the 80386 instructions
* A8:: 16 and 32 bits code and segments
* A9:: Difference with the built in assembler
* AA:: A rant about redundancy
* AB:: Reference opcodes Intel 386
* ABA:: Reference opcodes Pentium-only
* AC:: The dreaded SIB byte
* AE:: An incomplete and irregular guide to the instruction mnemonics.
* AF:: Assembler Errors
@end menu
@node A2, A3, AF, Assembler
@section Introduction

Via @samp{http://home.hccnet.nl/a.w.m.van.der.horst/forthassembler.html}
you can find a couple of assemblers, to complement the generic
ciforth system.
The assemblers are not part of the lina
package, and must be fetched separately.

They are based on the postit/fixup principle, an original and novel
design to accommodate reverse engineering.
The assembler that is present in the blocks,
is code compatible, but is less sophisticated,
especially regards error detection.
This assembler is automatically loaded in its 16 or a 32 bit form,
such that it is appropriate for adding small code definitions to the
system at hand.
The background information given here applies equally to that assembler.


A useful technique is to develop code 
using the full assembler.
Then with code that at least contains valid instruction enter
the debugging phase with the assembler from the library.

@*
forth.lab : equivalent to 
asgen.frt plus asi86.frt plus asipentium.frt but without error detection.
@*
@file{ass.frt}  : the 80-line 8086 assembler (no error detection), a prototype.
@*
@file{as6809s.frt}  : a small 6809 assembler (no error detection).
@*
@file{asgen.frt} : generic part of postit/fixup assembler
@*
@file{as80.frt}  : 8080 assembler, requires @file{asgen.frt}
@*
@file{asi86.frt}  : 8086 assembler, requires @file{asgen.frt}
@*
@file{asi386.frt} : 80386 assembler, requires @file{asgen.frt}
@*
@file{aspentium.frt} : general Pentium non-386 instructions, requires @file{asgen.frt}
@*
@file{asalpha.frt} : DEC Alpha assembler, requires @file{asgen.frt}
@*
@file{asi6809.frt} : 6809 assembler, requires @file{asgen.frt}
@*
@file{ps.frt}     : generate opcode sheets
@*
@file{p0.asi386.ps} : first byte opcode for asi386 assembler
@*
@file{p0F.asi386.ps} : two byte opcode for same that start with 0F.
@*
@file{test.mak} : makefile, i.e. with targets for opcode sheets.
@*

De @file{asi386.frt} (containing the full 80386 instruction set) is in
many respects non-compliant to Intel syntax. The instruction
mnemonics are redesigned in behalf of reverse engineering.
There is a one to one correspondence between mnemonics and
machine instructions. In principle this would require a
monumental amount of documentation, comparable to parts of
Intel's architecture manuals. Not to mention the amount of work
to check this. I circumvent this. Opcode sheets for this
assembler are generated by tools automatically, and you can ask
interactively how a particular instructions can be completed.
This is a viable alternative to using manuals, if not more
practical. (Of course someone has to write up the descriptions,
I am happy Intel has done that.).

So look at my opcode sheets. If you think an instruction would be
what you want, use @code{SHOW:}
@findex SHOW:
 to find out how it is
to be completed.
If you are at all a bit familiar,
most of the time you can understand what your options are.
If not compare with an Intel opcode sheet, and look up the instruction
that sits on the same place. If you don't understand them, you can still
experiment in a Forth to find out.

The assembler in the Library Addressable
by Blocks (block file) hasn't the advanced features of disassembly,
completion and error detection.
It is intended for incidental use, to speed up a crucial word.
But the code is fully compatible,
so you can develop using the full assembler.

@node A3, A4, A2, Assembler
@section Reliability

I skimped on write up. I didn't skimp on testing.
All full assemblers, like
@file{asi386.frt} and @file{aspentium.frt},
are tested in this way:

@enumerate
@item All instructions are generated.
(Because this uses the same
mechanism as checking during entry, it is most unlikely that you will get an
instruction assembled that is not in this set.)

@item They are assembled.

@item They are disassembled again and compared with
the original code, which must be the same.

@item They are disassembled by a different tool (GNU's objdump),
and the output is compared with 3. This has been done manually,
just once.
@end enumerate

This leaves room for a defect of the following type:
A valid instruction is rejected or has been totally overlooked.

But opcode maps reveal their Terra incognita relentlessly. So I
am quite confident to promise a bottle of good Irish whiskey to
the first one to come up with a defect in this assembler.

The full set of instructions, with all operand combinations sit
in a file for reference. This is all barring the 256-way @samp{SIB}
construction and prefixes, or combinations thereof. This would
explode this approach to beyond the practical.
Straightforward generation of all instructions
is also not
practical for the Alpha with 32K register combinations per
instruction. This is solved by defining ``interesting'' registers
that are used as examples
and leaving out opcode-operand combinations with uninteresting
registers.


@node A4, A5, A3, Assembler
@section Principle of operation

In making an assembler for the Pentium it turns out that
the in-between-step of creation defining words for each type
of assembly gets in the way. There are just too many of them.

MASM heavily overloads the instruction, in particular @samp{MOV} .
Once I used to criticise Intel because they had an unpleasant to use
instruction set with @samp{MOV} @samp{MVR} and @samp{MVI} for move instructions.
In hindsight I find the use of different opcodes correct.
(I mean they are really different instructions, it might have been
better if they weren't. But an assembler must live up to the truth.)
Where the Intel folks really go overboard is with the disambiguation of
essentially ambiguous constructs, by things as @samp{OFFSET} @samp{BYTE POINTER}
 @samp{ASSUME} . You can no longer find out what the instruction means by itself.
@*
A simple example to illustrate this problem is
@example
@iftex
@cartouche
        INC [BX]
@end cartouche
@end iftex
@ifinfo
        INC [BX]
@end ifinfo
@end example
Are we to increment the byte or the word at BX?
Intel's solution is @samp{INC BYTE POINTER BX})
Contrarily here we adapt the rule:
if an instruction doesn't determine the operand
size (some do, like @code{LEA,}
@findex LEA,
 ),
then a size fixup is needed ( @samp{X|} or @samp{B|} ).
@*
In this assembler this looks like
@example
@iftex
@cartouche
        INC, B| D0 [BX] 
@end cartouche
@end iftex
@ifinfo
        INC, B| D0 [BX] 
@end ifinfo
@end example
This is completely unambiguous.

These are the phases in which this assembler handles an instruction:

@itemize @bullet
@item
POSTIT phase:
@code{MOV,}
@findex MOV,
 assembles a two byte instruction with holes.
@item
FIXUP phase:
@code{X|}
@findex X|
 or @code{B|}
@findex B|
 fits in one of the holes left.
Other fixups determine registers and addressing mode.
@item
COMMA phase:
First check whether the fixups have filled up all holes.
Then add addresses (or offsets) and/or immediate data,
using e.g. @code{IL,}
@findex IL,
 or @code{L,}
@findex L,

@item
Check whether all commaers, requested either by postit's or fixup's
are present.
This check is actually executed by a postit like @code{MOV,}
@findex MOV,

prior to assembling, or by @code{END-CODE}
@findex END-CODE
.
@end itemize


Doesn't this system lay a burden on the programmer? Yes.
He has to know exactly what he is doing.
But assembly programming is dancing on a rope. The Intel syntax tries
to hide from you were the rope is. A bad idea. There is no such thing as
assembly programming for dummies.

An advantage is that you are more
aware of what instructions are there.
Because you see the duplicates.

Now if you are serious, you have to study the @file{asgen.frt} and
@file{as80.frt} sources.
You better get your feet wet with @file{as80.frt}
before you attack the Pentium.
The way @samp{SIB} is handled is so
clever, that sometimes I don't understand it myself.
It deviates somewhat from the phases explained here.

Another invention in this assembler is the @dfn{family of instructions}
@cindex family of instructions
.
Assembler instructions are grouped into families with identical fixups, and
a increment for the opcodes.
These are defined as a group by a single execution of a defining word.
For each group there is one opportunity to get the opcode wrong;
formerly that was for each opcode.

@node A5, A6, A4, Assembler
@section The 8080 assembler

The 8080 assembler doesn't take less place than Cassady's .
(In the end the postit-fixup makes the Pentium assembler
more compact, but not the 8080.)
But... The regularities are much
more apparent. It is much more difficult to make a mistake with the
code for the @samp{ADD} and @samp{ADI} instructions.
And there is information there
to the point that it allows to make a disassembler that is independant
of the instruction information, one that will work for the 8086, look
at the pop family.
First I had
@example
@iftex
@cartouche
 38 C1 02 4 1FAMILY, POP -- PUSH RST      ( B'|) 
@end cartouche
@end iftex
@ifinfo
 38 C1 02 4 1FAMILY, POP -- PUSH RST      ( B'|) 
@end ifinfo
@end example
(cause I started from an existing assembler.)
But of course @code{RST}
@findex RST
 (the restart instruction) has nothing
to
do
with registers, so it gets a separated out. Then the exception, represented
by the hole @samp{--} disappears.
The bottom line is : the assembler proper now takes 22 lines of code.
Furthermore the ``call conditional'' and ``return conditional''
instructions where missing. This became apparent as soon as I printed the
opcode sheets.
For me this means turning ``jump conditional'' into a family.

@node A6, A7, A5, Assembler
@section Opcode sheets

Using @file{test.mak} (on a linux computer in lina) you can
generate opcode sheets
by  "make asi386.ps".
For the opcode sheets featuring a n-byte prefix you must
pass the @samp{PREFIX} to make and a @samp{MASK} that covers the prefix and
the byte opcode, e.g. @samp{make asi386.ps MASK=FFFF PREFIX=0F}
The opcode sheets @file{p0.asi386.ps} and @file{p0F.asi386.ps} are
already part of the distribution and can be
printed on a PostScript printer or viewed with e.g. @samp{gv}.

Compare the opcode sheets with Intel's to get an overview of what I have done
to the instruction set. In essence I have re-engineered it to make it reverse
assemblable, i.e. from a disassembly you can regenerate the machine code.
This is @b{not} true for Intel's instruction set, e.g. Intel has the same opcode for
@samp{MOV, X| T| AX'| R| BX| }     and
@samp{MOV, X| F| BX'| R| AX|}.

To get a reminder of what instructions there are type
@code{SHOW-OPCODES}
@findex SHOW-OPCODES
 . If you are a bit familiar with the
opcodes you are almost there. For if you want to know what the
precise instruction format of e.g. @code{IMUL|AD,}
@findex IMUL|AD,
 just
type @samp{SHOW: IMUL|AD,} You can also type
@code{SHOW-ALL,}
@findex SHOW-ALL,
 but that takes a lot of time and is more
intended for test purposes.

@node A7, A8, A6, Assembler


@section Details about the 80386 instructions

Read the introductory comment of @file{asgen.frt} for how the assembler
keeps track of the state, using the @code{BI}
@findex BI
 @code{BY}
@findex BY
 @code{BA}
@findex BA
 tallies.
@enumerate
@item
A word ending in @kbd{,}, an ``opcode'' reserves place in the dictionary.
It stand for one assembler instruction.
The start of the instruction is kept and there is a bitfield (the tally) for
all bits that belong to the instruction, if only mentally. These bits are
put as comment in front of the instruction and they are considered filled
in.
The opcode also determines the instruction length.
@item
A fixup mostly ends in @kbd{|}.
It @code{OR}
@findex OR
s in some bits
in an already assembled instruction. Again there is a mask in front
of fixups and in using the fixup these bits are considered to be filled
in.
A fixup cannot touch data before the start of the latest instruction.
Some addressing modes fixups do not have @kbd{|} in them.
This is in order to adhere more closely to conventions regarding those
addressing modes.
This much can be said. You can be sure that a word containing
@kbd{[} and/or @kbd{]} is a fixup, that it
is addressing mode related and that the addressing is indirect.
@item
Families can be constructed from instructions or fixups with the
same tally bit fields, provided the instructions differ by a fixed increment.
The tallies also contain information about data and addresses following.
These fields must be the same too.
@item
The part before a possible @kbd{|} in an instruction -- but excluding an
optional trailing I -- is the opcode. Opcodes define indeed a same action.
@item
The part after @kbd{|} in an instruction may be
considered a built in fixup where irregularity forbids to use a
real fixup. A X stands for xell or natural data width. This is
16 bit for a 16 bit assembler and 32 bit for a 32 bit
assembler. These can be overruled with @code{ AS:, }
@findex  AS:, 
 applying to @code{DX|}
@findex DX|
 and @code{MEM|}
@findex MEM|
 and with
@code{ OS:, }
@findex  OS:, 
 applying to tdata required where there is
an I suffix.
The commaers always reveal their true width.
It is either @code{IW,}
@findex IW,
 or @code{IL,}
@findex IL,
 .
@item
Width fixups determine the data width : @code{X|}
@findex X|

(xell or natural data width 16/32 ) or @code{B|}
@findex B|
 ( 8 bit) unless
implied.
Offset fixups determine the offset or address width : @code{XO|}
@findex XO|

(xell or natural data width 16/32 ) or @code{BO|}
@findex BO|
 ( 8 bit) or @code{ZO|}
@findex ZO|
 .
@item
Instruction ending in @kbd{I} have an immediate data field after all
fixups. This can be either
@code{IB,}
@findex IB,
 @code{IW,}
@findex IW,
 @code{IL,}
@findex IL,
 ( 8 16 32 bit).
If there are width fixups they should correspond with the data.
@item
Instructions ending in @samp{|SG} builtin fixup
(segments) require @code{SG,}
@findex SG,
 (which is always 16 bits).
For Xells in the presence of width overrules,
the programmer should carefully insert @code{W,}
@findex W,
 or
@code{L,}
@findex L,
 whatever appropriate.
@item
With r/m you can
have offsets (for @code{BO|}
@findex BO|
 and @code{XO|}
@findex XO|
 ) that
must be assembled using @code{B,}
@findex B,
 or @code{L,}
@findex L,
 but
mind the previous point.
@item
Instruction with r/m can have a register instead of memory indicated
by the normal fixups @code{AX|}
@findex AX|
 etc.
@item
If instructions with r/m have another register, that one is indicated
by a prime such as @code{AX'|}
@findex AX'|
. Or if an instruction can handle two general
registers, the one that cannot be replaced by a memory reference gets a prime.
@item
Unless @code{T|}
@findex T|
 @code{F|}
@findex F|
 (to/from) are present,
a primed register is the modifiable one,
else @code{T|}
@findex T|
 @code{F|}
@findex F|
 refer to the primed register.
The primed register is the one
that cannot be replaced by a memory reference.
@item
At the start of an instruction the mask of the previous instruction
plus fixup should add up non-overlappingly to a full field.
Offsets and immediate data should have been comma-ed in in that order.
This is diagnosed in the great assembler.
@item
Instructions ending in @samp{ :, } are prefixes and are considered in their own
right. They have no fixups.
@item
The Scaled Index Byte is handled internally in the following way:
The fixup @code{SIB|}
@findex SIB|
 closes the previous instruction (i.e.
fill up its bit field), but possible immediate data and offsets are kept.
Then @code{SIB,}
@findex SIB,
 starts a new instruction.
The user merely needs to use a fixup with an unbalanced opening square
bracket such as @code{[AX}
@findex [AX
, that handles this transparently.
@item The @code{SET,}
@findex SET,
 instruction unfortunately requires a duplicate of the
@code{O|}
@findex O|
 etc. fixups of the @code{J,}
@findex J,
 and @code{J|X,}
@findex J|X,
 instructions,
called @code{O'|}
@findex O'|
 etc.
@item
Similarly,
some single byte instructions require @code{X'|}
@findex X'|
 and
@code{B'|}
@findex B'|
 instead of @code{X|}
@findex X|
 and @code{B|}
@findex B|
 that are used for the ubiquitous instructions with r/m.
@end enumerate

This is the way the disassembler works.

@enumerate
@item
Find the first instruction that agrees with the data at the
program counter. Tally the bits. The instructions length follows from
the instruction. As does the presence of address offsets and immediate
data. In the current implementation the search follows dictionary links.
The dictionary must be organized such that the correct
instruction is found first.
If two instructions agree with the data,
in general the one that covers the most bits must be found first.
@item
Find the first fixup that agrees with untallied bits.
Note that opcode and previous fixups may have set bits in the
@code{BAD}
@findex BAD
 variable.
Any fixups that set a bit in @code{BAD}
@findex BAD
 that would
result in a conflict are not considered.
@item
If not all bits have been tallied go to 2, searching the dictionary
from where we left off
@item
Disassemble the address offsets and immediate data, in accordance with
the instruction. Length is determined from fixups and prefix bytes.
The commaers that were used to assemble the data have an associated
execution token to disassemble the data.
This is used to advantage to change the representation from
program counter relative to absolute,
or look up and show the name for a label.
@end enumerate
 

@node A8, A9, A7, Assembler
@section 16 and 32 bits code and segments

Note that the handling of segments and mixing thereof changed starting
ciforth version 4.0.6.
Contrary to the old situation,
commaers are checked correctly in the presence of prefixes
and you have never to overrule error-checking.

The description of 16 or 32 bits in the Intel manuals is messy.
These are the rules.
@enumerate
@item
In real mode all sizes are 16 bits.
@item
In protected mode the size of an address or Xell
offset agrees with the size of the code segment.
@item
In protected mode the size of an immediate data Xell agrees with
the size of the applicable data segment.
Mostly this is the data segment, but it may be the stack segment
or some extra segment.
@item
In all previous cases the code length can be swapped between
16 and 32 bits by a code length override prefix @code{OS:}
@findex OS:
,
the data length by a data length override prefix @code{AS:}
@findex AS:
,
@end enumerate

The 16 bit indexing in a 32 bit assembler have separate fixup's,
that all end in a @kbd{%}-sign.

In fixup X is used to mean Xell, or the natural word length.
This is 16 bits for 16 bits segments and 32 bits for 32 bits segments.
Likewise in PostIt-FixUp AX means Intel's @code{AX}
@findex AX
 for 16 bits
segments and @code{EAX}
@findex EAX
 for 32 bits segments.

In comma-ing, you must always select the proper one, xell-wide commaers
always contain either @kbd{W} or @kbd{L} .

After the directive @code{BITS-16}
@findex BITS-16
 code is generated for and checked
against 16 bit code and data segments.
After the directive @code{BITS-32}
@findex BITS-32
 code is generated for and checked
against 32 bit code and data segments.

In a 16 bits segments the following commaers must be used:
 @code{W,}
@findex W,
 @code{IW,}
@findex IW,
 @code{(RW,)}
@findex (RW,)
 and @code{RW,}
@findex RW,
 .

In a 32 bits segments the following commaers must be used:
 @code{L,}
@findex L,
 @code{IL,}
@findex IL,
 @code{(RL,)}
@findex (RL,)
 and @code{RL,}
@findex RL,
 .

The prefix @code{OS:}
@findex OS:
 switches the following opcode to use
@code{IL,}
@findex IL,
 instead of @code{IW,}
@findex IW,
 and vice versa.
Similarly the prefix @code{AS:}
@findex AS:
 switches between @code{W,}
@findex W,

and @code{L,}
@findex L,
, or between @code{RW,}
@findex RW,
 and @code{RL,}
@findex RL,
.

While mixing modes,
whenever you get error messages and
you are sure you know better than the assembler,
put @code{!TALLY}
@findex !TALLY
 before the word that gives the error
messages.
This will @dfn{override the error detection}
@cindex override the error detection
.
Proper use of the BITS-xx directives makes this largely unnecessary,
but it can be needed if you use e.g. an extra segment @code{ES|}
@findex ES|

that is 16 bits in an otherwise 32 bits environment.

@node A9, AA, A8, Assembler
@section The built in assembler

From within ciforth one can load an assembler from the installed LAB
library by the command @code{REQUIRE ASSEMBLERi86 }
@findex REQUIRE ASSEMBLERi86 
.
Automatically a 32 bit assembler is loaded
if the Forth itself is 32 bits and a 16 bit assembler for the
16 bit forths.
This is a simplified version with no error checking and
no provisions for 16/32 bit mixing.
(Those are not needed, because you can mix with impunity.)
In the future this assembler is now (since 4.0.6)
fully compatible
with the large file-based one.

@b{Consequently you can take a debugged program and run it
through the LAB assembler. }

@b{The built in assembler has no error
checking.}

@b{IMPORTANT NOTE: The 4.0.6 version and later contains
assembler code in the LAB file that has not yet been converted.
This code largely relates to a booting version;
It will be updated as soon as I have a booting version in a binary
form available.
}

@node AA, AB, A9, Assembler


@section A rant about redundancy

You could complain about redundancy in postit-fixup assemblers.
But there is an advantage to that, it helps detect invalid
combinations of instructions parts. They look bad at first
sight. What about @* @samp{MOV, B| T| [BX+SI] R|
AX|} @* @samp{MOV,} needs two operands but there
is no primary operand in sight. @code{[BX+SI]}
@findex [BX+SI]
 would not
qualify. and not even @code{BX|}
@findex BX|
 because the primary
operand should be marked with a prime. @*
@samp{MOV, X| T| BX| AX|} looks bad because you know
@code{BX|}
@findex BX|
 and @code{AX|}
@findex AX|
 work on the same bit
fields, so it easy to remember you need the prime.
@code{T|}
@findex T|
 and @code{F|}
@findex F|
 refer to the primary
operands, so gone is the endless confusion about what is the
destination of the move. @* @samp{MOV, X| T| BX'|
R| AL}| looks bad , because @code{AL|}
@findex AL|
 could not
possibly qualify as an X register. @* @samp{MOV,
X| T| BX'| AX|} looks bad , because soon you will adopt the
habit that one of the 8 main register always must be preceeded
with @file{T|} @code{F|}
@findex F|
 or @code{R|}
@findex R|
 .
@* @samp{MOV, X| T| BX'| R| AX|} looks right but
you still can code @samp{MOV, AX| BX'| R| T| X|} if you
prefer your fixups in alphabetic order. (A nice rule for those
Code Standard Police out there?).

And yes @samp{ES: OS:
MOV, X| T| DI'| SIB|, XO| [BP +8* AX] FFFFF800 X,} though
being correct, and in a logical order, looks still bad, because
it @b{is} bad in the sense that the Pentium design got
overboard in complication. (This example is from the built-in assembler,
the one in @file{asi386.frt} redefines @code{[BP}
@findex [BP
 c.s.
to get rid of the @code{SIB|,}
@findex SIB|,
 instruction.)
@*
First remark: lets assume this is
32 bit code,(because otherwise there
would not be a @code{SIB,}
@findex SIB,
 sure?)
@*
There are 3 sizes involved :
@itemize @bullet
@item
The size of the data transported this is always the @samp{X} as
in @code{X|}
@findex X|
 .
Then the first @code{X|}
@findex X|
 changes its meaning to 16 bit, because
of the @code{OS:}
@findex OS:
 prefix.
@item
The @code{X}
@findex X
 in @code{XO|}
@findex XO|
 and in @code{X,}
@findex X,
 must
agree and are 32 bits because you are in a 32 bits segment and this
cannot be overridden.
@item
The offset (in @samp{+AX]} ) is counted in 64 bits, a strange
array for fetching the @samp{DI} but anyway.
@end itemize
And .. by the way the data is placed in the extra segment.
Add a bit of awareness of the cost of the instructions in execution time
and take care of the difference between the Pentium processors MMX en III
and what not and you will see that assembly program is not for the faint
of heart. The @samp{ASSUME} of the MASM assembler buys you
nothing,
but
inconvenience.
 

@node AB, ABA, AA, Assembler

@section Reference opcodes, Intel 386

Table one contains all the opcodes used in @file{asi386.frt} in alphabetic order,
with @kbd{|} sorted before any letter.
The opcodes that lift the assembler to the level of the Pentium is separately
in table 3, in order not to make the tables overly long.
All opcodes on the first position are the same as Intel opcodes,
barring the bar.
Note that sometimes parts that are integrated in the opcodes in Intel
mnemonics are a separate fixup in the Postit-Fixup assembler.
Examples are the condition codes in jumps.

You can use it in two ways.

@itemize @bullet
@item
You want the opcode for some known Intel opcode.
@*
Look it up in the first column. One of the opcodes on that
line is what you want. To
pick the right one, consider the extension that are explained
in table 2. Exception: @samp{PUSHI} is not on the line with @samp{PUSH} .
Some times you have to trim built in size designators, e.g. you
look up @samp{LODSW} but you are stuck at @code{LODS}
@findex LODS
 , so that's it.
With @samp{ SHOW: LODS, } you can see what the operands look like.
@item
You want to know what a POSIT/FIXUP code does. Look it up in the table,
on the first word on the line you should recognize an Intel opcode. For example you have
@code{ CALLFAROI, }
@findex  CALLFAROI, 

That is at the line with @code{CALL,}
@findex CALL,
 . So the
combination of operands for @code{CALLFAROI,}
@findex CALLFAROI,
 are to be
found in the description for @samp{CALL} in the Intel
manuals.
@end itemize

Note. Some things are ugly. @code{LDS,}
@findex LDS,
 should be
@code{L|DS,}
@findex L|DS,
 . I would replace @code{MOV|FA,}
@findex MOV|FA,
 by
@code{STA,}
@findex STA,
 and @code{MOV|TA,}
@findex MOV|TA,
 by @code{LDA, }
@findex LDA, 
 . But
that would make the cross referencing more problematic. Note. The
meaning of the operands for @samp{JMP} and @samp{JMPFAR}
are totally different. So my suffices are different.

Table 1. Opcode cross reference.

@table @var
@item AAA,
@item AAD,
@item AAM,
@item AAS,
@item ADC, ADCI, ADCI|A, ADCSI,
@item ADD, ADDI, ADDI|A, ADDSI,
@item AND, ANDI, ANDI|A,
@item ARPL,
@item AS:,
@item BOUND,
@item BSF,
@item BSR,
@item BT, BTI,
@item BTC, BTCI,
@item BTR, BTRI,
@item BTS, BTSI,
@item CALL, CALLFAR, CALLFAROI, CALLO,
@item CBW,
@item CLC,
@item CLD,
@item CLI,
@item CLTS,
@item CMC,
@item CMP, CMPI, CMPI|A,
@item CMPS, CMPSI,
@item CPUID,
@item CS:,
@item CWD,
@item DAA,
@item DAS,
@item DEC, DEC|X,
@item DIV|AD,
@item DS:,
@item ENTER,
@item ES:,
@item FS:,
@item GS:,
@item HLT,
@item IDIV|AD,
@item IMUL, IMUL|AD, IMULI, IMULSI,
@item INC, INC|X,
@item INS,
@item INT, INT3, INTO,
@item IN|D, IN|P,
@item IRET,
@item J, J|X, (Intel Jcc)
@item JCXZ,
@item JMP, JMPFAR, JMPFAROI, JMPO, JMPS,
@item LAHF,
@item LAR,
@item LDS,
@item LEA,
@item LEAVE,
@item LES,
@item LFS,
@item LGDT,
@item LGS,
@item LIDT,
@item LLDT,
@item LMSW,
@item LOCK,
@item LODS,
@item LOOP, LOOPNZ, LOOPZ,
@item LSL,
@item LSS,
@item LTR,
@item MOV, MOV|CD, MOV|FA, MOV|SG, MOV|TA,
@item MOVI, MOVI|BR, MOVI|XR,
@item MOVS,
@item MOVSX|B, MOVSX|W,
@item MOVZX|B, MOVZX|W,
@item MUL|AD,
@item NEG,
@item NOT,
@item OR, ORI, ORI|A,
@item OS:,
@item OUTS,
@item OUT|D, OUT|P,
@item POP, POP|ALL, POP|DS, POP|ES, POP|FS, POP|GS, POP|SS, POP|X,
@item POPF,
@item PUSH, PUSH|ALL, PUSH|CS, PUSH|DS, PUSH|ES, PUSH|FS, PUSH|GS, PUSH|SS, PUSH|X,
@item PUSHF,
@item PUSHI|B, PUSHI|X,
@item RCL,
@item RCR,
@item REPNZ,
@item REPZ,
@item RET+, RET, RETFAR+, RETFAR,
@item ROL,
@item ROR,
@item SAHF,
@item SAR,
@item SBB, SBBI, SBBI|A, SBBSI,
@item SCAS,
@item SET,   (Intel SETcc)
@item SGDT,
@item SHL,
@item SHLD|C, SHLDI,
@item SHR,
@item SHRD|C, SHRDI,
@item SIDT,
@item SLDT,
@item SMSW,
@item SS:,
@item STC,
@item STD,
@item STI,
@item STOS,
@item STR,
@item SUB, SUBI, SUBI|A, SUBSI,
@item TEST, TESTI, TESTI|A,
@item VERR,
@item VERW,
@item WAIT,
@item XCHG,
@item XCHG|AX,
@item XLAT,
@item XOR, XORI, XORI|A,
@item ~SIB,
@end table

 Table 2 Suffixes, not separated by a @kbd{|}
@table @var
@item I       : Immediate operand
@item SI      : Sign extended immediate operand
@item FAR     : Far (sometimes combined with OI)
@item O       : Operand
@item OI      : Operand indirect
@end table

 


@node ABA, AC, AB, Assembler

@section Reference opcodes, Pentium only.

Table three contains all the opcodes present in @file{asipentium.frt}
in alphabetic order,
with @kbd{|} sorted before any letter.
All opcodes on the first position are the same as Intel opcodes,
barring the bar.
Note that again sometimes parts that are integrated in the opcodes in Intel
mnemonics are a separate fixup in the Postit-Fixup assembler.

You can use it in the same way as the Intel 386 table.
But there are much less instances where the opcodes do not agree exactly with
Intels.
Memory operands are specified in the same way for floating point
instructions.
But in     those instructions
register operands are always floating point registers.


There is always at most one register specified in a floating point
instruction.
This explicit register may be modifiable (target) or not.
For two register operation @code{ST0}
@findex ST0
 is always implicit.
In that case normally it is the first operand as per @samp{ST0-ST1}.
If modiable, this means the result is
stored in @code{ST1}
@findex ST1
, the explicit register.
Reversed operation means @code{ST0}
@findex ST0

is the second operand as per @samp{ST1-ST0}.
If modiable, this means (again) that
the result is stored in @code{ST1}
@findex ST1
, the explicit register.

And don't forget! @samp{SHOW: <opcode>} is your friend.

Table 3. Opcode cross reference. Pentium-only.

@table @var
@item BSWAP,
@item CMPXCHG,
@item CMPXCHG8B,
@item F2XM1,
@item FABS,
@item FADD,
@item FADDP,
@item FBLD,
@item FBSTP,
@item FCHS,
@item FCLEX,
@item FCOM,
@item FCOMP,
@item FCOMPP,
@item FCOS,
@item FDECSTP,
@item FDIV,
@item FDIVP,
@item FFREE,
@item FIADD,
@item FICOM,
@item FICOMP,
@item FIDIV,
@item FILD, FILD|64,
@item FIMUL,
@item FINCSTP,
@item FINIT,
@item FIST,
@item FISTP, FISTP|64,
@item FISUB,
@item FLD, FLD|e,
@item FLD1,
@item FLDCW,
@item FLDENV,
@item FLDL2E,
@item FLDL2T,
@item FLDLG2,
@item FLDLN2,
@item FLDZ,
@item FMUL,
@item FMULP,
@item FNOP,
@item FPATAN,
@item FPREM,
@item FPREM1,
@item FPTAN,
@item FRNDINT,
@item FRSTOR,
@item FSAVE,
@item FSCALE,
@item FSIN,
@item FSINCOS,
@item FSQRT,
@item FST, FST|u,
@item FSTCW,
@item FSTENV,
@item FSTP, FSTP|e, FSTP|u,
@item FSTSW,
@item FSTSW|AX,
@item FSUB,
@item FSUBP,
@item FTST,
@item FUCOM,
@item FUCOMP,
@item FUCOMPP,
@item FXAM,
@item FXCH,
@item FXTRACT,
@item FYL2X,
@item FYL2XP1,
@item INVD,
@item INVLPG,
@item Illegal-1,
@item Illegal-2,
@item RDMSR,
@item RDTSC,
@item RSM,
@item WBINVD,
@item WRMSR,
@item XADD,
@end table

Table 4 Fixups and their meanings, Pentium-only.
@table @var
@item ST0|    : Register name
@item ST1|
@item ST2|
@item ST3|
@item ST4|
@item ST5|
@item ST6|
@item ST7|
@item s|      : Single (16 bit)
@item d|      : Double (32 bit)
@item m|      : Register is modifiable
@item u|      : Register is unmodifiable
@item n|      : ST0 is first operand (normal)
@item r|      : ST0 is second operand (reverse)
@item |16     : Int width in memory.
@item |32     : Int width in memory.
@end table

 


@node AC, AE, ABA, Assembler
@section The dreaded SIB byte

If you ask for the operands of a memory instruction (one of the
simple one is LGDT, ) instead of all the sib (@dfn{scaled index byte}
@cindex scaled index byte
)
possibilities you see.
@samp{LGDT, BO| ~SIB| 14 SIB,, 18, B,}
This loads the general description table from an address
described by a sib-byte of 14.

The @samp{~SIB| 14 SIB,,} may be replaced by any sib-specification of
the kind @samp{[AX +2* SI]}.
You can ask for a reminder of the 256 possibilities by
@samp{SHOW: ~SIB,}

The SIB constituents are not normal fixups.
They must always appear between the normal fixups and
the commaers, and the first must be the base register,
the one with opening bracket,
such as @code{[AX}
@findex [AX
.

 Table 3 SIB-byte fixups.
@table @var
@item [AX   : Base register
@item [CX   : Base register
@item [DX   : Base register
@item [BX   : Base register
@item [SP   : Base register
@item [BP   : Base register
@item [MEM  : Base memory
@item [SI   : Base register
@item [DI   : register
@item +1*   : Scale by 1 byte.
@item +2*   : Scale by 2 bytes.
@item +4*   : Scale by 4 bytes.
@item +8*   : Scale by 8 bytes.
@item AX]   : Scaled register
@item CX]   : Scaled register
@item DX]   : Scaled  register
@item BX]   : Scaled register
@item 0]    : No register
@item BP]   : Scaled register
@item SI]   : Scaled register
@item DI]   : Scaled register

@end table


For the curious:

Explanation of
@samp{LGDT, BO| ~SIB| 10 SIB,, 14, B,}
This way of specifying a sib-byte
would be perfectly legal, had I not hidden those words.
It shows what is going on: the instruction is completed by ~SIB|
telling the assembler that a comma-er @code{SIB,,}
@findex SIB,,
 is required.

Instead of the comma-er we use a @code{~SIB,}
@findex ~SIB,
 instruction.
This specifies in fact a one byte opcode with three fields
examplified by @samp{[AX +2* SI}] (and
again you might say @samp{+2* SI] [AX} with the same meaning.)

Many subtleties are involved to get right the error detection and the
disassembly.
 

@node AE, AF, AC, Assembler

@section An incomplete and irregular guide to the instruction mnemonics.

The following is an attempted overview of the suffixes and fixup's
used. It may be of some help for using the assembler because it gives
some idea of some of the names.
It doesn't contain all mnemonics,
you have to consult an Intel manual anyway,
just a few of them that I find hard to remember.

It also doesn't contain all fixup's, only those that are particularly
hard or irregular.
Neither does it contain fixups that are
part of a @dfn{SIB}
@cindex SIB
 byte (treated elsewhere).

So beware!

Note that some of the instruction are Pentium and as yet
not present in the @file{asi386.frt}.

Be careful with fixups that end in a % (such as @code{ [BP+IS]%}
@findex  [BP+IS]%
.
They are to be used in incidental 16 bits code, so in 16 bits code segments
or for instructions preceeded by an address size overwrite prefix.

The @dfn{primed registers}
@cindex primed registers
 have a prime after the register name
such as @code{AX'|}
@findex AX'|
 , compared to @code{AX|}
@findex AX|
.
Some opcodes allow two registers.
Whether the primed register is a source or destination is explicitly
covered by @code{T|}
@findex T|
 and @code{F|}
@findex F|
 ,
@b{not} by any order in which the operands appear.

The primed conditions such as @code{Z'|}
@findex Z'|
 have a different
reason.
Those cannot be the same as the unprimed ones,
because they occur at a different place in the opcode,
though I would prefer them to be.

Some instructions
@*
CPUID: CPU Identification
@*
L :   Load Full Pointer
@*
LLDT: Load Local Descriptor Table Register
@*
LGDT: Load General Descriptor Table Register
@*
LIDT: Load Interrupt Descriptor Table Register
@*
LTR:  Load Task Register
@*
LMSW: Load Machine Status Word
@*
RDTSC: Read from Time Stamp Counter
@*
RDMSR: Read from Model Specific Register
@*
SHLD: Double Precision Shift Left
@*
SHRD: Double Precision Shift Right
@*
SLDT: Store Local Descriptor Table Register
@*
SMSW: Store Machine Status Word
@*
VERR: Verify a Segment for Reading or Writing
@*
WRMSR: Write to Model Specific Register
@*
@*
Suffices of the opcode, i.e. part of the opcode word.
@*
|ALL : All
@*
|CD : Control/Debug register
@*
|FS : Replaces FS| in irregular opcodes.
@*
|GS : Replaces GS| in irregular opcodes.
@*
|AD : Implicit A and Double result.
@*
|C  : Implicit C (count)
@*
@*
Items in Fixups.
@*
Y| : Yes, Use the condition straight
@*
N| : No, Use the condition inverted
@*
O| : Overflow
@*
C| : Carry
@*
Z| : Zero
@*
CZ| : C || Z (unsigned <= )
@*
S| : Sign ( <0 )
@*
P| : Parity (even)
@*
L| :  S != O (signed < )
@*
LE| : L || Z (signed <= )
@*
T| : To (primed or special register)
@*
F| : From (primed or special register)
@*
V| : Variable number (in shifts)
@*
1| : Just  by 1.
@*
ZO| : Zero Offset
@*
BO| : Byte Offset
@*
XO| : Xell Offset
@*
Items in Commaers.
Note that in commaers, there is never an @kbd{X}.
You always have to choose between @kbd{W} for 16 bits
and @kbd{L} for 32 bits.
@*
OW,    Obligatory word
@*
(RL,)  Cell relative to IP
@*
(RW,)  Cell relative to IP
@*
(RB,)  Byte relative to IP
@*
SG,   Segment: word
@*
P,    Port number : byte
@*
IS,   Single obligatory  byte
@*
IL,   immediate data : cell
@*
IW,   immediate data : cell
@*
IB,   immediate data : byte
@*
L,    address/offset data : cell
@*
W,    address/offset data : cell
@*
B,    address/offset data : byte
@*
SIB,, Scaled index byte, an instruction with in an instruction
@*
OB, : Obligatory byte
@*
OW, : Obligatory word (=16bits)
@*

There are also @code{RB, RW, RL,}
@findex RB, RW, RL,
 based on
@code{(RB,) (RW,) (RL,)}
@findex (RB,) (RW,) (RL,)
.
They comma in an amount relative to the program counter
based on an absolute address,
such that you can use labels.
These are used preferably, and are made to appear
in the disassemblies.
Otherwise no labels could appear in disassemblies.

 

@node AF, A2, AE, Assembler
@section  Assembler Errors

Errors are identified by a number. They are globally unique, so
assembler error numbers do not overlap with other ciforth error numbers,
or errors returned from operating system calls.
Of course the error numbers are given in decimal, always.

The errors whose message starts with @samp{AS:} are used by the PostIt FixUp assembler
in the file @file{asgen.frt}. @xref{Errors}, for other errors.

@itemize @bullet
@item
@samp{ciforth ERROR # 26 : AS: PREVIOUS INSTRUCTION INCOMPLETE}

You left holes in the instruction before the current one, i.e.
one or more fixups like @code{X|}
@findex X|
 are missing. Or you forget
to supply data required by the opcode like @code{OW,}
@findex OW,
 .
With @code{SHOW:}
@findex SHOW:
 you can see what completions of your opcode
are legal.

@item
@samp{ciforth ERROR # 27 : AS: INSTRUCTION PROHIBITED IRREGULARLY}

The instruction you try to assemble would have been legal, if Intel
had not made an exception just for this combination. This situation
is handled by special code, to issue just this error.

@item
@samp{ciforth ERROR # 28 : AS: UNEXPECTED FIXUP/COMMAER}

You try to complete an opcode by fixup's (like @code{X|}
@findex X|
)
or comma-ers (like @code{OW,}
@findex OW,
 ) in a way that conflicts
with what you specified earlier. So the fixup/comma-er word at
which this error is detected conflicts with either the opcode,
or one of the other fixups/comma-ers.
For example @code{B|}
@findex B|
 (byte size) with a @code{LEA,}
@findex LEA,
 opcode
or with a @code{DI|}
@findex DI|
 operand.

@item
 @samp{ciforth ERROR # 29 : AS: DUPLICATE FIXUP/UNEXPECTED COMMAER}

You try to complete an opcode by fixup's (like @code{X|}
@findex X|
  ) or comma-ers (like @code{OW,}
@findex OW,
 ) in a way that conflicts
with what you specified earlier. So the fixup/comma-er word at
which this error is detected conflicts with either the opcode,
or one of other fixups/comma-ers.
For example @code{B|}
@findex B|
 (byte size) with a @code{LEA,}
@findex LEA,
 opcode
or with a DI| operand.

@item
@samp{ciforth ERROR # 30 : AS: COMMAERS IN WRONG ORDER}

The opcode requires more than one data item to be comma-ed in, such as
immediate data and an address. However you put them in the wrong order.
Use @code{SHOW:}
@findex SHOW:
 .

@item
 @samp{ciforth ERROR # 31 : AS: DESIGN ERROR, INCOMPATIBLE MASK}

This signals an internal inconsistency in the assembler itself.
If you are using an assembler supplied with ciforth, you can report
this as a defect (``bug'').
The remainder of this explanation is intended for the writers
of assemblers.
The bits that are filled in by an assembler word are outside
of the area were it is supposed to fill bits in. The latter
are specified separately by a mask.

@item
 @samp{ciforth ERROR # 32 : AS: PREVIOUS OPCODE PLUS FIXUPS INCONSISTENT}

The total instruction with opcode, fixups and data is ``bad''.
Somewhere there are parts that are conflicting. This may be another
one of the irregularities of the Intel instruction set. Or the
@code{BAD}
@findex BAD
 data was preset with bits to indicate that you
want to prohibit this instruction on this processor, because it
is not implemented. Investigate @code{BAD}
@findex BAD
 for two consecutive bits
that are up, and inspect the meaning of each of the two bits.
@end itemize


@node Errors, Documentation, Assembler, top
@chapter  Errors

Errors are uniquely identified by a number.
The error code is the same as the @code{THROW}
@findex THROW
 code. In other words
the Forth exception system is used for errors.
A ciforth always displays
the text ``ciforth ERROR #'' plus the error number,
immediately and directly.
Of course the error numbers are given in decimal. irrespective of @code{BASE}
@findex BASE
.
This allows you to look the error up in the section ``Error explanations''.
More specific problems are addressed in the section ``Common Problems''.
@section Error philosophy
If you know the error number issued by ciforth, the situation
you are in is identified, and you can read an explanation in the next section.
Preferably in
addition to the number a @dfn{mnemonic message}
@cindex mnemonic message
 is displayed.
 It is fetched from the
@dfn{library file}
@cindex library file
.
But this is not always possible, such is the nature of error
situations.
A mnemonic message has a size limited to 63 characters and is therefore seldomly
a sufficient explanation.

A good error system gives additional specific information about the error.
In a plain ciforth this is limited to the input line that generated the error.
Via the library file you may install
a more sophisticated error reporting, if available.

Within ciforth itself all error situation have their unique identification.
You may issue errors yourself at your discretion using
@code{THROW}
@findex THROW
 or, preferably, @code{?ERROR}
@findex ?ERROR
 and use
an error number with an applicable message.
However, unless yours is a quick and dirty program, you are encouraged to
use some other unique error number.
@section Common problems


@subsection Error 11 or 12 caused by lower case.
If you type a standard word like @code{words}
@findex words
 in lower case,
it will not be recognised, resulting in error 11.
Similarly @code{' words}
@findex ' words
 results in error 12.
This is because lina is @dfn{case sensitive}
@cindex case sensitive
, i.e.
the difference between lower and upper case is significant
 and only words that match in this respect too
are found in the dictionary.

After @samp{1 LOAD} or if started up using @samp{lina -r}
you have @code{REQUIRED}
@findex REQUIRED
 available.
You may now issue @samp{  "CASE-INSENSITIVE" REQUIRED } and switch the system
into case-insensitivity and back by issuing the words @code{CASE-INSENSITIVE}
@findex CASE-INSENSITIVE
 and
@code{CASE-SENSITIVE}
@findex CASE-SENSITIVE
.

Case insensitivity applies to the words looked up in the dictionary,
not to hex digits.

@subsection Error 8 or only error numbers
If you get an error 8 as soon as you try to @code{LOAD}
@findex LOAD
 or @code{LIST}
@findex LIST
 a screen
or use an option, or if errors show up only as numbers without the mnemonic message,
this is because you cannot access the library file.
It may not be there, or it may not be at the expected place.
ciforth contains a string @code{BLOCK-FILE}
@findex BLOCK-FILE
 , that contains the name of the
library file interpreter, with as a default @file{forth.lab}.
If this is not correct you may change it as appropriate by e.g.

 @samp{S" /usrlib/ciforth/forth.lab" BLOCK-FILE $! }
The library is accessible for read and write access and mnemonic message
will be fetched from it,
after you install it with @samp{2 BLOCK-INIT    1 WARNING !}.


@subsection Error 8 while editing a screen
If after editing a screen, you get error 8, the screen has not been written
to disk, because you have no write
access for the library file.
You must issue @code{DEVELOP}
@findex DEVELOP
 which reopens the library file in READ_WRITE
mode. Normally this should be part of loading the @code{EDITOR}
@findex EDITOR
 .
 It may be of course that you don't have privilege to write
to the file. As non-privileged user you cannot edit the the system-wide library file.

You may always edit and use a private copy of the library file, by the @samp{-l} option.
@xref{Manual}, for how opttions work. The @samp{-l} option itself works only if at least the
official library file has been correctly installed.

@section Error explanations
This section shows the explanation of the errors in ascending order.
In actual situations sometimes you may not see the part after the semi colon.
If in this section an explanation is missing, this means that the
error is given for reference only; the error cannot be generated
by your lina, but maybe by
other version of ciforth or even a differently configured lina.
For example for a version without
security you will never see error 1. If it says ``not used'', this
means it is not used by any ciforth.

The errors whose message starts with @samp{AS:} are used by the PostIt FixUp assembler
in the file @file{asgen.frt},(@pxref{Assembler}).

Negative error numbers are those reported by
 Linux. If possible, mnemonic
error messages are shown. But no explanation of the error is
available.

.

Here are the error explanations.
@itemize @bullet
@item
@samp{ciforth ERROR # 1 : EMPTY STACK}

 The stack has underflowed. This is detected by
@code{?STACK}
@findex ?STACK
 at several places, in particular in
@code{INTERPRET}
@findex INTERPRET
 after each word interpreted or compiled.
There is ample slack, but malicious intent can crash the system
before this is detected. 

@item
 @samp{ciforth ERROR # 2 : DICTIONARY FULL}

Not used.

@item
@samp{ciforth ERROR # 3 : FIRST ARGUMENT MUST BE OPTION}


If you pass arguments to ciforth, your first argument must be
an option (such as -a), otherwise it doesn't know what to
do with it.

@item
 @samp{ciforth ERROR # 4 : ISN'T UNIQUE}

Not being unique is not so much an error as a warning. The word
printed is the latest defined. A word with the same name exists already in the current
search order.

@item
 @samp{ciforth ERROR # 5 : EMPTY NAME FOR NEW DEFINITION}

An attempt is made to define a new word with an empty string
for a name. This is detected by @code{(CREATE)}
@findex (CREATE)
 .
All @dfn{defining word}
@cindex defining word
 can return this message. It is
typically caused by using such a word at the end of a line.

@item
@samp{ciforth ERROR # 6 : DISK RANGE ?}

Reading to the terminal input buffer failed. The message is
probably inappropiate.

@item
@samp{ciforth ERROR # 7 : FULL STACK}

 The stack has run into the dictionary. This can be
caused by pushing too many items, but usually it must be
interpreted as dictionary full. If you have enough room, you
have passed a wrong value to @code{ALLOT}
@findex ALLOT
 . This is
detected at several places, in particular in
@code{INTERPRET}
@findex INTERPRET
 after each word interpreted.


@item
 @samp{ciforth ERROR # 8 : DISC ERROR !}

An access to the Library Accessible by Block (screen aka block
file) has failed. This is detected by
@code{?DISK-ERROR}
@findex ?DISK-ERROR
 called from places where
a disk access has occurred. It may be that the library file has
not been properly installed. Check the content of
@code{BLOCK-FILE}
@findex BLOCK-FILE
 . You may not have the right to access
it. Try to view the file. Normally the library file is opened
read-only. If you want to edit it make sure to do
@code{DEVELOP}
@findex DEVELOP
 in order to reopen it in read/write mode.
If you forget, you get this message too.

@item
 @samp{ciforth ERROR # 9 : UNRESOLVED FORWARD REFERENCE}

Not used.

@item
 @samp{ciforth ERROR # 10 : NOT A WORD, NOR A NUMBER OR OTHER DENOTATION}

The string printed was not found in the dictionary as such,
but its first part matches a @dfn{denotation}
@cindex denotation
 .
The denotation word however rejected it as not properly formed.
An example of this is a number containing some non-digit
character, or the character denotation @code{&}
@findex &
 followed by more
than one character. It may also be a miss-spelled word that
looks like a number, e.g. @samp{25WAP} .
Be aware that denotations may mask regular words.
This will only happen with user-defined denotations.
Built-in denotations are in the
@code{ONLY}
@findex ONLY
 vocabulary, that can only be accessed last,
because it ends the search order.
Note that hex digits must be typed in uppercase, 
even if @code{"CASE-SENSITIVE"}
@findex "CASE-SENSITIVE"
 is in effect.
Error 10 may be caused by using lower case where upper case is 
expected, suach as for ISO standard words.  
See the section "Common problems" in this chapter if you want
to make ciforth case insensitive.

@item
 @samp{ciforth ERROR # 11 : WORD IS NOT FOUND}

The string printed was not found in the dictionary.
This error is detected by @code{'}
@findex '
 (tick).
This may be caused by using lower case where upper case is
required for ISO standard words.
See the section "Common problems" in this chapter if you want
to make ciforth case insensitive.

@item
 @samp{ciforth ERROR # 12 : NOT RECOGNIZED}

The string printed was not found in the dictionary, nor
does it match a number, or some other denotation.
This may be caused by using lower case where upper case is
required for ISO standard words or for hex digits.
See the section "Common problems" in this chapter if you want
to make ciforth case insensitive.

@item
 @samp{ciforth ERROR # 13 : ERROR, NO FURTHER INFORMATION}

This error is used temporily, whenever there is need for
an error message but there is not yet one assigned.

@item
 @samp{ciforth ERROR # 14 : SAVE/RESTORE MUST RUN FROM FLOPPY}



@item
 @samp{ciforth ERROR # 15 : CANNOT FIND WORD TO BE POSTPONED}

The word following POSTPONE must be postponed, but it can't be found in the
search order.

@item
 @samp{ciforth ERROR # 16 : CANNOT FIND WORD TO BE COMPILED}

The word following [COMPILE] must be postponed, but it can't be found in the
search order.

@item
@samp{ciforth ERROR # 17 : COMPILATION ONLY, USE IN DEFINITION}


This error is reported by @code{?COMP}
@findex ?COMP
. You try to use a
word that doesn't work properly in interpret mode. This mostly
refers to control words like @code{IF}
@findex IF
 and @code{DO}
@findex DO
 .
If you want control words to work in interpret mode,
require @code{NEW-IF}
@findex NEW-IF
 .


@item
@samp{ciforth ERROR # 18 : EXECUTION ONLY}

This error is reported by @code{?EXEC.}
@findex ?EXEC.
. You try to use a
word that doesn't work properly in compile mode. You will not
see this error, because all words in ciforth do.


@item
 @samp{ciforth ERROR # 19 : CONDITIONALS NOT PAIRED}


This error is reported by @code{?PAIRS}
@findex ?PAIRS
. You try to
improperly use control words that pair up (like @code{IF}
@findex IF
 and
@code{THEN}
@findex THEN
 , or @code{DO}
@findex DO
 and @code{LOOP}
@findex LOOP
 )


@item
@samp{ciforth ERROR # 20 : STACK UNBALANCE, STRUCTURE UNFINISHED?}


This error is reported by @code{?CSP}
@findex ?CSP
.
It detects   stack unbalance between @code{:}
@findex :
 and @code{;}
@findex ;
,
or wherever you choose to use the words @code{!CSP}
@findex !CSP
 and @code{?CSP}
@findex ?CSP
.
This means there is an error in the compiled code.
This message is given also if during compilation you try to use data
that is put on the stack before @code{:}
@findex :
 .
Instead of

@samp{<generatedata> : name LITERAL .... ;}

use

@samp{<generatedata> : name [ _ SWAP ] LITERAL .... ; DROP}

to keep the stack at the same depth.


@item
@samp{ciforth ERROR # 21 : IN PROTECTED DICTIONARY}

The word you are trying to @code{FORGET}
@findex FORGET
 is below the @code{FENCE}
@findex FENCE
 ,
such that forgetting is not allowed.

@item
@samp{ciforth ERROR # 22 : USE ONLY WHEN LOADING}


This error is reported by @code{?LOAD}
@findex ?LOAD
. You try to use a
word that only works while loading from the @code{BLOCK-FILE}
@findex BLOCK-FILE
 ,
in casu @code{-->}
@findex -->
 .


@item
@samp{ciforth ERROR # 23 : OFF CURRENT EDITING SCREEN}

@item
@samp{ciforth ERROR # 24 : (WARNING) NOT PRESENT, THOUGH REQUIRED}
This error is reported by @code{REQUIRED}
@findex REQUIRED
.
The word you required, has been looked up in the index lines.
It was not found in the index lines, 
or it was a dummy item, 
that only marks the screen to be loaded, 
e.g. @samp{ASSEMBLER-GENERIC}.
In the latter case it can be safely ignored.
 This @b{must} be a warning only,
because compilation can still succeed if the word is supplied by
other means, in particular conditional compilation.

@samp{ciforth ERROR # 25 : LIST EXPECTS DECIMAL}

This message is used by a redefined @code{LIST}
@findex LIST
 , to prevent
getting the wrong screen.

@end itemize

@xref{ASSEMBLER},, for errors generated by the assembler.
These have numbers that are all higher than the general errors.

@node Documentation,Glossary,Errors,top
@chapter  Documentation summary

This is copied from the FIG documentation 1978.
It is probably out of date now.

The following manuals are in print:

Caltech FORTH Manual, an advanced manual with internal details of Forth. Has
Some implementation peculiarities. Approx. $6.50 from the Caltech Book
Store, Pasadena, CA.

Kitt Peak Forth Primer, $20.00 postpaid from the Forth Interest Group, P. O.
Box 1105, San Carlos, CA 94070.

microFORTH Primer, $15.00 Forth, Inc.
815 Manhattan Ave. Manhattan Beach, CA 90266


Forth Dimensions, newsletter of the Forth Interest Group, $5.00 for 6 issues
including membership. F-I-G. P.O. Box 1105, San Carlos, CA. 94070

@node Glossary,top,Documentation,top
@chapter Glossary
Wherever it says
single precision number or @dfn{cell}
@cindex cell
 32 bits is meant.
Wherever it says
 @dfn{double}
@cindex double
 or ``double precision number'' a
64 bits number is meant.

The first line of each entry shows a symbolic description of the action of
the proceedure on the parameter stack. The symbols indicate the order in
which input parameters have been placed on the stack. The dashes ``---''
indicate the execution point; any parameters left on the stack are listed.
In this notation, the top of the stack is to the right.
Any symbol may be followed by a number to indicate different data items
passed to or from a Forth word.

The symbols include:

@table @samp
@item addr
memory address
@item b
8 bit byte (the remaining bits are zero)
@item c
7 bit ascii character (the remaining bits are zero)
@item d
64 bit signed double integer: most significant portion with sign
on top of stack
@item dea
An @dfn{dictionary entry address}
@cindex dictionary entry address
 , the basic address of a Forth word from which
all its fields can be found.
@item f
logical @dfn{flag}
@cindex flag
: zero is interpreted as false, non-zero as true
@item faraddr
a <selector:address> pair

@item ff
@dfn{Forth flag}
@cindex Forth flag
, a well-formed logical flag, 0=false, -1=true.
@item false
a false @dfn{Forth flag}
@cindex Forth flag
: 0
@item n
32 bit signed integer number;
it is also used for a 32-bit entity where it is irrelevant what number it represents
@item sc
a @dfn{string constant}
@cindex string constant
, i.e. two cells, an address and a length;
length characters are present at the address
(they must not be changed)
@item true
a true @dfn{Forth flag}
@cindex Forth flag
: -1.
@item u
32-bit unsigned integer
@item ud
64-bit unsigned double integer: most significant portion
on top of stack
@end table


The capital letters on the right show definition characteristics:

@table @samp
@item B
The word is available only after loading from background storage
@item C
May only be used within a colon definition. A digit indicates number
of memory addresses used, if other than one.
@item E
Intended for execution only.
@item FIG
Belongs to the FIG model
@item I
Has immediate bit set. Will execute even when compiling.
@item ISO
Belongs to ISO standard
@item L0
Level Zero definition of FORTH-78
@item L1
Level One definition of FORTH-78
@item NFIG
Word belongs to FIG standard, 
but the implementation is not quite conforming.
@item NISO
Word belongs to ISO standard, but the implementation is not
quite conforming.
@item U
A user variable.
@end table

Where there is mention of a standard or a model,
it means that the word actually complies to the standard or the model,
not that some word of that name is present.
Words marked with @samp{ISO,FIG,L0} will behave identically
over all but the whole spectra of Forth's.

Unless otherwise noted, all references to numbers are for 32-bit
signed integers. For 64-bit signed numbers, the
most significant part (with the sign) is on top.

All arithmetic is implicitly 32-bit signed integer math, with error and
under-flow indication unspecified.

A @dfn{nil pointer}
@cindex nil pointer
 is an address containing zero. This
indicates an invalid address.

The Forth words are divided into @dfn{wordset}
@cindex wordset
s, that contain
words that logically belong together. Each wordset has a separate section
with a description.
The following rules take precedence over any wordset a word may
logically belong to.
@itemize @bullet
@item
A defining word --- one that adds to the dictionary --- is
present in the wordset @samp{DEFINING}.
@item
A denotation word -- one that has the prefix bit set -- is 
present in the wordset @samp{DENOTATIONS}.
@item
An environmental query word --- one that is understood by
@code{?ENVIRONMENT}
@findex ?ENVIRONMENT
 --- is present in the wordset
@samp{ENVIRONMENTS}.
@end itemize

@menu
* BLOCKS ::
* COMPILING ::
* CONTROL ::
* DEFINING ::
* DENOTATIONS ::
* DICTIONARY ::
* DOUBLE ::
* ENVIRONMENTS ::
* ERRORS ::
* FILES ::
* FORMATTING ::
* INIT ::
* INPUT ::
* JUGGLING ::
* LOGIC ::
* MEMORY ::
* MISC ::
* MULTIPLYING ::
* OPERATINGSYSTEM ::
* OPERATOR ::
* OUTPUT ::
* PARSING ::
* SCREEN ::
* SECURITY ::
* STACKS ::
* STRING ::
* SUPERFLUOUS ::
* WORDLISTS ::
@end menu



 





@node BLOCKS, COMPILING,, Glossary
@section BLOCKS
     
    The block mechanism connects to the Forth system a single background
storage divided in numbered @dfn{blocks}
@cindex blocks
.
The wordset @samp{BLOCKS} contains words to input and
output to this mass storage. In this ciforth blocks reside
  in a file, by default
named @file{forth.lab}. . Most blocks are used for the
@samp{SCREEN} facility, where each block contains source
code.

    

    

@menu


* #BUFF  ::
* ?DISK-ERROR  ::
* B/BUF  ::
* BLOCK-EXIT  ::
* BLOCK-FILE  ::
* BLOCK-HANDLE  ::
* BLOCK-INIT  ::
* BLOCK  ::
* DISK-ERROR  ::
* EMPTY-BUFFERS  ::
* R\W  ::
* UPDATE  ::
* (BUFFER)  :paren_buffer
* +BUF  ::
* FIRST  ::
* FLUSH  ::
* LIMIT  ::
* OFFSET  ::
* PREV  ::
* RESTORE-INPUT  ::
* RESTORE  ::
* SAVE-INPUT  ::
* SAVE  ::
* SEEK  ::
* STALEST  ::
@end menu
@node #BUFF, ?DISK-ERROR, BLOCKS, BLOCKS
@subsection #BUFF
@pindex #BUFF
@findex #BUFF

@noindent
Name: @code{#BUFF}

@noindent
Stackeffect: --- n

@noindent
Attributes: 

@noindent
Description:
A constant that leaves the number of block buffers.
Because a buffer that is being interpreted is locked in memory,
this is also a limit to the nesting depth of blocks loading other
blocks. 

@noindent
See also: @samp{BLOCK}
 @samp{THRU}
 @samp{LOAD}
 @samp{LOCK}
 



        


@node ?DISK-ERROR, B/BUF, #BUFF, BLOCKS
@subsection ?DISK-ERROR
@pindex ?DISK-ERROR
@findex ?DISK-ERROR

@noindent
Name: @code{?DISK-ERROR}

@noindent
Stackeffect: n---

@noindent
Attributes: 

@noindent
Description:
Interpret @samp{n} as the status of a disk i/o call and
@dfn{signal an error}
@cindex signal an error
 if it contains an error condition.


@noindent
See also: @samp{BLOCK-FILE}
 @samp{BLOCK-HANDLE}
 @samp{BLOCK-INIT}
 @samp{BLOCK-EXIT}
 



        


@node B/BUF, BLOCK-EXIT, ?DISK-ERROR, BLOCKS
@subsection B/BUF
@pindex B/BUF
@findex B/BUF

@noindent
Name: @code{B/BUF}

@noindent
Stackeffect: --- n

@noindent
Attributes: 

@noindent
Description:
This constant leaves the number of bytes per disc buffer, the byte
count read from disc by @code{BLOCK}
@findex BLOCK
 .
The ISO standard fixes this to 1024.

@noindent
See also: @samp{(BUFFER)}
 
        


@node BLOCK-EXIT, BLOCK-FILE, B/BUF, BLOCKS
@subsection BLOCK-EXIT
@pindex BLOCK-EXIT
@findex BLOCK-EXIT

@noindent
Name: @code{BLOCK-EXIT}

@noindent
Stackeffect: ---

@noindent
Attributes: 

@noindent
Description:
A block file must have been opened by @code{BLOCK-INIT}
@findex BLOCK-INIT
 .
Close the currently open block file @code{BLOCK-HANDLE}
@findex BLOCK-HANDLE
,
i.e. the mass storage words no longer work, and will result in
error messages.
If error messages were fetched from disk, they
no longer are.

@noindent
See also: @samp{BLOCK}
 @samp{LIST}
 @samp{LOAD}
 @samp{DISK-ERROR}
 @samp{WARNING}
 




        


@node BLOCK-FILE, BLOCK-HANDLE, BLOCK-EXIT, BLOCKS
@subsection BLOCK-FILE
@pindex BLOCK-FILE
@findex BLOCK-FILE

@noindent
Name: @code{BLOCK-FILE}

@noindent
Stackeffect: ---addr

@noindent
Attributes: 

@noindent
Description:
Leave the address @samp{addr} of a counted string,
the name of a @dfn{library file}
@cindex library file

in which @dfn{blocks}
@cindex blocks
 are (to be) allocated.
The name may contain a path and be at most
252 characters long.
The default name is @samp{forth.lab} .
This name may be changed and is used by the
 @code{BLOCK-INIT}
@findex BLOCK-INIT
 command.


@noindent
See also: @samp{BLOCK-HANDLE}
 @samp{BLOCK-INIT}
 @samp{BLOCK-EXIT}
 


        


@node BLOCK-HANDLE, BLOCK-INIT, BLOCK-FILE, BLOCKS
@subsection BLOCK-HANDLE
@pindex BLOCK-HANDLE
@findex BLOCK-HANDLE

@noindent
Name: @code{BLOCK-HANDLE}

@noindent
Stackeffect: ---n

@noindent
Attributes: 

@noindent
Description:
Leave a file handle in @samp{n} .
If it is negative there is no block file open,
otherwise the handle is used by the system to access blocks.



@noindent
See also: @samp{BLOCK-FILE}
 @samp{BLOCK-INIT}
 @samp{BLOCK-EXIT}
 


        


@node BLOCK-INIT, BLOCK, BLOCK-HANDLE, BLOCKS
@subsection BLOCK-INIT
@pindex BLOCK-INIT
@findex BLOCK-INIT

@noindent
Name: @code{BLOCK-INIT}

@noindent
Stackeffect: n ---

@noindent
Attributes: 

@noindent
Description:
Map the blocks on the block file @code{BLOCK-FILE}
@findex BLOCK-FILE
,
i.e. the mass storage words refer
to the blocks in this file. The handle
@samp{BLOCK-HANDLE} can be used
to access it, with access code @samp{n}
(2 for read and write).
This command fails silently.
You must activate mnemonic error messages explicitly
by setting @code{WARNING}
@findex WARNING
.


@noindent
See also: @samp{BLOCK}
 @samp{LIST}
 @samp{LOAD}
 @samp{BLOCK-EXIT}
 @samp{OPEN-FILE}
 




        


@node BLOCK, DISK-ERROR, BLOCK-INIT, BLOCKS
@subsection BLOCK
@pindex BLOCK
@findex BLOCK

@noindent
Name: @code{BLOCK}

@noindent
Stackeffect: n --- addr

@noindent
Attributes: ISO FIG L0

@noindent
Description:
Leave @samp{addr}, the disc buffer containing block
@samp{n}, which is the physical disk block
@samp{OFFSET+n}. The address left is the field within the
buffer to be used for data storage. If the block is not already
in memory, it is transferred from disc to a new buffer allocated
by @code{(BUFFER)}
@findex (BUFFER)
 .
Blocks are generally
used to contain source code to be interpreted
by @code{LOAD}
@findex LOAD
. They can be equally useful to contain
other data, e.g. for implementing a database. 


@noindent
See also: @samp{(BUFFER)}
 @samp{R\W}
 @samp{OFFSET}
 @samp{UPDATE}
 @samp{FLUSH}
 @samp{LOAD}
 





        


@node DISK-ERROR, EMPTY-BUFFERS, BLOCK, BLOCKS
@subsection DISK-ERROR
@pindex DISK-ERROR
@findex DISK-ERROR

@noindent
Name: @code{DISK-ERROR}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
using or
closing the block file.
One means an
error and and zero means okay.
Beware that if error messages are loaded from disk,
this may clear @code{DISK-ERROR}
@findex DISK-ERROR
 
This flag is not used.


@noindent
See also: @samp{BLOCK}
 
        


@node EMPTY-BUFFERS, R\W, DISK-ERROR, BLOCKS
@subsection EMPTY-BUFFERS
@pindex EMPTY-BUFFERS
@findex EMPTY-BUFFERS

@noindent
Name: @code{EMPTY-BUFFERS}

@noindent
No stackeffect

@noindent
Attributes: ISO FIG L0

@noindent
Description:
Mark all block-buffers as empty. Updated blocks are not
written to the disc. This is an initialization proceedure
before first use of the disc. The usage as an
``undo'' is infeasible in ciforth. 

@noindent
See also: @samp{FLUSH}
 @samp{BLOCK}
 @samp{SCREEN}
 @samp{UPDATE}
 



        


@node R\W, UPDATE, EMPTY-BUFFERS, BLOCKS
@subsection R\W
@pindex R\W
@findex R\W

@noindent
Name: @code{R\W}

@noindent
Stackeffect: addr blk n ---

@noindent
Attributes: 

@noindent
Description:
The ciforth primitive for read-write of blocks. @samp{addr}
specifies the source or destination block buffer, @samp{blk} is
the sequential number of the referenced physical block; and
@samp{n} is a control variable
for @samp{n}=0 write and @samp{n}=l
read. @code{R\W}
@findex R\W
 determines the location on mass storage,
performs the read or write and throws an exception on errors.

@noindent
See also: @samp{BLOCK}
 @samp{DISK-ERROR}
 

        


@node UPDATE, paren_buffer, R\W, BLOCKS
@subsection UPDATE
@pindex UPDATE
@findex UPDATE

@noindent
Name: @code{UPDATE}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Marks the most recently referenced block (pointed to by
@code{PREV}
@findex PREV
 ) as altered. The block will subsequently be
transferred automatically to disc should its buffer be required for
storage of a different block. In fact the block is transferred
to disk immediately.

@noindent
See also: @samp{BLOCK}
 @samp{SCREEN}
 

        


@node paren_buffer, +BUF, UPDATE, BLOCKS
@subsection (BUFFER)
@pindex (BUFFER)
@findex (BUFFER)

@noindent
Name: @code{(BUFFER)}

@noindent
Stackeffect: n --- addr

@noindent
Attributes: 

@noindent
Description:
Return the addres @samp{addr} of a buffer assigned to
block @samp{n} .
The buffer layout is as follows: a cell
with the block number, a cell with the status, and the
content. The status is negative for locked, zero for free and
one for present and unlocked.
The block is not read from the disc. The buffer
is either one that was already assigned, or else a free buffer.
If there is none free, the stalest buffer is freed. The
contents of that buffer is written to the disc, if it was
marked as updated. In ciforth this is never needed, because
updated blocks are written immediately. In ciforth blocks can
be locked, and locked buffers are never freed by
@code{(BUFFER)}
@findex (BUFFER)
 .
An update flag would somehow be multiplexed with
the lock count, but it is not needed in ciforth. If all
buffers were locked, @code{(BUFFER)}
@findex (BUFFER)
 freezes the system.


@noindent
See also: @samp{BLOCK}
 @samp{STALEST}
 @samp{PREV}
 @samp{#BUFF}
 @samp{LOCK}
 @samp{UNLOCK}
 





        


@node +BUF, FIRST, paren_buffer, BLOCKS
@subsection +BUF
@pindex +BUF
@findex +BUF

@noindent
Name: @code{+BUF}

@noindent
Stackeffect: addr1 --- addr2 ff

@noindent
Attributes: FIG

@noindent
Description:
Advance the disc buffer address @samp{addr1} to the address of
the next buffer @samp{addr2} . Boolean @samp{ff} is false
when @samp{addr2} is the buffer presently pointed to by variable
@code{PREV}
@findex PREV
.


@noindent
See also: @samp{BLOCK}
 
        


@node FIRST, FLUSH, +BUF, BLOCKS
@subsection FIRST
@pindex FIRST
@findex FIRST

@noindent
Name: @code{FIRST}

@noindent
Stackeffect: --- n

@noindent
Attributes: 

@noindent
Description:
A constant that leaves the address of the first (lowest) block
buffer.

@noindent
See also: @samp{BLOCK}
 @samp{LIMIT}
 

        


@node FLUSH, LIMIT, FIRST, BLOCKS
@subsection FLUSH
@pindex FLUSH
@findex FLUSH

@noindent
Name: @code{FLUSH}

@noindent
No stackeffect

@noindent
Attributes: ISO FIG L0

@noindent
Description:
Make sure that the content of all @code{UPDATE}
@findex UPDATE
 d block buffers
has been transferred to disk.
They are no longer associated with a block and their content is
no longer available.


@noindent
See also: @samp{EMPTY-BUFFERS}
 @samp{BLOCK}
 @samp{SCREEN}
 


        


@node LIMIT, OFFSET, FLUSH, BLOCKS
@subsection LIMIT
@pindex LIMIT
@findex LIMIT

@noindent
Name: @code{LIMIT}

@noindent
Stackeffect: ---- n

@noindent
Attributes: 

@noindent
Description:
A constant leaving the address just above the highest memory
available for a disc buffer.
Actually this is the highest system memory. 


@noindent
See also: @samp{BLOCK}
 @samp{FIRST}
 

        


@node OFFSET, PREV, LIMIT, BLOCKS
@subsection OFFSET
@pindex OFFSET
@findex OFFSET

@noindent
Name: @code{OFFSET}

@noindent
Stackeffect: --- addr

@noindent
Attributes: U

@noindent
Description:
A user variable which contains a block offset to disc drives;
in this way a part of it is available for boot-code.

As blocks are allocated in a file on the host operating system it is 0.
The
contents of @code{OFFSET}
@findex OFFSET
 is added to the stack number by @code{BLOCK}
@findex BLOCK
 before calling
@samp{R\W}. 

@noindent
See also: @samp{BLOCK}
 @samp{MESSAGE }
 

        


@node PREV, RESTORE-INPUT, OFFSET, BLOCKS
@subsection PREV
@pindex PREV
@findex PREV

@noindent
Name: @code{PREV}

@noindent
Stackeffect: ---- addr

@noindent
Attributes: 

@noindent
Description:
A variable containing the address of the disc buffer (not its
content field!) most recently referenced. The
@code{UPDATE}
@findex UPDATE
 command marks this buffer to be
written to disc.

@noindent
See also: @samp{(BUFFER)}
 
        


@node RESTORE-INPUT, RESTORE, PREV, BLOCKS
@subsection RESTORE-INPUT
@pindex RESTORE-INPUT
@findex RESTORE-INPUT

@noindent
Name: @code{RESTORE-INPUT}

@noindent
Stackeffect:  n1 n2 n3 3---f

@noindent
Attributes: ISO

@noindent
Description:
Restore the input source stream from what was saved by
SAVE-INPUT .
ciforth is always able to restore the input across
different input sources, as long as the input to be restored was
not exhausted. This has the effect of chaining, and doesn't
affect the return from nested calls be it interpreting, loading
or evaluating. ciforth always returns a true into @samp{f}.
The input source abandoned will
never be closed properly, so use should be restricted to the same
input source.  

@noindent
See also: @samp{RESTORE}
 @samp{SAVE-INPUT}
 

        


@node RESTORE, SAVE-INPUT, RESTORE-INPUT, BLOCKS
@subsection RESTORE
@pindex RESTORE
@findex RESTORE

@noindent
Name: @code{RESTORE}

@noindent
Stackeffect:  ---

@noindent
Attributes: 

@noindent
Description:
This must follow a @code{SAVE}
@findex SAVE
 in the same definition.
Restore the content of @code{SRC}
@findex SRC
 from the return stack
thus restoring the @dfn{current input source}
@cindex current input source
 to what
it was when the @code{SAVE}
@findex SAVE
 was executed.


@noindent
See also: @samp{RESTORE-INPUT}
 @samp{SAVE-INPUT}
 

        


@node SAVE-INPUT, SAVE, RESTORE, BLOCKS
@subsection SAVE-INPUT
@pindex SAVE-INPUT
@findex SAVE-INPUT

@noindent
Name: @code{SAVE-INPUT}

@noindent
Stackeffect:  --- n1 n2 n3 3

@noindent
Attributes: ISO

@noindent
Description:
Get a complete specification of the input source stream. For
ciforth this is the content of @code{SRC}
@findex SRC
. ciforth needs
3 cells, and is always able to @code{RESTORE}
@findex RESTORE
 an input
saved like this. In practice the use of
@code{SAVE-INPUT}
@findex SAVE-INPUT
 should be restricted to restoring input
of the same stream.
 

@noindent
See also: @samp{RESTORE}
 @samp{RESTORE-INPUT}
 

        


@node SAVE, SEEK, SAVE-INPUT, BLOCKS
@subsection SAVE
@pindex SAVE
@findex SAVE

@noindent
Name: @code{SAVE}

@noindent
Stackeffect:  ---

@noindent
Attributes: 

@noindent
Description:
Save the content of @code{SRC}
@findex SRC
 on the return stack
prior to changing the @dfn{current input source}
@cindex current input source
.
This must be balanced by a RESTORE in the same definition.

@noindent
See also: @samp{RESTORE}
 @samp{SAVE-INPUT}
 

        


@node SEEK, STALEST, SAVE, BLOCKS
@subsection SEEK
@pindex SEEK
@findex SEEK

@noindent
Name: @code{SEEK}

@noindent
Stackeffect: n---

@noindent
Attributes: 

@noindent
Description:
A block file must have been opened by @code{BLOCK-INIT}
@findex BLOCK-INIT
 .
Position the file pointer at block @samp{n}
in behalf of subsequent reads and writes.


@noindent
See also: @samp{BLOCK}
 @samp{LIST}
 @samp{LOAD}
 


        


@node STALEST, , SEEK, BLOCKS
@subsection STALEST
@pindex STALEST
@findex STALEST

@noindent
Name: @code{STALEST}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
A variable containing the address of the oldest
block buffer, the first candidate to be claimed if a new
one is needed.

@noindent
See also: @samp{BLOCK}
 
        




@node COMPILING, CONTROL,BLOCKS, Glossary
@section COMPILING
     
    The wordset @samp{COMPILING} contains words that compile
@xref{IMMEDIATE}, words and numbers.
You need special precautions because these words would execute during
compilation. Numbers are compiled @dfn{in line}
@cindex in line
 , behind a word that fetches
them.
    

    

@menu


* DLITERAL  ::
* LITERAL  ::
* POSTPONE  ::
* [COMPILE]  :bracket_compile
* LIT  ::
* SDLITERAL  ::
@end menu
@node DLITERAL, LITERAL, COMPILING, COMPILING
@subsection DLITERAL
@pindex DLITERAL
@findex DLITERAL

@noindent
Name: @code{DLITERAL}

@noindent
Stackeffect: d --- d (executing) d --- (compiling)

@noindent
Attributes: I

@noindent
Description:
If compiling, compile a stack double number into a literal.
Later execution of the definition containing the literal will
push it to the stack. If executing in ciforth, the number will just remain on
the stack.

@noindent
See also: @samp{LITERAL}
 @samp{LIT}
 

        


@node LITERAL, POSTPONE, DLITERAL, COMPILING
@subsection LITERAL
@pindex LITERAL
@findex LITERAL

@noindent
Name: @code{LITERAL}

@noindent
Stackeffect: n --- n (executing) n --- (compiling)

@noindent
Attributes: ISO,I,C2,L0

@noindent
Description:
If compiling, then compile the stack value @samp{n} as a
32 bit literal.
The intended use is:
     @samp{: xxx    [ calculate ]  LITERAL  ;}
Compilation is suspended for the compile time calculation of a
value. Compilation is resumed and @code{LITERAL}
@findex LITERAL
 compiles
this value. Later execution of the definition containing the literal will
push it to the stack. If executing in ciforth, the number will just remain on
the stack.

@noindent
See also: @samp{LIT}
 @samp{LITERAL}
 

        


@node POSTPONE, bracket_compile, LITERAL, COMPILING
@subsection POSTPONE
@pindex POSTPONE
@findex POSTPONE

@noindent
Name: @code{POSTPONE}

@noindent
No stackeffect

@noindent
Attributes: ISO,I,C

@noindent
Description:
Used in a colon-definition in the form:
    @example
@iftex
@cartouche
: xxx POSTPONE SOME-WORD 
@end cartouche
@end iftex
@ifinfo
: xxx POSTPONE SOME-WORD 
@end ifinfo
@end example
@code{POSTPONE}
@findex POSTPONE
 will postpone the
compilation behaviour of @samp{SOME-WORD} to the
definition being compiled. If @samp{SOME-WORD} is an immediate word
this is similar to @samp{[COMPILE] SOME-WORD}. 

@noindent
See also: @samp{[COMPILE]}
 
        


@node bracket_compile, LIT, POSTPONE, COMPILING
@subsection [COMPILE]
@pindex [COMPILE]
@findex [COMPILE]

@noindent
Name: @code{[COMPILE]}

@noindent
No stackeffect

@noindent
Attributes: ISO,I,C

@noindent
Description:
Used in a colon-definition in form:
@example
@iftex
@cartouche
:  xxx    [COMPILE]   FORTH   ;
@end cartouche
@end iftex
@ifinfo
:  xxx    [COMPILE]   FORTH   ;
@end ifinfo
@end example
@code{[COMPILE]}
@findex [COMPILE]
 will force the compilation of an immediate definitions,
that would otherwise execute during compilation. The above example
will select the @code{FORTH}
@findex FORTH
 vocabulary when @samp{xxx} executes, rather than at
compile time.

@noindent
See also: @samp{POSTPONE}
 
        


@node LIT, SDLITERAL, bracket_compile, COMPILING
@subsection LIT
@pindex LIT
@findex LIT

@noindent
Name: @code{LIT}

@noindent
Stackeffect: --- n

@noindent
Attributes: FIG,C2,L0

@noindent
Description:
Within a colon-definition, @code{LIT}
@findex LIT
 is compiled followed by a
32 bit literal number given during compilation.
Later execution of @code{LIT}
@findex LIT
 causes the contents of this
next dictionary cell to be pushed to the stack.

@noindent
See also: @samp{LITERAL}
 
        


@node SDLITERAL, , LIT, COMPILING
@subsection SDLITERAL
@pindex SDLITERAL
@findex SDLITERAL

@noindent
Name: @code{SDLITERAL}

@noindent
Stackeffect: d --- s/d (executing) d --- (compiling)

@noindent
Attributes: I

@noindent
Description:
If compiling, compile a stack double number into a literal or
double literal, depending on whether @code{DPL}
@findex DPL
 contains a
@dfn{nil pointer}
@cindex nil pointer
 or points into the input. Later execution of the
definition containing the literal will push it to the stack. If
executing, the number will remain on the stack.

@noindent
See also: @samp{SLITERAL}
 @samp{DLITERAL}
 

        




@node CONTROL, DEFINING,COMPILING, Glossary
@section CONTROL
     
    The wordset @samp{CONTROL} contains words that influence the control flow
of a program, i.e. the sequence in which commands are executed in compiled words.
With control words you can have actions performed repeatedly, or
depending on conditions.

    

    

@menu


* +LOOP  ::
* ?DO  ::
* AGAIN  ::
* BEGIN  ::
* CO  ::
* DO  ::
* ELSE  ::
* EXIT  ::
* IF  ::
* I  ::
* J  ::
* LEAVE  ::
* LOOP  ::
* RECURSE  ::
* REPEAT  ::
* SKIP  ::
* THEN  ::
* UNLOOP  ::
* UNTIL  ::
* WHILE  ::
* (+LOOP)  :paren_plus_loop
* (;)  :paren_semicolon
* (?DO)  :paren_question_do
* (BACK  :paren_back
* (DO)  :paren_do
* (FORWARD  :paren_forward
* (LOOP)  :paren_loop
* 0BRANCH  ::
* BACK)  :back_paren
* BRANCH  ::
* FORWARD)  :forward_paren
@end menu
@node +LOOP, ?DO, CONTROL, CONTROL
@subsection +LOOP
@pindex +LOOP
@findex +LOOP

@noindent
Name: @code{+LOOP}

@noindent
Stackeffect: n1 --- (run)  addr n2 --- (compile)

@noindent
Attributes: ISO,I,C2,L0

@noindent
Description:
Used in a colon-definition in the form:
    @example
@iftex
@cartouche
DO ... n1 +LOOP
@end cartouche
@end iftex
@ifinfo
DO ... n1 +LOOP
@end ifinfo
@end example
At run-time, @code{+LOOP}
@findex +LOOP
 selectively controls branching
back to the corresponding @code{DO}
@findex DO
 based on
@samp{n1} , the loop index and the loop limit. The signed
increment @samp{n1} is added to the index and the total
compared to the limit.
The branch back to @code{DO}
@findex DO
 occurs until the new index
is equal to or greater than the limit (@samp{n1>0}), or
until the new index is equal to or less than the limit
(@samp{n1<0}). Upon exiting the loop, the parameters are
discarded and execution continues ahead.

At compile time, @code{+LOOP}
@findex +LOOP
 compiles the run-time word
@code{(+LOOP)}
@findex (+LOOP)
 and the branch offset computed from
@code{HERE}
@findex HERE
 to the address left on the stack by
@code{DO}
@findex DO
 .
 @samp{n2} is used for compile time error
checking.

        


@node ?DO, AGAIN, +LOOP, CONTROL
@subsection ?DO
@pindex ?DO
@findex ?DO

@noindent
Name: @code{?DO}

@noindent
Stackeffect: n1 n2 --- (execute)
addr n --- (compile)

@noindent
Attributes: ISO,I,C2,L0

@noindent
Description:
Occurs in a colon-definition in form:
    @example
@iftex
@cartouche
?DO ... LOOP
@end cartouche
@end iftex
@ifinfo
?DO ... LOOP
@end ifinfo
@end example
It behaves like DO , with the exception that if n1 and n2 are equal
the loop body is not executed.

@noindent
See also: @samp{DO}
 @samp{I}
 @samp{LOOP}
 @samp{+LOOP}
 @samp{LEAVE}
 




        


@node AGAIN, BEGIN, ?DO, CONTROL
@subsection AGAIN
@pindex AGAIN
@findex AGAIN

@noindent
Name: @code{AGAIN}

@noindent
Stackeffect: addr n --- (compiling)

@noindent
Attributes: ISO,FIG,I,C2,L0

@noindent
Description:
Used in a colon-definition in the form:
    @example
@iftex
@cartouche
BEGIN ... AGAIN
@end cartouche
@end iftex
@ifinfo
BEGIN ... AGAIN
@end ifinfo
@end example
At run-time,
@code{AGAIN}
@findex AGAIN
 forces execution to return to the corresponding
@code{BEGIN}
@findex BEGIN
 . There is no effect on the stack. Execution
cannot leave this loop except for @code{EXIT}
@findex EXIT
. At compile
time, @code{AGAIN}
@findex AGAIN
 compiles @code{BRANCH}
@findex BRANCH
 with an
offset from @code{HERE}
@findex HERE
 to addr. @samp{n} is used
for compile-time error checking.

@noindent
See also: @samp{BEGIN}
 
        


@node BEGIN, CO, AGAIN, CONTROL
@subsection BEGIN
@pindex BEGIN
@findex BEGIN

@noindent
Name: @code{BEGIN}

@noindent
Stackeffect: --- addr n  (compiling)

@noindent
Attributes: ISO,FIG,I,L0

@noindent
Description:
Occurs in a colon-definition in one of the forms:
  @example
@iftex
@cartouche
BEGIN ... UNTIL
@end cartouche
@end iftex
@ifinfo
BEGIN ... UNTIL
@end ifinfo
@end example
  @example
@iftex
@cartouche
BEGIN ... AGAIN
@end cartouche
@end iftex
@ifinfo
BEGIN ... AGAIN
@end ifinfo
@end example
  @example
@iftex
@cartouche
BEGIN ... WHILE ... REPEAT
@end cartouche
@end iftex
@ifinfo
BEGIN ... WHILE ... REPEAT
@end ifinfo
@end example
At run-time, @code{BEGIN}
@findex BEGIN
 marks the start of a sequence that may be
repetitively executed. It serves as a return point from the
corresponding @code{UNTIL}
@findex UNTIL
 , @code{AGAIN}
@findex AGAIN
 or @code{REPEAT}
@findex REPEAT
 .
When executing @code{UNTIL}
@findex UNTIL
 a return
to @code{BEGIN}
@findex BEGIN
 will occur if the top of the stack is false;
for @code{AGAIN}
@findex AGAIN
 and @code{REPEAT}
@findex REPEAT
 a return to @code{BEGIN}
@findex BEGIN
 always occurs.

At compile time @code{BEGIN}
@findex BEGIN
 leaves its return address and @samp{n} for compiler
error checking.

@noindent
See also: @samp{(BACK}
 
        


@node CO, DO, BEGIN, CONTROL
@subsection CO
@pindex CO
@findex CO

@noindent
Name: @code{CO}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
 Return suspend interpretation of the current definition,
such that when the caller exits, this definition is resumed.
The return
stack must not be engaged, such as between @code{>R}
@findex >R
 and
@code{R>}
@findex R>
 , or @code{DO}
@findex DO
 and @code{LOOP}
@findex LOOP
 .


@noindent
See also: @samp{EXIT}
 
        


@node DO, ELSE, CO, CONTROL
@subsection DO
@pindex DO
@findex DO

@noindent
Name: @code{DO}

@noindent
Stackeffect: n1 n2 --- (execute) addr n --- (compile)

@noindent
Attributes: ISO,FIG,I,C2,L0

@noindent
Description:
Occurs in a colon-definition in form: @samp{DO ... LOOP}
At run time, @code{DO}
@findex DO
 begins a sequence with repetitive
execution controlled by a loop limit @samp{n1} and an
index with initial value @samp{n2} .
@code{DO}
@findex DO
 removes
these from the stack. Upon reaching @code{LOOP}
@findex LOOP
 the
index is incremented by one. Until the new index equals or
exceeds the limit, execution loops back to just after
@code{DO}
@findex DO
 ; otherwise the loop parameters are discarded
and execution continues ahead. Both @samp{n1} and
@samp{n2} are determined at run-time and may be the result
of other operations. Within a loop @code{I}
@findex I
 will copy the
current value of the index to the stack.

When compiling within the colon definition, @code{DO}
@findex DO
 compiles
@code{(DO)}
@findex (DO)
 and leaves the following address @samp{addr} and
@samp{n} for later error checking.

@noindent
See also: @samp{I}
 @samp{LOOP}
 @samp{+LOOP}
 @samp{LEAVE}
 



        


@node ELSE, EXIT, DO, CONTROL
@subsection ELSE
@pindex ELSE
@findex ELSE

@noindent
Name: @code{ELSE}

@noindent
Stackeffect: addr1 n1 --- addr2 n2 (compiling)

@noindent
Attributes: ISO,FIG,I,C2,L0

@noindent
Description:
Occurs within a colon-definition in the form:
               @example
@iftex
@cartouche
IF ... ELSE ... THEN
@end cartouche
@end iftex
@ifinfo
IF ... ELSE ... THEN
@end ifinfo
@end example
At run-time, @code{ELSE}
@findex ELSE
 executes after the true part
following @code{IF}
@findex IF
 . @code{ELSE}
@findex ELSE
 forces execution
to skip over the following false part and resumes execution
after the @code{THEN}
@findex THEN
 . It has no stack effect.

At compile-time @code{ELSE}
@findex ELSE
 emplaces
@code{BRANCH}
@findex BRANCH
 reserving a branch offset, leaves the
address @samp{addr2} and @samp{n2} for error
testing. @code{ELSE}
@findex ELSE
 also resolves the pending forward
branch from @code{IF}
@findex IF
 by calculating the offset from
@samp{addr1} to @code{HERE}
@findex HERE
 and storing at
@samp{addr1} .

@noindent
See also: @samp{(FORWARD}
 
        


@node EXIT, IF, ELSE, CONTROL
@subsection EXIT
@pindex EXIT
@findex EXIT

@noindent
Name: @code{EXIT}

@noindent
No stackeffect

@noindent
Attributes: ISO

@noindent
Description:
 Stop interpretation of the current definition. The return
stack must not be engaged, such as between @code{>R}
@findex >R
 and
@code{R>}
@findex R>
 , or @code{DO}
@findex DO
 and @code{LOOP}
@findex LOOP
 . In
ciforth it can also be used to terminate
interpretation from a
string, block or file, or a line from the current input stream.


@noindent
See also: @samp{(;)}
 
        


@node IF, I, EXIT, CONTROL
@subsection IF
@pindex IF
@findex IF

@noindent
Name: @code{IF}

@noindent
Stackeffect: f --- (run-time) / --- addr n (compile)

@noindent
Attributes: ISO,FIG,I,C2,L0

@noindent
Description:
Occurs in a colon-definition in form:
      @example
@iftex
@cartouche
IF (tp) ...  THEN
@end cartouche
@end iftex
@ifinfo
IF (tp) ...  THEN
@end ifinfo
@end example
    or
      @example
@iftex
@cartouche
IF (tp) ... ELSE (fp) ... THEN
@end cartouche
@end iftex
@ifinfo
IF (tp) ... ELSE (fp) ... THEN
@end ifinfo
@end example
At run-time, @code{IF}
@findex IF
 selects execution based on a
boolean flag. If @samp{f} is true (non-zero), execution
continues ahead thru the true part. If @samp{f} is false
(zero), execution skips till just after @code{ELSE}
@findex ELSE
 to
execute the false part. After either part, execution resumes
after @code{THEN}
@findex THEN
.
@code{ELSE}
@findex ELSE
 and its false part are optional; if missing,
false execution skips to just after @code{THEN}
@findex THEN
 .

At compile-time @code{IF}
@findex IF
 compiles
@code{0BRANCH}
@findex 0BRANCH
 and reserves space for an offset at
@samp{addr} . @samp{addr} and @samp{n} are
used later for resolution of the offset and error testing.

@noindent
See also: @samp{(FORWARD}
 
        


@node I, J, IF, CONTROL
@subsection I
@pindex I
@findex I

@noindent
Name: @code{I}

@noindent
Stackeffect: --- n

@noindent
Attributes: ISO,FIG,C,L0

@noindent
Description:
Used within a do-loop to copy the loop index to the stack.

@noindent
See also: @samp{DO}
 @samp{LOOP}
 @samp{+LOOP}
 


        


@node J, LEAVE, I, CONTROL
@subsection J
@pindex J
@findex J

@noindent
Name: @code{J}

@noindent
Stackeffect: --- n

@noindent
Attributes: ISO,FIG,C,L0

@noindent
Description:
Used within a nested do-loop to copy the loop index of the
outer do-loop to the stack.

@noindent
See also: @samp{DO}
 @samp{LOOP}
 @samp{+LOOP}
 


        


@node LEAVE, LOOP, J, CONTROL
@subsection LEAVE
@pindex LEAVE
@findex LEAVE

@noindent
Name: @code{LEAVE}

@noindent
No stackeffect

@noindent
Attributes: ISO

@noindent
Description:
Termination a do-loop by branching to directly behind the
end of a loop started by @samp{DO} or @samp{?DO} ,
so after the corresponding
@code{LOOP}
@findex LOOP
 or @code{+LOOP}
@findex +LOOP
 .

        


@node LOOP, RECURSE, LEAVE, CONTROL
@subsection LOOP
@pindex LOOP
@findex LOOP

@noindent
Name: @code{LOOP}

@noindent
Stackeffect:  --- (run) addr n --- (compiling)

@noindent
Attributes: ISO,I,C2,L0

@noindent
Description:
Occurs in a colon-definition in form:
    @example
@iftex
@cartouche
DO ... LOOP
@end cartouche
@end iftex
@ifinfo
DO ... LOOP
@end ifinfo
@end example
At run-time, @code{LOOP}
@findex LOOP
 selectively controls branching
back to the corresponding @code{DO}
@findex DO
 based on the loop
index and limit. The loop index is incremented by one and
compared to the limit. The branch back to
@code{DO}
@findex DO
 occurs until the index equals or exceeds the
limit; at that time, the parameters are discarded and execution
continues ahead.

At compile-time, @code{LOOP}
@findex LOOP
 compiles
@code{(LOOP)}
@findex (LOOP)
 and uses @samp{addr} to calculate an
offset to @samp{DO} . @samp{n2} is used for compile
time error checking.

@noindent
See also: @samp{+LOOP}
 
        


@node RECURSE, REPEAT, LOOP, CONTROL
@subsection RECURSE
@pindex RECURSE
@findex RECURSE

@noindent
Name: @code{RECURSE}

@noindent
Stackeffect: (varies)

@noindent
Attributes: ISO

@noindent
Description:
Do a recursive call of the definition being compiled.

@noindent
See also: @samp{:}
 
        


@node REPEAT, SKIP, RECURSE, CONTROL
@subsection REPEAT
@pindex REPEAT
@findex REPEAT

@noindent
Name: @code{REPEAT}

@noindent
Stackeffect: addr1 n1 addr2 n2--- (compiling)

@noindent
Attributes: ISO,FIG,I,C2

@noindent
Description:
Used within a colon-definition in the form:
    @example
@iftex
@cartouche
BEGIN ... WHILE ... REPEAT
@end cartouche
@end iftex
@ifinfo
BEGIN ... WHILE ... REPEAT
@end ifinfo
@end example
At run-time, @code{REPEAT}
@findex REPEAT
 forces an unconditional branch
back to just after the corresponding @code{BEGIN}
@findex BEGIN
 .

At compile-time, @code{REPEAT}
@findex REPEAT
 compiles
@code{BRANCH}
@findex BRANCH
 and the offset from @code{HERE}
@findex HERE
 to
@samp{addr2} . Then it fills in another branch offset at
@samp{addr1} left there by @code{WHILE}
@findex WHILE
 .
@samp{n1 n2} is used for error testing.

@noindent
See also: @samp{WHILE}
 
        


@node SKIP, THEN, REPEAT, CONTROL
@subsection SKIP
@pindex SKIP
@findex SKIP

@noindent
Name: @code{SKIP}

@noindent
No stackeffect

@noindent
Attributes: C2,L0

@noindent
Description:
Skip over an area in memory, where the length is given in the next cell.
This length doesn't include the length cell, so it is compatible with
@code{$@@}
@findex $@@
 .
Internal, used for nested compilation and compiling strings. 

@noindent
See also: @samp{BRANCH}
 
        


@node THEN, UNLOOP, SKIP, CONTROL
@subsection THEN
@pindex THEN
@findex THEN

@noindent
Name: @code{THEN}

@noindent
Stackeffect: addr n --- (compile)

@noindent
Attributes: ISO,FIG,I,CO,L0

@noindent
Description:
Occurs in a colon-definition in form:
 @example
@iftex
@cartouche
IF ... THEN
@end cartouche
@end iftex
@ifinfo
IF ... THEN
@end ifinfo
@end example
 @example
@iftex
@cartouche
IF ... ELSE ... THEN
@end cartouche
@end iftex
@ifinfo
IF ... ELSE ... THEN
@end ifinfo
@end example
At run-time, @code{THEN}
@findex THEN
 serves only as the destination
of a forward branch from @code{IF}
@findex IF
 or @code{ELSE}
@findex ELSE
 .
It marks the conclusion of the conditional structure. At
compile-time, @code{THEN}
@findex THEN
 computes the forward branch
offset from @samp{addr} to @code{HERE}
@findex HERE
 and stores it
at @samp{addr} . @samp{n} is used for error tests.

@noindent
See also: @samp{FORWARD)}
 @samp{IF}
 @samp{ELSE}
 


        


@node UNLOOP, UNTIL, THEN, CONTROL
@subsection UNLOOP
@pindex UNLOOP
@findex UNLOOP

@noindent
Name: @code{UNLOOP}

@noindent
Stackeffect: --- n

@noindent
Attributes: ISO,I,C,L0

@noindent
Description:
Discard the loop parameters. Must be used when the regular end
of the loop is by-passed. That means it is not ended via
@code{LOOP}
@findex LOOP
 @code{+LOOP}
@findex +LOOP
 or @code{LEAVE}
@findex LEAVE
. 

@noindent
See also: @samp{DO}
 @samp{LOOP}
 @samp{+LOOP}
 @samp{(BACK}
 @samp{(FORWARD}
 @samp{EXIT}
 





        


@node UNTIL, WHILE, UNLOOP, CONTROL
@subsection UNTIL
@pindex UNTIL
@findex UNTIL

@noindent
Name: @code{UNTIL}

@noindent
Stackeffect: f --- (run-time) addr n --- (compile)

@noindent
Attributes: ISO,FIG,I,C2,L0

@noindent
Description:
Occurs within a colon-definition in the form:
              @example
@iftex
@cartouche
BEGIN ... UNTIL
@end cartouche
@end iftex
@ifinfo
BEGIN ... UNTIL
@end ifinfo
@end example
At run-time, @code{UNTIL}
@findex UNTIL
 controls the conditional branch
back to the corresponding @code{BEGIN}
@findex BEGIN
 If f is false,
execution returns to just after @code{BEGIN}
@findex BEGIN
 , otherwise
execution continues ahead.

At compile-time, @code{UNTIL}
@findex UNTIL
 compiles
@code{0BRANCH}
@findex 0BRANCH
 and an offset from @code{HERE}
@findex HERE
 to
addr. @samp{n} is used for error tests.

@noindent
See also: @samp{BEGIN}
 
        


@node WHILE, paren_plus_loop, UNTIL, CONTROL
@subsection WHILE
@pindex WHILE
@findex WHILE

@noindent
Name: @code{WHILE}

@noindent
Stackeffect: f --- (run-time) addr1 nl --- addr2 n1 addr1 n2(compile-time)

@noindent
Attributes: ISO,FIG,I,C2

@noindent
Description:
Occurs in a colon-definition in the form:
         @samp{BEGIN ... WHILE (tp) ... REPEAT}
At run-time, @code{WHILE}
@findex WHILE
 selects conditional execution
based on boolean flag @samp{f} . If @samp{f} is true
(non-zero), @code{WHILE}
@findex WHILE
 continues execution of the true
part thru to @code{REPEAT}
@findex REPEAT
 , which then branches back to
@code{BEGIN}
@findex BEGIN
 . If @samp{f} is false (zero),
execution skips to just after @code{REPEAT}
@findex REPEAT
 , exiting the
structure.

At compile time, @code{WHILE}
@findex WHILE
 compiles
@code{0BRANCH}
@findex 0BRANCH
 and tucks the
target address @samp{addr2}
under the @samp{addr1} left there by
@code{BEGIN}
@findex BEGIN
 . The stack values will be resolved by
@code{REPEAT}
@findex REPEAT
 . @samp{n1} and @samp{n2}
provide checks for compiler security.

@noindent
See also: @samp{(FORWARD}
 @samp{BEGIN}
 

        


@node paren_plus_loop, paren_semicolon, WHILE, CONTROL
@subsection (+LOOP)
@pindex (+LOOP)
@findex (+LOOP)

@noindent
Name: @code{(+LOOP)}

@noindent
Stackeffect: n ---

@noindent
Attributes: C2

@noindent
Description:
The run-time proceedure compiled by @code{+LOOP}
@findex +LOOP
, which increments the loop
index by n and tests for loop completion.

@noindent
See also: @samp{+LOOP}
 
        


@node paren_semicolon, paren_question_do, paren_plus_loop, CONTROL
@subsection (;)
@pindex (;)
@findex (;)

@noindent
Name: @code{(;)}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
 This is a synonym for @code{EXIT}
@findex EXIT
. It is the run-time
word compiled at the end of a colon-definition which returns
execution to the calling proceedure. Stop interpretation of the
current definition. The return stack must not be engaged. 

@noindent
See also: @samp{EXIT}
 
        


@node paren_question_do, paren_back, paren_semicolon, CONTROL
@subsection (?DO)
@pindex (?DO)
@findex (?DO)

@noindent
Name: @code{(?DO)}

@noindent
No stackeffect

@noindent
Attributes: C

@noindent
Description:
The run-time proceedure compiled by @code{?DO}
@findex ?DO
 which
prepares the return stack, where the looping bookkeeping is kept.

@noindent
See also: @samp{?DO}
 
        


@node paren_back, paren_do, paren_question_do, CONTROL
@subsection (BACK
@pindex (BACK
@findex (BACK

@noindent
Name: @code{(BACK}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
Start a backward branch by leaving the target address
@code{HERE}
@findex HERE
 into @samp{addr}. Usage is
@samp{(BACK .. POSTPONE BRANCH BACK) } 

@noindent
See also: @samp{BACK)}
 @samp{BEGIN}
 @samp{DO}
 


        


@node paren_do, paren_forward, paren_back, CONTROL
@subsection (DO)
@pindex (DO)
@findex (DO)

@noindent
Name: @code{(DO)}

@noindent
No stackeffect

@noindent
Attributes: C

@noindent
Description:
The run-time proceedure compiled by @code{DO}
@findex DO
 which
prepares the return stack, where the looping bookkeeping is kept.

@noindent
See also: @samp{DO}
 
        


@node paren_forward, paren_loop, paren_do, CONTROL
@subsection (FORWARD
@pindex (FORWARD
@findex (FORWARD

@noindent
Name: @code{(FORWARD}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
Start a forward branch by leaving the address that must be
backpatched with an offset into @samp{addr}.
Usage is
@samp{POSTPONE BRANCH (FORWARD .. FORWARD) } 

@noindent
See also: @samp{IF}
 
        


@node paren_loop, 0BRANCH, paren_forward, CONTROL
@subsection (LOOP)
@pindex (LOOP)
@findex (LOOP)

@noindent
Name: @code{(LOOP)}

@noindent
No stackeffect

@noindent
Attributes: C2

@noindent
Description:
The run-time proceedure compiled by LOOP which increments the loop
index and tests for loop completion.


@noindent
See also: @samp{LOOP}
 
        


@node 0BRANCH, back_paren, paren_loop, CONTROL
@subsection 0BRANCH
@pindex 0BRANCH
@findex 0BRANCH

@noindent
Name: @code{0BRANCH}

@noindent
Stackeffect: f ---

@noindent
Attributes: FIG,C2

@noindent
Description:
The run-time proceedure to conditionally branch. If @samp{f} is false
(zero), the following in-line parameter is added to the interpretive
pointer to branch ahead or back.
Compiled by @code{IF}
@findex IF
 , @code{UNTIL}
@findex UNTIL
 , and @code{WHILE}
@findex WHILE
 .


@noindent
See also: @samp{BRANCH}
 
        


@node back_paren, BRANCH, 0BRANCH, CONTROL
@subsection BACK)
@pindex BACK)
@findex BACK)

@noindent
Name: @code{BACK)}

@noindent
Stackeffect: addr ---

@noindent
Attributes: 

@noindent
Description:
Complete a backward branch by compiling an offset from
@code{HERE}
@findex HERE
 to @samp{addr}, left there by
@code{(BACK}
@findex (BACK
 . Usage is
@samp{(BACK .. POSTPONE BRANCH BACK) } 

@noindent
See also: @samp{LOOP}
 @samp{UNTIL}
 

        


@node BRANCH, forward_paren, back_paren, CONTROL
@subsection BRANCH
@pindex BRANCH
@findex BRANCH

@noindent
Name: @code{BRANCH}

@noindent
No stackeffect

@noindent
Attributes: FIG,C2,L0

@noindent
Description:
The run-time proceedure to unconditionally branch. An in-line
offset is added to the interpretive pointer @code{IP}
@findex IP
 to
branch ahead or back. @code{BRANCH}
@findex BRANCH
 is compiled by
@code{ELSE}
@findex ELSE
 @code{AGAIN}
@findex AGAIN
 @code{REPEAT}
@findex REPEAT
 .

@noindent
See also: @samp{0BRANCH}
 
        


@node forward_paren, , BRANCH, CONTROL
@subsection FORWARD)
@pindex FORWARD)
@findex FORWARD)

@noindent
Name: @code{FORWARD)}

@noindent
Stackeffect: addr ---

@noindent
Attributes: 

@noindent
Description:
Complete a forward branch by backpatching an offset from
@code{HERE}
@findex HERE
 into @samp{addr}, left there by @code{(FORWARD}
@findex (FORWARD
 .
Usage is @samp{POSTPONE
BRANCH (FORWARD .. FORWARD) } 


@noindent
See also: @samp{LOOP}
 @samp{UNTIL}
 

        




@node DEFINING, DENOTATIONS,CONTROL, Glossary
@section DEFINING
     
    The wordset @samp{DEFINING} contains words that add new entries
to the dictionary. A number of such @dfn{defining word}
@cindex defining word
's
are predefined, but there is
also the possibility to make new defining words, using
@code{CREATE}
@findex CREATE
 and @code{DOES>}
@findex DOES>
 .

    

    

@menu


* :  ::
* ;  ::
* CONSTANT  ::
* CREATE  ::
* DOES>  ::
* USER  ::
* VARIABLE  ::
* VOCABULARY  ::
* (;CODE)  :paren_semicolon_code
* (CREATE)  :paren_create
* ;CODE  ::
@end menu
@node :, ;, DEFINING, DEFINING
@subsection :
@pindex :
@findex :

@noindent
Name: @code{:}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,E,L0

@noindent
Description:
Used in the form called a colon-definition:
@example
@iftex
@cartouche
: cccc     ...     ;
@end cartouche
@end iftex
@ifinfo
: cccc     ...     ;
@end ifinfo
@end example
Creates a dictionary entry defining @samp{cccc} as equivalent to the
following sequence of Forth word definitions '...' until the next
@code{';'}
@findex ';'
 or @code{';CODE'}
@findex ';CODE'
. The word is added as the latest
into the @code{CURRENT}
@findex CURRENT
 word list.
The compiling process is done by the text interpreter as long as
@code{STATE}
@findex STATE
 is non-zero.
Words with the immediate bit
set (I) are executed rather than being compiled.

        


@node ;, CONSTANT, :, DEFINING
@subsection ;
@pindex ;
@findex ;

@noindent
Name: @code{;}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,I,C,L0

@noindent
Description:
Terminate a colon-definition and stop further compilation. Compiles
the run-time @code{EXIT}
@findex EXIT
 .

@noindent
See also: @samp{:}
 
        


@node CONSTANT, CREATE, ;, DEFINING
@subsection CONSTANT
@pindex CONSTANT
@findex CONSTANT

@noindent
Name: @code{CONSTANT}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
A defining word used in the form:
    @samp{n} @code{CONSTANT}
@findex CONSTANT
 @samp{cccc}
to create word @samp{cccc} , with its data field containing
@samp{n} . When @samp{cccc} is later executed, it
will push the value of @samp{n} to the stack.

@noindent
See also: @samp{VARIABLE}
 
        


@node CREATE, DOES>, CONSTANT, DEFINING
@subsection CREATE
@pindex CREATE
@findex CREATE

@noindent
Name: @code{CREATE}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
A defining word used in the form:
     @samp{CREATE cccc}
Later execution of @samp{cccc} returns its data field, i.e.
the value of @code{HERE}
@findex HERE
 immediately
after executing @code{CREATE}
@findex CREATE
 .

It can be the base of a new defining word if used in the form:
     @example
@iftex
@cartouche
: CREATOR CREATE aaaa DOES> bbbb ;
CREATOR cccc

@end cartouche
@end iftex
@ifinfo
: CREATOR CREATE aaaa DOES> bbbb ;
CREATOR cccc

@end ifinfo
@end example
The second line has the effect of creating a word @samp{cccc} .
Its datastructure is build
by the code @samp{aaaa} and when executing @samp{cccc} , its data field is pushed
on the stack, then the code @samp{bbbb} is executed.

Space in this data field has yet to
be allocated and the execution action can be changed.
ciforth is byte aligned, so no extra measures are needed.

@noindent
See also: @samp{DOES>}
 @samp{;CODE}
 @samp{ALLOT}
 @samp{,}
 @samp{C,}
 




        


@node DOES>, USER, CREATE, DEFINING
@subsection DOES>
@pindex DOES>
@findex DOES>

@noindent
Name: @code{DOES>}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
A word which is normally use to specify the run-time action
within a high-level defining word. @code{DOES>}
@findex DOES>
 modifies
the behaviour of the latest word as to execute the sequence of
compiled word addresses following @code{DOES>}
@findex DOES>
 . Used in
combination with @code{CREATE}
@findex CREATE
 . When the
@code{DOES>}
@findex DOES>
 part executes it begins with the address of
the data field of the word on the stack. This allows
interpretation using this area or its contents. 
Typical uses include the Forth assembler, multidimensional
arrays, and compiler generation.


        


@node USER, VARIABLE, DOES>, DEFINING
@subsection USER
@pindex USER
@findex USER

@noindent
Name: @code{USER}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,L0

@noindent
Description:
A defining word used in the form:
               @samp{n USER cccc}
which creates a user variable @samp{cccc} . The data
field of @samp{cccc} contains @samp{n} as a fixed
offset relative to the user pointer register @samp{UP}
for this user variable. When @samp{cccc} is later
executed, it places the sum of its offset and the user area
base address on the stack as the storage address of that
particular variable. In ciforth the @samp{UP} is fixed.


@noindent
See also: @samp{VARIABLE}
 @samp{+ORIGIN}
 @samp{CONTEXT}
 @samp{>DFA}
 



        


@node VARIABLE, VOCABULARY, USER, DEFINING
@subsection VARIABLE
@pindex VARIABLE
@findex VARIABLE

@noindent
Name: @code{VARIABLE}

@noindent
No stackeffect

@noindent
Attributes: ISO,E,LU

@noindent
Description:
A defining word used in the form:
                 @samp{VARIABLE cccc}
When @code{VARIABLE}
@findex VARIABLE
 is executed, it creates the definition @samp{cccc} with its
data field pointing to a data location.
When @samp{cccc} is later executed, the
content of its data field (containing @samp{n} ) is left on the stack,
so that a fetch or store may access this location.

@noindent
See also: @samp{USER}
 @samp{CONSTANT}
 

        


@node VOCABULARY, paren_semicolon_code, VARIABLE, DEFINING
@subsection VOCABULARY
@pindex VOCABULARY
@findex VOCABULARY

@noindent
Name: @code{VOCABULARY}

@noindent
No stackeffect

@noindent
Attributes: FIG,E,L

@noindent
Description:
A defining word used in the form:
@code{VOCABULARY}
@findex VOCABULARY
 @samp{cccc} to create a
vocabulary definition @samp{cccc} . It will create a
@dfn{word list}
@cindex word list
in the ISO sense. Subsequent use of
@samp{cccc} will push this word list (the
@dfn{word list associated with}
@cindex word list associated with
 @samp{cccc}) to the top of
the search order in @code{CONTEXT}
@findex CONTEXT
. So it will
searched first by @code{INTERPRET}
@findex INTERPRET
 .

A vocabulary 's data content field contains at first the dovoc
pointer (like for any @code{DOES>}
@findex DOES>
 word) , then follows
its body. The body contains the vocabulary link
field address ( @dfn{VLFA}
@cindex VLFA
 ). The VLFA points to the VLFA
of the next vocabulary or  a @dfn{nil pointer}
@cindex nil pointer
 for the end.
Then follows a dummy dea that serves
as @dfn{word list identifier}
@cindex word list identifier
 or @dfn{WID}
@cindex WID
 in the sense of the ISO standard.
It has
empty fields, except for the link field.
The @dfn{link field address}
@cindex link field address
 contains the DEA of the latest word of
the vocabulary or a @dfn{nil pointer} if empty. Executing the
vocabulary means pushing its WID on top of the
@code{CONTEXT}
@findex CONTEXT
 order. In ciforth when there can be
at most 16 word list 's in the search order, the
oldest one gets lost. The vocabularies generated are
@code{IMMEDIATE}
@findex IMMEDIATE
 words.

@noindent
See also: @samp{VOC-LINK}
 @samp{DEFINITIONS}
 

        


@node paren_semicolon_code, paren_create, VOCABULARY, DEFINING
@subsection (;CODE)
@pindex (;CODE)
@findex (;CODE)

@noindent
Name: @code{(;CODE)}

@noindent
No stackeffect

@noindent
Attributes: C

@noindent
Description:
The run-time proceedure, compiled by @code{;CODE}
@findex ;CODE
, that rewrites the code
field of the most recently defined word to point to the following
machine code sequence. It is used after @code{CREATE}
@findex CREATE
 instead of @code{DOES>}
@findex DOES>
 if the code following
is assembler code instead of high level code.


@noindent
See also: @samp{ (CREATE)}
 @samp{;CODE}
 

        


@node paren_create, ;CODE, paren_semicolon_code, DEFINING
@subsection (CREATE)
@pindex (CREATE)
@findex (CREATE)

@noindent
Name: @code{(CREATE)}

@noindent
Stackeffect: sc ---

@noindent
Attributes: 

@noindent
Description:
This is the basis for all defining words. It lays down the
string @samp{sc} in the dictionary, then creates a
dictionary entries with that string as the namefield. It is
linked into the @code{CURRENT}
@findex CURRENT
 word list. The code field
and data field both point to the area owned by this header,
i.e. immediately following the completed header as
appropriate for a low level (assembler) definition. The
flag field is empty , so not @code{HIDDEN}
@findex HIDDEN
. 

@noindent
See also: @samp{CREATE}
 
        


@node ;CODE, , paren_create, DEFINING
@subsection ;CODE
@pindex ;CODE
@findex ;CODE

@noindent
Name: @code{;CODE}

@noindent
No stackeffect

@noindent
Attributes: B,ISO,FIG,I,C,L0

@noindent
Description:
Used in the form:
  @samp{: cccc CREATE .... ;CODE assembly mnemonics }
Stop compilation and terminate a new defining word
@samp{cccc} by compiling @code{(;CODE)}
@findex (;CODE)
. Set
@code{ASSEMBLER}
@findex ASSEMBLER
 to the top of the
@dfn{search order}
@cindex search order
 order. Start assembling to machine
code the following mnemonics.

When @samp{cccc} later executes in the form:
                     @samp{cccc nnnn}
the word @samp{nnnn} will be created with its execution proceedure given by
the machine code following @samp{cccc} .
That is, when @samp{nnnn} is executed, it does so by
jumping to the code after @samp{nnnn} .
Because of intimate relation to the
assembler, it is present in loadable form in the screens file
@file{forth.lab} .

@noindent
See also: @samp{(;CODE)}
 @samp{LOAD}
 @samp{:}
 


        




@node DENOTATIONS, DICTIONARY,DEFINING, Glossary
@section DENOTATIONS
     
    The wordset @samp{DENOTATIONS} contains prefixes (mostly one letter
words) that introduce a @dfn{denotation}
@cindex denotation
, i.e. a generalisation of
@code{NUMBER}
@findex NUMBER
 .
Any word starting with the prefix is considered found in the
dictionary and the prefix word executed.
These words parse input and leave a constant
(number, char or string) on the stack, or compile such constant,
depending on @code{STATE}
@findex STATE
.
For a kernel system it is guaranteed that they reside in the minimum search
order wordset, called @code{ONLY}
@findex ONLY
.
To make a distinction with the same words in other wordlists,
the names of denotations are prepended with ``Prefix_'' in the
documentation. Actual names in the dictionary do not contain
the prefix. Apart from @code{Prefix_0}
@findex Prefix_0
 , the vocabulary
contains entries for all hex digits 1...9 and A...F.
Like @code{NUMBER}
@findex NUMBER
 always did, all denotations behave
identical in interpret and compile mode and they are not supposed to be
postponed. 
    

    

@menu


* Prefix_"  :den_quote
* Prefix_&  ::
* Prefix_+  ::
* Prefix_-  ::
* Prefix_0  :den_zero
* Prefix_7  :den_seven
* Prefix_B  :den_b
* Prefix_^  ::
* Prefix__TICK  :tick_denotation
@end menu
@node den_quote, Prefix_&, DENOTATIONS, DENOTATIONS
@subsection Prefix_"
@pindex Prefix_"
@findex Prefix_"

@noindent
Name: @code{Prefix_"}

@noindent
Stackeffect: --- sc

@noindent
Attributes: CI

@noindent
Description:
Parse a @kbd{"} delimited string and leave it on the stack.
A @kbd{"} can be embedded in a string by doubling it.
This is a denotation: during compilation this behaviour is compiled.


        


@node Prefix_&, Prefix_+, den_quote, DENOTATIONS
@subsection Prefix_&
@pindex Prefix_&
@findex Prefix_&

@noindent
Name: @code{Prefix_&}

@noindent
Stackeffect: --- c

@noindent
Attributes: CI

@noindent
Description:
Leave @samp{c} the non blank char that follows.
Skip another blank character.
This is a denotation: during compilation this behaviour is compiled.


@noindent
See also: @samp{^}
 
        


@node Prefix_+, Prefix_-, Prefix_&, DENOTATIONS
@subsection Prefix_+
@pindex Prefix_+
@findex Prefix_+

@noindent
Name: @code{Prefix_+}

@noindent
Stackeffect: --- s/d

@noindent
Attributes: CI

@noindent
Description:
Implements @code{NUMBER}
@findex NUMBER
 for numbers that start with @kbd{+} .

        


@node Prefix_-, den_zero, Prefix_+, DENOTATIONS
@subsection Prefix_-
@pindex Prefix_-
@findex Prefix_-

@noindent
Name: @code{Prefix_-}

@noindent
Stackeffect: --- s/d

@noindent
Attributes: CI

@noindent
Description:
Implements @code{NUMBER}
@findex NUMBER
 for numbers that start with @kbd{-} .

        


@node den_zero, den_seven, Prefix_-, DENOTATIONS
@subsection Prefix_0
@pindex Prefix_0
@findex Prefix_0

@noindent
Name: @code{Prefix_0}

@noindent
Stackeffect: --- s/d

@noindent
Attributes: CI

@noindent
Description:
Implements @code{NUMBER}
@findex NUMBER
 for numbers that start with
@kbd{0} . Similar words are present for all decimal and hex digits.
 ISO compatibility ony requires that denotators for
decimal digits are present,
one can always use a leading zero.


@noindent
See also: @samp{B}
 @samp{7}
 

        


@node den_seven, den_b, den_zero, DENOTATIONS
@subsection Prefix_7
@pindex Prefix_7
@findex Prefix_7

@noindent
Name: @code{Prefix_7}

@noindent
Stackeffect: --- s/d

@noindent
Attributes: CI

@noindent
Description:
Implements @code{NUMBER}
@findex NUMBER
 for numbers that start with
@kbd{7} . Similar words are present for all decimal and hex digits.


@noindent
See also: @samp{0}
 @samp{B}
 

        


@node den_b, Prefix_^, den_seven, DENOTATIONS
@subsection Prefix_B
@pindex Prefix_B
@findex Prefix_B

@noindent
Name: @code{Prefix_B}

@noindent
Stackeffect: --- s/d

@noindent
Attributes: CI

@noindent
Description:
Implements @code{NUMBER}
@findex NUMBER
 for numbers that start with
@kbd{B} . Similar words are present for all decimal and hex digits.


@noindent
See also: @samp{0}
 @samp{7}
 

        


@node Prefix_^, tick_denotation, den_b, DENOTATIONS
@subsection Prefix_^
@pindex Prefix_^
@findex Prefix_^

@noindent
Name: @code{Prefix_^}

@noindent
Stackeffect: --- b

@noindent
Attributes: CI

@noindent
Description:
Leave @samp{b} the control character value of the char that follows
i.e. @samp{^A} results in 1 and so on.
Skip another blank character.
This is a denotation: during compilation this behaviour is compiled.


@noindent
See also: @samp{&}
 
        


@node tick_denotation, , Prefix_^, DENOTATIONS
@subsection Prefix__TICK
@pindex Prefix__TICK
@findex Prefix__TICK

@noindent
Name: @code{Prefix__TICK}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO,FIG,I,L0

@noindent
Description:
Used in the form: @example
@iftex
@cartouche
'nnnn
@end cartouche
@end iftex
@ifinfo
'nnnn
@end ifinfo
@end example
In interpret mode it
leaves the @dfn{execution token}
@cindex execution token
 (equivalent to the
dictionary entry address) of dictionary word @samp{nnnn}.
If the word is not found after a search of the search order
an appropriate error message is given.
In ciforth it can be used in compilation mode too, it
then compiles the address as a literal.
It is recommended that
one never compiles or postpones it.
(Use a
combination of @code{WORD}
@findex WORD
 and @code{FIND}
@findex FIND
 or
any form of explicit parsing and searching 
instead.)
Furthermore it is recommended
that for non-portable code @code{'}
@findex '
 is used in its
@dfn{denotation}
@cindex denotation
 form without the space.
 Note that if you separate @code{'}
@findex '
 by a space,
the ISO-conforming version of
 @code{'}
@findex '
 is found.


@noindent
See also: @samp{CONTEXT}
 @samp{[']}
 @samp{PRESENT}
 @samp{>CFA}
 @samp{>DFA}
 @samp{>FFA}
 @samp{>LFA}
 @samp{>NFA}
 @samp{>SFA}
 








        




@node DICTIONARY, DOUBLE,DENOTATIONS, Glossary
@section DICTIONARY
     
    The wordset @samp{DICTIONARY} contains words that at a
lower level than the wordset @samp{DEFINING} concern the
memory area that is allocated to the dictionary. They may add
data to the dictionary at the expense of the free space, one
cell or one byte at a time, or allocate a buffer at once. The
dictionary space may also be shrunk, and the words that were
there are lost. The @dfn{dictionary entry address}
@cindex dictionary entry address
 or
@dfn{DEA}
@cindex DEA
 represents a word. It is the lowest address of
a record with fields. Words to access those fields also belong
to this wordset.
    

    

@menu


* '  :tick_iso
* ,  :comma
* >BODY  ::
* ALLOT  ::
* BODY>  ::
* C,  :c_comma
* DP  ::
* FIND  ::
* FORGET  ::
* FOUND  ::
* HERE  ::
* ID.  ::
* IMMEDIATE  ::
* PAD  ::
* PREFIX  ::
* PRESENT  ::
* WORDS  ::
* [']  :bracket_tick_bracket
* (FIND)  :paren_find
* >CFA  ::
* >DFA  ::
* >FFA  ::
* >LFA  ::
* >NFA  ::
* >PHA  ::
* >SFA  ::
* >VFA  ::
* >WID  ::
* >XFA  ::
* CFA>  ::
* FENCE  ::
* FOR-VOCS  ::
* FOR-WORDS  ::
* FORGET-VOC  ::
* HIDDEN  ::
* OPT  :optimiser
* ~MATCH  :unmatch
@end menu
@node tick_iso, comma, DICTIONARY, DICTIONARY
@subsection ' (This addition because texinfo won't accept a single quote) 
@pindex '
@findex '

@noindent
Name: @code{'}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO,FIG,I,L0

@noindent
Description:
Used in the form: @example
@iftex
@cartouche
' nnnn 
@end cartouche
@end iftex
@ifinfo
' nnnn 
@end ifinfo
@end example
It leaves the @dfn{execution token}
@cindex execution token
 (equivalent to the
dictionary entry address) of dictionary word @samp{nnnn}.
If the word is not found after a search of
the search order an appropriate error message is
given.
If compiled the searching is done while
the word being compiled is executed.
Because this is so confusing,
it is recommended that
one never compiles or postpones @code{'}
@findex '
.
(Use a
combination of @code{WORD}
@findex WORD
 and @code{FIND}
@findex FIND
 or
any form of explicit parsing and searching 
instead.)
Furthermore it is recommended that
for non-portable code @code{'}
@findex '
 is used in its
@dfn{denotation}
@cindex denotation
 form without the space.


@noindent
See also: @samp{[']}
 @samp{FOUND}
 @samp{>CFA}
 @samp{>DFA}
 @samp{>FFA}
 @samp{>LFA}
 @samp{>NFA}
 @samp{>SFA}
 @samp{>XFA}
 








        


@node comma, >BODY, tick_iso, DICTIONARY
@subsection ,
@pindex ,
@findex ,

@noindent
Name: @code{,}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Store @samp{n} into the next available dictionary memory cell, advancing
the @dfn{dictionary pointer}
@cindex dictionary pointer
.

@noindent
See also: @samp{DP}
 @samp{C,}
 

        


@node >BODY, ALLOT, comma, DICTIONARY
@subsection >BODY
@pindex >BODY
@findex >BODY

@noindent
Name: @code{>BODY}

@noindent
Stackeffect: dea --- addr

@noindent
Attributes: ISO

@noindent
Description:
Given the @dfn{dictionary entry address}
@cindex dictionary entry address
 @samp{dea} of a
definition created with a @code{CREATE}
@findex CREATE
 /
@code{DOES>}
@findex DOES>
 construct, return its @dfn{data}
@cindex data
 field (in the ISO sense)
@samp{addr}.

@noindent
See also: @samp{'}
 @samp{>CFA}
 @samp{>DFA}
 @samp{>PHA}
 @samp{BODY>}
 




        


@node ALLOT, BODY>, >BODY, DICTIONARY
@subsection ALLOT
@pindex ALLOT
@findex ALLOT

@noindent
Name: @code{ALLOT}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Add the signed number to the @dfn{dictionary pointer}
@cindex dictionary pointer
 @code{DP}
@findex DP
 . May be used to
reserve dictionary space or re-origin memory. As the Pentium is a byte-addressable
machine @samp{n} counts bytes. 

@noindent
See also: @samp{CELL+}
 
        


@node BODY>, c_comma, ALLOT, DICTIONARY
@subsection BODY>
@pindex BODY>
@findex BODY>

@noindent
Name: @code{BODY>}

@noindent
Stackeffect: addr --- dea

@noindent
Attributes: 

@noindent
Description:
Convert the data field @samp{addr} of a definition
created
with a @code{CREATE}
@findex CREATE
 / @code{DOES>}
@findex DOES>
 construct to
its @samp{dea}. Where @code{>BODY}
@findex >BODY
 keeps working
after @dfn{revectoring}
@cindex revectoring
 , @code{BODY>}
@findex BODY>
 does not.
 There is some logic to this, because the
@dfn{DEA}
@cindex DEA
 to which the body belongs is no longer
unique.


@noindent
See also: @samp{'}
 @samp{>BODY}
 

        


@node c_comma, DP, BODY>, DICTIONARY
@subsection C,
@pindex C,
@findex C,

@noindent
Name: @code{C,}

@noindent
Stackeffect: b ---

@noindent
Attributes: ISO,FIG

@noindent
Description:
Store 8 bits of @samp{b} into the next available dictionary byte, advancing
the @dfn{dictionary pointer}
@cindex dictionary pointer
. 

@noindent
See also: @samp{DP}
 @samp{,}
 

        


@node DP, FIND, c_comma, DICTIONARY
@subsection DP
@pindex DP
@findex DP

@noindent
Name: @code{DP}

@noindent
Stackeffect: ---- addr

@noindent
Attributes: FIG,U,L

@noindent
Description:
A user variable, the @dfn{dictionary pointer}
@cindex dictionary pointer
, which contains the address
of the next free memory above the dictionary. The value may be read
by @code{HERE}
@findex HERE
 and altered by @code{ALLOT}
@findex ALLOT
 .

        


@node FIND, FORGET, DP, DICTIONARY
@subsection FIND
@pindex FIND
@findex FIND

@noindent
Name: @code{FIND}

@noindent
Stackeffect: addr ---xt 1/xt -1/addr 0

@noindent
Attributes: ISO

@noindent
Description:
For the @dfn{old fashioned string}
@cindex old fashioned string
 (stored with a
preceding character count) at @samp{addr} find a Forth
word in the current search order.
Return its
execution token @samp{xt}. If the word is immediate, also
return 1, otherwise also return -1. If it is not found, leave
the original @samp{addr} and a zero. 

@noindent
See also: @samp{CONTEXT}
 @samp{PRESENT}
 @samp{(FIND)}
 


        


@node FORGET, FOUND, FIND, DICTIONARY
@subsection FORGET
@pindex FORGET
@findex FORGET

@noindent
Name: @code{FORGET}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,E,L0

@noindent
Description:
Executed in the form:
               @code{FORGET}
@findex FORGET
 @samp{cccc}
Deletes definition named @samp{cccc} from the dictionary
with all entries physically following it. Recover the space
that was in use.

@noindent
See also: @samp{FENCE}
 @samp{FORGET-VOC}
 

        


@node FOUND, HERE, FORGET, DICTIONARY
@subsection FOUND
@pindex FOUND
@findex FOUND

@noindent
Name: @code{FOUND}

@noindent
Stackeffect: sc --- dea

@noindent
Attributes: 

@noindent
Description:
 Look up the string @samp{sc} in the dictionary observing
the current search order. If found, leave the dictionary
entry address @samp{dea} of the first entry found, else
leave a @dfn{nil pointer}. If the first part of the string
matches a @dfn{denotation}
@cindex denotation
 word, that word is found, whether
the denotation is correct or not.


@noindent
See also: @samp{PRESENT}
 @samp{CONTEXT}
 @samp{FIND}
 @samp{(FIND)}
 @samp{VOCABULARY}
 




        


@node HERE, ID., FOUND, DICTIONARY
@subsection HERE
@pindex HERE
@findex HERE

@noindent
Name: @code{HERE}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the address @samp{addr} of the next available
dictionary location.

@noindent
See also: @samp{DP}
 
        


@node ID., IMMEDIATE, HERE, DICTIONARY
@subsection ID.
@pindex ID.
@findex ID.

@noindent
Name: @code{ID.}

@noindent
Stackeffect: dea ---

@noindent
Attributes: 

@noindent
Description:
Print a definition's name from its dictionary entry address.
For dummy entries print nothing. 

@noindent
See also: @samp{'}
 @samp{>FFA}
 @samp{>NFA}
 


        


@node IMMEDIATE, PAD, ID., DICTIONARY
@subsection IMMEDIATE
@pindex IMMEDIATE
@findex IMMEDIATE

@noindent
Name: @code{IMMEDIATE}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
Mark the most recently made definition so that when encountered at
compile time, it will be executed rather than being compiled, i.e.
the immediate bit in its header is set.
This method allows definitions to handle unusual compiling
situations, rather than build them into the fundamental compiler.
The user may force compilation of an immediate definition by
preceding it with @code{POSTPONE}
@findex POSTPONE
 .

        


@node PAD, PREFIX, IMMEDIATE, DICTIONARY
@subsection PAD
@pindex PAD
@findex PAD

@noindent
Name: @code{PAD}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the address of the text output buffer, which is a fixed offset
above @code{HERE}
@findex HERE
. The area growing downword from @code{PAD}
@findex PAD
 is used
for numeric conversion.


        


@node PREFIX, PRESENT, PAD, DICTIONARY
@subsection PREFIX
@pindex PREFIX
@findex PREFIX

@noindent
Name: @code{PREFIX}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
Mark the most recently made definition a @dfn{prefix}
@cindex prefix
.
If searching the wordlists for a name that starts with the prefix,
the prefix is a match for that name.
This method allows to define numbers, and other
@dfn{denotations}
@cindex denotations
 such as strings, in a modular and extensible
fashion.
A prefix word finds the interpreter pointer pointing to
the remainder of the name (or number) sought for, and must compile
that remainder.
Prefix words are most mostly both immediate and @dfn{smart}
@cindex smart
,
i.e. they behave differently when compiled, than interpreted.
The result is that the compiled code looks the same and behaves the
same than the interpreted code.
 It is recommended that the only smart words present are
 prefix words. 

@noindent
See also: @samp{IMMEDIATE}
 
        


@node PRESENT, WORDS, PREFIX, DICTIONARY
@subsection PRESENT
@pindex PRESENT
@findex PRESENT

@noindent
Name: @code{PRESENT}

@noindent
Stackeffect: sc --- dea

@noindent
Attributes: 

@noindent
Description:
 If the string @samp{sc} is present as a word name in the
current search order, return its @samp{dea}, else leave a
@dfn{nil pointer}
@cindex nil pointer
. For a a @dfn{denotation}
@cindex denotation
 word, the
name must match @samp{sc} exactly.

@noindent
See also: @samp{FOUND}
 @samp{CONTEXT}
 @samp{FIND}
 @samp{(FIND)}
 @samp{VOCABULARY}
 




        


@node WORDS, bracket_tick_bracket, PRESENT, DICTIONARY
@subsection WORDS
@pindex WORDS
@findex WORDS

@noindent
Name: @code{WORDS}

@noindent
No stackeffect

@noindent
Attributes: ISO

@noindent
Description:
List the names of the definitions in the topmost word list of the
search order.


@noindent
See also: @samp{CONTEXT}
 
        


@node bracket_tick_bracket, paren_find, WORDS, DICTIONARY
@subsection [']
@pindex [']
@findex [']

@noindent
Name: @code{[']}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO,I

@noindent
Description:
Used in the form:
@example
@iftex
@cartouche
['] nnnn
@end cartouche
@end iftex
@ifinfo
['] nnnn
@end ifinfo
@end example
In compilation mode it leaves the
@dfn{execution token}
@cindex execution token
 (equivalent to the dictionary
entry address) of dictionary word @samp{nnnn}. So as a
compiler directive it compiles the address as a literal. If the
word is not found after a search of the search order
an appropriate error message is
given.
It is recommended that
where you can't use a @dfn{denotation}
@cindex denotation

 

@noindent
See also: @samp{FOUND}
 @samp{'}
 @samp{EXECUTE }
 


        


@node paren_find, >CFA, bracket_tick_bracket, DICTIONARY
@subsection (FIND)
@pindex (FIND)
@findex (FIND)

@noindent
Name: @code{(FIND)}

@noindent
Stackeffect: sc wid --- sc dea

@noindent
Attributes: 

@noindent
Description:
Search down from the @dfn{WID}
@cindex WID
 @samp{wid} for a
word with name @samp{sc}.
A @dfn{WID}
@cindex WID
 is
mostly a dummy @dfn{DEA}
@cindex DEA
 found in the
data field of a
vocabulary, fetched from @code{CURRENT}
@findex CURRENT
 or an other wid in the
@dfn{search order}
@cindex search order
 . Leave the dictionary entry address
@samp{dea} of the first entry found, else leave a zero.
Do not consume the string @samp{sc},
as this is a repetitive action. 

@noindent
See also: @samp{~MATCH}
 @samp{FIND}
 @samp{PRESENT}
 @samp{>WID}
 



        


@node >CFA, >DFA, paren_find, DICTIONARY
@subsection >CFA
@pindex >CFA
@findex >CFA

@noindent
Name: @code{>CFA}

@noindent
Stackeffect: dea --- addr

@noindent
Attributes: 

@noindent
Description:
Given a dictionary entry addres @samp{dea} return its
@dfn{code field address}
@cindex code field address
 @samp{addr}. By jumping
indirectly via this address the definition @samp{dea} is
executed. This is the address that is compiled within high
level definitions, so it serves as an execution token.
In ciforth it has offset 0, so it is actually the
same as the @dfn{DEA}
@cindex DEA
.

@noindent
See also: @samp{'}
 @samp{CFA>}
 @samp{>DFA}
 @samp{>FFA}
 @samp{>LFA}
 @samp{>NFA}
 @samp{>SFA}
 @samp{>PHA}
 







        


@node >DFA, >FFA, >CFA, DICTIONARY
@subsection >DFA
@pindex >DFA
@findex >DFA

@noindent
Name: @code{>DFA}

@noindent
Stackeffect: dea --- addr

@noindent
Attributes: 

@noindent
Description:
Given a dictionary entry addres return
its @dfn{data field address}
@cindex data field address
 @samp{addr} . This points to the code for a
code word, to the high level code for a colon-definition, and
to the @code{DOES>}
@findex DOES>
 pointer for a word build using
@code{CREATE}
@findex CREATE
. Normally this is the area behind the
header, found via @code{>PHA}
@findex >PHA
 . 

@noindent
See also: @samp{'}
 @samp{>BODY}
 @samp{>CFA}
 @samp{>FFA}
 @samp{>LFA}
 @samp{>NFA}
 @samp{>SFA}
 @samp{>PHA}
 







        


@node >FFA, >LFA, >DFA, DICTIONARY
@subsection >FFA
@pindex >FFA
@findex >FFA

@noindent
Name: @code{>FFA}

@noindent
Stackeffect: dea --- addr

@noindent
Attributes: 

@noindent
Description:
Given a dictionary entry addres return its
@dfn{flag field address}
@cindex flag field address
 @samp{addr} .

@noindent
See also: @samp{'}
 @samp{>CFA}
 @samp{>DFA}
 @samp{>LFA}
 @samp{>NFA}
 




        


@node >LFA, >NFA, >FFA, DICTIONARY
@subsection >LFA
@pindex >LFA
@findex >LFA

@noindent
Name: @code{>LFA}

@noindent
Stackeffect: dea --- addr

@noindent
Attributes: 

@noindent
Description:
Given a dictionary entry addres return its
@dfn{link field address}
@cindex link field address
 @samp{addr}. It contains
the DEA of the previous word. 

@noindent
See also: @samp{'}
 @samp{>CFA}
 @samp{>DFA}
 @samp{>FFA}
 @samp{>NFA}
 @samp{>PHA}
 @samp{>SFA}
 






        


@node >NFA, >PHA, >LFA, DICTIONARY
@subsection >NFA
@pindex >NFA
@findex >NFA

@noindent
Name: @code{>NFA}

@noindent
Stackeffect: dea --- nfa

@noindent
Attributes: 

@noindent
Description:
Given a dictionary entry addres return the
 @dfn{name field address}
@cindex name field address
.

@noindent
See also: @samp{'}
 @samp{>CFA}
 @samp{>DFA}
 @samp{>FFA}
 @samp{>LFA}
 @samp{>SFA}
 





        


@node >PHA, >SFA, >NFA, DICTIONARY
@subsection >PHA
@pindex >PHA
@findex >PHA

@noindent
Name: @code{>PHA}

@noindent
Stackeffect: dea --- addr

@noindent
Attributes: 

@noindent
Description:
Given a dictionary entry addres return the
@dfn{past header address}
@cindex past header address
. Here starts the area that no
longer belongs to the header of a dictionary entry, but most
often it is owned by it. 

@noindent
See also: @samp{'}
 @samp{>CFA}
 @samp{>BODY}
 


        


@node >SFA, >VFA, >PHA, DICTIONARY
@subsection >SFA
@pindex >SFA
@findex >SFA

@noindent
Name: @code{>SFA}

@noindent
Stackeffect: dea --- addr

@noindent
Attributes: 

@noindent
Description:
Given a dictionary entry addres return the
 @dfn{source field address}
@cindex source field address
 @samp{addr} .

@noindent
See also: @samp{'}
 @samp{>CFA}
 @samp{>DFA}
 @samp{>FFA}
 @samp{>LFA}
 @samp{>NFA}
 





        


@node >VFA, >WID, >SFA, DICTIONARY
@subsection >VFA
@pindex >VFA
@findex >VFA

@noindent
Name: @code{>VFA}

@noindent
Stackeffect: dea --- cfa

@noindent
Attributes: 

@noindent
Description:
Given the dictionary entry addres of a vocabulary
return the address of the link to the next vocabulary.


@noindent
See also: @samp{VOCABULARY}
 @samp{>CFA}
 @samp{>WID}
 


        


@node >WID, >XFA, >VFA, DICTIONARY
@subsection >WID
@pindex >WID
@findex >WID

@noindent
Name: @code{>WID}

@noindent
Stackeffect: dea --- wid

@noindent
Attributes: 

@noindent
Description:
Given the dictionary entry addres @samp{dea} of a
vocabulary return its
@dfn{WID}
@cindex WID
 @samp{wid}, a dummy DEA that serves as the start of a
dictionary search. 

@noindent
See also: @samp{VOCABULARY}
 @samp{>CFA}
 @samp{(FIND)}
 


        


@node >XFA, CFA>, >WID, DICTIONARY
@subsection >XFA
@pindex >XFA
@findex >XFA

@noindent
Name: @code{>XFA}

@noindent
Stackeffect: dea --- addr

@noindent
Attributes: 

@noindent
Description:
Given a dictionary entry addres return the
 @dfn{extra field address}
@cindex extra field address
 @samp{addr} .

@noindent
See also: @samp{'}
 @samp{>CFA}
 @samp{>DFA}
 @samp{>FFA}
 @samp{>LFA}
 @samp{>NFA}
 





        


@node CFA>, FENCE, >XFA, DICTIONARY
@subsection CFA>
@pindex CFA>
@findex CFA>

@noindent
Name: @code{CFA>}

@noindent
Stackeffect: cfa --- dea

@noindent
Attributes: 

@noindent
Description:
Convert the code field address of a definition to its
@dfn{dictionary entry address}
@cindex dictionary entry address
 @samp{dea}.

@noindent
See also: @samp{'}
 @samp{>CFA}
 

        


@node FENCE, FOR-VOCS, CFA>, DICTIONARY
@subsection FENCE
@pindex FENCE
@findex FENCE

@noindent
Name: @code{FENCE}

@noindent
Stackeffect: ---  addr

@noindent
Attributes: FIG,U

@noindent
Description:
A user variable containing an address below which @code{FORGET}
@findex FORGET
 ting is
trapped. To forget below this point the user must alter the contents
of @code{FENCE}
@findex FENCE
 .

        


@node FOR-VOCS, FOR-WORDS, FENCE, DICTIONARY
@subsection FOR-VOCS
@pindex FOR-VOCS
@findex FOR-VOCS

@noindent
Name: @code{FOR-VOCS}

@noindent
Stackeffect: x1..xn xt --- x1...xn

@noindent
Attributes: 

@noindent
Description:
For all vocabularies execute @samp{xt}
 with as data the @dfn{DEA}
@cindex DEA
 of those words. @samp{xt}
must have the stack diagram @samp{x1..xn dea --- x1..xn}


@noindent
See also: @samp{FOR-WORDS}
 @samp{EXECUTE}
 

        


@node FOR-WORDS, FORGET-VOC, FOR-VOCS, DICTIONARY
@subsection FOR-WORDS
@pindex FOR-WORDS
@findex FOR-WORDS

@noindent
Name: @code{FOR-WORDS}

@noindent
Stackeffect: x1...xn xt wid --x1...xn

@noindent
Attributes: 

@noindent
Description:
For all words from a word list identified by
@samp{wid}
execute @samp{xt}
 with as data @samp{x1..xn} plus
the @dfn{DEA}
@cindex DEA
 of those words.         @samp{xt}
must have the stack diagram @samp{x1..xn dea --- x1..xn}.
Note that you can use the DEA of any word as a WID
and the remainder of the word list will be searched.


@noindent
See also: @samp{FOR-VOCS}
 @samp{EXECUTE}
 

        


@node FORGET-VOC, HIDDEN, FOR-WORDS, DICTIONARY
@subsection FORGET-VOC
@pindex FORGET-VOC
@findex FORGET-VOC

@noindent
Name: @code{FORGET-VOC}

@noindent
Stackeffect: addr wid --
addr 

@noindent
Attributes: 

@noindent
Description:
Remove all words whose DEA is greater (later defined) than
@samp{addr} from a wordlist given by
@samp{wid} .
This works too if links have been redirected, such that some earlier
words point back to later defined words.
Leave @samp{addr} (as
@code{FORGET-VOC}
@findex FORGET-VOC
 is intended to be used with
@code{FOR-VOCS}
@findex FOR-VOCS
) . If any whole vocabulary is removed,
the search order is reset to @samp{ONLY FORTH}. The space
freed is not recovered.

@noindent
See also: @samp{FORGET}
 
        


@node HIDDEN, optimiser, FORGET-VOC, DICTIONARY
@subsection HIDDEN
@pindex HIDDEN
@findex HIDDEN

@noindent
Name: @code{HIDDEN}

@noindent
Stackeffect: dea ---

@noindent
Attributes: 

@noindent
Description:
Make the word with dictionary entry address @samp{dea}
unfindable, by toggling the "smudge bit" in a definitions' flag
field. If however it was the @samp{dea} of an unfindable
word, it is made findable again.
Used
during the definition of a colon word to prevents an
uncompleted definition from being found during dictionary
searches, until compiling is completed without error. It also
prevents that a word can be used recursively.


@noindent
See also: @samp{IMMEDIATE}
 @samp{RECURSE}
 

        


@node optimiser, unmatch, HIDDEN, DICTIONARY
@subsection OPT
@pindex OPT
@findex OPT

@noindent
Name: @code{OPT}

@noindent
Stackeffect: sc dea --- sc dea1

@noindent
Attributes: 

@noindent
Description:
Search down from the @dfn{DEA}
@cindex DEA
 @samp{dea} for a
word with name @samp{sc}.
Replace @samp{dea} with @samp{dea1} if the dictionary
part between both could not contain the name searched for.
@samp{dea1} being a null pointer means that the dictionary
doesn't contain the name.
This is an vector in behalf of optimisation,
that starts as a noop, and
can be filled in if the extra field is used for optimisation.


@noindent
See also: @samp{~MATCH}
 @samp{FIND}
 @samp{>XFA}
 


        


@node unmatch, , optimiser, DICTIONARY
@subsection ~MATCH
@pindex ~MATCH
@findex ~MATCH

@noindent
Name: @code{~MATCH}

@noindent
Stackeffect: sc dea --- sc dea n

@noindent
Attributes: 

@noindent
Description:
Intended to cooperate with @code{(FIND)}
@findex (FIND)
 . Compares
the @dfn{string constant}
@cindex string constant
 @samp{sc} with the dea
@samp{dea}.
Returns into @samp{n} the difference between the first characters
that compare unequal, or zero if the strings are the same up to the
smallest length.
It is required that the dea has a non-zero name field.


@noindent
See also: @samp{FIND}
 @samp{CORA}
 

        




@node DOUBLE, ENVIRONMENTS,DICTIONARY, Glossary
@section DOUBLE
     
    The wordset @samp{DOUBLE} contains words that manipulate @dfn{double}
@cindex double
's.
In this 32 Forth you would hardly need doubles if it weren't
for the NUMBER formatting wordset that uses them exclusively.
    

    

@menu


* D+  ::
* DABS  ::
* DNEGATE  ::
* S>D  ::
@end menu
@node D+, DABS, DOUBLE, DOUBLE
@subsection D+
@pindex D+
@findex D+

@noindent
Name: @code{D+}

@noindent
Stackeffect: d1 d2 --- dsum

@noindent
Attributes: ISO,FIG

@noindent
Description:
Leave the double number @samp{dsum}: the sum of two
double numbers @samp{d1} and @samp{d2} .

@noindent
See also: @samp{DNEGATE}
 @samp{+}
 

        


@node DABS, DNEGATE, D+, DOUBLE
@subsection DABS
@pindex DABS
@findex DABS

@noindent
Name: @code{DABS}

@noindent
Stackeffect: d --- ud

@noindent
Attributes: ISO,FIG

@noindent
Description:
Leave the absolute value @samp{ud} of a double number @samp{d} .

@noindent
See also: @samp{DNEGATE}
 @samp{ABS}
 

        


@node DNEGATE, S>D, DABS, DOUBLE
@subsection DNEGATE
@pindex DNEGATE
@findex DNEGATE

@noindent
Name: @code{DNEGATE}

@noindent
Stackeffect: d1 --- d2

@noindent
Attributes: ISO

@noindent
Description:
@samp{d2} is the negation of @samp{d1}.


@noindent
See also: @samp{D+}
 
        


@node S>D, , DNEGATE, DOUBLE
@subsection S>D
@pindex S>D
@findex S>D

@noindent
Name: @code{S>D}

@noindent
Stackeffect: n --- d

@noindent
Attributes: ISO

@noindent
Description:
Sign extend a single number to form a double number.

        




@node ENVIRONMENTS, ERRORS,DOUBLE, Glossary
@section ENVIRONMENTS
     
    The wordset @samp{ENVIRONMENTS} contains all words of
the @code{ENVIRONMENT}
@findex ENVIRONMENT
 vocabulary and those words needed
to recognize them as Forth environment queries.
Note that these are not environment variables in
the sense that are passed from an operating system to a
program. 
    

    

@menu


* CORE  ::
* CPU  ::
* ENVIRONMENT?  ::
* NAME  ::
* SUPPLIER  ::
* VERSION  ::
@end menu
@node CORE, CPU, ENVIRONMENTS, ENVIRONMENTS
@subsection CORE
@pindex CORE
@findex CORE

@noindent
Name: @code{CORE}

@noindent
Stackeffect: --- ff

@noindent
Attributes: ISO

@noindent
Description:
An environment query whether the CORE wordset is present.

@noindent
See also: @samp{ENVIRONMENT?}
 
        


@node CPU, ENVIRONMENT?, CORE, ENVIRONMENTS
@subsection CPU
@pindex CPU
@findex CPU

@noindent
Name: @code{CPU}

@noindent
Stackeffect: --- d

@noindent
Attributes: CI

@noindent
Description:
An environment query returning the cpu-type to be printed as a
base-36 number. 

@noindent
See also: @samp{ENVIRONMENT?}
 
        


@node ENVIRONMENT?, NAME, CPU, ENVIRONMENTS
@subsection ENVIRONMENT?
@pindex ENVIRONMENT?
@findex ENVIRONMENT?

@noindent
Name: @code{ENVIRONMENT?}

@noindent
Stackeffect: sc --- i*x true/false

@noindent
Attributes: ISO

@noindent
Description:
If the string @samp{sc} is a known environment
attribute, leave into @samp{i*x} the information about
that attribute and a true flag, else leave a false flag. In
fact the flag indicates whether the words is present in the
@code{ENVIRONMENT}
@findex ENVIRONMENT
 vocabulary and @samp{i*x} is
what is left by the word if executed.


@noindent
See also: @samp{VOCABULARY}
 
        


@node NAME, SUPPLIER, ENVIRONMENT?, ENVIRONMENTS
@subsection NAME
@pindex NAME
@findex NAME

@noindent
Name: @code{NAME}

@noindent
Stackeffect: --- sc

@noindent
Attributes: CI

@noindent
Description:
An environment query giving the name of this Forth as a @dfn{string constant}.


@noindent
See also: @samp{ENVIRONMENT?}
 
        


@node SUPPLIER, VERSION, NAME, ENVIRONMENTS
@subsection SUPPLIER
@pindex SUPPLIER
@findex SUPPLIER

@noindent
Name: @code{SUPPLIER}

@noindent
Stackeffect: --- sc

@noindent
Attributes: CI

@noindent
Description:
An environment query giving the SUPPLIER of this Forth as a @dfn{string constant}.


@noindent
See also: @samp{ENVIRONMENT?}
 
        


@node VERSION, , SUPPLIER, ENVIRONMENTS
@subsection VERSION
@pindex VERSION
@findex VERSION

@noindent
Name: @code{VERSION}

@noindent
Stackeffect: --- sc

@noindent
Attributes: CI

@noindent
Description:
An environment query giving the version of this Forth as a @dfn{string constant}.


@noindent
See also: @samp{ENVIRONMENT?}
 
        




@node ERRORS, FILES,ENVIRONMENTS, Glossary
@section ERRORS
     
    The wordset @samp{ERRORS} contains words to handle errors
and exceptions.
    

    

@menu


* ?ERROR  ::
* ?ERRUR  ::
* ABORT"  :abort_quote
* CATCH  ::
* ERROR  ::
* ERRSCR  ::
* MESSAGE  ::
* THROW  ::
* WARNING  ::
* WHERE  ::
* (ABORT")  :paren_abort_quote
* HANDLER  ::
@end menu
@node ?ERROR, ?ERRUR, ERRORS, ERRORS
@subsection ?ERROR
@pindex ?ERROR
@findex ?ERROR

@noindent
Name: @code{?ERROR}

@noindent
Stackeffect: f n ---

@noindent
Attributes: 

@noindent
Description:

If the boolean flag is true, @dfn{signal an error}
@cindex signal an error
 with
number @samp{n}.
This means that an exception is thrown,
and it is remembered that this is the original place where the
exception originated.
If the exception is never caught, an error message is displayed
using @code{ERROR}
@findex ERROR
 .
All errors signalled by the kernel go
through this word, allowing to catch
e.g. errors in accessing the block file.


@noindent
See also: @samp{ERROR}
 @samp{?ERRUR}
 

        


@node ?ERRUR, abort_quote, ?ERROR, ERRORS
@subsection ?ERRUR
@pindex ?ERRUR
@findex ?ERRUR

@noindent
Name: @code{?ERRUR}

@noindent
Stackeffect: n ---

@noindent
Attributes: 

@noindent
Description:
Handle the possible error @samp{n} in Unix fashion. If
it is zero or positive, this means okay. If it is negative, its
value identifies an error condition. This error is handled in
the same way as by @code{?ERROR}
@findex ?ERROR
 . 

@noindent
See also: @samp{ERROR}
 @samp{?ERROR}
 

        


@node abort_quote, CATCH, ?ERRUR, ERRORS
@subsection ABORT"
@pindex ABORT"
@findex ABORT"

@noindent
Name: @code{ABORT"}

@noindent
Stackeffect: f ---

@noindent
Attributes: ISO,I

@noindent
Description:
Usage is @samp{: <SOME> ... ABORT" <message>" ... ;}. If
ABORT" finds a non-zero @samp{f} on the stack, the
@samp{<message>} is displayed and an
@code{ABORT}
@findex ABORT
 is executed. Otherwise proceed with the
words after @samp{<message>}. This word can only be used
in compile mode.


@noindent
See also: @samp{?ERROR}
 
        


@node CATCH, ERROR, abort_quote, ERRORS
@subsection CATCH
@pindex CATCH
@findex CATCH

@noindent
Name: @code{CATCH}

@noindent
Stackeffect: ... xt --- ... tc 

@noindent
Attributes: ISO

@noindent
Description:
Execute @samp{xt}. If it executes successfully, i.e. no
@code{THROW}
@findex THROW
 is executed by @samp{xt}, leave a zero
into @samp{tc} in addition to any stack effect
@samp{xt} itself might have. Otherwise in @samp{tc}
the non-zero throw code is left, and the stack depth is
restored. The values of the parameters for
@samp{xt} could have been modified. In
general, there is nothing useful that can be done with those
stack items. Since the stack depth is known, the application
may @code{DROP}
@findex DROP
 those items.

@noindent
See also: @samp{THROW}
 @samp{QUIT}
 @samp{HANDLER}
 


        


@node ERROR, ERRSCR, CATCH, ERRORS
@subsection ERROR
@pindex ERROR
@findex ERROR

@noindent
Name: @code{ERROR}

@noindent
Stackeffect: n ---

@noindent
Attributes: 

@noindent
Description:
Notify the user that an uncaught exception or
error with number @samp{n} has occurred.
The word that caused it is found using @code{WHERE}
@findex WHERE
 and displayed .
Also @samp{n} is passed to @code{MESSAGE}
@findex MESSAGE
 in order to give a description
 of the error.
This word is executed by @code{THROW}
@findex THROW
 before restarting the interpreter
and can be revectored to give more elaborate diagnostics. 

@noindent
See also: @samp{?ERROR}
 @samp{WARNING}
 

        


@node ERRSCR, MESSAGE, ERROR, ERRORS
@subsection ERRSCR
@pindex ERRSCR
@findex ERRSCR

@noindent
Name: @code{ERRSCR}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
A variable containing the address of the number of the screen
from which messages are offset. Messages
correspond with lines and the offset
may be positive or negative.
@samp{0 MESSAGE} prints the first line of this screen.
Traditionally this was screen 4, but the negative
Unix error numbers makes this unfeasible.


@noindent
See also: @samp{C/L}
 @samp{MESSAGE}
 

        


@node MESSAGE, THROW, ERRSCR, ERRORS
@subsection MESSAGE
@pindex MESSAGE
@findex MESSAGE

@noindent
Name: @code{MESSAGE}

@noindent
Stackeffect: n ---

@noindent
Attributes: 

@noindent
Description:
 @code{MESSAGE}
@findex MESSAGE
 is generally used to print error and
warning messages.
Print on the standard error channel 
the text of line
@samp{n} relative to screen @code{ERRSCR}
@findex ERRSCR
 . @samp{n} may be
positive or negative and beyond just screen @code{ERRSCR}
@findex ERRSCR
.
The messages with negative offset contain
the strings belonging to the return values for Linux system calls .
@samp{0 MESSAGE} will print version information about the library file,
the messages sit in.
If @code{WARNING}
@findex WARNING
 is zero (disc unavailable), the message will simply be ignored.


@noindent
See also: @samp{ERROR}
 
        


@node THROW, WARNING, MESSAGE, ERRORS
@subsection THROW
@pindex THROW
@findex THROW

@noindent
Name: @code{THROW}

@noindent
Stackeffect: ... tc --- ... / ... tc

@noindent
Attributes: ISO

@noindent
Description:
If @samp{tc} is zero, it is merely discarded. If we are
executing under control of a @code{CATCH}
@findex CATCH
 , see
@code{CATCH}
@findex CATCH
 for the effect of a non-zero
@samp{tc}. If we are executing not under control of a
@code{CATCH}
@findex CATCH
, a non-zero @samp{tc} gives a message to the effect
that this exception has occurred and starts Forth anew.


@noindent
See also: @samp{CATCH}
 @samp{QUIT}
 @samp{HANDLER}
 @samp{?ERROR}
 @samp{ERROR}
 




        


@node WARNING, WHERE, THROW, ERRORS
@subsection WARNING
@pindex WARNING
@findex WARNING

@noindent
Name: @code{WARNING}

@noindent
Stackeffect: --- addr

@noindent
Attributes: FIG,U

@noindent
Description:
A user variable containing a value controlling messages. If it
is 1, a library file is open, and messages are fetched from it.
If it is 0,
messages will be presented by number only.
Don't set @code{WARNING}
@findex WARNING
 to 1 if there is no block system available,
because the error system will call itself recursively.
This may lead to a crash.


@noindent
See also: @samp{MESSAGE}
 @samp{ERROR}
 @samp{ERRSCR}
 


        


@node WHERE, paren_abort_quote, WARNING, ERRORS
@subsection WHERE
@pindex WHERE
@findex WHERE

@noindent
Name: @code{WHERE}

@noindent
Stackeffect: --- addr

@noindent
Attributes: U

@noindent
Description:
A user variable pair which contains the start of the source and the
character position of the last error that was thrown by
@code{?ERROR}
@findex ?ERROR
 ,so not of exceptions thrown.
The contents of @code{WHERE}
@findex WHERE
 is interpreted by
@code{ERROR}
@findex ERROR
 if the corresponding exception was never
caught. 

@noindent
See also: @samp{THROW}
 @samp{CATCH }
 

        


@node paren_abort_quote, HANDLER, WHERE, ERRORS
@subsection (ABORT")
@pindex (ABORT")
@findex (ABORT")

@noindent
Name: @code{(ABORT")}

@noindent
Stackeffect: f ---

@noindent
Attributes: 

@noindent
Description:
The run time action of @code{ABORT"}
@findex ABORT"
 .

        


@node HANDLER, , paren_abort_quote, ERRORS
@subsection HANDLER
@pindex HANDLER
@findex HANDLER

@noindent
Name: @code{HANDLER}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
A user variable address containing a pointer to the
last exception intercepting frame activated by @code{CATCH}
@findex CATCH
 .
It points into the return stack.
If there is a @code{THROW}
@findex THROW
, the return stack
is restored from @code{HANDLER}
@findex HANDLER
 effecting a multiple level return.
It is called a frame because more things are restored, such as the
position of the data stack top, and the previous value of @code{HANDLER}
@findex HANDLER
 .

@noindent
See also: @samp{CATCH}
 @samp{THROW}
 

        




@node FILES, FORMATTING,ERRORS, Glossary
@section FILES
     
    The wordset @samp{FILES} contains words to input and output
to files, or load words from files.
They are underlying the @samp{BLOCKS} facilities.
    

    

@menu


* CLOSE-FILE  ::
* CREATE-FILE  ::
* DELETE-FILE  ::
* GET-FILE  ::
* INCLUDED  ::
* OPEN-FILE  ::
* PUT-FILE  ::
* READ-FILE  ::
* REPOSITION-FILE  ::
* WRITE-FILE  ::
* RW-BUFFER  ::
@end menu
@node CLOSE-FILE, CREATE-FILE, FILES, FILES
@subsection CLOSE-FILE
@pindex CLOSE-FILE
@findex CLOSE-FILE

@noindent
Name: @code{CLOSE-FILE}

@noindent
Stackeffect: fileid --- ior 

@noindent
Attributes: ISO

@noindent
Description:
Close the file with file handle in @samp{fileid}. Return
a result code into @samp{ior}. The latter is the  Linux
error code negated, to be inspected using @code{MESSAGE}
@findex MESSAGE
. 

@noindent
See also: @samp{OPEN-FILE}
 @samp{READ-FILE}
 @samp{WRITE-FILE}
 @samp{CREATE-FILE}
 @samp{DELETE-FILE}
 




        


@node CREATE-FILE, DELETE-FILE, CLOSE-FILE, FILES
@subsection CREATE-FILE
@pindex CREATE-FILE
@findex CREATE-FILE

@noindent
Name: @code{CREATE-FILE}

@noindent
Stackeffect: sc u --- fileid ior 

@noindent
Attributes: NISO

@noindent
Description:
for normal files this is just 0.
.
Create a file with name @samp{sc} and file
access privileges @samp{u}  If the file already exists,
it is truncated to zero length. Return a file handle into
@samp{fileid} and a result code into @samp{ior}.
The latter is the  @samp{errno}  negated, to be inspected using
@code{MESSAGE}
@findex MESSAGE
 .
The handle is open for READ_WRITE. 

@noindent
See also: @samp{OPEN-FILE}
 @samp{READ-FILE}
 @samp{WRITE-FILE}
 @samp{CREATE-FILE}
 @samp{DELETE-FILE}
 




        


@node DELETE-FILE, GET-FILE, CREATE-FILE, FILES
@subsection DELETE-FILE
@pindex DELETE-FILE
@findex DELETE-FILE

@noindent
Name: @code{DELETE-FILE}

@noindent
Stackeffect: sc --- ior 

@noindent
Attributes: ISO

@noindent
Description:
Delete the file with name @samp{sc}. Return
a result code into @samp{ior}.
The latter is the  @samp{errno}  negated, to be inspected using
@code{MESSAGE}
@findex MESSAGE
 .


@noindent
See also: @samp{OPEN-FILE}
 @samp{READ-FILE}
 @samp{WRITE-FILE}
 @samp{CREATE-FILE}
 @samp{DELETE-FILE}
 




        


@node GET-FILE, INCLUDED, DELETE-FILE, FILES
@subsection GET-FILE
@pindex GET-FILE
@findex GET-FILE

@noindent
Name: @code{GET-FILE}

@noindent
Stackeffect: sc1 --- sc2

@noindent
Attributes: 

@noindent
Description:
Get the content of the file with name @samp{sc1};
leave it as a string @samp{sc2}. Any errors are thrown. 

@noindent
See also: @samp{PUT-FILE}
 @samp{OPEN-FILE}
 @samp{THROW}
 


        


@node INCLUDED, OPEN-FILE, GET-FILE, FILES
@subsection INCLUDED
@pindex INCLUDED
@findex INCLUDED

@noindent
Name: @code{INCLUDED}

@noindent
Stackeffect: sc1 --- i*x

@noindent
Attributes: ISO

@noindent
Description:
Interpret the content of the file with name @samp{sc1}
as if it was typed from the console, leaving result
@samp{i*x}. 

@noindent
See also: @samp{LOAD}
 
        


@node OPEN-FILE, PUT-FILE, INCLUDED, FILES
@subsection OPEN-FILE
@pindex OPEN-FILE
@findex OPEN-FILE

@noindent
Name: @code{OPEN-FILE}

@noindent
Stackeffect: sc fam --- fileid ior 

@noindent
Attributes: ISO

@noindent
Description:
Open the file with name @samp{sc} and file access method
@samp{fam}. Return a file handle into @samp{fileid}
and a result code into @samp{ior}. The latter is the  @samp{errno} 
error code negated, to be inspected using @code{MESSAGE}
@findex MESSAGE
.
 @samp{fam} is one of 0=READ_ONLY, 1=WRITE_ONLY, 2=READ_WRITE.


@noindent
See also: @samp{OPEN-FILE}
 @samp{READ-FILE}
 @samp{WRITE-FILE}
 @samp{CREATE-FILE}
 @samp{DELETE-FILE}
 




        


@node PUT-FILE, READ-FILE, OPEN-FILE, FILES
@subsection PUT-FILE
@pindex PUT-FILE
@findex PUT-FILE

@noindent
Name: @code{PUT-FILE}

@noindent
Stackeffect: sc1 sc2 ---

@noindent
Attributes: 

@noindent
Description:
Save the @dfn{string constant} @samp{sc2} to a file with
the name @samp{sc1}. Any errors are thrown. 

@noindent
See also: @samp{GET-FILE}
 @samp{OPEN-FILE}
 @samp{THROW}
 


        


@node READ-FILE, REPOSITION-FILE, PUT-FILE, FILES
@subsection READ-FILE
@pindex READ-FILE
@findex READ-FILE

@noindent
Name: @code{READ-FILE}

@noindent
Stackeffect: addr n1 fd --- n2 ior 

@noindent
Attributes: ISO

@noindent
Description:
Read @samp{n} characters to @samp{addr} from current
position of the file that is open at @samp{fd} .
@samp{n2} is the number of characters successfully read,
this may be zero. @samp{ior} is 0 for success, or
otherwise  @samp{errno} 
error code negated, to be inspected using @code{MESSAGE}
@findex MESSAGE
. 

@noindent
See also: @samp{OPEN-FILE}
 @samp{WRITE-FILE}
 @samp{REPOSITION-FILE}
 @samp{R\W}
 



        


@node REPOSITION-FILE, WRITE-FILE, READ-FILE, FILES
@subsection REPOSITION-FILE
@pindex REPOSITION-FILE
@findex REPOSITION-FILE

@noindent
Name: @code{REPOSITION-FILE}

@noindent
Stackeffect: ud fd --- ior 

@noindent
Attributes: ISO

@noindent
Description:
Position the file that is open at @samp{fd} at position
@samp{ud}. @samp{ior} is 0 for success, or otherwise
 @samp{errno}
negated . Information about
error codes can be found by @code{MESSAGE}
@findex MESSAGE
. 

@noindent
See also: @samp{OPEN-FILE}
 @samp{READ-FILE}
 @samp{WRITE-FILE}
 


        


@node WRITE-FILE, RW-BUFFER, REPOSITION-FILE, FILES
@subsection WRITE-FILE
@pindex WRITE-FILE
@findex WRITE-FILE

@noindent
Name: @code{WRITE-FILE}

@noindent
Stackeffect: addr n fd --- u1 

@noindent
Attributes: ISO

@noindent
Description:
Write @samp{n} characters from @samp{addr} to the file that is
open at @samp{fd} , starting at its current position.
@samp{u1} is 0 for success,
or otherwise  @samp{errno} 
error code
negated, to be inspected using @code{MESSAGE}
@findex MESSAGE
.


@noindent
See also: @samp{OPEN-FILE}
 @samp{READ-FILE}
 @samp{REPOSITION-FILE}
 @samp{R\W}
 



        


@node RW-BUFFER, , WRITE-FILE, FILES
@subsection RW-BUFFER
@pindex RW-BUFFER
@findex RW-BUFFER

@noindent
Name: @code{RW-BUFFER}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
A constant that leaves the address of a disk buffer used by
file i/o words.



@noindent
See also: @samp{READ-FILE}
 @samp{OPEN-FILE}
 

        




@node FORMATTING, INIT,FILES, Glossary
@section FORMATTING
     
    The wordset @samp{FORMATTING} generates formatted output for
numbers, i.e. printing the digits in a field with a certain width,
possibly with sign etc.
This is possible in any @dfn{number base}
@cindex number base
. (Normally base 10 is used,
which means that digits are found as a remainder by dividing by 10).
Formatting in Forth is always based on @dfn{double}
@cindex double
 numbers.
Single numbers are handled by converting them to @dfn{double}
@cindex double
 first.
This requires some double precision operators to be present in the Forth core.
@xref{DOUBLE}, wordset. @xref{MULTIPLYING}, wordset.

    

    

@menu


* #>  ::
* #S  ::
* #  ::
* <#  ::
* >NUMBER  ::
* BASE  ::
* DECIMAL  ::
* HEX  ::
* HOLD  ::
* SIGN  ::
* (NUMBER)  :paren_number
* DIGIT  ::
* DPL  ::
* FLD  ::
* HLD  ::
* NUMBER  ::
@end menu
@node #>, #S, FORMATTING, FORMATTING
@subsection #>
@pindex #>
@findex #>

@noindent
Name: @code{#>}

@noindent
Stackeffect: d --- sc 

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Terminates numeric output conversion by dropping @samp{d}, leaving
the formatted string @samp{sc} .

@noindent
See also: @samp{<#}
 
        


@node #S, #, #>, FORMATTING
@subsection #S
@pindex #S
@findex #S

@noindent
Name: @code{#S}

@noindent
Stackeffect: d1 --- d2

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Generates ASCII text in the text output buffer, by the use of
@code{#}
@findex #
, until a zero double number
@samp{d2} results. Used between @code{<#}
@findex <#
 and
@code{#>}
@findex #>
.

        


@node #, <#, #S, FORMATTING
@subsection #
@pindex #
@findex #

@noindent
Name: @code{#}

@noindent
Stackeffect: d1 --- d2

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Generate from a double number @samp{d1}, the next ASCII
character which is placed in an output string. Result
@samp{d2} is the quotient after division by
@code{BASE}
@findex BASE
, and is maintained for further processing.
Used between @code{<#}
@findex <#
 and @code{#>}
@findex #>
.

@noindent
See also: @samp{#S}
 
        


@node <#, >NUMBER, #, FORMATTING
@subsection <#
@pindex <#
@findex <#

@noindent
Name: @code{<#}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Setup for pictured numeric output formatting using the words:
@code{<#}
@findex <#
 @code{#}
@findex #
 @code{#S}
@findex #S

@code{SIGN}
@findex SIGN
 @code{#>}
@findex #>
 The conversion is done on a
double number producing text growing down from @code{PAD}
@findex PAD

.

@noindent
See also: @samp{DPL}
 @samp{HLD}
 @samp{HOLD}
 @samp{FLD}
 



        


@node >NUMBER, BASE, <#, FORMATTING
@subsection >NUMBER
@pindex >NUMBER
@findex >NUMBER

@noindent
Name: @code{>NUMBER}

@noindent
Stackeffect: ud1 addr1 u1 --- ud2 addr2 u2

@noindent
Attributes: ISO

@noindent
Description:

@samp{ud2} is the result of converting the characters
within the character string specified by @samp{addr1 u1}
into digits, using the number in @code{BASE}
@findex BASE
 , and adding
each into ud1 after multiplying @samp{ud1} by the number
in @code{BASE}
@findex BASE
 . Conversion continues until a character
that is not convertible is encountered or the string is
entirely converted. @samp{addr2} is the location of the
first unconverted character or the first character past the end
of the string if the string was entirely converted.
@samp{u2} is the number of unconverted characters in the
string. If @samp{ud2} overflows, in ciforth
@samp{ud2} will be incorrect, but no crash will result.
Both
@kbd{-} and @kbd{+} are considered unconvertible
character's by @samp{>NUMBER} .


@noindent
See also: @samp{NUMBER}
 @samp{DIGIT}
 

        


@node BASE, DECIMAL, >NUMBER, FORMATTING
@subsection BASE
@pindex BASE
@findex BASE

@noindent
Name: @code{BASE}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO,FIG,U,L0

@noindent
Description:
A user variable containing the current number base used for input
and output conversion.

@noindent
See also: @samp{DECIMAL}
 @samp{HEX}
 @samp{<#}
 


        


@node DECIMAL, HEX, BASE, FORMATTING
@subsection DECIMAL
@pindex DECIMAL
@findex DECIMAL

@noindent
Name: @code{DECIMAL}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Set the numeric conversion @code{BASE}
@findex BASE
 for decimal input-output.

@noindent
See also: @samp{HEX}
 
        


@node HEX, HOLD, DECIMAL, FORMATTING
@subsection HEX
@pindex HEX
@findex HEX

@noindent
Name: @code{HEX}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Set the numeric conversion @code{BASE}
@findex BASE
 for hexadecimal (base 16) input-output.

@noindent
See also: @samp{DECIMAL}
 
        


@node HOLD, SIGN, HEX, FORMATTING
@subsection HOLD
@pindex HOLD
@findex HOLD

@noindent
Name: @code{HOLD}

@noindent
Stackeffect: c ---

@noindent
Attributes: ISO,FIG

@noindent
Description:
Add the character @samp{c} to the beginning of the output
string. It must be executed for numeric formatting inside a
@code{<#}
@findex <#
 and @code{#>}
@findex #>
 construct . 

@noindent
See also: @samp{#}
 @samp{DIGIT}
 

        


@node SIGN, paren_number, HOLD, FORMATTING
@subsection SIGN
@pindex SIGN
@findex SIGN

@noindent
Name: @code{SIGN}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,FIG

@noindent
Description:
Stores an ASCII minus-sign @kbd{-} just before a converted numeric output
string in the text output buffer when @samp{n} is negative.
Must be used between @code{<#}
@findex <#
 and
@code{#>}
@findex #>
 .

@noindent
See also: @samp{HOLD}
 
        


@node paren_number, DIGIT, SIGN, FORMATTING
@subsection (NUMBER)
@pindex (NUMBER)
@findex (NUMBER)

@noindent
Name: @code{(NUMBER)}

@noindent
Stackeffect:  --- d1

@noindent
Attributes: 

@noindent
Description:
Convert the ASCII text at the
@dfn{current input source}
@cindex current input source
 with regard to @code{BASE}
@findex BASE
 .
The new value is
accumulated into double number @samp{d1} , being left. A
decimal point, anywhere, signifies that the input is to be
considered as a double. ISO requires it to be at the end of the
number. ciforth allows any number of decimal points with the
same meaning. ciforth also allows any number of comma's that
are just ignored, to improve readability. If the first
unconvertible digit is not a blank, this is an error. 

@noindent
See also: @samp{NUMBER}
 @samp{?BLANK}
 

        


@node DIGIT, DPL, paren_number, FORMATTING
@subsection DIGIT
@pindex DIGIT
@findex DIGIT

@noindent
Name: @code{DIGIT}

@noindent
Stackeffect: c n1 --- n2 true (ok) c n1 --- x false (bad)

@noindent
Attributes: 

@noindent
Description:
Converts the ASCII character @samp{c} (using base @samp{n1} ) to its binary
equivalent @samp{n2} , accompanied by a true flag. If the conversion is
invalid, leaves only a don't care value and a false flag.

        


@node DPL, FLD, DIGIT, FORMATTING
@subsection DPL
@pindex DPL
@findex DPL

@noindent
Name: @code{DPL}

@noindent
Stackeffect: ---- addr

@noindent
Attributes: FIG,U,L0

@noindent
Description:
A user variable containing the address of the decimal point on
double integer input, or a @dfn{nil pointer}. It may also be used to
hold the output column location of a decimal point, in user
generated formating. 

@noindent
See also: @samp{<#}
 @samp{FLD}
 @samp{HLD}
 


        


@node FLD, HLD, DPL, FORMATTING
@subsection FLD
@pindex FLD
@findex FLD

@noindent
Name: @code{FLD}

@noindent
Stackeffect: --- addr

@noindent
Attributes: FIG,U

@noindent
Description:
A user variable for control of number output field width.
Unused in the kernel of ciforth.

        


@node HLD, NUMBER, FLD, FORMATTING
@subsection HLD
@pindex HLD
@findex HLD

@noindent
Name: @code{HLD}

@noindent
Stackeffect: --- addr

@noindent
Attributes: FIG,L0

@noindent
Description:
A user variable that holds the address of the latest character of
text during numeric output conversion.

@noindent
See also: @samp{<#}
 @samp{DPL}
 @samp{FLD}
 


        


@node NUMBER, , HLD, FORMATTING
@subsection NUMBER
@pindex NUMBER
@findex NUMBER

@noindent
Name: @code{NUMBER}

@noindent
Stackeffect:  ---  s/d

@noindent
Attributes: 

@noindent
Description:

This word is intended to be called from single character denotation
words, hence the parse pointer is decremented, to include this first
character.
Convert characters from the current input source into a number,
and compile or execute this number. If the string contains a
decimal point it is a double else a single integer number. If
numeric conversion is not possible, an error message will be
given.


@noindent
See also: @samp{BASE}
 @samp{(NUMBER)}
 

        




@node INIT, INPUT,FORMATTING, Glossary
@section INIT
     
    The wordset @samp{INIT} contains words to initialise,
reinitialise or configure Forth.
    

    

@menu


* +ORIGIN  ::
* ABORT  ::
* COLD  ::
* OK  ::
* OPTIONS  ::
* QUIT  ::
* WARM  ::
@end menu
@node +ORIGIN, ABORT, INIT, INIT
@subsection +ORIGIN
@pindex +ORIGIN
@findex +ORIGIN

@noindent
Name: @code{+ORIGIN}

@noindent
Stackeffect: n --- addr

@noindent
Attributes: 

@noindent
Description:
Leave the memory address relative by @samp{n} bytes to
the area from which the user variables are initialised, so one
can access or modify the boot-up parameters. During run time
user variables are fetched from the current user area, via a
pointer at @samp{0 +ORIGIN } . This can be swapped to get
a fresh set of user variables, for multi-asking. One can access
or modify the boot-up parameters, prior to saving a customised
boot image. It will also change the initialisation by
@code{COLD}
@findex COLD
. 

@noindent
See also: @samp{USER}
 
        


@node ABORT, COLD, +ORIGIN, INIT
@subsection ABORT
@pindex ABORT
@findex ABORT

@noindent
Name: @code{ABORT}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Restart the system. In addition and before the actions of
@code{QUIT}
@findex QUIT
, clear also the data stack and reset the
search order, reset the exception mechanism and set
the numeric base to default.
As required by ISO it is silent. This may be confusing
at times, because you can't tell the difference between a word
that is still busy or that has aborted.


@noindent
See also: @samp{WARM}
 
        


@node COLD, OK, ABORT, INIT
@subsection COLD
@pindex COLD
@findex COLD

@noindent
Name: @code{COLD}

@noindent
No stackeffect

@noindent
Attributes: FIG

@noindent
Description:
Reinitialise the system. Clear all block buffers. Reinitialise
all user variables to their boot up values values, i.a. the
stacks and the @dfn{dictionary pointer} . Opens the
file that contains the blocks. Restart via @code{ABORT}
@findex ABORT
 .
May be called from the terminal to remove application
programs and restart, as long as there are no
new vocabularies with definitions.
But it is better to say @code{BYE}
@findex BYE
 to Forth and start again.



@noindent
See also: @samp{WARM}
 @samp{BLOCK}
 @samp{LIST}
 


        


@node OK, OPTIONS, COLD, INIT
@subsection OK
@pindex OK
@findex OK

@noindent
Name: @code{OK}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG

@noindent
Description:
Takes care of printing the okay-message, after interpreting
a line. Default it prints ``OK'' only for an interactive session
in interpret @code{STATE}
@findex STATE
. 

@noindent
See also: @samp{QUIT}
 @samp{COLD}
 

        


@node OPTIONS, QUIT, OK, INIT
@subsection OPTIONS
@pindex OPTIONS
@findex OPTIONS

@noindent
Name: @code{OPTIONS}

@noindent
Stackeffect: f1 -- f2

@noindent
Attributes: FIG L0

@noindent
Description:
Handle command line options, i.e. execute the screen
corresponding to the option letter. Accept and return a flag
@samp{f} whether the signon message must be
displayed. By redefining this as a
@samp{NOOP}, the handling of options during cold boot is
suppressed, useful for turnkey applications. By redefining as
@samp{DROP 0}, execution and signon are suppressed. 

@noindent
See also: @samp{COLD}
 
        


@node QUIT, WARM, OPTIONS, INIT
@subsection QUIT
@pindex QUIT
@findex QUIT

@noindent
Name: @code{QUIT}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG

@noindent
Description:
Restart the interpreter. Clear the return stack, stop
compilation, and return control to the operators terminal,
or to the redirected input stream.
This means @code{(ACCEPT)}
@findex (ACCEPT)
 user input to somewhere in the
terminal input buffer, and
then @code{INTERPRET}
@findex INTERPRET
 with that as a @code{SOURCE}
@findex SOURCE
 .
No message is given.

@noindent
See also: @samp{TIB}
 @samp{ABORT}
 

        


@node WARM, , QUIT, INIT
@subsection WARM
@pindex WARM
@findex WARM

@noindent
Name: @code{WARM}

@noindent
No stackeffect

@noindent
Attributes: FIG L0

@noindent
Description:
Perform a so called "warm" start. In addition and before the
actions of @code{ABORT}
@findex ABORT
, discard blocks; they may not be
written back to mass storage. Display the sign on message.


@noindent
See also: @samp{ABORT}
 
        




@node INPUT, JUGGLING,INIT, Glossary
@section INPUT
     
    The wordset @samp{INPUT} contains words to get input from the terminal
and such.
@xref{FILES}, for disk I/O.
@xref{BLOCKS}, for access of blocks. 
    

    

@menu


* (ACCEPT)  :paren_accept
* >IN  ::
* ACCEPT  ::
* IN  ::
* KEY?  ::
* KEY  ::
* RUBOUT  ::
* TIB  ::
* (>IN)  :paren_iso_in
* REFILL-TIB  ::
* REMAINDER  ::
* SET-TERM  ::
* TERMIO  ::
@end menu
@node paren_accept, >IN, INPUT, INPUT
@subsection (ACCEPT)
@pindex (ACCEPT)
@findex (ACCEPT)

@noindent
Name: @code{(ACCEPT)}

@noindent
Stackeffect:  --- sc  

@noindent
Attributes: 

@noindent
Description:
Accept characters from the terminal, until a @kbd{RET}
is received and return the result as a constant string
@samp{sc}.
It doesn't contain any line ending, but the buffer still does
and after @code{1+}
@findex 1+
 the string ends in a @kbd{LF}.
The editing functions are the same as with @code{ACCEPT}
@findex ACCEPT
 .
This is lighter on the system and sometimes easier
to use than @code{ACCEPT}
@findex ACCEPT
 


@noindent
See also: @samp{KEY}
 @samp{KEY?}
 @samp{ACCEPT}
 


        


@node >IN, ACCEPT, paren_accept, INPUT
@subsection >IN
@pindex >IN
@findex >IN

@noindent
Name: @code{>IN}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO

@noindent
Description:
Return a variable that contains the offset from the start
within the current input text buffer (terminal or disc) from
which the next text will be accepted. All parsing words use and
move the value of @code{IN}
@findex IN
. The variable
@code{>IN}
@findex >IN
 is not actually used and its content must be
fetched immediately.

@noindent
See also: @samp{(>IN)}
 @samp{IN}
 

        


@node ACCEPT, IN, >IN, INPUT
@subsection ACCEPT
@pindex ACCEPT
@findex ACCEPT

@noindent
Name: @code{ACCEPT}

@noindent
Stackeffect: addr count --- n

@noindent
Attributes: ISO

@noindent
Description:
Transfer at most @samp{count} characters from the
terminal to address, until a @kbd{RET} is received. The
simple tty editing functions of Linux are observed, i.e. the
``erase'' (delete a character) and ``kill'' (delete a line)
characters. Typically these are the backspace key and ^U. Note
that excess characters after @samp{count} are ignored.
The number of characters not
including the @kbd{RET} is returned into @samp{n}.


@noindent
See also: @samp{(ACCEPT)}
 @samp{KEY}
 @samp{KEY?}
 @samp{(ACCEPT)}
 



        


@node IN, KEY?, ACCEPT, INPUT
@subsection IN
@pindex IN
@findex IN

@noindent
Name: @code{IN}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
A user variable containing a pointer within the current input
text buffer (terminal or disc) from which the next text will be
accepted. All parsing words use and move the value of @code{IN}
@findex IN
 .

@noindent
See also: @samp{>IN}
 @samp{WORD}
 @samp{(WORD)}
 @samp{NUMBER}
 @samp{(PARSE)}
 @samp{IN[]}
 





        


@node KEY?, KEY, IN, INPUT
@subsection KEY?
@pindex KEY?
@findex KEY?

@noindent
Name: @code{KEY?}

@noindent
Stackeffect: --- ff

@noindent
Attributes: ISO

@noindent
Description:
Return into @samp{ff} return whether a character is available.
The next execution of @code{KEY}
@findex KEY
 will return the character immediately.


@noindent
See also: @samp{KEY}
 @samp{ACCEPT}
 @samp{KEY?}
 


        


@node KEY, RUBOUT, KEY?, INPUT
@subsection KEY
@pindex KEY
@findex KEY

@noindent
Name: @code{KEY}

@noindent
Stackeffect: --- c

@noindent
Attributes: ISO FIG L0

@noindent
Description:
Leave the ASCII value of the next terminal key struck.

@noindent
See also: @samp{ACCEPT}
 @samp{KEY?}
 

        


@node RUBOUT, TIB, KEY, INPUT
@subsection RUBOUT
@pindex RUBOUT
@findex RUBOUT

@noindent
Name: @code{RUBOUT}

@noindent
Stackeffect: --- c

@noindent
Attributes: 

@noindent
Description:
A user variable, leaving the key code that must delete the
last character from the input buffer.
In this ciforth it is not used, as the terminal input
editing is left to the host operating system.


@noindent
See also: @samp{USER}
 
        


@node TIB, paren_iso_in, RUBOUT, INPUT
@subsection TIB
@pindex TIB
@findex TIB

@noindent
Name: @code{TIB}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO,FIG,U

@noindent
Description:
A user variable containing the address of the terminal input buffer.

@noindent
See also: @samp{QUIT}
 
        


@node paren_iso_in, REFILL-TIB, TIB, INPUT
@subsection (>IN)
@pindex (>IN)
@findex (>IN)

@noindent
Name: @code{(>IN)}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
If the standard word @code{>IN}
@findex >IN
 is used, this variable
contains the offset from the start
within the current input
text buffer (terminal or disc) from which the next text will be
accepted. All parsing words use and move the value of @code{IN}
@findex IN
 .

@noindent
See also: @samp{>IN}
 @samp{IN}
 

        


@node REFILL-TIB, REMAINDER, paren_iso_in, INPUT
@subsection REFILL-TIB
@pindex REFILL-TIB
@findex REFILL-TIB

@noindent
Name: @code{REFILL-TIB}

@noindent
Stackeffect:  --- 

@noindent
Attributes: 

@noindent
Description:
Accept characters from the terminal input stream such as to
fill up @code{TIB}
@findex TIB
 . Normally this means until a
@kbd{RET}.
It is now consumable
by @code{ACCEPT}
@findex ACCEPT
 or after @code{SET-SRC}
@findex SET-SRC

by Forth parsing words like @code{WORD}
@findex WORD
 .
The editing functions
are those described by @code{ACCEPT}
@findex ACCEPT
.
Immediately, after @code{REFILL-TIB}
@findex REFILL-TIB
 @samp{REMAINDER 2@@} defines
the characters ready in the input buffer. All characters are
retained including the @kbd{RET}.

If the input is redirected (such that reading
after a @kbd{RET} occurs)
@samp{REMAINDER 2@@} contains the part of
@code{TIB}
@findex TIB
 that is not yet consumed by @code{(ACCEPT)}
@findex (ACCEPT)
 ,
and outside the reach of @code{SRC}
@findex SRC
 .

All system call errors result in an exception.
For redirected I/O this word may generate an end-of-pipe exception.


@noindent
See also: @samp{ACCEPT}
 @samp{(ACCEPT)}
 

        


@node REMAINDER, SET-TERM, REFILL-TIB, INPUT
@subsection REMAINDER
@pindex REMAINDER
@findex REMAINDER

@noindent
Name: @code{REMAINDER}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
A pointer to a constant string that contains the balance of
characters fetched into the input buffer, but not yet consumed.
Used as in @samp{REMAINDER 2@@} .


@noindent
See also: @samp{REFILL-TIB}
 
        


@node SET-TERM, TERMIO, REMAINDER, INPUT
@subsection SET-TERM
@pindex SET-TERM
@findex SET-TERM

@noindent
Name: @code{SET-TERM}

@noindent
Stackeffect: len b ---

@noindent
Attributes: 

@noindent
Description:
Set the terminal length to @samp{len} and toggle the c_lflag field
with @samp{b} in the termio structure @code{TERMIO}
@findex TERMIO
 .
In particular toggling with 0x0A makes that
the terminal doesn't wait for a @kbd{RET}.
This word is invalid for pipes, and is replaced by
a @code{2DROP}
@findex 2DROP
 in that case.


@noindent
See also: @samp{SET-TERM}
 
        


@node TERMIO, , SET-TERM, INPUT
@subsection TERMIO
@pindex TERMIO
@findex TERMIO

@noindent
Name: @code{TERMIO}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
Leave the address of the terminal description, this has the layout of
a c-structure @samp{termio} .


@noindent
See also: @samp{SET-TERM}
 
        




@node JUGGLING, LOGIC,INPUT, Glossary
@section JUGGLING
     
    The wordset @samp{JUGGLING} contains words that change order
of data on the @dfn{data stack}
@cindex data stack
 .
The necessity for this arise, because the data you want to feed to a Forth word
is not directly accessible, i.e. on top of the stack.
It is also possible that  you need the same data twice, because you have to feed
it to two different words's.
Design your word such that you need them as little as possible,
because they are confusing.
    

    

@menu


* 2DROP  ::
* 2DUP  ::
* 2OVER  ::
* 2SWAP  ::
* ?DUP  ::
* DROP  ::
* DUP  ::
* OVER  ::
* ROT  ::
* SWAP  ::
@end menu
@node 2DROP, 2DUP, JUGGLING, JUGGLING
@subsection 2DROP
@pindex 2DROP
@findex 2DROP

@noindent
Name: @code{2DROP}

@noindent
Stackeffect: n1 n2 ---

@noindent
Attributes: ISO

@noindent
Description:
Drop the topmost two
numbers (or one double number)
 from the stack.

@noindent
See also: @samp{DROP}
 @samp{2DUP}
 

        


@node 2DUP, 2OVER, 2DROP, JUGGLING
@subsection 2DUP
@pindex 2DUP
@findex 2DUP

@noindent
Name: @code{2DUP}

@noindent
Stackeffect: d --- d d

@noindent
Attributes: ISO

@noindent
Description:
Duplicate the double number on the stack.

@noindent
See also: @samp{OVER}
 
        


@node 2OVER, 2SWAP, 2DUP, JUGGLING
@subsection 2OVER
@pindex 2OVER
@findex 2OVER

@noindent
Name: @code{2OVER}

@noindent
Stackeffect: d1 d2 --- d1 d2 d1

@noindent
Attributes: ISO

@noindent
Description:
Copy the second stack double, placing it as the new top.

@noindent
See also: @samp{2DUP}
 
        


@node 2SWAP, ?DUP, 2OVER, JUGGLING
@subsection 2SWAP
@pindex 2SWAP
@findex 2SWAP

@noindent
Name: @code{2SWAP}

@noindent
Stackeffect: d1 d2 --- d2 d1

@noindent
Attributes: ISO

@noindent
Description:
Exchange the top doubles on the stack.

@noindent
See also: @samp{ROT}
 
        


@node ?DUP, DROP, 2SWAP, JUGGLING
@subsection ?DUP
@pindex ?DUP
@findex ?DUP

@noindent
Name: @code{?DUP}

@noindent
Stackeffect: n1 --- n1 (if zero) / n1 --- n1 n1 (non-zero)

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Reproduce @samp{n1} only if it is non-zero. This is
usually used to copy a value just before @code{IF}
@findex IF
 , to
eliminate the need for an @code{ELSE}
@findex ELSE
 part to drop
it.

@noindent
See also: @samp{DUP}
 @samp{_}
 

        


@node DROP, DUP, ?DUP, JUGGLING
@subsection DROP
@pindex DROP
@findex DROP

@noindent
Name: @code{DROP}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Drop the number from the stack.

@noindent
See also: @samp{DUP}
 
        


@node DUP, OVER, DROP, JUGGLING
@subsection DUP
@pindex DUP
@findex DUP

@noindent
Name: @code{DUP}

@noindent
Stackeffect: n --- n n

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Duplicate the value on the stack.

@noindent
See also: @samp{OVER}
 
        


@node OVER, ROT, DUP, JUGGLING
@subsection OVER
@pindex OVER
@findex OVER

@noindent
Name: @code{OVER}

@noindent
Stackeffect: nl n2 --- nl n2 n1

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Copy the second stack value, placing it as the new top.

@noindent
See also: @samp{DUP}
 
        


@node ROT, SWAP, OVER, JUGGLING
@subsection ROT
@pindex ROT
@findex ROT

@noindent
Name: @code{ROT}

@noindent
Stackeffect: nl n2 n3 --- n2 n3 nl

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Rotate the top three values on the stack, bringing the third to the
top.

@noindent
See also: @samp{SWAP}
 
        


@node SWAP, , ROT, JUGGLING
@subsection SWAP
@pindex SWAP
@findex SWAP

@noindent
Name: @code{SWAP}

@noindent
Stackeffect: n1 n2 --- n2 n1

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Exchange the top two values on the stack.

@noindent
See also: @samp{ROT}
 
        




@node LOGIC, MEMORY,JUGGLING, Glossary
@section LOGIC
     
    The wordset @samp{LOGIC} contains logic operators and
comparison operators.
A comparison operator (such as @code{=}
@findex =
 ) delivers a
@dfn{Forth flag}
@cindex Forth flag
, -1 for true, 0 for false, representing a
condition (such as equality of two numbers).
The number -1 has all bits set to one.
The logical operators ( @code{AND}
@findex AND
 etc.)
work on all 32 bits, one by one.
In this way they are useful for mask operations, as well
as for combining conditions
represented as flag's.
But beware that @code{IF}
@findex IF
 only cares whether
the top of the stack is non-zero, such that
@code{-}
@findex -
 can mean non-equal to @code{IF}
@findex IF
.
Such conditions (often named just @dfn{flag}
@cindex flag
's)
cannot be directly combined using logical operators,
but @samp{0= 0=} can help.
    

    

@menu


* 0<  ::
* 0=  ::
* <>  ::
* <  ::
* =  ::
* >  ::
* AND  ::
* INVERT  ::
* OR  ::
* U<  ::
* XOR  ::
@end menu
@node 0<, 0=, LOGIC, LOGIC
@subsection 0<
@pindex 0<
@findex 0<

@noindent
Name: @code{0<}

@noindent
Stackeffect: n --- ff

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave a true flag if the number is less than zero (negative),
otherwise leave a false flag.

@noindent
See also: @samp{<}
 
        


@node 0=, <>, 0<, LOGIC
@subsection 0=
@pindex 0=
@findex 0=

@noindent
Name: @code{0=}

@noindent
Stackeffect: n --- ff

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave a true flag @samp{ff} is the number @samp{n}
is equal to zero, otherwise leave a false flag.

@noindent
See also: @samp{=}
 
        


@node <>, <, 0=, LOGIC
@subsection <>
@pindex <>
@findex <>

@noindent
Name: @code{<>}

@noindent
Stackeffect: n1 n2 --- ff

@noindent
Attributes: ISO,L0

@noindent
Description:
Leave a true flag if @samp{n1} is not equal than
@samp{n2} ; otherwise leave a false flag.

@noindent
See also: @samp{>}
 @samp{=}
 @samp{0<}
 


        


@node <, =, <>, LOGIC
@subsection <
@pindex <
@findex <

@noindent
Name: @code{<}

@noindent
Stackeffect: n1 n2 --- ff

@noindent
Attributes: L0,ISO

@noindent
Description:
Leave a true flag if @samp{n1} is less than @samp{n2} ;
otherwise leave a false
flag.

@noindent
See also: @samp{=}
 @samp{>}
 @samp{0<}
 


        


@node =, >, <, LOGIC
@subsection =
@pindex =
@findex =

@noindent
Name: @code{=}

@noindent
Stackeffect: n1 n2 --- ff

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave a true flag if @samp{n1=n2} ; otherwise leave a false flag.

@noindent
See also: @samp{<}
 @samp{>}
 @samp{0=}
 @samp{-}
 



        


@node >, AND, =, LOGIC
@subsection >
@pindex >
@findex >

@noindent
Name: @code{>}

@noindent
Stackeffect: n1 n2 --- ff

@noindent
Attributes: ISO,L0

@noindent
Description:
Leave a true flag if @samp{n1} is greater than
@samp{n2} ; otherwise leave a false flag.

@noindent
See also: @samp{<}
 @samp{=}
 @samp{0<}
 


        


@node AND, INVERT, >, LOGIC
@subsection AND
@pindex AND
@findex AND

@noindent
Name: @code{AND}

@noindent
Stackeffect: n1 n2 --- n3

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the bitwise logical and of @samp{n1} and
@samp{n2} as @samp{n3} .

@noindent
See also: @samp{XOR}
 @samp{OR}
 

        


@node INVERT, OR, AND, LOGIC
@subsection INVERT
@pindex INVERT
@findex INVERT

@noindent
Name: @code{INVERT}

@noindent
Stackeffect: n1 --- n2

@noindent
Attributes: ISO,L1

@noindent
Description:
Invert all bits of @samp{n1} leaving @samp{n2} .
For pure flags (0 or -1) this is the @dfn{logical not}
@cindex logical not
 operator.


@noindent
See also: @samp{AND}
 @samp{OR}
 

        


@node OR, U<, INVERT, LOGIC
@subsection OR
@pindex OR
@findex OR

@noindent
Name: @code{OR}

@noindent
Stackeffect: n1 n2 --- n3

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the bit-wise logical or of two 32-bit
values.

@noindent
See also: @samp{AND}
 @samp{XOR}
 

        


@node U<, XOR, OR, LOGIC
@subsection U<
@pindex U<
@findex U<

@noindent
Name: @code{U<}

@noindent
Stackeffect: u1 u2 --- ff

@noindent
Attributes: ISO,L0

@noindent
Description:
Leave a true flag if @samp{u1} is less than @samp{u2} ; otherwise leave a false
flag.(Interpreted as unsigned numbers).

@noindent
See also: @samp{<}
 
        


@node XOR, , U<, LOGIC
@subsection XOR
@pindex XOR
@findex XOR

@noindent
Name: @code{XOR}

@noindent
Stackeffect: nl n2 --- n3

@noindent
Attributes: L1

@noindent
Description:
Leave the bitwise logical exclusive or of two
 32-bit values.

@noindent
See also: @samp{AND}
 @samp{OR}
 

        




@node MEMORY, MISC,LOGIC, Glossary
@section MEMORY
     
    The wordset @samp{MEMORY} contains words to fetch and
store numbers from @dfn{double}
@cindex double
s, @dfn{cell}
@cindex cell
s or bytes in memory.
There are also words to copy blocks of memory or fill them, and words that
fetch a @dfn{cell}
@cindex cell
, operate on it and store it back.
    

    

@menu


* !  ::
* +!  ::
* 2!  ::
* 2@@  :two_fetch
* @@  :fetch
* ALIGNED  ::
* ALIGN  ::
* BLANK  ::
* BM  ::
* C!  ::
* C@@  :c_fetch
* CELL+  ::
* CELLS  ::
* CHAR+  ::
* CHARS  ::
* CMOVE  ::
* CORA  ::
* EM  ::
* ERASE  ::
* FARMOVE  ::
* FILL  ::
* L!  ::
* L@@  :long_fetch
* MOVE  ::
* P!  ::
* P@@  :port_fetch
* PC!  ::
* PC@@  :port_char_fetch
* TOGGLE  ::
* WITHIN  ::
@end menu
@node !, +!, MEMORY, MEMORY
@subsection !
@pindex !
@findex !

@noindent
Name: @code{!}

@noindent
Stackeffect: n addr ---

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Store all 32 bits of n at @samp{addr} .

@noindent
See also: @samp{@@}
 @samp{C!}
 @samp{2!}
 @samp{L!}
 @samp{P!}
 @samp{PC!}
 





        


@node +!, 2!, !, MEMORY
@subsection +!
@pindex +!
@findex +!

@noindent
Name: @code{+!}

@noindent
Stackeffect: n addr ---

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
 Add @samp{n} to the value @samp{addr}.

@noindent
See also: @samp{TOGGLE}
 @samp{!}
 

        


@node 2!, two_fetch, +!, MEMORY
@subsection 2!
@pindex 2!
@findex 2!

@noindent
Name: @code{2!}

@noindent
Stackeffect: addr--- x1 x2

@noindent
Attributes: ISO

@noindent
Description:
Store a pair of 32 bits values @samp{x1}
@samp{x2} to consecutive cells at @samp{addr} .
@samp{x2} is stored at the lowest address.


@noindent
See also: @samp{2@@}
 @samp{!}
 @samp{C!}
 


        


@node two_fetch, fetch, 2!, MEMORY
@subsection 2@@
@pindex 2@@
@findex 2@@

@noindent
Name: @code{2@@}

@noindent
Stackeffect: addr--- x1 x2

@noindent
Attributes: ISO

@noindent
Description:
Leave a pair of 32 bits values @samp{x1} @samp{x2} from
consequitive cells at @samp{addr} . @samp{x2} is fetched from
the lowest address. 

@noindent
See also: @samp{2!}
 @samp{@@}
 @samp{C@@}
 


        


@node fetch, ALIGNED, two_fetch, MEMORY
@subsection @@
@pindex @@
@findex @@

@noindent
Name: @code{@@}

@noindent
Stackeffect: addr --- n

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the 32 bit contents @samp{n}
of @samp{addr} .

@noindent
See also: @samp{!}
 @samp{C@@}
 @samp{2@@}
 @samp{P@@}
 @samp{PC@@}
 @samp{L@@}
 





        


@node ALIGNED, ALIGN, fetch, MEMORY
@subsection ALIGNED
@pindex ALIGNED
@findex ALIGNED

@noindent
Name: @code{ALIGNED}

@noindent
Stackeffect: addr1 --- addr2

@noindent
Attributes: ISO

@noindent
Description:
Make sure that @samp{addr1} is @dfn{aligned}
@cindex aligned
 by advancing
it if necessary to @samp{addr2}.



@noindent
See also: @samp{ALIGN}
 
        


@node ALIGN, BLANK, ALIGNED, MEMORY
@subsection ALIGN
@pindex ALIGN
@findex ALIGN

@noindent
Name: @code{ALIGN}

@noindent
Stackeffect:  ---

@noindent
Attributes: ISO

@noindent
Description:
Make sure that @code{HERE}
@findex HERE
 is @dfn{aligned}
@cindex aligned
 by advancing
it if necessary.
This means that data of any size can be fetched from that address efficiently.



@noindent
See also: @samp{ALIGNED}
 
        


@node BLANK, BM, ALIGN, MEMORY
@subsection BLANK
@pindex BLANK
@findex BLANK

@noindent
Name: @code{BLANK}

@noindent
Stackeffect: addr count ---

@noindent
Attributes: ISO

@noindent
Description:
This is shorthand for ``@code{BL}
@findex BL
 @code{FILL}
@findex FILL
''.

        


@node BM, C!, BLANK, MEMORY
@subsection BM
@pindex BM
@findex BM

@noindent
Name: @code{BM}

@noindent
Stackeffect: ---- addr

@noindent
Attributes: 

@noindent
Description:
A constant leaving the address of the lowest memory
in use by Forth.


@noindent
See also: @samp{DP}
 @samp{EM}
 

        


@node C!, c_fetch, BM, MEMORY
@subsection C!
@pindex C!
@findex C!

@noindent
Name: @code{C!}

@noindent
Stackeffect: b addr ---

@noindent
Attributes: ISO

@noindent
Description:
Store 8 bits of @samp{b} at @samp{addr} .
In ciforth , running on the Intel architectures
there are no restrictions regarding byte
addressing.


@noindent
See also: @samp{C@@}
 @samp{!}
 

        


@node c_fetch, CELL+, C!, MEMORY
@subsection C@@
@pindex C@@
@findex C@@

@noindent
Name: @code{C@@}

@noindent
Stackeffect: addr --- b

@noindent
Attributes: ISO

@noindent
Description:
Leave the 8 bit contents of memory address.
In ciforth , running on the Intel architectures
there are no restrictions regarding byte
addressing.


@noindent
See also: @samp{C!}
 @samp{@@}
 @samp{2@@}
 


        


@node CELL+, CELLS, c_fetch, MEMORY
@subsection CELL+
@pindex CELL+
@findex CELL+

@noindent
Name: @code{CELL+}

@noindent
Stackeffect: n1 --- n2

@noindent
Attributes: ISO

@noindent
Description:
Advance the memory pointer @samp{n1} by one (in this case  32 bits) cell to
@samp{n2}. This is invaluable for writing portable
code. Much of the library code of ciforth runs on both 16 and 32 bits
systems, thanks to this.


        


@node CELLS, CHAR+, CELL+, MEMORY
@subsection CELLS
@pindex CELLS
@findex CELLS

@noindent
Name: @code{CELLS}

@noindent
Stackeffect: n1 --- n2

@noindent
Attributes: ISO

@noindent
Description:
Return the equivalent of @samp{n1} cells in bytes:
@samp{n2}. This is invaluable for writing portable
code. Much of the library code of ciforth runs on both 16 and 32 bits
systems, thanks to this.


@noindent
See also: @samp{CELL+}
 
        


@node CHAR+, CHARS, CELLS, MEMORY
@subsection CHAR+
@pindex CHAR+
@findex CHAR+

@noindent
Name: @code{CHAR+}

@noindent
Stackeffect: n1 --- n2

@noindent
Attributes: ISO

@noindent
Description:
Advance the memory pointer @samp{n1} by one character to
@samp{n2}. In ciforth this means one byte. Bytes are the
address units ISO is talking about. Unfortunately
the ISO standard has no way to address bytes.


@noindent
See also: @samp{CELL+}
 
        


@node CHARS, CMOVE, CHAR+, MEMORY
@subsection CHARS
@pindex CHARS
@findex CHARS

@noindent
Name: @code{CHARS}

@noindent
Stackeffect: n1 --- n2

@noindent
Attributes: ISO

@noindent
Description:
Return the equivalent of @samp{n1} chars in bytes:
@samp{n2}. In ciforth this is a NOOP.
Unfortunately
the ISO standard has no way to address bytes.


@noindent
See also: @samp{CELLS}
 
        


@node CMOVE, CORA, CHARS, MEMORY
@subsection CMOVE
@pindex CMOVE
@findex CMOVE

@noindent
Name: @code{CMOVE}

@noindent
Stackeffect: from to count ---

@noindent
Attributes: 

@noindent
Description:
Move the specified quantity of characters beginning at address
 @samp{from} to address @samp{to} . The contents of
address from is moved first proceeding toward high memory, such
that memory propagation occurs. As the Intel 86-family is
byte-addressing there are no restrictions in ciforth. 

        


@node CORA, EM, CMOVE, MEMORY
@subsection CORA
@pindex CORA
@findex CORA

@noindent
Name: @code{CORA}

@noindent
Stackeffect: addr1 addr2 len  -- n

@noindent
Attributes: CIF

@noindent
Description:
Compare the memory areas at @samp{addr1} and @samp{addr2}
over a length @samp{len} .
For the first bytes that differ, return -1 if the byte
from @samp{addr1} is less (unsigned) than the one from @samp{addr2},
and 1 if it is greater.
If all @samp{len} bytes are equal, return
zero.
This is an abbreviation of @code{COMPARE-AREA}
@findex COMPARE-AREA
.
It would have been named @samp{COMPARE} ,
if that were not taken by ISO.


        


@node EM, ERASE, CORA, MEMORY
@subsection EM
@pindex EM
@findex EM

@noindent
Name: @code{EM}

@noindent
Stackeffect: ---- addr

@noindent
Attributes: 

@noindent
Description:
A constant leaving the address just above the highest memory
in use by Forth.


@noindent
See also: @samp{DP}
 @samp{BM}
 

        


@node ERASE, FARMOVE, EM, MEMORY
@subsection ERASE
@pindex ERASE
@findex ERASE

@noindent
Name: @code{ERASE}

@noindent
Stackeffect: addr n ---

@noindent
Attributes: ISO

@noindent
Description:
This is shorthand for @samp{0 FILL}.

@noindent
See also: @samp{BLANK}
 @samp{FILL}
 

        


@node FARMOVE, FILL, ERASE, MEMORY
@subsection FARMOVE
@pindex FARMOVE
@findex FARMOVE

@noindent
Name: @code{FARMOVE}

@noindent
Stackeffect: faraddr1 faraddr2 count ---

@noindent
Attributes: 

@noindent
Description:
Move @samp{count}
bytes beginning at @samp{faraddr1} to
@samp{faraddr2}. Segments that are zero are replaced by
defaults: data segment selector  for source, extra segment selector 
for destination.
Copying is done from low to high
offset, so there may be memory
propagating. This is not easily seen
from the selector 's, particularly not so in
protected mode.
As the Intel 86-family is byte-addressing there are
no restrictions.


@noindent
See also: @samp{MOVE}
 @samp{CMOVE}
 

        


@node FILL, L!, FARMOVE, MEMORY
@subsection FILL
@pindex FILL
@findex FILL

@noindent
Name: @code{FILL}

@noindent
Stackeffect: addr u b ---

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
 If @samp{u} is not zero, store @samp{b}
in each of @samp{u} consecutive bytes of memory beginning at
@samp{addr} . 

@noindent
See also: @samp{BLANK}
 @samp{ERASE}
 

        


@node L!, long_fetch, FILL, MEMORY
@subsection L!
@pindex L!
@findex L!

@noindent
Name: @code{L!}

@noindent
Stackeffect: n faraddr ---

@noindent
Attributes: 

@noindent
Description:
Store 32 bits of @samp{n} at segment address pair
@samp{faraddr}.


@noindent
See also: @samp{L@@}
 @samp{!}
 @samp{C!}
 @samp{2!}
 



        


@node long_fetch, MOVE, L!, MEMORY
@subsection L@@
@pindex L@@
@findex L@@

@noindent
Name: @code{L@@}

@noindent
Stackeffect: faraddr --- n

@noindent
Attributes: 

@noindent
Description:
Leave the 32 bit contents of
segment address pair @samp{faraddr}.


@noindent
See also: @samp{L!}
 @samp{@@}
 @samp{C@@}
 @samp{2@@}
 



        


@node MOVE, P!, long_fetch, MEMORY
@subsection MOVE
@pindex MOVE
@findex MOVE

@noindent
Name: @code{MOVE}

@noindent
Stackeffect: from to count ---

@noindent
Attributes: 

@noindent
Description:
Move the @samp{count}
bytes beginning at address @samp{from} to
address @samp{to}, such that the destination area contains
what the source area contained, regardless of overlaps.
As the Intel 86-family is byte-addressing there are
no restrictions. 

        


@node P!, port_fetch, MOVE, MEMORY
@subsection P!
@pindex P!
@findex P!

@noindent
Name: @code{P!}

@noindent
Stackeffect: n port ---

@noindent
Attributes: 

@noindent
Description:
Store the 32 bit data @samp{n} to the port address
@samp{port}.
In practice on a IBM PC architecture a port address is
10 bits. You can use ports only after asking permission
(using e.g. @samp{ioperm} ) and being super user.


@noindent
See also: @samp{P@@}
 @samp{PC!}
 @samp{PC@@}
 @samp{!}
 



        


@node port_fetch, PC!, P!, MEMORY
@subsection P@@
@pindex P@@
@findex P@@

@noindent
Name: @code{P@@}

@noindent
Stackeffect: port --- n

@noindent
Attributes: 

@noindent
Description:
Fetch the 32 bit contents @samp{n} from the port address
@samp{port}. A port address is always 16 bits.
In practice on a IBM PC architecture a port address is
10 bits. You can use ports only after asking permission
(using e.g. @samp{ioperm} ) and being super user.


@noindent
See also: @samp{P!}
 @samp{PC@@}
 @samp{PC!}
 @samp{@@}
 



        


@node PC!, port_char_fetch, port_fetch, MEMORY
@subsection PC!
@pindex PC!
@findex PC!

@noindent
Name: @code{PC!}

@noindent
Stackeffect: b port ---

@noindent
Attributes: 

@noindent
Description:
Store a byte @samp{b} to the port address
@samp{port}.
A port address is always 16 bits.
In practice on a IBM PC architecture a port address is
10 bits. You can use ports only after asking permission
(using e.g. @samp{ioperm} ) and being super user.


@noindent
See also: @samp{PC@@}
 @samp{P!}
 @samp{P@@}
 @samp{!}
 



        


@node port_char_fetch, TOGGLE, PC!, MEMORY
@subsection PC@@
@pindex PC@@
@findex PC@@

@noindent
Name: @code{PC@@}

@noindent
Stackeffect: port --- b

@noindent
Attributes: 

@noindent
Description:
Fetch a byte @samp{b} from the port address
@samp{port}. A port address is always 16 bits.
In practice on a IBM PC architecture a port address is
10 bits. You can use ports only after asking permission
(using e.g. @samp{ioperm} ) and being super user.


@noindent
See also: @samp{PC!}
 @samp{P@@}
 @samp{P!}
 @samp{@@}
 



        


@node TOGGLE, WITHIN, port_char_fetch, MEMORY
@subsection TOGGLE
@pindex TOGGLE
@findex TOGGLE

@noindent
Name: @code{TOGGLE}

@noindent
Stackeffect: addr b ---

@noindent
Attributes: NFIG

@noindent
Description:
Complement the contents of @samp{addr} by the bit pattern
@samp{b} .

@noindent
See also: @samp{XOR}
 @samp{+! }
 

        


@node WITHIN, , TOGGLE, MEMORY
@subsection WITHIN
@pindex WITHIN
@findex WITHIN

@noindent
Name: @code{WITHIN}

@noindent
Stackeffect: n1 n2 n3 --- ff

@noindent
Attributes: ISO

@noindent
Description:
Return a flag indicating that @samp{n1} is in
the range @samp{n2} (inclusive)
to @samp{n3} (non-inclusive).
This works for signed as well as unsigned numbers.
This is shorthand for: @samp{OVER - >R - R U<} 

@noindent
See also: @samp{<}
 @samp{U<}
 

        




@node MISC, MULTIPLYING,MEMORY, Glossary
@section MISC
     
    The wordset @samp{MISC} contains words that defy categorisation.
    

    

@menu


* .SIGNON  :dot_cpu
* EXECUTE  ::
* NOOP  ::
* TASK  ::
* U0  ::
* _  ::
@end menu
@node dot_cpu, EXECUTE, MISC, MISC
@subsection .SIGNON
@pindex .SIGNON
@findex .SIGNON

@noindent
Name: @code{.SIGNON}

@noindent
Stackeffect: ---

@noindent
Attributes: 

@noindent
Description:
Print a message identifying the version of this Forth.
 The name of the processor known from the environment
query @code{CPU}
@findex CPU
 is printed using the bizarre convention of a
base-36 number. This is a tribute to those FIG-pioneers. 

@noindent
See also: @samp{ABORT}
 @samp{COLD}
 

        


@node EXECUTE, NOOP, dot_cpu, MISC
@subsection EXECUTE
@pindex EXECUTE
@findex EXECUTE

@noindent
Name: @code{EXECUTE}

@noindent
Stackeffect: xt ---

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Execute the definition whose @dfn{execution token}
@cindex execution token
 is
given by @samp{xt} . The
@dfn{code field address}
@cindex code field address
 serves as an execution token.
(It even has offset 0, but one should not assume that a
@dfn{DEA}
@cindex DEA
 is an execution token in portable code.)

@noindent
See also: @samp{'}
 @samp{>CFA}
 

        


@node NOOP, TASK, EXECUTE, MISC
@subsection NOOP
@pindex NOOP
@findex NOOP

@noindent
Name: @code{NOOP}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
Do nothing. Primarily useful as a placeholder.


        


@node TASK, U0, NOOP, MISC
@subsection TASK
@pindex TASK
@findex TASK

@noindent
Name: @code{TASK}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
A no-operation word which marks the boundary between
the forth system and applications. 

@noindent
See also: @samp{COLD}
 
        


@node U0, _, TASK, MISC
@subsection U0
@pindex U0
@findex U0

@noindent
Name: @code{U0}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
A user variable, leaving the start address of the user area. This is
for reference only. What is taken into account by user variables is
the initialisation variable at @samp{0 +ORIGIN} .
This might be used for task switching.


@noindent
See also: @samp{USER}
 @samp{+ORIGIN}
 

        


@node _, , U0, MISC
@subsection _
@pindex _
@findex _

@noindent
Name: @code{_}

@noindent
Stackeffect: --- x

@noindent
Attributes: 

@noindent
Description:
Leave an undefined value @samp{x}.
Presumably it is to be dropped at some time, or it is a place holder.


        




@node MULTIPLYING, OPERATINGSYSTEM,MISC, Glossary
@section MULTIPLYING
     
    The original 16 bits Forth's have problems with overflow (@pxref{OPERATOR}).
Operators with intermediate results of double precision, mostly scaling operators,
solve this and are
present in the @samp{MULTIPLYING} wordset. In this 32-bit Forth
you will have less need.
Formatting is done with @dfn{double}
@cindex double
's exclusively, and relies
on this wordset. Operators with mixed precision and unsigned operators
allow to build arbitrary precision operators from them in @dfn{high level}
@cindex high level
 code.
    

    

@menu


* */MOD  ::
* */  ::
* FM/MOD  ::
* M*  ::
* M/MOD  ::
* SM/REM  ::
* UM*  ::
* UM/MOD  ::
@end menu
@node */MOD, */, MULTIPLYING, MULTIPLYING
@subsection */MOD
@pindex */MOD
@findex */MOD

@noindent
Name: @code{*/MOD}

@noindent
Stackeffect: n1 n2 n3 --- n4 n5

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the quotient @samp{n5} and remainder
@samp{n4} of the operation @samp{n1*n2/n3} (using @dfn{symmetric division}
@cindex symmetric division
).
A double precision
intermediate product is used giving correct results, unless
@samp{n4} or @samp{n5} overflows.
 @samp{n1 n2 * n3 /} gives an incorrect answer
as soon as @samp{n1 n2 *} overflows.


@noindent
See also: @samp{*/}
 @samp{/MOD}
 

        


@node */, FM/MOD, */MOD, MULTIPLYING
@subsection */
@pindex */
@findex */

@noindent
Name: @code{*/}

@noindent
Stackeffect: n1 n2 n3 --- n4

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the ratio @samp{n4 = n1*n2/n3} where all are signed
numbers(using @dfn{symmetric division}
@cindex symmetric division
).
A double precision
intermediate product is used giving correct results, unless
@samp{n4} overflows.


@noindent
See also: @samp{*/MOD}
 @samp{/MOD}
 

        


@node FM/MOD, M*, */, MULTIPLYING
@subsection FM/MOD
@pindex FM/MOD
@findex FM/MOD

@noindent
Name: @code{FM/MOD}

@noindent
Stackeffect: d n1 --- n2 n3

@noindent
Attributes: ISO

@noindent
Description:
A mixed magnitude math operator which leaves the signed
remainder @samp{n2} and signed quotient @samp{n3}
from a double number dividend @samp{d} and divisor
@samp{n1}. This is floored division, i.e.
the remainder takes its sign from the divisor.

@noindent
See also: @samp{SM/REM}
 @samp{M/MOD}
 @samp{/}
 @samp{M*}
 



        


@node M*, M/MOD, FM/MOD, MULTIPLYING
@subsection M*
@pindex M*
@findex M*

@noindent
Name: @code{M*}

@noindent
Stackeffect: n1 n2 --- d

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
A mixed magnitude math operation which leaves the double
number @samp{d} : the signed product of two signed number
@samp{n1} and @samp{n2} .

@noindent
See also: @samp{M/MOD}
 @samp{SM/REM}
 @samp{*}
 


        


@node M/MOD, SM/REM, M*, MULTIPLYING
@subsection M/MOD
@pindex M/MOD
@findex M/MOD

@noindent
Name: @code{M/MOD}

@noindent
Stackeffect: ud1 u2 --- u3 ud4

@noindent
Attributes: CIF,FIG

@noindent
Description:
An unsigned mixed magnitude math operation which leaves a
double quotient @samp{ud4} and remainder @samp{u3} ,
from a double dividend @samp{ud1} and single divisor
@samp{u2}.


@noindent
See also: @samp{UM/MOD}
 @samp{SM/REM}
 @samp{M*}
 


        


@node SM/REM, UM*, M/MOD, MULTIPLYING
@subsection SM/REM
@pindex SM/REM
@findex SM/REM

@noindent
Name: @code{SM/REM}

@noindent
Stackeffect: d n1 --- n2 n3

@noindent
Attributes: ISO

@noindent
Description:
A mixed magnitude math operator which leaves the signed
remainder @samp{n2} and signed quotient @samp{n3}
from a double number dividend @samp{d} and divisor
@samp{n1}. This is a symmetric division, i.e.
the remainder takes its sign from the
dividend.

@noindent
See also: @samp{M/MOD}
 @samp{/}
 @samp{M*}
 


        


@node UM*, UM/MOD, SM/REM, MULTIPLYING
@subsection UM*
@pindex UM*
@findex UM*

@noindent
Name: @code{UM*}

@noindent
Stackeffect: u1 u2 --- ud

@noindent
Attributes: ISO

@noindent
Description:
A mixed magnitude math operation which leaves the double number
@samp{ud} : the unsigned product of two unsigned numbers
@samp{u1} and @samp{u2} .

@noindent
See also: @samp{UM/MOD}
 @samp{M*}
 @samp{*}
 


        


@node UM/MOD, , UM*, MULTIPLYING
@subsection UM/MOD
@pindex UM/MOD
@findex UM/MOD

@noindent
Name: @code{UM/MOD}

@noindent
Stackeffect: ud u1 --- u2 u3

@noindent
Attributes: ISO

@noindent
Description:
Leave the unsigned remainder @samp{u2} and unsigned
quotient @samp{u3} from the unsigned double dividend
@samp{ud} and unsigned divisor @samp{u1} .

@noindent
See also: @samp{UM*}
 @samp{SM/REM}
 @samp{/}
 


        




@node OPERATINGSYSTEM, OPERATOR,MULTIPLYING, Glossary
@section OPERATINGSYSTEM
     
    The wordset @samp{OPERATINGSYSTEM} contains words that call the underlying operating
system or functions available in the BIOS-rom.
    

    

@menu


* ARGS  ::
* BYE  ::
* EXIT-CODE  ::
* LINOS5  ::
* LINOS  ::
* MS  ::
* SHELL  ::
* SYSTEM  ::
* ZEN  ::
@end menu
@node ARGS, BYE, OPERATINGSYSTEM, OPERATINGSYSTEM
@subsection ARGS
@pindex ARGS
@findex ARGS

@noindent
Name: @code{ARGS}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
 Return the addr of @code{ARGS}
@findex ARGS
 a user variable that
contains a system dependant pointer to any arguments that are
passed from the operating system to ciforth during startup.

In this ciforth it points to an area with the argument count,
followed by a a null ended array of arguments strings,
then by a null ended array of environment strings.




@noindent
See also: @samp{SYSTEM}
 
        


@node BYE, EXIT-CODE, ARGS, OPERATINGSYSTEM
@subsection BYE
@pindex BYE
@findex BYE

@noindent
Name: @code{BYE}

@noindent
Stackeffect: ---

@noindent
Attributes: ISO

@noindent
Description:
Return to the host environment Linux.


@noindent
See also: @samp{COLD}
 @samp{EXIT-CODE}
 

        


@node EXIT-CODE, LINOS5, BYE, OPERATINGSYSTEM
@subsection EXIT-CODE
@pindex EXIT-CODE
@findex EXIT-CODE

@noindent
Name: @code{EXIT-CODE}

@noindent
Stackeffect: addr ---

@noindent
Attributes: 

@noindent
Description:
Return @samp{addr} the address of a variable with the
exit code. Its content is passed to the host environment while
going @code{BYE}
@findex BYE
 . It is custom to return zero if there
are no errors.  Linux allows only single byte return
codes.


@noindent
See also: @samp{BYE}
 
        


@node LINOS5, LINOS, EXIT-CODE, OPERATINGSYSTEM
@subsection LINOS5
@pindex LINOS5
@findex LINOS5

@noindent
Name: @code{LINOS5}

@noindent
Stackeffect: n1 n2 n3 n4 n5 n---ret

@noindent
Attributes: 

@noindent
Description:
 Do a Linux system call @samp{n} (man 2) with parameters
@samp{n1 n2 n3 n4 n5}. @samp{ret} is the return
value of the call. If it is negative, it is mostly an error,
such as known by @samp{errno} . This makes available
@b{all} facilities present in Linux.


@noindent
See also: @samp{?ERRUR}
 
        


@node LINOS, MS, LINOS5, OPERATINGSYSTEM
@subsection LINOS
@pindex LINOS
@findex LINOS

@noindent
Name: @code{LINOS}

@noindent
Stackeffect: n1 n2 n3 n---ret

@noindent
Attributes: 

@noindent
Description:
 Do a Linux
system call @samp{n}
(man 2) with parameters @samp{n1 n2 n3}.
@samp{ret} is the return value of the call. If it is negative, it
is mostly an error, such as known by @samp{errno} . This makes
available all facilities present in Linux, except those with 4 or 5 parameters
that are handled by @code{LINOS5}
@findex LINOS5
 .


@noindent
See also: @samp{?ERRUR}
 
        


@node MS, SHELL, LINOS, OPERATINGSYSTEM
@subsection MS
@pindex MS
@findex MS

@noindent
Name: @code{MS}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO

@noindent
Description:
 Wait for @samp{n} milliseconds. 

@noindent
See also: @samp{KEY?}
 
        


@node SHELL, SYSTEM, MS, OPERATINGSYSTEM
@subsection SHELL
@pindex SHELL
@findex SHELL

@noindent
Name: @code{SHELL}

@noindent
Stackeffect: ---addr

@noindent
Attributes: 

@noindent
Description:
Leave the address @samp{addr} of a counted string,
the name of a file that contains the command interpreter,
or shell.
This name may be changed an is used by the
 @code{SYSTEM}
@findex SYSTEM
 command.
The name may contain a path and be at most
252 characters long.
The default name is @samp{/bin/sh} .
 are reserved for
a start up stack.)


@noindent
See also: @samp{SYSTEM}
 
        


@node SYSTEM, ZEN, SHELL, OPERATINGSYSTEM
@subsection SYSTEM
@pindex SYSTEM
@findex SYSTEM

@noindent
Name: @code{SYSTEM}

@noindent
Stackeffect: sc ---

@noindent
Attributes: ISO

@noindent
Description:
Have the operating system execute the command contained
in the string @samp{sc}.



@noindent
See also: @samp{BLOCK}
 @samp{?ERROR}
 @samp{?ERRUR}
 


        


@node ZEN, , SYSTEM, OPERATINGSYSTEM
@subsection ZEN
@pindex ZEN
@findex ZEN

@noindent
Name: @code{ZEN}

@noindent
Stackeffect: sc --- addr

@noindent
Attributes: 

@noindent
Description:
Leaves an address that contains a zero-ended (c-type) equivalent of @samp{sc}.
The same buffer is reused, such that this word is not reentrant.
Use the word immediately, e.g. its intended used is passing parameters
to the operating system. In fact this is @code{RW-BUFFER}
@findex RW-BUFFER
 . 



@noindent
See also: @samp{OPEN-FILE}
 @samp{LINOS}
 @samp{LINOS5}
 


        




@node OPERATOR, OUTPUT,OPERATINGSYSTEM, Glossary
@section OPERATOR
     
    The wordset @samp{OPERATOR} contains the familiar operators for addition, multiplication etc.
The result of the operation is always
an integer number, so division can't be precise.
On ciforth all division operations are compatible with @dfn{symmetric division}
@cindex symmetric division
.

The ISO standard require a Forth to choose between floored or symmetric division
for its standard operations.
Divisions involving negative numbers have an interpretation problem.
In any case we want the combination of @code{/}
@findex /
 and
@code{MOD}
@findex MOD
 (remainder) to be such that you can get the
original @samp{n} back from the two values left by
@samp{n m MOD} and  @samp{n m /} by performing @samp{m * +} .
This is true for all Forth's.
On ciforth the @code{/}
@findex /
 is a @dfn{symmetric division}
@cindex symmetric division
, i.e.
@samp{-n m /} give the same result as @samp{n m /}, but negated.
The foregoing rule now has the consequence that @samp{m MOD}
has @samp{2|m|-1} possible outcomes instead of @samp{|m|} .
This is very worrysome for mathematicians, who stick to the
rule that @samp{m MOD} has @samp{|m|} outcomes:
@samp{0 ... |m|-1}, or @samp{-|m|+1 ... 0 } for
negative numbers. (@dfn{floored division}
@cindex floored division
). 
    

    

@menu


* *  :star
* +  ::
* -  ::
* /MOD  ::
* /  ::
* ABS  ::
* LSHIFT  ::
* MAX  ::
* MIN  ::
* MOD  ::
* NEGATE  ::
* RSHIFT  ::
@end menu
@node star, +, OPERATOR, OPERATOR
@subsection *
@pindex *
@findex *

@noindent
Name: @code{*}

@noindent
Stackeffect: n1 n2 --- n3

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the signed product @samp{n3} of two signed numbers
@samp{n1} and @samp{n2} .

@noindent
See also: @samp{+}
 @samp{-}
 @samp{/}
 @samp{MOD}
 



        


@node +, -, star, OPERATOR
@subsection +
@pindex +
@findex +

@noindent
Name: @code{+}

@noindent
Stackeffect: n1 n2 --- sum

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the sum of @samp{n1} and @samp{n2} .

@noindent
See also: @samp{-}
 @samp{*}
 @samp{/}
 @samp{MOD}
 



        


@node -, /MOD, +, OPERATOR
@subsection -
@pindex -
@findex -

@noindent
Name: @code{-}

@noindent
Stackeffect: n1 n2 --- diff

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the difference of @samp{n1} and @samp{n2} .

@noindent
See also: @samp{NEGATE}
 @samp{+}
 @samp{*}
 @samp{/}
 @samp{MOD}
 




        


@node /MOD, /, -, OPERATOR
@subsection /MOD
@pindex /MOD
@findex /MOD

@noindent
Name: @code{/MOD}

@noindent
Stackeffect: n1 n2 --- rem quot

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the remainder and signed quotient of @samp{n1} and @samp{n2} .
The remainder has the sign of the dividend
(i.e. @dfn{symmetric division}
@cindex symmetric division
). 

@noindent
See also: @samp{*/MOD}
 @samp{*/}
 @samp{SM/REM}
 


        


@node /, ABS, /MOD, OPERATOR
@subsection /
@pindex /
@findex /

@noindent
Name: @code{/}

@noindent
Stackeffect: n1 n2 --- quot

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the signed quotient of @samp{n1} and @samp{n2} .
(using @dfn{symmetric division}
@cindex symmetric division
). 

@noindent
See also: @samp{+}
 @samp{-}
 @samp{*}
 @samp{MOD}
 @samp{*/MOD}
 




        


@node ABS, LSHIFT, /, OPERATOR
@subsection ABS
@pindex ABS
@findex ABS

@noindent
Name: @code{ABS}

@noindent
Stackeffect: n --- u

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the absolute value of @samp{n} as @samp{u} .

@noindent
See also: @samp{DABS}
 
        


@node LSHIFT, MAX, ABS, OPERATOR
@subsection LSHIFT
@pindex LSHIFT
@findex LSHIFT

@noindent
Name: @code{LSHIFT}

@noindent
Stackeffect: u1 n --- u2

@noindent
Attributes: ISO

@noindent
Description:
Perform a @samp{logical shift } of the bits of
@samp{u1} to the left by @samp{n} places.
Put zero into the places uncovered by the shift. 

@noindent
See also: @samp{RSHIFT}
 @samp{2*}
 

        


@node MAX, MIN, LSHIFT, OPERATOR
@subsection MAX
@pindex MAX
@findex MAX

@noindent
Name: @code{MAX}

@noindent
Stackeffect: n1 n2 --- max

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the greater of two numbers.

@noindent
See also: @samp{MIN}
 
        


@node MIN, MOD, MAX, OPERATOR
@subsection MIN
@pindex MIN
@findex MIN

@noindent
Name: @code{MIN}

@noindent
Stackeffect: n1 n2 --- min

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the smaller of two numbers.

@noindent
See also: @samp{MAX}
 
        


@node MOD, NEGATE, MIN, OPERATOR
@subsection MOD
@pindex MOD
@findex MOD

@noindent
Name: @code{MOD}

@noindent
Stackeffect: n1 n2 --- mod

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the remainder of @samp{n1} divided by @samp{n2} , with the same sign
as @samp{n1} (i.e. @dfn{symmetric division}
@cindex symmetric division
).

@noindent
See also: @samp{+}
 @samp{-}
 @samp{*}
 @samp{/}
 @samp{MOD}
 @samp{*/MOD}
 





        


@node NEGATE, RSHIFT, MOD, OPERATOR
@subsection NEGATE
@pindex NEGATE
@findex NEGATE

@noindent
Name: @code{NEGATE}

@noindent
Stackeffect: n1 --- n2

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the two's complement of a number, i.e.
 @samp{n2} is @samp{-n1}

@noindent
See also: @samp{-}
 
        


@node RSHIFT, , NEGATE, OPERATOR
@subsection RSHIFT
@pindex RSHIFT
@findex RSHIFT

@noindent
Name: @code{RSHIFT}

@noindent
Stackeffect: u1 n --- u2

@noindent
Attributes: ISO

@noindent
Description:
Perform a @samp{logical shift } of the bits of
@samp{u1} to the right by @samp{n} places.
Put zero into the places uncovered by the shift. 

@noindent
See also: @samp{LSHIFT}
 @samp{2/}
 

        




@node OUTPUT, PARSING,OPERATOR, Glossary
@section OUTPUT
     
    The wordset @samp{OUTPUT}
contains words to output to the terminal and such.
@xref{FILES}, for disk I/O.
@xref{BLOCKS}, for blocks.
    

    

@menu


* (D.R)  :paren_d_dot_r
* ."  :dot_quote
* .(  :dot_paren
* .R  :dot_r
* .  :dot
* ?  ::
* CR  ::
* D.R  ::
* D.  ::
* EMIT  ::
* ETYPE  ::
* OUT  ::
* SPACES  ::
* SPACE  ::
* TYPE  ::
* U.  :u_dot
@end menu
@node paren_d_dot_r, dot_quote, OUTPUT, OUTPUT
@subsection (D.R)
@pindex (D.R)
@findex (D.R)

@noindent
Name: @code{(D.R)}

@noindent
Stackeffect: d n ---sc

@noindent
Attributes: ISO,FIG

@noindent
Description:
Format a signed double number @samp{d} right aligned in a
field @samp{n} characters wide to the string @samp{sc}.
Enlarge the field, if
needed. So a field length of 0 results effectively in free format.


@noindent
See also: @samp{OUT}
 @samp{D.}
 @samp{D.R}
 


        


@node dot_quote, dot_paren, paren_d_dot_r, OUTPUT
@subsection ."
@pindex ."
@findex ."

@noindent
Name: @code{."}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,I,L0

@noindent
Description:
Used in the form:
  @samp{." cccc"}
In a definition it compiles an in-line string @samp{cccc}
(as if the denotation @code{"cccc"}
@findex "cccc"
 was used)
followed by @code{TYPE}
@findex TYPE
 .
In ciforth @code{."}
@findex ."
 behaves the same way in interpret mode.
In ciforth the number of characters has no limit.
In ciforth @code{."}
@findex ."
 always has an effect
on @code{HERE}
@findex HERE
 during interpretation.
In ISO programs you may only use this word during compilation.
We recommend that @samp{." cccc"} is replaced by @samp{"cccc" TYPE}.
)

@noindent
See also: @samp{OUT}
 
        


@node dot_paren, dot_r, dot_quote, OUTPUT
@subsection .(
@pindex .(
@findex .(

@noindent
Name: @code{.(}

@noindent
No stackeffect

@noindent
Attributes: I,L0

@noindent
Description:
 In ciforth this is an alias for ." , except that the string is closed with @kbd{})
instead of parsed as per @code{"}
@findex "
 .
In ISO programs you may only use this word while interpreting.
We recommend that @samp{.( cccc)} is replaced by @samp{"cccc" TYPE}.


@noindent
See also: @samp{OUT}
 @samp{."}
 

        


@node dot_r, dot, dot_paren, OUTPUT
@subsection .R
@pindex .R
@findex .R

@noindent
Name: @code{.R}

@noindent
Stackeffect: n1 n2 ---

@noindent
Attributes: 

@noindent
Description:
Print a signed number @samp{n1} right aligned in a
field @samp{n2} characters wide. Enlarge the field, if
needed.
So a field length of 0 results effectively in free format.


@noindent
See also: @samp{OUT}
 @samp{.}
 @samp{(D.R)}
 


        


@node dot, ?, dot_r, OUTPUT
@subsection .
@pindex .
@findex .

@noindent
Name: @code{.}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Print the number @samp{n1}
observing the current @code{BASE}
@findex BASE
, followed by a blank.


@noindent
See also: @samp{OUT}
 @samp{U.}
 @samp{.R}
 @samp{D.R}
 @samp{D.}
 @samp{(D.R)}
 





        


@node ?, CR, dot, OUTPUT
@subsection ?
@pindex ?
@findex ?

@noindent
Name: @code{?}

@noindent
Stackeffect: addr ---

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Print the value contained at the address @samp{addr}
observing the current @code{BASE}
@findex BASE
, followed by a blank.


@noindent
See also: @samp{OUT}
 @samp{.}
 

        


@node CR, D.R, ?, OUTPUT
@subsection CR
@pindex CR
@findex CR

@noindent
Name: @code{CR}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Transmit character(s)
to the terminal, that result in
a "carriage return" and a "line feed".
This means that the cursor is positioned at the start
of the next line, if needed the display is scrolled.

@noindent
See also: @samp{OUT}
 
        


@node D.R, D., CR, OUTPUT
@subsection D.R
@pindex D.R
@findex D.R

@noindent
Name: @code{D.R}

@noindent
Stackeffect: d n ---

@noindent
Attributes: ISO,FIG

@noindent
Description:
Print a signed double number @samp{d} right aligned in a
field @samp{n} characters wide. Enlarge the field, if
needed.
So a field length of 0 results effectively in free format.


@noindent
See also: @samp{OUT}
 @samp{D.}
 @samp{(D.R)}
 


        


@node D., EMIT, D.R, OUTPUT
@subsection D.
@pindex D.
@findex D.

@noindent
Name: @code{D.}

@noindent
Stackeffect: d ---

@noindent
Attributes: ISO,FIG,L1

@noindent
Description:
Print the signed double number @samp{d},
observing the current @code{BASE}
@findex BASE
, followed by a blank.


@noindent
See also: @samp{OUT}
 @samp{.}
 @samp{D.R}
 @samp{(D.R)}
 



        


@node EMIT, ETYPE, D., OUTPUT
@subsection EMIT
@pindex EMIT
@findex EMIT

@noindent
Name: @code{EMIT}

@noindent
Stackeffect: c ---

@noindent
Attributes: ISO FIG L0

@noindent
Description:
Transmit ASCII character @samp{c} to the output device.
For this ciforth all terminal I/O goes through @code{TYPE}
@findex TYPE
.
In this ciforth @code{EMIT}
@findex EMIT
 maintains @code{OUT}
@findex OUT
.

@noindent
See also: @samp{TYPE}
 @samp{OUT}
 

        


@node ETYPE, OUT, EMIT, OUTPUT
@subsection ETYPE
@pindex ETYPE
@findex ETYPE

@noindent
Name: @code{ETYPE}

@noindent
Stackeffect: addr count ---

@noindent
Attributes: 

@noindent
Description:
Transmit @samp{count} characters from @samp{addr} to
the standard error device.
It is high level so error output can be redirected, by
@dfn{revectoring}
@cindex revectoring
 it. Or you may use
redirection by Linux. In this
ciforth strings may contain embedded @kbd{LF} 's with the
effect of a new line at that point in the output. 

@noindent
See also: @samp{EMIT}
 @samp{TYPE}
 

        


@node OUT, SPACES, ETYPE, OUTPUT
@subsection OUT
@pindex OUT
@findex OUT

@noindent
Name: @code{OUT}

@noindent
Stackeffect: --- addr

@noindent
Attributes: U

@noindent
Description:
A user variable that reflects the position at the current line
of the output device where the next character transmitted will
appear. The first position is zero. Only an explicit
@code{CR}
@findex CR
 will reset @code{OUT}
@findex OUT
 , not an
@kbd{LF} embedded in a string that is @code{TYPE}
@findex TYPE
d.

@noindent
See also: @samp{EMIT}
 @samp{TYPE}
 @samp{CR}
 


        


@node SPACES, SPACE, OUT, OUTPUT
@subsection SPACES
@pindex SPACES
@findex SPACES

@noindent
Name: @code{SPACES}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
If @samp{n} is greater or equal to zero, display as much
spaces. 

@noindent
See also: @samp{SPACE}
 @samp{OUT}
 

        


@node SPACE, TYPE, SPACES, OUTPUT
@subsection SPACE
@pindex SPACE
@findex SPACE

@noindent
Name: @code{SPACE}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Transmit an ASCII blank to the output device.

@noindent
See also: @samp{EMIT}
 @samp{OUT}
 

        


@node TYPE, u_dot, SPACE, OUTPUT
@subsection TYPE
@pindex TYPE
@findex TYPE

@noindent
Name: @code{TYPE}

@noindent
Stackeffect: addr count ---

@noindent
Attributes: ISO FIG L0

@noindent
Description:
Transmit @samp{count} characters from @samp{addr} to
the output device. All terminal I/O goes through this word. It
is high level so terminal I/O can be redirected, by
@dfn{revectoring}
@cindex revectoring
 it and the usual
redirection or @samp{tee}-ing by Linux. In this
ciforth strings may contain embedded @kbd{LF} 's with the
effect of a new line at that point in the output, however in
that case @code{OUT}
@findex OUT
 is not observed. 

@noindent
See also: @samp{EMIT}
 @samp{OUT}
 @samp{ETYPE}
 


        


@node u_dot, , TYPE, OUTPUT
@subsection U.
@pindex U.
@findex U.

@noindent
Name: @code{U.}

@noindent
Stackeffect: u ---

@noindent
Attributes: ISO

@noindent
Description:
Print the unsigned number @samp{u}
observing the current @code{BASE}
@findex BASE
, followed by a blank.


@noindent
See also: @samp{OUT}
 @samp{.}
 @samp{.R}
 @samp{D.R}
 @samp{D.}
 @samp{(D.R)}
 





        




@node PARSING, SCREEN,OUTPUT, Glossary
@section PARSING
     
    The @dfn{outer interpreter}
@cindex outer interpreter
 is responsible for parsing,
i.e. it gets a word from the @dfn{current input source }
@cindex current input source 
 and interprets or compiles it,
advancing the @code{IN}
@findex IN
  pointer.
The wordset @samp{PARSING} contains the words used by this
interpreter and other words that consume characters from the
input source. In this way the outer interpreter need not be
very smart, because its capabilities can be extended by new
words based on those building blocks.
    

    

@menu


* (PARSE)  :paren_parse
* (WORD)  :paren_word
* (  :paren
* ?BLANK  ::
* CHAR  ::
* EVALUATE  ::
* INTERPRET  ::
* IN[]  :in_next
* SET-SRC  :set_source
* SOURCE  ::
* SRC  ::
* STATE  ::
* WORD  ::
* [CHAR]  :bracket_char_bracket
* [  :left_bracket
* \  :backslash
* ]  :righ_bracket
@end menu
@node paren_parse, paren_word, PARSING, PARSING
@subsection (PARSE)
@pindex (PARSE)
@findex (PARSE)

@noindent
Name: @code{(PARSE)}

@noindent
Stackeffect:  c --- sc 

@noindent
Attributes: 

@noindent
Description:
Scan the @dfn{current input source}
@cindex current input source
 for the character @samp{c} .
Return @samp{sc}: a string from the current position in the
input stream, ending before the first such character,
or at the end of the current input source if it isn't
there. The character is consumed.
As it goes with @dfn{string constant}s, you may not alter
its content, nor assume anything is appended.
So no leading delimiters are skipped.
The difference with an ISO @samp{PARSE} is that
ISO considers control characters a match for a blank.

@noindent
See also: @samp{WORD}
 @samp{(WORD)}
 

        


@node paren_word, paren, paren_parse, PARSING
@subsection (WORD)
@pindex (WORD)
@findex (WORD)

@noindent
Name: @code{(WORD)}

@noindent
Stackeffect: --- sc

@noindent
Attributes: CI L0

@noindent
Description:
Parse the @dfn{current input source}
@cindex current input source
 for a word, i.e.
blank-delimited as per @code{?BLANK}
@findex ?BLANK
 . Skip leading delimiters then
advance the input pointer to past the next delimiter or past
the end of the input source. Leave the word found as a string
constant @samp{sc}. As it goes with string
constants, you may not alter its content, nor assume anything
is appended. Note that this is more deserving of the name
``WORD'' than what is in the ISO standard, that can be used to parse lines.


@noindent
See also: @samp{BLK}
 @samp{WORD}
 @samp{IN}
 


        


@node paren, ?BLANK, paren_word, PARSING
@subsection (
@pindex (
@findex (

@noindent
Name: @code{(}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,I,L0

@noindent
Description:
Used in the form: @samp{( cccc)}. Ignore a comment that
will be delimited by a right parenthesis that must be in the
same input source, i.e. on the same line for terminal input, or
in the same string, block or file, when that is the input. It
is an immediate word, so colon definitions can
be commented too.
A blank after the word @code{(}
@findex (
 is required.

@noindent
See also: @samp{\}
 
        


@node ?BLANK, CHAR, paren, PARSING
@subsection ?BLANK
@pindex ?BLANK
@findex ?BLANK

@noindent
Name: @code{?BLANK}

@noindent
Stackeffect: c --- ff 

@noindent
Attributes: 

@noindent
Description:
For the character @samp{c} return whether this is
considered to be white space into the flag @samp{ff} .
At least the space, ASCII null, the tab and the carriage return and line
feed characters are white space.

@noindent
See also: @samp{BL}
 @samp{SPACE}
 

        


@node CHAR, EVALUATE, ?BLANK, PARSING
@subsection CHAR
@pindex CHAR
@findex CHAR

@noindent
Name: @code{CHAR}

@noindent
Stackeffect: --- c

@noindent
Attributes: ISO,I

@noindent
Description:
Parse a word and
leave @samp{c} the first non blank char of that word in the
input source.
If compiled the searching is done while
the word being compiled is executed.
Because this is so confusing,
it is recommended that
one never compiles or postpones @code{CHAR}
@findex CHAR
.


@noindent
See also: @samp{Prefix_&}
 @samp{[CHAR]}
 @samp{'}
 


        


@node EVALUATE, INTERPRET, CHAR, PARSING
@subsection EVALUATE
@pindex EVALUATE
@findex EVALUATE

@noindent
Name: @code{EVALUATE}

@noindent
Stackeffect: sc --- ??

@noindent
Attributes: ISO

@noindent
Description:
Interpret the content of @samp{sc}. Afterwards return to
the @dfn{current input source}
@cindex current input source
 .

@noindent
See also: @samp{LOAD}
 @samp{INCLUDE}
 @samp{SET-SRC}
 


        


@node INTERPRET, in_next, EVALUATE, PARSING
@subsection INTERPRET
@pindex INTERPRET
@findex INTERPRET

@noindent
Name: @code{INTERPRET}

@noindent
Stackeffect: ?? --- ??

@noindent
Attributes: 

@noindent
Description:
Repeatedly fetch the next text word from the
@samp{current input source} and
execute it (@code{STATE}
@findex STATE
 is not 1) or compile it
(@code{STATE}
@findex STATE
 is 1). A word is blank-delimited and looked
up in the vocabularies of @dfn{search-order}
@cindex search-order
.
Note that the denotations
in the @code{ONLY}
@findex ONLY
 wordlist match numbers.
If it is not found at all, it
is an @code{ERROR}
@findex ERROR
.
A @dfn{denotation}
@cindex denotation
 is a number, a double number, a
character or a string etc. Denotations are handled
respectively by the words
@code{0}
@findex 0
 ... @code{F}
@findex F
 @code{&}
@findex &
 @code{"}
@findex "
 and
any other word of the
@code{ONLY}
@findex ONLY
 wordlist, depending on the first
character or characters.

A number is converted according to the current base.
If a decimal point is found as part of a number, the number
value that is left is a double number, otherwise it is a single
number. Comma's are ignored in ciforth.
)


@noindent
See also: @samp{WORD}
 @samp{NUMBER}
 @samp{BLK}
 @samp{DPL}
 



        


@node in_next, set_source, INTERPRET, PARSING
@subsection IN[]
@pindex IN[]
@findex IN[]

@noindent
Name: @code{IN[]}

@noindent
Stackeffect:  ---addr c

@noindent
Attributes: CI L0

@noindent
Description:
Parse the @dfn{current input source}
@cindex current input source
 leaving the next
character @samp{c} and its address @samp{addr} . If
at the end of the input source, leave a pointer past the end
and a zero. Advance the input pointer to the next character.


@noindent
See also: @samp{BLK}
 @samp{WORD}
 @samp{IN}
 


        


@node set_source, SOURCE, in_next, PARSING
@subsection SET-SRC
@pindex SET-SRC
@findex SET-SRC

@noindent
Name: @code{SET-SRC}

@noindent
Stackeffect: sc ---

@noindent
Attributes: 

@noindent
Description:
Make the @dfn{string constant} @samp{sc} the
@dfn{current input source}
@cindex current input source
. This input is chained, i.e.
exhausting it has the same effect as exhausting the input that
called @code{SET-SRC}
@findex SET-SRC
. In practice this word
is almost always followed by a call to
@code{INTERPRET}
@findex INTERPRET
.

@noindent
See also: @samp{EVALUATE}
 @samp{INTERPRET}
 

        


@node SOURCE, SRC, set_source, PARSING
@subsection SOURCE
@pindex SOURCE
@findex SOURCE

@noindent
Name: @code{SOURCE}

@noindent
Stackeffect:  --- addr n1

@noindent
Attributes: ISO

@noindent
Description:
Return the address and length of the @dfn{current input source}
@cindex current input source
 .


@noindent
See also: @samp{SRC}
 @samp{SOURCE-ID}
 

        


@node SRC, STATE, SOURCE, PARSING
@subsection SRC
@pindex SRC
@findex SRC

@noindent
Name: @code{SRC}

@noindent
Stackeffect: addr ---

@noindent
Attributes: 

@noindent
Description:
Return the address @samp{addr}
of the @dfn{current input source}
@cindex current input source
 specification,
allocated in the user area. It consists of three cells: the
lowest and non-inclusive highest address of the parse area
the non-inclusive highest address of the parse area
and a pointer to the next character to be parsed.
 Changing @samp{SRC} takes immediate effect,
and must be atomic, by using @samp{RESTORE-INPUT},
or changing only the third cell.
The third cell has the alias
@samp{IN} .

Words like @samp{>IN BLK SOURCE SOURCE-ID} are secondary,
and return their output by ``second-guessing'' @samp{SRC} .

@noindent
See also: @samp{BLK}
 @samp{SOURCE-ID}
 

        


@node STATE, WORD, SRC, PARSING
@subsection STATE
@pindex STATE
@findex STATE

@noindent
Name: @code{STATE}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO,L0,U

@noindent
Description:
A user variable containing the compilation state. A non-zero value
indicates compilation.

        


@node WORD, bracket_char_bracket, STATE, PARSING
@subsection WORD
@pindex WORD
@findex WORD

@noindent
Name: @code{WORD}

@noindent
Stackeffect: c ---addr

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Parse the @samp{current input source} using @samp{c} for a delimiter.
Skip leading delimiters then advance the input pointer to past
the next delimiter or past the end of the input source.
Leave at @samp{addr} a copy of the string,
that was surrounded by @samp{c} in the input source.
This is an oldfashioned string to be fetched by @code{COUNT}
@findex COUNT
 , not @code{$@@}
@findex $@@
 .
In ciforth the character string is positioned
at the dictionary buffer @code{HERE}
@findex HERE
 .
@code{WORD}
@findex WORD
 leaves the character count in the first byte, the characters, and
ends with two or more blanks.


@noindent
See also: @samp{(WORD)}
 @samp{(PARSE)}
 @samp{BLK }
 @samp{IN}
 



        


@node bracket_char_bracket, left_bracket, WORD, PARSING
@subsection [CHAR]
@pindex [CHAR]
@findex [CHAR]

@noindent
Name: @code{[CHAR]}

@noindent
Stackeffect: --- c

@noindent
Attributes: ISO I

@noindent
Description:
A compiling word. Parse a word.  Add the run time behaviour:
leave @samp{c}, the first non blank char of that word in the
input source. In ciforth this word works also in interpret mode.

@noindent
See also: @samp{Prefix_&}
 @samp{CHAR}
 

        


@node left_bracket, backslash, bracket_char_bracket, PARSING
@subsection [
@pindex [
@findex [

@noindent
Name: @code{[}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,I,L1

@noindent
Description:
Used in a colon-definition in form:
@example
@iftex
@cartouche
:  xxx    [  words   ]    more   ;
@end cartouche
@end iftex
@ifinfo
:  xxx    [  words   ]    more   ;
@end ifinfo
@end example
Suspend compilation. The words after @code{[}
@findex [
 are executed, not compiled.
This allows calculation or compilation exceptions before resuming
compilation with @code{]}
@findex ]


@noindent
See also: @samp{LITERAL }
 @samp{]}
 

        


@node backslash, righ_bracket, left_bracket, PARSING
@subsection \
@pindex \
@findex \

@noindent
Name: @code{\}

@noindent
No stackeffect

@noindent
Attributes: ISO,I,L0

@noindent
Description:
Used in the form:
@samp{\ cccc}
Ignore a comment that will be delimited by the end of the current line.
May occur during execution or in a colon-definition.
Blank space after the word @code{\}
@findex \
 is required.

@noindent
See also: @samp{(}
 
        


@node righ_bracket, , backslash, PARSING
@subsection ]
@pindex ]
@findex ]

@noindent
Name: @code{]}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,L1

@noindent
Description:
Resume compilation, to the completion of a colon-definition.

@noindent
See also: @samp{[}
 
        




@node SCREEN, SECURITY,PARSING, Glossary
@section SCREEN
     
    Most of the @dfn{blocks} mass storage is used for @dfn{screen}
@cindex screen
's that
have 16 lines of 64 characters. They are used for source code
and documentation.
Each screen is one @code{BLOCK}
@findex BLOCK
 as required by ISO.
The @samp{SCREEN} wordset contains facilities to view screens,
and @dfn{load}
@cindex load
 them, that is compiling them and thus extending
the base system.
A system is customized by loading source screens, possibly one of
these extension is a text editor for screens.
    

    

@menu


* (LINE)  :paren_line
* -->  :next_screen
* C/L  ::
* INDEX  ::
* LIST  ::
* LOAD  ::
* LOCK  ::
* R#  ::
* SCR  ::
* THRU  ::
* TRIAD  ::
* UNLOCK  ::
* (BLK)  :paren_blk
* BLK  ::
@end menu
@node paren_line, next_screen, SCREEN, SCREEN
@subsection (LINE)
@pindex (LINE)
@findex (LINE)

@noindent
Name: @code{(LINE)}

@noindent
Stackeffect: n1 n2 --- sc 

@noindent
Attributes: 

@noindent
Description:
Convert the line number @samp{n1} and the screen
@samp{n2} to a string @samp{sc} the content of the
line (without the trailing new line). 

@noindent
See also: @samp{LINE}
 
        


@node next_screen, C/L, paren_line, SCREEN
@subsection -->
@pindex -->
@findex -->

@noindent
Name: @code{-->}

@noindent
No stackeffect

@noindent
Attributes: I,L0

@noindent
Description:
Continue interpretation with the next disc screen. If the
current input source is not from a block, a crash will ensue.
If this new screen is left by throw of an exception, the
screen may remain locked until a @code{QUIT}
@findex QUIT
, or any
uncaught exception. 

@noindent
See also: @samp{LOCK}
 @samp{CATCH}
 @samp{LOAD}
 


        


@node C/L, INDEX, next_screen, SCREEN
@subsection C/L
@pindex C/L
@findex C/L

@noindent
Name: @code{C/L}

@noindent
Stackeffect: --- c

@noindent
Attributes: 

@noindent
Description:
A constant that leaves the number of characters on a line of a
standard screen: 64. The last character of each line is a @kbd{LF}. 

@noindent
See also: @samp{LIST}
 @samp{LINE}
 

        


@node INDEX, LIST, C/L, SCREEN
@subsection INDEX
@pindex INDEX
@findex INDEX

@noindent
Name: @code{INDEX}

@noindent
Stackeffect: from to ---

@noindent
Attributes: 

@noindent
Description:
Print the first line of each screen over the inclusive
range
@samp{from} , @samp{to} . This is used to view the
comment lines of an area of text on disc screens.

@noindent
See also: @samp{LIST}
 
        


@node LIST, LOAD, INDEX, SCREEN
@subsection LIST
@pindex LIST
@findex LIST

@noindent
Name: @code{LIST}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Display the ASCII text of @dfn{screen}
@cindex screen
 @samp{n}.
The number of the screen is always printed in decimal.
@code{SCR}
@findex SCR
 contains the screen number during and after this process.

@noindent
See also: @samp{BLOCK}
 
        


@node LOAD, LOCK, LIST, SCREEN
@subsection LOAD
@pindex LOAD
@findex LOAD

@noindent
Name: @code{LOAD}

@noindent
Stackeffect: n --- ??

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Interrupt the @dfn{current input source}
@cindex current input source
 in order to
interpret screen @samp{n} .
The stack changes in according with the words executed.
At the end of the screen, barring errors or forced changes,
it continues with the interrupted input source.

@noindent
See also: @samp{BLOCK}
 @samp{#BUFF}
 @samp{THRU}
 @samp{QUIT}
 @samp{EXIT}
 @samp{-->}
 @samp{LIST}
 






        


@node LOCK, R#, LOAD, SCREEN
@subsection LOCK
@pindex LOCK
@findex LOCK

@noindent
Name: @code{LOCK}

@noindent
Stackeffect:  n ---

@noindent
Attributes: CI

@noindent
Description:
Lock the block @samp{n}.
Multiple locks are possible, and require multiple unlocks.
Probably, because it
is to become the @dfn{current input source}
@cindex current input source
.
The result is that its buffer will not be reclaimed
until an @code{UNLOCK}
@findex UNLOCK
 occurs.

@noindent
See also: @samp{BLOCK}
 @samp{UNLOCK}
 @samp{#BUFF}
 


        


@node R#, SCR, LOCK, SCREEN
@subsection R#
@pindex R#
@findex R#

@noindent
Name: @code{R#}

@noindent
Stackeffect: --- addr

@noindent
Attributes: U

@noindent
Description:
A user variable which may contain the location of an editing cursor,
or other file related function.
Unused in the kernel of ciforth.

        


@node SCR, THRU, R#, SCREEN
@subsection SCR
@pindex SCR
@findex SCR

@noindent
Name: @code{SCR}

@noindent
Stackeffect: --- addr

@noindent
Attributes: U

@noindent
Description:
A user variable containing the screen number most recently reference
by @code{LIST}
@findex LIST
 .

@noindent
See also: @samp{BLOCK}
 
        


@node THRU, TRIAD, SCR, SCREEN
@subsection THRU
@pindex THRU
@findex THRU

@noindent
Name: @code{THRU}

@noindent
Stackeffect: n1 n2 --- ??

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Interrupt the @dfn{current input source}
@cindex current input source
 in order to
interpret screen @samp{n1} through @samp{n2}
(inclusive).
The stack changes in according with the words executed.
At the end of the screens, barring errors or forced changes,
it continues with the interrupted input source.

@noindent
See also: @samp{#BUFF}
 @samp{BLOCK}
 @samp{LOAD}
 @samp{QUIT}
 @samp{EXIT}
 @samp{-->}
 





        


@node TRIAD, UNLOCK, THRU, SCREEN
@subsection TRIAD
@pindex TRIAD
@findex TRIAD

@noindent
Name: @code{TRIAD}

@noindent
Stackeffect: scr ---

@noindent
Attributes: 

@noindent
Description:
Display on the selected output device the three screens which
include that numbered @samp{scr} , beginning with a screen evenly divisible
by three. Output is suitable for source text records, and includes a
reference line at the bottom taken from line 0 of the first error screen.

@noindent
See also: @samp{MESSAGE}
 @samp{ERRSCR }
 

        


@node UNLOCK, paren_blk, TRIAD, SCREEN
@subsection UNLOCK
@pindex UNLOCK
@findex UNLOCK

@noindent
Name: @code{UNLOCK}

@noindent
Stackeffect:  n ---

@noindent
Attributes: CI

@noindent
Description:
Unlock the block @samp{n}.
Probably, because it
is no longer the @dfn{current input source}
@cindex current input source
.
The result is that its buffer can again be reclaimed.
Unlocking without a previous lock may lead to a crash.


@noindent
See also: @samp{LOCK}
 @samp{#BUFF}
 

        


@node paren_blk, BLK, UNLOCK, SCREEN
@subsection (BLK)
@pindex (BLK)
@findex (BLK)

@noindent
Name: @code{(BLK)}

@noindent
Stackeffect: --- addr

@noindent
Attributes: U

@noindent
Description:
When the standard word @code{BLK}
@findex BLK
 is used, this user variable
reflects the state of the @samp{current input source}.
It indicates the block number being interpreted, or
zero, if input is being taken from the terminal input buffer.
Changing @code{BLK}
@findex BLK
 has no effect, and its content must be fetched before
the @dfn{current input source}
@cindex current input source
 has changed.

@noindent
See also: @samp{BLOCK}
 @samp{TIB}
 

        


@node BLK, , paren_blk, SCREEN
@subsection BLK
@pindex BLK
@findex BLK

@noindent
Name: @code{BLK}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO

@noindent
Description:
When the standard word @code{BLK}
@findex BLK
 is used, the content
of the user variable @samp{(BLK)} is refreshed to reflect
the state of the current input source and its address is returned
in @samp{addr} .
It indicates the block
number being interpreted, or zero, if input is being taken from
the terminal input buffer. In ciforth
changing the content at
@samp{addr} has no effect, and its content must be
fetched before the @dfn{current input source}
@cindex current input source
 has
changed.

@noindent
See also: @samp{BLOCK}
 @samp{TIB}
 

        




@node SECURITY, STACKS,SCREEN, Glossary
@section SECURITY
     
    The wordset @samp{SECURITY} contains words that are used by control
words to abort with an error message if the control structure is not
correct. Some say that this is not Forth-like.
You only need to know them if you want to extend the
@samp{CONTROL} wordset.


    

    

@menu


* !CSP  ::
* ?COMP  ::
* ?CSP  ::
* ?DELIM  ::
* ?EXEC  ::
* ?LOADING  ::
* ?PAIRS  ::
* ?STACK  ::
* CSP  ::
@end menu
@node !CSP, ?COMP, SECURITY, SECURITY
@subsection !CSP
@pindex !CSP
@findex !CSP

@noindent
Name: @code{!CSP}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
Save the stack position in @code{CSP}
@findex CSP
. Used as part of the compiler
security.

        


@node ?COMP, ?CSP, !CSP, SECURITY
@subsection ?COMP
@pindex ?COMP
@findex ?COMP

@noindent
Name: @code{?COMP}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
Issue error message if not compiling.

@noindent
See also: @samp{?ERROR}
 
        


@node ?CSP, ?DELIM, ?COMP, SECURITY
@subsection ?CSP
@pindex ?CSP
@findex ?CSP

@noindent
Name: @code{?CSP}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
Issue error message if stack position differs from value saved in
@samp{CSP} .

        


@node ?DELIM, ?EXEC, ?CSP, SECURITY
@subsection ?DELIM
@pindex ?DELIM
@findex ?DELIM

@noindent
Name: @code{?DELIM}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
Parse a character and issue error message if it is not a blank
delimiter.

        


@node ?EXEC, ?LOADING, ?DELIM, SECURITY
@subsection ?EXEC
@pindex ?EXEC
@findex ?EXEC

@noindent
Name: @code{?EXEC}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
Issue an error message if not executing.

@noindent
See also: @samp{?ERROR}
 
        


@node ?LOADING, ?PAIRS, ?EXEC, SECURITY
@subsection ?LOADING
@pindex ?LOADING
@findex ?LOADING

@noindent
Name: @code{?LOADING}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
Issue an error message if not loading

@noindent
See also: @samp{?ERROR}
 
        


@node ?PAIRS, ?STACK, ?LOADING, SECURITY
@subsection ?PAIRS
@pindex ?PAIRS
@findex ?PAIRS

@noindent
Name: @code{?PAIRS}

@noindent
Stackeffect: n1 n2 ---

@noindent
Attributes: 

@noindent
Description:
Issue an error message if @samp{n1} does not equal @samp{n2} . The message
indicates that compiled conditionals do not match.

@noindent
See also: @samp{?ERROR}
 
        


@node ?STACK, CSP, ?PAIRS, SECURITY
@subsection ?STACK
@pindex ?STACK
@findex ?STACK

@noindent
Name: @code{?STACK}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
Issue an error message if the stack is out of bounds.

@noindent
See also: @samp{?ERROR}
 
        


@node CSP, , ?STACK, SECURITY
@subsection CSP
@pindex CSP
@findex CSP

@noindent
Name: @code{CSP}

@noindent
Stackeffect: ---- addr

@noindent
Attributes: U

@noindent
Description:
A user variable temporarily storing the stack pointer position, for
compilation error checking.

        




@node STACKS, STRING,SECURITY, Glossary
@section STACKS
     
    The wordset @samp{STACKS} contains words related to the
@dfn{data stack}
@cindex data stack
 and @dfn{return stack}
@cindex return stack
.
Words can be moved between both stacks.
Stacks can be reinitialised and the value used to initialise the
@dfn{stack pointer}
@cindex stack pointer
's can be altered.
    

    

@menu


* .S  :dot_s
* >R  ::
* DEPTH  ::
* DSP!  ::
* DSP@@  :d_s_p_fetch
* R0  ::
* R>  ::
* R@@  :r_fetch
* RDROP  ::
* RSP!  ::
* RSP@@  :r_s_p_fetch
* S0  ::
@end menu
@node dot_s, >R, STACKS, STACKS
@subsection .S
@pindex .S
@findex .S

@noindent
Name: @code{.S}

@noindent
Stackeffect: from to ---

@noindent
Attributes: 

@noindent
Description:
Print the stack, in the current base.

@noindent
See also: @samp{LIST}
 
        


@node >R, DEPTH, dot_s, STACKS
@subsection >R
@pindex >R
@findex >R

@noindent
Name: @code{>R}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,FIG,C,L0

@noindent
Description:
Remove a number from the @dfn{data stack}
@cindex data stack
 and place as the most
accessable on the @dfn{return stack}
@cindex return stack
. Use should be balanced with @code{R>}
@findex R>
 in
the same definition.

@noindent
See also: @samp{R@@}
 
        


@node DEPTH, DSP!, >R, STACKS
@subsection DEPTH
@pindex DEPTH
@findex DEPTH

@noindent
Name: @code{DEPTH}

@noindent
Stackeffect: --- n1

@noindent
Attributes: ISO

@noindent
Description:
Leave into @samp{n1} the number of items on the data stack,
before @samp{n1} was pushed.

@noindent
See also: @samp{DSP@@}
 
        


@node DSP!, d_s_p_fetch, DEPTH, STACKS
@subsection DSP!
@pindex DSP!
@findex DSP!

@noindent
Name: @code{DSP!}

@noindent
Stackeffect: addr ---

@noindent
Attributes: 

@noindent
Description:
Initialize the data stack pointer with @samp{addr} .

@noindent
See also: @samp{DSP@@}
 
        


@node d_s_p_fetch, R0, DSP!, STACKS
@subsection DSP@@
@pindex DSP@@
@findex DSP@@

@noindent
Name: @code{DSP@@}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
Return the address @samp{addr} of the data stack position,
as it was before @code{DSP@@}
@findex DSP@@
 was executed.


@noindent
See also: @samp{S0}
 @samp{DSP!}
 

        


@node R0, R>, d_s_p_fetch, STACKS
@subsection R0
@pindex R0
@findex R0

@noindent
Name: @code{R0}

@noindent
Stackeffect: --- addr

@noindent
Attributes: U

@noindent
Description:
A user variable containing the initial location of the return stack. 

@noindent
See also: @samp{RSP!}
 
        


@node R>, r_fetch, R0, STACKS
@subsection R>
@pindex R>
@findex R>

@noindent
Name: @code{R>}

@noindent
Stackeffect: --- n

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Remove the top value from the @dfn{return stack}
@cindex return stack
 and leave it on the
@dfn{data stack}
@cindex data stack
 . 

@noindent
See also: @samp{>R}
 @samp{R@@}
 

        


@node r_fetch, RDROP, R>, STACKS
@subsection R@@
@pindex R@@
@findex R@@

@noindent
Name: @code{R@@}

@noindent
Stackeffect: --- n

@noindent
Attributes: ISO

@noindent
Description:
Copy the top of the return stack to the data stack.

@noindent
See also: @samp{>R}
 @samp{<R}
 

        


@node RDROP, RSP!, r_fetch, STACKS
@subsection RDROP
@pindex RDROP
@findex RDROP

@noindent
Name: @code{RDROP}

@noindent
Stackeffect: --- 

@noindent
Attributes: 

@noindent
Description:
Remove the top value from the return stack.

@noindent
See also: @samp{>R}
 @samp{R@@}
 @samp{R>}
 


        


@node RSP!, r_s_p_fetch, RDROP, STACKS
@subsection RSP!
@pindex RSP!
@findex RSP!

@noindent
Name: @code{RSP!}

@noindent
Stackeffect: addr ---

@noindent
Attributes: 

@noindent
Description:
Initialize the return stack
pointer with @samp{addr}.

@noindent
See also: @samp{RSP@@}
 
        


@node r_s_p_fetch, S0, RSP!, STACKS
@subsection RSP@@
@pindex RSP@@
@findex RSP@@

@noindent
Name: @code{RSP@@}

@noindent
Stackeffect: --- addr

@noindent
Attributes: 

@noindent
Description:
Return the address @samp{addr} of the current return
stack position, i.e. pointing the current topmost value.

@noindent
See also: @samp{R0}
 @samp{RSP!}
 

        


@node S0, , r_s_p_fetch, STACKS
@subsection S0
@pindex S0
@findex S0

@noindent
Name: @code{S0}

@noindent
Stackeffect: --- addr

@noindent
Attributes: U

@noindent
Description:
A user variable that contains the initial value for the data stack
pointer.

@noindent
See also: @samp{DSP!}
 
        




@node STRING, SUPERFLUOUS,STACKS, Glossary
@section STRING
     
    The wordset @samp{STRING} contains words that manipulate
strings of characters.
In ciforth strings have been given their civil rights.
So they are entitled to a @dfn{denotation}
@cindex denotation
 (the word @code{"}
@findex "
 )
and have a proper fetch and store.
An (address length) pair is considered a @dfn{string constant}
@cindex string constant
.
It may be trimmed, but the data referring to via the address must not be changed.
It can be stored in a buffer, a @dfn{string variable}
@cindex string variable
, that contains
in its first cell the count. Formerly this was in the first byte, and these
are called @dfn{old fashioned string}
@cindex old fashioned string
's  (or less
flatteringly: brain-damaged).

    

    

@menu


* $!-BD  ::
* $!  ::
* $+!  ::
* $,  :string_comma
* $@@  :string_fetch
* $C+  ::
* $I  ::
* $S  ::
* -TRAILING  ::
* BL  ::
* COUNT  ::
* S"  :s_quote
@end menu
@node $!-BD, $!, STRING, STRING
@subsection $!-BD
@pindex $!-BD
@findex $!-BD

@noindent
Name: @code{$!-BD}

@noindent
Stackeffect: sc addr ---

@noindent
Attributes: 

@noindent
Description:
Store a @dfn{string constant} @samp{sc} in the
@dfn{old fashioned string}
@cindex old fashioned string
 variable at address
@samp{addr}, i.e. it can be fetched with
@code{COUNT}
@findex COUNT
.  (Where would that BD come
from?)

@noindent
See also: @samp{COUNT}
 @samp{$!}
 

        


@node $!, $+!, $!-BD, STRING
@subsection $!
@pindex $!
@findex $!

@noindent
Name: @code{$!}

@noindent
Stackeffect: sc addr ---

@noindent
Attributes: 

@noindent
Description:
Store a @dfn{string constant} @samp{sc}
in the string variable at address @samp{addr}.

@noindent
See also: @samp{$@@}
 @samp{$+!}
 @samp{$C+}
 


        


@node $+!, string_comma, $!, STRING
@subsection $+!
@pindex $+!
@findex $+!

@noindent
Name: @code{$+!}

@noindent
Stackeffect: sc addr ---

@noindent
Attributes: 

@noindent
Description:
Append a @dfn{string constant} @samp{sc}
to the string variable at address @samp{addr}.

@noindent
See also: @samp{$@@}
 @samp{$!}
 @samp{$C+}
 


        


@node string_comma, string_fetch, $+!, STRING
@subsection $,
@pindex $,
@findex $,

@noindent
Name: @code{$,}

@noindent
Stackeffect: sc --- addr

@noindent
Attributes: 

@noindent
Description:
Allocate and store a @dfn{string constant} @samp{sc}
in the dictionary and leave its address @samp{addr}.

@noindent
See also: @samp{$@@}
 @samp{$!}
 

        


@node string_fetch, $C+, string_comma, STRING
@subsection $@@
@pindex $@@
@findex $@@

@noindent
Name: @code{$@@}

@noindent
Stackeffect: addr --- sc

@noindent
Attributes: 

@noindent
Description:
 From address @samp{addr} fetch a @dfn{string constant} @samp{sc} .

@noindent
See also: @samp{$@@}
 @samp{$!}
 @samp{$+!}
 @samp{$C+}
 



        


@node $C+, $I, string_fetch, STRING
@subsection $C+
@pindex $C+
@findex $C+

@noindent
Name: @code{$C+}

@noindent
Stackeffect: c addr ---

@noindent
Attributes: 

@noindent
Description:
Append a char @samp{c}
to the string variable at address @samp{addr}.

@noindent
See also: @samp{$@@}
 @samp{$!}
 @samp{$+!}
 


        


@node $I, $S, $C+, STRING
@subsection $I
@pindex $I
@findex $I

@noindent
Name: @code{$I}

@noindent
Stackeffect: sc c -- addr

@noindent
Attributes: 

@noindent
Description:
Find the first @samp{c} in the @dfn{string constant} @samp{sc} and
return its @samp{addr} if present.
Otherwise return a @dfn{nil pointer}.
A null string (0 0) or an empty string are allowed, and result in not found. 

@noindent
See also: @samp{$S}
 @samp{CORA}
 

        


@node $S, -TRAILING, $I, STRING
@subsection $S
@pindex $S
@findex $S

@noindent
Name: @code{$S}

@noindent
Stackeffect: sc c -- sc1 sc2

@noindent
Attributes: 

@noindent
Description:
Find the first @samp{c} in the @dfn{string constant}
@samp{sc} and split it at that address. Return the strings
after and before @samp{c} into @samp{sc1} and
@samp{sc2} respectively. If the character is not present
@samp{sc1} is a null string (its address is
zero) and @samp{sc2} is the original string.
Both @samp{sc1} and @samp{sc2} may be
empty strings (i.e. their count is zero), if @samp{c} is
the last or first character in @samp{sc} . 

@noindent
See also: @samp{$I}
 @samp{CORA}
 

        


@node -TRAILING, BL, $S, STRING
@subsection -TRAILING
@pindex -TRAILING
@findex -TRAILING

@noindent
Name: @code{-TRAILING}

@noindent
Stackeffect: sc1 --- sc2

@noindent
Attributes: ISO

@noindent
Description:
Trim the @dfn{string constant} @samp{sc1} so as not to contain
trailing blank space and leave it as @samp{sc2} . 

@noindent
See also: @samp{?BLANK}
 
        


@node BL, COUNT, -TRAILING, STRING
@subsection BL
@pindex BL
@findex BL

@noindent
Name: @code{BL}

@noindent
Stackeffect: --- c

@noindent
Attributes: ISO.FIG

@noindent
Description:
 A constant that leaves the
   ASCII value for "blank".

        


@node COUNT, s_quote, BL, STRING
@subsection COUNT
@pindex COUNT
@findex COUNT

@noindent
Name: @code{COUNT}

@noindent
Stackeffect: addr1 --- addr2 n

@noindent
Attributes: ISO,FIG,L0

@noindent
Description:
Leave the byte address @samp{addr2} and byte count @samp{n} of a message text
beginning at address @samp{addr1} . It is presumed that the first byte at
@samp{addr1} contains the text byte count and the actual text starts with
the second byte. Alternatively stated, fetch a
@dfn{string constant} @samp{addr n} from
the brain damaged string variable at @samp{addr1} .


@noindent
See also: @samp{TYPE}
 
        


@node s_quote, , COUNT, STRING
@subsection S"
@pindex S"
@findex S"

@noindent
Name: @code{S"}

@noindent
Stackeffect:  --- addr1 n

@noindent
Attributes: ISO,L0

@noindent
Description:
 Used in the form:
  @samp{S" cccc"}
Leaves an in-line string @samp{cccc} (delimited by the
trailing @kbd{"}) as a constant string @samp{addr1
n} . In ciforth the number of characters has no limit and
using @samp{S"} has always an effect on
@code{HERE}
@findex HERE
, even during interpretation.
In ciforth a @kbd{"} can be embedded in a string by doubling it.
In non-portable code denotations are recommended.


@noindent
See also: @samp{"}
 
        




@node SUPERFLUOUS, WORDLISTS,STRING, Glossary
@section SUPERFLUOUS
     
    The wordset @samp{SUPERFLUOUS} contains words that are superfluous,
because they are equivalent to small sequences of code.
Traditionally one hoped to speed Forth up by coding these words
directly.
    

    

@menu


* 0  ::
* 1+  ::
* 1-  ::
* 2*  ::
* 2/  ::
* Number_1  ::
* Number_2  ::
@end menu
@node 0, 1+, SUPERFLUOUS, SUPERFLUOUS
@subsection 0
@pindex 0
@findex 0

@noindent
Name: @code{0}

@noindent
Stackeffect: --- 0

@noindent
Attributes: 

@noindent
Description:
Leave the number 0. 

@noindent
See also: @samp{CONSTANT}
 
        


@node 1+, 1-, 0, SUPERFLUOUS
@subsection 1+
@pindex 1+
@findex 1+

@noindent
Name: @code{1+}

@noindent
Stackeffect: n1 --- n2

@noindent
Attributes: L1

@noindent
Description:
This is shorthand for ``@samp{1} @code{+}
@findex +
''.

@noindent
See also: @samp{CELL+}
 @samp{1-}
 

        


@node 1-, 2*, 1+, SUPERFLUOUS
@subsection 1-
@pindex 1-
@findex 1-

@noindent
Name: @code{1-}

@noindent
Stackeffect: n1 --- n2

@noindent
Attributes: ISO

@noindent
Description:
 This is shorthand for @samp{1 -}. 

@noindent
See also: @samp{1+ }
 
        


@node 2*, 2/, 1-, SUPERFLUOUS
@subsection 2*
@pindex 2*
@findex 2*

@noindent
Name: @code{2*}

@noindent
Stackeffect: n1 --- n2

@noindent
Attributes: ISO

@noindent
Description:
Perform an arithmetical  left.
The bit pattern of @samp{n1} is shifted to the left,
with a result identical to @samp{1 LSHIFT}.
This word should not be used.

@noindent
See also: @samp{2/ }
 
        


@node 2/, Number_1, 2*, SUPERFLUOUS
@subsection 2/
@pindex 2/
@findex 2/

@noindent
Name: @code{2/}

@noindent
Stackeffect: n1 --- n2

@noindent
Attributes: ISO

@noindent
Description:
Perform an arithmetical  right.
The bit pattern of @samp{n1} is shifted to the right, except that
the left most bit (``sign bit'') remains the same.
 This is the same as @samp{S>D 2 FM/MOD SWAP
DROP}. It is not the same as @samp{2 /} , nor is it the
same as @samp{1 RSHIFT}. This confusing word should never
be used.

@noindent
See also: @samp{2* }
 
        


@node Number_1, Number_2, 2/, SUPERFLUOUS
@subsection Number_1
@pindex Number_1
@findex Number_1

@noindent
Name: @code{Number_1}

@noindent
Stackeffect: --- 1

@noindent
Attributes: 

@noindent
Description:
Leave the number 1. 

@noindent
See also: @samp{CONSTANT}
 
        


@node Number_2, , Number_1, SUPERFLUOUS
@subsection Number_2
@pindex Number_2
@findex Number_2

@noindent
Name: @code{Number_2}

@noindent
Stackeffect: --- 2

@noindent
Attributes: 

@noindent
Description:
Leave the number 2. 

@noindent
See also: @samp{CONSTANT}
 
        




@node WORDLISTS, ,SUPERFLUOUS, Glossary
@section WORDLISTS
     
    The dictionary is subdivided in non-overlapping subsets: the
@dfn{word list}
@cindex word list
's (@pxref{DICTIONARY}).
 They are created by the defining word
@code{VOCABULARY}
@findex VOCABULARY
 and filled by defining words while that
vocabulary is @code{CURRENT}
@findex CURRENT
 . They regulate how words
are found; different vocabularies can have words with the same
names.

A word list in the ISO sense has no name, but a
 @dfn{word list identifier}
@cindex word list identifier
 or @dfn{WID}
@cindex WID
,
which is
inconvenient. We use vocabulary words created by the defining
word @code{VOCABULARY}
@findex VOCABULARY
 . They are used to manipulate the
word list's that are associated with them. So
vocabularies are nearly the wordlist 's of the ISO standard,
the primary difference is that they have a name. 
    

    

@menu


* ALSO  ::
* ASSEMBLER  ::
* CONTEXT  ::
* CURRENT  ::
* DEFINITIONS  ::
* ENVIRONMENT  ::
* FORTH  ::
* LATEST  ::
* ONLY  ::
* PREVIOUS  ::
* VOC-LINK  ::
@end menu
@node ALSO, ASSEMBLER, WORDLISTS, WORDLISTS
@subsection ALSO
@pindex ALSO
@findex ALSO

@noindent
Name: @code{ALSO}

@noindent
No stackeffect

@noindent
Attributes: ISO

@noindent
Description:
Duplicate the topmost @dfn{WID}
@cindex WID
 in the search order stack.
If there were already 16 WID 's,
ciforth looses the last one.
This is not counting
the @code{ONLY}
@findex ONLY
 search order.
You seldomly want to use this word, because in ciforth
by naming a vocabulary you add it to the order.

@noindent
See also: @samp{CONTEXT}
 @samp{VOCABULARY}
 

        


@node ASSEMBLER, CONTEXT, ALSO, WORDLISTS
@subsection ASSEMBLER
@pindex ASSEMBLER
@findex ASSEMBLER

@noindent
Name: @code{ASSEMBLER}

@noindent
No stackeffect

@noindent
Attributes: B,NISO,FIG,I,L1

@noindent
Description:
The name of the vocabulary to make machine code definitions.
In ciforth execution it pushes the associated word list to the
top of the @code{CONTEXT}
@findex CONTEXT
 stack. (For ISO-compliance it
would replace the top.) @code{ASSEMBLER}
@findex ASSEMBLER
 is
immediate, so it will execute during the creation of a
colon-definition, to select this vocabulary at compile time.
This word makes only sense in combination with the words that
belong to it. So it is present in loadable form in the screens
file @file{forth.lab} .

@noindent
See also: @samp{VOCABULARY}
 @samp{LOAD}
 

        


@node CONTEXT, CURRENT, ASSEMBLER, WORDLISTS
@subsection CONTEXT
@pindex CONTEXT
@findex CONTEXT

@noindent
Name: @code{CONTEXT}

@noindent
Stackeffect: --- addr

@noindent
Attributes: FIG,U,L0

@noindent
Description:
 The context is the address where the WID is found of the wordlist
that is searched first. In ciforth @samp{addr} actually points
to the @dfn{search order}
@cindex search order
,
a row of WID 's
ending with the minimum search order WID.
The corresponding wordlists are searched in that order for definitions during
interpretation.
This row of WID's is allocated in the user variable space allowing for
compilation in threads.
It may contain up to 16 WID 's in
this ciforth, while the ISO Search-Order wordset requires a capacity of at
least 8.
@code{CONTEXT}
@findex CONTEXT
 is the last user variable at offset 37 ,
such that new user variables may be allocated using offsets of
37+16 and up.


@noindent
See also: @samp{PRESENT}
 @samp{VOCABULARY}
 @samp{CURRENT}
 @samp{USER}
 



        


@node CURRENT, DEFINITIONS, CONTEXT, WORDLISTS
@subsection CURRENT
@pindex CURRENT
@findex CURRENT

@noindent
Name: @code{CURRENT}

@noindent
Stackeffect: --- addr

@noindent
Attributes: FIG,U,L0

@noindent
Description:
A user variable containing the WID of a vocabulary to which
new words will be added.
It is
the @dfn{compilation word list}
@cindex compilation word list
 in the sense of the ISO
standard.
The WID has the structure of a @dfn{dictionary entry}
@cindex dictionary entry
.
This allows to link in a new word between the
link field of the WID and the next definition.


@noindent
See also: @samp{VOCABULARY}
 @samp{CONTEXT}
 

        


@node DEFINITIONS, ENVIRONMENT, CURRENT, WORDLISTS
@subsection DEFINITIONS
@pindex DEFINITIONS
@findex DEFINITIONS

@noindent
Name: @code{DEFINITIONS}

@noindent
No stackeffect

@noindent
Attributes: ISO

@noindent
Description:
Used in the form:
           @samp{cccc DEFINITIONS}
Make
the top most
@dfn{search order}
@cindex search order
 word list, (context),
the compilation
word list (current).
In the example, executing
vocabulary name @samp{cccc} add it to the top of the
@dfn{search order}
@cindex search order
 and executing
@code{DEFINITIONS}
@findex DEFINITIONS
 will result in new definitions added to
@samp{cccc} .

@noindent
See also: @samp{CONTEXT}
 @samp{VOCABULARY}
 

        


@node ENVIRONMENT, FORTH, DEFINITIONS, WORDLISTS
@subsection ENVIRONMENT
@pindex ENVIRONMENT
@findex ENVIRONMENT

@noindent
Name: @code{ENVIRONMENT}

@noindent
No stackeffect

@noindent
Attributes: CI

@noindent
Description:
The name of the @code{ENVIRONMENT}
@findex ENVIRONMENT
 vocabulary. The
associated @dfn{word list}
@cindex word list
 contains environment queries.
The names of words present in @code{ENVIRONMENT}
@findex ENVIRONMENT
 are
recognized by
@code{ENVIRONMENT?}
@findex ENVIRONMENT?
. This word list is not intended to
be used as a @code{CONTEXT}
@findex CONTEXT
 word list; and only as a
@code{CURRENT}
@findex CURRENT
 whenever you want to add an environment
query.

@noindent
See also: @samp{VOCABULARY}
 
        


@node FORTH, LATEST, ENVIRONMENT, WORDLISTS
@subsection FORTH
@pindex FORTH
@findex FORTH

@noindent
Name: @code{FORTH}

@noindent
No stackeffect

@noindent
Attributes: NISO,FIG,I,L1

@noindent
Description:
The name of the primary vocabulary. Execution pushes the
@code{FORTH}
@findex FORTH
 @dfn{WID}
@cindex WID

to the top of the @dfn{search order}
@cindex search order
 .
(For ISO-compliance it
would replace the top.)
Until additional user @dfn{word list}
@cindex word list
 's are created, new user definitions
become a part of @code{FORTH}
@findex FORTH
 . @code{FORTH}
@findex FORTH
 is
immediate, so it will execute during the creation of a
colon-definition, to select this @dfn{word list}
@cindex word list
 at compile time.

@noindent
See also: @samp{CONTEXT}
 @samp{VOCABULARY}
 

        


@node LATEST, ONLY, FORTH, WORDLISTS
@subsection LATEST
@pindex LATEST
@findex LATEST

@noindent
Name: @code{LATEST}

@noindent
Stackeffect: --- addr

@noindent
Attributes: FIG

@noindent
Description:
Leave the dictionary entry address @samp{addr} of the
topmost word in the @code{CURRENT}
@findex CURRENT
 word list.

@noindent
See also: @samp{VOCABULARY}
 
        


@node ONLY, PREVIOUS, LATEST, WORDLISTS
@subsection ONLY
@pindex ONLY
@findex ONLY

@noindent
Name: @code{ONLY}

@noindent
No stackeffect

@noindent
Attributes: NISO

@noindent
Description:
Set the minimum search order, such that only
@dfn{denotation}
@cindex denotation
's (numbers etc.) can be found
plus the word @code{FORTH}
@findex FORTH
.
By using @code{FORTH}
@findex FORTH
 one can regain control towards a startup search order.

@code{ONLY}
@findex ONLY
 is actually a regular @code{VOCABULARY}
@findex VOCABULARY
.
The
associated @dfn{word list}
@cindex word list
 contains mainly prefix words,
that scan denotations and are described in the chapter
@code{DENOTATIONS}
@findex DENOTATIONS
.
If found the parse pointer is moved back to immediately after
the prefix, and the corresponding denotation definition
executed.
If you want to add a denotation


@noindent
See also: @samp{PREFIX}
 
        


@node PREVIOUS, VOC-LINK, ONLY, WORDLISTS
@subsection PREVIOUS
@pindex PREVIOUS
@findex PREVIOUS

@noindent
Name: @code{PREVIOUS}

@noindent
No stackeffect

@noindent
Attributes: ISO

@noindent
Description:
Pop the topmost @dfn{WID}
@cindex WID
 from the search order stack.
If empty still the @code{ONLY}
@findex ONLY
 search order is left.

@noindent
See also: @samp{CONTEXT}
 @samp{VOCABULARY}
 

        


@node VOC-LINK, , PREVIOUS, WORDLISTS
@subsection VOC-LINK
@pindex VOC-LINK
@findex VOC-LINK

@noindent
Name: @code{VOC-LINK}

@noindent
Stackeffect: --- addr

@noindent
Attributes: U

@noindent
Description:
A user variable containing the @dfn{dictionary entry
address}
@cindex dictionary entry
address
 of the word most recently created by
@code{VOCABULARY}
@findex VOCABULARY
 . All vocabulary names are
linked by these fields to allow @code{FORGET}
@findex FORGET
 to find all
vocabularies.

@noindent
See also: @samp{VOCABULARY}
 
        






@node Glossary Index,,,Top
@unnumbered Glossary Index
This index finds the glossary description of each word.
@printindex pg
@node Forth Word Index,,,Top
@unnumbered Forth Word Index
This index contains @emph{all} references to a word.
Use the glossary index to find the glossary description of each word.
@printindex fn
@node Concept Index,,,Top
@unnumbered Concept Index
Mostly the first reference is where the concept is explained.
But sometimes in introductory and tutorial sections
an explanation sometimes was considered too distracting.
@printindex cp
@summarycontents
@contents
@bye
