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). |