This is Info file gforth.info, produced by Makeinfo version 1.68 from
the input file gforth.texi.

INFO-DIR-SECTION GNU programming tools
START-INFO-DIR-ENTRY
* Gforth: (gforth).             A fast interpreter for the Forth language.
END-INFO-DIR-ENTRY

   This file documents Gforth 0.4.0

   Copyright (C) 1995-1998 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.


File: gforth.info,  Node: ANS conformance,  Next: Model,  Prev: Tools,  Up: Top

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

* Menu:

* The Core Words::
* The optional Block word set::
* The optional Double Number word set::
* The optional Exception word set::
* The optional Facility word set::
* The optional File-Access word set::
* The optional Floating-Point word set::
* The optional Locals word set::
* The optional Memory-Allocation word set::
* The optional Programming-Tools word set::
* The optional Search-Order word set::


File: gforth.info,  Node: The Core Words,  Next: The optional Block word set,  Prev: ANS conformance,  Up: ANS conformance

The Core Words
==============

* Menu:

* core-idef::                   Implementation Defined Options
* core-ambcond::                Ambiguous Conditions
* core-other::                  Other System Documentation


File: gforth.info,  Node: core-idef,  Next: core-ambcond,  Prev: The Core Words,  Up: 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).

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 charcter can be used in a name.
     Matching is case-insensitive (except in `TABLE's). The matching is
     performed using the C 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. `PARSE-WORD' 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 ports, 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
     ports.

number representation and arithmetic:
     Processor-dependent. Binary two's complement on all current ports.

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

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), although a `-10 throw'
     (divide by zero) would be more appropriate.

whether the current definition can be found after DOES>:
     No.


File: gforth.info,  Node: core-ambcond,  Next: core-other,  Prev: core-idef,  Up: The Core Words

Ambiguous conditions
--------------------

a name is neither a word nor a number:
     `-13 throw' (Undefined word). Actually, `-13 bounce', which
     preserves the data and FP stack, so you don't lose more work than
     necessary.

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 name 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:
     typically results in a `-55 throw' (floating point unidentified
     fault), although a `-10 throw' (divide by zero) would be more
     appropriate.

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 `-9 throw' (Invalid memory address) as soon as the
     overflow happens. If it is not check, 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:
     Not checked. Runs into the dictionary and destroys it (at least,
     partially).

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 `-55 throw' (floatingpoint
     unidentified fault), although a `-10 throw' (divide by zero) would
     be more appropriate. `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.
     The consequences of stack underflows are similar to the
     consequences of stack overflows. 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).

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.


File: gforth.info,  Node: core-other,  Prev: core-ambcond,  Up: The Core Words

Other system documentation
--------------------------

nonstandard words using `PAD':
     None.

operator's terminal facilities available:
     After processing the 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.


File: gforth.info,  Node: The optional Block word set,  Next: The optional Double Number word set,  Prev: The Core Words,  Up: ANS conformance

The optional Block word set
===========================

* Menu:

* block-idef::                  Implementation Defined Options
* block-ambcond::               Ambiguous Conditions
* block-other::                 Other System Documentation


File: gforth.info,  Node: block-idef,  Next: block-ambcond,  Prev: The optional Block word set,  Up: 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.


File: gforth.info,  Node: block-ambcond,  Next: block-other,  Prev: block-idef,  Up: The optional Block word set

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.


File: gforth.info,  Node: block-other,  Prev: block-ambcond,  Up: The optional Block word set

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.


File: gforth.info,  Node: The optional Double Number word set,  Next: The optional Exception word set,  Prev: The optional Block word set,  Up: ANS conformance

The optional Double Number word set
===================================

* Menu:

* double-ambcond::              Ambiguous Conditions


File: gforth.info,  Node: double-ambcond,  Prev: The optional Double Number word set,  Up: 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.


File: gforth.info,  Node: The optional Exception word set,  Next: The optional Facility word set,  Prev: The optional Double Number word set,  Up: ANS conformance

The optional Exception word set
===============================

* Menu:

* exception-idef::              Implementation Defined Options


File: gforth.info,  Node: exception-idef,  Prev: The optional Exception word set,  Up: 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.


File: gforth.info,  Node: The optional Facility word set,  Next: The optional File-Access word set,  Prev: The optional Exception word set,  Up: ANS conformance

The optional Facility word set
==============================

* Menu:

* facility-idef::               Implementation Defined Options
* facility-ambcond::            Ambiguous Conditions


File: gforth.info,  Node: facility-idef,  Next: facility-ambcond,  Prev: The optional Facility word set,  Up: The optional Facility word set

Implementation Defined Options
------------------------------

encoding of keyboard events (`EKEY'):
     Not yet implemented.

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.


