--- gforth/Attic/gforth.ds 1996/09/23 08:52:47 1.36 +++ gforth/Attic/gforth.ds 1996/11/11 16:59:16 1.40 @@ -86,6 +86,7 @@ personal machines. This manual correspon * Other Books:: Things you might want to read * Invocation:: Starting Gforth * Words:: Forth words available in Gforth +* Tools:: Programming tools * ANS conformance:: Implementation-defined options etc. * Model:: The abstract machine of Gforth * Integrating Gforth:: Forth as scripting language for applications. @@ -600,11 +601,11 @@ Loads the Forth image @var{file} instead @item --path @var{path} @item -p @var{path} -Uses @var{path} for searching the image file and Forth source code -files instead of the default in the environment variable -@code{GFORTHPATH} or the path specified at installation time (typically -@file{/usr/local/lib/gforth:.}). A path is given as a @code{:}-separated -list. +Uses @var{path} for searching the image file and Forth source code files +instead of the default in the environment variable @code{GFORTHPATH} or +the path specified at installation time (e.g., +@file{/usr/local/share/gforth/0.2.0:.}). A path is given as a list of +directories, separated by @samp{:} (on Unix) or @samp{;} (on other OSs). @item --dictionary-size @var{size} @item -m @var{size} @@ -662,7 +663,7 @@ the user initialization file @file{.gfor option @code{--no-rc} is given; this file is first searched in @file{.}, then in @file{~}, then in the normal path (see above). -@node Words, ANS conformance, Invocation, Top +@node Words, Tools, Invocation, Top @chapter Forth Words @menu @@ -673,6 +674,7 @@ then in @file{~}, then in the normal pat * Control Structures:: * Locals:: * Defining Words:: +* Tokens for Words:: * Wordlists:: * Files:: * Blocks:: @@ -1962,7 +1964,7 @@ programs harder to read, and easier to m merit of this syntax is that it is easy to implement using the ANS Forth locals wordset. -@node Defining Words, Wordlists, Locals, Words +@node Defining Words, Tokens for Words, Locals, Words @section Defining Words @menu @@ -2367,7 +2369,74 @@ accessing the header structure usually k @code{' word >body} also gives you the body of a word created with @code{create-interpret/compile}. -@node Wordlists, Files, Defining Words, Words +@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 kowledge, 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, Tokens for Words, Words @section Wordlists @node Files, Blocks, Wordlists, Words @@ -2484,7 +2553,7 @@ probably more appropriate than an assert Gforth provides some words for defining primitives (words written in machine code), and for defining the the machine-code equivalent of @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 worse is that the register allocation not only depends on the processor, but also on the @code{gcc} version and options used. @@ -2580,7 +2649,58 @@ with @code{>DOES-CODE}. If the word was returned is different from 0 and identifies the @code{DOES>} used by the 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 To the best of our knowledge, Gforth is an @@ -3145,7 +3265,7 @@ The least significant cell of @var{d} is The codes -256@minus{}-511 are used for reporting signals (see @file{errore.fs}). The codes -512@minus{}-2047 are used for OS errors (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 strange number; e.g., @code{-1000 THROW} results in @code{Unknown error 488} on my system. @@ -3262,9 +3382,8 @@ of open files available. This should not @code{/line}. Currently 255. @item methods of mapping block ranges to files: -Currently, the block words automatically access the file -@file{blocks.fb} in the currend working directory. More sophisticated -methods could be implemented if there is demand (and a volunteer). +By default, blocks are accessed in the file @file{blocks.fb} in the +current working directory. The file can be switched with @code{USE}. @item number of string buffers provided by @code{S"}: 1 @@ -3360,11 +3479,11 @@ with the command-line option @code{-f}. @table @i @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. @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. @item Floating-point result out of range: @@ -3512,14 +3631,15 @@ intended as throw codes. They typically @table @i @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}: -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}: -Not implemented (yet). If they were implemented, they would use the -search order wordset. +The ANS Forth search order word set. @item source and format of display by @code{SEE}: The source for @code{see} is the intermediate code used by the inner @@ -3548,9 +3668,9 @@ unlucky, this ambiguous condition is not Not implemented (yet). @item @var{name} not defined via @code{CREATE}: -@code{;code} is not implemented (yet). If it were, it would behave like -@code{DOES>} in this respect, i.e., change the execution semantics of -the last defined word no matter how it was defined. +@code{;code} behaves like @code{DOES>} in this respect, i.e., it changes +the execution semantics of the last defined word no matter how it was +defined. @item @code{POSTPONE} applied to @code{[IF]}: After defining @code{: X POSTPONE [IF] ; IMMEDIATE}. @code{X} is @@ -4145,8 +4265,8 @@ relative Win32- NT eforth 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 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 -fib 1.00 1.52 1.34 1.22 1.13 1.74 2.99 4.30 +matmul 1.00 1.47 1.35 1.46 0.74 1.58 4.09 +fib 1.00 1.52 1.34 1.22 0.86 1.74 2.99 4.30 @end example You may find the good performance of Gforth compared with the systems @@ -4218,7 +4338,8 @@ one of Gforth's first users, in mid-1993 with their continuous feedback. Lennart Benshop contributed @file{glosgen.fs}, while Stuart Ramsden has been working on automatic 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, and autoconf, among others), and to the creators of the Internet: Gforth