This file documents Gforth 0.5.0

   Copyright (C) 1995-2000 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
 are preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this      manual under the conditions for verbatim copying, provided
also that the      sections entitled "Distribution" and "General Public
License" are      included exactly as in the original, and provided
that the entire      resulting derived work is distributed under the
terms of a permission      notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual      into another language, under the above conditions for
modified versions,      except that the sections entitled
"Distribution" and "General Public      License" may be included in a
translation approved by the author instead      of in the original
English.

   Gforth is a free implementation of ANS Forth available on many
personal machines. This manual corresponds to version 0.5.0.

GNU GENERAL PUBLIC LICENSE
**************************

                         Version 2, June 1991

     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     59 Temple Place, Suite 330, Boston, MA 02111, USA
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
========

   The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.

   To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

   We protect your rights with two steps: (1) copyright the software,
and (2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

   Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

   Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

   The precise terms and conditions for copying, distribution and
modification follow.

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License applies to any program or other work which contains a
     notice placed by the copyright holder saying it may be distributed
     under the terms of this General Public License.  The "Program",
     below, refers to any such program or work, and a "work based on
     the Program" means either the Program or any derivative work under
     copyright law: that is to say, a work containing the Program or a
     portion of it, either verbatim or with modifications and/or
     translated into another language.  (Hereinafter, translation is
     included without limitation in the term "modification".)  Each
     licensee is addressed as "you".

     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running the Program is not restricted, and the output from the
     Program is covered only if its contents constitute a work based on
     the Program (independent of having been made by running the
     Program).  Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
     source code as you receive it, in any medium, provided that you
     conspicuously and appropriately publish on each copy an appropriate
     copyright notice and disclaimer of warranty; keep intact all the
     notices that refer to this License and to the absence of any
     warranty; and give any other recipients of the Program a copy of
     this License along with the Program.

     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.

  2. You may modify your copy or copies of the Program or any portion
     of it, thus forming a work based on the Program, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:

       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.

       b. You must cause any work that you distribute or publish, that
          in whole or in part contains or is derived from the Program
          or any part thereof, to be licensed as a whole at no charge
          to all third parties under the terms of this License.

       c. If the modified program normally reads commands interactively
          when run, you must cause it, when started running for such
          interactive use in the most ordinary way, to print or display
          an announcement including an appropriate copyright notice and
          a notice that there is no warranty (or else, saying that you
          provide a warranty) and that users may redistribute the
          program under these conditions, and telling the user how to
          view a copy of this License.  (Exception: if the Program
          itself is interactive but does not normally print such an
          announcement, your work based on the Program is not required
          to print an announcement.)

     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Program, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Program, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the
     Program with the Program (or with a work based on the Program) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
     under Section 2) in object code or executable form under the terms
     of Sections 1 and 2 above provided that you also do one of the
     following:

       a. Accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Sections 1 and 2 above on a medium customarily used for
          software interchange; or,

       b. Accompany it with a written offer, valid for at least three
          years, to give any third party, for a charge no more than your
          cost of physically performing source distribution, a complete
          machine-readable copy of the corresponding source code, to be
          distributed under the terms of Sections 1 and 2 above on a
          medium customarily used for software interchange; or,

       c. Accompany it with the information you received as to the offer
          to distribute corresponding source code.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form with
          such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for
     making modifications to it.  For an executable work, complete
     source code means all the source code for all modules it contains,
     plus any associated interface definition files, plus the scripts
     used to control compilation and installation of the executable.
     However, as a special exception, the source code distributed need
     not include anything that is normally distributed (in either
     source or binary form) with the major components (compiler,
     kernel, and so on) of the operating system on which the executable
     runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering
     access to copy from a designated place, then offering equivalent
     access to copy the source code from the same place counts as
     distribution of the source code, even though third parties are not
     compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or distribute the Program is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

  5. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Program or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Program (or any work
     based on the Program), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
     Program), the recipient automatically receives a license from the
     original licensor to copy, distribute or modify the Program
     subject to these terms and conditions.  You may not impose any
     further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties to this License.

  7. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Program at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Program by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system, which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Program under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.

  9. The Free Software Foundation may publish revised and/or new
     versions of the General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Program
     does not specify a version number of this License, you may choose
     any version ever published by the Free Software Foundation.

 10. If you wish to incorporate parts of the Program into other free
     programs whose distribution conditions are different, write to the
     author to ask for permission.  For software which is copyrighted
     by the Free Software Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for this.  Our decision
     will be guided by the two goals of preserving the free status of
     all derivatives of our free software and of promoting the sharing
     and reuse of software generally.

                                NO WARRANTY

 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                      END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs
=============================================

   If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  NAME OF AUTHOR
     
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
     
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.

   Also add information on how to contact you by electronic and paper
mail.

   If the program is interactive, make it output a short notice like
this when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
     type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.

   You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright interest in the program
     `Gnomovision' (which makes passes at compilers) written by James Hacker.
     
     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

   This General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Library General Public License instead of this License.

Goals of Gforth
***************

   The goal of the Gforth Project is to develop a standard model for
ANS Forth. This can be split into several subgoals:

   * Gforth should conform to the ANS Forth Standard.

   * It should be a model, i.e. it should define all the
     implementation-dependent things.

   * It should become standard, i.e. widely accepted and used. This goal
     is the most difficult one.

   To achieve these goals Gforth should be
   * Similar to previous models (fig-Forth, F83)

   * Powerful. It should provide for all the things that are considered
     necessary today and even some that are not yet considered
     necessary.

   * Efficient. It should not get the reputation of being exceptionally
     slow.

   * Free.

   * Available on many machines/easy to port.

   Have we achieved these goals? Gforth conforms to the ANS Forth
standard. It may be considered a model, but we have not yet documented
which parts of the model are stable and which parts we are likely to
change. It certainly has not yet become a de facto standard, but it
appears to be quite popular. It has some similarities to and some
differences from previous models. It has some powerful features, but not
yet everything that we envisioned. We certainly have achieved our
execution speed goals (*note Performance::)(1).  It is free and
available on many machines.

   ---------- Footnotes ----------

   (1) However, in 1998 the bar was raised when the major commercial
Forth vendors switched to native code compilers.

Gforth Environment
******************

   Note: ultimately, the Gforth man page will be auto-generated from the
material in this chapter.

   For related information about the creation of images see *Note Image
Files::.

Invoking Gforth
===============

   Gforth is made up of two parts; an executable "engine" (named
`gforth' or `gforth-fast') and an image file. To start it, you will
usually just say `gforth' - this automatically loads the default image
file `gforth.fi'. In many other cases the default Gforth image will be
invoked like this:
     gforth [file | -e forth-code] ...

This interprets the contents of the files and the Forth code in the
order they are given.

   In addition to the `gforth' engine, there is also an engine called
`gforth-fast', which is faster, but gives less informative error
messages (*note Error messages::).  You should use it for debugged,
performance-critical programs.

   In general, the command line looks like this:

     gforth[-fast] [engine options] [image options]

   The engine options must come before the rest of the command line.
They are:

`--image-file file'
`-i file'
     Loads the Forth image file instead of the default `gforth.fi'
     (*note Image Files::).

`--appl-image file'
     Loads the image file and leaves all further command-line arguments
     to the image (instead of processing them as engine options).  This
     is useful for building executable application images on Unix,
     built with `gforthmi --application ...'.

`--path path'
`-p path'
     Uses path for searching the image file and Forth source code files
     instead of the default in the environment variable `GFORTHPATH' or
     the path specified at installation time (e.g.,
     `/usr/local/share/gforth/0.2.0:.'). A path is given as a list of
     directories, separated by `:' (on Unix) or `;' (on other OSs).

`--dictionary-size size'
`-m size'
     Allocate size space for the Forth dictionary space instead of
     using the default specified in the image (typically 256K). The
     size specification for this and subsequent options consists of an
     integer and a unit (e.g., `4M'). The unit can be one of `b'
     (bytes), `e' (element size, in this case Cells), `k' (kilobytes),
     `M' (Megabytes), `G' (Gigabytes), and `T' (Terabytes). If no unit
     is specified, `e' is used.

`--data-stack-size size'
`-d size'
     Allocate size space for the data stack instead of using the
     default specified in the image (typically 16K).

`--return-stack-size size'
`-r size'
     Allocate size space for the return stack instead of using the
     default specified in the image (typically 15K).

`--fp-stack-size size'
`-f size'
     Allocate size space for the floating point stack instead of using
     the default specified in the image (typically 15.5K). In this case
     the unit specifier `e' refers to floating point numbers.

`--locals-stack-size size'
`-l size'
     Allocate size space for the locals stack instead of using the
     default specified in the image (typically 14.5K).

`--help'
`-h'
     Print a message about the command-line options

`--version'
`-v'
     Print version and exit

`--debug'
     Print some information useful for debugging on startup.

`--offset-image'
     Start the dictionary at a slightly different position than would
     be used otherwise (useful for creating data-relocatable images,
     *note Data-Relocatable Image Files::).

`--no-offset-im'
     Start the dictionary at the normal position.

`--clear-dictionary'
     Initialize all bytes in the dictionary to 0 before loading the
     image (*note Data-Relocatable Image Files::).

`--die-on-signal'
     Normally Gforth handles most signals (e.g., the user interrupt
     SIGINT, or the segmentation violation SIGSEGV) by translating it
     into a Forth `THROW'. With this option, Gforth exits if it
     receives such a signal. This option is useful when the engine
     and/or the image might be severely broken (such that it causes
     another signal before recovering from the first); this option
     avoids endless loops in such cases.

   As explained above, the image-specific command-line arguments for the
default image `gforth.fi' consist of a sequence of filenames and `-e
FORTH-CODE' options that are interpreted in the sequence in which they
are given. The `-e FORTH-CODE' or `--evaluate FORTH-CODE' option
evaluates the Forth code. This option takes only one argument; if you
want to evaluate more Forth words, you have to quote them or use `-e'
several times. To exit after processing the command line (instead of
entering interactive mode) append `-e bye' to the command line.

   If you have several versions of Gforth installed, `gforth' will
invoke the version that was installed last. `gforth-version' invokes a
specific version. If your environment contains the variable
`GFORTHPATH', you may want to override it by using the `--path' option.

   Not yet implemented: On startup the system first executes the system
initialization file (unless the option `--no-init-file' is given; note
that the system resulting from using this option may not be ANS Forth
conformant). Then the user initialization file `.gforth.fs' is
executed, unless the option `--no-rc' is given; this file is searched
for in `.', then in `~', then in the normal path (see above).

Leaving Gforth
==============

   You can leave Gforth by typing `bye' or `Ctrl-d' (at the start of a
line) or (if you invoked Gforth with the `--die-on-signal' option)
`Ctrl-c'. When you leave Gforth, all of your definitions and data are
discarded.  For ways of saving the state of the system before leaving
Gforth see *Note Image Files::.

`bye'       -         tools-ext       ``bye''
   Return control to the host operating system (if any).

Command-line editing
====================

   Gforth maintains a history file that records every line that you
type to the text interpreter. This file is preserved between sessions,
and is used to provide a command-line recall facility; if you type
`Ctrl-P' repeatedly you can recall successively older commands from
this (or previous) session(s). The full list of command-line editing
facilities is:

   * `Ctrl-p' ("previous") (or up-arrow) to recall successively older
     commands from the history buffer.

   * `Ctrl-n' ("next") (or down-arrow) to recall successively newer
     commands from the history buffer.

   * `Ctrl-f' (or right-arrow) to move the cursor right,
     non-destructively.

   * `Ctrl-b' (or left-arrow) to move the cursor left,
     non-destructively.

   * `Ctrl-h' (backspace) to delete the character to the left of the
     cursor, closing up the line.

   * `Ctrl-k' to delete ("kill") from the cursor to the end of the line.

   * `Ctrl-a' to move the cursor to the start of the line.

   * `Ctrl-e' to move the cursor to the end of the line.

   * <RET> (`Ctrl-m') or <LFD> (`Ctrl-j') to submit the current line.

   * <TAB> to step through all possible full-word completions of the
     word currently being typed.

   * `Ctrl-d' on an empty line line to terminate Gforth (gracefully,
     using `bye').

   * `Ctrl-x' (or `Ctrl-d' on a non-empty line) to delete the character
     under the cursor.

   When editing, displayable characters are inserted to the left of the
cursor position; the line is always in "insert" (as opposed to
"overstrike") mode.

   On Unix systems, the history file is `~/.gforth-history' by
default(1). You can find out the name and location of your history file
using:

     history-file type \ Unix-class systems
     
     history-file type \ Other systems
     history-dir  type

   If you enter long definitions by hand, you can use a text editor to
paste them out of the history file into a Forth source file for reuse at
a later time.

   Gforth never trims the size of the history file, so you should do
this periodically, if necessary.

   ---------- Footnotes ----------

   (1) i.e. it is stored in the user's home directory.

Environment variables
=====================

   Gforth uses these environment variables:

   * `GFORTHHIST' - (Unix systems only) specifies the directory in
     which to open/create the history file, `.gforth-history'. Default:
     `$HOME'.

   * `GFORTHPATH' - specifies the path used when searching for the
     gforth image file and for Forth source-code files.

   * `GFORTH' - used by `gforthmi', *Note gforthmi::.

   * `GFORTHD' - used by `gforthmi', *Note gforthmi::.

   * `TMP', `TEMP' - (non-Unix systems only) used as a potential
     location for the history file.

   All the Gforth environment variables default to sensible values if
they are not set.

Gforth files
============

   When you install Gforth on a Unix system, it installs files in these
locations by default:

   * `/usr/local/bin/gforth'

   * `/usr/local/bin/gforthmi'

   * `/usr/local/man/man1/gforth.1' - man page.

   * `/usr/local/info' - the Info version of this manual.

   * `/usr/local/lib/gforth/<version>/...' - Gforth `.fi' files.

   * `/usr/local/share/gforth/<version>/TAGS' - Emacs TAGS file.

   * `/usr/local/share/gforth/<version>/...' - Gforth source files.

   * `.../emacs/site-lisp/gforth.el' - Emacs gforth mode.

   You can select different places for installation by using
`configure' options (listed with `configure --help').

Startup speed
=============

   If Gforth is used for CGI scripts or in shell scripts, its startup
speed may become a problem.  On a 300MHz 21064a under Linux-2.2.13 with
glibc-2.0.7, `gforth -e bye' takes about 24.6ms user and 11.3ms system
time.

   If startup speed is a problem, you may consider the following ways to
improve it; or you may consider ways to reduce the number of startups
(for example, by using Fast-CGI).

   The first step to improve startup speed is to statically link
Gforth, by building it with `XLDFLAGS=-static'.  This requires more
memory for the code and will therefore slow down the first invocation,
but subsequent invocations avoid the dynamic linking overhead.  Another
disadvantage is that Gforth won't profit from library upgrades.  As a
result, `gforth-static -e bye' takes about 17.1ms user and 8.2ms system
time.

   The next step to improve startup speed is to use a non-relocatable
image (*note Non-Relocatable Image Files::).  You can create this image
with `gforth -e "savesystem gforthnr.fi bye"' and later use it with
`gforth -i gforthnr.fi ...'.  This avoids the relocation overhead and a
part of the copy-on-write overhead.  The disadvantage is that the
non-relocatable image does not work if the OS gives Gforth a different
address for the dictionary, for whatever reason; so you better provide a
fallback on a relocatable image.  `gforth-static -i gforthnr.fi -e bye'
takes about 15.3ms user and 7.5ms system time.

   The final step is to disable dictionary hashing in Gforth.  Gforth
builds the hash table on startup, which takes much of the startup
overhead. You can do this by commenting out the `include hash.fs' in
`startup.fs' and everything that requires `hash.fs' (at the moment
`table.fs' and `ekey.fs') and then doing `make'.  The disadvantages are
that functionality like `table' and `ekey' is missing and that text
interpretation (e.g., compiling) now takes much longer. So, you should
only use this method if there is no significant text interpretation to
perform (the script should be compiled into the image, amongst other
things).  `gforth-static -i gforthnrnh.fi -e bye' takes about 2.1ms
user and 6.1ms system time.

Forth Tutorial
**************

   The difference of this chapter from the Introduction (*note
Introduction::) is that this tutorial is more fast-paced, should be
used while sitting in front of a computer, and covers much more
material, but does not explain how the Forth system works.

   This tutorial can be used with any ANS-compliant Forth; any
Gforth-specific features are marked as such and you can skip them if you
work with another Forth.  This tutorial does not explain all features of
Forth, just enough to get you started and give you some ideas about the
facilities available in Forth.  Read the rest of the manual and the
standard when you are through this.

   The intended way to use this tutorial is that you work through it
while sitting in front of the console, take a look at the examples and
predict what they will do, then try them out; if the outcome is not as
expected, find out why (e.g., by trying out variations of the example),
so you understand what's going on.  There are also some assignments
that you should solve.

   This tutorial assumes that you have programmed before and know what,
e.g., a loop is.

Starting Gforth
===============

   You can start Gforth by typing its name:

     gforth

   That puts you into interactive mode; you can leave Gforth by typing
`bye'.  While in Gforth, you can edit the command line and access the
command line history with cursor keys, similar to bash.

Syntax
======

   A "word" is a sequence of arbitrary characters (expcept white
space).  Words are separated by white space.  E.g., each of the
following lines contains exactly one word:

     word
     !@#$%^&*()
     1234567890
     5!a

   A frequent beginner's error is to leave away necessary white space,
resulting in an error like `Undefined word'; so if you see such an
error, check if you have put spaces wherever necessary.

     ." hello, world" \ correct
     ."hello, world"  \ gives an "Undefined word" error

   Gforth and most other Forth systems ignore differences in case (they
are case-insensitive), i.e., `word' is the same as `Word'.  If your
system is case-sensitive, you may have to type all the examples given
here in upper case.

Crash Course
============

   Type

     0 0 !
     here execute
     ' catch >body 20 erase abort
     ' (quit) >body 20 erase

   The last two examples are guaranteed to destroy parts of Gforth (and
most other systems), so you better leave Gforth afterwards (if it has
not finished by itself).  On some systems you may have to kill gforth
from outside (e.g., in Unix with `kill').

   Now that you know how to produce crashes (and that there's not much
to them), let's learn how to produce meaningful programs.

Stack
=====

   The most obvious feature of Forth is the stack.  When you type in a
number, it is pushed on the stack.  You can display the content of the
stack with `.s'.

     1 2 .s
     3 .s

   `.s' displays the top-of-stack to the right, i.e., the numbers
appear in `.s' output as they appeared in the input.

   You can print the top of stack element with `.'.

     1 2 3 . . .

   In general, words consume their stack arguments (`.s' is an
exception).

Assignment:
     What does the stack contain after `5 6 7 .'?

Arithmetics
===========

   The words `+', `-', `*', `/', and `mod' always operate on the top
two stack items:

     2 2 .s
     + .s
     .
     2 1 - .
     7 3 mod .

   The operands of `-', `/', and `mod' are in the same order as in the
corresponding infix expression (this is generally the case in Forth).

   Parentheses are superfluous (and not available), because the order of
the words unambiguously determines the order of evaluation and the
operands:

     3 4 + 5 * .
     3 4 5 * + .

Assignment:
     What are the infix expressions corresponding to the Forth code
     above?  Write `6-7*8+9' in Forth notation(1).

   To change the sign, use `negate':

     2 negate .

Assignment:
     Convert -(-3)*4-5 to Forth.

   `/mod' performs both `/' and `mod'.

     7 3 /mod . .

   Reference: *Note Arithmetic::.

   ---------- Footnotes ----------

   (1) This notation is also known as Postfix or RPN (Reverse Polish
Notation).

Stack Manipulation
==================

   Stack manipulation words rearrange the data on the stack.

     1 .s drop .s
     1 .s dup .s drop drop .s
     1 2 .s over .s drop drop drop
     1 2 .s swap .s drop drop
     1 2 3 .s rot .s drop drop drop

   These are the most important stack manipulation words.  There are
also variants that manipulate twice as many stack items:

     1 2 3 4 .s 2swap .s 2drop 2drop

   Two more stack manipulation words are:

     1 2 .s nip .s drop
     1 2 .s tuck .s 2drop drop

Assignment:
     Replace `nip' and `tuck' with combinations of other stack
     manipulation words.

          Given:          How do you get:
          1 2 3           3 2 1
          1 2 3           1 2 3 2
          1 2 3           1 2 3 3
          1 2 3           1 3 3
          1 2 3           2 1 3
          1 2 3 4         4 3 2 1
          1 2 3           1 2 3 1 2 3
          1 2 3 4         1 2 3 4 1 2
          1 2 3
          1 2 3           1 2 3 4
          1 2 3           1 3

     5 dup * .

Assignment:
     Write 17^3 and 17^4 in Forth, without writing `17' more than once.
     Write a piece of Forth code that expects two numbers on the stack
     (A and B, with B on top) and computes `(a-b)(a+1)'.

   Reference: *Note Stack Manipulation::.

Using files for Forth code
==========================

   While working at the Forth command line is convenient for one-line
examples and short one-off code, you probably want to store your source
code in files for convenient editing and persistence.  You can use your
favourite editor (Gforth includes Emacs support, *note Emacs and
Gforth::) to create FILE and use

     s" FILE" included

   to load it into your Forth system.  The file name extension I use for
Forth files is `.fs'.

   You can easily start Gforth with some files loaded like this:

     gforth FILE1 FILE2

   If an error occurs during loading these files, Gforth terminates,
whereas an error during `INCLUDED' within Gforth usually gives you a
Gforth command line.  Starting the Forth system every time gives you a
clean start every time, without interference from the results of earlier
tries.

   I often put all the tests in a file, then load the code and run the
tests with

     gforth CODE TESTS -e bye

   (often by performing this command with `C-x C-e' in Emacs).  The `-e
bye' ensures that Gforth terminates afterwards so that I can restart
this command without ado.

   The advantage of this approach is that the tests can be repeated
easily every time the program ist changed, making it easy to catch bugs
introduced by the change.

   Reference: *Note Forth source files::.

Comments
========

     \ That's a comment; it ends at the end of the line
     ( Another comment; it ends here: )  .s

   `\' and `(' are ordinary Forth words and therefore have to be
separated with white space from the following text.

     \This gives an "Undefined word" error

   The first `)' ends a comment started with `(', so you cannot nest
`('-comments; and you cannot comment out text containing a `)' with `(
... )'(1).

   I use `\'-comments for descriptive text and for commenting out code
of one or more line; I use `('-comments for describing the stack
effect, the stack contents, or for commenting out sub-line pieces of
code.

   The Emacs mode `gforth.el' (*note Emacs and Gforth::) supports these
uses by commenting out a region with `C-x \', uncommenting a region
with `C-u C-x \', and filling a `\'-commented region with `M-q'.

   Reference: *Note Comments::.

   ---------- Footnotes ----------

   (1) therefore it's a good idea to avoid `)' in word names.

Colon Definitions
=================

   are similar to procedures and functions in other programming
languages.

     : squared ( n -- n^2 )
        dup * ;
     5 squared .
     7 squared .

   `:' starts the colon definition; its name is `squared'.  The
following comment describes its stack effect.  The words `dup *' are
not executed, but compiled into the definition.  `;' ends the colon
definition.

   The newly-defined word can be used like any other word, including
using it in other definitions:

     : cubed ( n -- n^3 )
        dup squared * ;
     -5 cubed .
     : fourth-power ( n -- n^4 )
        squared squared ;
     3 fourth-power .

Assignment:
     Write colon definitions for `nip', `tuck', `negate', and `/mod' in
     terms of other Forth words, and check if they work (hint: test
     your tests on the originals first).  Don't let the
     `redefined'-Messages spook you, they are just warnings.

   Reference: *Note Colon Definitions::.

Decompilation
=============

   You can decompile colon definitions with `see':

     see squared
     see cubed

   In Gforth `see' shows you a reconstruction of the source code from
the executable code.  Informations that were present in the source, but
not in the executable code, are lost (e.g., comments).

   You can also decompile the predefined words:

     see .
     see +

Stack-Effect Comments
=====================

   By convention the comment after the name of a definition describes
the stack effect: The part in from of the `--' describes the state of
the stack before the execution of the definition, i.e., the parameters
that are passed into the colon definition; the part behind the `--' is
the state of the stack after the execution of the definition, i.e., the
results of the definition.  The stack comment only shows the top stack
items that the definition accesses and/or changes.

   You should put a correct stack effect on every definition, even if
it is just `( -- )'.  You should also add some descriptive comment to
more complicated words (I usually do this in the lines following `:').
If you don't do this, your code becomes unreadable (because you have to
work through every definition before you can undertsand any).

Assignment:
     The stack effect of `swap' can be written like this: `x1 x2 -- x2
     x1'.  Describe the stack effect of `-', `drop', `dup', `over',
     `rot', `nip', and `tuck'.  Hint: When you are done, you can
     compare your stack effects to those in this manual (*note Word
     Index::).

   Sometimes programmers put comments at various places in colon
definitions that describe the contents of the stack at that place (stack
comments); i.e., they are like the first part of a stack-effect
comment. E.g.,

     : cubed ( n -- n^3 )
        dup squared  ( n n^2 ) * ;

   In this case the stack comment is pretty superfluous, because the
word is simple enough.  If you think it would be a good idea to add
such a comment to increase readability, you should also consider
factoring the word into several simpler words (*note Factoring:
Factoring Tutorial.), which typically eliminates the need for the stack
comment; however, if you decide not to refactor it, then having such a
comment is better than not having it.

   The names of the stack items in stack-effect and stack comments in
the standard, in this manual, and in many programs specify the type
through a type prefix, similar to Fortran and Hungarian notation.  The
most frequent prefixes are:

`n'
     signed integer

`u'
     unsigned integer

`c'
     character

`f'
     Boolean flags, i.e. `false' or `true'.

`a-addr,a-'
     Cell-aligned address

`c-addr,c-'
     Char-aligned address (note that a Char may have two bytes in
     Windows NT)

`xt'
     Execution token, same size as Cell

`w,x'
     Cell, can contain an integer or an address.  It usually takes 32,
     64 or 16 bits (depending on your platform and Forth system). A
     cell is more commonly known as machine word, but the term _word_
     already means something different in Forth.

`d'
     signed double-cell integer

`ud'
     unsigned double-cell integer

`r'
     Float (on the FP stack)

   You can find a more complete list in *Note Notation::.

Assignment:
     Write stack-effect comments for all definitions you have written
     up to now.

Types
=====

   In Forth the names of the operations are not overloaded; so similar
operations on different types need different names; e.g., `+' adds
integers, and you have to use `f+' to add floating-point numbers.  The
following prefixes are often used for related operations on different
types:

`(none)'
     signed integer

`u'
     unsigned integer

`c'
     character

`d'
     signed double-cell integer

`ud, du'
     unsigned double-cell integer

`2'
     two cells (not-necessarily double-cell numbers)

`m, um'
     mixed single-cell and double-cell operations

`f'
     floating-point (note that in stack comments `f' represents flags,
     and `r' represents FP numbers).

   If there are no differences between the signed and the unsigned
variant (e.g., for `+'), there is only the prefix-less variant.

   Forth does not perform type checking, neither at compile time, nor at
run time.  If you use the wrong oeration, the data are interpreted
incorrectly:

     -1 u.

   If you have only experience with type-checked languages until now,
and have heard how important type-checking is, don't panic!  In my
experience (and that of other Forthers), type errors in Forth code are
usually easy to find (once you get used to it), the increased vigilance
of the programmer tends to catch some harder errors in addition to most
type errors, and you never have to work around the type system, so in
most situations the lack of type-checking seems to be a win (projects to
add type checking to Forth have not caught on).

Factoring
=========

   If you try to write longer definitions, you will soon find it hard to
keep track of the stack contents.  Therefore, good Forth programmers
tend to write only short definitions (e.g., three lines).  The art of
finding meaningful short definitions is known as factoring (as in
factoring polynomials).

   Well-factored programs offer additional advantages: smaller, more
general words, are easier to test and debug and can be reused more and
better than larger, specialized words.

   So, if you run into difficulties with stack management, when writing
code, try to define meaningful factors for the word, and define the word
in terms of those.  Even if a factor contains only two words, it is
often helpful.

   Good factoring is not easy, and it takes some practice to get the
knack for it; but even experienced Forth programmers often don't find
the right solution right away, but only when rewriting the program.
So, if you don't come up with a good solution immediately, keep trying,
don't despair.

Designing the stack effect
==========================

   In other languages you can use an arbitrary order of parameters for a
function; and since there is only one result, you don't have to deal
with the order of results, either.

   In Forth (and other stack-based languages, e.g., Postscript) the
parameter and result order of a definition is important and should be
designed well.  The general guideline is to design the stack effect such
that the word is simple to use in most cases, even if that complicates
the implementation of the word.  Some concrete rules are:

   * Words consume all of their parameters (e.g., `.').

   * If there is a convention on the order of parameters (e.g., from
     mathematics or another programming language), stick with it (e.g.,
     `-').

   * If one parameter usually requires only a short computation (e.g.,
     it is a constant), pass it on the top of the stack.  Conversely,
     parameters that usually require a long sequence of code to compute
     should be passed as the bottom (i.e., first) parameter.  This
     makes the code easier to read, because reader does not need to
     keep track of the bottom item through a long sequence of code (or,
     alternatively, through stack manipulations). E.g., `!' (store,
     *note Memory::) expects the address on top of the stack because it
     is usually simpler to compute than the stored value (often the
     address is just a variable).

   * Similarly, results that are usually consumed quickly should be
     returned on the top of stack, whereas a result that is often used
     in long computations should be passed as bottom result.  E.g., the
     file words like `open-file' return the error code on the top of
     stack, because it is usually consumed quickly by `throw';
     moreover, the error code has to be checked before doing anything
     with the other results.


   These rules are just general guidelines, don't lose sight of the
overall goal to make the words easy to use.  E.g., if the convention
rule conflicts with the computation-length rule, you might decide in
favour of the convention if the word will be used rarely, and in favour
of the computation-length rule if the word will be used frequently
(because with frequent use the cost of breaking the computation-length
rule would be quite high, and frequent use makes it easier to remember
an unconventional order).

Local Variables
===============

   You can define local variables (_locals_) in a colon definition:

     : swap { a b -- b a }
       b a ;
     1 2 swap .s 2drop

   (If your Forth system does not support this syntax, include
`compat/anslocals.fs' first).

   In this example `{ a b -- b a }' is the locals definition; it takes
two cells from the stack, puts the top of stack in `b' and the next
stack element in `a'.  `--' starts a comment ending with `}'.  After
the locals definition, using the name of the local will push its value
on the stack.  You can leave the comment part (`-- b a') away:

     : swap ( x1 x2 -- x2 x1 )
       { a b } b a ;

   In Gforth you can have several locals definitions, anywhere in a
colon definition; in contrast, in a standard program you can have only
one locals definition per colon definition, and that locals definition
must be outside any controll structure.

   With locals you can write slightly longer definitions without running
into stack trouble.  However, I recommend trying to write colon
definitions without locals for exercise purposes to help you gain the
essential factoring skills.

Assignment:
     Rewrite your definitions until now with locals

   Reference: *Note Locals::.

Conditional execution
=====================

   In Forth you can use control structures only inside colon
definitions.  An `if'-structure looks like this:

     : abs ( n1 -- +n2 )
         dup 0 < if
             negate
         endif ;
     5 abs .
     -5 abs .

   `if' takes a flag from the stack.  If the flag is non-zero (true),
the following code is performed, otherwise execution continues after the
`endif' (or `else').  `<' compares the top two stack elements and
prioduces a flag:

     1 2 < .
     2 1 < .
     1 1 < .

   Actually the standard name for `endif' is `then'.  This tutorial
presents the examples using `endif', because this is often less
confusing for people familiar with other programming languages where
`then' has a different meaning.  If your system does not have `endif',
define it with

     : endif postpone then ; immediate

   You can optionally use an `else'-part:

     : min ( n1 n2 -- n )
       2dup < if
         drop
       else
         nip
       endif ;
     2 3 min .
     3 2 min .

Assignment:
     Write `min' without `else'-part (hint: what's the definition of
     `nip'?).

   Reference: *Note Selection::.

Flags and Comparisons
=====================

   In a false-flag all bits are clear (0 when interpreted as integer).
In a canonical true-flag all bits are set (-1 as a twos-complement
signed integer); in many contexts (e.g., `if') any non-zero value is
treated as true flag.

     false .
     true .
     true hex u. decimal

   Comparison words produce canonical flags:

     1 1 = .
     1 0= .
     0 1 < .
     0 0 < .
     -1 1 u< . \ type error, u< interprets -1 as large unsigned number
     -1 1 < .

   Gforth supports all combinations of the prefixes `0 u d d0 du f f0'
(or none) and the comparisons `= <> < > <= >='.  Only a part of these
combinations are standard (for details see the standard, *Note Numeric
comparison::, *Note Floating Point:: or *Note Word Index::).

   You can use `and or xor invert' can be used as operations on
canonical flags.  Actually they are bitwise operations:

     1 2 and .
     1 2 or .
     1 3 xor .
     1 invert .

   You can convert a zero/non-zero flag into a canonical flag with
`0<>' (and complement it on the way with `0=').

     1 0= .
     1 0<> .

   You can use the all-bits-set feature of canonical flags and the
bitwise operation of the Boolean operations to avoid `if's:

     : foo ( n1 -- n2 )
       0= if
         14
       else
         0
       endif ;
     0 foo .
     1 foo .
     
     : foo ( n1 -- n2 )
       0= 14 and ;
     0 foo .
     1 foo .

Assignment:
     Write `min' without `if'.

   For reference, see *Note Boolean Flags::, *Note Numeric
comparison::, and *Note Bitwise operations::.

General Loops
=============

   The endless loop is the most simple one:

     : endless ( -- )
       0 begin
         dup . 1+
       again ;
     endless

   Terminate this loop by pressing `Ctrl-C' (in Gforth).  `begin' does
nothing at run-time, `again' jumps back to `begin'.

   A loop with one exit at any place looks like this:

     : log2 ( +n1 -- n2 )
     \ logarithmus dualis of n1>0, rounded down to the next integer
       assert( dup 0> )
       2/ 0 begin
         over 0> while
           1+ swap 2/ swap
       repeat
       nip ;
     7 log2 .
     8 log2 .

   At run-time `while' consumes a flag; if it is 0, execution continues
behind the `repeat'; if the flag is non-zero, execution continues
behind the `while'.  `Repeat' jumps back to `begin', just like `again'.

   In Forth there are many combinations/abbreviations, like `1+'.
However, `2/' is not one of them; it shifts it's argument right by one
bit (arithmetic shift right):

     -5 2 / .
     -5 2/ .

   `assert(' is no standard word, but you can get it on systems other
then Gforth by including `compat/assert.fs'.  You can see what it does
by trying

     0 log2 .

   Here's a loop with an exit at the end:

     : log2 ( +n1 -- n2 )
     \ logarithmus dualis of n1>0, rounded down to the next integer
       assert( dup 0 > )
       -1 begin
         1+ swap 2/ swap
         over 0 <=
       until
       nip ;

   `Until' consumes a flag; if it is non-zero, execution continues at
the `begin', otherwise after the `until'.

Assignment:
     Write a definition for computing the greatest common divisor.

   Reference: *Note Simple Loops::.

Counted loops
=============

     : ^ ( n1 u -- n )
     \ n = the uth power of u1
       1 swap 0 u+do
         over *
       loop
       nip ;
     3 2 ^ .
     4 3 ^ .

   `U+do' (from `compat/loops.fs', if your Forth system doesn't have
it) takes two numbers of the stack `( u3 u4 -- )', and then performs
the code between `u+do' and `loop' for `u3-u4' times (or not at all, if
`u3-u4<0').

   You can see the stack effect design rules at work in the stack
effect of the loop start words: Since the start value of the loop is
more frequently constant than the end value, the start value is passed
on the top-of-stack.

   You can access the counter of a counted loop with `i':

     : fac ( u -- u! )
       1 swap 1+ 1 u+do
         i *
       loop ;
     5 fac .
     7 fac .

   There is also `+do', which expects signed numbers (important for
deciding whether to enter the loop).

Assignment:
     Write a definition for computing the nth Fibonacci number.

   You can also use increments other than 1:

     : up2 ( n1 n2 -- )
       +do
         i .
       2 +loop ;
     10 0 up2
     
     : down2 ( n1 n2 -- )
       -do
         i .
       2 -loop ;
     0 10 down2

   Reference: *Note Counted Loops::.

Recursion
=========

   Usually the name of a definition is not visible in the definition;
but earlier definitions are usually visible:

     1 0 / . \ "Floating-point unidentified fault" in Gforth on most platforms
     : / ( n1 n2 -- n )
       dup 0= if
         -10 throw \ report division by zero
       endif
       /           \ old version
     ;
     1 0 /

   For recursive definitions you can use `recursive' (non-standard) or
`recurse':

     : fac1 ( n -- n! ) recursive
      dup 0> if
        dup 1- fac1 *
      else
        drop 1
      endif ;
     7 fac1 .
     
     : fac2 ( n -- n! )
      dup 0> if
        dup 1- recurse *
      else
        drop 1
      endif ;
     8 fac2 .

Assignment:
     Write a recursive definition for computing the nth Fibonacci
     number.

   Reference (including indirect recursion): *Note Calls and returns::.

Leaving definitions or loops
============================

   `EXIT' exits the current definition right away.  For every counted
loop that is left in this way, an `UNLOOP' has to be performed before
the `EXIT':

     : ...
      ... u+do
        ... if
          ... unloop exit
        endif
        ...
      loop
      ... ;

   `LEAVE' leaves the innermost counted loop right away:

     : ...
      ... u+do
        ... if
          ... leave
        endif
        ...
      loop
      ... ;

   Reference: *Note Calls and returns::, *Note Counted Loops::.

Return Stack
============

   In addition to the data stack Forth also has a second stack, the
return stack; most Forth systems store the return addresses of
procedure calls there (thus its name).  Programmers can also use this
stack:

     : foo ( n1 n2 -- )
      .s
      >r .s
      r@ .
      >r .s
      r@ .
      r> .
      r@ .
      r> . ;
     1 2 foo

   `>r' takes an element from the data stack and pushes it onto the
return stack; conversely, `r>' moves an elementm from the return to the
data stack; `r@' pushes a copy of the top of the return stack on the
return stack.

   Forth programmers usually use the return stack for storing data
temporarily, if using the data stack alone would be too complex, and
factoring and locals are not an option:

     : 2swap ( x1 x2 x3 x4 -- x3 x4 x1 x2 )
      rot >r rot r> ;

   The return address of the definition and the loop control parameters
of counted loops usually reside on the return stack, so you have to take
all items, that you have pushed on the return stack in a colon
definition or counted loop, from the return stack before the definition
or loop ends.  You cannot access items that you pushed on the return
stack outside some definition or loop within the definition of loop.

   If you miscount the return stack items, this usually ends in a crash:

     : crash ( n -- )
       >r ;
     5 crash

   You cannot mix using locals and using the return stack (according to
the standard; Gforth has no problem).  However, they solve the same
problems, so this shouldn't be an issue.

Assignment:
     Can you rewrite any of the definitions you wrote until now in a
     better way using the return stack?

   Reference: *Note Return stack::.

Memory
======

   You can create a global variable `v' with

     variable v ( -- addr )

   `v' pushes the address of a cell in memory on the stack.  This cell
was reserved by `variable'.  You can use `!' (store) to store values
into this cell and `@' (fetch) to load the value from the stack into
memory:

     v .
     5 v ! .s
     v @ .

   You can see a raw dump of memory with `dump':

     v 1 cells .s dump

   `Cells ( n1 -- n2 )' gives you the number of bytes (or, more
generally, address units (aus)) that `n1 cells' occupy.  You can also
reserve more memory:

     create v2 20 cells allot
     v2 20 cells dump

   creates a word `v2' and reserves 20 uninitialized cells; the address
pushed by `v2' points to the start of these 20 cells.  You can use
address arithmetic to access these cells:

     3 v2 5 cells + !
     v2 20 cells dump

   You can reserve and initialize memory with `,':

     create v3
       5 , 4 , 3 , 2 , 1 ,
     v3 @ .
     v3 cell+ @ .
     v3 2 cells + @ .
     v3 5 cells dump

Assignment:
     Write a definition `vsum ( addr u -- n )' that computes the sum of
     `u' cells, with the first of these cells at `addr', the next one
     at `addr cell+' etc.

   You can also reserve memory without creating a new word:

     here 10 cells allot .
     here .

   `Here' pushes the start address of the memory area.  You should
store it somewhere, or you will have a hard time finding the memory area
again.

   `Allot' manages dictionary memory.  The dictionary memory contains
the system's data structures for words etc. on Gforth and most other
Forth systems.  It is managed like a stack: You can free the memory that
you have just `allot'ed with

     -10 cells allot
     here .

   Note that you cannot do this if you have created a new word in the
meantime (because then your `allot'ed memory is no longer on the top of
the dictionary "stack").

   Alternatively, you can use `allocate' and `free' which allow freeing
memory in any order:

     10 cells allocate throw .s
     20 cells allocate throw .s
     swap
     free throw
     free throw

   The `throw's deal with errors (e.g., out of memory).

   And there is also a garbage collector
(http://www.complang.tuwien.ac.at/forth/garbage-collection.zip), which
eliminates the need to `free' memory explicitly.

   Reference: *Note Memory::.

Characters and Strings
======================

   On the stack characters take up a cell, like numbers.  In memory they
have their own size (one 8-bit byte on most systems), and therefore
require their own words for memory access:

     create v4
       104 c, 97 c, 108 c, 108 c, 111 c,
     v4 4 chars + c@ .
     v4 5 chars dump

   The preferred representation of strings on the stack is `addr
u-count', where `addr' is the address of the first character and
`u-count' is the number of characters in the string.

     v4 5 type

   You get a string constant with

     s" hello, world" .s
     type

   Make sure you have a space between `s"' and the string; `s"' is a
normal Forth word and must be delimited with white space (try what
happens when you remove the space).

   However, this interpretive use of `s"' is quite restricted: the
string exists only until the next call of `s"' (some Forth systems keep
more than one of these strings, but usually they still have a limited
lifetime).

     s" hello," s" world" .s
     type
     type

   You can also use `s"' in a definition, and the resulting strings
then live forever (well, for as long as the definition):

     : foo s" hello," s" world" ;
     foo .s
     type
     type

Assignment:
     `Emit ( c -- )' types `c' as character (not a number).  Implement
     `type ( addr u -- )'.

   Reference: *Note Memory Blocks::.

Alignment
=========

   On many processors cells have to be aligned in memory, if you want to
access them with `@' and `!' (and even if the processor does not
require alignment, access to aligned cells is faster).

   `Create' aligns `here' (i.e., the place where the next allocation
will occur, and that the `create'd word points to).  Likewise, the
memory produced by `allocate' starts at an aligned address.  Adding a
number of `cells' to an aligned address produces another aligned
address.

   However, address arithmetic involving `char+' and `chars' can create
an address that is not cell-aligned.  `Aligned ( addr -- a-addr )'
produces the next aligned address:

     v3 char+ aligned .s @ .
     v3 char+ .s @ .

   Similarly, `align' advances `here' to the next aligned address:

     create v5 97 c,
     here .
     align here .
     1000 ,

   Note that you should use aligned addresses even if your processor
does not require them, if you want your program to be portable.

   Reference: *Note Address arithmetic::.

Files
=====

   This section gives a short introduction into how to use files inside
Forth. It's broken up into five easy steps:

  1. Opened an ASCII text file for input

  2. Opened a file for output

  3. Read input file until string matched (or some other condition
     matched)

  4. Wrote some lines from input ( modified or not) to output

  5. Closed the files.

Open file for input
-------------------

     s" foo.in"  r/o open-file throw Value fd-in

Create file for output
----------------------

     s" foo.out" w/o create-file throw Value fd-out

   The available file modes are r/o for read-only access, r/w for
read-write access, and w/o for write-only access. You could open both
files with r/w, too, if you like. All file words return error codes; for
most applications, it's best to pass there error codes with `throw' to
the outer error handler.

   If you want words for opening and assigning, define them as follows:

     0 Value fd-in
     0 Value fd-out
     : open-input ( addr u -- )  r/o open-file throw to fd-in ;
     : open-output ( addr u -- )  w/o create-file throw to fd-out ;

   Usage example:

     s" foo.in" open-input
     s" foo.out" open-output

Scan file for a particular line
-------------------------------

     256 Constant max-line
     Create line-buffer  max-line 2 + allot
     
     : scan-file ( addr u -- )
       begin
           line-buffer max-line fd-in read-line throw
       while
              >r 2dup line-buffer r> compare 0=
          until
       else
          drop
       then
       2drop ;

   `read-line ( addr u1 fd -- u2 flag ior )' reads up to u1 bytes into
the buffer at addr, and returns the number of bytes read, a flag that's
true when the end of file is reached, and an error code.

   `compare ( addr1 u1 addr2 u2 -- n )' compares two strings and
returns zero if both strings are equal. It returns a positive number if
the first string is lexically greater, a negative if the second string
is lexically greater.

   We haven't seen this loop here; it has two exits. Since the `while'
exits with the number of bytes read on the stack, we have to clean up
that separately; that's after the `else'.

   Usage example:

     s" The text I search is here" scan-file

Copy input to output
--------------------

     : copy-file ( -- )
       begin
           line-buffer max-line fd-in read-line throw
       while
           line-buffer swap fd-out write-file throw
       repeat ;

Close files
-----------

     fd-in close-file throw
     fd-out close-file throw

   Likewise, you can put that into definitions, too:

     : close-input ( -- )  fd-in close-file throw ;
     : close-output ( -- )  fd-out close-file throw ;

Assignment:
     How could you modify `copy-file' so that it copies until a second
     line is matched? Can you write a program that extracts a section
     of a text file, given the line that starts and the line that
     terminates that section?

Interpretation and Compilation Semantics and Immediacy
======================================================

   When a word is compiled, it behaves differently from being
interpreted.  E.g., consider `+':

     1 2 + .
     : foo + ;

   These two behaviours are known as compilation and interpretation
semantics.  For normal words (e.g., `+'), the compilation semantics is
to append the interpretation semantics to the currently defined word
(`foo' in the example above).  I.e., when `foo' is executed later, the
interpretation semantics of `+' (i.e., adding two numbers) will be
performed.

   However, there are words with non-default compilation semantics,
e.g., the control-flow words like `if'.  You can use `immediate' to
change the compilation semantics of the last defined word to be equal to
the interpretation semantics:

     : [FOO] ( -- )
      5 . ; immediate
     
     [FOO]
     : bar ( -- )
       [FOO] ;
     bar
     see bar

   Two conventions to mark words with non-default compilation semnatics
are names with brackets (more frequently used) and to write them all in
upper case (less frequently used).

   In Gforth (and many other systems) you can also remove the
interpretation semantics with `compile-only' (the compilation semantics
is derived from the original interpretation semantics):

     : flip ( -- )
      6 . ; compile-only \ but not immediate
     flip
     
     : flop ( -- )
      flip ;
     flop

   In this example the interpretation semantics of `flop' is equal to
the original interpretation semantics of `flip'.

   The text interpreter has two states: in interpret state, it performs
the interpretation semantics of words it encounters; in compile state,
it performs the compilation semantics of these words.

   Among other things, `:' switches into compile state, and `;'
switches back to interpret state.  They contain the factors `]' (switch
to compile state) and `[' (switch to interpret state), that do nothing
but switch the state.

     : xxx ( -- )
       [ 5 . ]
     ;
     
     xxx
     see xxx

   These brackets are also the source of the naming convention mentioned
above.

   Reference: *Note Interpretation and Compilation Semantics::.

Execution Tokens
================

   `' word' gives you the execution token (XT) of a word.  The XT is a
cell representing the interpretation semantics of a word.  You can
execute this semantics with `execute':

     ' + .s
     1 2 rot execute .

   The XT is similar to a function pointer in C.  However, parameter
passing through the stack makes it a little more flexible:

     : map-array ( ... addr u xt -- ... )
     \ executes xt ( ... x -- ... ) for every element of the array starting
     \ at addr and containing u elements
       { xt }
       cells over + swap ?do
         i @ xt execute
       1 cells +loop ;
     
     create a 3 , 4 , 2 , -1 , 4 ,
     a 5 ' . map-array .s
     0 a 5 ' + map-array .
     s" max-n" environment? drop .s
     a 5 ' min map-array .

   You can use map-array with the XTs of words that consume one element
more than they produce.  In theory you can also use it with other XTs,
but the stack effect then depends on the size of the array, which is
hard to understand.

   Since XTs are cell-sized, you can store them in memory and manipulate
them on the stack like other cells.  You can also compile the XT into a
word with `compile,':

     : foo1 ( n1 n2 -- n )
        [ ' + compile, ] ;
     see foo

   This is non-standard, because `compile,' has no compilation
semantics in the standard, but it works in good Forth systems.  For the
broken ones, use

     : [compile,] compile, ; immediate
     
     : foo1 ( n1 n2 -- n )
        [ ' + ] [compile,] ;
     see foo

   `'' is a word with default compilation semantics; it parses the next
word when its interpretation semantics are executed, not during
compilation:

     : foo ( -- xt )
       ' ;
     see foo
     : bar ( ... "word" -- ... )
       ' execute ;
     see bar
     1 2 bar + .

   You often want to parse a word during compilation and compile its XT
so it will be pushed on the stack at run-time.  `[']' does this:

     : xt-+ ( -- xt )
       ['] + ;
     see xt-+
     1 2 xt-+ execute .

   Many programmers tend to see `'' and the word it parses as one unit,
and expect it to behave like `[']' when compiled, and are confused by
the actual behaviour.  If you are, just remember that the Forth system
just takes `'' as one unit and has no idea that it is a parsing word
(attempts to convenience programmers in this issue have usually
resulted in even worse pitfalls, see `State'-smartness--Why it is evil
and How to Exorcise it
(http://www.complang.tuwien.ac.at/papers/ertl98.ps.gz)).

   Note that the state of the interpreter does not come into play when
creating and executing XTs.  I.e., even when you execute `'' in compile
state, it still gives you the interpretation semantics.  And whatever
that state is, `execute' performs the semantics represented by the XT
(i.e., for XTs produced with `'' the interpretation semantics).

   Reference: *Note Tokens for Words::.

Exceptions
==========

   `throw ( n -- )' causes an exception unless n is zero.

     100 throw .s
     0 throw .s

   `catch ( ... xt -- ... n )' behaves similar to `execute', but it
catches exceptions and pushes the number of the exception on the stack
(or 0, if the xt executed without exception).  If there was an
exception, the stacks have the same depth as when entering `catch':

     .s
     3 0 ' / catch .s
     3 2 ' / catch .s

Assignment:
     Try the same with `execute' instead of `catch'.

   `Throw' always jumps to the dynamically next enclosing `catch', even
if it has to leave several call levels to achieve this:

     : foo 100 throw ;
     : foo1 foo ." after foo" ;
     : bar ['] foo1 catch ;
     bar .

   It is often important to restore a value upon leaving a definition,
even if the definition is left through an exception.  You can ensure
this like this:

     : ...
        save-x
        ['] word-changing-x catch ( ... n )
        restore-x
        ( ... n ) throw ;

   Gforth provides an alternative syntax in addition to `catch': `try
... recover ... endtry'.  If the code between `try' and `recover' has
an exception, the stack depths are restored, the exception number is
pushed on the stack, and the code between `recover' and `endtry' is
performed.  E.g., the definition for `catch' is

     : catch ( x1 .. xn xt -- y1 .. ym 0 / z1 .. zn error ) \ exception
       try
         execute 0
       recover
         nip
       endtry ;

   The equivalent to the restoration code above is

     : ...
       save-x
       try
         word-changing-x
       end-try
       restore-x
       throw ;

   As you can see, the `recover' part is optional.

   Reference: *Note Exception Handling::.

Defining Words
==============

   `:', `create', and `variable' are definition words: They define
other words.  `Constant' is another definition word:

     5 constant foo
     foo .

   You can also use the prefixes `2' (double-cell) and `f' (floating
point) with `variable' and `constant'.

   You can also define your own defining words.  E.g.:

     : variable ( "name" -- )
       create 0 , ;

   You can also define defining words that create words that do
something other than just producing their address:

     : constant ( n "name" -- )
       create ,
     does> ( -- n )
       ( addr ) @ ;
     
     5 constant foo
     foo .

   The definition of `constant' above ends at the `does>'; i.e.,
`does>' replaces `;', but it also does something else: It changes the
last defined word such that it pushes the address of the body of the
word and then performs the code after the `does>' whenever it is called.

   In the example above, `constant' uses `,' to store 5 into the body
of `foo'.  When `foo' executes, it pushes the address of the body onto
the stack, then (in the code after the `does>') fetches the 5 from
there.

   The stack comment near the `does>' reflects the stack effect of the
defined word, not the stack effect of the code after the `does>' (the
difference is that the code expects the address of the body that the
stack comment does not show).

   You can use these definition words to do factoring in cases that
involve (other) definition words.  E.g., a field offset is always added
to an address.  Instead of defining

     2 cells constant offset-field1

   and using this like

     ( addr ) offset-field1 +

   you can define a definition word

     : simple-field ( n "name" -- )
       create ,
     does> ( n1 -- n1+n )
       ( addr ) @ + ;

   Definition and use of field offsets now look like this:

     2 cells simple-field field1
     create mystruct 4 cells allot
     mystruct .s field1 .s drop

   If you want to do something with the word without performing the code
after the `does>', you can access the body of a `create'd word with
`>body ( xt -- addr )':

     : value ( n "name" -- )
       create ,
     does> ( -- n1 )
       @ ;
     : to ( n "name" -- )
       ' >body ! ;
     
     5 value foo
     foo .
     7 to foo
     foo .

Assignment:
     Define `defer ( "name" -- )', which creates a word that stores an
     XT (at the start the XT of `abort'), and upon execution `execute's
     the XT.  Define `is ( xt "name" -- )' that stores `xt' into
     `name', a word defined with `defer'.  Indirect recursion is one
     application of `defer'.

   Reference: *Note User-defined Defining Words::.

Arrays and Records
==================

   Forth has no standard words for defining data structures such as
arrays and records (structs in C terminology), but you can build them
yourself based on address arithmetic.  You can also define words for
defining arrays and records (*note Defining Words: Defining Words
Tutorial.).

   One of the first projects a Forth newcomer sets out upon when
learning about defining words is an array defining word (possibly for
n-dimensional arrays).  Go ahead and do it, I did it, too; you will
learn something from it.  However, don't be disappointed when you later
learn that you have little use for these words (inappropriate use would
be even worse).  I have not yet found a set of useful array words yet;
the needs are just too diverse, and named, global arrays (the result of
naive use of defining words) are often not flexible enough (e.g.,
consider how to pass them as parameters).  Another such project is a set
of words to help dealing with strings.

   On the other hand, there is a useful set of record words, and it has
been defined in `compat/struct.fs'; these words are predefined in
Gforth.  They are explained in depth elsewhere in this manual (see
*note Structures::).  The `simple-field' example above is simplified
variant of fields in this package.

`POSTPONE'
==========

   You can compile the compilation semantics (instead of compiling the
interpretation semantics) of a word with `POSTPONE':

     : MY-+ ( Compilation: -- ; Run-time of compiled code: n1 n2 -- n )
      POSTPONE + ; immediate
     : foo ( n1 n2 -- n )
      MY-+ ;
     1 2 foo .
     see foo

   During the definition of `foo' the text interpreter performs the
compilation semantics of `MY-+', which performs the compilation
semantics of `+', i.e., it compiles `+' into `foo'.

   This example also displays separate stack comments for the
compilation semantics and for the stack effect of the compiled code.
For words with default compilation semantics these stack effects are
usually not displayed; the stack effect of the compilation semantics is
always `( -- )' for these words, the stack effect for the compiled code
is the stack effect of the interpretation semantics.

   Note that the state of the interpreter does not come into play when
performing the compilation semantics in this way.  You can also perform
it interpretively, e.g.:

     : foo2 ( n1 n2 -- n )
      [ MY-+ ] ;
     1 2 foo .
     see foo

   However, there are some broken Forth systems where this does not
always work, and therefore this practice was been declared non-standard
in 1999.

   Here is another example for using `POSTPONE':

     : MY-- ( Compilation: -- ; Run-time of compiled code: n1 n2 -- n )
      POSTPONE negate POSTPONE + ; immediate compile-only
     : bar ( n1 n2 -- n )
       MY-- ;
     2 1 bar .
     see bar

   You can define `ENDIF' in this way:

     : ENDIF ( Compilation: orig -- )
       POSTPONE then ; immediate

Assignment:
     Write `MY-2DUP' that has compilation semantics equivalent to
     `2dup', but compiles `over over'.

`Literal'
=========

   You cannot `POSTPONE' numbers:

     : [FOO] POSTPONE 500 ; immediate

   Instead, you can use `LITERAL (compilation: n --; run-time: -- n )':

     : [FOO] ( compilation: --; run-time: -- n )
       500 POSTPONE literal ; immediate
     
     : flip [FOO] ;
     flip .
     see flip

   `LITERAL' consumes a number at compile-time (when it's compilation
semantics are executed) and pushes it at run-time (when the code it
compiled is executed).  A frequent use of `LITERAL' is to compile a
number computed at compile time into the current word:

     : bar ( -- n )
       [ 2 2 + ] literal ;
     see bar

Assignment:
     Write `]L' which allows writing the example above as `: bar ( -- n
     ) [ 2 2 + ]L ;'

Advanced macros
===============

   Reconsider `map-array' from *Note Execution Tokens: Execution Tokens
Tutorial.  It frequently performs `execute', a relatively expensive
operation in some Forth implementations.  You can use `compile,' and
`POSTPONE' to eliminate these `execute's and produce a word that
contains the word to be performed directly:

     : compile-map-array ( compilation: xt -- ; run-time: ... addr u -- ... )
     \ at run-time, execute xt ( ... x -- ... ) for each element of the
     \ array beginning at addr and containing u elements
       { xt }
       POSTPONE cells POSTPONE over POSTPONE + POSTPONE swap POSTPONE ?do
         POSTPONE i POSTPONE @ xt compile,
       1 cells POSTPONE literal POSTPONE +loop ;
     
     : sum-array ( addr u -- n )
      0 rot rot [ ' + compile-map-array ] ;
     see sum-array
     a 5 sum-array .

   You can use the full power of Forth for generating the code; here's
an example where the code is generated in a loop:

     : compile-vmul-step ( compilation: n --; run-time: n1 addr1 -- n2 addr2 )
     \ n2=n1+(addr1)*n, addr2=addr1+cell
       POSTPONE tuck POSTPONE @
       POSTPONE literal POSTPONE * POSTPONE +
       POSTPONE swap POSTPONE cell+ ;
     
     : compile-vmul ( compilation: addr1 u -- ; run-time: addr2 -- n )
     \ n=v1*v2 (inner product), where the v_i are represented as addr_i u
       0 postpone literal postpone swap
       [ ' compile-vmul-step compile-map-array ]
       postpone drop ;
     see compile-vmul
     
     : a-vmul ( addr -- n )
     \ n=a*v, where v is a vector that's as long as a and starts at addr
      [ a 5 compile-vmul ] ;
     see a-vmul
     a a-vmul .

   This example uses `compile-map-array' to show off, but you could
also use `map-array' instead (try it now!).

   You can use this technique for efficient multiplication of large
matrices.  In matrix multiplication, you multiply every line of one
matrix with every column of the other matrix.  You can generate the code
for one line once, and use it for every column.  The only downside of
this technique is that it is cumbersome to recover the memory consumed
by the generated code when you are done (and in more complicated cases
it is not possible portably).

Compilation Tokens
==================

   This section is Gforth-specific.  You can skip it.

   `' word compile,' compiles the interpretation semantics.  For words
with default compilation semantics this is the same as performing the
compilation semantics.  To represent the compilation semantics of other
words (e.g., words like `if' that have no interpretation semantics),
Gforth has the concept of a compilation token (CT, consisting of two
cells), and words `comp'' and `[comp']'.  You can perform the
compilation semantics represented by a CT with `execute':

     : foo2 ( n1 n2 -- n )
        [ comp' + execute ] ;
     see foo

   You can compile the compilation semantics represented by a CT with
`postpone,':

     : foo3 ( -- )
       [ comp' + postpone, ] ;
     see foo3

   `[ comp' word postpone, ]' is equivalent to `POSTPONE word'.
`comp'' is particularly useful for words that have no interpretation
semantics:

     ' if
     comp' if .s 2drop

   Reference: *Note Tokens for Words::.

Wordlists and Search Order
==========================

   The dictionary is not just a memory area that allows you to allocate
memory with `allot', it also contains the Forth words, arranged in
several wordlists.  When searching for a word in a wordlist,
conceptually you start searching at the youngest and proceed towards
older words (in reality most systems nowadays use hash-tables); i.e., if
you define a word with the same name as an older word, the new word
shadows the older word.

   Which wordlists are searched in which order is determined by the
search order.  You can display the search order with `order'.  It
displays first the search order, starting with the wordlist searched
first, then it displays the wordlist that will contain newly defined
words.

   You can create a new, empty wordlist with `wordlist ( -- wid )':

     wordlist constant mywords

   `Set-current ( wid -- )' sets the wordlist that will contain newly
defined words (the _current_ wordlist):

     mywords set-current
     order

   Gforth does not display a name for the wordlist in `mywords' because
this wordlist was created anonymously with `wordlist'.

   You can get the current wordlist with `get-current ( -- wid)'.  If
you want to put something into a specific wordlist without overall
effect on the current wordlist, this typically looks like this:

     get-current mywords set-current ( wid )
     create someword
     ( wid ) set-current

   You can write the search order with `set-order ( wid1 .. widn n --
)' and read it with `get-order ( -- wid1 .. widn n )'.  The first
searched wordlist is topmost.

     get-order mywords swap 1+ set-order
     order

   Yes, the order of wordlists in the output of `order' is reversed
from stack comments and the output of `.s' and thus unintuitive.

Assignment:
     Define `>order ( wid -- )' with adds `wid' as first searched
     wordlist to the search order.  Define `previous ( -- )', which
     removes the first searched wordlist from the search order.
     Experiment with boundary conditions (you will see some crashes or
     situations that are hard or impossible to leave).

   The search order is a powerful foundation for providing features
similar to Modula-2 modules and C++ namespaces.  However, trying to
modularize programs in this way has disadvantages for debugging and
reuse/factoring that overcome the advantages in my experience (I don't
do huge projects, though).  These disadvantages are not so clear in
other languages/programming environments, because these languages are
not so strong in debugging and reuse.

   Reference: *Note Word Lists::.

An Introduction to ANS Forth
****************************

   The difference of this chapter from the Tutorial (*note Tutorial::)
is that it is slower-paced in its examples, but uses them to dive deep
into explaining Forth internals (not covered by the Tutorial).  Apart
from that, this chapter covers far less material.  It is suitable for
reading without using a computer.

   The primary purpose of this manual is to document Gforth. However,
since Forth is not a widely-known language and there is a lack of
up-to-date teaching material, it seems worthwhile to provide some
introductory material.  For other sources of Forth-related information,
see *Note Forth-related information::.

   The examples in this section should work on any ANS Forth; the
output shown was produced using Gforth. Each example attempts to
reproduce the exact output that Gforth produces. If you try out the
examples (and you should), what you should type is shown `like this'
and Gforth's response is shown `like this'. The single exception is
that, where the example shows <RET> it means that you should press the
"carriage return" key. Unfortunately, some output formats for this
manual cannot show the difference between `this' and `this' which will
make trying out the examples harder (but not impossible).

   Forth is an unusual language. It provides an interactive development
environment which includes both an interpreter and compiler. Forth
programming style encourages you to break a problem down into many
small fragments ("factoring"), and then to develop and test each
fragment interactively. Forth advocates assert that breaking the
edit-compile-test cycle used by conventional programming languages can
lead to great productivity improvements.

Introducing the Text Interpreter
================================

   When you invoke the Forth image, you will see a startup banner
printed and nothing else (if you have Gforth installed on your system,
try invoking it now, by typing `gforth<RET>'). Forth is now running its
command line interpreter, which is called the "Text Interpreter" (also
known as the "Outer Interpreter").  (You will learn a lot about the
text interpreter as you read through this chapter, for more detail
*note The Text Interpreter::).

   Although it's not obvious, Forth is actually waiting for your input.
Type a number and press the <RET> key:

     45<RET>  ok

   Rather than give you a prompt to invite you to input something, the
text interpreter prints a status message after it has processed a line
of input. The status message in this case ("` ok'" followed by
carriage-return) indicates that the text interpreter was able to process
all of your input successfully. Now type something illegal:

     qwer341<RET>
     :1: Undefined word
     qwer341
     ^^^^^^^
     $400D2BA8 Bounce
     $400DBDA8 no.extensions

   The exact text, other than the "Undefined word" may differ slightly
on your system, but the effect is the same; when the text interpreter
detects an error, it discards any remaining text on a line, resets
certain internal state and prints an error message. For a detailed
description of error messages see *Note Error messages::.

   The text interpreter waits for you to press carriage-return, and then
processes your input line. Starting at the beginning of the line, it
breaks the line into groups of characters separated by spaces. For each
group of characters in turn, it makes two attempts to do something:

   * It tries to treat it as a command. It does this by searching a
     "name dictionary". If the group of characters matches an entry in
     the name dictionary, the name dictionary provides the text
     interpreter with information that allows the text interpreter
     perform some actions. In Forth jargon, we say that the group of
     characters names a "word", that the dictionary search returns an
     "execution token (xt)" corresponding to the "definition" of the
     word, and that the text interpreter executes the xt. Often, the
     terms "word" and "definition" are used interchangeably.

   * If the text interpreter fails to find a match in the name
     dictionary, it tries to treat the group of characters as a number
     in the current number base (when you start up Forth, the current
     number base is base 10). If the group of characters legitimately
     represents a number, the text interpreter pushes the number onto a
     stack (we'll learn more about that in the next section).

   If the text interpreter is unable to do either of these things with
any group of characters, it discards the group of characters and the
rest of the line, then prints an error message. If the text interpreter
reaches the end of the line without error, it prints the status message
"` ok'" followed by carriage-return.

   This is the simplest command we can give to the text interpreter:

     <RET>  ok

   The text interpreter did everything we asked it to do (nothing)
without an error, so it said that everything is "` ok'". Try a slightly
longer command:

     12 dup fred dup<RET>
     :1: Undefined word
     12 dup fred dup
            ^^^^
     $400D2BA8 Bounce
     $400DBDA8 no.extensions

   When you press the carriage-return key, the text interpreter starts
to work its way along the line:

   * When it gets to the space after the `2', it takes the group of
     characters `12' and looks them up in the name dictionary(1). There
     is no match for this group of characters in the name dictionary,
     so it tries to treat them as a number. It is able to do this
     successfully, so it puts the number, 12, "on the stack" (whatever
     that means).

   * The text interpreter resumes scanning the line and gets the next
     group of characters, `dup'. It looks it up in the name dictionary
     and (you'll have to take my word for this) finds it, and executes
     the word `dup' (whatever that means).

   * Once again, the text interpreter resumes scanning the line and
     gets the group of characters `fred'. It looks them up in the name
     dictionary, but can't find them. It tries to treat them as a
     number, but they don't represent any legal number.

   At this point, the text interpreter gives up and prints an error
message. The error message shows exactly how far the text interpreter
got in processing the line. In particular, it shows that the text
interpreter made no attempt to do anything with the final character
group, `dup', even though we have good reason to believe that the text
interpreter would have no problem looking that word up and executing it
a second time.

   ---------- Footnotes ----------

   (1) We can't tell if it found them or not, but assume for now that
it did not

Stacks, postfix notation and parameter passing
==============================================

   In procedural programming languages (like C and Pascal), the
building-block of programs is the "function" or "procedure". These
functions or procedures are called with "explicit parameters". For
example, in C we might write:

     total = total + new_volume(length,height,depth);

where new_volume is a function-call to another piece of code, and total,
length, height and depth are all variables. length, height and depth are
parameters to the function-call.

   In Forth, the equivalent of the function or procedure is the
"definition" and parameters are implicitly passed between definitions
using a shared stack that is visible to the programmer. Although Forth
does support variables, the existence of the stack means that they are
used far less often than in most other programming languages. When the
text interpreter encounters a number, it will place ("push") it on the
stack. There are several stacks (the actual number is
implementation-dependent ...) and the particular stack used for any
operation is implied unambiguously by the operation being performed.
The stack used for all integer operations is called the "data stack"
and, since this is the stack used most commonly, references to "the
data stack" are often abbreviated to "the stack".

   The stacks have a last-in, first-out (LIFO) organisation. If you
type:

     1 2 3<RET>  ok

   Then this instructs the text interpreter to placed three numbers on
the (data) stack. An analogy for the behaviour of the stack is to take a
pack of playing cards and deal out the ace (1), 2 and 3 into a pile on
the table. The 3 was the last card onto the pile ("last-in") and if you
take a card off the pile then, unless you're prepared to fiddle a bit,
the card that you take off will be the 3 ("first-out"). The number that
will be first-out of the stack is called the "top of stack", which is
often abbreviated to "TOS".

   To understand how parameters are passed in Forth, consider the
behaviour of the definition `+' (pronounced "plus"). You will not be
surprised to learn that this definition performs addition. More
precisely, it adds two number together and produces a result. Where does
it get the two numbers from? It takes the top two numbers off the
stack. Where does it place the result? On the stack. You can act-out the
behaviour of `+' with your playing cards like this:

   * Pick up two cards from the stack on the table

   * Stare at them intently and ask yourself "what is the sum of these
     two numbers"

   * Decide that the answer is 5

   * Shuffle the two cards back into the pack and find a 5

   * Put a 5 on the remaining ace that's on the table.

   If you don't have a pack of cards handy but you do have Forth
running, you can use the definition `.s' to show the current state of
the stack, without affecting the stack. Type:

     clearstack 1 2 3<RET> ok
     .s<RET> <3> 1 2 3  ok

   The text interpreter looks up the word `clearstack' and executes it;
it tidies up the stack and removes any entries that may have been left
on it by earlier examples. The text interpreter pushes each of the
three numbers in turn onto the stack. Finally, the text interpreter
looks up the word `.s' and executes it. The effect of executing `.s' is
to print the "<3>" (the total number of items on the stack) followed by
a list of all the items on the stack; the item on the far right-hand
side is the TOS.

   You can now type:

     + .s<RET> <2> 1 5  ok

which is correct; there are now 2 items on the stack and the result of
the addition is 5.

   If you're playing with cards, try doing a second addition: pick up
the two cards, work out that their sum is 6, shuffle them into the pack,
look for a 6 and place that on the table. You now have just one item on
the stack. What happens if you try to do a third addition? Pick up the
first card, pick up the second card - ah! There is no second card. This
is called a "stack underflow" and consitutes an error. If you try to do
the same thing with Forth it will report an error (probably a Stack
Underflow or an Invalid Memory Address error).

   The opposite situation to a stack underflow is a "stack overflow",
which simply accepts that there is a finite amount of storage space
reserved for the stack. To stretch the playing card analogy, if you had
enough packs of cards and you piled the cards up on the table, you would
eventually be unable to add another card; you'd hit the ceiling. Gforth
allows you to set the maximum size of the stacks. In general, the only
time that you will get a stack overflow is because a definition has a
bug in it and is generating data on the stack uncontrollably.

   There's one final use for the playing card analogy. If you model your
stack using a pack of playing cards, the maximum number of items on
your stack will be 52 (I assume you didn't use the Joker). The maximum
value of any item on the stack is 13 (the King). In fact, the only
possible numbers are positive integer numbers 1 through 13; you can't
have (for example) 0 or 27 or 3.52 or -2. If you change the way you
think about some of the cards, you can accommodate different numbers.
For example, you could think of the Jack as representing 0, the Queen
as representing -1 and the King as representing -2. Your range remains
unchanged (you can still only represent a total of 13 numbers) but the
numbers that you can represent are -2 through 10.

   In that analogy, the limit was the amount of information that a
single stack entry could hold, and Forth has a similar limit. In Forth,
the size of a stack entry is called a "cell". The actual size of a cell
is implementation dependent and affects the maximum value that a stack
entry can hold. A Standard Forth provides a cell size of at least
16-bits, and most desktop systems use a cell size of 32-bits.

   Forth does not do any type checking for you, so you are free to
manipulate and combine stack items in any way you wish. A convenient way
of treating stack items is as 2's complement signed integers, and that
is what Standard words like `+' do. Therefore you can type:

     -5 12 + .s<RET> <1> 7  ok

   If you use numbers and definitions like `+' in order to turn Forth
into a great big pocket calculator, you will realise that it's rather
different from a normal calculator. Rather than typing 2 + 3 = you had
to type 2 3 + (ignore the fact that you had to use `.s' to see the
result). The terminology used to describe this difference is to say that
your calculator uses "Infix Notation" (parameters and operators are
mixed) whilst Forth uses "Postfix Notation" (parameters and operators
are separate), also called "Reverse Polish Notation".

   Whilst postfix notation might look confusing to begin with, it has
several important advantages:

   * it is unambiguous

   * it is more concise

   * it fits naturally with a stack-based system

   To examine these claims in more detail, consider these sums:

     6 + 5 * 4 =
     4 * 5 + 6 =

   If you're just learning maths or your maths is very rusty, you will
probably come up with the answer 44 for the first and 26 for the
second. If you are a bit of a whizz at maths you will remember the
convention that multiplication takes precendence over addition, and
you'd come up with the answer 26 both times. To explain the answer 26
to someone who got the answer 44, you'd probably rewrite the first sum
like this:

     6 + (5 * 4) =

   If what you really wanted was to perform the addition before the
multiplication, you would have to use parentheses to force it.

   If you did the first two sums on a pocket calculator you would
probably get the right answers, unless you were very cautious and
entered them using these keystroke sequences:

   6 + 5 = * 4 = 4 * 5 = + 6 =

   Postfix notation is unambiguous because the order that the operators
are applied is always explicit; that also means that parentheses are
never required. The operators are active (the act of quoting the
operator makes the operation occur) which removes the need for "=".

   The sum 6 + 5 * 4 can be written (in postfix notation) in two
equivalent ways:

     6 5 4 * +      or:
     5 4 * 6 +

   An important thing that you should notice about this notation is that
the order of the numbers does not change; if you want to subtract 2
from 10 you type `10 2 -'.

   The reason that Forth uses postfix notation is very simple to
explain: it makes the implementation extremely simple, and it follows
naturally from using the stack as a mechanism for passing parameters.
Another way of thinking about this is to realise that all Forth
definitions are active; they execute as they are encountered by the text
interpreter. The result of this is that the syntax of Forth is trivially
simple.

Your first Forth definition
===========================

   Until now, the examples we've seen have been trivial; we've just been
using Forth as a bigger-than-pocket calculator. Also, each calculation
we've shown has been a "one-off" - to repeat it we'd need to type it in
again(1) In this section we'll see how to add new words to Forth's
vocabulary.

   The easiest way to create a new word is to use a "colon definition".
We'll define a few and try them out before worrying too much about how
they work. Try typing in these examples; be careful to copy the spaces
accurately:

     : add-two 2 + . ;
     : greet ." Hello and welcome" ;
     : demo 5 add-two ;

Now try them out:

     greet<RET> Hello and welcome  ok
     greet greet<RET> Hello and welcomeHello and welcome  ok
     4 add-two<RET> 6  ok
     demo<RET> 7  ok
     9 greet demo add-two<RET> Hello and welcome7 11  ok

   The first new thing that we've introduced here is the pair of words
`:' and `;'. These are used to start and terminate a new definition,
respectively. The first word after the `:' is the name for the new
definition.

   As you can see from the examples, a definition is built up of words
that have already been defined; Forth makes no distinction between
definitions that existed when you started the system up, and those that
you define yourself.

   The examples also introduce the words `.' (dot), `."' (dot-quote)
and `dup' (dewp). Dot takes the value from the top of the stack and
displays it. It's like `.s' except that it only displays the top item
of the stack and it is destructive; after it has executed, the number
is no longer on the stack. There is always one space printed after the
number, and no spaces before it. Dot-quote defines a string (a sequence
of characters) that will be printed when the word is executed. The
string can contain any printable characters except `"'. A `"' has a
special function; it is not a Forth word but it acts as a delimiter
(the way that delimiters work is described in the next section).
Finally, `dup' duplicates the value at the top of the stack. Try typing
`5 dup .s' to see what it does.

   We already know that the text interpreter searches through the
dictionary to locate names. If you've followed the examples earlier, you
will already have a definition called `add-two'. Lets try modifying it
by typing in a new definition:

     : add-two dup . ." + 2 =" 2 + . ;<RET> redefined add-two  ok

   Forth recognised that we were defining a word that already exists,
and printed a message to warn us of that fact. Let's try out the new
definition:

     9 add-two<RET> 9 + 2 =11  ok

All that we've actually done here, though, is to create a new
definition, with a particular name. The fact that there was already a
definition with the same name did not make any difference to the way
that the new definition was created (except that Forth printed a warning
message). The old definition of add-two still exists (try `demo' again
to see that this is true). Any new definition will use the new
definition of `add-two', but old definitions continue to use the
version that already existed at the time that they were `compiled'.

   Before you go on to the next section, try defining and redefining
some words of your own.

   ---------- Footnotes ----------

   (1) That's not quite true. If you press the up-arrow key on your
keyboard you should be able to scroll back to any earlier command, edit
it and re-enter it.

How does that work?
===================

   Now we're going to take another look at the definition of `add-two'
from the previous section. From our knowledge of the way that the text
interpreter works, we would have expected this result when we tried to
define `add-two':

     : add-two 2 + . ;<RET>
       ^^^^^^^
     Error: Undefined word

   The reason that this didn't happen is bound up in the way that `:'
works. The word `:' does two special things. The first special thing
that it does prevents the text interpreter from ever seeing the
characters `add-two'. The text interpreter uses a variable called `>IN'
(pronounced "to-in") to keep track of where it is in the input line.
When it encounters the word `:' it behaves in exactly the same way as
it does for any other word; it looks it up in the name dictionary,
finds its xt and executes it. When `:' executes, it looks at the input
buffer, finds the word `add-two' and advances the value of `>IN' to
point past it. It then does some other stuff associated with creating
the new definition (including creating an entry for `add-two' in the
name dictionary). When the execution of `:' completes, control returns
to the text interpreter, which is oblivious to the fact that it has
been tricked into ignoring part of the input line.

   Words like `:' - words that advance the value of `>IN' and so
prevent the text interpreter from acting on the whole of the input line
- are called "parsing words".

   The second special thing that `:' does is change the value of a
variable called `state', which affects the way that the text
interpreter behaves. When Gforth starts up, `state' has the value 0,
and the text interpreter is said to be "interpreting". During a colon
definition (started with `:'), `state' is set to -1 and the text
interpreter is said to be "compiling".

   In this example, the text interpreter is compiling when it processes
the string "`2 + . ;'". It still breaks the string down into character
sequences in the same way. However, instead of pushing the number `2'
onto the stack, it lays down ("compiles") some magic into the
definition of `add-two' that will make the number `2' get pushed onto
the stack when `add-two' is "executed". Similarly, the behaviours of
`+' and `.' are also compiled into the definition.

   One category of words don't get compiled. These so-called "immediate
words" get executed (performed now) regardless of whether the text
interpreter is interpreting or compiling. The word `;' is an immediate
word. Rather than being compiled into the definition, it executes. Its
effect is to terminate the current definition, which includes changing
the value of `state' back to 0.

   When you execute `add-two', it has a "run-time effect" that is
exactly the same as if you had typed `2 + . <RET>' outside of a
definition.

   In Forth, every word or number can be described in terms of two
properties:

   * Its "interpretation semantics" describe how it will behave when the
     text interpreter encounters it in "interpret" state. The
     interpretation semantics of a word are represented by an "execution
     token".

   * Its "compilation semantics" describe how it will behave when the
     text interpreter encounters it in "compile" state. The compilation
     semantics of a word are represented in an implementation-dependent
     way; Gforth uses a "compilation token".

Numbers are always treated in a fixed way:

   * When the number is "interpreted", its behaviour is to push the
     number onto the stack.

   * When the number is "compiled", a piece of code is appended to the
     current definition that pushes the number when it runs. (In other
     words, the compilation semantics of a number are to postpone its
     interpretation semantics until the run-time of the definition that
     it is being compiled into.)

   Words don't behave in such a regular way, but most have default
semantics which means that they behave like this:

   * The "interpretation semantics" of the word are to do something
     useful.

   * The "compilation semantics" of the word are to append its
     "interpretation semantics" to the current definition (so that its
     run-time behaviour is to do something useful).

   The actual behaviour of any particular word can be controlled by
using the words `immediate' and `compile-only' when the word is
defined. These words set flags in the name dictionary entry of the most
recently defined word, and these flags are retrieved by the text
interpreter when it finds the word in the name dictionary.

   A word that is marked as "immediate" has compilation semantics that
are identical to its interpretation semantics. In other words, it
behaves like this:

   * The "interpretation semantics" of the word are to do something
     useful.

   * The "compilation semantics" of the word are to do something useful
     (and actually the same thing); i.e., it is executed during
     compilation.

   Marking a word as "compile-only" prohibits the text interpreter from
performing the interpretation semantics of the word directly; an attempt
to do so will generate an error. It is never necessary to use
`compile-only' (and it is not even part of ANS Forth, though it is
provided by many implementations) but it is good etiquette to apply it
to a word that will not behave correctly (and might have unexpected
side-effects) in interpret state. For example, it is only legal to use
the conditional word `IF' within a definition. If you forget this and
try to use it elsewhere, the fact that (in Gforth) it is marked as
`compile-only' allows the text interpreter to generate a helpful error
message rather than subjecting you to the consequences of your folly.

   This example shows the difference between an immediate and a
non-immediate word:

     : show-state state @ . ;
     : show-state-now show-state ; immediate
     : word1 show-state ;
     : word2 show-state-now ;

   The word `immediate' after the definition of `show-state-now' makes
that word an immediate word. These definitions introduce a new word:
`@' (pronounced "fetch"). This word fetches the value of a variable,
and leaves it on the stack. Therefore, the behaviour of `show-state' is
to print a number that represents the current value of `state'.

   When you execute `word1', it prints the number 0, indicating that
the system is interpreting. When the text interpreter compiled the
definition of `word1', it encountered `show-state' whose compilation
semantics are to append its interpretation semantics to the current
definition. When you execute `word1', it performs the interpretation
semantics of `show-state'.  At the time that `word1' (and therefore
`show-state') are executed, the system is interpreting.

   When you pressed <RET> after entering the definition of `word2', you
should have seen the number -1 printed, followed by "` ok'". When the
text interpreter compiled the definition of `word2', it encountered
`show-state-now', an immediate word, whose compilation semantics are
therefore to perform its interpretation semantics. It is executed
straight away (even before the text interpreter has moved on to process
another group of characters; the `;' in this example). The effect of
executing it are to display the value of `state' at the time that the
definition of `word2' is being defined. Printing -1 demonstrates that
the system is compiling at this time. If you execute `word2' it does
nothing at all.

   Before leaving the subject of immediate words, consider the
behaviour of `."' in the definition of `greet', in the previous
section. This word is both a parsing word and an immediate word. Notice
that there is a space between `."' and the start of the text `Hello and
welcome', but that there is no space between the last letter of
`welcome' and the `"' character. The reason for this is that `."' is a
Forth word; it must have a space after it so that the text interpreter
can identify it. The `"' is not a Forth word; it is a "delimiter". The
examples earlier show that, when the string is displayed, there is
neither a space before the `H' nor after the `e'. Since `."' is an
immediate word, it executes at the time that `greet' is defined. When
it executes, its behaviour is to search forward in the input line
looking for the delimiter. When it finds the delimiter, it updates
`>IN' to point past the delimiter. It also compiles some magic code
into the definition of `greet'; the xt of a run-time routine that
prints a text string. It compiles the string `Hello and welcome' into
memory so that it is available to be printed later. When the text
interpreter gains control, the next word it finds in the input stream
is `;' and so it terminates the definition of `greet'.

Forth is written in Forth
=========================

   When you start up a Forth compiler, a large number of definitions
already exist. In Forth, you develop a new application using bottom-up
programming techniques to create new definitions that are defined in
terms of existing definitions. As you create each definition you can
test and debug it interactively.

   If you have tried out the examples in this section, you will probably
have typed them in by hand; when you leave Gforth, your definitions will
be lost. You can avoid this by using a text editor to enter Forth source
code into a file, and then loading code from the file using `include'
(*note Forth source files::). A Forth source file is processed by the
text interpreter, just as though you had typed it in by hand(1).

   Gforth also supports the traditional Forth alternative to using text
files for program entry (*note Blocks::).

   In common with many, if not most, Forth compilers, most of Gforth is
actually written in Forth. All of the `.fs' files in the installation
directory(2) are Forth source files, which you can study to see
examples of Forth programming.

   Gforth maintains a history file that records every line that you
type to the text interpreter. This file is preserved between sessions,
and is used to provide a command-line recall facility. If you enter long
definitions by hand, you can use a text editor to paste them out of the
history file into a Forth source file for reuse at a later time (for
more information *note Command-line editing::).

   ---------- Footnotes ----------

   (1) Actually, there are some subtle differences - see *Note The Text
Interpreter::.

   (2) For example, `/usr/local/share/gforth...'

Review - elements of a Forth system
===================================

   To summarise this chapter:

   * Forth programs use "factoring" to break a problem down into small
     fragments called "words" or "definitions".

   * Forth program development is an interactive process.

   * The main command loop that accepts input, and controls both
     interpretation and compilation, is called the "text interpreter"
     (also known as the "outer interpreter").

   * Forth has a very simple syntax, consisting of words and numbers
     separated by spaces or carriage-return characters. Any additional
     syntax is imposed by "parsing words".

   * Forth uses a stack to pass parameters between words. As a result,
     it uses postfix notation.

   * To use a word that has previously been defined, the text
     interpreter searches for the word in the "name dictionary".

   * Words have "interpretation semantics" and "compilation semantics".

   * The text interpreter uses the value of `state' to select between
     the use of the "interpretation semantics" and the  "compilation
     semantics" of a word that it encounters.

   * The relationship between the "interpretation semantics" and
     "compilation semantics" for a word depend upon the way in which
     the word was defined (for example, whether it is an "immediate"
     word).

   * Forth definitions can be implemented in Forth (called "high-level
     definitions") or in some other way (usually a lower-level language
     and as a result often called "low-level definitions", "code
     definitions" or "primitives").

   * Many Forth systems are implemented mainly in Forth.

Where To Go Next
================

   Amazing as it may seem, if you have read (and understood) this far,
you know almost all the fundamentals about the inner workings of a Forth
system. You certainly know enough to be able to read and understand the
rest of this manual and the ANS Forth document, to learn more about the
facilities that Forth in general and Gforth in particular provide. Even
scarier, you know almost enough to implement your own Forth system.
However, that's not a good idea just yet... better to try writing some
programs in Gforth.

   Forth has such a rich vocabulary that it can be hard to know where to
start in learning it. This section suggests a few sets of words that are
enough to write small but useful programs. Use the word index in this
document to learn more about each word, then try it out and try to write
small definitions using it. Start by experimenting with these words:

   * Arithmetic: `+ - * / /MOD */ ABS INVERT'

   * Comparison: `MIN MAX ='

   * Logic: `AND OR XOR NOT'

   * Stack manipulation: `DUP DROP SWAP OVER'

   * Loops and decisions: `IF ELSE ENDIF ?DO I LOOP'

   * Input/Output: `. ." EMIT CR KEY'

   * Defining words: `: ; CREATE'

   * Memory allocation words: `ALLOT ,'

   * Tools: `SEE WORDS .S MARKER'

   When you have mastered those, go on to:

   * More defining words: `VARIABLE CONSTANT VALUE TO CREATE DOES>'

   * Memory access: `@ !'

   When you have mastered these, there's nothing for it but to read
through the whole of this manual and find out what you've missed.

Exercises
=========

   TODO: provide a set of programming excercises linked into the stuff
done already and into other sections of the manual. Provide solutions
to all the exercises in a .fs file in the distribution.

Forth Words
***********

Notation
========

   The Forth words are described in this section in the glossary
notation that has become a de-facto standard for Forth texts:

word     Stack effect   wordset   pronunciation
   Description

WORD
     The name of the word.

STACK EFFECT
     The stack effect is written in the notation `before -- after',
     where before and after describe the top of stack entries before
     and after the execution of the word. The rest of the stack is not
     touched by the word. The top of stack is rightmost, i.e., a stack
     sequence is written as it is typed in. Note that Gforth uses a
     separate floating point stack, but a unified stack notation. Also,
     return stack effects are not shown in stack effect, but in
     Description. The name of a stack item describes the type and/or
     the function of the item. See below for a discussion of the types.

     All words have two stack effects: A compile-time stack effect and a
     run-time stack effect. The compile-time stack-effect of most words
     is  - . If the compile-time stack-effect of a word deviates from
     this standard behaviour, or the word does other unusual things at
     compile time, both stack effects are shown; otherwise only the
     run-time stack effect is shown.

PRONUNCIATION
     How the word is pronounced.

WORDSET
     The ANS Forth standard is divided into several word sets. A
     standard system need not support all of them. Therefore, in
     theory, the fewer word sets your program uses the more portable it
     will be. However, we suspect that most ANS Forth systems on
     personal machines will feature all word sets. Words that are not
     defined in ANS Forth have `gforth' or `gforth-internal' as word
     set. `gforth' describes words that will work in future releases of
     Gforth; `gforth-internal' words are more volatile. Environmental
     query strings are also displayed like words; you can recognize
     them by the `environment' in the word set field.

DESCRIPTION
     A description of the behaviour of the word.

   The type of a stack item is specified by the character(s) the name
starts with:

`f'
     Boolean flags, i.e. `false' or `true'.

`c'
     Char

`w'
     Cell, can contain an integer or an address

`n'
     signed integer

`u'
     unsigned integer

`d'
     double sized signed integer

`ud'
     double sized unsigned integer

`r'
     Float (on the FP stack)

`a-'
     Cell-aligned address

`c-'
     Char-aligned address (note that a Char may have two bytes in
     Windows NT)

`f-'
     Float-aligned address

`df-'
     Address aligned for IEEE double precision float

`sf-'
     Address aligned for IEEE single precision float

`xt'
     Execution token, same size as Cell

`wid'
     Word list ID, same size as Cell

`ior, wior'
     I/O result code, cell-sized.  In Gforth, you can `throw' iors.

`f83name'
     Pointer to a name structure

`"'
     string in the input stream (not on the stack). The terminating
     character is a blank by default. If it is not a blank, it is shown
     in `<>' quotes.

Case insensitivity
==================

   Gforth is case-insensitive; you can enter definitions and invoke
Standard words using upper, lower or mixed case (however, *note
Implementation-defined options: core-idef.).

   ANS Forth only requires implementations to recognise Standard words
when they are typed entirely in upper case. Therefore, a Standard
program must use upper case for all Standard words. You can use whatever
case you like for words that you define, but in a Standard program you
have to use the words in the same case that you defined them.

   Gforth supports case sensitivity through `table's (case-sensitive
wordlists, *note Word Lists::).

   Two people have asked how to convert Gforth to be case-sensitive;
while we think this is a bad idea, you can change all wordlists into
tables like this:

     ' table-find forth-wordlist wordlist-map  !

   Note that you now have to type the predefined words in the same case
that we defined them, which are varying.  You may want to convert them
to your favourite case before doing this operation (I won't explain how,
because if you are even contemplating doing this, you'd better have
enough knowledge of Forth systems to know this already).

Comments
========

   Forth supports two styles of comment; the traditional in-line
comment, `(' and its modern cousin, the comment to end of line; `\'.

`('       compilation 'ccc<close-paren>' - ; run-time -         core,file       ``paren''
   Comment, usually till the next `)': parse and discard all subsequent
characters in the parse area until ")" is encountered. During
interactive input, an end-of-line also acts as a comment terminator.
For file input, it does not; if the end-of-file is encountered whilst
parsing for the ")" delimiter, Gforth will generate a warning.

`\'       compilation 'ccc<newline>' - ; run-time -         core-ext,block-ext       ``backslash''
   Comment till the end of the line if `BLK' contains 0 (i.e., while
not loading a block), parse and discard the remainder of the parse
area. Otherwise, parse and discard all subsequent characters in the
parse area corresponding to the current line.

`\G'       compilation 'ccc<newline>' - ; run-time -         gforth       ``backslash-gee''
   Equivalent to `\' but used as a tag to annotate definition comments
into documentation.

Boolean Flags
=============

   A Boolean flag is cell-sized. A cell with all bits clear represents
the flag `false' and a flag with all bits set represents the flag
`true'. Words that check a flag (for example, `IF') will treat a cell
that has any bit set as `true'.

`true'       - f         core-ext       ``true''
   `Constant' - f is a cell with all bits set.

`false'       - f         core-ext       ``false''
   `Constant' - f is a cell with all bits clear.

`on'       a-addr -         gforth       ``on''
   Set the (value of the) variable  at a-addr to `true'.

`off'       a-addr -         gforth       ``off''
   Set the (value of the) variable at a-addr to `false'.

Arithmetic
==========

   Forth arithmetic is not checked, i.e., you will not hear about
integer overflow on addition or multiplication, you may hear about
division by zero if you are lucky. The operator is written after the
operands, but the operands are still in the original order. I.e., the
infix `2-1' corresponds to `2 1 -'. Forth offers a variety of division
operators. If you perform division with potentially negative operands,
you do not want to use `/' or `/mod' with its undefined behaviour, but
rather `fm/mod' or `sm/mod' (probably the former, *note Mixed
precision::).

Single precision
----------------

   By default, numbers in Forth are single-precision integers that are
one cell in size. They can be signed or unsigned, depending upon how you
treat them. For the rules used by the text interpreter for recognising
single-precision integers see *Note Number Conversion::.

   These words are all defined for signed operands, but some of them
also work for unsigned numbers: `+', `1+', `-', `1-', `*'.

`+'       n1 n2 - n        core       ``plus''

`1+'       n1 - n2        core       ``one-plus''

`-'       n1 n2 - n        core       ``minus''

`1-'       n1 - n2        core       ``one-minus''

`*'       n1 n2 - n        core       ``star''

`/'       n1 n2 - n        core       ``slash''

`mod'       n1 n2 - n        core       ``mod''

`/mod'       n1 n2 - n3 n4        core       ``slash-mod''

`negate'       n1 - n2        core       ``negate''

`abs'       n - u        core       ``abs''

`min'       n1 n2 - n        core       ``min''

`max'       n1 n2 - n        core       ``max''

`FLOORED'       - f         environment       ``FLOORED''
   True if `/' etc. perform floored division

Double precision
----------------

   For the rules used by the text interpreter for recognising
double-precision integers, see *Note Number Conversion::.

   A double precision number is represented by a cell pair, with the
most significant cell at the TOS. It is trivial to convert an unsigned
single to a double: simply push a `0' onto the TOS. Since numbers are
represented by Gforth using 2's complement arithmetic, converting a
signed single to a (signed) double requires sign-extension across the
most significant cell. This can be achieved using `s>d'. The moral of
the story is that you cannot convert a number without knowing whether
it represents an unsigned or a signed number.

   These words are all defined for signed operands, but some of them
also work for unsigned numbers: `d+', `d-'.

`s>d'       n - d         core       ``s-to-d''

`d>s'       d - n         double       ``d-to-s''

`d+'       d1 d2 - d        double       ``d-plus''

`d-'       d1 d2 - d        double       ``d-minus''

`dnegate'       d1 - d2        double       ``d-negate''

`dabs'       d - ud         double       ``d-abs''

`dmin'       d1 d2 - d         double       ``d-min''

`dmax'       d1 d2 - d         double       ``d-max''

Bitwise operations
------------------

`and'       w1 w2 - w        core       ``and''

`or'       w1 w2 - w        core       ``or''

`xor'       w1 w2 - w        core       ``x-or''

`invert'       w1 - w2        core       ``invert''

`lshift'       u1 n - u2        core       ``l-shift''

`rshift'       u1 n - u2        core       ``r-shift''
   Logical shift right by n bits.

`2*'       n1 - n2        core       ``two-star''
   Shift left by 1; also works on unsigned numbers

`d2*'       d1 - d2        double       ``d-two-star''
   Shift left by 1; also works on unsigned numbers

`2/'       n1 - n2        core       ``two-slash''
   Arithmetic shift right by 1.  For signed numbers this is a floored
division by 2 (note that `/' not necessarily floors).

`d2/'       d1 - d2        double       ``d-two-slash''
   Arithmetic shift right by 1.  For signed numbers this is a floored
division by 2.

Numeric comparison
------------------

   Note that the words that compare for equality (`= <> 0= 0<> d= d<>
d0= d0<>') work for for both signed and unsigned numbers.

`<'       n1 n2 - f        core       ``less-than''

`<='       n1 n2 - f        gforth       ``less-or-equal''

`<>'       n1 n2 - f        core-ext       ``not-equals''

`='       n1 n2 - f        core       ``equals''

`>'       n1 n2 - f        core       ``greater-than''

`>='       n1 n2 - f        gforth       ``greater-or-equal''

`0<'       n - f        core       ``zero-less-than''

`0<='       n - f        gforth       ``zero-less-or-equal''

`0<>'       n - f        core-ext       ``zero-not-equals''

`0='       n - f        core       ``zero-equals''

`0>'       n - f        core-ext       ``zero-greater-than''

`0>='       n - f        gforth       ``zero-greater-or-equal''

`u<'       u1 u2 - f        core       ``u-less-than''

`u<='       u1 u2 - f        gforth       ``u-less-or-equal''

`u>'       u1 u2 - f        core-ext       ``u-greater-than''

`u>='       u1 u2 - f        gforth       ``u-greater-or-equal''

`within'       u1 u2 u3 - f        core-ext       ``within''
   u2=<u1<u3 or: u3=<u2 and u1 is not in [u3,u2).  This works for
unsigned and signed numbers (but not a mixture).  Another way to think
about this word is to consider the numbers as a circle (wrapping around
from `max-u' to 0 for unsigned, and from `max-n' to min-n for signed
numbers); now consider the range from u2 towards increasing numbers up
to and excluding u3 (giving an empty range if u2=u3); if u1 is in this
range, `within' returns true.

`d<'       d1 d2 - f        double       ``d-less-than''

`d<='       d1 d2 - f        gforth       ``d-less-or-equal''

`d<>'       d1 d2 - f        gforth       ``d-not-equals''

`d='       d1 d2 - f        double       ``d-equals''

`d>'       d1 d2 - f        gforth       ``d-greater-than''

`d>='       d1 d2 - f        gforth       ``d-greater-or-equal''

`d0<'       d - f        double       ``d-zero-less-than''

`d0<='       d - f        gforth       ``d-zero-less-or-equal''

`d0<>'       d - f        gforth       ``d-zero-not-equals''

`d0='       d - f        double       ``d-zero-equals''

`d0>'       d - f        gforth       ``d-zero-greater-than''

`d0>='       d - f        gforth       ``d-zero-greater-or-equal''

`du<'       ud1 ud2 - f        double-ext       ``d-u-less-than''

`du<='       ud1 ud2 - f        gforth       ``d-u-less-or-equal''

`du>'       ud1 ud2 - f        gforth       ``d-u-greater-than''

`du>='       ud1 ud2 - f        gforth       ``d-u-greater-or-equal''

Mixed precision
---------------

`m+'       d1 n - d2        double       ``m-plus''

`*/'       n1 n2 n3 - n4         core       ``star-slash''
   n4=(n1*n2)/n3, with the intermediate result being double.

`*/mod'       n1 n2 n3 - n4 n5         core       ``star-slash-mod''
   n1*n2=n3*n5+n4, with the intermediate result (n1*n2) being double.

`m*'       n1 n2 - d        core       ``m-star''

`um*'       u1 u2 - ud        core       ``u-m-star''

`m*/'       d1 n2 u3 - dquot         double       ``m-star-slash''
   dquot=(d1*n2)/u3, with the intermediate result being
triple-precision.  In ANS Forth u3 can only be a positive signed number.

`um/mod'       ud u1 - u2 u3        core       ``u-m-slash-mod''
   ud=u3*u1+u2, u1>u2>=0

`fm/mod'       d1 n1 - n2 n3        core       ``f-m-slash-mod''
   Floored division: d1 = n3*n1+n2, n1>n2>=0 or 0>=n2>n1.

`sm/rem'       d1 n1 - n2 n3        core       ``s-m-slash-rem''
   Symmetric division: d1 = n3*n1+n2, sign(n2)=sign(d1) or 0.

Floating Point
--------------

   For the rules used by the text interpreter for recognising
floating-point numbers see *Note Number Conversion::.

   Gforth has a separate floating point stack, but the documentation
uses the unified notation.(1)

   Floating point numbers have a number of unpleasant surprises for the
unwary (e.g., floating point addition is not associative) and even a few
for the wary. You should not use them unless you know what you are doing
or you don't care that the results you get are totally bogus. If you
want to learn about the problems of floating point numbers (and how to
avoid them), you might start with `David Goldberg, What Every Computer
Scientist Should Know About Floating-Point Arithmetic
(http://www.validgh.com/goldberg/paper.ps), ACM Computing Surveys
23(1):5-48, March 1991'.

`d>f'       d - r        float       ``d-to-f''

`f>d'       r - d        float       ``f-to-d''

`f+'       r1 r2 - r3        float       ``f-plus''

`f-'       r1 r2 - r3        float       ``f-minus''

`f*'       r1 r2 - r3        float       ``f-star''

`f/'       r1 r2 - r3        float       ``f-slash''

`fnegate'       r1 - r2        float       ``f-negate''

`fabs'       r1 - r2        float-ext       ``f-abs''

`fmax'       r1 r2 - r3        float       ``f-max''

`fmin'       r1 r2 - r3        float       ``f-min''

`floor'       r1 - r2        float       ``floor''
   Round towards the next smaller integral value, i.e., round toward
negative infinity.

`fround'       r1 - r2        float       ``f-round''
   Round to the nearest integral value.

`f**'       r1 r2 - r3        float-ext       ``f-star-star''
   r3 is r1 raised to the r2th power.

`fsqrt'       r1 - r2        float-ext       ``f-square-root''

`fexp'       r1 - r2        float-ext       ``f-e-x-p''

`fexpm1'       r1 - r2        float-ext       ``f-e-x-p-m-one''
   r2=e**r1-1

`fln'       r1 - r2        float-ext       ``f-l-n''

`flnp1'       r1 - r2        float-ext       ``f-l-n-p-one''
   r2=ln(r1+1)

`flog'       r1 - r2        float-ext       ``f-log''
   The decimal logarithm.

`falog'       r1 - r2        float-ext       ``f-a-log''
   r2=10**r1

`f2*'       r1 - r2         gforth       ``f2*''
   Multiply r1 by 2.0e0

`f2/'       r1 - r2         gforth       ``f2/''
   Multiply r1 by 0.5e0

`1/f'       r1 - r2         gforth       ``1/f''
   Divide 1.0e0 by r1.

`precision'       - u         float-ext       ``precision''
   u is the number of significant digits currently used by `F.' `FE.'
and `FS.'

`set-precision'       u -         float-ext       ``set-precision''
   Set the number of significant digits currently used by `F.' `FE.'
and `FS.' to u.

   Angles in floating point operations are given in radians (a full
circle has 2 pi radians).

`fsin'       r1 - r2        float-ext       ``f-sine''

`fcos'       r1 - r2        float-ext       ``f-cos''

`fsincos'       r1 - r2 r3        float-ext       ``f-sine-cos''
   r2=sin(r1), r3=cos(r1)

`ftan'       r1 - r2        float-ext       ``f-tan''

`fasin'       r1 - r2        float-ext       ``f-a-sine''

`facos'       r1 - r2        float-ext       ``f-a-cos''

`fatan'       r1 - r2        float-ext       ``f-a-tan''

`fatan2'       r1 r2 - r3        float-ext       ``f-a-tan-two''
   r1/r2=tan(r3). ANS Forth does not require, but probably intends this
to be the inverse of `fsincos'. In gforth it is.

`fsinh'       r1 - r2        float-ext       ``f-cinch''

`fcosh'       r1 - r2        float-ext       ``f-cosh''

`ftanh'       r1 - r2        float-ext       ``f-tan-h''

`fasinh'       r1 - r2        float-ext       ``f-a-cinch''

`facosh'       r1 - r2        float-ext       ``f-a-cosh''

`fatanh'       r1 - r2        float-ext       ``f-a-tan-h''

`pi'       - r         gforth       ``pi''
   `Fconstant' - r is the value pi; the ratio of a circle's area to its
diameter.

   One particular problem with floating-point arithmetic is that
comparison for equality often fails when you would expect it to
succeed.  For this reason approximate equality is often preferred (but
you still have to know what you are doing).  Also note that IEEE NaNs
may compare differently from what you might expect.  The comparison
words are:

`f~rel'       r1 r2 r3 - flag         gforth       ``f~rel''
   Approximate equality with relative error: |r1-r2|<r3*|r1+r2|.

`f~abs'       r1 r2 r3 - flag         gforth       ``f~abs''
   Approximate equality with absolute error: |r1-r2|<r3.

`f~'       r1 r2 r3 - flag         float-ext       ``f-proximate''
   ANS Forth medley for comparing r1 and r2 for equality: r3>0:
`f~abs'; r3=0: bitwise comparison; r3<0: `fnegate f~rel'.

`f='       r1 r2 - f        gforth       ``f-equals''

`f<>'       r1 r2 - f        gforth       ``f-not-equals''

`f<'       r1 r2 - f        float       ``f-less-than''

`f<='       r1 r2 - f        gforth       ``f-less-or-equal''

`f>'       r1 r2 - f        gforth       ``f-greater-than''

`f>='       r1 r2 - f        gforth       ``f-greater-or-equal''

`f0<'       r - f        float       ``f-zero-less-than''

`f0<='       r - f        gforth       ``f-zero-less-or-equal''

`f0<>'       r - f        gforth       ``f-zero-not-equals''

`f0='       r - f        float       ``f-zero-equals''

`f0>'       r - f        gforth       ``f-zero-greater-than''

`f0>='       r - f        gforth       ``f-zero-greater-or-equal''

   ---------- Footnotes ----------

   (1) It's easy to generate the separate notation from that by just
separating the floating-point numbers out: e.g. `( n r1 u r2 -- r3 )'
becomes `( n u -- ) ( F: r1 r2 -- r3 )'.

Stack Manipulation
==================

   Gforth maintains a number of separate stacks:

   * A data stack (also known as the "parameter stack") - for
     characters, cells, addresses, and double cells.

   * A floating point stack - for holding floating point (FP) numbers.

   * A return stack - for holding the return addresses of colon
     definitions and other (non-FP) data.

   * A locals stack - for holding local variables.

Data stack
----------

`drop'       w -        core       ``drop''

`nip'       w1 w2 - w2        core-ext       ``nip''

`dup'       w - w w        core       ``dupe''

`over'       w1 w2 - w1 w2 w1        core       ``over''

`tuck'       w1 w2 - w2 w1 w2        core-ext       ``tuck''

`swap'       w1 w2 - w2 w1        core       ``swap''

`pick'       u - w        core-ext       ``pick''
   Actually the stack effect is ` x0 ... xu u -- x0 ... xu x0 '.

`rot'       w1 w2 w3 - w2 w3 w1        core       ``rote''

`-rot'       w1 w2 w3 - w3 w1 w2        gforth       ``not-rote''

`?dup'       w - w        core       ``question-dupe''
   Actually the stack effect is: `( w -- 0 | w w )'.  It performs a
`dup' if w is nonzero.

`roll'       x0 x1 .. xn n - x1 .. xn x0         core-ext       ``roll''

`2drop'       w1 w2 -        core       ``two-drop''

`2nip'       w1 w2 w3 w4 - w3 w4        gforth       ``two-nip''

`2dup'       w1 w2 - w1 w2 w1 w2        core       ``two-dupe''

`2over'       w1 w2 w3 w4 - w1 w2 w3 w4 w1 w2        core       ``two-over''

`2tuck'       w1 w2 w3 w4 - w3 w4 w1 w2 w3 w4        gforth       ``two-tuck''

`2swap'       w1 w2 w3 w4 - w3 w4 w1 w2        core       ``two-swap''

`2rot'       w1 w2 w3 w4 w5 w6 - w3 w4 w5 w6 w1 w2        double-ext       ``two-rote''

Floating point stack
--------------------

   Whilst every sane Forth has a separate floating-point stack, it is
not strictly required; an ANS Forth system could theoretically keep
floating-point numbers on the data stack. As an additional difficulty,
you don't know how many cells a floating-point number takes. It is
reportedly possible to write words in a way that they work also for a
unified stack model, but we do not recommend trying it. Instead, just
say that your program has an environmental dependency on a separate
floating-point stack.

`floating-stack'       - n         environment       ``floating-stack''
   N is non-zero, showing that Gforth maintains a separate
floating-point stack of depth N.

`fdrop'       r -        float       ``f-drop''

`fnip'       r1 r2 - r2        gforth       ``f-nip''

`fdup'       r - r r        float       ``f-dupe''

`fover'       r1 r2 - r1 r2 r1        float       ``f-over''

`ftuck'       r1 r2 - r2 r1 r2        gforth       ``f-tuck''

`fswap'       r1 r2 - r2 r1        float       ``f-swap''

`fpick'       u - r        gforth       ``fpick''
   Actually the stack effect is ` r0 ... ru u -- r0 ... ru r0 '.

`frot'       r1 r2 r3 - r2 r3 r1        float       ``f-rote''

Return stack
------------

   A Forth system is allowed to keep local variables on the return
stack. This is reasonable, as local variables usually eliminate the
need to use the return stack explicitly. So, if you want to produce a
standard compliant program and you are using local variables in a word,
forget about return stack manipulations in that word (refer to the
standard document for the exact rules).

`>r'       w -        core       ``to-r''
   `( R: -- w )'

`r>'       - w        core       ``r-from''
   `( R: w -- )'

`r@'       - w ; R: w - w         core       ``r-fetch''

`rdrop'       -        gforth       ``rdrop''
   `( R: w -- )'

`2>r'       w1 w2 -        core-ext       ``two-to-r''
   `( R: -- w1 w2 )'

`2r>'       - w1 w2        core-ext       ``two-r-from''
   `( R: w1 w2 -- )'

`2r@'       - w1 w2        core-ext       ``two-r-fetch''
   `( R: w1 w2 -- w1 w2 )'

`2rdrop'       -        gforth       ``two-r-drop''
   `( R: w1 w2 -- )'

Locals stack
------------

   Gforth uses an extra locals stack.  It is described, along with the
reasons for its existence, in *Note Locals implementation::.

Stack pointer manipulation
--------------------------

`sp0'       - a-addr         gforth       ``sp0''
   `User' variable - initial value of the data stack pointer.

`sp@'       - a-addr        gforth       ``sp-fetch''

`sp!'       a-addr -        gforth       ``sp-store''

`fp0'       - a-addr         gforth       ``fp0''
   `User' variable - initial value of the floating-point stack pointer.

`fp@'       - f-addr        gforth       ``fp-fetch''

`fp!'       f-addr -        gforth       ``fp-store''

`rp0'       - a-addr         gforth       ``rp0''
   `User' variable - initial value of the return stack pointer.

`rp@'       - a-addr        gforth       ``rp-fetch''

`rp!'       a-addr -        gforth       ``rp-store''

`lp0'       - a-addr         gforth       ``lp0''
   `User' variable - initial value of the locals stack pointer.

`lp@'       - addr         gforth       ``lp-fetch''

`lp!'       c-addr -        gforth       ``lp-store''

Memory
======

   In addition to the standard Forth memory allocation words, there is
also a garbage collector
(http://www.complang.tuwien.ac.at/forth/garbage-collection.zip).

ANS Forth and Gforth memory models
----------------------------------

   ANS Forth considers a Forth system as consisting of several address
spaces, of which only "data space" is managed and accessible with the
memory words.  Memory not necessarily in data space includes the
stacks, the code (called code space) and the headers (called name
space). In Gforth everything is in data space, but the code for the
primitives is usually read-only.

   Data space is divided into a number of areas: The (data space
portion of the) dictionary(1), the heap, and a number of
system-allocated buffers.

   In ANS Forth data space is also divided into contiguous regions.  You
can only use address arithmetic within a contiguous region, not between
them.  Usually each allocation gives you one contiguous region, but the
dictionary allocation words have additional rules (*note Dictionary
allocation::).

   Gforth provides one big address space, and address arithmetic can be
performed between any addresses. However, in the dictionary headers or
code are interleaved with data, so almost the only contiguous data space
regions there are those described by ANS Forth as contiguous; but you
can be sure that the dictionary is allocated towards increasing
addresses even between contiguous regions.  The memory order of
allocations in the heap is platform-dependent (and possibly different
from one run to the next).

   ---------- Footnotes ----------

   (1) Sometimes, the term "dictionary" is used to refer to the search
data structure embodied in word lists and headers, because it is used
for looking up names, just as you would in a conventional dictionary.

Dictionary allocation
---------------------

   Dictionary allocation is a stack-oriented allocation scheme, i.e., if
you want to deallocate X, you also deallocate everything allocated
after X.

   The allocations using the words below are contiguous and grow the
region towards increasing addresses.  Other words that allocate
dictionary memory of any kind (i.e., defining words including
`:noname') end the contiguous region and start a new one.

   In ANS Forth only `create'd words are guaranteed to produce an
address that is the start of the following contiguous region.  In
particular, the cell allocated by `variable' is not guaranteed to be
contiguous with following `allot'ed memory.

   You can deallocate memory by using `allot' with a negative argument
(with some restrictions, see `allot'). For larger deallocations use
`marker'.

`here'       - addr         core       ``here''
   Return the address of the next free location in data space.

`unused'       - u         core-ext       ``unused''
   Return the amount of free space remaining (in address units) in the
region addressed by `here'.

`allot'       n -         core       ``allot''
   Reserve n address units of data space without initialization. n is a
signed number, passing a negative n releases memory.  In ANS Forth you
can only deallocate memory from the current contiguous region in this
way.  In Gforth you can deallocate anything in this way but named words.
The system does not check this restriction.

`c,'       c -         core       ``c-comma''
   Reserve data space for one char and store c in the space.

`f,'       f -         gforth       ``f,''
   Reserve data space for one floating-point number and store f in the
space.

`,'       w -         core       ``comma''
   Reserve data space for one cell and store w in the space.

`2,'       w1 w2 -         gforth       ``2,''
   Reserve data space for two cells and store the double w1 w2 there,
w2 first (lower address).

   Memory accesses have to be aligned (*note Address arithmetic::). So
of course you should allocate memory in an aligned way, too. I.e.,
before allocating allocating a cell, `here' must be cell-aligned, etc.
The words below align `here' if it is not already.  Basically it is
only already aligned for a type, if the last allocation was a multiple
of the size of this type and if `here' was aligned for this type before.

   After freshly `create'ing a word, `here' is `align'ed in ANS Forth
(`maxalign'ed in Gforth).

`align'       -         core       ``align''
   If the data-space pointer is not aligned, reserve enough space to
align it.

`falign'       -         float       ``f-align''
   If the data-space pointer is not float-aligned, reserve enough space
to align it.

`sfalign'       -         float-ext       ``s-f-align''
   If the data-space pointer is not single-float-aligned, reserve
enough space to align it.

`dfalign'       -         float-ext       ``d-f-align''
   If the data-space pointer is not double-float-aligned, reserve
enough space to align it.

`maxalign'       -         gforth       ``maxalign''
   Align data-space pointer for all alignment requirements.

`cfalign'       -         gforth       ``cfalign''
   Align data-space pointer for code field requirements (i.e., such
that the corresponding body is maxaligned).

Heap allocation
---------------

   Heap allocation supports deallocation of allocated memory in any
order. Dictionary allocation is not affected by it (i.e., it does not
end a contiguous region). In Gforth, these words are implemented using
the standard C library calls malloc(), free() and resize().

   The memory region produced by one invocation of `allocate' or
`resize' is internally contiguous.  There is no contiguity between such
a region and any other region (including others allocated from the
heap).

`allocate'       u - a-addr wior        memory       ``allocate''
   Allocate u address units of contiguous data space. The initial
contents of the data space is undefined. If the allocation is
successful, a-addr is the start address of the allocated region and wior
is 0. If the allocation fails, a-addr is undefined and wior is a
non-zero I/O result code.

`free'       a-addr - wior        memory       ``free''
   Return the region of data space starting at a-addr to the system.
The region must originally have been obtained using `allocate' or
`resize'. If the operational is successful, wior is 0.  If the
operation fails, wior is a non-zero I/O result code.

`resize'       a-addr1 u - a-addr2 wior        memory       ``resize''
   Change the size of the allocated area at a-addr1 to u address units,
possibly moving the contents to a different area. a-addr2 is the
address of the resulting area.  If the operation is successful, wior is
0.  If the operation fails, wior is a non-zero I/O result code. If
a-addr1 is 0, Gforth's (but not the Standard) `resize' `allocate's u
address units.

Memory Access
-------------

`@'       a-addr - w        core       ``fetch''
   w is the cell stored at a_addr.

`!'       w a-addr -        core       ``store''
   Store w into the cell at a-addr.

`+!'       n a-addr -        core       ``plus-store''
   Add n to the cell at a-addr.

`c@'       c-addr - c        core       ``c-fetch''
   c is the char stored at c_addr.

`c!'       c c-addr -        core       ``c-store''
   Store c into the char at c-addr.

`2@'       a-addr - w1 w2        core       ``two-fetch''
   w2 is the content of the cell stored at a-addr, w1 is the content of
the next cell.

`2!'       w1 w2 a-addr -        core       ``two-store''
   Store w2 into the cell at c-addr and w1 into the next cell.

`f@'       f-addr - r        float       ``f-fetch''
   r is the float at address f-addr.

`f!'       r f-addr -        float       ``f-store''
   Store r into the float at address f-addr.

`sf@'       sf-addr - r        float-ext       ``s-f-fetch''
   Fetch the single-precision IEEE floating-point value r from the
address sf-addr.

`sf!'       r sf-addr -        float-ext       ``s-f-store''
   Store r as single-precision IEEE floating-point value to the address
sf-addr.

`df@'       df-addr - r        float-ext       ``d-f-fetch''
   Fetch the double-precision IEEE floating-point value r from the
address df-addr.

`df!'       r df-addr -        float-ext       ``d-f-store''
   Store r as double-precision IEEE floating-point value to the address
df-addr.

Address arithmetic
------------------

   Address arithmetic is the foundation on which you can build data
structures like arrays, records (*note Structures::) and objects (*note
Object-oriented Forth::).

   ANS Forth does not specify the sizes of the data types. Instead, it
offers a number of words for computing sizes and doing address
arithmetic. Address arithmetic is performed in terms of address units
(aus); on most systems the address unit is one byte. Note that a
character may have more than one au, so `chars' is no noop (on
platforms where it is a noop, it compiles to nothing).

   The basic address arithmetic words are `+' and `-'.  E.g., if you
have the address of a cell, perform `1 cells +', and you will have the
address of the next cell.

   In ANS Forth you can perform address arithmetic only within a
contiguous region, i.e., if you have an address into one region, you
can only add and subtract such that the result is still within the
region; you can only subtract or compare addresses from within the same
contiguous region.  Reasons: several contiguous regions can be arranged
in memory in any way; on segmented systems addresses may have unusual
representations, such that address arithmetic only works within a
region.  Gforth provides a few more guarantees (linear address space,
dictionary grows upwards), but in general I have found it easy to stay
within contiguous regions (exception: computing and comparing to the
address just beyond the end of an array).

   ANS Forth also defines words for aligning addresses for specific
types. Many computers require that accesses to specific data types must
only occur at specific addresses; e.g., that cells may only be accessed
at addresses divisible by 4. Even if a machine allows unaligned
accesses, it can usually perform aligned accesses faster.

   For the performance-conscious: alignment operations are usually only
necessary during the definition of a data structure, not during the
(more frequent) accesses to it.

   ANS Forth defines no words for character-aligning addresses. This is
not an oversight, but reflects the fact that addresses that are not
char-aligned have no use in the standard and therefore will not be
created.

   ANS Forth guarantees that addresses returned by `CREATE'd words are
cell-aligned; in addition, Gforth guarantees that these addresses are
aligned for all purposes.

   Note that the ANS Forth word `char' has nothing to do with address
arithmetic.

`chars'       n1 - n2         core       ``chars''
   n2 is the number of address units of n1 chars.""

`char+'       c-addr1 - c-addr2        core       ``char-plus''
   `1 chars +'.

`cells'       n1 - n2        core       ``cells''
    n2 is the number of address units of n1 cells.

`cell+'       a-addr1 - a-addr2        core       ``cell-plus''
   `1 cells +'

`cell'       - u         gforth       ``cell''
   `Constant' - `1 cells'

`aligned'       c-addr - a-addr        core       ``aligned''
    a-addr is the first aligned address greater than or equal to c-addr.

`floats'       n1 - n2        float       ``floats''
   n2 is the number of address units of n1 floats.

`float+'       f-addr1 - f-addr2        float       ``float-plus''
   `1 floats +'.

`float'       - u         gforth       ``float''
   `Constant' - the number of address units corresponding to a
floating-point number.

`faligned'       c-addr - f-addr        float       ``f-aligned''
    f-addr is the first float-aligned address greater than or equal to
c-addr.

`sfloats'       n1 - n2        float-ext       ``s-floats''
   n2 is the number of address units of n1 single-precision IEEE
floating-point numbers.

`sfloat+'       sf-addr1 - sf-addr2         float-ext       ``s-float-plus''
   `1 sfloats +'.

`sfaligned'       c-addr - sf-addr        float-ext       ``s-f-aligned''
   sf-addr is the first single-float-aligned address greater than or
equal to c-addr.

`dfloats'       n1 - n2        float-ext       ``d-floats''
   n2 is the number of address units of n1 double-precision IEEE
floating-point numbers.

`dfloat+'       df-addr1 - df-addr2         float-ext       ``d-float-plus''
   `1 dfloats +'.

`dfaligned'       c-addr - df-addr        float-ext       ``d-f-aligned''
   df-addr is the first double-float-aligned address greater than or
equal to c-addr.

`maxaligned'       addr1 - addr2         gforth       ``maxaligned''
   addr2 is the first address after addr1 that satisfies all alignment
restrictions.  maxaligned"

`cfaligned'       addr1 - addr2         gforth       ``cfaligned''
   addr2 is the first address after addr1 that is aligned for a code
field (i.e., such that the corresponding body is maxaligned).

`ADDRESS-UNIT-BITS'       - n         environment       ``ADDRESS-UNIT-BITS''
   Size of one address unit, in bits.

Memory Blocks
-------------

   Memory blocks often represent character strings; For ways of storing
character strings in memory see *Note String Formats::.  For other
string-processing words see *Note Displaying characters and strings::.

   A few of these words work on address unit blocks.  In that case, you
usually have to insert `CHARS' before the word when working on
character strings.  Most words work on character blocks, and expect a
char-aligned address.

   When copying characters between overlapping memory regions, use
`chars move' or choose carefully between `cmove' and `cmove>'.

`move'       c-from c-to ucount -        core       ``move''
   Copy the contents of ucount aus at c-from to c-to. `move' works
correctly even if the two areas overlap.

`erase'       addr u -         core-ext       ``erase''
   Clear all bits in u aus starting at addr.

`cmove'       c-from c-to u -        string       ``c-move''
   Copy the contents of ucount characters from data space at c-from to
c-to. The copy proceeds `char'-by-`char' from low address to high
address; i.e., for overlapping areas it is safe if c-to=<c-from.

`cmove>'       c-from c-to u -        string       ``c-move-up''
   Copy the contents of ucount characters from data space at c-from to
c-to. The copy proceeds `char'-by-`char' from high address to low
address; i.e., for overlapping areas it is safe if c-to>=c-from.

`fill'       c-addr u c -        core       ``fill''
   Store c in u chars starting at c-addr.

`blank'       c-addr u -         string       ``blank''
   Store the space character into u chars starting at c-addr.

`compare'       c-addr1 u1 c-addr2 u2 - n        string       ``compare''
   Compare two strings lexicographically. If they are equal, n is 0; if
the first string is smaller, n is -1; if the first string is larger, n
is 1. Currently this is based on the machine's character comparison. In
the future, this may change to consider the current locale and its
collation order.

`search'       c-addr1 u1 c-addr2 u2 - c-addr3 u3 flag         string       ``search''
   Search the string specified by c-addr1, u1 for the string specified
by c-addr2, u2. If flag is true: match was found at c-addr3 with u3
characters remaining. If flag is false: no match was found; c-addr3, u3
are equal to c-addr1, u1.

`-trailing'       c-addr u1 - c-addr u2        string       ``dash-trailing''
   Adjust the string specified by c-addr, u1 to remove all trailing
spaces. u2 is the length of the modified string.

`/string'       c-addr1 u1 n - c-addr2 u2        string       ``slash-string''
   Adjust the string specified by c-addr1, u1 to remove n characters
from the start of the string.

`bounds'       addr u - addr+u addr         gforth       ``bounds''
   Given a memory block represented by starting address addr and length
u in aus, produce the end address addr+u and the start address in the
right order for `u+do' or `?do'.

Control Structures
==================

   Control structures in Forth cannot be used interpretively, only in a
colon definition(1). We do not like this limitation, but have not seen
a satisfying way around it yet, although many schemes have been
proposed.

   ---------- Footnotes ----------

   (1) To be precise, they have no interpretation semantics (*note
Interpretation and Compilation Semantics::).

Selection
---------

     flag
     IF
       code
     ENDIF

If flag is non-zero (as far as `IF' etc. are concerned, a cell with any
bit set represents truth) code is executed.

     flag
     IF
       code1
     ELSE
       code2
     ENDIF

   If FLAG is true, code1 is executed, otherwise code2 is executed.

   You can use `THEN' instead of `ENDIF'. Indeed, `THEN' is standard,
and `ENDIF' is not, although it is quite popular. We recommend using
`ENDIF', because it is less confusing for people who also know other
languages (and is not prone to reinforcing negative prejudices against
Forth in these people). Adding `ENDIF' to a system that only supplies
`THEN' is simple:
     : ENDIF   POSTPONE then ; immediate

   [According to `Webster's New Encyclopedic Dictionary', "then (adv.)"
has the following meanings:
     ... 2b: following next after in order ... 3d: as a necessary
     consequence (if you were there, then you saw them).
   Forth's `THEN' has the meaning 2b, whereas `THEN' in Pascal and many
other programming languages has the meaning 3d.]

   Gforth also provides the words `?DUP-IF' and `?DUP-0=-IF', so you
can avoid using `?dup'. Using these alternatives is also more efficient
than using `?dup'. Definitions in ANS Forth for `ENDIF', `?DUP-IF' and
`?DUP-0=-IF' are provided in `compat/control.fs'.

     n
     CASE
       n1 OF code1 ENDOF
       n2 OF code2 ENDOF
       ...
       ( n ) default-code ( n )
     ENDCASE

   Executes the first codei, where the ni is equal to n.  If no ni
matches, the optional default-code is executed. The optional default
case can be added by simply writing the code after the last `ENDOF'. It
may use n, which is on top of the stack, but must not consume it.

   Programming style note: To keep the code understandable, you should
ensure that on all paths through a selection construct the stack is
changed in the same way (wrt. number and types of stack items consumed
and pushed).

Simple Loops
------------

     BEGIN
       code1
       flag
     WHILE
       code2
     REPEAT

   code1 is executed and flag is computed. If it is true, code2 is
executed and the loop is restarted; If flag is false, execution
continues after the `REPEAT'.

     BEGIN
       code
       flag
     UNTIL

   code is executed. The loop is restarted if `flag' is false.

   Programming style note: To keep the code understandable, a complete
iteration of the loop should not change the number and types of the
items on the stacks.

     BEGIN
       code
     AGAIN

   This is an endless loop.

Counted Loops
-------------

   The basic counted loop is:
     limit start
     ?DO
       body
     LOOP

   This performs one iteration for every integer, starting from start
and up to, but excluding limit. The counter, or index, can be accessed
with `i'. For example, the loop:
     10 0 ?DO
       i .
     LOOP

prints `0 1 2 3 4 5 6 7 8 9'

   The index of the innermost loop can be accessed with `i', the index
of the next loop with `j', and the index of the third loop with `k'.

`i'       - n        core       ``i''

`j'       - n        core       ``j''

`k'       - n        gforth       ``k''

   The loop control data are kept on the return stack, so there are some
restrictions on mixing return stack accesses and counted loop words. In
particuler, if you put values on the return stack outside the loop, you
cannot read them inside the loop(1). If you put values on the return
stack within a loop, you have to remove them before the end of the loop
and before accessing the index of the loop.

   There are several variations on the counted loop:

   * `LEAVE' leaves the innermost counted loop immediately; execution
     continues after the associated `LOOP' or `NEXT'. For example:

          10 0 ?DO  i DUP . 3 = IF LEAVE THEN LOOP
     prints `0 1 2 3'

   * `UNLOOP' prepares for an abnormal loop exit, e.g., via `EXIT'.
     `UNLOOP' removes the loop control parameters from the return stack
     so `EXIT' can get to its return address. For example:

          : demo 10 0 ?DO i DUP . 3 = IF UNLOOP EXIT THEN LOOP ." Done" ;
     prints `0 1 2 3'

   * If start is greater than limit, a `?DO' loop is entered (and
     `LOOP' iterates until they become equal by wrap-around
     arithmetic). This behaviour is usually not what you want.
     Therefore, Gforth offers `+DO' and `U+DO' (as replacements for
     `?DO'), which do not enter the loop if start is greater than
     limit; `+DO' is for signed loop parameters, `U+DO' for unsigned
     loop parameters.

   * `?DO' can be replaced by `DO'. `DO' always enters the loop,
     independent of the loop parameters. Do not use `DO', even if you
     know that the loop is entered in any case. Such knowledge tends to
     become invalid during maintenance of a program, and then the `DO'
     will make trouble.

   * `LOOP' can be replaced with `n +LOOP'; this updates the index by n
     instead of by 1. The loop is terminated when the border between
     limit-1 and limit is crossed. E.g.:

          4 0 +DO  i .  2 +LOOP

     prints `0 2'

          4 1 +DO  i .  2 +LOOP

     prints `1 3'

   * The behaviour of `n +LOOP' is peculiar when n is negative:

          -1 0 ?DO  i .  -1 +LOOP

     prints `0 -1'

          0 0 ?DO  i .  -1 +LOOP
     prints nothing.

     Therefore we recommend avoiding `n +LOOP' with negative n. One
     alternative is `u -LOOP', which reduces the index by u each
     iteration. The loop is terminated when the border between limit+1
     and limit is crossed. Gforth also provides `-DO' and `U-DO' for
     down-counting loops. E.g.:

          -2 0 -DO  i .  1 -LOOP

     prints `0 -1'

          -1 0 -DO  i .  1 -LOOP

     prints `0'

          0 0 -DO  i .  1 -LOOP

     prints nothing.


   Unfortunately, `+DO', `U+DO', `-DO', `U-DO' and `-LOOP' are not
defined in ANS Forth. However, an implementation for these words that
uses only standard words is provided in `compat/loops.fs'.

   Another counted loop is:
     n
     FOR
       body
     NEXT
   This is the preferred loop of native code compiler writers who are
too lazy to optimize `?DO' loops properly. This loop structure is not
defined in ANS Forth. In Gforth, this loop iterates n+1 times; `i'
produces values starting with n and ending with 0. Other Forth systems
may behave differently, even if they support `FOR' loops. To avoid
problems, don't use `FOR' loops.

   ---------- Footnotes ----------

   (1) well, not in a way that is portable.

Arbitrary control structures
----------------------------

   ANS Forth permits and supports using control structures in a
non-nested way. Information about incomplete control structures is
stored on the control-flow stack. This stack may be implemented on the
Forth data stack, and this is what we have done in Gforth.

   An orig entry represents an unresolved forward branch, a dest entry
represents a backward branch target. A few words are the basis for
building any control structure possible (except control structures that
need storage, like calls, coroutines, and backtracking).

`IF'       compilation - orig ; run-time f -         core       ``IF''

`AHEAD'       compilation - orig ; run-time -         tools-ext       ``AHEAD''

`THEN'       compilation orig - ; run-time -         core       ``THEN''

`BEGIN'       compilation - dest ; run-time -         core       ``BEGIN''

`UNTIL'       compilation dest - ; run-time f -         core       ``UNTIL''

`AGAIN'       compilation dest - ; run-time -         core-ext       ``AGAIN''

`CS-PICK'       ... u - ... destu         tools-ext       ``c-s-pick''

`CS-ROLL'       destu/origu .. dest0/orig0 u - .. dest0/orig0 destu/origu         tools-ext       ``c-s-roll''

   The Standard words `CS-PICK' and `CS-ROLL' allow you to manipulate
the control-flow stack in a portable way. Without them, you would need
to know how many stack items are occupied by a control-flow entry (many
systems use one cell. In Gforth they currently take three, but this may
change in the future).

   Some standard control structure words are built from these words:

`ELSE'       compilation orig1 - orig2 ; run-time f -         core       ``ELSE''

`WHILE'       compilation dest - orig dest ; run-time f -         core       ``WHILE''

`REPEAT'       compilation orig dest - ; run-time -         core       ``REPEAT''

Gforth adds some more control-structure words:

`ENDIF'       compilation orig - ; run-time -         gforth       ``ENDIF''

`?DUP-IF'       compilation - orig ; run-time n - n|         gforth       ``question-dupe-if''
   This is the preferred alternative to the idiom "`?DUP IF'", since it
can be better handled by tools like stack checkers. Besides, it's
faster.

`?DUP-0=-IF'       compilation - orig ; run-time n - n|         gforth       ``question-dupe-zero-equals-if''

Counted loop words constitute a separate group of words:

`?DO'       compilation - do-sys ; run-time w1 w2 - | loop-sys         core-ext       ``question-do''

`+DO'       compilation - do-sys ; run-time n1 n2 - | loop-sys         gforth       ``plus-do''

`U+DO'       compilation - do-sys ; run-time u1 u2 - | loop-sys         gforth       ``u-plus-do''

`-DO'       compilation - do-sys ; run-time n1 n2 - | loop-sys         gforth       ``minus-do''

`U-DO'       compilation - do-sys ; run-time u1 u2 - | loop-sys         gforth       ``u-minus-do''

`DO'       compilation - do-sys ; run-time w1 w2 - loop-sys         core       ``DO''

`FOR'       compilation - do-sys ; run-time u - loop-sys         gforth       ``FOR''

`LOOP'       compilation do-sys - ; run-time loop-sys1 - | loop-sys2         core       ``LOOP''

`+LOOP'       compilation do-sys - ; run-time loop-sys1 n - | loop-sys2         core       ``plus-loop''

`-LOOP'       compilation do-sys - ; run-time loop-sys1 u - | loop-sys2         gforth       ``minus-loop''

`NEXT'       compilation do-sys - ; run-time loop-sys1 - | loop-sys2         gforth       ``NEXT''

`LEAVE'       compilation - ; run-time loop-sys -         core       ``LEAVE''

`?LEAVE'       compilation - ; run-time f | f loop-sys -         gforth       ``question-leave''

`unloop'       -        core       ``unloop''

`DONE'       compilation orig - ; run-time -         gforth       ``DONE''

   The standard does not allow using `CS-PICK' and `CS-ROLL' on do-sys.
Gforth allows it, but it's your job to ensure that for every `?DO' etc.
there is exactly one `UNLOOP' on any path through the definition
(`LOOP' etc. compile an `UNLOOP' on the fall-through path). Also, you
have to ensure that all `LEAVE's are resolved (by using one of the
loop-ending words or `DONE').

Another group of control structure words are:

`case'       compilation  - case-sys ; run-time  -         core-ext       ``case''

`endcase'       compilation case-sys - ; run-time x -         core-ext       ``end-case''

`of'       compilation  - of-sys ; run-time x1 x2 - |x1         core-ext       ``of''

`endof'       compilation case-sys1 of-sys - case-sys2 ; run-time  -         core-ext       ``end-of''

   case-sys and of-sys cannot be processed using `CS-PICK' and
`CS-ROLL'.

Programming Style
.................

   In order to ensure readability we recommend that you do not create
arbitrary control structures directly, but define new control structure
words for the control structure you want and use these words in your
program. For example, instead of writing:

     BEGIN
       ...
     IF [ 1 CS-ROLL ]
       ...
     AGAIN THEN

we recommend defining control structure words, e.g.,

     : WHILE ( DEST -- ORIG DEST )
      POSTPONE IF
      1 CS-ROLL ; immediate
     
     : REPEAT ( orig dest -- )
      POSTPONE AGAIN
      POSTPONE THEN ; immediate

and then using these to create the control structure:

     BEGIN
       ...
     WHILE
       ...
     REPEAT

   That's much easier to read, isn't it? Of course, `REPEAT' and
`WHILE' are predefined, so in this example it would not be necessary to
define them.

Calls and returns
-----------------

   A definition can be called simply be writing the name of the
definition to be called. Normally a definition is invisible during its
own definition. If you want to write a directly recursive definition,
you can use `recursive' to make the current definition visible, or
`recurse' to call the current definition directly.

`recursive'       compilation - ; run-time -         gforth       ``recursive''
   Make the current definition visible, enabling it to call itself
recursively.

`recurse'       compilation - ; run-time ?? - ??         core       ``recurse''
   Call the current definition.

     Programming style note: I prefer using `recursive' to `recurse',
     because calling the definition by name is more descriptive (if the
     name is well-chosen) than the somewhat cryptic `recurse'.  E.g.,
     in a quicksort implementation, it is much better to read (and
     think) "now sort the partitions" than to read "now do a recursive
     call".

   For mutual recursion, use `Defer'red words, like this:

     Defer foo
     
     : bar ( ... -- ... )
      ... foo ... ;
     
     :noname ( ... -- ... )
      ... bar ... ;
     IS foo

   Deferred words are discussed in more detail in *Note Deferred
words::.

   The current definition returns control to the calling definition when
the end of the definition is reached or `EXIT' is encountered.

`EXIT'       compilation - ; run-time nest-sys -         core       ``EXIT''
   Return to the calling definition; usually used as a way of forcing
an early return from a definition. Before `EXIT'ing you must clean up
the return stack and `UNLOOP' any outstanding `?DO'...`LOOP's.

`;s'       -        gforth       ``semis''
   The primitive compiled by `EXIT'.

Exception Handling
------------------

   If a word detects an error condition that it cannot handle, it can
`throw' an exception.  In the simplest case, this will terminate your
program, and report an appropriate error.

`throw'       y1 .. ym nerror - y1 .. ym / z1 .. zn error         exception       ``throw''
   If nerror is 0, drop it and continue.  Otherwise, transfer control
to the next dynamically enclosing exception handler, reset the stacks
accordingly, and push nerror.

   `Throw' consumes a cell-sized error number on the stack. There are
some predefined error numbers in ANS Forth (see `errors.fs').  In
Gforth (and most other systems) you can use the iors produced by various
words as error numbers (e.g., a typical use of `allocate' is `allocate
throw').  Gforth also provides the word `exception' to define your own
error numbers (with decent error reporting); an ANS Forth version of
this word (but without the error messages) is available in
`compat/except.fs'.  And finally, you can use your own error numbers
(anything outside the range -4095..0), but won't get nice error
messages, only numbers.  For example, try:

     -10 throw                    \ ANS defined
     -267 throw                   \ system defined
     s" my error" exception throw \ user defined
     7 throw                      \ arbitrary number

`exception'       addr u - n         gforth       ``exception''
   N is a previously unused `throw' value in the range (-4095...-256).
Consecutive calls to `exception' return consecutive decreasing numbers.
Gforth uses the string ADDR U as an error message.

   A common idiom to `THROW' a specific error if a flag is true is this:

     `( flag ) 0<> errno and throw'

   Your program can provide exception handlers to catch exceptions.  An
exception handler can be used to correct the problem, or to clean up
some data structures and just throw the exception to the next exception
handler.  Note that `throw' jumps to the dynamically innermost
exception handler.  The system's exception handler is outermost, and
just prints an error and restarts command-line interpretation (or, in
batch mode (i.e., while processing the shell command line), leaves
Gforth).

   The ANS Forth way to catch exceptions is `catch':

`catch'       ... xt - ... n         exception       ``catch''

   The most common use of exception handlers is to clean up the state
when an error happens.  E.g.,

     base  >r hex \ actually the hex should be inside foo, or we h
     ['] foo catch ( nerror|0 )
     r> base !
     ( nerror|0 ) throw \ pass it on

   A use of `catch' for handling the error `myerror' might look like
this:

     ['] foo catch
     CASE
       myerror OF ... ( do something about it ) ENDOF
       dup throw \ default: pass other errors on, do nothing on non-errors
     ENDCASE

   Having to wrap the code into a separate word is often cumbersome,
therefore Gforth provides an alternative syntax:

     TRY
       code1
     RECOVER     \ optional
       code2 \ optional
     ENDTRY

   This performs Code1.  If code1 completes normally, execution
continues after the `endtry'.  If Code1 throws, the stacks are reset to
the state during `try', the throw value is pushed on the data stack,
and execution constinues at code2, and finally falls through the
`endtry' into the following code. If there is no `recover' clause, this
works like an empty recover clause.

`try'       compilation  - orig ; run-time  -         gforth       ``try''

`recover'       compilation  orig1 - orig2 ; run-time  -         gforth       ``recover''

`endtry'       compilation  orig - ; run-time  -         gforth       ``endtry''

   The cleanup example from above in this syntax:

     base  >r TRY
       hex foo \ now the hex is placed correctly
       0       \ value for throw
     ENDTRY
     r> base ! throw

   And here's the error handling example:

     TRY
       foo
     RECOVER
       CASE
         myerror OF ... ( do something about it ) ENDOF
         throw \ pass other errors on
       ENDCASE
     ENDTRY

   Programming style note: As usual, you should ensure that the stack
depth is statically known at the end: either after the `throw' for
passing on errors, or after the `ENDTRY' (or, if you use `catch', after
the end of the selection construct for handling the error).

   There are two alternatives to `throw': `Abort"' is conditional and
you can provide an error message.  `Abort' just produces an "Aborted"
error.

   The problem with these words is that exception handlers cannot
differentiate between different `abort"'s; they just look like `-2
throw' to them (the error message cannot be accessed by standard
programs).  Similar `abort' looks like `-1 throw' to exception handlers.

`abort"'       compilation 'ccc"' - ; run-time f -         core,exception-ext       ``abort-quote''
   If any bit of f is non-zero, perform the function of `-2 throw',
displaying the string ccc if there is no exception frame on the
exception stack.

`abort'       ?? - ??         core,exception-ext       ``abort''
   `-1 throw'.

Defining Words
==============

   Defining words are used to extend Forth by creating new entries in
the dictionary.

`CREATE'
--------

   Defining words are used to create new entries in the dictionary. The
simplest defining word is `CREATE'. `CREATE' is used like this:

     CREATE new-word1

   `CREATE' is a parsing word, i.e., it takes an argument from the
input stream (`new-word1' in our example).  It generates a dictionary
entry for `new-word1'. When `new-word1' is executed, all that it does
is leave an address on the stack. The address represents the value of
the data space pointer (`HERE') at the time that `new-word1' was
defined. Therefore, `CREATE' is a way of associating a name with the
address of a region of memory.

`Create'       "name" -         core       ``Create''

   Note that in ANS Forth guarantees only for `create' that its body is
in dictionary data space (i.e., where `here', `allot' etc. work, *note
Dictionary allocation::).  Also, in ANS Forth only `create'd words can
be modified with `does>' (*note User-defined Defining Words::).  And in
ANS Forth `>body' can only be applied to `create'd words.

   By extending this example to reserve some memory in data space, we
end up with something like a variable. Here are two different ways to do
it:

     CREATE new-word2 1 cells allot  \ reserve 1 cell - initial value undefined
     CREATE new-word3 4 ,            \ reserve 1 cell and initialise it (to 4)

   The variable can be examined and modified using `@' ("fetch") and
`!' ("store") like this:

     new-word2 @ .      \ get address, fetch from it and display
     1234 new-word2 !   \ new value, get address, store to it

   A similar mechanism can be used to create arrays. For example, an
80-character text input buffer:

     CREATE text-buf 80 chars allot
     
     text-buf 0 chars c@ \ the 1st character (offset 0)
     text-buf 3 chars c@ \ the 4th character (offset 3)

   You can build arbitrarily complex data structures by allocating
appropriate areas of memory. For further discussions of this, and to
learn about some Gforth tools that make it easier, *Note Structures::.

Variables
---------

   The previous section showed how a sequence of commands could be used
to generate a variable.  As a final refinement, the whole code sequence
can be wrapped up in a defining word (pre-empting the subject of the
next section), making it easier to create new variables:

     : myvariableX ( "name" -- a-addr ) CREATE 1 cells allot ;
     : myvariable0 ( "name" -- a-addr ) CREATE 0 , ;
     
     myvariableX foo \ variable foo starts off with an unknown value
     myvariable0 joe \ whilst joe is initialised to 0
     
     45 3 * foo !   \ set foo to 135
     1234 joe !     \ set joe to 1234
     3 joe +!       \ increment joe by 3.. to 1237

   Not surprisingly, there is no need to define `myvariable', since
Forth already has a definition `Variable'. ANS Forth does not guarantee
that a `Variable' is initialised when it is created (i.e., it may
behave like `myvariableX'). In contrast, Gforth's `Variable'
initialises the variable to 0 (i.e., it behaves exactly like
`myvariable0'). Forth also provides `2Variable' and `fvariable' for
double and floating-point variables, respectively - they are
initialised to 0. and 0e in Gforth. If you use a `Variable' to store a
boolean, you can use `on' and `off' to toggle its state.

`Variable'       "name" -         core       ``Variable''

`2Variable'       "name" -         double       ``two-variable''

`fvariable'       "name" -         float       ``f-variable''

   The defining word `User' behaves in the same way as `Variable'.  The
difference is that it reserves space in user (data) space rather than
normal data space. In a Forth system that has a multi-tasker, each task
has its own set of user variables.

`User'       "name" -         gforth       ``User''

Constants
---------

   `Constant' allows you to declare a fixed value and refer to it by
name. For example:

     12 Constant INCHES-PER-FOOT
     3E+08 fconstant SPEED-O-LIGHT

   A `Variable' can be both read and written, so its run-time behaviour
is to supply an address through which its current value can be
manipulated. In contrast, the value of a `Constant' cannot be changed
once it has been declared(1) so it's not necessary to supply the
address - it is more efficient to return the value of the constant
directly. That's exactly what happens; the run-time effect of a
constant is to put its value on the top of the stack (You can find one
way of implementing `Constant' in *Note User-defined Defining Words::).

   Forth also provides `2Constant' and `fconstant' for defining double
and floating-point constants, respectively.

`Constant'       w "name" -         core       ``Constant''
   Define a constant name with value w.

   name execution: - w

`2Constant'       w1 w2 "name" -         double       ``two-constant''

`fconstant'       r "name" -         float       ``f-constant''

   Constants in Forth behave differently from their equivalents in other
programming languages. In other languages, a constant (such as an EQU in
assembler or a #define in C) only exists at compile-time; in the
executable program the constant has been translated into an absolute
number and, unless you are using a symbolic debugger, it's impossible to
know what abstract thing that number represents. In Forth a constant has
an entry in the header space and remains there after the code that uses
it has been defined. In fact, it must remain in the dictionary since it
has run-time duties to perform. For example:

     12 Constant INCHES-PER-FOOT
     : FEET-TO-INCHES ( n1 -- n2 ) INCHES-PER-FOOT * ;

   When `FEET-TO-INCHES' is executed, it will in turn execute the xt
associated with the constant `INCHES-PER-FOOT'. If you use `see' to
decompile the definition of `FEET-TO-INCHES', you can see that it makes
a call to `INCHES-PER-FOOT'. Some Forth compilers attempt to optimise
constants by in-lining them where they are used. You can force Gforth
to in-line a constant like this:

     : FEET-TO-INCHES ( n1 -- n2 ) [ INCHES-PER-FOOT ] LITERAL * ;

   If you use `see' to decompile this version of `FEET-TO-INCHES', you
can see that `INCHES-PER-FOOT' is no longer present. To understand how
this works, read *Note Interpret/Compile states::, and *Note Literals::.

   In-lining constants in this way might improve execution time
fractionally, and can ensure that a constant is now only referenced at
compile-time. However, the definition of the constant still remains in
the dictionary. Some Forth compilers provide a mechanism for controlling
a second dictionary for holding transient words such that this second
dictionary can be deleted later in order to recover memory space.
However, there is no standard way of doing this.

   ---------- Footnotes ----------

   (1) Well, often it can be - but not in a Standard, portable way.
It's safer to use a `Value' (read on).

Values
------

   A `Value' behaves like a `Constant', but it can be changed.  `TO' is
a parsing word that changes a `Values'.  In Gforth (not in ANS Forth)
you can access (and change) a `value' also with `>body'.

   Here are some examples:

     12 Value APPLES     \ Define APPLES with an initial value of 12
     34 TO APPLES        \ Change the value of APPLES. TO is a parsing word
     1 ' APPLES >body +! \ Increment APPLES.  Non-standard usage.
     APPLES              \ puts 35 on the top of the stack.

`Value'       w "name" -         core-ext       ``Value''

`TO'       w "name" -         core-ext       ``TO''

Colon Definitions
-----------------

     : name ( ... -- ... )
         word1 word2 word3 ;

Creates a word called `name' that, upon execution, executes `word1
word2 word3'. `name' is a "(colon) definition".

   The explanation above is somewhat superficial. For simple examples of
colon definitions see *Note Your first definition::.  For an in-depth
discussion of some of the issues involved, *Note Interpretation and
Compilation Semantics::.

`:'       "name" - colon-sys         core       ``colon''

`;'       compilation colon-sys - ; run-time nest-sys         core       ``semicolon''

Anonymous Definitions
---------------------

   Sometimes you want to define an "anonymous word"; a word without a
name. You can do this with:

`:noname'       - xt colon-sys         core-ext       ``colon-no-name''

   This leaves the execution token for the word on the stack after the
closing `;'. Here's an example in which a deferred word is initialised
with an `xt' from an anonymous colon definition:

     Defer deferred
     :noname ( ... -- ... )
       ... ;
     IS deferred

Gforth provides an alternative way of doing this, using two separate
words:

`noname'       -         gforth       ``noname''
   The next defined word will be anonymous. The defining word will
leave the input stream alone. The xt of the defined word will be given
by `lastxt'.

`lastxt'       - xt         gforth       ``lastxt''
   xt is the execution token of the last word defined.

The previous example can be rewritten using `noname' and `lastxt':

     Defer deferred
     noname : ( ... -- ... )
       ... ;
     lastxt IS deferred

`noname' works with any defining word, not just `:'.

   `lastxt' also works when the last word was not defined as `noname'.
It does not work for combined words, though.  It also has the useful
property that is is valid as soon as the header for a definition has
been built. Thus:

     lastxt . : foo [ lastxt . ] ; ' foo .

prints 3 numbers; the last two are the same.

Supplying the name of a defined word
------------------------------------

   By default, a defining word takes the name for the defined word from
the input stream. Sometimes you want to supply the name from a string.
You can do this with:

`nextname'       c-addr u -         gforth       ``nextname''
   The next defined word will have the name C-ADDR U; the defining word
will leave the input stream alone.

   For example:

     s" foo" nextname create

is equivalent to:

     create foo

`nextname' works with any defining word.

User-defined Defining Words
---------------------------

   You can create a new defining word by wrapping defining-time code
around an existing defining word and putting the sequence in a colon
definition.

   For example, suppose that you have a word `stats' that gathers
statistics about colon definitions given the xt of the definition, and
you want every colon definition in your application to make a call to
`stats'. You can define and use a new version of `:' like this:

     : stats ( xt -- ) DUP ." (Gathering statistics for " . ." )"
       ... ;  \ other code
     
     : my: : lastxt postpone literal ['] stats compile, ;
     
     my: foo + - ;

   When `foo' is defined using `my:' these steps occur:

   * `my:' is executed.

   * The `:' within the definition (the one between `my:' and `lastxt')
     is executed, and does just what it always does; it parses the
     input stream for a name, builds a dictionary header for the name
     `foo' and switches `state' from interpret to compile.

   * The word `lastxt' is executed. It puts the xt for the word that is
     being defined - `foo' - onto the stack.

   * The code that was produced by `postpone literal' is executed; this
     causes the value on the stack to be compiled as a literal in the
     code area of `foo'.

   * The code `['] stats' compiles a literal into the definition of
     `my:'. When `compile,' is executed, that literal - the execution
     token for `stats' - is layed down in the code area of `foo' ,
     following the literal(1).

   * At this point, the execution of `my:' is complete, and control
     returns to the text interpreter. The text interpreter is in compile
     state, so subsequent text `+ -' is compiled into the definition of
     `foo' and the `;' terminates the definition as always.

   You can use `see' to decompile a word that was defined using `my:'
and see how it is different from a normal `:' definition. For example:

     : bar + - ;  \ like foo but using : rather than my:
     see bar
     : bar
       + - ;
     see foo
     : foo
       107645672 stats + - ;
     
     \ use ' stats . to show that 107645672 is the xt for stats

   You can use techniques like this to make new defining words in terms
of any existing defining word.

   If you want the words defined with your defining words to behave
differently from words defined with standard defining words, you can
write your defining word like this:

     : def-word ( "name" -- )
         CREATE code1
     DOES> ( ... -- ... )
         code2 ;
     
     def-word name

   This fragment defines a "defining word" `def-word' and then executes
it.  When `def-word' executes, it `CREATE's a new word, `name', and
executes the code code1. The code code2 is not executed at this time.
The word `name' is sometimes called a "child" of `def-word'.

   When you execute `name', the address of the body of `name' is put on
the data stack and code2 is executed (the address of the body of `name'
is the address `HERE' returns immediately after the `CREATE', i.e., the
address a `create'd word returns by default).

   You can use `def-word' to define a set of child words that behave
similarly; they all have a common run-time behaviour determined by
code2. Typically, the code1 sequence builds a data area in the body of
the child word. The structure of the data is common to all children of
`def-word', but the data values are specific - and private - to each
child word. When a child word is executed, the address of its private
data area is passed as a parameter on TOS to be used and manipulated(2)
by code2.

   The two fragments of code that make up the defining words act (are
executed) at two completely separate times:

   * At define time, the defining word executes code1 to generate a
     child word

   * At child execution time, when a child word is invoked, code2 is
     executed, using parameters (data) that are private and specific to
     the child word.

   Another way of understanding the behaviour of `def-word' and `name'
is to say that, if you make the following definitions:
     : def-word1 ( "name" -- )
         CREATE code1 ;
     
     : action1 ( ... -- ... )
         code2 ;
     
     def-word1 name1

Then using `name1 action1' is equivalent to using `name'.

   The classic example is that you can define `CONSTANT' in this way:

     : CONSTANT ( w "name" -- )
         CREATE ,
     DOES> ( -- w )
         @ ;

   When you create a constant with `5 CONSTANT five', a set of
define-time actions take place; first a new word `five' is created,
then the value 5 is laid down in the body of `five' with `,'. When
`five' is executed, the address of the body is put on the stack, and
`@' retrieves the value 5. The word `five' has no code of its own; it
simply contains a data field and a pointer to the code that follows
`DOES>' in its defining word. That makes words created in this way very
compact.

   The final example in this section is intended to remind you that
space reserved in `CREATE'd words is data space and therefore can be
both read and written by a Standard program(3):

     : foo ( "name" -- )
         CREATE -1 ,
     DOES> ( -- )
         @ . ;
     
     foo first-word
     foo second-word
     
     123 ' first-word >BODY !

   If `first-word' had been a `CREATE'd word, we could simply have
executed it to get the address of its data field. However, since it was
defined to have `DOES>' actions, its execution semantics are to perform
those `DOES>' actions. To get the address of its data field it's
necessary to use `'' to get its xt, then `>BODY' to translate the xt
into the address of the data field.  When you execute `first-word', it
will display `123'. When you execute `second-word' it will display `-1'.

   In the examples above the stack comment after the `DOES>' specifies
the stack effect of the defined words, not the stack effect of the
following code (the following code expects the address of the body on
the top of stack, which is not reflected in the stack comment). This is
the convention that I use and recommend (it clashes a bit with using
locals declarations for stack effect specification, though).

   ---------- Footnotes ----------

   (1) Strictly speaking, the mechanism that `compile,' uses to convert
an xt into something in the code area is implementation-dependent. A
threaded implementation might spit out the execution token directly
whilst another implementation might spit out a native code sequence.

   (2) It is legitimate both to read and write to this data area.

   (3) Exercise: use this example as a starting point for your own
implementation of `Value' and `TO' - if you get stuck, investigate the
behaviour of `'' and `[']'.

Applications of `CREATE..DOES>'
...............................

   You may wonder how to use this feature. Here are some usage patterns:

   When you see a sequence of code occurring several times, and you can
identify a meaning, you will factor it out as a colon definition. When
you see similar colon definitions, you can factor them using
`CREATE..DOES>'. E.g., an assembler usually defines several words that
look very similar:
     : ori, ( reg-target reg-source n -- )
         0 asm-reg-reg-imm ;
     : andi, ( reg-target reg-source n -- )
         1 asm-reg-reg-imm ;

This could be factored with:
     : reg-reg-imm ( op-code -- )
         CREATE ,
     DOES> ( reg-target reg-source n -- )
         @ asm-reg-reg-imm ;
     
     0 reg-reg-imm ori,
     1 reg-reg-imm andi,

   Another view of `CREATE..DOES>' is to consider it as a crude way to
supply a part of the parameters for a word (known as "currying" in the
functional language community). E.g., `+' needs two parameters.
Creating versions of `+' with one parameter fixed can be done like this:

     : curry+ ( n1 "name" -- )
         CREATE ,
     DOES> ( n2 -- n1+n2 )
         @ + ;
     
      3 curry+ 3+
     -2 curry+ 2-

The gory details of `CREATE..DOES>'
...................................

`DOES>'       compilation colon-sys1 - colon-sys2 ; run-time nest-sys -         core       ``does''

   This means that you need not use `CREATE' and `DOES>' in the same
definition; you can put the `DOES>'-part in a separate definition. This
allows us to, e.g., select among different `DOES>'-parts:
     : does1
     DOES> ( ... -- ... )
         ... ;
     
     : does2
     DOES> ( ... -- ... )
         ... ;
     
     : def-word ( ... -- ... )
         create ...
         IF
            does1
         ELSE
            does2
         ENDIF ;

   In this example, the selection of whether to use `does1' or `does2'
is made at definition-time; at the time that the child word is
`CREATE'd.

   In a standard program you can apply a `DOES>'-part only if the last
word was defined with `CREATE'. In Gforth, the `DOES>'-part will
override the behaviour of the last word defined in any case. In a
standard program, you can use `DOES>' only in a colon definition. In
Gforth, you can also use it in interpretation state, in a kind of
one-shot mode; for example:
     CREATE name ( ... -- ... )
       initialization
     DOES>
       code ;

is equivalent to the standard:
     :noname
     DOES>
         code ;
     CREATE name EXECUTE ( ... -- ... )
         initialization

`>body'       xt - a-addr        core       ``to-body''
    Get the address of the body of the word represented by xt (the
address of the word's data field).

Advanced does> usage example
............................

   The MIPS disassembler (`arch/mips/disasm.fs') contains many words
for disassembling instructions, that follow a very repetetive scheme:

     :noname DISASM-OPERANDS s" INST-NAME" type ;
     ENTRY-NUM cells TABLE + !

   Of course, this inspires the idea to factor out the commonalities to
allow a definition like

     DISASM-OPERANDS ENTRY-NUM TABLE define-inst INST-NAME

   The parameters DISASM-OPERANDS and TABLE are usually correlated.
Moreover, before I wrote the disassembler, there already existed code
that defines instructions like this:

     ENTRY-NUM INST-FORMAT INST-NAME

   This code comes from the assembler and resides in
`arch/mips/insts.fs'.

   So I had to define the INST-FORMAT words that performed the scheme
above when executed.  At first I chose to use run-time code-generation:

     : INST-FORMAT ( entry-num "name" -- ; compiled code: addr w -- )
       :noname Postpone DISASM-OPERANDS
       name Postpone sliteral Postpone type Postpone ;
       swap cells TABLE + ! ;

   Note that this supplies the other two parameters of the scheme above.

   An alternative would have been to write this using `create'/`does>':

     : INST-FORMAT ( entry-num "name" -- )
       here name string, ( entry-num c-addr ) \ parse and save "name"
       noname create , ( entry-num )
       lastxt swap cells TABLE + !
     does> ( addr w -- )
       \ disassemble instruction w at addr
       @ >r
       DISASM-OPERANDS
       r> count type ;

   Somehow the first solution is simpler, mainly because it's simpler to
shift a string from definition-time to use-time with `sliteral' than
with `string,' and friends.

   I wrote a lot of words following this scheme and soon thought about
factoring out the commonalities among them.  Note that this uses a
two-level defining word, i.e., a word that defines ordinary defining
words.

   This time a solution involving `postpone' and friends seemed more
difficult (try it as an exercise), so I decided to use a
`create'/`does>' word; since I was already at it, I also used
`create'/`does>' for the lower level (try using `postpone' etc. as an
exercise), resulting in the following definition:

     : define-format ( disasm-xt table-xt -- )
         \ define an instruction format that uses disasm-xt for
         \ disassembling and enters the defined instructions into table
         \ table-xt
         create 2,
     does> ( u "inst" -- )
         \ defines an anonymous word for disassembling instruction inst,
         \ and enters it as u-th entry into table-xt
         2@ swap here name string, ( u table-xt disasm-xt c-addr ) \ remember string
         noname create 2,      \ define anonymous word
         execute lastxt swap ! \ enter xt of defined word into table-xt
     does> ( addr w -- )
         \ disassemble instruction w at addr
         2@ >r ( addr w disasm-xt R: c-addr )
         execute ( R: c-addr ) \ disassemble operands
         r> count type ; \ print name

   Note that the tables here (in contrast to above) do the `cells +' by
themselves (that's why you have to pass an xt).  This word is used in
the following way:

     ' DISASM-OPERANDS ' TABLE define-format INST-FORMAT

   As shown above, the defined instruction format is then used like
this:

     ENTRY-NUM INST-FORMAT INST-NAME

   In terms of currying, this kind of two-level defining word provides
the parameters in three stages: first DISASM-OPERANDS and TABLE, then
ENTRY-NUM and INST-NAME, finally `addr w', i.e., the instruction to be
disassembled.

   Of course this did not quite fit all the instruction format names
used in `insts.fs', so I had to define a few wrappers that conditioned
the parameters into the right form.

   If you have trouble following this section, don't worry.  First,
this is involved and takes time (and probably some playing around) to
understand; second, this is the first two-level `create'/`does>' word I
have written in seventeen years of Forth; and if I did not have
`insts.fs' to start with, I may well have elected to use just a
one-level defining word (with some repeating of parameters when using
the defining word). So it is not necessary to understand this, but it
may improve your understanding of Forth.

Deferred words
--------------

   The defining word `Defer' allows you to define a word by name
without defining its behaviour; the definition of its behaviour is
deferred. Here are two situation where this can be useful:

   * Where you want to allow the behaviour of a word to be altered
     later, and for all precompiled references to the word to change
     when its behaviour is changed.

   * For mutual recursion; *Note Calls and returns::.

   In the following example, `foo' always invokes the version of
`greet' that prints "`Good morning'" whilst `bar' always invokes the
version that prints "`Hello'". There is no way of getting `foo' to use
the later version without re-ordering the source code and recompiling
it.

     : greet ." Good morning" ;
     : foo ... greet ... ;
     : greet ." Hello" ;
     : bar ... greet ... ;

   This problem can be solved by defining `greet' as a `Defer'red word.
The behaviour of a `Defer'red word can be defined and redefined at any
time by using `IS' to associate the xt of a previously-defined word
with it. The previous example becomes:

     Defer greet ( -- )
     : foo ... greet ... ;
     : bar ... greet ... ;
     : greet1 ( -- ) ." Good morning" ;
     : greet2 ( -- ) ." Hello" ;
     ' greet2 <IS> greet  \ make greet behave like greet2

   Programming style note: You should write a stack comment for every
deferred word, and put only XTs into deferred words that conform to
this stack effect.  Otherwise it's too difficult to use the deferred
word.

   A deferred word can be used to improve the statistics-gathering
example from *Note User-defined Defining Words::; rather than edit the
application's source code to change every `:' to a `my:', do this:

     : real: : ;     \ retain access to the original
     defer :         \ redefine as a deferred word
     ' my: <IS> :      \ use special version of :
     \
     \ load application here
     \
     ' real: <IS> :    \ go back to the original

   One thing to note is that `<IS>' consumes its name when it is
executed.  If you want to specify the name at compile time, use `[IS]':

     : set-greet ( xt -- )
       [IS] greet ;
     
     ' greet1 set-greet

   A deferred word can only inherit execution semantics from the xt
(because that is all that an xt can represent - for more discussion of
this *note Tokens for Words::); by default it will have default
interpretation and compilation semantics deriving from this execution
semantics.  However, you can change the interpretation and compilation
semantics of the deferred word in the usual ways:

     : bar .... ; compile-only
     Defer fred immediate
     Defer jim
     
     ' bar <IS> jim  \ jim has default semantics
     ' bar <IS> fred \ fred is immediate

`Defer'       "name" -         gforth       ``Defer''

`<IS>'       "name" xt -         gforth       ``<IS>''
   Changes the `defer'red word NAME to execute XT.

`[IS]'       compilation "name" - ; run-time xt -         gforth       ``bracket-is''
   At run-time, changes the `defer'red word NAME to execute XT.

`IS'       xt "name" -         gforth       ``IS''
   A combined word made up from `<IS>' and `[IS]'.

`What's'       interpretation "name" - xt; compilation "name" - ; run-time - xt         gforth       ``What's''
   Xt is the XT that is currently assigned to name.

`Defers'       compilation "name" - ; run-time ... - ...         gforth       ``Defers''
   Compiles the present contents of the deferred word name into the
current definition.  I.e., this produces static binding as if name was
not deferred.

   Definitions in ANS Forth for `defer', `<is>' and `[is]' are provided
in `compat/defer.fs'.

Aliases
-------

   The defining word `Alias' allows you to define a word by name that
has the same behaviour as some other word. Here are two situation where
this can be useful:

   * When you want access to a word's definition from a different word
     list (for an example of this, see the definition of the `Root'
     word list in the Gforth source).

   * When you want to create a synonym; a definition that can be known
     by either of two names (for example, `THEN' and `ENDIF' are
     aliases).

   Like deferred words, an alias has default compilation and
interpretation semantics at the beginning (not the modifications of the
other word), but you can change them in the usual ways (`immediate',
`compile-only'). For example:

     : foo ... ; immediate
     
     ' foo Alias bar \ bar is not an immediate word
     ' foo Alias fooby immediate \ fooby is an immediate word

   Words that are aliases have the same xt, different headers in the
dictionary, and consequently different name tokens (*note Tokens for
Words::) and possibly different immediate flags.  An alias can only have
default or immediate compilation semantics; you can define aliases for
combined words with `interpret/compile:' - see *Note Combined words::.

`Alias'       xt "name" -         gforth       ``Alias''

Interpretation and Compilation Semantics
========================================

   The "interpretation semantics" of a (named) word are what the text
interpreter does when it encounters the word in interpret state. It also
appears in some other contexts, e.g., the execution token returned by
`' word' identifies the interpretation semantics of word (in other
words, `' word execute' is equivalent to interpret-state text
interpretation of `word').

   The "compilation semantics" of a (named) word are what the text
interpreter does when it encounters the word in compile state. It also
appears in other contexts, e.g, `POSTPONE word' compiles(1) the
compilation semantics of word.

   The standard also talks about "execution semantics". They are used
only for defining the interpretation and compilation semantics of many
words. By default, the interpretation semantics of a word are to
`execute' its execution semantics, and the compilation semantics of a
word are to `compile,' its execution semantics.(2)

   Unnamed words (*note Anonymous Definitions::) cannot be encountered
by the text interpreter, ticked, or `postpone'd, so they have no
interpretation or compilation semantics.  Their behaviour is represented
by their XT (*note Tokens for Words::), and we call it execution
semantics, too.

   You can change the semantics of the most-recently defined word:

`immediate'       -         core       ``immediate''
   Make the compilation semantics of a word be to `execute' the
execution semantics.

`compile-only'       -         gforth       ``compile-only''
   Remove the interpretation semantics of a word.

`restrict'       -         gforth       ``restrict''
   A synonym for `compile-only'

   By convention, words with non-default compilation semantics (e.g.,
immediate words) often have names surrounded with brackets (e.g.,
`[']', *note Execution token::).

   Note that ticking (`'') a compile-only word gives an error
("Interpreting a compile-only word").

   ---------- Footnotes ----------

   (1) In standard terminology, "appends to the current definition".

   (2) In standard terminology: The default interpretation semantics
are its execution semantics; the default compilation semantics are to
append its execution semantics to the execution semantics of the current
definition.

Combined Words
--------------

   Gforth allows you to define "combined words" - words that have an
arbitrary combination of interpretation and compilation semantics.

`interpret/compile:'       interp-xt comp-xt "name" -         gforth       ``interpret/compile:''

   This feature was introduced for implementing `TO' and `S"'. I
recommend that you do not define such words, as cute as they may be:
they make it hard to get at both parts of the word in some contexts.
E.g., assume you want to get an execution token for the compilation
part. Instead, define two words, one that embodies the interpretation
part, and one that embodies the compilation part.  Once you have done
that, you can define a combined word with `interpret/compile:' for the
convenience of your users.

   You might try to use this feature to provide an optimizing
implementation of the default compilation semantics of a word. For
example, by defining:
     :noname
        foo bar ;
     :noname
        POSTPONE foo POSTPONE bar ;
     interpret/compile: opti-foobar

as an optimizing version of:

     : foobar
         foo bar ;

   Unfortunately, this does not work correctly with `[compile]',
because `[compile]' assumes that the compilation semantics of all
`interpret/compile:' words are non-default. I.e., `[compile]
opti-foobar' would compile compilation semantics, whereas `[compile]
foobar' would compile interpretation semantics.

   Some people try to use "state-smart" words to emulate the feature
provided by `interpret/compile:' (words are state-smart if they check
`STATE' during execution). E.g., they would try to code `foobar' like
this:

     : foobar
       STATE @
       IF ( compilation state )
         POSTPONE foo POSTPONE bar
       ELSE
         foo bar
       ENDIF ; immediate

   Although this works if `foobar' is only processed by the text
interpreter, it does not work in other contexts (like `'' or
`POSTPONE'). E.g., `' foobar' will produce an execution token for a
state-smart word, not for the interpretation semantics of the original
`foobar'; when you execute this execution token (directly with
`EXECUTE' or indirectly through `COMPILE,') in compile state, the
result will not be what you expected (i.e., it will not perform `foo
bar'). State-smart words are a bad idea. Simply don't write them(1)!

   It is also possible to write defining words that define words with
arbitrary combinations of interpretation and compilation semantics. In
general, they look like this:

     : def-word
         create-interpret/compile
         code1
     interpretation>
         code2
     <interpretation
     compilation>
         code3
     <compilation ;

   For a word defined with `def-word', the interpretation semantics are
to push the address of the body of word and perform code2, and the
compilation semantics are to push the address of the body of word and
perform code3. E.g., `constant' can also be defined like this (except
that the defined constants don't behave correctly when `[compile]'d):

     : constant ( n "name" -- )
         create-interpret/compile
         ,
     interpretation> ( -- n )
         @
     <interpretation
     compilation> ( compilation. -- ; run-time. -- n )
         @ postpone literal
     <compilation ;

`create-interpret/compile'       "name" -         gforth       ``create-interpret/compile''

`interpretation>'       compilation. - orig colon-sys         gforth       ``interpretation>''

`<interpretation'       compilation. orig colon-sys -         gforth       ``<interpretation''

`compilation>'       compilation. - orig colon-sys         gforth       ``compilation>''

`<compilation'       compilation. orig colon-sys -         gforth       ``<compilation''

   Words defined with `interpret/compile:' and
`create-interpret/compile' have an extended header structure that
differs from other words; however, unless you try to access them with
plain address arithmetic, you should not notice this. Words for
accessing the header structure usually know how to deal with this; e.g.,
`'' word `>body' also gives you the body of a word created with
`create-interpret/compile'.

   ---------- Footnotes ----------

   (1) For a more detailed discussion of this topic, see M. Anton Ertl,
``State'-smartness--Why it is Evil and How to Exorcise it
(http://www.complang.tuwien.ac.at/papers/ertl98.ps.gz)', EuroForth '98.

Tokens for Words
================

   This section describes the creation and use of tokens that represent
words.

Execution token
---------------

   An "execution token" (XT) represents some behaviour of a word.  You
can use `execute' to invoke this behaviour.

   You can use `'' to get an execution token that represents the
interpretation semantics of a named word:

     5 ' .
     execute

`''       "name" - xt         core       ``tick''
   xt represents name's interpretation semantics. Perform `-14 throw'
if the word has no interpretation semantics.

   `'' parses at run-time; there is also a word `[']' that parses when
it is compiled, and compiles the resulting XT:

     : foo ['] . execute ;
     5 foo
     : bar ' execute ; \ by contrast,
     5 bar .           \ ' parses "." when bar executes

`[']'       compilation. "name" - ; run-time. - xt         core       ``bracket-tick''
   xt represents name's interpretation semantics. Perform `-14 throw'
if the word has no interpretation semantics.

   If you want the execution token of word, write `['] word' in
compiled code and `' word' in interpreted code.  Gforth's `'' and `[']'
behave somewhat unusually by complaining about compile-only words
(because these words have no interpretation semantics).  You might get
what you want by using `COMP' word DROP' or `[COMP'] word DROP' (for
details *note Compilation token::).

   Another way to get an XT is `:noname' or `lastxt' (*note Anonymous
Definitions::).  For anonymous words this gives an xt for the only
behaviour the word has (the execution semantics).  For named words,
`lastxt' produces an XT for the same behaviour it would produce if the
word was defined anonymously.

     :noname ." hello" ;
     execute

   An XT occupies one cell and can be manipulated like any other cell.

   In ANS Forth the XT is just an abstract data type (i.e., defined by
the operations that produce or consume it).  For old hands: In Gforth,
the XT is implemented as a code field address (CFA).

`execute'       xt -        core       ``execute''
   Perform the semantics represented by the execution token, xt.

`perform'       a-addr -        gforth       ``perform''
   `@ execute'.

Compilation token
-----------------

   Gforth represents the compilation semantics of a named word by a
"compilation token" consisting of two cells: w xt. The top cell xt is
an execution token. The compilation semantics represented by the
compilation token can be performed with `execute', which consumes the
whole compilation token, with an additional stack effect determined by
the represented compilation semantics.

   At present, the w part of a compilation token is an execution token,
and the xt part represents either `execute' or `compile,'(1). However,
don't rely on that knowledge, unless necessary; future versions of
Gforth may introduce unusual compilation tokens (e.g., a compilation
token that represents the compilation semantics of a literal).

   You can perform the compilation semantics represented by the
compilation token with `execute'.  You can compile the compilation
semantics with `postpone,'. I.e., `COMP' word postpone,' is equivalent
to `postpone word'.

`[COMP']'       compilation "name" - ; run-time - w xt         gforth       ``bracket-comp-tick''
   Compilation token w xt represents name's compilation semantics.

`COMP''       "name" - w xt         gforth       ``comp-tick''
   Compilation token w xt represents name's compilation semantics.

`postpone,'       w xt -         gforth       ``postpone-comma''
   Compile the compilation semantics represented by the compilation
token w xt.

   ---------- Footnotes ----------

   (1) Depending upon the compilation semantics of the word. If the
word has default compilation semantics, the xt will represent
`compile,'. Otherwise (e.g., for immediate words), the xt will
represent `execute'.

Name token
----------

   Gforth represents named words by the "name token", (nt). In Gforth,
the abstract data type _name token_ is implemented as a name field
address (NFA).

`find-name'       c-addr u - nt | 0         gforth       ``find-name''
   Find the name c-addr u in the current search order. Return its nt,
if found, otherwise 0.

`name>int'       nt - xt         gforth       ``name>int''
   xt represents the interpretation semantics of the word nt. If nt has
no interpretation semantics (i.e. is `compile-only'), xt is the
execution token for `compile-only-error', which performs `-14 throw'.

`name?int'       nt - xt         gforth       ``name?int''
   Like `name>int', but perform `-14 throw' if nt has no interpretation
semantics.

`name>comp'       nt - w xt         gforth       ``name>comp''
   w xt is the compilation token for the word nt.

`name>string'       nt - addr count         gforth       ``head-to-string''
   addr count is the name of the word represented by nt.

Compiling words
===============

   In contrast to most other languages, Forth has no strict boundary
between compilation and run-time.  E.g., you can run arbitrary code
between defining words (or for computing data used by defining words
like `constant'). Moreover, `Immediate' (*note Interpretation and
Compilation Semantics:: and `['...`]' (see below) allow running
arbitrary code while compiling a colon definition (exception: you must
not allot dictionary space).

Literals
--------

   The simplest and most frequent example is to compute a literal during
compilation.  E.g., the following definition prints an array of strings,
one string per line:

     : .strings ( addr u -- ) \ gforth
         2* cells bounds U+DO
     	cr i 2@ type
         2 cells +LOOP ;

   With a simple-minded compiler like Gforth's, this computes `2 cells'
on every loop iteration.  You can compute this value once and for all
at compile time and compile it into the definition like this:

     : .strings ( addr u -- ) \ gforth
         2* cells bounds U+DO
     	cr i 2@ type
         [ 2 cells ] literal +LOOP ;

   `[' switches the text interpreter to interpret state (you will get
an `ok' prompt if you type this example interactively and insert a
newline between `[' and `]'), so it performs the interpretation
semantics of `2 cells'; this computes a number.  `]' switches the text
interpreter back into compile state.  It then performs `Literal''s
compilation semantics, which are to compile this number into the
current word.  You can decompile the word with `see .strings' to see
the effect on the compiled code.

   You can also optimize the `2* cells' into `[ 2 cells ] literal *' in
this way.

`['       -         core       ``left-bracket''
   Enter interpretation state. Immediate word.

`]'       -         core       ``right-bracket''
   Enter compilation state.

`Literal'       compilation n - ; run-time - n         core       ``Literal''
   Compilation semantics: compile the run-time semantics.
Run-time Semantics: push n.
Interpretation semantics: undefined.

`]L'       compilation: n - ; run-time: - n         gforth       ``]L''
   equivalent to `] literal'

   There are also words for compiling other data types than single
cells as literals:

`2Literal'       compilation w1 w2 - ; run-time  - w1 w2         double       ``two-literal''
   Compile appropriate code such that, at run-time, cell pair w1, w2 are
placed on the stack. Interpretation semantics are undefined.

`FLiteral'       compilation r - ; run-time - r         float       ``f-literal''
   Compile appropriate code such that, at run-time, r is placed on the
(floating-point) stack. Interpretation semantics are undefined.

`SLiteral'       Compilation c-addr1 u ; run-time - c-addr2 u         string       ``SLiteral''
   Compilation: compile the string specified by c-addr1, u into the
current definition. Run-time: return c-addr2 u describing the address
and length of the string.

   You might be tempted to pass data from outside a colon definition to
the inside on the data stack.  This does not work, because `:' puhes a
colon-sys, making stuff below unaccessible.  E.g., this does not work:

     5 : foo literal ; \ error: "unstructured"

   Instead, you have to pass the value in some other way, e.g., through
a variable:

     variable temp
     5 temp !
     : foo [ temp @ ] literal ;

Macros
------

   `Literal' and friends compile data values into the current
definition.  You can also write words that compile other words into the
current definition.  E.g.,

     : compile-+ ( -- ) \ compiled code: ( n1 n2 -- n )
       POSTPONE + ;
     
     : foo ( n1 n2 -- n )
       [ compile-+ ] ;
     1 2 foo .

   This is equivalent to `: foo + ;' (`see foo' to check this).  What
happens in this example?  `Postpone' compiles the compilation semantics
of `+' into `compile-+'; later the text interpreter executes
`compile-+' and thus the compilation semantics of +, which compile (the
execution semantics of) `+' into `foo'.(1)

`POSTPONE'       "name" -         core       ``POSTPONE''
   Compiles the compilation semantics of name.

`[compile]'       compilation "name" - ; run-time ? - ?         core-ext       ``bracket-compile''

   Compiling words like `compile-+' are usually immediate (or similar)
so you do not have to switch to interpret state to execute them;
mopifying the last example accordingly produces:

     : [compile-+] ( compilation: --; interpretation: -- )
       \ compiled code: ( n1 n2 -- n )
       POSTPONE + ; immediate
     
     : foo ( n1 n2 -- n )
       [compile-+] ;
     1 2 foo .

   Immediate compiling words are similar to macros in other languages
(in particular, Lisp).  The important differences to macros in, e.g., C
are:

   * You use the same language for defining and processing macros, not a
     separate preprocessing language and processor.

   * Consequently, the full power of Forth is available in macro
     definitions.  E.g., you can perform arbitrarily complex
     computations, or generate different code conditionally or in a
     loop (e.g., *note Advanced macros Tutorial::).  This power is very
     useful when writing a parser generators or other code-generating
     software.

   * Macros defined using `postpone' etc. deal with the language at a
     higher level than strings; name binding happens at macro definition
     time, so you can avoid the pitfalls of name collisions that can
     happen in C macros.  Of course, Forth is a liberal language and
     also allows to shoot yourself in the foot with text-interpreted
     macros like

          : [compile-+] s" +" evaluate ; immediate

     Apart from binding the name at macro use time, using `evaluate'
     also makes your definition `state'-smart (*note state-smartness::).

   You may want the macro to compile a number into a word.  The word to
do it is `literal', but you have to `postpone' it, so its compilation
semantics take effect when the macro is executed, not when it is
compiled:

     : [compile-5] ( -- ) \ compiled code: ( -- n )
       5 POSTPONE literal ; immediate
     
     : foo [compile-5] ;
     foo .

   You may want to pass parameters to a macro, that the macro should
compile into the current definition.  If the parameter is a number, then
you can use `postpone literal' (similar for other values).

   If you want to pass a word that is to be compiled, the usual way is
to pass an execution token and `compile,' it:

     : twice1 ( xt -- ) \ compiled code: ... -- ...
       dup compile, compile, ;
     
     : 2+ ( n1 -- n2 )
       [ ' 1+ twice1 ] ;

`compile,'       xt -         core-ext       ``compile-comma''
    Compile the word represented by the execution token xt  into the
current definition.

   An alternative available in Gforth, that allows you to pass
compile-only words as parameters is to use the compilation token (*note
Compilation token::).  The same example in this technique:

     : twice ( ... ct -- ... ) \ compiled code: ... -- ...
       2dup 2>r execute 2r> execute ;
     
     : 2+ ( n1 -- n2 )
       [ comp' 1+ twice ] ;

   In the example above `2>r' and `2r>' ensure that `twice' works even
if the executed compilation semantics has an effect on the data stack.

   You can also define complete definitions with these words; this
provides an alternative to using `does>' (*note User-defined Defining
Words::).  E.g., instead of

     : curry+ ( n1 "name" -- )
         CREATE ,
     DOES> ( n2 -- n1+n2 )
         @ + ;

   you could define

     : curry+ ( n1 "name" -- )
       \ name execution: ( n2 -- n1+n2 )
       >r : r> POSTPONE literal POSTPONE + POSTPONE ; ;
     
     -3 curry+ 3-
     see 3-

   The sequence `>r : r>' is necessary, because `:' puts a colon-sys on
the data stack that makes everything below it unaccessible.

   This way of writing defining words is sometimes more, sometimes less
convenient than using `does>' (*note Advanced does> usage example::).
One advantage of this method is that it can be optimized better,
because the compiler knows that the value compiled with `literal' is
fixed, whereas the data associated with a `create'd word can be changed.

   ---------- Footnotes ----------

   (1) A recent RFI answer requires that compiling words should only be
executed in compile state, so this example is not guaranteed to work on
all standard systems, but on any decent system it will work.

The Text Interpreter
====================

   The text interpreter(1) is an endless loop that processes input from
the current input device. It is also called the outer interpreter, in
contrast to the inner interpreter (*note Engine::) which executes the
compiled Forth code on interpretive implementations.

   The text interpreter operates in one of two states: "interpret
state" and "compile state". The current state is defined by the
aptly-named variable `state'.

   This section starts by describing how the text interpreter behaves
when it is in interpret state, processing input from the user input
device - the keyboard. This is the mode that a Forth system is in after
it starts up.

   The text interpreter works from an area of memory called the "input
buffer"(2), which stores your keyboard input when you press the <RET>
key. Starting at the beginning of the input buffer, it skips leading
spaces (called "delimiters") then parses a string (a sequence of
non-space characters) until it reaches either a space character or the
end of the buffer. Having parsed a string, it makes two attempts to
process it:

   * It looks for the string in a "dictionary" of definitions. If the
     string is found, the string names a "definition" (also known as a
     "word") and the dictionary search returns information that allows
     the text interpreter to perform the word's "interpretation
     semantics". In most cases, this simply means that the word will be
     executed.

   * If the string is not found in the dictionary, the text interpreter
     attempts to treat it as a number, using the rules described in
     *Note Number Conversion::. If the string represents a legal number
     in the current radix, the number is pushed onto a parameter stack
     (the data stack for integers, the floating-point stack for
     floating-point numbers).

   If both attempts fail, or if the word is found in the dictionary but
has no interpretation semantics(3) the text interpreter discards the
remainder of the input buffer, issues an error message and waits for
more input. If one of the attempts succeeds, the text interpreter
repeats the parsing process until the whole of the input buffer has been
processed, at which point it prints the status message "` ok'" and
waits for more input.

   The text interpreter keeps track of its position in the input buffer
by updating a variable called `>IN' (pronounced "to-in"). The value of
`>IN' starts out as 0, indicating an offset of 0 from the start of the
input buffer. The region from offset `>IN @' to the end of the input
buffer is called the "parse area"(4).  This example shows how `>IN'
changes as the text interpreter parses the input buffer:

     : remaining >IN @ SOURCE 2 PICK - -ROT + SWAP
       CR ." ->" TYPE ." <-" ; IMMEDIATE
     
     1 2 3 remaining + remaining .
     
     : foo 1 2 3 remaining SWAP remaining ;

The result is:

     ->+ remaining .<-
     ->.<-5  ok
     
     ->SWAP remaining ;-<
     ->;<-  ok

   The value of `>IN' can also be modified by a word in the input
buffer that is executed by the text interpreter.  This means that a word
can "trick" the text interpreter into either skipping a section of the
input buffer(5) or into parsing a section twice. For example:

     : lat ." <<foo>>" ;
     : flat ." <<bar>>" >IN DUP @ 3 - SWAP ! ;

When `flat' is executed, this output is produced(6):

     <<bar>><<foo>>

   This technique can be used to work around some of the
interoperability problems of parsing words.  Of course, it's better to
avoid parsing words where possible.

Two important notes about the behaviour of the text interpreter:

   * It processes each input string to completion before parsing
     additional characters from the input buffer.

   * It treats the input buffer as a read-only region (and so must your
     code).

When the text interpreter is in compile state, its behaviour changes in
these ways:

   * If a parsed string is found in the dictionary, the text
     interpreter will perform the word's "compilation semantics". In
     most cases, this simply means that the execution semantics of the
     word will be appended to the current definition.

   * When a number is encountered, it is compiled into the current
     definition (as a literal) rather than being pushed onto a
     parameter stack.

   * If an error occurs, `state' is modified to put the text interpreter
     back into interpret state.

   * Each time a line is entered from the keyboard, Gforth prints "`
     compiled'" rather than " `ok'".

   When the text interpreter is using an input device other than the
keyboard, its behaviour changes in these ways:

   * When the parse area is empty, the text interpreter attempts to
     refill the input buffer from the input source. When the input
     source is exhausted, the input source is set back to the previous
     input source.

   * It doesn't print out "` ok'" or "` compiled'" messages each time
     the parse area is emptied.

   * If an error occurs, the input source is set back to the user input
     device.

   You can read about this in more detail in *Note Input Sources::.

`>in'       - a-addr         core       ``to-in''
   `User' variable - a-addr is the address of a cell containing the
char offset from the start of the input buffer to the start of the
parse area.

`source'       - c-addr u         core       ``source''
   c-addr is the address of the input buffer and u is the number of
characters in it.

`tib'       - c-addr         core-ext       ``t-i-b''
   c-addr is the address of the Terminal Input Buffer.  OBSOLESCENT:
`source' superceeds the function of this word.

`#tib'       - a-addr         core-ext       ``number-t-i-b''
   `User' variable - a-addr is the address of a cell containing the
number of characters in the terminal input buffer.  OBSOLESCENT:
`source' superceeds the function of this word.

   ---------- Footnotes ----------

   (1) This is an expanded version of the material in *Note Introducing
the Text Interpreter::.

   (2) When the text interpreter is processing input from the keyboard,
this area of memory is called the "terminal input buffer" (TIB) and is
addressed by the (obsolescent) words `TIB' and `#TIB'.

   (3) This happens if the word was defined as `COMPILE-ONLY'.

   (4) In other words, the text interpreter processes the contents of
the input buffer by parsing strings from the parse area until the parse
area is empty.

   (5) This is how parsing words work.

   (6) Exercise for the reader: what would happen if the `3' were
replaced with `4'?

Input Sources
-------------

   By default, the text interpreter processes input from the user input
device (the keyboard) when Forth starts up. The text interpreter can
process input from any of these sources:

   * The user input device - the keyboard.

   * A file, using the words described in *Note Forth source files::.

   * A block, using the words described in *Note Blocks::.

   * A text string, using `evaluate'.

   A program can identify the current input device from the values of
`source-id' and `blk'.

`source-id'       - 0 | -1 | fileid         core-ext,file       ``source-i-d''
   Return 0 (the input source is the user input device), -1 (the input
source is a string being processed by `evaluate') or a fileid (the
input source is the file specified by fileid).

`blk'       - a-addr         block       ``b-l-k''
   `User' variable - a-addr is the address of a cell containing zero
(in which case the input source is not a block and can be identified by
`source-id') or the number of the block currently being interpreted. A
Standard program should not alter `blk' directly.

`save-input'       - xn .. x1 n         core-ext       ``save-input''
   The n entries xn - x1 describe the current state of the input source
specification, in some platform-dependent way that can be used by
`restore-input'.

`restore-input'       xn .. x1 n - flag         core-ext       ``restore-input''
   Attempt to restore the input source specification to the state
described by the n entries xn - x1. flag is true if the restore fails.
In Gforth it fails pretty often (and sometimes with a `throw').

`evaluate'       c-addr u -         core,block       ``evaluate''
   Save the current input source specification. Store `-1' in
`source-id' and `0' in `blk'. Set `>IN' to `0' and make the string
c-addr u the input source and input buffer. Interpret. When the parse
area is empty, restore the input source specification.

Number Conversion
-----------------

   This section describes the rules that the text interpreter uses when
it tries to convert a string into a number.

   Let <digit> represent any character that is a legal digit in the
current number base(1).

   Let <decimal digit> represent any character in the range 0-9.

   Let {a b} represent the optional presence of any of the characters
in the braces (a or b or neither).

   Let * represent any number of instances of the previous character
(including none).

   Let any other character represent itself.

Now, the conversion rules are:

   * A string of the form <digit><digit>* is treated as a
     single-precision (cell-sized) positive integer. Examples are 0 123
     6784532 32343212343456 42

   * A string of the form -<digit><digit>* is treated as a
     single-precision (cell-sized) negative integer, and is represented
     using 2's-complement arithmetic. Examples are -45 -5681 -0

   * A string of the form <digit><digit>*.<digit>* is treated as a
     double-precision (double-cell-sized) positive integer. Examples
     are 3465. 3.465 34.65 (all three of these represent the same
     number).

   * A string of the form -<digit><digit>*.<digit>* is treated as a
     double-precision (double-cell-sized) negative integer, and is
     represented using 2's-complement arithmetic. Examples are -3465.
     -3.465 -34.65 (all three of these represent the same number).

   * A string of the form {+ -}<decimal digit>{.}<decimal digit>*{e
     E}{+ -}<decimal digit><decimal digit>* is treated as a
     floating-point number. Examples are 1e 1e0 1.e 1.e0 +1e+0 (which
     all represent the same number) +12.E-4

   By default, the number base used for integer number conversion is
given by the contents of the variable `base'.  Note that a lot of
confusion can result from unexpected values of `base'.  If you change
`base' anywhere, make sure to save the old value and restore it
afterwards.  In general I recommend keeping `base' decimal, and using
the prefixes described below for the popular non-decimal bases.

`dpl'       - a-addr         gforth       ``dpl''
   `User' variable - a-addr is the address of a cell that stores the
position of the decimal point in the most recent numeric conversion.
Initialised to -1. After the conversion of a number containing no
decimal point, ` dpl' is -1. After the conversion of `2.' it holds 0.
After the conversion of 234123.9 it contains 1, and so forth.

`base'       - a-addr         core       ``base''
   `User' variable - a-addr is the address of a cell that stores the
number base used by default for number conversion during input and
output.

`hex'       -         core-ext       ``hex''
   Set `base' to &16 (hexadecimal).

`decimal'       -         core       ``decimal''
   Set `base' to &10 (decimal).

   Gforth allows you to override the value of `base' by using a
prefix(2) before the first digit of an (integer) number. Four prefixes
are supported:

   * `&' - decimal

   * `%' - binary

   * `$' - hexadecimal

   * `'' - base `max-char+1'

   Here are some examples, with the equivalent decimal number shown
after in braces:

   -$41 (-65), %1001101 (205), %1001.0001 (145 - a double-precision
number), 'AB (16706; ascii A is 65, ascii B is 66, number is 65*256 +
66), 'ab (24930; ascii a is 97, ascii B is 98, number is 97*256 + 98),
&905 (905), $abc (2478), $ABC (2478).

Number conversion has a number of traps for the unwary:

   * You cannot determine the current number base using the code
     sequence `base @ .' - the number base is always 10 in the current
     number base. Instead, use something like `base @ dec.'

   * If the number base is set to a value greater than 14 (for example,
     hexadecimal), the number 123E4 is ambiguous; the conversion rules
     allow it to be intepreted as either a single-precision integer or a
     floating-point number (Gforth treats it as an integer). The
     ambiguity can be resolved by explicitly stating the sign of the
     mantissa and/or exponent: 123E+4 or +123E4 - if the number base is
     decimal, no ambiguity arises; either representation will be
     treated as a floating-point number.

   * There is a word `bin' but it does not set the number base!  It is
     used to specify file types.

   * ANS Forth requires the `.' of a double-precision number to be the
     final character in the string.  Gforth allows the `.' to be
     anywhere after the first digit.

   * The number conversion process does not check for overflow.

   * In an ANS Forth program `base' is required to be decimal when
     converting floating-point numbers.  In Gforth, number conversion to
     floating-point numbers always uses base &10, irrespective of the
     value of `base'.

   You can read numbers into your programs with the words described in
*Note Input::.

   ---------- Footnotes ----------

   (1) For example, 0-9 when the number base is decimal or 0-9, A-F
when the number base is hexadecimal.

   (2) Some Forth implementations provide a similar scheme by
implementing `$' etc. as parsing words that process the subsequent
number in the input stream and push it onto the stack. For example, see
`Number Conversion and Literals', by Wil Baden; Forth Dimensions 20(3)
pages 26-27. In such implementations, unlike in Gforth, a space is
required between the prefix and the number.

Interpret/Compile states
------------------------

   A standard program is not permitted to change `state' explicitly.
However, it can change `state' implicitly, using the words `[' and `]'.
When `[' is executed it switches `state' to interpret state, and
therefore the text interpreter starts interpreting. When `]' is
executed it switches `state' to compile state and therefore the text
interpreter starts compiling. The most common usage for these words is
for switching into interpret state and back from within a colon
definition; this technique can be used to compile a literal (for an
example, *note Literals::) or for conditional compilation (for an
example, *note Interpreter Directives::).

   `[' and `]' also give you the ability to switch into compile state
and back, but we cannot think of any useful Standard application for
this ability. Pre-ANS Forth textbooks have examples like this:

     : AA ." this is A" ;
     : BB ." this is B" ;
     : CC ." this is C" ;
     
     create table ] aa bb cc [
     
     : go ( n -- ) \ n is offset into table.. 0 for 1st entry
       cells table +  execute ;

   This example builds a jump table; `0 go' will display "`this is A'".
Using `[' and `]' in this example is equivalent to defining `table'
like this:

     create table ' aa COMPILE, ' bb COMPILE, ' cc COMPILE,

   The problem with this code is that the definition of `table' is not
portable - it compiles execution tokens into code space. Whilst it may
work on systems where code space and data space co-incide, the Standard
only allows data space to be assigned for a `CREATE'd word. In
addition, the Standard only allows `@' to access data space, whilst
this example is using it to access code space. The only portable,
Standard way to build this table is to build it in data space, like
this:

     create table ' aa , ' bb , ' cc ,

`state'       - a-addr         core,tools-ext       ``state''
   `User' variable - a-addr is the address of a cell containing the
compilation state flag. 0 => interpreting, -1 => compiling.  A program
shall not directly alter the value of `state'. The following Standard
words alter the value in `state': `:' (colon) `;' (semicolon) `abort'
`quit' `:noname' `[' (left-bracket) `]' (right-bracket) `;code'. Don't
use `state'! For an alternative see *Note Interpretation and
Compilation Semantics::.

Interpreter Directives
----------------------

   These words are usually used in interpret state; typically to control
which parts of a source file are processed by the text interpreter.
There are only a few ANS Forth Standard words, but Gforth supplements
these with a rich set of immediate control structure words to
compensate for the fact that the non-immediate versions can only be
used in compile state (*note Control Structures::). Typical usages:

     FALSE Constant HAVE-ASSEMBLER
     .
     .
     HAVE-ASSEMBLER [IF]
     : ASSEMBLER-FEATURE
       ...
     ;
     [ENDIF]
     .
     .
     : SEE
       ... \ general-purpose SEE code
       [ HAVE-ASSEMBLER [IF] ]
       ... \ assembler-specific SEE code
       [ [ENDIF] ]
     ;

`[IF]'       flag | flag "<spaces>name ..." -         tools-ext       ``bracket-if''
   If flag is `TRUE' do nothing (and therefore execute subsequent words
as normal). If flag is `FALSE', parse and discard words from the parse
area (refilling it if necessary using `REFILL') including nested
instances of `[IF]'..  `[ELSE]'.. `[THEN]' and `[IF]'.. `[THEN]' until
the balancing `[ELSE]' or `[THEN]' has been parsed and discarded.
Immediate word.

`[ELSE]'       "<spaces>name ..." -         tools-ext       ``bracket-else''
   Parse and discard words from the parse area (refilling it if
necessary using `REFILL') including nested instances of `[IF]'..
`[ELSE]'.. `[THEN]' and `[IF]'.. `[THEN]' until the balancing `[THEN]'
has been parsed and discarded.  `[ELSE]' only gets executed if the
balancing `[IF]' was `TRUE'; if it was `FALSE', `[IF]' would have
parsed and discarded the `[ELSE]', leaving the subsequent words to be
executed as normal.  Immediate word.

`[THEN]'       -         tools-ext       ``bracket-then''
   Do nothing; used as a marker for other words to parse and discard up
to. Immediate word.

`[ENDIF]'       -         gforth       ``bracket-end-if''
   Do nothing; synonym for `[THEN]'

`[IFDEF]'       "<spaces>name" -         gforth       ``bracket-if-def''
   If name is found in the current search-order, behave like `[IF]'
with a `TRUE' flag, otherwise behave like `[IF]' with a `FALSE' flag.
Immediate word.

`[IFUNDEF]'       "<spaces>name" -         gforth       ``bracket-if-un-def''
   If name is not found in the current search-order, behave like `[IF]'
with a `TRUE' flag, otherwise behave like `[IF]' with a `FALSE' flag.
Immediate word.

`[?DO]'       n-limit n-index -         gforth       ``bracket-question-do''

`[DO]'       n-limit n-index -         gforth       ``bracket-do''

`[FOR]'       n -         gforth       ``bracket-for''

`[LOOP]'       -         gforth       ``bracket-loop''

`[+LOOP]'       n -         gforth       ``bracket-question-plus-loop''

`[NEXT]'       n -         gforth       ``bracket-next''

`[BEGIN]'       -         gforth       ``bracket-begin''

`[UNTIL]'       flag -         gforth       ``bracket-until''

`[AGAIN]'       -         gforth       ``bracket-again''

`[WHILE]'       flag -         gforth       ``bracket-while''

`[REPEAT]'       -         gforth       ``bracket-repeat''

Word Lists
==========

   A wordlist is a list of named words; you can add new words and look
up words by name (and you can remove words in a restricted way with
markers).  Every named (and `reveal'ed) word is in one wordlist.

   The text interpreter searches the wordlists present in the search
order (a stack of wordlists), from the top to the bottom.  Within each
wordlist, the search starts conceptually at the newest word; i.e., if
two words in a wordlist have the same name, the newer word is found.

   New words are added to the "compilation wordlist" (aka current
wordlist).

   A word list is identified by a cell-sized word list identifier (wid)
in much the same way as a file is identified by a file handle. The
numerical value of the wid has no (portable) meaning, and might change
from session to session.

   The ANS Forth "Search order" word set is intended to provide a set of
low-level tools that allow various different schemes to be implemented.
Gforth also provides `vocabulary', a traditional Forth word.
`compat/vocabulary.fs' provides an implementation in ANS Forth.

`forth-wordlist'       - wid         search       ``forth-wordlist''
   `Constant' - wid identifies the word list that includes all of the
standard words provided by Gforth. When Gforth is invoked, this word
list is the compilation word list and is at the top of the search order.

`definitions'       -         search       ``definitions''
   Set the compilation word list to be the same as the word list that
is currently at the top of the search order.

`get-current'       - wid         search       ``get-current''
   wid is the identifier of the current compilation word list.

`set-current'       wid -         search       ``set-current''
   Set the compilation word list to the word list identified by wid.

`get-order'       - widn .. wid1 n         search       ``get-order''
   Copy the search order to the data stack. The current search order
has n entries, of which wid1 represents the wordlist that is searched
first (the word list at the top of the search order) and widn
represents the wordlist that is searched last.

`set-order'       widn .. wid1 n -         search       ``set-order''
   If N=0, empty the search order.  If N=-1, set the search order to
the implementation-defined minimum search order (for Gforth, this is
the word list `Root'). Otherwise, replace the existing search order
with the N wid entries such that WID1 represents the word list that
will be searched first and WIDN represents the word list that will be
searched last.

`wordlist'       - wid         search       ``wordlist''
   Create a new, empty word list represented by wid.

`table'       - wid         gforth       ``table''
   Create a case-sensitive wordlist.

`>order'       wid -         gforth       ``to-order''
   Push WID on the search order.

`previous'       -         search-ext       ``previous''
   Drop the wordlist at the top of the search order.

`also'       -         search-ext       ``also''
   Like `DUP' for the search order. Usually used before a vocabulary
(e.g., `also Forth'); the combined effect is to push the wordlist
represented by the vocabulary on the search order.

`Forth'       -         search-ext       ``Forth''
   Replace the wid at the top of the search order with the wid
associated with the word list `forth-wordlist'.

`Only'       -         search-ext       ``Only''
   Set the search order to the implementation-defined minimum search
order (for Gforth, this is the word list `Root').

`order'       -         search-ext       ``order''
   Print the search order and the compilation word list.  The word
lists are printed in the order in which they are searched (which is
reversed with respect to the conventional way of displaying stacks).
The compilation word list is displayed last.

`find'       c-addr - xt +-1 | c-addr 0         core,search       ``find''
   Search all word lists in the current search order for the definition
named by the counted string at c-addr.  If the definition is not found,
return 0. If the definition is found return 1 (if the definition has
non-default compilation semantics) or -1 (if the definition has default
compilation semantics).  The xt returned in interpret state represents
the interpretation semantics.  The xt returned in compile state
represented either the compilation semantics (for non-default
compilation semantics) or the run-time semantics that the compilation
semantics would `compile,' (for default compilation semantics).  The
ANS Forth standard does not specify clearly what the returned xt
represents (and also talks about immediacy instead of non-default
compilation semantics), so this word is questionable in portable
programs.  If non-portability is ok, `find-name' and friends are better
(*note Name token::).

`search-wordlist'       c-addr count wid - 0 | xt +-1         search       ``search-wordlist''
   Search the word list identified by wid for the definition named by
the string at c-addr count.  If the definition is not found, return 0.
If the definition is found return 1 (if the definition is immediate) or
-1 (if the definition is not immediate) together with the xt.  In
Gforth, the xt returned represents the interpretation semantics.  ANS
Forth does not specify clearly what xt represents.

`words'       -         tools       ``words''
   Display a list of all of the definitions in the word list at the top
of the search order.

`vlist'       -         gforth       ``vlist''
   Old (pre-Forth-83) name for `WORDS'.

`Root'       -         gforth       ``Root''
   Add the root wordlist to the search order stack.  This vocabulary
makes up the minimum search order and contains only a search-order
words.

`Vocabulary'       "name" -         gforth       ``Vocabulary''
   Create a definition "name" and associate a new word list with it.
The run-time effect of "name" is to replace the wid at the top of the
search order with the wid associated with the new word list.

`seal'       -         gforth       ``seal''
   Remove all word lists from the search order stack other than the word
list that is currently on the top of the search order stack.

`vocs'       -         gforth       ``vocs''
   List vocabularies and wordlists defined in the system.

`current'       - addr         gforth       ``current''
   `Variable' - holds the wid of the compilation word list.

`context'       - addr         gforth       ``context''
   `context' `@' is the wid of the word list at the top of the search
order.

Vocabularies
------------

   Here is an example of creating and using a new wordlist using ANS
Forth words:

     wordlist constant my-new-words-wordlist
     : my-new-words get-order nip my-new-words-wordlist swap set-order ;
     
     \ add it to the search order
     also my-new-words
     
     \ alternatively, add it to the search order and make it
     \ the compilation word list
     also my-new-words definitions
     \ type "order" to see the problem

   The problem with this example is that `order' has no way to
associate the name `my-new-words' with the wid of the word list (in
Gforth, `order' and `vocs' will display `???'  for a wid that has no
associated name). There is no Standard way of associating a name with a
wid.

   In Gforth, this example can be re-coded using `vocabulary', which
associates a name with a wid:

     vocabulary my-new-words
     
     \ add it to the search order
     also my-new-words
     
     \ alternatively, add it to the search order and make it
     \ the compilation word list
     my-new-words definitions
     \ type "order" to see that the problem is solved

Why use word lists?
-------------------

   Here are some reasons why people use wordlists:

   * To prevent a set of words from being used outside the context in
     which they are valid. Two classic examples of this are an
     integrated editor (all of the edit commands are defined in a
     separate word list; the search order is set to the editor word
     list when the editor is invoked; the old search order is restored
     when the editor is terminated) and an integrated assembler (the
     op-codes for the machine are defined in a separate word list which
     is used when a `CODE' word is defined).

   * To organize the words of an application or library into a
     user-visible set (in `forth-wordlist' or some other common
     wordlist) and a set of helper words used just for the
     implementation (hidden in a separate wordlist).  This keeps
     `words'' output smaller, separates implementation and interface,
     and reduces the chance of name conflicts within the common
     wordlist.

   * To prevent a name-space clash between multiple definitions with
     the same name. For example, when building a cross-compiler you
     might have a word `IF' that generates conditional code for your
     target system. By placing this definition in a different word list
     you can control whether the host system's `IF' or the target
     system's `IF' get used in any particular context by controlling
     the order of the word lists on the search order stack.


   The downsides of using wordlists are:

   * Debugging becomes more cumbersome.

   * Name conflicts worked around with wordlists are still there, and
     you have to arrange the search order carefully to get the desired
     results; if you forget to do that, you get hard-to-find errors (as
     in any case where you read the code differently from the compiler;
     `see' can help seeing which of several possible words the name
     resolves to in such cases).  `See' displays just the name of the
     words, not what wordlist they belong to, so it might be
     misleading.  Using unique names is a better approach to avoid name
     conflicts.

   * You have to explicitly undo any changes to the search order.  In
     many cases it would be more convenient if this happened
     implicitly.  Gforth currently does not provide such a feature, but
     it may do so in the future.

Word list example
-----------------

   The following example is from the garbage collector
(http://www.complang.tuwien.ac.at/forth/garbage-collection.zip) and
uses wordlists to separate public words from helper words:

     get-current ( wid )
     vocabulary garbage-collector also garbage-collector definitions
     ... \ define helper words
     ( wid ) set-current \ restore original (i.e., public) compilation wordlist
     ... \ define the public (i.e., API) words
         \ they can refer to the helper words
     previous \ restore original search order (helper words become invisible)

Environmental Queries
=====================

   ANS Forth introduced the idea of "environmental queries" as a way
for a program running on a system to determine certain characteristics
of the system.  The Standard specifies a number of strings that might
be recognised by a system.

   The Standard requires that the header space used for environmental
queries be distinct from the header space used for definitions.

   Typically, environmental queries are supported by creating a set of
definitions in a word list that is only used during environmental
queries; that is what Gforth does. There is no Standard way of adding
definitions to the set of recognised environmental queries, but any
implementation that supports the loading of optional word sets must have
some mechanism for doing this (after loading the word set, the
associated environmental query string must return `true'). In Gforth,
the word list used to honour environmental queries can be manipulated
just like any other word list.

`environment?'       c-addr u - false / ... true         core       ``environment-query''
   c-addr, u specify a counted string. If the string is not recognised,
return a `false' flag. Otherwise return a `true' flag and some
(string-specific) information about the queried string.

`environment-wordlist'       - wid         gforth       ``environment-wordlist''
   wid identifies the word list that is searched by environmental
queries.

`gforth'       - c-addr u         gforth-environment       ``gforth''
   Counted string representing a version string for this version of
Gforth (for versions>0.3.0).  The version strings of the various
versions are guaranteed to be ordered lexicographically.

`os-class'       - c-addr u         gforth-environment       ``os-class''
   Counted string representing a description of the host operating
system.

   Note that, whilst the documentation for (e.g.) `gforth' shows it
returning two items on the stack, querying it using `environment?' will
return an additional item; the `true' flag that shows that the string
was recognised.

   Here are some examples of using environmental queries:

     s" address-unit-bits" environment? 0=
     [IF]
          cr .( environmental attribute address-units-bits unknown... ) cr
     [ELSE]
          drop \ ensure balanced stack effect
     [THEN]
     
     \ this might occur in the prelude of a standard program that uses THROW
     s" exception" environment? [IF]
        0= [IF]
           : throw abort" exception thrown" ;
        [THEN]
     [ELSE] \ we don't know, so make sure
        : throw abort" exception thrown" ;
     [THEN]
     
     s" gforth" environment? [IF] .( Gforth version ) TYPE
                             [ELSE] .( Not Gforth..) [THEN]
     
     \ a program using v*
     s" gforth" environment? [IF]
       s" 0.5.0" compare 0< [IF] \ v* is a primitive since 0.5.0
        : v* ( f_addr1 nstride1 f_addr2 nstride2 ucount -- r )
          >r swap 2swap swap 0e r> 0 ?DO
            dup f over + 2swap dup f f* f+ over + 2swap
          LOOP
          2drop 2drop ;
       [THEN]
     [ELSE] \
       : v* ( f_addr1 nstride1 f_addr2 nstride2 ucount -- r )
       ...
     [THEN]

   Here is an example of adding a definition to the environment word
list:

     get-current environment-wordlist set-current
     true constant block
     true constant block-ext
     set-current

   You can see what definitions are in the environment word list like
this:

     environment-wordlist >order words previous

Files
=====

   Gforth provides facilities for accessing files that are stored in the
host operating system's file-system. Files that are processed by Gforth
can be divided into two categories:

   * Files that are processed by the Text Interpreter ("Forth source
     files").

   * Files that are processed by some other program ("general files").

Forth source files
------------------

   The simplest way to interpret the contents of a file is to use one of
these two formats:

     include mysource.fs
     s" mysource.fs" included

   You usually want to include a file only if it is not included already
(by, say, another source file). In that case, you can use one of these
three formats:

     require mysource.fs
     needs mysource.fs
     s" mysource.fs" required

   It is good practice to write your source files such that
interpreting them does not change the stack. Source files designed in
this way can be used with `required' and friends without complications.
For example:

     1024 require foo.fs drop

   Here you want to pass the argument 1024 (e.g., a buffer size) to
`foo.fs'.  Interpreting `foo.fs' has the stack effect ( n - n ), which
allows its use with `require'.  Of course with such parameters to
required files, you have to ensure that the first `require' fits for
all uses (i.e., `require' it early in the master load file).

`include-file'       i*x wfileid - j*x         file       ``include-file''

`included'       i*x c-addr u - j*x         file       ``included''
   `include-file' the file whose name is given by the string C-ADDR U.

`included?'       c-addr u - f         gforth       ``included?''
   True only if the file C-ADDR U is in the list of earlier included
files. If the file has been loaded, it may have been specified as, say,
`foo.fs' and found somewhere on the Forth search path. To return `true'
from `included?', you must specify the exact path to the file, even if
that is `./foo.fs'

`include'       ... "file" - ...         gforth       ``include''
   `include-file' the file FILE.

`required'       i*x addr u - j*x         gforth       ``required''
   `include-file' the file with the name given by ADDR U, if it is not
`included' (or `required') already. Currently this works by comparing
the name of the file (with path) against the names of earlier included
files.

`require'       ... "file" - ...         gforth       ``require''
   `include-file' FILE only if it is not included already.

`needs'       ... "name" - ...         gforth       ``needs''
   An alias for `require'; exists on other systems (e.g., Win32Forth).

`sourcefilename'       - c-addr u         gforth       ``sourcefilename''
   The name of the source file which is currently the input source.
The result is valid only while the file is being loaded.  If the
current input source is no (stream) file, the result is undefined.  In
Gforth, the result is valid during the whole seesion (but not across
`savesystem' etc.).

`sourceline#'       - u         gforth       ``sourceline-number''
   The line number of the line that is currently being interpreted from
a (stream) file. The first line has the number 1. If the current input
source is not a (stream) file, the result is undefined.

   A definition in ANS Forth for `required' is provided in
`compat/required.fs'.

General files
-------------

   Files are opened/created by name and type. The following file access
methods (FAMs) are recognised:

`r/o'       - fam         file       ``r-o''

`r/w'       - fam         file       ``r-w''

`w/o'       - fam         file       ``w-o''

`bin'       fam1 - fam2         file       ``bin''

   When a file is opened/created, it returns a file identifier, wfileid
that is used for all other file commands. All file commands also return
a status value, wior, that is 0 for a successful operation and an
implementation-defined non-zero value in the case of an error.

`open-file'       c-addr u wfam - wfileid wior        file       ``open-file''

`create-file'       c-addr u wfam - wfileid wior        file       ``create-file''

`close-file'       wfileid - wior        file       ``close-file''

`delete-file'       c-addr u - wior        file       ``delete-file''

`rename-file'       c-addr1 u1 c-addr2 u2 - wior        file-ext       ``rename-file''
   Rename file c_addr1 u1 to new name c_addr2 u2

`read-file'       c-addr u1 wfileid - u2 wior        file       ``read-file''

`read-line'       c-addr u1 wfileid - u2 flag wior        file       ``read-line''
   this is only for backward compatibility

`write-file'       c-addr u1 wfileid - wior        file       ``write-file''

`write-line'       c-addr u fileid - ior         file       ``write-line''

`emit-file'       c wfileid - wior        gforth       ``emit-file''

`flush-file'       wfileid - wior        file-ext       ``flush-file''

`file-status'       c-addr u - wfam wior        file-ext       ``file-status''

`file-position'       wfileid - ud wior        file       ``file-position''

`reposition-file'       ud wfileid - wior        file       ``reposition-file''

`file-size'       wfileid - ud wior        file       ``file-size''

`resize-file'       ud wfileid - wior        file       ``resize-file''

Search Paths
------------

   If you specify an absolute filename (i.e., a filename starting with
`/' or `~', or with `:' in the second position (as in `C:...')) for
`included' and friends, that file is included just as you would expect.

   If the filename starts with `./', this refers to the directory that
the present file was `included' from.  This allows files to include
other files relative to their own position (irrespective of the current
working directory or the absolute position).  This feature is essential
for libraries consisting of several files, where a file may include
other files from the library.  It corresponds to `#include "..."' in C.
If the current input source is not a file, `.' refers to the directory
of the innermost file being included, or, if there is no file being
included, to the current working directory.

   For relative filenames (not starting with `./'), Gforth uses a
search path similar to Forth's search order (*note Word Lists::). It
tries to find the given filename in the directories present in the path,
and includes the first one it finds. There are separate search paths for
Forth source files and general files.  If the search path contains the
directory `.', this refers to the directory of the current file, or the
working directory, as if the file had been specified with `./'.

   Use `~+' to refer to the current working directory (as in the
`bash').

Source Search Paths
...................

   The search path is initialized when you start Gforth (*note Invoking
Gforth::). You can display it and change it using `fpath' in
combination with the general path handling words.

`fpath'       - path-addr         gforth       ``fpath''

Here is an example of using `fpath' and `require':

     fpath path= /usr/lib/forth/|./
     require timer.fs

General Search Paths
....................

   Your application may need to search files in several directories,
like `included' does. To facilitate this, Gforth allows you to define
and use your own search paths, by providing generic equivalents of the
Forth search path words:

`open-path-file'       addr1 u1 path-addr - wfileid addr2 u2 0 | ior         gforth       ``open-path-file''
   Look in path PATH-ADDR for the file specified by ADDR1 U1.  If
found, the resulting path and and (read-only) open file descriptor are
returned. If the file is not found, IOR is non-zero.

`path-allot'       umax -         unknown       ``path-allot''
   `Allot' a path with umax characters capacity, initially empty.

`clear-path'       path-addr -         gforth       ``clear-path''
   Set the path path-addr to empty.

`also-path'       c-addr len path-addr -         gforth       ``also-path''
   add the directory c-addr len to path-addr.

`.path'       path-addr -         gforth       ``.path''
   Display the contents of the search path PATH-ADDR.

`path+'       path-addr  "dir" -         gforth       ``path+''
   Add the directory DIR to the search path PATH-ADDR.

`path='       path-addr "dir1|dir2|dir3"         gforth       ``path=''
   Make a complete new search path; the path separator is |.

   Here's an example of creating an empty search path:
     create mypath 500 path-allot \ maximum length 500 chars (is checked)

Blocks
======

   When you run Gforth on a modern desk-top computer, it runs under the
control of an operating system which provides certain services.  One of
these services is FILE SERVICES, which allows Forth source code and
data to be stored in files and read into Gforth (*note Files::).

   Traditionally, Forth has been an important programming language on
systems where it has interfaced directly to the underlying hardware with
no intervening operating system. Forth provides a mechanism, called
"blocks", for accessing mass storage on such systems.

   A block is a 1024-byte data area, which can be used to hold data or
Forth source code. No structure is imposed on the contents of the
block. A block is identified by its number; blocks are numbered
contiguously from 1 to an implementation-defined maximum.

   A typical system that used blocks but no operating system might use a
single floppy-disk drive for mass storage, with the disks formatted to
provide 256-byte sectors. Blocks would be implemented by assigning the
first four sectors of the disk to block 1, the second four sectors to
block 2 and so on, up to the limit of the capacity of the disk. The disk
would not contain any file system information, just the set of blocks.

   On systems that do provide file services, blocks are typically
implemented by storing a sequence of blocks within a single "blocks
file".  The size of the blocks file will be an exact multiple of 1024
bytes, corresponding to the number of blocks it contains. This is the
mechanism that Gforth uses.

   Only one blocks file can be open at a time. If you use block words
without having specified a blocks file, Gforth defaults to the blocks
file `blocks.fb'. Gforth uses the Forth search path when attempting to
locate a blocks file (*note Source Search Paths::).

   When you read and write blocks under program control, Gforth uses a
number of "block buffers" as intermediate storage. These buffers are
not used when you use `load' to interpret the contents of a block.

   The behaviour of the block buffers is analagous to that of a cache.
Each block buffer has three states:

   * Unassigned

   * Assigned-clean

   * Assigned-dirty

   Initially, all block buffers are unassigned. In order to access a
block, the block (specified by its block number) must be assigned to a
block buffer.

   The assignment of a block to a block buffer is performed by `block'
or `buffer'. Use `block' when you wish to modify the existing contents
of a block. Use `buffer' when you don't care about the existing
contents of the block(1).

   Once a block has been assigned to a block buffer using `block' or
`buffer', that block buffer becomes the current block buffer. Data may
only be manipulated (read or written) within the current block buffer.

   When the contents of the current block buffer has been modified it is
necessary, _before calling `block' or `buffer' again_, to either
abandon the changes (by doing nothing) or mark the block as changed
(assigned-dirty), using `update'. Using `update' does not change the
blocks file; it simply changes a block buffer's state to
assigned-dirty.  The block will be written implicitly when it's buffer
is needed for another block, or explicitly by `flush' or `save-buffers'.

   word `Flush' writes all assigned-dirty blocks back to the blocks
file on disk. Leaving Gforth with `bye' also performs a `flush'.

   In Gforth, `block' and `buffer' use a direct-mapped algorithm to
assign a block buffer to a block. That means that any particular block
can only be assigned to one specific block buffer, called (for the
particular operation) the victim buffer. If the victim buffer is
unassigned or assigned-clean it is allocated to the new block
immediately. If it is assigned-dirty its current contents are written
back to the blocks file on disk before it is allocated to the new block.

   Although no structure is imposed on the contents of a block, it is
traditional to display the contents as 16 lines each of 64 characters.
A block provides a single, continuous stream of input (for example, it
acts as a single parse area) - there are no end-of-line characters
within a block, and no end-of-file character at the end of a block.
There are two consequences of this:

   * The last character of one line wraps straight into the first
     character of the following line

   * The word `\' - comment to end of line - requires special
     treatment; in the context of a block it causes all characters
     until the end of the current 64-character "line" to be ignored.

   In Gforth, when you use `block' with a non-existent block number,
the current blocks file will be extended to the appropriate size and the
block buffer will be initialised with spaces.

   Gforth includes a simple block editor (type `use blocked.fb 0 list'
for details) but doesn't encourage the use of blocks; the mechanism is
only provided for backward compatibility - ANS Forth requires blocks to
be available when files are.

   Common techniques that are used when working with blocks include:

   * A screen editor that allows you to edit blocks without leaving the
     Forth environment.

   * Shadow screens; where every code block has an associated block
     containing comments (for example: code in odd block numbers,
     comments in even block numbers). Typically, the block editor
     provides a convenient mechanism to toggle between code and
     comments.

   * Load blocks; a single block (typically block 1) contains a number
     of `thru' commands which `load' the whole of the application.

   See Frank Sergeant's Pygmy Forth to see just how well blocks can be
integrated into a Forth programming environment.

`open-blocks'       c-addr u -         gforth       ``open-blocks''
   Use the file, whose name is given by c-addr u, as the blocks file.

`use'       "file" -         gforth       ``use''
   Use file as the blocks file.

`block-offset'       - addr         gforth       ``block-offset''
   User variable containing the number of the first block (default
since 0.5.0: 0).  Block files created with Gforth versions before 0.5.0
have the offset 1.  If you use these files you can: `1 offset !'; or
add 1 to every block number used; or prepend 1024 characters to the
file.

`get-block-fid'       - wfileid         gforth       ``get-block-fid''
   Return the file-id of the current blocks file. If no blocks file has
been opened, use `blocks.fb' as the default blocks file.

`block-position'       u -         block       ``block-position''
   Position the block file to the start of block u.

`list'       u -         block-ext       ``list''
   Display block u. In Gforth, the block is displayed as 16 numbered
lines, each of 64 characters.

`scr'       - a-addr         block-ext       ``s-c-r''
   `User' variable - a-addr is the address of a cell containing the
block number of the block most recently processed by `list'.

`block'       u - a-addr         block       ``block''
   If a block buffer is assigned for block u, return its start address,
a-addr. Otherwise, assign a block buffer for block u (if the assigned
block buffer has been `update'd, transfer the contents to mass
storage), read the block into the block buffer and return its start
address, a-addr.

`buffer'       u - a-addr         block       ``buffer''
   If a block buffer is assigned for block u, return its start address,
a-addr. Otherwise, assign a block buffer for block u (if the assigned
block buffer has been `update'd, transfer the contents to mass storage)
and return its start address, a-addr.  The subtle difference between
`buffer' and `block' mean that you should only use `buffer' if you
don't care about the previous contents of block u. In Gforth, this
simply calls `block'.

`empty-buffers'       -         block-ext       ``empty-buffers''
   Mark all block buffers as unassigned; if any had been marked as
assigned-dirty (by `update'), the changes to those blocks will be lost.

`empty-buffer'       buffer -         gforth       ``empty-buffer''

`update'       -         block       ``update''
   Mark the state of the current block buffer as assigned-dirty.

`updated?'       n - f         gforth       ``updated?''
   Return true if `updated' has been used to mark block n as
assigned-dirty.

`save-buffers'       -         block       ``save-buffers''
   Transfer the contents of each `update'd block buffer to mass
storage, then mark all block buffers as assigned-clean.

`save-buffer'       buffer -         gforth       ``save-buffer''

`flush'       -         block       ``flush''
   Perform the functions of `save-buffers' then `empty-buffers'.

`load'       i*x n - j*x         block       ``load''
   Save the current input source specification. Store n in `BLK', set
`>IN' to 0 and interpret. When the parse area is exhausted, restore the
input source specification.

`thru'       i*x n1 n2 - j*x         block-ext       ``thru''
   `load' the blocks n1 through n2 in sequence.

`+load'       i*x n - j*x         gforth       ``+load''
   Used within a block to load the block specified as the current block
+ n.

`+thru'       i*x n1 n2 - j*x         gforth       ``+thru''
   Used within a block to load the range of blocks specified as the
current block + n1 thru the current block + n2.

`-->'       -         gforth       ``chain''
   If this symbol is encountered whilst loading block n, discard the
remainder of the block and load block n+1. Used for chaining multiple
blocks together as a single loadable unit.  Not recommended, because it
destroys the independence of loading.  Use `thru' (which is standard)
or `+thru' instead.

`block-included'       a-addr u -         gforth       ``block-included''
   Use within a block that is to be processed by `load'. Save the
current blocks file specification, open the blocks file specified by
a-addr u and `load' block 1 from that file (which may in turn chain or
load other blocks). Finally, close the blocks file and restore the
original blocks file.

   ---------- Footnotes ----------

   (1) The ANS Forth definition of `buffer' is intended not to cause
disk I/O; if the data associated with the particular block is already
stored in a block buffer due to an earlier `block' command, `buffer'
will return that block buffer and the existing contents of the block
will be available. Otherwise, `buffer' will simply assign a new, empty
block buffer for the block.

Other I/O
=========

Simple numeric output
---------------------

   The simplest output functions are those that display numbers from the
data or floating-point stacks. Floating-point output is always displayed
using base 10. Numbers displayed from the data stack use the value
stored in `base'.

`.'       n -         core       ``dot''
   Display (the signed single number) N in free-format, followed by a
space.

`dec.'       n -         gforth       ``dec.''
   Display n as a signed decimal number, followed by a space.

`hex.'       u -         gforth       ``hex.''
   Display u as an unsigned hex number, prefixed with a "$" and
followed by a space.

`u.'       u -         core       ``u-dot''
   Display (the unsigned single number) U in free-format, followed by a
space.

`.r'       n1 n2 -         core-ext       ``dot-r''
   Display N1 right-aligned in a field N2 characters wide. If more than
N2 characters are needed to display the number, all digits are
displayed.  If appropriate, N2 must include a character for a leading
"-".

`u.r'       u n -         core-ext       ``u-dot-r''
   Display U right-aligned in a field N characters wide. If more than N
characters are needed to display the number, all digits are displayed.

`d.'       d -         double       ``d-dot''
   Display (the signed double number) D in free-format. followed by a
space.

`ud.'       ud -         gforth       ``u-d-dot''
   Display (the signed double number) UD in free-format, followed by a
space.

`d.r'       d n -         double       ``d-dot-r''
   Display D right-aligned in a field N characters wide. If more than N
characters are needed to display the number, all digits are displayed.
If appropriate, N must include a character for a leading "-".

`ud.r'       ud n -         gforth       ``u-d-dot-r''
   Display UD right-aligned in a field N characters wide. If more than
N characters are needed to display the number, all digits are displayed.

`f.'       r -         float-ext       ``f-dot''
   Display (the floating-point number) r without exponent, followed by
a space.

`fe.'       r -         float-ext       ``f-e-dot''
   Display r using engineering notation (with exponent dividable by 3),
followed by a space.

`fs.'       r -         float-ext       ``f-s-dot''
   Display r using scientific notation (with exponent), followed by a
space.

   Examples of printing the number 1234.5678E23 in the different
floating-point output formats are shown below:

     f. 123456779999999000000000000.
     fe. 123.456779999999E24
     fs. 1.23456779999999E26

Formatted numeric output
------------------------

   Forth traditionally uses a technique called "pictured numeric
output" for formatted printing of integers.  In this technique, digits
are extracted from the number (using the current output radix defined by
`base'), converted to ASCII codes and appended to a string that is
built in a scratch-pad area of memory (*note Implementation-defined
options: core-idef.). Arbitrary characters can be appended to the
string during the extraction process. The completed string is specified
by an address and length and can be manipulated (`TYPE'ed, copied,
modified) under program control.

   All of the integer output words described in the previous section
(*note Simple numeric output::) are implemented in Gforth using pictured
numeric output.

   Three important things to remember about pictured numeric output:

   * It always operates on double-precision numbers; to display a
     single-precision number, convert it first (for ways of doing this
     *note Double precision::).

   * It always treats the double-precision number as though it were
     unsigned. The examples below show ways of printing signed numbers.

   * The string is built up from right to left; least significant digit
     first.

`<#'       -         core       ``less-number-sign''
   Initialise/clear the pictured numeric output string.

`<<#'       -         gforth       ``less-less-number-sign''
   Start a hold area that ends with `#>>'. Can be nested in each other
and in `<#'.  Note: if you do not match up the `<<#'s with `#>>'s, you
will eventually run out of hold area; you can reset the hold area to
empty with `<#'.

`#'       ud1 - ud2         core       ``number-sign''
   Used within `<#' and `#>'. Add the next least-significant digit to
the pictured numeric output string. This is achieved by dividing UD1 by
the number in `base' to leave quotient UD2 and remainder N; N is
converted to the appropriate display code (eg ASCII code) and appended
to the string. If the number has been fully converted, UD1 will be 0
and `#' will append a "0" to the string.

`#s'       ud - 0 0         core       ``number-sign-s''
   Used within `<#' and `#>'. Convert all remaining digits using the
same algorithm as for `#'. `#s' will convert at least one digit.
Therefore, if UD is 0, `#s' will append a "0" to the pictured numeric
output string.

`hold'       char -         core       ``hold''
   Used within `<#' and `#>'. Append the character CHAR to the pictured
numeric output string.

`sign'       n -         core       ``sign''
   Used within `<#' and `#>'. If N (a SINGLE number) is negative,
append the display code for a minus sign to the pictured numeric output
string. Since the string is built up "backwards" this is usually used
immediately prior to `#>', as shown in the examples below.

`#>'       xd - addr u         core       ``number-sign-greater''
   Complete the pictured numeric output string by discarding XD and
returning ADDR U; the address and length of the formatted string. A
Standard program may modify characters within the string.

`#>>'       -         gforth       ``number-sign-greater-greater''
   Release the hold area started with `<<#'.

`represent'       r c-addr u - n f1 f2        float       ``represent''

Here are some examples of using pictured numeric output:

     : my-u. ( u -- )
       \ Simplest use of pns.. behaves like Standard u.
       0              \ convert to unsigned double
       <<#            \ start conversion
       #s             \ convert all digits
       #>             \ complete conversion
       TYPE SPACE     \ display, with trailing space
       #>> ;          \ release hold area
     
     : cents-only ( u -- )
       0              \ convert to unsigned double
       <<#            \ start conversion
       # #            \ convert two least-significant digits
       #>             \ complete conversion, discard other digits
       TYPE SPACE     \ display, with trailing space
       #>> ;          \ release hold area
     
     : dollars-and-cents ( u -- )
       0              \ convert to unsigned double
       <<#            \ start conversion
       # #            \ convert two least-significant digits
       [char] . hold  \ insert decimal point
       #s             \ convert remaining digits
       [char] $ hold  \ append currency symbol
       #>             \ complete conversion
       TYPE SPACE     \ display, with trailing space
       #>> ;          \ release hold area
     
     : my-. ( n -- )
       \ handling negatives.. behaves like Standard .
       s>d            \ convert to signed double
       swap over dabs \ leave sign byte followed by unsigned double
       <<#            \ start conversion
       #s             \ convert all digits
       rot sign       \ get at sign byte, append "-" if needed
       #>             \ complete conversion
       TYPE SPACE     \ display, with trailing space
       #>> ;          \ release hold area
     
     : account. ( n -- )
       \ accountants don't like minus signs, they use parentheses
       \ for negative numbers
       s>d            \ convert to signed double
       swap over dabs \ leave sign byte followed by unsigned double
       <<#            \ start conversion
       2 pick         \ get copy of sign byte
       0< IF [char] ) hold THEN \ right-most character of output
       #s             \ convert all digits
       rot            \ get at sign byte
       0< IF [char] ( hold THEN
       #>             \ complete conversion
       TYPE SPACE     \ display, with trailing space
       #>> ;          \ release hold area

   Here are some examples of using these words:

     1 my-u. 1
     hex -1 my-u. decimal FFFFFFFF
     1 cents-only 01
     1234 cents-only 34
     2 dollars-and-cents $0.02
     1234 dollars-and-cents $12.34
     123 my-. 123
     -123 my. -123
     123 account. 123
     -456 account. (456)

String Formats
--------------

   Forth commonly uses two different methods for representing character
strings:

   * As a "counted string", represented by a c-addr. The char addressed
     by c-addr contains a character-count, n, of the string and the
     string occupies the subsequent n char addresses in memory.

   * As cell pair on the stack; c-addr u, where u is the length of the
     string in characters, and c-addr is the address of the first byte
     of the string.

   ANS Forth encourages the use of the second format when representing
strings.

`count'       c-addr1 - c-addr2 u        core       ``count''
   c-addr2 is the first character and u the length of the counted
string at c-addr1.

   For words that move, copy and search for strings see *Note Memory
Blocks::. For words that display characters and strings see *Note
Displaying characters and strings::.

Displaying characters and strings
---------------------------------

   This section starts with a glossary of Forth words and ends with a
set of examples.

`bl'       - c-char         core       ``b-l''
   c-char is the character value for a space.

`space'       -         core       ``space''
   Display one space.

`spaces'       u -         core       ``spaces''
   Display N spaces.

`emit'       c -         core       ``emit''
   Display the character associated with character value c.

`toupper'       c1 - c2        gforth       ``toupper''
   If c1 is a lower-case character (in the current locale), c2 is the
equivalent upper-case character. All other characters are unchanged.

`."'       compilation 'ccc"' - ; run-time -         core       ``dot-quote''
   Compilation: Parse a string ccc delimited by a " (double quote). At
run-time, display the string. Interpretation semantics for this word
are undefined in ANS Forth. Gforth's interpretation semantics are to
display the string. This is the simplest way to display a string from
within a definition; see examples below.

`.('       compilation,interpretation "ccc<paren>" -         core-ext       ``dot-paren''
   Compilation and interpretation semantics: Parse a string ccc
delimited by a `)' (right parenthesis). Display the string. This is
often used to display progress information during compilation; see
examples below.

`type'       c-addr u -         core       ``type''
   If U>0, display U characters from a string starting with the
character stored at C-ADDR.

`typewhite'       addr u -         gforth       ``typewhite''
   Like type, but white space is printed instead of the characters.

`cr'       -         core       ``c-r''
   Output a newline (of the favourite kind of the host OS).  Note that
due to the way the Forth command line interpreter inserts newlines, the
preferred way to use `cr' is at the start of a piece of text; e.g., `cr
." hello, world"'.

`at-xy'       u1 u2 -         facility       ``at-x-y''
   Position the cursor so that subsequent text output will take place
at column U1, row U2 of the display. (column 0, row 0 is the top
left-hand corner of the display).

`page'       -         facility       ``page''
   Clear the display and set the cursor to the top left-hand corner.

`S"'       compilation 'ccc"' - ; run-time - c-addr u         core,file       ``s-quote''
   Compilation: Parse a string ccc delimited by a `"' (double quote).
At run-time, return the length, u, and the start address, c-addr of the
string. Interpretation: parse the string as before, and return c-addr,
u. The string is stored in a temporary buffer which may be overwritten
by subsequent uses of `S"'.

`C"'       compilation "ccc<quote>" - ; run-time  - c-addr         core-ext       ``c-quote''
   Compilation: parse a string ccc delimited by a `"' (double quote).
At run-time, return c-addr which specifies the counted string ccc.
Interpretation semantics are undefined.

`char'       '<spaces>ccc' - c         core       ``char''
   Skip leading spaces. Parse the string ccc and return c, the display
code representing the first character of ccc.

`[char]'       compilation '<spaces>ccc' - ; run-time - c         core       ``bracket-char''
   Compilation: skip leading spaces. Parse the string ccc. Run-time:
return c, the display code representing the first character of ccc.
Interpretation semantics for this word are undefined.

As an example, consider the following text, stored in a file `test.fs':

     .( text-1)
     : my-word
       ." text-2" cr
       .( text-3)
     ;
     
     ." text-4"
     
     : my-char
       [char] ALPHABET emit
       char emit
     ;

   When you load this code into Gforth, the following output is
generated:

     include test.fs <RET> text-1text-3text-4 ok

   * Messages `text-1' and `text-3' are displayed because `.(' is an
     immediate word; it behaves in the same way whether it is used
     inside or outside a colon definition.

   * Message `text-4' is displayed because of Gforth's added
     interpretation semantics for `."'.

   * Message `text-2' is not displayed, because the text interpreter
     performs the compilation semantics for `."' within the definition
     of `my-word'.

   Here are some examples of executing `my-word' and `my-char':

     my-word <RET> text-2
      ok
     my-char fred <RET> Af ok
     my-char jim <RET> Aj ok

   * Message `text-2' is displayed because of the run-time behaviour of
     `."'.

   * `[char]' compiles the "A" from "ALPHABET" and puts its display code
     on the stack at run-time. `emit' always displays the character
     when `my-char' is executed.

   * `char' parses a string at run-time and the second `emit' displays
     the first character of the string.

   * If you type `see my-char' you can see that `[char]' discarded the
     text "LPHABET" and only compiled the display code for "A" into the
     definition of `my-char'.

Input
-----

   For ways of storing character strings in memory see *Note String
Formats::.

`key'       - char         core       ``key''
   Receive (but do not display) one character, CHAR.

`key?'       - flag         facility       ``key-question''
   Determine whether a character is available. If a character is
available, FLAG is true; the next call to `key' will yield the
character. Once `key?' returns true, subsequent calls to `key?' before
calling `key' or `ekey' will also return true.

`ekey'       - u         facility-ext       ``e-key''

`ekey?'       - flag         facility-ext       ``e-key-question''
   Return `true' if a keyboard event is available (use `ekey' to
receive the event), `false' otherwise.

`ekey>char'       u - u false | c true         facility-ext       ``e-key-to-char''

`>number'       ud1 c-addr1 u1 - ud2 c-addr2 u2         core       ``to-number''
   Attempt to convert the character string C-ADDR1 U1 to an unsigned
number in the current number base. The double UD1 accumulates the
result of the conversion to form UD2. Conversion continues,
left-to-right, until the whole string is converted or a character that
is not convertable in the current number base is encountered (including
+ or -). For each convertable character, UD1 is first multiplied by the
value in `BASE' and then incremented by the value represented by the
character. C-ADDR2 is the location of the first unconverted character
(past the end of the string if the whole string was converted). U2 is
the number of unconverted characters in the string. Overflow is not
detected.

`>float'       c-addr u - flag        float       ``to-float''
   Actual stack effect: ( c_addr u - r t | f ).  Attempt to convert the
character string c-addr u to internal floating-point representation. If
the string represents a valid floating-point number r is placed on the
floating-point stack and flag is true. Otherwise, flag is false. A
string of blanks is a special case and represents the floating-point
number 0.

`accept'       c-addr +n1 - +n2         core       ``accept''
   Receive a string of at most +N2 characters, and store it in memory
starting at C-ADDR. The string is displayed. Input terminates when the
<return> key is pressed or N1 characters have been received. The normal
Gforth line editing capabilites are available. +N2 is the length of the
string; it does not include the <return> character.

`pad'       - c-addr         core-ext       ``pad''
   C-ADDR is the address of a transient region that can be used as
temporary data storage. At least 84 characters of space is available.

`parse'       char "ccc<char>" - c-addr u         core-ext       ``parse''
   Parse ccc, delimited by char, in the parse area. c-addr u specifies
the parsed string within the parse area. If the parse area was empty, u
is 0.

`word'       char "<chars>ccc<char>- c-addr         core       ``word''
   Skip leading delimiters. Parse ccc, delimited by char, in the parse
area. c-addr is the address of a transient region containing the parsed
string in counted-string format. If the parse area was empty or
contained no characters other than delimiters, the resulting string has
zero length. A program may replace characters within the counted
string. OBSOLESCENT: the counted string has a trailing space that is
not included in its length.

`sword'       char - addr len         gforth       ``s-word''
   Parses like `word', but the output is like `parse' output.  *Note
core-idef::.

`name'       - c-addr count         gforth       ``name''
   Get the next word from the input buffer

`refill'       - flag         core-ext,block-ext,file-ext       ``refill''
   Attempt to fill the input buffer from the input source.  When the
input source is the user input device, attempt to receive input into
the terminal input device. If successful, make the result the input
buffer, set `>IN' to 0 and return true; otherwise return false. When
the input source is a block, add 1 to the value of `BLK' to make the
next block the input source and current input buffer, and set `>IN' to
0; return true if the new value of `BLK' is a valid block number, false
otherwise. When the input source is a text file, attempt to read the
next line from the file. If successful, make the result the current
input buffer, set `>IN' to 0 and return true; otherwise, return false.
A successful result includes receipt of a line containing 0 characters.

`convert'       ud1 c-addr1 - ud2 c-addr2         core-ext       ``convert''
   OBSOLESCENT: superseded by `>number'.

`query'       -         core-ext       ``query''
   Make the user input device the input source. Receive input into the
Terminal Input Buffer. Set `>IN' to zero. OBSOLESCENT: superceeded by
`accept'.

`expect'       c-addr +n -         core-ext       ``expect''
   Receive a string of at most +n characters, and store it in memory
starting at c-addr. The string is displayed. Input terminates when the
<return> key is pressed or +n characters have been received. The normal
Gforth line editing capabilites are available. The length of the string
is stored in `span'; it does not include the <return> character.
OBSOLESCENT: superceeded by `accept'.

`span'       - c-addr         core-ext       ``span''
   `Variable' - c-addr is the address of a cell that stores the length
of the last string received by `expect'. OBSOLESCENT.

Locals
======

   Local variables can make Forth programming more enjoyable and Forth
programs easier to read. Unfortunately, the locals of ANS Forth are
laden with restrictions. Therefore, we provide not only the ANS Forth
locals wordset, but also our own, more powerful locals wordset (we
implemented the ANS Forth locals wordset through our locals wordset).

   The ideas in this section have also been published in M. Anton Ertl,
`Automatic Scoping of Local Variables
(http://www.complang.tuwien.ac.at/papers/ertl94l.ps.gz)', EuroForth '94.

Gforth locals
-------------

   Locals can be defined with

     { local1 local2 ... -- comment }
   or
     { local1 local2 ... }

   E.g.,
     : max { n1 n2 -- n3 }
      n1 n2 > if
        n1
      else
        n2
      endif ;

   The similarity of locals definitions with stack comments is
intended. A locals definition often replaces the stack comment of a
word. The order of the locals corresponds to the order in a stack
comment and everything after the `--' is really a comment.

   This similarity has one disadvantage: It is too easy to confuse
locals declarations with stack comments, causing bugs and making them
hard to find. However, this problem can be avoided by appropriate coding
conventions: Do not use both notations in the same program. If you do,
they should be distinguished using additional means, e.g. by position.

   The name of the local may be preceded by a type specifier, e.g.,
`F:' for a floating point value:

     : CX* { F: Ar F: Ai F: Br F: Bi -- Cr Ci }
     \ complex multiplication
      Ar Br f* Ai Bi f* f-
      Ar Bi f* Ai Br f* f+ ;

   Gforth currently supports cells (`W:', `W^'), doubles (`D:', `D^'),
floats (`F:', `F^') and characters (`C:', `C^') in two flavours: a
value-flavoured local (defined with `W:', `D:' etc.) produces its value
and can be changed with `TO'. A variable-flavoured local (defined with
`W^' etc.)  produces its address (which becomes invalid when the
variable's scope is left). E.g., the standard word `emit' can be
defined in terms of `type' like this:

     : emit { C^ char* -- }
         char* 1 type ;

   A local without type specifier is a `W:' local. Both flavours of
locals are initialized with values from the data or FP stack.

   Currently there is no way to define locals with user-defined data
structures, but we are working on it.

   Gforth allows defining locals everywhere in a colon definition. This
poses the following questions:

Where are locals visible by name?
.................................

   Basically, the answer is that locals are visible where you would
expect it in block-structured languages, and sometimes a little longer.
If you want to restrict the scope of a local, enclose its definition in
`SCOPE'...`ENDSCOPE'.

`scope'       compilation  - scope ; run-time  -         gforth       ``scope''

`endscope'       compilation scope - ; run-time  -         gforth       ``endscope''

   These words behave like control structure words, so you can use them
with `CS-PICK' and `CS-ROLL' to restrict the scope in arbitrary ways.

   If you want a more exact answer to the visibility question, here's
the basic principle: A local is visible in all places that can only be
reached through the definition of the local(1). In other words, it is
not visible in places that can be reached without going through the
definition of the local. E.g., locals defined in `IF'...`ENDIF' are
visible until the `ENDIF', locals defined in `BEGIN'...`UNTIL' are
visible after the `UNTIL' (until, e.g., a subsequent `ENDSCOPE').

   The reasoning behind this solution is: We want to have the locals
visible as long as it is meaningful. The user can always make the
visibility shorter by using explicit scoping. In a place that can only
be reached through the definition of a local, the meaning of a local
name is clear. In other places it is not: How is the local initialized
at the control flow path that does not contain the definition? Which
local is meant, if the same name is defined twice in two independent
control flow paths?

   This should be enough detail for nearly all users, so you can skip
the rest of this section. If you really must know all the gory details
and options, read on.

   In order to implement this rule, the compiler has to know which
places are unreachable. It knows this automatically after `AHEAD',
`AGAIN', `EXIT' and `LEAVE'; in other cases (e.g., after most
`THROW's), you can use the word `UNREACHABLE' to tell the compiler that
the control flow never reaches that place. If `UNREACHABLE' is not used
where it could, the only consequence is that the visibility of some
locals is more limited than the rule above says. If `UNREACHABLE' is
used where it should not (i.e., if you lie to the compiler), buggy code
will be produced.

`UNREACHABLE'       -         gforth       ``UNREACHABLE''

   Another problem with this rule is that at `BEGIN', the compiler does
not know which locals will be visible on the incoming back-edge. All
problems discussed in the following are due to this ignorance of the
compiler (we discuss the problems using `BEGIN' loops as examples; the
discussion also applies to `?DO' and other loops). Perhaps the most
insidious example is:
     AHEAD
     BEGIN
       x
     [ 1 CS-ROLL ] THEN
       { x }
       ...
     UNTIL

   This should be legal according to the visibility rule. The use of
`x' can only be reached through the definition; but that appears
textually below the use.

   From this example it is clear that the visibility rules cannot be
fully implemented without major headaches. Our implementation treats
common cases as advertised and the exceptions are treated in a safe
way: The compiler makes a reasonable guess about the locals visible
after a `BEGIN'; if it is too pessimistic, the user will get a spurious
error about the local not being defined; if the compiler is too
optimistic, it will notice this later and issue a warning. In the case
above the compiler would complain about `x' being undefined at its use.
You can see from the obscure examples in this section that it takes
quite unusual control structures to get the compiler into trouble, and
even then it will often do fine.

   If the `BEGIN' is reachable from above, the most optimistic guess is
that all locals visible before the `BEGIN' will also be visible after
the `BEGIN'. This guess is valid for all loops that are entered only
through the `BEGIN', in particular, for normal
`BEGIN'...`WHILE'...`REPEAT' and `BEGIN'...`UNTIL' loops and it is
implemented in our compiler. When the branch to the `BEGIN' is finally
generated by `AGAIN' or `UNTIL', the compiler checks the guess and
warns the user if it was too optimistic:
     IF
       { x }
     BEGIN
       \ x ?
     [ 1 cs-roll ] THEN
       ...
     UNTIL

   Here, `x' lives only until the `BEGIN', but the compiler
optimistically assumes that it lives until the `THEN'. It notices this
difference when it compiles the `UNTIL' and issues a warning. The user
can avoid the warning, and make sure that `x' is not used in the wrong
area by using explicit scoping:
     IF
       SCOPE
       { x }
       ENDSCOPE
     BEGIN
     [ 1 cs-roll ] THEN
       ...
     UNTIL

   Since the guess is optimistic, there will be no spurious error
messages about undefined locals.

   If the `BEGIN' is not reachable from above (e.g., after `AHEAD' or
`EXIT'), the compiler cannot even make an optimistic guess, as the
locals visible after the `BEGIN' may be defined later. Therefore, the
compiler assumes that no locals are visible after the `BEGIN'. However,
the user can use `ASSUME-LIVE' to make the compiler assume that the
same locals are visible at the BEGIN as at the point where the top
control-flow stack item was created.

`ASSUME-LIVE'       orig - orig         gforth       ``ASSUME-LIVE''

E.g.,
     { x }
     AHEAD
     ASSUME-LIVE
     BEGIN
       x
     [ 1 CS-ROLL ] THEN
       ...
     UNTIL

   Other cases where the locals are defined before the `BEGIN' can be
handled by inserting an appropriate `CS-ROLL' before the `ASSUME-LIVE'
(and changing the control-flow stack manipulation behind the
`ASSUME-LIVE').

   Cases where locals are defined after the `BEGIN' (but should be
visible immediately after the `BEGIN') can only be handled by
rearranging the loop. E.g., the "most insidious" example above can be
arranged into:
     BEGIN
       { x }
       ... 0=
     WHILE
       x
     REPEAT

   ---------- Footnotes ----------

   (1) In compiler construction terminology, all places dominated by
the definition of the local.

How long do locals live?
........................

   The right answer for the lifetime question would be: A local lives at
least as long as it can be accessed. For a value-flavoured local this
means: until the end of its visibility. However, a variable-flavoured
local could be accessed through its address far beyond its visibility
scope. Ultimately, this would mean that such locals would have to be
garbage collected. Since this entails un-Forth-like implementation
complexities, I adopted the same cowardly solution as some other
languages (e.g., C): The local lives only as long as it is visible;
afterwards its address is invalid (and programs that access it
afterwards are erroneous).

Locals programming style
........................

   The freedom to define locals anywhere has the potential to change
programming styles dramatically. In particular, the need to use the
return stack for intermediate storage vanishes. Moreover, all stack
manipulations (except `PICK's and `ROLL's with run-time determined
arguments) can be eliminated: If the stack items are in the wrong
order, just write a locals definition for all of them; then write the
items in the order you want.

   This seems a little far-fetched and eliminating stack manipulations
is unlikely to become a conscious programming objective. Still, the
number of stack manipulations will be reduced dramatically if local
variables are used liberally (e.g., compare `max' (*note Gforth
locals::) with a traditional implementation of `max').

   This shows one potential benefit of locals: making Forth programs
more readable. Of course, this benefit will only be realized if the
programmers continue to honour the principle of factoring instead of
using the added latitude to make the words longer.

   Using `TO' can and should be avoided.  Without `TO', every
value-flavoured local has only a single assignment and many advantages
of functional languages apply to Forth. I.e., programs are easier to
analyse, to optimize and to read: It is clear from the definition what
the local stands for, it does not turn into something different later.

   E.g., a definition using `TO' might look like this:
     : strcmp { addr1 u1 addr2 u2 -- n }
      u1 u2 min 0
      ?do
        addr1 c@ addr2 c@ -
        ?dup-if
          unloop exit
        then
        addr1 char+ TO addr1
        addr2 char+ TO addr2
      loop
      u1 u2 - ;
   Here, `TO' is used to update `addr1' and `addr2' at every loop
iteration. `strcmp' is a typical example of the readability problems of
using `TO'. When you start reading `strcmp', you think that `addr1'
refers to the start of the string. Only near the end of the loop you
realize that it is something else.

   This can be avoided by defining two locals at the start of the loop
that are initialized with the right value for the current iteration.
     : strcmp { addr1 u1 addr2 u2 -- n }
      addr1 addr2
      u1 u2 min 0
      ?do { s1 s2 }
        s1 c@ s2 c@ -
        ?dup-if
          unloop exit
        then
        s1 char+ s2 char+
      loop
      2drop
      u1 u2 - ;
   Here it is clear from the start that `s1' has a different value in
every loop iteration.

Locals implementation
.....................

   Gforth uses an extra locals stack. The most compelling reason for
this is that the return stack is not float-aligned; using an extra stack
also eliminates the problems and restrictions of using the return stack
as locals stack. Like the other stacks, the locals stack grows toward
lower addresses. A few primitives allow an efficient implementation:

`@local#'       - w        gforth       ``fetch-local-number''

`f@local#'       - r        gforth       ``f-fetch-local-number''

`laddr#'       - c-addr        gforth       ``laddr-number''

`lp+!#'       -        gforth       ``lp-plus-store-number''
   used with negative immediate values it allocates memory on the local
stack, a positive immediate argument drops memory from the local stack

`lp!'       c-addr -        gforth       ``lp-store''

`>l'       w -        gforth       ``to-l''

`f>l'       r -        gforth       ``f-to-l''

   In addition to these primitives, some specializations of these
primitives for commonly occurring inline arguments are provided for
efficiency reasons, e.g., `@local0' as specialization of `@local#' for
the inline argument 0. The following compiling words compile the right
specialized version, or the general version, as appropriate:

`compile-@local'       n -         gforth       ``compile-fetch-local''

`compile-f@local'       n -         gforth       ``compile-f-fetch-local''

`compile-lp+!'       n -         gforth       ``compile-l-p-plus-store''

   Combinations of conditional branches and `lp+!#' like
`?branch-lp+!#' (the locals pointer is only changed if the branch is
taken) are provided for efficiency and correctness in loops.

   A special area in the dictionary space is reserved for keeping the
local variable names. `{' switches the dictionary pointer to this area
and `}' switches it back and generates the locals initializing code.
`W:' etc. are normal defining words. This special area is cleared at
the start of every colon definition.

   A special feature of Gforth's dictionary is used to implement the
definition of locals without type specifiers: every word list (aka
vocabulary) has its own methods for searching etc. (*note Word
Lists::). For the present purpose we defined a word list with a special
search method: When it is searched for a word, it actually creates that
word using `W:'. `{' changes the search order to first search the word
list containing `}', `W:' etc., and then the word list for defining
locals without type specifiers.

   The lifetime rules support a stack discipline within a colon
definition: The lifetime of a local is either nested with other locals
lifetimes or it does not overlap them.

   At `BEGIN', `IF', and `AHEAD' no code for locals stack pointer
manipulation is generated. Between control structure words locals
definitions can push locals onto the locals stack. `AGAIN' is the
simplest of the other three control flow words. It has to restore the
locals stack depth of the corresponding `BEGIN' before branching. The
code looks like this:
`lp+!#' current-locals-size - dest-locals-size
`branch' <begin>

   `UNTIL' is a little more complicated: If it branches back, it must
adjust the stack just like `AGAIN'. But if it falls through, the locals
stack must not be changed. The compiler generates the following code:
`?branch-lp+!#' <begin> current-locals-size - dest-locals-size
   The locals stack pointer is only adjusted if the branch is taken.

   `THEN' can produce somewhat inefficient code:
`lp+!#' current-locals-size - orig-locals-size
<orig target>:
`lp+!#' orig-locals-size - new-locals-size
   The second `lp+!#' adjusts the locals stack pointer from the level
at the orig point to the level after the `THEN'. The first `lp+!#'
adjusts the locals stack pointer from the current level to the level at
the orig point, so the complete effect is an adjustment from the
current level to the right level after the `THEN'.

   In a conventional Forth implementation a dest control-flow stack
entry is just the target address and an orig entry is just the address
to be patched. Our locals implementation adds a word list to every orig
or dest item. It is the list of locals visible (or assumed visible) at
the point described by the entry. Our implementation also adds a tag to
identify the kind of entry, in particular to differentiate between live
and dead (reachable and unreachable) orig entries.

   A few unusual operations have to be performed on locals word lists:

`common-list'       list1 list2 - list3         gforth-internal       ``common-list''

`sub-list?'       list1 list2 - f         gforth-internal       ``sub-list?''

`list-size'       list - u         gforth-internal       ``list-size''

   Several features of our locals word list implementation make these
operations easy to implement: The locals word lists are organised as
linked lists; the tails of these lists are shared, if the lists contain
some of the same locals; and the address of a name is greater than the
address of the names behind it in the list.

   Another important implementation detail is the variable `dead-code'.
It is used by `BEGIN' and `THEN' to determine if they can be reached
directly or only through the branch that they resolve. `dead-code' is
set by `UNREACHABLE', `AHEAD', `EXIT' etc., and cleared at the start of
a colon definition, by `BEGIN' and usually by `THEN'.

   Counted loops are similar to other loops in most respects, but
`LEAVE' requires special attention: It performs basically the same
service as `AHEAD', but it does not create a control-flow stack entry.
Therefore the information has to be stored elsewhere; traditionally,
the information was stored in the target fields of the branches created
by the `LEAVE's, by organizing these fields into a linked list.
Unfortunately, this clever trick does not provide enough space for
storing our extended control flow information. Therefore, we introduce
another stack, the leave stack. It contains the control-flow stack
entries for all unresolved `LEAVE's.

   Local names are kept until the end of the colon definition, even if
they are no longer visible in any control-flow path. In a few cases
this may lead to increased space needs for the locals name area, but
usually less than reclaiming this space would cost in code size.

ANS Forth locals
----------------

   The ANS Forth locals wordset does not define a syntax for locals, but
words that make it possible to define various syntaxes. One of the
possible syntaxes is a subset of the syntax we used in the Gforth locals
wordset, i.e.:

     { local1 local2 ... -- comment }

or
     { local1 local2 ... }

   The order of the locals corresponds to the order in a stack comment.
The restrictions are:

   * Locals can only be cell-sized values (no type specifiers are
     allowed).

   * Locals can be defined only outside control structures.

   * Locals can interfere with explicit usage of the return stack. For
     the exact (and long) rules, see the standard. If you don't use
     return stack accessing words in a definition using locals, you
     will be all right. The purpose of this rule is to make locals
     implementation on the return stack easier.

   * The whole definition must be in one line.

   Locals defined in ANS Forth behave like `VALUE's (*note Values::).
I.e., they are initialized from the stack. Using their name produces
their value. Their value can be changed using `TO'.

   Since the syntax above is supported by Gforth directly, you need not
do anything to use it. If you want to port a program using this syntax
to another ANS Forth system, use `compat/anslocal.fs' to implement the
syntax on the other system.

   Note that a syntax shown in the standard, section A.13 looks
similar, but is quite different in having the order of locals reversed.
Beware!

   The ANS Forth locals wordset itself consists of one word:

`(local)'       addr u -         local       ``paren-local-paren''

   The ANS Forth locals extension wordset defines a syntax using
`locals|', but it is so awful that we strongly recommend not to use it.
We have implemented this syntax to make porting to Gforth easy, but do
not document it here. The problem with this syntax is that the locals
are defined in an order reversed with respect to the standard stack
comment notation, making programs harder to read, and easier to misread
and miswrite. The only merit of this syntax is that it is easy to
implement using the ANS Forth locals wordset.

Structures
==========

   This section presents the structure package that comes with Gforth. A
version of the package implemented in ANS Forth is available in
`compat/struct.fs'. This package was inspired by a posting on
comp.lang.forth in 1989 (unfortunately I don't remember, by whom;
possibly John Hayes). A version of this section has been published in
M. Anton Ertl, Yet Another Forth Structures Package
(http://www.complang.tuwien.ac.at/forth/objects/structs.html), Forth
Dimensions 19(3), pages 13-16. Marcel Hendrix provided helpful comments.

Why explicit structure support?
-------------------------------

   If we want to use a structure containing several fields, we could
simply reserve memory for it, and access the fields using address
arithmetic (*note Address arithmetic::). As an example, consider a
structure with the following fields

`a'
     is a float

`b'
     is a cell

`c'
     is a float

   Given the (float-aligned) base address of the structure we get the
address of the field

`a'
     without doing anything further.

`b'
     with `float+'

`c'
     with `float+ cell+ faligned'

   It is easy to see that this can become quite tiring.

   Moreover, it is not very readable, because seeing a `cell+' tells us
neither which kind of structure is accessed nor what field is accessed;
we have to somehow infer the kind of structure, and then look up in the
documentation, which field of that structure corresponds to that offset.

   Finally, this kind of address arithmetic also causes maintenance
troubles: If you add or delete a field somewhere in the middle of the
structure, you have to find and change all computations for the fields
afterwards.

   So, instead of using `cell+' and friends directly, how about storing
the offsets in constants:

     0 constant a-offset
     0 float+ constant b-offset
     0 float+ cell+ faligned c-offset

   Now we can get the address of field `x' with `x-offset +'. This is
much better in all respects. Of course, you still have to change all
later offset definitions if you add a field. You can fix this by
declaring the offsets in the following way:

     0 constant a-offset
     a-offset float+ constant b-offset
     b-offset cell+ faligned constant c-offset

   Since we always use the offsets with `+', we could use a defining
word `cfield' that includes the `+' in the action of the defined word:

     : cfield ( n "name" -- )
         create ,
     does> ( name execution: addr1 -- addr2 )
         @ + ;
     
     0 cfield a
     0 a float+ cfield b
     0 b cell+ faligned cfield c

   Instead of `x-offset +', we now simply write `x'.

   The structure field words now can be used quite nicely. However,
their definition is still a bit cumbersome: We have to repeat the name,
the information about size and alignment is distributed before and
after the field definitions etc.  The structure package presented here
addresses these problems.

Structure Usage
---------------

   You can define a structure for a (data-less) linked list with:
     struct
         cell% field list-next
     end-struct list%

   With the address of the list node on the stack, you can compute the
address of the field that contains the address of the next node with
`list-next'. E.g., you can determine the length of a list with:

     : list-length ( list -- n )
     \ "list" is a pointer to the first element of a linked list
     \ "n" is the length of the list
         0 BEGIN ( list1 n1 )
             over
         WHILE ( list1 n1 )
             1+ swap list-next @ swap
         REPEAT
         nip ;

   You can reserve memory for a list node in the dictionary with `list%
%allot', which leaves the address of the list node on the stack. For
the equivalent allocation on the heap you can use `list% %alloc' (or,
for an `allocate'-like stack effect (i.e., with ior), use `list%
%allocate'). You can get the the size of a list node with `list% %size'
and its alignment with `list% %alignment'.

   Note that in ANS Forth the body of a `create'd word is `aligned' but
not necessarily `faligned'; therefore, if you do a:

     create _name_ foo% %allot drop

then the memory alloted for `foo%' is guaranteed to start at the body
of `_name_' only if `foo%' contains only character, cell and double
fields.  Therefore, if your structure contains floats, better use

     foo% %allot constant _name_

   You can include a structure `foo%' as a field of another structure,
like this:
     struct
     ...
         foo% field ...
     ...
     end-struct ...

   Instead of starting with an empty structure, you can extend an
existing structure. E.g., a plain linked list without data, as defined
above, is hardly useful; You can extend it to a linked list of integers,
like this:(1)

     list%
         cell% field intlist-int
     end-struct intlist%

   `intlist%' is a structure with two fields: `list-next' and
`intlist-int'.

   You can specify an array type containing _n_ elements of type `foo%'
like this:

     foo% _n_ *

   You can use this array type in any place where you can use a normal
type, e.g., when defining a `field', or with `%allot'.

   The first field is at the base address of a structure and the word
for this field (e.g., `list-next') actually does not change the address
on the stack. You may be tempted to leave it away in the interest of
run-time and space efficiency. This is not necessary, because the
structure package optimizes this case: If you compile a first-field
words, no code is generated. So, in the interest of readability and
maintainability you should include the word for the field when accessing
the field.

   ---------- Footnotes ----------

   (1) This feature is also known as _extended records_. It is the main
innovation in the Oberon language; in other words, adding this feature
to Modula-2 led Wirth to create a new language, write a new compiler
etc.  Adding this feature to Forth just required a few lines of code.

Structure Naming Convention
---------------------------

   The field names that come to (my) mind are often quite generic, and,
if used, would cause frequent name clashes. E.g., many structures
probably contain a `counter' field. The structure names that come to
(my) mind are often also the logical choice for the names of words that
create such a structure.

   Therefore, I have adopted the following naming conventions:

   * The names of fields are of the form `_struct_-_field_', where
     `_struct_' is the basic name of the structure, and `_field_' is
     the basic name of the field. You can think of field words as
     converting the (address of the) structure into the (address of
     the) field.

   * The names of structures are of the form `_struct_%', where
     `_struct_' is the basic name of the structure.

   This naming convention does not work that well for fields of extended
structures; e.g., the integer list structure has a field `intlist-int',
but has `list-next', not `intlist-next'.

Structure Implementation
------------------------

   The central idea in the implementation is to pass the data about the
structure being built on the stack, not in some global variable.
Everything else falls into place naturally once this design decision is
made.

   The type description on the stack is of the form _align size_.
Keeping the size on the top-of-stack makes dealing with arrays very
simple.

   `field' is a defining word that uses `Create' and `DOES>'. The body
of the field contains the offset of the field, and the normal `DOES>'
action is simply:

     @ +

i.e., add the offset to the address, giving the stack effect addr1 -
addr2 for a field.

   This simple structure is slightly complicated by the optimization
for fields with offset 0, which requires a different `DOES>'-part
(because we cannot rely on there being something on the stack if such a
field is invoked during compilation). Therefore, we put the different
`DOES>'-parts in separate words, and decide which one to invoke based
on the offset. For a zero offset, the field is basically a noop; it is
immediate, and therefore no code is generated when it is compiled.

Structure Glossary
------------------

`%align'       align size -         gforth       ``%align''
   Align the data space pointer to the alignment ALIGN.

`%alignment'       align size - align         gforth       ``%alignment''
   The alignment of the structure.

`%alloc'       size align - addr         gforth       ``%alloc''
   Allocate SIZE address units with alignment ALIGN, giving a data
block at ADDR; `throw' an ior code if not successful.

`%allocate'       align size - addr ior         gforth       ``%allocate''
   Allocate SIZE address units with alignment ALIGN, similar to
`allocate'.

`%allot'       align size - addr         gforth       ``%allot''
   Allot SIZE address units of data space with alignment ALIGN; the
resulting block of data is found at ADDR.

`cell%'       - align size         gforth       ``cell%''

`char%'       - align size         gforth       ``char%''

`dfloat%'       - align size         gforth       ``dfloat%''

`double%'       - align size         gforth       ``double%''

`end-struct'       align size "name" -         gforth       ``end-struct''
   Define a structure/type descriptor NAME with alignment ALIGN and
size SIZE1 (SIZE rounded up to be a multiple of ALIGN).
`name' execution: - ALIGN SIZE1
`field'       align1 offset1 align size "name" -  align2 offset2         gforth       ``field''
Create a field NAME with offset OFFSET1, and the type given by ALIGN
SIZE. OFFSET2 is the offset of the next field, and ALIGN2 is the
alignment of all fields.
`name' execution: ADDR1 - ADDR2.
ADDR2=ADDR1+OFFSET1

`float%'       - align size         gforth       ``float%''

`naligned'       addr1 n - addr2         gforth       ``naligned''
   ADDR2 is the aligned version of ADDR1 with respect to the alignment
N.

`sfloat%'       - align size         gforth       ``sfloat%''

`%size'       align size - size         gforth       ``%size''
   The size of the structure.

`struct'       - align size         gforth       ``struct''
   An empty structure, used to start a structure definition.

Object-oriented Forth
=====================

   Gforth comes with three packages for object-oriented programming:
`objects.fs', `oof.fs', and `mini-oof.fs'; none of them is preloaded,
so you have to `include' them before use. The most important
differences between these packages (and others) are discussed in *Note
Comparison with other object models::. All packages are written in ANS
Forth and can be used with any other ANS Forth.

Why object-oriented programming?
--------------------------------

   Often we have to deal with several data structures (_objects_), that
have to be treated similarly in some respects, but differently in
others. Graphical objects are the textbook example: circles, triangles,
dinosaurs, icons, and others, and we may want to add more during program
development. We want to apply some operations to any graphical object,
e.g., `draw' for displaying it on the screen. However, `draw' has to do
something different for every kind of object.

   We could implement `draw' as a big `CASE' control structure that
executes the appropriate code depending on the kind of object to be
drawn. This would be not be very elegant, and, moreover, we would have
to change `draw' every time we add a new kind of graphical object (say,
a spaceship).

   What we would rather do is: When defining spaceships, we would tell
the system: "Here's how you `draw' a spaceship; you figure out the
rest".

   This is the problem that all systems solve that (rightfully) call
themselves object-oriented; the object-oriented packages presented here
solve this problem (and not much else).

Object-Oriented Terminology
---------------------------

   This section is mainly for reference, so you don't have to understand
all of it right away.  The terminology is mainly Smalltalk-inspired.  In
short:

_class_
     a data structure definition with some extras.

_object_
     an instance of the data structure described by the class
     definition.

_instance variables_
     fields of the data structure.

_selector_
     (or _method selector_) a word (e.g., `draw') that performs an
     operation on a variety of data structures (classes). A selector
     describes _what_ operation to perform. In C++ terminology: a
     (pure) virtual function.

_method_
     the concrete definition that performs the operation described by
     the selector for a specific class. A method specifies _how_ the
     operation is performed for a specific class.

_selector invocation_
     a call of a selector. One argument of the call (the TOS
     (top-of-stack)) is used for determining which method is used. In
     Smalltalk terminology: a message (consisting of the selector and
     the other arguments) is sent to the object.

_receiving object_
     the object used for determining the method executed by a selector
     invocation. In the `objects.fs' model, it is the object that is on
     the TOS when the selector is invoked. (_Receiving_ comes from the
     Smalltalk _message_ terminology.)

_child class_
     a class that has (_inherits_) all properties (instance variables,
     selectors, methods) from a _parent class_. In Smalltalk
     terminology: The subclass inherits from the superclass. In C++
     terminology: The derived class inherits from the base class.

The `objects.fs' model
----------------------

   This section describes the `objects.fs' package. This material also
has been published in M. Anton Ertl, `Yet Another Forth Objects Package
(http://www.complang.tuwien.ac.at/forth/objects/objects.html)', Forth
Dimensions 19(2), pages 37-43.

   This section assumes that you have read *Note Structures::.

   The techniques on which this model is based have been used to
implement the parser generator, Gray, and have also been used in Gforth
for implementing the various flavours of word lists (hashed or not,
case-sensitive or not, special-purpose word lists for locals etc.).

   Marcel Hendrix provided helpful comments on this section.

Properties of the `objects.fs' model
....................................

   * It is straightforward to pass objects on the stack. Passing
     selectors on the stack is a little less convenient, but possible.

   * Objects are just data structures in memory, and are referenced by
     their address. You can create words for objects with normal
     defining words like `constant'. Likewise, there is no difference
     between instance variables that contain objects and those that
     contain other data.

   * Late binding is efficient and easy to use.

   * It avoids parsing, and thus avoids problems with state-smartness
     and reduced extensibility; for convenience there are a few parsing
     words, but they have non-parsing counterparts. There are also a few
     defining words that parse. This is hard to avoid, because all
     standard defining words parse (except `:noname'); however, such
     words are not as bad as many other parsing words, because they are
     not state-smart.

   * It does not try to incorporate everything. It does a few things
     and does them well (IMO). In particular, this model was not
     designed to support information hiding (although it has features
     that may help); you can use a separate package for achieving this.

   * It is layered; you don't have to learn and use all features to use
     this model. Only a few features are necessary (*note Basic Objects
     Usage::, *note The Objects base class::, *note Creating
     objects::.), the others are optional and independent of each other.

   * An implementation in ANS Forth is available.


Basic `objects.fs' Usage
........................

   You can define a class for graphical objects like this:

     object class \ "object" is the parent class
       selector draw ( x y graphical -- )
     end-class graphical

   This code defines a class `graphical' with an operation `draw'.  We
can perform the operation `draw' on any `graphical' object, e.g.:

     100 100 t-rex draw

where `t-rex' is a word (say, a constant) that produces a graphical
object.

   How do we create a graphical object? With the present definitions,
we cannot create a useful graphical object. The class `graphical'
describes graphical objects in general, but not any concrete graphical
object type (C++ users would call it an _abstract class_); e.g., there
is no method for the selector `draw' in the class `graphical'.

   For concrete graphical objects, we define child classes of the class
`graphical', e.g.:

     graphical class \ "graphical" is the parent class
       cell% field circle-radius
     
     :noname ( x y circle -- )
       circle-radius @ draw-circle ;
     overrides draw
     
     :noname ( n-radius circle -- )
       circle-radius ! ;
     overrides construct
     
     end-class circle

   Here we define a class `circle' as a child of `graphical', with
field `circle-radius' (which behaves just like a field (*note
Structures::); it defines (using `overrides') new methods for the
selectors `draw' and `construct' (`construct' is defined in `object',
the parent class of `graphical').

   Now we can create a circle on the heap (i.e., `allocate'd memory)
with:

     50 circle heap-new constant my-circle

`heap-new' invokes `construct', thus initializing the field
`circle-radius' with 50. We can draw this new circle at (100,100) with:

     100 100 my-circle draw

   Note: You can only invoke a selector if the object on the TOS (the
receiving object) belongs to the class where the selector was defined
or one of its descendents; e.g., you can invoke `draw' only for objects
belonging to `graphical' or its descendents (e.g., `circle').
Immediately before `end-class', the search order has to be the same as
immediately after `class'.

The `object.fs' base class
..........................

   When you define a class, you have to specify a parent class.  So how
do you start defining classes? There is one class available from the
start: `object'. It is ancestor for all classes and so is the only
class that has no parent. It has two selectors: `construct' and `print'.

Creating objects
................

   You can create and initialize an object of a class on the heap with
`heap-new' ( ... class - object ) and in the dictionary (allocation
with `allot') with `dict-new' ( ... class - object ). Both words invoke
`construct', which consumes the stack items indicated by "..." above.

   If you want to allocate memory for an object yourself, you can get
its alignment and size with `class-inst-size 2@' ( class - align size
). Once you have memory for an object, you can initialize it with
`init-object' ( ... class object - ); `construct' does only a part of
the necessary work.

Object-Oriented Programming Style
.................................

   This section is not exhaustive.

   In general, it is a good idea to ensure that all methods for the
same selector have the same stack effect: when you invoke a selector,
you often have no idea which method will be invoked, so, unless all
methods have the same stack effect, you will not know the stack effect
of the selector invocation.

   One exception to this rule is methods for the selector `construct'.
We know which method is invoked, because we specify the class to be
constructed at the same place. Actually, I defined `construct' as a
selector only to give the users a convenient way to specify
initialization. The way it is used, a mechanism different from selector
invocation would be more natural (but probably would take more code and
more space to explain).

Class Binding
.............

   Normal selector invocations determine the method at run-time
depending on the class of the receiving object. This run-time selection
is called late binding.

   Sometimes it's preferable to invoke a different method. For example,
you might want to use the simple method for `print'ing `object's
instead of the possibly long-winded `print' method of the receiver
class. You can achieve this by replacing the invocation of `print' with:

     [bind] object print

in compiled code or:

     bind object print

in interpreted code. Alternatively, you can define the method with a
name (e.g., `print-object'), and then invoke it through the name. Class
binding is just a (often more convenient) way to achieve the same
effect; it avoids name clutter and allows you to invoke methods
directly without naming them first.

   A frequent use of class binding is this: When we define a method for
a selector, we often want the method to do what the selector does in
the parent class, and a little more. There is a special word for this
purpose: `[parent]'; `[parent] _selector_' is equivalent to `[bind]
_parent selector_', where `_parent_' is the parent class of the current
class. E.g., a method definition might look like:

     :noname
       dup [parent] foo \ do parent's foo on the receiving object
       ... \ do some more
     ; overrides foo

   In `Object-oriented programming in ANS Forth' (Forth Dimensions,
March 1997), Andrew McKewan presents class binding as an optimization
technique. I recommend not using it for this purpose unless you are in
an emergency. Late binding is pretty fast with this model anyway, so the
benefit of using class binding is small; the cost of using class binding
where it is not appropriate is reduced maintainability.

   While we are at programming style questions: You should bind
selectors only to ancestor classes of the receiving object. E.g., say,
you know that the receiving object is of class `foo' or its
descendents; then you should bind only to `foo' and its ancestors.

Method conveniences
...................

   In a method you usually access the receiving object pretty often.  If
you define the method as a plain colon definition (e.g., with
`:noname'), you may have to do a lot of stack gymnastics. To avoid
this, you can define the method with `m: ... ;m'. E.g., you could
define the method for `draw'ing a `circle' with

     m: ( x y circle -- )
       ( x y ) this circle-radius @ draw-circle ;m

   When this method is executed, the receiver object is removed from the
stack; you can access it with `this' (admittedly, in this example the
use of `m: ... ;m' offers no advantage). Note that I specify the stack
effect for the whole method (i.e. including the receiver object), not
just for the code between `m:' and `;m'. You cannot use `exit' in
`m:...;m'; instead, use `exitm'.(1)

   You will frequently use sequences of the form `this _field_' (in the
example above: `this circle-radius'). If you use the field only in this
way, you can define it with `inst-var' and eliminate the `this' before
the field name. E.g., the `circle' class above could also be defined
with:

     graphical class
       cell% inst-var radius
     
     m: ( x y circle -- )
       radius @ draw-circle ;m
     overrides draw
     
     m: ( n-radius circle -- )
       radius ! ;m
     overrides construct
     
     end-class circle

   `radius' can only be used in `circle' and its descendent classes and
inside `m:...;m'.

   You can also define fields with `inst-value', which is to `inst-var'
what `value' is to `variable'.  You can change the value of such a
field with `[to-inst]'.  E.g., we could also define the class `circle'
like this:

     graphical class
       inst-value radius
     
     m: ( x y circle -- )
       radius draw-circle ;m
     overrides draw
     
     m: ( n-radius circle -- )
       [to-inst] radius ;m
     overrides construct
     
     end-class circle

   ---------- Footnotes ----------

   (1) Moreover, for any word that calls `catch' and was defined before
loading `objects.fs', you have to redefine it like I redefined `catch':
`: catch this >r catch r> to-this ;'

Classes and Scoping
...................

   Inheritance is frequent, unlike structure extension. This exacerbates
the problem with the field name convention (*note Structure Naming
Convention::): One always has to remember in which class the field was
originally defined; changing a part of the class structure would require
changes for renaming in otherwise unaffected code.

   To solve this problem, I added a scoping mechanism (which was not in
my original charter): A field defined with `inst-var' (or `inst-value')
is visible only in the class where it is defined and in the descendent
classes of this class.  Using such fields only makes sense in
`m:'-defined methods in these classes anyway.

   This scoping mechanism allows us to use the unadorned field name,
because name clashes with unrelated words become much less likely.

   Once we have this mechanism, we can also use it for controlling the
visibility of other words: All words defined after `protected' are
visible only in the current class and its descendents. `public'
restores the compilation (i.e. `current') word list that was in effect
before. If you have several `protected's without an intervening
`public' or `set-current', `public' will restore the compilation word
list in effect before the first of these `protected's.

Dividing classes
................

   You may want to do the definition of methods separate from the
definition of the class, its selectors, fields, and instance variables,
i.e., separate the implementation from the definition.  You can do this
in the following way:

     graphical class
       inst-value radius
     end-class circle
     
     ... \ do some other stuff
     
     circle methods \ now we are ready
     
     m: ( x y circle -- )
       radius draw-circle ;m
     overrides draw
     
     m: ( n-radius circle -- )
       [to-inst] radius ;m
     overrides construct
     
     end-methods

   You can use several `methods'...`end-methods' sections.  The only
things you can do to the class in these sections are: defining methods,
and overriding the class's selectors.  You must not define new
selectors or fields.

   Note that you often have to override a selector before using it.  In
particular, you usually have to override `construct' with a new method
before you can invoke `heap-new' and friends.  E.g., you must not
create a circle before the `overrides construct' sequence in the
example above.

Object Interfaces
.................

   In this model you can only call selectors defined in the class of the
receiving objects or in one of its ancestors. If you call a selector
with a receiving object that is not in one of these classes, the result
is undefined; if you are lucky, the program crashes immediately.

   Now consider the case when you want to have a selector (or several)
available in two classes: You would have to add the selector to a
common ancestor class, in the worst case to `object'. You may not want
to do this, e.g., because someone else is responsible for this ancestor
class.

   The solution for this problem is interfaces. An interface is a
collection of selectors. If a class implements an interface, the
selectors become available to the class and its descendents. A class
can implement an unlimited number of interfaces. For the problem
discussed above, we would define an interface for the selector(s), and
both classes would implement the interface.

   As an example, consider an interface `storage' for writing objects
to disk and getting them back, and a class `foo' that implements it.
The code would look like this:

     interface
       selector write ( file object -- )
       selector read1 ( file object -- )
     end-interface storage
     
     bar class
       storage implementation
     
     ... overrides write
     ... overrides read1
     ...
     end-class foo

(I would add a word `read' ( file - object ) that uses `read1'
internally, but that's beyond the point illustrated here.)

   Note that you cannot use `protected' in an interface; and of course
you cannot define fields.

   In the Neon model, all selectors are available for all classes;
therefore it does not need interfaces. The price you pay in this model
is slower late binding, and therefore, added complexity to avoid late
binding.

`objects.fs' Implementation
...........................

   An object is a piece of memory, like one of the data structures
described with `struct...end-struct'. It has a field `object-map' that
points to the method map for the object's class.

   The _method map_(1) is an array that contains the execution tokens
(xts) of the methods for the object's class. Each selector contains an
offset into a method map.

   `selector' is a defining word that uses `CREATE' and `DOES>'. The
body of the selector contains the offset; the `DOES>' action for a
class selector is, basically:

     ( object addr ) @ over object-map @ + @ execute

   Since `object-map' is the first field of the object, it does not
generate any code. As you can see, calling a selector has a small,
constant cost.

   A class is basically a `struct' combined with a method map. During
the class definition the alignment and size of the class are passed on
the stack, just as with `struct's, so `field' can also be used for
defining class fields. However, passing more items on the stack would be
inconvenient, so `class' builds a data structure in memory, which is
accessed through the variable `current-interface'. After its definition
is complete, the class is represented on the stack by a pointer (e.g.,
as parameter for a child class definition).

   A new class starts off with the alignment and size of its parent,
and a copy of the parent's method map. Defining new fields extends the
size and alignment; likewise, defining new selectors extends the method
map. `overrides' just stores a new xt in the method map at the offset
given by the selector.

   Class binding just gets the xt at the offset given by the selector
from the class's method map and `compile,'s (in the case of `[bind]')
it.

   I implemented `this' as a `value'. At the start of an `m:...;m'
method the old `this' is stored to the return stack and restored at the
end; and the object on the TOS is stored `TO this'. This technique has
one disadvantage: If the user does not leave the method via `;m', but
via `throw' or `exit', `this' is not restored (and `exit' may crash).
To deal with the `throw' problem, I have redefined `catch' to save and
restore `this'; the same should be done with any word that can catch an
exception. As for `exit', I simply forbid it (as a replacement, there is
`exitm').

   `inst-var' is just the same as `field', with a different `DOES>'
action:
     @ this +
   Similar for `inst-value'.

   Each class also has a word list that contains the words defined with
`inst-var' and `inst-value', and its protected words. It also has a
pointer to its parent. `class' pushes the word lists of the class and
all its ancestors onto the search order stack, and `end-class' drops
them.

   An interface is like a class without fields, parent and protected
words; i.e., it just has a method map. If a class implements an
interface, its method map contains a pointer to the method map of the
interface. The positive offsets in the map are reserved for class
methods, therefore interface map pointers have negative offsets.
Interfaces have offsets that are unique throughout the system, unlike
class selectors, whose offsets are only unique for the classes where
the selector is available (invokable).

   This structure means that interface selectors have to perform one
indirection more than class selectors to find their method. Their body
contains the interface map pointer offset in the class method map, and
the method offset in the interface method map. The `does>' action for
an interface selector is, basically:

     ( object selector-body )
     2dup selector-interface @ ( object selector-body object interface-offset )
     swap object-map @ + @ ( object selector-body map )
     swap selector-offset @ + @ execute

   where `object-map' and `selector-offset' are first fields and
generate no code.

   As a concrete example, consider the following code:

     interface
       selector if1sel1
       selector if1sel2
     end-interface if1
     
     object class
       if1 implementation
       selector cl1sel1
       cell% inst-var cl1iv1
     
     ' m1 overrides construct
     ' m2 overrides if1sel1
     ' m3 overrides if1sel2
     ' m4 overrides cl1sel2
     end-class cl1
     
     create obj1 object dict-new drop
     create obj2 cl1    dict-new drop

   The data structure created by this code (including the data structure
for `object') is shown in the figure (objects-implementation.eps),
assuming a cell size of 4.

   ---------- Footnotes ----------

   (1) This is Self terminology; in C++ terminology: virtual function
table.

`objects.fs' Glossary
.....................

`bind'       ... "class" "selector" - ...         objects       ``bind''
   Execute the method for SELECTOR in CLASS.

`<bind>'       class selector-xt - xt         objects       ``<bind>''
   XT is the method for the selector SELECTOR-XT in CLASS.

`bind''       "class" "selector" - xt         objects       ``bind'''
   XT is the method for SELECTOR in CLASS.

`[bind]'       compile-time: "class" "selector" - ; run-time: ... object - ...         objects       ``[bind]''
   Compile the method for SELECTOR in CLASS.

`class'       parent-class - align offset         objects       ``class''
   Start a new class definition as a child of PARENT-CLASS. ALIGN
OFFSET are for use by FIELD etc.

`class->map'       class - map         objects       ``class->map''
   MAP is the pointer to CLASS's method map; it points to the place in
the map to which the selector offsets refer (i.e., where OBJECT-MAPs
point to).

`class-inst-size'       class - addr         objects       ``class-inst-size''
   Give the size specification for an instance (i.e. an object) of
CLASS; used as `class-inst-size 2 ( class -- align size )'.

`class-override!'       xt sel-xt class-map -         objects       ``class-override!''
   XT is the new method for the selector SEL-XT in CLASS-MAP.

`class-previous'       class -         objects       ``class-previous''
   Drop CLASS's wordlists from the search order. No checking is made
whether CLASS's wordlists are actually on the search order.

`class>order'       class -         objects       ``class>order''
   Add CLASS's wordlists to the head of the search-order.

`construct'       ... object -         objects       ``construct''
   Initialize the data fields of OBJECT. The method for the class
OBJECT just does nothing: `( object -- )'.

`current''       "selector" - xt         objects       ``current'''
   XT is the method for SELECTOR in the current class.

`[current]'       compile-time: "selector" - ; run-time: ... object - ...         objects       ``[current]''
   Compile the method for SELECTOR in the current class.

`current-interface'       - addr         objects       ``current-interface''
   Variable: contains the class or interface currently being defined.

`dict-new'       ... class - object         objects       ``dict-new''
   `allot' and initialize an object of class CLASS in the dictionary.

`end-class'       align offset "name" -         objects       ``end-class''
   NAME execution: `-- class'
End a class definition. The resulting class is CLASS.

`end-class-noname'       align offset - class         objects       ``end-class-noname''
   End a class definition. The resulting class is CLASS.

`end-interface'       "name" -         objects       ``end-interface''
   `name' execution: `-- interface'
End an interface definition. The resulting interface is INTERFACE.

`end-interface-noname'       - interface         objects       ``end-interface-noname''
   End an interface definition. The resulting interface is INTERFACE.

`end-methods'       -         objects       ``end-methods''
   Switch back from defining methods of a class to normal mode
(currently this just restores the old search order).

`exitm'       -         objects       ``exitm''
   `exit' from a method; restore old `this'.

`heap-new'       ... class - object         objects       ``heap-new''
   `allocate' and initialize an object of class CLASS.

`implementation'       interface -         objects       ``implementation''
   The current class implements INTERFACE. I.e., you can use all
selectors of the interface in the current class and its descendents.

`init-object'       ... class object -         objects       ``init-object''
   Initialize a chunk of memory (OBJECT) to an object of class CLASS;
then performs `construct'.

`inst-value'       align1 offset1 "name" - align2 offset2         objects       ``inst-value''
   NAME execution: `-- w'
W is the value of the field NAME in `this' object.

`inst-var'       align1 offset1 align size "name" - align2 offset2         objects       ``inst-var''
   NAME execution: `-- addr'
ADDR is the address of the field NAME in `this' object.

`interface'       -         objects       ``interface''
   Start an interface definition.

`m:'       - xt colon-sys; run-time: object -         objects       ``m:''
   Start a method definition; OBJECT becomes new `this'.

`:m'       "name" - xt; run-time: object -         objects       ``:m''
   Start a named method definition; OBJECT becomes new `this'.  Has to
be ended with `;m'.

`;m'       colon-sys -; run-time: -         objects       ``;m''
   End a method definition; restore old `this'.

`method'       xt "name" -         objects       ``method''
   `name' execution: `... object -- ...'
Create selector NAME and makes XT its method in the current class.

`methods'       class -         objects       ``methods''
   Makes CLASS the current class. This is intended to be used for
defining methods to override selectors; you cannot define new fields or
selectors.

`object'       - class         objects       ``object''
   the ancestor of all classes.

`overrides'       xt "selector" -         objects       ``overrides''
   replace default method for SELECTOR in the current class with XT.
`overrides' must not be used during an interface definition.

`[parent]'       compile-time: "selector" - ; run-time: ... object - ...         objects       ``[parent]''
   Compile the method for SELECTOR in the parent of the current class.

`print'       object -         objects       ``print''
   Print the object. The method for the class OBJECT prints the address
of the object and the address of its class.

`protected'       -         objects       ``protected''
   Set the compilation wordlist to the current class's wordlist

`public'       -         objects       ``public''
   Restore the compilation wordlist that was in effect before the last
`protected' that actually changed the compilation wordlist.

`selector'       "name" -         objects       ``selector''
   NAME execution: `... object -- ...'
Create selector NAME for the current class and its descendents; you can
set a method for the selector in the current class with `overrides'.

`this'       - object         objects       ``this''
   the receiving object of the current method (aka active object).

`<to-inst>'       w xt -         objects       ``<to-inst>''
   store W into the field XT in `this' object.

`[to-inst]'       compile-time: "name" - ; run-time: w -         objects       ``[to-inst]''
   store W into field NAME in `this' object.

`to-this'       object -         objects       ``to-this''
   Set `this' (used internally, but useful when debugging).

`xt-new'       ... class xt - object         objects       ``xt-new''
   Make a new object, using `xt ( align size -- addr )' to get memory.

The `oof.fs' model
------------------

   This section describes the `oof.fs' package.

   The package described in this section has been used in bigFORTH
since 1991, and used for two large applications: a chromatographic
system used to create new medicaments, and a graphic user interface
library (MINOS).

   You can find a description (in German) of `oof.fs' in `Object
oriented bigFORTH' by Bernd Paysan, published in `Vierte Dimension'
10(2), 1994.

Properties of the `oof.fs' model
................................

   * This model combines object oriented programming with information
     hiding. It helps you writing large application, where scoping is
     necessary, because it provides class-oriented scoping.

   * Named objects, object pointers, and object arrays can be created,
     selector invocation uses the "object selector" syntax. Selector
     invocation to objects and/or selectors on the stack is a bit less
     convenient, but possible.

   * Selector invocation and instance variable usage of the active
     object is straightforward, since both make use of the active
     object.

   * Late binding is efficient and easy to use.

   * State-smart objects parse selectors. However, extensibility is
     provided using a (parsing) selector `postpone' and a selector `''.

   * An implementation in ANS Forth is available.


Basic `oof.fs' Usage
....................

   This section uses the same example as for `objects' (*note Basic
Objects Usage::).

   You can define a class for graphical objects like this:

     object class graphical \ "object" is the parent class
       method draw ( x y graphical -- )
     class;

   This code defines a class `graphical' with an operation `draw'.  We
can perform the operation `draw' on any `graphical' object, e.g.:

     100 100 t-rex draw

where `t-rex' is an object or object pointer, created with e.g.
`graphical : t-rex'.

   How do we create a graphical object? With the present definitions,
we cannot create a useful graphical object. The class `graphical'
describes graphical objects in general, but not any concrete graphical
object type (C++ users would call it an _abstract class_); e.g., there
is no method for the selector `draw' in the class `graphical'.

   For concrete graphical objects, we define child classes of the class
`graphical', e.g.:

     graphical class circle \ "graphical" is the parent class
       cell var circle-radius
     how:
       : draw ( x y -- )
         circle-radius @ draw-circle ;
     
       : init ( n-radius -- (
         circle-radius ! ;
     class;

   Here we define a class `circle' as a child of `graphical', with a
field `circle-radius'; it defines new methods for the selectors `draw'
and `init' (`init' is defined in `object', the parent class of
`graphical').

   Now we can create a circle in the dictionary with:

     50 circle : my-circle

`:' invokes `init', thus initializing the field `circle-radius' with
50. We can draw this new circle at (100,100) with:

     100 100 my-circle draw

   Note: You can only invoke a selector if the receiving object belongs
to the class where the selector was defined or one of its descendents;
e.g., you can invoke `draw' only for objects belonging to `graphical'
or its descendents (e.g., `circle'). The scoping mechanism will check
if you try to invoke a selector that is not defined in this class
hierarchy, so you'll get an error at compilation time.

The `oof.fs' base class
.......................

   When you define a class, you have to specify a parent class.  So how
do you start defining classes? There is one class available from the
start: `object'. You have to use it as ancestor for all classes. It is
the only class that has no parent. Classes are also objects, except that
they don't have instance variables; class manipulation such as
inheritance or changing definitions of a class is handled through
selectors of the class `object'.

   `object' provides a number of selectors:

   * `class' for subclassing, `definitions' to add definitions later
     on, and `class?' to get type informations (is the class a subclass
     of the class passed on the stack?).

     `class'       "name" -         oof       ``class''

     `definitions'       -         oof       ``definitions''

     `class?'       o - flag         oof       ``class-query''

   * `init' and `dispose' as constructor and destructor of the object.
     `init' is invocated after the object's memory is allocated, while
     `dispose' also handles deallocation. Thus if you redefine
     `dispose', you have to call the parent's dispose with `super
     dispose', too.

     `init'       ... -         oof       ``init''

     `dispose'       -         oof       ``dispose''

   * `new', `new[]', `:', `ptr', `asptr', and `[]' to create named and
     unnamed objects and object arrays or object pointers.

     `new'       - o         oof       ``new''

     `new[]'       n - o         oof       ``new-array''

     `:'       "name" -         oof       ``define''

     `ptr'       "name" -         oof       ``ptr''

     `asptr'       o "name" -         oof       ``asptr''

     `[]'       n "name" -         oof       ``array''

   * `::' and `super' for explicit scoping. You should use explicit
     scoping only for super classes or classes with the same set of
     instance variables. Explicitly-scoped selectors use early binding.

     `::'       "name" -         oof       ``scope''

     `super'       "name" -         oof       ``super''

   * `self' to get the address of the object

     `self'       - o         oof       ``self''

   * `bind', `bound', `link', and `is' to assign object pointers and
     instance defers.

     `bind'       o "name" -         oof       ``bind''

     `bound'       class addr "name" -         oof       ``bound''

     `link'       "name" - class addr         oof       ``link''

     `is'       xt "name" -         oof       ``is''

   * `'' to obtain selector tokens, `send' to invocate selectors form
     the stack, and `postpone' to generate selector invocation code.

     `''       "name" - xt         oof       ``tick''

     `postpone'       "name" -         oof       ``postpone''

   * `with' and `endwith' to select the active object from the stack,
     and enable its scope. Using `with' and `endwith' also allows you
     to create code using selector `postpone' without being trapped by
     the state-smart objects.

     `with'       o -         oof       ``with''

     `endwith'       -         oof       ``endwith''


Class Declaration
.................

   * Instance variables

     `var'       size -         oof       ``var''
     Create an instance variable

   * Object pointers

     `ptr'       -         oof       ``ptr''
     Create an instance pointer

     `asptr'       class -         oof       ``asptr''
     Create an alias to an instance pointer, cast to another class.

   * Instance defers

     `defer'       -         oof       ``defer''
     Create an instance defer

   * Method selectors

     `early'       -         oof       ``early''
     Create a method selector for early binding.

     `method'       -         oof       ``method''
     Create a method selector.

   * Class-wide variables

     `static'       -         oof       ``static''
     Create a class-wide cell-sized variable.

   * End declaration

     `how:'       -         oof       ``how-to''
     End declaration, start implementation

     `class;'       -         oof       ``end-class''
     End class declaration or implementation


Class Implementation
....................

The `mini-oof.fs' model
-----------------------

   Gforth's third object oriented Forth package is a 12-liner. It uses a
mixture of the `objects.fs' and the `oof.fs' syntax, and reduces to the
bare minimum of features. This is based on a posting of Bernd Paysan in
comp.lang.forth.

Basic `mini-oof.fs' Usage
.........................

   There is a base class (`class', which allocates one cell for the
object pointer) plus seven other words: to define a method, a variable,
a class; to end a class, to resolve binding, to allocate an object and
to compile a class method.

`object'       - a-addr         mini-oof       ``object''
   OBJECT is the base class of all objects.

`method'       m v "name" - m' v         mini-oof       ``method''
   Define a selector.

`var'       m v size "name" - m v'         mini-oof       ``var''
   Define a variable with SIZE bytes.

`class'       class - class selectors vars         mini-oof       ``class''
   Start the definition of a class.

`end-class'       class selectors vars "name" -         mini-oof       ``end-class''
   End the definition of a class.

`defines'       xt class "name" -         mini-oof       ``defines''
   Bind XT to the selector NAME in class CLASS.

`new'       class - o         mini-oof       ``new''
   Create a new incarnation of the class CLASS.

`::'       class "name" -         mini-oof       ``colon-colon''
   Compile the method for the selector NAME of the class CLASS (not
immediate!).

Mini-OOF Example
................

   A short example shows how to use this package. This example, in
slightly extended form, is supplied as `moof-exm.fs'

     object class
       method init
       method draw
     end-class graphical

   This code defines a class `graphical' with an operation `draw'.  We
can perform the operation `draw' on any `graphical' object, e.g.:

     100 100 t-rex draw

   where `t-rex' is an object or object pointer, created with e.g.
`graphical new Constant t-rex'.

   For concrete graphical objects, we define child classes of the class
`graphical', e.g.:

     graphical class
       cell var circle-radius
     end-class circle \ "graphical" is the parent class
     
     :noname ( x y -- )
       circle-radius @ draw-circle ; circle defines draw
     :noname ( r -- )
       circle-radius ! ; circle defines init

   There is no implicit init method, so we have to define one. The
creation code of the object now has to call init explicitely.

     circle new Constant my-circle
     50 my-circle init

   It is also possible to add a function to create named objects with
automatic call of `init', given that all objects have `init' on the
same place:

     : new: ( .. o "name" -- )
         new dup Constant init ;
     80 circle new: large-circle

   We can draw this new circle at (100,100) with:

     100 100 my-circle draw

`mini-oof.fs' Implementation
............................

   Object-oriented systems with late binding typically use a
"vtable"-approach: the first variable in each object is a pointer to a
table, which contains the methods as function pointers. The vtable may
also contain other information.

   So first, let's declare selectors:

     : method ( m v "name" -- m' v ) Create  over , swap cell+ swap
       DOES> ( ... o -- ... ) @ over @ + @ execute ;

   During selector declaration, the number of selectors and instance
variables is on the stack (in address units). `method' creates one
selector and increments the selector number. To execute a selector, it
takes the object, fetches the vtable pointer, adds the offset, and
executes the method xt stored there. Each selector takes the object it
is invoked with as top of stack parameter; it passes the parameters
(including the object) unchanged to the appropriate method which should
consume that object.

   Now, we also have to declare instance variables

     : var ( m v size "name" -- m v' ) Create  over , +
       DOES> ( o -- addr ) @ + ;

   As before, a word is created with the current offset. Instance
variables can have different sizes (cells, floats, doubles, chars), so
all we do is take the size and add it to the offset. If your machine
has alignment restrictions, put the proper `aligned' or `faligned'
before the variable, to adjust the variable offset. That's why it is on
the top of stack.

   We need a starting point (the base object) and some syntactic sugar:

     Create object  1 cells , 2 cells ,
     : class ( class -- class selectors vars ) dup 2@ ;

   For inheritance, the vtable of the parent object has to be copied
when a new, derived class is declared. This gives all the methods of
the parent class, which can be overridden, though.

     : end-class  ( class selectors vars "name" -- )
       Create  here >r , dup , 2 cells ?DO ['] noop , 1 cells +LOOP
       cell+ dup cell+ r> rot @ 2 cells /string move ;

   The first line creates the vtable, initialized with `noop's. The
second line is the inheritance mechanism, it copies the xts from the
parent vtable.

   We still have no way to define new methods, let's do that now:

     : defines ( xt class "name" -- ) ' >body @ + ! ;

   To allocate a new object, we need a word, too:

     : new ( class -- o )  here over @ allot swap over ! ;

   Sometimes derived classes want to access the method of the parent
object. There are two ways to achieve this with Mini-OOF: first, you
could use named words, and second, you could look up the vtable of the
parent object.

     : :: ( class "name" -- ) ' >body @ + @ compile, ;

   Nothing can be more confusing than a good example, so here is one.
First let's declare a text object (called `button'), that stores text
and position:

     object class
       cell var text
       cell var len
       cell var x
       cell var y
       method init
       method draw
     end-class button

Now, implement the two methods, `draw' and `init':

     :noname ( o -- )
      >r r@ x @ r@ y @ at-xy  r@ text @ r> len @ type ;
      button defines draw
     :noname ( addr u o -- )
      >r 0 r@ x ! 0 r@ y ! r@ len ! r> text ! ;
      button defines init

To demonstrate inheritance, we define a class `bold-button', with no
new data and no new selectors:

     button class
     end-class bold-button
     
     : bold   27 emit ." [1m" ;
     : normal 27 emit ." [0m" ;

The class `bold-button' has a different draw method to `button', but
the new method is defined in terms of the draw method for `button':

     :noname bold [ button :: draw ] normal ; bold-button defines draw

Finally, create two objects and apply selectors:

     button new Constant foo
     s" thin foo" foo init
     page
     foo draw
     bold-button new Constant bar
     s" fat bar" bar init
     1 bar y !
     bar draw

Comparison with other object models
-----------------------------------

   Many object-oriented Forth extensions have been proposed (`A survey
of object-oriented Forths' (SIGPLAN Notices, April 1996) by Bradford J.
Rodriguez and W. F. S. Poehlman lists 17). This section discusses the
relation of the object models described here to two well-known and two
closely-related (by the use of method maps) models.  Andras Zsoter
helped us with this section.

   The most popular model currently seems to be the Neon model (see
`Object-oriented programming in ANS Forth' (Forth Dimensions, March
1997) by Andrew McKewan) but this model has a number of limitations (1):

   * It uses a `_selector object_' syntax, which makes it unnatural to
     pass objects on the stack.

   * It requires that the selector parses the input stream (at compile
     time); this leads to reduced extensibility and to bugs that are
     hard to find.

   * It allows using every selector on every object; this eliminates the
     need for interfaces, but makes it harder to create efficient
     implementations.

   Another well-known publication is `Object-Oriented Forth' (Academic
Press, London, 1987) by Dick Pountain. However, it is not really about
object-oriented programming, because it hardly deals with late binding.
Instead, it focuses on features like information hiding and overloading
that are characteristic of modular languages like Ada (83).

   In Does late binding have to be slow?
(http://www.forth.org/oopf.html) (Forth Dimensions 18(1) 1996, pages
31-35) Andras Zsoter describes a model that makes heavy use of an
active object (like `this' in `objects.fs'): The active object is not
only used for accessing all fields, but also specifies the receiving
object of every selector invocation; you have to change the active
object explicitly with `{ ... }', whereas in `objects.fs' it changes
more or less implicitly at `m: ... ;m'. Such a change at the method
entry point is unnecessary with Zsoter's model, because the receiving
object is the active object already. On the other hand, the explicit
change is absolutely necessary in that model, because otherwise no one
could ever change the active object. An ANS Forth implementation of
this model is available through `http://www.forth.org/oopf.html'.

   The `oof.fs' model combines information hiding and overloading
resolution (by keeping names in various word lists) with object-oriented
programming. It sets the active object implicitly on method entry, but
also allows explicit changing (with `>o...o>' or with
`with...endwith'). It uses parsing and state-smart objects and classes
for resolving overloading and for early binding: the object or class
parses the selector and determines the method from this. If the
selector is not parsed by an object or class, it performs a call to the
selector for the active object (late binding), like Zsoter's model.
Fields are always accessed through the active object. The big
disadvantage of this model is the parsing and the state-smartness, which
reduces extensibility and increases the opportunities for subtle bugs;
essentially, you are only safe if you never tick or `postpone' an
object or class (Bernd disagrees, but I (Anton) am not convinced).

   The `mini-oof.fs' model is quite similar to a very stripped-down
version of the `objects.fs' model, but syntactically it is a mixture of
the `objects.fs' and `oof.fs' models.

   ---------- Footnotes ----------

   (1) A longer version of this critique can be found in `On
Standardizing Object-Oriented Forth Extensions' (Forth Dimensions, May
1997) by Anton Ertl.

Programming Tools
=================

Examining data and code
-----------------------

   The following words inspect the stack non-destructively:

`.s'       -         tools       ``dot-s''
   Display the number of items on the data stack, followed by a list of
the items; TOS is the right-most item.

`f.s'       -         gforth       ``f-dot-s''
   Display the number of items on the floating-point stack, followed by
a list of the items; TOS is the right-most item.

   There is a word `.r' but it does not display the return stack!  It
is used for formatted numeric output (*note Simple numeric output::).

`depth'       - +n         core       ``depth''
   +N is the number of values that were on the data stack before +N
itself was placed on the stack.

`fdepth'       - +n         float       ``f-depth''
   +n is the current number of (floating-point) values on the
floating-point stack.

`clearstack'       ... -         gforth       ``clear-stack''
   remove and discard all/any items from the data stack.

   The following words inspect memory.

`?'       a-addr -         tools       ``question''
   Display the contents of address A-ADDR in the current number base.

`dump'       addr u -         tools       ``dump''
   Display U lines of memory starting at address ADDR. Each line
displays the contents of 16 bytes. When Gforth is running under an
operating system you may get `Invalid memory address' errors if you
attempt to access arbitrary locations.

   And finally, `see' allows to inspect code:

`see'       "<spaces>name" -         tools       ``see''
   Locate NAME using the current search order. Display the definition
of NAME. Since this is achieved by decompiling the definition, the
formatting is mechanised and some source information (comments,
interpreted sequences within definitions etc.) is lost.

`xt-see'       xt -         gforth       ``xt-see''
   Decompile the definition represented by xt.

Forgetting words
----------------

   Forth allows you to forget words (and everything that was alloted in
the dictonary after them) in a LIFO manner.

`marker'       "<spaces> name" -         core-ext       ``marker''
   Create a definition, name (called a mark) whose execution semantics
are to remove itself and everything defined after it.

   The most common use of this feature is during progam development:
when you change a source file, forget all the words it defined and load
it again (since you also forget everything defined after the source file
was loaded, you have to reload that, too).  Note that effects like
storing to variables and destroyed system words are not undone when you
forget words.  With a system like Gforth, that is fast enough at
starting up and compiling, I find it more convenient to exit and restart
Gforth, as this gives me a clean slate.

   Here's an example of using `marker' at the start of a source file
that you are debugging; it ensures that you only ever have one copy of
the file's definitions compiled at any time:

     [IFDEF] my-code
         my-code
     [ENDIF]
     
     marker my-code
     init-included-files
     
     \ .. definitions start here
     \ .
     \ .
     \ end

Debugging
---------

   Languages with a slow edit/compile/link/test development loop tend to
require sophisticated tracing/stepping debuggers to facilate debugging.

   A much better (faster) way in fast-compiling languages is to add
printing code at well-selected places, let the program run, look at the
output, see where things went wrong, add more printing code, etc.,
until the bug is found.

   The simple debugging aids provided in `debugs.fs' are meant to
support this style of debugging.

   The word `~~' prints debugging information (by default the source
location and the stack contents). It is easy to insert. If you use Emacs
it is also easy to remove (`C-x ~' in the Emacs Forth mode to
query-replace them with nothing). The deferred words `printdebugdata'
and `printdebugline' control the output of `~~'. The default source
location output format works well with Emacs' compilation mode, so you
can step through the program at the source level using `C-x `' (the
advantage over a stepping debugger is that you can step in any
direction and you know where the crash has happened or where the
strange data has occurred).

`~~'       compilation  - ; run-time  -         gforth       ``tilde-tilde''

`printdebugdata'       -         gforth       ``print-debug-data''

`printdebugline'       addr -         gforth       ``print-debug-line''

Assertions
----------

   It is a good idea to make your programs self-checking, especially if
you make an assumption that may become invalid during maintenance (for
example, that a certain field of a data structure is never zero). Gforth
supports "assertions" for this purpose. They are used like this:

     assert( flag )

   The code between `assert(' and `)' should compute a flag, that
should be true if everything is alright and false otherwise. It should
not change anything else on the stack. The overall stack effect of the
assertion is `( -- )'. E.g.

     assert( 1 1 + 2 = ) \ what we learn in school
     assert( dup 0<> ) \ assert that the top of stack is not zero
     assert( false ) \ this code should not be reached

   The need for assertions is different at different times. During
debugging, we want more checking, in production we sometimes care more
for speed. Therefore, assertions can be turned off, i.e., the assertion
becomes a comment. Depending on the importance of an assertion and the
time it takes to check it, you may want to turn off some assertions and
keep others turned on. Gforth provides several levels of assertions for
this purpose:

`assert0('       -         gforth       ``assert-zero''
   Important assertions that should always be turned on.

`assert1('       -         gforth       ``assert-one''
   Normal assertions; turned on by default.

`assert2('       -         gforth       ``assert-two''
   Debugging assertions.

`assert3('       -         gforth       ``assert-three''
   Slow assertions that you may not want to turn on in normal debugging;
you would turn them on mainly for thorough checking.

`assert('       -         gforth       ``assert(''
   Equivalent to `assert1('

`)'       -         gforth       ``close-paren''
   End an assertion.

   The variable `assert-level' specifies the highest assertions that
are turned on. I.e., at the default `assert-level' of one, `assert0('
and `assert1(' assertions perform checking, while `assert2(' and
`assert3(' assertions are treated as comments.

   The value of `assert-level' is evaluated at compile-time, not at
run-time. Therefore you cannot turn assertions on or off at run-time;
you have to set the `assert-level' appropriately before compiling a
piece of code. You can compile different pieces of code at different
`assert-level's (e.g., a trusted library at level 1 and newly-written
code at level 3).

`assert-level'       - a-addr         gforth       ``assert-level''
   All assertions above this level are turned off.

   If an assertion fails, a message compatible with Emacs' compilation
mode is produced and the execution is aborted (currently with `ABORT"'.
If there is interest, we will introduce a special throw code. But if you
intend to `catch' a specific condition, using `throw' is probably more
appropriate than an assertion).

   Definitions in ANS Forth for these assertion words are provided in
`compat/assert.fs'.

Singlestep Debugger
-------------------

   When you create a new word there's often the need to check whether it
behaves correctly or not. You can do this by typing `dbg badword'. A
debug session might look like this:

     : badword 0 DO i . LOOP ;  ok
     2 dbg badword
     : badword
     Scanning code...
     
     Nesting debugger ready!
     
     400D4738  8049BC4 0              -> [ 2 ] 00002 00000
     400D4740  8049F68 DO             -> [ 0 ]
     400D4744  804A0C8 i              -> [ 1 ] 00000
     400D4748 400C5E60 .              -> 0 [ 0 ]
     400D474C  8049D0C LOOP           -> [ 0 ]
     400D4744  804A0C8 i              -> [ 1 ] 00001
     400D4748 400C5E60 .              -> 1 [ 0 ]
     400D474C  8049D0C LOOP           -> [ 0 ]
     400D4758  804B384 ;              ->  ok

   Each line displayed is one step. You always have to hit return to
execute the next word that is displayed. If you don't want to execute
the next word in a whole, you have to type `n' for `nest'. Here is an
overview what keys are available:

<RET>
     Next; Execute the next word.

n
     Nest; Single step through next word.

u
     Unnest; Stop debugging and execute rest of word. If we got to this
     word with nest, continue debugging with the calling word.

d
     Done; Stop debugging and execute rest.

s
     Stop; Abort immediately.

   Debugging large application with this mechanism is very difficult,
because you have to nest very deeply into the program before the
interesting part begins. This takes a lot of time.

   To do it more directly put a `BREAK:' command into your source code.
When program execution reaches `BREAK:' the single step debugger is
invoked and you have all the features described above.

   If you have more than one part to debug it is useful to know where
the program has stopped at the moment. You can do this by the `BREAK"
string"' command. This behaves like `BREAK:' except that string is
typed out when the "breakpoint" is reached.

`dbg'       "name" -         gforth       ``dbg''

`break:'       -         gforth       ``break:''

`break"'       'ccc"' -         gforth       ``break"''

Assembler and Code Words
========================

`Code' and `;code'
------------------

   Gforth provides some words for defining primitives (words written in
machine code), and for defining the machine-code equivalent of
`DOES>'-based defining words. However, the machine-independent nature
of Gforth poses a few problems: First of all, Gforth runs on several
architectures, so it can provide no standard assembler. What's worse is
that the register allocation not only depends on the processor, but
also on the `gcc' version and options used.

   The words that Gforth offers encapsulate some system dependences
(e.g., the header structure), so a system-independent assembler may be
used in Gforth. If you do not have an assembler, you can compile
machine code directly with `,' and `c,'(1).

`assembler'       -         tools-ext       ``assembler''

`init-asm'       -         gforth       ``init-asm''

`code'       "name" - colon-sys         tools-ext       ``code''

`end-code'       colon-sys -         gforth       ``end-code''

`;code'       compilation. colon-sys1 - colon-sys2         tools-ext       ``semicolon-code''

`flush-icache'       c-addr u -        gforth       ``flush-icache''
   Make sure that the instruction cache of the processor (if there is
one) does not contain stale data at c-addr and u bytes afterwards.
`END-CODE' performs a `flush-icache' automatically. Caveat:
`flush-icache' might not work on your installation; this is usually the
case if direct threading is not supported on your machine (take a look
at your `machine.h') and your machine has a separate instruction cache.
In such cases, `flush-icache' does nothing instead of flushing the
instruction cache.

   If `flush-icache' does not work correctly, `code' words etc. will
not work (reliably), either.

   The typical usage of these `code' words can be shown most easily by
analogy to the equivalent high-level defining words:

     : foo                              code foo
        <high-level Forth words>              <assembler>
     ;                                  end-code
     
     : bar                              : bar
        <high-level Forth words>           <high-level Forth words>
        CREATE                             CREATE
           <high-level Forth words>           <high-level Forth words>
        DOES>                              ;code
           <high-level Forth words>           <assembler>
     ;                                  end-code

   In the assembly code you will want to refer to the inner
interpreter's registers (e.g., the data stack pointer) and you may want
to use other registers for temporary storage. Unfortunately, the
register allocation is installation-dependent.

   In particular, `ip' (Forth instruction pointer) and `rp' (return
stack pointer) are in different places in `gforth' and `gforth-fast'.
This means that you cannot write a `NEXT' routine that works on both
versions; so for doing `NEXT', I recomment jumping to `' noop
>code-address', which contains nothing but a `NEXT'.

   For general accesses to the inner interpreter's registers, the
easiest solution is to use explicit register declarations (*note
Variables in Specified Registers: (gcc.info)Explicit Reg Vars.) for all
of the inner interpreter's registers: You have to compile Gforth with
`-DFORCE_REG' (configure option `--enable-force-reg') and the
appropriate declarations must be present in the `machine.h' file (see
`mips.h' for an example; you can find a full list of all declarable
register symbols with `grep register engine.c'). If you give explicit
registers to all variables that are declared at the beginning of
`engine()', you should be able to use the other caller-saved registers
for temporary storage. Alternatively, you can use the `gcc' option
`-ffixed-REG' (*note Options for Code Generation Conventions:
(gcc.info)Code Gen Options.) to reserve a register (however, this
restriction on register allocation may slow Gforth significantly).

   If this solution is not viable (e.g., because `gcc' does not allow
you to explicitly declare all the registers you need), you have to find
out by looking at the code where the inner interpreter's registers
reside and which registers can be used for temporary storage. You can
get an assembly listing of the engine's code with `make engine.s'.

   In any case, it is good practice to abstract your assembly code from
the actual register allocation. E.g., if the data stack pointer resides
in register `$17', create an alias for this register called `sp', and
use that in your assembly code.

   Another option for implementing normal and defining words efficiently
is to add the desired functionality to the source of Gforth. For normal
words you just have to edit `primitives' (*note Automatic
Generation::). Defining words (equivalent to `;CODE' words, for fast
defined words) may require changes in `engine.c', `kernel.fs',
`prims2x.fs', and possibly `cross.fs'.

   ---------- Footnotes ----------

   (1) This isn't portable, because these words emit stuff in data
space; it works because Gforth has unified code/data spaces. Assembler
isn't likely to be portable anyway.

Common Assembler
----------------

   The assemblers in Gforth generally use a postfix syntax, i.e., the
instruction name follows the operands.

   The operands are passed in the usual order (the same that is used in
the manual of the architecture).  Since they all are Forth words, they
have to be separated by spaces; you can also use Forth words to compute
the operands.

   The instruction names usually end with a `,'.  This makes it easier
to visually separate instructions if you put several of them on one
line; it also avoids shadowing other Forth words (e.g., `and').

   Registers are usually specified by number; e.g., (decimal) `11'
specifies registers R11 and F11 on the Alpha architecture (which one,
depends on the instruction).  The usual names are also available, e.g.,
`s2' for R11 on Alpha.

   Control flow is specified similar to normal Forth code (*note
Arbitrary control structures::), with `if,', `ahead,', `then,',
`begin,', `until,', `again,', `cs-roll', `cs-pick', `else,', `while,',
and `repeat,'.  The conditions are specified in a way specific to each
assembler.

   Note that the register assignments of the Gforth engine can change
between Gforth versions, or even between different compilations of the
same Gforth version (e.g., if you use a different GCC version).  So if
you want to refer to Gforth's registers (e.g., the stack pointer or
TOS), I recommend defining your own words for refering to these
registers, and using them later on; then you can easily adapt to a
changed register assignment.  The stability of the register assignment
is usually better if you build Gforth with `--enable-force-reg'.

   In particular, the return stack pointer and the instruction pointer
are in memory in `gforth', and usually in registers in `gforth-fast'.
The most common use of these registers is to dispatch to the next word
(the `next' routine).  A portable way to do this is to jump to `' noop
>code-address' (of course, this is less efficient than integrating the
`next' code and scheduling it well).

Common Disassembler
-------------------

   You can disassemble a `code' word with `see' (*note Debugging::).
You can disassemble a section of memory with

   doc-disasm

   The disassembler generally produces output that can be fed into the
assembler (i.e., same syntax, etc.).  It also includes additional
information in comments.  In particular, the address of the instruction
is given in a comment before the instruction.

   `See' may display more or less than the actual code of the word,
because the recognition of the end of the code is unreliable.  You can
use `disasm' if it did not display enough.  It may display more, if the
code word is not immediately followed by a named word.  If you have
something else there, you can follow the word with `align last  ,' to
ensure that the end is recognized.

386 Assembler
-------------

   The 386 assembler included in Gforth was written by Bernd Paysan,
it's available under GPL, and originally part of bigFORTH.

   The 386 disassembler included in Gforth was written by Andrew McKewan
and is in the public domain.

   The disassembler displays code in prefix Intel syntax.

   The assembler uses a postfix syntax with reversed parameters.

   The assembler includes all instruction of the Athlon, i.e. 486 core
instructions, Pentium and PPro extensions, floating point, MMX, 3Dnow!,
but not ISSE. It's an integrated 16- and 32-bit assembler. Default is 32
bit, you can switch to 16 bit with .86 and back to 32 bit with .386.

   There are several prefixes to switch between different operation
sizes, `.b' for byte accesses, `.w' for word accesses, `.d' for
double-word accesses. Addressing modes can be switched with `.wa' for
16 bit addresses, and `.da' for 32 bit addresses. You don't need a
prefix for byte register names (`AL' et al).

   For floating point operations, the prefixes are `.fs' (IEEE single),
`.fl' (IEEE double), `.fx' (extended), `.fw' (word), `.fd'
(double-word), and `.fq' (quad-word).

   The MMX opcodes don't have size prefixes, they are spelled out like
in the Intel assembler. Instead of move from and to memory, there are
PLDQ/PLDD and PSTQ/PSTD.

   The registers lack the 'e' prefix; even in 32 bit mode, eax is called
ax.  Immediate values are indicated by postfixing them with `#', e.g.,
`3 #'.  Here are some examples of addressing modes:

     3 #          \ immediate
     1000 #)      \ absolute
     ax           \ register
     100 di d)    \ 100[edi]
     4 bx cx di)  \ 4[ebx][ecx]
     di ax *4 i)  \ [edi][eax*4]
     20 ax *4 i#) \ 20[eax*4]

   Some example of instructions are:

     ax bx mov             \ move ebx,eax
     3 # ax mov            \ mov eax,3
     100 di ) ax mov       \ mov eax,100[edi]
     4 bx cx di) ax mov    \ mov eax,4[ebx][ecx]
     .w ax bx mov          \ mov bx,ax

   The following forms are supported for binary instructions:

     <reg> <reg> <inst>
     <n> # <reg> <inst>
     <mem> <reg> <inst>
     <reg> <mem> <inst>

   Immediate to memory is not supported.  The shift/rotate syntax is:

     <reg/mem> 1 # shl \ shortens to shift without immediate
     <reg/mem> 4 # shl
     <reg/mem> cl shl

   Precede string instructions (`movs' etc.) with `.b' to get the byte
version.

   The control structure words `IF' `UNTIL' etc. must be preceded by
one of these conditions: `vs vc u< u>= 0= 0<> u<= u> 0< 0>= ps pc < >=
<= >'. (Note that most of these words shadow some Forth words when
`assembler' is in front of `forth' in the search path, e.g., in `code'
words).  Currently the control structure words use one stack item, so
you have to use `roll' instead of `cs-roll' to shuffle them (you can
also use `swap' etc.).

   Here is an example of a `code' word (assumes that the stack pointer
is in esi and the TOS is in ebx):

     code my+ ( n1 n2 -- n )
         4 si D) bx add
         4 # si add
         Next
     end-code

Alpha Assembler
---------------

   The Alpha assembler and disassembler were originally written by Bernd
Thallner.

   The register names `a0'-`a5' are not available to avoid shadowing
hex numbers.

   Immediate forms of arithmetic instructions are distinguished by a
`#' just before the `,', e.g., `and#,' (note: `lda,' does not count as
arithmetic instruction).

   You have to specify all operands to an instruction, even those that
other assemblers consider optional, e.g., the destination register for
`br,', or the destination register and hint for `jmp,'.

   You can specify conditions for `if,' by removing the first `b' and
the trailing `,' from a branch with a corresponding name; e.g.,

     11 fgt if, \ if F11>0e
       ...
     endif,

   `fbgt,' gives `fgt'.

MIPS assembler
--------------

   The MIPS assembler was originally written by Christian Pirker.

   Currently the assembler and disassembler only cover the MIPS-I
architecture (R3000), and don't support FP instructions.

   The register names `$a0'-`$a3' are not available to avoid shadowing
hex numbers.

   Because there is no way to distinguish registers from immediate
values, you have to explicitly use the immediate forms of instructions,
i.e., `addiu,', not just `addu,' (`as' does this implicitly).

   If the architecture manual specifies several formats for the
instruction (e.g., for `jalr,'), you usually have to use the one with
more arguments (i.e., two for `jalr,').  When in doubt, see
`arch/mips/testasm.fs' for an example of correct use.

   Branches and jumps in the MIPS architecture have a delay slot.  You
have to fill it yourself (the simplest way is to use `nop,'), the
assembler does not do it for you (unlike `as').  Even `if,', `ahead,',
`until,', `again,', `while,', `else,' and `repeat,' need a delay slot.
Since `begin,' and `then,' just specify branch targets, they are not
affected.

   Note that you must not put branches, jumps, or `li,' into the delay
slot: `li,' may expand to several instructions, and control flow
instructions may not be put into the branch delay slot in any case.

   For branches the argument specifying the target is a relative
address; You have to add the address of the delay slot to get the
absolute address.

   The MIPS architecture also has load delay slots and restrictions on
using `mfhi,' and `mflo,'; you have to order the instructions yourself
to satisfy these restrictions, the assembler does not do it for you.

   You can specify the conditions for `if,' etc. by taking a
conditional branch and leaving away the `b' at the start and the `,' at
the end.  E.g.,

     4 5 eq if,
       ... \ do something if $4 equals $5
     then,

Other assemblers
----------------

   If you want to contribute another assembler/disassembler, please
contact us (<bug-gforth@gnu.org>) to check if we have such an assembler
already.  If you are writing them from scratch, please use a similar
syntax style as the one we use (i.e., postfix, commas at the end of the
instruction names, *note Common Assembler::); make the output of the
disassembler be valid input for the assembler, and keep the style
similar to the style we used.

   Hints on implementation: The most important part is to have a good
test suite that contains all instructions.  Once you have that, the
rest is easy.  For actual coding you can take a look at
`arch/mips/disasm.fs' to get some ideas on how to use data for both the
assembler and disassembler, avoiding redundancy and some potential
bugs.  You can also look at that file (and *note Advanced does> usage
example::) to get ideas how to factor a disassembler.

   Start with the disassembler, because it's easier to reuse data from
the disassembler for the assembler than the other way round.

   For the assembler, take a look at `arch/alpha/asm.fs', which shows
how simple it can be.

Threading Words
===============

   These words provide access to code addresses and other threading
stuff in Gforth (and, possibly, other interpretive Forths). It more or
less abstracts away the differences between direct and indirect
threading (and, for direct threading, the machine dependences).
However, at present this wordset is still incomplete. It is also pretty
low-level; some day it will hopefully be made unnecessary by an
internals wordset that abstracts implementation details away completely.

   The terminology used here stems from indirect threaded Forth
systems; in such a system, the XT of a word is represented by the CFA
(code field address) of a word; the CFA points to a cell that contains
the code address.  The code address is the address of some machine code
that performs the run-time action of invoking the word (e.g., the
`dovar:' routine pushes the address of the body of the word (a
variable) on the stack ).

   In an indirect threaded Forth, you can get the code address of name
with `' name @'; in Gforth you can get it with `' name >code-address',
independent of the threading method.

`threading-method'       - n        gforth       ``threading-method''
   0 if the engine is direct threaded. Note that this may change during
the lifetime of an image.

`>code-address'       xt - c-addr        gforth       ``to-code-address''
   c-addr is the code address of the word xt.

`code-address!'       c-addr xt -        gforth       ``code-address-store''
   Create a code field with code address c-addr at xt.

   For a word defined with `DOES>', the code address usually points to
a jump instruction (the "does-handler") that jumps to the dodoes
routine (in Gforth on some platforms, it can also point to the dodoes
routine itself).  What you are typically interested in, though, is
whether a word is a `DOES>'-defined word, and what Forth code it
executes; `>does-code' tells you that.

`>does-code'       xt - a-addr        gforth       ``to-does-code''
   If xt is the execution token of a child of a `DOES>' word, a-addr is
the start of the Forth code after the `DOES>'; Otherwise a-addr is 0.

   To create a `DOES>'-defined word with the following basic words, you
have to set up a `DOES>'-handler with `does-handler!'; `/does-handler'
aus behind you have to place your executable Forth code.  Finally you
have to create a word and modify its behaviour with `does-handler!'.

`does-code!'       a-addr xt -        gforth       ``does-code-store''
   Create a code field at xt for a child of a `DOES>'-word; a-addr is
the start of the Forth code after `DOES>'.

`does-handler!'       a-addr -        gforth       ``does-handler-store''
   Create a `DOES>'-handler at address a-addr. Normally, a-addr points
just behind a `DOES>'.

`/does-handler'       - n        gforth       ``slash-does-handler''
   The size of a `DOES>'-handler (includes possible padding).

   The code addresses produced by various defining words are produced by
the following words:

`docol:'       - addr         gforth       ``docol:''
   The code address of a colon definition.

`docon:'       - addr         gforth       ``docon:''
   The code address of a `CONSTANT'.

`dovar:'       - addr         gforth       ``dovar:''
   The code address of a `CREATE'd word.

`douser:'       - addr         gforth       ``douser:''
   The code address of a `USER' variable.

`dodefer:'       - addr         gforth       ``dodefer:''
   The code address of a `defer'ed word.

`dofield:'       - addr         gforth       ``dofield:''
   The code address of a `field'.

Passing Commands to the Operating System
========================================

   Gforth allows you to pass an arbitrary string to the host operating
system shell (if such a thing exists) for execution.

`sh'       "..." -         gforth       ``sh''
   Parse a string and use `system' to pass it to the host operating
system for execution in a sub-shell.

`system'       c-addr u -         gforth       ``system''
   Pass the string specified by C-ADDR U to the host operating system
for execution in a sub-shell.

`$?'       - n         gforth       ``dollar-question''
   `Value' - the exit status returned by the most recently executed
`system' command.

`getenv'       c-addr1 u1 - c-addr2 u2        gforth       ``getenv''
   The string c-addr1 u1 specifies an environment variable. The string
c-addr2 u2 is the host operating system's expansion of that environment
variable. If the environment variable does not exist, c-addr2 u2
specifies a string 0 characters in length.

Keeping track of Time
=====================

`ms'       n -        facility-ext       ``ms''
   Wait at least n milli-second.

`time&date'       - nsec nmin nhour nday nmonth nyear        facility-ext       ``time-and-date''
   Report the current time of day. Seconds, minutes and hours are
numbered from 0.  Months are numbered from 1.

`utime'       - dtime        gforth       ``utime''
   Report the current time in microseconds since some epoch.

`cputime'       - duser dsystem        gforth       ``cputime''
   duser and dsystem are the respective user- and system-level CPU
times used since the start of the Forth system (excluding child
processes), in microseconds (the granularity may be much larger,
however).  On platforms without the getrusage call, it reports elapsed
time (since some epoch) for duser and 0 for dsystem.

Miscellaneous Words
===================

   These section lists the ANS Forth words that are not documented
elsewhere in this manual. Ultimately, they all need proper homes.

`quit'       ?? - ??         core       ``quit''
   Empty the return stack, make the user input device the input source,
enter interpret state and start the text interpreter.

   The following ANS Forth words are not currently supported by Gforth
(*note ANS conformance::):

   `EDITOR' `EMIT?' `FORGET'

Error messages
**************

   A typical Gforth error message looks like this:

     in file included from \evaluated string/:-1
     in file included from ./yyy.fs:1
     ./xxx.fs:4: Invalid memory address
     bar
     ^^^
     Backtrace:
     $400E664C @
     $400E6664 foo

   The message identifying the error is `Invalid memory address'.  The
error happened when text-interpreting line 4 of the file `./xxx.fs'.
This line is given (it contains `bar'), and the word on the line where
the error happened, is pointed out (with `^^^').

   The file containing the error was included in line 1 of `./yyy.fs',
and `yyy.fs' was included from a non-file (in this case, by giving
`yyy.fs' as command-line parameter to Gforth).

   At the end of the error message you find a return stack dump that
can be interpreted as a backtrace (possibly empty). On top you find the
top of the return stack when the `throw' happened, and at the bottom you
find the return stack entry just above the return stack of the topmost
text interpreter.

   To the right of most return stack entries you see a guess for the
word that pushed that return stack entry as its return address. This
gives a backtrace. In our case we see that `bar' called `foo', and
`foo' called `@' (and `@' had an _Invalid memory address_ exception).

   Note that the backtrace is not perfect: We don't know which return
stack entries are return addresses (so we may get false positives); and
in some cases (e.g., for `abort"') we cannot determine from the return
address the word that pushed the return address, so for some return
addresses you see no names in the return stack dump.

   The return stack dump represents the return stack at the time when a
specific `throw' was executed.  In programs that make use of `catch',
it is not necessarily clear which `throw' should be used for the return
stack dump (e.g., consider one `throw' that indicates an error, which
is caught, and during recovery another error happens; which `throw'
should be used for the stack dump?).  Gforth presents the return stack
dump for the first `throw' after the last executed (not returned-to)
`catch'; this works well in the usual case.

   `Gforth' is able to do a return stack dump for throws generated from
primitives (e.g., invalid memory address, stack empty etc.);
`gforth-fast' is only able to do a return stack dump from a directly
called `throw' (including `abort' etc.).  This is the only difference
(apart from a speed factor of between 1.15 (K6-2) and 2 (21264))
between `gforth' and `gforth-fast'.  Given an exception caused by a
primitive in `gforth-fast', you will typically see no return stack dump
at all; however, if the exception is caught by `catch' (e.g., for
restoring some state), and then `throw'n again, the return stack dump
will be for the first such `throw'.

Tools
*****

   See also *Note Emacs and Gforth::.

`ans-report.fs': Report the words used, sorted by wordset
=========================================================

   If you want to label a Forth program as ANS Forth Program, you must
document which wordsets the program uses; for extension wordsets, it is
helpful to list the words the program requires from these wordsets
(because Forth systems are allowed to provide only some words of them).

   The `ans-report.fs' tool makes it easy for you to determine which
words from which wordset and which non-ANS words your application uses.
You simply have to include `ans-report.fs' before loading the program
you want to check. After loading your program, you can get the report
with `print-ans-report'. A typical use is to run this as batch job like
this:
     gforth ans-report.fs myprog.fs -e "print-ans-report bye"

   The output looks like this (for `compat/control.fs'):
     The program uses the following words
     from CORE :
     : POSTPONE THEN ; immediate ?dup IF 0=
     from BLOCK-EXT :
     \
     from FILE :
     (

Caveats
-------

   Note that `ans-report.fs' just checks which words are used, not
whether they are used in an ANS Forth conforming way!

   Some words are defined in several wordsets in the standard.
`ans-report.fs' reports them for only one of the wordsets, and not
necessarily the one you expect. It depends on usage which wordset is
the right one to specify. E.g., if you only use the compilation
semantics of `S"', it is a Core word; if you also use its
interpretation semantics, it is a File word.

ANS conformance
***************

   To the best of our knowledge, Gforth is an

   ANS Forth System
   * providing the Core Extensions word set

   * providing the Block word set

   * providing the Block Extensions word set

   * providing the Double-Number word set

   * providing the Double-Number Extensions word set

   * providing the Exception word set

   * providing the Exception Extensions word set

   * providing the Facility word set

   * providing `EKEY', `EKEY>CHAR', `EKEY?', `MS' and `TIME&DATE' from
     the Facility Extensions word set

   * providing the File Access word set

   * providing the File Access Extensions word set

   * providing the Floating-Point word set

   * providing the Floating-Point Extensions word set

   * providing the Locals word set

   * providing the Locals Extensions word set

   * providing the Memory-Allocation word set

   * providing the Memory-Allocation Extensions word set (that one's
     easy)

   * providing the Programming-Tools word set

   * providing `;CODE', `AHEAD', `ASSEMBLER', `BYE', `CODE', `CS-PICK',
     `CS-ROLL', `STATE', `[ELSE]', `[IF]', `[THEN]' from the
     Programming-Tools Extensions word set

   * providing the Search-Order word set

   * providing the Search-Order Extensions word set

   * providing the String word set

   * providing the String Extensions word set (another easy one)

   In addition, ANS Forth systems are required to document certain
implementation choices. This chapter tries to meet these requirements.
In many cases it gives a way to ask the system for the information
instead of providing the information directly, in particular, if the
information depends on the processor, the operating system or the
installation options chosen, or if they are likely to change during the
maintenance of Gforth.

The Core Words
==============

Implementation Defined Options
------------------------------

(Cell) aligned addresses:
     processor-dependent. Gforth's alignment words perform natural
     alignment (e.g., an address aligned for a datum of size 8 is
     divisible by 8). Unaligned accesses usually result in a `-23
     THROW'.

`EMIT' and non-graphic characters:
     The character is output using the C library function (actually,
     macro) `putc'.

character editing of `ACCEPT' and `EXPECT':
     This is modeled on the GNU readline library (*note Command Line
     Editing: (readline)Readline Interaction.) with Emacs-like key
     bindings. `Tab' deviates a little by producing a full word
     completion every time you type it (instead of producing the common
     prefix of all completions). *Note Command-line editing::.

character set:
     The character set of your computer and display device. Gforth is
     8-bit-clean (but some other component in your system may make
     trouble).

Character-aligned address requirements:
     installation-dependent. Currently a character is represented by a C
     `unsigned char'; in the future we might switch to `wchar_t'
     (Comments on that requested).

character-set extensions and matching of names:
     Any character except the ASCII NUL character can be used in a
     name. Matching is case-insensitive (except in `TABLE's). The
     matching is performed using the C library function `strncasecmp',
     whose function is probably influenced by the locale. E.g., the `C'
     locale does not know about accents and umlauts, so they are matched
     case-sensitively in that locale. For portability reasons it is
     best to write programs such that they work in the `C' locale. Then
     one can use libraries written by a Polish programmer (who might
     use words containing ISO Latin-2 encoded characters) and by a
     French programmer (ISO Latin-1) in the same program (of course,
     `WORDS' will produce funny results for some of the words (which
     ones, depends on the font you are using)). Also, the locale you
     prefer may not be available in other operating systems. Hopefully,
     Unicode will solve these problems one day.

conditions under which control characters match a space delimiter:
     If `WORD' is called with the space character as a delimiter, all
     white-space characters (as identified by the C macro `isspace()')
     are delimiters. `PARSE', on the other hand, treats space like other
     delimiters. `SWORD' treats space like `WORD', but behaves like
     `PARSE' otherwise. `Name', which is used by the outer interpreter
     (aka text interpreter) by default, treats all white-space
     characters as delimiters.

format of the control-flow stack:
     The data stack is used as control-flow stack. The size of a
     control-flow stack item in cells is given by the constant
     `cs-item-size'. At the time of this writing, an item consists of a
     (pointer to a) locals list (third), an address in the code
     (second), and a tag for identifying the item (TOS). The following
     tags are used: `defstart', `live-orig', `dead-orig', `dest',
     `do-dest', `scopestart'.

conversion of digits > 35
     The characters `[\]^_'' are the digits with the decimal value
     36-41. There is no way to input many of the larger digits.

display after input terminates in `ACCEPT' and `EXPECT':
     The cursor is moved to the end of the entered string. If the input
     is terminated using the `Return' key, a space is typed.

exception abort sequence of `ABORT"':
     The error string is stored into the variable `"error' and a `-2
     throw' is performed.

input line terminator:
     For interactive input, `C-m' (CR) and `C-j' (LF) terminate lines.
     One of these characters is typically produced when you type the
     `Enter' or `Return' key.

maximum size of a counted string:
     `s" /counted-string" environment? drop .'. Currently 255 characters
     on all platforms, but this may change.

maximum size of a parsed string:
     Given by the constant `/line'. Currently 255 characters.

maximum size of a definition name, in characters:
     31

maximum string length for `ENVIRONMENT?', in characters:
     31

method of selecting the user input device:
     The user input device is the standard input. There is currently no
     way to change it from within Gforth. However, the input can
     typically be redirected in the command line that starts Gforth.

method of selecting the user output device:
     `EMIT' and `TYPE' output to the file-id stored in the value
     `outfile-id' (`stdout' by default). Gforth uses unbuffered output
     when the user output device is a terminal, otherwise the output is
     buffered.

methods of dictionary compilation:
     What are we expected to document here?

number of bits in one address unit:
     `s" address-units-bits" environment? drop .'. 8 in all current
     platforms.

number representation and arithmetic:
     Processor-dependent. Binary two's complement on all current
     platforms.

ranges for integer types:
     Installation-dependent. Make environmental queries for `MAX-N',
     `MAX-U', `MAX-D' and `MAX-UD'. The lower bounds for unsigned (and
     positive) types is 0. The lower bound for signed types on two's
     complement and one's complement machines machines can be computed
     by adding 1 to the upper bound.

read-only data space regions:
     The whole Forth data space is writable.

size of buffer at `WORD':
     `PAD HERE - .'. 104 characters on 32-bit machines. The buffer is
     shared with the pictured numeric output string. If overwriting
     `PAD' is acceptable, it is as large as the remaining dictionary
     space, although only as much can be sensibly used as fits in a
     counted string.

size of one cell in address units:
     `1 cells .'.

size of one character in address units:
     `1 chars .'. 1 on all current platforms.

size of the keyboard terminal buffer:
     Varies. You can determine the size at a specific time using `lp@
     tib - .'. It is shared with the locals stack and TIBs of files that
     include the current file. You can change the amount of space for
     TIBs and locals stack at Gforth startup with the command line
     option `-l'.

size of the pictured numeric output buffer:
     `PAD HERE - .'. 104 characters on 32-bit machines. The buffer is
     shared with `WORD'.

size of the scratch area returned by `PAD':
     The remainder of dictionary space. `unused pad here - - .'.

system case-sensitivity characteristics:
     Dictionary searches are case-insensitive (except in `TABLE's).
     However, as explained above under character-set extensions, the
     matching for non-ASCII characters is determined by the locale you
     are using. In the default `C' locale all non-ASCII characters are
     matched case-sensitively.

system prompt:
     ` ok' in interpret state, ` compiled' in compile state.

division rounding:
     installation dependent. `s" floored" environment? drop .'. We leave
     the choice to `gcc' (what to use for `/') and to you (whether to
     use `fm/mod', `sm/rem' or simply `/').

values of `STATE' when true:
     -1.

values returned after arithmetic overflow:
     On two's complement machines, arithmetic is performed modulo
     2**bits-per-cell for single arithmetic and 4**bits-per-cell for
     double arithmetic (with appropriate mapping for signed types).
     Division by zero typically results in a `-55 throw'
     (Floating-point unidentified fault) or `-10 throw' (divide by
     zero).

whether the current definition can be found after DOES>:
     No.

Ambiguous conditions
--------------------

a name is neither a word nor a number:
     `-13 throw' (Undefined word).

a definition name exceeds the maximum length allowed:
     `-19 throw' (Word name too long)

addressing a region not inside the various data spaces of the forth system:
     The stacks, code space and header space are accessible. Machine
     code space is typically readable. Accessing other addresses gives
     results dependent on the operating system. On decent systems: `-9
     throw' (Invalid memory address).

argument type incompatible with parameter:
     This is usually not caught. Some words perform checks, e.g., the
     control flow words, and issue a `ABORT"' or `-12 THROW' (Argument
     type mismatch).

attempting to obtain the execution token of a word with undefined execution semantics:
     `-14 throw' (Interpreting a compile-only word). In some cases, you
     get an execution token for `compile-only-error' (which performs a
     `-14 throw' when executed).

dividing by zero:
     On some platforms, this produces a `-10 throw' (Division by zero);
     on other systems, this typically results in a `-55 throw'
     (Floating-point unidentified fault).

insufficient data stack or return stack space:
     Depending on the operating system, the installation, and the
     invocation of Gforth, this is either checked by the memory
     management hardware, or it is not checked. If it is checked, you
     typically get a `-3 throw' (Stack overflow), `-5 throw' (Return
     stack overflow), or `-9 throw' (Invalid memory address) (depending
     on the platform and how you achieved the overflow) as soon as the
     overflow happens. If it is not checked, overflows typically result
     in mysterious illegal memory accesses, producing `-9 throw'
     (Invalid memory address) or `-23 throw' (Address alignment
     exception); they might also destroy the internal data structure of
     `ALLOCATE' and friends, resulting in various errors in these words.

insufficient space for loop control parameters:
     Like other return stack overflows.

insufficient space in the dictionary:
     If you try to allot (either directly with `allot', or indirectly
     with `,', `create' etc.) more memory than available in the
     dictionary, you get a `-8 throw' (Dictionary overflow). If you try
     to access memory beyond the end of the dictionary, the results are
     similar to stack overflows.

interpreting a word with undefined interpretation semantics:
     For some words, we have defined interpretation semantics. For the
     others: `-14 throw' (Interpreting a compile-only word).

modifying the contents of the input buffer or a string literal:
     These are located in writable memory and can be modified.

overflow of the pictured numeric output string:
     `-17 throw' (Pictured numeric ouput string overflow).

parsed string overflow:
     `PARSE' cannot overflow. `WORD' does not check for overflow.

producing a result out of range:
     On two's complement machines, arithmetic is performed modulo
     2**bits-per-cell for single arithmetic and 4**bits-per-cell for
     double arithmetic (with appropriate mapping for signed types).
     Division by zero typically results in a `-10 throw' (divide by
     zero) or `-55 throw' (floating point unidentified fault).
     `convert' and `>number' currently overflow silently.

reading from an empty data or return stack:
     The data stack is checked by the outer (aka text) interpreter after
     every word executed. If it has underflowed, a `-4 throw' (Stack
     underflow) is performed. Apart from that, stacks may be checked or
     not, depending on operating system, installation, and invocation.
     If they are caught by a check, they typically result in `-4 throw'
     (Stack underflow), `-6 throw' (Return stack underflow) or `-9
     throw' (Invalid memory address), depending on the platform and
     which stack underflows and by how much. Note that even if the
     system uses checking (through the MMU), your program may have to
     underflow by a significant number of stack items to trigger the
     reaction (the reason for this is that the MMU, and therefore the
     checking, works with a page-size granularity).  If there is no
     checking, the symptoms resulting from an underflow are similar to
     those from an overflow.  Unbalanced return stack errors can result
     in a variety of symptoms, including `-9 throw' (Invalid memory
     address) and Illegal Instruction (typically `-260 throw').

unexpected end of the input buffer, resulting in an attempt to use a zero-length string as a name:
     `Create' and its descendants perform a `-16 throw' (Attempt to use
     zero-length string as a name). Words like `'' probably will not
     find what they search. Note that it is possible to create
     zero-length names with `nextname' (should it not?).

`>IN' greater than input buffer:
     The next invocation of a parsing word returns a string with length
     0.

`RECURSE' appears after `DOES>':
     Compiles a recursive call to the defining word, not to the defined
     word.

argument input source different than current input source for `RESTORE-INPUT':
     `-12 THROW'. Note that, once an input file is closed (e.g., because
     the end of the file was reached), its source-id may be reused.
     Therefore, restoring an input source specification referencing a
     closed file may lead to unpredictable results instead of a `-12
     THROW'.

     In the future, Gforth may be able to restore input source
     specifications from other than the current input source.

data space containing definitions gets de-allocated:
     Deallocation with `allot' is not checked. This typically results in
     memory access faults or execution of illegal instructions.

data space read/write with incorrect alignment:
     Processor-dependent. Typically results in a `-23 throw' (Address
     alignment exception). Under Linux-Intel on a 486 or later
     processor with alignment turned on, incorrect alignment results in
     a `-9 throw' (Invalid memory address). There are reportedly some
     processors with alignment restrictions that do not report
     violations.

data space pointer not properly aligned, `,', `C,':
     Like other alignment errors.

less than u+2 stack items (`PICK' and `ROLL'):
     Like other stack underflows.

loop control parameters not available:
     Not checked. The counted loop words simply assume that the top of
     return stack items are loop control parameters and behave
     accordingly.

most recent definition does not have a name (`IMMEDIATE'):
     `abort" last word was headerless"'.

name not defined by `VALUE' used by `TO':
     `-32 throw' (Invalid name argument) (unless name is a local or was
     defined by `CONSTANT'; in the latter case it just changes the
     constant).

name not found (`'', `POSTPONE', `[']', `[COMPILE]'):
     `-13 throw' (Undefined word)

parameters are not of the same type (`DO', `?DO', `WITHIN'):
     Gforth behaves as if they were of the same type. I.e., you can
     predict the behaviour by interpreting all parameters as, e.g.,
     signed.

`POSTPONE' or `[COMPILE]' applied to `TO':
     Assume `: X POSTPONE TO ; IMMEDIATE'. `X' performs the compilation
     semantics of `TO'.

String longer than a counted string returned by `WORD':
     Not checked. The string will be ok, but the count will, of course,
     contain only the least significant bits of the length.

u greater than or equal to the number of bits in a cell (`LSHIFT', `RSHIFT'):
     Processor-dependent. Typical behaviours are returning 0 and using
     only the low bits of the shift count.

word not defined via `CREATE':
     `>BODY' produces the PFA of the word no matter how it was defined.

     `DOES>' changes the execution semantics of the last defined word no
     matter how it was defined. E.g., `CONSTANT DOES>' is equivalent to
     `CREATE , DOES>'.

words improperly used outside `<#' and `#>':
     Not checked. As usual, you can expect memory faults.

Other system documentation
--------------------------

nonstandard words using `PAD':
     None.

operator's terminal facilities available:
     After processing the OS's command line, Gforth goes into
     interactive mode, and you can give commands to Gforth
     interactively. The actual facilities available depend on how you
     invoke Gforth.

program data space available:
     `UNUSED .' gives the remaining dictionary space. The total
     dictionary space can be specified with the `-m' switch (*note
     Invoking Gforth::) when Gforth starts up.

return stack space available:
     You can compute the total return stack space in cells with `s"
     RETURN-STACK-CELLS" environment? drop .'. You can specify it at
     startup time with the `-r' switch (*note Invoking Gforth::).

stack space available:
     You can compute the total data stack space in cells with `s"
     STACK-CELLS" environment? drop .'. You can specify it at startup
     time with the `-d' switch (*note Invoking Gforth::).

system dictionary space required, in address units:
     Type `here forthstart - .' after startup. At the time of this
     writing, this gives 80080 (bytes) on a 32-bit system.

The optional Block word set
===========================

Implementation Defined Options
------------------------------

the format for display by `LIST':
     First the screen number is displayed, then 16 lines of 64
     characters, each line preceded by the line number.

the length of a line affected by `\':
     64 characters.

Ambiguous conditions
--------------------

correct block read was not possible:
     Typically results in a `throw' of some OS-derived value (between
     -512 and -2048). If the blocks file was just not long enough,
     blanks are supplied for the missing portion.

I/O exception in block transfer:
     Typically results in a `throw' of some OS-derived value (between
     -512 and -2048).

invalid block number:
     `-35 throw' (Invalid block number)

a program directly alters the contents of `BLK':
     The input stream is switched to that other block, at the same
     position. If the storing to `BLK' happens when interpreting
     non-block input, the system will get quite confused when the block
     ends.

no current block buffer for `UPDATE':
     `UPDATE' has no effect.

Other system documentation
--------------------------

any restrictions a multiprogramming system places on the use of buffer addresses:
     No restrictions (yet).

the number of blocks available for source and data:
     depends on your disk space.

The optional Double Number word set
===================================

Ambiguous conditions
--------------------

d outside of range of n in `D>S':
     The least significant cell of d is produced.

The optional Exception word set
===============================

Implementation Defined Options
------------------------------

`THROW'-codes used in the system:
     The codes -256--511 are used for reporting signals. The mapping
     from OS signal numbers to throw codes is -256-signal. The codes
     -512--2047 are used for OS errors (for file and memory allocation
     operations). The mapping from OS error numbers to throw codes is
     -512-`errno'. One side effect of this mapping is that undefined OS
     errors produce a message with a strange number; e.g., `-1000
     THROW' results in `Unknown error 488' on my system.

The optional Facility word set
==============================

Implementation Defined Options
------------------------------

encoding of keyboard events (`EKEY'):
     Keys corresponding to ASCII characters are encoded as ASCII
     characters.  Other keys are encoded with the constants `k-left',
     `k-right', `k-up', `k-down', `k-home', `k-end', `k1', `k2', `k3',
     `k4', `k5', `k6', `k7', `k8', `k9', `k10', `k11', `k12'.

duration of a system clock tick:
     System dependent. With respect to `MS', the time is specified in
     microseconds. How well the OS and the hardware implement this, is
     another question.

repeatability to be expected from the execution of `MS':
     System dependent. On Unix, a lot depends on load. If the system is
     lightly loaded, and the delay is short enough that Gforth does not
     get swapped out, the performance should be acceptable. Under
     MS-DOS and other single-tasking systems, it should be good.

Ambiguous conditions
--------------------

`AT-XY' can't be performed on user output device:
     Largely terminal dependent. No range checks are done on the
     arguments.  No errors are reported. You may see some garbage
     appearing, you may see simply nothing happen.

The optional File-Access word set
=================================

Implementation Defined Options
------------------------------

file access methods used:
     `R/O', `R/W' and `BIN' work as you would expect. `W/O' translates
     into the C file opening mode `w' (or `wb'): The file is cleared,
     if it exists, and created, if it does not (with both `open-file'
     and `create-file').  Under Unix `create-file' creates a file with
     666 permissions modified by your umask.

file exceptions:
     The file words do not raise exceptions (except, perhaps, memory
     access faults when you pass illegal addresses or file-ids).

file line terminator:
     System-dependent. Gforth uses C's newline character as line
     terminator. What the actual character code(s) of this are is
     system-dependent.

file name format:
     System dependent. Gforth just uses the file name format of your OS.

information returned by `FILE-STATUS':
     `FILE-STATUS' returns the most powerful file access mode allowed
     for the file: Either `R/O', `W/O' or `R/W'. If the file cannot be
     accessed, `R/O BIN' is returned. `BIN' is applicable along with
     the returned mode.

input file state after an exception when including source:
     All files that are left via the exception are closed.

ior values and meaning:
     The iors returned by the file and memory allocation words are
     intended as throw codes. They typically are in the range
     -512--2047 of OS errors.  The mapping from OS error numbers to
     iors is -512-errno.

maximum depth of file input nesting:
     limited by the amount of return stack, locals/TIB stack, and the
     number of open files available. This should not give you troubles.

maximum size of input line:
     `/line'. Currently 255.

methods of mapping block ranges to files:
     By default, blocks are accessed in the file `blocks.fb' in the
     current working directory. The file can be switched with `USE'.

number of string buffers provided by `S"':
     1

size of string buffer used by `S"':
     `/line'. currently 255.

Ambiguous conditions
--------------------

attempting to position a file outside its boundaries:
     `REPOSITION-FILE' is performed as usual: Afterwards,
     `FILE-POSITION' returns the value given to `REPOSITION-FILE'.

attempting to read from file positions not yet written:
     End-of-file, i.e., zero characters are read and no error is
     reported.

file-id is invalid (`INCLUDE-FILE'):
     An appropriate exception may be thrown, but a memory fault or other
     problem is more probable.

I/O exception reading or closing file-id (`INCLUDE-FILE', `INCLUDED'):
     The ior produced by the operation, that discovered the problem, is
     thrown.

named file cannot be opened (`INCLUDED'):
     The ior produced by `open-file' is thrown.

requesting an unmapped block number:
     There are no unmapped legal block numbers. On some operating
     systems, writing a block with a large number may overflow the file
     system and have an error message as consequence.

using `source-id' when `blk' is non-zero:
     `source-id' performs its function. Typically it will give the id of
     the source which loaded the block. (Better ideas?)

The optional Floating-Point word set
====================================

Implementation Defined Options
------------------------------

format and range of floating point numbers:
     System-dependent; the `double' type of C.

results of `REPRESENT' when float is out of range:
     System dependent; `REPRESENT' is implemented using the C library
     function `ecvt()' and inherits its behaviour in this respect.

rounding or truncation of floating-point numbers:
     System dependent; the rounding behaviour is inherited from the
     hosting C compiler. IEEE-FP-based (i.e., most) systems by default
     round to nearest, and break ties by rounding to even (i.e., such
     that the last bit of the mantissa is 0).

size of floating-point stack:
     `s" FLOATING-STACK" environment? drop .' gives the total size of
     the floating-point stack (in floats). You can specify this on
     startup with the command-line option `-f' (*note Invoking
     Gforth::).

width of floating-point stack:
     `1 floats'.

Ambiguous conditions
--------------------

`df@' or `df!' used with an address that is not double-float  aligned:
     System-dependent. Typically results in a `-23 THROW' like other
     alignment violations.

`f@' or `f!' used with an address that is not float  aligned:
     System-dependent. Typically results in a `-23 THROW' like other
     alignment violations.

floating-point result out of range:
     System-dependent. Can result in a `-43 throw' (floating point
     overflow), `-54 throw' (floating point underflow), `-41 throw'
     (floating point inexact result), `-55 THROW' (Floating-point
     unidentified fault), or can produce a special value representing,
     e.g., Infinity.

`sf@' or `sf!' used with an address that is not single-float  aligned:
     System-dependent. Typically results in an alignment fault like
     other alignment violations.

`base' is not decimal (`REPRESENT', `F.', `FE.', `FS.'):
     The floating-point number is converted into decimal nonetheless.

Both arguments are equal to zero (`FATAN2'):
     System-dependent. `FATAN2' is implemented using the C library
     function `atan2()'.

Using `FTAN' on an argument r1 where cos(r1) is zero:
     System-dependent. Anyway, typically the cos of r1 will not be zero
     because of small errors and the tan will be a very large (or very
     small) but finite number.

d cannot be presented precisely as a float in `D>F':
     The result is rounded to the nearest float.

dividing by zero:
     Platform-dependent; can produce an Infinity, NaN, `-42 throw'
     (floating point divide by zero) or `-55 throw' (Floating-point
     unidentified fault).

exponent too big for conversion (`DF!', `DF@', `SF!', `SF@'):
     System dependent. On IEEE-FP based systems the number is converted
     into an infinity.

float<1 (`FACOSH'):
     Platform-dependent; on IEEE-FP systems typically produces a NaN.

float=<-1 (`FLNP1'):
     Platform-dependent; on IEEE-FP systems typically produces a NaN
     (or a negative infinity for float=-1).

float=<0 (`FLN', `FLOG'):
     Platform-dependent; on IEEE-FP systems typically produces a NaN
     (or a negative infinity for float=0).

float<0 (`FASINH', `FSQRT'):
     Platform-dependent; for `fsqrt' this typically gives a NaN, for
     `fasinh' some platforms produce a NaN, others a number (bug in the
     C library?).

|float|>1 (`FACOS', `FASIN', `FATANH'):
     Platform-dependent; IEEE-FP systems typically produce a NaN.

integer part of float cannot be represented by d in `F>D':
     Platform-dependent; typically, some double number is produced and
     no error is reported.

string larger than pictured numeric output area (`f.', `fe.', `fs.'):
     `Precision' characters of the numeric output area are used.  If
     `precision' is too high, these words will smash the data or code
     close to `here'.

The optional Locals word set
============================

Implementation Defined Options
------------------------------

maximum number of locals in a definition:
     `s" #locals" environment? drop .'. Currently 15. This is a lower
     bound, e.g., on a 32-bit machine there can be 41 locals of up to 8
     characters. The number of locals in a definition is bounded by the
     size of locals-buffer, which contains the names of the locals.

Ambiguous conditions
--------------------

executing a named local in interpretation state:
     Locals have no interpretation semantics. If you try to perform the
     interpretation semantics, you will get a `-14 throw' somewhere
     (Interpreting a compile-only word). If you perform the compilation
     semantics, the locals access will be compiled (irrespective of
     state).

name not defined by `VALUE' or `(LOCAL)' (`TO'):
     `-32 throw' (Invalid name argument)

The optional Memory-Allocation word set
=======================================

Implementation Defined Options
------------------------------

values and meaning of ior:
     The iors returned by the file and memory allocation words are
     intended as throw codes. They typically are in the range
     -512--2047 of OS errors.  The mapping from OS error numbers to
     iors is -512-errno.

The optional Programming-Tools word set
=======================================

Implementation Defined Options
------------------------------

ending sequence for input following `;CODE' and `CODE':
     `END-CODE'

manner of processing input following `;CODE' and `CODE':
     The `ASSEMBLER' vocabulary is pushed on the search order stack, and
     the input is processed by the text interpreter, (starting) in
     interpret state.

search order capability for `EDITOR' and `ASSEMBLER':
     The ANS Forth search order word set.

source and format of display by `SEE':
     The source for `see' is the executable code used by the inner
     interpreter.  The current `see' tries to output Forth source code
     (and on some platforms, assembly code for primitives) as well as
     possible.

Ambiguous conditions
--------------------

deleting the compilation word list (`FORGET'):
     Not implemented (yet).

fewer than u+1 items on the control-flow stack (`CS-PICK', `CS-ROLL'):
     This typically results in an `abort"' with a descriptive error
     message (may change into a `-22 throw' (Control structure mismatch)
     in the future). You may also get a memory access error. If you are
     unlucky, this ambiguous condition is not caught.

name can't be found (`FORGET'):
     Not implemented (yet).

name not defined via `CREATE':
     `;CODE' behaves like `DOES>' in this respect, i.e., it changes the
     execution semantics of the last defined word no matter how it was
     defined.

`POSTPONE' applied to `[IF]':
     After defining `: X POSTPONE [IF] ; IMMEDIATE'. `X' is equivalent
     to `[IF]'.

reaching the end of the input source before matching `[ELSE]' or `[THEN]':
     Continue in the same state of conditional compilation in the next
     outer input source. Currently there is no warning to the user
     about this.

removing a needed definition (`FORGET'):
     Not implemented (yet).

The optional Search-Order word set
==================================

Implementation Defined Options
------------------------------

maximum number of word lists in search order:
     `s" wordlists" environment? drop .'. Currently 16.

minimum search order:
     `root root'.

Ambiguous conditions
--------------------

changing the compilation word list (during compilation):
     The word is entered into the word list that was the compilation
     word list at the start of the definition. Any changes to the name
     field (e.g., `immediate') or the code field (e.g., when executing
     `DOES>') are applied to the latest defined word (as reported by
     `last' or `lastxt'), if possible, irrespective of the compilation
     word list.

search order empty (`previous'):
     `abort" Vocstack empty"'.

too many word lists in search order (`also'):
     `abort" Vocstack full"'.

Should I use Gforth extensions?
*******************************

   As you read through the rest of this manual, you will see
documentation for Standard words, and documentation for some appealing
Gforth extensions. You might ask yourself the question: "Should I
restrict myself to the standard, or should I use the extensions?"

   The answer depends on the goals you have for the program you are
working on:

   * Is it just for yourself or do you want to share it with others?

   * If you want to share it, do the others all use Gforth?

   * If it is just for yourself, do you want to restrict yourself to
     Gforth?


   If restricting the program to Gforth is ok, then there is no reason
not to use extensions.  It is still a good idea to keep to the standard
where it is easy, in case you want to reuse these parts in another
program that you want to be portable.

   If you want to be able to port the program to other Forth systems,
there are the following points to consider:

   * Most Forth systems that are being maintained support the ANS Forth
     standard.  So if your program complies with the standard, it will
     be portable among many systems.

   * A number of the Gforth extensions can be implemented in ANS Forth
     using public-domain files provided in the `compat/' directory.
     These are mentioned in the text in passing.  There is no reason
     not to use these extensions, your program will still be ANS Forth
     compliant; just include the appropriate compat files with your
     program.

   * The tool `ans-report.fs' (*note ANS Report::) makes it easy to
     analyse your program and determine what non-Standard words it
     relies upon.  However, it does not check whether you use standard
     words in a non-standard way.

   * Some techniques are not standardized by ANS Forth, and are hard or
     impossible to implement in a standard way, but can be implemented
     in most Forth systems easily, and usually in similar ways (e.g.,
     accessing word headers).  Forth has a rich historical precedent
     for programmers taking advantage of implementation-dependent
     features of their tools (for example, relying on a knowledge of
     the dictionary structure). Sometimes these techniques are
     necessary to extract every last bit of performance from the
     hardware, sometimes they are just a programming shorthand.

   * Does using a Gforth extension save more work than the porting this
     part to other Forth systems (if any) will cost?

   * Is the additional functionality worth the reduction in portability
     and the additional porting problems?


   In order to perform these consideratios, you need to know what's
standard and what's not.  This manual generally states if something is
non-standard, but the authoritative source is the standard document
(http://www.taygeta.com/forth/dpans.html).  Appendix A of the Standard
(RATIONALE) provides a valuable insight into the thought processes of
the technical committee.

   Note also that portability between Forth systems is not the only
portability issue; there is also the issue of portability between
different platforms (processor/OS combinations).

Model
*****

   This chapter has yet to be written. It will contain information, on
which internal structures you can rely.

Integrating Gforth into C programs
**********************************

   This is not yet implemented.

   Several people like to use Forth as scripting language for
applications that are otherwise written in C, C++, or some other
language.

   The Forth system ATLAST provides facilities for embedding it into
applications; unfortunately it has several disadvantages: most
importantly, it is not based on ANS Forth, and it is apparently dead
(i.e., not developed further and not supported). The facilities
provided by Gforth in this area are inspired by ATLAST's facilities, so
making the switch should not be hard.

   We also tried to design the interface such that it can easily be
implemented by other Forth systems, so that we may one day arrive at a
standardized interface. Such a standard interface would allow you to
replace the Forth system without having to rewrite C code.

   You embed the Gforth interpreter by linking with the library
`libgforth.a' (give the compiler the option `-lgforth').  All global
symbols in this library that belong to the interface, have the prefix
`forth_'. (Global symbols that are used internally have the prefix
`gforth_').

   You can include the declarations of Forth types and the functions and
variables of the interface with `#include <forth.h>'.

   Types.

   Variables.

   Data and FP Stack pointer. Area sizes.

   functions.

   forth_init(imagefile) forth_evaluate(string) exceptions?
forth_goto(address) (or forth_execute(xt)?)  forth_continue() (a
corountining mechanism)

   Adding primitives.

   No checking.

   Signals?

   Accessing the Stacks

Emacs and Gforth
****************

   Gforth comes with `gforth.el', an improved version of `forth.el' by
Goran Rydqvist (included in the TILE package). The improvements are:

   * A better (but still not perfect) handling of indentation.

   * Comment paragraph filling (`M-q')

   * Commenting (`C-x \') and uncommenting (`C-u C-x \') of regions

   * Removal of debugging tracers (`C-x ~', *note Debugging::).

   * Support of the `info-lookup' feature for looking up the
     documentation of a word.

   I left the stuff I do not use alone, even though some of it only
makes sense for TILE. To get a description of these features, enter
Forth mode and type `C-h m'.

   In addition, Gforth supports Emacs quite well: The source code
locations given in error messages, debugging output (from `~~') and
failed assertion messages are in the right format for Emacs'
compilation mode (*note Running Compilations under Emacs:
(emacs)Compilation.) so the source location corresponding to an error
or other message is only a few keystrokes away (`C-x `' for the next
error, `C-c C-c' for the error under the cursor).

   Also, if you `require' `etags.fs', a new `TAGS' file will be
produced (*note Tags Tables: (emacs)Tags.) that contains the
definitions of all words defined afterwards. You can then find the
source for a word using `M-.'. Note that emacs can use several tags
files at the same time (e.g., one for the Gforth sources and one for
your program, *note Selecting a Tags Table: (emacs)Select Tags Table.).
The TAGS file for the preloaded words is
`$(datadir)/gforth/$(VERSION)/TAGS' (e.g.,
`/usr/local/share/gforth/0.2.0/TAGS').  To get the best behaviour with
`etags.fs', you should avoid putting definitions both before and after
`require' etc., otherwise you will see the same file visited several
times by commands like `tags-search'.

   Moreover, for words documented in this manual, you can look up the
glossary entry quickly by using `C-h TAB' (`info-lookup-symbol', *note
Documentation Commands: (emacs)Documentation.).  This feature requires
Emacs 20.3 or later and does not work for words containing `:'.

   To get all these benefits, add the following lines to your `.emacs'
file:

     (autoload 'forth-mode "gforth.el")
     (setq auto-mode-alist (cons '("\\.fs\\'" . forth-mode) auto-mode-alist))

Image Files
***********

   An image file is a file containing an image of the Forth dictionary,
i.e., compiled Forth code and data residing in the dictionary.  By
convention, we use the extension `.fi' for image files.

Image Licensing Issues
======================

   An image created with `gforthmi' (*note gforthmi::) or `savesystem'
(*note Non-Relocatable Image Files::) includes the original image;
i.e., according to copyright law it is a derived work of the original
image.

   Since Gforth is distributed under the GNU GPL, the newly created
image falls under the GNU GPL, too. In particular, this means that if
you distribute the image, you have to make all of the sources for the
image available, including those you wrote.  For details see *Note GNU
General Public License (Section 3): License.

   If you create an image with `cross' (*note cross.fs::), the image
contains only code compiled from the sources you gave it; if none of
these sources is under the GPL, the terms discussed above do not apply
to the image. However, if your image needs an engine (a gforth binary)
that is under the GPL, you should make sure that you distribute both in
a way that is at most a _mere aggregation_, if you don't want the terms
of the GPL to apply to the image.

Image File Background
=====================

   Gforth consists not only of primitives (in the engine), but also of
definitions written in Forth. Since the Forth compiler itself belongs to
those definitions, it is not possible to start the system with the
engine and the Forth source alone. Therefore we provide the Forth code
as an image file in nearly executable form. When Gforth starts up, a C
routine loads the image file into memory, optionally relocates the
addresses, then sets up the memory (stacks etc.) according to
information in the image file, and (finally) starts executing Forth
code.

   The image file variants represent different compromises between the
goals of making it easy to generate image files and making them
portable.

   Win32Forth 3.4 and Mitch Bradley's `cforth' use relocation at
run-time. This avoids many of the complications discussed below (image
files are data relocatable without further ado), but costs performance
(one addition per memory access).

   By contrast, the Gforth loader performs relocation at image load
time. The loader also has to replace tokens that represent primitive
calls with the appropriate code-field addresses (or code addresses in
the case of direct threading).

   There are three kinds of image files, with different degrees of
relocatability: non-relocatable, data-relocatable, and fully relocatable
image files.

   These image file variants have several restrictions in common; they
are caused by the design of the image file loader:

   * There is only one segment; in particular, this means, that an
     image file cannot represent `ALLOCATE'd memory chunks (and
     pointers to them). The contents of the stacks are not represented,
     either.

   * The only kinds of relocation supported are: adding the same offset
     to all cells that represent data addresses; and replacing special
     tokens with code addresses or with pieces of machine code.

     If any complex computations involving addresses are performed, the
     results cannot be represented in the image file. Several
     applications that use such computations come to mind:
        - Hashing addresses (or data structures which contain
          addresses) for table lookup. If you use Gforth's `table's or
          `wordlist's for this purpose, you will have no problem,
          because the hash tables are recomputed automatically when the
          system is started. If you use your own hash tables, you will
          have to do something similar.

        - There's a cute implementation of doubly-linked lists that uses
          `XOR'ed addresses. You could represent such lists as
          singly-linked in the image file, and restore the
          doubly-linked representation on startup.(1)

        - The code addresses of run-time routines like `docol:' cannot
          be represented in the image file (because their tokens would
          be replaced by machine code in direct threaded
          implementations). As a workaround, compute these addresses at
          run-time with `>code-address' from the executions tokens of
          appropriate words (see the definitions of `docol:' and
          friends in `kernel/getdoers.fs').

        - On many architectures addresses are represented in machine
          code in some shifted or mangled form. You cannot put `CODE'
          words that contain absolute addresses in this form in a
          relocatable image file. Workarounds are representing the
          address in some relative form (e.g., relative to the CFA,
          which is present in some register), or loading the address
          from a place where it is stored in a non-mangled form.

   ---------- Footnotes ----------

   (1) In my opinion, though, you should think thrice before using a
doubly-linked list (whatever implementation).

Non-Relocatable Image Files
===========================

   These files are simple memory dumps of the dictionary. They are
specific to the executable (i.e., `gforth' file) they were created
with. What's worse, they are specific to the place on which the
dictionary resided when the image was created. Now, there is no
guarantee that the dictionary will reside at the same place the next
time you start Gforth, so there's no guarantee that a non-relocatable
image will work the next time (Gforth will complain instead of crashing,
though).

   You can create a non-relocatable image file with

`savesystem'       "name" -         gforth       ``savesystem''

Data-Relocatable Image Files
============================

   These files contain relocatable data addresses, but fixed code
addresses (instead of tokens). They are specific to the executable
(i.e., `gforth' file) they were created with. For direct threading on
some architectures (e.g., the i386), data-relocatable images do not
work. You get a data-relocatable image, if you use `gforthmi' with a
Gforth binary that is not doubly indirect threaded (*note Fully
Relocatable Image Files::).

Fully Relocatable Image Files
=============================

   These image files have relocatable data addresses, and tokens for
code addresses. They can be used with different binaries (e.g., with and
without debugging) on the same machine, and even across machines with
the same data formats (byte order, cell size, floating point format).
However, they are usually specific to the version of Gforth they were
created with. The files `gforth.fi' and `kernl*.fi' are fully
relocatable.

   There are two ways to create a fully relocatable image file:

`gforthmi'
----------

   You will usually use `gforthmi'. If you want to create an image file
that contains everything you would load by invoking Gforth with `gforth
options', you simply say:
     gforthmi file options

   E.g., if you want to create an image `asm.fi' that has the file
`asm.fs' loaded in addition to the usual stuff, you could do it like
this:

     gforthmi asm.fi asm.fs

   `gforthmi' is implemented as a sh script and works like this: It
produces two non-relocatable images for different addresses and then
compares them. Its output reflects this: first you see the output (if
any) of the two Gforth invocations that produce the non-relocatable
image files, then you see the output of the comparing program: It
displays the offset used for data addresses and the offset used for
code addresses; moreover, for each cell that cannot be represented
correctly in the image files, it displays a line like this:

          78DC         BFFFFA50         BFFFFA40

   This means that at offset $78dc from `forthstart', one input image
contains $bffffa50, and the other contains $bffffa40. Since these cells
cannot be represented correctly in the output image, you should examine
these places in the dictionary and verify that these cells are dead
(i.e., not read before they are written).

   If you insert the option `--application' in front of the image file
name, you will get an image that uses the `--appl-image' option instead
of the `--image-file' option (*note Invoking Gforth::). When you
execute such an image on Unix (by typing the image name as command),
the Gforth engine will pass all options to the image instead of trying
to interpret them as engine options.

   If you type `gforthmi' with no arguments, it prints some usage
instructions.

   There are a few wrinkles: After processing the passed options, the
words `savesystem' and `bye' must be visible. A special doubly indirect
threaded version of the `gforth' executable is used for creating the
non-relocatable images; you can pass the exact filename of this
executable through the environment variable `GFORTHD' (default:
`gforth-ditc'); if you pass a version that is not doubly indirect
threaded, you will not get a fully relocatable image, but a
data-relocatable image (because there is no code address offset). The
normal `gforth' executable is used for creating the relocatable image;
you can pass the exact filename of this executable through the
environment variable `GFORTH'.

`cross.fs'
----------

   You can also use `cross', a batch compiler that accepts a Forth-like
programming language (*note Cross Compiler::).

   `cross' allows you to create image files for machines with different
data sizes and data formats than the one used for generating the image
file. You can also use it to create an application image that does not
contain a Forth compiler. These features are bought with restrictions
and inconveniences in programming. E.g., addresses have to be stored in
memory with special words (`A!', `A,', etc.) in order to make the code
relocatable.

Stack and Dictionary Sizes
==========================

   If you invoke Gforth with a command line flag for the size (*note
Invoking Gforth::), the size you specify is stored in the dictionary.
If you save the dictionary with `savesystem' or create an image with
`gforthmi', this size will become the default for the resulting image
file. E.g., the following will create a fully relocatable version of
`gforth.fi' with a 1MB dictionary:

     gforthmi gforth.fi -m 1M

   In other words, if you want to set the default size for the
dictionary and the stacks of an image, just invoke `gforthmi' with the
appropriate options when creating the image.

   Note: For cache-friendly behaviour (i.e., good performance), you
should make the sizes of the stacks modulo, say, 2K, somewhat
different. E.g., the default stack sizes are: data: 16k (mod 2k=0); fp:
15.5k (mod 2k=1.5k); return: 15k(mod 2k=1k); locals: 14.5k (mod
2k=0.5k).

Running Image Files
===================

   You can invoke Gforth with an image file image instead of the
default `gforth.fi' with the `-i' flag (*note Invoking Gforth::):
     gforth -i image

   If your operating system supports starting scripts with a line of the
form `#! ...', you just have to type the image file name to start
Gforth with this image file (note that the file extension `.fi' is just
a convention). I.e., to run Gforth with the image file image, you can
just type image instead of `gforth -i image'.  This works because every
`.fi' file starts with a line of this format:

     #! /usr/local/bin/gforth-0.4.0 -i

   The file and pathname for the Gforth engine specified on this line is
the specific Gforth executable that it was built against; i.e. the value
of the environment variable `GFORTH' at the time that `gforthmi' was
executed.

   You can make use of the same shell capability to make a Forth source
file into an executable. For example, if you place this text in a file:

     #! /usr/local/bin/gforth
     
     ." Hello, world" CR
     bye

and then make the file executable (chmod +x in Unix), you can run it
directly from the command line. The sequence `#!' is used in two ways;
firstly, it is recognised as a "magic sequence" by the operating
system(1) secondly it is treated as a comment character by Gforth.
Because of the second usage, a space is required between `#!' and the
path to the executable (moreover, some Unixes require the sequence `#!
/').

   The disadvantage of this latter technique, compared with using
`gforthmi', is that it is slightly slower; the Forth source code is
compiled on-the-fly, each time the program is invoked.

`#!'       -         gforth       ``hash-bang''
   An alias for `\'

   ---------- Footnotes ----------

   (1) The Unix kernel actually recognises two types of files:
executable files and files of data, where the data is processed by an
interpreter that is specified on the "interpreter line" - the first
line of the file, starting with the sequence #!. There may be a small
limit (e.g., 32) on the number of characters that may be specified on
the interpreter line.

Modifying the Startup Sequence
==============================

   You can add your own initialization to the startup sequence through
the deferred word `'cold'. `'cold' is invoked just before the
image-specific command line processing (i.e., loading files and
evaluating (`-e') strings) starts.

   A sequence for adding your initialization usually looks like this:

     :noname
         Defers 'cold \ do other initialization stuff (e.g., rehashing wordlists)
         ... \ your stuff
     ; IS 'cold

   You can make a turnkey image by letting `'cold' execute a word (your
turnkey application) that never returns; instead, it exits Gforth via
`bye' or `throw'.

   You can access the (image-specific) command-line arguments through
the variables `argc' and `argv'. `arg' provides convenient access to
`argv'.

   If `'cold' exits normally, Gforth processes the command-line
arguments as files to be loaded and strings to be evaluated.  Therefore,
`'cold' should remove the arguments it has used in this case.

`'cold'       -         gforth       ``tick-cold''

`argc'       - addr         gforth       ``argc''
   `Variable' - the number of command-line arguments (including the
command name).

`argv'       - addr         gforth       ``argv''
   `Variable' - a pointer to a vector of pointers to the command-line
arguments (including the command-name). Each argument is represented as
a C-style string.

`arg'       n - addr count         gforth       ``arg''
   Return the string for the nth command-line argument.

Engine
******

   Reading this chapter is not necessary for programming with Gforth. It
may be helpful for finding your way in the Gforth sources.

   The ideas in this section have also been published in Bernd Paysan,
`ANS fig/GNU/??? Forth' (in German), Forth-Tagung '93 and M. Anton
Ertl, `A Portable Forth Engine
(http://www.complang.tuwien.ac.at/papers/ertl93.ps.Z)', EuroForth '93.

Portability
===========

   An important goal of the Gforth Project is availability across a wide
range of personal machines. fig-Forth, and, to a lesser extent, F83,
achieved this goal by manually coding the engine in assembly language
for several then-popular processors. This approach is very
labor-intensive and the results are short-lived due to progress in
computer architecture.

   Others have avoided this problem by coding in C, e.g., Mitch Bradley
(cforth), Mikael Patel (TILE) and Dirk Zoller (pfe). This approach is
particularly popular for UNIX-based Forths due to the large variety of
architectures of UNIX machines. Unfortunately an implementation in C
does not mix well with the goals of efficiency and with using
traditional techniques: Indirect or direct threading cannot be expressed
in C, and switch threading, the fastest technique available in C, is
significantly slower. Another problem with C is that it is very
cumbersome to express double integer arithmetic.

   Fortunately, there is a portable language that does not have these
limitations: GNU C, the version of C processed by the GNU C compiler
(*note Extensions to the C Language Family: (gcc.info)C Extensions.).
Its labels as values feature (*note Labels as Values: (gcc.info)Labels
as Values.) makes direct and indirect threading possible, its `long
long' type (*note Double-Word Integers: (gcc.info)Long Long.)
corresponds to Forth's double numbers(1). GNU C is available for free
on all important (and many unimportant) UNIX machines, VMS, 80386s
running MS-DOS, the Amiga, and the Atari ST, so a Forth written in GNU
C can run on all these machines.

   Writing in a portable language has the reputation of producing code
that is slower than assembly. For our Forth engine we repeatedly looked
at the code produced by the compiler and eliminated most
compiler-induced inefficiencies by appropriate changes in the source
code.

   However, register allocation cannot be portably influenced by the
programmer, leading to some inefficiencies on register-starved
machines. We use explicit register declarations (*note Variables in
Specified Registers: (gcc.info)Explicit Reg Vars.) to improve the speed
on some machines. They are turned on by using the configuration flag
`--enable-force-reg' (`gcc' switch `-DFORCE_REG'). Unfortunately, this
feature not only depends on the machine, but also on the compiler
version: On some machines some compiler versions produce incorrect code
when certain explicit register declarations are used. So by default
`-DFORCE_REG' is not used.

   ---------- Footnotes ----------

   (1) Unfortunately, long longs are not implemented properly on all
machines (e.g., on alpha-osf1, long longs are only 64 bits, the same
size as longs (and pointers), but they should be twice as long
according to *note Double-Word Integers: (gcc.info)Long Long.). So, we
had to implement doubles in C after all. Still, on most machines we can
use long longs and achieve better performance than with the emulation
package.

Threading
=========

   GNU C's labels as values extension (available since `gcc-2.0', *note
Labels as Values: (gcc.info)Labels as Values.)  makes it possible to
take the address of label by writing `&&label'.  This address can then
be used in a statement like `goto *address'. I.e., `goto *&&x' is the
same as `goto x'.

   With this feature an indirect threaded `NEXT' looks like:
     cfa = *ip++;
     ca = *cfa;
     goto *ca;
   For those unfamiliar with the names: `ip' is the Forth instruction
pointer; the `cfa' (code-field address) corresponds to ANS Forths
execution token and points to the code field of the next word to be
executed; The `ca' (code address) fetched from there points to some
executable code, e.g., a primitive or the colon definition handler
`docol'.

   Direct threading is even simpler:
     ca = *ip++;
     goto *ca;

   Of course we have packaged the whole thing neatly in macros called
`NEXT' and `NEXT1' (the part of `NEXT' after fetching the cfa).

Scheduling
----------

   There is a little complication: Pipelined and superscalar processors,
i.e., RISC and some modern CISC machines can process independent
instructions while waiting for the results of an instruction. The
compiler usually reorders (schedules) the instructions in a way that
achieves good usage of these delay slots. However, on our first tries
the compiler did not do well on scheduling primitives. E.g., for `+'
implemented as
     n=sp[0]+sp[1];
     sp++;
     sp[0]=n;
     NEXT;
   the `NEXT' comes strictly after the other code, i.e., there is
nearly no scheduling. After a little thought the problem becomes clear:
The compiler cannot know that `sp' and `ip' point to different
addresses (and the version of `gcc' we used would not know it even if
it was possible), so it could not move the load of the cfa above the
store to the TOS. Indeed the pointers could be the same, if code on or
very near the top of stack were executed. In the interest of speed we
chose to forbid this probably unused "feature" and helped the compiler
in scheduling: `NEXT' is divided into several parts: `NEXT_P0',
`NEXT_P1' and `NEXT_P2'). `+' now looks like:
     NEXT_P0;
     n=sp[0]+sp[1];
     sp++;
     NEXT_P1;
     sp[0]=n;
     NEXT_P2;

   There are various schemes that distribute the different operations of
NEXT between these parts in several ways; in general, different schemes
perform best on different processors.  We use a scheme for most
architectures that performs well for most processors of this
architecture; in the furture we may switch to benchmarking and chosing
the scheme on installation time.

Direct or Indirect Threaded?
----------------------------

   Both! After packaging the nasty details in macro definitions we
realized that we could switch between direct and indirect threading by
simply setting a compilation flag (`-DDIRECT_THREADED') and defining a
few machine-specific macros for the direct-threading case.  On the
Forth level we also offer access words that hide the differences
between the threading methods (*note Threading Words::).

   Indirect threading is implemented completely machine-independently.
Direct threading needs routines for creating jumps to the executable
code (e.g. to `docol' or `dodoes'). These routines are inherently
machine-dependent, but they do not amount to many source lines.
Therefore, even porting direct threading to a new machine requires
little effort.

   The default threading method is machine-dependent. You can enforce a
specific threading method when building Gforth with the configuration
flag `--enable-direct-threaded' or `--enable-indirect-threaded'. Note
that direct threading is not supported on all machines.

DOES>
-----

   One of the most complex parts of a Forth engine is `dodoes', i.e.,
the chunk of code executed by every word defined by a
`CREATE'...`DOES>' pair. The main problem here is: How to find the
Forth code to be executed, i.e. the code after the `DOES>' (the
`DOES>'-code)? There are two solutions:

   In fig-Forth the code field points directly to the `dodoes' and the
`DOES>'-code address is stored in the cell after the code address (i.e.
at `CFA cell+'). It may seem that this solution is illegal in the
Forth-79 and all later standards, because in fig-Forth this address
lies in the body (which is illegal in these standards). However, by
making the code field larger for all words this solution becomes legal
again. We use this approach for the indirect threaded version and for
direct threading on some machines. Leaving a cell unused in most words
is a bit wasteful, but on the machines we are targeting this is hardly a
problem. The other reason for having a code field size of two cells is
to avoid having different image files for direct and indirect threaded
systems (direct threaded systems require two-cell code fields on many
machines).

   The other approach is that the code field points or jumps to the cell
after `DOES>'. In this variant there is a jump to `dodoes' at this
address (the `DOES>'-handler). `dodoes' can then get the `DOES>'-code
address by computing the code address, i.e., the address of the jump to
`dodoes', and add the length of that jump field. A variant of this is
to have a call to `dodoes' after the `DOES>'; then the return address
(which can be found in the return register on RISCs) is the
`DOES>'-code address. Since the two cells available in the code field
are used up by the jump to the code address in direct threading on many
architectures, we use this approach for direct threading on these
architectures. We did not want to add another cell to the code field.

Primitives
==========

Automatic Generation
--------------------

   Since the primitives are implemented in a portable language, there
is no longer any need to minimize the number of primitives. On the
contrary, having many primitives has an advantage: speed. In order to
reduce the number of errors in primitives and to make programming them
easier, we provide a tool, the primitive generator (`prims2x.fs'), that
automatically generates most (and sometimes all) of the C code for a
primitive from the stack effect notation.  The source for a primitive
has the following form:

Forth-name  ( stack-effect )        category    [pronounc.]
[`""'glossary entry`""']
C code
[`:'
Forth code]

   The items in brackets are optional. The category and glossary fields
are there for generating the documentation, the Forth code is there for
manual implementations on machines without GNU C. E.g., the source for
the primitive `+' is:
     +    ( n1 n2 -- n )   core    plus
     n = n1+n2;

   This looks like a specification, but in fact `n = n1+n2' is C code.
Our primitive generation tool extracts a lot of information from the
stack effect notations(1): The number of items popped from and pushed
on the stack, their type, and by what name they are referred to in the
C code. It then generates a C code prelude and postlude for each
primitive. The final C code for `+' looks like this:

     I_plus: /* + ( n1 n2 -- n ) */  /* label, stack effect */
     /*  */                          /* documentation */
     NAME("+")                       /* debugging output (with -DDEBUG) */
     {
     DEF_CA                          /* definition of variable ca (indirect threading) */
     Cell n1;                        /* definitions of variables */
     Cell n2;
     Cell n;
     NEXT_P0;                        /* NEXT part 0 */
     n1 = (Cell) sp[1];              /* input */
     n2 = (Cell) TOS;
     sp += 1;                        /* stack adjustment */
     {
     n = n1+n2;                      /* C code taken from the source */
     }
     NEXT_P1;                        /* NEXT part 1 */
     TOS = (Cell)n;                  /* output */
     NEXT_P2;                        /* NEXT part 2 */
     }

   This looks long and inefficient, but the GNU C compiler optimizes
quite well and produces optimal code for `+' on, e.g., the R3000 and the
HP RISC machines: Defining the `n's does not produce any code, and
using them as intermediate storage also adds no cost.

   There are also other optimizations that are not illustrated by this
example: assignments between simple variables are usually for free (copy
propagation). If one of the stack items is not used by the primitive
(e.g.  in `drop'), the compiler eliminates the load from the stack
(dead code elimination). On the other hand, there are some things that
the compiler does not do, therefore they are performed by `prims2x.fs':
The compiler does not optimize code away that stores a stack item to
the place where it just came from (e.g., `over').

   While programming a primitive is usually easy, there are a few cases
where the programmer has to take the actions of the generator into
account, most notably `?dup', but also words that do not (always) fall
through to `NEXT'.

   ---------- Footnotes ----------

   (1) We use a one-stack notation, even though we have separate data
and floating-point stacks; The separate notation can be generated
easily from the unified notation.

TOS Optimization
----------------

   An important optimization for stack machine emulators, e.g., Forth
engines, is keeping  one or more of the top stack items in registers.
If a word has the stack effect in1...inx `--' out1...outy, keeping the
top n items in registers
   * is better than keeping n-1 items, if x>=n and y>=n, due to fewer
     loads from and stores to the stack.

   * is slower than keeping n-1 items, if x<>y and x<n and y<n, due to
     additional moves between registers.

   In particular, keeping one item in a register is never a
disadvantage, if there are enough registers. Keeping two items in
registers is a disadvantage for frequent words like `?branch',
constants, variables, literals and `i'. Therefore our generator only
produces code that keeps zero or one items in registers. The generated
C code covers both cases; the selection between these alternatives is
made at C-compile time using the switch `-DUSE_TOS'. `TOS' in the C
code for `+' is just a simple variable name in the one-item case,
otherwise it is a macro that expands into `sp[0]'. Note that the GNU C
compiler tries to keep simple variables like `TOS' in registers, and it
usually succeeds, if there are enough registers.

   The primitive generator performs the TOS optimization for the
floating-point stack, too (`-DUSE_FTOS'). For floating-point operations
the benefit of this optimization is even larger: floating-point
operations take quite long on most processors, but can be performed in
parallel with other operations as long as their results are not used.
If the FP-TOS is kept in a register, this works. If it is kept on the
stack, i.e., in memory, the store into memory has to wait for the
result of the floating-point operation, lengthening the execution time
of the primitive considerably.

   The TOS optimization makes the automatic generation of primitives a
bit more complicated. Just replacing all occurrences of `sp[0]' by
`TOS' is not sufficient. There are some special cases to consider:
   * In the case of `dup ( w -- w w )' the generator must not eliminate
     the store to the original location of the item on the stack, if
     the TOS optimization is turned on.

   * Primitives with stack effects of the form `--' out1...outy must
     store the TOS to the stack at the start.  Likewise, primitives
     with the stack effect in1...inx `--' must load the TOS from the
     stack at the end. But for the null stack effect `--' no stores or
     loads should be generated.

Produced code
-------------

   To see what assembly code is produced for the primitives on your
machine with your compiler and your flag settings, type `make engine.s'
and look at the resulting file `engine.s'.  Alternatively, you can also
disassemble the code of primitives with `see' on some architectures.

Performance
===========

   On RISCs the Gforth engine is very close to optimal; i.e., it is
usually impossible to write a significantly faster engine.

   On register-starved machines like the 386 architecture processors
improvements are possible, because `gcc' does not utilize the registers
as well as a human, even with explicit register declarations; e.g.,
Bernd Beuster wrote a Forth system fragment in assembly language and
hand-tuned it for the 486; this system is 1.19 times faster on the
Sieve benchmark on a 486DX2/66 than Gforth compiled with `gcc-2.6.3'
with `-DFORCE_REG'.  The situation has improved with gcc-2.95 and
gforth-0.4.9; now the most important virtual machine registers fit in
real registers (and we can even afford to use the TOS optimization),
resulting in a speedup of 1.14 on the sieve over the earlier results.

   The potential advantage of assembly language implementations is not
necessarily realized in complete Forth systems: We compared Gforth-0.4.9
(direct threaded, compiled with `gcc-2.95.1' and `-DFORCE_REG') with
Win32Forth 1.2093 (newer versions are reportedly much faster), LMI's NT
Forth (Beta, May 1994) and Eforth (with and without peephole (aka
pinhole) optimization of the threaded code); all these systems were
written in assembly language. We also compared Gforth with three
systems written in C: PFE-0.9.14 (compiled with `gcc-2.6.3' with the
default configuration for Linux: `-O2 -fomit-frame-pointer -DUSE_REGS
-DUNROLL_NEXT'), ThisForth Beta (compiled with `gcc-2.6.3 -O3
-fomit-frame-pointer'; ThisForth employs peephole optimization of the
threaded code) and TILE (compiled with `make opt'). We benchmarked
Gforth, PFE, ThisForth and TILE on a 486DX2/66 under Linux. Kenneth
O'Heskin kindly provided the results for Win32Forth and NT Forth on a
486DX2/66 with similar memory performance under Windows NT. Marcel
Hendrix ported Eforth to Linux, then extended it to run the benchmarks,
added the peephole optimizer, ran the benchmarks and reported the
results.

   We used four small benchmarks: the ubiquitous Sieve; bubble-sorting
and matrix multiplication come from the Stanford integer benchmarks and
have been translated into Forth by Martin Fraeman; we used the versions
included in the TILE Forth package, but with bigger data set sizes; and
a recursive Fibonacci number computation for benchmarking calling
performance. The following table shows the time taken for the benchmarks
scaled by the time taken by Gforth (in other words, it shows the speedup
factor that Gforth achieved over the other systems).

     relative      Win32-    NT       eforth       This-
       time  Gforth Forth Forth eforth  +opt   PFE Forth  TILE
     sieve     1.00  1.60  1.32   1.60  0.98  1.82  3.67  9.91
     bubble    1.00  1.55  1.66   1.75  1.04  1.78        4.58
     matmul    1.00  1.71  1.57   1.69  0.86  1.83        4.74
     fib       1.00  1.76  1.54   1.41  1.00  2.01  3.45  4.96

   You may be quite surprised by the good performance of Gforth when
compared with systems written in assembly language. One important reason
for the disappointing performance of these other systems is probably
that they are not written optimally for the 486 (e.g., they use the
`lods' instruction). In addition, Win32Forth uses a comfortable, but
costly method for relocating the Forth image: like `cforth', it
computes the actual addresses at run time, resulting in two address
computations per `NEXT' (*note Image File Background::).

   Only Eforth with the peephole optimizer performs comparable to
Gforth. The speedups achieved with peephole optimization of threaded
code are quite remarkable. Adding a peephole optimizer to Gforth should
cause similar speedups.

   The speedup of Gforth over PFE, ThisForth and TILE can be easily
explained with the self-imposed restriction of the latter systems to
standard C, which makes efficient threading impossible (however, the
measured implementation of PFE uses a GNU C extension: *note Defining
Global Register Variables: (gcc.info)Global Reg Vars.).  Moreover,
current C compilers have a hard time optimizing other aspects of the
ThisForth and the TILE source.

   The performance of Gforth on 386 architecture processors varies
widely with the version of `gcc' used. E.g., `gcc-2.5.8' failed to
allocate any of the virtual machine registers into real machine
registers by itself and would not work correctly with explicit register
declarations, giving a 1.5 times slower engine (on a 486DX2/66 running
the Sieve) than the one measured above.

   Note that there have been several releases of Win32Forth since the
release presented here, so the results presented above may have little
predictive value for the performance of Win32Forth today (results for
the current release on an i486DX2/66 are welcome).

   In `Translating Forth to Efficient C
(http://www.complang.tuwien.ac.at/papers/ertl&maierhofer95.ps.gz)' by
M. Anton Ertl and Martin Maierhofer (presented at EuroForth '95), an
indirect threaded version of Gforth is compared with Win32Forth, NT
Forth, PFE, ThisForth, and several native code systems; that version of
Gforth is slower on a 486 than the direct threaded version used here.
You can find a newer version of these measurements at
`http://www.complang.tuwien.ac.at/forth/performance.html'. You can find
numbers for Gforth on various machines in `Benchres'.

Binding to System Library
*************************

Cross Compiler
**************

   The cross compiler is used to bootstrap a Forth kernel. Since Gforth
is mostly written in Forth, including crucial parts like the outer
interpreter and compiler, it needs compiled Forth code to get started.
The cross compiler allows to create new images for other architectures,
even running under another Forth system.

Using the Cross Compiler
========================

   The cross compiler uses a language that resembles Forth, but isn't.
The main difference is that you can execute Forth code after definition,
while you usually can't execute the code compiled by cross, because the
code you are compiling is typically for a different computer than the
one you are compiling on.

   The Makefile is already set up to allow you to create kernels for new
architectures with a simple make command. The generic kernels using the
GCC compiled virtual machine are created in the normal build process
with `make'. To create a embedded Gforth executable for e.g. the 8086
processor (running on a DOS machine), type

     make kernl-8086.fi

   This will use the machine description from the `arch/8086' directory
to create a new kernel. A machine file may look like that:

     \ Parameter for target systems                         06oct92py
     
         4 Constant cell             \ cell size in bytes
         2 Constant cell<<           \ cell shift to bytes
         5 Constant cell>bit         \ cell shift to bits
         8 Constant bits/char        \ bits per character
         8 Constant bits/byte        \ bits per byte [default: 8]
         8 Constant float            \ bytes per float
         8 Constant /maxalign        \ maximum alignment in bytes
     false Constant bigendian        \ byte order
     ( true=big, false=little )
     
     include machpc.fs               \ feature list

   This part is obligatory for the cross compiler itself, the feature
list is used by the kernel to conditionally compile some features in
and out, depending on whether the target supports these features.

   There are some optional features, if you define your own primitives,
have an assembler, or need special, nonstandard preparation to make the
boot process work. `asm-include' includes an assembler, `prims-include'
includes primitives, and `>boot' prepares for booting.

     : asm-include    ." Include assembler" cr
       s" arch/8086/asm.fs" included ;
     
     : prims-include  ." Include primitives" cr
       s" arch/8086/prim.fs" included ;
     
     : >boot          ." Prepare booting" cr
       s" ' boot >body into-forth 1+ !" evaluate ;

   These words are used as sort of macro during the cross compilation in
the file `kernel/main.fs'. Instead of using these macros, it would be
possible -- but more complicated -- to write a new kernel project file,
too.

   `kernel/main.fs' expects the machine description file name on the
stack; the cross compiler itself (`cross.fs') assumes that either
`mach-file' leaves a counted string on the stack, or `machine-file'
leaves an address, count pair of the filename on the stack.

   The feature list is typically controlled using `SetValue', generic
files that are used by several projects can use `DefaultValue' instead.
Both functions work like `Value', when the value isn't defined, but
`SetValue' works like `to' if the value is defined, and `DefaultValue'
doesn't set anything, if the value is defined.

     \ generic mach file for pc gforth                       03sep97jaw
     
     true DefaultValue NIL  \ relocating
     
     >ENVIRON
     
     true DefaultValue file          \ controls the presence of the
                                     \ file access wordset
     true DefaultValue OS            \ flag to indicate a operating system
     
     true DefaultValue prims         \ true: primitives are c-code
     
     true DefaultValue floating      \ floating point wordset is present
     
     true DefaultValue glocals       \ gforth locals are present
                                     \ will be loaded
     true DefaultValue dcomps        \ double number comparisons
     
     true DefaultValue hash          \ hashing primitives are loaded/present
     
     true DefaultValue xconds        \ used together with glocals,
                                     \ special conditionals supporting gforths'
                                     \ local variables
     true DefaultValue header        \ save a header information
     
     true DefaultValue backtrace     \ enables backtrace code
     
     false DefaultValue ec
     false DefaultValue crlf
     
     cell 2 = [IF] &32 [ELSE] &256 [THEN] KB DefaultValue kernel-size
     
     &16 KB          DefaultValue stack-size
     &15 KB &512 +   DefaultValue fstack-size
     &15 KB          DefaultValue rstack-size
     &14 KB &512 +   DefaultValue lstack-size

How the Cross Compiler Works
============================

Bugs
****

   Known bugs are described in the file `BUGS' in the Gforth
distribution.

   If you find a bug, please send a bug report to <bug-gforth@gnu.org>.
A bug report should include this information:

   * A program (or a sequence of keyboard commands) that reproduces the
     bug.

   * A description of what you think constitutes the buggy behaviour.

   * The Gforth version used (it is announced at the start of an
     interactive Gforth session).

   * The machine and operating system (on Unix systems `uname -a' will
     report this information).

   * The installation options (you can find the configure options at the
     start of `config.status') and configuration (`configure' output or
     `config.cache').

   * A complete list of changes (if any) you (or your installer) have
     made to the Gforth sources.

   For a thorough guide on reporting bugs read *Note How to Report
Bugs: (gcc.info)Bug Reporting.

Authors and Ancestors of Gforth
*******************************

Authors and Contributors
========================

   The Gforth project was started in mid-1992 by Bernd Paysan and Anton
Ertl. The third major author was Jens Wilke.  Neal Crook contributed a
lot to the manual.  Assemblers and disassemblers were contributed by
Andrew McKewan, Christian Pirker, and Bernd Thallner.  Lennart Benschop
(who was one of Gforth's first users, in mid-1993) and Stuart Ramsden
inspired us with their continuous feedback. Lennart Benshop contributed
`glosgen.fs', while Stuart Ramsden has been working on automatic
support for calling C libraries. Helpful comments also came from Paul
Kleinrubatscher, Christian Pirker, Dirk Zoller, Marcel Hendrix, John
Wavrik, Barrie Stott, Marc de Groot, Jorge Acerada, Bruce Hoyt, and
Robert Epprecht. Since the release of Gforth-0.2.1 there were also
helpful comments from many others; thank you all, sorry for not listing
you here (but digging through my mailbox to extract your names is on my
to-do list).

   Gforth also owes a lot to the authors of the tools we used (GCC, CVS,
and autoconf, among others), and to the creators of the Internet: Gforth
was developed across the Internet, and its authors did not meet
physically for the first 4 years of development.

Pedigree
========

   Gforth descends from bigFORTH (1993) and fig-Forth.  Of course, a
significant part of the design of Gforth was prescribed by ANS Forth.

   Bernd Paysan wrote bigFORTH, a descendent from TurboForth, an
unreleased 32 bit native code version of VolksForth for the Atari ST,
written mostly by Dietrich Weineck.

   VolksForth was written by Klaus Schleisiek, Bernd Pennemann, Georg
Rehfeld and Dietrich Weineck for the C64 (called UltraForth there) in
the mid-80s and ported to the Atari ST in 1986.  It descends from F83.

   Henry Laxen and Mike Perry wrote F83 as a model implementation of the
Forth-83 standard. !! Pedigree? When?

   A team led by Bill Ragsdale implemented fig-Forth on many processors
in 1979. Robert Selzer and Bill Ragsdale developed the original
implementation of fig-Forth for the 6502 based on microForth.

   The principal architect of microForth was Dean Sanderson. microForth
was FORTH, Inc.'s first off-the-shelf product. It was developed in 1976
for the 1802, and subsequently implemented on the 8080, the 6800 and the
Z80.

   All earlier Forth systems were custom-made, usually by Charles Moore,
who discovered (as he puts it) Forth during the late 60s. The first full
Forth existed in 1971.

   A part of the information in this section comes from `The Evolution
of Forth (http://www.forth.com/Content/History/History1.htm)' by
Elizabeth D. Rather, Donald R. Colburn and Charles H. Moore, presented
at the HOPL-II conference and preprinted in SIGPLAN Notices 28(3),
1993.  You can find more historical and genealogical information about
Forth there.

Other Forth-related information
*******************************

   There is an active news group (comp.lang.forth) discussing Forth
(including Gforth) and Forth-related issues. Its FAQs
(http://www.complang.tuwien.ac.at/forth/faq/faq-general-2.html)
(frequently asked questions and their answers) contains a lot of
information on Forth.  You should read it before posting to
comp.lang.forth.

   The ANS Forth standard is most usable in its HTML form
(http://www.taygeta.com/forth/dpans.html).

Word Index
**********

   This index is a list of Forth words that have "glossary" entries
within this manual. Each word is listed with its stack effect and
wordset.

!  W A-ADDR -    core:
          See ``Memory Access''.
#  UD1 - UD2     core:
          See ``Formatted numeric output''.
#!  -     gforth:
          See ``Running Image Files''.
#>  XD - ADDR U     core:
          See ``Formatted numeric output''.
#>>  -     gforth:
          See ``Formatted numeric output''.
#s  UD - 0 0     core:
          See ``Formatted numeric output''.
#tib  - A-ADDR     core-ext:
          See ``The Text Interpreter''.
$?  - N     gforth:
          See ``Passing Commands to the Operating System''.
%align  ALIGN SIZE -     gforth:
          See ``Structure Glossary''.
%alignment  ALIGN SIZE - ALIGN     gforth:
          See ``Structure Glossary''.
%alloc  SIZE ALIGN - ADDR     gforth:
          See ``Structure Glossary''.
%allocate  ALIGN SIZE - ADDR IOR     gforth:
          See ``Structure Glossary''.
%allot  ALIGN SIZE - ADDR     gforth:
          See ``Structure Glossary''.
%size  ALIGN SIZE - SIZE     gforth:
          See ``Structure Glossary''.
'  "NAME" - XT     core:
          See ``Execution token''.
'  "NAME" - XT     oof:
          See ``The `oof.fs' base class''.
'cold  -     gforth:
          See ``Modifying the Startup Sequence''.
(  COMPILATION 'CCC<CLOSE-PAREN>' - ; RUN-TIME -     core,file:
          See ``Comments''.
(local)  ADDR U -     local:
          See ``ANS Forth locals''.
)  -     gforth:
          See ``Assertions''.
*  N1 N2 - N    core:
          See ``Single precision''.
*/  N1 N2 N3 - N4     core:
          See ``Mixed precision''.
*/mod  N1 N2 N3 - N4 N5     core:
          See ``Mixed precision''.
+  N1 N2 - N    core:
          See ``Single precision''.
+!  N A-ADDR -    core:
          See ``Memory Access''.
+DO  COMPILATION - DO-SYS ; RUN-TIME N1 N2 - | LOOP-SYS     gforth:
          See ``Arbitrary control structures''.
+load  I*X N - J*X     gforth:
          See ``Blocks''.
+LOOP  COMPILATION DO-SYS - ; RUN-TIME LOOP-SYS1 N - | LOOP-SYS2     core:
          See ``Arbitrary control structures''.
+thru  I*X N1 N2 - J*X     gforth:
          See ``Blocks''.
,  W -     core:
          See ``Dictionary allocation''.
-  N1 N2 - N    core:
          See ``Single precision''.
-->  -     gforth:
          See ``Blocks''.
-DO  COMPILATION - DO-SYS ; RUN-TIME N1 N2 - | LOOP-SYS     gforth:
          See ``Arbitrary control structures''.
-LOOP  COMPILATION DO-SYS - ; RUN-TIME LOOP-SYS1 U - | LOOP-SYS2     gforth:
          See ``Arbitrary control structures''.
-rot  W1 W2 W3 - W3 W1 W2    gforth:
          See ``Data stack''.
-trailing  C-ADDR U1 - C-ADDR U2    string:
          See ``Memory Blocks''.
.  N -     core:
          See ``Simple numeric output''.
."  COMPILATION 'CCC"' - ; RUN-TIME -     core:
          See ``Displaying characters and strings''.
.(  COMPILATION,INTERPRETATION "CCC<PAREN>" -     core-ext:
          See ``Displaying characters and strings''.
.path  PATH-ADDR -     gforth:
          See ``General Search Paths''.
.r  N1 N2 -     core-ext:
          See ``Simple numeric output''.
.s  -     tools:
          See ``Examining data and code''.
/  N1 N2 - N    core:
          See ``Single precision''.
/does-handler  - N    gforth:
          See ``Threading Words''.
/mod  N1 N2 - N3 N4    core:
          See ``Single precision''.
/string  C-ADDR1 U1 N - C-ADDR2 U2    string:
          See ``Memory Blocks''.
0<  N - F    core:
          See ``Numeric comparison''.
0<=  N - F    gforth:
          See ``Numeric comparison''.
0<>  N - F    core-ext:
          See ``Numeric comparison''.
0=  N - F    core:
          See ``Numeric comparison''.
0>  N - F    core-ext:
          See ``Numeric comparison''.
0>=  N - F    gforth:
          See ``Numeric comparison''.
1+  N1 - N2    core:
          See ``Single precision''.
1-  N1 - N2    core:
          See ``Single precision''.
1/f  R1 - R2     gforth:
          See ``Floating Point''.
2!  W1 W2 A-ADDR -    core:
          See ``Memory Access''.
2*  N1 - N2    core:
          See ``Bitwise operations''.
2,  W1 W2 -     gforth:
          See ``Dictionary allocation''.
2/  N1 - N2    core:
          See ``Bitwise operations''.
2>r  W1 W2 -    core-ext:
          See ``Return stack''.
2@  A-ADDR - W1 W2    core:
          See ``Memory Access''.
2Constant  W1 W2 "NAME" -     double:
          See ``Constants''.
2drop  W1 W2 -    core:
          See ``Data stack''.
2dup  W1 W2 - W1 W2 W1 W2    core:
          See ``Data stack''.
2Literal  COMPILATION W1 W2 - ; RUN-TIME  - W1 W2     double:
          See ``Literals''.
2nip  W1 W2 W3 W4 - W3 W4    gforth:
          See ``Data stack''.
2over  W1 W2 W3 W4 - W1 W2 W3 W4 W1 W2    core:
          See ``Data stack''.
2r>  - W1 W2    core-ext:
          See ``Return stack''.
2r@  - W1 W2    core-ext:
          See ``Return stack''.
2rdrop  -    gforth:
          See ``Return stack''.
2rot  W1 W2 W3 W4 W5 W6 - W3 W4 W5 W6 W1 W2    double-ext:
          See ``Data stack''.
2swap  W1 W2 W3 W4 - W3 W4 W1 W2    core:
          See ``Data stack''.
2tuck  W1 W2 W3 W4 - W3 W4 W1 W2 W3 W4    gforth:
          See ``Data stack''.
2Variable  "NAME" -     double:
          See ``Variables''.
:  "NAME" -     oof:
          See ``The `oof.fs' base class''.
:  "NAME" - COLON-SYS     core:
          See ``Colon Definitions''.
::  "NAME" -     oof:
          See ``The `oof.fs' base class''.
::  CLASS "NAME" -     mini-oof:
          See ``Basic `mini-oof.fs' Usage''.
:m  "NAME" - XT; RUN-TIME: OBJECT -     objects:
          See ```objects.fs' Glossary''.
:noname  - XT COLON-SYS     core-ext:
          See ``Anonymous Definitions''.
;  COMPILATION COLON-SYS - ; RUN-TIME NEST-SYS     core:
          See ``Colon Definitions''.
;code  COMPILATION. COLON-SYS1 - COLON-SYS2     tools-ext:
          See ```Code' and `;code'''.
;m  COLON-SYS -; RUN-TIME: -     objects:
          See ```objects.fs' Glossary''.
;s  -    gforth:
          See ``Calls and returns''.
<  N1 N2 - F    core:
          See ``Numeric comparison''.
<#  -     core:
          See ``Formatted numeric output''.
<<#  -     gforth:
          See ``Formatted numeric output''.
<=  N1 N2 - F    gforth:
          See ``Numeric comparison''.
<>  N1 N2 - F    core-ext:
          See ``Numeric comparison''.
<bind>  CLASS SELECTOR-XT - XT     objects:
          See ```objects.fs' Glossary''.
<compilation  COMPILATION. ORIG COLON-SYS -     gforth:
          See ``Combined Words''.
<interpretation  COMPILATION. ORIG COLON-SYS -     gforth:
          See ``Combined Words''.
<IS>  "NAME" XT -     gforth:
          See ``Deferred words''.
<to-inst>  W XT -     objects:
          See ```objects.fs' Glossary''.
=  N1 N2 - F    core:
          See ``Numeric comparison''.
>  N1 N2 - F    core:
          See ``Numeric comparison''.
>=  N1 N2 - F    gforth:
          See ``Numeric comparison''.
>body  XT - A-ADDR    core:
          See ``The gory details of `CREATE..DOES>'''.
>code-address  XT - C-ADDR    gforth:
          See ``Threading Words''.
>does-code  XT - A-ADDR    gforth:
          See ``Threading Words''.
>float  C-ADDR U - FLAG    float:
          See ``Input''.
>in  - A-ADDR     core:
          See ``The Text Interpreter''.
>l  W -    gforth:
          See ``Locals implementation''.
>number  UD1 C-ADDR1 U1 - UD2 C-ADDR2 U2     core:
          See ``Input''.
>order  WID -     gforth:
          See ``Word Lists''.
>r  W -    core:
          See ``Return stack''.
?  A-ADDR -     tools:
          See ``Examining data and code''.
?DO  COMPILATION - DO-SYS ; RUN-TIME W1 W2 - | LOOP-SYS     core-ext:
          See ``Arbitrary control structures''.
?dup  W - W    core:
          See ``Data stack''.
?DUP-0=-IF  COMPILATION - ORIG ; RUN-TIME N - N|     gforth:
          See ``Arbitrary control structures''.
?DUP-IF  COMPILATION - ORIG ; RUN-TIME N - N|     gforth:
          See ``Arbitrary control structures''.
?LEAVE  COMPILATION - ; RUN-TIME F | F LOOP-SYS -     gforth:
          See ``Arbitrary control structures''.
@  A-ADDR - W    core:
          See ``Memory Access''.
@local#  - W    gforth:
          See ``Locals implementation''.
[  -     core:
          See ``Literals''.
[']  COMPILATION. "NAME" - ; RUN-TIME. - XT     core:
          See ``Execution token''.
[+LOOP]  N -     gforth:
          See ``Interpreter Directives''.
[?DO]  N-LIMIT N-INDEX -     gforth:
          See ``Interpreter Directives''.
[]  N "NAME" -     oof:
          See ``The `oof.fs' base class''.
[AGAIN]  -     gforth:
          See ``Interpreter Directives''.
[BEGIN]  -     gforth:
          See ``Interpreter Directives''.
[bind]  COMPILE-TIME: "CLASS" "SELECTOR" - ; RUN-TIME: ... OBJECT - ...     objects:
          See ```objects.fs' Glossary''.
[char]  COMPILATION '<SPACES>CCC' - ; RUN-TIME - C     core:
          See ``Displaying characters and strings''.
[COMP']  COMPILATION "NAME" - ; RUN-TIME - W XT     gforth:
          See ``Compilation token''.
[compile]  COMPILATION "NAME" - ; RUN-TIME ? - ?     core-ext:
          See ``Macros''.
[current]  COMPILE-TIME: "SELECTOR" - ; RUN-TIME: ... OBJECT - ...     objects:
          See ```objects.fs' Glossary''.
[DO]  N-LIMIT N-INDEX -     gforth:
          See ``Interpreter Directives''.
[ELSE]  "<SPACES>NAME ..." -     tools-ext:
          See ``Interpreter Directives''.
[ENDIF]  -     gforth:
          See ``Interpreter Directives''.
[FOR]  N -     gforth:
          See ``Interpreter Directives''.
[IF]  FLAG | FLAG "<SPACES>NAME ..." -     tools-ext:
          See ``Interpreter Directives''.
[IFDEF]  "<SPACES>NAME" -     gforth:
          See ``Interpreter Directives''.
[IFUNDEF]  "<SPACES>NAME" -     gforth:
          See ``Interpreter Directives''.
[IS]  COMPILATION "NAME" - ; RUN-TIME XT -     gforth:
          See ``Deferred words''.
[LOOP]  -     gforth:
          See ``Interpreter Directives''.
[NEXT]  N -     gforth:
          See ``Interpreter Directives''.
[parent]  COMPILE-TIME: "SELECTOR" - ; RUN-TIME: ... OBJECT - ...     objects:
          See ```objects.fs' Glossary''.
[REPEAT]  -     gforth:
          See ``Interpreter Directives''.
[THEN]  -     tools-ext:
          See ``Interpreter Directives''.
[to-inst]  COMPILE-TIME: "NAME" - ; RUN-TIME: W -     objects:
          See ```objects.fs' Glossary''.
[UNTIL]  FLAG -     gforth:
          See ``Interpreter Directives''.
[WHILE]  FLAG -     gforth:
          See ``Interpreter Directives''.
\  COMPILATION 'CCC<NEWLINE>' - ; RUN-TIME -     core-ext,block-ext:
          See ``Comments''.
\G  COMPILATION 'CCC<NEWLINE>' - ; RUN-TIME -     gforth:
          See ``Comments''.
]  -     core:
          See ``Literals''.
]L  COMPILATION: N - ; RUN-TIME: - N     gforth:
          See ``Literals''.
abort  ?? - ??     core,exception-ext:
          See ``Exception Handling''.
abort"  COMPILATION 'CCC"' - ; RUN-TIME F -     core,exception-ext:
          See ``Exception Handling''.
abs  N - U    core:
          See ``Single precision''.
accept  C-ADDR +N1 - +N2     core:
          See ``Input''.
ADDRESS-UNIT-BITS  - N     environment:
          See ``Address arithmetic''.
AGAIN  COMPILATION DEST - ; RUN-TIME -     core-ext:
          See ``Arbitrary control structures''.
AHEAD  COMPILATION - ORIG ; RUN-TIME -     tools-ext:
          See ``Arbitrary control structures''.
Alias  XT "NAME" -     gforth:
          See ``Aliases''.
align  -     core:
          See ``Dictionary allocation''.
aligned  C-ADDR - A-ADDR    core:
          See ``Address arithmetic''.
allocate  U - A-ADDR WIOR    memory:
          See ``Heap allocation''.
allot  N -     core:
          See ``Dictionary allocation''.
also  -     search-ext:
          See ``Word Lists''.
also-path  C-ADDR LEN PATH-ADDR -     gforth:
          See ``General Search Paths''.
and  W1 W2 - W    core:
          See ``Bitwise operations''.
arg  N - ADDR COUNT     gforth:
          See ``Modifying the Startup Sequence''.
argc  - ADDR     gforth:
          See ``Modifying the Startup Sequence''.
argv  - ADDR     gforth:
          See ``Modifying the Startup Sequence''.
asptr  CLASS -     oof:
          See ``Class Declaration''.
asptr  O "NAME" -     oof:
          See ``The `oof.fs' base class''.
assembler  -     tools-ext:
          See ```Code' and `;code'''.
assert(  -     gforth:
          See ``Assertions''.
assert-level  - A-ADDR     gforth:
          See ``Assertions''.
assert0(  -     gforth:
          See ``Assertions''.
assert1(  -     gforth:
          See ``Assertions''.
assert2(  -     gforth:
          See ``Assertions''.
assert3(  -     gforth:
          See ``Assertions''.
ASSUME-LIVE  ORIG - ORIG     gforth:
          See ``Where are locals visible by name?''.
at-xy  U1 U2 -     facility:
          See ``Displaying characters and strings''.
base  - A-ADDR     core:
          See ``Number Conversion''.
BEGIN  COMPILATION - DEST ; RUN-TIME -     core:
          See ``Arbitrary control structures''.
bin  FAM1 - FAM2     file:
          See ``General files''.
bind  ... "CLASS" "SELECTOR" - ...     objects:
          See ```objects.fs' Glossary''.
bind  O "NAME" -     oof:
          See ``The `oof.fs' base class''.
bind'  "CLASS" "SELECTOR" - XT     objects:
          See ```objects.fs' Glossary''.
bl  - C-CHAR     core:
          See ``Displaying characters and strings''.
blank  C-ADDR U -     string:
          See ``Memory Blocks''.
blk  - A-ADDR     block:
          See ``Input Sources''.
block  U - A-ADDR     block:
          See ``Blocks''.
block-included  A-ADDR U -     gforth:
          See ``Blocks''.
block-offset  - ADDR     gforth:
          See ``Blocks''.
block-position  U -     block:
          See ``Blocks''.
bound  CLASS ADDR "NAME" -     oof:
          See ``The `oof.fs' base class''.
bounds  ADDR U - ADDR+U ADDR     gforth:
          See ``Memory Blocks''.
break"  'CCC"' -     gforth:
          See ``Singlestep Debugger''.
break:  -     gforth:
          See ``Singlestep Debugger''.
buffer  U - A-ADDR     block:
          See ``Blocks''.
bye  -     tools-ext:
          See ``Leaving Gforth''.
c!  C C-ADDR -    core:
          See ``Memory Access''.
C"  COMPILATION "CCC<QUOTE>" - ; RUN-TIME  - C-ADDR     core-ext:
          See ``Displaying characters and strings''.
c,  C -     core:
          See ``Dictionary allocation''.
c@  C-ADDR - C    core:
          See ``Memory Access''.
case  COMPILATION  - CASE-SYS ; RUN-TIME  -     core-ext:
          See ``Arbitrary control structures''.
catch  ... XT - ... N     exception:
          See ``Exception Handling''.
cell  - U     gforth:
          See ``Address arithmetic''.
cell%  - ALIGN SIZE     gforth:
          See ``Structure Glossary''.
cell+  A-ADDR1 - A-ADDR2    core:
          See ``Address arithmetic''.
cells  N1 - N2    core:
          See ``Address arithmetic''.
cfalign  -     gforth:
          See ``Dictionary allocation''.
cfaligned  ADDR1 - ADDR2     gforth:
          See ``Address arithmetic''.
char  '<SPACES>CCC' - C     core:
          See ``Displaying characters and strings''.
char%  - ALIGN SIZE     gforth:
          See ``Structure Glossary''.
char+  C-ADDR1 - C-ADDR2    core:
          See ``Address arithmetic''.
chars  N1 - N2     core:
          See ``Address arithmetic''.
class  "NAME" -     oof:
          See ``The `oof.fs' base class''.
class  CLASS - CLASS SELECTORS VARS     mini-oof:
          See ``Basic `mini-oof.fs' Usage''.
class  PARENT-CLASS - ALIGN OFFSET     objects:
          See ```objects.fs' Glossary''.
class->map  CLASS - MAP     objects:
          See ```objects.fs' Glossary''.
class-inst-size  CLASS - ADDR     objects:
          See ```objects.fs' Glossary''.
class-override!  XT SEL-XT CLASS-MAP -     objects:
          See ```objects.fs' Glossary''.
class-previous  CLASS -     objects:
          See ```objects.fs' Glossary''.
class;  -     oof:
          See ``Class Declaration''.
class>order  CLASS -     objects:
          See ```objects.fs' Glossary''.
class?  O - FLAG     oof:
          See ``The `oof.fs' base class''.
clear-path  PATH-ADDR -     gforth:
          See ``General Search Paths''.
clearstack  ... -     gforth:
          See ``Examining data and code''.
close-file  WFILEID - WIOR    file:
          See ``General files''.
cmove  C-FROM C-TO U -    string:
          See ``Memory Blocks''.
cmove>  C-FROM C-TO U -    string:
          See ``Memory Blocks''.
code  "NAME" - COLON-SYS     tools-ext:
          See ```Code' and `;code'''.
code-address!  C-ADDR XT -    gforth:
          See ``Threading Words''.
common-list  LIST1 LIST2 - LIST3     gforth-internal:
          See ``Locals implementation''.
COMP'  "NAME" - W XT     gforth:
          See ``Compilation token''.
compare  C-ADDR1 U1 C-ADDR2 U2 - N    string:
          See ``Memory Blocks''.
compilation>  COMPILATION. - ORIG COLON-SYS     gforth:
          See ``Combined Words''.
compile,  XT -     core-ext:
          See ``Macros''.
compile-@local  N -     gforth:
          See ``Locals implementation''.
compile-f@local  N -     gforth:
          See ``Locals implementation''.
compile-lp+!  N -     gforth:
          See ``Locals implementation''.
compile-only  -     gforth:
          See ``Interpretation and Compilation Semantics''.
Constant  W "NAME" -     core:
          See ``Constants''.
construct  ... OBJECT -     objects:
          See ```objects.fs' Glossary''.
context  - ADDR     gforth:
          See ``Word Lists''.
convert  UD1 C-ADDR1 - UD2 C-ADDR2     core-ext:
          See ``Input''.
count  C-ADDR1 - C-ADDR2 U    core:
          See ``String Formats''.
cputime  - DUSER DSYSTEM    gforth:
          See ``Keeping track of Time''.
cr  -     core:
          See ``Displaying characters and strings''.
Create  "NAME" -     core:
          See ```CREATE'''.
create-file  C-ADDR U WFAM - WFILEID WIOR    file:
          See ``General files''.
create-interpret/compile  "NAME" -     gforth:
          See ``Combined Words''.
CS-PICK  ... U - ... DESTU     tools-ext:
          See ``Arbitrary control structures''.
CS-ROLL  DESTU/ORIGU .. DEST0/ORIG0 U - .. DEST0/ORIG0 DESTU/ORIGU     tools-ext:
          See ``Arbitrary control structures''.
current  - ADDR     gforth:
          See ``Word Lists''.
current'  "SELECTOR" - XT     objects:
          See ```objects.fs' Glossary''.
current-interface  - ADDR     objects:
          See ```objects.fs' Glossary''.
d+  D1 D2 - D    double:
          See ``Double precision''.
d-  D1 D2 - D    double:
          See ``Double precision''.
d.  D -     double:
          See ``Simple numeric output''.
d.r  D N -     double:
          See ``Simple numeric output''.
d0<  D - F    double:
          See ``Numeric comparison''.
d0<=  D - F    gforth:
          See ``Numeric comparison''.
d0<>  D - F    gforth:
          See ``Numeric comparison''.
d0=  D - F    double:
          See ``Numeric comparison''.
d0>  D - F    gforth:
          See ``Numeric comparison''.
d0>=  D - F    gforth:
          See ``Numeric comparison''.
d2*  D1 - D2    double:
          See ``Bitwise operations''.
d2/  D1 - D2    double:
          See ``Bitwise operations''.
d<  D1 D2 - F    double:
          See ``Numeric comparison''.
d<=  D1 D2 - F    gforth:
          See ``Numeric comparison''.
d<>  D1 D2 - F    gforth:
          See ``Numeric comparison''.
d=  D1 D2 - F    double:
          See ``Numeric comparison''.
d>  D1 D2 - F    gforth:
          See ``Numeric comparison''.
d>=  D1 D2 - F    gforth:
          See ``Numeric comparison''.
d>f  D - R    float:
          See ``Floating Point''.
d>s  D - N     double:
          See ``Double precision''.
dabs  D - UD     double:
          See ``Double precision''.
dbg  "NAME" -     gforth:
          See ``Singlestep Debugger''.
dec.  N -     gforth:
          See ``Simple numeric output''.
decimal  -     core:
          See ``Number Conversion''.
Defer  "NAME" -     gforth:
          See ``Deferred words''.
defer  -     oof:
          See ``Class Declaration''.
Defers  COMPILATION "NAME" - ; RUN-TIME ... - ...     gforth:
          See ``Deferred words''.
defines  XT CLASS "NAME" -     mini-oof:
          See ``Basic `mini-oof.fs' Usage''.
definitions  -     oof:
          See ``The `oof.fs' base class''.
definitions  -     search:
          See ``Word Lists''.
delete-file  C-ADDR U - WIOR    file:
          See ``General files''.
depth  - +N     core:
          See ``Examining data and code''.
df!  R DF-ADDR -    float-ext:
          See ``Memory Access''.
df@  DF-ADDR - R    float-ext:
          See ``Memory Access''.
dfalign  -     float-ext:
          See ``Dictionary allocation''.
dfaligned  C-ADDR - DF-ADDR    float-ext:
          See ``Address arithmetic''.
dfloat%  - ALIGN SIZE     gforth:
          See ``Structure Glossary''.
dfloat+  DF-ADDR1 - DF-ADDR2     float-ext:
          See ``Address arithmetic''.
dfloats  N1 - N2    float-ext:
          See ``Address arithmetic''.
dict-new  ... CLASS - OBJECT     objects:
          See ```objects.fs' Glossary''.
dispose  -     oof:
          See ``The `oof.fs' base class''.
dmax  D1 D2 - D     double:
          See ``Double precision''.
dmin  D1 D2 - D     double:
          See ``Double precision''.
dnegate  D1 - D2    double:
          See ``Double precision''.
DO  COMPILATION - DO-SYS ; RUN-TIME W1 W2 - LOOP-SYS     core:
          See ``Arbitrary control structures''.
docol:  - ADDR     gforth:
          See ``Threading Words''.
docon:  - ADDR     gforth:
          See ``Threading Words''.
dodefer:  - ADDR     gforth:
          See ``Threading Words''.
does-code!  A-ADDR XT -    gforth:
          See ``Threading Words''.
does-handler!  A-ADDR -    gforth:
          See ``Threading Words''.
DOES>  COMPILATION COLON-SYS1 - COLON-SYS2 ; RUN-TIME NEST-SYS -     core:
          See ``The gory details of `CREATE..DOES>'''.
dofield:  - ADDR     gforth:
          See ``Threading Words''.
DONE  COMPILATION ORIG - ; RUN-TIME -     gforth:
          See ``Arbitrary control structures''.
double%  - ALIGN SIZE     gforth:
          See ``Structure Glossary''.
douser:  - ADDR     gforth:
          See ``Threading Words''.
dovar:  - ADDR     gforth:
          See ``Threading Words''.
dpl  - A-ADDR     gforth:
          See ``Number Conversion''.
drop  W -    core:
          See ``Data stack''.
du<  UD1 UD2 - F    double-ext:
          See ``Numeric comparison''.
du<=  UD1 UD2 - F    gforth:
          See ``Numeric comparison''.
du>  UD1 UD2 - F    gforth:
          See ``Numeric comparison''.
du>=  UD1 UD2 - F    gforth:
          See ``Numeric comparison''.
dump  ADDR U -     tools:
          See ``Examining data and code''.
dup  W - W W    core:
          See ``Data stack''.
early  -     oof:
          See ``Class Declaration''.
ekey  - U     facility-ext:
          See ``Input''.
ekey>char  U - U FALSE | C TRUE     facility-ext:
          See ``Input''.
ekey?  - FLAG     facility-ext:
          See ``Input''.
ELSE  COMPILATION ORIG1 - ORIG2 ; RUN-TIME F -     core:
          See ``Arbitrary control structures''.
emit  C -     core:
          See ``Displaying characters and strings''.
emit-file  C WFILEID - WIOR    gforth:
          See ``General files''.
empty-buffer  BUFFER -     gforth:
          See ``Blocks''.
empty-buffers  -     block-ext:
          See ``Blocks''.
end-class  ALIGN OFFSET "NAME" -     objects:
          See ```objects.fs' Glossary''.
end-class  CLASS SELECTORS VARS "NAME" -     mini-oof:
          See ``Basic `mini-oof.fs' Usage''.
end-class-noname  ALIGN OFFSET - CLASS     objects:
          See ```objects.fs' Glossary''.
end-code  COLON-SYS -     gforth:
          See ```Code' and `;code'''.
end-interface  "NAME" -     objects:
          See ```objects.fs' Glossary''.
end-interface-noname  - INTERFACE     objects:
          See ```objects.fs' Glossary''.
end-methods  -     objects:
          See ```objects.fs' Glossary''.
end-struct  ALIGN SIZE "NAME" -     gforth:
          See ``Structure Glossary''.
endcase  COMPILATION CASE-SYS - ; RUN-TIME X -     core-ext:
          See ``Arbitrary control structures''.
ENDIF  COMPILATION ORIG - ; RUN-TIME -     gforth:
          See ``Arbitrary control structures''.
endof  COMPILATION CASE-SYS1 OF-SYS - CASE-SYS2 ; RUN-TIME  -     core-ext:
          See ``Arbitrary control structures''.
endscope  COMPILATION SCOPE - ; RUN-TIME  -     gforth:
          See ``Where are locals visible by name?''.
endtry  COMPILATION  ORIG - ; RUN-TIME  -     gforth:
          See ``Exception Handling''.
endwith  -     oof:
          See ``The `oof.fs' base class''.
environment-wordlist  - WID     gforth:
          See ``Environmental Queries''.
environment?  C-ADDR U - FALSE / ... TRUE     core:
          See ``Environmental Queries''.
erase  ADDR U -     core-ext:
          See ``Memory Blocks''.
evaluate  C-ADDR U -     core,block:
          See ``Input Sources''.
exception  ADDR U - N     gforth:
          See ``Exception Handling''.
execute  XT -    core:
          See ``Execution token''.
EXIT  COMPILATION - ; RUN-TIME NEST-SYS -     core:
          See ``Calls and returns''.
exitm  -     objects:
          See ```objects.fs' Glossary''.
expect  C-ADDR +N -     core-ext:
          See ``Input''.
f!  R F-ADDR -    float:
          See ``Memory Access''.
f*  R1 R2 - R3    float:
          See ``Floating Point''.
f**  R1 R2 - R3    float-ext:
          See ``Floating Point''.
f+  R1 R2 - R3    float:
          See ``Floating Point''.
f,  F -     gforth:
          See ``Dictionary allocation''.
f-  R1 R2 - R3    float:
          See ``Floating Point''.
f.  R -     float-ext:
          See ``Simple numeric output''.
f.s  -     gforth:
          See ``Examining data and code''.
f/  R1 R2 - R3    float:
          See ``Floating Point''.
f0<  R - F    float:
          See ``Floating Point''.
f0<=  R - F    gforth:
          See ``Floating Point''.
f0<>  R - F    gforth:
          See ``Floating Point''.
f0=  R - F    float:
          See ``Floating Point''.
f0>  R - F    gforth:
          See ``Floating Point''.
f0>=  R - F    gforth:
          See ``Floating Point''.
f2*  R1 - R2     gforth:
          See ``Floating Point''.
f2/  R1 - R2     gforth:
          See ``Floating Point''.
f<  R1 R2 - F    float:
          See ``Floating Point''.
f<=  R1 R2 - F    gforth:
          See ``Floating Point''.
f<>  R1 R2 - F    gforth:
          See ``Floating Point''.
f=  R1 R2 - F    gforth:
          See ``Floating Point''.
f>  R1 R2 - F    gforth:
          See ``Floating Point''.
f>=  R1 R2 - F    gforth:
          See ``Floating Point''.
f>d  R - D    float:
          See ``Floating Point''.
f>l  R -    gforth:
          See ``Locals implementation''.
f@  F-ADDR - R    float:
          See ``Memory Access''.
f@local#  - R    gforth:
          See ``Locals implementation''.
fabs  R1 - R2    float-ext:
          See ``Floating Point''.
facos  R1 - R2    float-ext:
          See ``Floating Point''.
facosh  R1 - R2    float-ext:
          See ``Floating Point''.
falign  -     float:
          See ``Dictionary allocation''.
faligned  C-ADDR - F-ADDR    float:
          See ``Address arithmetic''.
falog  R1 - R2    float-ext:
          See ``Floating Point''.
false  - F     core-ext:
          See ``Boolean Flags''.
fasin  R1 - R2    float-ext:
          See ``Floating Point''.
fasinh  R1 - R2    float-ext:
          See ``Floating Point''.
fatan  R1 - R2    float-ext:
          See ``Floating Point''.
fatan2  R1 R2 - R3    float-ext:
          See ``Floating Point''.
fatanh  R1 - R2    float-ext:
          See ``Floating Point''.
fconstant  R "NAME" -     float:
          See ``Constants''.
fcos  R1 - R2    float-ext:
          See ``Floating Point''.
fcosh  R1 - R2    float-ext:
          See ``Floating Point''.
fdepth  - +N     float:
          See ``Examining data and code''.
fdrop  R -    float:
          See ``Floating point stack''.
fdup  R - R R    float:
          See ``Floating point stack''.
fe.  R -     float-ext:
          See ``Simple numeric output''.
fexp  R1 - R2    float-ext:
          See ``Floating Point''.
fexpm1  R1 - R2    float-ext:
          See ``Floating Point''.
field  ALIGN1 OFFSET1 ALIGN SIZE "NAME" -  ALIGN2 OFFSET2     gforth:
          See ``Structure Glossary''.
file-position  WFILEID - UD WIOR    file:
          See ``General files''.
file-size  WFILEID - UD WIOR    file:
          See ``General files''.
file-status  C-ADDR U - WFAM WIOR    file-ext:
          See ``General files''.
fill  C-ADDR U C -    core:
          See ``Memory Blocks''.
find  C-ADDR - XT +-1 | C-ADDR 0     core,search:
          See ``Word Lists''.
find-name  C-ADDR U - NT | 0     gforth:
          See ``Name token''.
FLiteral  COMPILATION R - ; RUN-TIME - R     float:
          See ``Literals''.
fln  R1 - R2    float-ext:
          See ``Floating Point''.
flnp1  R1 - R2    float-ext:
          See ``Floating Point''.
float  - U     gforth:
          See ``Address arithmetic''.
float%  - ALIGN SIZE     gforth:
          See ``Structure Glossary''.
float+  F-ADDR1 - F-ADDR2    float:
          See ``Address arithmetic''.
floating-stack  - N     environment:
          See ``Floating point stack''.
floats  N1 - N2    float:
          See ``Address arithmetic''.
flog  R1 - R2    float-ext:
          See ``Floating Point''.
floor  R1 - R2    float:
          See ``Floating Point''.
FLOORED  - F     environment:
          See ``Single precision''.
flush  -     block:
          See ``Blocks''.
flush-file  WFILEID - WIOR    file-ext:
          See ``General files''.
flush-icache  C-ADDR U -    gforth:
          See ```Code' and `;code'''.
fm/mod  D1 N1 - N2 N3    core:
          See ``Mixed precision''.
fmax  R1 R2 - R3    float:
          See ``Floating Point''.
fmin  R1 R2 - R3    float:
          See ``Floating Point''.
fnegate  R1 - R2    float:
          See ``Floating Point''.
fnip  R1 R2 - R2    gforth:
          See ``Floating point stack''.
FOR  COMPILATION - DO-SYS ; RUN-TIME U - LOOP-SYS     gforth:
          See ``Arbitrary control structures''.
Forth  -     search-ext:
          See ``Word Lists''.
forth-wordlist  - WID     search:
          See ``Word Lists''.
fover  R1 R2 - R1 R2 R1    float:
          See ``Floating point stack''.
fp!  F-ADDR -    gforth:
          See ``Stack pointer manipulation''.
fp0  - A-ADDR     gforth:
          See ``Stack pointer manipulation''.
fp@  - F-ADDR    gforth:
          See ``Stack pointer manipulation''.
fpath  - PATH-ADDR     gforth:
          See ``Source Search Paths''.
fpick  U - R    gforth:
          See ``Floating point stack''.
free  A-ADDR - WIOR    memory:
          See ``Heap allocation''.
frot  R1 R2 R3 - R2 R3 R1    float:
          See ``Floating point stack''.
fround  R1 - R2    float:
          See ``Floating Point''.
fs.  R -     float-ext:
          See ``Simple numeric output''.
fsin  R1 - R2    float-ext:
          See ``Floating Point''.
fsincos  R1 - R2 R3    float-ext:
          See ``Floating Point''.
fsinh  R1 - R2    float-ext:
          See ``Floating Point''.
fsqrt  R1 - R2    float-ext:
          See ``Floating Point''.
fswap  R1 R2 - R2 R1    float:
          See ``Floating point stack''.
ftan  R1 - R2    float-ext:
          See ``Floating Point''.
ftanh  R1 - R2    float-ext:
          See ``Floating Point''.
ftuck  R1 R2 - R2 R1 R2    gforth:
          See ``Floating point stack''.
fvariable  "NAME" -     float:
          See ``Variables''.
f~  R1 R2 R3 - FLAG     float-ext:
          See ``Floating Point''.
f~abs  R1 R2 R3 - FLAG     gforth:
          See ``Floating Point''.
f~rel  R1 R2 R3 - FLAG     gforth:
          See ``Floating Point''.
get-block-fid  - WFILEID     gforth:
          See ``Blocks''.
get-current  - WID     search:
          See ``Word Lists''.
get-order  - WIDN .. WID1 N     search:
          See ``Word Lists''.
getenv  C-ADDR1 U1 - C-ADDR2 U2    gforth:
          See ``Passing Commands to the Operating System''.
gforth  - C-ADDR U     gforth-environment:
          See ``Environmental Queries''.
heap-new  ... CLASS - OBJECT     objects:
          See ```objects.fs' Glossary''.
here  - ADDR     core:
          See ``Dictionary allocation''.
hex  -     core-ext:
          See ``Number Conversion''.
hex.  U -     gforth:
          See ``Simple numeric output''.
hold  CHAR -     core:
          See ``Formatted numeric output''.
how:  -     oof:
          See ``Class Declaration''.
i  - N    core:
          See ``Counted Loops''.
IF  COMPILATION - ORIG ; RUN-TIME F -     core:
          See ``Arbitrary control structures''.
immediate  -     core:
          See ``Interpretation and Compilation Semantics''.
implementation  INTERFACE -     objects:
          See ```objects.fs' Glossary''.
include  ... "FILE" - ...     gforth:
          See ``Forth source files''.
include-file  I*X WFILEID - J*X     file:
          See ``Forth source files''.
included  I*X C-ADDR U - J*X     file:
          See ``Forth source files''.
included?  C-ADDR U - F     gforth:
          See ``Forth source files''.
init  ... -     oof:
          See ``The `oof.fs' base class''.
init-asm  -     gforth:
          See ```Code' and `;code'''.
init-object  ... CLASS OBJECT -     objects:
          See ```objects.fs' Glossary''.
inst-value  ALIGN1 OFFSET1 "NAME" - ALIGN2 OFFSET2     objects:
          See ```objects.fs' Glossary''.
inst-var  ALIGN1 OFFSET1 ALIGN SIZE "NAME" - ALIGN2 OFFSET2     objects:
          See ```objects.fs' Glossary''.
interface  -     objects:
          See ```objects.fs' Glossary''.
interpret/compile:  INTERP-XT COMP-XT "NAME" -     gforth:
          See ``Combined Words''.
interpretation>  COMPILATION. - ORIG COLON-SYS     gforth:
          See ``Combined Words''.
invert  W1 - W2    core:
          See ``Bitwise operations''.
IS  XT "NAME" -     gforth:
          See ``Deferred words''.
is  XT "NAME" -     oof:
          See ``The `oof.fs' base class''.
j  - N    core:
          See ``Counted Loops''.
k  - N    gforth:
          See ``Counted Loops''.
key  - CHAR     core:
          See ``Input''.
key?  - FLAG     facility:
          See ``Input''.
laddr#  - C-ADDR    gforth:
          See ``Locals implementation''.
lastxt  - XT     gforth:
          See ``Anonymous Definitions''.
LEAVE  COMPILATION - ; RUN-TIME LOOP-SYS -     core:
          See ``Arbitrary control structures''.
link  "NAME" - CLASS ADDR     oof:
          See ``The `oof.fs' base class''.
list  U -     block-ext:
          See ``Blocks''.
list-size  LIST - U     gforth-internal:
          See ``Locals implementation''.
Literal  COMPILATION N - ; RUN-TIME - N     core:
          See ``Literals''.
load  I*X N - J*X     block:
          See ``Blocks''.
LOOP  COMPILATION DO-SYS - ; RUN-TIME LOOP-SYS1 - | LOOP-SYS2     core:
          See ``Arbitrary control structures''.
lp!  C-ADDR -    gforth <1>:
          See ``Locals implementation''.
lp!  C-ADDR -    gforth:
          See ``Stack pointer manipulation''.
lp+!#  -    gforth:
          See ``Locals implementation''.
lp0  - A-ADDR     gforth:
          See ``Stack pointer manipulation''.
lp@  - ADDR     gforth:
          See ``Stack pointer manipulation''.
lshift  U1 N - U2    core:
          See ``Bitwise operations''.
m*  N1 N2 - D    core:
          See ``Mixed precision''.
m*/  D1 N2 U3 - DQUOT     double:
          See ``Mixed precision''.
m+  D1 N - D2    double:
          See ``Mixed precision''.
m:  - XT COLON-SYS; RUN-TIME: OBJECT -     objects:
          See ```objects.fs' Glossary''.
marker  "<SPACES> NAME" -     core-ext:
          See ``Forgetting words''.
max  N1 N2 - N    core:
          See ``Single precision''.
maxalign  -     gforth:
          See ``Dictionary allocation''.
maxaligned  ADDR1 - ADDR2     gforth:
          See ``Address arithmetic''.
method  -     oof:
          See ``Class Declaration''.
method  M V "NAME" - M' V     mini-oof:
          See ``Basic `mini-oof.fs' Usage''.
method  XT "NAME" -     objects:
          See ```objects.fs' Glossary''.
methods  CLASS -     objects:
          See ```objects.fs' Glossary''.
min  N1 N2 - N    core:
          See ``Single precision''.
mod  N1 N2 - N    core:
          See ``Single precision''.
move  C-FROM C-TO UCOUNT -    core:
          See ``Memory Blocks''.
ms  N -    facility-ext:
          See ``Keeping track of Time''.
naligned  ADDR1 N - ADDR2     gforth:
          See ``Structure Glossary''.
name  - C-ADDR COUNT     gforth:
          See ``Input''.
name>comp  NT - W XT     gforth:
          See ``Name token''.
name>int  NT - XT     gforth:
          See ``Name token''.
name>string  NT - ADDR COUNT     gforth:
          See ``Name token''.
name?int  NT - XT     gforth:
          See ``Name token''.
needs  ... "NAME" - ...     gforth:
          See ``Forth source files''.
negate  N1 - N2    core:
          See ``Single precision''.
new  - O     oof:
          See ``The `oof.fs' base class''.
new  CLASS - O     mini-oof:
          See ``Basic `mini-oof.fs' Usage''.
new[]  N - O     oof:
          See ``The `oof.fs' base class''.
NEXT  COMPILATION DO-SYS - ; RUN-TIME LOOP-SYS1 - | LOOP-SYS2     gforth:
          See ``Arbitrary control structures''.
nextname  C-ADDR U -     gforth:
          See ``Supplying the name of a defined word''.
nip  W1 W2 - W2    core-ext:
          See ``Data stack''.
noname  -     gforth:
          See ``Anonymous Definitions''.
object  - A-ADDR     mini-oof:
          See ``Basic `mini-oof.fs' Usage''.
object  - CLASS     objects:
          See ```objects.fs' Glossary''.
of  COMPILATION  - OF-SYS ; RUN-TIME X1 X2 - |X1     core-ext:
          See ``Arbitrary control structures''.
off  A-ADDR -     gforth:
          See ``Boolean Flags''.
on  A-ADDR -     gforth:
          See ``Boolean Flags''.
Only  -     search-ext:
          See ``Word Lists''.
open-blocks  C-ADDR U -     gforth:
          See ``Blocks''.
open-file  C-ADDR U WFAM - WFILEID WIOR    file:
          See ``General files''.
open-path-file  ADDR1 U1 PATH-ADDR - WFILEID ADDR2 U2 0 | IOR     gforth:
          See ``General Search Paths''.
or  W1 W2 - W    core:
          See ``Bitwise operations''.
order  -     search-ext:
          See ``Word Lists''.
os-class  - C-ADDR U     gforth-environment:
          See ``Environmental Queries''.
over  W1 W2 - W1 W2 W1    core:
          See ``Data stack''.
overrides  XT "SELECTOR" -     objects:
          See ```objects.fs' Glossary''.
pad  - C-ADDR     core-ext:
          See ``Input''.
page  -     facility:
          See ``Displaying characters and strings''.
parse  CHAR "CCC<CHAR>" - C-ADDR U     core-ext:
          See ``Input''.
path+  PATH-ADDR  "DIR" -     gforth:
          See ``General Search Paths''.
path-allot  UMAX -     unknown:
          See ``General Search Paths''.
path=  PATH-ADDR "DIR1|DIR2|DIR3"     gforth:
          See ``General Search Paths''.
perform  A-ADDR -    gforth:
          See ``Execution token''.
pi  - R     gforth:
          See ``Floating Point''.
pick  U - W    core-ext:
          See ``Data stack''.
POSTPONE  "NAME" -     core:
          See ``Macros''.
postpone  "NAME" -     oof:
          See ``The `oof.fs' base class''.
postpone,  W XT -     gforth:
          See ``Compilation token''.
precision  - U     float-ext:
          See ``Floating Point''.
previous  -     search-ext:
          See ``Word Lists''.
print  OBJECT -     objects:
          See ```objects.fs' Glossary''.
printdebugdata  -     gforth:
          See ``Debugging''.
printdebugline  ADDR -     gforth:
          See ``Debugging''.
protected  -     objects:
          See ```objects.fs' Glossary''.
ptr  "NAME" -     oof:
          See ``The `oof.fs' base class''.
ptr  -     oof:
          See ``Class Declaration''.
public  -     objects:
          See ```objects.fs' Glossary''.
query  -     core-ext:
          See ``Input''.
quit  ?? - ??     core:
          See ``Miscellaneous Words''.
r/o  - FAM     file:
          See ``General files''.
r/w  - FAM     file:
          See ``General files''.
r>  - W    core:
          See ``Return stack''.
r@  - W ; R: W - W     core:
          See ``Return stack''.
rdrop  -    gforth:
          See ``Return stack''.
read-file  C-ADDR U1 WFILEID - U2 WIOR    file:
          See ``General files''.
read-line  C-ADDR U1 WFILEID - U2 FLAG WIOR    file:
          See ``General files''.
recover  COMPILATION  ORIG1 - ORIG2 ; RUN-TIME  -     gforth:
          See ``Exception Handling''.
recurse  COMPILATION - ; RUN-TIME ?? - ??     core:
          See ``Calls and returns''.
recursive  COMPILATION - ; RUN-TIME -     gforth:
          See ``Calls and returns''.
refill  - FLAG     core-ext,block-ext,file-ext:
          See ``Input''.
rename-file  C-ADDR1 U1 C-ADDR2 U2 - WIOR    file-ext:
          See ``General files''.
REPEAT  COMPILATION ORIG DEST - ; RUN-TIME -     core:
          See ``Arbitrary control structures''.
reposition-file  UD WFILEID - WIOR    file:
          See ``General files''.
represent  R C-ADDR U - N F1 F2    float:
          See ``Formatted numeric output''.
require  ... "FILE" - ...     gforth:
          See ``Forth source files''.
required  I*X ADDR U - J*X     gforth:
          See ``Forth source files''.
resize  A-ADDR1 U - A-ADDR2 WIOR    memory:
          See ``Heap allocation''.
resize-file  UD WFILEID - WIOR    file:
          See ``General files''.
restore-input  XN .. X1 N - FLAG     core-ext:
          See ``Input Sources''.
restrict  -     gforth:
          See ``Interpretation and Compilation Semantics''.
roll  X0 X1 .. XN N - X1 .. XN X0     core-ext:
          See ``Data stack''.
Root  -     gforth:
          See ``Word Lists''.
rot  W1 W2 W3 - W2 W3 W1    core:
          See ``Data stack''.
rp!  A-ADDR -    gforth:
          See ``Stack pointer manipulation''.
rp0  - A-ADDR     gforth:
          See ``Stack pointer manipulation''.
rp@  - A-ADDR    gforth:
          See ``Stack pointer manipulation''.
rshift  U1 N - U2    core:
          See ``Bitwise operations''.
S"  COMPILATION 'CCC"' - ; RUN-TIME - C-ADDR U     core,file:
          See ``Displaying characters and strings''.
s>d  N - D     core:
          See ``Double precision''.
save-buffer  BUFFER -     gforth:
          See ``Blocks''.
save-buffers  -     block:
          See ``Blocks''.
save-input  - XN .. X1 N     core-ext:
          See ``Input Sources''.
savesystem  "NAME" -     gforth:
          See ``Non-Relocatable Image Files''.
scope  COMPILATION  - SCOPE ; RUN-TIME  -     gforth:
          See ``Where are locals visible by name?''.
scr  - A-ADDR     block-ext:
          See ``Blocks''.
seal  -     gforth:
          See ``Word Lists''.
search  C-ADDR1 U1 C-ADDR2 U2 - C-ADDR3 U3 FLAG     string:
          See ``Memory Blocks''.
search-wordlist  C-ADDR COUNT WID - 0 | XT +-1     search:
          See ``Word Lists''.
see  "<SPACES>NAME" -     tools:
          See ``Examining data and code''.
selector  "NAME" -     objects:
          See ```objects.fs' Glossary''.
self  - O     oof:
          See ``The `oof.fs' base class''.
set-current  WID -     search:
          See ``Word Lists''.
set-order  WIDN .. WID1 N -     search:
          See ``Word Lists''.
set-precision  U -     float-ext:
          See ``Floating Point''.
sf!  R SF-ADDR -    float-ext:
          See ``Memory Access''.
sf@  SF-ADDR - R    float-ext:
          See ``Memory Access''.
sfalign  -     float-ext:
          See ``Dictionary allocation''.
sfaligned  C-ADDR - SF-ADDR    float-ext:
          See ``Address arithmetic''.
sfloat%  - ALIGN SIZE     gforth:
          See ``Structure Glossary''.
sfloat+  SF-ADDR1 - SF-ADDR2     float-ext:
          See ``Address arithmetic''.
sfloats  N1 - N2    float-ext:
          See ``Address arithmetic''.
sh  "..." -     gforth:
          See ``Passing Commands to the Operating System''.
sign  N -     core:
          See ``Formatted numeric output''.
SLiteral  COMPILATION C-ADDR1 U ; RUN-TIME - C-ADDR2 U     string:
          See ``Literals''.
sm/rem  D1 N1 - N2 N3    core:
          See ``Mixed precision''.
source  - C-ADDR U     core:
          See ``The Text Interpreter''.
source-id  - 0 | -1 | FILEID     core-ext,file:
          See ``Input Sources''.
sourcefilename  - C-ADDR U     gforth:
          See ``Forth source files''.
sourceline#  - U     gforth:
          See ``Forth source files''.
sp!  A-ADDR -    gforth:
          See ``Stack pointer manipulation''.
sp0  - A-ADDR     gforth:
          See ``Stack pointer manipulation''.
sp@  - A-ADDR    gforth:
          See ``Stack pointer manipulation''.
space  -     core:
          See ``Displaying characters and strings''.
spaces  U -     core:
          See ``Displaying characters and strings''.
span  - C-ADDR     core-ext:
          See ``Input''.
state  - A-ADDR     core,tools-ext:
          See ``Interpret/Compile states''.
static  -     oof:
          See ``Class Declaration''.
struct  - ALIGN SIZE     gforth:
          See ``Structure Glossary''.
sub-list?  LIST1 LIST2 - F     gforth-internal:
          See ``Locals implementation''.
super  "NAME" -     oof:
          See ``The `oof.fs' base class''.
swap  W1 W2 - W2 W1    core:
          See ``Data stack''.
sword  CHAR - ADDR LEN     gforth:
          See ``Input''.
system  C-ADDR U -     gforth:
          See ``Passing Commands to the Operating System''.
table  - WID     gforth:
          See ``Word Lists''.
THEN  COMPILATION ORIG - ; RUN-TIME -     core:
          See ``Arbitrary control structures''.
this  - OBJECT     objects:
          See ```objects.fs' Glossary''.
threading-method  - N    gforth:
          See ``Threading Words''.
throw  Y1 .. YM NERROR - Y1 .. YM / Z1 .. ZN ERROR     exception:
          See ``Exception Handling''.
thru  I*X N1 N2 - J*X     block-ext:
          See ``Blocks''.
tib  - C-ADDR     core-ext:
          See ``The Text Interpreter''.
time&date  - NSEC NMIN NHOUR NDAY NMONTH NYEAR    facility-ext:
          See ``Keeping track of Time''.
TO  W "NAME" -     core-ext:
          See ``Values''.
to-this  OBJECT -     objects:
          See ```objects.fs' Glossary''.
toupper  C1 - C2    gforth:
          See ``Displaying characters and strings''.
true  - F     core-ext:
          See ``Boolean Flags''.
try  COMPILATION  - ORIG ; RUN-TIME  -     gforth:
          See ``Exception Handling''.
tuck  W1 W2 - W2 W1 W2    core-ext:
          See ``Data stack''.
type  C-ADDR U -     core:
          See ``Displaying characters and strings''.
typewhite  ADDR U -     gforth:
          See ``Displaying characters and strings''.
U+DO  COMPILATION - DO-SYS ; RUN-TIME U1 U2 - | LOOP-SYS     gforth:
          See ``Arbitrary control structures''.
U-DO  COMPILATION - DO-SYS ; RUN-TIME U1 U2 - | LOOP-SYS     gforth:
          See ``Arbitrary control structures''.
u.  U -     core:
          See ``Simple numeric output''.
u.r  U N -     core-ext:
          See ``Simple numeric output''.
u<  U1 U2 - F    core:
          See ``Numeric comparison''.
u<=  U1 U2 - F    gforth:
          See ``Numeric comparison''.
u>  U1 U2 - F    core-ext:
          See ``Numeric comparison''.
u>=  U1 U2 - F    gforth:
          See ``Numeric comparison''.
ud.  UD -     gforth:
          See ``Simple numeric output''.
ud.r  UD N -     gforth:
          See ``Simple numeric output''.
um*  U1 U2 - UD    core:
          See ``Mixed precision''.
um/mod  UD U1 - U2 U3    core:
          See ``Mixed precision''.
unloop  -    core:
          See ``Arbitrary control structures''.
UNREACHABLE  -     gforth:
          See ``Where are locals visible by name?''.
UNTIL  COMPILATION DEST - ; RUN-TIME F -     core:
          See ``Arbitrary control structures''.
unused  - U     core-ext:
          See ``Dictionary allocation''.
update  -     block:
          See ``Blocks''.
updated?  N - F     gforth:
          See ``Blocks''.
use  "FILE" -     gforth:
          See ``Blocks''.
User  "NAME" -     gforth:
          See ``Variables''.
utime  - DTIME    gforth:
          See ``Keeping track of Time''.
Value  W "NAME" -     core-ext:
          See ``Values''.
var  M V SIZE "NAME" - M V'     mini-oof:
          See ``Basic `mini-oof.fs' Usage''.
var  SIZE -     oof:
          See ``Class Declaration''.
Variable  "NAME" -     core:
          See ``Variables''.
vlist  -     gforth:
          See ``Word Lists''.
Vocabulary  "NAME" -     gforth:
          See ``Word Lists''.
vocs  -     gforth:
          See ``Word Lists''.
w/o  - FAM     file:
          See ``General files''.
What's  INTERPRETATION "NAME" - XT; COMPILATION "NAME" - ; RUN-TIME - XT     gforth:
          See ``Deferred words''.
WHILE  COMPILATION DEST - ORIG DEST ; RUN-TIME F -     core:
          See ``Arbitrary control structures''.
with  O -     oof:
          See ``The `oof.fs' base class''.
within  U1 U2 U3 - F    core-ext:
          See ``Numeric comparison''.
word  CHAR "<CHARS>CCC<CHAR>- C-ADDR     core:
          See ``Input''.
wordlist  - WID     search:
          See ``Word Lists''.
words  -     tools:
          See ``Word Lists''.
write-file  C-ADDR U1 WFILEID - WIOR    file:
          See ``General files''.
write-line  C-ADDR U FILEID - IOR     file:
          See ``General files''.
xor  W1 W2 - W    core:
          See ``Bitwise operations''.
xt-new  ... CLASS XT - OBJECT     objects:
          See ```objects.fs' Glossary''.
xt-see  XT -     gforth:
          See ``Examining data and code''.
~~  COMPILATION  - ; RUN-TIME  -     gforth:
          See ``Debugging''.
Concept and Word Index
**********************

   Not all entries listed in this index are present verbatim in the
text. This index also duplicates, in abbreviated form, all of the words
listed in the Word Index (only the names are listed for the words here).

!:
          See ``Memory Access''.
", stack item type:
          See ``Notation''.
#:
          See ``Formatted numeric output''.
#!:
          See ``Running Image Files''.
#>:
          See ``Formatted numeric output''.
#>>:
          See ``Formatted numeric output''.
#s:
          See ``Formatted numeric output''.
#tib:
          See ``The Text Interpreter''.
$-prefix for hexadecimal numbers:
          See ``Number Conversion''.
$?:
          See ``Passing Commands to the Operating System''.
%-prefix for binary numbers:
          See ``Number Conversion''.
%align:
          See ``Structure Glossary''.
%alignment:
          See ``Structure Glossary''.
%alloc:
          See ``Structure Glossary''.
%allocate:
          See ``Structure Glossary''.
%allot:
          See ``Structure Glossary''.
%size:
          See ``Structure Glossary''.
&-prefix for decimal numbers:
          See ``Number Conversion''.
' <1>:
          See ``The `oof.fs' base class''.
':
          See ``Execution token''.
'-prefix for character strings:
          See ``Number Conversion''.
'cold:
          See ``Modifying the Startup Sequence''.
(:
          See ``Comments''.
(local):
          See ``ANS Forth locals''.
):
          See ``Assertions''.
*:
          See ``Single precision''.
*/:
          See ``Mixed precision''.
*/mod:
          See ``Mixed precision''.
+:
          See ``Single precision''.
+!:
          See ``Memory Access''.
+DO:
          See ``Arbitrary control structures''.
+load:
          See ``Blocks''.
+LOOP:
          See ``Arbitrary control structures''.
+thru:
          See ``Blocks''.
,:
          See ``Dictionary allocation''.
-:
          See ``Single precision''.
-, tutorial:
          See ``Stack-Effect Comments''.
-->:
          See ``Blocks''.
-appl-image, command-line option:
          See ``Invoking Gforth''.
-application, gforthmi option:
          See ```gforthmi'''.
-clear-dictionary, command-line option:
          See ``Invoking Gforth''.
-d, command-line option:
          See ``Invoking Gforth''.
-data-stack-size, command-line option:
          See ``Invoking Gforth''.
-DDIRECT_THREADED:
          See ``Direct or Indirect Threaded?''.
-debug, command-line option:
          See ``Invoking Gforth''.
-DFORCE_REG:
          See ``Portability''.
-dictionary-size, command-line option:
          See ``Invoking Gforth''.
-die-on-signal, command-line-option:
          See ``Invoking Gforth''.
-DO:
          See ``Arbitrary control structures''.
-DUSE_FTOS:
          See ``TOS Optimization''.
-DUSE_NO_FTOS:
          See ``TOS Optimization''.
-DUSE_NO_TOS:
          See ``TOS Optimization''.
-DUSE_TOS:
          See ``TOS Optimization''.
-enable-direct-threaded, configuration flag:
          See ``Direct or Indirect Threaded?''.
-enable-force-reg, configuration flag:
          See ``Portability''.
-enable-indirect-threaded, configuration flag:
          See ``Direct or Indirect Threaded?''.
-f, command-line option:
          See ``Invoking Gforth''.
-fp-stack-size, command-line option:
          See ``Invoking Gforth''.
-h, command-line option:
          See ``Invoking Gforth''.
-help, command-line option:
          See ``Invoking Gforth''.
-i, command-line option:
          See ``Invoking Gforth''.
-i, invoke image file:
          See ``Running Image Files''.
-image file, invoke image file:
          See ``Running Image Files''.
-image-file, command-line option:
          See ``Invoking Gforth''.
-l, command-line option:
          See ``Invoking Gforth''.
-locals-stack-size, command-line option:
          See ``Invoking Gforth''.
-LOOP:
          See ``Arbitrary control structures''.
-m, command-line option:
          See ``Invoking Gforth''.
-no-offset-im, command-line option:
          See ``Invoking Gforth''.
-offset-image, command-line option:
          See ``Invoking Gforth''.
-p, command-line option:
          See ``Invoking Gforth''.
-path, command-line option:
          See ``Invoking Gforth''.
-r, command-line option:
          See ``Invoking Gforth''.
-return-stack-size, command-line option:
          See ``Invoking Gforth''.
-rot:
          See ``Data stack''.
-trailing:
          See ``Memory Blocks''.
-v, command-line option:
          See ``Invoking Gforth''.
-version, command-line option:
          See ``Invoking Gforth''.
.:
          See ``Simple numeric output''.
.":
          See ``Displaying characters and strings''.
.", how it works:
          See ``How does that work?''.
.(:
          See ``Displaying characters and strings''.
.emacs:
          See ``Emacs and Gforth''.
.fi files:
          See ``Image Files''.
.gforth-history:
          See ``Command-line editing''.
.path:
          See ``General Search Paths''.
.r:
          See ``Simple numeric output''.
.s:
          See ``Examining data and code''.
/:
          See ``Single precision''.
/does-handler:
          See ``Threading Words''.
/mod:
          See ``Single precision''.
/string:
          See ``Memory Blocks''.
0<:
          See ``Numeric comparison''.
0<=:
          See ``Numeric comparison''.
0<>:
          See ``Numeric comparison''.
0=:
          See ``Numeric comparison''.
0>:
          See ``Numeric comparison''.
0>=:
          See ``Numeric comparison''.
1+:
          See ``Single precision''.
1-:
          See ``Single precision''.
1/f:
          See ``Floating Point''.
2!:
          See ``Memory Access''.
2*:
          See ``Bitwise operations''.
2,:
          See ``Dictionary allocation''.
2/:
          See ``Bitwise operations''.
2>r:
          See ``Return stack''.
2@:
          See ``Memory Access''.
2Constant:
          See ``Constants''.
2drop:
          See ``Data stack''.
2dup:
          See ``Data stack''.
2Literal:
          See ``Literals''.
2nip:
          See ``Data stack''.
2over:
          See ``Data stack''.
2r>:
          See ``Return stack''.
2r@:
          See ``Return stack''.
2rdrop:
          See ``Return stack''.
2rot:
          See ``Data stack''.
2swap:
          See ``Data stack''.
2tuck:
          See ``Data stack''.
2Variable:
          See ``Variables''.
: <1>:
          See ``The `oof.fs' base class''.
::
          See ``Colon Definitions''.
:, passing data across:
          See ``Literals''.
:: <1>:
          See ``Basic `mini-oof.fs' Usage''.
:::
          See ``The `oof.fs' base class''.
:m:
          See ```objects.fs' Glossary''.
:noname:
          See ``Anonymous Definitions''.
;:
          See ``Colon Definitions''.
;code:
          See ```Code' and `;code'''.
;CODE ending sequence:
          See ``Implementation Defined Options''.
;CODE, name not defined via CREATE:
          See ``Ambiguous conditions''.
;CODE, processing input:
          See ``Implementation Defined Options''.
;m:
          See ```objects.fs' Glossary''.
;m usage:
          See ``Method conveniences''.
;s:
          See ``Calls and returns''.
<:
          See ``Numeric comparison''.
<#:
          See ``Formatted numeric output''.
<<#:
          See ``Formatted numeric output''.
<=:
          See ``Numeric comparison''.
<>:
          See ``Numeric comparison''.
<bind>:
          See ```objects.fs' Glossary''.
<compilation:
          See ``Combined Words''.
<interpretation:
          See ``Combined Words''.
<IS>:
          See ``Deferred words''.
<to-inst>:
          See ```objects.fs' Glossary''.
=:
          See ``Numeric comparison''.
>:
          See ``Numeric comparison''.
>=:
          See ``Numeric comparison''.
>body:
          See ``The gory details of `CREATE..DOES>'''.
>BODY of non-CREATEd words:
          See ``Ambiguous conditions''.
>code-address:
          See ``Threading Words''.
>does-code:
          See ``Threading Words''.
>float:
          See ``Input''.
>in:
          See ``The Text Interpreter''.
>IN greater than input buffer:
          See ``Ambiguous conditions''.
>l:
          See ``Locals implementation''.
>number:
          See ``Input''.
>order:
          See ``Word Lists''.
>r:
          See ``Return stack''.
?:
          See ``Examining data and code''.
?DO:
          See ``Arbitrary control structures''.
?dup:
          See ``Data stack''.
?DUP-0=-IF:
          See ``Arbitrary control structures''.
?DUP-IF:
          See ``Arbitrary control structures''.
?LEAVE:
          See ``Arbitrary control structures''.
@:
          See ``Memory Access''.
@local#:
          See ``Locals implementation''.
[:
          See ``Literals''.
[']:
          See ``Execution token''.
[+LOOP]:
          See ``Interpreter Directives''.
[?DO]:
          See ``Interpreter Directives''.
[]:
          See ``The `oof.fs' base class''.
[AGAIN]:
          See ``Interpreter Directives''.
[BEGIN]:
          See ``Interpreter Directives''.
[bind]:
          See ```objects.fs' Glossary''.
[bind] usage:
          See ``Class Binding''.
[char]:
          See ``Displaying characters and strings''.
[COMP']:
          See ``Compilation token''.
[compile]:
          See ``Macros''.
[current]:
          See ```objects.fs' Glossary''.
[DO]:
          See ``Interpreter Directives''.
[ELSE]:
          See ``Interpreter Directives''.
[ENDIF]:
          See ``Interpreter Directives''.
[FOR]:
          See ``Interpreter Directives''.
[IF]:
          See ``Interpreter Directives''.
[IF] and POSTPONE:
          See ``Ambiguous conditions''.
[IF], end of the input source before matching [ELSE] or [THEN]:
          See ``Ambiguous conditions''.
[IFDEF]:
          See ``Interpreter Directives''.
[IFUNDEF]:
          See ``Interpreter Directives''.
[IS]:
          See ``Deferred words''.
[LOOP]:
          See ``Interpreter Directives''.
[NEXT]:
          See ``Interpreter Directives''.
[parent]:
          See ```objects.fs' Glossary''.
[parent] usage:
          See ``Class Binding''.
[REPEAT]:
          See ``Interpreter Directives''.
[THEN]:
          See ``Interpreter Directives''.
[to-inst]:
          See ```objects.fs' Glossary''.
[UNTIL]:
          See ``Interpreter Directives''.
[WHILE]:
          See ``Interpreter Directives''.
\:
          See ``Comments''.
\, editing with Emacs:
          See ``Emacs and Gforth''.
\, line length in blocks:
          See ``Implementation Defined Options''.
\G:
          See ``Comments''.
]:
          See ``Literals''.
]L:
          See ``Literals''.
a_, stack item type:
          See ``Notation''.
abort:
          See ``Exception Handling''.
abort":
          See ``Exception Handling''.
ABORT", exception abort sequence:
          See ``Implementation Defined Options''.
abs:
          See ``Single precision''.
abstract class <1>:
          See ``Basic `oof.fs' Usage''.
abstract class:
          See ``Basic `objects.fs' Usage''.
accept:
          See ``Input''.
ACCEPT, display after end of input:
          See ``Implementation Defined Options''.
ACCEPT, editing:
          See ``Implementation Defined Options''.
address alignment exception:
          See ``Ambiguous conditions''.
address alignment exception, stack overflow:
          See ``Ambiguous conditions''.
address arithmetic for structures:
          See ``Why explicit structure support?''.
address arithmetic restrictions, ANS vs. Gforth:
          See ``ANS Forth and Gforth memory models''.
address arithmetic words:
          See ``Address arithmetic''.
address of counted string:
          See ``String Formats''.
address unit:
          See ``Address arithmetic''.
address unit, size in bits:
          See ``Implementation Defined Options''.
ADDRESS-UNIT-BITS:
          See ``Address arithmetic''.
AGAIN:
          See ``Arbitrary control structures''.
AHEAD:
          See ``Arbitrary control structures''.
Alias:
          See ``Aliases''.
aliases:
          See ``Aliases''.
align:
          See ``Dictionary allocation''.
aligned:
          See ``Address arithmetic''.
aligned addresses:
          See ``Implementation Defined Options''.
alignment faults:
          See ``Ambiguous conditions''.
alignment of addresses for types:
          See ``Address arithmetic''.
alignment tutorial:
          See ``Alignment''.
allocate:
          See ``Heap allocation''.
allot:
          See ``Dictionary allocation''.
also:
          See ``Word Lists''.
also, too many word lists in search order:
          See ``Ambiguous conditions''.
also-path:
          See ``General Search Paths''.
ambiguous conditions, block words:
          See ``Ambiguous conditions''.
ambiguous conditions, core words:
          See ``Ambiguous conditions''.
ambiguous conditions, double words:
          See ``Ambiguous conditions''.
ambiguous conditions, facility words:
          See ``Ambiguous conditions''.
ambiguous conditions, file words:
          See ``Ambiguous conditions''.
ambiguous conditions, floating-point words:
          See ``Ambiguous conditions''.
ambiguous conditions, locals words:
          See ``Ambiguous conditions''.
ambiguous conditions, programming-tools words:
          See ``Ambiguous conditions''.
ambiguous conditions, search-order words:
          See ``Ambiguous conditions''.
and:
          See ``Bitwise operations''.
angles in trigonometric operations:
          See ``Floating Point''.
ANS conformance of Gforth:
          See ``ANS conformance''.
ans-report.fs:
          See ```ans-report.fs': Report the words used, sorted by wordset''.
arg:
          See ``Modifying the Startup Sequence''.
argc:
          See ``Modifying the Startup Sequence''.
argument input source different than current input source for RESTORE-INPUT:
          See ``Ambiguous conditions''.
argument type mismatch:
          See ``Ambiguous conditions''.
argument type mismatch, RESTORE-INPUT:
          See ``Ambiguous conditions''.
arguments on the command line, access:
          See ``Modifying the Startup Sequence''.
argv:
          See ``Modifying the Startup Sequence''.
arithmetic words:
          See ``Arithmetic''.
arithmetics tutorial:
          See ``Arithmetics''.
arrays:
          See ```CREATE'''.
arrays tutorial:
          See ``Arrays and Records''.
asptr <1>:
          See ``Class Declaration''.
asptr:
          See ``The `oof.fs' base class''.
assembler <1>:
          See ```Code' and `;code'''.
assembler:
          See ``Assembler and Code Words''.
ASSEMBLER, search order capability:
          See ``Implementation Defined Options''.
assert(:
          See ``Assertions''.
assert-level:
          See ``Assertions''.
assert0(:
          See ``Assertions''.
assert1(:
          See ``Assertions''.
assert2(:
          See ``Assertions''.
assert3(:
          See ``Assertions''.
assertions:
          See ``Assertions''.
ASSUME-LIVE:
          See ``Where are locals visible by name?''.
at-xy:
          See ``Displaying characters and strings''.
AT-XY can't be performed on user output device:
          See ``Ambiguous conditions''.
Attempt to use zero-length string as a name:
          See ``Ambiguous conditions''.
au (address unit):
          See ``Address arithmetic''.
authors of Gforth:
          See ``Authors and Ancestors of Gforth''.
backtrace:
          See ``Error messages''.
backtraces with gforth-fast:
          See ``Error messages''.
base:
          See ``Number Conversion''.
base is not decimal (REPRESENT, F., FE., FS.):
          See ``Ambiguous conditions''.
basic objects usage:
          See ``Basic `objects.fs' Usage''.
batch processing with Gforth:
          See ``Invoking Gforth''.
BEGIN:
          See ``Arbitrary control structures''.
benchmarking Forth systems:
          See ``Performance''.
Benchres:
          See ``Performance''.
bin:
          See ``General files''.
bind <1>:
          See ``The `oof.fs' base class''.
bind:
          See ```objects.fs' Glossary''.
bind usage:
          See ``Class Binding''.
bind':
          See ```objects.fs' Glossary''.
bitwise operation words:
          See ``Bitwise operations''.
bl:
          See ``Displaying characters and strings''.
blank:
          See ``Memory Blocks''.
blk:
          See ``Input Sources''.
BLK, altering BLK:
          See ``Ambiguous conditions''.
block:
          See ``Blocks''.
block buffers:
          See ``Blocks''.
block number invalid:
          See ``Ambiguous conditions''.
block read not possible:
          See ``Ambiguous conditions''.
block transfer, I/O exception:
          See ``Ambiguous conditions''.
block words, ambiguous conditions:
          See ``Ambiguous conditions''.
block words, implementation-defined options:
          See ``Implementation Defined Options''.
block words, other system documentation:
          See ``Other system documentation''.
block words, system documentation:
          See ``The optional Block word set''.
block-included:
          See ``Blocks''.
block-offset:
          See ``Blocks''.
block-position:
          See ``Blocks''.
blocks:
          See ``Blocks''.
blocks file:
          See ``Blocks''.
blocks in files:
          See ``Implementation Defined Options''.
blocks.fb:
          See ``Blocks''.
Boolean flags:
          See ``Boolean Flags''.
bound:
          See ``The `oof.fs' base class''.
bounds:
          See ``Memory Blocks''.
break":
          See ``Singlestep Debugger''.
break::
          See ``Singlestep Debugger''.
buffer:
          See ``Blocks''.
bug reporting:
          See ``Bugs''.
bye:
          See ``Leaving Gforth''.
bye during gforthmi:
          See ```gforthmi'''.
c!:
          See ``Memory Access''.
C":
          See ``Displaying characters and strings''.
c,:
          See ``Dictionary allocation''.
c, stack item type:
          See ``Notation''.
C, using C for the engine:
          See ``Portability''.
c@:
          See ``Memory Access''.
c_, stack item type:
          See ``Notation''.
calling a definition:
          See ``Calls and returns''.
case:
          See ``Arbitrary control structures''.
CASE control structure:
          See ``Selection''.
case sensitivity:
          See ``Case insensitivity''.
case-sensitivity characteristics:
          See ``Implementation Defined Options''.
case-sensitivity for name lookup:
          See ``Implementation Defined Options''.
catch:
          See ``Exception Handling''.
catch and backtraces:
          See ``Error messages''.
catch and this:
          See ```objects.fs' Implementation''.
catch in m: ... ;m:
          See ``Method conveniences''.
cell:
          See ``Address arithmetic''.
cell size:
          See ``Implementation Defined Options''.
cell%:
          See ``Structure Glossary''.
cell+:
          See ``Address arithmetic''.
cell-aligned addresses:
          See ``Implementation Defined Options''.
cells:
          See ``Address arithmetic''.
CFA:
          See ``Execution token''.
cfalign:
          See ``Dictionary allocation''.
cfaligned:
          See ``Address arithmetic''.
changing the compilation word list (during compilation):
          See ``Ambiguous conditions''.
char:
          See ``Displaying characters and strings''.
char size:
          See ``Implementation Defined Options''.
char%:
          See ``Structure Glossary''.
char+:
          See ``Address arithmetic''.
character editing of ACCEPT and EXPECT:
          See ``Implementation Defined Options''.
character set:
          See ``Implementation Defined Options''.
character strings - compiling and displaying:
          See ``Displaying characters and strings''.
character strings - formats:
          See ``String Formats''.
character strings - moving and copying:
          See ``Memory Blocks''.
character-aligned address requirements:
          See ``Implementation Defined Options''.
character-set extensions and matching of names:
          See ``Implementation Defined Options''.
characters - compiling and displaying:
          See ``Displaying characters and strings''.
characters tutorial:
          See ``Characters and Strings''.
chars:
          See ``Address arithmetic''.
child class:
          See ``Object-Oriented Terminology''.
child words:
          See ``User-defined Defining Words''.
class <1>:
          See ``Basic `mini-oof.fs' Usage''.
class <2>:
          See ``The `oof.fs' base class''.
class <3>:
          See ```objects.fs' Glossary''.
class:
          See ``Object-Oriented Terminology''.
class binding:
          See ``Class Binding''.
class binding as optimization:
          See ``Class Binding''.
class binding, alternative to:
          See ``Class Binding''.
class binding, implementation:
          See ```objects.fs' Implementation''.
class declaration:
          See ``Class Declaration''.
class definition, restrictions <1>:
          See ``Basic `oof.fs' Usage''.
class definition, restrictions:
          See ``Basic `objects.fs' Usage''.
class implementation:
          See ``Class Implementation''.
class implementation and representation:
          See ```objects.fs' Implementation''.
class scoping implementation:
          See ```objects.fs' Implementation''.
class usage <1>:
          See ``Basic `oof.fs' Usage''.
class usage:
          See ``Basic `objects.fs' Usage''.
class->map:
          See ```objects.fs' Glossary''.
class-inst-size:
          See ```objects.fs' Glossary''.
class-inst-size discussion:
          See ``Creating objects''.
class-override!:
          See ```objects.fs' Glossary''.
class-previous:
          See ```objects.fs' Glossary''.
class;:
          See ``Class Declaration''.
class; usage:
          See ``Basic `oof.fs' Usage''.
class>order:
          See ```objects.fs' Glossary''.
class?:
          See ``The `oof.fs' base class''.
classes and scoping:
          See ``Classes and Scoping''.
clear-path:
          See ``General Search Paths''.
clearstack:
          See ``Examining data and code''.
clock tick duration:
          See ``Implementation Defined Options''.
close-file:
          See ``General files''.
cmove:
          See ``Memory Blocks''.
cmove>:
          See ``Memory Blocks''.
code:
          See ```Code' and `;code'''.
code address:
          See ``Threading Words''.
CODE ending sequence:
          See ``Implementation Defined Options''.
code examination:
          See ``Examining data and code''.
code field address <1>:
          See ``Threading Words''.
code field address:
          See ``Execution token''.
code words:
          See ``Assembler and Code Words''.
code words, portable:
          See ```Code' and `;code'''.
CODE, processing input:
          See ``Implementation Defined Options''.
code-address!:
          See ``Threading Words''.
colon definitions <1>:
          See ``Anonymous Definitions''.
colon definitions:
          See ``Colon Definitions''.
colon definitions, tutorial:
          See ``Colon Definitions''.
colon-sys, passing data across ::
          See ``Literals''.
combined words:
          See ``Combined Words''.
command-line arguments, access:
          See ``Modifying the Startup Sequence''.
command-line editing:
          See ``Command-line editing''.
command-line options:
          See ``Invoking Gforth''.
comment editing commands:
          See ``Emacs and Gforth''.
comments:
          See ``Comments''.
comments tutorial:
          See ``Comments''.
common-list:
          See ``Locals implementation''.
COMP':
          See ``Compilation token''.
comp-i.fs:
          See ```gforthmi'''.
comp.lang.forth:
          See ``Other Forth-related information''.
compare:
          See ``Memory Blocks''.
comparison of object models:
          See ``Comparison with other object models''.
comparison tutorial:
          See ``Flags and Comparisons''.
compilation semantics <1>:
          See ``Interpretation and Compilation Semantics''.
compilation semantics:
          See ``How does that work?''.
compilation semantics tutorial:
          See ``Interpretation and Compilation Semantics and Immediacy''.
compilation token:
          See ``Compilation token''.
compilation tokens, tutorial:
          See ``Compilation Tokens''.
compilation word list:
          See ``Word Lists''.
compilation word list, change before definition ends:
          See ``Ambiguous conditions''.
compilation>:
          See ``Combined Words''.
compile state:
          See ``The Text Interpreter''.
compile,:
          See ``Macros''.
compile-@local:
          See ``Locals implementation''.
compile-f@local:
          See ``Locals implementation''.
compile-lp+!:
          See ``Locals implementation''.
compile-only:
          See ``Interpretation and Compilation Semantics''.
compile-only words:
          See ``Interpretation and Compilation Semantics''.
compiling compilation semantics:
          See ``Macros''.
compiling words:
          See ``Compiling words''.
conditional compilation:
          See ``Interpreter Directives''.
conditionals, tutorial:
          See ``Conditional execution''.
Constant:
          See ``Constants''.
constants:
          See ``Constants''.
construct:
          See ```objects.fs' Glossary''.
construct discussion:
          See ``Creating objects''.
context:
          See ``Word Lists''.
context-sensitive help:
          See ``Emacs and Gforth''.
contiguous regions and address arithmetic:
          See ``Address arithmetic''.
contiguous regions and heap allocation:
          See ``Heap allocation''.
contiguous regions in dictionary allocation:
          See ``Dictionary allocation''.
contiguous regions, ANS vs. Gforth:
          See ``ANS Forth and Gforth memory models''.
contributors to Gforth:
          See ``Authors and Ancestors of Gforth''.
control characters as delimiters:
          See ``Implementation Defined Options''.
control structures:
          See ``Control Structures''.
control structures for selection:
          See ``Selection''.
control structures programming style:
          See ``Arbitrary control structures''.
control structures, user-defined:
          See ``Arbitrary control structures''.
control-flow stack:
          See ``Arbitrary control structures''.
control-flow stack items, locals information:
          See ``Locals implementation''.
control-flow stack underflow:
          See ``Ambiguous conditions''.
control-flow stack, format:
          See ``Implementation Defined Options''.
convert:
          See ``Input''.
core words, ambiguous conditions:
          See ``Ambiguous conditions''.
core words, implementation-defined options:
          See ``Implementation Defined Options''.
core words, other system documentation:
          See ``Other system documentation''.
core words, system documentation:
          See ``The Core Words''.
count:
          See ``String Formats''.
counted loops:
          See ``Counted Loops''.
counted loops with negative increment:
          See ``Counted Loops''.
counted string:
          See ``String Formats''.
counted string, maximum size:
          See ``Implementation Defined Options''.
counted strings:
          See ``String Formats''.
cputime:
          See ``Keeping track of Time''.
cr:
          See ``Displaying characters and strings''.
Create:
          See ```CREATE'''.
CREATE ... DOES>:
          See ``User-defined Defining Words''.
CREATE ... DOES>, applications:
          See ``Applications of `CREATE..DOES>'''.
CREATE ... DOES>, details:
          See ``The gory details of `CREATE..DOES>'''.
CREATE and alignment:
          See ``Address arithmetic''.
create-file:
          See ``General files''.
create-interpret/compile:
          See ``Combined Words''.
create...does> tutorial:
          See ``Defining Words''.
creating objects:
          See ``Creating objects''.
cross-compiler <1>:
          See ``Cross Compiler''.
cross-compiler:
          See ```cross.fs'''.
cross.fs <1>:
          See ``Cross Compiler''.
cross.fs:
          See ```cross.fs'''.
CS-PICK:
          See ``Arbitrary control structures''.
CS-PICK, fewer than u+1 items on the control flow-stack:
          See ``Ambiguous conditions''.
CS-ROLL:
          See ``Arbitrary control structures''.
CS-ROLL, fewer than u+1 items on the control flow-stack:
          See ``Ambiguous conditions''.
CT (compilation token):
          See ``Compilation token''.
CT, tutorial:
          See ``Compilation Tokens''.
current:
          See ``Word Lists''.
current':
          See ```objects.fs' Glossary''.
current-interface:
          See ```objects.fs' Glossary''.
current-interface discussion:
          See ```objects.fs' Implementation''.
currying:
          See ``Applications of `CREATE..DOES>'''.
cursor control:
          See ``Displaying characters and strings''.
d+:
          See ``Double precision''.
d, stack item type:
          See ``Notation''.
d-:
          See ``Double precision''.
d.:
          See ``Simple numeric output''.
d.r:
          See ``Simple numeric output''.
d0<:
          See ``Numeric comparison''.
d0<=:
          See ``Numeric comparison''.
d0<>:
          See ``Numeric comparison''.
d0=:
          See ``Numeric comparison''.
d0>:
          See ``Numeric comparison''.
d0>=:
          See ``Numeric comparison''.
d2*:
          See ``Bitwise operations''.
d2/:
          See ``Bitwise operations''.
d<:
          See ``Numeric comparison''.
d<=:
          See ``Numeric comparison''.
d<>:
          See ``Numeric comparison''.
d=:
          See ``Numeric comparison''.
d>:
          See ``Numeric comparison''.
d>=:
          See ``Numeric comparison''.
d>f:
          See ``Floating Point''.
D>F, d cannot be presented precisely as a float:
          See ``Ambiguous conditions''.
d>s:
          See ``Double precision''.
D>S, d out of range of n:
          See ``Ambiguous conditions''.
dabs:
          See ``Double precision''.
data examination:
          See ``Examining data and code''.
data space - reserving some:
          See ``Dictionary allocation''.
data space available:
          See ``Other system documentation''.
data space containing definitions gets de-allocated:
          See ``Ambiguous conditions''.
data space pointer not properly aligned, ,, C,:
          See ``Ambiguous conditions''.
data space read/write with incorrect alignment:
          See ``Ambiguous conditions''.
data stack:
          See ``Stack Manipulation''.
data stack manipulation words:
          See ``Data stack''.
data-relocatable image files:
          See ``Data-Relocatable Image Files''.
data-space, read-only regions:
          See ``Implementation Defined Options''.
dbg:
          See ``Singlestep Debugger''.
debug tracer editing commands:
          See ``Emacs and Gforth''.
debugging:
          See ``Debugging''.
debugging output, finding the source location in Emacs:
          See ``Emacs and Gforth''.
debugging Singlestep:
          See ``Singlestep Debugger''.
dec.:
          See ``Simple numeric output''.
decimal:
          See ``Number Conversion''.
decompilation tutorial:
          See ``Decompilation''.
default type of locals:
          See ``Gforth locals''.
defer:
          See ``Class Declaration''.
Defer:
          See ``Deferred words''.
deferred words:
          See ``Deferred words''.
Defers:
          See ``Deferred words''.
defines:
          See ``Basic `mini-oof.fs' Usage''.
defining defining words:
          See ``User-defined Defining Words''.
defining words:
          See ``Defining Words''.
defining words tutorial:
          See ``Defining Words''.
defining words with arbitrary semantics combinations:
          See ``Combined Words''.
defining words without name:
          See ``Anonymous Definitions''.
defining words, name given in a string:
          See ``Supplying the name of a defined word''.
defining words, simple:
          See ```CREATE'''.
defining words, user-defined:
          See ``User-defined Defining Words''.
definition:
          See ``Introducing the Text Interpreter''.
definitions <1>:
          See ``The `oof.fs' base class''.
definitions:
          See ``Word Lists''.
definitions, tutorial:
          See ``Colon Definitions''.
delete-file:
          See ``General files''.
depth:
          See ``Examining data and code''.
design of stack effects, tutorial:
          See ``Designing the stack effect''.
dest, control-flow stack item:
          See ``Arbitrary control structures''.
df!:
          See ``Memory Access''.
df@:
          See ``Memory Access''.
df@ or df! used with an address that is not double-float  aligned:
          See ``Ambiguous conditions''.
df_, stack item type:
          See ``Notation''.
dfalign:
          See ``Dictionary allocation''.
dfaligned:
          See ``Address arithmetic''.
dfloat%:
          See ``Structure Glossary''.
dfloat+:
          See ``Address arithmetic''.
dfloats:
          See ``Address arithmetic''.
dict-new:
          See ```objects.fs' Glossary''.
dict-new discussion:
          See ``Creating objects''.
dictionary:
          See ``The Text Interpreter''.
dictionary in persistent form:
          See ``Image Files''.
dictionary overflow:
          See ``Ambiguous conditions''.
dictionary size default:
          See ``Stack and Dictionary Sizes''.
digits > 35:
          See ``Implementation Defined Options''.
direct threaded inner interpreter:
          See ``Threading''.
dispose:
          See ``The `oof.fs' base class''.
dividing by zero:
          See ``Ambiguous conditions''.
dividing by zero, floating-point:
          See ``Ambiguous conditions''.
Dividing classes:
          See ``Dividing classes''.
division rounding:
          See ``Implementation Defined Options''.
division with potentially negative operands:
          See ``Arithmetic''.
dmax:
          See ``Double precision''.
dmin:
          See ``Double precision''.
dnegate:
          See ``Double precision''.
DO:
          See ``Arbitrary control structures''.
DO loops:
          See ``Counted Loops''.
docol::
          See ``Threading Words''.
docon::
          See ``Threading Words''.
dodefer::
          See ``Threading Words''.
dodoes routine:
          See ``DOES>''.
does-code!:
          See ``Threading Words''.
does-handler!:
          See ``Threading Words''.
DOES>:
          See ``The gory details of `CREATE..DOES>'''.
DOES> implementation:
          See ``DOES>''.
DOES> in a separate definition:
          See ``The gory details of `CREATE..DOES>'''.
DOES> in interpretation state:
          See ``The gory details of `CREATE..DOES>'''.
DOES> of non-CREATEd words:
          See ``Ambiguous conditions''.
does> tutorial:
          See ``Defining Words''.
DOES>, visibility of current definition:
          See ``Implementation Defined Options''.
DOES>-code:
          See ``DOES>''.
does>-code:
          See ``Threading Words''.
DOES>-handler:
          See ``DOES>''.
does>-handler:
          See ``Threading Words''.
DOES>-parts, stack effect:
          See ``User-defined Defining Words''.
dofield::
          See ``Threading Words''.
DONE:
          See ``Arbitrary control structures''.
double precision arithmetic words:
          See ``Double precision''.
double words, ambiguous conditions:
          See ``Ambiguous conditions''.
double words, system documentation:
          See ``The optional Double Number word set''.
double%:
          See ``Structure Glossary''.
double-cell numbers, input format:
          See ``Number Conversion''.
doubly indirect threaded code:
          See ```gforthmi'''.
douser::
          See ``Threading Words''.
dovar::
          See ``Threading Words''.
dpl:
          See ``Number Conversion''.
drop:
          See ``Data stack''.
du<:
          See ``Numeric comparison''.
du<=:
          See ``Numeric comparison''.
du>:
          See ``Numeric comparison''.
du>=:
          See ``Numeric comparison''.
dump:
          See ``Examining data and code''.
dup:
          See ``Data stack''.
duration of a system clock tick:
          See ``Implementation Defined Options''.
dynamic allocation of memory:
          See ``Heap allocation''.
early:
          See ``Class Declaration''.
early binding:
          See ``Class Binding''.
editing in ACCEPT and EXPECT:
          See ``Implementation Defined Options''.
eforth performance:
          See ``Performance''.
ekey:
          See ``Input''.
EKEY, encoding of keyboard events:
          See ``Implementation Defined Options''.
ekey>char:
          See ``Input''.
ekey?:
          See ``Input''.
elements of a Forth system:
          See ``Review - elements of a Forth system''.
ELSE:
          See ``Arbitrary control structures''.
Emacs and Gforth:
          See ``Emacs and Gforth''.
emit:
          See ``Displaying characters and strings''.
EMIT and non-graphic characters:
          See ``Implementation Defined Options''.
emit-file:
          See ``General files''.
empty-buffer:
          See ``Blocks''.
empty-buffers:
          See ``Blocks''.
end-class <1>:
          See ``Basic `mini-oof.fs' Usage''.
end-class:
          See ```objects.fs' Glossary''.
end-class usage:
          See ``Basic `objects.fs' Usage''.
end-class-noname:
          See ```objects.fs' Glossary''.
end-code:
          See ```Code' and `;code'''.
end-interface:
          See ```objects.fs' Glossary''.
end-interface usage:
          See ``Object Interfaces''.
end-interface-noname:
          See ```objects.fs' Glossary''.
end-methods:
          See ```objects.fs' Glossary''.
end-struct:
          See ``Structure Glossary''.
end-struct usage:
          See ``Structure Usage''.
endcase:
          See ``Arbitrary control structures''.
ENDIF:
          See ``Arbitrary control structures''.
endless loop:
          See ``Simple Loops''.
endof:
          See ``Arbitrary control structures''.
endscope:
          See ``Where are locals visible by name?''.
endtry:
          See ``Exception Handling''.
endwith:
          See ``The `oof.fs' base class''.
engine:
          See ``Engine''.
engine performance:
          See ``Performance''.
engine portability:
          See ``Portability''.
engine.s:
          See ``Produced code''.
environment variables <1>:
          See ```gforthmi'''.
environment variables:
          See ``Environment variables''.
environment wordset:
          See ``Notation''.
environment-wordlist:
          See ``Environmental Queries''.
environment?:
          See ``Environmental Queries''.
ENVIRONMENT? string length, maximum:
          See ``Implementation Defined Options''.
environmental queries:
          See ``Environmental Queries''.
equality of floats:
          See ``Floating Point''.
erase:
          See ``Memory Blocks''.
error messages:
          See ``Error messages''.
error output, finding the source location in Emacs:
          See ``Emacs and Gforth''.
etags.fs:
          See ``Emacs and Gforth''.
evaluate:
          See ``Input Sources''.
examining data and code:
          See ``Examining data and code''.
exception:
          See ``Exception Handling''.
exception abort sequence of ABORT":
          See ``Implementation Defined Options''.
exception when including source:
          See ``Implementation Defined Options''.
exception words, implementation-defined options:
          See ``Implementation Defined Options''.
exception words, system documentation:
          See ``The optional Exception word set''.
exceptions:
          See ``Exception Handling''.
exceptions tutorial:
          See ``Exceptions''.
executable image file:
          See ``Running Image Files''.
execute:
          See ``Execution token''.
executing code on startup:
          See ``Invoking Gforth''.
execution semantics:
          See ``Interpretation and Compilation Semantics''.
execution token <1>:
          See ``Execution token''.
execution token:
          See ``Introducing the Text Interpreter''.
execution token of last defined word:
          See ``Anonymous Definitions''.
execution token of words with undefined execution semantics:
          See ``Ambiguous conditions''.
execution tokens tutorial:
          See ``Execution Tokens''.
exercises:
          See ``Exercises''.
EXIT:
          See ``Calls and returns''.
exit in m: ... ;m:
          See ``Method conveniences''.
exitm:
          See ```objects.fs' Glossary''.
exitm discussion:
          See ``Method conveniences''.
expect:
          See ``Input''.
EXPECT, display after end of input:
          See ``Implementation Defined Options''.
EXPECT, editing:
          See ``Implementation Defined Options''.
explicit register declarations:
          See ``Portability''.
exponent too big for conversion (DF!, DF@, SF!, SF@):
          See ``Ambiguous conditions''.
extended records:
          See ``Structure Usage''.
f!:
          See ``Memory Access''.
f! used with an address that is not float aligned:
          See ``Ambiguous conditions''.
f*:
          See ``Floating Point''.
f**:
          See ``Floating Point''.
f+:
          See ``Floating Point''.
f,:
          See ``Dictionary allocation''.
f, stack item type:
          See ``Notation''.
f-:
          See ``Floating Point''.
f.:
          See ``Simple numeric output''.
f.s:
          See ``Examining data and code''.
f/:
          See ``Floating Point''.
f0<:
          See ``Floating Point''.
f0<=:
          See ``Floating Point''.
f0<>:
          See ``Floating Point''.
f0=:
          See ``Floating Point''.
f0>:
          See ``Floating Point''.
f0>=:
          See ``Floating Point''.
f2*:
          See ``Floating Point''.
f2/:
          See ``Floating Point''.
f83name, stack item type:
          See ``Notation''.
f<:
          See ``Floating Point''.
f<=:
          See ``Floating Point''.
f<>:
          See ``Floating Point''.
f=:
          See ``Floating Point''.
f>:
          See ``Floating Point''.
f>=:
          See ``Floating Point''.
f>d:
          See ``Floating Point''.
F>D, integer part of float cannot be represented by d:
          See ``Ambiguous conditions''.
f>l:
          See ``Locals implementation''.
f@:
          See ``Memory Access''.
f@ used with an address that is not float aligned:
          See ``Ambiguous conditions''.
f@local#:
          See ``Locals implementation''.
f_, stack item type:
          See ``Notation''.
fabs:
          See ``Floating Point''.
facility words, ambiguous conditions:
          See ``Ambiguous conditions''.
facility words, implementation-defined options:
          See ``Implementation Defined Options''.
facility words, system documentation:
          See ``The optional Facility word set''.
facos:
          See ``Floating Point''.
FACOS, |float|>1:
          See ``Ambiguous conditions''.
facosh:
          See ``Floating Point''.
FACOSH, float<1:
          See ``Ambiguous conditions''.
factoring:
          See ``An Introduction to ANS Forth''.
factoring similar colon definitions:
          See ``Applications of `CREATE..DOES>'''.
factoring tutorial:
          See ``Factoring''.
falign:
          See ``Dictionary allocation''.
faligned:
          See ``Address arithmetic''.
falog:
          See ``Floating Point''.
false:
          See ``Boolean Flags''.
fam (file access method):
          See ``General files''.
fasin:
          See ``Floating Point''.
FASIN, |float|>1:
          See ``Ambiguous conditions''.
fasinh:
          See ``Floating Point''.
FASINH, float<0:
          See ``Ambiguous conditions''.
fatan:
          See ``Floating Point''.
fatan2:
          See ``Floating Point''.
FATAN2, both arguments are equal to zero:
          See ``Ambiguous conditions''.
fatanh:
          See ``Floating Point''.
FATANH, |float|>1:
          See ``Ambiguous conditions''.
fconstant:
          See ``Constants''.
fcos:
          See ``Floating Point''.
fcosh:
          See ``Floating Point''.
fdepth:
          See ``Examining data and code''.
fdrop:
          See ``Floating point stack''.
fdup:
          See ``Floating point stack''.
fe.:
          See ``Simple numeric output''.
fexp:
          See ``Floating Point''.
fexpm1:
          See ``Floating Point''.
field:
          See ``Structure Glossary''.
field naming convention:
          See ``Structure Naming Convention''.
field usage:
          See ``Structure Usage''.
field usage in class definition:
          See ``Basic `objects.fs' Usage''.
file access methods used:
          See ``Implementation Defined Options''.
file exceptions:
          See ``Implementation Defined Options''.
file input nesting, maximum depth:
          See ``Implementation Defined Options''.
file line terminator:
          See ``Implementation Defined Options''.
file name format:
          See ``Implementation Defined Options''.
file search path:
          See ``Search Paths''.
file words, ambiguous conditions:
          See ``Ambiguous conditions''.
file words, implementation-defined options:
          See ``Implementation Defined Options''.
file words, system documentation:
          See ``The optional File-Access word set''.
file-handling:
          See ``General files''.
file-position:
          See ``General files''.
file-size:
          See ``General files''.
file-status:
          See ``General files''.
FILE-STATUS, returned information:
          See ``Implementation Defined Options''.
files:
          See ``Files''.
files containing blocks:
          See ``Implementation Defined Options''.
files containing Forth code, tutorial:
          See ``Using files for Forth code''.
files tutorial:
          See ``Files''.
fill:
          See ``Memory Blocks''.
find:
          See ``Word Lists''.
find-name:
          See ``Name token''.
first definition:
          See ``Your first Forth definition''.
first field optimization:
          See ``Structure Usage''.
first field optimization, implementation:
          See ``Structure Implementation''.
flags on the command line:
          See ``Invoking Gforth''.
flags tutorial:
          See ``Flags and Comparisons''.
flavours of locals:
          See ``Gforth locals''.
FLiteral:
          See ``Literals''.
fln:
          See ``Floating Point''.
FLN, float=<0:
          See ``Ambiguous conditions''.
flnp1:
          See ``Floating Point''.
FLNP1, float=<-1:
          See ``Ambiguous conditions''.
float:
          See ``Address arithmetic''.
float%:
          See ``Structure Glossary''.
float+:
          See ``Address arithmetic''.
floating point arithmetic words:
          See ``Floating Point''.
floating point numbers, format and range:
          See ``Implementation Defined Options''.
floating point unidentified fault, integer division:
          See ``Ambiguous conditions''.
floating-point arithmetic, pitfalls:
          See ``Floating Point''.
floating-point comparisons:
          See ``Floating Point''.
floating-point dividing by zero:
          See ``Ambiguous conditions''.
floating-point numbers, input format:
          See ``Number Conversion''.
floating-point numbers, rounding or truncation:
          See ``Implementation Defined Options''.
floating-point result out of range:
          See ``Ambiguous conditions''.
floating-point stack:
          See ``Stack Manipulation''.
floating-point stack in the standard:
          See ``Stack Manipulation''.
floating-point stack manipulation words:
          See ``Floating point stack''.
floating-point stack size:
          See ``Implementation Defined Options''.
floating-point stack width:
          See ``Implementation Defined Options''.
floating-point unidentified fault, F>D:
          See ``Ambiguous conditions''.
floating-point unidentified fault, FACOS, FASIN or FATANH:
          See ``Ambiguous conditions''.
floating-point unidentified fault, FACOSH:
          See ``Ambiguous conditions''.
floating-point unidentified fault, FASINH or FSQRT:
          See ``Ambiguous conditions''.
floating-point unidentified fault, FLN or FLOG:
          See ``Ambiguous conditions''.
floating-point unidentified fault, FLNP1:
          See ``Ambiguous conditions''.
floating-point unidentified fault, FP divide-by-zero:
          See ``Ambiguous conditions''.
floating-point words, ambiguous conditions:
          See ``Ambiguous conditions''.
floating-point words, implementation-defined options:
          See ``Implementation Defined Options''.
floating-point words, system documentation:
          See ``The optional Floating-Point word set''.
floating-stack:
          See ``Floating point stack''.
floats:
          See ``Address arithmetic''.
flog:
          See ``Floating Point''.
FLOG, float=<0:
          See ``Ambiguous conditions''.
floor:
          See ``Floating Point''.
FLOORED:
          See ``Single precision''.
flush:
          See ``Blocks''.
flush-file:
          See ``General files''.
flush-icache:
          See ```Code' and `;code'''.
fm/mod:
          See ``Mixed precision''.
fmax:
          See ``Floating Point''.
fmin:
          See ``Floating Point''.
fnegate:
          See ``Floating Point''.
fnip:
          See ``Floating point stack''.
FOR:
          See ``Arbitrary control structures''.
FOR loops:
          See ``Counted Loops''.
FORGET, deleting the compilation word list:
          See ``Ambiguous conditions''.
FORGET, name can't be found:
          See ``Ambiguous conditions''.
FORGET, removing a needed definition:
          See ``Ambiguous conditions''.
forgeting words:
          See ``Forgetting words''.
format and range of floating point numbers:
          See ``Implementation Defined Options''.
format of glossary entries:
          See ``Notation''.
formatted numeric output:
          See ``Formatted numeric output''.
Forth:
          See ``Word Lists''.
Forth - an introduction:
          See ``An Introduction to ANS Forth''.
Forth mode in Emacs:
          See ``Emacs and Gforth''.
Forth source files:
          See ``Forth source files''.
Forth Tutorial:
          See ``Forth Tutorial''.
Forth-related information:
          See ``Other Forth-related information''.
forth-wordlist:
          See ``Word Lists''.
forth.el:
          See ``Emacs and Gforth''.
fover:
          See ``Floating point stack''.
fp!:
          See ``Stack pointer manipulation''.
fp0:
          See ``Stack pointer manipulation''.
fp@:
          See ``Stack pointer manipulation''.
fpath:
          See ``Source Search Paths''.
fpick:
          See ``Floating point stack''.
free:
          See ``Heap allocation''.
frequently asked questions:
          See ``Other Forth-related information''.
frot:
          See ``Floating point stack''.
fround:
          See ``Floating Point''.
fs.:
          See ``Simple numeric output''.
fsin:
          See ``Floating Point''.
fsincos:
          See ``Floating Point''.
fsinh:
          See ``Floating Point''.
fsqrt:
          See ``Floating Point''.
FSQRT, float<0:
          See ``Ambiguous conditions''.
fswap:
          See ``Floating point stack''.
ftan:
          See ``Floating Point''.
FTAN on an argument r1 where cos(r1) is zero:
          See ``Ambiguous conditions''.
ftanh:
          See ``Floating Point''.
ftuck:
          See ``Floating point stack''.
fully relocatable image files:
          See ``Fully Relocatable Image Files''.
functions, tutorial:
          See ``Colon Definitions''.
fvariable:
          See ``Variables''.
f~:
          See ``Floating Point''.
f~abs:
          See ``Floating Point''.
f~rel:
          See ``Floating Point''.
general files:
          See ``General files''.
get-block-fid:
          See ``Blocks''.
get-current:
          See ``Word Lists''.
get-order:
          See ``Word Lists''.
getenv:
          See ``Passing Commands to the Operating System''.
gforth:
          See ``Environmental Queries''.
GFORTH - environment variable <1>:
          See ```gforthmi'''.
GFORTH - environment variable:
          See ``Environment variables''.
Gforth - leaving:
          See ``Leaving Gforth''.
Gforth environment:
          See ``Gforth Environment''.
Gforth extensions:
          See ``Should I use Gforth extensions?''.
Gforth files:
          See ``Gforth files''.
Gforth locals:
          See ``Gforth locals''.
Gforth performance:
          See ``Performance''.
gforth-ditc:
          See ```gforthmi'''.
gforth-fast and backtraces:
          See ``Error messages''.
gforth-fast, difference from gforth:
          See ``Error messages''.
gforth.el:
          See ``Emacs and Gforth''.
gforth.fi, relocatability:
          See ``Fully Relocatable Image Files''.
GFORTHD - environment variable <1>:
          See ```gforthmi'''.
GFORTHD - environment variable:
          See ``Environment variables''.
GFORTHHIST - environment variable:
          See ``Environment variables''.
gforthmi:
          See ```gforthmi'''.
GFORTHPATH - environment variable:
          See ``Environment variables''.
glossary notation format:
          See ``Notation''.
GNU C for the engine:
          See ``Portability''.
goals of the Gforth project:
          See ``Goals of Gforth''.
header space:
          See ``Word Lists''.
heap allocation:
          See ``Heap allocation''.
heap-new:
          See ```objects.fs' Glossary''.
heap-new discussion:
          See ``Creating objects''.
heap-new usage:
          See ``Basic `objects.fs' Usage''.
here:
          See ``Dictionary allocation''.
hex:
          See ``Number Conversion''.
hex.:
          See ``Simple numeric output''.
history file:
          See ``Command-line editing''.
hold:
          See ``Formatted numeric output''.
how::
          See ``Class Declaration''.
i:
          See ``Counted Loops''.
I/O - blocks:
          See ``Blocks''.
I/O - file-handling:
          See ``Files''.
I/O - keyboard and display:
          See ``Other I/O''.
I/O - see character strings:
          See ``String Formats''.
I/O - see input:
          See ``Input''.
I/O exception in block transfer:
          See ``Ambiguous conditions''.
IF:
          See ``Arbitrary control structures''.
IF control structure:
          See ``Selection''.
if, tutorial:
          See ``Conditional execution''.
image file:
          See ``Image Files''.
image file background:
          See ``Image File Background''.
image file initialization sequence:
          See ``Modifying the Startup Sequence''.
image file invocation:
          See ``Running Image Files''.
image file loader:
          See ``Image File Background''.
image file, data-relocatable:
          See ``Data-Relocatable Image Files''.
image file, executable:
          See ``Running Image Files''.
image file, fully relocatable:
          See ``Fully Relocatable Image Files''.
image file, non-relocatable:
          See ``Non-Relocatable Image Files''.
image file, stack and dictionary sizes:
          See ``Stack and Dictionary Sizes''.
image file, turnkey applications:
          See ``Modifying the Startup Sequence''.
image license:
          See ``Image Licensing Issues''.
immediate:
          See ``Interpretation and Compilation Semantics''.
immediate words <1>:
          See ``Interpretation and Compilation Semantics''.
immediate words:
          See ``How does that work?''.
immediate, tutorial:
          See ``Interpretation and Compilation Semantics and Immediacy''.
implementation:
          See ```objects.fs' Glossary''.
implementation of locals:
          See ``Locals implementation''.
implementation of structures:
          See ``Structure Implementation''.
implementation usage:
          See ``Object Interfaces''.
implementation-defined options, block words:
          See ``Implementation Defined Options''.
implementation-defined options, core words:
          See ``Implementation Defined Options''.
implementation-defined options, exception words:
          See ``Implementation Defined Options''.
implementation-defined options, facility words:
          See ``Implementation Defined Options''.
implementation-defined options, file words:
          See ``Implementation Defined Options''.
implementation-defined options, floating-point words:
          See ``Implementation Defined Options''.
implementation-defined options, locals words:
          See ``Implementation Defined Options''.
implementation-defined options, memory-allocation words:
          See ``Implementation Defined Options''.
implementation-defined options, programming-tools words:
          See ``Implementation Defined Options''.
implementation-defined options, search-order words:
          See ``Implementation Defined Options''.
in-lining of constants:
          See ``Constants''.
include:
          See ``Forth source files''.
include search path:
          See ``Search Paths''.
include, placement in files:
          See ``Emacs and Gforth''.
include-file:
          See ``Forth source files''.
INCLUDE-FILE, file-id is invalid:
          See ``Ambiguous conditions''.
INCLUDE-FILE, I/O exception reading or closing file-id:
          See ``Ambiguous conditions''.
included:
          See ``Forth source files''.
INCLUDED, I/O exception reading or closing file-id:
          See ``Ambiguous conditions''.
INCLUDED, named file cannot be opened:
          See ``Ambiguous conditions''.
included?:
          See ``Forth source files''.
including files:
          See ``Forth source files''.
including files, stack effect:
          See ``Forth source files''.
indirect threaded inner interpreter:
          See ``Threading''.
inheritance:
          See ``Object-Oriented Terminology''.
init:
          See ``The `oof.fs' base class''.
init-asm:
          See ```Code' and `;code'''.
init-object:
          See ```objects.fs' Glossary''.
init-object discussion:
          See ``Creating objects''.
initialization sequence of image file:
          See ``Modifying the Startup Sequence''.
inner interpreter implementation:
          See ``Threading''.
inner interpreter optimization:
          See ``Scheduling''.
inner interpreter, direct threaded:
          See ``Threading''.
inner interpreter, indirect threaded:
          See ``Threading''.
input:
          See ``Input''.
input buffer:
          See ``The Text Interpreter''.
input format for double-cell numbers:
          See ``Number Conversion''.
input format for floating-point numbers:
          See ``Number Conversion''.
input format for single-cell numbers:
          See ``Number Conversion''.
input line size, maximum:
          See ``Implementation Defined Options''.
input line terminator:
          See ``Implementation Defined Options''.
input sources:
          See ``Input Sources''.
inst-value:
          See ```objects.fs' Glossary''.
inst-value usage:
          See ``Method conveniences''.
inst-value visibility:
          See ``Classes and Scoping''.
inst-var:
          See ```objects.fs' Glossary''.
inst-var implementation:
          See ```objects.fs' Implementation''.
inst-var usage:
          See ``Method conveniences''.
inst-var visibility:
          See ``Classes and Scoping''.
instance variables:
          See ``Object-Oriented Terminology''.
instruction pointer:
          See ``Threading''.
insufficient data stack or return stack space:
          See ``Ambiguous conditions''.
insufficient space for loop control parameters:
          See ``Ambiguous conditions''.
insufficient space in the dictionary:
          See ``Ambiguous conditions''.
integer types, ranges:
          See ``Implementation Defined Options''.
interface:
          See ```objects.fs' Glossary''.
interface implementation:
          See ```objects.fs' Implementation''.
interface usage:
          See ``Object Interfaces''.
interfaces for objects:
          See ``Object Interfaces''.
interpret state:
          See ``The Text Interpreter''.
Interpret/Compile states:
          See ``Interpret/Compile states''.
interpret/compile::
          See ``Combined Words''.
interpretation semantics <1>:
          See ``Interpretation and Compilation Semantics''.
interpretation semantics:
          See ``How does that work?''.
interpretation semantics tutorial:
          See ``Interpretation and Compilation Semantics and Immediacy''.
interpretation>:
          See ``Combined Words''.
interpreter - outer:
          See ``The Text Interpreter''.
interpreter directives:
          See ``Interpreter Directives''.
Interpreting a compile-only word:
          See ``Ambiguous conditions''.
Interpreting a compile-only word, for ' etc.:
          See ``Ambiguous conditions''.
Interpreting a compile-only word, for a local:
          See ``Ambiguous conditions''.
interpreting a word with undefined interpretation semantics:
          See ``Ambiguous conditions''.
invalid block number:
          See ``Ambiguous conditions''.
Invalid memory address:
          See ``Ambiguous conditions''.
Invalid memory address, stack overflow:
          See ``Ambiguous conditions''.
Invalid name argument, TO <1>:
          See ``Ambiguous conditions''.
Invalid name argument, TO:
          See ``Ambiguous conditions''.
invert:
          See ``Bitwise operations''.
invoking a selector:
          See ``Object-Oriented Terminology''.
invoking Gforth:
          See ``Invoking Gforth''.
invoking image files:
          See ``Running Image Files''.
ior type description:
          See ``Notation''.
ior values and meaning <1>:
          See ``Implementation Defined Options''.
ior values and meaning:
          See ``Implementation Defined Options''.
is:
          See ``The `oof.fs' base class''.
IS:
          See ``Deferred words''.
j:
          See ``Counted Loops''.
k:
          See ``Counted Loops''.
kern*.fi, relocatability:
          See ``Fully Relocatable Image Files''.
key:
          See ``Input''.
key?:
          See ``Input''.
keyboard events, encoding in EKEY:
          See ``Implementation Defined Options''.
labels as values:
          See ``Threading''.
laddr#:
          See ``Locals implementation''.
last word was headerless:
          See ``Ambiguous conditions''.
lastxt:
          See ``Anonymous Definitions''.
late binding:
          See ``Class Binding''.
LEAVE:
          See ``Arbitrary control structures''.
leaving definitions, tutorial:
          See ``Leaving definitions or loops''.
leaving Gforth:
          See ``Leaving Gforth''.
leaving loops, tutorial:
          See ``Leaving definitions or loops''.
length of a line affected by \:
          See ``Implementation Defined Options''.
license for images:
          See ``Image Licensing Issues''.
lifetime of locals:
          See ``How long do locals live?''.
line terminator on input:
          See ``Implementation Defined Options''.
link:
          See ``The `oof.fs' base class''.
list:
          See ``Blocks''.
LIST display format:
          See ``Implementation Defined Options''.
list-size:
          See ``Locals implementation''.
Literal:
          See ``Literals''.
literal tutorial:
          See ```Literal'''.
Literals:
          See ``Literals''.
load:
          See ``Blocks''.
loader for image files:
          See ``Image File Background''.
loading files at startup:
          See ``Invoking Gforth''.
loading Forth code, tutorial:
          See ``Using files for Forth code''.
local in interpretation state:
          See ``Ambiguous conditions''.
local variables, tutorial:
          See ``Local Variables''.
locale and case-sensitivity:
          See ``Implementation Defined Options''.
locals:
          See ``Locals''.
locals and return stack:
          See ``Return stack''.
locals flavours:
          See ``Gforth locals''.
locals implementation:
          See ``Locals implementation''.
locals information on the control-flow stack:
          See ``Locals implementation''.
locals lifetime:
          See ``How long do locals live?''.
locals programming style:
          See ``Locals programming style''.
locals stack <1>:
          See ``Locals implementation''.
locals stack:
          See ``Stack Manipulation''.
locals types:
          See ``Gforth locals''.
locals visibility:
          See ``Where are locals visible by name?''.
locals words, ambiguous conditions:
          See ``Ambiguous conditions''.
locals words, implementation-defined options:
          See ``Implementation Defined Options''.
locals words, system documentation:
          See ``The optional Locals word set''.
locals, ANS Forth style:
          See ``ANS Forth locals''.
locals, default type:
          See ``Gforth locals''.
locals, Gforth style:
          See ``Gforth locals''.
locals, maximum number in a definition:
          See ``Implementation Defined Options''.
long long:
          See ``Portability''.
LOOP:
          See ``Arbitrary control structures''.
loop control parameters not available:
          See ``Ambiguous conditions''.
loops without count:
          See ``Simple Loops''.
loops, counted:
          See ``Counted Loops''.
loops, counted, tutorial:
          See ``Counted loops''.
loops, endless:
          See ``Simple Loops''.
loops, indefinite, tutorial:
          See ``General Loops''.
lp! <1>:
          See ``Locals implementation''.
lp!:
          See ``Stack pointer manipulation''.
lp+!#:
          See ``Locals implementation''.
lp0:
          See ``Stack pointer manipulation''.
lp@:
          See ``Stack pointer manipulation''.
lshift:
          See ``Bitwise operations''.
LSHIFT, large shift counts:
          See ``Ambiguous conditions''.
m*:
          See ``Mixed precision''.
m*/:
          See ``Mixed precision''.
m+:
          See ``Mixed precision''.
m::
          See ```objects.fs' Glossary''.
m: usage:
          See ``Method conveniences''.
Macros:
          See ``Macros''.
macros:
          See ``Compiling words''.
macros, advanced tutorial:
          See ``Advanced macros''.
mapping block ranges to files:
          See ``Implementation Defined Options''.
marker:
          See ``Forgetting words''.
max:
          See ``Single precision''.
maxalign:
          See ``Dictionary allocation''.
maxaligned:
          See ``Address arithmetic''.
maximum depth of file input nesting:
          See ``Implementation Defined Options''.
maximum number of locals in a definition:
          See ``Implementation Defined Options''.
maximum number of word lists in search order:
          See ``Implementation Defined Options''.
maximum size of a counted string:
          See ``Implementation Defined Options''.
maximum size of a definition name, in characters:
          See ``Implementation Defined Options''.
maximum size of a parsed string:
          See ``Implementation Defined Options''.
maximum size of input line:
          See ``Implementation Defined Options''.
maximum string length for ENVIRONMENT?, in characters:
          See ``Implementation Defined Options''.
memory access words:
          See ``Memory Access''.
memory access/allocation tutorial:
          See ``Memory''.
memory alignment tutorial:
          See ``Alignment''.
memory block words:
          See ``Memory Blocks''.
memory words:
          See ``Memory''.
memory-allocation word set:
          See ``Heap allocation''.
memory-allocation words, implementation-defined options:
          See ``Implementation Defined Options''.
memory-allocation words, system documentation:
          See ``The optional Memory-Allocation word set''.
message send:
          See ``Object-Oriented Terminology''.
metacompiler <1>:
          See ``Cross Compiler''.
metacompiler:
          See ```cross.fs'''.
method <1>:
          See ``Basic `mini-oof.fs' Usage''.
method <2>:
          See ``Class Declaration''.
method <3>:
          See ```objects.fs' Glossary''.
method:
          See ``Object-Oriented Terminology''.
method conveniences:
          See ``Method conveniences''.
method map:
          See ```objects.fs' Implementation''.
method selector:
          See ``Object-Oriented Terminology''.
method usage:
          See ``Basic `oof.fs' Usage''.
methods:
          See ```objects.fs' Glossary''.
methods...end-methods:
          See ``Dividing classes''.
min:
          See ``Single precision''.
mini-oof:
          See ``The `mini-oof.fs' model''.
mini-oof example:
          See ``Mini-OOF Example''.
mini-oof usage:
          See ``Basic `mini-oof.fs' Usage''.
mini-oof.fs, differences to other models:
          See ``Comparison with other object models''.
minimum search order:
          See ``Implementation Defined Options''.
miscellaneous words:
          See ``Miscellaneous Words''.
mixed precision arithmetic words:
          See ``Mixed precision''.
mod:
          See ``Single precision''.
modifying >IN:
          See ``How does that work?''.
modifying the contents of the input buffer or a string literal:
          See ``Ambiguous conditions''.
most recent definition does not have a name (IMMEDIATE):
          See ``Ambiguous conditions''.
motivation for object-oriented programming:
          See ``Why object-oriented programming?''.
move:
          See ``Memory Blocks''.
ms:
          See ``Keeping track of Time''.
MS, repeatability to be expected:
          See ``Implementation Defined Options''.
n, stack item type:
          See ``Notation''.
naligned:
          See ``Structure Glossary''.
name:
          See ``Input''.
name dictionary:
          See ``Introducing the Text Interpreter''.
name field address:
          See ``Name token''.
name lookup, case-sensitivity:
          See ``Implementation Defined Options''.
name not defined by VALUE or (LOCAL) used by TO:
          See ``Ambiguous conditions''.
name not defined by VALUE used by TO:
          See ``Ambiguous conditions''.
name not found:
          See ``Ambiguous conditions''.
name not found (', POSTPONE, ['], [COMPILE]):
          See ``Ambiguous conditions''.
name token:
          See ``Name token''.
name, maximum length:
          See ``Implementation Defined Options''.
name>comp:
          See ``Name token''.
name>int:
          See ``Name token''.
name>string:
          See ``Name token''.
name?int:
          See ``Name token''.
names for defined words:
          See ``Supplying the name of a defined word''.
needs:
          See ``Forth source files''.
negate:
          See ``Single precision''.
negative increment for counted loops:
          See ``Counted Loops''.
Neon model:
          See ``Comparison with other object models''.
new <1>:
          See ``Basic `mini-oof.fs' Usage''.
new:
          See ``The `oof.fs' base class''.
new[]:
          See ``The `oof.fs' base class''.
newline character on input:
          See ``Implementation Defined Options''.
NEXT:
          See ``Arbitrary control structures''.
NEXT, direct threaded:
          See ``Threading''.
NEXT, indirect threaded:
          See ``Threading''.
nextname:
          See ``Supplying the name of a defined word''.
NFA:
          See ``Name token''.
nip:
          See ``Data stack''.
non-graphic characters and EMIT:
          See ``Implementation Defined Options''.
non-relocatable image files:
          See ``Non-Relocatable Image Files''.
noname:
          See ``Anonymous Definitions''.
notation of glossary entries:
          See ``Notation''.
NT Forth performance:
          See ``Performance''.
number conversion:
          See ``Number Conversion''.
number conversion - traps for the unwary:
          See ``Number Conversion''.
number of bits in one address unit:
          See ``Implementation Defined Options''.
number representation and arithmetic:
          See ``Implementation Defined Options''.
numeric comparison words:
          See ``Numeric comparison''.
numeric output - formatted:
          See ``Formatted numeric output''.
numeric output - simple/free-format:
          See ``Simple numeric output''.
object <1>:
          See ``Basic `mini-oof.fs' Usage''.
object <2>:
          See ```objects.fs' Glossary''.
object:
          See ``Object-Oriented Terminology''.
object allocation options:
          See ``Creating objects''.
object class:
          See ``The `object.fs' base class''.
object creation:
          See ``Creating objects''.
object interfaces:
          See ``Object Interfaces''.
object models, comparison:
          See ``Comparison with other object models''.
object-map discussion:
          See ```objects.fs' Implementation''.
object-oriented programming <1>:
          See ``The `oof.fs' model''.
object-oriented programming:
          See ``The `objects.fs' model''.
object-oriented programming motivation:
          See ``Why object-oriented programming?''.
object-oriented programming style:
          See ``Object-Oriented Programming Style''.
object-oriented terminology:
          See ``Object-Oriented Terminology''.
objects:
          See ``The `objects.fs' model''.
objects, basic usage:
          See ``Basic `objects.fs' Usage''.
objects.fs <1>:
          See ``The `oof.fs' model''.
objects.fs:
          See ``The `objects.fs' model''.
objects.fs Glossary:
          See ```objects.fs' Glossary''.
objects.fs implementation:
          See ```objects.fs' Implementation''.
objects.fs properties:
          See ``Properties of the `objects.fs' model''.
of:
          See ``Arbitrary control structures''.
off:
          See ``Boolean Flags''.
on:
          See ``Boolean Flags''.
Only:
          See ``Word Lists''.
oof:
          See ``The `oof.fs' model''.
oof.fs <1>:
          See ``The `oof.fs' model''.
oof.fs:
          See ``The `objects.fs' model''.
oof.fs base class:
          See ``The `oof.fs' base class''.
oof.fs properties:
          See ``Properties of the `oof.fs' model''.
oof.fs usage:
          See ``Basic `oof.fs' Usage''.
oof.fs, differences to other models:
          See ``Comparison with other object models''.
open-blocks:
          See ``Blocks''.
open-file:
          See ``General files''.
open-path-file:
          See ``General Search Paths''.
operating system - passing commands:
          See ``Passing Commands to the Operating System''.
operator's terminal facilities available:
          See ``Other system documentation''.
options on the command line:
          See ``Invoking Gforth''.
or:
          See ``Bitwise operations''.
order:
          See ``Word Lists''.
orig, control-flow stack item:
          See ``Arbitrary control structures''.
os-class:
          See ``Environmental Queries''.
other system documentation, block words:
          See ``Other system documentation''.
other system documentation, core words:
          See ``Other system documentation''.
outer interpreter <1>:
          See ``The Text Interpreter''.
outer interpreter <2>:
          See ``Stacks, postfix notation and parameter passing''.
outer interpreter:
          See ``Introducing the Text Interpreter''.
over:
          See ``Data stack''.
overflow of the pictured numeric output string:
          See ``Ambiguous conditions''.
overrides:
          See ```objects.fs' Glossary''.
overrides usage:
          See ``Basic `objects.fs' Usage''.
pad:
          See ``Input''.
PAD size:
          See ``Implementation Defined Options''.
PAD use by nonstandard words:
          See ``Other system documentation''.
page:
          See ``Displaying characters and strings''.
parameter stack:
          See ``Stack Manipulation''.
parameters are not of the same type (DO, ?DO, WITHIN):
          See ``Ambiguous conditions''.
parent class:
          See ``Object-Oriented Terminology''.
parent class binding:
          See ``Class Binding''.
parse:
          See ``Input''.
parse area:
          See ``The Text Interpreter''.
parsed string overflow:
          See ``Ambiguous conditions''.
parsed string, maximum size:
          See ``Implementation Defined Options''.
parsing a string:
          See ``Input''.
parsing words <1>:
          See ``The Text Interpreter''.
parsing words:
          See ``How does that work?''.
path for included:
          See ``Search Paths''.
path+:
          See ``General Search Paths''.
path-allot:
          See ``General Search Paths''.
path=:
          See ``General Search Paths''.
pedigree of Gforth:
          See ``Authors and Ancestors of Gforth''.
perform:
          See ``Execution token''.
performance of some Forth interpreters:
          See ``Performance''.
persistent form of dictionary:
          See ``Image Files''.
PFE performance:
          See ``Performance''.
pi:
          See ``Floating Point''.
pick:
          See ``Data stack''.
pictured numeric output:
          See ``Formatted numeric output''.
pictured numeric output buffer, size:
          See ``Implementation Defined Options''.
pictured numeric output string, overflow:
          See ``Ambiguous conditions''.
postpone:
          See ``The `oof.fs' base class''.
POSTPONE:
          See ``Macros''.
POSTPONE applied to [IF]:
          See ``Ambiguous conditions''.
POSTPONE or [COMPILE] applied to TO:
          See ``Ambiguous conditions''.
postpone tutorial:
          See ```POSTPONE'''.
postpone,:
          See ``Compilation token''.
Pountain's object-oriented model:
          See ``Comparison with other object models''.
precision:
          See ``Floating Point''.
precompiled Forth code:
          See ``Image Files''.
previous:
          See ``Word Lists''.
previous, search order empty:
          See ``Ambiguous conditions''.
primitive source format:
          See ``Automatic Generation''.
primitives, assembly code listing:
          See ``Produced code''.
primitives, automatic generation:
          See ``Automatic Generation''.
primitives, implementation:
          See ``Primitives''.
primitives, keeping the TOS in a register:
          See ``TOS Optimization''.
prims2x.fs:
          See ``Automatic Generation''.
print:
          See ```objects.fs' Glossary''.
printdebugdata:
          See ``Debugging''.
printdebugline:
          See ``Debugging''.
private discussion:
          See ``Classes and Scoping''.
procedures, tutorial:
          See ``Colon Definitions''.
program data space available:
          See ``Other system documentation''.
programming style, arbitrary control structures:
          See ``Arbitrary control structures''.
programming style, locals:
          See ``Locals programming style''.
programming style, object-oriented:
          See ``Object-Oriented Programming Style''.
programming tools:
          See ``Programming Tools''.
programming-tools words, ambiguous conditions:
          See ``Ambiguous conditions''.
programming-tools words, implementation-defined options:
          See ``Implementation Defined Options''.
programming-tools words, system documentation:
          See ``The optional Programming-Tools word set''.
prompt:
          See ``Implementation Defined Options''.
pronounciation of words:
          See ``Notation''.
protected:
          See ```objects.fs' Glossary''.
protected discussion:
          See ``Classes and Scoping''.
ptr <1>:
          See ``Class Declaration''.
ptr:
          See ``The `oof.fs' base class''.
public:
          See ```objects.fs' Glossary''.
query:
          See ``Input''.
quit:
          See ``Miscellaneous Words''.
r, stack item type:
          See ``Notation''.
r/o:
          See ``General files''.
r/w:
          See ``General files''.
r>:
          See ``Return stack''.
r@:
          See ``Return stack''.
ranges for integer types:
          See ``Implementation Defined Options''.
rdrop:
          See ``Return stack''.
read-file:
          See ``General files''.
read-line:
          See ``General files''.
read-only data space regions:
          See ``Implementation Defined Options''.
reading from file positions not yet written:
          See ``Ambiguous conditions''.
receiving object:
          See ``Object-Oriented Terminology''.
records:
          See ``Structures''.
records tutorial:
          See ``Arrays and Records''.
recover:
          See ``Exception Handling''.
recurse:
          See ``Calls and returns''.
RECURSE appears after DOES>:
          See ``Ambiguous conditions''.
recursion tutorial:
          See ``Recursion''.
recursive:
          See ``Calls and returns''.
recursive definitions:
          See ``Calls and returns''.
refill:
          See ``Input''.
registers of the inner interpreter:
          See ```Code' and `;code'''.
relocating loader:
          See ``Image File Background''.
relocation at load-time:
          See ``Image File Background''.
relocation at run-time:
          See ``Image File Background''.
rename-file:
          See ``General files''.
REPEAT:
          See ``Arbitrary control structures''.
repeatability to be expected from the execution of MS:
          See ``Implementation Defined Options''.
report the words used in your program:
          See ```ans-report.fs': Report the words used, sorted by wordset''.
reposition-file:
          See ``General files''.
REPOSITION-FILE, outside the file's boundaries:
          See ``Ambiguous conditions''.
represent:
          See ``Formatted numeric output''.
REPRESENT, results when float is out of range:
          See ``Implementation Defined Options''.
require:
          See ``Forth source files''.
require, placement in files:
          See ``Emacs and Gforth''.
required:
          See ``Forth source files''.
reserving data space:
          See ``Dictionary allocation''.
resize:
          See ``Heap allocation''.
resize-file:
          See ``General files''.
restore-input:
          See ``Input Sources''.
RESTORE-INPUT, Argument type mismatch:
          See ``Ambiguous conditions''.
restrict:
          See ``Interpretation and Compilation Semantics''.
result out of range:
          See ``Ambiguous conditions''.
return stack:
          See ``Stack Manipulation''.
return stack and locals:
          See ``Return stack''.
return stack dump with gforth-fast:
          See ``Error messages''.
return stack manipulation words:
          See ``Return stack''.
return stack space available:
          See ``Other system documentation''.
return stack tutorial:
          See ``Return Stack''.
return stack underflow:
          See ``Ambiguous conditions''.
returning from a definition:
          See ``Calls and returns''.
roll:
          See ``Data stack''.
Root:
          See ``Word Lists''.
rot:
          See ``Data stack''.
rounding of floating-point numbers:
          See ``Implementation Defined Options''.
rp!:
          See ``Stack pointer manipulation''.
rp0:
          See ``Stack pointer manipulation''.
rp@:
          See ``Stack pointer manipulation''.
rshift:
          See ``Bitwise operations''.
RSHIFT, large shift counts:
          See ``Ambiguous conditions''.
run-time code generation, tutorial:
          See ``Advanced macros''.
running Gforth:
          See ``Invoking Gforth''.
running image files:
          See ``Running Image Files''.
Rydqvist, Goran:
          See ``Emacs and Gforth''.
S":
          See ``Displaying characters and strings''.
S", number of string buffers:
          See ``Implementation Defined Options''.
S", size of string buffer:
          See ``Implementation Defined Options''.
s>d:
          See ``Double precision''.
save-buffer:
          See ``Blocks''.
save-buffers:
          See ``Blocks''.
save-input:
          See ``Input Sources''.
savesystem:
          See ``Non-Relocatable Image Files''.
savesystem during gforthmi:
          See ```gforthmi'''.
scope:
          See ``Where are locals visible by name?''.
scope of locals:
          See ``Where are locals visible by name?''.
scoping and classes:
          See ``Classes and Scoping''.
scr:
          See ``Blocks''.
seal:
          See ``Word Lists''.
search:
          See ``Memory Blocks''.
search order stack:
          See ``Word Lists''.
search order, maximum depth:
          See ``Implementation Defined Options''.
search order, minimum:
          See ``Implementation Defined Options''.
search order, tutorial:
          See ``Wordlists and Search Order''.
search path control, source files <1>:
          See ``General Search Paths''.
search path control, source files:
          See ``Source Search Paths''.
search path for files:
          See ``Search Paths''.
search-order words, ambiguous conditions:
          See ``Ambiguous conditions''.
search-order words, implementation-defined options:
          See ``Implementation Defined Options''.
search-order words, system documentation:
          See ``The optional Search-Order word set''.
search-wordlist:
          See ``Word Lists''.
see:
          See ``Examining data and code''.
see tutorial:
          See ``Decompilation''.
SEE, source and format of output:
          See ``Implementation Defined Options''.
selection control structures:
          See ``Selection''.
selector <1>:
          See ```objects.fs' Glossary''.
selector:
          See ``Object-Oriented Terminology''.
selector implementation, class:
          See ```objects.fs' Implementation''.
selector invocation:
          See ``Object-Oriented Terminology''.
selector invocation, restrictions <1>:
          See ``Basic `oof.fs' Usage''.
selector invocation, restrictions:
          See ``Basic `objects.fs' Usage''.
selector usage:
          See ``Basic `objects.fs' Usage''.
selectors and stack effects:
          See ``Object-Oriented Programming Style''.
selectors common to hardly-related classes:
          See ``Object Interfaces''.
self:
          See ``The `oof.fs' base class''.
semantics tutorial:
          See ``Interpretation and Compilation Semantics and Immediacy''.
semantics, interpretation and compilation:
          See ``Interpretation and Compilation Semantics''.
set-current:
          See ``Word Lists''.
set-order:
          See ``Word Lists''.
set-precision:
          See ``Floating Point''.
sf!:
          See ``Memory Access''.
sf@:
          See ``Memory Access''.
sf@ or sf! used with an address that is not single-float  aligned:
          See ``Ambiguous conditions''.
sf_, stack item type:
          See ``Notation''.
sfalign:
          See ``Dictionary allocation''.
sfaligned:
          See ``Address arithmetic''.
sfloat%:
          See ``Structure Glossary''.
sfloat+:
          See ``Address arithmetic''.
sfloats:
          See ``Address arithmetic''.
sh:
          See ``Passing Commands to the Operating System''.
shell commands:
          See ``Passing Commands to the Operating System''.
sign:
          See ``Formatted numeric output''.
simple defining words:
          See ```CREATE'''.
simple loops:
          See ``Simple Loops''.
single precision arithmetic words:
          See ``Single precision''.
single-assignment style for locals:
          See ``Locals programming style''.
single-cell numbers, input format:
          See ``Number Conversion''.
singlestep Debugger:
          See ``Singlestep Debugger''.
size of buffer at WORD:
          See ``Implementation Defined Options''.
size of the dictionary and the stacks:
          See ``Invoking Gforth''.
size of the keyboard terminal buffer:
          See ``Implementation Defined Options''.
size of the pictured numeric output buffer:
          See ``Implementation Defined Options''.
size of the scratch area returned by PAD:
          See ``Implementation Defined Options''.
size parameters for command-line options:
          See ``Invoking Gforth''.
SLiteral:
          See ``Literals''.
sm/rem:
          See ``Mixed precision''.
source:
          See ``The Text Interpreter''.
source location of error or debugging output in Emacs:
          See ``Emacs and Gforth''.
source-id:
          See ``Input Sources''.
SOURCE-ID, behaviour when BLK is non-zero:
          See ``Ambiguous conditions''.
sourcefilename:
          See ``Forth source files''.
sourceline#:
          See ``Forth source files''.
sp!:
          See ``Stack pointer manipulation''.
sp0:
          See ``Stack pointer manipulation''.
sp@:
          See ``Stack pointer manipulation''.
space:
          See ``Displaying characters and strings''.
space delimiters:
          See ``Implementation Defined Options''.
spaces:
          See ``Displaying characters and strings''.
span:
          See ``Input''.
speed, startup:
          See ``Startup speed''.
stack effect:
          See ``Notation''.
Stack effect design, tutorial:
          See ``Designing the stack effect''.
stack effect of DOES>-parts:
          See ``User-defined Defining Words''.
stack effect of included files:
          See ``Forth source files''.
stack effects of selectors:
          See ``Object-Oriented Programming Style''.
stack empty:
          See ``Ambiguous conditions''.
stack item types:
          See ``Notation''.
stack manipulation tutorial:
          See ``Stack Manipulation''.
stack manipulation words:
          See ``Stack Manipulation''.
stack manipulation words, floating-point stack:
          See ``Floating point stack''.
stack manipulation words, return stack:
          See ``Return stack''.
stack manipulations words, data stack:
          See ``Data stack''.
stack overflow:
          See ``Ambiguous conditions''.
stack pointer manipulation words:
          See ``Stack pointer manipulation''.
stack size default:
          See ``Stack and Dictionary Sizes''.
stack size, cache-friendly:
          See ``Stack and Dictionary Sizes''.
stack space available:
          See ``Other system documentation''.
stack tutorial:
          See ``Stack''.
stack underflow:
          See ``Ambiguous conditions''.
stack-effect comments, tutorial:
          See ``Stack-Effect Comments''.
starting Gforth tutorial:
          See ``Starting Gforth''.
startup sequence for image file:
          See ``Modifying the Startup Sequence''.
Startup speed:
          See ``Startup speed''.
state:
          See ``Interpret/Compile states''.
state - effect on the text interpreter:
          See ``How does that work?''.
STATE values:
          See ``Implementation Defined Options''.
state-smart words (are a bad idea):
          See ``Combined Words''.
static:
          See ``Class Declaration''.
string larger than pictured numeric output area (f., fe., fs.):
          See ``Ambiguous conditions''.
string longer than a counted string returned by WORD:
          See ``Ambiguous conditions''.
strings - see character strings:
          See ``String Formats''.
strings tutorial:
          See ``Characters and Strings''.
struct:
          See ``Structure Glossary''.
struct usage:
          See ``Structure Usage''.
structs tutorial:
          See ``Arrays and Records''.
structure extension:
          See ``Structure Usage''.
structure glossary:
          See ``Structure Glossary''.
structure implementation:
          See ``Structure Implementation''.
structure naming convention:
          See ``Structure Naming Convention''.
structure of Forth programs:
          See ``Forth is written in Forth''.
structure usage:
          See ``Structure Usage''.
structures:
          See ``Structures''.
structures containing arrays:
          See ``Structure Usage''.
structures containing structures:
          See ``Structure Usage''.
structures using address arithmetic:
          See ``Why explicit structure support?''.
sub-list?:
          See ``Locals implementation''.
super:
          See ``The `oof.fs' base class''.
superclass binding:
          See ``Class Binding''.
swap:
          See ``Data stack''.
sword:
          See ``Input''.
syntax tutorial:
          See ``Syntax''.
system:
          See ``Passing Commands to the Operating System''.
system dictionary space required, in address units:
          See ``Other system documentation''.
system documentation:
          See ``ANS conformance''.
system documentation, block words:
          See ``The optional Block word set''.
system documentation, core words:
          See ``The Core Words''.
system documentation, double words:
          See ``The optional Double Number word set''.
system documentation, exception words:
          See ``The optional Exception word set''.
system documentation, facility words:
          See ``The optional Facility word set''.
system documentation, file words:
          See ``The optional File-Access word set''.
system documentation, floating-point words:
          See ``The optional Floating-Point word set''.
system documentation, locals words:
          See ``The optional Locals word set''.
system documentation, memory-allocation words:
          See ``The optional Memory-Allocation word set''.
system documentation, programming-tools words:
          See ``The optional Programming-Tools word set''.
system documentation, search-order words:
          See ``The optional Search-Order word set''.
system prompt:
          See ``Implementation Defined Options''.
table:
          See ``Word Lists''.
TAGS file:
          See ``Emacs and Gforth''.
target compiler <1>:
          See ``Cross Compiler''.
target compiler:
          See ```cross.fs'''.
terminal buffer, size:
          See ``Implementation Defined Options''.
terminal input buffer:
          See ``The Text Interpreter''.
terminology for object-oriented programming:
          See ``Object-Oriented Terminology''.
text interpreter <1>:
          See ``The Text Interpreter''.
text interpreter <2>:
          See ``Stacks, postfix notation and parameter passing''.
text interpreter:
          See ``Introducing the Text Interpreter''.
text interpreter - effect of state:
          See ``How does that work?''.
text interpreter - input sources <1>:
          See ``Input Sources''.
text interpreter - input sources:
          See ``The Text Interpreter''.
THEN:
          See ``Arbitrary control structures''.
this:
          See ```objects.fs' Glossary''.
this and catch:
          See ```objects.fs' Implementation''.
this implementation:
          See ```objects.fs' Implementation''.
this usage:
          See ``Method conveniences''.
ThisForth performance:
          See ``Performance''.
threaded code implementation:
          See ``Threading''.
threading words:
          See ``Threading Words''.
threading, direct or indirect?:
          See ``Direct or Indirect Threaded?''.
threading-method:
          See ``Threading Words''.
throw:
          See ``Exception Handling''.
THROW-codes used in the system:
          See ``Implementation Defined Options''.
thru:
          See ``Blocks''.
tib:
          See ``The Text Interpreter''.
tick ('):
          See ``Execution token''.
TILE performance:
          See ``Performance''.
time&date:
          See ``Keeping track of Time''.
time-related words:
          See ``Keeping track of Time''.
TMP, TEMP - environment variable:
          See ``Environment variables''.
TO:
          See ``Values''.
TO on non-VALUEs:
          See ``Ambiguous conditions''.
TO on non-VALUEs and non-locals:
          See ``Ambiguous conditions''.
to-this:
          See ```objects.fs' Glossary''.
tokens for words:
          See ``Tokens for Words''.
TOS definition:
          See ``Stacks, postfix notation and parameter passing''.
TOS optimization for primitives:
          See ``TOS Optimization''.
toupper:
          See ``Displaying characters and strings''.
trigonometric operations:
          See ``Floating Point''.
true:
          See ``Boolean Flags''.
truncation of floating-point numbers:
          See ``Implementation Defined Options''.
try:
          See ``Exception Handling''.
tuck:
          See ``Data stack''.
turnkey image files:
          See ``Modifying the Startup Sequence''.
Tutorial:
          See ``Forth Tutorial''.
type:
          See ``Displaying characters and strings''.
types of locals:
          See ``Gforth locals''.
types of stack items:
          See ``Notation''.
types tutorial:
          See ``Types''.
typewhite:
          See ``Displaying characters and strings''.
U+DO:
          See ``Arbitrary control structures''.
u, stack item type:
          See ``Notation''.
U-DO:
          See ``Arbitrary control structures''.
u.:
          See ``Simple numeric output''.
u.r:
          See ``Simple numeric output''.
u<:
          See ``Numeric comparison''.
u<=:
          See ``Numeric comparison''.
u>:
          See ``Numeric comparison''.
u>=:
          See ``Numeric comparison''.
ud, stack item type:
          See ``Notation''.
ud.:
          See ``Simple numeric output''.
ud.r:
          See ``Simple numeric output''.
um*:
          See ``Mixed precision''.
um/mod:
          See ``Mixed precision''.
undefined word:
          See ``Ambiguous conditions''.
undefined word, ', POSTPONE, ['], [COMPILE]:
          See ``Ambiguous conditions''.
unexpected end of the input buffer:
          See ``Ambiguous conditions''.
unloop:
          See ``Arbitrary control structures''.
unmapped block numbers:
          See ``Ambiguous conditions''.
UNREACHABLE:
          See ``Where are locals visible by name?''.
UNTIL:
          See ``Arbitrary control structures''.
UNTIL loop:
          See ``Simple Loops''.
unused:
          See ``Dictionary allocation''.
update:
          See ``Blocks''.
UPDATE, no current block buffer:
          See ``Ambiguous conditions''.
updated?:
          See ``Blocks''.
upper and lower case:
          See ``Case insensitivity''.
use:
          See ``Blocks''.
User:
          See ``Variables''.
user input device, method of selecting:
          See ``Implementation Defined Options''.
user output device, method of selecting:
          See ``Implementation Defined Options''.
user space:
          See ``Variables''.
user variables:
          See ``Variables''.
user-defined defining words:
          See ``User-defined Defining Words''.
utime:
          See ``Keeping track of Time''.
Value:
          See ``Values''.
value-flavoured locals:
          See ``Gforth locals''.
values:
          See ``Values''.
var <1>:
          See ``Basic `mini-oof.fs' Usage''.
var:
          See ``Class Declaration''.
Variable:
          See ``Variables''.
variable-flavoured locals:
          See ``Gforth locals''.
variables:
          See ``Variables''.
versions, invoking other versions of Gforth:
          See ``Invoking Gforth''.
viewing the documentation of a word in Emacs:
          See ``Emacs and Gforth''.
viewing the source of a word in Emacs:
          See ``Emacs and Gforth''.
virtual function:
          See ``Object-Oriented Terminology''.
virtual function table:
          See ```objects.fs' Implementation''.
virtual machine:
          See ``Engine''.
virtual machine instructions, implementation:
          See ``Primitives''.
visibility of locals:
          See ``Where are locals visible by name?''.
vlist:
          See ``Word Lists''.
Vocabularies, detailed explanation:
          See ``Vocabularies''.
Vocabulary:
          See ``Word Lists''.
vocs:
          See ``Word Lists''.
vocstack empty, previous:
          See ``Ambiguous conditions''.
vocstack full, also:
          See ``Ambiguous conditions''.
w, stack item type:
          See ``Notation''.
w/o:
          See ``General files''.
What's:
          See ``Deferred words''.
where to go next:
          See ``Where To Go Next''.
WHILE:
          See ``Arbitrary control structures''.
WHILE loop:
          See ``Simple Loops''.
wid:
          See ``Word Lists''.
wid, stack item type:
          See ``Notation''.
Win32Forth performance:
          See ``Performance''.
wior type description:
          See ``Notation''.
wior values and meaning:
          See ``Implementation Defined Options''.
with:
          See ``The `oof.fs' base class''.
within:
          See ``Numeric comparison''.
word <1>:
          See ``Input''.
word:
          See ``Introducing the Text Interpreter''.
WORD buffer size:
          See ``Implementation Defined Options''.
word glossary entry format:
          See ``Notation''.
word list for defining locals:
          See ``Locals implementation''.
word lists:
          See ``Word Lists''.
word lists - example:
          See ``Word list example''.
word lists - why use them?:
          See ``Why use word lists?''.
word name too long:
          See ``Ambiguous conditions''.
WORD, string overflow:
          See ``Ambiguous conditions''.
wordlist:
          See ``Word Lists''.
wordlists tutorial:
          See ``Wordlists and Search Order''.
words <1>:
          See ``Word Lists''.
words:
          See ``Forth Words''.
words used in your program:
          See ```ans-report.fs': Report the words used, sorted by wordset''.
words, forgetting:
          See ``Forgetting words''.
wordset:
          See ``Notation''.
write-file:
          See ``General files''.
write-line:
          See ``General files''.
xor:
          See ``Bitwise operations''.
xt <1>:
          See ``Execution token''.
xt:
          See ``Introducing the Text Interpreter''.
XT tutorial:
          See ``Execution Tokens''.
xt, stack item type:
          See ``Notation''.
xt-new:
          See ```objects.fs' Glossary''.
xt-see:
          See ``Examining data and code''.
zero-length string as a name:
          See ``Ambiguous conditions''.
Zsoter's object-oriented model:
          See ``Comparison with other object models''.
~~:
          See ``Debugging''.
~~, removal with Emacs:
          See ``Emacs and Gforth''.

...Table of Contents...