File: gforth.info,  Node: facility-ambcond,  Prev: facility-idef,  Up: The optional Facility word set

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.


File: gforth.info,  Node: The optional File-Access word set,  Next: The optional Floating-Point word set,  Prev: The optional Facility word set,  Up: ANS conformance

The optional File-Access word set
=================================

* Menu:

* file-idef::                   Implementation Defined Options
* file-ambcond::                Ambiguous Conditions


File: gforth.info,  Node: file-idef,  Next: file-ambcond,  Prev: The optional File-Access word set,  Up: 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.


File: gforth.info,  Node: file-ambcond,  Prev: file-idef,  Up: The optional File-Access word set

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


File: gforth.info,  Node: The optional Floating-Point word set,  Next: The optional Locals word set,  Prev: The optional File-Access word set,  Up: ANS conformance

The optional Floating-Point word set
====================================

* Menu:

* floating-idef::               Implementation Defined Options
* floating-ambcond::            Ambiguous Conditions


File: gforth.info,  Node: floating-idef,  Next: floating-ambcond,  Prev: The optional Floating-Point word set,  Up: 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'.


File: gforth.info,  Node: floating-ambcond,  Prev: floating-idef,  Up: The optional Floating-Point word set

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 `-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:
     `-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'):
     `-55 throw' (Floating-point unidentified fault)

FLOAT=<-1 (`FLNP1'):
     `-55 throw' (Floating-point unidentified fault). On IEEE-FP systems
     negative infinity is typically produced for FLOAT=-1.

FLOAT=<0 (`FLN', `FLOG'):
     `-55 throw' (Floating-point unidentified fault). On IEEE-FP systems
     negative infinity is typically produced for FLOAT=0.

FLOAT<0 (`FASINH', `FSQRT'):
     `-55 throw' (Floating-point unidentified fault). `fasinh' produces
     values for these inputs on my Linux box (Bug in the C library?)

|FLOAT|>1 (`FACOS', `FASIN', `FATANH'):
     `-55 throw' (Floating-point unidentified fault).

integer part of float cannot be represented by D in `F>D':
     `-55 throw' (Floating-point unidentified fault).

string larger than pictured numeric output area (`f.', `fe.', `fs.'):
     This does not happen.


File: gforth.info,  Node: The optional Locals word set,  Next: The optional Memory-Allocation word set,  Prev: The optional Floating-Point word set,  Up: ANS conformance

The optional Locals word set
============================

* Menu:

* locals-idef::                 Implementation Defined Options
* locals-ambcond::              Ambiguous Conditions


File: gforth.info,  Node: locals-idef,  Next: locals-ambcond,  Prev: The optional Locals word set,  Up: 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.


File: gforth.info,  Node: locals-ambcond,  Prev: locals-idef,  Up: The optional Locals word set

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)


File: gforth.info,  Node: The optional Memory-Allocation word set,  Next: The optional Programming-Tools word set,  Prev: The optional Locals word set,  Up: ANS conformance

The optional Memory-Allocation word set
=======================================

* Menu:

* memory-idef::                 Implementation Defined Options


File: gforth.info,  Node: memory-idef,  Prev: The optional Memory-Allocation word set,  Up: 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.


File: gforth.info,  Node: The optional Programming-Tools word set,  Next: The optional Search-Order word set,  Prev: The optional Memory-Allocation word set,  Up: ANS conformance

The optional Programming-Tools word set
=======================================

* Menu:

* programming-idef::            Implementation Defined Options
* programming-ambcond::         Ambiguous Conditions


File: gforth.info,  Node: programming-idef,  Next: programming-ambcond,  Prev: The optional Programming-Tools word set,  Up: 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 intermediate code used by the inner
     interpreter.  The current `see' tries to output Forth source code
     as well as possible.


