This chapter presents a complete reference on wfroth.
|
Last update: |
1-January-1999 |
|
State (estimation) |
100% |
This chapter includes the following sections:
Numeric objects stored on stack parameters are untyped: they are only 32-bits integers. Interpretation of their value is made by each word. For example, a same value can be interpreted as a signed integer (for example the word .), an an unsigned integer (U.), or a string (type). It's the programmer's responsability to be sure that the correct stack parameters are available for each definition: right number of parameters and right type for each parameter. You can use the word ?ENOUGHT to check for the number of parameters.
|
.s |
( --- ) |
Print all values available on stack. This is not destructive. Each value is interpreted as a signed integer, and is shown in decimal, whatever the value of the current base for integer numeric I/O. The purpose of this word is above all for debugging, or learning stack manipulation.
|
DEPTH |
( --- n ) |
Push the number of integers available on stack. If n is zero that means that stack is empty.
|
?ENOUGHT |
( n --- ) |
Allows to verify at run-time if there is at least n integers available on stack. n must be a constant number compiled before the call of ?ENOUGHT. If the variable ?SAFE is FALSE, there is nothing compiled into your definition, and the constant is removed: for example "3 ?ENOUGHT" does not compile anything. If the variable ?SAFE is TRUE, then ?ENOUGHT is compiled and will be executed at run-time. That means that you can test your program without any source modification, just change the value of variable ?SAFE.
|
DROP |
( n --- ) |
Discard the value which is on top of the stack.
|
DDROP |
( n1 n2 --- ) |
Alias: 2DROP |
Discard the two values which are on top stack.
: DDROP DROP DROP ;
|
DROPS |
( n --- ) |
Discard the n top values from stack.
: DROPS TIMES drop ENDTIMES ;
|
UNDER |
( n1 n2 --- n2 ) |
Alias: NIP |
Discard the value which under the top of the stack. We could define UNDER as:
: UNDER swap drop ;
|
BELOW |
( n1 n2 n3 --- n2 n3 ) |
Discard the value which under-under the top of the stack. We could define UNDER as:
: BELOW rot drop ;
|
DUP |
( n --- n n ) |
Duplicate the value which is on top stack.
|
DDUP |
( n1 n2 --- n1 n2 n1 n2 ) |
Alias: 2DUP |
Duplicate the two values which are on top stack. This word could be defined as:
: DDUP over over ;
|
OVER |
( n1 n2 --- n1 n2 n1 ) |
Duplicate the value which is under the top stack.
|
ABOVE |
( n1 n2 n3 --- n1 n2 n3 n1 ) |
Duplicate the value which is under under the top stack.
|
SWAP |
( n1 n2 --- n2 n1 ) |
Exchange the two values on top stack.
|
DSWAP |
( n1 n2 n1 n2 --- n2 n1 n2 n1 ) |
Alias: 2SWAP |
Exchange the two couples on top stack.
|
ROT |
( n1 n2 n3 --- n2 n3 n1 ) |
Rotate the top three values on stack.
|
-ROT |
( n1 n2 n3 --- n3 n1 n2 ) |
Rotate the top three values on stack.
|
ROLL |
( n --- ) |
Rotate the top n values on stack. ROT can be defined as:
: ROT 3 roll ;
|
-ROLL |
( n --- ) |
Rotate the top n values on stack. -ROT can be defined as:
: -ROT 3 -roll ;
|
PICK |
( n1 --- n2 ) |
Duplicate the n1-th value which is under the top stack. The next definitions can be defined using PICK:
: OVER 2 pick ;
: ABOVE 3 pick ;
The Return Stack is used by wfroth to save/restore the nested calls to the definitions (forth vm). The Return Stack is also used to save current index and limit for loops (do..loop). Therefore:
· leaving a definition, always lets the Return Stack in the state you have found when entering into this definition:
|
Correct: |
: test 10 >R " hello" type R> drop ; |
|
Incorrect: |
: test 10 >R " hello" type R drop ; |
· always let the return stack in the same state within a do..loop
|
Correct: |
: test 10 1 DO I . space 10 >R R> drop LOOP ; |
|
Incorrect: |
: test 10 1 DO I . space 10 >R R drop LOOP ; |
|
Definition |
Return Stack |
Parameters Stack |
|
>R |
( --- n ) |
( n --- ) |
Push a value into the Return Stack.
|
Definition |
Return Stack |
Parameters Stack |
|
R> |
( n --- ) |
( --- n ) |
Pop a value from the Return Stack.
|
Definition |
Return Stack |
Parameters Stack |
Alias |
|
R |
( n --- n ) |
( --- n ) |
R |
Copy a value on top of the Return Stack.
|
Definition |
Return Stack |
|
RDROP |
( n --- ) |
Discard the value from the Return Stack.
: RDROP R> drop ;
|
Definition |
Return Stack |
|
RUNDER |
( n1 n2 --- n2 ) |
Discard the value under top the Return Stack.
: RUNDER R> R> drop >R ;
|
Definition |
Return Stack |
|
RBELOW |
( n1 n2 n3 --- n2 n3 ) |
Discard the value under-under top the Return Stack.
: RBELOW R> R> R> drop >R >R ;
|
Definition |
Return Stack |
|
RDUP |
( n --- n n ) |
Duplicate the value on top of the Return Stack.
: RDUP R >R ;
|
Definition |
Return Stack |
|
RSWAP |
( n1 n2 --- n2 n1 ) |
Exchange the 2 values on top of the Return Stack.
: RSWAP R> R> swap >R >R ;
|
Definition |
Return Stack |
|
ROVER |
( n1 n2 --- n1 n2 n1 ) |
Duplicate the value under-top of the Return Stack.
: ROVER R> R> dup -rot >R >R >R ;
|
Definition |
Return Stack |
|
RABOVE |
( n1 n2 n3 --- n1 n2 n3 n1 ) |
Duplicate the value under-under-top of the Return Stack.
: RABOVE R> R> R -rot >R >R >R ;