Diff for /gforth/Attic/gforth.ds between versions 1.33 and 1.35

version 1.33, 1996/05/13 16:36:56 version 1.35, 1996/09/10 16:08:37
Line 88  personal machines. This manual correspon Line 88  personal machines. This manual correspon
 * Words::                       Forth words available in Gforth  * Words::                       Forth words available in Gforth
 * 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.
 * Emacs and Gforth::            The Gforth Mode  * Emacs and Gforth::            The Gforth Mode
 * Internals::                   Implementation details  * Internals::                   Implementation details
 * Bugs::                        How to report them  * Bugs::                        How to report them
Line 848  The format of floating point numbers rec Line 849  The format of floating point numbers rec
 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} ist the same as
 @code{+1.0e+1}. 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,
 conversions between string and floating point numbers always use base  conversions between string and floating point numbers always use base
Line 1930  stack easier. Line 1931  stack easier.
 The whole definition must be in one line.  The whole definition must be in one line.
 @end itemize  @end itemize
   
 Locals defined in this way behave like @code{VALUE}s  Locals defined in this way behave like @code{VALUE}s (@xref{Simple
 (@xref{Values}). I.e., they are initialized from the stack. Using their  Defining Words}). I.e., they are initialized from the stack. Using their
 name produces their value. Their value can be changed using @code{TO}.  name produces their value. Their value can be changed using @code{TO}.
   
 Since this syntax is supported by Gforth directly, you need not do  Since this syntax is supported by Gforth directly, you need not do
Line 1960  locals wordset. Line 1961  locals wordset.
 @section Defining Words  @section Defining Words
   
 @menu  @menu
 * Values::                        * Simple Defining Words::       
   * Colon Definitions::           
   * User-defined Defining Words::  
   * Supplying names::             
   * Interpretation and Compilation Semantics::  
 @end menu  @end menu
   
 @node Values,  , Defining Words, Defining Words  @node Simple Defining Words, Colon Definitions, Defining Words, Defining Words
 @subsection Values  @subsection Simple Defining Words
   
   doc-constant
   doc-2constant
   doc-fconstant
   doc-variable
   doc-2variable
   doc-fvariable
   doc-create
   doc-user
   doc-value
   doc-to
   doc-defer
   doc-is
   
   @node Colon Definitions, User-defined Defining Words, Simple Defining Words, Defining Words
   @subsection Colon Definitions
   
   @example
   : name ( ... -- ... )
       word1 word2 word3 ;
   @end example
   
   creates a word called @code{name}, that, upon execution, executes
   @code{word1 word2 word3}. @code{name} is a @dfn{(colon) definition}.
   
   The explanation above is somewhat superficial. @xref{Interpretation and
   Compilation Semantics} for an in-depth discussion of some of the issues
   involved.
   
   doc-:
   doc-;
   
   @node User-defined Defining Words, Supplying names, Colon Definitions, Defining Words
   @subsection User-defined Defining Words
   
   You can create new defining words simply by wrapping defining-time code
   around existing defining words and putting the sequence in a colon
   definition.
   
   If you want the words defined by your defining words to behave
   differently than words defined with standard defining words, you can
   write your defining word like this:
   
   @example
   : def-word ( "name" -- )
       Create @var{code1}
   DOES> ( ... -- ... )
       @var{code2} ;
   
   def-word name
   @end example
   
   Technically, this fragment defines a defining word @code{def-word}, and
   a word @code{name}; when you execute @code{name}, the address of the
   body of @code{name} is put on the data stack and @var{code2} is executed
   (the address of the body of @code{name} is the address @code{HERE}
   returns immediately after the @code{CREATE}). E.g., you can implement
   @code{Constant} in this way:
   
   @example
   : constant ( w "name" -- )
       create ,
   DOES> ( -- w )
       @ ;
   @end example
   
   When you create a constant with @code{5 constant five}, first a new word
   @code{five} is created, then the value 5 is laid down in the body of
   @code{five} with @code{,}. When @code{five} is invoked, the address of
   the body is put on the stack, and @code{@@} retrieves the value 5.
   
   In the example above the stack comment after the @code{DOES>} specifies
   the stack effect of the defined words, not the stack effect of the
   following code (the following code expects the address of the body on
   the top of stack, which is not reflected in the stack comment). This is
   the convention that I use and recommend (it clashes a bit with using
   locals declarations for stack effect specification, though).
   
   @subsubsection Applications of @code{CREATE..DOES>}
   
   You may not be sure how to use this feature. Here are some usage
   patterns:
   
   When you see a sequence of code occurring several times, and you can
   identify a meaning, you will factor it out as a colon definition. When
   you see similar colon definitions, you can factor them using
   @code{CREATE..DOES>}. E.g., an assembler usually defines several words
   that look very similar:
   @example
   : ori, ( reg-taget reg-source n -- )
       0 asm-reg-reg-imm ;
   : andi, ( reg-taget reg-source n -- )
       1 asm-reg-reg-imm ;
   @end example
   
   This could be factored with:
   @example
   : reg-reg-imm ( op-code -- )
       create ,
   DOES> ( reg-taget reg-source n -- )
       @ asm-reg-reg-imm ;
   
   0 reg-reg-imm ori,
   1 reg-reg-imm andi,
   @end example
   
   Another view of @code{CREATE..DOES>} is to consider it as a crude way to
   supply a part of the parameters for a word (known as @dfn{currying} in
   the functional language community). E.g., @code{+} needs two
   parameters. Creating versions of @code{+} with one parameter fixed can
   be done like this:
   @example
   : curry+ ( n1 -- )
       create ,
   DOES> ( n2 -- n1+n2 )
       @ + ;
   
    3 curry+ 3+
   -2 curry+ 2-
   @end example
   
   @subsubsection The gory details of @code{CREATE..DOES>}
   
   doc-does>
   
   This means that you need not use @code{CREATE} and @code{DOES>} in the
   same definition; E.g., you can put the @code{DOES>}-part in a separate
   definition. This allows us to, e.g., select among different DOES>-parts:
   @example
   : does1 
   DOES> ( ... -- ... )
       ... ;
   
   : does2
   DOES> ( ... -- ... )
       ... ;
   
   : def-word ( ... -- ... )
       create ...
       IF
          does1
       ELSE
          does2
       ENDIF ;
   @end example
   
   In a standard program you can apply a @code{DOES>}-part only if the last
   word was defined with @code{CREATE}. In Gforth, the @code{DOES>}-part
   will override the behaviour of the last word defined in any case. In a
   standard program, you can use @code{DOES>} only in a colon
   definition. In Gforth, you can also use it in interpretation state, in a
   kind of one-shot mode:
   @example
   CREATE name ( ... -- ... )
     @var{initialization}
   DOES>
     @var{code} ;
   @end example
   This is equivalwent to the standard
   @example
   :noname
   DOES>
       @var{code} ;
   CREATE name EXECUTE ( ... -- ... )
       @var{initialization}
   @end example
   
   You can get the address of the body of a word with
   
   doc->body
   
   @node Supplying names, Interpretation and Compilation Semantics, User-defined Defining Words, Defining Words
   @subsection Supplying names for the defined words
   
   By default, defining words take the names for the defined words from the
   input stream. Sometimes you want to supply the name from a string. You
   can do this with
   
   doc-nextname
   
   E.g.,
   
   @example
   s" foo" nextname create
   @end example
   is equivalent to
   @example
   create foo
   @end example
   
   Sometimes you want to define a word without a name. You can do this with
   
   doc-noname
   
   To make any use of the newly defined word, you need its execution
   token. You can get it with
   
   doc-lastxt
   
   E.g., you can initialize a deferred word with an anonymous colon
   definition:
   @example
   Defer deferred
   noname : ( ... -- ... )
     ... ;
   lastxt IS deferred
   @end example
   
   @code{lastxt} also works when the last word was not defined as
   @code{noname}. 
   
   The standard has also recognized the need for anonymous words and
   provides
   
   doc-:noname
   
   This leaves the execution token for the word on the stack after the
   closing @code{;}. You can rewrite the last example with @code{:noname}:
   @example
   Defer deferred
   :noname ( ... -- ... )
     ... ;
   IS deferred
   @end example
   
   @node Interpretation and Compilation Semantics,  , Supplying names, Defining Words
   @subsection Interpretation and Compilation Semantics
   
   doc-immediate
   doc-interpret/compile:
   
   
   
 @node Wordlists, Files, Defining Words, Words  @node Wordlists, Files, Defining Words, Words
 @section Wordlists  @section Wordlists
