--- gforth/Attic/gforth.ds 1996/09/23 08:52:47 1.36 +++ gforth/Attic/gforth.ds 1997/01/14 16:30:50 1.42 @@ -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. @@ -566,7 +567,7 @@ versions can be found through @cite{Forth: The new model} by Jack Woehr (Prentice-Hall, 1993) is an introductory book based on a draft version of the standard. It does not cover the whole standard. It also contains interesting background -information (Jack Woehr was in the ANS Forth Technical Committe). It is +information (Jack Woehr was in the ANS Forth Technical Committee). It is not appropriate for complete newbies, but programmers experienced in other languages should find it ok. @@ -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} @@ -640,7 +641,7 @@ default specified in the image (typicall As explained above, the image-specific command-line arguments for the 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 @code{--evaluate @var{forth-code}} option evaluates the forth code. This option takes only one argument; if you want to evaluate more @@ -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:: @@ -853,7 +855,7 @@ doc-dmax The format of floating point numbers recognized by the outer (aka text) interpreter is: a signed decimal number, possibly containing a decimal 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} is not interpreted as floating-point number, but as double (if the number contains a @code{.}) or single precision integer. Also, @@ -1508,7 +1510,7 @@ Gforth currently supports cells (@code{W 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.) 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: @example @@ -1567,7 +1569,7 @@ definition? Which local is meant, if the two independent control flow paths? 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. In order to implement this rule, the compiler has to know which places @@ -1620,7 +1622,7 @@ are entered only through the @code{BEGIN @code{BEGIN}...@code{UNTIL} loops and it is implemented in our compiler. When the branch to the @code{BEGIN} is finally generated by @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 IF @{ x @} @@ -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 @@ -2078,9 +2080,9 @@ you see similar colon definitions, you c @code{CREATE..DOES>}. E.g., an assembler usually defines several words that look very similar: @example -: ori, ( reg-taget reg-source n -- ) +: ori, ( reg-target reg-source n -- ) 0 asm-reg-reg-imm ; -: andi, ( reg-taget reg-source n -- ) +: andi, ( reg-target reg-source n -- ) 1 asm-reg-reg-imm ; @end example @@ -2088,7 +2090,7 @@ This could be factored with: @example : reg-reg-imm ( op-code -- ) create , -DOES> ( reg-taget reg-source n -- ) +DOES> ( reg-target reg-source n -- ) @@ asm-reg-reg-imm ; 0 reg-reg-imm ori, @@ -2147,7 +2149,7 @@ CREATE name ( ... -- ... ) DOES> @var{code} ; @end example -This is equivalwent to the standard +This is equivalent to the standard @example :noname DOES> @@ -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 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, Tokens for Words, Words @section Wordlists @node Files, Blocks, Wordlists, Words @@ -2395,7 +2464,7 @@ are meant to support a different style o tracing/stepping debuggers used in languages with long turn-around 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 the output, see where things went wrong, add more printing code, etc., until the bug is found. @@ -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 @@ -2920,7 +3040,7 @@ find what they search. Note that it is p names with @code{nextname} (should it not?). @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>}: Compiles a recursive call to the defining word, not to the defined word. @@ -2933,10 +3053,10 @@ closed file may lead to unpredictable re THROW}. 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: -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. @item data space read/write with incorrect alignment: @@ -3011,20 +3131,23 @@ and you can give commands to Gforth inte available depend on how you invoke Gforth. @item program data space available: -@code{sp@@ here - .} gives the space remaining for dictionary and data -stack together. +@code{UNUSED .} gives the remaining dictionary space. The total +dictionary space can be specified with the @code{-m} switch +(@pxref{Invocation}) when Gforth starts up. @item return stack space available: -By default 16 KBytes. The default can be overridden with the @code{-r} -switch (@pxref{Invocation}) when Gforth starts up. +You can compute the total return stack space in cells with +@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: -@code{sp@@ here - .} gives the space remaining for dictionary and data -stack together. +You can compute the total data stack space in cells with +@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: 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 @@ -3145,7 +3268,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. @@ -3170,7 +3293,7 @@ strange number; e.g., @code{-1000 THROW} @table @i @item encoding of keyboard events (@code{EKEY}): -Not yet implemeted. +Not yet implemented. @item duration of a system clock tick System dependent. With respect to @code{MS}, the time is specified in @@ -3194,7 +3317,7 @@ other single-tasking systems, it should @table @i @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 simply nothing happen. @@ -3243,7 +3366,7 @@ System dependent. Gforth just uses the f @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 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: All files that are left via the exception are closed. @@ -3262,9 +3385,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 @@ -3343,8 +3465,9 @@ nearest, and break ties by rounding to e bit of the mantissa is 0). @item size of floating-point stack: -@code{s" FLOATING-STACK" environment? drop .}. Can be changed at startup -with the command-line option @code{-f}. +@code{s" FLOATING-STACK" environment? drop .} gives the total size of +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: @code{1 floats}. @@ -3360,11 +3483,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 +3635,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 +3672,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 @@ -3892,7 +4016,7 @@ lies in the body (which is illegal in th making the code field larger for all words this solution becomes legal 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 -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 for direct and indirect threaded systems (@pxref{System Architecture}). @@ -4086,7 +4210,7 @@ comply to some restrictions: addresses h special words (@code{A!}, @code{A,}, etc.) in order to make the code relocatable. Cells, floats, etc., have to be stored at the natural 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 machines with stricter alignment. The image file is produced by a metacompiler (@file{cross.fs}). @@ -4145,8 +4269,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 +4342,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 @@ -4247,7 +4372,7 @@ A team led by Bill Ragsdale implemented implementation of fig-Forth for the 6502 based on microForth. 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 Z80.