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.48 and 1.49

version 1.48, 2000/05/14 20:23:05	version 1.49, 2000/05/15 14:04:11
Line 22	Line 22
@direntry	@direntry
* Gforth: (gforth). A fast interpreter for the Forth language.	* Gforth: (gforth). A fast interpreter for the Forth language.
@end direntry	@end direntry
	@c The Texinfo manual also recommends doing this, but for Gforth it may
	@c not make much sense
	@c @dircategory Individual utilities
	@c @direntry
	@c * Gforth: (gforth)Invoking Gforth. gforth, gforth-fast, gforthmi
	@c @end direntry

@comment @setchapternewpage odd	@comment @setchapternewpage odd
@comment TODO this gets left in by HTML converter	@comment TODO this gets left in by HTML converter
@macro progstyle {}	@macro progstyle {}
Line 62 Programming style note:	Line 69 Programming style note:

@include version.texi	@include version.texi

@ifinfo	@ifnottex
This file documents Gforth @value{VERSION}	This file documents Gforth @value{VERSION}

Copyright @copyright{} 1995-1999 Free Software Foundation, Inc.	Copyright @copyright{} 1995-1999 Free Software Foundation, Inc.
Line 90 Copyright @copyright{} 1995-1999 Free So	Line 97 Copyright @copyright{} 1995-1999 Free So
except that the sections entitled "Distribution" and "General Public	except that the sections entitled "Distribution" and "General Public
License" may be included in a translation approved by the author instead	License" may be included in a translation approved by the author instead
of in the original English.	of in the original English.
@end ifinfo	@end ifnottex

@finalout	@finalout
@titlepage	@titlepage
Line 132 Copyright @copyright{} 1995--1999 Free S	Line 139 Copyright @copyright{} 1995--1999 Free S
@end titlepage	@end titlepage

@node Top, License, (dir), (dir)	@node Top, License, (dir), (dir)
@ifinfo	@ifnottex
Gforth is a free implementation of ANS Forth available on many	Gforth is a free implementation of ANS Forth available on many
personal machines. This manual corresponds to version @value{VERSION}.	personal machines. This manual corresponds to version @value{VERSION}.
@end ifinfo	@end ifnottex

@menu	@menu
* License:: The GPL	* License:: The GPL
Line 590 modification follow.	Line 597 modification follow.
@iftex	@iftex
@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION	@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end iftex	@end iftex
@ifinfo	@ifnottex
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION	@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end ifinfo	@end ifnottex

@enumerate 0	@enumerate 0
@item	@item
Line 815 of promoting the sharing and reuse of so	Line 822 of promoting the sharing and reuse of so
@iftex	@iftex
@heading NO WARRANTY	@heading NO WARRANTY
@end iftex	@end iftex
@ifinfo	@ifnottex
@center NO WARRANTY	@center NO WARRANTY
@end ifinfo	@end ifnottex

@item	@item
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY	BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
Line 845 POSSIBILITY OF SUCH DAMAGES.	Line 852 POSSIBILITY OF SUCH DAMAGES.
@iftex	@iftex
@heading END OF TERMS AND CONDITIONS	@heading END OF TERMS AND CONDITIONS
@end iftex	@end iftex
@ifinfo	@ifnottex
@center END OF TERMS AND CONDITIONS	@center END OF TERMS AND CONDITIONS
@end ifinfo	@end ifnottex

@page	@page
@unnumberedsec How to Apply These Terms to Your New Programs	@unnumberedsec How to Apply These Terms to Your New Programs
Line 1039 material in this chapter.	Line 1046 material in this chapter.
* Startup speed:: When 35ms is not fast enough ...	* Startup speed:: When 35ms is not fast enough ...
@end menu	@end menu

@xref{Image Files} for related information about the creation of images.	For related information about the creation of images see @ref{Image Files}.

