Diff for /gforth/Attic/gforth.ds between versions 1.17 and 1.19

version 1.17, 1995/09/15 14:52:51 version 1.19, 1995/10/16 18:33:08
Line 157  not written for ANS Forth, as you will n Line 157  not written for ANS Forth, as you will n
 deviations of the book.  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 is available in printed form from the
 Global Engineering Documents !! somtime in spring or summer 1994. If you  National Standards Institute Sales Department (Tel.: USA (212) 642-4900;
 are lucky, you can still get dpANS6 (the draft that was approved as  Fax.: USA (212) 302-1286) as document @cite{X3.215-1994} for about $200. You
 standard) by aftp from ftp.uu.net:/vendor/minerva/x3j14.  can also get it from Global Engineering Documents (Tel.: USA (800)
   854-7179; Fax.: (303) 843-9880) for about $300.
   
   @cite{dpANS6}, the last draft of the standard, which was then submitted to ANSI
   for publication is available electronically and for free in some MS Word
   format, and it has been converted to HTML. Some pointers to these
   versions can be found through
   http://www.complang.tuwien.ac.at/projects/forth.html.
   
 @cite{Forth: The new model} by Jack Woehr (!! Publisher) is an  @cite{Forth: The new model} by Jack Woehr (!! Publisher) is an
 introductory book based on a draft version of the standard. It does not  introductory book based on a draft version of the standard. It does not
Line 269  then in @file{~}, then in the normal pat Line 276  then in @file{~}, then in the normal pat
 * Blocks::                        * Blocks::                      
 * Other I/O::                     * Other I/O::                   
 * Programming Tools::             * Programming Tools::           
   * Assembler and Code words::    
 * Threading Words::               * Threading Words::             
 @end menu  @end menu
   
Line 300  effect}, but in @var{Description}. The n Line 308  effect}, but in @var{Description}. The n
 the type and/or the function of the item. See below for a discussion of  the type and/or the function of the item. See below for a discussion of
 the types.  the types.
   
   All words have two stack effects: A compile-time stack effect and a
   run-time stack effect. The compile-time stack-effect of most words is
   @var{ -- }. If the compile-time stack-effect of a word deviates from
   this standard behaviour, or the word does other unusual things at
   compile time, both stack effects are shown; otherwise only the run-time
   stack effect is shown.
   
 @item pronunciation  @item pronunciation
 How the word is pronounced  How the word is pronounced
   
Line 309  system need not support all of them. So, Line 324  system need not support all of them. So,
 uses the more portable it will be in theory. However, we suspect that  uses the more portable it will be in theory. However, we suspect that
 most ANS Forth systems on personal machines will feature all  most ANS Forth systems on personal machines will feature all
 wordsets. Words that are not defined in the ANS standard have  wordsets. Words that are not defined in the ANS standard have
 @code{gforth} as wordset.  @code{gforth} or @code{gforth-internal} as wordset. @code{gforth}
   describes words that will work in future releases of Gforth;
   @code{gforth-internal} words are more volatile. Environmental query
   strings are also displayed like words; you can recognize them by the
   @code{environment} in the wordset field.
   
 @item Description  @item Description
 A description of the behaviour of the word.  A description of the behaviour of the word.