Line 2140  and use that in your assembly code. Line 2377  and use that in your assembly code.
   
 Another option for implementing normal and defining words efficiently  Another option for implementing normal and defining words efficiently
 is: adding the wanted functionality to the source of Gforth. For normal  is: adding the wanted functionality to the source of Gforth. For normal
 words you just have to edit @file{primitives}, defining words (for fast  words you just have to edit @file{primitives} (@pxref{Automatic
 defined words) may require changes in @file{engine.c},  Generation}), defining words (equivalent to @code{;CODE} words, for fast
 @file{kernal.fs}, @file{prims2x.fs}, and possibly @file{cross.fs}.  defined words) may 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  @node Threading Words,  , Assembler and Code words, Words
Line 2173  doc-douser: Line 2411  doc-douser:
 doc-dodefer:  doc-dodefer:
 doc-dofield:  doc-dofield:
   
 Currently there is no installation-independent way for recogizing words  You can recognize words defined by a @code{CREATE}...@code{DOES>} word
 defined by a @code{CREATE}...@code{DOES>} word; however, once you know  with @code{>DOES-CODE}. If the word was defined in that way, the value
 that a word is defined by a @code{CREATE}...@code{DOES>} word, you can  returned is different from 0 and identifies the @code{DOES>} used by the
 use @code{>DOES-CODE}.  defining word.
   
 @node ANS conformance, Model, Words, Top  @node ANS conformance, Model, Words, Top
 @chapter ANS conformance  @chapter ANS conformance
