








































\input texinfo
@setfilename ci86.lina64.texinfo
@dircategory Programming
@direntry
* lina: (lina).                Close to ISO, Forth interpreter and compiler.
@end direntry
@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 lina64:
@itemize @bullet
@item
version 5.4.1
@item
64-bits protected mode 
@item
running under Linux using system calls directly

@item
contains security words 
@item
the full ISO CORE set is present, possibly after loading
@item
headers with source fields

@end itemize

@author Albert van der Horst
Dutch Forth Workshop


@page
@c @vskip Opt plus 1fill
Copyright @copyright{} 2000,2015 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 ``lina64'' once it is installed on your system.

ciforth consists of three files:
@itemize @bullet
@item
   lina64    : the program

@item
One of @file{ciforth.ps} @file{ciforth.pdf} @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 5.4.1.
It is running in protected mode.     
It is running under
Linux    Blocks are allocated in files.     A number has a precision of 64 bits.  It calls linux system from Forth directly.  It has compiler security, sacrificing some ISO
compatibity. It use @code{PP}
@findex PP
 instead of the ISO @code{>IN}
@findex >IN
 .   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 need to read this.
* Rationale & legalese:: For experts. You don't want to read this.
* Manual::         User manual
* Assembler::      The assemblers
* Optimiser::      Notes about optimisation
* 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{lina64} @* 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 > lina64

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

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

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

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.

You will be curious about what are all those commands available.
Of course they are documented, but you can find the exact set
by typing @code{WORDS}
@findex WORDS
 .
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 can check that it has been added, by typing @code{WORDS}
@findex WORDS
 again.

The above  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} .

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

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

@example
@iftex
@cartouche
: TEST 1 2 + 7 * ;     21 .
21 OK 
@end cartouche
@end iftex
@ifinfo
: TEST 1 2 + 7 * ;     21 .
21 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..
This publicationis is available under GPL 2, the GNU public license.
The file @file{COPYING} containing the legal expression of these
lines must accompany it.

You can make closed source program with the -c options.
Such programs are naturally your own,
quite the same as programs build with the gcc compiler.
However also if you base an application program on ciforth,
you need not make its source available,
even if the application contains the Forth interpreter
exposed. This would be a derived work and,
in a strict interpretation of the GPL,
such interpretive systems based on ciforth
are always legally obliged to make the source available.
Because Forth is ``programming by extending the language'' ,
we consider this ``normal 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:

@enumerate
@item
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 considered normal use of the
compilation 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.

@item
Code snippets in the library inasfar not in the public domain
are available under the LGPL, so you can freely borrow from it
or build on it.
@end enumerate
@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 lina64 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, 32 and 64 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{lina64} 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
Note that the computer ends its output with @samp{OK}
to indicate that it has completed the command.
@*
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 lina64.
As soon as you leave lina64,
the new command is gone.

@*
If you want to use the program a second time,
you can put it in a file @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
This file can be @code{INCLUDED}
@findex INCLUDED
 in order to add the command
@samp{HELLO} to your Forth environment, like so:
@example
@iftex
@cartouche
"hello.frt" INCLUDED
OK
HELLO
Hello world!
OK 
@end cartouche
@end iftex
@ifinfo
"hello.frt" INCLUDED
OK
HELLO
Hello world!
OK 
@end ifinfo
@end example
During development you probably have started with
@samp{lina64 -e}, so you need just type
@example
@iftex
@cartouche
INCLUDE hello.frt
@end cartouche
@end iftex
@ifinfo
INCLUDE hello.frt
@end ifinfo
@end example

In order to make a stand alone program to say hello you can
use that same source file, again @file{hello.frt}.
Now build the program by
@*
lina64 -c hello.frt
@*
(That is @kbd{c} for compile.)
The result is a file @file{hello} .
This file can be run from your command interpreter, or shell.
It then will execute the last word defined in the source file in this case @samp{HELLO} .
It is a single file that you can pass to some one else to run on their
computer, without the need for them to install Forth.
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 lina64 you never have to worry about the life time of 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 lina64'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 lina64 does.

lina64 uses the @dfn{blocks}
@cindex blocks
 as a library
by addition of the word @code{WANTED}
@findex WANTED
 and a convention.
Starting with @samp{lina64 -w} or most any option you have this
facility available. If you are already in lina64, 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" WANTED
OK
DO-DEBUG

S[ ] OK 1 2

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

S[ ] OK 1 2

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

More convenient than @code{WANTED}
@findex WANTED
 is @code{WANT}
@findex WANT
 that adds
all words that are on the remainder of the line, so without quotes.

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, lina64 doesn't know about a forth word named
@code{TUCK}
@findex TUCK
, but after @samp{"TUCK" WANTED} maybe
it does. You may try again.

The convention about the way the library file must be
organized for @code{WANTED}
@findex WANTED
 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.
This continues until the word has been defined,
or the end of the search area is reached.
This is marked by a screen with an empty index line.
I tell you this not because you need to know,
but to show that there is nothing to it.

The library file contains examples for you
to load using @code{WANT}
@findex WANT
 .
Try
@example
@iftex
@cartouche
WANT 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
WANT 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 lina64 by @samp{lina64 -e}.
That is @kbd{e} for elective.
@samp{lina64 -e} instructs lina64 to load screen 5
(@kbd{e} is the 5-th letter.)
 
You  can configure this screen 5 to suit your particular needs,
by just using some programmers editor.
We will come back to that later.
@*
You will have available:
@enumerate
@item
@code{WANTED}
@findex WANTED
 and @code{WANT}
@findex WANT
 .
@samp{WANT xxx yyy} is equivalent to
@samp{"xxx" WANTED "yyy" WANTED} , 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{SEE}
@findex SEE

To analyse words, showing the source code of compiled words.
(Also known as @code{CRACK}
@findex CRACK
.)
 
@item
 @code{LOCATE}
@findex LOCATE

To show the part of the source file where the word is defined,
or, if loaded from the library file, the block where it is defined.
 
 
@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 lina64 in a window, and use a separate window to start your
editor. Try out things in lina64. 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{SEE}
@findex SEE
 .
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 lina64
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 lina64. 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 lina64 again by @samp{lina64 -e}.
The sequence
@example
@iftex
@cartouche
WANT TUCK
LOCATE TUCK
@end cartouche
@end iftex
@ifinfo
WANT TUCK
LOCATE TUCK
@end ifinfo
@end example
shows you the source for TUCK if it is in the library somewhere.
@example
@iftex
@cartouche
WANT TUCK
SEE TUCK
@end cartouche
@end iftex
@ifinfo
WANT TUCK
SEE 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 lina64,
you may use @code{"newforth" SAVE-SYSTEM}
@findex "newforth" SAVE-SYSTEM
 .
This will do most of the time,
but then you build in the @code{SAVE-SYSTEM}
@findex SAVE-SYSTEM
 command as well.
For configuring your lina64, without enlarging the dictionary,
you may use the following sequence
@example
@iftex
@cartouche
 S" myforth.lab" BLOCK-FILE $! \ Or any configuration command
1 LOAD
WANT SAVE-SYSTEM
: DOIT
    '_pad 'FORTH FORGET-VOC
    '_pad >NFA @@ DP !
    "newforth" SAVE-SYSTEM BYE ;
DOIT 
@end cartouche
@end iftex
@ifinfo
 S" myforth.lab" BLOCK-FILE $! \ Or any configuration command
1 LOAD
WANT SAVE-SYSTEM
: DOIT
    '_pad 'FORTH FORGET-VOC
    '_pad >NFA @@ DP !
    "newforth" SAVE-SYSTEM BYE ;
DOIT 
@end ifinfo
@end example
Here @samp{DOIT} trims the dictionary just before
saving your system into a file.
@code{_pad}
@findex _pad
 is the first word of
the facilities in screen 1 that was loaded.
(This was different in previous version of ciforth.)

@code{FAR-DP}
@findex FAR-DP
 allows to have a disposable part of the
dictionary.
If you decide to use this facility for your own purposes,
make sure to always @code{FORGET}
@findex FORGET
 the disposed off words.
The @samp{-c} option uses this to avoid having
source files as part of an executable image.

@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 namespace.
Apart from the name, a word contains data and executable code,
(interpreted or not) and linking information
(@pxref{NAMESPACE}).
The order of words in a wordlist is important for looking them up.
The most recent words are found first.

The concept word list is part of the ISO standard, but we will
use @dfn{namespace}
@cindex namespace
. A namespace is much more
convenient, being a word list with a name, created by
@code{NAMESPACE}
@findex NAMESPACE
 . 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{NAMESPACE}
@findex NAMESPACE
.
When looking up a word, only the wordslists that are in the current
@dfn{search order}
@cindex search order
 are found.
By executing the namespace 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
namespace.
You can derive the WID from the DEA of a namespace by @code{>WID}
@findex >WID
.

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{WOR}. It then jumps to the address
pointed to by the address pointed to by @samp{WOR}. @samp{WOR} points to the code field of a definition which (at offset forthdef(>CFA) )
contains the address of the code which executes for that definition.
For speed reasons this offset is choosen to be zero.
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
 can 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
.
Apart from @samp{HIP} and @samp{WOR} the return and data stack
are kept in registers named @samp{RPO} and @samp{SPO}.
If you're interested in the actual registers, you can inspect the
assembler source file that goes with this Forth.
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 a Pentium processor this is
32 or 64 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 64,
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 is most accessible on the stack and if stored in
memory, it is lowest.

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 letters, using @code{PREFIX}
@findex PREFIX
.
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
0x8000403A
#3487
0177
S" Arpeggio"
"JAMES BROWN IS DEAD"
" JK "
'DROP
' DROP
@end cartouche
@end iftex
@ifinfo
10
'a'
^A
0DEAD
$8000403A
0x8000403A
#3487
0177
S" 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,
but 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 admits. 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
As @code{ABORT"}
@findex ABORT"
 @code{ABORT}
@findex ABORT
 @code{QUIT}
@findex QUIT
 are not implemented
using @code{THROW}
@findex THROW
 it is not possible to catch those words.
@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 uses @code{PP}
@findex PP
 instead of the ISO @code{>IN}
@findex >IN

The @code{>IN}
@findex >IN
 that is available via the library is a fake, that can only be
read, but changing it has no effect.
@code{PP}
@findex PP
 can be manipulated to have such effects as the familiar
@code{0 >IN !}
@findex 0 >IN !
 idiom.
 @item
Counting in do loops do not wrap through the boundary between
negative and positive numbers.
This is not useful on Forths of 32 bits and higher;
for compatibility among ciforths 16 bit ciforths don't wrap either.
@item
Namespaces are wordlists with a name. They push the wordlist
to the search order, instead of replacing the topmost one,
as is done by VOCABULARY (not an ISO-word) that is present in some other
Forth's.
In this sense @code{FORTH}
@findex FORTH
 and @code{ASSEMBLER}
@findex ASSEMBLER
 words are not
conforming.
@item
This is not strictly non-conforming, but worth mentioning here.
In fact lina64 contains only one state-smart word
besides @code{LITERAL}
@findex LITERAL
 (that word is @code{."}
@findex ."
 ).
All denotations are state-smart only because they use @code{LITERAL}
@findex LITERAL

and 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 lina64-specific -- but hopefully documented -- behaviour.
Understanding it requires some study of non-portable facilities.
@item
When a file is @code{INCLUDED}
@findex INCLUDED
 it is read in as a whole,
so there is never a need for @code{REFILL}
@findex REFILL
 .
After @code{ WANT REFILL}
@findex  WANT REFILL
 a @code{REFILL}
@findex REFILL
 is loaded that
sets the parse pointer to the start of the next line.
In nearly all cases this will accomplish the effect described by the standard.

@end enumerate

Here we will explain how you must read the glossary of lina64,
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 ``lina64'', 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.
A typical example is the size of a cell.
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
lina64 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/64 bit clean.
This means that it runs on 16, 32 and 64 bits systems.
@section Compatibility with lina64 4.0.x
Since version 5.x changes have been made to increase compatibility
with existing practice.
By invoking @code{WANT -legacy-}
@findex WANT -legacy-
 you load a screen that
forces compatibility with 4.x.x versions.
You will notice that existing programs either invoke this, or have
been reworked to not need legacy items.
In either case, those programs have been tested with version 5.x

What the legacy items are can be seen from the screen that has
@code{-legacy-}
@findex -legacy-
 in its index line.
In particular @code{REQUIRE REQUIRED PRESENT? VOCABULARY
WORD FIND (WORD) (PARSE) SAVE-INPUT RESTORE-INPUT }
@findex REQUIRE REQUIRED PRESENT? VOCABULARY
WORD FIND (WORD) (PARSE) SAVE-INPUT RESTORE-INPUT 
 are
to be found in those screens.
Note that by using legacy items your code may be in conflict with
upcoming standards.

The names @code{VOCABULARY}
@findex VOCABULARY
 and @code{REQUIRE}
@findex REQUIRE
 are
being proposed for standardisation.
The ciforth definitions with these names were not compatible with
this proposal.
So the @code{REQUIRE}
@findex REQUIRE
 of older versions is now called @code{WANT}
@findex WANT
.
Likewise @code{REQUIRED}
@findex REQUIRED
 is renamed to @code{WANTED}
@findex WANTED
.
@code{VOCABULARY}
@findex VOCABULARY
 is renamed to @code{NAMESPACE}
@findex NAMESPACE
,
with the difference that @code{NAMESPACE}
@findex NAMESPACE
 is not immediate.
This allows to include the new standardised definitions
in a loadable screen.
@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 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.
Having a program to execute a certain word is even easier,just use the
@samp{-c} option. @xref{Manual}, Section Libraries and options.

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 64 bits (8 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 lina64 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, which is now
from @code{BM}
@findex BM
 to @code{HERE}
@findex HERE
.
The command @samp{WANT 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 and
the input buffer for the console
and disk block buffers 
.
@end itemize
The lowest part of the free memory is used as a scratch area: @code{PAD}
@findex PAD
 .


The dictionary area is the only part that is initialised,
the other parts are just allocated.

The program as residing on disk must contain the first area.
In addition it contains a header, to tell
the Linux how to transfer the program to memory. 
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.

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 supports 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
extend from @samp{0 +ORIGIN} and supply an initial value for all
of the user area.
This is the image for the @dfn{user area}
@cindex user area
.

In ciforth the bootup parameters are more or less the data area
belonging to 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{TYPE}
@findex TYPE

 @code{CR}
@findex CR
 @code{BLOCK-READ}
@findex BLOCK-READ
 and @code{BLOCK-WRITE}
@findex BLOCK-WRITE

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.
These definitions are often revectored especially those for output.
Output is revectored using @code{TYPE}
@findex TYPE
 . In other Forth's this is mostly
done via @code{KEY}
@findex KEY
 and @code{CR}
@findex CR
 separately.
 Input revectoring cannot be done via @code{KEY}
@findex KEY
 .
Redirection works and is easier most of the time.
@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.
The @dfn{Library Addressable by Block}
@cindex Library Addressable by Block
 contains an assembler,
to add code definitions that will blend in like they were written
in the kernel.
Such definitions are to be closely matched with your particular
ciforth,
and you must be aware which registers play which role in ciforth.
This is documented in the assembler source of this ciforth that
accompanies this distribution.
Of course it is also a rich source of examples how to
make assembler definitions.

It bears repeating: code words are perfectly normal dictionary entries.

Note: if you want to change this
ciforth's assembler source to fit your needs,
follow the instructions present in the source,
assembling as well as linking instructions.
@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 may result in deviations from the standard,
so you probably want to leave this area alone.
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 formatting.
Some of these are fixed by the ISO standard too.
In ciforth most of those facilitities are not available in the kernel,
but from the library.
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).
You can @code{FORGET}
@findex FORGET
 part of
the high-level and re-compile altered definitions from disc.
Mostly this is a mistake, and to make sure you mean it,
you must change @code{FENCE}
@findex FENCE
 to defeat a protection mechanism.

A number of entries that could easily be made loadable
are integrated in the assembler source of this ciforth version.
Instead of forgetting them, you can load your own version
on top of the existing system and waste some space.

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.  In ciforth those facilities are mostly not
available in the kernel, but from the library.
For example, an assembler is not part of he kernel as delivered,
but it is available after @samp{WANT ASSEMBLERi86}.
Beware! The assembler can only be loaded on top of a
@code{CASE-SENSITIVE}
@findex CASE-SENSITIVE
 system.


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 1 LOAD; cat pascal.frt - )| lina64 }
@*
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.
@*
In an installed system you will put @samp{WANT OS-IMPORT WANT INCLUDE}
in your electives screen (5), and just type
@samp{vim mysrc.frt} to edit a file, without leaving lina64 and
load it with @samp{INCLUDE mysrc.frt}

A Pentium 32 and a 8086
Forth assembler are available in @file{forth.lab}.
They are loaded in accordance with the system that is run.
The registers used by lina64 are called HIP, SPO, RPO and WOR.
The mapping on actual processor registers is documented in the
source.

It is essential that you regard lina64 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.
Some words criticial for speed you can later rewrite as code words.
Some words are easier to write in code right away.


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 console 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 and 64 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 32-bits Linux to 4G minus
something and forget about this issue forever. 

The boundary between this area and the previous ones is pretty sharp,
it is where @code{DP}
@findex DP
 points.
The other areas are more of a logical distinction.
But even this boundary constantly changes as you add and forget definitions.
Multi-tasking requires allocation of extra areas.
@xref{Manual}, Section Details of memory layout.

@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) and 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,
then padding for alignment.
Unfortunately, @dfn{name token}
@cindex name token
 is
