version 1.26, 1999/03/23 20:24:21
|
version 1.27, 1999/03/29 22:52:31
|
Line 71 Copyright @copyright{} 1995-1999 Free So
|
Line 71 Copyright @copyright{} 1995-1999 Free So
|
@center Jens Wilke |
@center Jens Wilke |
@center Neal Crook |
@center Neal Crook |
@sp 3 |
@sp 3 |
@center This manual is permanently under construction and was last updated on 23-Mar-1999 |
@center This manual is permanently under construction and was last updated on 26-Mar-1999 |
|
|
@comment The following two commands start the copyright page. |
@comment The following two commands start the copyright page. |
@page |
@page |
Line 188 Stack Manipulation
|
Line 188 Stack Manipulation
|
|
|
Memory |
Memory |
|
|
|
* Reserving Data Space:: |
* Memory Access:: |
* Memory Access:: |
* Address arithmetic:: |
* Address Arithmetic:: |
* Memory Blocks:: |
* Memory Blocks:: |
|
* Dynamic Allocation:: |
|
|
Control Structures |
Control Structures |
|
|
Line 215 The Text Interpreter
|
Line 217 The Text Interpreter
|
* Interpret/Compile states:: |
* Interpret/Compile states:: |
* Literals:: |
* Literals:: |
* Interpreter Directives:: |
* Interpreter Directives:: |
|
* Input Sources:: |
|
|
Word Lists |
Word Lists |
|
|
Line 385 Image Files
|
Line 388 Image Files
|
|
|
Fully Relocatable Image Files |
Fully Relocatable Image Files |
|
|
* gforthmi:: The normal way |
* gforthmi:: The normal way |
* cross.fs:: The hard way |
* cross.fs:: The hard way |
|
|
Engine |
Engine |
Line 999 your system, but the effect is the same;
|
Line 1002 your system, but the effect is the same;
|
detects an error, it discards any remaining text on a line, resets |
detects an error, it discards any remaining text on a line, resets |
certain internal state and prints an error message. |
certain internal state and prints an error message. |
|
|
The text interpreter waits for you to press carrage-return, and then |
The text interpreter waits for you to press carriage-return, and then |
processes your input line. Starting at the beginning of the line, it |
processes your input line. Starting at the beginning of the line, it |
breaks the line into groups of characters separated by spaces. For each |
breaks the line into groups of characters separated by spaces. For each |
group of characters in turn, it makes two attempts to do something: |
group of characters in turn, it makes two attempts to do something: |
Line 1560 non-immediate word:
|
Line 1563 non-immediate word:
|
|
|
The word @code{immediate} after the definition of @code{show-state-now} |
The word @code{immediate} after the definition of @code{show-state-now} |
makes that word an immediate word. These definitions introduce a new |
makes that word an immediate word. These definitions introduce a new |
word: @code{@@} (pronounced ''at''). This word fetches the value of a |
word: @code{@@} (pronounced ``fetch''). This word fetches the value of a |
variable, and leaves it on the stack. Therefore, the behaviour of |
variable, and leaves it on the stack. Therefore, the behaviour of |
@code{show-state} is to print a number that represents the current value |
@code{show-state} is to print a number that represents the current value |
of @code{state}. |
of @code{state}. |
Line 2151 doc-abs
|
Line 2154 doc-abs
|
doc-min |
doc-min |
doc-max |
doc-max |
doc-d>s |
doc-d>s |
|
doc-floored |
|
|
@node Bitwise operations, Double precision, Single precision, Arithmetic |
@node Bitwise operations, Double precision, Single precision, Arithmetic |
@subsection Bitwise operations |
@subsection Bitwise operations |
Line 2452 doc-lp!
|
Line 2456 doc-lp!
|
@section Memory |
@section Memory |
@cindex memory words |
@cindex memory words |
|
|
|
@cindex dictionary |
|
Forth definitions are organised in memory structures that are |
|
collectively called the @var{dictionary}. The dictionary can be |
|
considered as three logical memory regions: |
|
|
|
@itemize @bullet |
|
@item |
|
@cindex code space |
|
@cindex code dictionary |
|
Code space, also known as the @var{code dictionary}. |
|
@item |
|
@cindex name space |
|
@cindex name dictionary |
|
Name space, also known as the @var{name dictionary}@footnote{Sometimes, |
|
people use the term @var{dictionary} to simply refer to the name |
|
dictionary, because it is the one region that is used for looking up |
|
names, just as you would in a conventional dictionary.}. |
|
@item |
|
@cindex data space |
|
Data space |
|
@end itemize |
|
|
|
When you create a colon definition, the text interpreter compiles |
|
the definition itself into the code dictionary and compiles the name |
|
of the definition into the name dictionary, together with other |
|
information about the definition (such as its execution token). |
|
|
|
When you create a variable, the execution of @code{variable} will |
|
compile some code, assign once cell in data space, and compile the name |
|
of the variable into the name dictionary. |
|
|
|
@cindex memory regions - relationship between them |
|
ANS Forth does not specify the relationship between the three memory |
|
regions, and specifies that a Standard program must not access code or |
|
data space directly -- it may only access data space directly. In |
|
addition, the Standard defines what relationships you may and may not |
|
rely on when allocating regions in data space. These constraints are |
|
simply a reflection of the many diverse techniques that are used to |
|
implement Forth systems; understanding and following the requirements of |
|
the Standard allows you to write portable programs -- programs that run |
|
in the same way on any of these diverse systems. Another way of looking |
|
at this is to say that ANS Forth was designed to permit compliant Forth |
|
systems to be implemented in many diverse ways. |
|
|
|
@cindex memory regions - how they are assigned |
|
Here are some examples of the way in which name, code and data spaces |
|
are assigned: |
|
|
|
@itemize @bullet |
|
@item |
|
For a Forth system that runs from RAM under a general-purpose operating |
|
system, it can be convenient to interleave name, code and data spaces in |
|
a single contiguous memory region. This organisation can be |
|
memory-efficient (for example, because the relationship between the name |
|
dictionary entry and the associated code dictionary entry can be |
|
implicit, rather than requiring an explicit memory pointer to reference |
|
from the name dictionary and the code dictionary). This is the |
|
organisation used by Gforth, as this example@footnote{The addresses |
|
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: |
|
@example |
|
hex |
|
variable fred 123456 fred ! |
|
variable jim abcd jim ! |
|
: foo + / - ; |
|
' fred 10 - 50 dump |
|
..80: 5C 46 0E 40 84 66 72 65 - 64 20 20 20 20 20 20 20 \F.@.fred |
|
..90: D0 9B 04 08 00 00 00 00 - 56 34 12 00 80 46 0E 40 ........V4...F.@ |
|
..A0: 83 6A 69 6D 20 20 20 20 - D0 9B 04 08 00 00 00 00 .jim ........ |
|
..B0: CD AB 00 00 9C 46 0E 40 - 83 66 6F 6F 20 20 20 20 .....F.@.foo |
|
..C0: 80 9B 04 08 00 00 00 00 - E4 2E 05 08 0C 2F 05 08 ............./.. |
|
@end example |
|
|
|
@item |
|
For a high-performance system running on a modern RISC processor with a |
|
modified Harvard architecture (one that has a unified main memory but |
|
separate instruction and data caches), it is desirable to separate |
|
processor instructions from processor data. This encourages a high cache |
|
density and therefore a high cache hit rate. The Forth code dictionary |
|
is not necessarily made up entirely of processor instructions; its |
|
nature is dependent upon the Forth implementation. |
|
|
|
@item |
|
A Forth compiler that runs on a segmented 8086 processor could be |
|
designed to interleave the name, code and data spaces within a single |
|
64Kbyte segment. A more common implementation choice is to use a |
|
separate 64Kbyte segment for each region, which provides more memory |
|
overall but provides an address map in which only the data space is |
|
accessible. |
|
|
|
@item |
|
Microprocessors exist that run Forth (or many of the primitives required |
|
to implement the Forth virtual machine efficiently) directly. On these |
|
processors, the relationship between name, code and data spaces may be |
|
imposed as a side-effect of the microarchitecture of the processor. |
|
|
|
@item |
|
A Forth compiler that executes from ROM on an embedded system needs its |
|
data space separated from the name and code spaces so that the data |
|
space can be mapped to a RAM area. |
|
|
|
@item |
|
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 |
|
separate the name space from the data and code spaces; once the |
|
application has been compiled, the name dictionary is no longer |
|
required@footnote{more strictly speaking, most applications can be |
|
designed so that this is the case}. The name dictionary can be deleted |
|
entirely, or could be stored in memory on a remote @var{host} system for |
|
debug and development purposes. In the latter case, the compiler running |
|
on the @var{target} system could implement a protocol across a |
|
communication link that would allow it to interrogate the name dictionary. |
|
@end itemize |
|
|
@menu |
@menu |
* Memory Access:: |
* Reserving Data Space:: |
* Address arithmetic:: |
* Memory Access:: |
* Memory Blocks:: |
* Address Arithmetic:: |
|
* Memory Blocks:: |
|
* Dynamic Allocation:: |
@end menu |
@end menu |
|
|
@node Memory Access, Address arithmetic, Memory, Memory |
|
|
@node Reserving Data Space, Memory Access, Memory, Memory |
|
@subsection Reserving Data Space |
|
@cindex reserving data space |
|
@cindex data space - reserving some |
|
|
|
@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, |
|
@var{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 |
|
|
|
@cindex data space pointer - contiguous regions |
|
Contiguous regions may be created in data space under these conditions: |
|
@itemize @bullet |
|
@item |
|
The value of the data-space pointer, @code{here}, always defines the |
|
beginning of a contiguous region of data space. |
|
|
|
@item |
|
@code{CREATE} establishes the beginning of a contiguous region of data |
|
space (the @code{CREATE}d definition returns the initial address of the |
|
region). |
|
|
|
@item |
|
@code{variable} does @var{not} establish the beginning of a contiguous |
|
region in data space; @code{variable} followed by @code{allot} is not |
|
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 |
|
|
|
doc-here |
|
doc-unused |
|
doc-allot |
|
doc-c, |
|
doc-, |
|
doc-2, |
|
|
|
|
|
@node Memory Access, Address Arithmetic, Reserving Data Space, Memory |
@subsection Memory Access |
@subsection Memory Access |
@cindex memory access words |
@cindex memory access words |
|
|
Line 2476 doc-sf!
|
Line 2671 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 |
|
|
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 |
Line 2537 doc-cfalign
|
Line 2732 doc-cfalign
|
doc-cfaligned |
doc-cfaligned |
doc-address-unit-bits |
doc-address-unit-bits |
|
|
@node Memory Blocks, , Address arithmetic, Memory |
@node Memory Blocks, Dynamic Allocation, Address Arithmetic, Memory |
@subsection Memory Blocks |
@subsection Memory Blocks |
@cindex memory block words |
@cindex memory block words |
|
@cindex character strings - moving and copying |
|
|
|
Memory blocks often represent character strings; @xref{String Formats} |
|
for ways of storing character strings in memory. @xref{Displaying |
|
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 (increments of @code{CELL}), |
and expect a @code{CELL}-aligned address. Others work on character units |
and expect a @code{CELL}-aligned address. Others work on character units |
Line 2557 carefully between @code{cmove} and @code
|
Line 2757 carefully between @code{cmove} and @code
|
|
|
You can only use any of these words @var{portably} to access data space. |
You can only use any of these words @var{portably} to access data space. |
|
|
@comment - think the naming of the arguments is wrong for move |
@comment TODO - think the naming of the arguments is wrong for move |
doc-move |
doc-move |
doc-erase |
doc-erase |
|
@comment TODO - think the naming of the arguments is wrong for cmove |
@comment - think the naming of the arguments is wrong for cmove |
|
doc-cmove |
doc-cmove |
@comment - think the naming of the arguments is wrong for cmove> |
@comment TODO - think the naming of the arguments is wrong for cmove> |
doc-cmove> |
doc-cmove> |
doc-fill |
doc-fill |
@comment - think the naming of the arguments is wrong for blank |
|
doc-blank |
doc-blank |
doc-compare |
doc-compare |
doc-search |
doc-search |
|
doc--trailing |
|
doc-/string |
|
|
|
@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 3149 co-exist in memory without any clash of
|
Line 3366 co-exist in memory without any clash of
|
of @code{exception} in ANS Forth is provided in |
of @code{exception} in ANS Forth is provided in |
@file{compat/exception.fs}. |
@file{compat/exception.fs}. |
|
|
|
|
doc-quit |
doc-quit |
doc-abort |
doc-abort |
doc-abort" |
doc-abort" |
Line 3168 doc---exception-exception
|
Line 3384 doc---exception-exception
|
@comment values, user-defined defining words. |
@comment values, user-defined defining words. |
|
|
@menu |
@menu |
* Simple Defining Words:: |
* Simple Defining Words:: |
* Colon Definitions:: |
* Colon Definitions:: |
* User-defined Defining Words:: |
* User-defined Defining Words:: |
* Supplying names:: |
* Supplying names:: |
* Interpretation and Compilation Semantics:: |
* Interpretation and Compilation Semantics:: |
@end menu |
@end menu |
|
|
@node Simple Defining Words, Colon Definitions, Defining Words, Defining Words |
@node Simple Defining Words, Colon Definitions, Defining Words, Defining Words |
Line 3180 doc---exception-exception
|
Line 3396 doc---exception-exception
|
@cindex simple defining words |
@cindex simple defining words |
@cindex defining words, simple |
@cindex defining words, simple |
|
|
|
@comment TODO include examples of reserving data space for buffers |
|
@comment etc. using variable, allot, create and build up to the point |
|
@comment where it is appropriate to x-ref to the "structures" section. |
|
|
doc-constant |
doc-constant |
doc-2constant |
doc-2constant |
doc-fconstant |
doc-fconstant |
Line 3616 accessing the header structure usually k
|
Line 3836 accessing the header structure usually k
|
@code{' word >body} also gives you the body of a word created with |
@code{' word >body} also gives you the body of a word created with |
@code{create-interpret/compile}. |
@code{create-interpret/compile}. |
|
|
|
doc-postpone |
|
|
|
|
|
|
@c ---------------------------------------------------------- |
@c ---------------------------------------------------------- |
@node The Text Interpreter, Tokens for Words, Defining Words, Words |
@node The Text Interpreter, Tokens for Words, Defining Words, Words |
@section The Text Interpreter |
@section The Text Interpreter |
Line 3623 accessing the header structure usually k
|
Line 3847 accessing the header structure usually k
|
@cindex text interpreter |
@cindex text interpreter |
@cindex outer interpreter |
@cindex outer interpreter |
|
|
Intro blah. |
@comment index.. |
|
|
@comment TODO |
When a Forth system starts up, the final stages of initialisation are to |
|
set @code{state} to 0 (interperetation state) and execute @code{quit}, |
|
to start the text interpreter. |
|
|
|
The text interpreter is an endless loop that accepts input from various |
|
devices (by default the user input device -- the keyboard). A popular |
|
implementation technique for Forth is to implement a @var{forth virtual |
|
machine} using a loop called the @var{inner interpreter}. Because of |
|
this naming, the text interpreter is also known as the @var{outer |
|
interpreter}. |
|
|
|
The text interpreter works on input one line at a time. Starting at the |
|
beginning of the line, it skips leading spaces (called @var{delimiters}) |
|
then parses a string (a sequence of non-space characters) until it |
|
either reaches a space character or it reaches the end of the |
|
line. Having parsed a string, it then makes two attempts to do something |
|
with it: |
|
|
|
@itemize @bullet |
|
@item |
|
It looks the string up in a dictionary of definitions. If the string is |
|
found in the dictionary, the string names a @var{definition} (also known |
|
as a @var{word}) and the dictionary search will return an @var{execution |
|
token} (xt) for the definition and some flags that show when the |
|
definition can be used legally. If the definition can be legally |
|
executed in @var{interpret} mode then the text interpreter will use the |
|
xt to execute it, otherwise it will issue an error message. The |
|
dictionary is described in more detail in <TODO>. |
|
@item |
|
If the string is not found in the dictionary, the text interpreter |
|
attempts to treat it as a number in the current radix (base 10 after |
|
initial startup). If the string represents a legal number in the current |
|
radix, the number is pushed onto the appropriate parameter stack. |
|
See @ref{Number Conversion} for details. |
|
@end itemize |
|
If both of these attempts fail, the remainder of the input line is |
|
discarded and the text interpreter isses an error message. If one of |
|
these attempts succeeds, the text interpreter repeats the parsing |
|
process until the end of the line has been reached. At this point, |
|
it prints the status message `` ok'' and waits for more input. |
|
|
|
There are two important things to note about the behaviour of the text |
|
interpreter: |
|
|
|
@itemize @bullet |
|
@item |
|
It processes each input string to completion before parsing additional |
|
characters from the input line. |
|
@item |
|
It keeps track of its position in the input line using a variable |
|
(called @code{>IN}, pronounced ``to-in''). The value of @code{>IN} can |
|
be modified by the execution of definitions in the input line. This |
|
means that definitions can ``trick'' the text interpreter either into |
|
skipping sections of the input line or into parsing a section of the |
|
input line more than once. |
|
@end itemize |
|
|
doc->in |
doc->in |
doc-tib |
|
doc-#tib |
|
doc-span |
|
doc-restore-input |
|
doc-save-input |
|
doc-source |
doc-source |
doc-source-id |
|
|
|
|
doc-tib |
|
doc-#tib |
|
|
@menu |
@menu |
* Number Conversion:: |
* Number Conversion:: |
* Interpret/Compile states:: |
* Interpret/Compile states:: |
* Literals:: |
* Literals:: |
* Interpreter Directives:: |
* Interpreter Directives:: |
|
* Input Sources:: |
@end menu |
@end menu |
|
|
@comment TODO |
|
|
|
The text interpreter works on input one line at a time. Starting at |
|
the beginning of the line, it skips leading spaces (called |
|
@var{delimiters}) then parses a string (a sequence of non-space |
|
characters) until it either reaches a space character or it |
|
reaches the end of the line. Having parsed a string, it then makes two |
|
attempts to do something with it: |
|
|
|
* It looks the string up in a dictionary of definitions. If the string |
|
is found in the dictionary, the string names a @var{definition} (also |
|
known as a @var{word}) and the dictionary search will return an |
|
@var{Execution token} (xt) for the definition and some flags that show |
|
when the definition can be used legally. If the definition can be |
|
legally executed in @var{Interpret} mode then the text interpreter will |
|
use the xt to execute it, otherwise it will issue an error |
|
message. The dictionary is described in more detail in <blah>. |
|
|
|
* If the string is not found in the dictionary, the text interpreter |
|
attempts to treat it as a number in the current radix (base 10 after |
|
initial startup). If the string represents a legal number in the |
|
current radix, the number is pushed onto the appropriate parameter |
|
stack. Stacks are discussed in more detail in <blah>. Number |
|
conversion is described in more detail in <section about +, - |
|
numbers and different number formats>. |
|
|
|
If both of these attempts fail, the remainer of the input line is |
|
discarded and the text interpreter isses an error message. If one of |
|
these attempts succeeds, the text interpreter repeats the parsing |
|
process until the end of the line has been reached. At this point, |
|
it prints the status message `` ok'' and waits for more input. |
|
|
|
There are two important things to note about the behaviour of the text |
|
interpreter: |
|
|
|
* it processes each input string to completion before parsing |
|
additional characters from the input line. |
|
|
|
* it keeps track of its position in the input line using a variable |
|
(called >IN, pronounced ``to-in''). The value of >IN can be modified |
|
by the execution of definitions in the input line. This means that |
|
definitions can ``trick'' the text interpreter either into skipping |
|
sections of the input line or into parsing a section of the |
|
input line more than once. |
|
|
|
|
|
@node Number Conversion, Interpret/Compile states, The Text Interpreter, The Text Interpreter |
@node Number Conversion, Interpret/Compile states, The Text Interpreter, The Text Interpreter |
@subsection Number Conversion |
@subsection Number Conversion |
Line 3835 doc-]L
|
Line 4066 doc-]L
|
doc-2literal |
doc-2literal |
doc-fliteral |
doc-fliteral |
|
|
@node Interpreter Directives, ,Literals, The Text Interpreter |
@node Interpreter Directives, Input Sources, Literals, The Text Interpreter |
@subsection Interpreter Directives |
@subsection Interpreter Directives |
@cindex interpreter directives |
@cindex interpreter directives |
|
|
Line 3867 doc-[AGAIN]
|
Line 4098 doc-[AGAIN]
|
doc-[WHILE] |
doc-[WHILE] |
doc-[REPEAT] |
doc-[REPEAT] |
|
|
|
|
|
@node Input Sources, , Interpreter Directives, The Text Interpreter |
|
@subsection Input Sources |
|
@cindex input sources |
|
@cindex text interpreter - input sources |
|
|
|
The text interpreter can process input from these sources: |
|
|
|
@itemize @bullet |
|
@item |
|
The user input device -- the keyboard. This is the default input for the |
|
text interpreter when Forth is started up. |
|
@item |
|
A file, using the words described in @ref{Forth source files}. |
|
@item |
|
A block, using the words described in @ref{Blocks}. |
|
@item |
|
A text string, using @code{evaluate}. |
|
@end itemize |
|
|
|
A program can determine the current input device by checking the values |
|
of @code{source-id} and @code{blk}. |
|
|
|
doc-source-id |
|
doc-blk |
|
|
|
doc-save-input |
|
doc-restore-input |
|
|
|
doc-evaluate |
|
|
|
|
@c ------------------------------------------------------------- |
@c ------------------------------------------------------------- |
@node Tokens for Words, Word Lists, The Text Interpreter, Words |
@node Tokens for Words, Word Lists, The Text Interpreter, Words |
@section Tokens for Words |
@section Tokens for Words |
Line 3983 implemented. Gforth provides @code{vocab
|
Line 4246 implemented. Gforth provides @code{vocab
|
word. @file{compat/vocabulary.fs} provides an implementation in ANS |
word. @file{compat/vocabulary.fs} provides an implementation in ANS |
Standard Forth. |
Standard Forth. |
|
|
TODO: locals section refers to here, saying that every word list (aka |
@comment TODO: locals section refers to here, saying that every word list (aka |
vocabulary) has its own methods for searching etc. Need to document that. |
@comment vocabulary) has its own methods for searching etc. Need to document that. |
|
|
|
@comment the thisone- prefix is used to pick out the true definition of a |
|
@comment word from the source files, rather than some alias. |
doc-forth-wordlist |
doc-forth-wordlist |
doc-definitions |
doc-definitions |
doc-get-current |
doc-get-current |
doc-set-current |
doc-set-current |
|
|
@comment TODO when a defn (like set-order) is instanced twice, the second instance gets documented. |
|
@comment In general that might be fine, but in this example (search.fs) the second instance is an |
|
@comment alias, so it would not naturally have documentation |
|
@comment .. the fix to that is to add a specific prefix, like the object-orientation stuff does. |
|
|
|
doc-get-order |
doc-get-order |
doc-set-order |
doc---thisone-set-order |
doc-wordlist |
doc-wordlist |
doc-also |
doc-also |
doc-forth |
doc---thisone-forth |
doc-only |
doc-only |
doc-order |
doc---thisone-order |
doc-previous |
doc-previous |
|
|
doc-find |
doc-find |
Line 4105 my-new-words definitions
|
Line 4364 my-new-words definitions
|
@node Environmental Queries, Files, Word Lists, Words |
@node Environmental Queries, Files, Word Lists, Words |
@section Environmental Queries |
@section Environmental Queries |
@cindex environmental queries |
@cindex environmental queries |
@comment TODO more index entries |
|
|
|
ANS Forth introduced the idea of ``environmental queries'' as a way |
ANS Forth introduced the idea of ``environmental queries'' as a way |
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. |
Line 4379 standard requires blocks to be available
|
Line 4637 standard requires blocks to be available
|
doc-open-blocks |
doc-open-blocks |
doc-use |
doc-use |
doc-scr |
doc-scr |
doc-blk |
|
doc-get-block-fid |
doc-get-block-fid |
doc-block-position |
doc-block-position |
doc-update |
doc-update |
Line 4560 hex -1 my-u. decimal FFFFFFFF
|
Line 4817 hex -1 my-u. decimal FFFFFFFF
|
|
|
@node String Formats, Displaying characters and strings, Formatted numeric output, Other I/O |
@node String Formats, Displaying characters and strings, Formatted numeric output, Other I/O |
@subsection String Formats |
@subsection String Formats |
@cindex string formats |
@cindex strings - see character strings |
|
@cindex character strings - formats |
|
|
@comment TODO more index entries |
@comment TODO more index entries |
|
|
Forth commonly uses two different methods for representing a string: |
Forth commonly uses two different methods for representing character |
|
strings: |
|
|
@itemize @bullet |
@itemize @bullet |
@item |
@item |
Line 4592 display characters and strings.
|
Line 4851 display characters and strings.
|
|
|
@node Displaying characters and strings, Input, String Formats, Other I/O |
@node Displaying characters and strings, Input, String Formats, Other I/O |
@subsection Displaying characters and strings |
@subsection Displaying characters and strings |
@cindex displaying characters and strings |
@cindex characters - compiling and displaying |
@cindex compiling characters and strings |
@cindex character strings - compiling and displaying |
@cindex cursor control |
|
|
|
@comment TODO more index entries |
@comment TODO more index entries |
|
|
Line 4610 doc-."
|
Line 4868 doc-."
|
doc-.( |
doc-.( |
doc-type |
doc-type |
doc-cr |
doc-cr |
|
@cindex cursor control |
doc-at-xy |
doc-at-xy |
doc-page |
doc-page |
doc-s" |
doc-s" |
Line 4688 definition of @code{my-char}.
|
Line 4947 definition of @code{my-char}.
|
@cindex input |
@cindex input |
@comment TODO more index entries |
@comment TODO more index entries |
|
|
Blah on traditional and recommended string formats. |
@xref{String Formats} for ways of storing character strings in memory. |
|
|
doc--trailing |
@comment TODO examples for >number >float accept key key? pad parse word refill |
doc-/string |
|
doc-convert |
doc-key |
|
doc-key? |
doc->number |
doc->number |
doc->float |
doc->float |
doc-accept |
doc-accept |
|
doc-pad |
|
doc-parse |
|
doc-word |
|
doc-sword |
|
doc-refill |
|
@comment obsolescent words.. |
|
doc-convert |
doc-query |
doc-query |
doc-expect |
doc-expect |
doc-evaluate |
doc-span |
doc-key |
|
doc-key? |
|
|
|
TODO reference the block move stuff elsewhere |
|
|
|
TODO convert and >number might be better in the numeric input section. |
|
|
|
TODO maybe some of these shouldn't be here but should be in a ``parsing'' section |
TODO maybe some of these shouldn't be here but should be in a ``parsing'' section |
|
|
Line 5621 possibly John Hayes). A version of this
|
Line 5883 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 7283 doc-getenv
|
Line 7545 doc-getenv
|
These section lists the ANS Forth words that are not documented |
These section lists the ANS Forth words that are not documented |
elsewhere in this manual. Ultimately, they all need proper homes. |
elsewhere in this manual. Ultimately, they all need proper homes. |
|
|
doc-, |
|
doc-allocate |
|
doc-allot |
|
doc-c, |
|
doc-here |
|
doc-ms |
doc-ms |
doc-pad |
|
doc-parse |
|
doc-postpone |
|
doc-resize |
|
doc-time&date |
doc-time&date |
doc-unused |
|
doc-word |
|
doc-[compile] |
doc-[compile] |
doc-refill |
|
|
|
These ANS Forth words are not currently implemented in Gforth |
|
(see TODO section on dependencies) |
|
|
|
The following ANS Forth words are not currently supported by Gforth |
The following ANS Forth words are not currently supported by Gforth |
(@pxref{ANS conformance}) |
(@pxref{ANS conformance}): |
|
|
@code{EDITOR} |
@code{EDITOR} |
@code{EKEY} |
@code{EKEY} |
Line 9096 There are two ways to create a fully rel
|
Line 9345 There are two ways to create a fully rel
|
|
|
You will usually use @file{gforthmi}. If you want to create an |
You will usually use @file{gforthmi}. If you want to create an |
image @var{file} that contains everything you would load by invoking |
image @var{file} that contains everything you would load by invoking |
Gforth with @code{gforth @var{options}}, you simply say |
Gforth with @code{gforth @var{options}}, you simply say: |
@example |
@example |
gforthmi @var{file} @var{options} |
gforthmi @var{file} @var{options} |
@end example |
@end example |
Line 9109 like this:
|
Line 9358 like this:
|
gforthmi asm.fi asm.fs |
gforthmi asm.fi asm.fs |
@end example |
@end example |
|
|
@file{gforthmi} works like this: It produces two non-relocatable |
@file{gforthmi} is implemented as a sh script and works like this: It |
images for different addresses and then compares them. Its output |
produces two non-relocatable images for different addresses and then |
reflects this: first you see the output (if any) of the two Gforth |
compares them. Its output reflects this: first you see the output (if |
invocations that produce the nonrelocatable image files, then you see |
any) of the two Gforth invocations that produce the nonrelocatable image |
the output of the comparing program: It displays the offset used for |
files, then you see the output of the comparing program: It displays the |
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 |
image files, it displays a line like the following one: |
image files, it displays a line like the following one: |
|
|
Line 9128 cannot be represented correctly in the o
|
Line 9377 cannot be represented correctly in the o
|
these places in the dictionary and verify that these cells are dead |
these places in the dictionary and verify that these cells are dead |
(i.e., not read before they are written). |
(i.e., not read before they are written). |
|
|
|
If you type @file{gforthmi} with no arguments, it prints some usage |
|
instructions. |
|
|
@cindex @code{savesystem} during @file{gforthmi} |
@cindex @code{savesystem} during @file{gforthmi} |
@cindex @code{bye} during @file{gforthmi} |
@cindex @code{bye} during @file{gforthmi} |
@cindex doubly indirect threaded code |
@cindex doubly indirect threaded code |
Line 9141 creating the nonrelocatable images; you
|
Line 9393 creating the nonrelocatable images; you
|
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 |
data-relocatable image (because there is no code address offset). |
data-relocatable image (because there is no code address offset). The |
|
normal @file{gforth} executable is used for creating the relocatable |
|
image; you can pass the exact filename of this executable through the |
|
environment variable @code{GFORTH}. |
|
|
@node cross.fs, , gforthmi, Fully Relocatable Image Files |
@node cross.fs, , gforthmi, Fully Relocatable Image Files |
@subsection @file{cross.fs} |
@subsection @file{cross.fs} |
Line 9211 form @code{#! ...}, you just have to typ
|
Line 9466 form @code{#! ...}, you just have to typ
|
Gforth with this image file (note that the file extension @code{.fi} is |
Gforth with this image file (note that the file extension @code{.fi} is |
just a convention). I.e., to run Gforth with the image file @var{image}, |
just a convention). I.e., to run Gforth with the image file @var{image}, |
you can just type @var{image} instead of @code{gforth -i @var{image}}. |
you can just type @var{image} instead of @code{gforth -i @var{image}}. |
|
This works because every @code{.fi} file starts with a line of this |
|
format: |
|
|
|
@example |
|
#! /usr/local/bin/gforth-0.4.0 -i |
|
@end example |
|
|
|
The file and pathname for the Gforth engine specified on this line is |
|
the specific Gforth executable that it was built against; i.e. the value |
|
of the environment variable @code{GFORTH} at the time that |
|
@file{gforthmi} was executed. |
|
|
For example, if you place this text in a file: |
You can make use of the same shell capability to make a Forth source |
|
file into an executable. For example, if you place this text in a file: |
|
|
@example |
@example |
#! /usr/local/bin/gforth |
#! /usr/local/bin/gforth |
|
|
." Hello, world" CR |
." Hello, world" CR |
bye |
bye |
|
|
@end example |
@end example |
|
|
@noindent |
@noindent |
And then make the file executable (chmod +x in Unix), you can run it |
and then make the file executable (chmod +x in Unix), you can run it |
directly from the command line. The sequence @code{#!} is used in two |
directly from the command line. The sequence @code{#!} is used in two |
ways; firstly, it is recognised as a ``magic sequence'' by the operating |
ways; firstly, it is recognised as a ``magic sequence'' by the operating |
system, secondly it is treated as a comment character by Gforth. Because |
system, secondly it is treated as a comment character by Gforth. Because |
of the second usage, a space is required between @code{#!} and the path |
of the second usage, a space is required between @code{#!} and the path |
to the executable. |
to the executable. |
|
|
|
The disadvantage of this latter technique, compared with using |
|
@file{gforthmi}, is that it is slower; the Forth source code is compiled |
|
on-the-fly, each time the program is invoked. |
|
|
@comment TODO describe the #! magic with reference to the Power Tools book. |
@comment TODO describe the #! magic with reference to the Power Tools book. |
|
|
doc-#! |
doc-#! |