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

Diff for /gforth/doc/gforth.ds between versions 1.61 and 1.62

version 1.61, 2000/07/20 14:00:00 version 1.62, 2000/07/21 17:38:58
Line 72  Programming style note: Line 72  Programming style note:
 @ifnottex  @ifnottex
 This file documents Gforth @value{VERSION}  This file documents Gforth @value{VERSION}
   
 Copyright @copyright{} 1995-1999 Free Software Foundation, Inc.  Copyright @copyright{} 1995--2000 Free Software Foundation, Inc.
   
      Permission is granted to make and distribute verbatim copies of       Permission is granted to make and distribute verbatim copies of
      this manual provided the copyright notice and this permission notice       this manual provided the copyright notice and this permission notice
Line 116  Copyright @copyright{} 1995-1999 Free So Line 116  Copyright @copyright{} 1995-1999 Free So
 @comment  The following two commands start the copyright page.  @comment  The following two commands start the copyright page.
 @page  @page
 @vskip 0pt plus 1filll  @vskip 0pt plus 1filll
 Copyright @copyright{} 1995--1999 Free Software Foundation, Inc.  Copyright @copyright{} 1995--2000 Free Software Foundation, Inc.
   
 @comment !! Published by ... or You can get a copy of this manual ...  @comment !! Published by ... or You can get a copy of this manual ...
   
Line 309  Defining Words Line 309  Defining Words
 * Aliases::  * Aliases::
 * Supplying names::  * Supplying names::
   
 User-defined Defining Words  
   
 * CREATE..DOES> applications::    
 * CREATE..DOES> details::         
 * Advanced does> usage example::    
   
 Interpretation and Compilation Semantics  Interpretation and Compilation Semantics
   
 * Combined words::  * Combined words::
Line 357  Programming Tools Line 351  Programming Tools
 * Assertions::                  Making your programs self-checking.  * Assertions::                  Making your programs self-checking.
 * Singlestep Debugger::         Executing your program word by word.  * Singlestep Debugger::         Executing your program word by word.
   
 Assembler and Code Words  
   
 * Code and ;code::                
 * Common Assembler::            Assembler Syntax  
 * Common Disassembler::           
 * 386 Assembler::               Deviations and special cases  
 * Alpha Assembler::             Deviations and special cases  
 * MIPS assembler::              Deviations and special cases  
 * Other assemblers::            How to write them  
   
 Locals  Locals
   
 * Gforth locals::                 * Gforth locals::               
Line 1233  On startup the system first executes the Line 1217  On startup the system first executes the
 (unless the option @code{--no-init-file} is given; note that the system  (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  resulting from using this option may not be ANS Forth conformant). Then
 the user initialization file @file{.gforth.fs} is executed, unless the  the user initialization file @file{.gforth.fs} is executed, unless the
 option @code{--no-rc} is given; this file is first searched in @file{.},  option @code{--no-rc} is given; this file is searched for in @file{.},
 then in @file{~}, then in the normal path (see above).  then in @file{~}, then in the normal path (see above).
   
   
Line 1339  options}). Line 1323  options}).
 ANS Forth only @i{requires} implementations to recognise Standard words  ANS Forth only @i{requires} implementations to recognise Standard words
 when they are typed entirely in upper case. Therefore, a Standard  when they are typed entirely in upper case. Therefore, a Standard
 program must use upper case for all Standard words. You can use whatever  program must use upper case for all Standard words. You can use whatever
 case you like for words that you define, but in a standard program you  case you like for words that you define, but in a Standard program you
 have to use the words in the same case that you defined them.  have to use the words in the same case that you defined them.
   
 Gforth supports case sensitivity through @code{table}s (case-sensitive  Gforth supports case sensitivity through @code{table}s (case-sensitive
 wordlists, @pxref{Word Lists}).  wordlists, @pxref{Word Lists}).
   
 Two people have asked how to convert Gforth to case sensitivity; while  Two people have asked how to convert Gforth to be case-sensitive; while
 we think this is a bad idea, you can change all wordlists into tables  we think this is a bad idea, you can change all wordlists into tables
 like this:  like this:
   
