gforth/doc/gforth.ds - diff

Return to gforth.ds CVS log

Up to [gforth] / gforth / doc

Diff for /gforth/doc/gforth.ds between versions 1.43 and 1.44

version 1.43, 1999/11/06 15:01:16	version 1.44, 1999/11/08 21:33:17
Line 95 Copyright @copyright{} 1995-1999 Free So	Line 95 Copyright @copyright{} 1995-1999 Free So
@center Bernd Paysan	@center Bernd Paysan
@center Jens Wilke	@center Jens Wilke
@sp 3	@sp 3
@center This manual is permanently under construction and was last updated on 04-May-1999	@center This manual is permanently under construction and was last updated on 05-Jun-1999

@comment The following two commands start the copyright page.	@comment The following two commands start the copyright page.
@page	@page
Line 242 Control Structures	Line 242 Control Structures

Defining Words	Defining Words

* Simple Defining Words:: Variables, values and constants	* @code{CREATE}::
	* Variables:: Variables and user variables
	* Constants::
	* Values:: Initialised variables
* Colon Definitions::	* Colon Definitions::
	* Anonymous Definitions:: Definitions without names
* User-defined Defining Words::	* User-defined Defining Words::
	* Deferred words:: Allow forward references
	* Aliases::
* Supplying names::	* Supplying names::
* Interpretation and Compilation Semantics::	* Interpretation and Compilation Semantics::
	* Combined words::

The Text Interpreter	The Text Interpreter

Line 1166 the system before leaving Gforth.	Line 1173 the system before leaving Gforth.

doc-bye	doc-bye


@comment ----------------------------------------------	@comment ----------------------------------------------
@node Command-line editing, Upper and lower case,Leaving Gforth,Gforth Environment	@node Command-line editing, Upper and lower case,Leaving Gforth,Gforth Environment
@section Command-line editing	@section Command-line editing
Line 1177 used to provide a command-line recall fa	Line 1185 used to provide a command-line recall fa
repeatedly you can recall successively older commands from this (or	repeatedly you can recall successively older commands from this (or
previous) session(s). The full list of command-line editing facilities is:	previous) session(s). The full list of command-line editing facilities is:

@comment use @table? - anton
@itemize @bullet	@itemize @bullet
@item	@item
@kbd{Ctrl-p} (``previous'') (or up-arrow) to recall successively older	@kbd{Ctrl-p} (``previous'') (or up-arrow) to recall successively older
Line 1234 Gforth never trims the size of the histo	Line 1241 Gforth never trims the size of the histo
periodically, if necessary.	periodically, if necessary.

@comment this is all defined in history.fs	@comment this is all defined in history.fs
	@comment NAC TODO the ctrl-D behaviour can either do a bye or a beep.. how is that option
	@comment chosen?



Line 1243 periodically, if necessary.	Line 1252 periodically, if necessary.
@cindex case-sensitivity	@cindex case-sensitivity
@cindex upper and lower case	@cindex upper and lower case

Gforth is case-insensitive, so you can enter definitions and invoke	Gforth is case-insensitive; you can enter definitions and invoke
Standard words using upper, lower or mixed case (however,	Standard words using upper, lower or mixed case (however,
@pxref{core-idef, Implementation-defined options, Implementation-defined	@pxref{core-idef, Implementation-defined options, Implementation-defined
options}).	options}).
Line 1280 Gforth uses these environment variables:	Line 1289 Gforth uses these environment variables:

@itemize @bullet	@itemize @bullet
@item	@item
@cindex GFORTHHIST - environment variable	@cindex @code{GFORTHHIST} -- environment variable
GFORTHHIST - (Unix systems only) specifies the directory in which to	@code{GFORTHHIST} -- (Unix systems only) specifies the directory in which to
open/create the history file, @file{.gforth-history}. Default:	open/create the history file, @file{.gforth-history}. Default:
@code{$HOME}.	@code{$HOME}.

@item	@item
@cindex GFORTHPATH - environment variable	@cindex @code{GFORTHPATH} -- environment variable
GFORTHPATH - specifies the path used when searching for the gforth image file and	@code{GFORTHPATH} -- specifies the path used when searching for the gforth image file and
for Forth source-code files.	for Forth source-code files.

@item	@item
@cindex GFORTH - environment variable	@cindex @code{GFORTH} -- environment variable
GFORTH - used by @file{gforthmi} @xref{gforthmi}.	@code{GFORTH} -- used by @file{gforthmi} @xref{gforthmi}.

@item	@item
@cindex GFORTHD - environment variable	@cindex @code{GFORTHD} -- environment variable
GFORTHD - used by @file{gforthmi} @xref{gforthmi}.	@code{GFORTHD} -- used by @file{gforthmi} @xref{gforthmi}.

@item	@item
@cindex TMP, TEMP - environment variable	@cindex @code{TMP}, @code{TEMP} - environment variable
TMP, TEMP - (non-Unix systems only) used as a potential location for the	@code{TMP}, @code{TEMP} - (non-Unix systems only) used as a potential
history file.	location for the history file.
@end itemize	@end itemize

@comment also POSIXELY_CORRECT LINES COLUMNS HOME but no interest in	@comment also POSIXELY_CORRECT LINES COLUMNS HOME but no interest in
Line 1316 are not set.	Line 1325 are not set.
@section Gforth files	@section Gforth files
@cindex Gforth files	@cindex Gforth files

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

@itemize @bullet	@itemize @bullet
@item	@item
Line 1395 lead to great productivity improvements.	Line 1404 lead to great productivity improvements.
@c http://www.complang.tuwien.ac.at/anton/lvas/skriptum-stack.html	@c http://www.complang.tuwien.ac.at/anton/lvas/skriptum-stack.html
@c to see how I do it - anton	@c to see how I do it - anton

	@c nac-> Where I have accepted your comments 100% and modified the text
	@c accordingly, I have deleted your comments. Elsewhere I have added a
	@c response like this to attempt to rationalise what I have done. Of
	@c course, this is a very clumsy mechanism for something that would be
	@c done far more efficiently over a beer. Please delete any dialogue
	@c you consider closed.

When you invoke the Forth image, you will see a startup banner printed	When you invoke the Forth image, you will see a startup banner printed
and nothing else (if you have Gforth installed on your system, try	and nothing else (if you have Gforth installed on your system, try
invoking it now, by typing @kbd{gforth@key{RET}}). Forth is now running	invoking it now, by typing @kbd{gforth@key{RET}}). Forth is now running
Line 1438 group of characters in turn, it makes tw	Line 1454 group of characters in turn, it makes tw

@itemize @bullet	@itemize @bullet
@item	@item
	@cindex name dictionary
It tries to treat it as a command. It does this by searching a @dfn{name	It tries to treat it as a command. It does this by searching a @dfn{name
dictionary}. If the group of characters matches an entry in the name	dictionary}. If the group of characters matches an entry in the name
dictionary, the name dictionary provides the text interpreter with	dictionary, the name dictionary provides the text interpreter with
Line 1843 words of your own.	Line 1860 words of your own.
@c be better to keep them (or add run-time semantics), to make it easier to	@c be better to keep them (or add run-time semantics), to make it easier to
@c explain what compilation semantics usually does. - anton	@c explain what compilation semantics usually does. - anton

	@c nac-> I removed the term ``default compilation sematics'' from the
	@c introductory chapter. Removing ``execution semantics'' was making
	@c everything simpler to explain, then I think the use of this term made
	@c everything more complex again. I replaced it with ``default
	@c semantics'' (which is used elsewhere in the manual) by which I mean
	@c ``a definition that has neither the immediate nor the compile-only
	@c flag set''. I reworded big chunks of the ``how does that work''
	@c section (and, unusually for me, I think I even made it shorter!). See
	@c what you think -- I know I have not addressed your primary concern
	@c that it is too heavy-going for an introduction. From what I understood
	@c of your course notes it looks as though they might be a good framework.
	@c Things that I've tried to capture here are some things that came as a
	@c great revelation here when I first understood them. Also, I like the
	@c fact that a very simple code example shows up almost all of the issues
	@c that you need to understand to see how Forth works. That's unique and
	@c worthwhile to emphasise.

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

@example	@example
@kbd{: add-two 2 + . " ;@key{RET}}	@kbd{: add-two 2 + . ;@key{RET}}
^^^^^^^	^^^^^^^
Error: Undefined word	Error: Undefined word
@end example	@end example
Line 1859 works. The word @code{:} does two specia	Line 1893 works. The word @code{:} does two specia
thing that it does prevents the text interpreter from ever seeing the	thing that it does prevents the text interpreter from ever seeing the
characters @code{add-two}. The text interpreter uses a variable called	characters @code{add-two}. The text interpreter uses a variable called
@cindex modifying >IN	@cindex modifying >IN
@code{>IN} (pronounced ''to-in'') to keep track of where it is in the	@code{>IN} (pronounced ``to-in'') to keep track of where it is in the
input line. When it encounters the word @code{:} it behaves in exactly	input line. When it encounters the word @code{:} it behaves in exactly
the same way as it does for any other word; it looks it up in the name	the same way as it does for any other word; it looks it up in the name
dictionary, finds its xt and executes it. When @code{:} executes, it	dictionary, finds its xt and executes it. When @code{:} executes, it
Line 1883 variable called @code{state}, which affe	Line 1917 variable called @code{state}, which affe
interpreter behaves. When Gforth starts up, @code{state} has the value	interpreter behaves. When Gforth starts up, @code{state} has the value
0, and the text interpreter is said to be @dfn{interpreting}. During a	0, and the text interpreter is said to be @dfn{interpreting}. During a
colon definition (started with @code{:}), @code{state} is set to -1 and	colon definition (started with @code{:}), @code{state} is set to -1 and
the text interpreter is said to be @dfn{compiling}. The word @code{;}	the text interpreter is said to be @dfn{compiling}.
ends the definition -- one of the things that it does is to change the
value of @code{state} back to 0.	In this example, the text interpreter is compiling when it processes the
	string ``@code{2 + . ;}''. It still breaks the string down into
We have already seen how the text interpreter behaves when it is	character sequences in the same way. However, instead of pushing the
interpreting; it looks for each character sequence in the dictionary,	number @code{2} onto the stack, it lays down (@dfn{compiles}) some magic
finds its xt and executes it, or it converts it to a number and pushes	into the definition of @code{add-two} that will make the number @code{2} get
it onto the stack, or it fails to do either and generates an error.	pushed onto the stack when @code{add-two} is @dfn{executed}. Similarly,
	the behaviours of @code{+} and @code{.} are also compiled into the
When the text interpreter is compiling, its behaviour is slightly	definition.
different; it still looks for each character sequence in the dictionary
and finds it, or converts it to a number, or fails to do either and	One category of words don't get compiled. These so-called @dfn{immediate
generates an error. But instead of the execution token of a word it	words} get executed (performed @i{now}) regardless of whether the text
finds and executes the compilation token. For most words executing the	interpreter is interpreting or compiling. The word @code{;} is an
compilation token results in laying down (@dfn{compiling}) the execution	immediate word. Rather than being compiled into the definition, it
token, i.e., some magic to make that xt or number get executed or pushed	executes. Its effect is to terminate the current definition, which
at a later time; at the time that @code{add-two} is	includes changing the value of @code{state} back to 0.
@dfn{executed}. Therefore, when you execute @code{add-two} its
@dfn{run-time effect} is exactly the same as if you had typed @code{2 +	When you execute @code{add-two}, it has a @dfn{run-time effect} that is
.} outside of a definition, and pressed carriage-return.	exactly the same as if you had typed @code{2 + . @key{RET}} outside of a
	definition.

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

@itemize @bullet	@itemize @bullet
@item	@item
Its @dfn{interpretation semantics}, represented by the execution token.
@item
Its @dfn{compilation semantics}, represented by the compilation token.
@end itemize

The value of @code{state} determines whether the text interpreter will
use the compilation or interpretation semantics of a word or number that
it encounters.

@itemize @bullet
@item
@cindex interpretation semantics	@cindex interpretation semantics
When the text interpreter encounters a word or number in @dfn{interpret}	Its @dfn{interpretation semantics} describe how it will behave when the
state, it performs the @dfn{interpretation semantics} of the word or	text interpreter encounters it in @dfn{interpret} state. The
number.	interpretation semantics of a word are represented by an @dfn{execution
	token}.
@item	@item
@cindex compilation semantics	@cindex compilation semantics
When the text interpreter encounters a word or number in @dfn{compile}	Its @dfn{compilation semantics} describe how it will behave when the
state, it performs the @dfn{compilation semantics} of the word or	text interpreter encounters it in @dfn{compile} state. The compilation
number.	semantics of a word are represented in an implementation-dependent way;
	Gforth uses a @dfn{compilation token}.
@end itemize	@end itemize

@noindent	@noindent
Line 1936 Numbers are always treated in a fixed wa	Line 1962 Numbers are always treated in a fixed wa

@itemize @bullet	@itemize @bullet
@item	@item
When the number is @dfn{interpreted}, its behaviour is to push the number onto the stack.	When the number is @dfn{interpreted}, its behaviour is to push the
	number onto the stack.
@item	@item
When the number is @dfn{compiled}, a piece of code is appended to the	When the number is @dfn{compiled}, a piece of code is appended to the
current definition that pushes the number when it runs. (In other words,	current definition that pushes the number when it runs. (In other words,
Line 1945 semantics until the run-time of the defi	Line 1972 semantics until the run-time of the defi
into.)	into.)
@end itemize	@end itemize

The behaviour of a word is not so regular, but most have @i{default	Words don't behave in such a regular way, but most have @i{default
compilation semantics} which means that they behave like this:	semantics} which means that they behave like this:

