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

Diff for /gforth/doc/gforth.ds between versions 1.70 and 1.71

version 1.70, 2000/08/14 19:15:55 version 1.71, 2000/08/14 21:15:01
Line 302  Defining Words Line 302  Defining Words
 * Values::                      Initialised variables  * Values::                      Initialised variables
 * Colon Definitions::             * Colon Definitions::           
 * Anonymous Definitions::       Definitions without names  * Anonymous Definitions::       Definitions without names
 * Supplying names::               * Supplying names::             Passing definition names as strings
 * User-defined Defining Words::    * User-defined Defining Words::  
 * Deferred words::              Allow forward references  * Deferred words::              Allow forward references
 * Aliases::                       * Aliases::                     
Line 317  Interpretation and Compilation Semantics Line 317  Interpretation and Compilation Semantics
   
 * Combined words::                * Combined words::              
   
   Tokens for Words
   
   * Execution token::             represents execution/interpretation semantics
   * Compilation token::           represents compilation semantics
   * Name token::                  represents named words
   
 The Text Interpreter  The Text Interpreter
   
 * Input Sources::                 * Input Sources::               
Line 6150  lastxt IS deferred Line 6156  lastxt IS deferred
 @code{noname} works with any defining word, not just @code{:}.  @code{noname} works with any defining word, not just @code{:}.
   
 @code{lastxt} also works when the last word was not defined as  @code{lastxt} also works when the last word was not defined as
 @code{noname}. It also has the useful property that is is valid as soon  @code{noname}.  It does not work for combined words, though.  It also has
 as the header for a definition has been built. Thus:  the useful property that is is valid as soon as the header for a
   definition has been built. Thus:
   
 @example  @example
 lastxt . : foo [ lastxt . ] ; ' foo .  lastxt . : foo [ lastxt . ] ; ' foo .
Line 6616  the following way: Line 6623  the following way:
 ' @var{disasm-operands} ' @var{table} define-format @var{inst-format}  ' @var{disasm-operands} ' @var{table} define-format @var{inst-format}
 @end example  @end example
   
   As shown above, the defined instruction format is then used like this:
   
   @example
   @var{entry-num} @var{inst-format} @var{inst-name}
   @end example
   
 In terms of currying, this kind of two-level defining word provides the  In terms of currying, this kind of two-level defining word provides the
 parameters in three stages: first @var{disasm-operands} and @var{table},  parameters in three stages: first @var{disasm-operands} and @var{table},
 then @var{entry-num} and @var{inst-name}, finally @code{addr w}, i.e.,  then @var{entry-num} and @var{inst-name}, finally @code{addr w}, i.e.,
Line 6785  doc-alias Line 6798  doc-alias
 @section Interpretation and Compilation Semantics  @section Interpretation and Compilation Semantics
 @cindex semantics, interpretation and compilation  @cindex semantics, interpretation and compilation
   
   @c !! state and ' are used without explanation
   @c example for immediate/compile-only? or is the tutorial enough
   
 @cindex interpretation semantics  @cindex interpretation semantics
 The @dfn{interpretation semantics} of a word are what the text  The @dfn{interpretation semantics} of a (named) word are what the text
 interpreter does when it encounters the word in interpret state. It also  interpreter does when it encounters the word in interpret state. It also
 appears in some other contexts, e.g., the execution token returned by  appears in some other contexts, e.g., the execution token returned by
 @code{' @i{word}} identifies the interpretation semantics of  @code{' @i{word}} identifies the interpretation semantics of @i{word}
 @i{word} (in other words, @code{' @i{word} execute} is equivalent to  (in other words, @code{' @i{word} execute} is equivalent to
 interpret-state text interpretation of @code{@i{word}}).  interpret-state text interpretation of @code{@i{word}}).
   
 @cindex compilation semantics  @cindex compilation semantics
 The @dfn{compilation semantics} of a word are what the text interpreter  The @dfn{compilation semantics} of a (named) word are what the text
 does when it encounters the word in compile state. It also appears in  interpreter does when it encounters the word in compile state. It also
 other contexts, e.g, @code{POSTPONE @i{word}} compiles@footnote{In  appears in other contexts, e.g, @code{POSTPONE @i{word}}
 standard terminology, ``appends to the current definition''.} the  compiles@footnote{In standard terminology, ``appends to the current
 compilation semantics of @i{word}.  definition''.} the compilation semantics of @i{word}.
   
 @cindex execution semantics  @cindex execution semantics
 The standard also talks about @dfn{execution semantics}. They are used  The standard also talks about @dfn{execution semantics}. They are used
