--- gforth/Attic/gforth.ds 1996/09/30 13:16:09 1.37 +++ 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 @@ -854,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, @@ -1509,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 @@ -1568,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 @@ -1621,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 @} @@ -2079,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 @@ -2089,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, @@ -2148,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> @@ -2414,9 +2415,15 @@ 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; +@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). @@ -2457,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. @@ -2546,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. @@ -2642,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 @@ -2982,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. @@ -2995,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: @@ -3073,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 @@ -3232,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 @@ -3256,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. @@ -3305,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. @@ -3404,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}. @@ -3954,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}). @@ -4148,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}). @@ -4207,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 @@ -4281,7 +4343,7 @@ with their continuous feedback. Lennart @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, 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, and autoconf, among others), and to the creators of the Internet: Gforth @@ -4310,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.