@itemize @bullet	@itemize @bullet
@item	@item
Line 1958 run-time behaviour is to do something us	Line 1985 run-time behaviour is to do something us
@end itemize	@end itemize

@cindex immediate words	@cindex immediate words
The actual behaviour of any particular word depends upon the way in	The actual behaviour of any particular word can be controlled by using
which it was defined. When the text interpreter finds the word in the	the words @code{immediate} and @code{compile-only} when the word is
name dictionary, it not only retrieves the xt for the word, it also	defined. These words set flags in the name dictionary entry of the most
retrieves some flags: the @dfn{compile-only} flag and the @dfn{immediate	recently defined word, and these flags are retrieved by the text
flag}. The compile-only flag indicates that the word has no	interpreter when it finds the word in the name dictionary.
interpretation semantics (the run-time behaviour for the default
compilation semantics is not affected by this flag, however); any	A word that is marked as @dfn{immediate} has compilation semantics that
attempt to interpret a word that has the compile-only flag set will	are identical to its interpretation semantics. In other words, it
generate an error (for example, @code{IF} has no interpretation	behaves like this:
semantics). The immediate flag changes the compilation semantics of the
word; if it is set, the compilation semantics are equal to the
interpretation semantics (again ignoring the compile-only flag). it. In
other words, these so-called @dfn{immediate} words behave like this:

@itemize @bullet	@itemize @bullet
@item	@item
Line 1980 The @dfn{compilation semantics} of the w	Line 2003 The @dfn{compilation semantics} of the w
(and actually the same thing); i.e., it is executed during compilation.	(and actually the same thing); i.e., it is executed during compilation.
@end itemize	@end itemize

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

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

