[BACK]Return to gforth.texi CVS log [TXT] [DIR] Up to [gforth] / gforth

Diff for /gforth/Attic/gforth.texi between versions 1.3 and 1.7

version 1.3, 1994/06/17 12:35:02 version 1.7, 1994/09/05 17:36:19
Line 106  for introductory material. Line 106  for introductory material.
 @comment node-name,     next,           previous, up  @comment node-name,     next,           previous, up
 @chapter Goals of GNU Forth  @chapter Goals of GNU Forth
 @cindex Goals  @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  @node Other Books, Invocation, Goals, Top
 @chapter Other books on ANS Forth  @chapter Other books on ANS Forth
Line 118  deviations of the book. Line 157  deviations of the book.
   
 There is, of course, the standard, the definite reference if you want to  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  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  Global Engineering Documents !! somtime in spring or summer 1994. If you
 dpANS6 (the draft that was approved as standard) by aftp from  are lucky, you can still get dpANS6 (the draft that was approved as
 ftp.uu.net:/vendor/minerva/x3j14.  standard) by aftp from ftp.uu.net:/vendor/minerva/x3j14.
   
 @cite{Forth: The new model} by Jack Woehr (!! Publisher) is an introductory  @cite{Forth: The new model} by Jack Woehr (!! Publisher) is an
 book based on a draft version of the standard. It does not cover the  introductory book based on a draft version of the standard. It does not
 whole standard. It also contains interesting background information  cover the whole standard. It also contains interesting background
 (Jack Woehr was in the ANS Forth Technical Committe).  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  @node Invocation, Words, Other Books, Top
 @chapter Invocation  @chapter Invocation
   
 You will usually just say @code{gforth}. More generally, the default GNU  You will usually just say @code{gforth}. In many other cases the default
 Forth image can be invoked like this  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  @example
 gforth [--batch] [files] [-e forth-code]  gforth [initialization options] [image-specific options]
 @end example  @end example
   
 The @code{--batch} option makes @code{gforth} exit after processing the  The initialization options must come before the rest of the command
 command line. Also, the startup message is suppressed. @file{files} are  line. They are:
 Forth source files that are executed in the order in which they  
 appear. The @code{-e @samp{forth-code}} or @code{--evaluate  @table @code
 @samp{forth-code}} option evaluates the forth code; it can be freely  @item --image-file @samp{file}
 mixed with the files. This option takes only one argument; if you want  Loads the Forth image @samp{file} instead of the default
 to evaluate more Forth words, you have to quote them or use several  @file{gforth.fi}.
 @code{-e}s. !! option for suppressing default loading.  
   @item --path @samp{path}
 You can use the command line option @code{-i @samp{file}} or  Uses @samp{path} for searching the image file and Forth source code
 @code{--image-file @samp{file}} to specify a different image file. Note  files instead of the default in the environment variable
 that this option must be the first in the command line. The rest of the  @code{GFORTHPATH} or the path specified at installation time (typically
 command line is processed by the image file.  @file{/usr/local/lib/gforth:.}). A path is given as a @code{:}-separated
   list.
 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  @item --dictionary-size @samp{size}
 variable @code{GFORTHPATH}; if this does not exist, in  @item -m @samp{size}
 @file{/usr/local/lib/gforth} and in @file{/usr/lib/gforth}.  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  @node Words,  , Invocation, Top
 @chapter Forth Words  @chapter Forth Words
Line 223  The name of a stack item corresponds in Line 319  The name of a stack item corresponds in
 @item name starts with  @item name starts with
 Type  Type
 @item f  @item f
 Bool, i.e. false (0) or true (-1).  Bool, i.e. @code{false} or @code{true}.
 @item c  @item c
 Char  Char
 @item w  @item w
Line 318  variables. Note that while every sane Fo Line 414  variables. Note that while every sane Fo
 point stack, this is not strictly required; an ANS Forth system could  point stack, this is not strictly required; an ANS Forth system could
 theoretically keep floating point numbers on the data stack. As an  theoretically keep floating point numbers on the data stack. As an
 additional difficulty, you don't know how many cells a floating point  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  they work also for a unified stack model, but we do not recommend trying
 it. Also, a Forth system is allowed to keep the local variables on the  it. Also, a Forth system is allowed to keep the local variables on the
 return stack. This is reasonable, as local variables usually eliminate  return stack. This is reasonable, as local variables usually eliminate
 the need to use the return stack explicitely. So, if you want to produce  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  a standard complying program and if you are using local variables in a
 word, forget about return stack manipulations in that word (see the  word, forget about return stack manipulations in that word (see the
 standard document for the exact rules).  standard document for the exact rules).
Line 363  r@ Line 459  r@
 rdrop  rdrop
 2>r  2>r
 2r>  2r>
   2r@
   2rdrop
   
 @subsection Locals stack  @subsection Locals stack
   
Line 397  df! Line 495  df!
 @subsection Memory block access  @subsection Memory block access
   
 move  move
 fill  
 blanks  
 erase  erase
   
   While the previous words work on address units, the rest works on
   characters.
   
   cmove
   cmove>
   fill
   blank
   
 @node Control Structures  @node Control Structures
 @section Control Structures  @section Control Structures
   
Line 437  system that only supplies @code{THEN} is Line 541  system that only supplies @code{THEN} is
 : endif   POSTPONE then ; immediate  : endif   POSTPONE then ; immediate
 @end example  @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}.  can avoid using @code{?dup}.
   
 @example  @example
Line 550  The loop is terminated when the border b Line 663  The loop is terminated when the border b
 @var{limit} is crossed. However, @code{S+LOOP} is not part of the ANS  @var{limit} is crossed. However, @code{S+LOOP} is not part of the ANS
 Forth standard.  Forth standard.
   
 The @code{?DO} can be replaced by @code{DO}. @code{DO} enters the loop  @code{?DO} can be replaced by @code{DO}. @code{DO} enters the loop even
 even when the start and the limit value are equal. We do not recommend  when the start and the limit value are equal. We do not recommend using
 using @code{DO}. It will just give you maintenance troubles.  @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  @contents
 @bye  @bye
Removed from v.1.3  
changed lines
  Added in v.1.7

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>