Line 6811  execution semantics; the default compila Line 6827  execution semantics; the default compila
 execution semantics to the execution semantics of the current  execution semantics to the execution semantics of the current
 definition.}  definition.}
   
   Unnamed words (@pxref{Anonymous Definitions}) cannot be encountered by
   the text interpreter, ticked, or @code{postpone}d, so they have no
   interpretation or compilation semantics.  Their behaviour is represented
   by their XT (@pxref{Tokens for Words}), and we call it execution
   semantics, too.
   
 @comment TODO expand, make it co-operate with new sections on text interpreter.  @comment TODO expand, make it co-operate with new sections on text interpreter.
   
 @cindex immediate words  @cindex immediate words
Line 6830  Note that ticking (@code{'}) a compile-o Line 6852  Note that ticking (@code{'}) a compile-o
 * Combined words::                * Combined words::              
 @end menu  @end menu
   
   
 @node Combined words,  , Interpretation and Compilation Semantics, Interpretation and Compilation Semantics  @node Combined words,  , Interpretation and Compilation Semantics, Interpretation and Compilation Semantics
 @subsection Combined Words  @subsection Combined Words
 @cindex combined words  @cindex combined words
Line 6837  Note that ticking (@code{'}) a compile-o Line 6860  Note that ticking (@code{'}) a compile-o
 Gforth allows you to define @dfn{combined words} -- words that have an  Gforth allows you to define @dfn{combined words} -- words that have an
 arbitrary combination of interpretation and compilation semantics.  arbitrary combination of interpretation and compilation semantics.
   
   
 doc-interpret/compile:  doc-interpret/compile:
   
   
 This feature was introduced for implementing @code{TO} and @code{S"}. I  This feature was introduced for implementing @code{TO} and @code{S"}. I
 recommend that you do not define such words, as cute as they may be:  recommend that you do not define such words, as cute as they may be:
 they make it hard to get at both parts of the word in some contexts.  they make it hard to get at both parts of the word in some contexts.