Line 1356  like this: Line 1340  like this:
 Note that you now have to type the predefined words in the same case  Note that you now have to type the predefined words in the same case
 that we defined them, which are varying.  You may want to convert them  that we defined them, which are varying.  You may want to convert them
 to your favourite case before doing this operation (I won't explain how,  to your favourite case before doing this operation (I won't explain how,
 because if you are even contemplating to do this, you'd better have  because if you are even contemplating doing this, you'd better have
 enough knowledge of Forth systems to know this already).  enough knowledge of Forth systems to know this already).
   
 @comment ----------------------------------------------  @comment ----------------------------------------------
Line 1384  for Forth source-code files. Line 1368  for Forth source-code files.
   
 @item  @item
 @cindex @code{GFORTHD} -- environment variable  @cindex @code{GFORTHD} -- environment variable
 @code{GFORTHD} -- used by @file{gforthmi} @xref{gforthmi}.  @code{GFORTHD} -- used by @file{gforthmi}, @xref{gforthmi}.
   
 @item  @item
 @cindex @code{TMP}, @code{TEMP} - environment variable  @cindex @code{TMP}, @code{TEMP} - environment variable
Line 1442  system time. Line 1426  system time.
   
 If startup speed is a problem, you may consider the following ways to  If startup speed is a problem, you may consider the following ways to
 improve it; or you may consider ways to reduce the number of startups  improve it; or you may consider ways to reduce the number of startups
 (e.g., Fast-CGI).  (for example, by using Fast-CGI).
   
 The first step to improve startup speed is to statically link Gforth, by  The first step to improve startup speed is to statically link Gforth, by
 building it with @code{XLDFLAGS=-static}.  This requires more memory for  building it with @code{XLDFLAGS=-static}.  This requires more memory for
Line 1453  result, @code{gforth-static -e bye} take Line 1437  result, @code{gforth-static -e bye} take
 8.2ms system time.  8.2ms system time.
   
 The next step to improve startup speed is to use a non-relocatable image  The next step to improve startup speed is to use a non-relocatable image
 @ref{Non-Relocatable Image Files}.  You can create this image with  (@xref{Non-Relocatable Image Files}).  You can create this image with
 @code{gforth -e "savesystem gforthnr.fi bye"} and later use it with  @code{gforth -e "savesystem gforthnr.fi bye"} and later use it with
 @code{gforth -i gforthnr.fi ...}.  This avoids the relocation overhead  @code{gforth -i gforthnr.fi ...}.  This avoids the relocation overhead
 and a part of the copy-on-write overhead.  The disadvantage is that the  and a part of the copy-on-write overhead.  The disadvantage is that the
 nonrelocatable image does not work if the OS gives Gforth a different  non-relocatable image does not work if the OS gives Gforth a different
 address for the dictionary, for whatever reason; so you better provide a  address for the dictionary, for whatever reason; so you better provide a
 fallback on a relocatable image.  @code{gforth-static -i gforthnr.fi -e  fallback on a relocatable image.  @code{gforth-static -i gforthnr.fi -e
 bye} takes about 15.3ms user and 7.5ms system time.  bye} takes about 15.3ms user and 7.5ms system time.
Line 1471  The disadvantages are that functionality Line 1455  The disadvantages are that functionality
 @code{ekey} is missing and that text interpretation (e.g., compiling)  @code{ekey} is missing and that text interpretation (e.g., compiling)
 now takes much longer. So, you should only use this method if there is  now takes much longer. So, you should only use this method if there is
 no significant text interpretation to perform (the script should be  no significant text interpretation to perform (the script should be
 compiled into the image, among other things).  @code{gforth-static -i  compiled into the image, amongst other things).  @code{gforth-static -i
 gforthnrnh.fi -e bye} takes about 2.1ms user and 6.1ms system time.  gforthnrnh.fi -e bye} takes about 2.1ms user and 6.1ms system time.
   
 @c ******************************************************************  @c ******************************************************************
