gforth/gforth.ds - diff

Return to gforth.ds CVS log

Up to [gforth] / gforth

Diff for /gforth/Attic/gforth.ds between versions 1.35 and 1.42

version 1.35, 1996/09/10 16:08:37	version 1.42, 1997/01/14 16:30:50
Line 86 personal machines. This manual correspon	Line 86 personal machines. This manual correspon
* Other Books:: Things you might want to read	* Other Books:: Things you might want to read
* Invocation:: Starting Gforth	* Invocation:: Starting Gforth
* Words:: Forth words available in Gforth	* Words:: Forth words available in Gforth
	* Tools:: Programming tools
* ANS conformance:: Implementation-defined options etc.	* ANS conformance:: Implementation-defined options etc.
* Model:: The abstract machine of Gforth	* Model:: The abstract machine of Gforth
* Integrating Gforth:: Forth as scripting language for applications.	* Integrating Gforth:: Forth as scripting language for applications.
Line 566 versions can be found through	Line 567 versions can be found through
@cite{Forth: The new model} by Jack Woehr (Prentice-Hall, 1993) is an	@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	introductory book based on a draft version of the standard. It does not
cover the whole standard. It also contains interesting background	cover the whole standard. It also contains interesting background
information (Jack Woehr was in the ANS Forth Technical Committe). It is	information (Jack Woehr was in the ANS Forth Technical Committee). It is
not appropriate for complete newbies, but programmers experienced in	not appropriate for complete newbies, but programmers experienced in
other languages should find it ok.	other languages should find it ok.

Line 600 Loads the Forth image @var{file} instead	Line 601 Loads the Forth image @var{file} instead

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

