Diff for /gforth/Attic/gforth.ds between versions 1.38 and 1.41

version 1.38, 1996/10/01 16:25:58 version 1.41, 1997/01/04 16:32:29
Line 86  personal machines. This manual correspon Line 86  personal machines. This manual correspon
 * Other Books::                 Things you might want to read  * Other Books::                 Things you might want to read
 * Invocation::                  Starting Gforth  * Invocation::                  Starting Gforth
 * Words::                       Forth words available in Gforth  * Words::                       Forth words available in Gforth
   * Tools::                       Programming tools
 * ANS conformance::             Implementation-defined options etc.  * ANS conformance::             Implementation-defined options etc.
 * Model::                       The abstract machine of Gforth  * Model::                       The abstract machine of Gforth
 * Integrating Gforth::          Forth as scripting language for applications.  * Integrating Gforth::          Forth as scripting language for applications.
Line 566  versions can be found through Line 567  versions can be found through
 @cite{Forth: The new model} by Jack Woehr (Prentice-Hall, 1993) is an  @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  introductory book based on a draft version of the standard. It does not
 cover the whole standard. It also contains interesting background  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  not appropriate for complete newbies, but programmers experienced in
 other languages should find it ok.  other languages should find it ok.
   
Line 600  Loads the Forth image @var{file} instead Line 601  Loads the Forth image @var{file} instead
   
 @item --path @var{path}  @item --path @var{path}
 @item -p @var{path}  @item -p @var{path}
 Uses @var{path} for searching the image file and Forth source code  Uses @var{path} for searching the image file and Forth source code files
 files instead of the default in the environment variable  instead of the default in the environment variable @code{GFORTHPATH} or
 @code{GFORTHPATH} or the path specified at installation time (typically  the path specified at installation time (e.g.,
 @file{/usr/local/lib/gforth:.}). A path is given as a @code{:}-separated  @file{/usr/local/share/gforth/0.2.0:.}). A path is given as a list of
 list.  directories, separated by @samp{:} (on Unix) or @samp{;} (on other OSs).
   
 @item --dictionary-size @var{size}  @item --dictionary-size @var{size}
 @item -m @var{size}  @item -m @var{size}