Line 1480  gforthnrnh.fi -e bye} takes about 2.1ms Line 1464  gforthnrnh.fi -e bye} takes about 2.1ms
 @cindex Tutorial  @cindex Tutorial
 @cindex Forth Tutorial  @cindex Forth Tutorial
   
 This tutorial can be used with any ANS-compliant Forth; any places that  This tutorial can be used with any ANS-compliant Forth; any
 mention features specific to Gforth are marked as such and you can skip  Gforth-specific features are marked as such and you can skip them if you
 them, if you work with another Forth.  This tutorial does not explain  work with another Forth.  This tutorial does not explain all features of
 all features of Forth, just enough to get you started and give you some  Forth, just enough to get you started and give you some ideas about the
 ideas about the facilities available in Forth.  Read the rest of the  facilities available in Forth.  Read the rest of the manual and the
 manual and the standard when you are through this.  standard when you are through this.
   
 The intended way to use this tutorial is that you work through it while  The intended way to use this tutorial is that you work through it while
 sitting in front of the console, take a look at the examples and predict  sitting in front of the console, take a look at the examples and predict
Line 2628  happens when you remove the space). Line 2612  happens when you remove the space).
 However, this interpretive use of @code{s"} is quite restricted: the  However, this interpretive use of @code{s"} is quite restricted: the
 string exists only until the next call of @code{s"} (some Forth systems  string exists only until the next call of @code{s"} (some Forth systems
 keep more than one of these strings, but usually they still have a  keep more than one of these strings, but usually they still have a
 limited lifetime.  limited lifetime).
   
 @example  @example
 s" hello," s" world" .s  s" hello," s" world" .s
Line 2636  type Line 2620  type
 type  type
 @end example  @end example
   
 However, you can also use @code{s"} in a definition, and the resulting  You can also use @code{s"} in a definition, and the resulting
 strings then live forever (well, as long as the definition):  strings then live forever (well, for as long as the definition):
   
 @example  @example
 : foo s" hello," s" world" ;  : foo s" hello," s" world" ;
Line 2656  Implement @code{type ( addr u -- )}. Line 2640  Implement @code{type ( addr u -- )}.
   
 On many processors cells have to be aligned in memory, if you want to  On many processors cells have to be aligned in memory, if you want to
 access them with @code{@@} and @code{!} (and even if the processor does  access them with @code{@@} and @code{!} (and even if the processor does
 not require alignment, access to aligned cells are faster).  not require alignment, access to aligned cells is faster).
   
 @code{Create} aligns @code{here} (i.e., the place where the next  @code{Create} aligns @code{here} (i.e., the place where the next
 allocation will occur, and that the @code{create}d word points to).  allocation will occur, and that the @code{create}d word points to).
Line 3110  see foo Line 3094  see foo
 @end example  @end example
   
 However, there are some broken Forth systems where this does not always  However, there are some broken Forth systems where this does not always
 work, and therefore this practice has been declared non-standard in  work, and therefore this practice was been declared non-standard in
 1999.  1999.
 @c !! repair.fs  @c !! repair.fs
   
Line 6290  locals declarations for stack effect spe Line 6274  locals declarations for stack effect spe
 @menu  @menu
 * CREATE..DOES> applications::    * CREATE..DOES> applications::  
 * CREATE..DOES> details::         * CREATE..DOES> details::       
 * Advanced does> usage example::    * Advanced does> usage::        
 @end menu  @end menu
   
 @node CREATE..DOES> applications, CREATE..DOES> details, User-defined Defining Words, User-defined Defining Words  @node CREATE..DOES> applications, CREATE..DOES> details, User-defined Defining Words, User-defined Defining Words