@item --dictionary-size @var{size}	@item --dictionary-size @var{size}
@item -m @var{size}	@item -m @var{size}
Line 640 default specified in the image (typicall	Line 641 default specified in the image (typicall

As explained above, the image-specific command-line arguments for the	As explained above, the image-specific command-line arguments for the
default image @file{gforth.fi} consist of a sequence of filenames and	default image @file{gforth.fi} consist of a sequence of filenames and
@code{-e @var{forth-code}} options that are interpreted in the seqence	@code{-e @var{forth-code}} options that are interpreted in the sequence
in which they are given. The @code{-e @var{forth-code}} or	in which they are given. The @code{-e @var{forth-code}} or
@code{--evaluate @var{forth-code}} option evaluates the forth	@code{--evaluate @var{forth-code}} option evaluates the forth
code. This option takes only one argument; if you want to evaluate more	code. This option takes only one argument; if you want to evaluate more
Line 662 the user initialization file @file{.gfor	Line 663 the user initialization file @file{.gfor
option @code{--no-rc} is given; this file is first searched in @file{.},	option @code{--no-rc} is given; this file is first searched in @file{.},
then in @file{~}, then in the normal path (see above).	then in @file{~}, then in the normal path (see above).

@node Words, ANS conformance, Invocation, Top	@node Words, Tools, Invocation, Top
@chapter Forth Words	@chapter Forth Words

@menu	@menu
Line 673 then in @file{~}, then in the normal pat	Line 674 then in @file{~}, then in the normal pat
* Control Structures::	* Control Structures::
* Locals::	* Locals::
* Defining Words::	* Defining Words::
	* Tokens for Words::
* Wordlists::	* Wordlists::
* Files::	* Files::
* Blocks::	* Blocks::
Line 755 double sized signed integer	Line 757 double sized signed integer
@item ud	@item ud
double sized unsigned integer	double sized unsigned integer
@item r	@item r
Float	Float (on the FP stack)
@item a_	@item a_
Cell-aligned address	Cell-aligned address
@item c_	@item c_
Char-aligned address (note that a Char is two bytes in Windows NT)	Char-aligned address (note that a Char may have two bytes in Windows NT)
@item f_	@item f_
Float-aligned address	Float-aligned address
@item df_	@item df_
Line 772 Execution token, same size as Cell	Line 774 Execution token, same size as Cell
Wordlist ID, same size as Cell	Wordlist ID, same size as Cell
@item f83name	@item f83name
Pointer to a name structure	Pointer to a name structure
	@item "
	string in the input stream (not the stack). The terminating character is
	a blank by default. If it is not a blank, it is shown in @code{<>}
	quotes.

@end table	@end table

@node Arithmetic, Stack Manipulation, Notation, Words	@node Arithmetic, Stack Manipulation, Notation, Words
Line 848 doc-dmax	Line 855 doc-dmax
The format of floating point numbers recognized by the outer (aka text)	The format of floating point numbers recognized by the outer (aka text)
interpreter is: a signed decimal number, possibly containing a decimal	interpreter is: a signed decimal number, possibly containing a decimal
point (@code{.}), followed by @code{E} or @code{e}, optionally followed	point (@code{.}), followed by @code{E} or @code{e}, optionally followed
by a signed integer (the exponent). E.g., @code{1e} ist the same as	by a signed integer (the exponent). E.g., @code{1e} is the same as
@code{+1.0e+0}. Note that a number without @code{e}	@code{+1.0e+0}. Note that a number without @code{e}
is not interpreted as floating-point number, but as double (if the	is not interpreted as floating-point number, but as double (if the
number contains a @code{.}) or single precision integer. Also,	number contains a @code{.}) or single precision integer. Also,
Line 1503 Gforth currently supports cells (@code{W	Line 1510 Gforth currently supports cells (@code{W
with @code{W:}, @code{D:} etc.) produces its value and can be changed	with @code{W:}, @code{D:} etc.) produces its value and can be changed
with @code{TO}. A variable-flavoured local (defined with @code{W^} etc.)	with @code{TO}. A variable-flavoured local (defined with @code{W^} etc.)
produces its address (which becomes invalid when the variable's scope is	produces its address (which becomes invalid when the variable's scope is
left). E.g., the standard word @code{emit} can be defined in therms of	left). E.g., the standard word @code{emit} can be defined in terms of
@code{type} like this:	@code{type} like this:

@example	@example
Line 1562 definition? Which local is meant, if the	Line 1569 definition? Which local is meant, if the
two independent control flow paths?	two independent control flow paths?

This should be enough detail for nearly all users, so you can skip the	This should be enough detail for nearly all users, so you can skip the
rest of this section. If you relly must know all the gory details and	rest of this section. If you really must know all the gory details and
options, read on.	options, read on.

In order to implement this rule, the compiler has to know which places	In order to implement this rule, the compiler has to know which places
Line 1615 are entered only through the @code{BEGIN	Line 1622 are entered only through the @code{BEGIN
@code{BEGIN}...@code{UNTIL} loops and it is implemented in our	@code{BEGIN}...@code{UNTIL} loops and it is implemented in our
compiler. When the branch to the @code{BEGIN} is finally generated by	compiler. When the branch to the @code{BEGIN} is finally generated by
@code{AGAIN} or @code{UNTIL}, the compiler checks the guess and	@code{AGAIN} or @code{UNTIL}, the compiler checks the guess and
warns the user if it was too optimisitic:	warns the user if it was too optimistic:
@example	@example
IF	IF
@{ x @}	@{ x @}
Line 1734 E.g., a definition using @code{TO} might	Line 1741 E.g., a definition using @code{TO} might
: strcmp @{ addr1 u1 addr2 u2 -- n @}	: strcmp @{ addr1 u1 addr2 u2 -- n @}
u1 u2 min 0	u1 u2 min 0
?do	?do
addr1 c@ addr2 c@ -	addr1 c@@ addr2 c@@ -
?dup-if	?dup-if
unloop exit	unloop exit
then	then
Line 1757 are initialized with the right value for	Line 1764 are initialized with the right value for
addr1 addr2	addr1 addr2
u1 u2 min 0	u1 u2 min 0
?do @{ s1 s2 @}	?do @{ s1 s2 @}
s1 c@ s2 c@ -	s1 c@@ s2 c@@ -
?dup-if	?dup-if
unloop exit	unloop exit
then	then
Line 1957 programs harder to read, and easier to m	Line 1964 programs harder to read, and easier to m
merit of this syntax is that it is easy to implement using the ANS Forth	merit of this syntax is that it is easy to implement using the ANS Forth
locals wordset.	locals wordset.

@node Defining Words, Wordlists, Locals, Words	@node Defining Words, Tokens for Words, Locals, Words
@section Defining Words	@section Defining Words

@menu	@menu
Line 2009 You can create new defining words simply	Line 2016 You can create new defining words simply
around existing defining words and putting the sequence in a colon	around existing defining words and putting the sequence in a colon
definition.	definition.

If you want the words defined by your defining words to behave	If you want the words defined with your defining words to behave
differently than words defined with standard defining words, you can	differently from words defined with standard defining words, you can
write your defining word like this:	write your defining word like this:

@example	@example
Line 2026 Technically, this fragment defines a def	Line 2033 Technically, this fragment defines a def
a word @code{name}; when you execute @code{name}, the address of the	a word @code{name}; when you execute @code{name}, the address of the
body of @code{name} is put on the data stack and @var{code2} is executed	body of @code{name} is put on the data stack and @var{code2} is executed
(the address of the body of @code{name} is the address @code{HERE}	(the address of the body of @code{name} is the address @code{HERE}
returns immediately after the @code{CREATE}). E.g., you can implement	returns immediately after the @code{CREATE}).
@code{Constant} in this way:
	In other words, if you make the following definitions:

	@example
	: def-word1 ( "name" -- )
	Create @var{code1} ;

	: action1 ( ... -- ... )
	@var{code2} ;

	def-word name1
	@end example

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

	E.g., you can implement @code{Constant} in this way:

@example	@example
: constant ( w "name" -- )	: constant ( w "name" -- )
create ,	create ,
DOES> ( -- w )	DOES> ( -- w )
@ ;	@@ ;
@end example	@end example

When you create a constant with @code{5 constant five}, first a new word	When you create a constant with @code{5 constant five}, first a new word
Line 2050 locals declarations for stack effect spe	Line 2072 locals declarations for stack effect spe

@subsubsection Applications of @code{CREATE..DOES>}	@subsubsection Applications of @code{CREATE..DOES>}

You may not be sure how to use this feature. Here are some usage	You may wonder how to use this feature. Here are some usage patterns:
patterns:

When you see a sequence of code occurring several times, and you can	When you see a sequence of code occurring several times, and you can
identify a meaning, you will factor it out as a colon definition. When	identify a meaning, you will factor it out as a colon definition. When
Line 2059 you see similar colon definitions, you c	Line 2080 you see similar colon definitions, you c
@code{CREATE..DOES>}. E.g., an assembler usually defines several words	@code{CREATE..DOES>}. E.g., an assembler usually defines several words
that look very similar:	that look very similar:
@example	@example
: ori, ( reg-taget reg-source n -- )	: ori, ( reg-target reg-source n -- )
0 asm-reg-reg-imm ;	0 asm-reg-reg-imm ;
: andi, ( reg-taget reg-source n -- )	: andi, ( reg-target reg-source n -- )
1 asm-reg-reg-imm ;	1 asm-reg-reg-imm ;
@end example	@end example

Line 2069 This could be factored with:	Line 2090 This could be factored with:
@example	@example
: reg-reg-imm ( op-code -- )	: reg-reg-imm ( op-code -- )
create ,	create ,
DOES> ( reg-taget reg-source n -- )	DOES> ( reg-target reg-source n -- )
@ asm-reg-reg-imm ;	@@ asm-reg-reg-imm ;

0 reg-reg-imm ori,	0 reg-reg-imm ori,
1 reg-reg-imm andi,	1 reg-reg-imm andi,
Line 2085 be done like this:	Line 2106 be done like this:
: curry+ ( n1 -- )	: curry+ ( n1 -- )
create ,	create ,
DOES> ( n2 -- n1+n2 )	DOES> ( n2 -- n1+n2 )
@ + ;	@@ + ;

3 curry+ 3+	3 curry+ 3+
-2 curry+ 2-	-2 curry+ 2-
Line 2128 CREATE name ( ... -- ... )	Line 2149 CREATE name ( ... -- ... )
DOES>	DOES>
@var{code} ;	@var{code} ;
@end example	@end example
This is equivalwent to the standard	This is equivalent to the standard
@example	@example
:noname	:noname
DOES>	DOES>
Line 2198 IS deferred	Line 2219 IS deferred
@node Interpretation and Compilation Semantics, , Supplying names, Defining Words	@node Interpretation and Compilation Semantics, , Supplying names, Defining Words
@subsection Interpretation and Compilation Semantics	@subsection Interpretation and Compilation Semantics

	The @dfn{interpretation semantics} of a word are what the text
	interpreter does when it encounters the word in interpret state. It also
	appears in some other contexts, e.g., the execution token returned by
	@code{' @var{word}} identifies the interpretation semantics of
	@var{word} (in other words, @code{' @var{word} execute} is equivalent to
	interpret-state text interpretation of @code{@var{word}}).

	The @dfn{compilation semantics} of a word are what the text interpreter
	does when it encounters the word in compile state. It also appears in
	other contexts, e.g, @code{POSTPONE @var{word}} compiles@footnote{In
	standard terminology, ``appends to the current definition''.} the
	compilation semantics of @var{word}.

	The standard also talks about @dfn{execution semantics}. They are used
	only for defining the interpretation and compilation semantics of many
	words. By default, the interpretation semantics of a word are to
	@code{execute} its execution semantics, and the compilation semantics of
	a word are to @code{compile,} its execution semantics.@footnote{In
	standard terminology: The default interpretation semantics are its
	execution semantics; the default compilation semantics are to append its
	execution semantics to the execution semantics of the current
	definition.}

	You can change the compilation semantics into @code{execute}ing the
	execution semantics with

doc-immediate	doc-immediate

	You can remove the interpretation semantics of a word with

	doc-compile-only
	doc-restrict

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

	Gforth also allows you to define words with arbitrary combinations of
	interpretation and compilation semantics.

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

	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:
	they make it hard to get at both parts of the word in some contexts.
	E.g., assume you want to get an execution token for the compilation
	part. Instead, define two words, one that embodies the interpretation
	part, and one that embodies the compilation part.

	There is, however, a potentially useful application of this feature:
	Providing differing implementations for the default semantics. While
	this introduces redundancy and is therefore usually a bad idea, a
	performance improvement may be worth the trouble. E.g., consider the
	word @code{foobar}:

	@example
	: foobar
	foo bar ;
	@end example

	Let us assume that @code{foobar} is called so frequently that the
	calling overhead would take a significant amount of the run-time. We can
	optimize it with @code{interpret/compile:}:

	@example
	:noname
	foo bar ;
	:noname
	POSTPONE foo POSTPONE bar ;
	interpret/compile: foobar
	@end example

	This definition has the same interpretation semantics and essentially
	the same compilation semantics as the simple definition of
	@code{foobar}, but the implementation of the compilation semantics is
	more efficient with respect to run-time.

	Some people try to use state-smart words to emulate the feature provided
	by @code{interpret/compile:} (words are state-smart if they check
	@code{STATE} during execution). E.g., they would try to code
	@code{foobar} like this:

	@example
	: foobar
	STATE @@
	IF ( compilation state )
	POSTPONE foo POSTPONE bar
	ELSE
	foo bar
	ENDIF ; immediate
	@end example

	While this works if @code{foobar} is processed only by the text
	interpreter, it does not work in other contexts (like @code{'} or
	@code{POSTPONE}). E.g., @code{' foobar} will produce an execution token
	for a state-smart word, not for the interpretation semantics of the
	original @code{foobar}; when you execute this execution token (directly
	with @code{EXECUTE} or indirectly through @code{COMPILE,}) in compile
	state, the result will not be what you expected (i.e., it will not
	perform @code{foo bar}). State-smart words are a bad idea. Simply don't
	write them!

	It is also possible to write defining words that define words with
	arbitrary combinations of interpretation and compilation semantics (or,
	preferably, arbitrary combinations of implementations of the default
	semantics). In general, this looks like:

	@example
	: def-word
	create-interpret/compile
	@var{code1}
	interpretation>
	@var{code2}
	<interpretation
	compilation>
	@var{code3}
	<compilation ;
	@end example

	For a @var{word} defined with @code{def-word}, the interpretation
	semantics are to push the address of the body of @var{word} and perform
	@var{code2}, and the compilation semantics are to push the address of
	the body of @var{word} and perform @var{code3}. E.g., @code{constant}
	can also be defined like this:

	@example
	: constant ( n "name" -- )
	create-interpret/compile
	,
	interpretation> ( -- n )
	@@
	<interpretation
	compilation> ( compilation. -- ; run-time. -- n )
	@@ postpone literal
	<compilation ;
	@end example

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

	Note that words defined with @code{interpret/compile:} and
	@code{create-interpret/compile} have an extended header structure that
	differs from other words; however, unless you try to access them with
	plain address arithmetic, you should not notice this. Words for
	accessing the header structure usually know how to deal with this; e.g.,
	@code{' word >body} also gives you the body of a word created with
	@code{create-interpret/compile}.

	@node Tokens for Words, Wordlists, Defining Words, Words
	@section Tokens for Words

	This chapter describes the creation and use of tokens that represent
	words on the stack (and in data space).

	Named words have interpretation and compilation semantics. Unnamed words
	just have execution semantics.

	An @dfn{execution token} represents the execution semantics of an
	unnamed word. An execution token occupies one cell. As explained in
	section @ref{Supplying names}, the execution token of the last words
	defined can be produced with

	short-lastxt

	You can perform the semantics represented by an execution token with
	doc-execute
	You can compile the word with
	doc-compile,

	In Gforth, the abstract data type @emph{execution token} is implemented
	as CFA (code field address).

	The interpretation semantics of a named word are also represented by an
	execution token. You can get it with

	doc-[']
	doc-'

	For literals, you use @code{'} in interpreted code and @code{[']} in
	compiled code. Gforth's @code{'} and @code{[']} behave somewhat unusual
	by complaining about compile-only words. To get an execution token for a
	compiling word @var{X}, use @code{COMP' @var{X} drop} or @code{[COMP']
	@var{X} drop}.

	The compilation semantics are represented by a @dfn{compilation token}
	consisting of two cells: @var{w xt}. The top cell @var{xt} is an
	execution token. The compilation semantics represented by the
	compilation token can be performed with @code{execute}, which consumes
	the whole compilation token, with an additional stack effect determined
	by the represented compilation semantics.

	doc-[comp']
	doc-comp'

	You can compile the compilation semantics with @code{postpone,}. I.e.,
	@code{COMP' @var{word} POSTPONE,} is equivalent to @code{POSTPONE
	@var{word}}.

	doc-postpone,

	At present, the @var{w} part of a compilation token is an execution
	token, and the @var{xt} part represents either @code{execute} or
	@code{compile,}. However, don't rely on that knowledge, unless necessary;
	we may introduce unusual compilation tokens in the future (e.g.,
	compilation tokens representing the compilation semantics of literals).

	Named words are also represented by the @dfn{name token}. The abstract
	data type @emph{name token} is implemented as NFA (name field address).

	doc-find-name
	doc-name>int
	doc-name?int
	doc-name>comp
	doc-name>string

@node Wordlists, Files, Defining Words, Words	@node Wordlists, Files, Tokens for Words, Words
@section Wordlists	@section Wordlists

@node Files, Blocks, Wordlists, Words	@node Files, Blocks, Wordlists, Words
Line 2231 are meant to support a different style o	Line 2464 are meant to support a different style o
tracing/stepping debuggers used in languages with long turn-around	tracing/stepping debuggers used in languages with long turn-around
times.	times.

A much better (faster) way in fast-compilig languages is to add	A much better (faster) way in fast-compiling languages is to add
printing code at well-selected places, let the program run, look at	printing code at well-selected places, let the program run, look at
the output, see where things went wrong, add more printing code, etc.,	the output, see where things went wrong, add more printing code, etc.,
until the bug is found.	until the bug is found.
Line 2320 probably more appropriate than an assert	Line 2553 probably more appropriate than an assert
Gforth provides some words for defining primitives (words written in	Gforth provides some words for defining primitives (words written in
machine code), and for defining the the machine-code equivalent of	machine code), and for defining the the machine-code equivalent of
@code{DOES>}-based defining words. However, the machine-independent	@code{DOES>}-based defining words. However, the machine-independent
nature of Gforth poses a few problems: First of all. Gforth runs on	nature of Gforth poses a few problems: First of all, Gforth runs on
several architectures, so it can provide no standard assembler. What's	several architectures, so it can provide no standard assembler. What's
worse is that the register allocation not only depends on the processor,	worse is that the register allocation not only depends on the processor,
but also on the @code{gcc} version and options used.	but also on the @code{gcc} version and options used.
Line 2416 with @code{>DOES-CODE}. If the word was	Line 2649 with @code{>DOES-CODE}. If the word was
returned is different from 0 and identifies the @code{DOES>} used by the	returned is different from 0 and identifies the @code{DOES>} used by the
defining word.	defining word.

@node ANS conformance, Model, Words, Top	@node Tools, ANS conformance, Words, Top
	@chapter Tools

	@menu
	* ANS Report:: Report the words used, sorted by wordset
	@end menu

	See also @ref{Emacs and Gforth}.

	@node ANS Report, , Tools, Tools
	@section @file{ans-report.fs}: Report the words used, sorted by wordset

	If you want to label a Forth program as ANS Forth Program, you must
	document which wordsets the program uses; for extension wordsets, it is
	helpful to list the words the program requires from these wordsets
	(because Forth systems are allowed to provide only some words of them).

	The @file{ans-report.fs} tool makes it easy for you to determine which
	words from which wordset and which non-ANS words your application
	uses. You simply have to include @file{ans-report.fs} before loading the
	program you want to check. After loading your program, you can get the
	report with @code{print-ans-report}. A typical use is to run this as
	batch job like this:
	@example
	gforth ans-report.fs myprog.fs -e "print-ans-report bye"
	@end example

	The output looks like this (for @file{compat/control.fs}):
	@example
	The program uses the following words
	from CORE :
	: POSTPONE THEN ; immediate ?dup IF 0=
	from BLOCK-EXT :
	\
	from FILE :
	(
	@end example

	@subsection Caveats

	Note that @file{ans-report.fs} just checks which words are used, not whether
	they are used in an ANS Forth conforming way!

	Some words are defined in several wordsets in the
	standard. @file{ans-report.fs} reports them for only one of the
	wordsets, and not necessarily the one you expect. It depends on usage
	which wordset is the right one to specify. E.g., if you only use the
	compilation semantics of @code{S"}, it is a Core word; if you also use
	its interpretation semantics, it is a File word.


	@node ANS conformance, Model, Tools, Top
@chapter ANS conformance	@chapter ANS conformance

To the best of our knowledge, Gforth is an	To the best of our knowledge, Gforth is an
Line 2499 processor-dependent. Gforth's alignment	Line 2783 processor-dependent. Gforth's alignment

@item @code{EMIT} and non-graphic characters:	@item @code{EMIT} and non-graphic characters:
The character is output using the C library function (actually, macro)	The character is output using the C library function (actually, macro)
@code{putchar}.	@code{putc}.

@item character editing of @code{ACCEPT} and @code{EXPECT}:	@item character editing of @code{ACCEPT} and @code{EXPECT}:
This is modeled on the GNU readline library (@pxref{Readline	This is modeled on the GNU readline library (@pxref{Readline
Line 2519 installation-dependent. Currently a char	Line 2803 installation-dependent. Currently a char

@item character-set extensions and matching of names:	@item character-set extensions and matching of names:
Any character except the ASCII NUL charcter can be used in a	Any character except the ASCII NUL charcter can be used in a
name. Matching is case-insensitive. The matching is performed using the	name. Matching is case-insensitive (except in @code{TABLE}s. The
C function @code{strncasecmp}, whose function is probably influenced by	matching is performed using the C function @code{strncasecmp}, whose
the locale. E.g., the @code{C} locale does not know about accents and	function is probably influenced by the locale. E.g., the @code{C} locale
umlauts, so they are matched case-sensitively in that locale. For	does not know about accents and umlauts, so they are matched
portability reasons it is best to write programs such that they work in	case-sensitively in that locale. For portability reasons it is best to
the @code{C} locale. Then one can use libraries written by a Polish	write programs such that they work in the @code{C} locale. Then one can
programmer (who might use words containing ISO Latin-2 encoded	use libraries written by a Polish programmer (who might use words
characters) and by a French programmer (ISO Latin-1) in the same program	containing ISO Latin-2 encoded characters) and by a French programmer
(of course, @code{WORDS} will produce funny results for some of the	(ISO Latin-1) in the same program (of course, @code{WORDS} will produce
words (which ones, depends on the font you are using)). Also, the locale	funny results for some of the words (which ones, depends on the font you
you prefer may not be available in other operating systems. Hopefully,	are using)). Also, the locale you prefer may not be available in other
Unicode will solve these problems one day.	operating systems. Hopefully, Unicode will solve these problems one day.

@item conditions under which control characters match a space delimiter:	@item conditions under which control characters match a space delimiter:
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
Line 2563 The error string is stored into the vari	Line 2847 The error string is stored into the vari
@code{-2 throw} is performed.	@code{-2 throw} is performed.

@item input line terminator:	@item input line terminator:
For interactive input, @kbd{C-m} and @kbd{C-j} terminate lines. One of	For interactive input, @kbd{C-m} (CR) and @kbd{C-j} (LF) terminate
these characters is typically produced when you type the @kbd{Enter} or	lines. One of these characters is typically produced when you type the
@kbd{Return} key.	@kbd{Enter} or @kbd{Return} key.

@item maximum size of a counted string:	@item maximum size of a counted string:
@code{s" /counted-string" environment? drop .}. Currently 255 characters	@code{s" /counted-string" environment? drop .}. Currently 255 characters
Line 2586 change it from within Gforth. However, t	Line 2870 change it from within Gforth. However, t
redirected in the command line that starts Gforth.	redirected in the command line that starts Gforth.

@item method of selecting the user output device:	@item method of selecting the user output device:
The user output device is the standard output. It cannot be redirected	@code{EMIT} and @code{TYPE} output to the file-id stored in the value
from within Gforth, but typically from the command line that starts	@code{outfile-id} (@code{stdout} by default). Gforth uses buffered
Gforth. Gforth uses buffered output, so output on a terminal does not	output, so output on a terminal does not become visible before the next
become visible before the next newline or buffer overflow. Output on	newline or buffer overflow. Output on non-terminals is invisible until
non-terminals is invisible until the buffer overflows.	the buffer overflows.

@item methods of dictionary compilation:	@item methods of dictionary compilation:
What are we expected to document here?	What are we expected to document here?
Line 2626 string.	Line 2910 string.
@code{1 chars .}. 1 on all current ports.	@code{1 chars .}. 1 on all current ports.

@item size of the keyboard terminal buffer:	@item size of the keyboard terminal buffer:
Varies. You can determine the size at a specific time using @code{lp@	Varies. You can determine the size at a specific time using @code{lp@@
tib - .}. It is shared with the locals stack and TIBs of files that	tib - .}. It is shared with the locals stack and TIBs of files that
include the current file. You can change the amount of space for TIBs	include the current file. You can change the amount of space for TIBs
and locals stack at Gforth startup with the command line option	and locals stack at Gforth startup with the command line option
Line 2638 shared with @code{WORD}.	Line 2922 shared with @code{WORD}.

@item size of the scratch area returned by @code{PAD}:	@item size of the scratch area returned by @code{PAD}:
The remainder of dictionary space. You can even use the unused part of	The remainder of dictionary space. You can even use the unused part of
the data stack space. The current size can be computed with @code{sp@	the data stack space. The current size can be computed with @code{sp@@
pad - .}.	pad - .}.

@item system case-sensitivity characteristics:	@item system case-sensitivity characteristics:
Dictionary searches are case insensitive. However, as explained above	Dictionary searches are case insensitive (except in
under @i{character-set extensions}, the matching for non-ASCII	@code{TABLE}s). However, as explained above under @i{character-set
characters is determined by the locale you are using. In the default	extensions}, the matching for non-ASCII characters is determined by the
@code{C} locale all non-ASCII characters are matched case-sensitively.	locale you are using. In the default @code{C} locale all non-ASCII
	characters are matched case-sensitively.

@item system prompt:	@item system prompt:
@code{ ok} in interpret state, @code{ compiled} in compile state.	@code{ ok} in interpret state, @code{ compiled} in compile state.
Line 2662 the choice to @code{gcc} (what to use fo	Line 2947 the choice to @code{gcc} (what to use fo
On two's complement machines, arithmetic is performed modulo	On two's complement machines, arithmetic is performed modulo
2bits-per-cell for single arithmetic and 4bits-per-cell for double	2bits-per-cell for single arithmetic and 4bits-per-cell for double
arithmetic (with appropriate mapping for signed types). Division by zero	arithmetic (with appropriate mapping for signed types). Division by zero
typically results in a @code{-55 throw} (floatingpoint unidentified	typically results in a @code{-55 throw} (Floating-point unidentified
fault), although a @code{-10 throw} (divide by zero) would be more	fault), although a @code{-10 throw} (divide by zero) would be more
appropriate.	appropriate.

Line 2679 No.	Line 2964 No.
@table @i	@table @i

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

@item a definition name exceeds the maximum length allowed:	@item a definition name exceeds the maximum length allowed:
@code{-19 throw} (Word name too long)	@code{-19 throw} (Word name too long)
Line 2696 flow words, and issue a @code{ABORT"} or	Line 2983 flow words, and issue a @code{ABORT"} or
mismatch).	mismatch).

@item attempting to obtain the execution token of a word with undefined execution semantics:	@item attempting to obtain the execution token of a word with undefined execution semantics:
You get an execution token representing the compilation semantics	@code{-14 throw} (Interpreting a compile-only word). In some cases, you
instead.	get an execution token for @code{compile-only-error} (which performs a
	@code{-14 throw} when executed).

@item dividing by zero:	@item dividing by zero:
typically results in a @code{-55 throw} (floating point unidentified	typically results in a @code{-55 throw} (floating point unidentified
Line 2718 error appears at a different place when	Line 3006 error appears at a different place when

@item interpreting a word with undefined interpretation semantics:	@item interpreting a word with undefined interpretation semantics:
For some words, we defined interpretation semantics. For the others:	For some words, we defined interpretation semantics. For the others:
@code{-14 throw} (Interpreting a compile-only word). Note that this is	@code{-14 throw} (Interpreting a compile-only word).
checked only by the outer (aka text) interpreter; if the word is
@code{execute}d in some other way, it will typically perform it's
compilation semantics even in interpret state. (We could change @code{'}
and relatives not to give the xt of such words, but we think that would
be too restrictive).

@item modifying the contents of the input buffer or a string literal:	@item modifying the contents of the input buffer or a string literal:
These are located in writable memory and can be modified.	These are located in writable memory and can be modified.
Line 2750 underflow) is performed. Apart from that	Line 3033 underflow) is performed. Apart from that
underflows can result in similar behaviour as overflows (of adjacent	underflows can result in similar behaviour as overflows (of adjacent
stacks).	stacks).

@item unexepected end of the input buffer, resulting in an attempt to use a zero-length string as a name:	@item unexpected end of the input buffer, resulting in an attempt to use a zero-length string as a name:
@code{Create} and its descendants perform a @code{-16 throw} (Attempt to	@code{Create} and its descendants perform a @code{-16 throw} (Attempt to
use zero-length string as a name). Words like @code{'} probably will not	use zero-length string as a name). Words like @code{'} probably will not
find what they search. Note that it is possible to create zero-length	find what they search. Note that it is possible to create zero-length
names with @code{nextname} (should it not?).	names with @code{nextname} (should it not?).

@item @code{>IN} greater than input buffer:	@item @code{>IN} greater than input buffer:
The next invocation of a parsing word returns a string wih length 0.	The next invocation of a parsing word returns a string with length 0.

@item @code{RECURSE} appears after @code{DOES>}:	@item @code{RECURSE} appears after @code{DOES>}:
Compiles a recursive call to the defining word not to the defined word.	Compiles a recursive call to the defining word, not to the defined word.

@item argument input source different than current input source for @code{RESTORE-INPUT}:	@item argument input source different than current input source for @code{RESTORE-INPUT}:
@code{-12 THROW}. Note that, once an input file is closed (e.g., because	@code{-12 THROW}. Note that, once an input file is closed (e.g., because
Line 2769 reused. Therefore, restoring an input so	Line 3052 reused. Therefore, restoring an input so
closed file may lead to unpredictable results instead of a @code{-12	closed file may lead to unpredictable results instead of a @code{-12
THROW}.	THROW}.

In the future, Gforth may be able to retore input source specifications	In the future, Gforth may be able to restore input source specifications
from other than the current input soruce.	from other than the current input source.

@item data space containing definitions gets de-allocated:	@item data space containing definitions gets de-allocated:
Deallocation with @code{allot} is not checked. This typically resuls in	Deallocation with @code{allot} is not checked. This typically results in
memory access faults or execution of illegal instructions.	memory access faults or execution of illegal instructions.

@item data space read/write with incorrect alignment:	@item data space read/write with incorrect alignment:
Line 2797 stack items are loop control parameters	Line 3080 stack items are loop control parameters
@code{abort" last word was headerless"}.	@code{abort" last word was headerless"}.

@item name not defined by @code{VALUE} used by @code{TO}:	@item name not defined by @code{VALUE} used by @code{TO}:
@code{-32 throw} (Invalid name argument)	@code{-32 throw} (Invalid name argument) (unless name was defined by
	@code{CONSTANT}; then it just changes the constant).

@item name not found (@code{'}, @code{POSTPONE}, @code{[']}, @code{[COMPILE]}):	@item name not found (@code{'}, @code{POSTPONE}, @code{[']}, @code{[COMPILE]}):
@code{-13 throw} (Undefined word)	@code{-13 throw} (Undefined word)
Line 2807 Gforth behaves as if they were of the sa	Line 3091 Gforth behaves as if they were of the sa
the behaviour by interpreting all parameters as, e.g., signed.	the behaviour by interpreting all parameters as, e.g., signed.

@item @code{POSTPONE} or @code{[COMPILE]} applied to @code{TO}:	@item @code{POSTPONE} or @code{[COMPILE]} applied to @code{TO}:
Assume @code{: X POSTPONE TO ; IMMEDIATE}. @code{X} is equivalent to	Assume @code{: X POSTPONE TO ; IMMEDIATE}. @code{X} performs the
@code{TO}.	compilation semantics of @code{TO}.

@item String longer than a counted string returned by @code{WORD}:	@item String longer than a counted string returned by @code{WORD}:
Not checked. The string will be ok, but the count will, of course,	Not checked. The string will be ok, but the count will, of course,
Line 2847 and you can give commands to Gforth inte	Line 3131 and you can give commands to Gforth inte
available depend on how you invoke Gforth.	available depend on how you invoke Gforth.

@item program data space available:	@item program data space available:
@code{sp@ here - .} gives the space remaining for dictionary and data	@code{UNUSED .} gives the remaining dictionary space. The total
stack together.	dictionary space can be specified with the @code{-m} switch
	(@pxref{Invocation}) when Gforth starts up.

@item return stack space available:	@item return stack space available:
By default 16 KBytes. The default can be overridden with the @code{-r}	You can compute the total return stack space in cells with
switch (@pxref{Invocation}) when Gforth starts up.	@code{s" RETURN-STACK-CELLS" environment? drop .}. You can specify it at
	startup time with the @code{-r} switch (@pxref{Invocation}).

@item stack space available:	@item stack space available:
@code{sp@ here - .} gives the space remaining for dictionary and data	You can compute the total data stack space in cells with
stack together.	@code{s" STACK-CELLS" environment? drop .}. You can specify it at
	startup time with the @code{-d} switch (@pxref{Invocation}).

@item system dictionary space required, in address units:	@item system dictionary space required, in address units:
Type @code{here forthstart - .} after startup. At the time of this	Type @code{here forthstart - .} after startup. At the time of this
writing, this gives 70108 (bytes) on a 32-bit system.	writing, this gives 80080 (bytes) on a 32-bit system.
@end table	@end table


Line 2981 The least significant cell of @var{d} is	Line 3268 The least significant cell of @var{d} is
The codes -256@minus{}-511 are used for reporting signals (see	The codes -256@minus{}-511 are used for reporting signals (see
@file{errore.fs}). The codes -512@minus{}-2047 are used for OS errors	@file{errore.fs}). The codes -512@minus{}-2047 are used for OS errors
(for file and memory allocation operations). The mapping from OS error	(for file and memory allocation operations). The mapping from OS error
numbers to throw code is -512@minus{}@var{errno}. One side effect of	numbers to throw code is -512@minus{}@code{errno}. One side effect of
this mapping is that undefined OS errors produce a message with a	this mapping is that undefined OS errors produce a message with a
strange number; e.g., @code{-1000 THROW} results in @code{Unknown error	strange number; e.g., @code{-1000 THROW} results in @code{Unknown error
488} on my system.	488} on my system.
Line 3006 strange number; e.g., @code{-1000 THROW}	Line 3293 strange number; e.g., @code{-1000 THROW}
@table @i	@table @i

@item encoding of keyboard events (@code{EKEY}):	@item encoding of keyboard events (@code{EKEY}):
Not yet implemeted.	Not yet implemented.

@item duration of a system clock tick	@item duration of a system clock tick
System dependent. With respect to @code{MS}, the time is specified in	System dependent. With respect to @code{MS}, the time is specified in
Line 3030 other single-tasking systems, it should	Line 3317 other single-tasking systems, it should
@table @i	@table @i

@item @code{AT-XY} can't be performed on user output device:	@item @code{AT-XY} can't be performed on user output device:
Largely terminal dependant. No range checks are done on the arguments.	Largely terminal dependent. No range checks are done on the arguments.
No errors are reported. You may see some garbage appearing, you may see	No errors are reported. You may see some garbage appearing, you may see
simply nothing happen.	simply nothing happen.

Line 3079 System dependent. Gforth just uses the f	Line 3366 System dependent. Gforth just uses the f
@code{FILE-STATUS} returns the most powerful file access mode allowed	@code{FILE-STATUS} returns the most powerful file access mode allowed
for the file: Either @code{R/O}, @code{W/O} or @code{R/W}. If the file	for the file: Either @code{R/O}, @code{W/O} or @code{R/W}. If the file
cannot be accessed, @code{R/O BIN} is returned. @code{BIN} is applicable	cannot be accessed, @code{R/O BIN} is returned. @code{BIN} is applicable
along with the retured mode.	along with the returned mode.

@item input file state after an exception when including source:	@item input file state after an exception when including source:
All files that are left via the exception are closed.	All files that are left via the exception are closed.
Line 3098 of open files available. This should not	Line 3385 of open files available. This should not
@code{/line}. Currently 255.	@code{/line}. Currently 255.

@item methods of mapping block ranges to files:	@item methods of mapping block ranges to files:
Currently, the block words automatically access the file	By default, blocks are accessed in the file @file{blocks.fb} in the
@file{blocks.fb} in the currend working directory. More sophisticated	current working directory. The file can be switched with @code{USE}.
methods could be implemented if there is demand (and a volunteer).

@item number of string buffers provided by @code{S"}:	@item number of string buffers provided by @code{S"}:
1	1
Line 3179 nearest, and break ties by rounding to e	Line 3465 nearest, and break ties by rounding to e
bit of the mantissa is 0).	bit of the mantissa is 0).

@item size of floating-point stack:	@item size of floating-point stack:
@code{s" FLOATING-STACK" environment? drop .}. Can be changed at startup	@code{s" FLOATING-STACK" environment? drop .} gives the total size of
with the command-line option @code{-f}.	the floating-point stack (in floats). You can specify this on startup
	with the command-line option @code{-f} (@pxref{Invocation}).

@item width of floating-point stack:	@item width of floating-point stack:
@code{1 floats}.	@code{1 floats}.
Line 3196 with the command-line option @code{-f}.	Line 3483 with the command-line option @code{-f}.
@table @i	@table @i

@item @code{df@@} or @code{df!} used with an address that is not double-float aligned:	@item @code{df@@} or @code{df!} used with an address that is not double-float aligned:
System-dependent. Typically results in an alignment fault like other	System-dependent. Typically results in a @code{-23 THROW} like other
alignment violations.	alignment violations.

@item @code{f@@} or @code{f!} used with an address that is not float aligned:	@item @code{f@@} or @code{f!} used with an address that is not float aligned:
System-dependent. Typically results in an alignment fault like other	System-dependent. Typically results in a @code{-23 THROW} like other
alignment violations.	alignment violations.

@item Floating-point result out of range:	@item Floating-point result out of range:
Line 3348 intended as throw codes. They typically	Line 3635 intended as throw codes. They typically
@table @i	@table @i

@item ending sequence for input following @code{;code} and @code{code}:	@item ending sequence for input following @code{;code} and @code{code}:
Not implemented (yet).	@code{end-code}

@item manner of processing input following @code{;code} and @code{code}:	@item manner of processing input following @code{;code} and @code{code}:
Not implemented (yet).	The @code{assembler} vocabulary is pushed on the search order stack, and
	the input is processed by the text interpreter, (starting) in interpret
	state.

@item search order capability for @code{EDITOR} and @code{ASSEMBLER}:	@item search order capability for @code{EDITOR} and @code{ASSEMBLER}:
Not implemented (yet). If they were implemented, they would use the	The ANS Forth search order word set.
search order wordset.

@item source and format of display by @code{SEE}:	@item source and format of display by @code{SEE}:
The source for @code{see} is the intermediate code used by the inner	The source for @code{see} is the intermediate code used by the inner
Line 3384 unlucky, this ambiguous condition is not	Line 3672 unlucky, this ambiguous condition is not
Not implemented (yet).	Not implemented (yet).

@item @var{name} not defined via @code{CREATE}:	@item @var{name} not defined via @code{CREATE}:
@code{;code} is not implemented (yet). If it were, it would behave like	@code{;code} behaves like @code{DOES>} in this respect, i.e., it changes
@code{DOES>} in this respect, i.e., change the execution semantics of	the execution semantics of the last defined word no matter how it was
the last defined word no matter how it was defined.	defined.

@item @code{POSTPONE} applied to @code{[IF]}:	@item @code{POSTPONE} applied to @code{[IF]}:
After defining @code{: X POSTPONE [IF] ; IMMEDIATE}. @code{X} is	After defining @code{: X POSTPONE [IF] ; IMMEDIATE}. @code{X} is
Line 3466 that are otherwise written in C, C++, or	Line 3754 that are otherwise written in C, C++, or

The Forth system ATLAST provides facilities for embedding it into	The Forth system ATLAST provides facilities for embedding it into
applications; unfortunately it has several disadvantages: most	applications; unfortunately it has several disadvantages: most
implorantly, it is not based on ANS Forth, and it is apparently dead	importantly, it is not based on ANS Forth, and it is apparently dead
(i.e., not developed further and not supported). The facilities	(i.e., not developed further and not supported). The facilities
provided by Gforth in this area are inspired by ATLASTs facilities, so	provided by Gforth in this area are inspired by ATLASTs facilities, so
making the switch should not be hard.	making the switch should not be hard.
Line 3483 prefix @code{forth_}. (Global symbols th	Line 3771 prefix @code{forth_}. (Global symbols th
prefix @code{gforth_}).	prefix @code{gforth_}).

You can include the declarations of Forth types and the functions and	You can include the declarations of Forth types and the functions and
variables of the interface with @code{include <forth.h>}.	variables of the interface with @code{#include <forth.h>}.

Types.	Types.

Line 3728 lies in the body (which is illegal in th	Line 4016 lies in the body (which is illegal in th
making the code field larger for all words this solution becomes legal	making the code field larger for all words this solution becomes legal
again. We use this approach for the indirect threaded version. Leaving	again. We use this approach for the indirect threaded version. Leaving
a cell unused in most words is a bit wasteful, but on the machines we	a cell unused in most words is a bit wasteful, but on the machines we
are targetting this is hardly a problem. The other reason for having a	are targeting this is hardly a problem. The other reason for having a
code field size of two cells is to avoid having different image files	code field size of two cells is to avoid having different image files
for direct and indirect threaded systems (@pxref{System Architecture}).	for direct and indirect threaded systems (@pxref{System Architecture}).

Line 3922 comply to some restrictions: addresses h	Line 4210 comply to some restrictions: addresses h
special words (@code{A!}, @code{A,}, etc.) in order to make the code	special words (@code{A!}, @code{A,}, etc.) in order to make the code
relocatable. Cells, floats, etc., have to be stored at the natural	relocatable. Cells, floats, etc., have to be stored at the natural
alignment boundaries@footnote{E.g., store floats (8 bytes) at an address	alignment boundaries@footnote{E.g., store floats (8 bytes) at an address
dividable by~8. This happens automatically in our system when you use	divisible by~8. This happens automatically in our system when you use
the ANS Forth alignment words.}, in order to avoid alignment faults on	the ANS Forth alignment words.}, in order to avoid alignment faults on
machines with stricter alignment. The image file is produced by a	machines with stricter alignment. The image file is produced by a
metacompiler (@file{cross.fs}).	metacompiler (@file{cross.fs}).
Line 3981 relative Win32- NT eforth	Line 4269 relative Win32- NT eforth
time Gforth Forth Forth eforth +opt PFE Forth TILE	time Gforth Forth Forth eforth +opt PFE Forth TILE
sieve 1.00 1.39 1.14 1.39 0.85 1.58 3.18 8.58	sieve 1.00 1.39 1.14 1.39 0.85 1.58 3.18 8.58
bubble 1.00 1.31 1.41 1.48 0.88 1.50 3.88	bubble 1.00 1.31 1.41 1.48 0.88 1.50 3.88
matmul 1.00 1.47 1.35 1.46 1.16 1.58 4.09	matmul 1.00 1.47 1.35 1.46 0.74 1.58 4.09
fib 1.00 1.52 1.34 1.22 1.13 1.74 2.99 4.30	fib 1.00 1.52 1.34 1.22 0.86 1.74 2.99 4.30
@end example	@end example

You may find the good performance of Gforth compared with the systems	You may find the good performance of Gforth compared with the systems
Line 4054 one of Gforth's first users, in mid-1993	Line 4342 one of Gforth's first users, in mid-1993
with their continuous feedback. Lennart Benshop contributed	with their continuous feedback. Lennart Benshop contributed
@file{glosgen.fs}, while Stuart Ramsden has been working on automatic	@file{glosgen.fs}, while Stuart Ramsden has been working on automatic
support for calling C libraries. Helpful comments also came from Paul	support for calling C libraries. Helpful comments also came from Paul
Kleinrubatscher, Christian Pirker, Dirk Zoller and Marcel Hendrix.	Kleinrubatscher, Christian Pirker, Dirk Zoller, Marcel Hendrix, John
	Wavrik, Barrie Stott and Marc de Groot.

Gforth also owes a lot to the authors of the tools we used (GCC, CVS,	Gforth also owes a lot to the authors of the tools we used (GCC, CVS,
and autoconf, among others), and to the creators of the Internet: Gforth	and autoconf, among others), and to the creators of the Internet: Gforth
Line 4083 A team led by Bill Ragsdale implemented	Line 4372 A team led by Bill Ragsdale implemented
implementation of fig-Forth for the 6502 based on microForth.	implementation of fig-Forth for the 6502 based on microForth.

The principal architect of microForth was Dean Sanderson. microForth was	The principal architect of microForth was Dean Sanderson. microForth was
FORTH, Inc.'s first off-the-shelf product. It was developped in 1976 for	FORTH, Inc.'s first off-the-shelf product. It was developed in 1976 for
the 1802, and subsequently implemented on the 8080, the 6800 and the	the 1802, and subsequently implemented on the 8080, the 6800 and the
Z80.	Z80.

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

Removed from v.1.35
changed lines
	Added in v.1.42