A GLOSSARY of words in the RubyFORTH dictionary.
================================================


Words in the FORTH wordlist
---------------------------


!		( n a -- )

		Store value /n/ at address /a/.

"		( "...<">" -- $ )

		Forward parse until either EOL or the string
		delimiter. Return a string object.

'		( "<word>" -- xt )

		Push the execution token of the next word in the input
		stream. Searched all vocabularies. See also 'xt?'

(		( "...<)>" -- )

		Comment until closing parenthesis or EOL.

*		( n1 n2 -- n1*n2 )

		Multiply.

+		( n1 n2 -- n1+n2 )

		Add.

+!		( n a -- )

		Increment /a/ by /n/.

,		( n -- )

		Write /n/ to the next free cell of data space, then
		increment the data space pointer, /here/.

-		( n1 n2 -- n1-n2 )

		Subtract.

-rot		( a b c -- c a b )

		Inverse of /rot/.

.		( n -- )

		Print the top of the stack.

."		( "...<">" -- )

		Forward parse until either EOL or the string
		delimiter. Type the parsed string.

.context	( -- )

		Print the active wordlist.

.ds		( -- )

		Dictionary dump. Dumps the contents of the dictionary
		with mild formatting.

.r		( n1 n2 -- )

		Print /n1/ with visual width /n2/.

.s		( -- )

		Print a representation of the data stack.

.vocab		( <vocab> -- )

		Print all the words in the 'forth' and 'compiler' wordlists
		from the supplied vocabulary (see 'words').

/		( n1 n2 -- n1/n2 )

		Divide.

0=		( n -- f )

		Is /n/ equal to 0? Can also mean, is /n/ 'false'?

1+		( n -- n+1 )
		
1-		( n -- n-1 )

2!		( n1 n2 a -- )

		Store a double at address /a/.	

2,		( n1 n2 -- )

		Write a double to dataspace, advancing HERE accordingly.
		(See /,/).

2@		( a -- n1 n2 )

		Fetch a double from address /a/.	

2drop		( n1 n2 -- )

		Drop the first two items on the data stack.

2dup		( n1 n2 -- n1 n2 n1 n2 )

		Duplicate the first two items on the data stack.

2swap		( n1 n2 n3 n4 -- n3 n4 n1 n2 )

		Swap the the top two pairs on the data stack.

:		( "<word>" -- )

		Begin a new word definition. Writes its header
		immediately.

:noname		( -- )

		Begin a headerless definition. Leaves the word's xt on
		the top of the stack immediately, so beware of
		accessing the stack during the :noname word's
		definition (e.g., inside [ ]).

<		( n1 n2 -- f )

		Is /n1/ less than /n2/?

<=		( n1 n2 -- f )

		Is /n1/ less than or equal to /n2/?

=		( n1 n2 -- f )

		Is /n1/ equal to /n2?

>		( n1 n2 -- f )

		Is /n1/ greater than /n2/?

>=		( n1 n2 -- f )

		Is /n1/ greater than or equal to /n2/?

>r		( n -- )

		Push the top of the data stack into the return stack.

?branch		( f -- )

		Conditionally branch to the contents of the adjacent
		memory address.

?dup		( n -- n ?n )

		Conditionally duplicate the top of the stack if it tests true.

@		( a -- n )

		Fetch the contents of /a/.

\		( "...<EOL>" -- )

		Comment out the rest of the line.

]		( -- )

		Enter compilation mode.

alias		( "<new-word>" "<old-word>" -- )

		Create a new header, /new-word/, pointing to the same
		xt as /old-word/.

allot		( n -- )

		Advance the data space pointer by /n/.

and		( n1 n2 -- f )

		Logical and of /n1/ and /n2/.

bl		( -- )

		Emit a space.

branch		( -- )

		Branch to the contents of the adjacent memory address.
		
bye		( -- )

		Exit RubyFORTH.

cd		( "directory" -- )

		Forward parse the entire line, and change the current working
		directory.

chdir		( directory$ -- )

		Using a stack string, change the current working directory.

char		( "<character>" -- c )

		Forward parse and push the ascii value of the found
		character to the data stack.

close		( fd -- )

		Close the file specified by file descriptor /fd/.

compiler	( -- )

		Switch the active wordlist to 'compiler'. This means
		that subsequent headers will be written into the
		compiler vocabulary.

constant	( n "<word>" -- )

		Create a new word that will push /n/ to the stack when
		it is called.

cr		( -- )

		Print a newline character.

create		( "<word>" -- )

		Create a new word that will return its data space
		address when called. See also does>.

defer		( "<word>" -- )

		Create a new deferred word. The specific action of
		this word can be set using 'is'.

drop		( n -- )

		Drop the top of the stack.

dup		( n -- n n )

		Duplicate the top of the stack (i.e., push a copy of
		the TOS).

emit		( c -- )

		Print ascii value /c/ to stdout.

enter-ruby	( -- )

		Enter Ruby REPL using the IRB module.

eof?		( fd -- f )

		Is file /fd/ at the EOF?