Line 6340  DOES> ( n2 -- n1+n2 ) Line 6324  DOES> ( n2 -- n1+n2 )
 -2 curry+ 2-  -2 curry+ 2-
 @end example  @end example
   
 @node CREATE..DOES> details, Advanced does> usage example, CREATE..DOES> applications, User-defined Defining Words  @node CREATE..DOES> details, Advanced does> usage, CREATE..DOES> applications, User-defined Defining Words
 @subsubsection The gory details of @code{CREATE..DOES>}  @subsubsection The gory details of @code{CREATE..DOES>}
 @cindex @code{CREATE} ... @code{DOES>}, details  @cindex @code{CREATE} ... @code{DOES>}, details
   
Line 6398  CREATE name EXECUTE ( ... -- ... ) Line 6382  CREATE name EXECUTE ( ... -- ... )
   
 doc->body  doc->body
   
 @node Advanced does> usage example,  , CREATE..DOES> details, User-defined Defining Words  @node Advanced does> usage,  , CREATE..DOES> details, User-defined Defining Words
 @subsubsection Advanced does> usage example  @subsubsection Advanced does> usage
   
 The MIPS disassembler (@file{arch/mips/disasm.fs}) contains many words  
 for disassembling instructions, that follow a very repetetive scheme:  
   
 @example  
 :noname @var{disasm-operands} s" @var{inst-name}" type ;  
 @var{entry-num} cells @var{table} + !  
 @end example  
   
 Of course, this inspires the idea to factor out the commonalities to  
 allow a definition like  
   
 @example  
 @var{disasm-operands} @var{entry-num} @var{table} define-inst @var{inst-name}  
 @end example  
   
 The parameters @var{disasm-operands} and @var{table} are usually  
 correlated.  Moreover, there existed code defining instructions like  
 this:  
   
 @example  
 @var{entry-num} @var{inst-format} @var{inst-name}  
 @end example  
   
 This code comes from the assembler and resides in  
 @file{arch/mips/insts.fs}.  
   
 So I had to define the @var{inst-format} words that performed the scheme  
 above when executed.  At first I chose to use run-time code-generation:  
   
 @example  
 : @var{inst-format} ( entry-num "name" -- ; compiled code: addr w -- )  
   :noname Postpone @var{disasm-operands}  
   name Postpone sliteral Postpone type Postpone ;  
   swap cells @var{table} + ! ;  
 @end example  
   
 Note that this supplies the other two parameters of the scheme above.  
   
 An alternative would have been to write this using  
 @code{create}/@code{does>}:  
   
 @example  
 : @var{inst-format} ( entry-num "name" -- )  
   here name string, ( entry-num c-addr ) \ parse and save "name"  
   noname create , ( entry-num )  
   lastxt swap cells @var{table} + !  
 does> ( addr w -- )  
   \ disassemble instruction w at addr  
   @@ >r   
   @var{disasm-operands}  
   r> count type ;  
 @end example  
   
 Somehow the first solution is simpler, mainly because it's simpler to  
 shift a string from definition-time to use-time with @code{sliteral}  
 than with @code{string,} and friends.  
   
 I wrote a lot of words following this scheme and soon thought about  
 factoring out the commonalities among them.  Note that this uses a  
 two-level defining word, i.e., a word that defines ordinary defining  
 words.  
   
 This time a solution involving @code{postpone} and friends seemed more  
 difficult (try it as an exercise), so I decided to use a  
 @code{create}/@code{does>} word; since I was already at it, I also used  
 @code{create}/@code{does>} for the lower level (try using  
 @code{postpone} etc. as an exercise), resulting in the following  
 definition:  
   
 @example  
 : define-format ( disasm-xt table-xt -- )  
     \ define an instruction format that uses disasm-xt for  
     \ disassembling and enters the defined instructions into table  
     \ table-xt  
     create 2,  
 does> ( u "inst" -- )  
     \ defines an anonymous word for disassembling instruction inst,  
     \ and enters it as u-th entry into table-xt  
     2@@ swap here name string, ( u table-xt disasm-xt c-addr ) \ remember string  
     noname create 2,      \ define anonymous word  
     execute lastxt swap ! \ enter xt of defined word into table-xt  
 does> ( addr w -- )  
     \ disassemble instruction w at addr  
     2@@ >r ( addr w disasm-xt R: c-addr )  
     execute ( R: c-addr ) \ disassemble operands  
     r> count type ; \ print name   
 @end example  
   
 Note that the tables here (in contrast to above) do the @code{cells +}  
 by themselves (that's why you have to pass an xt).  This word is used in  
 the following way:  
   
 @example  
 ' @var{disasm-operands} ' @var{table} define-format @var{inst-format}  
 @end example  
   
 In terms of currying, this kind of two-level defining word provides the  
 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.,  
 the instruction to be disassembled.    
   
 Of course this did not quite fit all the instruction format names used  
 in @file{insts.fs}, so I had to define a few wrappers that conditioned  
 the parameters into the right form.  
   
 If you have trouble following this section, don't worry.  First, this is  
 involved and takes time (and probably some playing around) to  
 understand; second, this is the first two-level  
 @code{create}/@code{does>} word I have written in seventeen years of  
 Forth; and if I did not have @file{insts.fs} to start with, I may well  
 have elected to use just a one-level defining word (with some repeating  
 of parameters when using the defining word). So it is not necessary to  
 understand this, but it may improve your understanding of Forth.  
   
   
 @node Deferred words, Aliases, User-defined Defining Words, Defining Words  @node Deferred words, Aliases, User-defined Defining Words, Defining Words
Line 9011  suite that contains all instructions.  O Line 8882  suite that contains all instructions.  O
 easy.  For actual coding you can take a look at  easy.  For actual coding you can take a look at
 @file{arch/mips/disasm.fs} to get some ideas on how to use data for both  @file{arch/mips/disasm.fs} to get some ideas on how to use data for both
 the assembler and disassembler, avoiding redundancy and some potential  the assembler and disassembler, avoiding redundancy and some potential
 bugs.  You can also look at that file (and @pxref{Advanced does> usage  bugs.  You can also look at that file (and @pxref{Advanced does> usage})
 example}) to get ideas how to factor a disassembler.  to get ideas how to factor a disassembler.
   
 Start with the disassembler, because it's easier to reuse data from the  Start with the disassembler, because it's easier to reuse data from the
 disassembler for the assembler than the other way round.  disassembler for the assembler than the other way round.
Line 13264  gforthmi asm.fi asm.fs Line 13135  gforthmi asm.fi asm.fs
 @file{gforthmi} is implemented as a sh script and works like this: It  @file{gforthmi} is implemented as a sh script and works like this: It
 produces two non-relocatable images for different addresses and then  produces two non-relocatable images for different addresses and then
 compares them. Its output reflects this: first you see the output (if  compares them. Its output reflects this: first you see the output (if
 any) of the two Gforth invocations that produce the nonrelocatable image  any) of the two Gforth invocations that produce the non-relocatable image
 files, then you see the output of the comparing program: It displays the  files, then you see the output of the comparing program: It displays the
 offset used for data addresses and the offset used for code addresses;  offset used for data addresses and the offset used for code addresses;
 moreover, for each cell that cannot be represented correctly in the  moreover, for each cell that cannot be represented correctly in the
Line 13301  instructions. Line 13172  instructions.
 There are a few wrinkles: After processing the passed @i{options}, the  There are a few wrinkles: After processing the passed @i{options}, the
 words @code{savesystem} and @code{bye} must be visible. A special doubly  words @code{savesystem} and @code{bye} must be visible. A special doubly
 indirect threaded version of the @file{gforth} executable is used for  indirect threaded version of the @file{gforth} executable is used for
 creating the nonrelocatable images; you can pass the exact filename of  creating the non-relocatable images; you can pass the exact filename of
 this executable through the environment variable @code{GFORTHD}  this executable through the environment variable @code{GFORTHD}
 (default: @file{gforth-ditc}); if you pass a version that is not doubly  (default: @file{gforth-ditc}); if you pass a version that is not doubly
 indirect threaded, you will not get a fully relocatable image, but a  indirect threaded, you will not get a fully relocatable image, but a
Removed from v.1.61  
changed lines
  Added in v.1.62

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