used in other Forth's to indicate a base to find other fields,
what we call a @dfn{dictionary entry address}
@cindex dictionary entry address

This came about because the name is lowest in memory.
In this Forth the code field address and the dictionary address happens
to be the same. This has a small advantage in @dfn{next}
@cindex next
,
it needs no offset. 
@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.
For kernel words it stays at zero.
@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

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
 .
@code{(CREATE)}
@findex (CREATE)
 takes care to generate the dictionary entry
data structure; it is called by all defining words.

Note that @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.
Furthermore only particular words have data fields, those defined
by @code{CREATE}
@findex CREATE
 .

The flag bits used in the kernel are:
@itemize @bullet
@item
The INVISIBLE bit = 1 when @dfn{smudge}
@cindex smudge
d; this 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 namespace; 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 character word, but not necessarily.
All built-in prefix words are part of the minimum search order and are
one character.
@end itemize
After the last letter of a name follow zero bytes up till the next cell boundary.
The @dfn{code field}
@cindex code field
 of all @dfn{colon definition}
@cindex colon definition
's
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}.
On the other hand all @dfn{code definitions}
@cindex code definitions
 (those written
in assembler code) have different code fields.

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 the same pointer as in the code field.
@item
For a word defined by
@code{CONSTANT}
@findex CONSTANT
, @code{VARIABLE}
@findex VARIABLE
, @code{USER}
@findex USER
, or
@code{DATA}
@findex DATA
 it has a width of one cell, and contains data.
For @code{VARIABLE}
@findex VARIABLE
 it is a pointer to a cell,
for @code{DATA}
@findex DATA
 it is a pointer to a memory area of varying length.
@item
For all @dfn{colon definition}
@cindex colon definition
's the data field address
contains a pointer to an area of varying length. It contains the
compiled high level code, a sequence of @dfn{dea}
@cindex dea
's.
@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

The wordset @samp{DICTIONARY} contains words for turning
a @dfn{dictionary entry address}
@cindex dictionary entry address
 into any of these fields.
They customarily start with @kbd{>}.

In summary, a dictionary falls apart into
@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}
@findex B/BUF
 bytes plus two cells.

For this ciforth the number of disk buffers is configured
at 16 . 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, @code{MAX-USER}
@findex MAX-USER

contains the size of the area that is in use, in bytes.
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.
Updating @code{MAX-USER}
@findex MAX-USER
 is recommended.
 The user area is just under the disc
buffers. So it ends at @code{_FIRST}
@findex _FIRST
 .   

The console input buffer  and the return stack share an area configured at a
size of 0x10000 bytes.
The lower half is intended for the console 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.

In multi-tasking a separate user area is allocated
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 console input buffer.
A task is set up by allocating another area for all four.
For task switching, it suffices to switch
both stack pointers and the pointer to the user area.
In this Forth the user area is moved during startup,
such that it has a round address.
This makes it possible to derive the user base
pointer from the return stack pointer on the fly and
handle one less register during task switching. 

@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 lina64 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{ACCEPT}
@findex ACCEPT
 are subject to correction
until <RET> has been pressed.
On lina64 @code{ACCEPT}
@findex ACCEPT
 is left to the
operating system, such that inputting to lina64 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.
This is a limitation but input direction supplied by the operating system
goes a long way to alleviate this.


@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{WANTED}
@findex WANTED
 takes a string and loads the
first screen where that name occurs in the index line. For
convenience also @code{WANT}
@findex WANT
 is there that looks ahead
in the input stream.
These words are not in the kernel but are present in screen 1,
that corresponds to the @samp{-a} option.

Screen 0 and screen 1 to 31 are reserved for options, some of which are
available to be filled in by the user.

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.
Moreover it can interpret options, only if it is properly
installed with a connection to a @file{lab} file.
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 option @code{-x}
@findex -x
 triggers the code @code{^X LOAD}
@findex ^X LOAD
,
loading screen 24.

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

@itemize @bullet

@item
@samp{-a}

Make sure @code{WANTED}
@findex WANTED
 is available.
This is a copy of the @samp{-w} 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.
If @file{name} ends in @samp{.frt} it is ommitted to arrive at the
name of the binary, otherwise the binary is called @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.
In addition @code{WANT}
@findex WANT
 and ARG[] are made available.

@item
@samp{-d name }
Include @file{name} with @code{[DEFINED]}
@findex [DEFINED]
 available.
This file can be made to load onto other Forths without modifications.

@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 contains system wide default preferences.
See the @samp{-l} option if the default preferences don't suite you.
In an elective screen you just put
commands to load or execute at startup of an interactive session,
such as 
@samp{ "fortune -f /usr/lib/forthcookies" SYSTEM }
 or 
@samp{ WANT 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.
Expanding to the full size of the available RAM does no harm,
as Linux overcommits memory.


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

The first option letter is trimmed to 5 bits, and excess characters
are ignored.
Thus 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 described in the beginning 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{-p}

@b{Reserved option, not implemented.}
@*
Be pedantic about ISO.
Redefine some words to follow the standard as closely as possible.

@item
@samp{-q}

Be quiet, don't give a startup message.


@item
@samp{-s script}

Load the file @file{script} , but ignore its first line.
This is intended to be used for Linux 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{WANT}
@findex WANT
 and @code{ARG[]}
@findex ARG[]
 are available and
you can use standard in and standard out.
This follows the Unix conventions for script files.
If you set the execute bit the file file becomes a command and accepts
arguments.

@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.

@item
@samp{-w}

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

@item
@samp{-?}

Give help, made to act the same as @samp{-h}.
The trimming makes that this is mapped to screen 31.

@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{WANTED}
@findex WANTED
 .

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.
You can also use the @samp{-i} option to make a customized lina64 in
your project directory.
@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 lina64 in your programs can remain
the same.

@subsection Stand alone programs.
A stand alone program is made relying on the word @code{SAVE-SYSTEM}
@findex SAVE-SYSTEM
 .
A stand alone program may be an enhanced version of ciforth or a program
with a special purpose,
what in other languages is normally called a compiled program.
In Forth parlance this is called a @dfn{turnkey application}
@cindex turnkey application
,
because mostly the program has special requirements from the environment.
They 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.
Unlike other Forths, the resulting program is a regular executable,
that can be run on other computers with the same operating system.
Generally an application ignores the absence of a library file.
It must make sure to @code{CATCH}
@findex CATCH
 any possible errors and
report them in terms of the situation the user is in.
Otherwise the user will be confronted with raw Forth error numbers
without even the one line description.

Mostly it is much easier to just use the @samp{-c} option.
For a simple example
@xref{Manual}, Getting Started Subsection Hello World!


@node Assembler, Errors, Manual, top



@chapter Assembler

The @file{ciasdis} assembler is described in this manual,
because the assembler that is in the lab file is compatible.
The idea is that you test code with ciasdis relying on comprehensive
consistency checking.
Then can you use the assembler in the blocks and can the real
debugging begin.
This chapter is about the assembler itself,
the information about what registers are used in ciforth is
contained in its assemblers 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, 32 and 64 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 lina64
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.

@*
The assembler is usable for 64 bit lina.
The assembler in @file{forth.lab} is without reserve
useable for instructions
that do not require a prefix. Furthermore
the @code{REX,}
@findex REX,
 instruction
that makes the operand size 64 bits  is provided, plus
a 64 bit version of @code{NEXT,}
@findex NEXT,
.
These additions are sufficient to make the floating point library
assemble under 64 bits as floating point instructions do not require
a prefix, nor does the instruction @code{lEA,}
@findex lEA,
.

The following files comprise the great assembler.
@*
@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.
@*

The relevant assembler present in


but without error detection.

The @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 (e.g. 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})
The INC instruction in this (the mod/rm) incarnation has
a size bit. Here we require that this bit be filled in
explicitly, either with @samp{ X| } or @samp{ B| } ).
Failing to do so is a fatal error.
This results in 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| ZO| [BX] 
@end cartouche
@end iftex
@ifinfo
        INC, B| ZO| [BX] 
@end ifinfo
@end example
This completely unambiguously determines the actual machine code.

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 the next postit
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.
@samp{SIB} is handled as an instruction within an instruction,
clever, but hard to understand.
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
an 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.
This principle allows to make a disassembler that is independant
of the instruction information, one that will work for the 8086.
A typical family are the 8 immediate- operand instructions, with an
increment of 08.
@example
@iftex
@cartouche
 08 C6 8 1FAMILY, ADI ACI SUI SBI ANI XRI ORI CPI 
@end cartouche
@end iftex
@ifinfo
 08 C6 8 1FAMILY, ADI ACI SUI SBI ANI XRI ORI CPI 
@end ifinfo
@end example
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

The makefile for the assembler project contain facilities to
generate opcode sheets directly from the instruction sets,
such as @file{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. The most useful of them all is @code{??}
@findex ??

that for a partially completed instruction shows all possible completions.

@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{,} is an ``opcode'' and 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 data 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,
 @code{IQ,}
@findex IQ,
 ( 8 16 32 64 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
If an instructions with r/m has one register, it is always the target,
i.e. it is modified.
@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 two registers, the second one is indicated
by a prime such as @code{AX'|}
@findex AX'|
.
Stated differently, if an instruction can handle two general
registers, the one that cannot be replaced by a memory reference gets a prime.
@item
If @code{T|}
@findex T|
 or @code{F|}
@findex F|
 are present they apply to the
primed register.
@code{T|}
@findex T|
 ``to'' means that the primed register is modified.
Absent those the primed register is the one that is modified. e.g.
in @code{LEA,}
@findex LEA,

@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 order as required.
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.
It
@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.
(FIXME! This probably is remedied in the first release of ciasdis. )
@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, 32 and 64 bits code and segments

The buildin assembler would be cumbersome to use,
without the help of @file{ciasdis}, the great assembler.
Not only are the instructions checked as explained before,
from version 2.0.0 on, the interplay between segment size as
instruction size are checked.

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

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 in the presence of segment override prefixes.
@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 comma-ing, you must always select the proper one, commaers
contain either @kbd{C}, @kbd{W}, @kbd{L} or
@kbd{Q} for 1, 2, 4 or 8 byte widths.

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.
After the directive @code{BITS-64}
@findex BITS-64
 code is generated for and checked
against 64 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,
 .

In a 64 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,
 and occasionally @code{IQ,}
@findex IQ,
.

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.

In 64 bits mode instructions that contain an immediate address
differ from 32 bits mode.
Those addresses are specified relative to the program counter, not absolute.
Consequently the @code{MEM|}
@findex MEM|
 fixup leads to an error message, and
instead @code{REL|}
@findex REL|
 must be used with either a @code{RL,}
@findex RL,
 or
an @code{(RL,)}
@findex (RL,)
 commaer.
Absolute 64-bits addresses are nowhere present in the instruction set,
as they are not really useful.

The great assembler enforces all these rules.

AMD took advantage of the fact that Intel instruction are available
in a short and long form, e.g. @code{INC|X,}
@findex INC|X,
 and @code{INC, X|}
@findex INC, X|
.
The short form is hijacked, so @code{DEC|X, AX|}
@findex DEC|X, AX|
 becomes
@code{REX,}
@findex REX,
 .
All immediate data and offsets are sign-extended from 32 to 64 bits
in 64 bits code, with the rational that full 64 bit is rarely useful.
The result is that 32 and 64 code looks the same.
In the rare case that a 64 bit value is needed, @code{MOVI|X,}
@findex MOVI|X,
  is
hijacked and replaced with @code{MOVI|Q,}
@findex MOVI|Q,
 .
(Remember @code{MOVI, X|}
@findex MOVI, X|
 is a duplicate.)
So only instructions involving ghost registers representing
integers and memory storage
are different between 32 and 64 bits.
That is all, and a 64-bit assembler is practically accommodated in full.
Bottom line, the assembler built in into forth.lab is adequate to assemble
the floating point wordset.

We need the 64-bit related prefix 0x48 to force the size to 64 bit in all
cases where a register is mentioned in the instruction.
Floating point instructions don't use regular registers and need not use
this prefix unless e.g. @code{[SP}
@findex [SP
 is used.
The three least significant bits in the 0x4#  switch the registers
(possible in three positions) to the ghost registers.
Such prefixes are present in @file{ciasdis},
but in the lab file only @code{REX,}
@findex REX,
 is available.


There us more to say about @dfn{ghost}
@cindex ghost
 registers
in using @file{ciasdis} itself.
 They appear instead of the regular
registers, e.g @code{AX}
@findex AX
 is turned into @code{R8}
@findex R8
 .
We make a distinction between instruction with possibly two
register operands, and the others. The first class is called modr/m
in Intel and AMD lit.
A two operand instruction always has a primary register that has
a prime like @code{AX'|}
@findex AX'|
 and @code{T|}
@findex T|
 @code{F|}
@findex F|
 apply
to that register.
(The other operand may be a register, or indirect such as
sib or memory address.)
If you learned the distinction and use of primed and unprimed registers
it is easy:

@enumerate
@item
  @code{'}
@findex '
 applies to primed registers, turns @code{AX'|}
@findex AX'|
 to @code{R8'|}
@findex R8'|

@item
@code{]}
@findex ]
 applies to index registers in sib-intructions, turns @code{AX']}
@findex AX']
 to @code{R8']}
@findex R8']

@item
  @code{N}
@findex N
 bit applies to all other registers:
@end enumerate

The remaining case of use of registers are
@enumerate
@item
     - unprimed register like @code{BX|}
@findex BX|
 .
@item
     - indirect like @code{[BX]}
@findex [BX]
 .
@item
     - base register in sib like @code{[AX}
@findex [AX
 .
@end enumerate

In summary we get
  @code{ Q: QN: Q]: QN]: Q': QN': Q']: QN']: }
@findex  Q: QN: Q]: QN]: Q': QN': Q']: QN']: 
 for possible
 prefixes, that switch at the same time to 64 bits.
Similar prefixes are available with E , if you want the 32
  bit ghost registers.

Note that
an unprimed register cannot be combined with sib (scaled
indexing) in any way, which would signify conflict between
@code{AX|}
@findex AX|
 and @code{[AX}
@findex [AX
 .

Note that most assemblers would conflate
@code{MOV, MOVI, MOVI|X, }
@findex MOV, MOVI, MOVI|X, 
 etc,
instructions and would not allow for such an easy explanation.

@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{WANT ASSEMBLERi86 }
@findex WANT ASSEMBLERi86 
.
Automatically a 32 bit assembler is loaded
if the Forth itself is 32/64 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.)
This assembler is now (since 5.0.0) 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 5.169 version and later may contain
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'| XO| [BP +8* AX] FFFFF800 L,} 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 fixups related to address offsets @code{XO|}
@findex XO|
 and @code{L,}
@findex L,
 must
agree and are 32 bits because you are in a 32 bits segment and this
was not be overridden.
@item
The offset (in @samp{+AX]} ) is counted in 64 bits.
Apparently, the @samp{DI} is fetched from two cell records.
@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, ANDSI,
@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|B, MOVI|X,
@item MOVS,
@item MOVSX|B, MOVSX|W,
@item MOVZX|B, MOVZX|W,
@item MUL|AD,
@item NEG,
@item NOT,
@item OR, ORI, ORI|A, ORSI,
@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, RCLI,
@item RCR, RCRI,
@item REPNZ,
@item REPZ,
@item RET+, RET, RETFAR+, RETFAR,
@item ROL, ROLI,
@item ROR, RORI,
@item SAHF,
@item SAR, SARI,
@item SBB, SBBI, SBBI|A, SBBSI,
@item SCAS,
@item SET,   (Intel SETcc)
@item SGDT,
@item SHL, SHLI,
@item SHLD|C, SHLDI,
@item SHR, SHRI,
@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, XORSI,
@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 at most one register specified in a floating point
instruction.
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}.
@samp{a|} (abnormal operation) means @code{ST0}
@findex ST0

is the second operand as per @samp{ST1-ST0}.
Also normally @code{ST0}
@findex ST0
 gets the result.
@samp{m|} (modified) means that the explicit register gets modified
instead.

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 FLDPI,
@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

The fixups for floating point are in lower case to make
some distinction with the regular instructions.
There is one fixup that conflicts with an uppercase
fixup: @dfn{n|}
@cindex n|
 .
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|      : Explicit register is modified
@item u|      : Explicit is unmodied, result to ST0
@item n|      : ST0 is first operand (normal)
@item a|      : ST0 is second operand (abnormal)
@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 ones is LGDT, ) instead of all the @dfn{scaled index byte}
@cindex scaled index byte

(@dfn{SIB}
@cindex SIB
) 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 and an offset of 18.

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
.

Error-prone as that may seem, the great assembler only accepts
correct instructions.
Instructions are verbose, but they are hard to misinterpret.

 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 index
@item CX]   : Scaled index
@item DX]   : Scaled  index
@item BX]   : Scaled index
@item 0]    : No index
@item BP]   : Scaled index
@item SI]   : Scaled index
@item DI]   : Scaled index