@comment ----------------------------------------------	@comment ----------------------------------------------
@node Invoking Gforth, Leaving Gforth, Gforth Environment, Gforth Environment	@node Invoking Gforth, Leaving Gforth, Gforth Environment, Gforth Environment
Line 1224 then in @file{~}, then in the normal pat	Line 1231 then in @file{~}, then in the normal pat
You can leave Gforth by typing @code{bye} or @kbd{Ctrl-d} (at the start	You can leave Gforth by typing @code{bye} or @kbd{Ctrl-d} (at the start
of a line) or (if you invoked Gforth with the @code{--die-on-signal}	of a line) or (if you invoked Gforth with the @code{--die-on-signal}
option) @kbd{Ctrl-c}. When you leave Gforth, all of your definitions and	option) @kbd{Ctrl-c}. When you leave Gforth, all of your definitions and
data are discarded. @xref{Image Files} for ways of saving the state of	data are discarded. For ways of saving the state of the system before
the system before leaving Gforth.	leaving Gforth see @ref{Image Files}.

doc-bye	doc-bye

Line 1357 for Forth source-code files.	Line 1364 for Forth source-code files.

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

@item	@item
@cindex @code{GFORTHD} -- environment variable	@cindex @code{GFORTHD} -- environment variable
Line 2029 that usually require a long sequence of	Line 2036 that usually require a long sequence of
as the bottom (i.e., first) parameter. This makes the code easier to	as the bottom (i.e., first) parameter. This makes the code easier to
read, because reader does not need to keep track of the bottom item	read, because reader does not need to keep track of the bottom item
through a long sequence of code (or, alternatively, through stack	through a long sequence of code (or, alternatively, through stack
manipulations). E.g., @code{!} (store, see @pxref{Memory}) expects the	manipulations). E.g., @code{!} (store, @pxref{Memory}) expects the
address on top of the stack because it is usually simpler to compute	address on top of the stack because it is usually simpler to compute
than the stored value (often the address is just a variable).	than the stored value (often the address is just a variable).

Line 3328 strong in debugging and reuse.	Line 3335 strong in debugging and reuse.
The primary purpose of this manual is to document Gforth. However, since	The primary purpose of this manual is to document Gforth. However, since
Forth is not a widely-known language and there is a lack of up-to-date	Forth is not a widely-known language and there is a lack of up-to-date
teaching material, it seems worthwhile to provide some introductory	teaching material, it seems worthwhile to provide some introductory
material. @xref{Forth-related information} for other sources of Forth-related	material. For other sources of Forth-related
information.	information, see @ref{Forth-related information}.

