Diff for /gforth/doc/gforth.ds between versions 1.31 and 1.32

version 1.31, 1999/05/15 20:00:22 version 1.32, 1999/05/16 17:13:24
Line 156  Goals of Gforth Line 156  Goals of Gforth
   
 Gforth Environment  Gforth Environment
   
 * Invoking Gforth::  * Invoking Gforth::             Getting in
 * Leaving Gforth::  * Leaving Gforth::              Getting out
 * Command-line editing::  * Command-line editing::        
 * Upper and lower case::  * Upper and lower case::
 * Environment variables::  * Environment variables::       ..that affect how Gforth starts up
 * Gforth Files::  * Gforth Files::                What gets installed and where
   
 An Introduction to ANS Forth  An Introduction to ANS Forth
   
Line 206  Arithmetic Line 206  Arithmetic
 * Bitwise operations::            * Bitwise operations::          
 * Double precision::            Double-cell integer arithmetic  * Double precision::            Double-cell integer arithmetic
 * Numeric comparison::  * Numeric comparison::
 * Mixed precision::             operations with single and double-cell integers  * Mixed precision::             Operations with single and double-cell integers
 * Floating Point::                * Floating Point::              
   
 Stack Manipulation  Stack Manipulation
Line 219  Stack Manipulation Line 219  Stack Manipulation
   
 Memory  Memory
   
 * Reserving Data Space::  * Memory model::                
 * Memory Access::        * Dictionary allocation::       
 * Address Arithmetic::            * Heap Allocation::             
 * Memory Blocks::  * Memory Access::               
 * Dynamic Allocation::          * Address arithmetic::          
   * Memory Blocks::               
   
 Control Structures  Control Structures
   
 * Selection::                     * Selection::                   IF.. ELSE.. ENDIF
 * Simple Loops::                  * Simple Loops::                BEGIN..
 * Counted Loops::                 * Counted Loops::               DO
 * Arbitrary control structures::    * Arbitrary control structures::
 * Calls and returns::             * Calls and returns::
 * Exception Handling::            * Exception Handling::          
   
 Defining Words  Defining Words
   
 * Simple Defining Words::         * Simple Defining Words::       Variables, values and constants
 * Colon Definitions::             * Colon Definitions::
 * User-defined Defining Words::    * User-defined Defining Words::
 * Supplying names::               * Supplying names::
 * Interpretation and Compilation Semantics::    * Interpretation and Compilation Semantics::
   
 The Text Interpreter  The Text Interpreter
   
Line 265  Files Line 266  Files
   
 Other I/O  Other I/O
   
 * Simple numeric output::  * Simple numeric output::       Predefined formats
 * Formatted numeric output::  * Formatted numeric output::    Formatted (pictured) output
 * String Formats::  * String Formats::              How Forth stores strings in memory
 * Displaying characters and strings::  * Displaying characters and strings:: Other stuff
 * Input::  * Input::                       Input
   
 Programming Tools  Programming Tools
   
Line 410  Image Files Line 411  Image Files
   
 * Image Licensing Issues::      Distribution terms for images.  * Image Licensing Issues::      Distribution terms for images.
 * Image File Background::       Why have image files?  * Image File Background::       Why have image files?
 * Non-Relocatable Image Files::  don't always work.  * Non-Relocatable Image Files::   don't always work.
 * Data-Relocatable Image Files::  are better.  * Data-Relocatable Image Files::  are better.
 * Fully Relocatable Image Files::  better yet.  * Fully Relocatable Image Files:: better yet.
 * Stack and Dictionary Sizes::  Setting the default sizes for an image.  * Stack and Dictionary Sizes::  Setting the default sizes for an image.
 * Running Image Files::         @code{gforth -i @var{file}} or @var{file}.  * Running Image Files::         @code{gforth -i @i{file}} or @i{file}.
 * Modifying the Startup Sequence::  and turnkey applications.  * Modifying the Startup Sequence::  and turnkey applications.
   
 Fully Relocatable Image Files  Fully Relocatable Image Files