Line 808  There are several variations on the coun Line 827  There are several variations on the coun
   
 @code{LEAVE} leaves the innermost counted loop immediately.  @code{LEAVE} leaves the innermost counted loop immediately.
   
   If @var{start} is greater than @var{limit}, a @code{?DO} loop is entered
   (and @code{LOOP} iterates until they become equal by wrap-around
   arithmetic). This behaviour is usually not what you want. Therefore,
   Gforth offers @code{+DO} and @code{U+DO} (as replacements for
   @code{?DO}), which do not enter the loop if @var{start} is greater than
   @var{limit}; @code{+DO} is for signed loop parameters, @code{U+DO} for
   unsigned loop parameters. These words can be implemented easily on
   standard systems, so using them does not make your programs hard to
   port; e.g.:
   @example
   : +DO ( compile-time: -- do-sys; run-time: n1 n2 -- )
       POSTPONE over POSTPONE min POSTPONE ?DO ; immediate
   @end example
   
 @code{LOOP} can be replaced with @code{@var{n} +LOOP}; this updates the  @code{LOOP} can be replaced with @code{@var{n} +LOOP}; this updates the
 index by @var{n} instead of by 1. The loop is terminated when the border  index by @var{n} instead of by 1. The loop is terminated when the border
 between @var{limit-1} and @var{limit} is crossed. E.g.:  between @var{limit-1} and @var{limit} is crossed. E.g.:
   
 @code{4 0 ?DO  i .  2 +LOOP}   prints @code{0 2}  @code{4 0 +DO  i .  2 +LOOP}   prints @code{0 2}
   
 @code{4 1 ?DO  i .  2 +LOOP}   prints @code{1 3}  @code{4 1 +DO  i .  2 +LOOP}   prints @code{1 3}
   
 The behaviour of @code{@var{n} +LOOP} is peculiar when @var{n} is negative:  The behaviour of @code{@var{n} +LOOP} is peculiar when @var{n} is negative:
   
Line 822  The behaviour of @code{@var{n} +LOOP} is Line 855  The behaviour of @code{@var{n} +LOOP} is
   
 @code{ 0 0 ?DO  i .  -1 +LOOP}  prints nothing  @code{ 0 0 ?DO  i .  -1 +LOOP}  prints nothing
   
 Therefore we recommend avoiding using @code{@var{n} +LOOP} with negative  Therefore we recommend avoiding @code{@var{n} +LOOP} with negative
 @var{n}. One alternative is @code{@var{n} S+LOOP}, where the negative  @var{n}. One alternative is @code{@var{u} -LOOP}, which reduces the
 case behaves symmetrical to the positive case:  index by @var{u} each iteration. The loop is terminated when the border
   between @var{limit+1} and @var{limit} is crossed. Gforth also provides
   @code{-DO} and @code{U-DO} for down-counting loops. E.g.:
   
 @code{-2 0 ?DO  i .  -1 S+LOOP}  prints @code{0 -1}  @code{-2 0 -DO  i .  1 -LOOP}  prints @code{0 -1}
   
 @code{-1 0 ?DO  i .  -1 S+LOOP}  prints @code{0}  @code{-1 0 -DO  i .  1 -LOOP}  prints @code{0}
   
 @code{ 0 0 ?DO  i .  -1 S+LOOP}  prints nothing  @code{ 0 0 -DO  i .  1 -LOOP}  prints nothing
   
 The loop is terminated when the border between @var{limit@minus{}sgn(n)} and  Another alternative is @code{@var{n} S+LOOP}, where the negative
 @var{limit} is crossed. However, @code{S+LOOP} is not part of the ANS  case behaves symmetrical to the positive case:
 Forth standard.  
   @code{-2 0 -DO  i .  -1 S+LOOP}  prints @code{0 -1}
   
 @code{?DO} can be replaced by @code{DO}. @code{DO} enters the loop even  The loop is terminated when the border between @var{limit@minus{}sgn(n)}
 when the start and the limit value are equal. We do not recommend using  and @var{limit} is crossed. Unfortunately, neither @code{-LOOP} nor
 @code{DO}. It will just give you maintenance troubles.  @code{S+LOOP} are part of the ANS Forth standard, and they are not easy
   to implement using standard words. If you want to write standard
   programs, just avoid counting down.
   
   @code{?DO} can also be replaced by @code{DO}. @code{DO} always enters
   the loop, independent of the loop parameters. Do not use @code{DO}, even
   if you know that the loop is entered in any case. Such knowledge tends
   to become invalid during maintenance of a program, and then the
   @code{DO} will make trouble.
   
 @code{UNLOOP} is used to prepare for an abnormal loop exit, e.g., via  @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  @code{EXIT}. @code{UNLOOP} removes the loop control parameters from the