execute		( xt -- )

		Execute the xt. For example "myword" could be executed
		by calling "myword" OR "' myword execute". See also
		':noname'.

expose		( <vocab> -- )

		Push the supplied vocabulary onto the vocabulary search stack.

forth		( -- )

		Switch the active wordlist to 'forth'. This means that
		subsequent headers will be written into the forth
		vocabulary.

header		( "<word>" -- )

		Create a new header in the active wordlist, pointing
		'here'.

here		( -- a )

		The data space pointer. Also, the code space pointer.

i!		( c string$ i -- )

		Set the /i/th element in /string/ to character /c/.
		This will work with arrays, too. 0 offset.

i@		( string$ i -- c )

		Return the /i/th character in /string/. 0 offset.

include		( "<filename>" -- )

		Load the contents of filename, evaluating each line. Sets
		'forth' as the default context before and after including
		source.

included	( filename$ -- f )

		Has 'filename' already been included?

is		( xt "<deferred word>" -- )

		Set the deferred word's value to xt. This means that
		when the deferred word is called, the code at xt will
		be executed.

local'		( "word" -- xt )
		
		Push the execution token of the next word in the input
		stream. Only search the current vocabulary. See also 'search',
		tick, and 'xt?'.

local-name?	( xt -- f | name$ )

		Return the header for xt, if found in the active wordlist in
		the current vocabulary. Return a false flag otherwise.

local-xt	( name$ -- xt )

		Return the execution token of the supplied name if
		it's in the current vocabulary.

make		( name$ -- )

		Identical to 'create' with one exception -- instead of forward
		parsing, the created word's header is read from the
		stack. This offers additional flexibility as it can be used in
		conjunction with string handling words to automate word
		generation.

max		( n1 n2 -- n3 )

		Calculate the greater of n1 and n2, leave it on the stack.

min		( n1 n2 -- n3 )

		Calculate the lesser of n1 and n2, leave it on the stack.

name?		( xt -- f | name$ )

		Return the header for xt, if found in the active
		wordlist. Return a false flag otherwise.

nip		( n1 n2 -- n2 )

		Drop the stack item beneath the top of stack.

needs		( "<filename>" -- )

		Include 'filename' (see 'include') unless it has already been
		included.

not		( n -- f )

		Equivalent to '0=', used for logical comparison.

open		( filename$ mode$ -- fd )

		Open /filename/ with the relevant /mode/, returning a
		file descriptor. For more on modes, see the words:
		'r/o', 'r/w', 'w/o' and w/r'.

or		( n1 n2 -- f )

		Logical or.

order		( -- )
		
		Print the current vocabulary search order (see 'vocab',
		'expose', 'shield').

over		( n1 n2 -- n1 n2 n1 )

		Push a copy of the second stack item to the data
		stack.

page		( -- )

		Clears the screen (currently Unix only).

parse		( c -- parsed$ )

		Consume the input stream up until character /c/ or EOL
		is met. Everything that has been consumed is placed on
		the stack as the parsed string.

parse-word	( -- parsed$ )

		Consume the input stream up until a whitespace token -- this
		can be either TAB or space. This is *not* equivalent to 'bl
		parse' as 'parse' can only take one termination character.

peek		( c -- peeked$ )

		Identical to 'parse', except that the input stream is
		left unharmed. In other words, peek _copies_
		everything up until /c/ or EOL, it doesn't consume.

peek-word	( -- peeked$ )

		Identical to 'parse-word', except that the input stream is
		left unharmed.

position	( fd -- pos )

		Push the current position in file /fd/.

prim		( "<name>" "...<EOL>" -- )

		Create a new primitive from within RubyFORTH. The
		first token is the name of this primitive (which is
		inserted into the active wordlist). The rest of the
		line is Ruby code, evaluated as a primitive whenever
		encountered.

quit		( -- )

		Return to toplevel immediately.

r/o		( -- mode$ )

		Return a Ruby mode string indicating read-only.

r/w		( -- mode$ )

		Return a Ruby mode string indicating read-write.

r>		( -- n )

		Pop the top of the return stack and push it to the
		data stack.

r@		( -- n )

		As 'r>', but _copies_ from the return stack instead of
		popping.

read		( fd count -- read$ )

		Read /count/ bytes from /fd/.

readline	( fd -- line$ )

		Read a line from /fd/.

rot		( n1 n2 n3 -- n2 n3 n1 )

		Rotate the third stack item, bringing it to the top of
		the data stack.

ruby-include	( "<filename>" -- )

		Load a Ruby module, evaluating its contents.

rubyforth	( -- <vocab> )

		Push the main RubyFORTH vocabulary onto the stack.

search		( word$ vocabulary -- xt )

		Search for word$ in the supplied vocabulary, returning the
		execution token.

see		( "<word>" -- )

		Print a representation of the parsed word. This is
		useful for debugging. Primitives are also represented.

seek		( fd pos -- )

		Set the position of /fd/ to /pos/.

shield		( -- )

		Drop the topmost vocabulary from the search stack.

space		( -- )

		Print a space to stdout.

spaces		( n -- )

		Print /n/ spaces to stdout.