Line 2527  doc-sm/rem Line 2528  doc-sm/rem
 @xref{Number Conversion} for the rules used by the text interpreter for  @xref{Number Conversion} for the rules used by the text interpreter for
 recognising floating-point numbers.  recognising floating-point numbers.
   
 @cindex angles in trigonometric operations  Gforth has a separate floating point
 @cindex trigonometric operations  
 Angles in floating point operations are given in radians (a full circle  
 has 2 pi radians). Gforth has a separate floating point  
 stack, but the documentation uses the unified notation.  stack, but the documentation uses the unified notation.
   
 @cindex floating-point arithmetic, pitfalls  @cindex floating-point arithmetic, pitfalls
Line 2564  doc-fln Line 2562  doc-fln
 doc-flnp1  doc-flnp1
 doc-flog  doc-flog
 doc-falog  doc-falog
   doc-f2*
   doc-f2/
   doc-1/f
   doc-precision
   doc-set-precision
   
   @cindex angles in trigonometric operations
   @cindex trigonometric operations
   Angles in floating point operations are given in radians (a full circle
   has 2 pi radians).
   
 doc-fsin  doc-fsin
 doc-fcos  doc-fcos
 doc-fsincos  doc-fsincos
Line 2580  doc-facosh Line 2589  doc-facosh
 doc-fatanh  doc-fatanh
 doc-pi  doc-pi
   
 doc-f2*  @cindex equality of floats
 doc-f2/  @cindex floating-point comparisons
 doc-1/f  
 doc-precision  
 doc-set-precision  
   
 One particular problem with floating-point arithmetic is that comparison  One particular problem with floating-point arithmetic is that comparison
 for equality often fails when you would expect it to succeed.  For this  for equality often fails when you would expect it to succeed.  For this
 reason approximate equality is often preferred (but you still have to  reason approximate equality is often preferred (but you still have to
Line 2631  A floating point stack -- for floating p Line 2636  A floating point stack -- for floating p
 @cindex return stack  @cindex return stack
 @item  @item
 A return stack -- for storing the return addresses of colon  A return stack -- for storing the return addresses of colon
 definitions and other data.  definitions and other (non-FP) data.
   
 @cindex locals stack  @cindex locals stack
 @item  @item
 A locals stack for storing local variables.  A locals stack for storing local variables.
 @end itemize  @end itemize
   
 Whilst every sane Forth has a separate floating-point stack, it is not  
 strictly required; an ANS Forth system could theoretically keep  
 floating-point numbers on the data stack. As an additional difficulty,  
 you don't know how many cells a floating-point number takes. It is  
 reportedly possible to write words in a way that they work also for a  
 unified stack model, but we do not recommend trying it. Instead, just  
 say that your program has an environmental dependency on a separate  
 floating-point stack.  
   
 doc-floating-stack  
   
 @cindex return stack and locals  
 @cindex locals and return stack  
 A Forth system is allowed to keep local variables on the  
 return stack. This is reasonable, as local variables usually eliminate  
 the need to use the return stack explicitly. So, if you want to produce  
 a standard compliant program and you are using local variables in a  
 word, forget about return stack manipulations in that word (refer to the  
 standard document for the exact rules).  
   
 @menu  @menu
 * Data stack::                    * Data stack::                  
 * Floating point stack::          * Floating point stack::        
Line 2695  doc-2rot Line 2680  doc-2rot
 @cindex floating-point stack manipulation words  @cindex floating-point stack manipulation words
 @cindex stack manipulation words, floating-point stack  @cindex stack manipulation words, floating-point stack
   
   Whilst every sane Forth has a separate floating-point stack, it is not
   strictly required; an ANS Forth system could theoretically keep
   floating-point numbers on the data stack. As an additional difficulty,
   you don't know how many cells a floating-point number takes. It is
   reportedly possible to write words in a way that they work also for a
   unified stack model, but we do not recommend trying it. Instead, just
   say that your program has an environmental dependency on a separate
   floating-point stack.
   
   doc-floating-stack
   
 doc-fdrop  doc-fdrop
 doc-fnip  doc-fnip
 doc-fdup  doc-fdup
Line 2709  doc-frot Line 2705  doc-frot
 @cindex return stack manipulation words  @cindex return stack manipulation words
 @cindex stack manipulation words, return stack  @cindex stack manipulation words, return stack
   
   @cindex return stack and locals
   @cindex locals and return stack
   A Forth system is allowed to keep local variables on the
   return stack. This is reasonable, as local variables usually eliminate
   the need to use the return stack explicitly. So, if you want to produce
   a standard compliant program and you are using local variables in a
   word, forget about return stack manipulations in that word (refer to the
   standard document for the exact rules).
   
 doc->r  doc->r
 doc-r>  doc-r>
 doc-r@  doc-r@
Line 2728  doc-2rdrop Line 2733  doc-2rdrop
 @cindex stack pointer manipulation words  @cindex stack pointer manipulation words
   
 doc-sp0  doc-sp0
 doc-s0  
 doc-sp@  doc-sp@
 doc-sp!  doc-sp!
 doc-fp0  doc-fp0
 doc-fp@  doc-fp@
 doc-fp!  doc-fp!
 doc-rp0  doc-rp0
 doc-r0  
 doc-rp@  doc-rp@
 doc-rp!  doc-rp!
 doc-lp0  doc-lp0
 doc-l0  
 doc-lp@  doc-lp@
 doc-lp!  doc-lp!
   
Line 2747  doc-lp! Line 2749  doc-lp!
 @section Memory  @section Memory
 @cindex memory words  @cindex memory words
   
 @cindex dictionary  @menu
 Forth definitions are organised in memory structures that are  * Memory model::                
 collectively called the @dfn{dictionary}. The dictionary can be  * Dictionary allocation::       
 considered as three logical memory regions:  * Heap Allocation::             
   * Memory Access::               
   * Address arithmetic::          
   * Memory Blocks::               
   @end menu
   
 @itemize @bullet  @node Memory model, Dictionary allocation, Memory, Memory
 @item  @subsection ANS Forth and Gforth memory models
 @cindex code space  
 @cindex code dictionary  @c The ANS Forth description is a mess (e.g., is the heap part of
 Code space, also known as the @dfn{code dictionary}.  @c the dictionary?), so let's not stick to closely with it.
 @item  
 @cindex name space  ANS Forth considers a Forth system as consisting of several memories, of
 @cindex name dictionary  which only @dfn{data space} is managed and accessible with the memory
 Name space, also known as the @dfn{name dictionary}@footnote{Sometimes,  words.  Memory not necessarily in data space includes the stacks, the
 the term @dfn{dictionary} is used simply to refer to the name  code (called code space) and the headers (called name space). In Gforth
 dictionary, because it is the one region that is used for looking up  everything is in data space, but the code for the primitives is usually
 names, just as you would in a conventional dictionary.}.  read-only.
 @item  
 @cindex data space  Data space is divided into a number of areas: The (data space portion of
 Data space  the) dictionary@footnote{Sometimes, the term @dfn{dictionary} is used to
 @end itemize  refer to the search data structure embodied in word lists and headers,
   because it is used for looking up names, just as you would in a
   conventional dictionary.}, the heap, and a number of system-allocated
   buffers.
   
   In ANS Forth data space is also divided into contiguous regions.  You
   can only use address arithmetic within a contiguous region, not between
   them.  Usually each allocation gives you one contiguous region, but the
   Dictionary allocation words have additional rules (@pxref{Dictionary
   allocation}).
   
   Gforth provides one big address space, and address arithmetic can be
   performed between any addresses. However, in the dictionary headers or
   code are interleaved with data, so almost the only contiguous data space
   regions there are those described by ANS Forth as contiguous; but you
   can be sure that the dictionary is allocated towards increasing
   addresses even between contiguous regions.  The memory order of
   allocations in the heap is platform-dependent (and possibly different
   from one run to the next).
   
   @subsubsection ANS Forth dictionary details
   
   @c !! I have deleted some of the stuff this section refers to - anton
   
   This section is just informative, you can skip it if you are in a hurry.
   
 When you create a colon definition, the text interpreter compiles the  When you create a colon definition, the text interpreter compiles the
 code for the definition into the code dictionary and compiles the name  code for the definition into the code space and compiles the name
 of the definition into the name dictionary, together with other  of the definition into the header space, together with other
 information about the definition (such as its execution token).  information about the definition (such as its execution token).
   
 When you create a variable, the execution of @code{variable} will  When you create a variable, the execution of @code{variable} will
 compile some code, assign once cell in data space, and compile the name  compile some code, assign one cell in data space, and compile the name
 of the variable into the name dictionary.  of the variable into the header space.
   
 @cindex memory regions - relationship between them  @cindex memory regions - relationship between them
 ANS Forth does not specify the relationship between the three memory  ANS Forth does not specify the relationship between the three memory
Line 2801  For a Forth system that runs from RAM un Line 2831  For a Forth system that runs from RAM un
 system, it can be convenient to interleave name, code and data spaces in  system, it can be convenient to interleave name, code and data spaces in
 a single contiguous memory region. This organisation can be  a single contiguous memory region. This organisation can be
 memory-efficient (for example, because the relationship between the name  memory-efficient (for example, because the relationship between the name
 dictionary entry and the associated code dictionary entry can be  dictionary entry and the associated code space entry can be
 implicit, rather than requiring an explicit memory pointer to reference  implicit, rather than requiring an explicit memory pointer to reference
 from the name dictionary and the code dictionary). This is the  from the header space and the code space). This is the
 organisation used by Gforth, as this example@footnote{The addresses  organisation used by Gforth, as this example@footnote{The addresses
 in the example have been truncated to fit it onto the page, and the  in the example have been truncated to fit it onto the page, and the
 addresses and data shown will not match the output from your system} shows:  addresses and data shown will not match the output from your system} shows:
Line 2825  For a high-performance system running on Line 2855  For a high-performance system running on
 modified Harvard architecture (one that has a unified main memory but  modified Harvard architecture (one that has a unified main memory but
 separate instruction and data caches), it is desirable to separate  separate instruction and data caches), it is desirable to separate
 processor instructions from processor data. This encourages a high cache  processor instructions from processor data. This encourages a high cache
 density and therefore a high cache hit rate. The Forth code dictionary  density and therefore a high cache hit rate. The Forth code space
 is not necessarily made up entirely of processor instructions; its  is not necessarily made up entirely of processor instructions; its
 nature is dependent upon the Forth implementation.   nature is dependent upon the Forth implementation. 
   
Line 2841  accessible. Line 2871  accessible.
 Microprocessors exist that run Forth (or many of the primitives required  Microprocessors exist that run Forth (or many of the primitives required
 to implement the Forth virtual machine efficiently) directly. On these  to implement the Forth virtual machine efficiently) directly. On these
 processors, the relationship between name, code and data spaces may be  processors, the relationship between name, code and data spaces may be
 imposed as a side-effect of the microarchitecture of the processor.  imposed as a side-effect of the architecture of the processor.
   
 @item  @item
 A Forth compiler that executes from ROM on an embedded system needs its  A Forth compiler that executes from ROM on an embedded system needs its
Line 2851  space can be mapped to a RAM area. Line 2881  space can be mapped to a RAM area.
 @item   @item 
 A Forth compiler that runs on an embedded system may have a requirement  A Forth compiler that runs on an embedded system may have a requirement
 for a small memory footprint. On such a system it can be useful to  for a small memory footprint. On such a system it can be useful to
 separate the name space from the data and code spaces; once the  separate the header space from the data and code spaces; once the
 application has been compiled, the name dictionary is no longer  application has been compiled, the header space is no longer
 required@footnote{more strictly speaking, most applications can be  required@footnote{more strictly speaking, most applications can be
 designed so that this is the case}. The name dictionary can be deleted  designed so that this is the case}. The header space can be deleted
 entirely, or could be stored in memory on a remote @i{host} system for  entirely, or could be stored in memory on a remote @i{host} system for
 debug and development purposes. In the latter case, the compiler running  debug and development purposes. In the latter case, the compiler running
 on the @i{target} system could implement a protocol across a  on the @i{target} system could implement a protocol across a
 communication link that would allow it to interrogate the name dictionary.  communication link that would allow it to interrogate the header space.
 @end itemize  @end itemize
   
 @menu  
 * Reserving Data Space::  
 * Memory Access::  
 * Address Arithmetic::  
 * Memory Blocks::  
 * Dynamic Allocation::  
 @end menu  
   
   @node Dictionary allocation, Heap Allocation, Memory model, Memory
 @node Reserving Data Space, Memory Access, Memory, Memory  @subsection Dictionary allocation
 @subsection Reserving Data Space  
 @cindex reserving data space  @cindex reserving data space
 @cindex data space - reserving some  @cindex data space - reserving some
   
 @cindex data space pointer - contiguous regions  Dictionary allocation is a stack-oriented allocation scheme, i.e., if
 Data space may be reserved as individual chars or cells or in contiguous  you want to deallocate X, you also deallocate everything
 regions. These are the rules for reserving contiguous regions in a  allocated after X.
 Standard (i.e., portable) way:  
 @itemize @bullet  The allocations using the words below are contiguous and grow the region
 @item  towards increasing addresses.  Other words that allocate dictionary
 The value of the data-space pointer, @code{here}, always defines the  memory of any kind (i.e., defining words including @code{:noname}) end
 beginning of a contiguous region of data space.  the contiguous region and start a new one.
   
 @item  In ANS Forth only @code{create}d words are guaranteed to produce an
 @code{CREATE} establishes the beginning of a contiguous region of data  address that is the start of the following contiguous region.  In
 space (the @code{CREATE}d definition returns the initial address of the  particular, the cell allocated by @code{variable} is not guaranteed to
 region).  be contiguous with following @code{allot}ed memory.
   
 @item  You can deallocate memory by using @code{allot} with a negative argument
 @code{variable} does @i{not} establish the beginning of a contiguous  (with some restrictions, see @code{allot}). For larger deallocations use
 region in data space; @code{variable} followed by @code{allot} is not  @code{marker}.
 guaranteed to allocate data space region that is contiguous with the  
 storage allocated by @code{variable}. Instead, use @code{create} --  
 @xref{Simple Defining Words} for examples.  
   
 @item  
 Successive calls to @code{allot}, @code{,} (comma), @code{2,} (2-comma),  
 @code{c,} (c-comma) and @code{align} reserve a single contiguous region  
 in data space. The contiguity of the region is interrupted by compiling  
 (or removing) definitions from the dictionary.  
   
 @item  
 The most recently reserved contiguous region may be released by calling  
 @code{allot} with a negative argument, provided that the region has not  
 been interrupted by compiling (or removing) definitions from the  
 dictionary.  
 @end itemize  
   
 @cindex data space pointer - alignment  
 These factors affect the alignment of @code{here}, the data  
 space pointer:  
   
 @itemize @bullet  
 @item  
 If the data-space pointer is aligned@footnote{In ANS Forth-speak,  
 @i{aligned} implictly means @code{CELL}-aligned.} before an  
 @code{allot}, and a whole number of characters are reserved or released, it  
 will remain aligned after the @code{allot}.  
   
 @item  
 If the data-space pointer is character-aligned before an @code{allot},  
 and a whole number of cells are reserved or released, it will remain  
 character-aligned after the @code{allot}.  
   
 @item  
 The initial contents of data space reserved using @code{allot} is  
 undefined.  
   
 @item  
 Definitions created by @code{create}, @code{variable}, @code{2variable}  
 return aligned addresses.  
   
 @item  
 After a definition is compiled or @code{align} is executed, the data  
 space pointer is guaranteed to be aligned.  
 @end itemize  
   
 doc-here  doc-here
 doc-unused  doc-unused
Line 2949  doc-2, Line 2927  doc-2,
 doc-udp  doc-udp
 doc-uallot  doc-uallot
   
   Memory accesses have to be aligned (@pxref{Address arithmetic}). So of
   course you should allocate memory in an aligned way, too. I.e., before
   allocating allocating a cell, @code{here} must be cell-aligned, etc.
   The words below align @code{here} if it is not already.  Basically it is
   only already aligned for a type, if the last allocation was a multiple
   of the size of this type and if @code{here} was aligned for this type
   before.
   
   After freshly @code{create}ing a word, @code{here} is @code{align}ed in
   ANS Forth (@code{maxalign}ed in Gforth).
   
   doc-align
   doc-falign
   doc-sfalign
   doc-dfalign
   doc-maxalign
   doc-cfalign
   
   
   @node Heap Allocation, Memory Access, Dictionary allocation, Memory
   @subsection Heap allocation
   @cindex heap allocation
   @cindex dynamic allocation of memory
   @cindex memory-allocation word set
   
   Heap allocation supports deallocation of allocated memory in any
   order. Dictionary allocation is not affected by it (i.e., it does not
   end a contiguous region). In Gforth, these words are implemented using
   the standard C library calls malloc(), free() and resize().
   
   doc-allocate
   doc-free
   doc-resize
   
   
 @node Memory Access, Address Arithmetic, Reserving Data Space, Memory  @node Memory Access, Address arithmetic, Heap Allocation, Memory
 @subsection Memory Access  @subsection Memory Access
 @cindex memory access words  @cindex memory access words
   
Line 2968  doc-sf! Line 2980  doc-sf!
 doc-df@  doc-df@
 doc-df!  doc-df!
   
 @node Address Arithmetic, Memory Blocks, Memory Access, Memory  @node Address arithmetic, Memory Blocks, Memory Access, Memory
 @subsection Address Arithmetic  @subsection Address arithmetic
 @cindex address arithmetic words  @cindex address arithmetic words
   
   Address arithmetic is the foundation on which data structures like
   arrays, records (@pxref{Structures}) and objects (@pxref{Object-oriented
   Forth}) are built.
   
 ANS Forth does not specify the sizes of the data types. Instead, it  ANS Forth does not specify the sizes of the data types. Instead, it
 offers a number of words for computing sizes and doing address  offers a number of words for computing sizes and doing address
 arithmetic. Address arithmetic is performed in terms of address units  arithmetic. Address arithmetic is performed in terms of address units
Line 3008  doc-char+ Line 3024  doc-char+
 doc-cells  doc-cells
 doc-cell+  doc-cell+
 doc-cell  doc-cell
 doc-align  
 doc-aligned  doc-aligned
 doc-floats  doc-floats
 doc-float+  doc-float+
 doc-float  doc-float
 doc-falign  
 doc-faligned  doc-faligned
 doc-sfloats  doc-sfloats
 doc-sfloat+  doc-sfloat+
 doc-sfalign  
 doc-sfaligned  doc-sfaligned
 doc-dfloats  doc-dfloats
 doc-dfloat+  doc-dfloat+
 doc-dfalign  
 doc-dfaligned  doc-dfaligned
 doc-maxalign  
 doc-maxaligned  doc-maxaligned
 doc-cfalign  
 doc-cfaligned  doc-cfaligned
 doc-address-unit-bits  doc-address-unit-bits
   
 @node Memory Blocks, Dynamic Allocation, Address Arithmetic, Memory  @node Memory Blocks,  , Address arithmetic, Memory
 @subsection Memory Blocks  @subsection Memory Blocks
 @cindex memory block words  @cindex memory block words
 @cindex character strings - moving and copying  @cindex character strings - moving and copying
Line 3038  Memory blocks often represent character Line 3048  Memory blocks often represent character
 for ways of storing character strings in memory. @xref{Displaying  for ways of storing character strings in memory. @xref{Displaying
 characters and strings} for other string-processing words.  characters and strings} for other string-processing words.
   
 Some of these words work on address units (increments of @code{CELL}),  Some of these words work on address units. Others work on character
 and expect a @code{CELL}-aligned address. Others work on character units  units (increments of @code{CHAR}), and expect a @code{CHAR}-aligned
 (increments of @code{CHAR}), and expect a @code{CHAR}-aligned  address. Choose the correct operation depending upon your data type.
 address. Choose the correct operation depending upon your data type. If  
 you are moving a block of memory (for example, a region reserved by  
 @code{allot}) it is safe to use @code{move}, and it should be faster  
 than using @code{cmove}. If you are moving (for example) a string  
 compiled using @code{S"}, it is not portable to use @code{move}; the  
 alignment of the string in memory could change, and the relationship  
 between @code{CELL} and @code{CHAR} could change.  
   
 When copying characters between overlapping memory regions, choose  When copying characters between overlapping memory regions, choose
 carefully between @code{cmove} and @code{cmove>}.  carefully between @code{cmove} and @code{cmove>}.
Line 3072  doc-/string Line 3075  doc-/string
   
 @comment TODO examples  @comment TODO examples
   
 @node Dynamic Allocation, ,Memory Blocks, Memory  
 @subsection Dynamic Allocation of Memory  
 @cindex dynamic allocation of memory  
 @cindex memory-allocation word set  
   
 The ANS Forth memory-allocation word set allows memory regions to be  
 dynamically assigned, resized and released without affecting the data  
 space pointer. In Gforth, these words are implemented using  
 the standard C library calls malloc(), free() and resize().  
   
 doc-allocate  
 doc-free  
 doc-resize  
   
   
 @node Control Structures, Defining Words, Memory, Words  @node Control Structures, Defining Words, Memory, Words
 @section Control Structures  @section Control Structures
Line 3799  assembler or a #define in C) only exists Line 3788  assembler or a #define in C) only exists
 executable program the constant has been translated into an absolute  executable program the constant has been translated into an absolute
 number and, unless you are using a symbolic debugger, it's impossible to  number and, unless you are using a symbolic debugger, it's impossible to
 know what abstract thing that number represents. In Forth a constant has  know what abstract thing that number represents. In Forth a constant has
 an entry in the name dictionary and remains there after the code that  an entry in the header space and remains there after the code that
 uses it has been defined. In fact, it must remain in the dictionary  uses it has been defined. In fact, it must remain in the dictionary
 since it has run-time duties to perform. For example:  since it has run-time duties to perform. For example:
   
Line 5063  doc-[REPEAT] Line 5052  doc-[REPEAT]
 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 name dictionary entries to  Named words have information stored in their header space entries to
 indicate any non-default semantics (@pxref{Interpretation and  indicate any non-default semantics (@pxref{Interpretation and
 Compilation Semantics}). The semantics can be modified, using  Compilation Semantics}). The semantics can be modified, using
 @code{immediate} and/or @code{compile-only}, at the time that the words  @code{immediate} and/or @code{compile-only}, at the time that the words
 are defined. Unnamed words have (by definition) no name dictionary  are defined. Unnamed words have (by definition) no header space
 entry, and therefore must have default semantics.  entry, and therefore must have default semantics.
   
 Named words have interpretation and compilation semantics. Unnamed words  Named words have interpretation and compilation semantics. Unnamed words
Line 5158  doc-name>string Line 5147  doc-name>string
 @node Word Lists, Environmental Queries, Tokens for Words, Words  @node Word Lists, Environmental Queries, Tokens for Words, Words
 @section Word Lists  @section Word Lists
 @cindex word lists  @cindex word lists
 @cindex name dictionary  @cindex header space
   
 @cindex wid  @cindex wid
 All definitions other than those created by @code{:noname} have an entry  All definitions other than those created by @code{:noname} have an entry
 in the name dictionary. The name dictionary is fragmented into a number  in the header space. The header space is fragmented into a number
 of parts, called @dfn{word lists}. A word list is identified by a  of parts, called @dfn{word lists}. A word list is identified by a
 cell-sized word list identifier (@i{wid}) in much the same way as a  cell-sized word list identifier (@i{wid}) in much the same way as a
 file is identified by a file handle. The numerical value of the wid has  file is identified by a file handle. The numerical value of the wid has
Line 5176  word list called @code{FORTH-WORDLIST}. Line 5165  word list called @code{FORTH-WORDLIST}.
   
 @cindex search order stack  @cindex search order stack
 Forth maintains a stack of word lists, representing the @dfn{search  Forth maintains a stack of word lists, representing the @dfn{search
 order}.  When the name dictionary is searched (for example, when  order}.  When the header space is searched (for example, when
 attempting to find a word's execution token during compilation), only  attempting to find a word's execution token during compilation), only
 those word lists that are currently in the search order are  those word lists that are currently in the search order are
 searched. The most recently-defined word in the word list at the top of  searched. The most recently-defined word in the word list at the top of
Line 5238  Here are some reasons for using multiple Line 5227  Here are some reasons for using multiple
   
 @itemize @bullet  @itemize @bullet
 @item  @item
 To improve compilation speed by reducing the number of name dictionary  To improve compilation speed by reducing the number of header space
 entries that must be searched. This is achieved by creating a new  entries that must be searched. This is achieved by creating a new
 word list that contains all of the definitions that are used in the  word list that contains all of the definitions that are used in the
 definition of a Forth system but which would not usually be used by  definition of a Forth system but which would not usually be used by
Line 5316  ANS Forth introduced the idea of ``envir Line 5305  ANS Forth introduced the idea of ``envir
 for a program running on a system to determine certain characteristics of the system.  for a program running on a system to determine certain characteristics of the system.
 The Standard specifies a number of strings that might be recognised by a system.  The Standard specifies a number of strings that might be recognised by a system.
   
 The Standard requires that the name space used for environmental queries  The Standard requires that the header space used for environmental queries
 be distinct from the name space used for definitions.  be distinct from the header space used for definitions.
   
 Typically, environmental queries are supported by creating a set of  Typically, environmental queries are supported by creating a set of
 definitions in a word list that is @i{only} used during environmental  definitions in a word list that is @i{only} used during environmental
Line 6979  possibly John Hayes). A version of this Line 6968  possibly John Hayes). A version of this
 @cindex structures using address arithmetic  @cindex structures using address arithmetic
 If we want to use a structure containing several fields, we could simply  If we want to use a structure containing several fields, we could simply
 reserve memory for it, and access the fields using address arithmetic  reserve memory for it, and access the fields using address arithmetic
 (@pxref{Address Arithmetic}). As an example, consider a structure with  (@pxref{Address arithmetic}). As an example, consider a structure with
 the following fields  the following fields
   
 @table @code  @table @code
Line 9125  necessary. Line 9114  necessary.
   
 @item addressing a region not inside the various data spaces of the forth system:  @item addressing a region not inside the various data spaces of the forth system:
 @cindex Invalid memory address  @cindex Invalid memory address
 The stacks, code space and name space are accessible. Machine code space is  The stacks, code space and header space are accessible. Machine code space is
 typically readable. Accessing other addresses gives results dependent on  typically readable. Accessing other addresses gives results dependent on
 the operating system. On decent systems: @code{-9 throw} (Invalid memory  the operating system. On decent systems: @code{-9 throw} (Invalid memory
 address).  address).

Removed from v.1.31  
changed lines
  Added in v.1.32


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