Line 894  doc-repeat Line 938  doc-repeat
 Counted loop words constitute a separate group of words:  Counted loop words constitute a separate group of words:
   
 doc-?do  doc-?do
   doc-+do
   doc-u+do
   doc--do
   doc-u-do
 doc-do  doc-do
 doc-for  doc-for
 doc-loop  doc-loop
 doc-s+loop  doc-s+loop
 doc-+loop  doc-+loop
   doc--loop
 doc-next  doc-next
 doc-leave  doc-leave
 doc-?leave  doc-?leave
Line 1526  locals wordset. Line 1575  locals wordset.
 @node Other I/O, Programming Tools, Blocks, Words  @node Other I/O, Programming Tools, Blocks, Words
 @section Other I/O  @section Other I/O
   
 @node Programming Tools, Threading Words, Other I/O, Words  @node Programming Tools, Assembler and Code words, Other I/O, Words
 @section Programming Tools  @section Programming Tools
   
 @menu  @menu
Line 1625  If there is interest, we will introduce Line 1674  If there is interest, we will introduce
 intend to @code{catch} a specific condition, using @code{throw} is  intend to @code{catch} a specific condition, using @code{throw} is
 probably more appropriate than an assertion).  probably more appropriate than an assertion).
   
 @node Threading Words,  , Programming Tools, Words  @node Assembler and Code words, Threading Words, Programming Tools, Words
   @section Assembler and Code words
   
   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
   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 gcc version and options used.
   
   The words Gforth offers encapsulate some system dependences (e.g., the
   header structure), so a system-independent assembler may be used in
   Gforth. If you do not have an assembler, you can compile machine code
   directly with @code{,} and @code{c,}.
   
   doc-assembler
   doc-code
   doc-end-code
   doc-;code
   doc-flush-icache
   
   If @code{flush-icache} does not work correctly, @code{code} words
   etc. will not work (reliably), either.
   
   These words are rarely used. Therefore they reside in @code{code.fs},
   which is usually not loaded (except @code{flush-icache}, which is always
   present). You can load them with @code{require code.fs}.
   
   Another option for implementing normal and defining words efficiently
   is: adding the wanted functionality to the source of Gforth. For normal
   words you just have to edit @file{primitives}, defining words (for fast
   defined words) probably require changes in @file{engine.c},
   @file{kernal.fs}, @file{prims2x.fs}, and possibly @file{cross.fs}.
   
   
   @node Threading Words,  , Assembler and Code words, Words
 @section Threading Words  @section Threading Words
   
 These words provide access to code addresses and other threading stuff  These words provide access to code addresses and other threading stuff
Line 1643  doc-does-code! Line 1728  doc-does-code!
 doc-does-handler!  doc-does-handler!
 doc-/does-handler  doc-/does-handler
   
   The code addresses produced by various defining words are produced by
   the following words:
   
   doc-docol:
   doc-docon:
   doc-dovar:
   doc-douser:
   doc-dodefer:
   doc-dofield:
   
   Currently there is no installation-independent way for recogizing words
   defined by a @code{CREATE}...@code{DOES>} word; however, once you know
   that a word is defined by a @code{CREATE}...@code{DOES>} word, you can
   use @code{>DOES-CODE}.
   
 @node ANS conformance, Model, Words, Top  @node ANS conformance, Model, Words, Top
 @chapter ANS conformance  @chapter ANS conformance
