~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Global Namespace
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

canvas
	( - )
	Open or shut the 'canvas' vocabulary. Shut by default.

debug
	( - )
	Open or shut the 'debug' vocabulary. Open by default.

editor
	( - )
	Open or shut the 'editor' vocabulary. Shut by default.

retro
	( - )
	Open or shut the 'retro' vocabulary. Open by default. 

))
	( - )
	Conclude a vocab, moves the vocab word to the end of the dictionary so
	that it can be visible when shut.

((
	( - )
	Start a vocab, by saving the last and second to last words to a set of
	fields.

vocab
	( "- )
	Create a new vocabulary.

.vocab
	( a- )
	Class handler for vocabularies. Toggles the open/shut state when a
	vocabulary is called.

shut
	( a- )
	Explicitly shut a vocabulary. Pass the address of the vocabulary.
	Sample:
	
	  ' editor shut
	

open
	( a- )
	Explicitly open a vocabulary. Pass the address of the vocabulary.
	Sample:
	
	  ' editor open
	

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Net
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

net.socket
	( -n )
	Create a new socket.

net.bind
	( np-f )
	Bind socket 'n' to port 'p'. Returns a flag.

net.listen
	( n-f )
	Setup port to allow listening for incoming connections.

net.accept
	( n-f )
	Accept a connection on socket 'n'. Returns a new socket for
	reading/writing.

net.close
	( n-f )
	Close a socket.

net.send
	( cn-f )
	Write character 'c' to socket 'n'.

net.recv
	( s-c )
	Read a character from a socket.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Canvas
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

white
	( - )
	Set the active drawing color to white. 

yellow
	( - )
	Set the active drawing color to yellow.

magenta
	( - )
	Set the active drawing color to magenta.

brightred
	( - )
	Set the active drawing color to bright red.

brightcyan
	( - ) 
	Set the active drawing color to bright cyan.

brightgreen
	( - ) 
	Set the active drawing color to bright green.

brightblue
	( - )
	Set the active drawing color to bright blue.

darkgray
	( - ) 
	Set the active drawing color to dark gray. 

gray
	( - ) 
	Set the active drawing color to light gray.

brown
	( - ) 
	Set the active drawing color to brown.

purple
	( - ) 
	Set the active drawing color to purple.

red
	( - ) 
	Set the active drawing color to dark red.

cyan
	( - ) 
	Set the active drawing color to cyan.

green
	( - ) 
	Set the active drawing color to dark green.

blue
	( - ) 
	Set the active drawing color to blue.

black
	( - ) 
	Set the active drawing color to black.

solidCircle
	( xyr- ) 
	Draw a filled circle.

circle
	( xyr- ) 
	Draw a hollow circle.

hline
	( xyw- ) 
	Draw a horizontal line.

vline
	( xyh- ) 
	Draw a vertical line.

solidBox
	( xyhw- ) 
	Draw a solid box.

box
	( xyhw- ) 
	Draw a hollow box.

pixel
	( xy- ) 
	Set a single pixel.

setColor
	( n- ) 
	Set the current color.

click?
	( -f )
	Get mouse button status.

mouse
	( -xy )
	Get mouse coordinates.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Debug
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

see
	( "- )
	Parse for a word, and decompile it.

:see
	( a- )
	Decompile a word, given a starting address.

.s
	( - )
	Display the depth and items on the data stack.

words
	( - )
	List all visible, named words.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:r
	( -n )
	Mode for 'reading' files.

:r+
	( -n )
	Mode for 'reading' and 'writing' files.

:w
	( -n )
	Mode for 'writing' to a file.

:w+
	( -n )
	Mode for 'reading' and 'writing' to a file. Will erase contents of file
	if it exists.

:a
	( -n )
	Mode for 'writing' to an existing file. Adds to the end of the file.
	Creates the file if it does not exist.

:a+
	( -n )
	Mode for 'reading' and 'writing' to a file. Adds to the end of the file.

fopen
	( $m-h )
	Open a file ('$') with a specific mode. Returns a handle that can be
	used with the other functions.

fread
	( hc-f )
	Read a byte from a file ('h'), storing it at address ('c'). Leaves a
	flag.

fwrite
	( ch-f )
	Write a byte ('c') to a file ('h'). Leaves a flag.

fclose
	( h-f )
	Close a file. Leaves a flag.

fpos
	( h-n )
	Get the current offset into the file.

fseek
	( nh-f )
	Seek a specific offset in the file. Returns a flag.

fsize
	( h-n )
	Return the size of a file.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Editor
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

set-blocks
	( n- )
	Set the current number of blocks. Does not erase the blocks.

ea
	( - ) 
	Evaluate all of the blocks.

e
	( - ) 
	Evaluate the current block.

new
	( - ) 
	Erase all of the blocks.

i
	( n"- )
	Parse for text and insert the text into line 'n'.

ia
	( nc"- )
	Parse for text and insert into line 'n' starting at column 'c'. 

n
	( - ) 
	Go to the next block.

p
	( - ) 
	Go to the previous block.

x
	( - ) 
	Delete the contents of the current block.

d
	( n- )
	Erase the contents of line 'n' in the current block.

s
	( n- )
	Quickly select a new block.

v
	( - ) 
	View the current block.

(ia)
	( lc"- ) 
	Internal factor of 'ia'.

(v)
	( - ) 
	Internal factor of 'v'.

(line)
	( n-a )
	Returns the address a line in the current block starts at.

(block)
	( -a )
	Returns the address the current block starts at.

block
	( n-a )
	Returns the address a block starts at.

blk
	( -a )
	Variable. Holds the number of the current block.

line-ending
	( -a )
	Variable. Holds the character that marks "end of line" for 'i' and 'ia'.

offset
	( -a )
	Variable. Holds the current start of the block buffer.

#-blocks
	( -a )
	Variable. Holds the number of blocks conained in the block buffer.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Retro
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1+
	( n-n )
	Increase TOS by 1. 

1-
	( n-n ) 
	Decrease TOS by 1.

swap
	( xy-yx ) 
	Exchange the positions of TOS and NOS.

drop
	( n- )
	Remove TOS from the stack. 

and
	( xy-z ) 
	Bitwise AND.

or
	( xy-z ) 
	Bitwise OR.

xor
	( xy-z ) 
	Bitwise XOR.

@
	( a-n ) 
	Fetch value from address.

!
	( na- ) 
	Store value to address.

+
	( xy-z )
	Add x and y, giving z. 

-
	( xy-z )
	Subtract y from x, giving z.

*
	( xy-z ) 
	Multiply x by y, giving z.

/mod
	( xy-rq )
	Divide x / y, giving the result (q) and modulus (r). 

<<
	( xy-z ) 
	Shift bits left.

>>
	( xy-z ) 
	Shift bits right.

nip
	( xy-y )
	Remove NOS, leaving TOS.

dup
	( x-xx )
	Duplicate TOS. 

in
	( p-n ) 
	Read a value from an I/O port.

out
	( np- )
	Write a value to an I/O port. 

accept
	( c- )
	Read from input device until the read character is equal to c. Results
	are stored in 'tib'.

here
	( -a )
	Return the next available address in the heap. 

,
	( n- )
	Copy value to 'here', and increase 'here' by 1. 

]
	( - )
	Turn 'compiler' 'on'.

create
	( "- )
	Create a new dictionary header pointing to 'here' with a class of
	'.data'

:
	( "- ) 
	'create' a new word, set class to '.word' and call ']'.

later
	( RS: xy-yx ) 
	Swap addresses on return stack. This is used to defer execution until a
	later time, hence the name.

cr
	( - ) 
	Display a newline character.

emit
	( c- )
	Display a character.

type
	( $- )
	Display a zero-terminated string 

clear
	( - )
	Clear the display. 

over
	( xy-xyx ) 
	Get a copy of NOS.

2drop
	( xy- ) 
	Drop the top two items on stack.

not
	( n-n )
	Perform a NOT operation.

rot
	( xyz-yzx ) 
	Rotate top three stack items.

-rot
	( xyz-xzy ) 
	Rotate top three stack items twice.

tuck
	( xy-yxy ) 
	Place a copy of TOS under NOS.

2dup
	( xy-xyxy ) 
	Duplicate the top two items on the stack.

on
	( a- ) 
	Set a variable to 'TRUE'.

off
	( a- ) 
	Set a variable to 'FALSE'.

/
	( xy-q ) 
	Return x / y.

mod
	( xy-r ) 
	Divide x / y and return modulus. 

neg
	( n-n )
	Negate the value. This is the same as '-1 *'.

execute
	( a- ) 
	Call an address.

(.)
	( n- ) 
	Display a number without a trailing space. See also '.'

"
	( "-$ ) 
	Parse for and return a string. See also 'tempString' and 'keepString'.

compare
	( $$-f ) 
	Compare two strings.

wait
	( - )
	Wait for an I/O event.

'
	( "-a )
	Parse for a name, return the corresponding xt.

@+
	( a-an )
	Fetch from an address, return the value and the address incremented by
	one.

!+
	( na-a ) 
	Store a value to an address and return the address incremented by one.

+!
	( na- ) 
	Add value to contents of address.

-!
	( na- ) 
	Subtract value from contents of address.

:is
	( xa- )
	Assign 'a' to call 'x' instead of its default definition.

:devector
	( a- )
	Restore a vectored definition, pointed to by 'a', to its default
	definition.

is
	( a"- )
	Parse for a word, and assign it as a vector to 'a'.

devector
	( "- )
	Parse for a name, and strip the vector.

compile
	( a- ) 
	Compile a call to an address.

literal,
	( n- ) 
	Compile a value as a literal (push to stack) instruction.

tempString
	( $-$ )
	Move a string to a temporary buffer for safekeeping.

redraw
	( - ) 
	Force a video update. See also 'fastRender'.

keepString
	( $-$ )
	Compile a string into the heap and return a pointer to it.

getLength
	( $-n ) 
	Get the length of a string.

bye
	( - )
	Exit Retro. 

remap-keys
	( c-c ) 
	Called by 'accept', this can replace or alter keys as they are being
	typed. Useful for custom remapping for unusual systems.

with-class
	( xa- )
	Special function called by 'listen'. It will invoke an xt ('x') via its
	class handler ('a'). Normally it just passes control to 'execute'.

.word
	( a- ) 
	Word class for normal words. Words with this class will be compiled
	into definitions, or called, if the interpreter is on.

.macro
	( a- ) 
	Word class for immediate words. Words with this class will always
	execute.

.data
	( n- ) 
	If interpreting, leave the value on the stack. If compiling, compile as
	a literal into the definition.

d->class
	( d-a )
	Given a dictionary header, return the address of the class field.

d->xt
	( d-a ) 
	Given a dictionary header, return the address of the xt field.

d->name
	( d-$ )
	Given a dictionary header, return the address the word name starts at.

boot
	( - ) 
	Called when Retro is started. Useful as a TurnKey hook.

depth
	( -n )
	Return the number of items on the stack.

reset
	( ...- ) 
	Remove all items from the stack.

notfound
	( - ) 
	Called when a token is not found in the dictionary and when the token
	is not a valid number in the current 'base'.

save
	( - ) 
	Save the current image.

>number
	( $-n )
	Convert a string to a number. Conversion is done in the current 'base'. 

ok
	( - )
	Called after each token is processed. Useful as a TurnKey hook.

listen
	( - ) 
	The main interpreter routine. Exercise caution when altering this.

isNumber?
	( - ) 

key
	( -c )
	Read a single character from the keyboard. If you want to display the
	character, use 'ekey' instead.

ekey
	( -c ) 
	Read and 'emit' a single character from the keyboard.

time
	( -n )
	Return the current UnixTime

s"
	( R: -$ )
	( C: "- )
	Parse for a string, call 'keepString', and compile the address into the
	defintion as a literal. This is 'compile-only'

[
	( C: - )
	Turn 'compiler' off. This is 'compile-only'

;
	( C: - )
	End a definition. This is 'compile-only'

;;
	( C: - )
	Compile an exit instruction into the current definition. This is
	'compile-only'

=if
	( R: xy- )
	( C: -a )
	Compare x = y, jump to 'then' or 'else' if condition is not met. This
	is 'compile-only'

>if
	( R: xy- )
	( C: -a )
	Compare x > y, jump to 'then' or 'else' if condition is not met. This
	is 'compile-only'

<if
	( R: xy- )
	( C: -a )
	Compare x < y, jump to 'then' or 'else' if condition is not met. This
	is 'compile-only'

!if
	( R: xy- )
	( C: -a )
	Compare x <> y, jump to 'then' or 'else' if condition is not met. This
	is 'compile-only'

then
	( R: - )
	( C: a- )
	This closes a conditional opened by one of the 'if' forms. This is
	'compile-only'. See also: 'else'.

repeat
	( R: - )
	( C: -a )
	Begin an unconditional loop. This is 'compile-only'

again
	( R: - )
	( C: a- )
	Finish an unconditional loop. This is 'compile-only'

0;
	( R: n-n || n- )
	( C: - )
	Exit a word if TOS = 0. If TOS = 0, also drop TOS. If not, leave TOS
	alone and continue executing. This is 'compile-only'

push
	( R: n- )
	( C: - )
	Move a value from the data stack to the return stack. This is
	'compile-only'

pop
	( R: -n ) 
	( C: - )
	Move a value from the return stack to the data stack. This is
	'compile-only'

[']
	( R: -a ) 
	( C: "- )
	Parse for a name and compile the corresponding xt into the definition
	as a literal. This is 'compile-only'

for
	( R: n- ) 
	( C: -a )
	Start a simple countdown loop. This should be paired with 'next'. This
	is 'compile-only'

next
	( R: - ) 
	( C: a- )
	Finish a simple countdown loop. This should be paired with 'for'. This
	is 'compile-only'

(
	( "- )
	Start a comment. Parse for and ignore anything up to a ) character.
	This is 'immediate'.

last
	( -a )
	Variable. Holds a pointer to the most recent dictionary header.

compiler
	( -a ) 
	Variable. Holds the current state of the compiler.

tib
	( -a )
	Return the address of the 'text input buffer'.

update
	( -a )
	Internal variable. Used to help control screen updates.

fb
	( -a )
	Variable. 'TRUE' if canvas exists, 'FALSE' otherwise.

fw
	( -a )
	Variable. Holds the width of the canvas.

fh
	( -a )
	Variable. Holds the height of the canvas.

#mem
	( -a )
	Variable. Holds the amount of memory the NgaroVm is providing to the
	image.

heap
	( -a )
	Variable. This holds the address returned by 'here'.

which
	( -a )
	A MetaVariable. This holds the address of the most recently
	searched-for dictionary header.

whitespace
	( -a ) 
	Variable. If 'on}}, remap cr, lf, tab to space. If 'off', do not.

base
	( -a )
	Variable. Holds the current numeric base for parsing and display. Used
	by '>number', '(.)', '.', and others.

forget
	( "- ) 
	Parse for and forget a word. Any words defined after the word will also
	be removed and their memory reclaimed.

d'
	( "-d ) 
	Parse for a name and return the dictionary header for it.
	Note:
	If not found, this will return the header for 'd'', so exercise caution
	if manipulating the header!

reclass
	( a- )
	Change the class of the most recently defined word to the class 'a'
	points to.

reclass:
	( a"- )
	Parse for, and change the class of a word, to the class 'a' points to.

.primitive
	( a- )
	Special class for words that map directly to primitives. If compiling,
	inline the opcode. If interpreting, call as usual. If revectored, fall
	back to '.word' class.

.compiler
	( a- ) 
	Class for words that will only be called when 'compiler' is 'on'.

compile-only
	( - )
	Change the class of the most recently defined word to '.compiler'

immediate
	( - )
	Change the class of the most recently defined word to '.macro'

char:
	( "-c )
	Parse for a character, pass the character to '.data'. This is
	'immediate'.

++
	( a- ) 
	Increment value at address by 1.

--
	( a- ) 
	Decrement value at address by 1.

<list>
	( -a ) 
	List of addresses used for building namespaces.

{
	( - ) 
	Start a private namespace.

}
	( - ) 
	Close a private namespace.

{{
	( - ) 
	Start a public/private namespace.

---reveal---
	( - ) 
	Switch a public/private namespace to public mode.

}}
	( - ) 
	Close a public/private namespace.

variable:
	( n"- ) 
	Create a variable with an initial value of 'n'.

variable
	( "- ) 
	Create a variable with an initial value of '0'.

constant
	( n"- ) 
	Create a constant with a value of 'n'.

allot
	( n- ) 
	Allocate or free memory in a linear fashion.

zallot
	( n- )
	Allocate or free memory. If allocating, fill memory with 0's.

copy
	( sdc- ) 
	Copy 'c' cells from 's' to 'd'.

fill
	( anc- )
	Fill memory starting at 'a', with 'c' copies of value 'n'. 

`
	( C: "- )
	Parse for a name, and lay down the xt and corresponding class handler.
	This is 'compile-only'
	Notes:
	This one is a bit tricky. Here is a short bit of code to illustrate
	what it does:
	
	  : foo 1 . ;
	  : bar 2 . ;
	  : test0 ['] foo .word ['] bar .word ; immediate
	  test0
	  : test1 test0 ;
	  test1
	  see test1
	  : test2 ` foo ` bar ; immediate
	  : test3 test2 ;
	  test2
	  test3
	  see test3
	
	By laying down an xt, and its class handler, it simulates the behavior
	of 'listen', allowing 'immediate' and 'compile-only' code to inline
	calls, literals, etc.

stub
	( "- )
	Create a stub word, for use with 'is' or ':is'.
	Sample:
	
	  stub foo
	
	Notes:
	This compiles to the same code as:
	
	  : foo ;
	

TRUE
	( -f )
	Return a TRUE flag. 

FALSE
	( -f )
	Return a FALSE flag.

ahead
	( -a ) 
	Compile a jump to 0; leaving the address the jump target is at on the
	stack. Can be patched later.

if
	( - ) 
	This is 'compile-only'.

if;
	( f- ) 
	Exit word if TOS <> 0. This is 'compile-only'.

;then
	( - )
	Exit a word, and close a conditional. This is 'compile-only'. This is
	the same as ';; then'

else
	( R: - )
	( C: a-a )
	Used with 'if'/'then', this lets you conditionally execute code if the
	condition was not met. This is 'compile-only'.
	Sample:
	
	  : foo ( f- ) if ." true" else ." false" then ;
	

=
	( xy-f )
	Compare x = y.

<>
	( xy-f )
	Compare x <> y.

>
	( xy-f ) 
	Compare x > y.

<
	( xy-f )
	Compare x < y.

pow
	( bp-n )
	Returns b^p.
	Sample:
	
	  256 3 pow
	
	Is the same as:
	
	  256 dup dup * *
	

r
	( -n )
	Get a copy of the top item on the return stack and place it on the data
	stack. Identical to 'pop dup push'. This is 'compile-only'.

rdrop
	( RS: - )
	This drops the top value on the return stack. It is 'compile-only', and
	acts the same as 'pop drop'. 

within
	( xlu-f ) 
	Check to see if 'x' is between 'l' and 'u'. The range is inclusive.

."
	( "- )
	Parse for and display a string. This is 'immediate' and can be used
	inside a definition.

decimal
	( - )
	Set 'base' to 10. This is the default setting.

hex
	( - )
	Set 'base' to 16.

octal
	( - )
	Set 'base' to 8.

binary
	( - )
	Set 'base' to 2.

find
	( "-af )
	Search for a word. Return an address and flag indicating success or
	failure.

.
	( n- )
	Display a number in the current 'base', with a trailing 'space'. 
	See also: '(.)'

xt->d
	( a-d )
	Get a dictionary header corresponding to an address.

.does
	( R: aa-a )
	( C: aa- )
	Superclass for 'does>'. See CreateDoes.

does>
	( -a )
	Reassign the class of a 'create''d word to the code following 'does>'.
	Lays down a pointer to the xt of the word, a pointer to the code after
	'does>', and a call to '.does'. See CreateDoes.

space
	( - ) 
	Display a space.

eval
	( ac- )
	Evaluate a string, starting at 'a', and being 'c' cells in length.

ifNotDefined
	( ""- )
	Parse for a name and execute a code block if the name is not defined. 
	Sample:
	
	  ifNotDefined rem { bye }
	

ifDefined
	( ""- ) 
	Parse for a name and execute a code block if the name is defined. 
	Sample:
	
	  ifDefined rem { bye }
	

fori
	( R: n-i )
	( C: -a )
	Start a 'fori' loop. The current loop index (from 0 to n-1) is pushed
	to the stack each time the loop repeats. This is 'compile-only'

nexti
	( R: - )
	( C: a- )
	Close a 'fori' loop. This is 'compile-only'

fastRender
	( - )
	Defer output generated by the calling word until the word executes.

elements
	( n"- )
	Create a series of variables. 'n' denotes the number of items. The
	memory allocated for the values will be contiguous and can be accessed
	as an array.

>last
	( a- ) 
	Move a dictionary entry to the top of the dictionary.

expose
	( "- ) 
	Parse for a word and move it to the top of the dictionary.

include
	( "- ) 
	Add a file to the input stack. This parses for a filename, and attempts
	to treat it as a source of input. It is not supported by all NgaroVm
	implementations, and should act as a no-op after parsing if the VM
	doesn't support it.