swap		( n1 n2 -- n2 n1 )

		Swap the top two stack items.

tuck		( n1 n2 -- n2 n1 n2 ) 

		Basically: 'swap', then 'over'. A useful stack manipulation word.

type		( string$ -- )

		Print a string. (See also '.').

variable	( "<name>" -- )

		Create a new variable. When executed, a variable
		returns its data space address. This can then be
		stored to (see '!') and fetched from (see '@').

vocab		( name$ -- <vocab> )

		Create a new vocabulary object with the supplied name and
		place it on the stack.

vocab:		( "name" -- )

		Creates a new vocabulary object with the supplied name and
		store this object has a RubyFORTH word with the same header.

w/o		( -- mode$ )

		Return a Ruby mode string indicating write-only.

w/r		( -- mode$ )

		Return a Ruby mode string indicating write-read.

word		( c -- a len )

		Like 'parse', but returns a familiar addr/len pair in
		scratch space. This is like a string; each address
		cell holds one character. Useful for quick parsing
		operations where all we want to do is fetch. Used by
		'char'.

words		( -- )

		Print all the words in the 'forth' and 'compiler'
		wordlists from the topmost vocabulary.

write		( text$ fd -- )

		Write /text/ to file /fd/.

xt?		( word$ -- xt )

		Push the execution token of the string at the top of the
		stack. See also tick.


Words in the COMPILER wordlist
------------------------------


"		See FORTH glossary.

(		See FORTH glossary.

."		See FORTH glossary.

2>r		( n1 n2 -- )

		Place /n1/ and /n2/ on the return stack.

2literal	( n1 n2 -- )

		As 'literal', but deals with pairs of literals.

2r>		( -- n1 n2 )

		Fetch the top two items from the return stack.

2r@		( -- n1 n2 )

		As '2r>', but leave the return stack unchanged. Peek.

2rdrop		( -- )

		Drop the first two items on the return stack. Compiles '2r>
		2drop'.

;		( -- )

		End a colon definition.

?if		( -- )
		
		Conditionally duplicate the top of stack if it's true (see
		'?dup'), then enter a conditional (see 'if').

[		( -- )

		Exit compilation mode. See ']'

[']		( "<word>" -- )

		Used to "tick" the next word in the input stream,
		immediately. This differs from the standard tick word
		which when compiled will only be called when its
		parent word is executed.

[compile]	( "<word>" -- )

		Compile the next word -- from the COMPILER wordlist --
		into the current definition.

[is]		( xt "<deferred word>" -- )

		See 'is'. Works immediately within a definition.

\		See FORTH glossary.

again		( a -- )
		
		Branch to the contents of memory address /a/. Used for
		'begin...again' constructions (infinite loops).

ahead		( -- a )

		Compiles a branch instruction, returning an address
		that can be set by /then/.

begin		( -- a )

		Simply returns the data space pointer. Marks the
		beginning of two loop constructs,
		'begin...while...repeat' and 'begin...again'.

char		See FORTH glossary.

compile		( "<word>" -- )

		Compile the next word -- from the FORTH wordlist --
		into the current definition when the parent word is
		called.

do		( upper lower -- a )

		Push the loop bounds to the return stack, compile a
		'dobranch?' instruction and return the data space pointer for
		branching purposes.

dobranch?	( -- )

		Test the top two items on the return stack (loop bounds) to
		see whether a do...loop should continue iterating. Contains a
		'?branch' instruction.

does>		( -- )

		Used with 'create'. 'does>' can expect the address of
		the created word on the stack. The body of a 'does>'
		statement specified what to do with this address
		whenever the created word is called. A very flexible
		construct.

else		( -- )

		Branching in conditionals.

for		( count -- a )

		Compile 'do', inferring a lower bound of 0. So, '10 0 do'
		becomes '10 for'. As such, 'for...next' iterates from 0 to the
		supplied bound on the stack. This may differ from some
		'for...next' implementations, notorious for the variety of
		their operation. Ours is a syntactic simplification of 'do'.

i		( -- n )

		Same as r@, a return stack peek word. Conventially
		used to indicate the loop index in 'do...loop's.

if		( -- a )

		Compiles a '?branch' instruction and places the
		address of the cell in which the branch address will
		be situated on the stack.

iterate		( -- )

		Increment the top of the return stack. Used to increment the
		do...loop index (see 'i').

literal		( n -- )

		Compile a 'lit' instruction, then write /n/ into the
		current definition. This tells the interpreter to
		treat the number as a literal, not a memory address.

loop		( -- )

		Compile an 'iterate' instruction to increase the loop index,
		then branch to the beginning of the loop (i.e., to 'do').

next		( -- )

		Compiles 'loop';  see the latter for more details.

repeat		( a -- )

		Takes an address for branching and compiles an 'again'
		instruction.

then		( a -- )
	
		Resolves branching addresses, thereby ending a
		conditional.

unloop		( -- )

		Used in a 'do...loop' construction. Sets the current
		index to the upper bound, making the current iteration
		the final one.

while		( -- a2 a1 )

		Compiles a conditional branch instruction, branching
		information, etc.