This is gforth.info, produced by makeinfo version 7.3 from gforth.texi.

This manual is for Gforth (version 0.7.9_20260902, September 02, 2026),
a fast and portable implementation of the Standard Forth language.  It
serves as reference manual, but it also contains an introduction to
Forth and a Forth tutorial.

   Authors: Bernd Paysan, Anton Ertl, Gerald Wodni, Neal Crook, David
Kuehling, Jens Wilke Copyright © 1995, 1996, 1997, 1998, 2000, 2003,
2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015,
2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023, 2024,2025 Free Software
Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.1 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover texts
     being "A GNU Manual," and with the Back-Cover Texts as in (a)
     below.  A copy of the license is included in the section entitled
     "GNU Free Documentation License."

     (a) The FSF's Back-Cover Text is: "You have freedom to copy and
     modify this GNU Manual, like GNU software.  Copies published by the
     Free Software Foundation raise funds for GNU development."
INFO-DIR-SECTION Software development
START-INFO-DIR-ENTRY
* Gforth: (gforth).             A fast interpreter for the Forth language.
END-INFO-DIR-ENTRY


File: gforth.info,  Node: Where are locals visible by name?,  Next: How long do locals live?,  Prev: Locals definition words,  Up: Gforth locals

6.26.1.2 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-0.2

‘endscope’ ( compilation scope - ; run-time  -  ) gforth-0.2

   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’...‘THEN’ are
visible until the ‘THEN’, 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), you can produce code
whose behaviour is best determined by looking at the implementation
(which may change).

‘UNREACHABLE’ ( -  ) gforth-0.2
   This word promises to the compiler that it can never be executed.
One could put it, e.g., behind a ‘-13 throw’.

   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 the use appears
textually before the definition.

   From this example it is clear that the visibility rules cannot be
fully implemented without major headaches in a one-pass compiler like
Gforth's.  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.

   It pessimistically assumes that all locals are visible that were
visible at the latest place outside any control structure (i.e., where
nothing is on the control-flow stack).  This means that in:

     : foo
       IF {: z :} THEN
       {: x :}
       AHEAD
         BEGIN
           ( * )
         [ 1 CS-ROLL ] THEN
         {: y :}
         ...
       UNTIL ;

   At the place marked with ‘( * )’, ‘x’ is visible, but ‘y’ is not
(although, according to the reachability rule it should); ‘z’ is not and
should not be visible there.

   However, you 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’ ( compilation orig - orig  ) gforth-0.2
   Used immediatly before a ‘BEGIN’ that is not reachable from above.
Causes the ‘BEGIN’ to assume that the same locals are live as right
before the control flow word (typically ‘ahead’) that pushed the orig.

E.g.,
     IF
       {: x :}
       AHEAD
         ASSUME-LIVE
         BEGIN
           x
         [ 1 CS-ROLL ] THEN
         ...
       UNTIL
     THEN

   Here ‘x’ would not be visible at the use of ‘x’, because its
definition is inside a control structure, but by using ASSUME-LIVE the
programmer tells the compiler that the locals visible at the ‘AHEAD’
should be visible at the ‘BEGIN’.

   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 in a ‘BEGIN’ loop and should be
visible in that loop before the definition 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

   The ideas in this section have also been published in M. Anton Ertl,