File: gforth.info,  Node: programming-ambcond,  Prev: programming-idef,  Up: The optional Programming-Tools word set

Ambiguous conditions
--------------------

deleting the compilation wordlist (`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).


File: gforth.info,  Node: The optional Search-Order word set,  Prev: The optional Programming-Tools word set,  Up: ANS conformance

The optional Search-Order word set
==================================

* Menu:

* search-idef::                 Implementation Defined Options
* search-ambcond::              Ambiguous Conditions


File: gforth.info,  Node: search-idef,  Next: search-ambcond,  Prev: The optional Search-Order word set,  Up: 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'.


File: gforth.info,  Node: search-ambcond,  Prev: search-idef,  Up: The optional Search-Order word set

Ambiguous conditions
--------------------

changing the compilation wordlist (during compilation):
     The word is entered into the wordlist that was the compilation
     wordlist 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
     wordlist.

search order empty (`previous'):
     `abort" Vocstack empty"'.

too many word lists in search order (`also'):
     `abort" Vocstack full"'.


File: gforth.info,  Node: Model,  Next: Integrating Gforth,  Prev: ANS conformance,  Up: Top

Model
*****

   This chapter has yet to be written. It will contain information, on
which internal structures you can rely.


File: gforth.info,  Node: Integrating Gforth,  Next: Emacs and Gforth,  Prev: Model,  Up: Top

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 ATLASTs 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


File: gforth.info,  Node: Emacs and Gforth,  Next: Image Files,  Prev: Integrating Gforth,  Up: Top

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. I have also
added comment paragraph filling (`M-q'), commenting (`C-x \') and
uncommenting (`C-u C-x \') regions and removing debugging tracers (`C-x
~', *note Debugging::.). 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 `include' `etags.fs', a new `TAGS' file (*note Tags
Tables: (emacs)Tags.) will be produced 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 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))


File: gforth.info,  Node: Image Files,  Next: Engine,  Prev: Emacs and Gforth,  Up: Top

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.

* Menu:

* Image Licensing Issues::      Distribution terms for images.
* Image File Background::       Why have image files?
* Non-Relocatable Image Files::  don't always work.
* Data-Relocatable Image Files::  are better.
* Fully Relocatable Image Files::  better yet.
* Stack and Dictionary Sizes::  Setting the default sizes for an image.
* Running Image Files::         `gforth -i FILE' or FILE.
* Modifying the Startup Sequence::  and turnkey applications.


File: gforth.info,  Node: Image Licensing Issues,  Next: Image File Background,  Prev: Image Files,  Up: 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.


File: gforth.info,  Node: Image File Background,  Next: Non-Relocatable Image Files,  Prev: Image Licensing Issues,  Up: Image Files

Image File Background
=====================

   Our Forth system consists not only of primitives, 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
primitives and the Forth source alone. Therefore we provide the Forth
code as an image file in nearly executable form. At the start of the
system 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 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 Bradleys `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, our loader performs relocation at image load time. The
loader also has to replace tokens standing for 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). And 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.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).


File: gforth.info,  Node: Non-Relocatable Image Files,  Next: Data-Relocatable Image Files,  Prev: Image File Background,  Up: Image Files

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''


File: gforth.info,  Node: Data-Relocatable Image Files,  Next: Fully Relocatable Image Files,  Prev: Non-Relocatable Image Files,  Up: Image Files

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::.).