Line 1670  ANS Forth System Line 1768  ANS Forth System
 @item providing the Memory-Allocation word set  @item providing the Memory-Allocation word set
 @item providing the Memory-Allocation Extensions word set (that one's easy)  @item providing the Memory-Allocation Extensions word set (that one's easy)
 @item providing the Programming-Tools word set  @item providing the Programming-Tools word set
 @item providing @code{AHEAD}, @code{BYE}, @code{CS-PICK}, @code{CS-ROLL}, @code{STATE}, @code{[ELSE]}, @code{[IF]}, @code{[THEN]} from the Programming-Tools Extensions word set  @item providing @code{;code}, @code{AHEAD}, @code{ASSEMBLER}, @code{BYE}, @code{CODE}, @code{CS-PICK}, @code{CS-ROLL}, @code{STATE}, @code{[ELSE]}, @code{[IF]}, @code{[THEN]} from the Programming-Tools Extensions word set
 @item providing the Search-Order word set  @item providing the Search-Order word set
 @item providing the Search-Order Extensions word set  @item providing the Search-Order Extensions word set
 @item providing the String word set  @item providing the String word set
Line 1993  Compiles a recursive call to the definin Line 2091  Compiles a recursive call to the definin
   
 @item argument input source different than current input source for @code{RESTORE-INPUT}:  @item argument input source different than current input source for @code{RESTORE-INPUT}:
 !!???If the argument input source is a valid input source then it gets  !!???If the argument input source is a valid input source then it gets
 restored. Otherwise causes @code{-12 THROW} which unless caught issues  restored. Otherwise causes @code{-12 THROW}, which, unless caught, issues
 the message "argument type mismatch" and aborts.  the message "argument type mismatch" and aborts.
   
 @item data space containing definitions gets de-allocated:  @item data space containing definitions gets de-allocated:
Line 3100  Sieve benchmark on a 486DX2/66 than Gfor Line 3198  Sieve benchmark on a 486DX2/66 than Gfor
 However, this potential advantage of assembly language implementations  However, this potential advantage of assembly language implementations
 is not necessarily realized in complete Forth systems: We compared  is not necessarily realized in complete Forth systems: We compared
 Gforth (compiled with @code{gcc-2.6.3} and @code{-DFORCE_REG}) with  Gforth (compiled with @code{gcc-2.6.3} and @code{-DFORCE_REG}) with
 Win32Forth and LMI's NT Forth, two systems written in assembly, and with  Win32Forth 1.2093 and LMI's NT Forth (Beta, May 1994), two systems
 two systems written in C: PFE-0.9.11 (compiled with @code{gcc-2.6.3}  written in assembly, and with two systems written in C: PFE-0.9.11
 with the default configuration for Linux: @code{-O2 -fomit-frame-pointer  (compiled with @code{gcc-2.6.3} with the default configuration for
 -DUSE_REGS}) and ThisForth Beta (compiled with gcc-2.6.3 -O3  Linux: @code{-O2 -fomit-frame-pointer -DUSE_REGS}) and ThisForth Beta
 -fomit-frame-pointer). We benchmarked Gforth, PFE and ThisForth on a  (compiled with gcc-2.6.3 -O3 -fomit-frame-pointer). We benchmarked
 486DX2/66 under Linux. Kenneth O'Heskin kindly provided the results for  Gforth, PFE and ThisForth on a 486DX2/66 under Linux. Kenneth O'Heskin
 Win32Forth and NT Forth on a 486DX2/66 with similar memory performance  kindly provided the results for Win32Forth and NT Forth on a 486DX2/66
 under Windows NT.  with similar memory performance under Windows NT.
     
 We used four small benchmarks: the ubiquitous Sieve; bubble-sorting and  We used four small benchmarks: the ubiquitous Sieve; bubble-sorting and
 matrix multiplication come from the Stanford integer benchmarks and have  matrix multiplication come from the Stanford integer benchmarks and have
Line 3197  information about Forth there. Line 3295  information about Forth there.
 @node Word Index, Node Index, Pedigree, Top  @node Word Index, Node Index, Pedigree, Top
 @chapter Word Index  @chapter Word Index
   
 This index is as incomplete as the manual.  This index is as incomplete as the manual. Each word is listed with
   stack effect and wordset.
   
 @printindex fn  @printindex fn
   

Removed from v.1.17  
changed lines
  Added in v.1.19


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