The examples in this section should work on any ANS Forth; the	The examples in this section should work on any ANS Forth; the
output shown was produced using Gforth. Each example attempts to	output shown was produced using Gforth. Each example attempts to
Line 3385 and nothing else (if you have Gforth ins	Line 3392 and nothing else (if you have Gforth ins
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
its command line interpreter, which is called the @dfn{Text Interpreter}	its command line interpreter, which is called the @dfn{Text Interpreter}
(also known as the @dfn{Outer Interpreter}). (You will learn a lot	(also known as the @dfn{Outer Interpreter}). (You will learn a lot
about the text interpreter as you read through this chapter, but	about the text interpreter as you read through this chapter, for more
@pxref{The Text Interpreter} for more detail).	detail @pxref{The Text Interpreter}).

Although it's not obvious, Forth is actually waiting for your	Although it's not obvious, Forth is actually waiting for your
input. Type a number and press the @key{RET} key:	input. Type a number and press the @key{RET} key:
Line 3413 $400DBDA8 no.extensions	Line 3420 $400DBDA8 no.extensions
The exact text, other than the ``Undefined word'' may differ slightly on	The exact text, other than the ``Undefined word'' may differ slightly on
your system, but the effect is the same; when the text interpreter	your system, but the effect is the same; when the text interpreter
detects an error, it discards any remaining text on a line, resets	detects an error, it discards any remaining text on a line, resets
certain internal state and prints an error message. @xref{Error	certain internal state and prints an error message. For a detailed description of error messages see @ref{Error
messages} for a detailed description of error messages.	messages}.

The text interpreter waits for you to press carriage-return, and then	The text interpreter waits for you to press carriage-return, and then
processes your input line. Starting at the beginning of the line, it	processes your input line. Starting at the beginning of the line, it
Line 4062 If you have tried out the examples in th	Line 4069 If you have tried out the examples in th
have typed them in by hand; when you leave Gforth, your definitions will	have typed them in by hand; when you leave Gforth, your definitions will
be lost. You can avoid this by using a text editor to enter Forth source	be lost. You can avoid this by using a text editor to enter Forth source
code into a file, and then loading code from the file using	code into a file, and then loading code from the file using
@code{include} (@xref{Forth source files}). A Forth source file is	@code{include} (@pxref{Forth source files}). A Forth source file is
processed by the text interpreter, just as though you had typed it in by	processed by the text interpreter, just as though you had typed it in by
hand@footnote{Actually, there are some subtle differences -- see	hand@footnote{Actually, there are some subtle differences -- see
@ref{The Text Interpreter}.}.	@ref{The Text Interpreter}.}.

Gforth also supports the traditional Forth alternative to using text	Gforth also supports the traditional Forth alternative to using text
files for program entry (@xref{Blocks}).	files for program entry (@pxref{Blocks}).

In common with many, if not most, Forth compilers, most of Gforth is	In common with many, if not most, Forth compilers, most of Gforth is
actually written in Forth. All of the @file{.fs} files in the	actually written in Forth. All of the @file{.fs} files in the
Line 4081 the text interpreter. This file is prese	Line 4088 the text interpreter. This file is prese
used to provide a command-line recall facility. If you enter long	used to provide a command-line recall facility. If you enter long
definitions by hand, you can use a text editor to paste them out of the	definitions by hand, you can use a text editor to paste them out of the
history file into a Forth source file for reuse at a later time	history file into a Forth source file for reuse at a later time
(@pxref{Command-line editing} for more information).	(for more information @pxref{Command-line editing}).


@comment ----------------------------------------------	@comment ----------------------------------------------
Line 4423 former, @pxref{Mixed precision}).	Line 4430 former, @pxref{Mixed precision}).

By default, numbers in Forth are single-precision integers that are 1	By default, numbers in Forth are single-precision integers that are 1
cell in size. They can be signed or unsigned, depending upon how you	cell in size. They can be signed or unsigned, depending upon how you
treat them. @xref{Number Conversion} for the rules used by the text	treat them. For the rules used by the text interpreter for recognising
interpreter for recognising single-precision integers.	single-precision integers see @ref{Number Conversion}.


doc-+	doc-+
Line 4464 doc-d2/	Line 4471 doc-d2/
@subsection Double precision	@subsection Double precision
@cindex double precision arithmetic words	@cindex double precision arithmetic words

@xref{Number Conversion} for the rules used by the text interpreter for	For the rules used by the text interpreter for
recognising double-precision integers.	recognising double-precision integers, see @ref{Number Conversion}.

A double precision number is represented by a cell pair, with the most	A double precision number is represented by a cell pair, with the most
significant cell at the TOS. It is trivial to convert an unsigned	significant cell at the TOS. It is trivial to convert an unsigned
Line 4559 doc-sm/rem	Line 4566 doc-sm/rem
@subsection Floating Point	@subsection Floating Point
@cindex floating point arithmetic words	@cindex floating point arithmetic words

@xref{Number Conversion} for the rules used by the text interpreter for	For the rules used by the text interpreter for
recognising floating-point numbers.	recognising floating-point numbers see @ref{Number Conversion}.

Gforth has a separate floating point	Gforth has a separate floating point
stack, but the documentation uses the unified notation.	stack, but the documentation uses the unified notation.
Line 5086 doc-address-unit-bits	Line 5093 doc-address-unit-bits
@cindex memory block words	@cindex memory block words
@cindex character strings - moving and copying	@cindex character strings - moving and copying