Line 6970  doc-postpone Line 6991  doc-postpone
 This section describes the creation and use of tokens that represent  This section describes the creation and use of tokens that represent
 words.  words.
   
 Named words have information stored in their header space entries to  @menu
 indicate any non-default semantics (@pxref{Interpretation and  * Execution token::             represents execution/interpretation semantics
 Compilation Semantics}). The semantics can be modified, using  * Compilation token::           represents compilation semantics
 @code{immediate} and/or @code{compile-only}, at the time that the words  * Name token::                  represents named words
 are defined. Unnamed words have (by definition) no header space  @end menu
 entry, and therefore must have default semantics.  
   
 Named words have interpretation and compilation semantics. Unnamed words  @node Execution token, Compilation token, Tokens for Words, Tokens for Words
 just have execution semantics.  @subsection Execution token
   
 @cindex xt  @cindex xt
 @cindex execution token  @cindex execution token
 The execution semantics of an unnamed word are represented by an  An @dfn{execution token} (@i{XT}) represents some behaviour of a word.
 @dfn{execution token} (@i{xt}). As explained in @ref{Supplying names},  You can use @code{execute} to invoke this behaviour.
 the execution token of the last word defined can be produced with  
 @code{lastxt}.  
   
 The interpretation semantics of a named word are also represented by an  @cindex tick (')
 execution token. You can produce the execution token using @code{'} or  You can use @code{'} to get an execution token that represents the
 @code{[']}. A simple example shows the difference between the two:  interpretation semantics of a named word:
   
 @example  @example
 : greet ( -- )   ." Hello" ;  5 ' .
 : foo ( -- xt )  ['] greet execute ; \ ['] parses greet at compile-time  execute
 : bar ( -- )     ' execute ; \  '  parses at run-time  @end example
   
 \ the next four lines all do the same thing  doc-'
 foo  
 bar greet  @code{'} parses at run-time; there is also a word @code{[']} that parses
 greet  when it is compiled, and compiles the resulting XT:
 ' greet EXECUTE  
   @example
   : foo ['] . execute ;
   5 foo
   : bar ' execute ; \ by contrast,
   5 bar .           \ ' parses "." when bar executes
   @end example
   
   doc-[']
   
   If you want the execution token of @i{word}, write @code{['] @i{word}}
   in compiled code and @code{' @i{word}} in interpreted code.  Gforth's
   @code{'} and @code{[']} behave somewhat unusually by complaining about
   compile-only words (because these words have no interpretation
   semantics).  You might get what you want by using @code{COMP' @i{word}
   DROP} or @code{[COMP'] @i{word} DROP} (for details @pxref{Compilation
   token}).
   
   Another way to get an XT is @code{:noname} or @code{lastxt}
   (@pxref{Anonymous Definitions}).  For anonymous words this gives an xt
   for the only behaviour the word has (the execution semantics).  For
   named words, @code{lastxt} produces an XT for the same behaviour it
   would produce if the word was defined anonymously.
   
   @example
   :noname ." hello" ;
   execute
 @end example  @end example
   
 An execution token occupies one cell.  An XT occupies one cell and can be manipulated like any other cell.
   
 @cindex code field address  @cindex code field address
 @cindex CFA  @cindex CFA
 In Gforth, the abstract data type @i{execution token} is implemented  In ANS Forth the XT is just an abstract data type (i.e., defined by the
 as a code field address (CFA).  operations that produce or consume it).  For old hands: In Gforth, the
 @comment TODO note that the standard does not say what it represents..  XT is implemented as a code field address (CFA).
 @comment and you cannot necessarily compile it in all Forths (eg native  
 @comment compilers?).  @c !! discuss "compile," some more (or in Macros).
   
 For literals, use @code{'} in interpreted code and @code{[']} in  doc-execute
 compiled code. Gforth's @code{'} and @code{[']} behave somewhat  doc-perform
 unusually by complaining about compile-only words. To get the execution  doc-compile,
 token for a compile-only word @i{name}, use @code{COMP' @i{name} DROP}  
 or @code{[COMP'] @i{name} DROP}.  @node Compilation token, Name token, Execution token, Tokens for Words
   @subsection Compilation token
   
 @cindex compilation token  @cindex compilation token
 The compilation semantics of a named word are represented by a  @cindex CT (compilation token)
   Gforth represents the compilation semantics of a named word by a
 @dfn{compilation token} consisting of two cells: @i{w xt}. The top cell  @dfn{compilation token} consisting of two cells: @i{w xt}. The top cell
 @i{xt} is an execution token. The compilation semantics represented by  @i{xt} is an execution token. The compilation semantics represented by
 the compilation token can be performed with @code{execute}, which  the compilation token can be performed with @code{execute}, which
Line 7036  knowledge, unless necessary; future vers Line 7083  knowledge, unless necessary; future vers
 unusual compilation tokens (e.g., a compilation token that represents  unusual compilation tokens (e.g., a compilation token that represents
 the compilation semantics of a literal).  the compilation semantics of a literal).
   
 You can compile the compilation semantics with @code{postpone,}. I.e.,  You can perform the compilation semantics represented by the compilation
 @code{COMP' @i{word} postpone,} is equivalent to @code{postpone  token with @code{execute}.  You can compile the compilation semantics
 @i{word}}.  with @code{postpone,}. I.e., @code{COMP' @i{word} postpone,} is
   equivalent to @code{postpone @i{word}}.
   
   doc-[comp']
   doc-comp'
   doc-postpone,
   
   @node Name token,  , Compilation token, Tokens for Words
   @subsection Name token
   
 @cindex name token  @cindex name token
 @cindex name field address  @cindex name field address
 @cindex NFA  @cindex NFA
 Named words are also represented by the @dfn{name token}, (@i{nt}). In  Gforth represents named words by the @dfn{name token}, (@i{nt}). In
 Gforth, the abstract data type @emph{name token} is implemented as a  Gforth, the abstract data type @emph{name token} is implemented as a
 name field address (NFA).  name field address (NFA).
   
   
 doc-execute  
 doc-perform  
 doc-compile,  
 doc-[']  
 doc-'  
 doc-[comp']  
 doc-comp'  
 doc-postpone,  
   
 doc-find-name  doc-find-name
 doc-name>int  doc-name>int
 doc-name?int  doc-name?int
Line 7081  doc-name>string Line 7126  doc-name>string
 @c seems to positively avoid going into too much detail for some of  @c seems to positively avoid going into too much detail for some of
 @c the internals.  @c the internals.
   
   @c anton: ok.  I wonder, though, if this is the right place; for some stuff
   @c it is; for the ugly details, I would prefer another place.  I wonder
   @c whether we should have a chapter before "Words" that describes some
   @c basic concepts referred to in words, and a chapter after "Words" that
   @c describes implementation details.
   
 The text interpreter@footnote{This is an expanded version of the  The text interpreter@footnote{This is an expanded version of the
 material in @ref{Introducing the Text Interpreter}.} is an endless loop  material in @ref{Introducing the Text Interpreter}.} is an endless loop
 that processes input from the current input device. It is also called  that processes input from the current input device. It is also called
Line 7092  implementations. Line 7143  implementations.
 @cindex compile state  @cindex compile state
 The text interpreter operates in one of two states: @dfn{interpret  The text interpreter operates in one of two states: @dfn{interpret
 state} and @dfn{compile state}. The current state is defined by the  state} and @dfn{compile state}. The current state is defined by the
 aptly-named variable, @code{state}.  aptly-named variable @code{state}.
   
 This section starts by describing how the text interpreter behaves when  This section starts by describing how the text interpreter behaves when
 it is in interpret state, processing input from the user input device --  it is in interpret state, processing input from the user input device --
Line 7139  repeats the parsing process until the wh Line 7190  repeats the parsing process until the wh
 processed, at which point it prints the status message ``@code{ ok}''  processed, at which point it prints the status message ``@code{ ok}''
 and waits for more input.  and waits for more input.
   
   @c anton: this should be in the input stream subsection (or below it)
   
 @cindex parse area  @cindex parse area
 The text interpreter keeps track of its position in the input buffer by  The text interpreter keeps track of its position in the input buffer by
 updating a variable called @code{>IN} (pronounced ``to-in''). The value  updating a variable called @code{>IN} (pronounced ``to-in''). The value
Line 7178  input buffer@footnote{This is how parsin Line 7231  input buffer@footnote{This is how parsin
 section twice. For example:  section twice. For example:
   
 @example  @example
 : lat ." <<lat>>" ;  : lat ." <<foo>>" ;
 : flat ." <<flat>>" >IN DUP @@ 3 - SWAP ! ;  : flat ." <<bar>>" >IN DUP @@ 3 - SWAP ! ;
 @end example  @end example
   
 @noindent  @noindent
Line 7188  for the reader: what would happen if the Line 7241  for the reader: what would happen if the
 @code{4}?}:  @code{4}?}:
   
 @example  @example
 <<flat>><<lat>>  <<bar>><<foo>>
 @end example  @end example
   
   This technique can be used to work around some of the interoperability
   problems of parsing words.  Of course, it's better to avoid parsing
   words where possible.
   
 @noindent  @noindent
 Two important notes about the behaviour of the text interpreter:  Two important notes about the behaviour of the text interpreter:
   
Line 7231  keyboard, its behaviour changes in these Line 7288  keyboard, its behaviour changes in these
 @item  @item
 When the parse area is empty, the text interpreter attempts to refill  When the parse area is empty, the text interpreter attempts to refill
 the input buffer from the input source. When the input source is  the input buffer from the input source. When the input source is
 exhausted, the input source is set back to the user input device.  exhausted, the input source is set back to the previous input source.
 @item  @item
 It doesn't print out ``@code{ ok}'' or ``@code{ compiled}'' messages each  It doesn't print out ``@code{ ok}'' or ``@code{ compiled}'' messages each
 time the parse area is emptied.  time the parse area is emptied.
Removed from v.1.70  
changed lines
  Added in v.1.71

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