Line 640  default specified in the image (typicall Line 641  default specified in the image (typicall
   
 As explained above, the image-specific command-line arguments for the  As explained above, the image-specific command-line arguments for the
 default image @file{gforth.fi} consist of a sequence of filenames and  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  in which they are given. The @code{-e @var{forth-code}} or
 @code{--evaluate @var{forth-code}} option evaluates the forth  @code{--evaluate @var{forth-code}} option evaluates the forth
 code. This option takes only one argument; if you want to evaluate more  code. This option takes only one argument; if you want to evaluate more
Line 662  the user initialization file @file{.gfor Line 663  the user initialization file @file{.gfor
 option @code{--no-rc} is given; this file is first searched in @file{.},  option @code{--no-rc} is given; this file is first searched in @file{.},
 then in @file{~}, then in the normal path (see above).  then in @file{~}, then in the normal path (see above).
   
 @node Words, ANS conformance, Invocation, Top  @node Words, Tools, Invocation, Top
 @chapter Forth Words  @chapter Forth Words
   
 @menu  @menu
Line 854  doc-dmax Line 855  doc-dmax
 The format of floating point numbers recognized by the outer (aka text)  The format of floating point numbers recognized by the outer (aka text)
 interpreter is: a signed decimal number, possibly containing a decimal  interpreter is: a signed decimal number, possibly containing a decimal
 point (@code{.}), followed by @code{E} or @code{e}, optionally followed  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}  @code{+1.0e+0}. Note that a number without @code{e}
 is not interpreted as floating-point number, but as double (if the  is not interpreted as floating-point number, but as double (if the
 number contains a @code{.}) or single precision integer. Also,  number contains a @code{.}) or single precision integer. Also,
Line 1509  Gforth currently supports cells (@code{W Line 1510  Gforth currently supports cells (@code{W
 with @code{W:}, @code{D:} etc.) produces its value and can be changed  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.)  with @code{TO}. A variable-flavoured local (defined with @code{W^} etc.)
 produces its address (which becomes invalid when the variable's scope is  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:  @code{type} like this:
   
 @example  @example
Line 1568  definition? Which local is meant, if the Line 1569  definition? Which local is meant, if the
 two independent control flow paths?  two independent control flow paths?
   
 This should be enough detail for nearly all users, so you can skip the  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.  options, read on.
   
 In order to implement this rule, the compiler has to know which places  In order to implement this rule, the compiler has to know which places
Line 1621  are entered only through the @code{BEGIN Line 1622  are entered only through the @code{BEGIN
 @code{BEGIN}...@code{UNTIL} loops and it is implemented in our  @code{BEGIN}...@code{UNTIL} loops and it is implemented in our
 compiler. When the branch to the @code{BEGIN} is finally generated by  compiler. When the branch to the @code{BEGIN} is finally generated by
 @code{AGAIN} or @code{UNTIL}, the compiler checks the guess and  @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  @example
 IF  IF
   @{ x @}    @{ x @}
Line 2079  you see similar colon definitions, you c Line 2080  you see similar colon definitions, you c
 @code{CREATE..DOES>}. E.g., an assembler usually defines several words  @code{CREATE..DOES>}. E.g., an assembler usually defines several words
 that look very similar:  that look very similar:
 @example  @example
 : ori, ( reg-taget reg-source n -- )  : ori, ( reg-target reg-source n -- )
     0 asm-reg-reg-imm ;      0 asm-reg-reg-imm ;
 : andi, ( reg-taget reg-source n -- )  : andi, ( reg-target reg-source n -- )
     1 asm-reg-reg-imm ;      1 asm-reg-reg-imm ;
 @end example  @end example
   
Line 2089  This could be factored with: Line 2090  This could be factored with:
 @example  @example
 : reg-reg-imm ( op-code -- )  : reg-reg-imm ( op-code -- )
     create ,      create ,
 DOES> ( reg-taget reg-source n -- )  DOES> ( reg-target reg-source n -- )
     @@ asm-reg-reg-imm ;      @@ asm-reg-reg-imm ;
   
 0 reg-reg-imm ori,  0 reg-reg-imm ori,
Line 2148  CREATE name ( ... -- ... ) Line 2149  CREATE name ( ... -- ... )
 DOES>  DOES>
   @var{code} ;    @var{code} ;
 @end example  @end example
 This is equivalwent to the standard  This is equivalent to the standard
 @example  @example
 :noname  :noname
 DOES>  DOES>
Line 2422  doc-postpone, Line 2423  doc-postpone,
   
 At present, the @var{w} part of a compilation token is an execution  At present, the @var{w} part of a compilation token is an execution
 token, and the @var{xt} part represents either @code{execute} or  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.,  we may introduce unusual compilation tokens in the future (e.g.,
 compilation tokens representing the compilation semantics of literals).  compilation tokens representing the compilation semantics of literals).
   
Line 2463  are meant to support a different style o Line 2464  are meant to support a different style o
 tracing/stepping debuggers used in languages with long turn-around  tracing/stepping debuggers used in languages with long turn-around
 times.  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  printing code at well-selected places, let the program run, look at
 the output, see where things went wrong, add more printing code, etc.,  the output, see where things went wrong, add more printing code, etc.,
 until the bug is found.  until the bug is found.
Line 2552  probably more appropriate than an assert Line 2553  probably more appropriate than an assert
 Gforth provides some words for defining primitives (words written in  Gforth provides some words for defining primitives (words written in
 machine code), and for defining the the machine-code equivalent of  machine code), and for defining the the machine-code equivalent of
 @code{DOES>}-based defining words. However, the machine-independent  @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  several architectures, so it can provide no standard assembler. What's
 worse is that the register allocation not only depends on the processor,  worse is that the register allocation not only depends on the processor,
 but also on the @code{gcc} version and options used.  but also on the @code{gcc} version and options used.
Line 2648  with @code{>DOES-CODE}. If the word was Line 2649  with @code{>DOES-CODE}. If the word was
 returned is different from 0 and identifies the @code{DOES>} used by the  returned is different from 0 and identifies the @code{DOES>} used by the
 defining word.  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  @chapter ANS conformance
   
 To the best of our knowledge, Gforth is an  To the best of our knowledge, Gforth is an
Line 2988  find what they search. Note that it is p Line 3040  find what they search. Note that it is p
 names with @code{nextname} (should it not?).  names with @code{nextname} (should it not?).
   
 @item @code{>IN} greater than input buffer:  @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>}:  @item @code{RECURSE} appears after @code{DOES>}:
 Compiles a recursive call to the defining word, not to the defined word.  Compiles a recursive call to the defining word, not to the defined word.
Line 3001  closed file may lead to unpredictable re Line 3053  closed file may lead to unpredictable re
 THROW}.  THROW}.
   
 In the future, Gforth may be able to restore input source specifications  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:  @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.  memory access faults or execution of illegal instructions.
   
 @item data space read/write with incorrect alignment:  @item data space read/write with incorrect alignment:
Line 3238  strange number; e.g., @code{-1000 THROW} Line 3290  strange number; e.g., @code{-1000 THROW}
 @table @i  @table @i
   
 @item encoding of keyboard events (@code{EKEY}):  @item encoding of keyboard events (@code{EKEY}):
 Not yet implemeted.  Not yet implemented.
   
 @item duration of a system clock tick  @item duration of a system clock tick
 System dependent. With respect to @code{MS}, the time is specified in  System dependent. With respect to @code{MS}, the time is specified in
Line 3262  other single-tasking systems, it should Line 3314  other single-tasking systems, it should
 @table @i  @table @i
   
 @item @code{AT-XY} can't be performed on user output device:  @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  No errors are reported. You may see some garbage appearing, you may see
 simply nothing happen.  simply nothing happen.
   
Line 3311  System dependent. Gforth just uses the f Line 3363  System dependent. Gforth just uses the f
 @code{FILE-STATUS} returns the most powerful file access mode allowed  @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  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  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:  @item input file state after an exception when including source:
 All files that are left via the exception are closed.  All files that are left via the exception are closed.
Line 3960  lies in the body (which is illegal in th Line 4012  lies in the body (which is illegal in th
 making the code field larger for all words this solution becomes legal  making the code field larger for all words this solution becomes legal
 again. We use this approach for the indirect threaded version. Leaving  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  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  code field size of two cells is to avoid having different image files
 for direct and indirect threaded systems (@pxref{System Architecture}).  for direct and indirect threaded systems (@pxref{System Architecture}).
   
Line 4154  comply to some restrictions: addresses h Line 4206  comply to some restrictions: addresses h
 special words (@code{A!}, @code{A,}, etc.) in order to make the code  special words (@code{A!}, @code{A,}, etc.) in order to make the code
 relocatable. Cells, floats, etc., have to be stored at the natural  relocatable. Cells, floats, etc., have to be stored at the natural
 alignment boundaries@footnote{E.g., store floats (8 bytes) at an address  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  the ANS Forth alignment words.}, in order to avoid alignment faults on
 machines with stricter alignment. The image file is produced by a  machines with stricter alignment. The image file is produced by a
 metacompiler (@file{cross.fs}).  metacompiler (@file{cross.fs}).
Line 4287  with their continuous feedback. Lennart Line 4339  with their continuous feedback. Lennart
 @file{glosgen.fs}, while Stuart Ramsden has been working on automatic  @file{glosgen.fs}, while Stuart Ramsden has been working on automatic
 support for calling C libraries. Helpful comments also came from Paul  support for calling C libraries. Helpful comments also came from Paul
 Kleinrubatscher, Christian Pirker, Dirk Zoller, Marcel Hendrix, John  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,  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  and autoconf, among others), and to the creators of the Internet: Gforth
Line 4316  A team led by Bill Ragsdale implemented Line 4368  A team led by Bill Ragsdale implemented
 implementation of fig-Forth for the 6502 based on microForth.  implementation of fig-Forth for the 6502 based on microForth.
   
 The principal architect of microForth was Dean Sanderson. microForth was  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  the 1802, and subsequently implemented on the 8080, the 6800 and the
 Z80.  Z80.
   

Removed from v.1.38  
changed lines
  Added in v.1.41


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