Forth commands

Forth commands

: xxxx yyy ;
( -- )
Creates a new definition with the name xxx, consisting of word or words yyy.

CR
( -- )
Performs a carriage return and line feed at your terminal.

SPACES
( n -- )
Prints the given number of blank spaces at your terminal.

SPACE
( -- )
Prints one blank space at your terminal.

EMIT
( c -- )
Transmits a character to the output device.

." xxx"
( -- )
Prints the character string xxx at your terminal. The " character terminates the string.

+
( n1 n2 -- sum )
Adds.
Similarly, -, *, / (integer division), mod
/mod ( n1 n2 -- rem quot )

.
( n -- )
Prints a number, followed by one space.

SWAP
( n1 n2 -- n2 n1 )
Reverses the top two stack items.

DUP
( n -- n n )
Duplicates the top stack item.

OVER
( n1 n2 -- n1 n2 n1 )
Makes a copy of the second item and pushes it on top.

ROT
( n1 n2 n3 -- n2 n3 n1 )
Rotates the third item to the top.

DROP
( n -- )
Discards the top stack item.

Similarly, 2swap, 2dup, 2over, 2drop.

USE xxx 	
( -- )
Designate OS text file xxx as the "Forth disk."

LIST 	
( n -- )
Lists a disk block.

LOAD 	
( n -- )
Loads a disk block (compiles or executes).

( xxx) 	
( -- )
Causes the string xxx to be ignored by the text interpreter. The character ) is the delimiter.

UPDATE 	
( -- )
Marks the most recently referenced block as modified. The block will later be automatically transferred to mass storage if its buffer is needed to store a different block or if FLUSH is executed.

EMPTY-BUFFERS 	
( -- )
Marks all block buffers as empty without necessarily affecting their actual contents. Updated blocks are not written to mass storage.

BLOCK 	
( u -- addr )
Leaves the address of the first byte in block u. If the block is not already in memory, it is transferred from mass storage into whichever memory buffer has been least recently accessed. If the block occupying that buffer has been updated (i.e., modified), it is rewritten onto mass storage before block u is read into the buffer.

INCLUDE xxx 	
( -- )
Load the text file xxx (compiles or executes).

FORGET xxx 	
( -- )
Forgets all definitions back to and including xxx.

MARKER xxx 	
( -- )
Creates a word xxx which, when executed, restores the dictionary to the state it had just prior to the definition of xxx. In particular, remove xxx and all subsequent word definitions.

IF   xxx
ELSE yyy
THEN zzz
IF: ( f -- )
If f is true (non-zero) executes xxx; otherwise executes yyy; continues execution with zzz regardless. The phrase ELSE yyy is optional.

=
( n1 n2 -- f )
Returns true if n1 and n2 are equal.

-
( n1 n2 -- n-diff )
Returns true (i.e., the non-zero difference) if n1 and n2 are not equal.

<
( n1 n2 -- f )
Returns true if n1 is less than n2.

>
( n1 n2 -- f )
Returns true if n1 is greater than n2.

0=
( n -- f )
Returns true if n is zero (i.e., reverse the truth value).

0<
( n -- f )
Returns true if n is negative.

0>
( n -- f )
Returns true if n is positive.

AND
( n1 n2 -- and )
Returns the logical AND.

OR
( n1 n2 -- or )
Returns the logical OR.

?DUP
( n -- n n ) or
( 0 -- 0 )
Duplicates only if n is non-zero.

ABORT" xx"
( f -- )
If the flag is true, types out an error message, followed by the text. Also clears the stacks and returns control to the terminal. If false, takes no action.

?STACK
( -- f )
Returns true if a stack underflow condition has occurred. 

1+, 1-, 2+, 2-, 2*, 2/

ABS
( n -- |n| )
Returns the absolute value.

NEGATE
( n -- -n )
Changes the sign.

MIN
( n1 n2 -- n-min )
Returns the minimum.

MAX
( n1 n2 -- n-max )
Returns the maximum.

>R
( n -- )
Takes a value off the parameter stack and pushes it onto the return stack.

R>
( -- n )
Takes a value off the return stack and pushes it onto the parameter stack.

I
( -- n )
Copies the top of the return stack without affecting it.

R@
( -- n )
Copies the top of the return stack without affecting it.

J
( -- n )
Copies the third item of the return stack without affecting it.

*/
( n1 n2 n3 --
n-result )
Multiplies, then divides (n1*n2/n3). Uses a double-length intermediate result.

*/MOD
( n1 n2 n3 --
n-rem n-result )
Multiplies, then divides (n1*n2/n3). Returns the remainder and the quotient. Uses a double-length intermediate result. 







You can define the same word more than once in different ways � only the most recent definition will be executed.

For example, if you have entered:

: GREET  ." Hello, I speak Forth. " ; ok 

then you should get this result:

GREET Hello, I speak Forth. ok 

And if you redefine:

: GREET  ." Hi there! " ; ok 

you get the most recent definition:

GREET Hi there! ok 

Has the first GREET been erased? No, it's still there, but the most recent GREET is executed because of the search order. The text interpreter always starts at the "back of the dictionary" where the most recent entry is. The definition he finds first is the one you defined last. This is the one he shows to EXECUTE.

We can prove that the old GREET is still there. Try this:

FORGET GREET ok 

and

GREET Hello, I speak Forth. ok 

(the old GREET again!).

The word FORGET looks up a given word in the dictionary and, in effect, removes it from the dictionary along with anything you may have defined since that word. FORGET, like the interpreter, searches starting from the back; he only removes the most recently defined versions of the word (along with any words that follow). So now when you type GREET at the terminal, the interpreter finds the original GREET.

FORGET is a good word to know; he helps you to weed out your dictionary so it won't overflow. (The dictionary takes up memory space, so as with any other use of memory, you want to conserve it.)

Some Forths do not have FORGET. In that case you need to plan the forgetting in advance, e.g.:

MARKER -work

defines the null definition -work to mark the current system state for you. When you execute -work at some later time, the system state is restored to that in effect when -work was defined. In particular, all words defined after the marker word -work are completely removed from the dictionary.