‘Automatic Scoping of Local Variables
(https://www.complang.tuwien.ac.at/papers/ertl94l.ps.gz)’, EuroForth
'94.

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

   (1) In compiler construction terminology, all places dominated by the
definition of the local.


File: gforth.info,  Node: How long do locals live?,  Next: POSTPONEing locals,  Prev: Where are locals visible by name?,  Up: Gforth locals

6.26.1.3 How long do locals live?
.................................

Each local lives only as long as it is visible; afterwards its address
is invalid, and programs that access it afterwards are erroneous; it's a
good idea to use non-addressable value-flavoured or defer-flavoured
locals to avoid such errors.


File: gforth.info,  Node: POSTPONEing locals,  Next: Locals programming style,  Prev: How long do locals live?,  Up: Gforth locals

6.26.1.4 POSTPONEing locals
...........................

In Gforth you can ‘postpone’ a local (or use a local inside ‘]]’...‘[[’,
*note Macros::).  Given the normal lifetime of locals (*note How long do
locals live?::), what does this mean?  Consider:

     : foo {: W: n D: d F: r C: c XT: xt -- :}
       POSTPONE n
       POSTPONE d
       POSTPONE r
       POSTPONE c
       POSTPONE xt
       0 ->n #0. ->d 0e ->r 0 ->c `abort =>xt
     ; immediate

   This is equivalent to

     : foo {: W: n D: d F: r C: c XT: xt -- :}
       n POSTPONE literal
       d POSTPONE 2literal
       r POSTPONE fliteral
       c POSTPONE literal
       ACTION-OF xt compile,
       0 ->n #0. ->d 0e -> r 0 ->c `abort =>xt
     ; immediate

   I.e., when applied to locals, ‘postpone’ compiles the value that the
local has at the point of the ‘postpone’, not any later value of the
local.  This solves the problem that the local does not live
indefinitely, and it also results in efficient code.  But in general it
does not produce the value that an infinite-lifetime local would have at
the place where the local is compiled into by the ‘postpone’ (what a
Scheme programmer would expect).  However, as long as you do not use
‘TO’, ‘+TO’, ‘IS’ or ‘ADDR’ on the same local as ‘POSTPONE’, the latter
produces the result that a Scheme programmer would expect.

   Concerning using locals without ‘TO’ and friends, *note Locals
programming style::.

   Using ‘postpone’ with variable-flavoured locals produces an error
during compilation.


File: gforth.info,  Node: Locals programming style,  Next: Locals implementation,  Prev: POSTPONEing locals,  Up: Gforth locals

6.26.1.5 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’ and friends,
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
        1 +TO addr1
        1 +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’ and friends: When you read the use of, e.g., ‘addr1’ near the
start of the loop, 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.


File: gforth.info,  Node: Locals implementation,  Prev: Locals programming style,  Up: Gforth locals

6.26.1.6 Locals implementation
..............................

Gforth uses a separate locals stack.  The most compelling reason for
this is that the return stack is not float-aligned; using a separate
stack also eliminates the restrictions that other systems have because
they use the return stack as locals stack (and that standard programs
therefore also have).  Like the other stacks, the locals stack grows
toward lower addresses.  A few primitives allow an efficient
implementation; you should not use them directly, but they appear in the
output of ‘see’, so they are documented here:

‘@localn’ ( noffset - w ) gforth-internal "fetch-local-n"
   w is the content of the local at noffset from the locals pointer.

‘f@localn’ ( noffset - r ) gforth-internal "f-fetch-local-n"
   r is the content of the F: local at noffset from the locals pointer.

‘!localn’ ( w noffset - ) gforth-internal "store-local-n"
   Store w to the local at noffset from the locals pointer.

‘lp+n’ ( noffset - c-addr ) gforth-internal "lp-plus-n"
   c-addr is the address of the local at noffset from the locals
pointer.

‘lp+!’ ( noffset - ) gforth-internal "lp-plus-store"
   Add noffset to the locals pointer; a negative noffset allocates, a
positive noffset frees.

‘>l’ ( w - ) gforth-internal "to-l"
   Push w on the locals stack.

‘f>l’ ( r - ) gforth-internal "f-to-l"
   Push r on the locals stack.

   See also ‘lp@’, ‘lp!’ (*note Stack pointer manipulation::).

   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 ‘0 @localn’.

   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.

   Local variable names are stored in their own section ‘locals-headers’
by ‘create-local’, the central factor in all the words that define a
local.  Locals names of a definition are deleted when the definition is
complete.

   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.  This implementation was designed before
Gforth acquired recognizers; for a reimplementation we would use
recognizers.

   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:
current-locals-size dest-locals-size - ‘lp+!’
‘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:
current-locals-size dest-locals-size - ‘lp+!’
<orig target>:
orig-locals-size new-locals-size - ‘lp+!’
   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’.  This effect happens e.g., if there is
an ‘ELSE’ and the code before the ‘ELSE’ defines locals, and they have a
different size than those after the ‘ELSE’.  In general we recommend not
to work around this shortcoming (except in performance-critical code).
We intend to eliminate this shortcoming at some point.

   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

‘sub-list?’ ( list1 list2 - f  ) gforth-internal "sub-list-question"

‘list-size’ ( list - u  ) gforth-internal

   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.


File: gforth.info,  Node: Standard Forth locals,  Prev: Gforth locals,  Up: Locals

6.26.2 Standard Forth locals
----------------------------

The Forth-2012 standard defines a syntax for locals that is a restricted
version of Gforth's locals:

   • Locals can only be cell-sized values (no type specifiers are
     allowed).
   • Locals can be defined only outside control structures.
   • Only one locals definition is allowed per colon definition.
   • 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 locals definition must be in one line.

   The Standard Forth locals wordset itself consists of two words: ‘{:’
and:

‘(local)’ ( addr u -  ) local "paren-local-paren"

   The Forth-2012 locals extension wordset also defines a syntax using
‘locals|’, but it is so awful that we strongly recommend not to use it,
and the standardization committee standardized another, better syntax
(the one using ‘{:’).  We have implemented this syntax only to make
porting to Gforth easy.  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.


File: gforth.info,  Node: Object-oriented Forth,  Next: Closures,  Prev: Locals,  Up: Words

6.27 Object-oriented Forth
==========================

Gforth comes with the following packages for object-oriented
programming: ‘objects.fs’, ‘oof.fs’, ‘mini-oof.fs’, and ‘mini-oof2.fs’;
none of them is preloaded, so you have to ‘require’ them before use.
The most important differences between these packages (and others) are
discussed in *note Comparison with other object models::.  Mini-OOF2 is
Gforth-specific, the other three are are written in Standard Forth and
can be used with any other standard-compliant Forth system.

* Menu:

* Why object-oriented programming?::
* Object-Oriented Terminology::
* Objects::
* OOF::
* Mini-OOF::
* Mini-OOF2::
* Comparison of object models::


File: gforth.info,  Node: Why object-oriented programming?,  Next: Object-Oriented Terminology,  Prev: Object-oriented Forth,  Up: Object-oriented Forth

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


File: gforth.info,  Node: Object-Oriented Terminology,  Next: Objects,  Prev: Why object-oriented programming?,  Up: Object-oriented Forth

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


File: gforth.info,  Node: Objects,  Next: OOF,  Prev: Object-Oriented Terminology,  Up: Object-oriented Forth

6.27.3 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
(https://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.).

* Menu:

* Properties of the Objects model::
* Basic Objects Usage::
* The Objects base class::
* Creating objects::
* Object-Oriented Programming Style::
* Class Binding::
* Method conveniences::
* Classes and Scoping::
* Dividing classes::
* Object Interfaces::
* Objects Implementation::
* Objects Glossary::

   Marcel Hendrix provided helpful comments on this section.


File: gforth.info,  Node: Properties of the Objects model,  Next: Basic Objects Usage,  Prev: Objects,  Up: Objects

6.27.3.1 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 Standard Forth is available.


File: gforth.info,  Node: Basic Objects Usage,  Next: The Objects base class,  Prev: Properties of the Objects model,  Up: Objects

6.27.3.2 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’.


File: gforth.info,  Node: The Objects base class,  Next: Creating objects,  Prev: Basic Objects Usage,  Up: Objects

6.27.3.3 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’.


File: gforth.info,  Node: Creating objects,  Next: Object-Oriented Programming Style,  Prev: The Objects base class,  Up: Objects

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


File: gforth.info,  Node: Object-Oriented Programming Style,  Next: Class Binding,  Prev: Creating objects,  Up: Objects

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


File: gforth.info,  Node: Class Binding,  Next: Method conveniences,  Prev: Object-Oriented Programming Style,  Up: Objects

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


File: gforth.info,  Node: Method conveniences,  Next: Classes and Scoping,  Prev: Class Binding,  Up: Objects

6.27.3.7 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 ;’


File: gforth.info,  Node: Classes and Scoping,  Next: Dividing classes,  Prev: Method conveniences,  Up: Objects

6.27.3.8 Classes and Scoping
............................

Inheritance is frequent, unlike structure extension.  This exacerbates
the problem with the field name convention (*note Standard
Structures::): 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.


File: gforth.info,  Node: Dividing classes,  Next: Object Interfaces,  Prev: Classes and Scoping,  Up: Objects

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


File: gforth.info,  Node: Object Interfaces,  Next: Objects Implementation,  Prev: Dividing classes,  Up: Objects

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


File: gforth.info,  Node: Objects Implementation,  Next: Objects Glossary,  Prev: Object Interfaces,  Up: Objects

6.27.3.11 ‘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 (invocable).

   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.


File: gforth.info,  Node: Objects Glossary,  Prev: Objects Implementation,  Up: Objects

6.27.3.12 ‘objects.fs’ Glossary
...............................

‘bind’ ( ... "class" "selector" - ...  ) objects
   Execute the method for SELECTOR in CLASS.

‘<bind>’ ( class selector-xt - xt  ) objects "less-bind-to"
   XT is the method for the selector SELECTOR-XT in CLASS.

‘bind'’ ( "class" "selector" - xt  ) objects "bind-tick"
   XT is the method for SELECTOR in CLASS.

‘[bind]’ ( compile-time: "class" "selector" - ; run-time: ... object - ...  ) objects "left-bracket-bind-right-bracket"
   Compile the method for SELECTOR in CLASS.

‘class’ ( parent-class - align offset  ) objects
   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-to-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
   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-store"
   XT is the new method for the selector SEL-XT in CLASS-MAP.

‘class-previous’ ( class -  ) objects
   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-to-order"
   Add CLASS's wordlists to the head of the search-order.

‘construct’ ( ... object -  ) objects
   Initialize the data fields of OBJECT.  The method for the class
OBJECT just does nothing: ‘( object -- )’.

‘current'’ ( "selector" - xt  ) objects "current-tick"
   XT is the method for SELECTOR in the current class.

‘[current]’ ( compile-time: "selector" - ; run-time: ... object - ...  ) objects "left-bracket-current-right-bracket"
   Compile the method for SELECTOR in the current class.

‘current-interface’ ( - addr  ) objects
   Variable: contains the class or interface currently being defined.

‘dict-new’ ( ... class - object  ) objects
   ‘allot’ and initialize an object of class CLASS in the dictionary.

‘end-class’ ( align offset "name" -  ) objects
   NAME execution: ‘-- class’
End a class definition.  The resulting class is CLASS.

‘end-class-noname’ ( align offset - class  ) objects
   End a class definition.  The resulting class is CLASS.

‘end-interface’ ( "name" -  ) objects
   ‘name’ execution: ‘-- interface’
End an interface definition.  The resulting interface is INTERFACE.

‘end-interface-noname’ ( - interface  ) objects
   End an interface definition.  The resulting interface is INTERFACE.

‘end-methods’ ( -  ) objects
   Switch back from defining methods of a class to normal mode
(currently this just restores the old search order).

‘exitm’ ( -  ) objects
   ‘exit’ from a method; restore old ‘this’.

‘heap-new’ ( ... class - object  ) objects
   ‘allocate’ and initialize an object of class CLASS.

‘implementation’ ( interface -  ) objects
   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
   Initialize a chunk of memory (OBJECT) to an object of class CLASS;
then performs ‘construct’.

‘inst-value’ ( align1 offset1 "name" - align2 offset2  ) objects
   NAME execution: ‘-- w’
W is the value of the field NAME in ‘this’ object.

‘inst-var’ ( align1 offset1 align size "name" - align2 offset2  ) objects
   NAME execution: ‘-- addr’
ADDR is the address of the field NAME in ‘this’ object.

‘interface’ ( -  ) objects
   Start an interface definition.

‘m:’ ( - xt colon-sys; run-time: object -  ) objects "m-colon"
   Start a method definition; OBJECT becomes new ‘this’.

‘:m’ ( "name" - xt; run-time: object -  ) objects "colon-m"
   Start a named method definition; OBJECT becomes new ‘this’.  Has to
be ended with ‘;m’.

‘;m’ ( colon-sys -; run-time: -  ) objects "semicolon-m"
   End a method definition; restore old ‘this’.

‘method’ ( xt "name" -  ) objects
   ‘name’ execution: ‘... object -- ...’
Create selector NAME and makes XT its method in the current class.

‘methods’ ( class -  ) objects
   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
   the ancestor of all classes.

‘overrides’ ( xt "selector" -  ) objects
   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 "left-bracket-parent-right-bracket"
   Compile the method for SELECTOR in the parent of the current class.

‘print’ ( object -  ) objects
   Print the object.  The method for the class OBJECT prints the address
of the object and the address of its class.

‘protected’ ( -  ) objects
   Set the compilation wordlist to the current class's wordlist

‘public’ ( -  ) objects
   Restore the compilation wordlist that was in effect before the last
‘protected’ that actually changed the compilation wordlist.

‘selector’ ( "name" -  ) objects
   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
   the receiving object of the current method (aka active object).

‘<to-inst>’ ( w xt -  ) objects "less-to-inst-to"
   store W into the field XT in ‘this’ object.

‘[to-inst]’ ( compile-time: "name" - ; run-time: w -  ) objects "left-bracket-to-inst-right-bracket"
   store W into field NAME in ‘this’ object.

‘to-this’ ( object -  ) objects
   Set ‘this’ (used internally, but useful when debugging).

‘xt-new’ ( ... class xt - object  ) objects
   Make a new object, using ‘xt ( align size -- addr )’ to get memory.


File: gforth.info,  Node: OOF,  Next: Mini-OOF,  Prev: Objects,  Up: Object-oriented Forth

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

* Menu:

* Properties of the OOF model::
* Basic OOF Usage::
* The OOF base class::
* Class Declaration::


File: gforth.info,  Node: Properties of the OOF model,  Next: Basic OOF Usage,  Prev: OOF,  Up: OOF

6.27.4.1 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 Standard Forth is available.


File: gforth.info,  Node: Basic OOF Usage,  Next: The OOF base class,  Prev: Properties of the OOF model,  Up: OOF

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


File: gforth.info,  Node: The OOF base class,  Next: Class Declaration,  Prev: Basic OOF Usage,  Up: OOF

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

     ‘object-class’ ( "name" -  ) oof

     ‘object-definitions’ ( -  ) oof

     ‘object-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.

     ‘object-init’ ( ... -  ) oof

     ‘object-dispose’ ( -  ) oof

   • ‘new’, ‘new[]’, ‘:’, ‘ptr’, ‘asptr’, and ‘[]’ to create named and
     unnamed objects and object arrays or object pointers.

     ‘object-new’ ( - o  ) oof

     ‘object-new[]’ ( n - o  ) oof "new-array"

     ‘object-:’ ( "name" -  ) oof "define"

     ‘object-ptr’ ( "name" -  ) oof

     ‘object-asptr’ ( o "name" -  ) oof

     ‘object-[]’ ( 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.

     ‘object-::’ ( "name" -  ) oof "scope"

     ‘object-super’ ( "name" -  ) oof

   • ‘self’ to get the address of the object

     ‘object-self’ ( - o  ) oof

   • ‘bind’, ‘bound’, ‘link’, and ‘is’ to assign object pointers and
     instance defers.

     ‘object-bind’ ( o "name" -  ) oof

     ‘object-bound’ ( class addr "name" -  ) oof

     ‘object-link’ ( "name" - class addr  ) oof

     ‘object-is’ ( xt "name" -  ) oof

   • ‘'’ to obtain selector tokens, ‘send’ to invocate selectors form
     the stack, and ‘postpone’ to generate selector invocation code.

     ‘object-'’ ( "name" - xt  ) oof "tick"

     ‘object-postpone’ ( "name" -  ) oof

   • ‘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.

     ‘object-with’ ( o -  ) oof

     ‘object-endwith’ ( -  ) oof


File: gforth.info,  Node: Class Declaration,  Prev: The OOF base class,  Up: OOF

6.27.4.4 Class Declaration
..........................

   • Instance variables

     ‘var’ ( size -  ) oof
     Create an instance variable

   • Object pointers

     ‘ptr’ ( -  ) oof
     Create an instance pointer

     ‘asptr’ ( class -  ) oof
     Create an alias to an instance pointer, cast to another class.

   • Instance defers

     ‘defer’ ( -  ) oof
     Create an instance defer

   • Method selectors

     ‘early’ ( -  ) oof
     Create a method selector for early binding.

     ‘method’ ( -  ) oof
     Create a method selector.

   • Class-wide variables

     ‘static’ ( -  ) oof
     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


File: gforth.info,  Node: Mini-OOF,  Next: Mini-OOF2,  Prev: OOF,  Up: Object-oriented Forth

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

* Menu:

* Basic Mini-OOF Usage::
* Mini-OOF Example::
* Mini-OOF Implementation::


File: gforth.info,  Node: Basic Mini-OOF Usage,  Next: Mini-OOF Example,  Prev: Mini-OOF,  Up: Mini-OOF

6.27.5.1 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 is the base class of all objects.

‘method’ ( m v "name" - m' v  ) mini-oof2
   Define a selector NAME; increments the number of selectors M (in
bytes).

‘var’ ( m v size "name" - m v'  ) mini-oof2
   define an instance variable with SIZE bytes by the name NAME, and
increments the amount of storage per instance M by SIZE.

‘class’ ( class - class methods vars  ) mini-oof2
   start a class definition with superclass CLASS, putting the size of
the methods table and instance variable space on the stack.

‘end-class’ ( class methods vars "name" -  ) mini-oof2
   finishs a class definition and assigns a name NAME to the newly
created class.  Inherited methods are copied from the superclass.

‘defines’ ( xt class "name" -  ) mini-oof
   Bind XT to the selector NAME in class CLASS.

‘new’ ( class - o  ) mini-oof
   Create a new incarnation of the class CLASS.

‘::’ ( class "name" -  ) mini-oof "double-colon"
   Compile the method for the selector NAME of the class CLASS (not
immediate!).


File: gforth.info,  Node: Mini-OOF Example,  Next: Mini-OOF Implementation,  Prev: Basic Mini-OOF Usage,  Up: Mini-OOF

6.27.5.2 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 explicitly.

     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


File: gforth.info,  Node: Mini-OOF Implementation,  Prev: Mini-OOF Example,  Up: Mini-OOF

6.27.5.3 ‘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


File: gforth.info,  Node: Mini-OOF2,  Next: Comparison of object models,  Prev: Mini-OOF,  Up: Object-oriented Forth

6.27.6 Mini-OOF2
----------------

Mini-OOF2 is very similar to Mini-OOF in many respects, but differs
significantly in a few aspects.  In particular, Mini-OOF2 has a current
object variable, and uses the primitives ‘>o’ and ‘o>’ to manipulate
that object stack.  All method invocations and instance variable
accesses refer to the current object.

‘>o’ ( c-addr - r:c-old ) new "to-o"
   Set the current object to C_ADDR, the previous current object is
pushed to the return stack

‘o>’ ( r:c-addr - ) new "o-restore"
   Restore the previous current object from the return stack

   To ease passing an object pointer to method invocation or instance
variable accesses, the additional recognizer ‘rec-moof2’ is activated.

‘rec-moof2’ ( c-addr u - nt translate-moof2 | translate-none  ) mini-oof2 "rec-moof-two"
   This recognizer recognizes ‘.word’ (if word is visible) and the
translation is equivalent to ‘>o word o>’.

   To assign methods to selectors, use XT CLASS ‘is’ SELECTOR, so no
‘defines’ necessary.  For early binding of methods, instead of ‘::’ you
use ‘defers’:

     [ class ] defers selector

   Instead of writing

     :noname code ; class is selector

   you can also use the syntactic sugar

     class :method selector code ;

‘:method’ ( class "name" -  ) gforth-experimental "colon-method"
   define a noname that is assigned to the deferred word NAME in CLASS
at ‘;’.


File: gforth.info,  Node: Comparison of object models,  Prev: Mini-OOF2,  Up: Object-oriented Forth

6.27.7 Comparison of 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).

   A number of Forth object-oriented models were inspired by Neon (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.  By contrast, all models discussed in
     this manual have objects on the stack, leading to a ‘_object
     selector_’ syntax.

   • 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.  In ‘oof.fs’ there is also parsing of the input
     stream, in the other models this does not happen for regular
     selector invocations.

   • It allows using every selector on every object; this eliminates the
     need for interfaces, but makes it harder to create efficient
     implementations.  The models included with Gforth typically only
     support using selectors on objects of certain classes, with
     surprising and usually unpleasant results if you use a selector on
     other objects (or other things).

   Another difference between object models is whether they have an
active object such as ‘this’ in ‘objects.fs’.  ‘mini-oof.fs’ does not
have an active object, and uses the top-of-stack as the object for
instance variables and the selector.

   And if they have an active object, there are differences in what sets
or changes it, and what make use of the active object.

   • In ‘objects.fs’ ‘this’ is only changed on method invocation (i.e.,
     by ‘m: ... ;m’; note the possible separation between methods and
     selectors in ‘objects.fs’), and restored when leaving the method.
     Only instance variables use ‘this’, while selectors take their
     object from the stack.

   • In ‘mini-oof2.fs’ only ‘>o ... o>’ changes the active object, and
     both selectors and instance variables use the active object as the
     object for which the selector is invoked, or the instance variable
     accessed.  However, ‘mini-oof2.fs’ has a recognizer that recognizes
     ‘.word’ and executes/compiles/postpones code equivalent to ‘>o word
     >o’, so you can use it like ‘objects.fs’ by always invoking
     selectors with a prefixed ‘.’, and never invoke instance variables
     in that way.

   • In ‘oof.fs’ selector/method invocation changes the active object,
     like in ‘object.fs’, but it also has ‘>o ... o>’ like
     ‘mini-oof2.fs’ (but without a helping recognizer).

   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 (like in ‘mini-oof2.fs’; you have to change
the active object explicitly with ‘{ ... }’ (similar to how you use ‘>o
... o>’ in ‘oof.fs’ and ‘mini-oof2.fs’).  A Standard 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).

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


File: gforth.info,  Node: Closures,  Next: Regular Expressions,  Prev: Object-oriented Forth,  Up: Words

6.28 Closures
=============

Gforth provides flat closures (called closures in the following).
Closures are similar to quotations (*note Quotations::), but the
execution token (xt) that represents a closure does not just refer to
code, but also to data.  Running the code of a closure definition
creates a closure data structure (also referred to as "closure"), that
is represented by an execution token.  The closure data structure needs
to be allocated somewhere, and in Gforth this memory is managed
explicitly.

   As an example, consider a word that sums up the results of a function
‘( n -- r)’ across a range of input values:

     : sum {: limit start xt -- r :}
       0e limit start ?do
         i xt execute f+
       loop ;

   You can add up the values of the function 1/n for n=1..10 with:

     11 1 [: s>f -1e f** ;] sum f.

   Yes, you can do it shorter and more efficiently with ‘1/f’, but bear
with me.  If you want to add up 1/n^2, you can write

     11 1 [: s>f -2e f** ;] sum f.

   Now if you want to deal with additional exponents and these exponents
are known at compile time, you can create a new quotation for every
exponent.  But you may prefer to provide an exponent and produce an xt
without having to write down a quotation every time.  If the value of
the exponent is only known at run-time, producing such an xt is possible
in Forth, but even more involved, and consumes dictionary memory (with
limited deallocation options).  Closures come to the rescue:

     : 1/n^r ( r -- xt; xt execution: n -- r1 )
       fnegate [f:h ( n -r ) s>f fswap f** ;] ;

     11 1 3e   1/n^r dup >r sum f. r> free-closure
     11 1 0.5e 1/n^r dup >r sum f. r> free-closure

   When ‘1/n^r’ runs, it creates a closure that incorporates a
floating-point number (indicated by the ‘f’ in ‘[f:h’), in particular
the value -r.  It also references the code between ‘[f:h’ and ‘;]’.  The
memory for the closure comes from the heap, i.e.  ‘allocate’d memory
(indicated by the ‘h’ in ‘[f:h’).  ‘1/n^r’ produces an xt representing
this closure.  This xt is then passed to ‘sum’ and ‘execute’d there.

   When the closure is executed (in ‘sum’), -r is pushed (in addition to
the n that has already been pushed before the ‘execute’) and the code of
the closure is run.

   The code above shows a pure-stack closure (no locals involved).
Pure-stack closures start with a word with the naming scheme ‘[T:A’
where the type T can be ‘n’ (cell), ‘d’ (double-cell), or ‘f’ (FP). The
allocator A can be ‘l’ (local), ‘d’ (dictionary), ‘h’ (heap), or ‘h1’:
‘Allocate’ the closure on the heap and ‘free’ it after the first
execution; this is used for passing data to another task with
‘send-event’ (*note Message queues::).  A pure-stack closure consumes
one T from a stack at closure creation time (when the code containing
the closure definition is run), and pushes an xt.  After creating the
closure, execution continues behind the ‘;]’.

   When the xt is executed (directly with ‘execute’ or indirectly
through, e.g., ‘compile,’ or a deferred word), it pushes the stack item
that was consumed at closure creation time and then runs the code inside
the closure definition (up to the ‘;]’).  You can deallocate
heap-allocated closures with

‘free-closure’ ( xt -  ) gforth-1.0
   Free the heap-allocated closure xt.

   Like a quotation, a (flat) closure cannot access locals of the
enclosing definition(s).

   The words for starting pure-stack closure definitions are:

‘[n:l’ ( compilation - colon-sys; run-time: n - xt ; xt execution: - n  ) gforth-1.0 "open-bracket-n-colon-l"

‘[d:l’ ( compilation - colon-sys; run-time: d - xt ; xt execution: - d  ) gforth-1.0 "open-bracket-d-colon-l"

‘[f:l’ ( compilation - colon-sys; run-time: r - xt ; xt execution: - r  ) gforth-1.0 "open-bracket-r-colon-l"

‘[n:d’ ( compilation - colon-sys; run-time: n - xt ; xt execution: - n  ) gforth-1.0 "open-bracket-n-colon-d"

‘[d:d’ ( compilation - colon-sys; run-time: d - xt ; xt execution: - d  ) gforth-1.0 "open-bracket-d-colon-d"

‘[f:d’ ( compilation - colon-sys; run-time: r - xt ; xt execution: - r  ) gforth-1.0 "open-bracket-r-colon-d"

‘[n:h’ ( compilation - colon-sys; run-time: n - xt ; xt execution: - n  ) gforth-1.0 "open-bracket-n-colon-h"

‘[d:h’ ( compilation - colon-sys; run-time: d - xt ; xt execution: - d  ) gforth-1.0 "open-bracket-d-colon-h"

‘[f:h’ ( compilation - colon-sys; run-time: r - xt ; xt execution: - r  ) gforth-1.0 "open-bracket-r-colon-h"

‘[n:h1’ ( compilation - colon-sys; run-time: n - xt ; xt execution: - n  ) gforth-1.0 "open-bracket-n-colon-h1"

‘[d:h1’ ( compilation - colon-sys; run-time: d - xt ; xt execution: - d  ) gforth-1.0 "open-bracket-d-colon-h1"

‘[f:h1’ ( compilation - colon-sys; run-time: r - xt ; xt execution: - r  ) gforth-1.0 "open-bracket-r-colon-h1"

   If you want to pass more than one stack item from closure creation to
execution time, defining more such words becomes unwieldy, and the code
inside the closure definition might have to juggle many stack items, so
Gforth does not provide such additional words.  Instead, Gforth offers
flat closures that define locals.  Here's the example above, but using
locals-defining closures:

     : 1/n^r ( r -- xt; xt execution: n -- r1 )
       fnegate [{: f: -r :}h s>f -r f** ;] ;

   The number, types, and order of the locals are used for specifying
how many and which stack items are consumed at closure creation time.
At closure execution time these values become the values of the locals.
The locals definition ends with a word with a naming scheme ‘:}A’, where
A specifies where the closure is allocated: ‘l’ (local), ‘d’
(dictionary), ‘h’ (heap), or ‘h1’ (heap, ‘free’ on first execution).

   Note that the locals are still strictly local to one execution of the
xt, and any changes to the locals (e.g., with ‘to’) do not change the
values stored in the closure; i.e., in the next execution of the closure
the locals will be initialized with the values that closure creation
consumed.

‘[{:’ ( compilation - hmaddr u latest wid 0 ; instantiation ... - xt  ) gforth-1.0 "start-closure"
   Starts a closure.  Closures started with ‘[{:’ define locals for use
inside the closure.  The locals-definition part ends with ‘:}l’, ‘:}h’,
‘:}h1’, ‘:}d’ or ‘:}xt’.  The rest of the closure definition is Forth
code.  The closure ends with ‘;]’.  When the closure definition is
encountered during execution (closure creation time), the values going
into the locals are consumed, and an execution token (xt) is pushed on
the stack; when that execution token is executed (with ‘execute’,
through ‘compile,’ or a deferred word), the code in the closure is
executed (closure execution time).  If the xt of a closure is executed
multiple times, the values of the locals at the start of code execution
are those from closure-creation time, unaffected by any locals-changes
in earlier executions of the closure.

‘:}l’ ( hmaddr u latest latestnt wid state 0 a-addr1 u1 ... -  ) gforth-1.0 "close-brace-locals"
   Ends a closure's locals definition.  The closure will be allocated on
the locals stack.

‘:}d’ ( hmaddr u latest latestnt wid state 0 a-addr1 u1 ... -  ) gforth-1.0 "colon-close-brace-d"
   Ends a closure's locals definition.  The closure will be allocated in
the dictionary.

‘:}h’ ( hmaddr u latest latestnt wid state 0 a-addr1 u1 ... -  ) gforth-1.0 "colon-close-brace-h"
   Ends a closure's locals definition.  At the run-time of the
surrounding definition this allocates the closure on the heap; you are
then responsible for deallocating it with ‘free-closure’.

‘:}h1’ ( hmaddr u latest latestnt wid state 0 a-addr1 u1 ... -  ) gforth-1.0 "colon-close-brace-h-one"
   Ends a closure's locals definition.  The closure is deallocated after
the first execution, so this is a one-shot closure, particularly useful
in combination with ‘send-event’ (*note Message queues::).

‘:}xt’ ( hmaddr u latest latestnt wid state 0 a-addr1 u1 ... -  ) gforth-1.0 "colon-close-brace-x-t"
   Ends a closure's locals definition.  The closure will be allocated by
the xt on the stack, so the closure's run-time stack effect is ‘( ...
xt-alloc -- xt-closure )’.

‘>addr’ ( ... xt - addr  ) gforth-internal "to-addr"
   Obtain the address ADDR of the ‘addressable:’ value-flavoured word
XT.  For some value-flavoured words, additional inputs may be consumed.

   If you look at closures in other languages (e.g., Scheme), they are
quite different: data is passed by accessing and possibly changing
locals of enclosing definitions (lexical scoping).  Gforth's closures
are based on the flat closures used in the implementation of Scheme, so
by writing the code appropriately (see the following subsections) you
can do the same things with Gforth's closures as with lexical-scoping
closures.

   In our programming we have not missed lexical scoping, except when
trying to convert code (usually textbook examples) coming from another
language.  I.e., in our experience flat closures are as useful and
similarly convenient as lexical scoping.  For comparison, if Gforth
supported lexical scoping instead of flat closures, the definition of
‘1/n^r’ might look as follows:

     \ this does not work in Gforth:
     : 1/n^r ( r -- xt; xt execution: n -- r1 )
       fnegate {: -r :} [:h s>f -r f** ;] ;

   But if you want to know how to convert lexical scoping to Gforth's
flat closures, the following subsections explain it.

* Menu:

* How do I read outer locals?::
* How do I write outer locals?::


File: gforth.info,  Node: How do I read outer locals?,  Next: How do I write outer locals?,  Prev: Closures,  Up: Closures

6.28.1 How do I read outer locals?
----------------------------------

As long as you only read the value of locals, you can duplicate them as
needed, so a way to convert an access to an outer local for flat
closures is to just pass the values on the stack to the closures and
define them again as locals there.  Here's an example: Consider the
following code for a hypothetical Gforth with a quotation-like syntax
for lexical-scoping closures:

     \ does not work; [:d would dictionary-allocate the closure
     : ...
       ... {: a b :} ...
       [:d ...
         ... {: c d :} ...
         [:d ... a b c d ... ;]
         ...
       ;]
       ... ;

   you can convert it to flat closures as follows:

     : ...
       ... {: a b :} ...
       a b [{: a b :}d ...
         ... {: c d :} ...
         a b c d [{: a b c d :}d
           ... a b c d ... ;]
         ...
       ;]
       ... ;

   Only those locals that are read in the closure need to be passed in.

   This process is called _closure conversion_ in the programming
language implementation literature.


File: gforth.info,  Node: How do I write outer locals?,  Prev: How do I read outer locals?,  Up: Closures

6.28.2 How do I write outer locals?
-----------------------------------

A local instance that is written and read must exist at only one
location, its home location.  The address of this home location is only
read and can be duplicated and passed around.  A textbook example might
look like this in a hypothetical Gforth with lexical-scoping and
explicit dictionary allocation:

     \ does not work
     : counter ( -- xt-inc xt-val )
       0 {: n :}d
       [:d n 1+ to n ;]
       [:d n ;]
     ;
     \ for usage example see below

   Instead, you allocate the home location, and pass its address around:

     : counter ( -- xt-inc xt-val )
       align here {: np :} 0 , \ home location
       np [{: np :}d 1 np +! ;]
       np [{: np :}d np @ ;]
     ;
     \ usage example
     counter \ first instance
     dup execute . \ prints 0
     over execute
     over execute
     dup execute . \ prints 2
     counter \ second instance
     over execute
     dup execute . \ prints 1
     2swap \ work on first instance again
     dup execute . \ prints 2

   This introduction of a home location is called _assignment
conversion_ in the programming language implementation literature.

   You can also use pure-stack closures in this case:

     : counter ( -- xt-inc xt-val )
       align here {: np :} 0 , \ home location
       np [n:d 1 swap +! ;]
       np [n:d @ ;]
     ;
     \ same usage

   Instead of dictionary allocation you can also ‘allocate’ on the heap.
For local allocation of the home location you can use variable-flavoured
locals (*note Gforth locals::), but of course then the closures must not
be used after leaving the definition in which the home location is
defined.  E.g.

     : counter-example ( -- )
       0 {: w^ np :} \ home location
       np [n:d 1 swap +! ;]
       np [n:d @ ;]
       dup execute cr .
       over execute
       over execute
       dup execute cr .
       2drop
     ;
     counter-example \ prints 0 and 2

   There is actually rarely a reason to use home locations at all,
because what the textbook examples do with closures and writable locals
can be done in Gforth more directly with structs (*note Structures::) or
objects (*note Object-oriented Forth::), or in the counter example,
simply with ‘create’:

     : counter ( "name" -- )
       create 0 , ;
     : counter-inc ( addr -- )
       1 swap +! ;
     : counter-val ( addr -- )
       @ ;
     \ usage example
     counter a
     a counter-val . \ prints 0
     a counter-inc
     a counter-inc
     a counter-val . \ prints 2
     counter b
     b counter-inc
     b counter-val . \ prints 1
     a counter-val . \ prints 2

   Still, for dictionary and heap allocation Gforth has a home-location
definition syntax based on the locals-definition syntax.  Here's a
heap-allocation version of ‘counter’ using closures and the locals-like
home-location syntax:

     : counter ( -- handle xt-inc xt-val )
       0 <{: w^ np :}h
       np [n:h 1 swap +! ;]
       np [n:h @ ;]
       ;> -rot ;
     \ usage example
     counter \ first instance
     dup execute . \ prints 0
     over execute
     over execute
     dup execute . \ prints 2
     counter \ second instance
     over execute
     dup execute . \ prints 1
     free-closure free-closure free throw \ back to first instance
     dup execute . \ prints 2
     free-closure free-clouse free throw

   Here ‘<{:’ starts a locals scope (similar to a closure itself), then
you define (variable-flavoured) locals.  ‘:}h’ (or ‘:}d’) finishes the
locals definition.  Now (and up to ‘;>’) you can use the names of the
defined locals.  Finally, ‘;>’ ends the scope and pushes the start
address of the allocated home-location block (also when using ‘:}d’ for
dictionary allocation), for ‘free’ing the home-location block later.

   We have produced no uses of ‘<{:’ and ‘;>’ in the first 6 years that
they were present in (development) Gforth.  We think that the reason is
that one prefers structs or objects for modifiable data.  Therefore, we
intend to remove these words in the future.  If you want to see them
preserved, contact us and make a case for them.

‘<{:’ ( compilation - colon-sys ; run-time -  ) gforth-obsolete "start-homelocation"
   Starts defining a home location block.

‘;>’ ( compilation colon-sys - ; run-time - addr  ) gforth-obsolete "end-homelocation"
   Ends defining a home location; addr is the start address of the
home-location block (used for deallocation).


File: gforth.info,  Node: Regular Expressions,  Next: Programming Tools,  Prev: Closures,  Up: Words

6.29 Regular Expressions
========================

Regular expressions are pattern matching algorithms for strings found in
many contemporary languages.  You can add regular expression
functionality to Gforth with ‘require regexp.fs’.

   However, the regexp support does not use any of the established
regexp syntaxes; instead, the syntax is described below.  Here's an
example of how it is used:

     charclass [bl-]   blanks +class '-' +char

     : telnum ( addr u -- flag )
         (( {{ ` (  \( \d \d \d \) ` ) || \( \d \d \d \) }}  \s
         \( \d \d \d \) [bl-] c?
         \( \d \d \d \d \) )) ;

     : ?tel ( addr u -- )
       telnum IF
         '(' emit \1 type ." ) " \2 type '-' emit \3 type ."  succeeded"
       ELSE
         \0 type ."  failed"
       THEN ;

     s" (555) 555-5555abc" ?tel \ prints "(555) 555-5555 succeeded"
     s" (555) 555-555abc"  ?tel \ prints "(555) 555-555abc failed"

   More examples can be found in ‘test/regexp-test.fs’.

   Your regular expression code is enclosed in ‘((’ and ‘))’.

‘((’ ( addr u -  ) regexp-pattern "paren-paren"
   start regexp block

‘))’ ( - flag  ) regexp-pattern "close-paren-close-paren"
   end regexp block

   Pattern matching in regular expressions have character sets as
elements, so a number of functions allow you to create and modify
character sets (called ‘charclass’).  All characters here are bytes, so
this doesn't extend to unicode characters.

‘charclass’ ( -  ) regexp-cg
   Create a charclass

‘+char’ ( char -  ) regexp-cg "plus-char"
   add a char to the current charclass

‘-char’ ( char -  ) regexp-cg
   remove a char from the current charclass

‘..char’ ( start end -  ) regexp-cg "dot-dot-char"
   add a range of chars to the current charclass

‘+chars’ ( addr u -  ) regexp-cg "plus-chars"
   add a string of chars to the current charclass

‘+class’ ( class -  ) regexp-cg "plus-class"
   union of charclass CLASS and the current charclass

‘-class’ ( class -  ) regexp-cg
   subtract the charclass CLASS from the current charclass

   There are predefined charclasses and tests for them, and generic
checks.  If a check fails, the next possible alternative of the regular
expression is tried, or a loop is terminated.

‘c?’ ( addr class -  ) regexp-pattern "c-question"
   check ADDR for membership in charclass CLASS

‘-c?’ ( addr class -  ) regexp-pattern "-c-question"
   check ADDR for not membership in charclass CLASS

‘\d’ ( addr - addr'  ) regexp-pattern "backslash-d"
   check for digit

‘\s’ ( addr - addr'  ) regexp-pattern "backslash-s"
   check for blanks

‘.?’ ( addr - addr'  ) regexp-pattern "dot-question"
   check for any single charachter

‘-\d’ ( addr - addr'  ) regexp-pattern "-backslash-d"
   check for not digit

‘-\s’ ( addr - addr'  ) regexp-pattern "-backslash-s"
   check for not blank

‘`’ ( "char" -  ) regexp-pattern "backtick"
   check for particular char

‘`?’ ( "char" -  ) regexp-pattern "backtick-question"

‘-`’ ( "char" -  ) regexp-pattern "-backtick"
   check for particular char

   You can certainly also check for start and end of the string, and for
whole string constants.

‘\^’ ( addr - addr  ) regexp-pattern "backslash-caret"
   check for string start

‘\$’ ( addr - addr  ) regexp-pattern "backslash-dollar"
   check for string end

‘str=?’ ( addr1 addr u - addr2  ) regexp-pattern "str-equals-question"
   check for a computed string on the stack (possibly a backreference)

‘="’ ( <string>" -  ) regexp-pattern "equals-quote"
   check for string

   Loops that check for repeated character sets can be greedy or
non-greedy.

‘{**’ ( addr - addr addr  ) regexp-pattern "begin-greedy-star"
   greedy zero-or-more pattern

‘**}’ ( sys -  ) regexp-pattern "end-greedy-star"
   end of greedy zero-or-more pattern

‘{++’ ( addr - addr addr  ) regexp-pattern "begin-greedy-plus"
   greedy one-or-more pattern

‘++}’ ( sys -  ) regexp-pattern "end-greedy-plus"
   end of greedy one-or-more pattern

‘{*’ ( addr - addr addr  ) regexp-pattern "begin-non-greedy-star"
   non-greedy zero-or-more pattern

‘*}’ ( addr addr' - addr'  ) regexp-pattern "end-non-greedy-star"
   end of non-greedy zero-or-more pattern

‘{+’ ( addr - addr addr  ) regexp-pattern "begin-non-greedy-plus"
   non-greedy one-or-more pattern

‘+}’ ( addr addr' - addr'  ) regexp-pattern "end-non-greedy-plus"
   end of non-greedy one-or-more pattern

   Example: Searching for a substring really is a non-greedy match of
anything in front of it.

‘//’ ( -  ) regexp-pattern "slash-slash"
   search for string

   Alternatives are written with

‘{{’ ( addr - addr addr  ) regexp-pattern "begin-alternatives"
   Start of alternatives

‘||’ ( addr addr - addr addr  ) regexp-pattern "next-alternative"
   separator between alternatives

‘}}’ ( addr addr - addr  ) regexp-pattern "end-alternatives"
   end of alternatives

   You can use up to 9 variables named ‘\1’ to ‘\9’ to refer to matched
substrings

‘\(’ ( addr - addr  ) regexp-pattern "backslash-paren"
   start of matching variable; variables are referred as \\1-9

‘\)’ ( addr - addr  ) regexp-pattern "backslash-close-paren"
   end of matching variable

‘\0’ ( - addr u  ) regexp-pattern "backslash-zero"
   the whole string

   Certainly, you can also write code to replace patterns you found.

‘s>>’ ( addr - addr  ) regexp-replace "s-to-to"
   Start replace pattern region

‘>>’ ( addr - addr  ) regexp-replace "to-to"
   Start arbitrary replacement code, the code shall compute a string on
the stack and pass it to ‘<<’

‘<<’ ( run-addr addr u - run-addr  ) regexp-replace "less-less"
   Replace string from start of replace pattern region with ADDR U

‘<<"’ ( "string<">" -  ) regexp-replace "less-less-quote"
   Replace string from start of replace pattern region with STRING

‘s//’ ( addr u - ptr  ) regexp-replace "s-slash-slash"
   start search/replace loop

‘//s’ ( ptr -  ) regexp-replace "slash-slash-s"
   search end

‘//o’ ( ptr addr u - addr' u'  ) regexp-replace "slash-slash-o"
   end search/replace single loop

‘//g’ ( ptr addr u - addr' u'  ) regexp-replace "slash-slash-g"
   end search/replace all loop

   The classical implementation for this pattern matching is a
backtracking algorithm, which is also necessary if you want to have
features like backreferencing.  Gforth implements regular expressions by
providing a language to define backtracking programs for pattern
matching.  Basic element is the control structure ‘FORK’ ... ‘JOIN’,
which is a forward call within a word, and therefore allows to code a
lightweight try and fail control structure.

‘FORK’ ( compilation - orig ; run-time f -  ) gforth-0.7
   AHEAD-like control structure: calls the code after JOIN.

‘JOIN’ ( orig -  ) gforth-0.7
   THEN-like control structure for FORK

   You can program any sort of arbitrary checks yourself by computing a
flag and ‘?LEAVE’ when the check fails.


File: gforth.info,  Node: Programming Tools,  Next: Multitasker,  Prev: Regular Expressions,  Up: Words

6.30 Programming Tools
======================

* Menu:

* Text interpreter status::
* Locating source code definitions::  and editing
* Locating uses of a word::     ‘where’.
* Locating backtrace entry source::
* Examining compiled code::     ‘see’ and friends.
* Examining data::              Stacks and Memory.
* Forgetting words::            Usually before reloading.
* Debugging::                   By inserting ‘~~’ tracers.
* Assertions::                  Making your programs self-checking.
* Singlestep Debugger::         Executing your program word by word.
* Code Coverage::               Measure execution frequency.
* Standard Report::
* Stack depth changes::

See also *note Emacs and Gforth::.


File: gforth.info,  Node: Text interpreter status,  Next: Locating source code definitions,  Prev: Programming Tools,  Up: Programming Tools

6.30.1 Text interpreter status
------------------------------

In interactive usage Gforth shows the status after processing each line.
The status consists of the "prompt" behind the end of the output of the
words on the line and optionally a status bar at the bottom (on by
default if the terminal is a color terminal).

   The prompt shows the current text interpreter state (‘ok’
(interpretation), ‘compiling’, or ‘postponing’) and the number of items
on the data stack (nothing shown if empty) and the FP stack (nothing
shown if empty).  E.g., if there are two items on the data stack and one
item on the FP stack, ‘2 f:1’ is shown.

   The status bar is in blue for interpretation, magenta for
compilation, and red for postponing state.  By default it shows the
contents of ‘base’ in decimal (not shown when the base is decimal), the
number of items on the data stack and the top items of the data stack,
the number of items on the FP stack, and the top items on the FP stack,
the search order and the current wordlist.  What is shown can be changed
by changing the contents of ‘status-xts’, but that is currently not
documented, apart from turning the status bar off completely:

‘-status’ ( -  ) gforth-1.0 ""minus-status""
   Turn off the status bar at the bottom of the screen

‘+status’ ( -  ) gforth-1.0 "plus-status"
   Turn on the status bar at the bottom of the screen


File: gforth.info,  Node: Locating source code definitions,  Next: Locating uses of a word,  Prev: Text interpreter status,  Up: Programming Tools

6.30.2 Locating source code definitions
---------------------------------------

Many programming systems are organized as an integrated development
environment (IDE) where the editor is the hub of the system, and allows
building and running programs.  If you want that, Gforth has it, too
(*note Emacs and Gforth::).

   However, several Forth systems have a different kind of IDE: The
Forth command line is the hub of the environment; you can view the
source from there in various ways, and call an editor if needed.

   Gforth also implements such an IDE. It mostly follows the conventions
of SwiftForth where they exist, but implements features beyond them.

   An advantage of this approach is that it allows you to use your
favourite editor: set the environment variable ‘EDITOR’ to your
favourite editor, and the editing commands will call that editor; Gforth
invokes some GUI editors in the background (so you do not need to finish
editing to continue with your Forth session), terminal editors in the
foreground (default for editors not known to Gforth is foreground).  If
you have not set ‘EDITOR’, the default editor is ‘vi’.

‘locate’ ( "name" -  ) gforth-1.0
   Show the source code of the word name, set the current location
there, and then call ‘fancy-after-l’ for navigating the displayed
source.

‘fancy-after-l’ ( c-addr1 u1 lineno1 - c-addr2 u2 lineno2  ) gforth-internal
   Wait for keyboard input.  If any other key than one of those
mentioned below is pressed (in particular, if <ESC> or <newline> is
pressed), ‘fancy-after-l’ terminates; you can then reenter the
‘fancy-after-l’ mode with ‘l’.
<cursor-up>, <Ctrl-p>, or <k>: Show one more line at the top.
<Cursor-down>, <ctrl-n>, or <j>: Show one more line at the bottom.
<Page-up> or <ctrl-u>: Show half of the terminal height more lines at
the top.
<Page-down> or <ctrl-d>: Show half of the terminal height more lines at
the bottom.
<Ctrl-b>: Scroll up by a full terminal height of source code, with only
one line of overlap.
<Space>: Scroll down by a full terminal height of source code, with only
one line of overlap.
<Cursor-right> or <l>: Switch to the next ‘where’, ‘browse’ or backtrace
result.
<Cursor-left> or <h>: Switch to the previous ‘where’, ‘browse’ or
backtrace result.
<Ctrl-l>: Redisplay the currently shown source code.

‘xt-locate’ ( nt/xt -  ) gforth-1.0
   Show the source code of the word xt, set the current location there,
and then call ‘fancy-after-l’ for navigating the displayed source.

   The _current location_ is set by a number of other words in addition
to ‘locate’.  Also, when an error happens while loading a file, the
location of the error becomes the current location.

   A number of words work with the current location:

‘l’ ( -  ) gforth-1.0
   Display source code lines at the current location, then call
‘fancy-after-l’ for navigating the displayed source.

‘n’ ( -  ) gforth-1.0
   Display lines behind the current location, or behind the last ‘n’ or
‘b’ output (whichever was later).

‘b’ ( -  ) gforth-1.0
   Display lines before the current location, or before the last ‘n’ or
‘b’ output (whichever was later).

‘g’ ( -  ) gforth-1.0
   Enter the editor at the current location, or at the start of the last
‘n’ or ‘b’ output (whichever was later).

   You can control how many lines ‘l’, ‘n’ and ‘b’ show by changing the
values:

‘before-locate’ ( - u  ) gforth-1.0
   number of lines shown before current location (default 3).

‘after-locate’ ( - u  ) gforth-1.0
   number of lines shown after current location (default 12).

   Finally, you can directly go to the source code of a word in the
editor with

‘edit’ ( "name" -  ) gforth-1.0
   Enter the editor at the location of "name"

   You can see the definitions of similarly-named words with

‘browse’ ( "subname" -  ) gforth-1.0
   Show all places where a word with a name that contains subname is
defined (‘mwords’-like, *note Word Lists::).  You can then use ‘ww’,
‘nw’ or ‘bw’ (*note Locating uses of a word::) to inspect specific
occurrences more closely.


File: gforth.info,  Node: Locating uses of a word,  Next: Locating backtrace entry source,  Prev: Locating source code definitions,  Up: Programming Tools

6.30.3 Locating uses of a word
------------------------------

‘where’ ( "name" -  ) gforth-1.0
   Show all places where name is used (text-interpreted).  You can then
use ‘ww’, ‘nw’ or ‘bw’ to inspect specific occurrences more closely.
Gforth's ‘where’ does not show the definition of name; use ‘locate’ for
that.

‘ww’ ( u -  ) gforth-1.0
   Show the source code of the ‘where’ or ‘browse’ result with index u
(indices are shown at the right edge of each line in ‘where’ or ‘browse’
output), set the current location there, and then call ‘fancy-after-l’
for navigating the displayed source (including switching to the next or
previous result).

‘nw’ ( -  ) gforth-1.0
   Show the source code of the next ‘where’ or ‘browse’ result and set
the current location there.  The "next result" wraps around to the first
result if you reach the end.  Then call ‘fancy-after-l’ for navigating
the displayed source (including switching to the next or previous
result).

‘bw’ ( -  ) gforth-1.0
   Show the source code of the previous ‘where’ or ‘browse’ result and
set the current location there.  The "previous result" wraps around to
the last result if you reach the beginning.  Then call ‘fancy-after-l’
for navigating the displayed source (including switching to the next or
previous result).

‘gg’ ( -  ) gforth-1.0
   The next ‘ww’, ‘nw’, ‘bw’, ‘tt’, ‘bt’, or ‘nt’ (but not ‘locate’,
‘edit’, ‘l’ or ‘g’) puts it result in the editor (like ‘g’) and does not
call ‘fancy-after-l’.  Use ‘gg gg’ to make this permanent rather than
one-shot.

‘ll’ ( -  ) gforth-1.0
   The next ‘ww’, ‘nw’, ‘bw’, ‘tt’, ‘bt’, or ‘nt’ (but not ‘locate’,
‘edit’, ‘l’ or ‘g’) displays in the Forth system (like ‘l’).  Use ‘ll
ll’ to make this permanent rather than one-shot.

‘whereg’ ( "name" -  ) gforth-1.0
   Like ‘where’, but puts the output in the editor.  In Emacs, you can
then use the compilation-mode commands (*note (emacs)Compilation Mode::)
to inspect specific occurrences more closely.

‘short-where’ ( -  ) gforth-1.0
   Set up ‘where’ to use a short file format (default).

‘expand-where’ ( -  ) gforth-1.0
   Set up ‘where’ to use a fully expanded file format (to pass to e.g.
editors).

‘prepend-where’ ( -  ) gforth-1.0
   Set up ‘where’ to show the file on a separate line, followed by
‘where’ lines without file names (like SwiftForth).

   The data we have on word usage also allows us to show which words
have no uses:

‘unused-words’ ( -  ) gforth-1.0
   list all words without usage


File: gforth.info,  Node: Locating backtrace entry source,  Next: Examining compiled code,  Prev: Locating uses of a word,  Up: Programming Tools

6.30.4 Locating backtrace entry source
--------------------------------------

An uncaught exception shows a backtrace (actually a return stack dump,
*note Error messages::).  If the return stack entry is a return address,
the immediately preceding location produced the call that the return
address would have returned from, and is shown as word in the backtrace.
You can inspect the source code of such a call with the following words:

‘tt’ ( u -  ) gforth-1.0
   Show the source code corresponding to the backtrace line with index u
(indices are shown in the backtrace after the file name and position
information and before the return stack content and its interpretation
as return address), set the current location there, and then call
‘fancy-after-l’ for navigating the displayed source (including switching
to the next or previous result).

‘nt’ (  -  ) gforth-1.0
   Show the source code corresponding to the next backtrace line and set
the current location there.  The "next backtrace line wraps around to
the first one if you reach the end.  Then call ‘fancy-after-l’ for
navigating the displayed source (including switching to the next or
previous result).

‘bt’ ( -  ) gforth-1.0
   Show the source code corresponding to the previous backtrace line and
set the current location there.  The "previous backtrace line" wraps
around to the last one if you reach the beginning.  Then call
‘fancy-after-l’ for navigating the displayed source (including switching
to the next or previous result).


File: gforth.info,  Node: Examining compiled code,  Next: Examining data,  Prev: Locating backtrace entry source,  Up: Programming Tools

6.30.5 Examining compiled code
------------------------------

And finally, ‘see’ and friends show compiled code.  Some of the things
in the source code are not present in the compiled code (e.g.,
formatting and comments), but this is useful to see what threaded code
or native code is produced by macros and Gforth's optimization features.

‘see’ ( "<spaces>name" -  ) tools
   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-0.2
   Decompile the definition represented by xt.

‘simple-see’ ( "name" -  ) gforth-0.6
   Decompile the colon definition name, showing a line for each cell,
and try to guess a meaning for the cell, and show that.

‘xt-simple-see’ ( xt -  ) gforth-1.0
   Decompile the colon definition xt like ‘simple-see’

‘simple-see-range’ ( addr1 addr2 -  ) gforth-0.6
   Decompile code in [addr1,addr2) like ‘simple-see’

‘see-code’ ( "name" -  ) gforth-0.7
   Like ‘simple-see’, but also shows the dynamic native code for the
inlined primitives.  For static superinstructions, it shows the
primitive sequence instead of the first primitive (the other primitives
of the superinstruction are shown, too).  For primitives for which
native code is generated, it shows the number of stack items in
registers at the beginning and at the end (e.g., ‘1->1’ means 1 stack
item is in a register at the start and at the end).  For each primitive
or superinstruction with native code, the inline arguments and component
primitives are shown first, then the native code.

‘xt-see-code’ ( xt -  ) gforth-1.0
   Decompile the colon definition xt like ‘see-code’.

‘see-code-range’ ( addr1 addr2 -  ) gforth-0.7
   Decompile code in [addr1,addr2) like ‘see-code’.

   As an example, consider the following contrived definition:

     : foo dup >r drop 5 fsin ;

   This is not particularly useful, but it demonstrates the various
variants in Gforth's code generation.  Compiling this on ‘gforth-fast’
on AMD64 and then using ‘see-code foo’ outputs:

     <foo>         dup >r     1->1
     <foo+$8>      >r    1->1
     <foo+$10>     drop    1->0
        $7FBC47873933: mov    %r13,-0x8(%r14)
        $7FBC47873937: sub    $0x8,%r14
     <foo+$18>     lit    0->1
     <foo+$20>     #5
     <foo+$28>     fsin    1->1
        $7FBC4787393B: mov    0x20(%rbx),%r13
        $7FBC4787393F: add    $0x28,%rbx
        $7FBC47873943: mov    (%rbx),%rax
        $7FBC47873946: jmp    *%rax
     <foo+$30>     ;s    1->1
        $7FBC47873948: mov    (%r14),%rbx
        $7FBC4787394B: add    $0x8,%r14
        $7FBC4787394F: mov    (%rbx),%rax
        $7FBC47873952: jmp    *%rax

   This shows two sequences: The threaded code at ‘<foo>...<foo+$30>’,
and the dynamically-generated native code at
‘$7FBC47873933’...‘$7FBC47873952’.  These two sequences are shown in an
interleaved way, ideally such that we see the threaded code of a
primitive or static superinstruction (including immediate arguments and
slots for the remaining primitives of a static superinstruction) is
followed by the native code for the primitive or static
superinstruction.  In some cases, Gforth deviates from this ideal, as we
will see.  But the important thing to remember is that the two sequences
are at different places in memory and are not interleaved there.  You
can easily see that by noticing that there is no room for the native
code between the threaded-code addresses, nor is there room for the
threaded code between the native-code addresses.

   In the example, you first see a threaded-code cell for a static
superinstruction with the components ‘dup’ and ‘>r’, starting and ending
with one data stack item in a register (‘1->1’); this is followed by the
the cell for the ‘>r’ component of the superinstruction; the latter cell
is not used, but is there, because static superinstructions are formed
only after the threaded-code layout has been determined.  Next, you see
the threaded code for ‘drop’, which starts with one data stack item in
registers and ends with no data stack items in registers (‘1->0’), i.e.,
all data stack items are in memory.

   Next, the dynamically generated native code for the superinstruction
‘dup >r’ is shown.

   There is no native code executed for ‘drop’ in the ‘1->0’ case, so no
native code is shown for ‘drop’, and that's also the reason why the
threaded code for ‘drop’ is shown before the native code for ‘dup >r’;
‘see-code’ is not clever enough to show the ‘drop’ behind that
native-code fragment.

   If you want to understand the native code shown here: the
return-stack pointer is in ‘%r14’, and the first data stack register is
‘%r13’ (i.e., the top of stack resides there if there is one data stack
item in a register).  The threaded-code instruction pointer (IP) is in
‘%rbx’ (used by ‘lit’ and ‘;s’ in this example).  Note that the register
assignments vary between builds, so you may see a different register
assignment for this code.

   Next, the threaded code for ‘lit’ is shown as well as its stack
states (‘0->1’), followed by the cell of the immediate argument ‘5’ of
‘lit’.

   Then the threaded code for ‘fsin’ is shown.  There is no
dynamically-generated native code for ‘fsin’, and ‘see-code’ does not
show the static native code for this word (you can look at it with ‘see
fsin’), that's why no native code is shown for ‘fsin’, and its threaded
code is shown adjacent to the previous threaded code.

   The next line is the native code for the ‘lit’, which is adjacent to
the last shown native code.  The code for ‘lit’ loads the 5 residing at
‘<foo+$20>’ with an access that uses IP (which still points to ‘<foo>’
at this point) with an offset of ‘$20’ (shown as ‘0x20’).

   Because the (static) native code for ‘fsin’ is elsewhere, code for
jumping to that native code has to be generated: First, IP is brought
up-to-date with the instruction at ‘$7FBC4787393F’ and after that IP
points to ‘<foo+$28>’.  The instruction at ‘$7FBC47873943’ loads the
code address of ‘fsin’ from IP, and the next instruction jumps to that
code address, executing ‘fsin’.  These two instructions constitute a
direct-threaded code dispatch (NEXT1).

   Next, we see the threaded code of ‘;s’ (the primitive compiled for
‘;’ in ‘foo’), and then the dynamically generated native code for ‘;s’:
It loads IP from the return stack and updates the return stack pointer.
Because it performs control flow, ‘;s’ has to end in a direct-threaded
code dispatch.


File: gforth.info,  Node: Examining data,  Next: Forgetting words,  Prev: Examining compiled code,  Up: Programming Tools

6.30.6 Examining data
---------------------

The following words inspect the stack non-destructively:

‘...’ ( x1 .. xn - x1 .. xn  ) gforth-1.0 "dot-dot-dot"
   Display the number of items on the data stack, followed by the items
(but not more than specified by ‘maxdepth-.s’; TOS is the right-most
item.  For each item, and in some cases, for a group of items, ‘...’
tries to guess the type and displays it accordingly (smart ‘.s’).

‘.s’ ( -  ) tools "dot-s"
   Display the number of items on the data stack, followed by the top
items (but not more than specified by ‘maxdepth-.s’; TOS is the
right-most item.  Each item is displayed as a number.

‘f.s’ ( -  ) gforth-0.2 "f-dot-s"
   Display the number of items on the floating-point stack, followed by
a list of the items (but not more than specified by ‘maxdepth-.s’; TOS
is the right-most item.

‘f.s-precision’ ( - u  ) gforth-1.0 "f-dot-s-precision"
   A ‘value’.  U is the field width for f.s output.  Other precision
details are derived from that value.

‘maxdepth-.s’ ( - addr  ) gforth-0.2 "maxdepth-dot-s"
   A variable containing 9 by default.  ‘.s’ and ‘f.s’ display at most
that many stack items.

   There is a word ‘.r’ but it does not display the return stack!  It is
used for formatted numeric output (*note Simple numeric output::).

   The following words work on the stack as a whole, either by
determining the depth or by clearing them:

‘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  ) floating "f-depth"
   +n is the current number of (floating-point) values on the
floating-point stack.

‘clearstack’ ( ... -  ) gforth-0.2 "clear-stack"
   remove and discard all/any items from the data stack.

‘fclearstack’ ( r0 .. rn -  ) gforth-1.0 "f-clearstack"
   clear the floating point stack

‘clearstacks’ ( ... -  ) gforth-0.7 "clear-stacks"
   empty data and FP 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.


File: gforth.info,  Node: Forgetting words,  Next: Debugging,  Prev: Examining data,  Up: Programming Tools

6.30.7 Forgetting words
-----------------------

Forth allows you to forget words (and everything that was allotted in
the dictionary after them) in a LIFO manner.

‘marker’ ( "<spaces> name" -  ) core-ext
   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 program 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
     [THEN]

     marker my-code
     init-included-files

     \ .. definitions start here
     \ .
     \ .
     \ end


File: gforth.info,  Node: Debugging,  Next: Assertions,  Prev: Forgetting words,  Up: Programming Tools

6.30.8 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 ‘.debugline’ 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).

‘~~’ ( -  ) gforth-0.2 "tilde-tilde"
   Prints the source code location of the ‘~~’ and the stack contents
with ‘.debugline’.

‘printdebugdata’ ( -  ) gforth-0.2 "print-debug-data"

‘.debugline’ ( nfile nline -  ) gforth-0.6 "print-debug-line"
   Print the source code location indicated by NFILE NLINE, and
additional debugging information; the default ‘.debugline’ prints the
additional information with ‘printdebugdata’.

‘debug-fid’ ( - file-id  ) gforth-1.0 "File-id"
   Output file for debugging words.  By default it is the process's
‘stderr’.

   ‘~~’ (and assertions) will usually print the wrong file name if a
marker is executed in the same file after their occurrence.  They will
print ‘*somewhere*’ as file name if a marker is executed in the same
file before their occurrence.

‘once’ ( -  ) gforth-1.0
   do the following up to THEN only once

‘~~bt’ ( -  ) gforth-1.0 "tilde-tilde-bt"
   print stackdump and backtrace

‘~~1bt’ ( -  ) gforth-1.0 "tilde-tilde-one-bt"
   print stackdump and backtrace once

‘???’ ( -  ) gforth-0.2 "question-question-question"
   Open a debuging shell

‘WTF??’ ( -  ) gforth-1.0 "WTF-question-question"
   Open a debugging shell with backtrace and stack dump

‘!!FIXME!!’ ( -  ) gforth-1.0 "store-store-FIXME-store-store"
   word that should never be reached

‘replace-word’ ( xt1 xt2 -  ) gforth-1.0
   make xt2 do xt1, both need to be colon definitions

‘~~Variable’ ( "name" -  ) gforth-1.0 "tilde-tilde-Variable"
   Define name and reserve a cell at addr.
name execution: ‘( -- addr )’ Show a ‘~~’ tracer with ‘addr @’ on the
top of the data stack.  In all other respects name behaves like a normal
variable.

‘~~Value’ ( n "name" -  ) gforth-1.0 "tilde-tilde-Value"
   Define name with the initial value w; like ‘value’ but with tracers
on the ‘to’ and ‘+to’ actions.
name execution: ( - w2 ) push the current value of name.
‘to name’ run-time: ( w3 - ) Show a ‘~~’ tracer with the xt of name on
top of w3, then change the value of name to w3.
‘+to name’ run-time: ( n|u - ) Show a ‘~~’ tracer with the xt of name on
top of n|u, then increment the value of name by n|u.

‘+ltrace’ ( -  ) gforth-1.0 "plus-ltrace"
   turn on line tracing

‘-ltrace’ ( -  ) gforth-1.0
   turn off line tracing

‘#loc’ ( nline nchar "file" -  ) gforth-1.0 "number-loc"
   set next word's location to NLINE NCHAR in "FILE"


File: gforth.info,  Node: Assertions,  Next: Singlestep Debugger,  Prev: Debugging,  Up: Programming Tools

6.30.9 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-0.2 "assert-zero"
   Important assertions that should always be turned on.

‘assert1(’ ( -  ) gforth-0.2 "assert-one"
   Normal assertions; turned on by default.

‘assert2(’ ( -  ) gforth-0.2 "assert-two"
   Debugging assertions.

‘assert3(’ ( -  ) gforth-0.2 "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-0.2 "assert-paren"
   Equivalent to ‘assert1(’

‘)’ ( -  ) gforth-0.2 "close-paren"
   End an assertion.  Generic end, can be used for other similar
purposes

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

   Assertions (and ‘~~’) will usually print the wrong file name if a
marker is executed in the same file after their occurrence.  They will
print ‘*somewhere*’ as file name if a marker is executed in the same
file before their occurrence.

   Definitions in Standard Forth for these assertion words are provided
in ‘compat/assert.fs’.


File: gforth.info,  Node: Singlestep Debugger,  Next: Code Coverage,  Prev: Assertions,  Up: Programming Tools

6.30.10 Singlestep Debugger
---------------------------

The singlestep debugger works only with the engine ‘gforth-itc’.

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

‘break:’ ( -  ) gforth-0.4 "break-colon"

‘break"’ ( 'ccc"' -  ) gforth-0.4 "break-quote"


File: gforth.info,  Node: Code Coverage,  Next: Standard Report,  Prev: Singlestep Debugger,  Up: Programming Tools

6.30.11 Code Coverage and Execution Frequency
---------------------------------------------

If you run extensive tests on your code, you often want to figure out if
the tests exercise all parts of the code.  This is called (test)
coverage.  The file ‘coverage.fs’ contains tools for measuring the
coverage as well as execution frequency.

   Code coverage inserts counting code in every basic block
(straight-line code sequence) loaded after ‘coverage.fs’.  Each time
that code is run, it increments the counter for that basic block.  Later
you can show the source file with the counts inserted in these basic
blocks.

   A simple use of the coverage tools is as follows:

     gforth coverage.fs fib.fs -e "main .coverage bye"

   This shows the source program annotated with execution counts (and
code that is never executed in red).  A more sophisticated usgae is:

     gforth coverage.fs source.fs tests1.fs -e "save-cov bye"
     gforth coverage.fs source.fs -e "load-cov" tests2.fs -e "save-cov bye"
     gforth coverage.fs source.fs -e "load-cov" tests3.fs -e "bw-cover annotate-cov bye"

   This runs the tests in three steps, saving and restoring the coverage
information from one step to the next.  Eventually the execution counts
are put in copies of the source file(s), with an appended extension
‘.cov’ (e.g., ‘source.fs.cov’).  The counts are shown in parentheses
(due to ‘bw-cover’) rather than in color (default).

‘.coverage’ ( -  ) gforth-experimental "dot-coverage"
   Show code with execution frequencies.

‘annotate-cov’ ( -  ) gforth-experimental
   For every file with coverage information, produce a ‘.cov’ file that
has the execution frequencies inserted.  We recommend to use ‘bw-cover’
first (with the default ‘color-cover’ you get escape sequences in the
files).

   By default, the counts are shown in colour (using ANSI escape
sequences), but you can use ‘bw-cover’ to show them in parenthesized
form without escape sequences.

‘bw-cover’ ( -  ) gforth-1.0
   Print execution counts in parentheses (source-code compatible).

‘color-cover’ ( -  ) gforth-1.0
   Print execution counts in colours (default).

   You can save and reload the coverage counters in binary format, to
aggregate coverage counters across several test runs of the same
program.

‘save-cov’ ( -  ) gforth-experimental
   Save coverage counters.

‘load-cov’ ( -  ) gforth-experimental
   Load coverage counters.

   In addition, there are the following words that one may want to use
in special circumstances.

‘nocov[’ ( -  ) gforth-1.0 "nocov-bracket"
   (Immediate) Turn coverage off temporarily.

‘]nocov’ ( -  ) gforth-1.0 "bracket-nocov"
   (Immediate) End of temporary turned off coverage.

‘cov+’ ( -  ) gforth-experimental "cov-plus"
   (Immediate) Place a coverage counter here.

‘?cov+’ ( flag - flag  ) gforth-experimental "question-cov-plus"
   (Immediate) A coverage counter for a flag; in the coverage output you
see three numbers behind ‘?cov’: The first is the number of executions
where the top-of-stack was non-zero; the second is the number of
executions where it was zero; the third is the total number of
executions.

‘cov%’ ( -  ) gforth-experimental "cov-percent"
   Print the percentage of basic blocks loaded after ‘coverage.fs’ that
are executed at least once.

‘.cover-raw’ ( -  ) gforth-experimental "dot-cover-raw"
   Print raw execution counts.


File: gforth.info,  Node: Standard Report,  Next: Stack depth changes,  Prev: Code Coverage,  Up: Programming Tools

6.30.12 ‘ans-report.fs’: Report the words used, sorted by wordset
-----------------------------------------------------------------

If you want to label a Forth program as Standard Program, you must
document which wordsets the program uses.

   The ‘ans-report.fs’ tool makes it easy for you to determine which
words from which wordset and which non-standard 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 :
     (

   ‘ans-report.fs’ reports both Forth-94 and Forth-2012 wordsets.  For
words that are in both standards, it reports the wordset without suffix
(e.g., ‘CORE-EXT’).  For Forth-2012-only words, it reports the wordset
with a ‘-2012’ suffix (e.g., ‘CORE-EXT-2012’); and likewise for the
words that are Forth-94-only (i.e., that have been removed in
Forth-2012).

6.30.12.1 Caveats
.................

Loading ‘ans-report.fs’ disables the reporting of shadowed words (a
quick fix to avoid recording the shadowed words as being used).

   Note that ‘ans-report.fs’ just checks which words are used, not
whether they are used in a standard-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.

   If you load ‘ans-report.fs’ on the OS command line, then enter
interactive mode and call ‘print-ans-report’ only afterwards, the word
‘bootmessage’ is reported, most likely spuriously.  To avoid that, call
‘print-ans-report’ from the OS command line, or ‘require ans-report.fs’
interactively.


File: gforth.info,  Node: Stack depth changes,  Prev: Standard Report,  Up: Programming Tools

6.30.13 Stack depth changes during interpretation
-------------------------------------------------

Sometimes you notice that, after loading a file, there are items left on
the stack.  The tool ‘depth-changes.fs’ helps you find out quickly where
in the file these stack items are coming from.

   The simplest way of using ‘depth-changes.fs’ is to include it before
the file(s) you want to check, e.g.:

     gforth depth-changes.fs my-file.fs

   This will compare the stack depths of the data and FP stack at every
empty line (in interpretation state) against these depths at the last
empty line (in interpretation state).  If the depths are not equal, the
position in the file and the stack contents are printed with ‘~~’ (*note
Debugging::).  This indicates that a stack depth change has occurred in
the paragraph of non-empty lines before the indicated line.  It is a
good idea to leave an empty line at the end of the file, so the last
paragraph is checked, too.

   Checking only at empty lines usually works well, but sometimes you
have big blocks of non-empty lines (e.g., when building a big table),
and you want to know where in this block the stack depth changed.  You
can check all interpreted lines with

     gforth depth-changes.fs -e "' all-lines is depth-changes-filter" my-file.fs

   This checks the stack depth at every end-of-line.  So the depth
change occurred in the line reported by the ‘~~’ (not in the line
before).

   Note that, while this offers better accuracy in indicating where the
stack depth changes, it will often report many intentional stack depth
changes (e.g., when an interpreted computation stretches across several
lines).  You can suppress the checking of some lines by putting
backslashes at the end of these lines (not followed by white space), and
using

     gforth depth-changes.fs -e "' most-lines is depth-changes-filter" my-file.fs


File: gforth.info,  Node: Multitasker,  Next: C Interface,  Prev: Programming Tools,  Up: Words

6.31 Multitasker
================

* Menu:

* Pthreads::                    Native Unix multitasker
* Cilk::                        Implements Cilk-like spawn+sync

Gforth offers two multitaskers: a traditional, cooperative round-robin
multitasker (undocumented), and a multitasker based on POSIX threads
(pthreads) which allows to run several threads concurrently on
multi-core machines (documented here).  The pthread-based multi-tasker
is now marked as experimental feature, as standardization of Forth
multitaskers will likely result in changes here and there.


File: gforth.info,  Node: Pthreads,  Next: Cilk,  Prev: Multitasker,  Up: Multitasker

6.31.1 Pthreads
---------------

Many of the following words are the same as in the traditional
cooperative multi-tasker.  However, while in the cooperative
multi-tasker you can be sure that any sequence of words between two
task-switching words (e.g., ‘pause’, ‘ms’, maybe I/O words) is atomic,
POSIX threads can switch tasks everywhere (pre-emptive multitasking) or
(worse) run two tasks at the same time on different cores, often with
unintuitive memory ordering by the hardware.

   So, with pthreads, you need to use various ways to perform atomic
accesses or use some mutual exclusion mechanism when dealing with
written-to memory shared between tasks.  Alternatively, you can use
message queues, which avoid the need to deal with shared memory.

* Menu:

* Basic multi-tasking::
* Task-local data::
* Mutexes::
* Atomic memory accesses and memory ordering::
* Message queues::


File: gforth.info,  Node: Basic multi-tasking,  Next: Task-local data,  Prev: Pthreads,  Up: Pthreads

6.31.1.1 Basic multi-tasking
............................

Tasks can be created with ‘newtask’ or ‘newtask4’ with a given amount of
stack space (either all the same or each stack's size specified).  The
task returned by the following words is a single cell that serves as
reference to the task.

‘newtask’ ( stacksize - task  ) gforth-experimental
   creates task; each stack (data, return, FP, locals) has size
stacksize.

‘task’ ( ustacksize "name" -  ) gforth-experimental
   creates a task name; each stack (data, return, FP, locals) has size
ustacksize.
name execution: ( - task )

‘newtask4’ ( u-data u-return u-fp u-locals - task  ) gforth-experimental "newtask-four"
   creates task with data stack size u-data, return stack size u-return,
FP stack size u-fp and locals stack size u-locals.

   If you don't know which stack sizes to use for the task, you can use
the size(s) of the main task:

‘stacksize’ ( - u  ) gforth-experimental
   u is the data stack size of the main task.

‘stacksize4’ ( - u-data u-return u-fp u-locals  ) gforth-experimental "stacksize-four"
   Pushes the data, return, FP, and locals stack sizes of the main task.

   A task is created in an inactive state.  To let it run, you have to
activate it with one of the following words:

‘initiate’ ( xt task -  ) gforth-experimental
   Let task execute xt.  Upon return from the xt, the task terminates
itself (VFX compatible).  Use one-time executable closures (see ‘:}h1’,
*note Closures::) to pass arbitrary paramenters to a task.

   You can also do creation and initiation in one step:

‘execute-task’ ( xt - task  ) gforth-experimental
   Create a new task TASK with the same stack sizes as the main task.
Let task execute xt.  Upon return from the xt, the task terminates
itself.

   Apart from terminating by running to the end, a task can terminate
itself with ‘kill-task’.  Other tasks can terminate it with ‘kill’.

‘kill-task’ ( -  ) gforth-experimental
   Terminate the current task.

‘kill’ ( task -  ) gforth-experimental
   Terminate task.

   Tasks can also temporarily stop themselves or be stopped:

‘stop’ ( -  ) gforth-experimental
   stops the current task, and waits for events (which may restart it)

‘stop-ns’ ( timeout -  ) gforth-experimental
   Stop with timeout (in nanoseconds), better replacement for ms

‘stop-dns’ ( dtimeout -  ) gforth-experimental
   Stop with dtimeout (in nanoseconds), better replacement for ms

‘thread-deadline’ ( d -  ) gforth-experimental
   stop until absolute time D in nanoseconds, base is 1970-1-1 0:00 UTC,
but you usually will want to base your deadlines on a time you get with
‘ntime’.

   Using ‘stop-dns’ is easier to code, but if you want your task to wake
up at regular intervals rather than some time after it finished its last
piece of work, the way to go is to work with deadlines.

‘halt’ ( task -  ) gforth-experimental
   ‘Stop’ task (no difference from ‘sleep’)

‘sleep’ ( task -  ) gforth-experimental
   ‘Stop’ task (no difference from ‘halt’)

   A task restarts when the timeout is over or when another task wakes
it with:

‘wake’ ( task -  ) gforth-experimental
   Wake task

‘restart’ ( task -  ) gforth-experimental
   Wake task (no difference from ‘wake’)

   There is also:

‘pause’ ( -  ) gforth-experimental
   voluntarily switch to the next waiting task (‘pause’ is the
traditional cooperative task switcher; in the pthread multitasker, you
don't need ‘pause’ for cooperation, but you still can use it e.g.  when
you have to resort to polling for some reason).  This also checks for
events in the queue.


File: gforth.info,  Node: Task-local data,  Next: Mutexes,  Prev: Basic multi-tasking,  Up: Pthreads

6.31.1.2 Task-local data
........................

In Forth every task has essentially the same task-local data, called
"user" area (early Forth systems were multi-user systems and there often
was one user per task).  The task result of, e.g.  ‘newtask’ is the
start address of its user area.  Each task gets the user data defined by
the system (e.g., ‘base’).  You can define additional user data with:

‘User’ ( "name" -  ) gforth-0.2
   Name is a user variable (1 cell).
Name execution: ( - addr )
Addr is the address of the user variable in the current task.

‘AUser’ ( "name" -  ) gforth-0.2
   Name is a user variable containing an address (this only makes a
difference in the cross-compiler).

‘uallot’ ( n1 - n2  ) gforth-0.3
   Reserve n1 bytes of user data.  n2 is the offset of the start of the
reserved area within the user area.

‘UValue’ ( "name" -  ) gforth-1.0
   Name is a user value.
Name execution: ( - x )

‘UDefer’ ( "name" -  ) gforth-1.0
   Name is a task-local deferred word.
Name execution: ( ...  - ...  )

   There are also the following words for dealing with user data.

‘up@’ ( - a-addr ) new "up-fetch"
   Addr is the start of the user area of the current task (addr also
serves as the task identifier of the current task).

‘user'’ ( "name" - u  ) gforth-experimental "user-tick"
   U is the offset of the user variable name in the user area of each
task.

‘'s’ ( addr1 task - addr2  ) gforth-experimental "tick-s"
   With addr1 being an address in the user data of the current task,
addr2 is the corresponding address in task's user data.

   The pictured numeric output buffer is also task-local, but other
areas like dictionary or ‘PAD’ are shared.


File: gforth.info,  Node: Mutexes,  Next: Atomic memory accesses and memory ordering,  Prev: Task-local data,  Up: Pthreads

6.31.1.3 Mutexes
................

Pthreads tasks run concurrently, so they need a mechanism to coordinate
access to resources (while that is not necessary for cooperative
multitasking).

   Mutexes can only be locked by one thread at one time, all other
threads have to wait until the mutex is unlocked.

‘mutex’ ( "name" -  ) gforth-experimental
   create a named mutex name, initially unlocked.
name execution: ( - mutex )

‘lock’ ( mutex -  ) gforth-experimental
   If mutex is currently locked, wait until it is unlocked.  Lock mutex.

‘unlock’ ( mutex -  ) gforth-experimental
   Unlock mutex.

   You can ensure that you always unlock a mutex after locking it by
using:

‘critical-section’ ( xt mutex -  ) gforth-experimental
   If mutex is currently locked, wait until it is unlocked.  Lock mutex,
then execute xt.  After xt finishes (regularly, or through an
exception), unlock mutex.


File: gforth.info,  Node: Atomic memory accesses and memory ordering,  Next: Message queues,  Prev: Mutexes,  Up: Pthreads

6.31.1.4 Atomic memory accesses and memory ordering
...................................................

Atomic hardware operations perform the whole operation, without any
other task seeing an intermediate state.  These operations can be used
to synchronize tasks without using slow OS primitives, but compared to
the non-atomic sequences of operations they tend to be slow.  Atomic
operations only work correctly on aligned addresses, even on hardware
that otherwise does not require alignment.

‘atomic!@’ ( w1 a-addr - w2 ) gforth-experimental "atomic-store-fetch"
   Fetch W2 from A_ADDR, then store W1 there, combined into an atomic
operation.

‘atomic+!@’ ( u1 a-addr - u2 ) gforth-experimental "atomic-plus-store-fetch"
   Fetch W2 from A_ADDR, then increment this location by U1.  This
atomic operation is commonly known as fetch-and-add.

‘atomic?!@’ ( unew uold a-addr - uprev ) gforth-experimental "atomic-question-store-fetch"
   Fetch UPREV from A_ADDR, compare it to UOLD, and if equal, store UNEW
there.  This atomic operation is commonly known as compare-and-swap.

   There are also the non-atomic ‘!@’ and ‘+!@’ (otherwise the same
behaviour, *note Memory Access::).

   Another hardware operation is the memory barrier.  Unfortunately
modern hardware often can reorder memory operations relative to other
memory operations (as seen by a different core), and the memory barrier
suppresses this reordering for one point in the execution of the task.

‘barrier’ ( - ) gforth-experimental "barrier"
   All memory operations before the barrier are performed before any
memory operation after the barrier.


File: gforth.info,  Node: Message queues,  Prev: Atomic memory accesses and memory ordering,  Up: Pthreads

6.31.1.5 Message queues
.......................

Gforth's message queues are a variant of the actor model.

   The sending task tells the receiving task to execute an xt with the
stack effect ‘( -- )’ (an _event_ in the name of the words below; the
actor model would call these xts _messages_), and when the receiving
task is ready, it will execute the xt, possibly after other xts from its
message queue.

   The execution order between xts from different tasks is arbitrary,
the order between xts from the same task is the sending order.

   In many cases you do not just want to pass the xts of existing words,
but also parameters.  You can construct execute-once closures (defined
using ‘:}h1’, *note Closures::) to achieve that, e.g., with

     : .-in-task ( n task -- )
       >r [{: n :}h1 n . ;] r> send-event ;

     5 my-task .-in-task \ my-task prints 5

‘send-event’ ( xt task -  ) gforth-experimental
   Inter-task communication: send XT ‘( -- )’ to TASK.  TASK executes
the xt at some later point in time.  To pass parameters, construct a
one-shot closure that contains the parameters (*note Closures::) and
pass the xt of that closure.

   In order to execute xts received from other tasks, perform one of the
following words in the receiving task:

‘?events’ ( -  ) gforth-experimental "question-events"
   Execute all event xts in the current task's message queue, one xt at
a time.

‘event-loop’ ( -  ) gforth-experimental
   Wait for event xts and execute these xts when they arrive, one at a
time.  Return to waiting if no event xts are in the queue.  This word
never returns.

   Alternatively, when a task is ‘stop’ped, it is also ready for
receiving xts, and receiving an xt will not just execute the xt, but
also continue execution after the ‘stop’.


File: gforth.info,  Node: Cilk,  Prev: Pthreads,  Up: Multitasker

6.31.2 Cilk
-----------

Gforth's Cilk is a framework for dividing work between multiple tasks
running on several cores, inspired by the programming language of the
same name.  Use ‘require cilk.fs’ if you want to use Cilk.

   The idea is that you identify subproblems that can be solved in
parallel, and the framework assigns worker tasks to these subproblems.
In particular, you use one of the ‘spawn’ words for each subtask.
Eventually you need to wait with ‘cilk-sync’ for the subproblems to be
solved.

   Currently all the spawning has to happen from one task, and
‘cilk-sync’ waits for all subproblems to complete, so using the current
Gforth Cilk for recursive algorithms is not straightforward.

   Do not divide the subproblems too finely, in order to avoid overhead;
how fine is too fine depends on how uniform the run-time for the
subproblems is, but for problems with substantial run-time, having
5*‘cores’ subproblems is probably a good starting point.

‘cores’ ( - u  ) cilk
   A value containing the number of worker tasks to use.  By default
this is the number of hardware threads (with SMT/HT), if we can
determine that, otherwise 1.  If you want to use a different number,
change ‘cores’ before calling ‘cilk-init’.

‘cilk-init’ ( -  ) cilk
   Start the worker tasks if not already done.

‘spawn’ ( xt -  ) cilk
   Execute xt ( - ) in a worker task.  Use one-time executable closures
(defined using ‘:}h1’, *note Closures::) to pass arbitrary data from the
spawner to the code running in the worker.
E.g.: ‘( n r ) [{: n f: r :}h1 code ;] spawn’

‘spawn1’ ( x xt -  ) cilk "spawn-one"
   Execute xt ( x - ) in a worker task.

‘spawn2’ ( x1 x2 xt -  ) cilk "spawn-two"
   Execute xt ( x1 x2 - ) in a worker task.

‘cilk-sync’ ( -  ) cilk
   Wait for all subproblems to complete.

‘cilk-bye’ ( -  ) cilk
   Terminate all workers.


File: gforth.info,  Node: C Interface,  Next: Assembler and Code Words,  Prev: Multitasker,  Up: Words

6.32 C Interface
================

Gforth's C interface works by compiling a wrapper library that contains
C functions which take parameters from the Forth stacks and calls the C
functions.  This wrapper library is compiled by the C compiler.
Compilation results are cached, so that Gforth only needs to rerun the C
compilation if the wrapper library has to change.  This build process is
automatic, and done at the end of a interface declaration.  Gforth uses
libtool and GCC for that process.

   The C interface is now mostly complete, callbacks have been added,
but for structs, we use Forth2012 structs, which don't have independent
scopes.  The offsets of those structs are extracted from header files
with a SWIG plugin.

* Menu:

* Existing C interface libraries::
* Calling C Functions::
* Declaring C Functions::
* Calling C function pointers::
* Defining library interfaces::
* C compiler and linker options::
* Callbacks::
* C interface internals::
* Low-Level C Interface Words::
* Automated interface generation using SWIG::
* Migrating the C interface from earlier Gforth::


File: gforth.info,  Node: Existing C interface libraries,  Next: Calling C Functions,  Prev: C Interface,  Up: C Interface

6.32.1 Existing C interface libraries
-------------------------------------

Before you can call a C function, you have to declare it in some way.
To spare you the effort of writing the declarations yourself (*note
Declaring C Functions::), Gforth comes with a number of files that
contain definitions for many of the commonly-used C functions available
in Unix-based systems.  They are typically in the files
‘/usr/local/share/gforth/1.0/unix’ (possibly with ‘/usr/local’ replaced
with some other installation directory, such as ‘/usr’, and ‘1.0’
replaced with the Gforth version).

   To find whether a function you are interested in has already been
declared, you can search the ‘.fs’ files in that directory.  E.g., to
find the function ‘localtime_r()’, you can use

     grep ' localtime_r ' /usr/local/share/gforth/1.0/unix/*.fs

   and you will find it defined in ‘unix/time.fs’ with:

         c-function localtime_r localtime_r a a -- a ( time-addr tmaddr -- tmaddr )

   Here you see ‘localtime_r’ twice, first as Forth name, then as C
name.  You can now include that file from Gforth with

     require unix/time.fs

   and then call ‘localtime_r’ (the Forth name of the C function) in
Forth (*note Calling C Functions::).

   The documentation for a C function also applies to the Forth word for
the C function.

   Some of the files containing the function definitions were written
manually (in that case you see a copyright notice at the top), and in
some cases contain useful Forth words (that are, however, usually not
documented in this manual) in addition to the C functions.

   Other files were generated by automatically converting ‘.h’ files.
In that case you see a comment "\ This file has been generated [...]"
at the top of the file.  These files declare Forth words for all the
constants, structures, fields and functions that could be converted from
the ‘.h’ file.


File: gforth.info,  Node: Calling C Functions,  Next: Declaring C Functions,  Prev: Existing C interface libraries,  Up: C Interface

6.32.2 Calling C functions
--------------------------

Once a C function has been declared (*note Existing C interface
libraries::, *note Declaring C Functions::), you can call it as follows:
You push the arguments on the stack(s), and then call the word for the C
function.  The arguments have to be pushed in the same order as the
arguments appear in the C documentation (i.e., the first argument is
deepest on the stack).  Integer and pointer arguments have to be pushed
on the data stack, floating-point arguments on the FP stack; these
arguments are consumed by the called C function.

   On returning from the C function, the return value, if any, resides
on the appropriate stack: an integer return value is pushed on the data
stack, an FP return value on the FP stack, and a void return value
results in not pushing anything.  Note that most C functions have a
return value, even if that is often not used in C; in Forth, you have to
‘drop’ this return value explicitly if you do not use it.

   The C interface automatically converts between the C type and the
Forth type as necessary, on a best-effort basis (in some cases, there
may be some loss).

   As an example, consider the POSIX function ‘lseek()’:

     off_t lseek(int fd, off_t offset, int whence);

   This function takes three integer arguments, and returns an integer
argument, so a Forth call for setting the current file offset to the
start of the file could look like this:

     fd @ 0 SEEK_SET lseek -1 = if
       ... \ error handling
     then

   You might be worried that an ‘off_t’ does not fit into a cell, so you
could not pass larger offsets to lseek, and might get only a part of the
return values.  In that case, in your declaration of the function (*note
Declaring C Functions::) you should declare it to use double-cells for
the off_t argument and return value, and maybe give the resulting Forth
word a different name, like ‘dlseek’; the result could be called like
this:

     fd @ 0. SEEK_SET dlseek -1. d= if
       ... \ error handling
     then

   Passing and returning structs or unions is currently not supported by
our interface(1).

   Calling functions with a variable number of arguments (_variadic_
functions, e.g., ‘printf()’) is only supported by having you declare one
function-calling word for each argument pattern, and calling the
appropriate word for the desired pattern.

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

   (1) If you know the calling convention of your C compiler, you
usually can call such functions in some way, but that way is usually not
portable between platforms, and sometimes not even between C compilers.


File: gforth.info,  Node: Declaring C Functions,  Next: Calling C function pointers,  Prev: Calling C Functions,  Up: C Interface

6.32.3 Declaring C Functions
----------------------------

Before you can call ‘lseek’ or ‘dlseek’, you have to declare it.

   In Gforth 1.0, C function declarations have to be enclosed in a C
library definition (*note Defining library interfaces::), e.g.

     c-library lseek-lib
     ...
     end-c-library

   The declaration of a C function consists of two parts:

The C part
     is the C declaration of the function, or more typically and
     portably, a C-style ‘#include’ of a file that contains the
     declaration of the C function.

The Forth part
     declares the Forth types of the parameters and the Forth word name
     corresponding to the C function.

   For the words ‘lseek’ and ‘dlseek’ mentioned earlier, the
declarations are:

     c-library lseek-lib
     \c #define _FILE_OFFSET_BITS 64
     \c #include <sys/types.h>
     \c #include <unistd.h>
     c-function lseek lseek n n n -- n
     c-function dlseek lseek n d n -- d
     0 constant SEEK_SET \ getting the value from the .h files is complicated
     end-c-library

   The C part of the declarations is prefixed by ‘\c’, and the rest of
the line is ordinary C code.  You can use as many lines of C
declarations as you like, and they are visible for all further function
declarations.

   The Forth part declares each interface word with ‘c-function’,
followed by the Forth name of the word, the C name of the called
function, and the stack effect of the word.  The stack effect contains
an arbitrary number of types of parameters, then ‘--’, and then exactly
one type for the return value.  The possible types are:

‘n’
     single-cell signed integer

‘u’
     single-cell unsigned integer

‘a’
     address (single-cell)

‘d’
     double-cell signed integer

‘ud’
     double-cell unsigned integer

‘r’
     floating-point value

‘func’
     C function pointer

‘void’
     no value (used as return type for void functions)

‘s’
     String: On the Forth side, represented as c-addr u pair, on the C
     side represented as zero-terminated string.

‘ws’
     wide string: On the Forth side, represented as c-addr u pair
     describing an UTF-8 string; on the C side, represented as a
     zero-terminated string of ‘wchar_t’ (i.e., UTF-16 or UTF-32,
     depending on the platform).

‘t’
     tuple

‘0’
     NULL pointer (sentinel)

‘...’
     varargs (programmable)

   To deal with variadic C functions, you can declare one Forth word for
every pattern you want to use, e.g.:

     \c #include <stdio.h>
     c-function printf-nr printf s n r -- n
     c-function printf-rn printf s r n -- n

   Note that with C functions declared as variadic (or if you don't
provide a prototype), the C interface has no C type to convert to, so no
automatic conversion happens, which may lead to portability problems in
some cases.  You can add the C type cast in curly braces after the Forth
type.  This also allows to pass e.g.  structs to C functions, which in
Forth cannot live on the stack.

     c-function printfll printf s n{(long long)} -- n
     c-function pass-struct pass_struct a{*(struct foo *)} -- n

   This typecasting is not available to return values, as C does not
allow typecasts for lvalues.

‘\c’ ( "rest-of-line" -  ) gforth-0.7 "backslash-c"
   One line of C declarations for the C interface

‘c-function’ ( "forth-name" "c-name" "{type}" "--" "type" -  ) gforth-0.7
   Define a Forth word forth-name.  Forth-name has the specified stack
effect and calls the C function ‘c-name’.

‘c-value’ ( "forth-name" "c-name" "--" "type" -  ) gforth-1.0
   Define a Forth word forth-name.  Forth-name has the specified stack
effect and gives the C value of ‘c-name’.

‘c-variable’ ( "forth-name" "c-name" -  ) gforth-1.0
   Define a Forth word forth-name.  Forth-name returns the address of
‘c-name’.

   In order to work, this C interface invokes GCC at run-time and uses
dynamic linking.  If these features are not available, there are other,
less convenient and less portable C interfaces in ‘lib.fs’ and
‘oldlib.fs’.  These interfaces are mostly undocumented and mostly
incompatible with each other and with the documented C interface; you
can find some examples for the ‘lib.fs’ interface in ‘lib.fs’.


File: gforth.info,  Node: Calling C function pointers,  Next: Defining library interfaces,  Prev: Declaring C Functions,  Up: C Interface

6.32.4 Calling C function pointers from Forth
---------------------------------------------

If you come across a C function pointer (e.g., in some C-constructed
structure) and want to call it from your Forth program, you could use
the structures as described above by defining a macro.  Or you use
‘c-funptr’.

‘c-funptr’ ( "forth-name" <{>"c-typecast"<}> "{type}" "--" "type" -  ) gforth-1.0
   Define a Forth word forth-name.  Forth-name has the specified stack
effect plus the called pointer on top of stack, i.e.  ‘( {type} ptr --
type )’ and calls the C function pointer ‘ptr’ using the typecast or
struct access ‘c-typecast’.

   Let us assume that there is a C function pointer type ‘func1’ defined
in some header file ‘func1.h’, and you know that these functions take
one integer argument and return an integer result; and you want to call
functions through such pointers.  Just define

     \c #include <func1.h>
     c-funptr call-func1 {((func1)ptr)} n -- n

   and then you can call a function pointed to by, say ‘func1a’ as
follows:

     -5 func1a call-func1 .

   The Forth word ‘call-func1’ is similar to ‘execute’, except that it
takes a C ‘func1’ pointer instead of a Forth execution token, and it is
specific to ‘func1’ pointers.  For each type of function pointer you
want to call from Forth, you have to define a separate calling word.


File: gforth.info,  Node: Defining library interfaces,  Next: C compiler and linker options,  Prev: Calling C function pointers,  Up: C Interface

6.32.5 Defining library interfaces
----------------------------------

As outlines earlier (*note Declaring C Functions::), you have to wrap C
function declarations in a C library definition.

   The effect of defining a C library is that the names of the generated
files will contain that name, and when you use the interface a second
time, it will use the existing files instead of generating and compiling
them again, saving you time.  The generated file contains a hash of the
source code, so changing the declarations will cause a new compilation.
Normally these files are cached in
‘$HOME/.gforth/’ARCHITECTURE‘/libcc-named’, so if you experience
problems or have other reasons to force a recompilation, you can delete
the files there.

   Note that you should use ‘c-library’ before everything else having
anything to do with that library, as it resets some setup stuff.  The
idea is that the typical use is to put each
‘c-library’...‘end-c-library’ unit in its own file, and to be able to
include these files in any order.  All other words dealing with the C
interface are hidden in the vocabulary ‘c-lib’, which is put on top o
the search stack by ‘c-library’ and removed by ‘end-c-library’.

   Note that the library name is not allocated in the dictionary and
therefore does not shadow dictionary names.  It is used in the file
system, so you have to use naming conventions appropriate for file
systems.  The name is also used as part of the C symbols, but characters
outside the legal C symbol names are replaced with underscores.  Also,
do not call a function you declare after ‘c-library’ before you perform
‘end-c-library’!

   A major benefit of these named library interfaces is that, once they
are generated, the tools used to generated them (in particular, the C
compiler and libtool) are no longer needed, so the interface can be used
even on machines that do not have the tools installed.  The build system
of Gforth can even cross-compile these libraries, so that the libraries
are available for platforms on which build tools aren't installed.

‘c-library-name’ ( c-addr u -  ) gforth-0.7
   Start a C library interface with name c-addr u.

‘c++-library-name’ ( c-addr u -  ) gforth-1.0 "c-plus-plus-library-name"
   Start a C++ library interface with name c-addr u.

‘c-library’ ( "name" -  ) gforth-0.7
   Parsing version of ‘c-library-name’

‘c++-library’ ( "name" -  ) gforth-1.0 "c-plus-plus-library"
   Parsing version of ‘c++-library-name’

‘end-c-library’ ( -  ) gforth-0.7
   Finish and (if necessary) build the latest C library interface.


File: gforth.info,  Node: C compiler and linker options,  Next: Callbacks,  Prev: Defining library interfaces,  Up: C Interface

6.32.6 C compiler and linker options
------------------------------------

Sometimes you need to pass additional options to the C compiler for
compiling or linking a library.

   For calling some C functions, you need to link with a specific
OS-level library that contains that function.  E.g., the ‘sin’ function
requires linking a special library by using the command line switch
‘-lm’.  In our C interface you do the equivalent thing by calling
‘add-lib’ as follows:

     c-library math
     s" m" add-lib
     \c #include <math.h>
     c-function sin sin r -- r
     end-c-library

   The ‘add-lib’ call adds the ‘-lm’ to the linker command line, such
that the library ‘libm.so’ (or somesuch) is linked with the new library;
you can add as many as you need.  Finally you declare the function as
shown above.  All words inside the ‘c-library’...‘end-c-library’ can use
functions from this library (or these libraries).

‘add-lib’ ( c-addr u -  ) gforth-0.7
   Add ‘-lstring’ to the linker call for the current library, where
string is represented by c-addr u.  I.e., link with ‘libstring.so’ or
somesuch.

‘add-libpath’ ( c-addr u -  ) gforth-0.7
   Add ‘-Lstring’ to the linker call for the current library, where
string is represented by c-addr u.  I.e., add string to the directories
that are searched for C libraries specified with ‘add-lib’.

‘add-framework’ ( c-addr u -  ) gforth-1.0
   Add ‘-framework string’ (*note (gcc)Darwin Options::) to the compiler
call for the current library, where string is represented by c-addr u.

‘add-incdir’ ( c-addr u -  ) gforth-1.0
   Add ‘-Istring’ to the compiler call for the current library, where
string is represented by c-addr u.  I.e., add string to the directory
where the C compiler searches for ‘.h’ files.

‘add-cflags’ ( c-addr u -  ) gforth-1.0
   Add the string c-addr u to the currently used flags for C
compilation.

‘add-ldflags’ ( c-addr u -  ) gforth-1.0
   Add the string c-addr u to the currently used flags for C linking.


File: gforth.info,  Node: Callbacks,  Next: C interface internals,  Prev: C compiler and linker options,  Up: C Interface

6.32.7 Callbacks
----------------

In some cases you have to pass a function pointer to a C function, i.e.,
the library wants to call back to your application (and the pointed-to
function is called a callback function).  You can pass the address of an
existing C function (that you get with ‘lib-sym’, *note Low-Level C
Interface Words::), but if there is no appropriate C function, you
probably want to define the function as a Forth word.  Then you need to
generate a callback as described below:

   Callbacks use a staged approach: First you define a callback
instantiator for a certain stack effect; then you use the instantiator
to produce a C function pointer from an xt (the prototype of the C
function is derived from the Forth stack effect); and finally you can
use the resulting C function pointer in a context that needs it.

   You can generate a callback instantiator with:

‘c-callback’ ( "forth-name" "{type}" "--" "type" -  ) gforth-1.0
   Define a callback instantiator with the given signature.  The
callback instantiator forth-name ‘( xt -- addr )’ takes an XT, and
returns the ADDRess of the C function handling that callback.

‘c-callback-thread’ ( "forth-name" "{type}" "--" "type" -  ) gforth-1.0
   Define a callback instantiator with the given signature.  The
callback instantiator forth-name ‘( xt -- addr )’ takes an XT, and
returns the ADDRess of the C function handling that callback.  This
callback is safe when called from another thread

   Each instantiator can be called ‘callback#’ times, and thus can
generate that number of callbacks, with the relevant value of
‘callback#’ being the one at the time when the instantiator is defined.
I.e., you can determine that number for an instantiator by changing the
value ‘callback#’ before defining the instantiator.  In other words, you
need to follow a static allocation discipline for the callbacks.

‘callback#’ ( - n  ) gforth-experimental "callback-number"
   N is the number of instantiations that the next callback instantiator
can create.  This number can be changed with ‘to callback#’, and affects
the callback instantiators defined after this change.

   Here is an example of a callback use with all stages:

     c-library callback-test
     \c typedef void (*rr2v)(double,double);
     \c void testrr2v(rr2v f) {f(0.5,1.5);} /* function that calls a callback function f */
     c-function testrr2v testrr2v a -- void
     c-callback rr2v-callback r r -- void   \ define callback instantiator
     end-c-library
     : printrr fswap f. f. ;
     ' printrr rr2v-callback constant printrr-c \ generate a callback instance
     printrr-c testrr2v \ use the callback function pointer by passing it to testrr2v


File: gforth.info,  Node: C interface internals,  Next: Low-Level C Interface Words,  Prev: Callbacks,  Up: C Interface

6.32.8 How the C interface works
--------------------------------

For every Forth word declared with ‘c-function’, the C interface
generates a wrapper function in C that takes the Forth data from the
Forth stacks, and calls the target C function with these data as
arguments.  After the C function returns, the return value is pushed on
the appropriate stack.

   During this process, type conversion may happen between the Forth
type and the C type of an argument or return value.  E.g.  on a 64-bit
platform, if the Forth argument is (64-bit) ‘n’, and the C argument is
(32-bit) int, the ‘n’ will be cast into the int (chopping off the 32
most-significant bits), while for a return value the same relation will
lead into a sign-extension of the 32-bit int into a 64-bit ‘n’.

   The ‘\c’ lines are literally included in the C code (but without the
‘\c’), and provide the necessary declarations so that the C compiler
knows the C types and has enough information to perform the conversion.

   These wrapper functions are eventually compiled and dynamically
linked into Gforth, and then they can be called.

   The libraries added with ‘add-lib’ are used in the compile command
line to specify dependent libraries with ‘-lLIB’, causing these
libraries to be dynamically linked when the wrapper function is linked.


File: gforth.info,  Node: Low-Level C Interface Words,  Next: Automated interface generation using SWIG,  Prev: C interface internals,  Up: C Interface

6.32.9 Low-Level C Interface Words
----------------------------------

‘open-lib’ ( c-addr1 u1 - c-addr2 ) gforth-0.4 "open-lib"
   Open the (typically shared) library with the name given by c-addr1 u1
and return the handle c-addr2 (to be used by ‘lib-sym’).

‘lib-sym’ ( c-addr1 u1 c-addr2 - c-addr3 ) gforth-0.4 "lib-sym"
   C-addr3 is the address of the symbol c-addr1 u1 in the library
c_addr2 (opened with ‘open-lib’).  If the library does not contain the
symbol, c-addr3 is 0.

‘lib-error’ ( - c-addr u ) gforth-0.7 "lib-error"
   Error message for last failed ‘open-lib’ or ‘lib-sym’.

‘call-c’ ( ... w - ... ) gforth-0.2 "call-c"
   Call the C function pointed to by w.  The C function has to access
the stack itself.  The stack pointers are exported into a ptrpair
structure passed to the C function, and returned in that form.


File: gforth.info,  Node: Automated interface generation using SWIG,  Next: Migrating the C interface from earlier Gforth,  Prev: Low-Level C Interface Words,  Up: C Interface

6.32.10 Automated interface generation using SWIG
-------------------------------------------------

SWIG, the Simple Wrapper Interface Generator, is used to create C
interfaces for a lot of programming languages.  The SWIG version
extended with a Forth module can be found on github
(https://github.com/GeraldWodni/swig).

6.32.10.1 Basic operation
.........................

C-headers are parsed and converted to Forth-Sourcecode which uses the
previously describe C interface functions.

6.32.10.2 Detailed operation:
.............................

  1. Select a target, in this example we are using ‘example.h’
  2. Create an interface file for the header.  This can be used to pass
     options, switches and define variables.  In the simplest case it
     just instructs to translate all of ‘example.h’:
          %module example
          %insert("include")
          {
              #include "example.h"
          }
          %include "example.h"
  3. Use SWIG to create a ‘.fsi-c’ file.
     ‘swig -forth -stackcomments -use-structs -enumcomments -o
     example-fsi.c example.i’.
     FSI stands "Forth Source Independent" meaning it can be transferred
     to any host having a C-compiler.  SWIG is not required past this
     point.
  4. On the target machine compile the ‘.fsi-c’ file to a ‘.fsx’ (x
     stands for executable)
     ‘gcc -o example.fsx example-fsi.c’
     The compilation will resolve all constants to the values on the
     target.
  5. The last step is to run the executable and capture its output to a
     ‘.fs’ "Forth Source" file.
     ‘./example.fsx -gforth > example.fs’
     This code can now be used on the target platform.

6.32.10.3 Examples
..................

You can find some examples in SWIG's Forth Example section
(https://github.com/GeraldWodni/swig/tree/master/Examples/forth).

   A lot of interface files can be found in Forth Posix C-Interface
(https://github.com/GeraldWodni/posix) and Forth C-Interface Modules
(https://github.com/GeraldWodni/forth-c-interfaces).

   Contribution to the Forth C-Interface Module repository
(https://github.com/GeraldWodni/forth-c-interfaces) is always welcome.


File: gforth.info,  Node: Migrating the C interface from earlier Gforth,  Prev: Automated interface generation using SWIG,  Up: C Interface

6.32.11 Migrating from Gforth 0.7
---------------------------------

In Gforth 1.0 and following, you can use ‘\c’, ‘c-function’ and
‘add-lib’ only inside ‘c-library’...‘end-c-library’.  ‘add-lib’ now
always starts from a clean slate inside a ‘c-library’, so you don't need
to use ‘clear-libs’ in most cases.

   If you have a program that uses these words outside
‘c-library’...‘end-c-library’, just wrap them in
‘c-library’...‘end-c-library’.  You may have to add some instances of
‘add-lib’, however.


File: gforth.info,  Node: Assembler and Code Words,  Next: Carnal words,  Prev: C Interface,  Up: Words

6.33 Assembler and Code Words
=============================

* Menu:

* Assembler Definitions::       Definitions in assembly language
* Common Assembler::            Assembler Syntax
* Common Disassembler::
* 386 Assembler::               Deviations and special cases
* Alpha Assembler::             Deviations and special cases
* AMD64 Assembler::
* ARM A32 assembler::
* LoongArch assembler::
* MIPS assembler::              Deviations and special cases
* PowerPC assembler::           Deviations and special cases
* RISC-V assembler::
* Other assemblers::            How to write them


File: gforth.info,  Node: Assembler Definitions,  Next: Common Assembler,  Prev: Assembler and Code Words,  Up: Assembler and Code Words

6.33.1 Definitions in assembly language
---------------------------------------

Gforth provides ways to implement words in assembly language (using
‘abi-code’...‘end-code’), and also ways to define defining words that
specify the run-time behaviour of the defined words in assembly language
(using ‘;abi-code’, similar to ‘does>’, but with assembly language after
‘;abi-code’).

   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.  It does provide assemblers for several
of the architectures it runs on, though.  Moreover, you can use a
system-independent assembler in Gforth, or compile machine code directly
with ‘,’ and ‘c,’.

   A problem with the traditional words ‘code’ and ‘;code’ is that the
virtual machine registers of Gforth (the stack pointers and the virtual
machine instruction pointer) depend on the installation and engine.
Also, which registers are free to use also depends on the installation
and engine.  So any code written to run in the context of the Gforth
virtual machine is essentially limited to the installation and engine it
was developed for (it may run elsewhere, but you cannot rely on that).

   Fortunately, you can define ‘abi-code’ and ‘;abi-code’ words in
Gforth that are portable to any Gforth running on a platform with the
same calling convention (ABI); typically this means portability to the
same architecture/OS combination, sometimes crossing OS boundaries).

‘assembler’ ( -  ) tools-ext
   A vocubulary: Replaces the wordlist at the top of the search order
with the assembler wordlist.

‘init-asm’ ( -  ) gforth-0.2
   Pushes the assembler wordlist on the search order.

‘abi-code’ ( "name" - colon-sys  ) gforth-1.0 "abi-code"
   Start a native code definition that is called using the platform's
ABI conventions corresponding to the C-prototype:
     Cell *function(Cell *sp, Float **fpp);
   The FP stack pointer is passed in by providing a reference to a
memory location containing the FP stack pointer and is passed out by
storing the changed FP stack pointer there (if necessary).

‘;abi-code’ ( -  ) gforth-1.0 "semicolon-abi-code"
   Ends the colon definition, but at run-time also changes the last
defined word X (which must be a ‘create’d word) to call the following
native code using the platform's ABI convention corresponding to the C
prototype:
      Cell *function(Cell *sp, Float **fpp, Address body);
   The FP stack pointer is passed in by providing a reference to a
memory location containing the FP stack pointer and is passed out by
storing the changed FP stack pointer there (if necessary).  The
parameter body is the body of X.

‘end-code’ ( colon-sys -  ) gforth-0.2 "end-code"
   End a code definition.  Note that you have to assemble the return
from the ABI call (for ‘abi-code’) or the dispatch to the next VM
instruction (for ‘code’ and ‘;code’) yourself.

‘code’ ( "name" - colon-sys  ) tools-ext
   Start a native code definition that runs in the context of the Gforth
virtual machine (engine).  Such a definition is not portable between
Gforth installations, so we recommend using ‘abi-code’ instead of
‘code’.  You have to end a ‘code’ definition with a dispatch to the next
virtual machine instruction.

‘;code’ ( compilation. colon-sys1 - colon-sys2  ) tools-ext "semicolon-code"
   The code after ‘;code’ becomes the behaviour of the last defined word
(which must be a ‘create’d word).  The same caveats apply as for ‘code’,
so we recommend using ‘;abi-code’ instead.

‘flush-icache’ ( c-addr u - ) gforth-0.2 "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, ‘abi-code’ words etc.
will not work (reliably), either.

   The typical usage of these words can be shown most easily by analogy
to the equivalent high-level defining words:

     : foo                              abi-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>                              ;abi-code
           <high-level Forth words>           <assembler>
     ;                                  end-code

   For using ‘abi-code’, take a look at the ABI documentation of your
platform to see how the parameters are passed (so you know where you get
the stack pointers) and how the return value is passed (so you know
where the data stack pointer is returned).  The ABI documentation also
tells you which registers are saved by the caller (caller-saved), so you
are free to destroy them in your code, and which registers have to be
preserved by the called word (callee-saved), so you have to save them
before using them, and restore them afterwards.  For some architectures
and OSs we give short summaries of the parts of the calling convention
in the appropriate sections.  More reverse-engineering oriented people
can also find out about the passing and returning of the stack pointers
through ‘see abi-call’.

   Most ABIs pass the parameters through registers, but some (in
particular the most common 386 (aka IA-32) calling conventions) pass
them on the architectural stack.  The common ABIs all pass the return
value in a register.

   Other things you need to know for using ‘abi-code’ is that both the
data and the FP stack grow downwards (towards lower addresses) in
Gforth, with ‘1 cells’ size per cell, and ‘1 floats’ size per FP value.

   Here's an example of using ‘abi-code’ on the 386 architecture:

     abi-code my+ ( n1 n2 -- n )
     4 sp d) ax mov \ sp into return reg
     ax )    cx mov \ tos
     4 #     ax add \ update sp (pop)
     cx    ax ) add \ sec = sec+tos
     ret            \ return from my+
     end-code

   An AMD64 variant of this example can be found in *note AMD64
Assembler::.

   Here's a 386 example that deals with FP values:

     abi-code my-f+ ( r1 r2 -- r )
     8 sp d) cx mov  \ load address of fp
     cx )    dx mov  \ load fp
     .fl dx )   fld  \ r2
     8 #     dx add  \ update fp
     .fl dx )   fadd \ r1+r2
     .fl dx )   fstp \ store r
     dx    cx ) mov  \ store new fp
     4 sp d) ax mov  \ sp into return reg
     ret             \ return from my-f+
     end-code

   And an AMD64 example of using ‘;abi-code’:

     : myconst ( n "name" -- )
       create ,
     ;abi-code ( -- n )
       \ data stack pointer in rdi, body address of "name" in rdx
       -8 di d) ax lea \ rax = rdi-8 \ compute new data stack pointer
       dx ) cx mov     \ rcx = *rdx  \ get the value of the constant
       cx ax ) mov     \ *rax = rcx  \ and store it on the data stack
       \ data stack pointer in rax
       ret
     end-code
     5 myconst x
     x .


File: gforth.info,  Node: Common Assembler,  Next: Common Disassembler,  Prev: Assembler Definitions,  Up: Assembler and Code Words

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

   The rest of this section is of interest mainly for those who want to
define ‘code’ words (instead of the more portable ‘abi-code’ words).

   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).  If you
are using ‘CODE’ instead of ‘ABI-CODE’, and you want to refer to
Gforth's registers (e.g., the stack pointer or TOS), I recommend
defining your own words for referring to these registers, and using them
later on; then you can adapt to a changed register assignment.

   The most common use of these registers is to end a ‘code’ definition
with a 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).
When using ‘ABI-CODE’, you can just assemble a normal subroutine return
(but make sure you return the data stack pointer).

   Another difference between Gforth versions is that the top of stack
is kept in memory in ‘gforth’ and, on most platforms, in a register in
‘gforth-fast’.  For ‘ABI-CODE’ definitions, any stack caching registers
are guaranteed to be flushed to the stack, allowing you to reliably
access the top of stack in memory.


File: gforth.info,  Node: Common Disassembler,  Next: 386 Assembler,  Prev: Common Assembler,  Up: Assembler and Code Words

6.33.3 Common Disassembler
--------------------------

You can disassemble a ‘code’ word with ‘see’ (*note Debugging::).  You
can disassemble a section of memory with

‘discode’ ( addr u -  ) gforth-0.2
   hook for the disassembler: disassemble u bytes of code at addr

   By default, ‘discode’ calls one of the following words (not all of
them are available on all installations):

   • ‘disasm2’, which calls ‘libopcodes’ from the binutils.  This is
     usually the default disassembler, if Gforth is built as we
     recommend.

   • ‘disasm’, a manually written disassembler (only available on some
     architectures).  This is often the default disassembler if
     ‘disasm2’ is not available.

     The Forth 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.

   • ‘disasm-gdb’, which calls ‘gdb’ to disassemble code.
     Unfortunately, this is not a very reliable disassembler, and can
     hang.  Use ‘Ctrl-c’ if that happens.  This disassembler is used by
     default if neither ‘disasm2’ nor ‘disasm’ is available.

   • ‘dump’ shows the machine code as hex dump.  This disassembler is
     used if none of the others are available.

   You can override the default by changing ‘discode’, e.g., with

     ' disasm is discode

   ‘See’ may display more or less than the actual code of a ‘code’ word,
because the recognition of the end of the code is unreliable.  You can
use ‘discode’ if it did not display enough.  ‘See’ 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 latest ,’ to
ensure that the end is recognized.

‘disasm2’ ( c-addr u -  ) gforth-1.0 "disasm-two"
   Disassemble code block starting at c-addr with u bytes length using
‘libopcodes’ from GNU binutils.  This word is only defined if Gforth was
built with ‘libopcodes’ support.

‘intel-syntax’ ( -  ) gforth-1.0
   Change ‘disasm2’ to output Intel syntax.  This word is only defined
on AMD64 and IA-32 machines and only if Gforth was built with
‘libopcodes’ support.

‘at&t-syntax’ ( -  ) gforth-1.0 "at-and-t-syntax"
   Change ‘disasm2’ to output AT&T syntax.  This word is only defined on
AMD64 and IA-32 machines and only if Gforth was built with ‘libopcodes’
support.

‘disasm’ ( c-addr u -  ) gforth-0.5
   Disassemble code block starting at c-addr with u bytes length using a
hand-written disassembler.  This word is only defined on architectures
for which a hand-written disassembler exists.

‘disasm-gdb’ ( addr u -  ) gforth-0.7
   Disassemble code block starting at c-addr with u bytes length by
calling ‘gdb’.  This word works only if ‘gdb’ is installed, can attach
to its parent, and uses the right syntax.  If it hangs, use ‘Ctrl-c’.


File: gforth.info,  Node: 386 Assembler,  Next: Alpha Assembler,  Prev: Common Disassembler,  Up: Assembler and Code Words

6.33.4 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 an Intel-like prefix syntax.

   The assembler uses a postfix syntax with AT&T-style parameter order
(i.e., destination last).

   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 default is ‘.fx’, so you need
to specify ‘.fl’ explicitly when dealing with Gforth FP values.

   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 in various syntaxes:

     Gforth          Intel (NASM)   AT&T (gas)      Name
     .w ax           ax             %ax             register (16 bit)
     ax              eax            %eax            register (32 bit)
     3 #             offset 3       $3              immediate
     1000 #)         byte ptr 1000  1000            displacement
     bx )            [ebx]          (%ebx)          base
     100 di d)       100[edi]       100(%edi)       base+displacement
     20 ax *4 i#)    20[eax*4]      20(,%eax,4)     (index*scale)+displacement
     di ax *4 i)     [edi][eax*4]   (%edi,%eax,4)   base+(index*scale)
     4 bx cx di)     4[ebx][ecx]    4(%ebx,%ecx)    base+index+displacement
     12 sp ax *2 di) 12[esp][eax*2] 12(%esp,%eax,2) base+(index*scale)+displacement

   You can use ‘L)’ and ‘LI)’ instead of ‘D)’ and ‘DI)’ to enforce
32-bit displacement fields (useful for later patching).

   Some example of instructions are:

     ax bx mov             \ move ebx,eax
     3 # ax mov            \ mov eax,3
     100 di d) 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>
     <n> # <mem> <inst>

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

   Based on the Intel ABI (used in Linux), ‘abi-code’ words can find the
data stack pointer at ‘4 sp d)’, and the address of the FP stack pointer
at ‘8 sp d)’; the data stack pointer is returned in ‘ax’; ‘Ax’, ‘cx’,
and ‘dx’ are caller-saved, so you do not need to preserve their values
inside the word.  You can return from the word with ‘ret’, the
parameters are cleaned up by the caller.

   For examples of 386 ‘abi-code’ words, see *note Assembler
Definitions::.


File: gforth.info,  Node: Alpha Assembler,  Next: AMD64 Assembler,  Prev: 386 Assembler,  Up: Assembler and Code Words

6.33.5 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’.


File: gforth.info,  Node: AMD64 Assembler,  Next: ARM A32 assembler,  Prev: Alpha Assembler,  Up: Assembler and Code Words

6.33.6 AMD64 (x86_64) Assembler
-------------------------------

The AMD64 assembler is a slightly modified version of the 386 assembler,
and as such shares most of the syntax.  Two new prefixes, ‘.q’ and
‘.qa’, are provided to select 64-bit operand and address sizes
respectively.  64-bit sizes are the default, so normally you only have
to use the other prefixes.  Also there are additional register operands
‘R8’-‘R15’.

   The registers lack the 'e' or 'r' prefix; even in 64 bit mode, ‘rax’
is called ‘ax’.  Additional register operands are available to refer to
the lowest-significant byte of all registers: ‘R8L’-‘R15L’, ‘SPL’,
‘BPL’, ‘SIL’, ‘DIL’.

   The Linux-AMD64 calling convention is to pass the first 6 integer
parameters in rdi, rsi, rdx, rcx, r8 and r9 and to return the result in
rax and rdx; to pass the first 8 FP parameters in xmm0-xmm7 and to
return FP results in xmm0-xmm1.  So ‘abi-code’ words get the data stack
pointer in ‘di’ and the address of the FP stack pointer in ‘si’, and
return the data stack pointer in ‘ax’.  The other caller-saved registers
are: r10, r11, xmm8-xmm15.  This calling convention reportedly is also
used in other non-Microsoft OSs.

   Windows x64 passes the first four integer parameters in rcx, rdx, r8
and r9 and return the integer result in rax.  The other caller-saved
registers are r10 and r11.

   On the Linux platform, according to
<https://uclibc.org/docs/psABI-x86_64.pdf> page 21 the registers AX CX
DX SI DI R8 R9 R10 R11 are available for scratch.

   The addressing modes for the AMD64 are:

     \ running word A produces a memory error as the registers are not initialised ;-)
     ABI-CODE A  ( -- )
         500        #               AX  MOV     \ immediate
             DX              AX  MOV     \ register
             200             AX  MOV     \ direct addressing
             DX  )           AX  MOV     \ indirect addressing
         40  DX  D)          AX  MOV     \ base with displacement
             DX  CX      I)  AX  MOV     \ scaled index
             DX  CX  *4  I)  AX  MOV     \ scaled index
         40  DX  CX  *4  DI) AX  MOV     \ scaled index with displacement

             DI              AX  MOV     \ SP Out := SP in
                                 RET
     END-CODE

   Here are a few examples of an AMD64 ‘abi-code’ words:

     abi-code my+  ( n1 n2 -- n3 )
     \ SP passed in di, returned in ax,  address of FP passed in si
     8 di d) ax lea        \ compute new sp in result reg
     di )    dx mov        \ get old tos
     dx    ax ) add        \ add to new tos
     ret
     end-code

     \ Do nothing
     ABI-CODE aNOP  ( -- )
            DI  )       AX      LEA          \ SP out := SP in
                                RET
     END-CODE

     \ Drop TOS
     ABI-CODE aDROP  ( n -- )
        8   DI  D)      AX      LEA          \ SPout := SPin - 1
                                RET
     END-CODE

     \ Push 5 on the data stack
     ABI-CODE aFIVE   ( -- 5 )
        -8  DI  D)      AX      LEA          \ SPout := SPin + 1
        5   #           AX  )   MOV          \ TOS := 5
                                RET
     END-CODE

     \ Push 10 and 20 into data stack
     ABI-CODE aTOS2  ( -- n n )
        -16 DI  D)      AX      LEA          \ SPout := SPin + 2
        10  #       8   AX  D)  MOV          \ TOS - 1 := 10
        20  #           AX  )   MOV          \ TOS := 20
                                RET
     END-CODE

     \ Get Time Stamp Counter as two 32 bit integers
     \ The TSC is incremented every CPU clock pulse
     ABI-CODE aRDTSC   ( -- TSCl TSCh )
                                RDTSC        \ DX:AX := TSC
        $FFFFFFFF #     AX      AND          \ Clear upper 32 bit AX
       0xFFFFFFFF #     DX      AND          \ Clear upper 32 bit DX
            AX          R8      MOV          \ Temporarily save AX
        -16 DI  D)      AX      LEA          \ SPout := SPin + 2
            R8      8   AX  D)  MOV          \ TOS-1 := saved AX = TSC low
            DX          AX  )   MOV          \ TOS := Dx = TSC high
                                RET
     END-CODE

     \ Get Time Stamp Counter as 64 bit integer
     ABI-CODE RDTSC   ( -- TSC )
                                RDTSC        \ DX:AX := TSC
        $FFFFFFFF #     AX      AND          \ Clear upper 32 bit AX
        32  #           DX      SHL          \ Move lower 32 bit DX to upper 32 bit
            AX          DX      OR           \ Combine AX with DX in DX
        -8  DI  D)      AX      LEA          \ SPout := SPin + 1
            DX          AX  )   MOV          \ TOS := DX
                                RET
     END-CODE

     VARIABLE V

     \ Assign 4 to variable V
     ABI-CODE V=4 ( -- )
            BX                  PUSH         \ Save BX, used by gforth
        V   #           BX      MOV          \ BX := address of V
        4   #           BX )    MOV          \ Write 4 to V
            BX                  POP          \ Restore BX
            DI  )       AX      LEA          \ SPout := SPin
                                RET
     END-CODE

     VARIABLE V

     \ Assign 5 to variable V
     ABI-CODE V=5 ( -- )
        V   #           CX      MOV          \ CX := address of V
        5   #           CX )    MOV          \ Write 5 to V
        DI )            AX      LEA          \ SPout := SPin
                                RET
     END-CODE

     ABI-CODE TEST2  ( -- n n )
        -16 DI  D)  AX          LEA          \ SPout := SPin + 2
        5   #       CX          MOV          \ CX := 5
        5   #       CX          CMP
        0= IF
            1   #   8   AX  D)      MOV      \ If CX = 5 then TOS - 1 := 1  <--
        ELSE
            2   #   8   AX  D)      MOV      \ else TOS - 1 := 2
        THEN
        6   #       CX          CMP
        0= IF
            3   #       AX  )       MOV      \ If CX = 6 then TOS := 3
        ELSE
            4   #       AX  )       MOV      \ else TOS := 4  <--
        THEN
                                RET
     END-CODE

     \ Do four loops. Expect : ( 4 3 2 1 -- )
     ABI-CODE LOOP4  ( -- n n n n )
            DI          AX      MOV          \ SPout := SPin
        4   #           DX      MOV          \ DX := 4  loop counter
        BEGIN
            8   #           AX      SUB      \ SP := SP + 1
                DX          AX  )   MOV      \ TOS := DX
            1   #           DX      SUB      \ DX := DX - 1
        0= UNTIL
                                RET
     END-CODE

   Here's a AMD64 example that deals with FP values:

     abi-code my-f+  ( r1 r2 -- r )
     \ SP passed in di, returned in ax,  address of FP passed in si
     si )       dx mov         \ load fp
     8 dx d)  xmm0 movsd       \ r2
     dx )     xmm0 addsd       \ r1+r2
     xmm0  8 dx d) movsd       \ store r
     8 #      si ) add         \ update fp
     di         ax mov         \ sp into return reg
     ret
     end-code


File: gforth.info,  Node: ARM A32 assembler,  Next: LoongArch assembler,  Prev: AMD64 Assembler,  Up: Assembler and Code Words

6.33.7 ARM A32 assembler
------------------------

Source code: ‘arch/arm/asm.fs’

   The ARM A32 assembler includes all instruction of ARM architecture
version 4, and the BLX instruction from architecture 5.  It does not
have support for T32 (Thumb) instructions.  It also lacks support for
any co-processors.

   The assembler uses a postfix syntax with the same operand order as
used in the ARM Architecture Reference Manual.  Mnemonics are suffixed
by a comma.

   Registers are specified by their names ‘r0’ through ‘r15’, with the
aliases ‘pc’, ‘lr’, ‘sp’, ‘ip’ and ‘fp’ provided for convenience.  Note
that ‘ip’ refers to the"intra procedure call scratch register" (‘r12’)
and does not refer to an instruction pointer.  ‘sp’ refers to the ARM
ABI stack pointer (‘r13’) and not the Forth stack pointer.

   Condition codes can be specified anywhere in the instruction, but
will be most readable if specified just in front of the mnemonic.  The
'S' flag is not a separate word, but encoded into instruction mnemonics,
ie.  just use ‘adds,’ instead of ‘add,’ if you want the status register
to be updated.

   The following table lists the syntax of operands for general
instructions:

     Gforth          normal assembler      description
     123 #           #123                  immediate
     r12             r12                   register
     r12 4 #LSL      r12, LSL #4           shift left by immediate
     r12 r1 LSL      r12, LSL r1           shift left by register
     r12 4 #LSR      r12, LSR #4           shift right by immediate
     r12 r1 LSR      r12, LSR r1           shift right by register
     r12 4 #ASR      r12, ASR #4           arithmetic shift right
     r12 r1 ASR      r12, ASR r1           ... by register
     r12 4 #ROR      r12, ROR #4           rotate right by immediate
     r12 r1 ROR      r12, ROR r1           ... by register
     r12 RRX         r12, RRX              rotate right with extend by 1

   Memory operand syntax is listed in this table:

     Gforth            normal assembler      description
     r4 ]              [r4]                  register
     r4 4 #]           [r4, #+4]             register with immediate offset
     r4 -4 #]          [r4, #-4]             with negative offset
     r4 r1 +]          [r4, +r1]             register with register offset
     r4 r1 -]          [r4, -r1]             with negated register offset
     r4 r1 2 #LSL -]   [r4, -r1, LSL #2]     with negated and shifted offset
     r4 4 #]!          [r4, #+4]!            immediate preincrement
     r4 r1 +]!         [r4, +r1]!            register preincrement
     r4 r1 -]!         [r4, +r1]!            register predecrement
     r4 r1 2 #LSL +]!  [r4, +r1, LSL #2]!    shifted preincrement
     r4 -4 ]#          [r4], #-4             immediate postdecrement
     r4 r1 ]+          [r4], r1              register postincrement
     r4 r1 ]-          [r4], -r1             register postdecrement
     r4 r1 2 #LSL ]-   [r4], -r1, LSL #2     shifted postdecrement
     ' xyz >body [#]   xyz                   PC-relative addressing

   Register lists for load/store multiple instructions are started and
terminated by using the words ‘{’ and ‘}’ respectively.  Between braces,
register names can be listed one by one or register ranges can be formed
by using the postfix operator ‘r-r’.  The ‘^’ flag is not encoded in the
register list operand, but instead directly encoded into the instruction
mnemonic, ie.  use ‘^ldm,’ and ‘^stm,’.

   Addressing modes for load/store multiple are not encoded as
instruction suffixes, but instead specified like an addressing mode, Use
one of ‘DA’, ‘IA’, ‘DB’, ‘IB’, ‘DA!’, ‘IA!’, ‘DB!’ or ‘IB!’.

   The following table gives some examples:

     Gforth                           normal assembler
     r4 ia  { r0 r7 r8 }  stm,        stmia    r4, {r0,r7,r8}
     r4 db!  { r0 r7 r8 }  ldm,       ldmdb    r4!, {r0,r7,r8}
     sp ia!  { r0 r15 r-r }  ^ldm,    ldmfd    sp!, {r0-r15}^

   Control structure words typical for Forth assemblers are available:
‘if,’ ‘ahead,’ ‘then,’ ‘else,’ ‘begin,’ ‘until,’ ‘again,’ ‘while,’
‘repeat,’ ‘repeat-until,’.  Conditions are specified in front of these
words:

     r1 r2 cmp,    \ compare r1 and r2
     eq if,        \ equal?
        ...          \ code executed if r1 == r2
     then,

   Example of a definition using the ARM assembler:

     abi-code my+ ( n1 n2 --  n3 )
        \ arm abi: r0=SP, r1=&FP, r2,r3,r12 saved by caller
        r0 IA!  { r2 r3 }  ldm,     \ pop r2 = n2, r3 = n1
        r3  r2  r3         add,     \ r3 = n1+n1
        r3  r0 -4 #]!      str,     \ push r3
        pc  lr             mov,     \ return to caller, new SP in r0
     end-code


File: gforth.info,  Node: LoongArch assembler,  Next: MIPS assembler,  Prev: ARM A32 assembler,  Up: Assembler and Code Words

6.33.8 LoongArch assembler
--------------------------

Source code: ‘arch/loongarch64/asm.fs’.  You can find the list of
instructions (and their formats) in ‘arch/loongarch64/insts.fs’.

   Registers are ‘r0’..‘r31’, ‘f0’..‘f31’, ‘fcsr0’...‘fcsr31’,
‘fcc0’..‘fcc7’ and ‘?caf ?saf ?clt ?slt ?ceq ?seq ?cle ?sle ?cun ?sun
?cult ?sult ?cueq ?sueq ?cule ?sule ?cne ?sne ?cor ?sor ?cune ?sune’.

   Mnemonics don't end with ",", so you need to worry about collisions
with Forth word names (e.g, ‘and’).  To use immediates, you need to use
the immediate name (e.g., ‘addi.d’ instead of ‘add.d’).

   This assembler does not support structured control structure words.


File: gforth.info,  Node: MIPS assembler,  Next: PowerPC assembler,  Prev: LoongArch assembler,  Up: Assembler and Code Words

6.33.9 MIPS assembler
---------------------

The MIPS assembler was originally written by Christian Pirker.

   Currently the assembler and disassembler covers most of the MIPS32
architecture and doesn't support FP instructions.

   The register names ‘$a0’-‘$a3’ are not available to avoid shadowing
hex numbers.  Use register numbers ‘$4’-‘$7’ instead.

   Nothing distinguishes registers from immediate values.  Use explicit
opcode names with the ‘i’ suffix for instructions with immediate
argument.  E.g.  ‘addiu,’ in place of ‘addu,’.

   Where the architecture manual specifies several formats for the
instruction (e.g., for ‘jalr,’),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 manually (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.  For branches the argument specifying the target is a relative
address.  Add the address of the delay slot to get the absolute address.

   Note that you must not put branches nor jumps (nor control-flow
instructions) into the delay slot.  Also it is a bad idea to put
pseudo-ops such as ‘li,’ into a delay slot, as these may expand to
several instructions.  The MIPS I architecture also had load delay
slots, and newer MIPSes still have restrictions on using ‘mfhi,’ and
‘mflo,’.  Be careful to satisfy these restrictions, the assembler does
not do it for you.

   Some example of instructions are:

     $ra  12 $sp  sw,         \ sw    ra,12(sp)
     $4    8 $s0  lw,         \ lw    a0,8(s0)
     $v0  $0  lui,            \ lui   v0,0x0
     $s0  $s4  $12  addiu,    \ addiu s0,s4,0x12
     $s0  $s4  $4  addu,      \ addu  s0,s4,$a0
     $ra  $t9  jalr,          \ jalr  t9

   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,

   The calling conventions for 32-bit MIPS machines is to pass the first
4 arguments in registers ‘$4’..‘$7’, and to use ‘$v0’-‘$v1’ for return
values.  In addition to these registers, it is ok to clobber registers
‘$t0’-‘$t8’ without saving and restoring them.

   If you use ‘jalr,’ to call into dynamic library routines, you must
first load the called function's address into ‘$t9’, which is used by
position-indirect code to do relative memory accesses.

   Here is an example of a MIPS32 ‘abi-code’ word:

     abi-code my+  ( n1 n2 -- n3 )
       \ SP passed in $4, returned in $v0
       $t0  4 $4  lw,         \ load n1, n2 from stack
       $t1  0 $4  lw,
       $t0  $t0  $t1  addu,   \ add n1+n2, result in $t0
       $t0  4 $4  sw,         \ store result (overwriting n1)
       $ra  jr,               \ return to caller
       $v0  $4  4  addiu,     \ (delay slot) return uptated SP in $v0
     end-code


File: gforth.info,  Node: PowerPC assembler,  Next: RISC-V assembler,  Prev: MIPS assembler,  Up: Assembler and Code Words

6.33.10 PowerPC assembler
-------------------------

The PowerPC assembler and disassembler were contributed by Michal
Revucky.

   This assembler does not follow the convention of ending mnemonic
names with a ",", so some mnemonic names shadow regular Forth words (in
particular: ‘and or xor fabs’); so if you want to use the Forth words,
you have to make them visible first, e.g., with ‘also forth’.

   Registers are referred to by their number, e.g., ‘9’ means the
integer register 9 or the FP register 9 (depending on the instruction).

   Because there is no way to distinguish registers from immediate
values, you have to explicitly use the immediate forms of instructions,
i.e., ‘addi,’, not just ‘add,’.

   The assembler and disassembler usually support the most general form
of an instruction, but usually not the shorter forms (especially for
branches).


File: gforth.info,  Node: RISC-V assembler,  Next: Other assemblers,  Prev: PowerPC assembler,  Up: Assembler and Code Words

6.33.11 RISC-V assembler
------------------------

Source code: ‘arch/riscv/asm.fs’.  The instructions are listed in
‘arch/riscv/inst32.fs’ and (compressed instructions)
‘arch/riscv/inst16.fs’; note that the compressed instructions are listed
there without their ‘c.’ prefix, but that prefix is required by the
assembler.

   Both raw register names (‘x0’...‘x31’, ‘f0’...‘f31’) and symbolic
names (e.g., ‘a7’, ‘fa7’) are available.  Note that some register names
form valid hex numbers, so we recommend using the prefix syntax ‘$fa7’
instead of using ‘hex’ base.

   Fences are called ‘|w |r |rw |o |ow |or |orw |i |iw |ir |irw |io |iow
|ior |iorw’.

   Instruction names do not end with ",", so there are conflicts with
Forth words like ‘and’.  You need to use the immediate form of an
instruction (e.g., ‘addi’ instead of just ‘add’) explicitly.  Only the
general form of the instruction is supported, not specialized names
(e.g, there is ‘jalr’, but not ‘jr’; there is, however ‘c.jr’).

   There is no automatic selection of compressed instructions.  Instead,
you have to call them by their name, with a preceding ‘c.’, e.g.,
‘c.addi’ for the compressed form of ‘addi’.

   Note that the assembler does not check whether the used registers and
immediate values fit in the instruction, and just produces some
truncated form if they don't.  This is especially relevant for
compressed instructions, where immediate value sizes are even smaller,
and some of which only work with some registers.


File: gforth.info,  Node: Other assemblers,  Prev: RISC-V assembler,  Up: Assembler and Code Words

6.33.12 Other assemblers
------------------------

In addition to the assemblers mentioned above, there are the following
asm.fs files:

     arch/4stack/asm.fs
     arch/6502/asm.fs
     arch/8086/asm.fs
     arch/avr/asm.fs
     arch/c165/asm.fs
     arch/h8/asm.fs
     arch/lm32/asm.fs
     arch/m68k/asm.fs
     arch/misc/asm.fs
     arch/nibz40/asm.fs
     arch/r8c/asm.fs
     arch/shboom/asm.fs

   These architectures may be supported by Gforth EC (embedded control),
but that's not documented here (and only sporadically elsewhere, with
quite a bit documentation for the r8c port).  If you want to use one of
these assemblers, use the source!

   If you want to contribute another assembler/disassembler, please
check at <https://cgit.git.savannah.gnu.org/cgit/gforth.git/tree/arch>
if there is 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.


File: gforth.info,  Node: Carnal words,  Next: Passing Commands to the OS,  Prev: Assembler and Code Words,  Up: Words

6.34 Carnal words
=================

These words deal with the mechanics of Gforth (in Forth circles called
"carnal knowledge" of a Forth system), but we consider them stable
enough to document them.

* Menu:

* Header fields::
* Header methods::
* Threading Words::


File: gforth.info,  Node: Header fields,  Next: Header methods,  Prev: Carnal words,  Up: Carnal words

6.34.1 Header fields
--------------------

In Gforth 1.0 we switched to a new word header layout.  For a detailed
description, read: Bernd Paysan and M. Anton Ertl.  ‘The new Gforth
header (http://www.euroforth.org/ef19/papers/paysan.pdf)’.  In 35th
EuroForth Conference, pages 5-20, 2019.  Since this paper was published,
xt and nt have been changed to point to the parameter field, like the
body, and "vt" (virtual table) has been renamed to "hm" (header
methods), but otherwise it is still up-to-date.

   This section explains just the data structure and the words used to
access it.  A header has the following fields:

     name
     >f+c
     >link
     >cfa
     >namehm
     >body

   Currently Gforth has the names shown above for getting from the
xt/nt/body to the field, but apart from the standard ‘>body’ they are
not stable Gforth words.  Instead, we provide access words.  Note that
the documented access words have survived the reorganization of the
header layout.

   Some of the words expect an nt, some expect an xt.  Given that both
nt and xt point to the body of a word, what is the difference?  For most
words, the xt and nt use the same header, and with nt=xt, they point to
the same place.  However, for a synonym (*note Synonyms::) there is a
difference; consider the example

     create x
     synonym y x
     synonym z y

   In this case the nt of ‘z’ points to the body of ‘z’, while the xt of
‘z’ points to the body of ‘x’.  Words defined with ‘alias’ or ‘forward’
(*note Calls and returns::) also have different nts and xts.

   The name field is variable-length and is accessed with ‘name>string’
(*note Name token::).

   The ‘>f+c’ field contains flags and the name length (count).  You
read the count with ‘name>string’, and the flags with ‘compile-only?’
and ‘obsolete?’ (*note Name token::).

   The ‘>link’ field contains a link to the previous word in the same
word list.  You can read it with ‘name>link’ (*note Name token::).

   The name, ‘>f+c’ and ‘>link’ fields are not present for ‘noname’
words, but ‘name>string’ and ‘name>link’ work nevertheless, producing 0
0 and 0, respectively.

   The ‘>cfa’ field (aka code field) contains the code address used for
‘execute’ing the word; you can read it with ‘>code-address’ and write it
with ‘code-address!’ (*note Threading Words::).

   The ‘>namehm’ field contains the address of the header methods table
(*note Header methods::).  You access it by performing or accessing
header methods (*note Header methods::).

   The ‘>body’ (aka parameter) field contains data or threaded code
specific to the word type; its length depends on the word type.  E.g.,
for a ‘constant’ it contains a cell with the value of the constant.  You
can access it through ‘>body’ (*note CREATE..DOES> details::), but this
is only standard for words you defined with ‘create’.


File: gforth.info,  Node: Header methods,  Next: Threading Words,  Prev: Header fields,  Up: Carnal words

6.34.2 Header methods
---------------------

The new Gforth word header is object-oriented and supports the following
methods (method selectors):

     .hm label method          overrider        field
               execute         set-execute      >cfa
     opt:      opt-compile,    set-optimizer    >hmcompile,
     to:       (to)            set-to           >hmto
     extra:                                     >hmextra
     >int:     name>interpret  set->int         >hm>int
     >comp:    name>compile    set->comp        >hm>comp
     >string:  name>string     set-name>string  >hm>string
     >link:    name>link       set-name>link    >hm>link

   Many of these words are not stable Gforth words, but Gforth has
stable higher-level words that we mention below.

   You can look at the header methods of a word with

‘.hm’ ( nt -  ) gforth-1.0 "dot-h-m"
   print the header methods of nt

   Overrider (setter) words change the method implementation for the
most recent definition.  Quotations or closures restore the previous
most recent definition when they are completed, so they are not
considered most recent, and you can do things like:

     : my2dup over over ;
     [: drop ]] over over [[ ;] set-optimizer

   The ‘execute’ method is actually stored in the ‘>cfa’ field in the
header rather than in the header-methods table for performance reasons;
also it is implemented through a native-code address, while the other
methods are implemented by calling an xt.  The high-level way to set
this method is

‘set-execute’ ( ca -  ) gforth-1.0
   Changes the current word such that it jumps to the native code at ca.
Also changes the ‘compile,’ implementation to the most general (and
slowest) one.  Call ‘set-optimizer’ afterwards if you want a more
efficient ‘compile,’ implementation.

   To get a code address for use with ‘set-execute’, you can use words
like ‘docol:’ or ‘>code-address’, *Note Threading Words::.

   As an alternative to ‘set-execute’, there is also ‘set-does>’ (*note
User-defined Defining Words::), which takes an xt.

   Moreover, there are the low-level ‘code-address!’ and ‘definer!’
(*note Threading Words::).

   The ‘opt-compile,’ method is what ‘compile,’ does on most Gforth
engines (‘gforth-itc’ uses ‘,’ instead).  You can define a more
efficient implementation of ‘compile,’ for the current word with
‘set-optimizer’ (*note User-defined compile-comma::).  Note that the end
result must be equivalent to ‘postpone literal postpone execute’.

   As an example of the use of ‘set-optimizer’, consider the following
definition of ‘constant’:

     : constant ( n "name" -- ; name: -- n )
       create ,
       ['] @ set-does>
     ;

     5 constant five
     : foo five ; see foo

   The Forth system does not know that the value of a constant must not
be changed, and just sees a ‘create’d word (which can be changed with
‘>body’), and ‘foo’ first pushes the body address of ‘five’ and then
fetches from there.  With ‘set-optimizer’ the definition of ‘constant’
can be optimized as follows:

     : constant ( n "name" -- ; name: -- n )
       create ,
       ['] @ set-does>
       [: >body @ postpone literal ;] set-optimizer
     ;

   Now ‘foo’ contains the literal 5 rather than a call to ‘five’.

   Note that ‘set-execute’ and ‘set-does>’ perform ‘set-optimizer’
themselves in order to ensure that ‘execute’ and ‘compile,’ agree, so if
you want to add your own optimizer, you should add it afterwards.

   The ‘(to)’ method and ‘set-to’ are used for implementing ‘to _name_’
semantics etc.  (*note Words with user-defined TO etc.::).

   The ‘>hmextra’ field is used for cases where additional data needs to
be stored in the header methods table.  In particular, it stores the xt
passed to ‘set-does>’ (and ‘does>’ calls ‘set-does>’) and the code
address behind ‘;abi-code’.

   The methods above all consume an xt, not an nt, but the override
words work on the most recent definition.  This means that if you use,
e.g., ‘set-optimizer’ on a synonym, the effect will probably not be what
you intended: When ‘compile,’ing the xt of the word, the ‘opt-compile,’
implementation of the original word will be used, not the freshly-set
one of the synonym.

   The following methods consume an nt.

   The ‘name>interpret’ method is implemented as noop for most words,
except synonyms and similar words.

‘set->int’ ( xt -  ) gforth-1.0 "set-to-int"
   Sets the implementation of the ‘name>interpret ( nt -- xt2 )’ method
of the current word to xt.

   The ‘name>compile’ method produces the compilation semantics of the
nt.  By changing it with ‘set->comp’, you can change the compilation
semantics, but it's not as simple as just pushing the xt of the desired
compilation semantics, because of the stack effect of ‘name>compile’.
Generally you should avoid changing the compilation semantics, and if
you do, use a higher-level word like ‘immediate’ or
‘interpret/compile:’, *Note Combined words::.

‘set->comp’ ( xt -  ) gforth-1.0 "set-to-comp"
   Sets the implementation of the ‘name>compile ( nt -- xt1 xt2 )’
method of the current word to xt.

‘immediate?’ ( nt - flag  ) gforth-1.0 "immediate-question"
   true if the word nt has non-default compilation semantics (that's not
quite according to the definition of immediacy, but many people mean
that when they call a word "immediate").

   ‘Name>string’ and ‘Name>link’ are methods in order to make it
possible to eliminate the name, ‘>f+c’ and ‘link’ fields from noname
headers, but still produce meaningful results when using these words.
You will typically not change the implementations of these methods
except with ‘noname’, but we still have

‘set-name>string’ ( xt -  ) gforth-1.0 "set-name-to-string"
   Sets the implementation of the ‘name>string ( nt -- addr u )’ method
of the current word to xt.

‘set-name>link’ ( xt -  ) gforth-1.0 "set-name-to-link"
   Sets the implementation of the ‘name>link ( nt1 -- nt2|0 )’ method of
the current word to xt.


File: gforth.info,  Node: Threading Words,  Prev: Header methods,  Up: Carnal words

6.34.3 Threading Words
----------------------

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

   These words provide access to code fields, code addresses and other
threading stuff in Gforth.  It more or less abstracts away the
differences between direct and indirect threading.

   Up to and including Gforth 0.7, the code address (plus, for
‘does>’-defined words, the address returned by ‘>does-code’) was
sufficient to know the type of the word.  However, since Gforth-1.0 the
behaviour or at least implementation of words like ‘compile,’ and
‘name>compile’ can be determined independently as described in *note
Header methods::.

   To create a code field and at the same time initialize the header
methods use ‘create-from’ (*note Creating from a prototype::).

   The following words were designed before the introduction of header
methods, and are therefore not the best (and recommended) way to deal
with different word types in Gforth.

   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-0.2 "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-0.2 "to-code-address"
   c-addr is the code address of the word xt.

‘code-address!’ ( c_addr xt -  ) gforth-obsolete "code-address-store"
   Change a code field with code address c-addr at xt.

   The code addresses produced by various defining words are produced by
the following words:

‘docol:’ ( - addr  ) gforth-0.2 "docol-colon"
   The code address of a colon definition.

‘docon:’ ( - addr  ) gforth-0.2 "docon-colon"
   The code address of a ‘CONSTANT’.

‘dovar:’ ( - addr  ) gforth-0.2 "dovar-colon"
   The code address of a ‘CREATE’d word.

‘douser:’ ( - addr  ) gforth-0.2 "douser-colon"
   The code address of a ‘USER’ variable.

‘dodefer:’ ( - addr  ) gforth-0.2 "dodefer-colon"
   The code address of a ‘defer’ed word.

‘dofield:’ ( - addr  ) gforth-0.2 "dofield-colon"
   The code address of a ‘field’.

‘dovalue:’ ( - addr  ) gforth-experimental "dovalue-colon"
   The code address of a ‘value’.  This will probably stop being
different from ‘:docon’ in a future version.  If you want to know
whether a word is a constant or a value, better test whether the
‘hmcompile,’ field contains the xt of ‘constant,’ or of ‘value,’.

‘dodoes:’ ( - addr  ) gforth-0.6 "dodoes-colon"
   The code address of a ‘DOES>’-defined word.

‘doabicode:’ ( - addr  ) gforth-1.0 "doabicode-colon"
   The code address of a ‘ABI-CODE’ definition.

   For a word X defined with ‘set-does>’, the code address points to
‘dodoes:’, and the ‘>hmextra’ field of the header methods contains the
xt of the word that is called after pushing the body address of X.

   If you want to know whether a word is a ‘DOES>’-defined word, and
what Forth code it executes, ‘>does-code’ tells you that:

‘>does-code’ ( xt1 - xt2  ) gforth-0.2 "to-does-code"
   If xt1 is the execution token of a child of a ‘set-does>’-defined
word, xt2 is the xt passed to ‘set-does>’, i.e, the xt of the word that
is executed when executing xt1 (but first the body address of xt1 is
pushed).  If xt1 does not belong to a ‘set-does>’-defined word, xt2 is
0.

   You can use the resulting xt2 with ‘set-does>’ (preferred) to change
the latest word or with

‘does-code!’ ( xt2 xt1 -  ) gforth-0.2 "does-code-store"
   Change xt1 to be a ‘xt2 set-does>’-defined word.

   to change an arbitrary word.

   The following two words generalize ‘>code-address’, ‘>does-code’,
‘code-address!’, and ‘does-code!’:

‘>definer’ ( xt - definer  ) gforth-0.2 "to-definer"
   DEFINER is a unique identifier for the way the XT was defined.  Words
defined with different ‘does>’-codes have different definers.  The
definer can be used for comparison and in ‘definer!’.

‘definer!’ ( definer xt -  ) gforth-obsolete "definer-store"
   The word represented by XT changes its behaviour to the behaviour
associated with DEFINER.

   ‘Code-address!’, ‘does-code!’, and ‘definer!’ update the
‘opt-compile,’ method to a somewhat generic compiler for that word type
(in particular, primitives get the slow ‘general-compile,’ method rather
than the primitive-specific ‘peephole-compile,’).


File: gforth.info,  Node: Passing Commands to the OS,  Next: Keeping track of Time,  Prev: Carnal words,  Up: Words

6.35 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-0.2
   Execute the rest of the command line as shell command(s).
Afterwards, ‘$?’ produces the exit status of the command.

‘system’ ( c-addr u -  ) gforth-0.2
   Pass the string specified by C-ADDR U to the host operating system
for execution in a sub-shell.  Afterwards, ‘$?’ produces the exit status
of the command.  The value of the environment variable
‘GFORTHSYSTEMPREFIX’ (or its default value) is prepended to the string
(mainly to support using ‘command.com’ as shell in Windows instead of
whatever shell Cygwin uses by default; *note Environment variables::).

‘sh-get’ ( c-addr u - c-addr2 u2  ) gforth-1.0
   Run the shell command addr u; c-addr2 u2 is the output of the
command.  The exit code is in ‘$?’, the output also in ‘sh$ 2@’.

‘$?’ ( - n  ) gforth-0.2 "dollar-question"
   ‘Value’ - the exit status returned by the most recently executed
‘system’ command.

‘getenv’ ( c-addr1 u1 - c-addr2 u2 ) gforth-0.2 "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.


File: gforth.info,  Node: Keeping track of Time,  Next: Miscellaneous Words,  Prev: Passing Commands to the OS,  Up: Words

6.36 Keeping track of Time
==========================

‘ms’ ( u -  ) facility-ext
   Wait u milliseconds.

‘ns’ ( ud -  ) gforth-1.0
   Wait ud nanoseconds.

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

‘>time&date&tz’ ( dtime - nsec nmin nhour nday nmonth nyear fdst ndstoff c-addrtz utz ) gforth-1.0 "to-time-and-date"
   Convert dtime in seconds since 1.1.1970 0:00Z to the current time of
day in the current timezone.  Seconds, minutes and hours are numbered
from 0.  Months are numbered from 1.

‘utime’ ( - dtime ) gforth-0.5 "utime"
   Report the current time in microseconds since some epoch.  Use
‘#1000000 um/mod nip’ to convert to seconds

‘ntime’ ( - dtime ) gforth-1.0 "ntime"
   Report the current time in nanoseconds since some epoch.

‘cputime’ ( - duser dsystem ) gforth-0.5 "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.


File: gforth.info,  Node: Miscellaneous Words,  Prev: Keeping track of Time,  Up: Words

6.37 Miscellaneous Words
========================

This section lists the Standard Forth words that are not documented
elsewhere in this manual.  Ultimately, they all need proper homes.

‘quit’ ( ?? - ??  ) core
   Empty the return stack, make the user input device the input source,
enter interpret state and start the text interpreter.

   The following Standard Forth words are not currently supported by
Gforth (*note Standard conformance::):

   ‘EDITOR’ ‘EMIT?’ ‘FORGET’


File: gforth.info,  Node: Error messages,  Next: Standard conformance,  Prev: Words,  Up: Top

7 Error messages
****************

A typical Gforth error message looks like this:

     in file included from *args*:1:1:
     in file included from xxx-err1.fs:1:9:
     xxx-err2.fs:3:1: error: Invalid memory address
     >>>bar<<<
     Backtrace:
     xxx-err2.fs:1:15:              0 $7FA610EA7F68 @
                                    1 $14
     xxx-err2.fs:2:7:               2 $7FA610EA7FB0 foo

   The line identifying the error is

     xxx-err2.fs:3:1: error: Invalid memory address

   It says that in file ‘xxx-err2.fs’, line 3, character 1, the error
"Invalid memory address" happened; more precisely, the exception -9 was
thrown there, and eventually was caught by Gforth's system exception
handler (either because the program did not ‘catch’ it or caught it and
rethrew it).

   The next line shows the text-interpreted line where the error
happened, abd the word where the error happened is surrounded by ‘>>>’
and ‘<<<’.

   Before that you find the nesting of source file includes that led to
the inclusion of ‘xxx-err2.fs’, with the outermost at the top and the
innermost at the bottom.  So in this case ‘xxx-err2.fs’ was included
from ‘xxx-err1.fs’, line 1, character 9, and that was included from an
OS-level command-line argument to Gforth, indicated by ‘*args*’.

   At the end of the error message you find the backtrace, actually a
return stack dump.  In our example, the middle line of the return stack
dump just contains the number 20 (‘$14’), and is not a return address.
The number ‘1’ before the ‘$14’ is the index of the return stack entry.

   The bottom line of the backtrace shows a return address, pushed by
the call to ‘foo’; the backtrace also shows ‘foo’ for this entry, at the
end, and the source location of the call ‘xxx-err2.fs:2:7’ at the
beginning of the line.

   The top line of the backtrace shows a pseudo-return address, as if
the primitive ‘@’ pushed a return address.  This return address was
pushed by the signal handler in order to produce this line in the
backtrace, so you know where the exception came from.

   So in our example we see that ‘bar’ called ‘foo’, and ‘foo’ pushed 20
on the return stack and then called ‘@’ (and ‘@’ threw an _Invalid
memory address_ exception).

   You can see the source code of the backtrace location with ‘nt’ (next
backtrace entry, initially the one with index 0, i.e., the top of the
return stack), ‘bt’ (previous backtrace entry, initially the one with
the biggest index, i.e., the bottom of the return stack), or ‘index tt’
(the indexed backtrace entry; *note Locating backtrace entry source::).

   Note that the backtrace is not perfect: We don't know which return
stack entries are return addresses (so we may get false positives).

   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’ or
‘nothrow’; this works well in the usual case.  To get the right
backtrace, you usually want to insert ‘nothrow’ or ‘['] false catch
2drop’ after a ‘catch’ if the error is not rethrown.

   The ‘gforth’ engine 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"’).  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’.

   ‘gforth-fast’ also does not attempt to differentiate between division
by zero and division overflow, because that costs time in every
division.


File: gforth.info,  Node: Standard conformance,  Next: Standard vs Extensions,  Prev: Error messages,  Up: Top

8 Standard conformance
**********************

To the best of our knowledge, Gforth is a

   ANS Forth (Forth-94) System and a Forth-2012 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 the Facility Extensions word set, except ‘EMIT?’
   • 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
   • providing the Programming-Tools word set
   • providing the Programming-Tools Extensions word set, except
     ‘EDITOR’ and ‘FORGET’
   • providing the Search-Order word set
   • providing the Search-Order Extensions word set
   • providing the String word set
   • providing the String Extensions word set
   • providing the Extended-Character wordset

   Gforth has the following environmental restrictions:

   • While processing the OS command line, if an exception is not
     caught, Gforth exits with a non-zero exit code instead of
     performing QUIT.

   • When a ‘throw’ is performed after a ‘query’, Gforth does not always
     restore the input source specification in effect at the
     corresponding catch.

   In addition, Standard Forth systems are required to document certain
implementation choices.  This chapter tries to meet these requirements
for the Forth-94 standard.  For the Forth-2012 standard, we decided to
produce the additional documentation only if there is demand.  So if you
are really missing this documentation, please let us know.

   In many cases, the following documentation 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: Standard conformance,  Up: Standard conformance

8.1 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

8.1.1 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 may 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:
     All addresses are character-aligned, because ‘1 chars’ produces 1.

character-set extensions and matching of names:
     Any character can be used in a name.  Matching is case-insensitive
     (except in ‘table’s and ‘cs-wordlist’s) for ASCII characters and
     case-sensitive for other characters.

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-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
     cell-sized stack-state descriptor (fourth), 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 ‘abort-string’ 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:
     255 characters.

maximum size of a parsed string:
     Given by the constant ‘/line’.  Currently 255 characters.

maximum size of a definition name, in characters:
     ‘-1 8 rshift’; 72057594037927935 characters on 64-bit systems,
     16777215 characters on 32-bit systems.

maximum string length for ‘ENVIRONMENT?’, in characters:
     Any string length, but only strings that can be names can be
     recognized.

method of selecting the user input device:
     Change ‘infile-id’, ideally with ‘infile-execute’.  Or by changing
     ‘ip-vector’ (undocumented).

method of selecting the user output device:
     Change ‘outfile-id’, e.g., with ‘outfile-execute’.  Or change
     ‘type’ and ‘emit’, e.g., with ‘>string-execute’.  Or by changing
     ‘op-vector’ (undocumented).

methods of dictionary compilation:
     What are we expected to document here?

number of bits in one address unit:
     8

number representation and arithmetic:
     Binary.  Negative integers are represented in two's-complement
     form.  FP numbers are represented as IEEE DP FP numbers (binary64)
     on nearly all platforms (exception: ARM with soft floats).

ranges for integer types:
     For 32-bit platforms: u: 0...4294967295, n:
     -2147483648...2147483647, ud: 0...18446744073709551615, d:
     -9223372036854775808...9223372036854775807.

     For 64-bit platforms: u: 0...18446744073709551615, n:
     -9223372036854775808...9223372036854775807, ud:
     0...340282366920938463463374607431768211455, d:
     -170141183460469231731687303715884105728...170141183460469231731687303715884105727

     You can also make environmental queries for ‘MAX-N’, ‘MAX-U’,
     ‘MAX-D’ and ‘MAX-UD’.

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, 176 on 64-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 .’.  4 on 32-bit systems, 8 on 64-bit systems.

size of one character in address units:
     1

size of the keyboard terminal buffer:
     ‘max#tib @’.  This can vary.

size of the pictured numeric output buffer:
     ‘word-pno-size’

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 for ASCII characters and
     case-sensitive for other characters (except that everything is
     case-sensitive in ‘table’s and ‘cs-wordlist’s).

system prompt:
     ‘ ok’ in interpret state, ‘ compiled’ in compile state, ‘
     postponed’ in postpone state.

division rounding:
     The ordinary division words ‘/ mod /mod */ */mod’ perform floored
     division.  If you write programs that need a specific division
     rounding, best use ‘fm/mod’ or ‘sm/rem’ for portability, but you
     can also use ‘/s’, ‘/f’ etc.

values of ‘STATE’ when true:
     -1.

values returned after arithmetic overflow:
     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).  Integer division overflow can result
     in these throws, or in ‘-11 throw’; in ‘gforth-fast’ division
     overflow and divide by zero may also result in returning bogus
     results without producing an exception.

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

8.1.2 Ambiguous conditions
--------------------------

a name is neither a word nor a number:
     If a recognizer matches (see ‘recs’, *note Default recognizers::,
     *note Literals in source code::), the text interpreter performs its
     interpreting, compiling, or postponing action (which one, depends
     on the state).  If none matches, the text interpreter performs ‘-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, data space, code space and header space are readable
     and writable.  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:
     You get an execution token that represents the interpretation
     semantics of the word.  In some cases, the standard does not define
     the interpretation semantics nor the execution semantics (e.g.,
     ‘if’).  In those cases, you get an execution token for the
     compilation semantics.  For words marked compile-only, the most
     common ways of obtaining the xt produce a warning.

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).  On some platforms, the
     ‘gforth-fast’ engine produces some hardware-dependent value.

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:
     Gforth defines interpretation semantics for all words; for words
     where the standard defines execution semantics (except ‘exit’ and
     ‘leave’), the interpretation semantics are to perform the execution
     semantics.  For words where the standard defines no interprtation
     semantics, but defined compilation semantics (plus ‘exit’ and
     ‘leave’), the interpretation semantics are to perform the
     compilation semantics.  Some words are marked as compile-only, and
     text-interpreting them gives a warning.

modifying the contents of the input buffer or a string literal:
     These are located in writable memory and can be modified, which may
     have bad consequences for later execution.

overflow of the pictured numeric output string:
     ‘-17 throw’ (Pictured numeric output string overflow).

parsed string overflow:
     ‘PARSE’ cannot overflow.  ‘WORD’ does not check for overflow.

producing a result out of range:
     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).  Overflow on division may result in
     these errors or in ‘-11 throw’ (result out of range).
     ‘Gforth-fast’ may silently produce bogus results on division
     overflow or division by zero.  ‘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, as well as ‘'’ and friends perform a
     ‘-16 throw’ (Attempt to use zero-length string as a name) if they
     are invoked at the end of a line.  However, it is possible to
     create zero-length names with ‘nextname’.

‘>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 code after ‘DOES>’.

argument input source different than current input source for ‘RESTORE-INPUT’:
     Ideally, this should result in a ‘-12 THROW’.  Currently it
     produces unintended results (up to and including terminating the
     Gforth session).

data space containing definitions gets de-allocated:
     Deallocation with ‘allot’ is not checked, possibly resulting in
     system corruption.  If you deallocate to the ‘section-start’, you
     get a ‘-8 throw’ (dictionary overflow).

data space read/write with incorrect alignment:
     Processor-dependent.  Typically results in a ‘-23 throw’ (Address
     alignment exception).  There are reportedly some processors with
     alignment restrictions that do not report violations, but just
     produce unintended results.

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’):
     No effect.

name not defined by ‘VALUE’ used by ‘TO’:
     If ‘to’ is not supported by the word type: ‘-21 throw’ (Unsupported
     operation).

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; or 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

8.1.3 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 696016 (bytes) on a 64-bit system.


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

8.2 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

8.2.1 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

8.2.2 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

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

any restrictions a multiprogramming system places on the use of buffer addresses:
     The current implementation of blocks is not thread-safe, so blocks
     should only be used by one task.

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: Standard conformance

8.3 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

8.3.1 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: Standard conformance

8.4 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

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

     You can allocate an exception number in the range (-4095...-256)
     with ‘exception’.  Gforth has allocated a number of such exceptions
     itself.


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

8.5 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

8.5.1 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’, ‘k-winch’,
     ‘k-eof’.

duration of a system clock tick:
     System dependent.  With respect to ‘MS’, the time is specified in
     nanoseconds.  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

8.5.2 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: Standard conformance

8.6 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

8.6.1 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 outputs LF on Unix (including WSL(2)) and
     CRLF on Windows (if anybody ever builds a Windows version again).
     Gforth accepts LF, CR and CRLF on input.

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:
     For file input, the maximum input line size is only limited by
     memory; the buffer is expanded to read in as long lines as the file
     contains.  For terminal input, this auto-expansion does not happen,
     and the current size of the input buffer is used; ‘max#tib ?’ shows
     the current input buffer size.

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
     ‘open-blocks’ or ‘use’.

number of string buffers provided by ‘S"’:
     The interpretation semantics ‘S"’ ‘allocate’s the memory for the
     strings, so the number of string buffers is only limited by memory.

size of string buffer used by ‘S"’:
     ‘S"’ ‘allocate’s the strings, as long as they are.


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

8.6.2 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 operation that discovers the problem produces an ior and that
     ior 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: Standard conformance

8.7 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

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

format and range of floating point numbers:
     The ‘double’ type of C, which is IEEE DP FP (binary64) on most
     platforms (exception: ARM with soft floats).

results of ‘REPRESENT’ when float is out of range:
     ‘Represent’ produces results for all inputs.  For infinities, it
     produces as much of "infinity" or "-infinity" as fits in the
     buffer.  For NaNs, it produces as much of "NaN" as fits in the
     buffer.  The remaining buffer is filled with spaces.  For
     infinities and NaNs, flag2 (valid) is false, otherwise true.

rounding or truncation of floating-point numbers:
     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

8.7.2 Ambiguous conditions
--------------------------

‘df@’ or ‘df!’ used with an address that is not double-float aligned:
     Hardware-dependent.  If the hardware does not support unaligned
     accesses, this typically results in a ‘-23 THROW’ like other
     alignment violations.

‘f@’ or ‘f!’ used with an address that is not float aligned:
     Hardware-dependent.  If the hardware does not support unaligned
     accesses, this typically results in a ‘-23 THROW’ like other
     alignment violations.

floating-point result out of range:
     An FP value is returned (so nothing is out of range), but it may be
     an infinity or a NaN.

‘sf@’ or ‘sf!’ used with an address that is not single-float aligned:
     Hardware-dependent.  If the hardware does not support unaligned
     accesses, this typically results in a ‘-23 THROW’ like other
     alignment violations.

‘base’ is not decimal (‘REPRESENT’, ‘F.’, ‘FE.’, ‘FS.’):
     Conversion between FP and string representations always use
     decimal, irrespective of ‘base’.

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:
     On IEEE FP based systems, prouces an infinity or a NaN.

exponent too big for conversion (‘DF!’, ‘DF@’, ‘SF!’, ‘SF@’):
     On IEEE-FP based systems the number is converted into an infinity.

float<1 (‘FACOSH’):
     On IEEE-FP based systems this produces a NaN.

float<=-1 (‘FLNP1’):
     On IEEE-FP based systems this produces a NaN (or a negative
     infinity for float=-1).

float<=0 (‘FLN’, ‘FLOG’):
     On IEEE-FP based systems this produces a NaN (or a negative
     infinity for float=0).

float<0 (‘FASINH’, ‘FSQRT’):
     On IEEE-FP based systems, for ‘fsqrt’ this gives a NaN, for
     ‘fasinh’ some platforms produce a NaN, others a number.

|float|>1 (‘FACOS’, ‘FASIN’, ‘FATANH’):
     IEEE-FP based systems 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.’):
     These words do not use the pictured numeric output buffer, but a
     buffer big enough for the needs of these words.


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

8.8 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

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

maximum number of locals in a definition:
     Gforth has a ‘locals-headers’ section with 19KB free.  How many
     locals fit in that section depends on the length of the locals
     names.  On a 64-bit machine a local takes about 40 bytes plus the
     length of the name, rounded up to 8.  So with typical use, several
     hundred locals fit.


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

8.8.2 Ambiguous conditions
--------------------------

executing a named local in interpretation state:
     Compiles the local into the current definition (just as in compile
     state); in addition text-interpreting a local in interpretation
     state gives an "is compile-only" warning.

name not defined by ‘VALUE’ or ‘(LOCAL)’ (‘TO’):
     ‘-21 throw’ (Unsupported operation)


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

8.9 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

8.9.1 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: Standard conformance

8.10 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

8.10.1 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 Search-Order word set.

source and format of display by ‘SEE’:
     The source for ‘see’ is the word header and possibly body data; for
     colon definitions ‘see’ decompiles the threaded code; for
     primitives ‘see’ disassembles the machine code.


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

8.10.2 Ambiguous conditions
---------------------------

deleting the compilation word list (‘FORGET’):
     Not implemented.

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 stack underflow error.  If you
     are unlucky, this ambiguous condition is not caught.

name can't be found (‘FORGET’):
     Not implemented.

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]’:
     While in a taken branch of an ‘[if]’ or ‘[if]’...‘[else]’, ‘[then]’
     is ignored, and it's absence is not noticed.

     While in a non-taken-branch, the end of the input source is
     considered to be the end of the ‘[if]’ construct, and the missing
     ‘[then]’ is reported in a warning.

removing a needed definition (‘FORGET’):
     Not implemented.


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

8.11 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

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

maximum number of word lists in search order:
     Only limited by memory.

minimum search order:
     ‘root root’.


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

8.11.2 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
     ‘latest’ or ‘latestxt’), if possible, irrespective of the
     compilation word list.

search order empty (‘previous’):
     ‘-4 throw’ (stack underflow).  You can distinguish this from data
     stack underflows by having ‘throw’ on the top of the backtrace and
     ‘stack>’ close by.

too many word lists in search order (‘also’):
     The search order size in Gforth is only limited by memory, and when
     the ‘resize’ fails, an appropriate exception is thrown.  However,
     if you use ‘get-order’, you will probably get a data stack overflow
     at a much smaller size (by default, the data stack can hold 4K
     elements).


File: gforth.info,  Node: Standard vs Extensions,  Next: Integrating Gforth,  Prev: Standard conformance,  Up: Top

9 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 Standard
     Forth.  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 Standard
     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
     Standard Forth compliant; just include the appropriate compat files
     with your program.

   • The tool ‘ans-report.fs’ (*note Standard 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 Standard 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.  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 considerations, 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
(https://forth-standard.org/standard/words).  Appendix A of the Standard
(RATIONALE) provides valuable insight into the thought processes of the
standardization 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).


File: gforth.info,  Node: Integrating Gforth,  Next: Emacs and Gforth,  Prev: Standard vs Extensions,  Up: Top

10 Integrating Gforth into C programs
*************************************

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 Standard 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’ or ‘libgforth.so’ (give the compiler the option
‘-lgforth’, or for one of the other engines ‘-lgforth-fast’,
‘-lgforth-itc’, or ‘-lgforth-ditc’).  All global symbols in this library
that belong to the interface, have the prefix ‘gforth_’; if a common
interface emerges, the functions may also be available through
‘#define’s with the prefix ‘forth_’.

   You can include the declarations of Forth types, the functions and
variables of the interface with ‘#include <gforth.h>’.

   As an example, you can build a small program to call the gforth
library as follows:

     #include <gforth.h>

     Cell main(int argc, char **argv, char **env)
     {
       Cell retvalue=gforth_start(argc, argv);

       if(retvalue == -56) { /* throw-code for quit */
         gforth_bootmessage();     // show boot message
         retvalue = gforth_quit(); // run quit loop
       }
       gforth_cleanup();
       gforth_printmetrics();
       // gforth_free_dict(); // if you want to restart, do this

       return retvalue;
     }

   This was compiled as follows (from the gforth source and build
directory, adjust the directories as appropriate):

     gcc -static -I engine -I include -L engine/.libs xxx.c -lgforth -lm -lltdl

   To interact with the Forth interpreter, there's ‘Xt gforth_find(Char
* name)’ and ‘Cell gforth_execute(Xt xt)’.

   More documentation needs to be put here.

10.1 Types
==========

‘Cell’, ‘UCell’: cell (data and return stack element)

   ‘Float’: float (FP stack element)

   ‘Address’: Memory address (a cell)

   ‘Xt’: execution token (a cell)

10.2 Variables
==============

‘gforth_SP’: data stack pointer.

   ‘gforth_FP’: FP stack pointer.

10.3 Functions
==============

     void *gforth_engine(Xt *, stackpointers *);
     Cell gforth_main(int argc, char **argv, char **env);
     int gforth_args(int argc, char **argv, char **path, char **imagename);
     ImageHeader* gforth_loader(char* imagename, char* path);
     user_area* gforth_stacks(Cell dsize, Cell rsize, Cell fsize, Cell lsize);
     void gforth_free_stacks(user_area* t);
     void gforth_setstacks(user_area * t);
     void gforth_free_dict();
     Cell gforth_go(Xt* ip0);
     Cell gforth_boot(int argc, char** argv, char* path);
     void gforth_bootmessage();
     Cell gforth_start(int argc, char ** argv);
     Cell gforth_quit();
     Xt gforth_find(Char * name);
     Cell gforth_execute(Xt xt);
     void gforth_cleanup();
     void gforth_printmetrics();
     void gforth_setwinch();

10.4 Signals
============

Gforth sets up signal handlers to catch exceptions and window size
changes.  This may interfere with your C program.


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

11 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 handling of indentation.
   • A custom hilighting engine for Forth-code.
   • 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.
   • Support for reading and writing blocks files.

   To get a basic 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).

   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 ‘:’.

* Menu:

* Installing gforth.el::        Making Emacs aware of Forth.
* Emacs Tags::                  Viewing the source of a word in Emacs.
* Hilighting::                  Making Forth code look prettier.
* Auto-Indentation::            Customizing auto-indentation.
* Blocks Files::                Reading and writing blocks files.


File: gforth.info,  Node: Installing gforth.el,  Next: Emacs Tags,  Prev: Emacs and Gforth,  Up: Emacs and Gforth

11.1 Installing gforth.el
=========================

To make the features from ‘gforth.el’ available in Emacs, add the
following lines to your ‘.emacs’ file:

     (autoload 'forth-mode "gforth.el")
     (setq auto-mode-alist (cons '("\\.fs\\'" . forth-mode)
                                 auto-mode-alist))
     (autoload 'forth-block-mode "gforth.el")
     (setq auto-mode-alist (cons '("\\.fb\\'" . forth-block-mode)
                                 auto-mode-alist))
     (add-hook 'forth-mode-hook (function (lambda ()
        ;; customize variables here:
        (setq forth-indent-level 4)
        (setq forth-minor-indent-level 2)
        (setq forth-hilight-level 3)
        ;;; ...
     )))


File: gforth.info,  Node: Emacs Tags,  Next: Hilighting,  Prev: Installing gforth.el,  Up: Emacs and Gforth

11.2 Emacs Tags
===============

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