Memory blocks often represent character strings; @xref{String Formats}	Memory blocks often represent character strings; For ways of storing
for ways of storing character strings in memory. @xref{Displaying	character strings in memory see @ref{String Formats}. For other
characters and strings} for other string-processing words.	string-processing words see @ref{Displaying characters and strings}.

Some of these words work on address units. Others work on character	Some of these words work on address units. Others work on character
units (increments of @code{CHAR}), and expect a @code{CHAR}-aligned	units (increments of @code{CHAR}), and expect a @code{CHAR}-aligned
Line 5821 \ the 4th character	Line 5828 \ the 4th character
@end example	@end example

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


@node Variables, Constants, CREATE, Defining Words	@node Variables, Constants, CREATE, Defining Words
Line 5896 not in a Standard, portable way. It's sa	Line 5904 not in a Standard, portable way. It's sa
on).} so it's not necessary to supply the address -- it is more	on).} so it's not necessary to supply the address -- it is more
efficient to return the value of the constant directly. That's exactly	efficient to return the value of the constant directly. That's exactly
what happens; the run-time effect of a constant is to put its value on	what happens; the run-time effect of a constant is to put its value on
the top of the stack (@ref{User-defined Defining Words} describes one	the top of the stack (You can find one
way of implementing @code{Constant}).	way of implementing @code{Constant} in @ref{User-defined Defining Words}).

Gforth also provides @code{2Constant} and @code{fconstant} for defining	Gforth also provides @code{2Constant} and @code{fconstant} for defining
double and floating-point constants, respectively.	double and floating-point constants, respectively.
Line 5942 can force Gforth to in-line a constant l	Line 5950 can force Gforth to in-line a constant l

If you use @code{see} to decompile @i{this} version of	If you use @code{see} to decompile @i{this} version of
@code{FEET-TO-INCHES}, you can see that @code{INCHES-PER-FOOT} is no	@code{FEET-TO-INCHES}, you can see that @code{INCHES-PER-FOOT} is no
longer present. @xref{Interpret/Compile states} and @ref{Literals} on	longer present. To understand how this works, read
how this works.	@ref{Interpret/Compile states}, and @ref{Literals}.

In-lining constants in this way might improve execution time	In-lining constants in this way might improve execution time
fractionally, and can ensure that a constant is now only referenced at	fractionally, and can ensure that a constant is now only referenced at
Line 5996 doc-to	Line 6004 doc-to
Creates a word called @code{name} that, upon execution, executes	Creates a word called @code{name} that, upon execution, executes
@code{word1 word2 word3}. @code{name} is a @dfn{(colon) definition}.	@code{word1 word2 word3}. @code{name} is a @dfn{(colon) definition}.

The explanation above is somewhat superficial. @xref{Your first	The explanation above is somewhat superficial. For simple examples of
definition} for simple examples of colon definitions, then	colon definitions see @ref{Your first definition}. For an in-depth
@xref{Interpretation and Compilation Semantics} for an in-depth	discussion of some of the issues involved, see @xref{Interpretation and
discussion of some of the issues involved.	Compilation Semantics}.

doc-:	doc-:
doc-;	doc-;
Line 6437 executed. If you want to specify the na	Line 6445 executed. If you want to specify the na
@end example	@end example

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

@example	@example
Line 6991 If an error occurs, the input source is	Line 6999 If an error occurs, the input source is
device.	device.
@end itemize	@end itemize

@ref{Input Sources} describes this in more detail.	You can read about this in more detail in @ref{Input Sources}.


doc->in	doc->in
doc-source	doc-source
Line 7176 conversion to floating-point numbers whi	Line 7183 conversion to floating-point numbers whi
@code{base} is not 10 is an ambiguous condition.	@code{base} is not 10 is an ambiguous condition.
@end itemize	@end itemize

@ref{Input} describes words that you can use to read numbers into your	You can read numbers into your programs with the words described in
programs.	@ref{Input}.