Line 2363 quotes.	Line 2399 quotes.
Forth supports two styles of comment; the traditional @i{in-line} comment,	Forth supports two styles of comment; the traditional @i{in-line} comment,
@code{(} and its modern cousin, the @i{comment to end of line}; @code{\}.	@code{(} and its modern cousin, the @i{comment to end of line}; @code{\}.


doc-(	doc-(
doc-\	doc-\
doc-\G	doc-\G


@node Boolean Flags, Arithmetic, Comments, Words	@node Boolean Flags, Arithmetic, Comments, Words
@section Boolean Flags	@section Boolean Flags
@cindex Boolean flags	@cindex Boolean flags
Line 2376 flag @code{false} and a flag with all bi	Line 2414 flag @code{false} and a flag with all bi
@code{true}. Words that check a flag (for example, @code{IF}) will treat	@code{true}. Words that check a flag (for example, @code{IF}) will treat
a cell that has @i{any} bit set as @code{true}.	a cell that has @i{any} bit set as @code{true}.


doc-true	doc-true
doc-false	doc-false
doc-on	doc-on
doc-off	doc-off


@node Arithmetic, Stack Manipulation, Boolean Flags, Words	@node Arithmetic, Stack Manipulation, Boolean Flags, Words
@section Arithmetic	@section Arithmetic
@cindex arithmetic words	@cindex arithmetic words
Line 2415 cell in size. They can be signed or unsi	Line 2455 cell in size. They can be signed or unsi
treat them. @xref{Number Conversion} for the rules used by the text	treat them. @xref{Number Conversion} for the rules used by the text
interpreter for recognising single-precision integers.	interpreter for recognising single-precision integers.


doc-+	doc-+
doc-1+	doc-1+
doc--	doc--
Line 2430 doc-max	Line 2471 doc-max
doc-d>s	doc-d>s
doc-floored	doc-floored


@node Bitwise operations, Double precision, Single precision, Arithmetic	@node Bitwise operations, Double precision, Single precision, Arithmetic
@subsection Bitwise operations	@subsection Bitwise operations
@cindex bitwise operation words	@cindex bitwise operation words


doc-and	doc-and
doc-or	doc-or
doc-xor	doc-xor
Line 2445 doc-d2*	Line 2488 doc-d2*
doc-2/	doc-2/
doc-d2/	doc-d2/


@node Double precision, Numeric comparison, Bitwise operations, Arithmetic	@node Double precision, Numeric comparison, Bitwise operations, Arithmetic
@subsection Double precision	@subsection Double precision
@cindex double precision arithmetic words	@cindex double precision arithmetic words
Line 2462 using @code{s>d}. The moral of the story	Line 2506 using @code{s>d}. The moral of the story
number without knowing whether it represents an unsigned or a	number without knowing whether it represents an unsigned or a
signed number.	signed number.


doc-s>d	doc-s>d
doc-d+	doc-d+
doc-d-	doc-d-
Line 2470 doc-dabs	Line 2515 doc-dabs
doc-dmin	doc-dmin
doc-dmax	doc-dmax


@node Numeric comparison, Mixed precision, Double precision, Arithmetic	@node Numeric comparison, Mixed precision, Double precision, Arithmetic
@subsection Numeric comparison	@subsection Numeric comparison
@cindex numeric comparison words	@cindex numeric comparison words


doc-<	doc-<
doc-<=	doc-<=
doc-<>	doc-<>
Line 2490 doc-0>=	Line 2537 doc-0>=

doc-u<	doc-u<
doc-u<=	doc-u<=
@c TODO why u<> and u= ... they are the same as <> and =	@c u<> and u= exist but are the same as <> and =
@c commented them out because they are unnecessary
@c doc-u<>	@c doc-u<>
@c doc-u=	@c doc-u=
doc-u>	doc-u>
Line 2515 doc-d0>=	Line 2561 doc-d0>=

doc-du<	doc-du<
doc-du<=	doc-du<=
	@c du<> and du= exist but are the same as d<> and d=
@c doc-du<>	@c doc-du<>
@c doc-du=	@c doc-du=
doc-du>	doc-du>
doc-du>=	doc-du>=


@node Mixed precision, Floating Point, Numeric comparison, Arithmetic	@node Mixed precision, Floating Point, Numeric comparison, Arithmetic
@subsection Mixed precision	@subsection Mixed precision
@cindex mixed precision arithmetic words	@cindex mixed precision arithmetic words


doc-m+	doc-m+
doc-*/	doc-*/
doc-*/mod	doc-*/mod
Line 2534 doc-um/mod	Line 2583 doc-um/mod
doc-fm/mod	doc-fm/mod
doc-sm/rem	doc-sm/rem


@node Floating Point, , Mixed precision, Arithmetic	@node Floating Point, , Mixed precision, Arithmetic
@subsection Floating Point	@subsection Floating Point
@cindex floating point arithmetic words	@cindex floating point arithmetic words
Line 2555 Computer Scientist Should Know About Flo	Line 2605 Computer Scientist Should Know About Flo
Computing Surveys 23(1):5@minus{}48, March 1991}	Computing Surveys 23(1):5@minus{}48, March 1991}
(@url{http://www.validgh.com/goldberg/paper.ps}).	(@url{http://www.validgh.com/goldberg/paper.ps}).


doc-d>f	doc-d>f
doc-f>d	doc-f>d
doc-f+	doc-f+
Line 2644 characters, cells, addresses, and double	Line 2695 characters, cells, addresses, and double

@cindex floating-point stack	@cindex floating-point stack
@item	@item
A floating point stack -- for floating point numbers.	A floating point stack -- for holding floating point (FP) numbers.

@cindex return stack	@cindex return stack
@item	@item
A return stack -- for storing the return addresses of colon	A return stack -- for holding the return addresses of colon
definitions and other (non-FP) data.	definitions and other (non-FP) data.

@cindex locals stack	@cindex locals stack
@item	@item
A locals stack for storing local variables.	A locals stack -- for holding local variables.
@end itemize	@end itemize

@menu	@menu
Line 2669 A locals stack for storing local variabl	Line 2720 A locals stack for storing local variabl
@cindex data stack manipulation words	@cindex data stack manipulation words
@cindex stack manipulations words, data stack	@cindex stack manipulations words, data stack


doc-drop	doc-drop
doc-nip	doc-nip
doc-dup	doc-dup
Line 2688 doc-2tuck	Line 2740 doc-2tuck
doc-2swap	doc-2swap
doc-2rot	doc-2rot


@node Floating point stack, Return stack, Data stack, Stack Manipulation	@node Floating point stack, Return stack, Data stack, Stack Manipulation
@subsection Floating point stack	@subsection Floating point stack
@cindex floating-point stack manipulation words	@cindex floating-point stack manipulation words
Line 2713 doc-fswap	Line 2766 doc-fswap
doc-fpick	doc-fpick
doc-frot	doc-frot


@node Return stack, Locals stack, Floating point stack, Stack Manipulation	@node Return stack, Locals stack, Floating point stack, Stack Manipulation
@subsection Return stack	@subsection Return stack
@cindex return stack manipulation words	@cindex return stack manipulation words
Line 2736 doc-2r>	Line 2790 doc-2r>
doc-2r@	doc-2r@
doc-2rdrop	doc-2rdrop


@node Locals stack, Stack pointer manipulation, Return stack, Stack Manipulation	@node Locals stack, Stack pointer manipulation, Return stack, Stack Manipulation
@subsection Locals stack	@subsection Locals stack

Line 2745 doc-2rdrop	Line 2800 doc-2rdrop
@subsection Stack pointer manipulation	@subsection Stack pointer manipulation
@cindex stack pointer manipulation words	@cindex stack pointer manipulation words

	@c removed s0 r0 l0 -- they are obsolete aliases for sp0 rp0 lp0
doc-sp0	doc-sp0
doc-sp@	doc-sp@
doc-sp!	doc-sp!
Line 2758 doc-lp0	Line 2814 doc-lp0
doc-lp@	doc-lp@
doc-lp!	doc-lp!


@node Memory, Control Structures, Stack Manipulation, Words	@node Memory, Control Structures, Stack Manipulation, Words
@section Memory	@section Memory
@cindex memory words	@cindex memory words
Line 2808 from one run to the next).	Line 2865 from one run to the next).

@subsubsection ANS Forth dictionary details	@subsubsection ANS Forth dictionary details

@c !! I have deleted some of the stuff this section refers to - anton

This section is just informative, you can skip it if you are in a hurry.	This section is just informative, you can skip it if you are in a hurry.

When you create a colon definition, the text interpreter compiles the	When you create a colon definition, the text interpreter compiles the
Line 2817 code for the definition into the code sp	Line 2872 code for the definition into the code sp
of the definition into the header space, together with other	of the definition into the header space, together with other
information about the definition (such as its execution token).	information about the definition (such as its execution token).

When you create a variable, the execution of @code{variable} will	When you create a variable, the execution of @code{Variable} will
compile some code, assign one cell in data space, and compile the name	compile some code, assign one cell in data space, and compile the name
of the variable into the header space.	of the variable into the header space.

Line 2904 on the @i{target} system could implement	Line 2959 on the @i{target} system could implement
communication link that would allow it to interrogate the header space.	communication link that would allow it to interrogate the header space.
@end itemize	@end itemize


@node Dictionary allocation, Heap Allocation, Memory model, Memory	@node Dictionary allocation, Heap Allocation, Memory model, Memory
@subsection Dictionary allocation	@subsection Dictionary allocation
@cindex reserving data space	@cindex reserving data space
Line 2979 doc-resize	Line 3033 doc-resize
@subsection Memory Access	@subsection Memory Access
@cindex memory access words	@cindex memory access words


doc-@	doc-@
doc-!	doc-!
doc-+!	doc-+!
Line 3032 are aligned for all purposes.	Line 3087 are aligned for all purposes.
Note that the ANS Forth word @code{char} has nothing to do with address	Note that the ANS Forth word @code{char} has nothing to do with address
arithmetic.	arithmetic.


doc-chars	doc-chars
doc-char+	doc-char+
doc-cells	doc-cells
Line 3052 doc-maxaligned	Line 3108 doc-maxaligned
doc-cfaligned	doc-cfaligned
doc-address-unit-bits	doc-address-unit-bits


@node Memory Blocks, , Address arithmetic, Memory	@node Memory Blocks, , Address arithmetic, Memory
@subsection Memory Blocks	@subsection Memory Blocks
@cindex memory block words	@cindex memory block words
Line 3075 You can only use any of these words @i{p	Line 3132 You can only use any of these words @i{p
@comment describes MOVE as a word that requires a CELL-aligned source	@comment describes MOVE as a word that requires a CELL-aligned source
@comment and destination address but a xtranfer count that need not	@comment and destination address but a xtranfer count that need not
@comment be a multiple of CELL.	@comment be a multiple of CELL.

doc-move	doc-move
doc-erase	doc-erase
doc-cmove	doc-cmove
Line 3086 doc-search	Line 3144 doc-search
doc--trailing	doc--trailing
doc-/string	doc-/string


@comment TODO examples	@comment TODO examples


Line 3116 yet, although many schemes have been pro	Line 3175 yet, although many schemes have been pro
@c what's the purpose of all these @i? Maybe we should define a macro	@c what's the purpose of all these @i? Maybe we should define a macro
@c so we can produce logical markup. - anton	@c so we can produce logical markup. - anton

	@c nac-> When I started working on the manual, a mixture of @i and @var
	@c were used inconsistently in code examples and \Glossary entries. These
	@c two behave differently in info format so I decided to standardize on @i.
	@c Logical markup would be better but texi isn't really upto it, and
	@c texi2html just ignores macros.

@cindex @code{IF} control structure	@cindex @code{IF} control structure
@example	@example
@i{flag}	@i{flag}
Line 3125 ENDIF	Line 3190 ENDIF
@end example	@end example
@noindent	@noindent

@var{code} is executed if @var{flag} is non-zero (that's truth as far as	If @i{flag} is non-zero (as far as @code{IF} etc. are concerned, a cell
@code{IF} etc. are concerned).	with any bit set represents truth) @i{code} is executed.

@example	@example
@i{flag}	@i{flag}
Line 3137 ELSE	Line 3202 ELSE
ENDIF	ENDIF
@end example	@end example

If @var{flag} is true, perform @var{code1}, otherwise @var{code2}.	If @var{flag} is true, @i{code1} is executed, otherwise @i{code2} is
	executed.

You can use @code{THEN} instead of @code{ENDIF}. Indeed, @code{THEN} is	You can use @code{THEN} instead of @code{ENDIF}. Indeed, @code{THEN} is
standard, and @code{ENDIF} is not, although it is quite popular. We	standard, and @code{ENDIF} is not, although it is quite popular. We
Line 3247 The index of the innermost loop can be a	Line 3313 The index of the innermost loop can be a
of the next loop with @code{j}, and the index of the third loop with	of the next loop with @code{j}, and the index of the third loop with
@code{k}.	@code{k}.


doc-i	doc-i
doc-j	doc-j
doc-k	doc-k


The loop control data are kept on the return stack, so there are some	The loop control data are kept on the return stack, so there are some
restrictions on mixing return stack accesses and counted loop words. In	restrictions on mixing return stack accesses and counted loop words. In
particuler, if you put values on the return stack outside the loop, you	particuler, if you put values on the return stack outside the loop, you
Line 3396 entry represents a backward branch targe	Line 3464 entry represents a backward branch targe
building any control structure possible (except control structures that	building any control structure possible (except control structures that
need storage, like calls, coroutines, and backtracking).	need storage, like calls, coroutines, and backtracking).


doc-if	doc-if
doc-ahead	doc-ahead
doc-then	doc-then
Line 3405 doc-again	Line 3474 doc-again
doc-cs-pick	doc-cs-pick
doc-cs-roll	doc-cs-roll


The Standard words @code{CS-PICK} and @code{CS-ROLL} allow you to	The Standard words @code{CS-PICK} and @code{CS-ROLL} allow you to
manipulate the control-flow stack in a portable way. Without them, you	manipulate the control-flow stack in a portable way. Without them, you
would need to know how many stack items are occupied by a control-flow	would need to know how many stack items are occupied by a control-flow
Line 3413 but this may change in the future).	Line 3483 but this may change in the future).

Some standard control structure words are built from these words:	Some standard control structure words are built from these words:


doc-else	doc-else
doc-while	doc-while
doc-repeat	doc-repeat


	@noindent
Gforth adds some more control-structure words:	Gforth adds some more control-structure words:


doc-endif	doc-endif
doc-?dup-if	doc-?dup-if
doc-?dup-0=-if	doc-?dup-0=-if


	@noindent
Counted loop words constitute a separate group of words:	Counted loop words constitute a separate group of words:


doc-?do	doc-?do
doc-+do	doc-+do
doc-u+do	doc-u+do
Line 3441 doc-?leave	Line 3518 doc-?leave
doc-unloop	doc-unloop
doc-done	doc-done


The standard does not allow using @code{CS-PICK} and @code{CS-ROLL} on	The standard does not allow using @code{CS-PICK} and @code{CS-ROLL} on
@i{do-sys}. Gforth allows it, but it's your job to ensure that for	@i{do-sys}. Gforth allows it, but it's your job to ensure that for
every @code{?DO} etc. there is exactly one @code{UNLOOP} on any path	every @code{?DO} etc. there is exactly one @code{UNLOOP} on any path
Line 3448 through the definition (@code{LOOP} etc.	Line 3526 through the definition (@code{LOOP} etc.
fall-through path). Also, you have to ensure that all @code{LEAVE}s are	fall-through path). Also, you have to ensure that all @code{LEAVE}s are
resolved (by using one of the loop-ending words or @code{DONE}).	resolved (by using one of the loop-ending words or @code{DONE}).

	@noindent
Another group of control structure words are:	Another group of control structure words are:


doc-case	doc-case
doc-endcase	doc-endcase
doc-of	doc-of
doc-endof	doc-endof


@i{case-sys} and @i{of-sys} cannot be processed using @code{CS-PICK} and	@i{case-sys} and @i{of-sys} cannot be processed using @code{CS-PICK} and
@code{CS-ROLL}.	@code{CS-ROLL}.

Line 3513 definition. If you want to write a direc	Line 3594 definition. If you want to write a direc
can use @code{recursive} to make the current definition visible, or	can use @code{recursive} to make the current definition visible, or
@code{recurse} to call the current definition directly.	@code{recurse} to call the current definition directly.


doc-recursive	doc-recursive
doc-recurse	doc-recurse


@comment TODO add example of the two recursion methods	@comment TODO add example of the two recursion methods
@quotation	@quotation
@progstyle	@progstyle
Line 3539 Defer foo	Line 3622 Defer foo
IS foo	IS foo
@end example	@end example

Deferred words are discussed in more detail in @ref{Simple	Deferred words are discussed in more detail in @ref{Deferred words}.
Defining Words}.

The current definition returns control to the calling definition when	The current definition returns control to the calling definition when
the end of the definition is reached or @code{EXIT} is encountered.	the end of the definition is reached or @code{EXIT} is encountered.
Line 3548 the end of the definition is reached or	Line 3630 the end of the definition is reached or
doc-exit	doc-exit
doc-;s	doc-;s


@node Exception Handling, , Calls and returns, Control Structures	@node Exception Handling, , Calls and returns, Control Structures
@subsection Exception Handling	@subsection Exception Handling
@cindex exceptions	@cindex exceptions
Line 3593 would be:	Line 3676 would be:
@end example	@end example

@c TOS is undefined. - anton	@c TOS is undefined. - anton

	@c nac-> TODO -- I need to look at this example again.

Whilst @code{foo} executes, it can call other words to any level of	Whilst @code{foo} executes, it can call other words to any level of
nesting, as usual. If @code{foo} (and all the words that it calls)	nesting, as usual. If @code{foo} (and all the words that it calls)
execute successfully, control will ultimately pass to the word following	execute successfully, control will ultimately pass to the word following
Line 3617 definition of @code{top-level} and work	Line 3703 definition of @code{top-level} and work
@example	@example
: lowest-level ( -- c )	: lowest-level ( -- c )
key dup 27 = if	key dup 27 = if
1 throw \ ESCAPE key pressed	1 throw \ ESCAPE key pressed
else	else
." lowest-level successfull" CR	." lowest-level successful" CR
then	then
;	;

Line 3627 definition of @code{top-level} and work	Line 3713 definition of @code{top-level} and work
lowest-level	lowest-level
\ at this level consider a CTRL-U to be a fatal error	\ at this level consider a CTRL-U to be a fatal error
dup 21 = if \ CTRL-U	dup 21 = if \ CTRL-U
2 throw	2 throw
else	else
." lower-level successfull" CR	." lower-level successful" CR
then	then
;	;

: low-level ( -- c )	: low-level ( -- c )
['] lower-level catch	['] lower-level catch
?dup if	?dup if
\ error occurred - do we recognise it?	\ error occurred - do we recognise it?
dup 1 = if	dup 1 = if
\ ESCAPE key pressed.. pretend it was an E	\ ESCAPE key pressed.. pretend it was an E
[char] E	[char] E
else throw \ propogate the error upwards	else throw \ propogate the error upwards
then	then
then	then
." low-level successfull" CR	." low-level successfull" CR
;	;
Line 3649 definition of @code{top-level} and work	Line 3735 definition of @code{top-level} and work
: top-level ( -- )	: top-level ( -- )
CR ['] low-level catch \ CATCH is used like EXECUTE	CR ['] low-level catch \ CATCH is used like EXECUTE
?dup if \ error occurred..	?dup if \ error occurred..
." Error " . ." occurred - contact your supplier"	." Error " . ." occurred - contact your supplier"
else	else
." The '" emit ." ' key was pressed" CR	." The '" emit ." ' key was pressed" CR
then	then
;	;
@end example	@end example
Line 3676 co-exist in memory without any clash of	Line 3762 co-exist in memory without any clash of
of @code{exception} in ANS Forth is provided in	of @code{exception} in ANS Forth is provided in
@file{compat/exception.fs}.	@file{compat/exception.fs}.


doc-quit	doc-quit
doc-abort	doc-abort
doc-abort"	doc-abort"
Line 3685 doc-throw	Line 3772 doc-throw
doc---exception-exception	doc---exception-exception



@c -------------------------------------------------------------	@c -------------------------------------------------------------
@node Defining Words, The Text Interpreter, Control Structures, Words	@node Defining Words, The Text Interpreter, Control Structures, Words
@section Defining Words	@section Defining Words
@cindex defining words	@cindex defining words

@menu	@menu
* Simple Defining Words:: Variables, values and constants	* CREATE::
	* Variables:: Variables and user variables
	* Constants::
	* Values:: Initialised variables
* Colon Definitions::	* Colon Definitions::
	* Anonymous Definitions:: Definitions without names
* User-defined Defining Words::	* User-defined Defining Words::
	* Deferred words:: Allow forward references
	* Aliases::
* Supplying names::	* Supplying names::
* Interpretation and Compilation Semantics::	* Interpretation and Compilation Semantics::
	* Combined words::
@end menu	@end menu

@node Simple Defining Words, Colon Definitions, Defining Words, Defining Words	@node CREATE, Variables, Defining Words, Defining Words
@subsection Simple Defining Words	@subsection @code{CREATE}
@cindex simple defining words	@cindex simple defining words
@cindex defining words, simple	@cindex defining words, simple

@c split this section?

Defining words are used to create new entries in the dictionary. The	Defining words are used to create new entries in the dictionary. The
simplest defining word is @code{CREATE}. @code{CREATE} is used like	simplest defining word is @code{CREATE}. @code{CREATE} is used like
this:	this:
Line 3738 . \ get address, fetch	Line 3831 . \ get address, fetch
1234 new-word2 ! \ new value, get address, store to it	1234 new-word2 ! \ new value, get address, store to it
@end example	@end example

As a final refinement, the whole code sequence can be wrapped up in a	@cindex arrays
defining word (pre-empting the subject of the next section), making it	A similar mechanism can be used to create arrays. For example, an
easier to create new variables:	80-character text input buffer:

@example	@example
: myvariable ( "name" -- a-addr ) CREATE 0 , ;	CREATE text-buf 80 chars allot

	text-buf 0 chars c@@ \ the 1st character (offset 0)
	text-buf 3 chars c@@ \ the 4th character (offset 3)
	@end example

myvariable foo	You can build arbitrarily complex data structures by allocating
myvariable joe	appropriate areas of memory. @xref{Structures} for further discussions
	of this, and to learn about some Gforth tools that make it easier.


	@node Variables, Constants, CREATE, Defining Words
	@subsection Variables
	@cindex variables

	The previous section showed how a sequence of commands could be used to
	generate a variable. As a final refinement, the whole code sequence can
	be wrapped up in a defining word (pre-empting the subject of the next
	section), making it easier to create new variables:

	@example
	: myvariableX ( "name" -- a-addr ) CREATE 1 cells allot ;
	: myvariable0 ( "name" -- a-addr ) CREATE 0 , ;

	myvariableX foo \ variable foo starts off with an unknown value
	myvariable0 joe \ whilst joe is initialised to 0

45 3 * foo ! \ set foo to 135	45 3 * foo ! \ set foo to 135
1234 joe ! \ set joe to 1234	1234 joe ! \ set joe to 1234
Line 3754 myvariable joe	Line 3869 myvariable joe
@end example	@end example

Not surprisingly, there is no need to define @code{myvariable}, since	Not surprisingly, there is no need to define @code{myvariable}, since
Forth already has a definition @code{Variable}. It behaves in exactly	Forth already has a definition @code{Variable}. ANS Forth does not
the same way as @code{myvariable}. Forth also provides @code{2Variable}	require a @code{Variable} to be initialised when it is created (i.e., it
and @code{fvariable} for double and floating-point variables,	behaves like @code{myvariableX}). In contrast, Gforth's @code{Variable}
respectively.	initialises the variable to 0 (i.e., it behaves exactly like
	@code{myvariable0}). Forth also provides @code{2Variable} and
	@code{fvariable} for double and floating-point variables,
	respectively -- both are initialised to 0 in Gforth.

doc-variable	doc-variable
doc-2variable	doc-2variable
doc-fvariable	doc-fvariable

@cindex arrays
A similar mechanism can be used to create arrays. For example, an
80-character text input buffer:

@example
CREATE text-buf 80 chars allot

text-buf 0 chars c@@ \ the 1st character (offset 0)
text-buf 3 chars c@@ \ the 4th character (offset 3)
@end example

You can build arbitrarily complex data structures by allocating
appropriate areas of memory. @xref{Structures} for further discussions
of this, and to learn about some Gforth tools that make it easier.

@cindex user variables	@cindex user variables
@cindex user space	@cindex user space
Line 3792 doc-user	Line 3896 doc-user
@comment should document tasker.fs (with some examples) elsewhere	@comment should document tasker.fs (with some examples) elsewhere
@comment in this manual, then expand on user space and user variables.	@comment in this manual, then expand on user space and user variables.

After @code{CREATE} and @code{Variable}s, the next defining word to
consider is @code{Constant}. @code{Constant} allows you to declare a	@node Constants, Values, Variables, Defining Words
fixed value and refer to it by name. For example:	@subsection Constants
	@cindex constants

	@code{Constant} allows you to declare a fixed value and refer to it by
	name. For example:

@example	@example
12 Constant INCHES-PER-FOOT	12 Constant INCHES-PER-FOOT
Line 3820 doc-2constant	Line 3928 doc-2constant
doc-fconstant	doc-fconstant

@c that's too deep, and it's not necessarily true for all ANS Forths. - anton	@c that's too deep, and it's not necessarily true for all ANS Forths. - anton
	@c nac-> How could that not be true in an ANS Forth? You can't define a
	@c constant, use it and then delete the definition of the constant..
	@c I agree that it's rather deep, but IMO it is an important difference
	@c relative to other programming languages.. often it's annoying: it
	@c certainly changes my programming style relative to C.

Constants in Forth behave differently from their equivalents in other	Constants in Forth behave differently from their equivalents in other
programming languages. In other languages, a constant (such as an EQU in	programming languages. In other languages, a constant (such as an EQU in
assembler or a #define in C) only exists at compile-time; in the	assembler or a #define in C) only exists at compile-time; in the
executable program the constant has been translated into an absolute	executable program the constant has been translated into an absolute
number and, unless you are using a symbolic debugger, it's impossible to	number and, unless you are using a symbolic debugger, it's impossible to
know what abstract thing that number represents. In Forth a constant has	know what abstract thing that number represents. In Forth a constant has
an entry in the header space and remains there after the code that	an entry in the header space and remains there after the code that uses
uses it has been defined. In fact, it must remain in the dictionary	it has been defined. In fact, it must remain in the dictionary since it
since it has run-time duties to perform. For example:	has run-time duties to perform. For example:

@example	@example
12 Constant INCHES-PER-FOOT	12 Constant INCHES-PER-FOOT
Line 3860 a second dictionary for holding transien	Line 3974 a second dictionary for holding transien
dictionary can be deleted later in order to recover memory	dictionary can be deleted later in order to recover memory
space. However, there is no standard way of doing this.	space. However, there is no standard way of doing this.

One aspect of constants and variables that can sometimes be confusing is
that they have different stack effects; one returns its value whilst the
other returns the address of its value. The defining word @code{Value}
provides an alternative to @code{Variable}, and has the same stack
effect as a constant. A @code{Value} needs an additional word, @code{TO}
to allow its value to be changed. Here are some examples:

@example	@node Values, Colon Definitions, Constants, Defining Words
12 Value APPLES \ a Value is initialised when it is declared.. like a	@subsection Values
\ constant but unlike a variable	@cindex values
34 TO APPLES \ Change the value of APPLES. TO is a parsing word
APPLES \ puts 34 on the top of the stack.
@end example

doc-value	A @code{Value} is like a @code{Variable} but with two important
doc-to	differences:

The defining word @code{Defer} allows you to define a word by name
without defining its behaviour; the definition of its behaviour is
deferred. Here are two situation where this can be useful:

@itemize @bullet	@itemize @bullet
@item	@item
Where you want to allow the behaviour of a word to be altered later, and	A @code{Value} is initialised when it is declared; like a
for all precompiled references to the word to change when its behaviour	@code{Constant} but unlike a @code{Variable}.
is changed.
@item	@item
For mutual recursion; @xref{Calls and returns}.	A @code{Value} returns its value rather than its address when it is
	executed; i.e., it has the same run-time behaviour as @code{Constant}.
@end itemize	@end itemize

In the following example, @code{foo} always invokes the version of	A @code{Value} needs an additional word, @code{TO} to allow its value to
@code{greet} that prints ``@code{Good morning}'' whilst @code{bar}	be changed. Here are some examples:
always invokes the version that prints ``@code{Hello}''. There is no way
of getting @code{foo} to use the later version without re-ordering the
source code and recompilng it.

@example	@example
: greet ." Good morning" ;	12 Value APPLES \ Define APPLES with an initial value of 12
: foo ... greet ... ;	34 TO APPLES \ Change the value of APPLES. TO is a parsing word
: greet ." Hello" ;	APPLES \ puts 34 on the top of the stack.
: bar ... greet ... ;
@end example	@end example

This problem can be solved by defining @code{greet} as a @code{Defer}red	doc-value
word. The behaviour of a @code{Defer}red word can be defined and	doc-to
redefined at any time by using @code{IS} to associate the xt of a
previously-defined word with it. The previous example becomes:

@example
Defer greet
: foo ... greet ... ;
: bar ... greet ... ;
: greet1 ." Good morning" ;
: greet2 ." Hello" ;
' greet2 <IS> greet \ make greet behave like greet2
@end example

One thing to note is that @code{<IS>} consumes it's name when it is	@node Colon Definitions, Anonymous Definitions, Values, Defining Words
executed. If you want to specify the name at compile time, use	@subsection Colon Definitions
@code{[IS]}:	@cindex colon definitions

@example	@example
: set-greet ( xt -- )	: name ( ... -- ... )
[IS] greet ;	word1 word2 word3 ;

' greet1 set-greet
@end example	@end example

A deferred word can only inherit default semantics from the xt (because	@noindent
that is all that an xt can represent -- @pxref{Tokens for Words} for	Creates a word called @code{name} that, upon execution, executes
more discussion of this). However, the semantics of the deferred word	@code{word1 word2 word3}. @code{name} is a @dfn{(colon) definition}.
itself can be modified at the time that it is defined. For example:

@example	The explanation above is somewhat superficial. @xref{Your first
: bar .... ; compile-only	definition} for simple examples of colon definitions, then
Defer fred immediate	@xref{Interpretation and Compilation Semantics} for an in-depth
Defer jim	discussion of some of the issues involved.

' bar <IS> jim \ jim has default semantics	doc-:
' bar <IS> fred \ fred is immediate	doc-;
@end example

doc-defer
doc-<is>
doc-[is]
@comment TODO document these: what's defers [is]
doc-what's
doc-defers

Definitions in ANS Forth for @code{defer}, @code{<is>} and	@node Anonymous Definitions, User-defined Defining Words, Colon Definitions, Defining Words
@code{[is]} are provided in @file{compat/defer.fs}.	@subsection Anonymous Definitions
	@cindex colon definitions
	@cindex defining words without name

The defining word @code{Alias} allows you to define a word by name that	Sometimes you want to define an @dfn{anonymous word}; a word without a
has the same behaviour as some other word. Here are two situation where	name. You can do this with:
this can be useful:

@itemize @bullet	doc-:noname
@item
When you want access to a word's definition from a different word list
(for an example of this, see the definition of the @code{Root} word list
in the Gforth source).
@item
When you want to create a synonym; a definition that can be known by
either of two names (for example, @code{THEN} and @code{ENDIF} are
aliases).
@end itemize

The word whose behaviour the alias is to inherit is represented by an	This leaves the execution token for the word on the stack after the
xt. Therefore, the alias only inherits default semantics from its	closing @code{;}. Here's an example in which a deferred word is
ancestor. The semantics of the alias itself can be modified at the time	initialised with an @code{xt} from an anonymous colon definition:
that it is defined. For example:

@example	@example
: foo ... ; immediate	Defer deferred
	:noname ( ... -- ... )
' foo Alias bar \ bar is not an immediate word	... ;
' foo Alias fooby immediate \ fooby is an immediate word	IS deferred
@end example	@end example

@c "combined words" is an undefined term	@noindent
Words that are aliases have the same xt, different headers in the	Gforth provides an alternative way of doing this, using two separate
dictionary, and consequently different name tokens (@pxref{Tokens for	words:
Words}) and possibly different immediate flags. An alias can only have
default or immediate compilation semantics; you can define aliases for
combined words with @code{interpret/compile:}.

@c distribute this to the appropriate paragraphs? - anton	doc-noname
doc-alias	@cindex execution token of last defined word
	doc-lastxt

@node Colon Definitions, User-defined Defining Words, Simple Defining Words, Defining Words	@noindent
@subsection Colon Definitions	The previous example can be rewritten using @code{noname} and
@cindex colon definitions	@code{lastxt}:

@example	@example
: name ( ... -- ... )	Defer deferred
word1 word2 word3 ;	noname : ( ... -- ... )
	... ;
	lastxt IS deferred
@end example	@end example

@noindent	@noindent
Creates a word called @code{name} that, upon execution, executes	@code{noname} works with any defining word, not just @code{:}.
@code{word1 word2 word3}. @code{name} is a @dfn{(colon) definition}.

The explanation above is somewhat superficial. @xref{Your first	@code{lastxt} also works when the last word was not defined as
definition} for simple examples of colon definitions, then	@code{noname}. It also has the useful property that is is valid as soon
@xref{Interpretation and Compilation Semantics} for an in-depth	as the header for a definition has been built. Thus:
discussion of some of the issues involved.
	@example
	lastxt . : foo [ lastxt . ] ; ' foo .
	@end example

	@noindent
	prints 3 numbers; the last two are the same.

doc-:
doc-;

@node User-defined Defining Words, Supplying names, Colon Definitions, Defining Words	@node User-defined Defining Words, Deferred words, Anonymous Definitions, Defining Words
@subsection User-defined Defining Words	@subsection User-defined Defining Words
@cindex user-defined defining words	@cindex user-defined defining words
@cindex defining words, user-defined	@cindex defining words, user-defined
Line 4081 see foo	Line 4152 see foo
\ use ' stats . to show that 107645672 is the xt for stats	\ use ' stats . to show that 107645672 is the xt for stats
@end example	@end example


@c a deferred word is not neccessary for these examples. - anton
Rather than edit your application's source code to change every @code{:}
to a @code{my:}, use a deferred word:

@example
: real: : ; \ retain access to the original
defer : \ redefine as a deferred word
' my: IS : \ use special version of :
\
\ load application here
\
' real: IS : \ go back to the original
@end example

You can use techniques like this to make new defining words in terms of	You can use techniques like this to make new defining words in terms of
@i{any} existing defining word.	@i{any} existing defining word.

Line 4151 is executed, using parameters (data) tha	Line 4207 is executed, using parameters (data) tha
the child word.	the child word.
@end itemize	@end itemize

@c NAC I think this is a really bad example, because it diminishes	Another way of understanding the behaviour of @code{def-word} and
@c rather than emphasising the fact that some important stuff happens	@code{name} is to say that, if you make the following definitions:
@c at define time, and other important stuff happens at child-invocation
@c time, and that those two times are potentially very different.

@c Well, IMO CREATE-DOES> is usually presented with much ado, making
@c people think that it's hard to understand, and making those people who
@c understand it easily think that it's hyped. I prefer presenting it in a
@c diminished way and only emphasize the special issues later. - anton

In other words, if you make the following definitions:
@example	@example
: def-word1 ( "name" -- )	: def-word1 ( "name" -- )
CREATE @i{code1} ;	CREATE @i{code1} ;
Line 4172 In other words, if you make the followin	Line 4219 In other words, if you make the followin
def-word1 name1	def-word1 name1
@end example	@end example

Using @code{name1 action1} is equivalent to using @code{name}.	@noindent
	Then using @code{name1 action1} is equivalent to using @code{name}.

The classic example is that you can define @code{CONSTANT} in this way:	The classic example is that you can define @code{CONSTANT} in this way:

Line 4190 DOES> ( -- w )	Line 4238 DOES> ( -- w )
When you create a constant with @code{5 CONSTANT five}, a set of	When you create a constant with @code{5 CONSTANT five}, a set of
define-time actions take place; first a new word @code{five} is created,	define-time actions take place; first a new word @code{five} is created,
then the value 5 is laid down in the body of @code{five} with	then the value 5 is laid down in the body of @code{five} with
@code{,}. When @code{five} is invoked, the address of the body is put on	@code{,}. When @code{five} is executed, the address of the body is put on
the stack, and @code{@@} retrieves the value 5. The word @code{five} has	the stack, and @code{@@} retrieves the value 5. The word @code{five} has
no code of its own; it simply contains a data field and a pointer to the	no code of its own; it simply contains a data field and a pointer to the
code that follows @code{DOES>} in its defining word. That makes words	code that follows @code{DOES>} in its defining word. That makes words
Line 4293 definition. This allows us to, e.g., sel	Line 4341 definition. This allows us to, e.g., sel
DOES> ( ... -- ... )	DOES> ( ... -- ... )
... ;	... ;

: does2	: does2
DOES> ( ... -- ... )	DOES> ( ... -- ... )
... ;	... ;

	: def-word ( ... -- ... )
	create ...
	IF
	does1
	ELSE
	does2
	ENDIF ;
	@end example

	In this example, the selection of whether to use @code{does1} or
	@code{does2} is made at compile-time; at the time that the child word is
	@code{CREATE}d.

	@cindex @code{DOES>} in interpretation state
	In a standard program you can apply a @code{DOES>}-part only if the last
	word was defined with @code{CREATE}. In Gforth, the @code{DOES>}-part
	will override the behaviour of the last word defined in any case. In a
	standard program, you can use @code{DOES>} only in a colon
	definition. In Gforth, you can also use it in interpretation state, in a
	kind of one-shot mode; for example:
	@example
	CREATE name ( ... -- ... )
	@i{initialization}
	DOES>
	@i{code} ;
	@end example

	@noindent
	is equivalent to the standard:
	@example
	:noname
	DOES>
	@i{code} ;
	CREATE name EXECUTE ( ... -- ... )
	@i{initialization}
	@end example


	doc->body


	@node Deferred words, Aliases, User-defined Defining Words, Defining Words
	@subsection Deferred words
	@cindex deferred words

	The defining word @code{Defer} allows you to define a word by name
	without defining its behaviour; the definition of its behaviour is
	deferred. Here are two situation where this can be useful:

	@itemize @bullet
	@item
	Where you want to allow the behaviour of a word to be altered later, and
	for all precompiled references to the word to change when its behaviour
	is changed.
	@item
	For mutual recursion; @xref{Calls and returns}.
	@end itemize

	In the following example, @code{foo} always invokes the version of
	@code{greet} that prints ``@code{Good morning}'' whilst @code{bar}
	always invokes the version that prints ``@code{Hello}''. There is no way
	of getting @code{foo} to use the later version without re-ordering the
	source code and recompiling it.

	@example
	: greet ." Good morning" ;
	: foo ... greet ... ;
	: greet ." Hello" ;
	: bar ... greet ... ;
	@end example

	This problem can be solved by defining @code{greet} as a @code{Defer}red
	word. The behaviour of a @code{Defer}red word can be defined and
	redefined at any time by using @code{IS} to associate the xt of a
	previously-defined word with it. The previous example becomes:

	@example
	Defer greet
	: foo ... greet ... ;
	: bar ... greet ... ;
	: greet1 ." Good morning" ;
	: greet2 ." Hello" ;
	' greet2 <IS> greet \ make greet behave like greet2
	@end example

	A deferred word can be used to improve the statistics-gathering example
	from @ref{User-defined Defining Words}; rather than edit the
	application's source code to change every @code{:} to a @code{my:}, do
	this:

	@example
	: real: : ; \ retain access to the original
	defer : \ redefine as a deferred word
	' my: IS : \ use special version of :
	\
	\ load application here
	\
	' real: IS : \ go back to the original
	@end example


	One thing to note is that @code{<IS>} consumes its name when it is
	executed. If you want to specify the name at compile time, use
	@code{[IS]}:

	@example
	: set-greet ( xt -- )
	[IS] greet ;

	' greet1 set-greet
	@end example

	A deferred word can only inherit default semantics from the xt (because
	that is all that an xt can represent -- @pxref{Tokens for Words} for
	more discussion of this). However, the semantics of the deferred word
	itself can be modified at the time that it is defined. For example:

	@example
	: bar .... ; compile-only
	Defer fred immediate
	Defer jim

	' bar <IS> jim \ jim has default semantics
	' bar <IS> fred \ fred is immediate
	@end example

	doc-defer
	doc-<is>
	doc-[is]
	doc-is
	@comment TODO document these: what's defers [is]
	doc-what's
	doc-defers

	@c Use @code{words-deferred} to see a list of deferred words.

	Definitions in ANS Forth for @code{defer}, @code{<is>} and @code{[is]}
	are provided in @file{compat/defer.fs}.


	@node Aliases, Supplying names, Deferred words, Defining Words
	@subsection Aliases
	@cindex aliases

: def-word ( ... -- ... )	The defining word @code{Alias} allows you to define a word by name that
create ...	has the same behaviour as some other word. Here are two situation where
IF	this can be useful:
does1
ELSE
does2
ENDIF ;
@end example

In this example, the selection of whether to use @code{does1} or	@itemize @bullet
@code{does2} is made at compile-time; at the time that the child word is	@item
@code{CREATE}d.	When you want access to a word's definition from a different word list
	(for an example of this, see the definition of the @code{Root} word list
	in the Gforth source).
	@item
	When you want to create a synonym; a definition that can be known by
	either of two names (for example, @code{THEN} and @code{ENDIF} are
	aliases).
	@end itemize

@cindex @code{DOES>} in interpretation state	The word whose behaviour the alias is to inherit is represented by an
In a standard program you can apply a @code{DOES>}-part only if the last	xt. Therefore, the alias only inherits default semantics from its
word was defined with @code{CREATE}. In Gforth, the @code{DOES>}-part	ancestor. The semantics of the alias itself can be modified at the time
will override the behaviour of the last word defined in any case. In a	that it is defined. For example:
standard program, you can use @code{DOES>} only in a colon
definition. In Gforth, you can also use it in interpretation state, in a
kind of one-shot mode; for example:
@example
CREATE name ( ... -- ... )
@i{initialization}
DOES>
@i{code} ;
@end example

@noindent
is equivalent to the standard:
@example	@example
:noname	: foo ... ; immediate
DOES>
@i{code} ;	' foo Alias bar \ bar is not an immediate word
CREATE name EXECUTE ( ... -- ... )	' foo Alias fooby immediate \ fooby is an immediate word
@i{initialization}
@end example	@end example

You can get the address of the body of a word with:	Words that are aliases have the same xt, different headers in the
	dictionary, and consequently different name tokens (@pxref{Tokens for
	Words}) and possibly different immediate flags. An alias can only have
	default or immediate compilation semantics; you can define aliases for
	combined words with @code{interpret/compile:} -- see @ref{Combined words}.

	doc-alias

doc->body

@node Supplying names, Interpretation and Compilation Semantics, User-defined Defining Words, Defining Words	@node Supplying names, Interpretation and Compilation Semantics, Aliases, Defining Words
@subsection Supplying the name of a defined word	@subsection Supplying the name of a defined word
@cindex names for defined words	@cindex names for defined words
@cindex defining words, name parameter

@cindex defining words, name given in a string	@cindex defining words, name given in a string

By default, a defining word takes the name for the defined word from the	By default, a defining word takes the name for the defined word from the
input stream. Sometimes you want to supply the name from a string. You	input stream. Sometimes you want to supply the name from a string. You
can do this with:	can do this with:
Line 4355 For example:	Line 4541 For example:
@example	@example
s" foo" nextname create	s" foo" nextname create
@end example	@end example
@noindent
is equivalent to:
@example
create foo
@end example

@cindex defining words without name
Sometimes you want to define an @dfn{anonymous word}; a word without a
name. You can do this with:

doc-:noname

This leaves the execution token for the word on the stack after the
closing @code{;}. Here's an example in which a deferred word is
initialised with an @code{xt} from an anonymous colon definition:
@example
Defer deferred
:noname ( ... -- ... )
... ;
IS deferred
@end example

@noindent
Gforth provides an alternative way of doing this, using two separate
words:

doc-noname
@cindex execution token of last defined word
doc-lastxt

@noindent
The previous example can be rewritten using @code{noname} and
@code{lastxt}:

@example
Defer deferred
noname : ( ... -- ... )
... ;
lastxt IS deferred
@end example

@noindent	@noindent
@code{noname} and @code{nextname} work with any defining word, not just	is equivalent to:
@code{:}.

@code{lastxt} also works when the last word was not defined as
@code{noname}. It also has the useful property that is is valid as soon
as the header for a definition has been build. Thus:

@example	@example
lastxt . : foo [ lastxt . ] ; ' foo .	create foo
@end example	@end example

@noindent	@noindent
prints 3 numbers; the last two are the same.	@code{nextname} works with any defining word, not just @code{:}.


@node Interpretation and Compilation Semantics, , Supplying names, Defining Words	@node Interpretation and Compilation Semantics, Combined words, Supplying names, Defining Words
@subsection Interpretation and Compilation Semantics	@subsection Interpretation and Compilation Semantics
@cindex semantics, interpretation and compilation	@cindex semantics, interpretation and compilation

Line 4448 definition.}	Line 4589 definition.}
@cindex compile-only words	@cindex compile-only words
You can change the semantics of the most-recently defined word:	You can change the semantics of the most-recently defined word:


doc-immediate	doc-immediate
doc-compile-only	doc-compile-only
doc-restrict	doc-restrict


Note that ticking (@code{'}) a compile-only word gives an error	Note that ticking (@code{'}) a compile-only word gives an error
(``Interpreting a compile-only word'').	(``Interpreting a compile-only word'').

Gforth also allows you to define words with arbitrary combinations of
interpretation and compilation semantics.	@node Combined words, ,Interpretation and Compilation Semantics, Defining Words
	@subsection Combined Words
	@cindex combined words

	Gforth allows you to define @dfn{combined words} -- words that have an
	arbitrary combination of interpretation and compilation semantics.


doc-interpret/compile:	doc-interpret/compile:


This feature was introduced for implementing @code{TO} and @code{S"}. I	This feature was introduced for implementing @code{TO} and @code{S"}. I
recommend that you do not define such words, as cute as they may be:	recommend that you do not define such words, as cute as they may be:
they make it hard to get at both parts of the word in some contexts.	they make it hard to get at both parts of the word in some contexts.
Line 4559 compilation> ( compilation. -- ; run-tim	Line 4709 compilation> ( compilation. -- ; run-tim
<compilation ;	<compilation ;
@end example	@end example


doc-create-interpret/compile	doc-create-interpret/compile
doc-interpretation>	doc-interpretation>
doc-<interpretation	doc-<interpretation
doc-compilation>	doc-compilation>
doc-<compilation	doc-<compilation


Words defined with @code{interpret/compile:} and	Words defined with @code{interpret/compile:} and
@code{create-interpret/compile} have an extended header structure that	@code{create-interpret/compile} have an extended header structure that
differs from other words; however, unless you try to access them with	differs from other words; however, unless you try to access them with
Line 4573 accessing the header structure usually k	Line 4725 accessing the header structure usually k
@code{'} @i{word} @code{>body} also gives you the body of a word created	@code{'} @i{word} @code{>body} also gives you the body of a word created
with @code{create-interpret/compile}.	with @code{create-interpret/compile}.


doc-postpone	doc-postpone

@comment TODO -- expand glossary text for POSTPONE	@comment TODO -- expand glossary text for POSTPONE

@c ----------------------------------------------------------	@c ----------------------------------------------------------
Line 4586 doc-postpone	Line 4740 doc-postpone
@c Should we really describe all these ugly details? IMO the text	@c Should we really describe all these ugly details? IMO the text
@c interpreter should be much cleaner, but that may not be possible within	@c interpreter should be much cleaner, but that may not be possible within
@c ANS Forth. - anton	@c ANS Forth. - anton
	@c nac-> I wanted to explain how it works to show how you can exploit
	@c it in your own programs. When I was writing a cross-compiler, figuring out
	@c some of these gory details was very helpful to me. None of the textbooks
	@c I've seen cover it, and the most modern Forth textbook -- Forth Inc's,
	@c seems to positively avoid going into too much detail for some of
	@c the internals.

The text interpreter@footnote{This is an expanded version of the	The text interpreter@footnote{This is an expanded version of the
material in @ref{Introducing the Text Interpreter}.} is an endless loop	material in @ref{Introducing the Text Interpreter}.} is an endless loop
Line 4748 device.	Line 4908 device.

@ref{Input Sources} describes this in more detail.	@ref{Input Sources} describes this in more detail.


doc->in	doc->in
doc-source	doc-source

doc-tib	doc-tib
doc-#tib	doc-#tib


@menu	@menu
* Input Sources::	* Input Sources::
* Number Conversion::	* Number Conversion::
Line 4767 doc-#tib	Line 4929 doc-#tib
@cindex input sources	@cindex input sources
@cindex text interpreter - input sources	@cindex text interpreter - input sources

By default, the text interpreter accepts input from the user input	By default, the text interpreter processes input from the user input
device (the keyboard) when Forth starts up. The text interpreter can	device (the keyboard) when Forth starts up. The text interpreter can
process input from any of these sources:	process input from any of these sources:

Line 4785 A text string, using @code{evaluate}.	Line 4947 A text string, using @code{evaluate}.
A program can identify the current input device from the values of	A program can identify the current input device from the values of
@code{source-id} and @code{blk}.	@code{source-id} and @code{blk}.


doc-source-id	doc-source-id
doc-blk	doc-blk

Line 4794 doc-restore-input	Line 4957 doc-restore-input
doc-evaluate	doc-evaluate



@node Number Conversion, Interpret/Compile states, Input Sources, The Text Interpreter	@node Number Conversion, Interpret/Compile states, Input Sources, The Text Interpreter
@subsection Number Conversion	@subsection Number Conversion
@cindex number conversion	@cindex number conversion
Line 4860 doc-base	Line 5024 doc-base
doc-hex	doc-hex
doc-decimal	doc-decimal


@cindex '-prefix for character strings	@cindex '-prefix for character strings
@cindex &-prefix for decimal numbers	@cindex &-prefix for decimal numbers
@cindex %-prefix for binary numbers	@cindex %-prefix for binary numbers
Line 4939 words @code{[} and @code{]}. When @code{	Line 5104 words @code{[} and @code{]}. When @code{
@code{state} to interpret state, and therefore the text interpreter	@code{state} to interpret state, and therefore the text interpreter
starts interpreting. When @code{]} is executed it switches @code{state}	starts interpreting. When @code{]} is executed it switches @code{state}
to compile state and therefore the text interpreter starts	to compile state and therefore the text interpreter starts
compiling. The most common usage for these words is to compile literals,	compiling. The most common usage for these words is for switching into
as shown in @ref{Literals}. However, they give you the freedom to switch	interpret state and back from within a colon definition; this technique
modes at will.	can be used to compile a literal (@pxref{Literals} for an example) or
	for conditional compilation (@pxref{Interpreter Directives} for an
	example).


@c This is a bad example: It's non-standard, and it's not necessary.	@c This is a bad example: It's non-standard, and it's not necessary.
@c However, I can't think of a good example for switching into compile	@c However, I can't think of a good example for switching into compile
@c state when there is no current word (@code{state}-smart words are not a	@c state when there is no current word (@code{state}-smart words are not a
@c good reason). So maybe we should use an example for switching into	@c good reason). So maybe we should use an example for switching into
@c interpret @code{state} in a colon def. - anton	@c interpret @code{state} in a colon def. - anton
	@c nac-> I agree. I started out by putting in the example, then realised
	@c that it was non-ANS, so wrote more words around it. I hope this
	@c re-written version is acceptable to you. I do want to keep the example
	@c as it is helpful for showing what is and what is not portable, particularly
	@c where it outlaws a style in common use.


Here is an example of building a jump-table of execution	@code{[} and @code{]} also give you the ability to switch into compile
tokens:	state and back, but we cannot think of any useful Standard application
	for this ability. Pre-ANS Forth textbooks have examples like this:

@example	@example
: AA ." this is A" ;	: AA ." this is A" ;
: BB ." this is B" ;	: BB ." this is B" ;
: CC ." this is C" ;	: CC ." this is C" ;

create table ' aa COMPILE, ' bb COMPILE, ' cc COMPILE,	create table ] aa bb cc [

: go ( n -- ) \ n is offset into table.. 0 for 1st entry	: go ( n -- ) \ n is offset into table.. 0 for 1st entry
cells table + @ execute ;	cells table + @ execute ;
@end example	@end example

@noindent	This example builds a jump table; @code{0 go} will display ``@code{this
Now @code{0 go} will display ``@code{this is A}''. The table can be	is A}''. Using @code{[} and @code{]} in this example is equivalent to
built far more neatly@footnote{The source code is neater.. what is	defining @code{table} like this:
compiled in memory in each case is identical.} like this:

@example	@example
create table ] aa bb cc [	create table ' aa COMPILE, ' bb COMPILE, ' cc COMPILE,
@end example	@end example

The problem with this code is that it is not portable; it will only work	The problem with this code is that the definition of @code{table} is not
on systems where code space and data space co-incide. The reason is that	portable -- it @i{compile}s execution tokens into code space. Whilst it
both tables @i{compile} execution tokens -- into code space. The	@i{may} work on systems where code space and data space co-incide, the
Standard only allows data space to be assigned for a @code{CREATE}d	Standard only allows data space to be assigned for a @code{CREATE}d
word. In addition, the Standard only allows @code{@@} to access data	word. In addition, the Standard only allows @code{@@} to access data
space, whilst this example is using it to access code space. The only	space, whilst this example is using it to access code space. The only
Line 4984 like this:	Line 5159 like this:
create table ' aa , ' bb , ' cc ,	create table ' aa , ' bb , ' cc ,
@end example	@end example

@noindent
A similar technique can be used to build a table of constants:

@example
create primes 1 , 3 , 5 , 7 , 11 ,
@end example

doc-state	doc-state
doc-[	doc-[
doc-]	doc-]


@node Literals, Interpreter Directives, Interpret/Compile states, The Text Interpreter	@node Literals, Interpreter Directives, Interpret/Compile states, The Text Interpreter
@subsection Literals	@subsection Literals
@cindex Literals	@cindex Literals
Line 5053 solving this problem in this instance is	Line 5222 solving this problem in this instance is
LITERAL * ; \ to seconds	LITERAL * ; \ to seconds
@end example	@end example


doc-literal	doc-literal
doc-]L	doc-]L
doc-2literal	doc-2literal
doc-fliteral	doc-fliteral


@node Interpreter Directives, , Literals, The Text Interpreter	@node Interpreter Directives, , Literals, The Text Interpreter
@subsection Interpreter Directives	@subsection Interpreter Directives
@cindex interpreter directives	@cindex interpreter directives
Line 5088 ASSEMBLER [IF]	Line 5259 ASSEMBLER [IF]
;	;
@end example	@end example


doc-[IF]	doc-[IF]
doc-[ELSE]	doc-[ELSE]
doc-[THEN]	doc-[THEN]
Line 5111 doc-[REPEAT]	Line 5283 doc-[REPEAT]




@c -------------------------------------------------------------	@c -------------------------------------------------------------
@node Tokens for Words, Word Lists, The Text Interpreter, Words	@node Tokens for Words, Word Lists, The Text Interpreter, Words
@section Tokens for Words	@section Tokens for Words
Line 5196 Named words are also represented by the	Line 5369 Named words are also represented by the
Gforth, the abstract data type @emph{name token} is implemented as a	Gforth, the abstract data type @emph{name token} is implemented as a
name field address (NFA).	name field address (NFA).


doc-execute	doc-execute
doc-compile,	doc-compile,
doc-[']	doc-[']
Line 5210 doc-name?int	Line 5384 doc-name?int
doc-name>comp	doc-name>comp
doc-name>string	doc-name>string


@c -------------------------------------------------------------	@c -------------------------------------------------------------
@node Word Lists, Environmental Queries, Tokens for Words, Words	@node Word Lists, Environmental Queries, Tokens for Words, Words
@section Word Lists	@section Word Lists
Line 5247 Standard Forth.	Line 5422 Standard Forth.

@comment the thisone- prefix is used to pick out the true definition of a	@comment the thisone- prefix is used to pick out the true definition of a
@comment word from the source files, rather than some alias.	@comment word from the source files, rather than some alias.

doc-forth-wordlist	doc-forth-wordlist
doc-definitions	doc-definitions
doc-get-current	doc-get-current
Line 5267 doc-search-wordlist	Line 5443 doc-search-wordlist

doc-words	doc-words
doc-vlist	doc-vlist
	@c doc-words-deferred

doc-mappedwordlist	doc-mappedwordlist
doc-root	doc-root
Line 5276 doc-vocs	Line 5453 doc-vocs
doc-current	doc-current
doc-context	doc-context


@menu	@menu
* Why use word lists?::	* Why use word lists?::
* Word list examples::	* Word list examples::
Line 5380 associated environmental query string mu	Line 5558 associated environmental query string mu
Gforth, the word list used to honour environmental queries can be	Gforth, the word list used to honour environmental queries can be
manipulated just like any other word list.	manipulated just like any other word list.


doc-environment?	doc-environment?
doc-environment-wordlist	doc-environment-wordlist

doc-gforth	doc-gforth
doc-os-class	doc-os-class


Note that, whilst the documentation for (e.g.) @code{gforth} shows it	Note that, whilst the documentation for (e.g.) @code{gforth} shows it
returning two items on the stack, querying it using @code{environment?}	returning two items on the stack, querying it using @code{environment?}
will return an additional item; the @code{true} flag that shows that the	will return an additional item; the @code{true} flag that shows that the
Line 5486 does not change the stack. This allows u	Line 5666 does not change the stack. This allows u
1 require foo.fs drop	1 require foo.fs drop
@end example	@end example


doc-include-file	doc-include-file
doc-included	doc-included
doc-included?	doc-included?
Line 5495 doc-require	Line 5676 doc-require
doc-needs	doc-needs
doc-init-included-files	doc-init-included-files


A definition in ANS Forth for @code{required} is provided in	A definition in ANS Forth for @code{required} is provided in
@file{compat/required.fs}.	@file{compat/required.fs}.

Line 5507 A definition in ANS Forth for @code{requ	Line 5689 A definition in ANS Forth for @code{requ
Files are opened/created by name and type. The following types are	Files are opened/created by name and type. The following types are
recognised:	recognised:


doc-r/o	doc-r/o
doc-r/w	doc-r/w
doc-w/o	doc-w/o
doc-bin	doc-bin


When a file is opened/created, it returns a file identifier,	When a file is opened/created, it returns a file identifier,
@i{wfileid} that is used for all other file commands. All file	@i{wfileid} that is used for all other file commands. All file
commands also return a status value, @i{wior}, that is 0 for a	commands also return a status value, @i{wior}, that is 0 for a
successful operation and an implementation-defined non-zero value in the	successful operation and an implementation-defined non-zero value in the
case of an error.	case of an error.


doc-open-file	doc-open-file
doc-create-file	doc-create-file

Line 5537 doc-reposition-file	Line 5722 doc-reposition-file
doc-file-size	doc-file-size
doc-resize-file	doc-resize-file


@c ---------------------------------------------------------	@c ---------------------------------------------------------
@node Search Paths, Forth Search Paths, General files, Files	@node Search Paths, Forth Search Paths, General files, Files
@subsection Search Paths	@subsection Search Paths
Line 5582 as described above.	Line 5768 as described above.
The search path is initialized when you start Gforth (@pxref{Invoking	The search path is initialized when you start Gforth (@pxref{Invoking
Gforth}). You can display it and change it using these words:	Gforth}). You can display it and change it using these words:


doc-.fpath	doc-.fpath
doc-fpath+	doc-fpath+
doc-fpath=	doc-fpath=
doc-open-fpath-file	doc-open-fpath-file


	@noindent
Here is an example of using @code{fpath} and @code{require}:	Here is an example of using @code{fpath} and @code{require}:

@example	@example
Line 5604 Your application may need to search file	Line 5793 Your application may need to search file
and use your own search paths, by providing generic equivalents of the	and use your own search paths, by providing generic equivalents of the
Forth search path words:	Forth search path words:


doc-.path	doc-.path
doc-path+	doc-path+
doc-path=	doc-path=
doc-open-path-file	doc-open-path-file


Here's an example of creating a search path:	Here's an example of creating a search path:

@example	@example
Line 5759 See Frank Sergeant's Pygmy Forth to see	Line 5950 See Frank Sergeant's Pygmy Forth to see
integrated into a Forth programming environment.	integrated into a Forth programming environment.

@comment TODO what about errors on open-blocks?	@comment TODO what about errors on open-blocks?

doc-open-blocks	doc-open-blocks
doc-use	doc-use
doc-get-block-fid	doc-get-block-fid
Line 5781 doc-load	Line 5973 doc-load
doc-thru	doc-thru
doc-+load	doc-+load
doc-+thru	doc-+thru
xdoc--gforth--->	doc---gforth--->
doc-block-included	doc-block-included


@c -------------------------------------------------------------	@c -------------------------------------------------------------
@node Other I/O, Programming Tools, Blocks, Words	@node Other I/O, Programming Tools, Blocks, Words
@section Other I/O	@section Other I/O
Line 5806 data or floating-point stacks. Floating-	Line 5999 data or floating-point stacks. Floating-
using base 10. Numbers displayed from the data stack use the value stored	using base 10. Numbers displayed from the data stack use the value stored
in @code{base}.	in @code{base}.


doc-.	doc-.
doc-dec.	doc-dec.
doc-hex.	doc-hex.
Line 5820 doc-f.	Line 6014 doc-f.
doc-fe.	doc-fe.
doc-fs.	doc-fs.


Examples of printing the number 1234.5678E23 in the different floating-point output	Examples of printing the number 1234.5678E23 in the different floating-point output
formats are shown below:	formats are shown below:

Line 5864 unsigned. The examples below show ways o	Line 6059 unsigned. The examples below show ways o
The string is built up from right to left; least significant digit first.	The string is built up from right to left; least significant digit first.
@end itemize	@end itemize


doc-<#	doc-<#
doc-#	doc-#
doc-#s	doc-#s
Line 5873 doc-#>	Line 6069 doc-#>

doc-represent	doc-represent


	@noindent
Here are some examples of using pictured numeric output:	Here are some examples of using pictured numeric output:

@example	@example
Line 5968 ANS Forth encourages the use of the seco	Line 6166 ANS Forth encourages the use of the seco
strings on the stack, whilst conceeding that the counted string format	strings on the stack, whilst conceeding that the counted string format
remains useful as a way of storing strings in memory.	remains useful as a way of storing strings in memory.


doc-count	doc-count


@xref{Memory Blocks} for words that move, copy and search	@xref{Memory Blocks} for words that move, copy and search
for strings. @xref{Displaying characters and strings,} for words that	for strings. @xref{Displaying characters and strings,} for words that
display characters and strings.	display characters and strings.
Line 5983 display characters and strings.	Line 6183 display characters and strings.
This section starts with a glossary of Forth words and ends with a set	This section starts with a glossary of Forth words and ends with a set
of examples.	of examples.


doc-bl	doc-bl
doc-space	doc-space
doc-spaces	doc-spaces
Line 5991 doc-toupper	Line 6192 doc-toupper
doc-."	doc-."
doc-.(	doc-.(
doc-type	doc-type
	doc-typewhite
doc-cr	doc-cr
@cindex cursor control	@cindex cursor control
doc-at-xy	doc-at-xy
Line 6001 doc-char	Line 6203 doc-char
doc-[char]	doc-[char]
doc-sliteral	doc-sliteral


	@noindent
As an example, consider the following text, stored in a file @file{test.fs}:	As an example, consider the following text, stored in a file @file{test.fs}:

@example	@example
Line 6077 definition of @code{my-char}.	Line 6281 definition of @code{my-char}.
@comment TODO examples for >number >float accept key key? pad parse word refill	@comment TODO examples for >number >float accept key key? pad parse word refill
@comment then index them	@comment then index them


doc-key	doc-key
doc-key?	doc-key?
doc->number	doc->number
Line 6086 doc-pad	Line 6291 doc-pad
doc-parse	doc-parse
doc-word	doc-word
doc-sword	doc-sword
	doc-(name)
doc-refill	doc-refill
@comment obsolescent words..	@comment obsolescent words..
doc-convert	doc-convert
Line 6094 doc-expect	Line 6300 doc-expect
doc-span	doc-span



@c -------------------------------------------------------------	@c -------------------------------------------------------------
@node Programming Tools, Assembler and Code Words, Other I/O, Words	@node Programming Tools, Assembler and Code Words, Other I/O, Words
@section Programming Tools	@section Programming Tools
Line 6122 The simple debugging aids provided in @f	Line 6329 The simple debugging aids provided in @f
are meant to support this style of debugging. In addition, there are	are meant to support this style of debugging. In addition, there are
words for non-destructively inspecting the stack and memory:	words for non-destructively inspecting the stack and memory:


doc-.s	doc-.s
doc-f.s	doc-f.s


There is a word @code{.r} but it does @i{not} display the return	There is a word @code{.r} but it does @i{not} display the return
stack! It is used for formatted numeric output.	stack! It is used for formatted numeric output.


doc-depth	doc-depth
doc-fdepth	doc-fdepth
doc-clearstack	doc-clearstack
doc-?	doc-?
doc-dump	doc-dump


The word @code{~~} prints debugging information (by default the source	The word @code{~~} prints debugging information (by default the source
location and the stack contents). It is easy to insert. If you use Emacs	location and the stack contents). It is easy to insert. If you use Emacs
it is also easy to remove (@kbd{C-x ~} in the Emacs Forth mode to	it is also easy to remove (@kbd{C-x ~} in the Emacs Forth mode to
Line 6149 The default actions of @code{~~} clobber	Line 6360 The default actions of @code{~~} clobber
numeric output string, so you should not use @code{~~}, e.g., between	numeric output string, so you should not use @code{~~}, e.g., between
@code{<#} and @code{#>}.	@code{<#} and @code{#>}.


doc-~~	doc-~~
doc-printdebugdata	doc-printdebugdata
doc-printdebugline	doc-printdebugline
Line 6156 doc-printdebugline	Line 6368 doc-printdebugline
doc-see	doc-see
doc-marker	doc-marker


Here's an example of using @code{marker} at the start of a source file	Here's an example of using @code{marker} at the start of a source file
that you are debugging; it ensures that you only ever have one copy of	that you are debugging; it ensures that you only ever have one copy of
the file's definitions compiled at any time:	the file's definitions compiled at any time:
Line 6208 time it takes to check it, you may want	Line 6421 time it takes to check it, you may want
keep others turned on. Gforth provides several levels of assertions for	keep others turned on. Gforth provides several levels of assertions for
this purpose:	this purpose:


doc-assert0(	doc-assert0(
doc-assert1(	doc-assert1(
doc-assert2(	doc-assert2(
Line 6215 doc-assert3(	Line 6429 doc-assert3(
doc-assert(	doc-assert(
doc-)	doc-)


The variable @code{assert-level} specifies the highest assertions that	The variable @code{assert-level} specifies the highest assertions that
are turned on. I.e., at the default @code{assert-level} of one,	are turned on. I.e., at the default @code{assert-level} of one,
@code{assert0(} and @code{assert1(} assertions perform checking, while	@code{assert0(} and @code{assert1(} assertions perform checking, while
Line 6227 piece of code. You can compile different	Line 6442 piece of code. You can compile different
@code{assert-level}s (e.g., a trusted library at level 1 and	@code{assert-level}s (e.g., a trusted library at level 1 and
newly-written code at level 3).	newly-written code at level 3).


doc-assert-level	doc-assert-level


If an assertion fails, a message compatible with Emacs' compilation mode	If an assertion fails, a message compatible with Emacs' compilation mode
is produced and the execution is aborted (currently with @code{ABORT"}.	is produced and the execution is aborted (currently with @code{ABORT"}.
If there is interest, we will introduce a special throw code. But if you	If there is interest, we will introduce a special throw code. But if you
Line 6308 program has stopped at the moment. You c	Line 6525 program has stopped at the moment. You c
@code{BREAK" string"} command. This behaves like @code{BREAK:} except that	@code{BREAK" string"} command. This behaves like @code{BREAK:} except that
string is typed out when the ``breakpoint'' is reached.	string is typed out when the ``breakpoint'' is reached.


doc-dbg	doc-dbg
doc-BREAK:	doc-BREAK:
doc-BREAK"	doc-BREAK"



@c -------------------------------------------------------------	@c -------------------------------------------------------------
@node Assembler and Code Words, Threading Words, Programming Tools, Words	@node Assembler and Code Words, Threading Words, Programming Tools, Words
@section Assembler and Code Words	@section Assembler and Code Words
Line 6335 because these words emit stuff in @i{dat	Line 6554 because these words emit stuff in @i{dat
Gforth has unified code/data spaces. Assembler isn't likely to be	Gforth has unified code/data spaces. Assembler isn't likely to be
portable anyway.}.	portable anyway.}.


doc-assembler	doc-assembler
doc-code	doc-code
doc-end-code	doc-end-code
doc-;code	doc-;code
doc-flush-icache	doc-flush-icache


If @code{flush-icache} does not work correctly, @code{code} words	If @code{flush-icache} does not work correctly, @code{code} words
etc. will not work (reliably), either.	etc. will not work (reliably), either.

Line 6421 present this wordset is still incomplete	Line 6642 present this wordset is still incomplete
some day it will hopefully be made unnecessary by an internals wordset	some day it will hopefully be made unnecessary by an internals wordset
that abstracts implementation details away completely.	that abstracts implementation details away completely.


doc-threading-method	doc-threading-method
doc->code-address	doc->code-address
doc->does-code	doc->does-code
Line 6429 doc-does-code!	Line 6651 doc-does-code!
doc-does-handler!	doc-does-handler!
doc-/does-handler	doc-/does-handler


The code addresses produced by various defining words are produced by	The code addresses produced by various defining words are produced by
the following words:	the following words:


doc-docol:	doc-docol:
doc-docon:	doc-docon:
doc-dovar:	doc-dovar:
Line 6439 doc-douser:	Line 6663 doc-douser:
doc-dodefer:	doc-dodefer:
doc-dofield:	doc-dofield:


You can recognize words defined by a @code{CREATE}...@code{DOES>} word	You can recognize words defined by a @code{CREATE}...@code{DOES>} word
with @code{>does-code}. If the word was defined in that way, the value	with @code{>does-code}. If the word was defined in that way, the value
returned is non-zero and identifies the @code{DOES>} used by the	returned is non-zero and identifies the @code{DOES>} used by the
Line 6561 it in block-structured languages, and so	Line 6786 it in block-structured languages, and so
want to restrict the scope of a local, enclose its definition in	want to restrict the scope of a local, enclose its definition in
@code{SCOPE}...@code{ENDSCOPE}.	@code{SCOPE}...@code{ENDSCOPE}.


doc-scope	doc-scope
doc-endscope	doc-endscope


These words behave like control structure words, so you can use them	These words behave like control structure words, so you can use them
with @code{CS-PICK} and @code{CS-ROLL} to restrict the scope in	with @code{CS-PICK} and @code{CS-ROLL} to restrict the scope in
arbitrary ways.	arbitrary ways.
Line 6601 that the visibility of some locals is mo	Line 6828 that the visibility of some locals is mo
says. If @code{UNREACHABLE} is used where it should not (i.e., if you	says. If @code{UNREACHABLE} is used where it should not (i.e., if you
lie to the compiler), buggy code will be produced.	lie to the compiler), buggy code will be produced.


doc-unreachable	doc-unreachable


Another problem with this rule is that at @code{BEGIN}, the compiler	Another problem with this rule is that at @code{BEGIN}, the compiler
does not know which locals will be visible on the incoming	does not know which locals will be visible on the incoming
back-edge. All problems discussed in the following are due to this	back-edge. All problems discussed in the following are due to this
Line 6682 visible after the @code{BEGIN}. However,	Line 6911 visible after the @code{BEGIN}. However,
visible at the BEGIN as at the point where the top control-flow stack	visible at the BEGIN as at the point where the top control-flow stack
item was created.	item was created.


doc-assume-live	doc-assume-live


	@noindent
E.g.,	E.g.,
@example	@example
@{ x @}	@{ x @}
Line 6814 also eliminates the problems and restric	Line 7046 also eliminates the problems and restric
as locals stack. Like the other stacks, the locals stack grows toward	as locals stack. Like the other stacks, the locals stack grows toward
lower addresses. A few primitives allow an efficient implementation:	lower addresses. A few primitives allow an efficient implementation:


doc-@local#	doc-@local#
doc-f@local#	doc-f@local#
doc-laddr#	doc-laddr#
Line 6822 doc-lp!	Line 7055 doc-lp!
doc->l	doc->l
doc-f>l	doc-f>l


In addition to these primitives, some specializations of these	In addition to these primitives, some specializations of these
primitives for commonly occurring inline arguments are provided for	primitives for commonly occurring inline arguments are provided for
efficiency reasons, e.g., @code{@@local0} as specialization of	efficiency reasons, e.g., @code{@@local0} as specialization of
Line 6829 local0	Line 7063 local0
compile the right specialized version, or the general version, as	compile the right specialized version, or the general version, as
appropriate:	appropriate:


doc-compile-@local	doc-compile-@local
doc-compile-f@local	doc-compile-f@local
doc-compile-lp+!	doc-compile-lp+!


Combinations of conditional branches and @code{lp+!#} like	Combinations of conditional branches and @code{lp+!#} like
@code{?branch-lp+!#} (the locals pointer is only changed if the branch	@code{?branch-lp+!#} (the locals pointer is only changed if the branch
is taken) are provided for efficiency and correctness in loops.	is taken) are provided for efficiency and correctness in loops.
Line 6902 the kind of entry, in particular to diff	Line 7138 the kind of entry, in particular to diff

A few unusual operations have to be performed on locals word lists:	A few unusual operations have to be performed on locals word lists:


doc-common-list	doc-common-list
doc-sub-list?	doc-sub-list?
doc-list-size	doc-list-size


Several features of our locals word list implementation make these	Several features of our locals word list implementation make these
operations easy to implement: The locals word lists are organised as	operations easy to implement: The locals word lists are organised as
linked lists; the tails of these lists are shared, if the lists	linked lists; the tails of these lists are shared, if the lists
Line 6972 stack easier.	Line 7210 stack easier.
The whole definition must be in one line.	The whole definition must be in one line.
@end itemize	@end itemize

Locals defined in this way behave like @code{VALUE}s (@xref{Simple	Locals defined in this way behave like @code{VALUE}s
Defining Words}). I.e., they are initialized from the stack. Using their	(@xref{Values}). I.e., they are initialized from the stack. Using their
name produces their value. Their value can be changed using @code{TO}.	name produces their value. Their value can be changed using @code{TO}.

Since this syntax is supported by Gforth directly, you need not do	Since this syntax is supported by Gforth directly, you need not do
Line 6987 reversed. Beware!	Line 7225 reversed. Beware!

The ANS Forth locals wordset itself consists of a word:	The ANS Forth locals wordset itself consists of a word:


doc-(local)	doc-(local)


The ANS Forth locals extension wordset defines a syntax using @code{locals\|}, but it is so	The ANS Forth locals extension wordset defines a syntax using @code{locals\|}, but it is so
awful that we strongly recommend not to use it. We have implemented this	awful that we strongly recommend not to use it. We have implemented this
syntax to make porting to Gforth easy, but do not document it here. The	syntax to make porting to Gforth easy, but do not document it here. The
Line 7285 immediate, and therefore no code is gene	Line 7525 immediate, and therefore no code is gene
@subsection Structure Glossary	@subsection Structure Glossary
@cindex structure glossary	@cindex structure glossary


doc-%align	doc-%align
doc-%alignment	doc-%alignment
doc-%alloc	doc-%alloc
Line 7302 doc-sfloat%	Line 7543 doc-sfloat%
doc-%size	doc-%size
doc-struct	doc-struct


@c -------------------------------------------------------------	@c -------------------------------------------------------------
@node Object-oriented Forth, Passing Commands to the OS, Structures, Words	@node Object-oriented Forth, Passing Commands to the OS, Structures, Words
@section Object-oriented Forth	@section Object-oriented Forth
Line 7969 selector contains an offset into a metho	Line 8211 selector contains an offset into a metho
@cindex @code{selector} implementation, class	@cindex @code{selector} implementation, class
@code{selector} is a defining word that uses	@code{selector} is a defining word that uses
@code{CREATE} and @code{DOES>}. The body of the	@code{CREATE} and @code{DOES>}. The body of the
selector contains the offset; the @code{does>} action for a	selector contains the offset; the @code{DOES>} action for a
class selector is, basically:	class selector is, basically:

@example	@example
Line 8093 href="objects-implementation.eps">figure	Line 8335 href="objects-implementation.eps">figure
@subsubsection @file{objects.fs} Glossary	@subsubsection @file{objects.fs} Glossary
@cindex @file{objects.fs} Glossary	@cindex @file{objects.fs} Glossary


doc---objects-bind	doc---objects-bind
doc---objects-<bind>	doc---objects-<bind>
doc---objects-bind'	doc---objects-bind'
Line 8138 doc---objects-[to-inst]	Line 8381 doc---objects-[to-inst]
doc---objects-to-this	doc---objects-to-this
doc---objects-xt-new	doc---objects-xt-new


@c -------------------------------------------------------------	@c -------------------------------------------------------------
@node OOF, Mini-OOF, Objects, Object-oriented Forth	@node OOF, Mini-OOF, Objects, Object-oriented Forth
@subsection The @file{oof.fs} model	@subsection The @file{oof.fs} model
Line 8300 selectors of the class @code{object}.	Line 8544 selectors of the class @code{object}.
@code{class} for subclassing, @code{definitions} to add definitions	@code{class} for subclassing, @code{definitions} to add definitions
later on, and @code{class?} to get type informations (is the class a	later on, and @code{class?} to get type informations (is the class a
subclass of the class passed on the stack?).	subclass of the class passed on the stack?).

doc---object-class	doc---object-class
doc---object-definitions	doc---object-definitions
doc---object-class?	doc---object-class?


@item	@item
@code{init} and @code{dispose} as constructor and destructor of the	@code{init} and @code{dispose} as constructor and destructor of the
object. @code{init} is invocated after the object's memory is allocated,	object. @code{init} is invocated after the object's memory is allocated,
while @code{dispose} also handles deallocation. Thus if you redefine	while @code{dispose} also handles deallocation. Thus if you redefine
@code{dispose}, you have to call the parent's dispose with @code{super	@code{dispose}, you have to call the parent's dispose with @code{super
dispose}, too.	dispose}, too.

doc---object-init	doc---object-init
doc---object-dispose	doc---object-dispose


@item	@item
@code{new}, @code{new[]}, @code{:}, @code{ptr}, @code{asptr}, and	@code{new}, @code{new[]}, @code{:}, @code{ptr}, @code{asptr}, and
@code{[]} to create named and unnamed objects and object arrays or	@code{[]} to create named and unnamed objects and object arrays or
object pointers.	object pointers.

doc---object-new	doc---object-new
doc---object-new[]	doc---object-new[]
doc---object-:	doc---object-:
Line 8324 doc---object-ptr	Line 8573 doc---object-ptr
doc---object-asptr	doc---object-asptr
doc---object-[]	doc---object-[]


@item	@item
@code{::} and @code{super} for explicit scoping. You should use explicit	@code{::} and @code{super} for explicit scoping. You should use explicit
scoping only for super classes or classes with the same set of instance	scoping only for super classes or classes with the same set of instance
variables. Explicitly-scoped selectors use early binding.	variables. Explicitly-scoped selectors use early binding.

doc---object-::	doc---object-::
doc---object-super	doc---object-super


@item	@item
@code{self} to get the address of the object	@code{self} to get the address of the object

doc---object-self	doc---object-self


@item	@item
@code{bind}, @code{bound}, @code{link}, and @code{is} to assign object	@code{bind}, @code{bound}, @code{link}, and @code{is} to assign object
pointers and instance defers.	pointers and instance defers.

doc---object-bind	doc---object-bind
doc---object-bound	doc---object-bound
doc---object-link	doc---object-link
doc---object-is	doc---object-is


@item	@item
@code{'} to obtain selector tokens, @code{send} to invocate selectors	@code{'} to obtain selector tokens, @code{send} to invocate selectors
form the stack, and @code{postpone} to generate selector invocation code.	form the stack, and @code{postpone} to generate selector invocation code.

doc---object-'	doc---object-'
doc---object-postpone	doc---object-postpone


@item	@item
@code{with} and @code{endwith} to select the active object from the	@code{with} and @code{endwith} to select the active object from the
stack, and enable its scope. Using @code{with} and @code{endwith}	stack, and enable its scope. Using @code{with} and @code{endwith}
also allows you to create code using selector @code{postpone} without being	also allows you to create code using selector @code{postpone} without being
trapped by the state-smart objects.	trapped by the state-smart objects.

doc---object-with	doc---object-with
doc---object-endwith	doc---object-endwith


@end itemize	@end itemize

@node Class Declaration, Class Implementation, The OOF base class, OOF	@node Class Declaration, Class Implementation, The OOF base class, OOF
Line 8366 doc---object-endwith	Line 8626 doc---object-endwith
@itemize @bullet	@itemize @bullet
@item	@item
Instance variables	Instance variables

doc---oof-var	doc---oof-var


@item	@item
Object pointers	Object pointers

doc---oof-ptr	doc---oof-ptr
doc---oof-asptr	doc---oof-asptr


@item	@item
Instance defers	Instance defers

doc---oof-defer	doc---oof-defer


@item	@item
Method selectors	Method selectors

doc---oof-early	doc---oof-early
doc---oof-method	doc---oof-method


@item	@item
Class-wide variables	Class-wide variables

doc---oof-static	doc---oof-static


@item	@item
End declaration	End declaration

doc---oof-how:	doc---oof-how:
doc---oof-class;	doc---oof-class;


@end itemize	@end itemize

@c -------------------------------------------------------------	@c -------------------------------------------------------------
Line 8425 a class; to end a class, to resolve bind	Line 8697 a class; to end a class, to resolve bind
to compile a class method.	to compile a class method.
@comment TODO better description of the last one	@comment TODO better description of the last one


doc-object	doc-object
doc-method	doc-method
doc-var	doc-var
Line 8435 doc-new	Line 8708 doc-new
doc-::	doc-::



@c -------------------------------------------------------------	@c -------------------------------------------------------------
@node Mini-OOF Example, Mini-OOF Implementation, Basic Mini-OOF Usage, Mini-OOF	@node Mini-OOF Example, Mini-OOF Implementation, Basic Mini-OOF Usage, Mini-OOF
@subsubsection Mini-OOF Example	@subsubsection Mini-OOF Example
Line 8730 the @file{objects.fs} model, but syntact	Line 9004 the @file{objects.fs} model, but syntact
Gforth allows you to pass an arbitrary string to the host operating	Gforth allows you to pass an arbitrary string to the host operating
system shell (if such a thing exists) for execution.	system shell (if such a thing exists) for execution.


doc-sh	doc-sh
doc-system	doc-system
doc-$?	doc-$?
doc-getenv	doc-getenv


@c -------------------------------------------------------------	@c -------------------------------------------------------------
@node Miscellaneous Words, , Passing Commands to the OS, Words	@node Miscellaneous Words, , Passing Commands to the OS, Words
@section Miscellaneous Words	@section Miscellaneous Words
Line 8745 doc-getenv	Line 9021 doc-getenv
These section lists the ANS Forth words that are not documented	These section lists the ANS Forth words that are not documented
elsewhere in this manual. Ultimately, they all need proper homes.	elsewhere in this manual. Ultimately, they all need proper homes.


doc-ms	doc-ms
doc-time&date	doc-time&date



doc-[compile]	doc-[compile]


The following ANS Forth words are not currently supported by Gforth	The following ANS Forth words are not currently supported by Gforth
(@pxref{ANS conformance}):	(@pxref{ANS conformance}):

Line 9027 operating systems. Hopefully, Unicode wi	Line 9307 operating systems. Hopefully, Unicode wi
If @code{WORD} is called with the space character as a delimiter, all	If @code{WORD} is called with the space character as a delimiter, all
white-space characters (as identified by the C macro @code{isspace()})	white-space characters (as identified by the C macro @code{isspace()})
are delimiters. @code{PARSE}, on the other hand, treats space like other	are delimiters. @code{PARSE}, on the other hand, treats space like other
delimiters. @code{PARSE-WORD} treats space like @code{WORD}, but behaves	delimiters. @code{SWORD} treats space like @code{WORD}, but behaves
like @code{PARSE} otherwise. @code{(NAME)}, which is used by the outer	like @code{PARSE} otherwise. @code{(NAME)}, which is used by the outer
interpreter (aka text interpreter) by default, treats all white-space	interpreter (aka text interpreter) by default, treats all white-space
characters as delimiters.	characters as delimiters.
Line 10520 though).	Line 10800 though).

You can create a non-relocatable image file with	You can create a non-relocatable image file with


doc-savesystem	doc-savesystem


@node Data-Relocatable Image Files, Fully Relocatable Image Files, Non-Relocatable Image Files, Image Files	@node Data-Relocatable Image Files, Fully Relocatable Image Files, Non-Relocatable Image Files, Image Files
@section Data-Relocatable Image Files	@section Data-Relocatable Image Files
@cindex data-relocatable image files	@cindex data-relocatable image files
Line 10584 any) of the two Gforth invocations that	Line 10866 any) of the two Gforth invocations that
files, then you see the output of the comparing program: It displays the	files, then you see the output of the comparing program: It displays the
offset used for data addresses and the offset used for code addresses;	offset used for data addresses and the offset used for code addresses;
moreover, for each cell that cannot be represented correctly in the	moreover, for each cell that cannot be represented correctly in the
image files, it displays a line like the following one:	image files, it displays a line like this:

@example	@example
78DC BFFFFA50 BFFFFA40	78DC BFFFFA50 BFFFFA40
Line 10610 instructions.	Line 10892 instructions.
@cindex @code{savesystem} during @file{gforthmi}	@cindex @code{savesystem} during @file{gforthmi}
@cindex @code{bye} during @file{gforthmi}	@cindex @code{bye} during @file{gforthmi}
@cindex doubly indirect threaded code	@cindex doubly indirect threaded code
@cindex environment variable @code{GFORTHD}	@cindex environment variables
@cindex @code{GFORTHD} environment variable	@cindex @code{GFORTHD} -- environment variable
	@cindex @code{GFORTH} -- environment variable
@cindex @code{gforth-ditc}	@cindex @code{gforth-ditc}
There are a few wrinkles: After processing the passed @i{options}, the	There are a few wrinkles: After processing the passed @i{options}, the
words @code{savesystem} and @code{bye} must be visible. A special doubly	words @code{savesystem} and @code{bye} must be visible. A special doubly
Line 10732 The disadvantage of this latter techniqu	Line 11015 The disadvantage of this latter techniqu
@file{gforthmi}, is that it is slower; the Forth source code is compiled	@file{gforthmi}, is that it is slower; the Forth source code is compiled
on-the-fly, each time the program is invoked.	on-the-fly, each time the program is invoked.

@comment TODO describe the #! magic with reference to the Power Tools book.

doc-#!	doc-#!


@node Modifying the Startup Sequence, , Running Image Files, Image Files	@node Modifying the Startup Sequence, , Running Image Files, Image Files
@section Modifying the Startup Sequence	@section Modifying the Startup Sequence
@cindex startup sequence for image file	@cindex startup sequence for image file
Line 10772 If @code{'cold} exits normally, Gforth p	Line 11055 If @code{'cold} exits normally, Gforth p
arguments as files to be loaded and strings to be evaluated. Therefore,	arguments as files to be loaded and strings to be evaluated. Therefore,
@code{'cold} should remove the arguments it has used in this case.	@code{'cold} should remove the arguments it has used in this case.



doc-'cold	doc-'cold
doc-argc	doc-argc
doc-argv	doc-argv
doc-arg	doc-arg



@c ******************************************************************	@c ******************************************************************
@node Engine, Binding to System Library, Image Files, Top	@node Engine, Binding to System Library, Image Files, Top
@chapter Engine	@chapter Engine
Line 11456 is not recommended to learn Forth by usi	Line 11742 is not recommended to learn Forth by usi
written for ANS Forth, as you will not know your mistakes from the	written for ANS Forth, as you will not know your mistakes from the
deviations of the book. However, books based on the Forth-83 standard	deviations of the book. However, books based on the Forth-83 standard
should be ok, because ANS Forth is primarily an extension of Forth-83.	should be ok, because ANS Forth is primarily an extension of Forth-83.
	Refer to the Forth FAQ for details of Forth-related books.

@cindex standard document for ANS Forth	@cindex standard document for ANS Forth
@cindex ANS Forth document	@cindex ANS Forth document
Line 11469 $200. You can also get it from Global En	Line 11756 $200. You can also get it from Global En
@cite{dpANS6}, the last draft of the standard, which was then submitted	@cite{dpANS6}, the last draft of the standard, which was then submitted
to ANSI for publication is available electronically and for free in some	to ANSI for publication is available electronically and for free in some
MS Word format, and it has been converted to HTML	MS Word format, and it has been converted to HTML
(@url{http://www.taygeta.com/forth/dpans.html}; this is my favourite	(@url{http://www.taygeta.com/forth/dpans.html}; this HTML version also
format); this HTML version also includes the answers to Requests for	includes the answers to Requests for Interpretation (RFIs). Some
Interpretation (RFIs). Some pointers to these versions can be found	pointers to these versions can be found through
through @*@url{http://www.complang.tuwien.ac.at/projects/forth.html}.	@*@url{http://www.complang.tuwien.ac.at/projects/forth.html}.

@cindex introductory book on Forth
@cindex book on Forth, introductory
@cindex Woehr, Jack: @cite{Forth: The New Model}
@cindex @cite{Forth: The new model} (book)
@cite{Forth: The New Model} by Jack Woehr (Prentice-Hall, 1993) is an
introductory book based on a draft version of the standard. It does not
cover the whole standard. It also contains interesting background
information (Jack Woehr was in the ANS Forth Technical Committee). It is
not appropriate for complete newbies, but programmers experienced in
other languages should find it ok.

@cindex Conklin, Edward K., and Elizabeth Rather: @cite{Forth Programmer's Handbook}
@cindex Rather, Elizabeth and Edward K. Conklin: @cite{Forth Programmer's Handbook}
@cindex @cite{Forth Programmer's Handbook} (book)
@cite{Forth Programmer's Handbook} by Edward K. Conklin, Elizabeth
D. Rather and the technical staff of Forth, Inc. (Forth, Inc., 1997;
ISBN 0-9662156-0-5) contains little introductory material. The majority
of the book is similar to @ref{Words}, but the book covers most of the
standard words and some non-standard words (whereas this manual is
quite incomplete). In addition, the book contains a chapter on
programming style. The major drawback of this book is that it usually
does not identify what is standard and what is specific to the Forth
system described in the book (probably one of Forth, Inc.'s systems).
Fortunately, many of the non-standard programming practices described in
the book work in Gforth, too. Still, this drawback makes the book
hardly more useful than a pre-ANS book.

@node The Forth Interest Group, Conferences, Books, Forth-related information	@node The Forth Interest Group, Conferences, Books, Forth-related information
@section The Forth Interest Group	@section The Forth Interest Group
Line 11520 chapters in other countries and American	Line 11781 chapters in other countries and American

There are several regular conferences related to Forth. They are all	There are several regular conferences related to Forth. They are all
well-publicised in @var{FORTH Dimensions} and on the comp.lang.forth	well-publicised in @var{FORTH Dimensions} and on the comp.lang.forth
news group:	newsgroup:

@itemize @bullet	@itemize @bullet
@item	@item

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>

Removed from v.1.43
changed lines
	Added in v.1.44