@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.)
At the same time it is a comma-er in the sense that it reports
that the demand for a sib-commaer is fill filled.

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 operands and then always one of them is a
primed register.
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
@*
@*
Suffixes 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 shift 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 or @kbd{Q} for 64 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{??}
@findex ??
 you can see what completions of your opcode
are possible.

@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.
(This is rare, most situations are handled by bad bits, resulting
in different errors.)

@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 specifying both a @code{SI'|}
@findex SI'|
 and a @code{DI'|}
@findex DI'|
 operand
for a @code{LEA,}
@findex LEA,
 opcode.

@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.
FIXME This explanation is the same as the previous.
For example @code{B|}
@findex B|
 (byte size) with a @code{LEA,}
@findex LEA,
 opcode .

@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 Optimiser , Errors, Assembler, top
@chapter Optimiser
@section Introduction
The optimiser is not yet part of ciforth, Computer Intelligence Forth.
Remember originally this Forth is conceived is a basis for
a Computer Intelligence that has insight in her own code.
As a consequence the Forth is made
as transparant and simple as possible,
and the theory is that optimisation is made easier the more the
language is self referential and simple.
This optimizer is thus a touch stone whether these ideas work in
practice.
This chapter outlines the theory; a practical application is in the
works.
Different types of optimisations interfere and finding one's way through this
certainly requires some heuristics.
The bottom line is that an optimiser qualifies as an AI application
in the old sense, a result of painstaking, errorprone effort.

@subsection Properties

A Forth system is a database of small programs. It is worthwhile to
investigate what properties these small programs (words) might have.
The flag field of a word allow to add this information to the header.
A certain combination of flags allow a particular optimisation.

@subsection Definitions
An annihilator is a word that only deletes an item from the stack.
Examples are DROP 2DROP NIP RDROP.

A juggler reorders the stack without adding or removing items.
Examples are SWAP 2SWAP ROT.

A duplicator copies an item from the stack.
Examples are DUP OVER 2DUP.

A sequence  of high level code
is called stable with respect to branching if there is no
branching into or out of the sequence.

A sequence  of high level code
is called stable with respect to the return stack
if it only pops, what it has pushed itself, and the stack is left
with the same depth as before.

A sequence is called stable if it is stable with respect to
anything that is relevant in the contest, mostly with respect to
everything.

@subsection Notations
In the following we will denote a stack effects as < N -- M >.
This means that N items are popped and replaced by M new items.
So 2DROP has the effect of < 2 -- 0 >.
Pointy brackets are used to make a distinction with the usual stack effect
notation.
@subsection Optimisations
Optimisations are manipulations on a program source, intermediate code
or machine code to improve the speed of the resulting program.
In other respect the result is inferior. Symbolic debugging --
one of Forth's strong points -- goes through the drain.
(The name "optimisation" is a misnomer.)

@itemize @bullet
@item
Folding.

Constant folding is a well known technique in optimisation.
It means that if an operator works on constants the result may be replaced
by a constant that is calculated at compile time.
In Forth we generalise this to folding.
Folding refers to all words that can be replaced by simpler words in case
they receive constant data on the stack.

@item
Reordering.

Reordering is not so much an optimisation per se, but it allows other optimisations
to kick in. As a rule of thumb constants are moved to the top of the stack, where
they fall prey to folding.
Reordering might also eliminate a juggler.

@item
Anihilation.

Annihilation is the elimination of a whole sequence of operations.
In Forth sometimes the result of a calculation is dropped.
Depending on the properties of the calculation,
the calculation itself can be removed.
This type of annihilation is related to an annihilator.
On closer analysis it appears that any ``no store''
sequence with a < N -- 0 > stack effect
can be replaced by N times DROP.

Another type is related to conditional branching where the condition is
known at compile time. Code known to be skipped is removed.

@item
Inlining.

Inlining means replacing a Forth word with its constituents.
This technique is very important in Forth, more so than
in other languages, due to the small size of Forth words.
Inlining is always a winner in speed, and mostly even also a
winner with regard to space.

Even more important is the fact that inlining allows folding to be applied
across constituent words. This applies to high level and low level code
alike.

Inlining high level code is trivial.
A further inlining stage replaces a high level definition that only calls code
words, by a code definition which concatenates the code words.
@end itemize

@subsection Data collecting
In order to add introspective information to a Forth, in the first
place the machine code words must be analysed, because ultimately everything is
defined in terms of code words.
For this purpose the code words are disassembled using a disassembler that
allows to readily inspect the parts of a disassembled instruction.
A Postit-Fixup assembler and disassembler is well suited.
@itemize @bullet
@item
By inspecting register words in the disassembly,
registers usage can be accumulated.
This information is then added to the header.

@item
At the same time information about whether memory or I/O ports
are accessed for read or write can be collected.
It turns out to be useful make a difference between input and output
side effects.
Here the words to look out for are the MOVE and IN/OUT instructions,
operations that access memory (in fact all operations that not target
registers) and special instructions like the string operations on
Pentia.

@item
Finally the stack effect can be deduced from the number of POP's and
PUSH'es.
And the use of the return stack can be marked, which mostly
warrants a special treatment.
@end itemize

After all code words have been analysed,
the stack effects and register usage can be concluded for all high level words.
The stack effect of a high level words is the concatenation of the stack effect
of its constituents.
The register usage of a high level word is the logical or of the
register usage of the constituents, as are its side effects.

There will no doubt be exceptions.
It is wrong to cater for too many exceptional situation in such a heuristic tool.
Instead, the exception are filled in by hand before the automated collection is started,
it fills in only as yet unknown items.
Of course it helps to have a simple and straightforward Forth to begin with.
@subsection Purpose
A \ci in general will use optimisation to generate a temporary definition
that is much faster, and retain all the valuable partial information about
words.

In normal non-AI applications, words are recursively replaced by faster words,
and those eventually by code definitions. Meanwhile words that are no longer directly
used in the final application are eliminated.
For space conservation headers may be removed as well, provided in the application
no dictionary lookup is needed.

@section Implementation
The following implementation notes apply to a 32 bits Pentium Forth
where a full cell (4 bytes, 0..3) is reserved for the flags.
They must be considered as an example.
The information about a word, optimisation opportunities and stack effect,
sits in the flag field.
Whenever nothing is filled in in the flag field, it means unknown.
This applies equally to the stack effect as to the optimisation flags.

@subsection Stack effects
The information about
the stack effects sits in the byte 3 of the flag field.
The highest nibble of this third byte applies to input.
It is the number of stack items popped plus one.
The lowest nibble thusly indicates the number of pushed items.
0 means an unknown (not yet analysed) stack effect.
0FH indicates a variable number of items.

The stack effect is added in three steps.
For all low level words the stack effect is found by counting
pops and pushes.
Irregular stack effects are corrected as well as filled in for high level words.
All high level stack effects are derived from the stack effect of their
constituents.

Code words are analysed by disassembling the code that is pointed to by the
code field to the first ``next'' code encountered. For each
instruction
the opcode, which is the first part of its disassembly, is looked up in
a set of possible pop and push instructions.

Irregularities are just tabulated in the source code of the analyser.

Words are recognized by their code field.
High level words are either created by ``:'' or by
a ``CREATE .. DOES>'' construction .
They are recognised by the code field containing DOCOL or DODOES respectively.
For both the data field points to a chain of high level calls, i.e. a number of such calls
possibly with inlined data and ending in a ``(;)'', the word compiled by ``;''.
(The result of this ``high level next'' is to return
control is returned to the word that called this one.)
For a linear chain of calls the stack effect is calculated as follows:

@itemize @bullet
@item
Start with a effect of < 0 -- 0 >
@item
For each constituent
@*
    Subtract the pops from the left (output) nibble.
    If the output nibble is negative, add its (absolute) value to inputs, and make it zero.
    Add the pushes to the left (output) nibble.
(Correction by 11H is not yet done).

@*
The following exceptions to a linear chain have special treatment:
@item
LIT BRANCH'es and SKIP are followed by inline data that must be taken care off
@item
A BRANCH or 0BRANCH forward is always taken, analysing just one path through a
definition: the shortest one. A more sophisticated way is to analyse
all paths and conclude a variable outcome if it is not consistent or
any of the paths contains a variable constituent.
@item
If the stack effect of a constituent is variable, the result is
variable, overruling any other outcome
@item
If the stack effect of a constituent is unknown, the result is
unknown, overruling any other outcome except variable.
@item
 For a CREATE .. DOES> word the linear chain pointed to by the DOES> pointer is
analysed. However the stack effect is initialised to < 0 -- 1 > to reflect the
passing of the data pointer to the  DOES> part.
@item
'<SOME-WORD> EXECUTE has the stack effect of <SOME-WORD> .
Other occurrences of EXECUTE lead to a variable stack effect.
Lateron we will leave this to the optimiser, but at the stage of
analysing the kernel this is useful, especially because all usage of
EXECUTE in the kernel is of this type.
@item
'<SOME-WORD> CATCH has the stack effect of <SOME-WORD> plus an extra output.
Other occurrences of CATCH lead to a variable stack effect.
So a word is treated as if exceptions do not occur.
This is okay because the stack effect is not relevant in case of
exceptions.
@end itemize

A high level word is recognised by its code field address containing DOCOL , i.e. the
nesting routine for the interpreter.
A CREATE .. DOES> word is detected by
is code field address containing DODOES , i.e. the common code that starts up words defined
by compiler extension.
All other words are treated as code.

The whole of Forth is treated as follows:
@itemize @bullet
@item
Fill in the exception
@item
Fill in the code words
@item
Sweep repeatedly through the dictionary, from early to latest:
    For each unknown stack effect, try to find it by discriminating between
    DODOES DOCOL and other words,
  Stop if no progress is made any more.
@end itemize

Hopefully everything is known now, but maybe we must add to the exceptions.
And repeat the above process.

The notion of a simple sequence is one that doesn't reach to the stack outside
what is defined within the sequence.

@subsection Optimisation classes
As has been pointed out, the optimisation class of a word is indicated by a bit
set
in the flags field. Each bit set to true opens up a particular opportunity for optimisation.
Further
a sequence has a certain class if each constituent has that class.
For example, if one of the words called does a store, the sequence is found to
do a store and the optimisations that would be allowed by ``no
stores''
are blocked.
So the optimisation class of a sequence is the logical or of the oc's of the constituents.
This can be done efficiently by bit-wise or operations.
@subsubsection The no store bit.
The "no store" bit would better be named "no output side effect" bit.
It indicates that the outside world doesn't change by executing this word.
Again not that the stacks and internal registers are inside.
Note that fetching from an input port has an output side effect, (as
well as an input side effect.)

The following optimisation are opened up:
@itemize @bullet
@item
In combination with an annihilator. If the output of a "no store" sequence is annihilated,
the whole sequence and the annihilator may be left out.
Example: BASE CELL+ @ XX @ NIP becomes XX @
@item
In combination with a juggler. If the outputs of "no store" sequence are juggled,
the sequences itself may be juggled, eliminating the juggler.
Example: XX CELL+ @ BASE @ SWAP becomes BASE @ XX CELL+ @
@item
In combination with a duplicator. Again a sequence may be duplicated and the duplicator
eliminated. This is not an optimisation, except for the duplication of constants.
Going the other direction can be an optimisation.
Two identical sequences with no output side effect can be replaced by one and a duplicator.
Example: (for a recursive definition with stack effect < 1 -- 1 > and no side effects)
12 RECURSE OVER RECURSE becomes 12 RECURSE 12 RECURSE  (elimination duplicator)
@*
12 RECURSE 12 RECURSE becomes 12 RECURSE DUP. (introducing duplicator)
@end itemize

@subsubsection The no fetch property.
The "no fetch" bit would better be named "no input side effect" bit.
It indicates that the outside world affects the outcome of this word.
Input side effects are weaker than output side effects and the
knowledge that they are absent allows less optimisation.

@subsubsection The no stack effect property.
The "no stack effect fetch" bit refers to absolute accesses of the stacks,
i.e. where the data or return stack are not used as stacks.
Typical examples are DEPTH and RSP@.
These words are rare but prevent considerable optimisation.

@subsubsection The no side effect property.
The combination of the ``no store '', ``no fetch '' and ``no stack effect ''
properties is quite common. Such a word is said to have the ``no side
effect'' property.
The combination allows substantially more optimisation than
each alone. We will use the abbreviation NS for this important concept.
Examples are CONSTANT's, VARIABLE's, operators like + or NEGATE, and all stack
manipulations: jugglers, annihilator, duplicators.

NS-words are amenable to folding:
@itemize @bullet
@item
If a NS-sequence has only constant inputs, it may be run at compile time.
Its inputs and the code sequence may be replaced by the resulting constant outputs.
Example: After "12 4 3 SWAP * +" is replaced by 24.
@item
If a NS-sequence has no inputs, it may be run at compile time
and replaced by the resulting constant outputs.
The difference with the preceeding example is that the sequence starts
with 12 instead of *. Any literals are of course NS.
@end itemize

On closer inspection the second condition is equivalent to the first.
It is the more easy one to implement.
@subsubsection Associativity.
An operator with two inputs and one output, so called ``binary operators''
can have, in addition to NS,
the property of associativity. This refers to a situation where three
operands are involved. Examples are OR and + . However @b{not F+} .
In the following we will denote an associative operator by %.
Associativity allows to replace the sequence ``x % y %'' with ``x y % %'' where
it may be that ``x y %'' can be folded into a constant.
Example: (assuming a 64-bit Forth)
``CELL+ CELL+'' is first inlined to ``8 + 8 +'' then associated to ``8 8 + +''
then folded to ``16 +''.
@*
Note that it is not necessary to look for other patterns, in view of other
transformation that are done.

@subsubsection Short circuit evaluation.
Another optimisation aplicable to binary NS-operators is short circuit
evaluation. This is the situation where the result is known, while only
one of the operands is known, such as ``FFFF AND'' ``FFFF OR'' ``0 +''
``0 XOR'' and ``0 *''. Some of these operations can be just dropped,
while in other cases the result is known and the other operand
(possibly non-constant) can be dropped.

@subsection Optimisation by recursive inlining
A word is optimized by first optimizing its constituents, then
inlining the constituents and apply any optimisation
opportunities like folding that open up.

@*
In more detail we have the following steps:
@itemize @bullet
@item Check.

First of all check whether the item has been optimised already.
We do in fact a ``depth first'' optimisation, so the words
lowest in the call hierarchy are optimised first. It is important
to only attempt optimisation once. This cuts the recursion short.
@item   Recurse

For all constituent words of this definition, do an optimisation, such
as defined in these steps.
@item Inline.

Build up an executable sequence in the dictionary.
Inline a constituents word, keeping track of all opportunities to
optimise.

@item Folding
Try to build up a sequence  of NS-words
that starts with constants
and where each word following doesn't consume more inputs than
are available. Consequently the outputs are available as constants.
(In the example program this can be done at the same time as the inlining.
Maybe that is unwise.)

@item Breakdown.

When a sequence of NS-words breaks down, we have identified a sequence
that can be run at compile time. This sequence is run, and removed from
the output sequence. Then the output of the run is compiled, as a
sequence of constants.

A more sophisticated method guarantees that constants move to the top
as late as possible, which is favourable for other optimisations.
In behalf of this, before compiling the sequence of constant,
the code that follows is inspected.
If a sequence is found with a < 0 -- 0 > effect, that sequence
is placed in front of the constants. The sequence need not have any special
properties, except for the weak ``no stack side effect'' property.
If a sequence is found with a < N -- 0 > effect and N is smaller than the number of
constants, a sequence with a < 0 -- 0 > is can be constructed by adding
N of the constants in front of it. The N constants are added to the output
sequence, followed by the ``no stack side effect'' sequence and the other,
very first, constants.

@item Special opportunities.

After inlining the sequence
is checked whether it allows
special optimisations, by comparing it to
a table of patterns.
Examples are the associativity optimisation
with a ``operand % operand %'' pattern, and
the execute optimisation with a ``literal EXECUTE'' pattern.
In a fashion similar to the inlining a new sequence is
built up.
If there was any improvement, a new folding step must be attempted.
@item Replace.

After inlining is finished, the sequence is now attached to the word
we are optimizing to replace the original sequence. Maybe the original code is
kept if no folding took place and/or the sequence is longer that a certain limit.
@item Mark properties
The current word is marked as optimised. Its stack effect and its optimization
classes are derived from its constituents and added to the flags header.
@end itemize
@subsection Inlining and control words
In the following with control words we will indicate words
like BRANCH DO and EXIT that affect the flow of the program.

With respect to control words the optimiser will have as a goal to
ultimately only have a body of code that consists of basic blocks
(Dragon book terminology) i.e. straight code ending in a
branch or a conditional branch, where branches only end at a the start
of a basic block.

Thereafter the code can be replaced by machine code as is found in the
constituent words. This code is inspected by a peep hole optimiser,
eliminating e.g. a push pop sequences. In exceptional cases Forth
calls to high level code, may need to be inserted, which block
probably most possibilities for further optimisation.

Originally a DO LOOP looks like
(DO) OFFSET .... (LOOP) .
A LEAVE returns to after (LOOP) by discarding return stack parameters.
The OFFSET allows (DO) to find the return address.
In order to optimise
this DO LOOP was replaced by a (DO) _ ... 1 (+LOOP) 0BRANCH OFFSET
UNLOOP.
Here (+LOOP) leaves a flag.
The new (+LOOP) has now normal inlinable word.

Now LEAVE must be replaced by a branch to UNLOOP.

DO OFFSET can be inlined to _ 2>R . The dummy return address is no
longer used, and hopefully will be removed by further optimisation.

The
EXIT must be replaced by a branch to the end of the word.
Then this can be unlined as is.

Recursion represents a problem. Surely a recursive word without
side effects can be optimised if the input is constant.
The word RECURSE can be replaced by inlining the word itself,
which may make sense if it triggers folding operations.
Tail call replacement is easy enough.
Replacing a recursive word by low level code is not straightforward
because one of the constituent words, i.e. itself, is not available
in machine code form. A recursive word without side effects may be
memoized to advantage though.




@node Errors, Documentation, Optimiser, 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 error 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 up the error 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, and document it.
@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 the names as defined in the standard are in upper case
and lina64 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 -a} or
@samp{lina -r} you have @code{WANTED}
@findex WANTED
 and @code{WANT}
@findex WANT
 available.
You may now issue @samp{  WANT CASE-INSENSITIVE } 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{"/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 system-wide library file.

You may always edit and use a private copy of the library file.
The @samp{-i} options installs a copy of ciforth to wherever you want,
and you can edit there.
Or you can copy the official library file, and edit the copy, then use it
by the @samp{-l} option.
@xref{Manual}, for how options 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 lina64, but maybe by
other version of ciforth or even a differently configured lina64.
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.
An explanation of the error is available in the manuals only.


@samp{ciforth ERROR # -2 : No such file }

is an example of a Linux message.
.

Here are the error explanations.
@itemize @bullet
@item
@samp{ciforth ERROR # XXX : ( NO TEXT MESSAGE AVAILABLE FOR THIS ERROR )}

This is the only messages that is common to more errors,
anything goes at the place of XXX.
It means that information about this error is not in the library,
but the error number remains to identify the error.
The error number is probably used by user programs and hopefully documented there.
So you can allocate error numbers not yet in use,
and use them to identify your error situations.
You can add messages to the library, but errors outside of the
range [ -256 63 ] need an edit of the source,
or regeneration using adapted values of  M4_ERRORMIN M4_ERRORMAX .

@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 inappropriate.

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

 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 : ERROR ACCESSING BLOCKS FROM MASS STORAGE}

An access to the Library Accessible by Block (screen aka block
file) has failed.
Or if you are an advanced user, and used the block
system at your own discretion, it simply means that access to the
blocks 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.
Otherwise you get this message too.

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

A word can be compiled before it is fully defined, with a standard
idiom like @code{DEFER}
@findex DEFER
 or ciforth idiom @code{:F}
@findex :F
.
If it is still not fully defined when it is used, this error is
issued.

@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
 namespace, 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, such 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 temporarily, 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,
use @code{WANT -scripting-}
@findex WANT -scripting-
 .


@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
 )

This detection mechanism
 makes it impossible to compile some constructions allowed
by the ISO standard.
You may disable this checking by @code{NO-SECURITY}
@findex NO-SECURITY
 and
re-instate it by @code{DO-SECURITY}
@findex DO-SECURITY
.
You can compile even combination of @code{DO}
@findex DO
 and
@code{BRANCH}
@findex BRANCH
 controls after
    @code{WANT -tricky-control- }
@findex WANT -tricky-control- 



@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 WANTED}
This error is reported by @code{WANTED}
@findex WANTED
.
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{-scripting-}.
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.

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

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

@item
@samp{ciforth ERROR # 33 : INPUT EXHAUSTED}

A parsing word doesn't find the input it expects, even after
@code{REFILL}
@findex REFILL
.

@item
@samp{ciforth ERROR # 40 : REGRESSION TEST FAILS, STACK DEPTH ERROR}

This message is detected by @code{REGRESS}
@findex REGRESS
 . It means that the number
of stack items left by the test, doesn't agree with the number of items in the
result specification.

@item
@samp{ciforth ERROR # 41 : REGRESSION TEST FAILS, RETURN VALUE ERROR}

This message is detected by @code{REGRESS}
@findex REGRESS
 . It means that the
stack items left by the test, don't agree with items in the result
specification.

@item
@samp{ciforth ERROR # 42 : REGRESSION TEST MALL-FORMED, SECOND PART MISSING}

This message is given by @code{REGRESS}
@findex REGRESS
 if there is no @code{S:}
@findex S:
 part.

@item
@samp{ciforth ERROR # 48 : NO BUFFER COULD BE FREED, ALL LOCKED}

While a block is in use by @code{THRU}
@findex THRU
, it is @dfn{locked}
@cindex locked
,
which means that it must stay in memory.
In addition blocks can be locked explicitly by @code{LOCK}
@findex LOCK
.
If a free block is needed, and there is no block that can be written
back to the mass storage (disk or flash), you get this error.
@item
@samp{ciforth ERROR # 49 : EXECUTION OF EXTERNAL PROGRAM FAILED}
The word @code{SYSTEM}
@findex SYSTEM
 detected an error while trying to execute
an external program.
@item
@samp{ciforth ERROR # 50 : NOT ENOUGH MEMORY FOR ALLOCATE}
The dynamic memory allocation could not allocate a buffer of the
size wanted, because there is not enough
consecutive memory available.
Fragmentation can cause this to happen while there is more than
that size available in total.
This is detected by @code{ALLOCATE}
@findex ALLOCATE
 or @code{RESIZE}
@findex RESIZE
 .

@item
@samp{ciforth ERROR # 51 : UNKNOWN FORMAT IDENTIFIER}
This error is detected by the @code{FORMAT}
@findex FORMAT
 wordset.
The word following @kbd{%} in a format string, is not known.
This means that it is not present in the @dfn{namespace}
@cindex namespace
 @code{FORMAT-WID}
@findex FORMAT-WID
.

@item
@samp{ciforth ERROR # 52 : CANNOT HEAPIFY BUFFER}
This error is detected by the @code{ALLOCATE}
@findex ALLOCATE
 wordset.
The buffer you want to use as or add to the heap space,
must be outside already existing heap space.
This error results if you violate this rule.
It may also result from corruption of the allocation system,
such a writing outside designated space.

@end itemize

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

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

The homepage of this Forth is

http://home.hccnet.nl/a.w.m.van.der.horst/lina.html
@*

It is based on a generic system available via

http://home.hccnet.nl/a.w.m.van.der.horst/ciforth.html
@*

The implementation of this Forth is indebted to FIGForth

http://home.hccnet.nl/a.w.m.van.der.horst/fig-Forth.html
@*

A tutorial in English (and Dutch) is to be found at

https://forth.hcc.nl/w/Ciforth/Ciforth?setlang=en
@*


The most important general Forth site is

http://www.forth.org

with links to all
Forth chapters and commercial and free Forth implementation.
@*

Like all modern languages the Forth ISO standard is available on the web

http://www.taygeta.com/forth/dpans.htm
@*
The official, printed manual by the Amercian National Standards Institute
commands a stiff price.
@*


In print
@itemize @bullet
@item
Starting forth by Leo Brodie

A classic still worth reading, despite its age. You must adapt the examples
in order to use it with an ISO Forth,
A modernized version is available online at
@*
http://www.forth.com/starting-forth/

@item
Going Forth by Leo Brodie
@*
More timeless, maybe even more important, about the filosofy of Forth.

@item
The German Fig Chapter has a publication: Vierte Dimension.
@end itemize

For historic interest the following is copied from the FIG documentation 1978.

Caltech FORTH Manual, an advanced manual with internal details of Forth. Has
Some implementation peculiarities. The Caltech Book Store, Pasadena, CA.

Kitt Peak Forth Primer, edited by the Forth Interest Group, P. O.
Box 1105, San Carlos, CA 94070.

microFORTH Primer, 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
 64 bits is meant.
Wherever it says
 @dfn{double}
@cindex double
 or ``double precision number'' a
128
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
128 bit signed double integer: most significant portion with sign
on top of stack
@item dea
A @dfn{dictionary entry address}
@cindex dictionary entry address
 , the basic address of a Forth word from which
all its properties 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
64 bit signed integer number;
it is also used for a 64-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, starting at the address
(they must not be changed)
@item true
a true @dfn{Forth flag}
@cindex Forth flag
: -1.
@item u
64-bit unsigned integer, also used whenever a cell is considered as a
bitset.
@item ud
128-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 C
May only be used within a colon definition.
@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 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 P
Word is a prefix, interprets and optionally compiles remainder of word.
@item WANT
Word is not in the kernel, use the @code{WANT}
@findex WANT
 to load
it from the library.
These words are maintained and tested,
will only be changed with notice and an upgrade pad will be supplied.

@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 in that standard.
Words marked with @samp{ISO,FIG} will behave identically
over all but the whole spectra of Forth's.

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

All arithmetic is implicitly 64-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 ::
* INITIALISATIONS ::
* INPUT ::
* JUGGLING ::
* LIBRARY ::
* 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  ::
* -->  :next_screen
* ?DISK-ERROR  ::
* B/BUF  ::
* BLOCK-EXIT  ::
* BLOCK-FILE  ::
* BLOCK-HANDLE  ::
* BLOCK-INIT  ::
* BLOCK-READ  ::
* BLOCK-WRITE  ::
* BLOCK  ::
* DISK-ERROR  ::
* EMPTY-BUFFERS  ::
* UPDATE  ::
* (BUFFER)  :paren_buffer
* +BUF  ::
* BLOCK-SEEK  ::
* FLUSH  ::
* OFFSET  ::
* _FIRST  ::
* _LIMIT  ::
* _PREV  ::
@end menu
@node #BUFF, next_screen, 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 next_screen, ?DISK-ERROR, #BUFF, BLOCKS
@subsection -->
@pindex -->
@findex -->

@noindent
Name: @code{-->}

@noindent
No stackeffect

@noindent
Attributes: I,WANT

@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 ?DISK-ERROR, B/BUF, next_screen, 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.
It is only used to signal errors related to accessing the
@code{BLOCK-FILE}
@findex BLOCK-FILE
.


@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
 .
All blocks are unlocked.
Any changed blocks are written back to mass storage.
Close the currently open block file @code{BLOCK-HANDLE}
@findex BLOCK-HANDLE
,
such that 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 @b{forth.lab} .
This name is typically changed during installation and is used by the
 @code{BLOCK-INIT}
@findex BLOCK-INIT
 command.


@noindent
See also: @samp{BLOCK-HANDLE}
 @samp{BLOCK-INIT}
 @samp{LIST}
 @samp{LOAD}
 @samp{$@@}
 




        


@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-READ, 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 signals failure by a negative handle in @code{BLOCK-HANDLE}
@findex BLOCK-HANDLE
.
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-READ, BLOCK-WRITE, BLOCK-INIT, BLOCKS
@subsection BLOCK-READ
@pindex BLOCK-READ
@findex BLOCK-READ

@noindent
Name: @code{BLOCK-READ}

@noindent
Stackeffect: addr blk ---

@noindent
Attributes: 

@noindent
Description:
The ciforth primitive for reading of blocks. @samp{addr}
specifies the destination block buffer, @samp{blk} is
the sequential number of the referenced physical block
@code{BLOCK-READ}
@findex BLOCK-READ
 determines the location on mass storage,
performs the read and throws an exception on errors.

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



        


@node BLOCK-WRITE, BLOCK, BLOCK-READ, BLOCKS
@subsection BLOCK-WRITE
@pindex BLOCK-WRITE
@findex BLOCK-WRITE

@noindent
Name: @code{BLOCK-WRITE}

@noindent
Stackeffect: addr blk ---

@noindent
Attributes: 

@noindent
Description:
The ciforth primitive for writing of blocks. @samp{addr}
specifies the source or destination block buffer, @samp{blk} is
the sequential number of the referenced physical block.
@code{BLOCK-WRITE}
@findex BLOCK-WRITE
 determines the location on mass storage,
performs the write and throws an exception on errors.

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



        


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

@noindent
Name: @code{BLOCK}

@noindent
Stackeffect: n --- addr

@noindent
Attributes: ISO,FIG

@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{BLOCK-READ}
 @samp{BLOCK-WRITE}
 @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:

This variable is not used in ci86.lina64.html, errors are thrown.


@noindent
See also: @samp{BLOCK}
 
        


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

@noindent
Name: @code{EMPTY-BUFFERS}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG

@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 UPDATE, paren_buffer, EMPTY-BUFFERS, BLOCKS
@subsection UPDATE
@pindex UPDATE
@findex UPDATE

@noindent
Name: @code{UPDATE}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG

@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{EMPTY-BUFFERS}
 

        


@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
identification @samp{n} , probably a block number.
Block numbers are positive, so a negative value can be
used for a buffer that is used for some other purpose.
The buffer layout is as follows: a cell
with @samp{n}, a cell with the status, and the
content of length @dfn{B/BUF}
@cindex B/BUF
 .
The status is negative for locked. The l.s.b. gives
zero for free and one for valid data.
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, some non-locked buffer is freed. The
contents of that buffer is written to the disc, if it was
marked as updated. In ciforth this will never happen,
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 this ciforth. If all
buffers were locked, @code{(BUFFER)}
@findex (BUFFER)
 throws exception 48.


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




        


@node +BUF, BLOCK-SEEK, 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 BLOCK-SEEK, FLUSH, +BUF, BLOCKS
@subsection BLOCK-SEEK
@pindex BLOCK-SEEK
@findex BLOCK-SEEK

@noindent
Name: @code{BLOCK-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}
 @samp{BLOCK-READ}
 @samp{BLOCK-WRITE}
 




        


@node FLUSH, OFFSET, BLOCK-SEEK, BLOCKS
@subsection FLUSH
@pindex FLUSH
@findex FLUSH

@noindent
Name: @code{FLUSH}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG

@noindent
Description:
Make sure that the content of all @code{UPDATE}
@findex UPDATE
 d block buffers
has been transferred to disk.
The buffers are no longer associated with a block and their content is
no longer available.
In ciforth no transfer takes place,
because mass storage is updated automatically in the background.


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

        


@node OFFSET, _FIRST, FLUSH, 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.
The contents of @code{OFFSET}
@findex OFFSET
 is added to the argument
for @code{BLOCK}
@findex BLOCK
 before reading or writing blocks.
In this way a part of disc drives can be reserved for boot-code.

As blocks are allocated in a file on the host operating system it is 0.


@noindent
See also: @samp{BLOCK}
 @samp{MESSAGE}
 @samp{BLOCK-READ}
 @samp{BLOCK-WRITE}
 



        


@node _FIRST, _LIMIT, OFFSET, BLOCKS
@subsection _FIRST
@pindex _FIRST
@findex _FIRST

@noindent
Name: @code{_FIRST}

@noindent
Stackeffect: --- addr1

@noindent
Attributes: 

@noindent
Description:
A constant that leaves the address of the block
buffer lowest in memory. 

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

        


@node _LIMIT, _PREV, _FIRST, BLOCKS
@subsection _LIMIT
@pindex _LIMIT
@findex _LIMIT

@noindent
Name: @code{_LIMIT}

@noindent
Stackeffect: ---- addr1

@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 _PREV, , _LIMIT, 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 COMPILING, CONTROL,BLOCKS, Glossary
@section COMPILING
     
    The wordset @samp{COMPILING} contains words that compile
words and numbers.
They need special attention because these words in general execute during
compilation @xref{IMMEDIATE}, .
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, the number will just remain on
the stack.

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


        


@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,C

@noindent
Description:
If compiling, then compile the stack value @samp{n} as a
64 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, the number will just remain on
the stack.

@noindent
See also: @samp{LIT}
 @samp{SDLITERAL}
 @samp{STATE}
 


        


@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 the form:
    @example
@iftex
@cartouche
:  xxx ... [COMPILE] IF ...  ;
@end cartouche
@end iftex
@ifinfo
:  xxx ... [COMPILE] IF ...  ;
@end ifinfo
@end example
@code{[COMPILE]}
@findex [COMPILE]
 will force the compilation of an immediate definition,
that would otherwise execute during compilation.
The above example will perform @code{IF}
@findex IF
 when @samp{xxx}
executes, rather than introducing conditional code in @samp{xxx}
itself.


@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,C

@noindent
Description:
Within a colon-definition, @code{LIT}
@findex LIT
 is compiled followed by a
64 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.
This word is compiled by @code{LITERAL}
@findex LITERAL
 . 

@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{LITERAL}
 @samp{DLITERAL}
 @samp{STATE}
 


        




@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
* 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,C

@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}). Negative increments cannot be combined with
 @code{?DO}
@findex ?DO
 , this deviates from the ISO standard.
Upon exiting the loop, the parameters are
discarded and execution continues ahead.

At compile-time, @code{LOOP}
@findex LOOP
 compiles code to the above
effect, existing of @code{(+LOOP) 0BRANCH UNLOOP}
@findex (+LOOP) 0BRANCH UNLOOP

and uses @samp{addr} , left on the stack by @code{DO}
@findex DO
,
to calculate the branch offset from @code{HERE}
@findex HERE
.

 @samp{n2} is used for compile time error
checking.

@noindent
See also: @samp{LOOP}
 
        


@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: NISO,I,C

@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 @code{DO}
@findex DO
,
with the exception that if @samp{n1} is less than @samp{n2}
the loop body is not executed.
This is intended to suppress the unwanted behaviour of looping
through the whole number range,
ciforth deviates from ISO in that it also suppresses the unwanted
behaviour of looping through almost the whole number range for
an input of e.g.
@example
@iftex
@cartouche
1 2
@end cartouche
@end iftex
@ifinfo
1 2
@end ifinfo
@end example
However, negative increments are made impossible for forthword(?DO) this way.


@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,C

@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

@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}
 @samp{DO}
 

        


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

@noindent
Name: @code{CO}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
 Return to the caller,
suspending 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,C

@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.
With @code{+LOOP}
@findex +LOOP
 it can be used with other increments than one.

It deviates from the ISO standard in that
that if @samp{n1} is equal to @samp{n2} the loop is never
executed even once.

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,C

@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
 compiles
@code{BRANCH}
@findex BRANCH
 and reserves a places for a branch offset,
leaving its 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}
 @samp{FORWARD)}
 @samp{BRANCH}
 


        


@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,C

@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}
 @samp{0BRANCH}
 

        


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

@noindent
Name: @code{I}

@noindent
Stackeffect: --- n

@noindent
Attributes: ISO,FIG,C

@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

@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:
Terminate a do-loop by branching to directly behind the
end of a loop started by @code{DO}
@findex DO
 or @code{?DO}
@findex ?DO
 ,
so after the corresponding
@code{LOOP}
@findex LOOP
 or @code{+LOOP}
@findex +LOOP
 .

@noindent
See also: @samp{UNLOOP}
 
        


@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,C

@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 to the above
effect, existing of @code{ONE (+LOOP) 0BRANCH UNLOOP}
@findex ONE (+LOOP) 0BRANCH UNLOOP

and uses @samp{addr} to calculate an
offset to be used by @samp{0BRANCH} . @samp{n} 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,C

@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: C

@noindent
Description:
Skip over an area in memory, where the length is given in the next cell,
then align.
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,C

@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
No stackeffect

@noindent
Attributes: ISO,I,C

@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
,
but my means of @code{EXIT}
@findex EXIT
 or unstructured branching.
In this Forth the parameters are the address after
the loop
af
. 

@noindent
See also: @samp{DO}
 @samp{LEAVE}
 @samp{0BRANCH}
 @samp{(FORWARD}
 



        


@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,C

@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,C

@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: C

@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}
 @samp{UNLOOP}
 

        


@node paren_forward, 0BRANCH, 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 allocating space for an offset,
that must be backpatched into @samp{addr}.
Usage is
@samp{POSTPONE BRANCH (FORWARD .. FORWARD) } 

@noindent
See also: @samp{IF}
 @samp{BRANCH}
 @samp{0BRANCH}
 


        


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

@noindent
Name: @code{0BRANCH}

@noindent
Stackeffect: f ---

@noindent
Attributes: FIG,C

@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}
 @samp{(FORWARD}
 @samp{(BACK}
 @samp{SKIP }
 



        


@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,C

@noindent
Description:
The run-time proceedure to unconditionally branch. An in-line
offset is added to the interpretive pointer @samp{HIP} 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}
 @samp{(FORWARD}
 @samp{(BACK }
 


        


@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}
 @samp{REPEAT}
 


        




@node DEFINING, DENOTATIONS,CONTROL, Glossary
@section DEFINING
     
    The wordset @samp{DEFINING} contains words that add new entries
to the dictionary, or are related to those words.
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  ::
* DATA  ::
* DOES>  ::
* MAX-USER  ::
* NAMESPACE  ::
* USER  ::
* VARIABLE  ::
* WORDLIST  ::
* colon  ::
* (;CODE)  :paren_semicolon_code
* (CREATE)  :paren_create
* HEADER  ::
* LINK  ::
@end menu
@node ;, CONSTANT, DEFINING, DEFINING
@subsection ;
@pindex ;
@findex ;

@noindent
Name: @code{;}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,I,C

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

@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

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

@noindent
See also: @samp{VARIABLE}
 @samp{>DFA}
 

        


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

@noindent
Name: @code{CREATE}

@noindent
No stackeffect

@noindent
Attributes: ISO

@noindent
Description:
A defining word used in the form:
     @samp{CREATE cccc}
Later execution of @samp{cccc} returns its @dfn{data field}
@cindex 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 @dfn{data field}
@cindex data field
 has yet to
be allocated. The @dfn{DFA}
@cindex DFA
  (data field address) points to the
the execution action that can be changed by @code{DOES>}
@findex DOES>
 .
ciforth is byte aligned, so no extra measures are needed.

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





        


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

@noindent
Name: @code{DATA}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
A defining word used in the form:
                 @samp{DATA cccc}
When @code{DATA}
@findex DATA
 is executed,
it creates the definition @samp{cccc}
whose @dfn{data field address}
@cindex data field address
 contains a
pointer @samp{n} to @code{HERE}
@findex HERE
.
This code is typically followed by some data
allocation word like @code{ALLOT}
@findex ALLOT
 or @code{,}
@findex ,
 .
@code{DOES>}
@findex DOES>
 must not be used with @samp{cccc}.

When @samp{cccc} is later executed,
this pointer @samp{n} is left on the stack,
so that data can be accessed.

@noindent
See also: @samp{VARIABLE}
 @samp{CREATE}
 @samp{>DFA}
 


        


@node DOES>, MAX-USER, DATA, DEFINING
@subsection DOES>
@pindex DOES>
@findex DOES>

@noindent
Name: @code{DOES>}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG

@noindent
Description:
A word which is used
in combination with @code{CREATE}
@findex CREATE

to specify the run-time action
within a high-level defining word. @code{DOES>}
@findex DOES>
 modifies
the default behaviour of the created word so as to execute the sequence of
compiled word addresses following @code{DOES>}
@findex DOES>
 .
When the
@code{DOES>}
@findex DOES>
 part executes it begins with the address of
the @dfn{data field}
@cindex data field
 of the word on the stack. This allows
interpretation using this area or its contents. 
Typical uses include the Forth assembler,
arrays and matrices, and compiler generation.


        


@node MAX-USER, NAMESPACE, DOES>, DEFINING
@subsection MAX-USER
@pindex MAX-USER
@findex MAX-USER

@noindent
Name: @code{MAX-USER}

@noindent
Stackeffect: --- addr

@noindent
Attributes: U

@noindent
Description:
A user variable which contains the offset of next user variable.
It is measured in cells from the start of the user area. 

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



        


@node NAMESPACE, USER, MAX-USER, DEFINING
@subsection NAMESPACE
@pindex NAMESPACE
@findex NAMESPACE

@noindent
Name: @code{NAMESPACE}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
A defining word used in the form:
@code{NAMESPACE}
@findex NAMESPACE
 @samp{cccc} to create a
namespace 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 be
searched first by @code{INTERPRET}
@findex INTERPRET
 .
A word create by @code{NAMESPACE}
@findex NAMESPACE
 is not immediate.
This is also different among Forth implementations.

A namespace '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 namespace ("vocabulary") link
field address ( @dfn{VLFA}
@cindex VLFA
 ). The VLFA points to the VLFA
of the next namespace  or  a @dfn{nil pointer}
@cindex nil pointer
 for the end.
Then follows a wordlist @dfn{word list identifier}
@cindex word list identifier
 or @dfn{WID}
@cindex WID
 .
Executing the
namespace 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.


@noindent
See also: @samp{ALSO}
 @samp{PREVIOUS}
 @samp{WORDLIST}
 @samp{DEFINITIONS}
 @samp{FOR-VOCS}
 @samp{>WID}
 





        


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

@noindent
Name: @code{USER}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO

@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
byte offset relative to the user pointer register @samp{UP}
for this user variable, which is @samp{n CELLS}.
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 this ciforth @samp{UP} is coupled to the return stack.
This means that with a switch of the return stack,
@samp{UP} is switched also automatically. 
It is best to do
  @samp{MAX-USER @@ DUP USER cccc    1 MAX-USER ! }
reflecting the current allocation in the user area.


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



        


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

@noindent
Name: @code{VARIABLE}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG

@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}
whose @dfn{data field address}
@cindex data field address
 contains a
pointer @samp{n} to a data location,
that can contain one cell.
When @samp{cccc} is later executed,
this pointer @samp{n} is left on the stack,
so that a fetch or store may access this location.

@noindent
See also: @samp{USER}
 @samp{CONSTANT}
 @samp{>DFA}
 @samp{DATA}
 



        


@node WORDLIST, colon, VARIABLE, DEFINING
@subsection WORDLIST
@pindex WORDLIST
@findex WORDLIST

@noindent
Name: @code{WORDLIST}

@noindent
Stackeffect: --- wid

@noindent
Attributes: ISO

@noindent
Description:
This words creates an empty wordlist which is a single header
structure @dfn{dea}
@cindex dea
 that serves as a
@dfn{word list identifier}
@cindex word list identifier
 or @dfn{WID}
@cindex WID
 in the sense of
the ISO standard.
Definitions will be added to it after it has been copied to
@code{CURRENT}
@findex CURRENT
.
This handle can be placed in the top of the search order
@code{CONTEXT}
@findex CONTEXT
 and the wordlist will be searched.
This word underlies @code{NAMESPACE}
@findex NAMESPACE
, there is no @dfn{VLFA}
@cindex VLFA
.

A wid's significant fields are the flag field and the link field.
The flag field indicates
that it is dummy, i.e. not intended to be executed.
The @dfn{link field address}
@cindex link field address
 contains the @dfn{dea}
@cindex dea
 of
the latest word of the wordlist or a @dfn{nil pointer} if empty.
The namefield points to an empty string


@noindent
See also: @samp{NAMESPACE}
 @samp{ALSO}
 @samp{>FFA}
 @samp{>LFA}
 @samp{FOR-WORDS}
 




        


@node colon, paren_semicolon_code, WORDLIST, DEFINING
@subsection colon
@pindex colon
@findex colon

@noindent
Name: @code{colon}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,E

@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 @dfn{immediate}
@cindex immediate
 bit set, attribute @samp{I},
are executed rather than being compiled.

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


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

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

@noindent
No stackeffect

@noindent
Attributes: WANT,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{;CODE}
 
        


@node paren_create, HEADER, 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, including
those which lack a data field in the ISO sense: @code{:}
@findex :
 @code{USER}
@findex USER
 @code{VARIABLE}
@findex VARIABLE

@code{NAMESPACE}
@findex NAMESPACE
 @code{CONSTANT}
@findex CONSTANT
 @code{DATA}
@findex DATA
 .
It creates a header with name @samp{sc} in the dictionary and
links it into the @code{CURRENT}
@findex CURRENT
 word list.


@noindent
See also: @samp{HEADER}
 @samp{LINK}
 @samp{CREATE}
 


        


@node HEADER, LINK, paren_create, DEFINING
@subsection HEADER
@pindex HEADER
@findex HEADER

@noindent
Name: @code{HEADER}

@noindent
Stackeffect: sc --- dea

@noindent
Attributes: 

@noindent
Description:
Create a dictionary entry structure for the word @samp{sc} and
returns its address into @samp{dea}.
A pointer to each of its fields is called a "field address" for
code data flag line name source extra.
In particular  that a data field address is not a @dfn{data field}
@cindex data field

in the ISO sense.
 @code{HEADER}
@findex HEADER
 initializes the @dfn{code field addres}
@cindex code field addres
 and
@dfn{data field address}
@cindex data field address
 to contain a same pointer
to the area owned by this header,
i.e. immediately following the completed header as
appropriate for a low level (assembler) definition.
The flag and link fields are initialised to
zero , so not @code{HIDDEN}
@findex HIDDEN
.
The name @samp{sc} is laid down in the dictionary before
the header and filled in into the name field.
The source field is filled in to best knowledge.


@noindent
See also: @samp{(CREATE)}
 @samp{>CFA}
 @samp{>DFA}
 @samp{>FFA}
 @samp{>LFA}
 @samp{>NFA}
 @samp{>SFA}
 @samp{>XFA}
 @samp{LINK}
 








        


@node LINK, , HEADER, DEFINING
@subsection LINK
@pindex LINK
@findex LINK

@noindent
Name: @code{LINK}

@noindent
Stackeffect: dea wid ---

@noindent
Attributes: 

@noindent
Description:
Links the Forth word represented by @samp{dea} into the wordlist
represented by @samp{wid} as the latest entry.
Alternatively, consider @samp{wid} as an other
@samp{dea2}. Link @samp{dea} between the @samp{dea2}
and its successor in the linked list.


@noindent
See also: @samp{HEADER}
 @samp{(CREATE)}
 

        




@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
 . @code{PREFIX}
@findex PREFIX
 turns the latest definition into
a prefix, similar to @code{IMMEDIATE}
@findex IMMEDIATE
.
If a word starting with the prefix is looked up in the dictionary,
the prefix is found and executed.
Prefix 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 wordlist, associated with the namespace @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 consists of the one character following
``Prefix_''.
Apart from @code{Prefix_0}
@findex Prefix_0
 , @code{ONLY}
@findex ONLY
 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.
The use of prefixes for other purposes than denotations require great care.

    

    

@menu


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

@noindent
Name: @code{Prefix_"}

@noindent
Stackeffect: --- sc

@noindent
Attributes: I,P

@noindent
Description:
Parse a @kbd{"} delimited string and leave it on the stack
as a @dfn{stringconstant}
@cindex stringconstant
 , i.e. an address and a length.
A @kbd{"} can be embedded in a string by doubling it.
The string is permanent and takes dictionary space.
The cell below the address contains the length,
so @samp{DROP 1 CELLS  - } can be used as a single cell reference.
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: I,P

@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: I,P

@noindent
Description:
A prefix that handles numbers that start with
@kbd{+} .

@noindent
See also: @samp{NUMBER}
 @samp{(NUMBER)}
 @samp{7}
 @samp{B}
 



        


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

@noindent
Name: @code{Prefix_-}

@noindent
Stackeffect: --- s/d

@noindent
Attributes: I,P

@noindent
Description:
A prefix that handles numbers that start with
@kbd{-} .

@noindent
See also: @samp{NUMBER}
 @samp{(NUMBER)}
 @samp{7}
 @samp{B}
 



        


@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: I,P

@noindent
Description:
A prefix that handles 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{NUMBER}
 @samp{(NUMBER)}
 @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: I,P

@noindent
Description:
A prefix that handles numbers that start with
@kbd{7} . Similar words are present for all decimal and hex digits.


@noindent
See also: @samp{NUMBER}
 @samp{(NUMBER)}
 @samp{0}
 @samp{B}
 



        


@node den_b, tick_denotation, den_seven, DENOTATIONS
@subsection Prefix_B
@pindex Prefix_B
@findex Prefix_B

@noindent
Name: @code{Prefix_B}

@noindent
Stackeffect: --- s/d

@noindent
Attributes: I,P

@noindent
Description:
A prefix that handles numbers that start with
@kbd{B} . Similar words are present for all decimal and hex digits.


@noindent
See also: @samp{NUMBER}
 @samp{(NUMBER)}
 @samp{0}
 @samp{7}
 



        


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

@noindent
Name: @code{Prefix_TICK}

@noindent
Stackeffect: --- addr

@noindent
Attributes: I,P

@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 @dfn{dea}
@cindex dea
 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 compile mode it finds the same address,
then compiles it as a literal.
It is recommended that one never compiles or postpones it.
(Use a
combination of @code{NAME}
@findex NAME
 and @code{FOUND}
@findex FOUND
 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{HEADER}
 @samp{CONTEXT}
 @samp{'}
 @samp{[']}
 @samp{PRESENT}
 @samp{>CFA}
 @samp{>DFA}
 @samp{>FFA}
 @samp{>LFA}
 








        


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

@noindent
Name: @code{Prefix_^}

@noindent
Stackeffect: --- b

@noindent
Attributes: I,P

@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 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
* 2,  :two_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  ::
* 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

@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
@dfn{dea}
@cindex dea
 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{NAME}
@findex NAME
 and @code{FOUND}
@findex FOUND
 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, two_comma, tick_iso, DICTIONARY
@subsection ,
@pindex ,
@findex ,

@noindent
Name: @code{,}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,FIG

@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 two_comma, >BODY, comma, DICTIONARY
@subsection 2,
@pindex 2,
@findex 2,

@noindent
Name: @code{2,}

@noindent
Stackeffect: d ---

@noindent
Attributes: ISO,FIG

@noindent
Description:
Store the most significand cell of @samp{d} into the next available dictionary
cell, advancing
the @dfn{dictionary pointer}
@cindex dictionary pointer
, then the least significand one.
. 

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

        


@node >BODY, ALLOT, two_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>}
 @samp{DATA}
 





        


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

@noindent
Name: @code{ALLOT}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,FIG

@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{HERE}
 @samp{,}
 

        


@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 @dfn{data field}
@cindex data field
 @samp{addr} of a definition created
with a @code{CREATE}
@findex CREATE
 / @code{DOES>}
@findex DOES>
 construct
to its @samp{dea}.
( @samp{addr} is not a header @dfn{data field address}
@cindex data field address
)
Where @code{>BODY}
@findex >BODY
 keeps working for a copy of the header,
@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 the least significand 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,WANT

@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.
In ciforth the alternative @code{FOUND}
@findex FOUND
 is used,
that uses a regular @dfn{stringconstant}
@cindex stringconstant
 ,
hence this is a loadable extension.


@noindent
See also: @samp{FOUND}
 @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

@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.
The @code{dea}
@findex dea
 allows to retrieve all properties of the word
such as whether it is immediate.


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





        


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

@noindent
Name: @code{HERE}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO,FIG

@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 special 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

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


        


@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{denotation}
@cindex denotation
's 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. Some prefixes, like @code{Prefix_7}
@findex Prefix_7
, decrement the
parse pointer by one before starting to parse.
Prefix words are 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.
Postponing prefix words voids your warranty.
 It is recommended that the only smart words present are
 prefix words. 

@noindent
See also: @samp{PP@@@@}
 @samp{IMMEDIATE}
 @samp{Prefix_0}
 @samp{ONLY}
 



        


@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 @dfn{denotation}
@cindex denotation
 word, the
name must match @samp{sc} exactly.

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




        


@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
, or don't want to,
you use a combination of
@code{NAME}
@findex NAME
 and @code{FOUND}
@findex FOUND
 (or @code{WORD}
@findex WORD
 and @code{FIND}
@findex FIND
) instead.

 

@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
namespace, 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{FOUND}
 @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.
In ciforth it has offset 0, so it is actually the
same as the @dfn{dea}
@cindex dea
.

@noindent
See also: @samp{Prefix_'}
 @samp{HEADER}
 

        


@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 contains a pointer to the code for a code word,
to the data for a word defined by @code{VARIABLE}
@findex VARIABLE
 or @code{DATA}
@findex DATA
 ,
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{Prefix_'}
 @samp{>BODY}
 @samp{HEADER}
 


        


@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{Prefix_'}
 @samp{HEADER}
 @samp{IMMEDIATE}
 @samp{PREFIX}
 



        


@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 @dfn{dea}
@cindex dea
 of the previous word. 

@noindent
See also: @samp{Prefix_'}
 @samp{HEADER}
 

        


@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{Prefix_'}
 @samp{HEADER}
 @samp{ID.}
 


        


@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{Prefix_'}
 @samp{HEADER}
 @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}.
If its content is higher than 1000, that is a pointer to
after the name of the definition in the source code.
This assumes that the source is still present in memory, which is true
during development.
If the content is zero, it is a kernel word and the source is not
available interactively.
Otherwise it is the block number from which the definition was compiled.
No attempt is made to erase this information when it becomes
incorrect, for e.g. turnkey programs.


@noindent
See also: @samp{Prefix_'}
 @samp{HEADER}
 

        


@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 namespace
return the address of the link to the next namespace.
Traditionally this was called vocabulary, hence the @kbd{V}.


@noindent
See also: @samp{NAMESPACE}
 @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
namespace return its
@dfn{WID}
@cindex WID
 @samp{wid}, a dummy @dfn{dea}
@cindex dea
 that serves as the start of a
dictionary search. 

@noindent
See also: @samp{NAMESPACE}
 @samp{>VFA}
 @samp{(FIND)}
 


        


@node >XFA, FENCE, >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} .
This is a field in the header that is free for an application to use
for whatever purpose.


@noindent
See also: @samp{Prefix_'}
 @samp{OPT}
 @samp{HEADER}
 


        


@node FENCE, FOR-VOCS, >XFA, 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 dea --- x1...xn

@noindent
Attributes: 

@noindent
Description:
For all words starting with and including @samp{dea}
execute @samp{xt}
 with as data @samp{x1..xn} plus
the @dfn{dea}
@cindex dea
 of those words by following the link fields.
@samp{xt}
must have the stack diagram @samp{x1..xn dea' --- x1..xn}.
Mostly the dea will identify a WID.
In that case all words of a wordlist are handled.
If you don't want to include the WID itself, you can ignore
it based on the dummy flag in its flag field.
Note that you can use the @dfn{dea}
@cindex 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 @dfn{dea}
@cindex dea
 is greater (which mostly means 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 namespace 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:

This is a vector in behalf of optimisation,
that starts as a noop, and
can be filled in if the extra field is used for optimisation.
It must adhere to the following specification:
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.


@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}'s name,
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 contains a pointer to a string
variable, which may contain an empty string.


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

        




@node DOUBLE, ENVIRONMENTS,DICTIONARY, Glossary
@section DOUBLE
     
    The wordset @samp{DOUBLE} contains words that manipulate @dfn{double}
@cindex double
's.

    

    

@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
 namespace and those words needed
to recognize them as Forth environment queries.
Note that these are not environment variables in
the sense that they 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
 namespace and @samp{i*x} is
what is left by the word if executed.


@noindent
See also: @samp{NAMESPACE}
 
        


@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 "5.4.1" 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 signaled by the kernel go through this word.


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


        


@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,C

@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, clamped to the range [-256, 63].
This word is executed by @code{THROW}
@findex THROW
 before restarting the interpreter
and can be revectored to give more elaborate diagnostics,
or even do a last minute recovery. 

@noindent
See also: @samp{MESSAGE}
 @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 infeasible.


@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.
If @code{WARNING}
@findex WARNING
 is zero (disc unavailable), this is a noop.
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
.
A certain range around 0 is reserved.
The messages with small positive offset contain ciforth error messages.
The messages with small 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
where the messages sit in.


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

        


@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 assumed to be open,
and messages are fetched from it.
If it is 0,
error messages will be presented by number only.


@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
position after the last character parsed when an error 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 also are underlying the @samp{BLOCKS} facilities.
    

    

@menu


* CLOSE-FILE  ::
* CREATE-FILE  ::
* DELETE-FILE  ::
* FILE-POSITION  ::
* GET-FILE  ::
* INCLUDED  ::
* INCLUDE  ::
* 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, usable as a throw code.

@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 fam --- fileid ior 

@noindent
Attributes: ISO

@noindent
Description:
 Create a file with name @samp{sc} and file
access method @samp{fam} .
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, so @samp{fam} is
in fact ignored.
The access privileges default to octal 755.
This can be changed by applying @code{mask 8 LSHIFT OR}
@findex mask 8 LSHIFT OR
 where
 @code{mask}
@findex mask
 contains the privilege bits one wants to change.


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



        


@node DELETE-FILE, FILE-POSITION, 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}
 



        


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

@noindent
Name: @code{FILE-POSITION}

@noindent
Stackeffect: fd --- ud ior 

@noindent
Attributes: ISO

@noindent
Description:

@samp{ud} is
the file current position for the file that is open at @samp{fd}.
@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{REPOSITION-FILE}
 

        


@node GET-FILE, INCLUDED, FILE-POSITION, 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.
The file is permanently stored at @code{HERE}
@findex HERE
 .


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


        


@node INCLUDED, INCLUDE, 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}.
The file is permanently stored in the dictionary,
but trimmed in compiled programs.


@noindent
See also: @samp{LOAD}
 @samp{INCLUDE}
 

        


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

@noindent
Name: @code{INCLUDE}

@noindent
Stackeffect: "name" --- i*x

@noindent
Attributes: ISO

@noindent
Description:
Interpret the content of the file with "name"
as if it was typed from the console, leaving result
@samp{i*x}.
The file is permanently stored in the dictionary,
but trimmed in compiled programs.


@noindent
See also: @samp{LOAD}
 
        


@node OPEN-FILE, PUT-FILE, INCLUDE, 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, usable as a throw code.
 @samp{fam} is one of 0=READ_ONLY, 1=WRITE_ONLY, 2=READ_WRITE.
all files are opened in binary mode.


@noindent
See also: @samp{READ-FILE}
 @samp{WRITE-FILE}
 @samp{CREATE-FILE}
 @samp{DELETE-FILE}
 @samp{CLOSE-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{sc1} to a file with
the name @samp{sc2}. 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, usable as a throw code. 

@noindent
See also: @samp{OPEN-FILE}
 @samp{WRITE-FILE}
 @samp{REPOSITION-FILE}
 @samp{BLOCK-READ}
 



        


@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, usable as a throw code.


@noindent
See also: @samp{OPEN-FILE}
 @samp{READ-FILE}
 @samp{REPOSITION-FILE}
 @samp{BLOCK-WRITE}
 



        


@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}
 @samp{ZEN}
 


        




@node FORMATTING, INITIALISATIONS,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  ::
* ECL  ::
* FLD  ::
* HLD  ::
* NUMBER  ::
@end menu
@node #>, #S, FORMATTING, FORMATTING
@subsection #>
@pindex #>
@findex #>

@noindent
Name: @code{#>}

@noindent
Stackeffect: d --- sc 

@noindent
Attributes: ISO,FIG

@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

@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

@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}
 @samp{HLD}
 

        


@node <#, >NUMBER, #, FORMATTING
@subsection <#
@pindex <#
@findex <#

@noindent
Name: @code{<#}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG

@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}
 @samp{DPL}
 


        


@node BASE, DECIMAL, >NUMBER, FORMATTING
@subsection BASE
@pindex BASE
@findex BASE

@noindent
Name: @code{BASE}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO,FIG,U

@noindent
Description:
A @dfn{user variable}
@cindex 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

@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

@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:
Add an ASCII minus-sign @kbd{-} inside a @code{<#}
@findex <#
 and @code{#>}
@findex #>

construct to the beginning of 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.
This word is used by all number prefixes.
ciforth guarantees that PP points directly after a number parsed,
such that for double numbers @samp{PP@ DPL @ - 1-} gives
the number of decimals.


@noindent
See also: @samp{NUMBER}
 @samp{?BLANK}
 @samp{Prefix_7}
 


        


@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 a don't care value and a false flag.

        


@node DPL, ECL, DIGIT, FORMATTING
@subsection DPL
@pindex DPL
@findex DPL

@noindent
Name: @code{DPL}

@noindent
Stackeffect: ---- addr

@noindent
Attributes: FIG,U

@noindent
Description:
A user variable containing the address of the decimal point on
double integer or floating point input, or a @dfn{nil pointer}.


@noindent
See also: @samp{<#}
 @samp{FLD}
 @samp{HLD}
 


        


@node ECL, FLD, DPL, FORMATTING
@subsection ECL
@pindex ECL
@findex ECL

@noindent
Name: @code{ECL}

@noindent
Stackeffect: ---- addr

@noindent
Attributes: 

@noindent
Description:
A user variable containing the address of the exponential sign
in a floating point input, or a @dfn{nil pointer}.


@noindent
See also: @samp{DPL}
 
        


@node FLD, HLD, ECL, 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

@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}
 @samp{HOLD}
 



        


@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 (aliased as)
single character denotation
words, marked as @code{PREFIX}
@findex PREFIX
 @code{IMMEDIATE}
@findex IMMEDIATE
.
Therefore it decrements the parse pointer to include this first
character.
Starting with this character, it converts characters from the current input source
into a number, and compiles or executes this number, depending on @code{STATE}
@findex STATE
.
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.
Any comma's in the number are ignored, to help in structuring large numbers.
Traditionally comma's also signified double precision numbers.
Revectoring @code{NUMBER}
@findex NUMBER
 affects all applicable number prefixes.
In this way floating point numbers can be accomodated.



@noindent
See also: @samp{BASE}
 @samp{(NUMBER)}
 

        




@node INITIALISATIONS, INPUT,FORMATTING, Glossary
@section INITIALISATIONS
     
    The wordset @samp{INITIALISATIONS} contains words to initialise,
reinitialise or configure Forth.
    

    

@menu


* +ORIGIN  ::
* ABORT  ::
* COLD  ::
* OK  ::
* OPTIONS  ::
* QUIT  ::
* WARM  ::
* _INIT  ::
@end menu
@node +ORIGIN, ABORT, INITIALISATIONS, INITIALISATIONS
@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 during startup.
Given a @dfn{user variable}
@cindex user variable
 the phrase @samp{>DFA @ +ORIGIN} finds the address
where its initial value is stored.
One can access
or modify those boot-up parameters, prior to saving a customised
image in behalf of turnkey programs.
This will affect the initialisation by @code{COLD}
@findex COLD
.

In this forth switching of the user area in behalf of multi-tasking
is accomplished
automatically when the return stack is switched. 



@noindent
See also: @samp{USER}
 
        


@node ABORT, COLD, +ORIGIN, INITIALISATIONS
@subsection ABORT
@pindex ABORT
@findex ABORT

@noindent
Name: @code{ABORT}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG

@noindent
Description:
Restart the interpreter. In addition and before the actions of
@code{QUIT}
@findex QUIT
, clear also the data stack and
reset the exception mechanism.
This word 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}
 @samp{_INIT}
 

        


@node COLD, OK, ABORT, INITIALISATIONS
@subsection COLD
@pindex COLD
@findex COLD

@noindent
Name: @code{COLD}

@noindent
No stackeffect

@noindent
Attributes: FIG

@noindent
Description:
When called for the first time it
initialises all user variables to their boot up values values,
i.a. the stacks and the @dfn{dictionary pointer} .
Initialise the system as per @code{_INIT}
@findex _INIT
.
Handle command line options, if any, as per @code{OPTIONS}
@findex OPTIONS
.
Show signon message and restart via @code{ABORT}
@findex ABORT
 .
May be called from the terminal to restart, while keeping all definitions.
But it is better to say @code{BYE}
@findex BYE
 to Forth and start again.



@noindent
See also: @samp{WARM}
 @samp{_INIT}
 @samp{OPTIONS}
 


        


@node OK, OPTIONS, COLD, INITIALISATIONS
@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
.
It can be revectored to show debugging info or give a prompt.


@noindent
See also: @samp{QUIT}
 @samp{COLD}
 

        


@node OPTIONS, QUIT, OK, INITIALISATIONS
@subsection OPTIONS
@pindex OPTIONS
@findex OPTIONS

@noindent
Name: @code{OPTIONS}

@noindent
Stackeffect: ft --- f2

@noindent
Attributes: CI

@noindent
Description:
Handle command line option.
If an option is given at startup, execute the screen corresponding
to the option letter and return a false flag into @samp{f2},
otherwise leave a true flag.
This is used to suppress the signon message if there is an option.
An option screen can always decide to execute
@code{.SIGNON}
@findex .SIGNON
. By redefining @code{OPTIONS}
@findex OPTIONS
 as
@samp{DROP 0}, the handling of options during cold boot is
suppressed, useful for turnkey applications.  

@noindent
See also: @samp{COLD}
 
        


@node QUIT, WARM, OPTIONS, INITIALISATIONS
@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, _INIT, QUIT, INITIALISATIONS
@subsection WARM
@pindex WARM
@findex WARM

@noindent
Name: @code{WARM}

@noindent
No stackeffect

@noindent
Attributes: FIG

@noindent
Description:
Perform a so called "warm" start.
Reinitialise the system as per @code{INIT}
@findex INIT
.
Show the signon message and restart via @code{ABORT}
@findex ABORT
 .


@noindent
See also: @samp{ABORT}
 
        


@node _INIT, , WARM, INITIALISATIONS
@subsection _INIT
@pindex _INIT
@findex _INIT

@noindent
Name: @code{_INIT}

@noindent
No stackeffect

@noindent
Attributes: FIG

@noindent
Description:
Initialise or reinitialise the system.
Reset the data stack, the search order, the number base and the
exception mechanism.
Initialise the block mechanism.
Any blocks that have not yet been
written back to mass storage are discarded.
Now open the file that contains the blocks, in read-only mode.
After @code{_INIT}
@findex _INIT
 we have the following situation.
The search order contains the @code{FORTH}
@findex FORTH
 words,
plus @code{ONLY}
@findex ONLY
 with i.a. number handling.
Definitions are added to the @code{FORTH}
@findex FORTH
 @dfn{namespace}
@cindex namespace
.
The number base is decimal.   


@noindent
See also: @samp{WARM}
 @samp{COLD}
 @samp{FORTH}
 @samp{BLOCK-INIT}
 @samp{BASE}
 @samp{S0}
 





        




@node INPUT, JUGGLING,INITIALISATIONS, 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
* ACCEPT  ::
* KEY?  ::
* KEY  ::
* PP  ::
* RUBOUT  ::
* TIB  ::
* (>IN)  :paren_iso_in
* REFILL-TIB  ::
* REMAINDER  ::
* SET-TERM  ::
* TERMIO  ::
@end menu
@node paren_accept, ACCEPT, 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
 
This input remains valid until the next time that the console
buffer is refilled.
With TIBSIZE characters the terminal input buffer overflows,
with unpredictable results.


@noindent
See also: @samp{KEY}
 @samp{KEY?}
 @samp{ACCEPT}
 @samp{PP@@@@}
 @samp{REFILL-TIB}
 




        


@node ACCEPT, KEY?, paren_accept, 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 @samp{addr} .
The transfer takes place when a @kbd{RET} is received,
and excess characters after @samp{count} are ignored.
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.
The number of characters not
including the @kbd{RET} is returned into @samp{n}.


@noindent
See also: @samp{(ACCEPT)}
 @samp{KEY}
 @samp{KEY?}
 


        


@node KEY?, KEY, ACCEPT, INPUT
@subsection KEY?
@pindex KEY?
@findex KEY?

@noindent
Name: @code{KEY?}

@noindent
Stackeffect: --- ff

@noindent
Attributes: ISO

@noindent
Description:
Return into @samp{ff} 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, PP, KEY?, INPUT
@subsection KEY
@pindex KEY
@findex KEY

@noindent
Name: @code{KEY}

@noindent
Stackeffect: --- c

@noindent
Attributes: ISO,FIG

@noindent
Description:
Leave the ASCII value of the next terminal key struck.

@noindent
See also: @samp{ACCEPT}
 @samp{KEY?}
 

        


@node PP, RUBOUT, KEY, INPUT
@subsection PP
@pindex PP
@findex PP

@noindent
Name: @code{PP}

@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{PP}
@findex PP
 .
This is different from how ISO @code{>IN}
@findex >IN
 works,
in the sense that zeroing it
doesn't reset the parse pointer to the start of the current line.


@noindent
See also: @samp{(>IN)}
 @samp{WORD}
 @samp{NAME}
 @samp{NUMBER}
 @samp{PARSE}
 @samp{PP@@@@}
 





        


@node RUBOUT, TIB, PP, 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.
Traditionally, this was used for file i/o too, but not so in
ciforth.


@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:
This is a user variable that is foreseen for code that fakes
the behaviour of @code{>IN}
@findex >IN
 in ciforth.
This could be part of the code loaded by @samp{"-legacy-" WANTED } .
(The word @code{>IN}
@findex >IN
 is intended to be used in the context that the source is
interpreted line by line.)
In ciforth the parse pointer @code{PP}
@findex PP
 is used by the system instead of
 @code{>IN}
@findex >IN
 .


@noindent
See also: @samp{>IN}
 @samp{PP}
 

        


@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{NAME}
@findex NAME
 .
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
after a @kbd{RET} more characters are available)
@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 errors from Linux result in an exception.
The end of normal or redirected I/O results in an an end-of-pipe exception
in this word, which terminates ci86.lina64.html and is not considered an error condition.


@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 from the the input stream,
but not yet part of the input buffer.
Unless there is redirection from a file,
this contains an empty string.
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 termios 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{TERMIO}
 @samp{KEY}
 

        


@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{termios} .


@noindent
See also: @samp{SET-TERM}
 
        




@node JUGGLING, LIBRARY,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.
Design your word such that you need them as little as possible,
because they are confusing.
    

    

@menu


* 2DROP  ::
* 2DUP  ::
* 2OVER  ::
* 2SWAP  ::
* ?DUP  ::
* DROP  ::
* DUP  ::
* NIP  ::
* 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{OVER}
 
        


@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{SWAP}
 
        


@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

@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

@noindent
Description:
Drop the number from the stack.

@noindent
See also: @samp{DUP}
 @samp{SWAP}
 @samp{OVER}
 


        


@node DUP, NIP, DROP, JUGGLING
@subsection DUP
@pindex DUP
@findex DUP

@noindent
Name: @code{DUP}

@noindent
Stackeffect: n --- n n

@noindent
Attributes: ISO,FIG

@noindent
Description:
Duplicate the value on the stack.

@noindent
See also: @samp{OVER}
 @samp{SWAP}
 @samp{DROP}
 


        


@node NIP, OVER, DUP, JUGGLING
@subsection NIP
@pindex NIP
@findex NIP

@noindent
Name: @code{NIP}

@noindent
Stackeffect: n1 n2---n2

@noindent
Attributes: ISO

@noindent
Description:
Drop the second number from the stack.

@noindent
See also: @samp{DUP}
 @samp{DROP}
 @samp{SWAP}
 @samp{OVER}
 



        


@node OVER, ROT, NIP, JUGGLING
@subsection OVER
@pindex OVER
@findex OVER

@noindent
Name: @code{OVER}

@noindent
Stackeffect: nl n2 --- nl n2 n1

@noindent
Attributes: ISO,FIG

@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

@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

@noindent
Description:
Exchange the top two values on the stack.

@noindent
See also: @samp{ROT}
 
        




@node LIBRARY, LOGIC,JUGGLING, Glossary
@section LIBRARY
     
    The words of the library have nothing particular in common,
except that they are available in the Library Accessable by Block @dfn{LAB}
@cindex LAB
 and not the
ciforth kernel.

All of them can be loaded from the library by @samp{WANT}
@samp{SOME_WORD}.
Most common ISO words are available.
The assembler is loaded by @samp{WANT ASSEMBLERi86} .
Floating point is loaded by @samp{WANT -fp-} .
Interactive controle structures are loaded by @samp{WANT -scripting-} .
Multi-tasking is loaded by @samp{WANT THREAD-PET} .
The memory wordset is loaded by @samp{WANT ALLOCATE} .

Useful application words in the @dfn{LAB}
@cindex LAB
 are i.a. : @code{ALIAS}
@findex ALIAS
 @code{QSORT}
@findex QSORT
 @code{MERGE-SORT}
@findex MERGE-SORT
 .
Useful debugging words in the @dfn{LAB}
@cindex LAB
 are i.a. : @code{DO-DEBUG}
@findex DO-DEBUG
 @code{LOCATE}
@findex LOCATE
 @code{SEE}
@findex SEE
 @code{REGRESS}
@findex REGRESS
 .
Non-iso words are supposedly usable from the description that goes with the code.


    

    

@menu

@end menu



@node LOGIC, MEMORY,LIBRARY, 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 64 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

@noindent
Description:
Leave a true flag if the number is less than zero (negative),
otherwise leave a false flag.

@noindent
See also: @samp{<}
 @samp{0=}
 

        


@node 0=, <>, 0<, LOGIC
@subsection 0=
@pindex 0=
@findex 0=

@noindent
Name: @code{0=}

@noindent
Stackeffect: n --- ff

@noindent
Attributes: ISO,FIG

@noindent
Description:
Leave a true flag @samp{ff} is the number @samp{n}
is equal to zero, otherwise leave a false flag.
It may be aliased to @code{NOT}
@findex NOT
 , which inverts a flag.


@noindent
See also: @samp{=}
 @samp{0<}
 

        


@node <>, <, 0=, LOGIC
@subsection <>
@pindex <>
@findex <>

@noindent
Name: @code{<>}

@noindent
Stackeffect: n1 n2 --- ff

@noindent
Attributes: ISO

@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: 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

@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

@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

@noindent
Description:
Leave the bitwise logical and of @samp{n1} and
@samp{n2} as @samp{n3} .
For Forth flags (0 or -1) this is the @dfn{logical and}
@cindex logical and
 operator.


@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

@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

@noindent
Description:
Leave the bit-wise logical or of two 64-bit
values.
For Forth flags (0 or -1) this is the @dfn{logical or}
@cindex logical or
 operator.


@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

@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: ISO,FIG

@noindent
Description:
Leave the bitwise logical exclusive or of two
 64-bit values.
For Forth flags (0 or -1) this is the @dfn{logical xor}
@cindex logical xor
 operator.


@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  ::
* FILL  ::
* L!  :long_store
* L@@  :long_fetch
* MOVE  ::
* PC!  ::
* PC@@  :port_char_fetch
* PW!  ::
* PW@@  :port_fetch
* TASK-SIZE  ::
* TOGGLE  ::
* WITHIN  ::
@end menu
@node !, +!, MEMORY, MEMORY
@subsection !
@pindex !
@findex !

@noindent
Name: @code{!}

@noindent
Stackeffect: n addr ---

@noindent
Attributes: ISO,FIG

@noindent
Description:
Store all 64 bits of n at @samp{addr} .

@noindent
See also: @samp{@@}
 @samp{C!}
 @samp{2!}
 @samp{FAR!}
 @samp{PW!}
 @samp{PC!}
 





        


@node +!, 2!, !, MEMORY
@subsection +!
@pindex +!
@findex +!

@noindent
Name: @code{+!}

@noindent
Stackeffect: n addr ---

@noindent
Attributes: ISO,FIG

@noindent
Description:
 Add @samp{n} to the value at @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: x1 x2 addr --- 

@noindent
Attributes: ISO

@noindent
Description:
Store a pair of 64 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 64 bits values @samp{x1} @samp{x2} from
consecutive 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

@noindent
Description:
Leave the 64 bit contents @samp{n}
of @samp{addr} .

@noindent
See also: @samp{!}
 @samp{C@@}
 @samp{2@@}
 @samp{PW@@}
 @samp{PC@@}
 @samp{FAR@@}
 





        


@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  64 bits) cell to
@samp{n2}. This is invaluable for writing portable
code.
Much of the library code of ciforth runs on 64, 32 and 16 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 64, 32 and 16 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 @samp{count} 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. 

@noindent
See also: @samp{MOVE}
 @samp{CHARS}
 

        


@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
. 


        


@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, FILL, 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 FILL, long_store, ERASE, MEMORY
@subsection FILL
@pindex FILL
@findex FILL

@noindent
Name: @code{FILL}

@noindent
Stackeffect: addr u b ---

@noindent
Attributes: ISO,FIG

@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 long_store, long_fetch, FILL, MEMORY
@subsection L!
@pindex L!
@findex L!

@noindent
Name: @code{L!}

@noindent
Stackeffect: u addr --- 

@noindent
Attributes: 

@noindent
Description:
Store the 32-bit contents of @samp{u} at @samp{addr} .

@noindent
See also: @samp{L@@}
 @samp{!}
 @samp{C!}
 @samp{2!}
 @samp{PW!}
 @samp{PC!}
 @samp{FAR!}
 






        


@node long_fetch, MOVE, long_store, MEMORY
@subsection L@@
@pindex L@@
@findex L@@

@noindent
Name: @code{L@@}

@noindent
Stackeffect: addr --- u

@noindent
Attributes: ISO,FIG

@noindent
Description:
Leave the 32 bit contents @samp{u}
of @samp{addr} .

@noindent
See also: @samp{!}
 @samp{C@@}
 @samp{2@@}
 @samp{PW@@}
 @samp{PC@@}
 @samp{FAR@@}
 





        


@node MOVE, PC!, long_fetch, MEMORY
@subsection MOVE
@pindex MOVE
@findex MOVE

@noindent
Name: @code{MOVE}

@noindent
Stackeffect: from to count ---

@noindent
Attributes: ISO

@noindent
Description:
Move @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.
Because in ciforth bytes (address units) and characters are the same
the difference with @code{CMOVE}
@findex CMOVE
 amounts to @code{MOVE}
@findex MOVE

being an intelligent move.


        


@node PC!, port_char_fetch, MOVE, 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}.
You can use ports only after asking permission
(using e.g. @samp{ioperm} ) and being super user.


@noindent
See also: @samp{PC@@}
 @samp{PW!}
 @samp{P@@}
 @samp{!}
 



        


@node port_char_fetch, PW!, 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
You can use ports only after asking permission
(using e.g. @samp{ioperm} ) and being super user.


@noindent
See also: @samp{PC!}
 @samp{PW@@}
 @samp{PW!}
 @samp{@@}
 



        


@node PW!, port_fetch, port_char_fetch, MEMORY
@subsection PW!
@pindex PW!
@findex PW!

@noindent
Name: @code{PW!}

@noindent
Stackeffect: n port ---

@noindent
Attributes: 

@noindent
Description:
Store the 16-bit data @samp{n} to the 16-bits port address
@samp{port}.
You can use ports only after asking permission
(using e.g. @samp{ioperm} ) and being super user.


@noindent
See also: @samp{PW@@}
 @samp{PC!}
 @samp{PC@@}
 @samp{!}
 



        


@node port_fetch, TASK-SIZE, PW!, MEMORY
@subsection PW@@
@pindex PW@@
@findex PW@@

@noindent
Name: @code{PW@@}

@noindent
Stackeffect: port --- n

@noindent
Attributes: 

@noindent
Description:
Fetch the 16-bit contents @samp{n} from the port address
@samp{port}.
You can use ports only after asking permission
(using e.g. @samp{ioperm} ) and being super user.


@noindent
See also: @samp{PW!}
 @samp{PC@@}
 @samp{PC!}
 @samp{@@}
 



        


@node TASK-SIZE, TOGGLE, port_fetch, MEMORY
@subsection TASK-SIZE
@pindex TASK-SIZE
@findex TASK-SIZE

@noindent
Name: @code{TASK-SIZE}

@noindent
Stackeffect: ---- n

@noindent
Attributes: 

@noindent
Description:
A constant leaving the total size of the per task areas:
data stack, return stack, terminal input buffer plus
user area.
The data stack of the main task runs down to @code{HERE}
@findex HERE
 .


@noindent
See also: @samp{DSP@@}
 @samp{RSP@@}
 @samp{TIB}
 


        


@node TOGGLE, WITHIN, TASK-SIZE, 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

@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.
After initialisation user variables derive their start address
from the return stack pointer. 
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 @xref{MULTIPLYING}, wordset. In this 64 bit Forth
you will have less need.
When you divide a 2.n digit number by an n digit number you get an n-digit
quotient and an n-digit remainder. So naturally many operators in this set
have a mix of double and single numbers in their
stack diagram: they are @dfn{mixed magnitude}
@cindex mixed magnitude
.
All those have @code{M}
@findex M
 in the name.
Furthermore all operations are signed,
with the exception of the ones starting with @code{U}
@findex U
 .
Those have unsigned operands exclusively.
The irregularly named word @dfn{M/MOD}
@cindex M/MOD
 is a relic from the
fig-forth era;
preferably its alias @dfn{UDM/MOD}
@cindex UDM/MOD
 is to be used.
Output formatting is done with @dfn{double}
@cindex double
's exclusively, and relies
on this wordset and the @samp{DOUBLE} wordset. Operators with mixed magnitude 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  ::
* UDM/MOD  ::
* 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

@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} overflows. Then ciforth will give a floating point exception.


@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

@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. Then ciforth will give a floating point exception.


@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{UDM/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

@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{UDM/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:
This is an irregarly named alias of  @dfn{UDM/MOD}
@cindex UDM/MOD
 .


@noindent
See also: @samp{UDM/MOD}
 
        


@node SM/REM, UDM/MOD, 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{UDM/MOD}
 @samp{FM/MOD}
 @samp{/}
 @samp{M*}
 



        


@node UDM/MOD, UM*, SM/REM, MULTIPLYING
@subsection UDM/MOD
@pindex UDM/MOD
@findex UDM/MOD

@noindent
Name: @code{UDM/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}.
Unlike with @dfn{UM/MOD}
@cindex UM/MOD
 the quotient can not overflow.
The traditional alias forthcdefi(M/MOD) dates from the fig-forth era.


@noindent
See also: @samp{UM/MOD}
 @samp{SM/REM}
 @samp{M*}
 


        


@node UM*, UM/MOD, UDM/MOD, 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  ::
* MS  ::
* SHELL  ::
* SYSTEM  ::
* XOS5  ::
* XOS  ::
* 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 null ended array of arguments c-strings,
then by a null ended array of environment c-strings.
C-string are chars followed by a zero byte and no preceeding count.





@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, MS, 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 MS, SHELL, EXIT-CODE, 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 string variable,
the name of a file that contains the command interpreter,
or shell.
This name may be changed and 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 @b{/bin/sh} .



@noindent
See also: @samp{SYSTEM}
 @samp{$@@}
 

        


@node SYSTEM, XOS5, 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{?ERRUR}
 @samp{SHELL}
 

        


@node XOS5, XOS, SYSTEM, OPERATINGSYSTEM
@subsection XOS5
@pindex XOS5
@findex XOS5

@noindent
Name: @code{XOS5}

@noindent
Stackeffect: n1 n2 n3 n4 n5 n---ret

@noindent
Attributes: 

@noindent
Description:
 Do a traditional Unix type 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 @b{errno} . This makes available
@b{all} facilities present in Linux.


@noindent
See also: @samp{?ERRUR}
 
        


@node XOS, ZEN, XOS5, OPERATINGSYSTEM
@subsection XOS
@pindex XOS
@findex XOS

@noindent
Name: @code{XOS}

@noindent
Stackeffect: n1 n2 n3 n---ret

@noindent
Attributes: 

@noindent
Description:
 Do a traditional Unix type
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.
Note
This makes
available all facilities present in Linux, except those with 4 or 5 parameters
that are handled by @code{XOS5}
@findex XOS5
 .


@noindent
See also: @samp{?ERRUR}
 
        


@node ZEN, , XOS, 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 (in fact @code{RW-BUFFER}
@findex RW-BUFFER
) is reused,
such that this word is not reentrant.
The size available is SIZE_RWBUF minus one for the zero character.
Use the word immediately, its intended used is
passing parameters to the operating system. 



@noindent
See also: @samp{OPEN-FILE}
 @samp{XOS}
 @samp{XOS5}
 


        




@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 worrisome 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

@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

@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

@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

@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

@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

@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 @b{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

@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

@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

@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

@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 @b{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

@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

@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

@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

@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

@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

@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

@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

@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

@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

@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{PP}
@findex PP
 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


* ?BLANK  ::
* CHAR  ::
* EVALUATE  ::
* INTERPRET  ::
* NAME  :name
* PARSE  :parse
* PP@@@@  :parse_pointer_fetch_fetch
* RESTORE-INPUT  ::
* RESTORE  ::
* SAVE-INPUT  ::
* SAVE  ::
* SET-SRC  :set_source
* SOURCE  ::
* SRC  ::
* STATE  ::
* WORD  ::
* [CHAR]  :bracket_char_bracket
* [  :left_bracket
* \  :backslash
* ]  :righ_bracket
* (  :paren
@end menu
@node ?BLANK, CHAR, PARSING, 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.
In ciforth all control characters are considered 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, name, 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
@dfn{current input source}
@cindex current input source
 and
execute it (@code{STATE}
@findex STATE
 is 0) 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
.
It can be either matched exactly, or it can match a prefix.
If it is matched regularly the parse pointer remains after the
blank delimiter as required by ISO.
If a word matches a prefix, @code{INTERPRET}
@findex INTERPRET
 sets back the
parse pointer to immediately after the prefix,
A word that matches a prefix is called a @dfn{denotation}
@cindex denotation
;
mostly this is a number.
If it is not found at all, it is an @code{ERROR}
@findex ERROR
.
Prefixes are present in the @dfn{namespace}
@cindex namespace
 @code{ONLY}
@findex ONLY
 which
comprises the minimum search order and is always present as
the last wordlist in the search order.
An application can add prefixes in whatever namespace is suitable.
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 characters.
The denotation parsing is extendable, e.g. after loading a floating
point package floating point numbers are recognized.
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 in numbers are ignored by ciforth.


@noindent
See also: @samp{NAME}
 @samp{(NUMBER)}
 @samp{NUMBER}
 @samp{BLK}
 @samp{DPL}
 




        


@node name, parse, INTERPRET, PARSING
@subsection NAME
@pindex NAME
@findex NAME

@noindent
Name: @code{NAME}

@noindent
Stackeffect: --- sc

@noindent
Attributes: CI

@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. 
Contrast this to a @code{PREFIX}
@findex PREFIX
 word that leaves the input pointer
past itself.


@noindent
See also: @samp{BLK}
 @samp{WORD}
 @samp{PP}
 


        


@node parse, parse_pointer_fetch_fetch, name, 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.

@noindent
See also: @samp{WORD}
 @samp{NAME}
 

        


@node parse_pointer_fetch_fetch, RESTORE-INPUT, parse, PARSING
@subsection PP@@@@
@pindex PP@@@@
@findex PP@@@@

@noindent
Name: @code{PP@@@@}

@noindent
Stackeffect:  ---addr c

@noindent
Attributes: CI

@noindent
Description:
Parse the @dfn{current input source}
@cindex current input source
 leaving the address @samp{addr}
of the next character @samp{c} . 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{PP}
 


        


@node RESTORE-INPUT, RESTORE, parse_pointer_fetch_fetch, PARSING
@subsection RESTORE-INPUT
@pindex RESTORE-INPUT
@findex RESTORE-INPUT

@noindent
Name: @code{RESTORE-INPUT}

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

@noindent
Attributes: ISO,WANT

@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{SAVE}
 @samp{SAVE-INPUT}
 

        


@node RESTORE, SAVE-INPUT, RESTORE-INPUT, PARSING
@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{SET-SRC}
 @samp{RESTORE-INPUT}
 

        


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

@noindent
Name: @code{SAVE-INPUT}

@noindent
Stackeffect:  --- n1 n2 n3 3

@noindent
Attributes: ISO,WANT

@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{SAVE}
 @samp{RESTORE-INPUT}
 

        


@node SAVE, set_source, SAVE-INPUT, PARSING
@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
to prepare for changing the @dfn{current input source}
@cindex current input source
.
This must be balanced by a @code{RESTORE}
@findex RESTORE
 in the same
definition.
@code{CO}
@findex CO
 can be used between the two.


@noindent
See also: @samp{SET-SRC}
 @samp{SAVE-INPUT}
 

        


@node set_source, SOURCE, SAVE, 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 surrounded by call's to @code{SAVE}
@findex SAVE
 and
@code{RESTORE}
@findex RESTORE
 and then
followed by a call to @code{INTERPRET}
@findex INTERPRET
or some such.

@noindent
See also: @samp{SRC}
 @samp{SAVE}
 @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}
 
        


@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 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 changing only the third cell or
by e.g. using @code{SET-SRC}
@findex SET-SRC
.
The third cell has the alias @samp{PP} .
Words like @samp{>IN BLK SOURCE} are secondary,
and return their output by ``second-guessing'' @samp{SRC} .

@noindent
See also: @samp{SAVE}
 @samp{RESTORE}
 @samp{PP}
 @samp{BLK}
 



        


@node STATE, WORD, SRC, PARSING
@subsection STATE
@pindex STATE
@findex STATE

@noindent
Name: @code{STATE}

@noindent
Stackeffect: --- addr

@noindent
Attributes: ISO,U

@noindent
Description:
A user variable containing the compilation state. A non-zero value
indicates compilation.
In ciforth it then contains 1.

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

        


@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,WANT

@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{NAME}
 @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,

@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

@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, paren, backslash, PARSING
@subsection ]
@pindex ]
@findex ]

@noindent
Name: @code{]}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG

@noindent
Description:
Resume compilation, to the completion of a colon-definition.

@noindent
See also: @samp{[}
 
        


@node paren, , righ_bracket, PARSING
@subsection (
@pindex (
@findex (

@noindent
Name: @code{(}

@noindent
No stackeffect

@noindent
Attributes: ISO,FIG,I

@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 @samp{(} is required.

@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
* C/L  ::
* INDEX  ::
* LIST  ::
* LOAD  ::
* LOCK  ::
* R#  ::
* SCR  ::
* THRU  ::
* TRIAD  ::
* UNLOCK  ::
* (BLK)  :paren_blk
* BLK  ::
@end menu
@node paren_line, C/L, 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 C/L, INDEX, paren_line, 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

@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

@noindent
Description:
Interrupt the @dfn{current input source}
@cindex current input source
 in order to
interpret screen @samp{n} .
While the screen is interpreted, it is locked, meaning that it
cannot be associated with a different screen nr than @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{LOCK}
 @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 buffer with identification @samp{n},
mostly a block number.
Multiple locks are possible, and require multiple unlocks.
Probably, 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{(BUFFER}
 

,UNLOCK,#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

@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: FIG,WANT

@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 buffer with identification @samp{n},
mostly a block number.
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{(BUFFER)}
 @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 @dfn{current input source}
@cindex 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 @samp{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, which may not be ISO compliant.
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: FIG,WANT

@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: FIG,WANT

@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  ::
* CLS  ::
* 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.
For stack underflow print nothing.


@noindent
See also: @samp{LIST}
 
        


@node >R, CLS, dot_s, STACKS
@subsection >R
@pindex >R
@findex >R

@noindent
Name: @code{>R}

@noindent
Stackeffect: n ---

@noindent
Attributes: ISO,FIG,C

@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 CLS, DEPTH, >R, STACKS
@subsection CLS
@pindex CLS
@findex CLS

@noindent
Name: @code{CLS}

@noindent
Stackeffect:  i*x -- 

@noindent
Attributes: 

@noindent
Description:
Clear the data stack

@noindent
See also: @samp{DSP!}
 
        


@node DEPTH, DSP!, CLS, 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@@}
 @samp{S0}
 

        


@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

@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@@}
 @samp{R0}
 

        


@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+  ::
* $\  ::
* $^  ::
* -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: WANT

@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
@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, string_comma, STRING
@subsection $/
@pindex $/
@findex $/

@noindent
Name: @code{$/}

@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{$^}
 @samp{CORA}
 @samp{$@@}
 


        


@node string_fetch, $C+, $/, 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} .
This is similar to @code{COUNT}
@findex COUNT
 with a cell-length instead of a char-length.


@noindent
See also: @samp{$!}
 @samp{$+!}
 @samp{$C+}
 


        


@node $C+, $\, 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{&}
 @samp{^}
 @samp{CHAR}
 




        


@node $\, $^, $C+, STRING
@subsection $\
@pindex $\
@findex $\

@noindent
Name: @code{$\}

@noindent
Stackeffect: sc c --- sc1 sc2

@noindent
Attributes: 

@noindent
Description:
Find the first @samp{c} in the @dfn{string constant}
@samp{sc} from the back and split it at that address.
Return the strings before and after @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{$^}
 @samp{CORA}
 @samp{$@@}
 


        


@node $^, -TRAILING, $\, STRING
@subsection $^
@pindex $^
@findex $^

@noindent
Name: @code{$^}

@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{$/}
 @samp{CORA}
 @samp{$@@}
 


        


@node -TRAILING, BL, $^, 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

@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{addr2 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

@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: ISO,FIG

@noindent
Description:
This is shorthand for ``@samp{1 +}''.

@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 shift left.
The bit pattern of @samp{n1} is shifted to the left,
with a result identical to @samp{1 LSHIFT}.

@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 shift right.
The bit pattern of @samp{n1} is shifted to the right, except that
the left most bit (``sign bit'') remains the same, called "arithmetic shift".
 On this 2-complement machine this is the same as
@samp{2 /} .

@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{NAMESPACE}
@findex NAMESPACE
 and filled by defining words while that
@dfn{namespace}
@cindex namespace
 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 a
@dfn{word list identifier}
@cindex word list identifier
 or @dfn{WID}
@cindex WID
,
but no name which is inconvenient.
We use namespace words created by the defining
word @code{NAMESPACE}
@findex NAMESPACE
 . They are used to manipulate the
word list's that are associated with them. So
namespaces are nearly the wordlist 's of the ISO standard,
the primary difference is that they have a name.
In most Forth literature namespaces are referred to as vocabularies,
and a word @code{VOCABULARY}
@findex VOCABULARY
 is used to create them.
 
    

    

@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, i.e. the first added to the search
order probably @code{FORTH}
@findex FORTH
. This is probably fatal.
@code{ONLY}
@findex ONLY
 remains in the search order and
@samp{ONLY FORTH} can be used to recover.
Using namespaces you will not need to use this word,
because in ciforth by executing a namespace you add it to the order.
This is different than the words defined by the customary
@code{VOCABULARY}
@findex VOCABULARY
 that replaces the topmost wordlist.


@noindent
See also: @samp{CONTEXT}
 @samp{NAMESPACE}
 

        


@node ASSEMBLER, CONTEXT, ALSO, WORDLISTS
@subsection ASSEMBLER
@pindex ASSEMBLER
@findex ASSEMBLER

@noindent
Name: @code{ASSEMBLER}

@noindent
No stackeffect

@noindent
Attributes: WANT,NISO,FIG

@noindent
Description:
The name of the namespace that contains machine code definitions.
In ciforth execution it pushes the associated word list to the
top of the @code{CONTEXT}
@findex CONTEXT
 stack. (A traditional @code{VOCABULARY}
@findex VOCABULARY

would replace the top.)
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{NAMESPACE}
 @samp{LOAD}
 

        


@node CONTEXT, CURRENT, ASSEMBLER, WORDLISTS
@subsection CONTEXT
@pindex CONTEXT
@findex CONTEXT

@noindent
Name: @code{CONTEXT}

@noindent
Stackeffect: --- addr

@noindent
Attributes: FIG,U

@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.


@noindent
See also: @samp{PRESENT}
 @samp{NAMESPACE}
 @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

@noindent
Description:
A user variable containing the WID of a namespace 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{NAMESPACE}
 @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
namespace 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{NAMESPACE}
 

        


@node ENVIRONMENT, FORTH, DEFINITIONS, WORDLISTS
@subsection ENVIRONMENT
@pindex ENVIRONMENT
@findex ENVIRONMENT

@noindent
Name: @code{ENVIRONMENT}

@noindent
No stackeffect

@noindent
Attributes: 

@noindent
Description:
The name of the @code{ENVIRONMENT}
@findex ENVIRONMENT
 namespace. 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{NAMESPACE}
 
        


@node FORTH, LATEST, ENVIRONMENT, WORDLISTS
@subsection FORTH
@pindex FORTH
@findex FORTH

@noindent
Name: @code{FORTH}

@noindent
No stackeffect

@noindent
Attributes: NISO,FIG

@noindent
Description:
The name of the primary namespace.
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, however the phrase
@samp{ONLY FORTH} has the effect required by ISO.)
Until additional user @dfn{word list}
@cindex word list
 's are created, new user definitions
become a part of @code{FORTH}
@findex FORTH
 .


@noindent
See also: @samp{CONTEXT}
 @samp{NAMESPACE}
 

        


@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{NAMESPACE}
 
        


@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{NAMESPACE}
@findex NAMESPACE
.
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 you want to add a denotation,
add it to the @code{ONLY}
@findex ONLY
 wordlist preferably.
This prevents masking regular words that start with the prefix.


@noindent
See also: @samp{PREFIX}
 @samp{PP}
 @samp{>WID}
 


        


@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{NAMESPACE}
 

        


@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{NAMESPACE}
@findex NAMESPACE
 . All namespace names are
linked by these fields to allow @code{FORGET}
@findex FORGET
 to find all
vocabularies.

@noindent
See also: @samp{NAMESPACE}
 
        






@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