@node Interpret/Compile states, Literals, Number Conversion, The Text Interpreter	@node Interpret/Compile states, Literals, Number Conversion, The Text Interpreter
@subsection Interpret/Compile states	@subsection Interpret/Compile states
Line 7191 starts interpreting. When @code{]} is ex	Line 7198 starts interpreting. When @code{]} is ex
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 for switching into	compiling. The most common usage for these words is for switching into
interpret state and back from within a colon definition; this technique	interpret state and back from within a colon definition; this technique
can be used to compile a literal (@pxref{Literals} for an example) or	can be used to compile a literal (for an example, @pxref{Literals}) or
for conditional compilation (@pxref{Interpreter Directives} for an	for conditional compilation (for an example, @pxref{Interpreter
example).	Directives}).


@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.
Line 8043 Three important things to remember about	Line 8050 Three important things to remember about
@itemize @bullet	@itemize @bullet
@item	@item
It always operates on double-precision numbers; to display a	It always operates on double-precision numbers; to display a
single-precision number, convert it first (@pxref{Double precision} for	single-precision number, convert it first (for ways of doing this
ways of doing this).	@pxref{Double precision}).
@item	@item
It always treats the double-precision number as though it were	It always treats the double-precision number as though it were
unsigned. The examples below show ways of printing signed numbers.	unsigned. The examples below show ways of printing signed numbers.
Line 8166 remains useful as a way of storing strin	Line 8173 remains useful as a way of storing strin
doc-count	doc-count


@xref{Memory Blocks} for words that move, copy and search	For words that move, copy and search for strings see @ref{Memory
for strings. @xref{Displaying characters and strings,} for words that	Blocks}. For words that display characters and strings see
display characters and strings.	@ref{Displaying characters and strings}.


@node Displaying characters and strings, Input, String Formats, Other I/O	@node Displaying characters and strings, Input, String Formats, Other I/O
@subsection Displaying characters and strings	@subsection Displaying characters and strings
Line 8272 definition of @code{my-char}.	Line 8278 definition of @code{my-char}.
@cindex I/O - see input	@cindex I/O - see input
@cindex parsing a string	@cindex parsing a string

@xref{String Formats} for ways of storing character strings in memory.	For ways of storing character strings in memory see @ref{String Formats}.

@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
Line 8975 write the items in the order you want.	Line 8981 write the items in the order you want.
This seems a little far-fetched and eliminating stack manipulations is	This seems a little far-fetched and eliminating stack manipulations is
unlikely to become a conscious programming objective. Still, the number	unlikely to become a conscious programming objective. Still, the number
of stack manipulations will be reduced dramatically if local variables	of stack manipulations will be reduced dramatically if local variables
are used liberally (e.g., compare @code{max} in @ref{Gforth locals} with	are used liberally (e.g., compare @code{max} (@pxref{Gforth locals}) with
a traditional implementation of @code{max}).	a traditional implementation of @code{max}).

This shows one potential benefit of locals: making Forth programs more	This shows one potential benefit of locals: making Forth programs more
Line 9208 The whole definition must be in one line	Line 9214 The whole definition must be in one line
@end itemize	@end itemize

Locals defined in this way behave like @code{VALUE}s	Locals defined in this way behave like @code{VALUE}s
(@xref{Values}). I.e., they are initialized from the stack. Using their	(@pxref{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 9739 a separate package for achieving this.	Line 9745 a separate package for achieving this.

@item	@item
It is layered; you don't have to learn and use all features to use this	It is layered; you don't have to learn and use all features to use this
model. Only a few features are necessary (@xref{Basic Objects Usage},	model. Only a few features are necessary (@pxref{Basic Objects Usage},
@xref{The Objects base class}, @xref{Creating objects}.), the others	@pxref{The Objects base class}, @pxref{Creating objects}.), the others
are optional and independent of each other.	are optional and independent of each other.

@item	@item

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

Removed from v.1.48
changed lines
	Added in v.1.49