version 1.38, 1996/10/01 16:25:58
|
version 1.41, 1997/01/04 16:32:29
|
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 854 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 1509 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 1568 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 1621 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 2079 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 2089 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, |
Line 2148 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 2422 doc-postpone,
|
Line 2423 doc-postpone,
|
|
|
At present, the @var{w} part of a compilation token is an execution |
At present, the @var{w} part of a compilation token is an execution |
token, and the @var{xt} part represents either @code{execute} or |
token, and the @var{xt} part represents either @code{execute} or |
@code{compile,}. However, don't rely on that kowledge, unless necessary; |
@code{compile,}. However, don't rely on that knowledge, unless necessary; |
we may introduce unusual compilation tokens in the future (e.g., |
we may introduce unusual compilation tokens in the future (e.g., |
compilation tokens representing the compilation semantics of literals). |
compilation tokens representing the compilation semantics of literals). |
|
|
Line 2463 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 2552 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 2648 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 2988 find what they search. Note that it is p
|
Line 3040 find what they search. Note that it is p
|
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. |
Line 3001 closed file may lead to unpredictable re
|
Line 3053 closed file may lead to unpredictable re
|
THROW}. |
THROW}. |
|
|
In the future, Gforth may be able to restore 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 3238 strange number; e.g., @code{-1000 THROW}
|
Line 3290 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 3262 other single-tasking systems, it should
|
Line 3314 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 3311 System dependent. Gforth just uses the f
|
Line 3363 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 3960 lies in the body (which is illegal in th
|
Line 4012 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 4154 comply to some restrictions: addresses h
|
Line 4206 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 4287 with their continuous feedback. Lennart
|
Line 4339 with their continuous feedback. Lennart
|
@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, Marcel Hendrix, John |
Kleinrubatscher, Christian Pirker, Dirk Zoller, Marcel Hendrix, John |
Wavrik, Stott Bolton and Marc de Groot. |
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 4316 A team led by Bill Ragsdale implemented
|
Line 4368 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. |
|
|