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