Line 2184  use @code{>DOES-CODE}. Line 2422  use @code{>DOES-CODE}.
 To the best of our knowledge, Gforth is an  To the best of our knowledge, Gforth is an
   
 ANS Forth System  ANS Forth System
 @itemize  @itemize @bullet
 @item providing the Core Extensions word set  @item providing the Core Extensions word set
 @item providing the Block word set  @item providing the Block word set
 @item providing the Block Extensions word set  @item providing the Block Extensions word set
Line 2203  ANS Forth System Line 2441  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{;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 @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 3212  are applied to the latest defined word ( Line 3450  are applied to the latest defined word (
   
 @end table  @end table
   
   @node Model, Integrating Gforth, ANS conformance, Top
 @node Model, Emacs and Gforth, ANS conformance, Top  
 @chapter Model  @chapter Model
   
 @node Emacs and Gforth, Internals, Model, Top  This chapter has yet to be written. It will contain information, on
   which internal structures you can rely.
   
   @node Integrating Gforth, Emacs and Gforth, Model, Top
   @chapter Integrating Gforth into C programs
   
   This is not yet implemented.
   
   Several people like to use Forth as scripting language for applications
   that are otherwise written in C, C++, or some other language.
   
   The Forth system ATLAST provides facilities for embedding it into
   applications; unfortunately it has several disadvantages: most
   implorantly, it is not based on ANS Forth, and it is apparently dead
   (i.e., not developed further and not supported). The facilities
   provided by Gforth in this area are inspired by ATLASTs facilities, so
   making the switch should not be hard.
   
   We also tried to design the interface such that it can easily be
   implemented by other Forth systems, so that we may one day arrive at a
   standardized interface. Such a standard interface would allow you to
   replace the Forth system without having to rewrite C code.
   
   You embed the Gforth interpreter by linking with the library
   @code{libgforth.a} (give the compiler the option @code{-lgforth}).  All
   global symbols in this library that belong to the interface, have the
   prefix @code{forth_}. (Global symbols that are used internally have the
   prefix @code{gforth_}).
   
   You can include the declarations of Forth types and the functions and
   variables of the interface with @code{include <forth.h>}.
   
   Types.
   
   Variables.
   
   Data and FP Stack pointer. Area sizes.
   
   functions.
   
   forth_init(imagefile)
   forth_evaluate(string) exceptions?
   forth_goto(address) (or forth_execute(xt)?)
   forth_continue() (a corountining mechanism)
   
   Adding primitives.
   
   No checking.
   
   Signals?
   
   Accessing the Stacks
   
   @node Emacs and Gforth, Internals, Integrating Gforth, Top
 @chapter Emacs and Gforth  @chapter Emacs and Gforth
   
 Gforth comes with @file{gforth.el}, an improved version of  Gforth comes with @file{gforth.el}, an improved version of
Line 3549  An important optimization for stack mach Line 3839  An important optimization for stack mach
 engines, is keeping  one or more of the top stack items in  engines, is keeping  one or more of the top stack items in
 registers.  If a word has the stack effect @var{in1}...@var{inx} @code{--}  registers.  If a word has the stack effect @var{in1}...@var{inx} @code{--}
 @var{out1}...@var{outy}, keeping the top @var{n} items in registers  @var{out1}...@var{outy}, keeping the top @var{n} items in registers
 @itemize  @itemize @bullet
 @item  @item
 is better than keeping @var{n-1} items, if @var{x>=n} and @var{y>=n},  is better than keeping @var{n-1} items, if @var{x>=n} and @var{y>=n},
 due to fewer loads from and stores to the stack.  due to fewer loads from and stores to the stack.
Line 3583  The TOS optimization makes the automatic Line 3873  The TOS optimization makes the automatic
 bit more complicated. Just replacing all occurrences of @code{sp[0]} by  bit more complicated. Just replacing all occurrences of @code{sp[0]} by
 @code{TOS} is not sufficient. There are some special cases to  @code{TOS} is not sufficient. There are some special cases to
 consider:  consider:
 @itemize  @itemize @bullet
 @item In the case of @code{dup ( w -- w w )} the generator must not  @item In the case of @code{dup ( w -- w w )} the generator must not
 eliminate the store to the original location of the item on the stack,  eliminate the store to the original location of the item on the stack,
 if the TOS optimization is turned on.  if the TOS optimization is turned on.
Line 3785  VolksForth descends from F83. It was wri Line 4075  VolksForth descends from F83. It was wri
 Pennemann, Georg Rehfeld and Dietrich Weineck for the C64 (called  Pennemann, Georg Rehfeld and Dietrich Weineck for the C64 (called
 UltraForth there) in the mid-80s and ported to the Atari ST in 1986.  UltraForth there) in the mid-80s and ported to the Atari ST in 1986.
   
 Hennry Laxen and Mike Perry wrote F83 as a model implementation of the  Henry Laxen and Mike Perry wrote F83 as a model implementation of the
 Forth-83 standard. !! Pedigree? When?  Forth-83 standard. !! Pedigree? When?
   
 A team led by Bill Ragsdale implemented fig-Forth on many processors in  A team led by Bill Ragsdale implemented fig-Forth on many processors in

Removed from v.1.33  
changed lines
  Added in v.1.35


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