--- gforth/Attic/gforth.texi 1994/05/07 14:55:54 1.1 +++ gforth/Attic/gforth.texi 1994/09/05 17:36:19 1.7 @@ -106,7 +106,46 @@ for introductory material. @comment node-name, next, previous, up @chapter Goals of GNU Forth @cindex Goals -!! Insert Goals here +The goal of the GNU Forth Project is to develop a standard model for +ANSI Forth. This can be split into several subgoals: + +@itemize @bullet +@item +GNU Forth should conform to the ANSI Forth standard. +@item +It should be a model, i.e. it should define all the +implementation-dependent things. +@item +It should become standard, i.e. widely accepted and used. This goal +is the most difficult one. +@end itemize + +To achieve these goals GNU Forth should be +@itemize @bullet +@item +Similar to previous models (fig-Forth, F83) +@item +Powerful. It should provide for all the things that are considered +necessary today and even some that are not yet considered necessary. +@item +Efficient. It should not get the reputation of being exceptionally +slow. +@item +Free. +@item +Available on many machines/easy to port. +@end itemize + +Have we achieved these goals? GNU Forth conforms to the ANS Forth +standard; it may be considered a model, but we have not yet documented +which parts of the model are stable and which parts we are likely to +change; it certainly has not yet become a de facto standard. It has some +similarities and some differences to previous models; It has some +powerful features, but not yet everything that we envisioned; on RISCs +it is as fast as interpreters programmed in assembly, on +register-starved machines it is not so fast, but still faster than any +other C-based interpretive implementation; it is free and available on +many machines. @node Other Books, Invocation, Goals, Top @chapter Other books on ANS Forth @@ -118,43 +157,100 @@ deviations of the book. There is, of course, the standard, the definite reference if you want to write ANS Forth programs. It will be available in printed form from -!! somtime in spring or summer 1994. If you are lucky, you can still get -dpANS6 (the draft that was approved as standard) by aftp from -ftp.uu.net:/vendor/minerva/x3j14. - -@cite{Forth: The new model} by Jack Woehr (!! Publisher) 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). +Global Engineering Documents !! somtime in spring or summer 1994. If you +are lucky, you can still get dpANS6 (the draft that was approved as +standard) by aftp from ftp.uu.net:/vendor/minerva/x3j14. + +@cite{Forth: The new model} by Jack Woehr (!! Publisher) 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 +not appropriate for complete newbies, but programmers experienced in +other languages should find it ok. @node Invocation, Words, Other Books, Top @chapter Invocation -You will usually just say @code{gforth}. More generally, the default GNU -Forth image can be invoked like this +You will usually just say @code{gforth}. In many other cases the default +GNU Forth image will be invoked like this: + +@example +gforth [files] [-e forth-code] +@end example + +executing the contents of the files and the Forth code in the order they +are given. + +In general, the command line looks like this: @example -gforth [--batch] [files] [-e forth-code] +gforth [initialization options] [image-specific options] @end example -The @code{--batch} option makes @code{gforth} exit after processing the -command line. Also, the startup message is suppressed. @file{files} are -Forth source files that are executed in the order in which they -appear. The @code{-e @samp{forth-code}} or @code{--evaluate -@samp{forth-code}} option evaluates the forth code; it can be freely -mixed with the files. This option takes only one argument; if you want -to evaluate more Forth words, you have to quote them or use several -@code{-e}s. !! option for suppressing default loading. - -You can use the command line option @code{-i @samp{file}} or -@code{--image-file @samp{file}} to specify a different image file. Note -that this option must be the first in the command line. The rest of the -command line is processed by the image file. - -If the @code{--image-file} option is not used, GNU Forth searches for a -file named @file{gforth.fi} in the path specified by the environment -variable @code{GFORTHPATH}; if this does not exist, in -@file{/usr/local/lib/gforth} and in @file{/usr/lib/gforth}. +The initialization options must come before the rest of the command +line. They are: + +@table @code +@item --image-file @samp{file} +Loads the Forth image @samp{file} instead of the default +@file{gforth.fi}. + +@item --path @samp{path} +Uses @samp{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. + +@item --dictionary-size @samp{size} +@item -m @samp{size} +Allocate @samp{size} space for the Forth dictionary space instead of +using the default specified in the image (typically 256K). The +@samp{size} specification consists of an integer and a unit (e.g., +@code{4M}). The unit can be one of @code{b} (bytes), @code{e} (element +size, in this case Cells), @code{k} (kilobytes), and @code{M} +(Megabytes). If no unit is specified, @code{e} is used. + +@item --data-stack-size @samp{size} +@item -d @samp{size} +Allocate @samp{size} space for the data stack instead of using the +default specified in the image (typically 16K). + +@item --return-stack-size @samp{size} +@item -r @samp{size} +Allocate @samp{size} space for the return stack instead of using the +default specified in the image (typically 16K). + +@item --fp-stack-size @samp{size} +@item -f @samp{size} +Allocate @samp{size} space for the floating point stack instead of +using the default specified in the image (typically 16K). In this case +the unit specifier @code{e} refers to floating point numbers. + +@item --locals-stack-size @samp{size} +@item -l @samp{size} +Allocate @samp{size} space for the locals stack instead of using the +default specified in the image (typically 16K). + +@end table + +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 @samp{forth-code}} options that are interpreted in the seqence +in which they are given. The @code{-e @samp{forth-code}} or +@code{--evaluate @samp{forth-code}} option evaluates the forth +code. This option takes only one argument; if you want to evaluate more +Forth words, you have to quote them or use several @code{-e}s. To exit +after processing the command line (instead of entering interactive mode) +append @code{-e bye} to the command line. + +Not yet implemented: +On startup the system first executes the system initialization file +(unless the option @code{--no-init-file} is given; note that the system +resulting from using this option may not be ANS Forth conformant). Then +the user initialization file @file{.gforth.fs} is executed, unless the +option @code{--no-rc} is given; this file is first searched in @file{.}, +then in @file{~}, then in the path given by the normal path (see below). @node Words, , Invocation, Top @chapter Forth Words @@ -177,7 +273,7 @@ variable @code{GFORTHPATH}; if this does @node Notation, Arithmetic, Words, Words @section Notation -The Forth words are describes in this section in the glossary notation +The Forth words are described in this section in the glossary notation that has become a de-facto standard for Forth texts, i.e. @quotation @@ -223,7 +319,7 @@ The name of a stack item corresponds in @item name starts with Type @item f -Bool, i.e. false (0) or true (-1). +Bool, i.e. @code{false} or @code{true}. @item c Char @item w @@ -318,16 +414,16 @@ variables. Note that while every sane Fo point stack, this is not strictly required; an ANS Forth system could theoretically keep floating point numbers on the data stack. As an additional difficulty, you don't know how many cells a floating point -numkber takes. It is reportedly possible to write words in a way that +number takes. It is reportedly possible to write words in a way that they work also for a unified stack model, but we do not recommend trying -it. Also, a Forth system to keep the local variables on the return -stack. This is reasonable, as local variables usually eliminate the need -to use the return stack explicitely. So, if you want to produce a -standard complying program and if you are using local variables in a +it. Also, a Forth system is allowed to keep the local variables on the +return stack. This is reasonable, as local variables usually eliminate +the need to use the return stack explicitly. So, if you want to produce +a standard complying program and if you are using local variables in a word, forget about return stack manipulations in that word (see the standard document for the exact rules). -@subsetion Data stack +@subsection Data stack drop nip dup @@ -363,6 +459,8 @@ r@ rdrop 2>r 2r> +2r@ +2rdrop @subsection Locals stack @@ -397,10 +495,16 @@ df! @subsection Memory block access move -fill -blanks erase +While the previous words work on address units, the rest works on +characters. + +cmove +cmove> +fill +blank + @node Control Structures @section Control Structures @@ -417,7 +521,7 @@ IF @var{code} ENDIF @end example - +or @example @var{flag} IF @@ -437,7 +541,16 @@ system that only supplies @code{THEN} is : endif POSTPONE then ; immediate @end example -We also provide the words @code{?dup-if} and @code{?dup-not-if}, so you +[According to @cite{Webster's New Encyclopedic Dictionary}, @dfn{then +(adv.)} has the following meanings: +@quotation +... 2b: following next after in order ... 3d: as a necessary consequence +(if you were there, then you saw them). +@end quotation +Forth's @code{THEN} has the meaning 2b, @code{THEN} in Pascal +and many other programming languages has the meaning 3d.] + +We also provide the words @code{?dup-if} and @code{?dup-0=-if}, so you can avoid using @code{?dup}. @example @@ -527,11 +640,13 @@ index by @var{n} instead of by 1. The lo between @var{limit-1} and @var{limit} is crossed. E.g.: 4 0 ?DO i . 2 +LOOP prints 0 2 + 4 1 ?DO i . 2 +LOOP prints 1 3 The behaviour of @code{@var{n} +LOOP} is peculiar when @var{n} is negative: -1 0 ?DO i . -1 +LOOP prints 0 -1 + 0 0 ?DO i . -1 +LOOP prints nothing Therefore we recommend avoiding using @code{@var{n} +LOOP} with negative @@ -539,18 +654,36 @@ Therefore we recommend avoiding using @c case behaves symmetrical to the positive case: -2 0 ?DO i . -1 +LOOP prints 0 -1 + -1 0 ?DO i . -1 +LOOP prints 0 + 0 0 ?DO i . -1 +LOOP prints nothing The loop is terminated when the border between @var{limit-sgn(n)} and @var{limit} is crossed. However, @code{S+LOOP} is not part of the ANS Forth standard. -The @code{?DO} can be replaced by @code{DO}. @code{DO} enters the loop -even when the start and the limit value are equal. We do not recommend -using @code{DO}. It will just give you maintenance troubles. +@code{?DO} can be replaced by @code{DO}. @code{DO} enters the loop even +when the start and the limit value are equal. We do not recommend using +@code{DO}. It will just give you maintenance troubles. + +@code{UNLOOP} is used to prepare for an abnormal loop exit, e.g., via +@code{EXIT}. @code{UNLOOP} removes the loop control parameters from the +return stack so @code{EXIT} can get to its return address. + +Another counted loop is +@example +@var{n} +FOR + @var{body} +NEXT +@end example +This is the preferred loop of native code compiler writers who are too +lazy to optimize @code{?DO} loops properly. In GNU Forth, this loop +iterates @var{n+1} times; @code{i} produces values starting with @var{n} +and ending with 0. Other Forth systems may differently, even if they +support @code{FOR} loops. -FOR NEXT UNLOOP @contents @bye