( n a -- )
	Store the cell "n" at address "a"
	see also: @
 

( <str>" -- a n )
	Create a string by parsing input up to the next double-quote.  If
	compiling, the string data are put in the heap and the runtime
	code will push the address and length of the string on the stack.
	If interpreting, the address and length will be put on the stack,
	and the string will be allocated from a buffer for transient
	strings.  In either case, one may put a double quote inside a
	string by prefacing it with the '\' (backslash) character:
	"\"Hi!\", said Mary"
	see also: strings
 

( -- )
	see (") 

 ( -- )
	Same as "|" - a comment to end-of-line.  This permits Linux-scripts to
	indicate via a line like:
		#! /bin/reva
	that they should be interpreted by Reva.
	see also:  @rem
 

( <name> -- xt | a n 0 )
	Look up the word "<name>" in the dictionary.  Returns the xt of
	the word in question, or the name and 0 on TOS.
	see also:  '' find (find)
 

( <name> -- dict | a n 0 )
	Similar to "'", but returns the dictionary pointer instead of the xt
	see also:  ' find (find)
 

( xt -- )
	Implementation of "alias" class.
 

( xt -- )
	Implementation of the "forth" class. 

( xt -- )
	Implementation of the "inline" class. 

( xt -- )
	Implementation of the "macro" class. 

( xt -- )
	Implementation of the "notail" class. 

( <text> -- )
	Inline comment, most often used to document the stack effects of a word.
	Parses until the next ")" character and drops the parsed text
	see also:  | 
 

( -- )
	Compiles the string "a,n" into the 'compiled string area' and
	compiles code to push that string on the stack, in 'here'.  The
	word "" is used by " in interpret mode to place the string in one
	of several rotating buffers. 

( -- )
	You want to use "lib" instead.
	OS code to unload the library handle (which had been created with
	(lib))
	see also: lib func
 

( n -- a n )
	Converts a number to a string using the current "base", without
	trailing space. Used by "."
	
	NOTE: The string returned should be saved elsewhere if you won't
	use it immediately!

	see also:  . (.r) .r (p.r) base
 

( x y -- a n )
	Converts the number "x" into a string of width "y", using
	"padchar" to fill in on the left if necessary.  Uses the current
	"base" for numeric conversion.
	
	NOTE: The string returned should be saved elsewhere if you won't
	use it immediately.

	NOTE: Does *not* truncate the outputted number to the width
	specified.
	
	see also:  .r . (.) (p.r) base
 

( -- )
	Pointer to the raw 'argv' data.  You probably want 'argv' instead.
	see also: argv argc
 

( n -- )
	Leave Reva with errorcode "n"
	see also:  bye
	 

( func n -- )
	Internal word used by 'func' - you probably don't want to use it.
	Calls 'func', pushing N params from the Forth stack to the CPU stack.
	Cleans up the CPU stack afterwards, and leaves the function result on
	TOS (garbage value if a "void" function return).  
	see also: func lib
 

( a n -- )
	Same as 'create' but operates on a passed-in string
	see also:  create header
 

 ( -- )
	You don't want to use this word; it's internal to the
	various conditionals.
	see also: conditionals
 

( -- )
	Pointer to environment strings array.  You probably want "getenv"
	see also: getenv
 

( a n -- )
	Same as "find" but returns the dictionary pointer for the word.
	see also:  ' '' find

 

( a n lib -- handle )
	Internal word used by 'func' - you probably don't want to use it.
	Returns a handle to the named function from the library
	see also: func lib
 

( a n -- )
	Create a new entry in the dictionary named for the passed-in string.
	see also:  header
 

( -- a )
	Returns a pointer to the variable holding the value of 'here'
	see also:  here
 

 ( -- )
	You don't want to use this word; it's internal to the
	various conditionals.
	see also: conditionals 

( a n -- )
	Same as 'include', but reads the string passed as a file name.
	see also:  include
	
 

( -- )
	You want to use "lib" instead.
	OS code to load the named library.  Returns a handle.
	see also: lib func
 

( -- )
	You don't want this word; see "loop".  But since you asked, it
	compiles either a short or long jump to the origin of the loop, as
	appropriate.
	see also: flow-control 

( n m c -- a n )
	Prints the value "n" to a string "m" wide, left-padded with character
	"c". The string returned should be saved elsewhere if you won't use it
	immediately.
	see also: (.r) (.) . .r
 

( -- )
	internal: used to implement "
 

( -- )
	Save the state of the program to the file named.  
	see also: program-control
 

( whence offset handle -- )
	Used to implement "seek"; this word is similar to the Unix "fseek"
	word, and has the same semantics.  "whence" is one of:

	0 - SEEK_SET, from the beginning of the file
	1 - SEEK_CUR, relative to the current position, or
	2 - SEEK_END, from the end of the file

	see also: seek tell file-io

 

( -- )
	You don't want this word; see "while"  and "(loop)"
	see also: flow-control
 

( a b -- n )
	Multiply top two items (signed): n=a*b
	see also: / */ mod /mod + - << >> 

( a b c -- n )
	Scaled multiplication operator (signed): n=(a*b)/c. 

	This uses the CPU's internal accuracy, and so does not have
	problems of 32-bit overflow errors which using * and / separately
	might have.

	see also: / * mod /mod + - << >>
 

( a b -- n )
	Add top two items: n=a+b
	see also: - / *
 

 ( n a -- )
	Add "n" to cell at location "a". Same as effect as:

		swap over @ + swap !
 

( a -- )
	Increment the cell at location "a".
	see also: -- 

( n a lstr -- )
	Same as "+place" but for "long" strings over 255 characters
	see also: lplace c+lplace strings 

( n a cstr -- )
	Append the string to a cstring, which is up to 255 characters.  
	see also: place c+place strings 

 ( n -- )
	Put one cell at "here", and increment here by
	the number of bytes put there. 
	see also: 1, 2, 3,
 

( a b -- n )
	Subtract b from a: n=a-b
	see also: + / *
 

( a -- )
	Decrement the cell at location "a".
	see also: ++
 

( a n c -- a1 n1)
	Same as chop but scans from the end of the string 
	see also: chop strings
 

( a b c -- c a b )
	Rotate top three items counter-clockwise 
	see also: stack-ops
 

 ( n -- )
	Prints a number followed by a space using the default base 
	see also: base .r (.) (.r) (p.r)
 

( <str>" -- )
	Types the string <str>.  The same string definition rules apply as
	for "
	see also: strings
 

( n -- )
	Print low 8 bits of a number as 2 hex digits, regardless of "base"
	see also: .x

 

( -- )
	Display list of external functions currently defined.  The handle
	shown is 0 if the function has not been loaded yet.  The word "::"
	indicates the func is not directly accessible.
	see also: .libs
	 

( -- )
	Display list of libraries currently defined.  The handle shown is
	0 if the library has not been loaded yet.  The word "::" indicates
	the lib is not directly accessible.
	see also: .funcs
	 

( x y -- )
	Prints number 'x' in a field 'y' wide.  Uses '(.r)' to format the number
	and appends a space afterwards, like '.'
	see also: (.r) . (.) (p.r)
 

( -- )
	Displays (up to) top ten return-stack items.
	see also: .s stack-ops
 

( -- )
	Displays (up to) top ten stack items.
	see also: .rs stack-ops
 

( -- )
	Display the version, including OS 
 

( n -- )
	Print a number as 8 hex digits, regardless of "base"
	see also: .2x 

( a b -- d )
	Divide a by b (signed): n=a/b
	see also: * */ mod /mod + - << >>
 

( a n c -- a1 n1 )
	Find character 'c' in string. Returns string beginning with the
	character found, or 0 0.  
	see also: \char strings 

( a b -- rem quo )
	Divide "a" by "b", place remainder and quotient on stack 
	see also: / mod
 

( n -- n | exit in n=0 )
	Exit a word if "n" == 0, but does NOT pop TOS.
	Does not change the stack it TOS not 0
	see also: 0;
 

( n -- n | exit and drop TOS if n=0 )
	Exit a word if "n" == 0, and also pop the stack in that case.
	Does not change the stack it TOS not 0
	see also: 00; 

( n -- )
	Execute condition if 'n' is zero
	see also: conditionals
 

( a n -- a n )
	Forces the string "a,n" to be NUL terminated.
	see also: strings
 

( n -- n )
	Increment TOS: ++n
	see also: 1- ++ -- 

( n -- )
	Put one byte at "here", and increment here by
	the number of bytes put there. 
	see also: , 2, 3,
 

( n -- n )
	Decrement TOS: --n
	see also: 1+ -- ++
 

 ( d 2var -- )
	Stores a double (8 bytes) "d" to a memory address "2var".
	see also: 2@, 2variable

 

( n -- 2*n ) 
	Multiply TOS by 2
	see also: 2/
	 

( n -- )
	Put two bytes at "here", and increment here by
	the number of bytes put there. 
	see also: 1, , 3,
 

( n -- 2*n ) 
	Divide TOS by 2
	see also: 2*
	 

( 2var -- d )
	Gets a double (8 bytes) from address "2var".
	see also: 2!, 2variable
 

( n -- n )
	Advance "n" by two cells (8 bytes) 
	see also:  cell+ 

( a b -- )
	Drop top two cells 
	see also: stack-ops
 

( a b -- a b a b )
	Duplicate top two cells 
	see also: stack-ops
 

( a b c d -- a b c d a b )
	Copy 3rd and 4th stack items over TOS
	see also: stack-ops
 

( a b c d -- c d a b )
	Swap top doubles
	see also: stack-ops
 

( <name> -- )
	Creates a new variable "<name>" which can hold a double.
	see also: 2@, 2!
 

( n -- )
	Put three bytes at "here", and increment here by
	the number of bytes put there. 
	see also: 1, 2, ,
 

( n -- n )
	Advance "n" by three cells (12 bytes) 
	see also:  cell+ 

( a b c -- a b c a b c )
	Similar to 2dup.  This has been used often enough to justify
	adding it to the core.
	see also: 2dup stack-ops
 

( n -- n )
	Advance "n" by four cells (16 bytes) 
	see also:  cell+ 

( <name> -- )
	Create a new word called "<name>".  Everything between this and
	the corresponding ";" are executed when "<name>" is invoked.
	see also:  ; :: 
 

( -- xt )
	Create a new word without a dictionary entry. "xt" is the pointer
	to the compiled code for the word.  This is mainly useful for
	providing an anonymous function to use as an implmentation of a
	defer-ed word.
	see also:  : ;
 

( -- )
	End a word definition started with ":".  Compiles a 'return' into
	the code space.  If the last thing compiled was a call to a word,
	optimizes it to a 'jump' to that word - thus implementing
	"tail-recursion optimization".  Also signals that we've stopped
	compiling.
	see also:  : :: ;; notail
 

( -- )
	Exit the current word without signalling that compilation has stopped.
	see also:  ; : ::
 

 ( m n -- flag)
	Returns 'true' or 'false' depending on the test "m<n" using
	signed-math.
	
	Example:
		2 3 < .
			prints: -1
		2 -3 < .
			prints: 0

	see also:  > = 

( a b -- n )
	Shift a left b bits: n=a*2^b
	see also: >> / * + -
 

( a b -- )
	Execute condition if "a" <> "b" (not-equal)
	see also: conditionals
 

( a b -- )
	Execute condition if "a" < "b"
	see also: conditionals 

 ( m n -- flag)
	Returns 'true' or 'false' depending on the test "m=n" using
	signed-math.
	see also:  < >
 

( a b -- )
	Execute condition if "a" = "b"
	see also: conditionals 

 ( m n -- flag)
	Returns 'true' or 'false' depending on the test "m>n" using
	signed-math.
	see also:  < = 

( a b -- n )
	Shift a right b bits: n=a/2^b
	see also: << / * + -
 

( dict -- a )
	Return the class field pointer from a dictionary pointer.
	see also:  >name >size >xt
 

( n -- c )
	Convert digit to its ASCII representation 
	Example:
		10 >digit emit
	shows 'A'
	see also: digit>
 

( a b -- )
	Execute condition if "a" > "b"
	see also: conditionals 

( -- tin )
	Variable holding pointer to current location in tib. 
	see also:  src
 

( xt -- xt' )
	Takes the xt of a 'literal', and returns the value it points to
 

( a n a2 -- a2 m )
	Compress the buffer "a,n" into the buffer "a2".  Returns "a2,m",
	where 'm' is the compressed length.  The buffer 'a2' must be big
	enough to contain 'lzmax' characters - e.g. "n lzmax allocate"
	will allocate a buffer big enough to hold the worst-case size of
	compressing 'n' bytes.  Used by the turnkey code to compress the
	dictionary and code data.
	see also: lz> lzmax
 

( dict -- a )
	Return the name field pointer from a dictionary pointer.
	see also:  >class >size >xt
 

( n -- r:n )
	Puts top stack item on return stack 
	see also: r-stack-ops
 

( n -- )
	Puts "n" under the top of the return-stack.  "tuck" for the
	return-stack.
	see also: r-stack-ops

 

( a n -- m true | a n false )
	Convert string to a number.  TOS will be true or false; true if
	the conversion succeeded - then 'm' will be the numeric value;
	false if it failed, then 'a n' is the original string.
	
 

( dict -- a )
	Return the size field pointer from a dictionary pointer.
	see also:  >name >class >xt
 

( dict -- a )
	Return the xt field pointer from a dictionary pointer.
	see also:  >name >class >size

 

( max start -- )
	ANS-compatible '?do'. Iterates from 'start' to 'max'-1.  If 'max'
	and 'start' are equal, will not do any iterations.
	see also: flow-control

| || 

( n -- n n )
	Duplicates TOS if it's not zero. 
	see also:  stack-ops
 

( a -- n )
	Returns the cell pointed to by the address in a 
	Be careful not to pass an invalid address to it!
	see also: !
	
 

( a -- )
	Same as "@ execute" but more efficient
	see also:  execute
 

( -- )
	Used for writing Reva "batch" files under Windows
	see also:  #!
 

( -- )
	Stop compiling and switch to the interpreter 
	see also:  ]
 

( <name> -- )
	Compile xt of "<name>"
	see also:  ' compile
 

( <name> -- flag )
	Returns "true" if the word has been defined, "false" otherwise.
	Intended to be used to take some action based upon runtime
	environmental issues.
	see also:  preprocessor
 

( -- )
	Used with [IF] and [THEN] for conditional compilation 
	see also:  [IF] [THEN] preprocessor
 

( n -- )
	Used with [THEN] and [ELSE] for conditional compilation. Exactly
	analagous to if/else/then, except that this allows one to compile
	based on a condition. The code in the branch not taken is not
	compiled and therefore doesn't contribute to the dictionary or
	have any side-effects.  Similar to "#if ... #endif" in C

	NOTE: one may NOT nest [IF]...[THEN] blocks!

	see also:  [THEN] [ELSE] preprocessor
 

( -- )
	Used with [IF] and [ELSE] for conditional compilation 
	see also:  [IF] [ELSE] preprocessor
 

( a n c -- a1 n1 )
	Same as /char but scans from the end of the string  
	see also: /char strings
 

( -- )
	Return to the compiler
	see also:  [
 

( n -- n )
	Return absolute value of top stack item.  
 

( a n -- m )
	Accepts at most 'n' characters into the buffer at 'a'; returns 'm'
	the number of characters read.  The ESC key cancels the accept and
	returns '0', CR key ends input before 'n' characters have been
	read.
	see also: console-io
 

( -- )
	Return to top of loop started by "repeat"
	see also: flow-control
 

	This library implements a simple C-style "enum", allowing you to
	quickly create a bunch of constants with increasing values.  It
	defines:

		enum: ( start# -- )
			Begins the enumeration from 'start#'.

		enum; ( -- )
			Terminates the enumeration.

	Example: 

		1 enum: ONE TWO THREE enum;
	 

	Simple singly-linked list implementation.  The following words are
	defined:
		(list-compare) - variable which holds the 'comparison'
			function for this list.
		list ( <name> -- ) 
			Creates a new 'list' object
		list-append ( list ptr -- )
			Appends 'ptr' to the list
		list-prepend ( list ptr -- )
			Prepends 'ptr' to the list
		list-insert ( list ptr -- )
			Inserts 'ptr' into the list, using (list-compare) to make
			an ordered list
		list-find ( list ptr -- closest | list )
			Looks for the closest match to 'ptr' (based on
			(list-compare)) and returns it, or 'list' if all items in
			the list are smaller than 'ptr'
		list-do ( list xt -- )
			Iterate over list and execute 'xt' for each item.  The
			'xt' is called with the item on TOS
	 

	Arbitrary sized stack.  Words are:

		stack: ( n <name> -- )
			Creates a 'stack' called "<name>", which can hold "n"
			cells worth of data.
		push ( x stack -- )
			Pushes 'x' onto the named stack
		pop ( stack -- x )
			Pops "x" off the named stack
		peek ( stack -- x )
			Gets TOS from the named stack, but does not pop it.
	 

	Allows "C" style structures.

		struct: ( <name> -- xx offset )
			Creates a new "struct" called "<name>".  Must end with "struct;"
		struct; ( xx offset -- )
			Terminates a "struct", and sets its "size" field
		sizeof ( <name> -- n )
			Gets the size of the named structure
		field: ( ofs size <name> -- ofs' )
			Creates arbitrarily sized field named "<name>".
		byte:
		short:
		long:  ( <name> -- ofs' )
			Create 1, 2 or 4-byte fields

	Example:
		
		struct: mystruct
			byte: id
			long: hash-code
			3 field: tri-byte
		struct;
		mystruct m1 

		m1 id + c@ | the id field
		m1 tri-byte + @ $ffffff and | the tri-byte field 
		... etc....

	 

( xt <new> -- )
	Create an alias for xt, so saying <new> results in the same. 
	see also:  alias:
 

( oldname newname -- )
	Create alias 'newname' for the word 'oldname', keeping the proper
	class semantics of the old word.
	see also:  alias
 

( -- )
	Align "here" to the next four-byte boundary.
	see also: aligned
 

( a -- a )
	Align the address on TOS to the next four-byte boundary.
	see also: align
 

( n -- addr )
	Allocates memory from the OS. 
	see also: free, resize
 

( n -- )
	Allocate memory by moving "here" by "n" bytes.  Can also be used
	for deallocation from 'here' if given a negative number. 
 

( a b -- n )
	AND top two items, like C bitwise operator: a & b
	see also:  or not xor
 

	This library implements a partial and quite incomplete ANS
	compatibility layer for Reva.  I am not sure if I will put more
	effort into maintaining it, as I think it is more effort than it
	is worth.

	Invoking Reva with the "-a" command-line switch loads this
	library.
	 

( -- a n )
	Return the full path to the running program, including trailing
	path-separator character
	see also: appname libdir pathsep needs
 

( -- a )
	Return a NUL terminated string containing the fully qualified name
	of the actual program file this application started from.
	see also: appdir
 

( -- )
	Similar to "main" in C,  this is the starting point for the
	application itself.  Called after 'hello'
	see also: hello onstartup onexit
 

( -- n )
	One more than the number of command-line arguments passed to Reva.
	So if no arguments were passed, argc is 1  
	see also: argv
 

( -- a )
	Internal word used by the startup code to keep track of the current
	command-line argument being processed.
 

( -- a )
	Address of variable holding the index of last 'argv' processed.
	see also:  argc# argc argv
 

( n -- addr len )
	Get command-line argument "n". The number is in the range 0.."argc". The
	first argument, "0 argv" is the name of the program; 1 is the index of the
	first user-supplied argument, etc.  

	If you pass a value that is out of range, it will be clamped to
	the proper range.  So "-1 argv" is the same as "0 argv"
	see also: argc
 

( a n -- )
	Puts the string 'a','n' into a counted-string at 'here' and
	adjusts 'here'. 
	see also: asciizl, 

( a n -- )
	Same as 'asciiz,' but puts a long-counted-string at 'here'.
	see also: asciiz,
 

	This library implements:
		asm{ ( <asmcode>} -- ) MACRO

	This lets you inline assembly language code directly instead of
	hard-coding opcodes and poking.  Requires that FASM be installed
	and available on your system, and will slow down Reva a little
	while compiling asm{ blocks.  

	Example:

		: incr asm{ inc eax } ;

	Note: lines between "asm{" and "}" MUST be in valid FASM syntax,
	one statement per line!
	 

( n -- )
	Generates code to jump back to the address specified on TOS
	see also: flow-control
 

( -- a )
	Returns a pointer to a variable containing the current base for
	number conversion.

	Example:

		6 2 base ! .

		prints "6" in binary, "110"
	see also: . decimal octal hex binary
 

( a b c -- flag )
	Returns true if "a">="b" and "a"<="c" 
 

( -- )
	Change base to binary (base 2) 
	see also: hex octal decimal base
 

( -- )
	Same as "0 (bye)"
	see also:  (bye)
 

( n a -- )
	Store byte "n" at address "a" 
	see also: c@
 

( c lstr -- )
	Like c+place except for long-strings.
	see also: lplace +lplace strings 

( c cstr -- )
	Append byte "c" to a cstring. 
	see also: place +place strings 

( a -- n )
	Return the byte stored at address "a" 
	see also: c!
 

( xt -- throwcode )
	Execute "xt", catching any throw which may have occurred. If no
	throw happened, 'throwcode' is zero - otherwise it's the value
	'throw'n
	throwcode of zero. 
	see also: throw
 

( xt numparams stacksize <name> -- )
	Create a new word whose xt can be used as a callback for a cdecl
	function. It is crucial the numparams be correct, or the callback
	will crash. 
	
	The "xt" is a normal Forth word, and can use any other Forth words
	it needs - subject to the 'stacksize' (number of words available
	for this callback to push) and subject to any environmental issues
	regarding the platform you are running on.

	see also: stdcb: 

( n -- n )
	Advance "n" by one cell (4 bytes) 
	see also:  cell- 

( n -- n )
	Diminish "n" by one cell (4 bytes) 
	see also:  cell+
 

( n -- n )
	Return number of bytes required by "n" cells
 

( xt n -- ) 
	Puts "xt" in the most recent 'choices:' variable, where 'n' is the
	value which will cause 'xt' to be executed when the 'choice:'
	variable is executed.
	see also:  choices: default

 

( <name> -- )
	Creates a new 'choice' variable called '<name>'.  This sets up a
	sort of 'sparse array' decision tree.  Use it like this:
	 
		choices: mychoices
			' choice1  'a choice
			' choice2  'b choice
			' choice-default default

	Then you use it like:

		ekey mychoices

	and the appropriate choice gets called.
	see also:  choice default

 

( a n c -- a1 n1 )
	Scan forward in string "a,n" for character "c". Returns the string up to
	the point where that character was found, or the original string if the
	character was not found 
	see also: -chop strings 

	Classes define the behavior of a word when executed by Reva.  A
	word's class is usually defined at the same time as the word is,
	but it can be modified later if desired.  The usual technique in
	Reva is to define a series of words using the same class,
	together; then switch back to the default 'forth' class:

	    inline
		: in1 ... ;
		: in2 ... ;
		forth

	see also:  forth macro inline notail 'alias
	
 

( -- )
	Deferred word which is called by the default 'bye'. Useful for closing
	files etc.  
 

( -- )
	Routine called at exit; unloads any libraries which were loaded
	via (lib) and ensures that it is safe to do a "save"
	see also: atexit save func lib
 

( fileid -- )
	Close "fileid" previously opened with 'open/r' 'open/rw' or
	'creat'.
	see also: file-io 

( a1 n1 a2 n2 -- n )
	Compare two strings, lexicographically. 0 means equal. Useful for
	sorting lists.
	see also: cmpi strings
 

( a1 n1 a2 n2 -- n )
	Save as 'cmp', but compares ignoring case, e.g. 'A' and 'a' are
	equivalent.
	see also: cmp strings
 

( -- )
	Resets the Reva virtual-machine to 'startup' state
	see also: program-control
 

( a -- )
	Compiles a call to the address "a"
	see also:  back
 

( -- flag)
	Returns a flag telling what the state of the interpreter/compiler
	currently is.  Useful inside 'macro' class words so they can
	behave differently if necessary depending on whether invoked by
	the interpreter or the compiler.
 

	These are the conditional statements Reva provides:

		if <>if 0if <if >if =if else then
	
 

	The following console I/O words are available in Reva:
	
		cr space emit key key? ekey type accept spaces
	
 

( n -- )
	Create a constant with the value "n"
	see also:  variable value 

( cstr -- a n )
	Converts a counted-string to an address-count pair.
	see also: place  strings 

( -- )
	Output a CR character (move to next line) 
	see also: console-io 

( a n -- fileid )
	Create a new file for reading and writing.
	see also: file-io 

( <name> -- )
	Create a named entry <name> in the dictionary.  Invoking this name
	will cause the address of the item's private data area to be
	pushed on the stack.  In effect, operating much like 'variable'.
	
	A 'created' item can be located using 'find' or '(find)', assuming
	it was not hidden subsequently or created in a 'loc:' block or in
	a different 'vocab:'
	see also:  (create) does> header  

	MD5 hash algorithm:
		
		md5 ( a n -- a' n' )
			Given an input buffer, returns the string with the 'MD5'
			hash.
	 

	RC4 symmetric encryption
		rc4setup ( a n -- )
			Sets up the encryption box to use the password given.
		rc4 ( a n -- )
			Encrypt the passed-in buffer in-place
	 

( -- a )
	Variable holding value of start of dict space (where dictionary
	starts)
	see also:  h0 s0 str0 rp0 

	Basic calendar functions.  Too many words to document here, look
	in the file itself.
	 

	Ecclesiastical calendar.
	 

	Jewish traditional calendar.
	 

	Some American holidays.
	 

	Islamic traditional calendar.
	 

	ISO calendar
	 

	Julian calendar
	 

	Weekly Torah portion
	 

	Various calendar utility words
	 

	Interface to the SQLite library

		sql_open ( a n -- handle )
			Opens (or creates) the database named, and returns a
			handle to it to be used with the other words
		sql_close ( handle -- )
			Close the database opened by sql_open
		sql_exec ( handle a n -- )
			Execute the SQL statement "a,n" on db "handle"
		sql_exec_cb ( handle a n cb -- )
			Same as 'sql_exec', but calls the passed-in callback for
			each for each row of the result.
		sql_version ( -- a n )
			Gives the string corresponding to the SQLite library
			version.
		sql_result ( -- a )
			Return address of variable containing the result of the
			sql_exec... 

	 

	A start at debugging words:

		name ( xt -- a n )  Takes an 'xt' and returns the name of the
		   word it represents.
	 

( -- )
	Change base to decimal (10) 
	see also: hex octal binary base
 

( xt -- )
	Makes 'xt' the default "choice" to be executed when nothing else
	matches.  The default "default" is to do nothing.
	see also: choice choice:

 

( -- n )
	Pointer to a variable containing the class which new words will
	use. 

	Type 'help' followed by the word you want help on, to get help
	specific to that word.  For example:

		help @

	Will display help about the word "@"

	You may also ask for help about certain topics:

		classes libraries preprocessor stack-ops file-io console-io
		conditionals flow-control program-control  strings
		throw-codes
	
 

( <name> -- )
	Create a deferred word "<name>". Initially this word will do nothing.
	Must be set to something more useful using "is".  Deferred words
	are useful if you want to change the action a word performs - for
	example, a 'print' word which might display to the screen or print
	on the printer.

	They are also useful when you have to make a word available before
	it is defined (called a 'forward reference' in other languages).

	A further use is permitting words to be redefined by later users.
	Reva for example has 'key' and 'type' (among others) implemented
	as deferred words.
	see also:  defer! defer@ is
 

 ( xt <name> -- )
	Create a deferred word "<name>", setting initial value to xt. 
	see also:  defer defer@ is
 

( xt -- xt' )
	Given the xt of a deferred word, returns the current value the
	word will execute.
	see also:  defer defer! is
 

( a n -- )
	Delete the named file
	see also: file-io 

( -- n )
	Puts the stack depth on the top of the stack. This is the number of
	cells currently on the stack.  

	NOTE: a negative value of 'depth' means the stack underflowed.
	This is almost always indicative of a problem!

	see also: rdepth stack-ops 

( a n -- dict )
	Given a string, looks it up in the dictionary - just like
	"find" does.  Returns the dictionary pointer, rather than
	the xt.
	see also:  '' find ' >xt >name >size >class 
 

( c -- n )
	Convert ASCII to the corresponding digit 
	Example:
		'9 digit> .
	shows '9'

	see also: >digit
 

( max start -- )
	ANS-compatible 'do'. Iterates from 'start' to 'max'-1. 
	see also: flow-control
 

( -- )
	Used to implement "does>" 

( -- )
	Change the runtime behavior of a "create"d word.  The normal
	runtime behavior of a "create"d word is to push the address of its
	data area on TOS.  "does>" appends whatever code is after it to
	the default action.

	Example:

		: const create , does> @ ;
		234 const x
		12 const y

	Executing 'x' will put '234' on TOS.  'y' will put '12' on TOS.
	They do this because they are 'const's which as you can see from
	the definition - stash away TOS in the private data area of the
	word on word creation; and put that value on TOS when invoked.
	
	see also:  create
 

( -- )
	internal: used to implement " 

( -- )
	internal: used to implement " 

( -- a )
	Returns the address of the code which handles 'variables'.
 

( a -- )
	Drop the top stack item 
	see also: stack-ops
 

( a n -- )
	Hex dump of the n bytes starting at a.  This is a 'traditional'
	hex dump.
 

( a -- a a )
	Duplicate the top stack item 
	see also: stack-ops
 

( -- c )
	Returns the ASCII value of a keypress as soon as a key has been
	pressed, including special keys.
	see also: console-io
 

( -- )
	Quit the innermost do..loop at the end of the loop and continue
	processing after the 'loop' word.  Essentially the same as
	modifying the loop counter so the loop doesn't repeat again.
	see also: leave flow-control
 

( -- )
	Begin alternate clause of conditional, execute if conditional
	false.
	see also: conditionals
 

( c -- )
	Print character corresponding to the ASCII value 'c'
	see also: console-io
 

( a n -- )
	Interpret the string as if it had been typed in at the console
	see also:  interp
 

( xt -- )
	Execute the word whose code is at "xt"
	see also:  @execute
 

( -- flag )
	Puts logical 'false' (no bits set, 0) on TOS
	see also: true and or xor not
 

 
	The file-io words supported by Reva are:

			creat open/r open/rw read write fsize 
			seek tell rename delete stat mtime
	
 

( a c b -- )
	Fill the memory at "a" with "c" copies of byte "b" 
 

( a n -- xt | a n 0 )
	Look up a word in the dictionary.  Returns the xt of the word in
	question, or the name and 0 on TOS.
	see also:  (find) ' ''
 

( -- )
	Stops the processing of command-line arguments
 

	The following words for flow-control are provided by Reva:

		do loop i j unloop leave
		repeat again while back eleave
		remains more skip ?do later
	
 

( a n -- m)
	Returns the FNV-1a hash of the string passed in.

 

( -- )
	Sets the default class ("default_class") to be "'forth".
	Subsequent words will be of the "forth" class (e.g. "normal" Forth
	words)
	see also:  macro inline notail classes
 

( a -- )
	Free the memory address "a" which had been allocated with
	"allocate".  Return zero on success.  
	see also: allocate, resize
 

( fileid -- n )
	Given an open file handle, return the file size.
	see also: file-io 

( a n N <fname>-- )
	Creates a word "<fname>" which encapsulates a call to the function
	which is located in the most recently used 'lib'.
	
	N is the number of parameters passed to the function, and must
	match EXACTLY what the function expects, or it will crash. 
	
	It doesn't matter whether the called function is cdecl or stdcall.
	Pass in the name of the function and the number of parameters.  It
	will look in the last 'lib' used or declared.

	NOTE: throws THROW_BADFUNC when invoked but the function was not
	loaded.  This may happen if the library was a different version
	than you expected, or if you misspelled the function name.

	see also: lib throw-codes
 

( -- n )
	WINDOWS ONLY: Handle to GDI32 library 
	see also: u32 k32 lib func
 

( a n -- a1 n1 )
	Given an environment variable, returns the value of the variable.  For
	example: " PATH" getenv
	NOTE: This word is case-insensitive on Windows, but case-sensitive
	on Linux.
	see also: (env)

 

( -- n )
	Get the current process id 
 

( -- a )
	Variable holding value of start of code space (where "here"
	starts)
	see also:  d0 s0 str0 rp0 

( <name> -- )
	Create a named entry "<name>" in the dictionary. 
	see also:  create (header) 

( <name> -- )
	Attempts to give help on the word named.

| META-topics: (not words) 

( -- a )
	Returns current value of "here", the end of currently allocated
	dictionary space.
	see also:  (here) 

( a n -- )
	Stores "n" bytes from address "a" to "here" and adjusts "here".  
 

( -- )
	Change base to hexadecimal (16) 
	see also: decimal binary octal base
 

( <name> -- )
	Makes the named word no longer visible in dictionary searches.
	Sort of an after-the-fact "loc:"
	see also:  loc: loc; reveal seal
	 

 ( -- n )
	Return process instance handle 
 

( -- ix )
	Current index of innermost "do" loop.
	see also: flow-control 

( flag -- )
	Execute condition if 'flag' is true
	see also: conditionals
 

 ( -- )
	You don't want to use this word; it's internal to the
	various conditionals.
	see also: conditionals 

	This library changes the behavior of the 'find' family of words to
	to a case-insensitive search.  Reva by default is case-sensitive,
	so "word" and "Word" are not the same.  This library makes them
	the same, at a cost of substantially decreasing interpretation
	speed (if you have a fast machine you won't notice probably).
	
 

( <name> -- )
	Read in the file "<name>" and evaluate it. Silent on failure, but
	'ioerr' will be non-zero.
	see also:  (include) needs ioerr 

( -- )
	Sets the default class ("default_class") to be "'inline".
	Subsequent words will be of the "inline" class - e.g, words whose
	bodies are copied directly into the compiled code - rather than
	the usual, which is to compile a call to the word's code
	see also:  forth macro notail classes
 

( -- )
	Force the interpreter loop to start again 
	see also: eval program-control
 

( n -- n' )
	Invert all bits in "n". Same as C "~" operator: n=~n
	see also: not negate
 

( -- a )
	The address of a variable containing the last "I/O error result",
	which is zero for success.
	see also: file-io 

( xt <name> -- )
	Sets the deferred word "<name>" to execute "xt" when invoked.
	see also:  defer defer@ defer!
 

( -- ix )
	Current index of enclosing "do" loop.
	see also: flow-control 

( -- n )
	WINDOWS ONLY: Handle to KERNEL32 library 
	see also: g32 u32
 

( -- c )
	Returns the ASCII value of a keypress, but only returns when CR has been
	pressed
	see also: console-io 

( -- flag )
	Returns 'true' if a character is waiting to be read from the
	input.
	see also: console-io
 

( -- a )
	Address of variable holding the address of the most recently
	defined dictionary entry
	see also:  find
 

( x y -- )
	Used after a "voc:" word was executed, to return to the last vocabulary 
	see also:  voc:
 

( -- )
	This is a unique flow-control word.  What it does is return
	immediately to the calling word, and when the calling word exits,
	resumes after the 'later'.

	Example:

	    : a ." in a " later ." later, dude!" ;
		: b ." in b " a ." after a " ;
		b

	Prints:

	    in b in a after a later, dude!
	see also: flow-control
	 

( c -- c )
	Converts the character 'c' to its lowercase equivalent.  NOTE: this is
	a simple ANSI transform, and does not work at all correctly for
	accented characters (for example).
	see also: strings
 

( cstr -- a n )
	Converts a long-counted-string (>255 chars) to an address-count
	pair.
	see also: lplace strings
 

( -- )
	Quit the innermost do..loop immediately and continue processing
	after the 'loop' word.
	see also: eleave flow-control 

( a n <libname>-- )
	Declares a word "<libname>" which encapulates a "dynamic library"
	(DLL or SO).  When it is declared, it becomes the default library
	for new 'func' declarations.  When executed, it also becomes the
	default library but in addition, puts the handle of the loaded
	library on TOS.

	NOTE: throws THROW_BADLIB when invoked but the library was not
	loaded.  This may happen if the library doesn't exist on your
	system or if you misspelled the library name.

	see also: func throw-codes 

( -- n )
	LINUX ONLY: Returns a "lib" handle for libc. 
	see also: lib func
 

( -- a n )
	Full path to "lib" directory, which is where the standard Reva
	libraries are stored.  The word "needs" uses this to find
	libraries.
	see also: appdir needs REVAUSERLIB
 

	The set of words built-in to Reva is impressive considering the
	small size of the program.  However, Reva also provides additional
	words covering a variety of fields, ready for use. These extra
	'libraries' are in the 'lib' subdirectory, and are currently:

		ansi asm ignorecase
		alg/enum alg/list alg/stack alg/structs
		crypt/md5 crypt/rc4
		date/calendar date/church date/hebrew date/holidays
		date/islam date/iso date/julian date/sedra date/util
		db/sqlite debug/debugger
		math/doubles math/float
		net/sockets
		os/console os/exception os/registry os/shell
		random/gm random/simple
		string/justify string/misc string/soundex string/trim
		string/regex string/iconv string/unicode
		util/auxstack util/classes util/eachline util/many
		util/misc util/tasks util/zlib
		util/case util/locals
	
	To use any of them, use 'needs'.  For example:

		needs date/calendar

	For help on what they do, just ask help:

		help date/calendar

	see also:  needs
	
 

( n -- )
	Compile the top stack item into the current word, as a literal. 
	see also:  literal, compile
 

( n -- )
	Same as "literal" but operates at run-time.
	see also:  literal compile
 

( -- )
	Begins a 'local definitions' list
	Anything defined between loc: and loc; is "local" and not visible in the
	dictionary unless specifically exposed.
	see also:  loc; reveal hide seal 

( -- )
	Ends a 'local definitions' list.
	see also:  loc: reveal hide seal 

( -- )
	If 'i' is less than the top bound for the current "do", return to
	the top of the do..loop and increment 'i'; otherwise, fall out of
	the do..loop
	see also: flow-control
 

( a n lstr -- )
	Same as "place" but for long strings over 255 characters.
	see also: lcount +lplace c+lplace strings
	
 

( a n a2 -- a2 n )
	Decompress the (previously compressed) buffer "a,n" into buffer
	"a2,n".  The 'n' is the uncompressed size of the buffer - so you
	need to know this when you call the "lz>" word!
	see also: >lz lzmax
 

( n -- m )
	Returns the maximum possible size required to compress a buffer of
	'n' bytes.
	see also:  >lz lz>
 

( -- )
	Sets the default class ("default_class") to be "'macro".
	Subsequent words will be of the "macro" class - e.g, words which
	are executed as soon as they are interpreted (like IMMEDIATE in
	ANS)
	see also:  forth inline notail classes 
 

( <name> -- )
	Creates a word which when executed, will revert the system to the
	state it had before that word was created.  This is very useful
	when you want to "play around" with things and remove their
	side-effects.
	
 

	Implementation of double (two-cell) words:


	s>d ( n -- d )  Sign-extend the cell 'n' to a double 'd'
	d+  ( d1 d2 -- d3) Adds "d1" and "d2" to make "d3"
	d-  ( d1 d2 -- d3) Subtracts "d2" from "d1" to make "d3"
	m+  ( d1 n -- d2 ) Adds the cell 'n' to the double 'd1' to make
    	the double 'd2'
	d= ( d1 d2 -- flag ) Compares the two doubles and returns a flag
	dnegate ( d1 -- -d1 ) Changes the sign of 'd1'
	dabs ( d1 -- d1 ) Returns the absolute value of 'd1'
	fm/mod ( d n -- rem div ) Divides 'd' by 'n',  giving the
		'floored' remainder and quotient.
	m* ( n1 n2 -- d ) Multiplies two cells n1 and n2, giving double 'd'
	um* ( u1 u2 -- ud2 )  Same as 'm*' but unsigned math.
	udm* ( ud n -- ud1 ) Like um*, but multiplies an unsigned double
	>double ( a n -- d true | a n false ) Converts a string to a double
	d# ( d1 -- d2 c ) Divide d1 by "base" giving d2, and convert low
		digit to character representation.  For example:
		"12. d#" gives 1 0 50 where '50' is ASCII for '2'
	(d.) ( d -- a n ) Like (.) but for doubles
	d. ( d -- ) Like . but for doubles

	 

	Implementation of floating-point math words.  Uses FPU stack, so
	limited to 7 floats on FP stack:
	
	fldcw ( -- n ) Get FP control word from FPU
	fstcw ( n -- ) Store new FP control word into FPU
	round.trunc round.even round.down round.up ( -- ) change rounding
		options for the FPU
	finit ( -- ) Initialize the FPU to known default state.
	f+ ( f:a f:b -- f:a+b ) Add two floats
	f- ( f:a f:b -- f:a-b ) Subtract top float from next to top.
	f* ( f:a f:b -- f:a*b ) Multiply two floats
	f/ ( f:a f:b -- f:a/b ) Divide two floats
	fswap ( f:a f:b -- f:b f:a ) Swap top two FP items
	fsin ( f:a -- f:sin[a]) sin(TOFS)
	fcos ( f:a -- f:cos[a]) cos(TOFS)
	ftan ( f:a -- f:tan[a]) tan(TOFS)
	fnegate ( f:a -- f:-a ) Negate TOFS
	f0 ( -- f:0.0 ) FP zero to TOFS
	f1 ( -- f:1.0 ) FP one to TOFS
	fpi ( -- f:pi ) FP pi (3.1415...) to TOFS
	fdup ( f:a -- f:a f:a ) Duplicate TOFS
	fdrop ( f:a f:b -- f:a )  Drop TOFS
	fabs ( f:a -- f:a ) abs(TOFS)
	s>f ( n -- f:a ) Convert TOS to TOFS
	d>f ( d -- f:a ) Convert double at TOS to TOFS
	f! ( addr f:a -- ) Store TOFS into fvariable 'addr'
	f@ ( addr -- f:a ) Retrieve TOFS from fvariable 'addr'
	f= ( f:a f:b -- flag ) Compare top two floats
	ffrac ( f:a -- f:a ) Get fractional part of TOFS
	f>s ( f:a -- n ) Convert TOFS to TOS
	f>d ( f:a -- d ) Convert TOFS to double on TOS
	f*10 ( f:a -- 10*f:a) Multiply TOFS by 10
	f/10 ( f:a -- f:a/10) Divide TOFS by 10
	10^n ( n -- f:10^n ) Put 10 raised to n'th power on TOFS
	str>f ( a n -- f:x ) Convert the string to float and put in TOFS
	f ( <fp> -- f:x ) Convert the following text to float and put in TOFS
	fvariable ( <name> -- ) Create a variable named <name> to hold a float
	fconstant ( f <name> -- ) Put 'f' in a constant <name>
	sigdig ( -- a ) Variable holding 'number of significant digits' displayed
	(f.) ( f:x -- a n) Convert TOFS to string
	f.r  ( n f:x -- a n ) Convert TOFS to string 'n' wide
	f.	( f:a -- ) Same as . but for floats
	 

( a b -- c )
	Puts the max (signed) of a and b on TOS: c=max(a,b)
	see also: min
 

( a b -- c )
	Puts the min (signed) of a and b on TOS: c=min(a,b)
	see also: max
 

( a b -- n )
	Divide a by b, and put the modulus (remainder) on TOS: n=a%b  
	see also: /mod /
 

( n -- )
	Set the do-loop to execute 'n' more iterations
	see also: flow-control 

( src dst n -- )
	Moves "n" bytes from "src" to "dst".
 

( n -- )
	Pauses for n milliseconds 
	see also:  ms@
 

( -- n )
	Retrieves current millisecond count, which may be used for timing
	see also:  ms
 

( a n -- n )
	Get the last-modified time of the named file, in Unix "seconds
	since 1/1/1970" format.
	see also: file-io 

( <name> -- )
	Locates the file "<name>" in the user library directory or the
	standard library directory includes it if it has not already been
	included.
	see also:  libdir REVAUSERLIB
	 

( n -- n )
	Flip the sign of n, same as C "unary -" operator: n=-n
	see also: not invert

 

	Socket access library.  See generic sockets documentation for
	details on how to use (or see examples/smtp.f)

		socket ( domain type proto -- sock )
		bind ( sock name len -- result )
		connect ( sock sockaddr flags -- result )
		listen ( sock backlog -- result )
		accept ( sock addr len -- result )
		gethostbyname ( name -- result ) pass a NUL terminated string
		closesocket ( sock -- result )
		send ( sock addr len flags -- result )
		recv ( sock addr len flags -- result )

		sockbad? ( sock -- sock flag )
		tcpsock ( -- sock ) Initialize a TCP socket
		udbsock ( -- sock ) Initially a UDP socket
		host>addr ( a n -- ipaddr ) Get IP address of host
		connectsocket ( a n port -- sock ) Connect to named host:port
			using TCP If "n" is zero, then "a" is an IP address.
	 

( a -- )
	Adjusts the input for this eval as starting from "a".  Takes care
	of adjusting "tin" etc.
 

( a b c -- a c )
	Drop the second stack item 
	see also: stack-ops
 

( -- )
	Does nothing. This is the default value for 'defer'ed words.  
 

( a -- n )
	Logical not of a. 0 => -1, !0 => 0, similar to C "!" operator
	see also:  and or xor
 

( -- )
	Same as "forth", but sets the class as "'notail".  This class
	supresses the 'tail-recursion-optimizer', and is used when using
	the word as the last word in a colon-def causes problems because
	the return stack is not what was expected.  Some words like ">rr"
	use this class.  All 'macro' class words also suppress the
	tail-optimizer now.
	see also:  forth macro inline classes
 

( -- a )
	Returns an "empty" NUL terminated string.  Good for when you need
	to pass such a string to a C library.
	 

( -- )
	Change base to octal (base 8) 
	see also: decimal binary hex base
 

( ptr -- )
	Stores a zero at the address 'ptr'.  Same as "0 swap !"
	see also: on
	 

( ptr -- )
	Stores a -1 (true) at the address 'ptr'.  Same as "true swap !"
	see also: off
	
 

( xt -- )
	Add the xt to the 'exit handlers list'.  This xt will be executed
	when "bye" is called
	see also: program-control
 

( xt -- )
	Add the xt to the 'startup handlers list'.  This xt will be
	executed when "cold" is called, just before "appstart" is called.
	see also: program-control
 

( a n -- h )
	Open the named file for reading.  Sets 'ioerr' appropriately to
	indicate failure.  
	
	Will fail if the file does not exist or if the user has
	insufficient privileges to access it.  In these cases, the
	value of 'h' is indeterminate.
	see also: file-io 

( a n -- h )
	Like 'open/r' but open for both reading and writing.
	see also: file-io 

( a b -- n )
	OR top two items, like C bitwise operator: a | b
	see also:  and xor not
 

( -- n )
	Returns 1 for Linux, 0 for Windows.  
	see also: osname
 

	Console I/O:

	These colors recognized: black red green yellow blue magenta cyan
		white normal bold dim underscore blink reverse concealed 

	Text attribute modifiers: foreground background color

	Position: gotoxy ( row col -- )  savepos ( -- ) restorepos ( -- )

	Misc: conRowsCols ( -- rows cols )  cls
	 

	Not working yet.  Will be exception handling.
	 

	Win32 only: registry functions.  See Win32 API docs

	RegCloseKey RegOpenKey RegCreateKey RegDeleteKey RegQueryValue
	RegQueryValueEx RegSetValue RegSetValueEx RegEnumKey

	HKCR HKCU HKLM HKUS REG_NONE REG_SZ REG_EXPAND_SZ REG_BINARY
	REG_DWORD
	 

	Interface to run external programs:

	shell ( a n -- n ) Run the command specified by "a,n"
	!! ( <to-eol> -- n) Run the command after !!

	Both return the exit code of the process run.
	 

( -- a n )
	Returns the name of the os.  
	see also: os
 

( a b -- a b a)
	Put copy of second stack item on top of stack 
	see also: stack-ops
 

( <name> -- )
	Similar to the ANS word POSTPONE.  Compiles the "xt" of the word
	"<name>" as well as a call to its class-handler.  This means that the
	word will be executed when the containing word is executed, rather than
	being run immediately.  Mostly useful for causing a 'macro' word to
	execute at run time rather than compile-time.
	see also:  x:
	
 

( -- a )
	Return the address of "pad" ( a temporary buffer used by many
	words ) 
 

( -- a )
	Address of variable holding the value used to 'pad' output
	numbers.  Default is a space, but can be changed to anything in
	order to get special output.

	Example:
		'* padchar !
		234 10 .r

	prints: *******234
	see also: (.) (.r) (p.r) base
 

( char <text>char -- a n )
	Parse input stream until "char"; returns the string corresponding
	to the read portion.  The remainder after "char" is still in the
	input stream, and will be processed next.
	see also:  parsews parse/
 

( char <text>char -- a n )
	Same as "parse", but handles escaped "\" characters
	see also:  parse parsews
 

( -- a n )
	Same as parse, but eliminates any "whitespace" from before or
	after the word. 
	see also:  parse parse/
 

( -- c )
	Returns an os-specific value for the file-path separator character
	
 

( -- )
	Used to implement "does>"
 

( n -- n )
	Return the n'th item from the stack. "0 pick" is the same as "dup", 
	"1 pick" is the same as "over".
	see also: stack-ops
 

( a n a2 -- )
	Store the string "a,n" as a counted string at "a2" - up to 255
	characters 
	see also: count +place strings 

( a -- )
	Moves the TOS to the CPU register EBX so the following code can
	operate on the values in EAX and EBX.  Used by words like '+'
	etc.
 

	There are several words which allow one to conditionally compile.
	These are called "preprocessor" words even though there is no such
	phase to Reva compilation.

	The words are:

		[IF] [THEN] [ELSE] [DEFINED]
	
 

( <word> -- )
	Once a word is defined (with ':') any prior version of it is lost
	to the interpreter.  This word allows invoking the previous
	version of "<word>" even though it was hidden from the
	interpreter.

	Example:
		: a ." hi" ;
		: a prior a ." there" ;  

	without the use of 'prior', the second 'a' would recurse forever.
	
 

	These words are provided by Reva for program-control:

		cold appstart prompt interp 
		onstartup onexit 
		save (save) bye (bye)

	On startup, Reva goes through this process:
		1. do OS-specific startup code
		2. unpack the dictionary (it's compressed)
		3. execute 'cold', which:
		3a.  resets the data stack
		3b.  calls the 'onstartup' handlers in order
		3c.  calls 'appstart'

		If 'appstart' returns to 'cold', Reva quits with exit code -1

	Reva's version of 'appstart' does this:
		1. if there are no arguments on the command-line, then print
		the Reva version
		2. process command-line arguments one at a time.  Each
		argument is treated as a file name to be included, except:
		   -a   load the 'ansi' library 
		   -n   "need" the next argument (load that library)
		   -e   "eval" the next argument
		3. call 'interp' in an infinite loop
		
	Shutdown occurs when "bye" or "(bye)" are called.  (bye) does:
		1. call 'onexit' handlers in reverse order
		2. call OS-specific exit code with the desired exit code.
	 

( -- )
	Called whenever Reva is waiting for input from the keyboard.  The
	default action is to print "ok> "
	see also: program-control
 

	Sometimes data are put on the return stack, or it is necessary to
	change the return stack somehow.

	Reva provides these return-stack manipulation words:

		r> >r r@ rdrop rp@ rp0 rpick >rr rr>

	Information about the return-stack can be got with:

		.rs rdepth
	 

( r:n -- n )
	Pops top item off return-stack and pushes it onto the data stack 
	see also: r-stack-ops

 

( -- n )
	Puts a copy of the top item on the return-stack onto the data
	stack.
	see also: r-stack-ops


 

	Heavy-duty random numbers, periodicity approx 2^123:

	rand ( -- n ) Get the next random number
	curseed4 ( -- a b c d ) Get the four-cell seed
	seed4 ( a b c d -- ) Set the four-cell seed
	 

	Simple random numbers from "Starting Forth":

	random ( -- n ) Get the next random number
	choose ( n -- m ) Return a random number in range 0...n-1
	 

( -- n )
	Returns depth of the return-stack
	see also: depth
 

( r:n -- )
	Drop one value from return-stack.
	see also: r-stack-ops

 

( a n fileid - n2 )
	Reads from 'fileid' into the buffer 'a n'.  'n2' is the number of
	bytes read. 
	see also: file-io 

( -- n )
	How many more loops remain in this do..loop
	see also: flow-control 

( a1 n1 a2 n2 -- )
	Rename the file named "a1,n1" to the new name "a2,n2"
	see also: file-io 

( -- )
	Start a loop to be used with "again" or "while"
	see also: flow-control
 

( -- )
	Resets stack to initial settings (e.g. drops everything) 
	see also:  cold
 

( a n -- a2 )
	Resize allocated memory "a" to "n" bytes. Returns 0 on success.
	see also: allocate, free
  

(environment variable)
	This is an optional environment variable which, if set, must
	contain the full path to the user's private library files, similar
	to the 'libdir' path (terminated with a / or \ as expected on your
	system)
	see also:  libdir needs
	 

( -- a n )
	String containing the Reva version.
 

( <name> -- )
	Used inside a loc:...loc; block, makes the word <name> visible
	outside that block.
	see also:  loc: loc; hide seal
	 

( a b c -- b c a )
	Rotate top three items clockwise
	see also: stack-ops
 

( -- a )
	Variable containing the beginning of the return-stack
	see also: r-stack-ops

 

( -- a )
	Variable holding value of start of return stack space 
	see also:  h0 s0 d0 str0
 

( -- n )
	Grab the current value of the return-stack pointer
	see also: r-stack-ops

 

( n -- m )
	Grab the 'nth' value on the return-stack
	see also: r-stack-ops

 

( -- n )
	Removes the second value off the return-stack. "nip" for the
	return-stack.
	see also: r-stack-ops
 

( -- a )
	Variable holding value of start of stack space
	see also:  h0 d0 str0 rp0 

( <name> -- )
	Saves the current Reva to the file "<name>" as a 'turnkey'
	program. 
	see also: program-control
 

( -- a )
	Returns the address of a 4K buffer which can be used for anything
	by anyone.  Don't rely on it to stay unchanged 
	see also:  temp pad
 

( dict -- )
	Given the dictionary pointer to a word, makes all words prior to
	it invisible in dictionary searches.  Do be careful with it, it
	cannot be undone!  Example:

		'' words seal

	After doing this, all words defined prior to 'words' are
	unavailable (note 'bye' doesn't work now!)

	see also:  loc: loc;
	
 

( a1 n1 a2 n2 -- a3 n3 true | false )
	Look for substring "a2,n2" in "a1,n1". Returns 0 on failure, or the
	matching substring "a3,n3" and true.
	see also: strings
 

( <name> -- )
	Dumps the bytes corresponding to the "xt" of "<name>", without
	disassembling (yet).
 

( n fileid -- )
	Move current position of 'fileid' to n bytes from the beginning of
	the file
	see also: file-io 

( n -- )
	Increment the loop index in a do..loop by 'n'.
	see also: flow-control
 

( addr n -- addr2 n2 )
	Reads in file given by name and puts a string containing the
	entire file on the stack. The string is allocated and needs to be
	'free'd.  If the 'slurp' failed, the values "0 0" will be on the
	stack.
	see also: include needs
 

( d n -- rem div )
	Symmetrical divide of a 'double' by a cell, like /mod but one
	argument is double.
	
 

( -- a )
	Puts the current value of the stack pointer (ESI) on TOS.
	 

( -- )
	Print a space character (ASCII 32) 
	see also: console-io 

( n -- )
	Prints 'n' spaces 
	see also: console-io
 

( a n c -- a n false | a1 n1 a2 n2 true )
	Split the string "a,n" at the first occurrence of "c". If the
	character was not found, returns original string and false;
	otherwise returns the split string and true.  
	see also: strings
 

( -- a )
	Address of variable holding current value of source pointer.  If that
	pointer is zero, the input is from the keyboard
	see also:  >in
 

( -- a n )
	Returns a string containing the remaining text to be processed by
	the interpreter.  Mostly for use in 'scan-ahead' processing, for
	example by "[IF]" etc.
 

	Manipulation of data on the 'stack' is one of the most important
	things to understand in Reva or any Forth.  Every word has a
	'stack-diagram', which is an explanation of how the word operates
	on the stack.

	Reva provides these stack manipulation words:
	
		dup drop swap over nip tuck rot -rot pick
		2dup 2drop 2swap 2over 3dup
	
	Information about the stack can be got with:

		.s depth
	
 

( a n -- n )
	Get the permissions (file attributes) of the named file.
	see also: file-io 

( xt numparams stacksize <name> -- )
	Same as "cb:", but for a stdcall function 
	see also: cb:
 

( -- n )
	Return handle of standard-input
	see also: stdout
 

( -- n )
	Return handle of standard-output
	see also: stdin
 

( -- a )
	Variable holding value of start of string space (where compiled
	strings are put)
	see also:  h0 s0 d0 rp0 

	This is a wrapper around the 'libiconv' character-set conversion
	library.  You will need 'libiconv.so' on Linux, or the included
	'libiconv2.dll' (in the 'bin' directory) to use this on Windows.

	Look in the 'libiconv' documentation for how you should use these
	words:

		iconv_open  ( z-to z-from -- desc )
		iconv ( desc **in *inleft **out *outleft -- result )
		iconv_close ( desc -- result )

		iconv_ver ( -- result ) 
			Return an integer which is the libiconv version.
	 

	Justify and pad strings:

	ljust ( a n m -- ) Prints "a,n" in field "m" wide
	rjust ( a n m -- ) Prints "a,n" right-justified in field "m" wide
	0pad ( a n m -- a' m' ) Pads "a,n" on left with zeroes to width "m"
	 

	Various and sundry string routines:

	spaces ( n -- ) print 'n' spaces
	strlwr ( a n -- a n ) lowercase the string
	ws? ( c -- flag ) test if 'c' is whitespace
	s++ ( a n -- a' n' ) advance string to next character
	/string ( a n m -- a' n') advance string 'm' characters
	 

	Wrapper around the PCRE library.  Linux users need to have PCRE
	installed (most will already have it).  Windows users get
	'pcre3.dll' in the 'bin' directory, which needs to be distributed
	with any application which uses PCRE.

	regex-options ( -- a ) Variable containing PCRE options
		These are various option flags to be "or"ed together
		PCRE_CASELESS PCRE_MULTILINE PCRE_DOTALL PCRE_EXTENDED
		PCRE_ANCHORED PCRE_DOLLAR_ENDONLY PCRE_EXTRA PCRE_NOTBOL
		PCRE_NOTEOL PCRE_UNGREEDY PCRE_NOTEMPTY PCRE_UTF8
		PCRE_NO_AUTO_CAPTURE PCRE_NO_UTF8_CHECK PCRE_AUTO_CALLOUT
		PCRE_PARTIAL
	regex: ( a n <name> -- ) Create a compiled 'regex' for use
	regex_getmatch ( n -- ) Return submatch "n" (0 is the main match)
	regex_find ( a n regex -- 0 | a n #matched) Returns number of
		matches, 0 for no match.  If #matched is 1 or more, also
		returns the main match.
	regex_find! ( a1 n1 a2 n2 -- 0 | a n #matched) Same as
		'regex_find', but matches against 'a2,n2' instead of a
		precompiled regex.

	To appreciate the complexities of the regular-expressions
	permitted, please look at the PCRE documentation on-line at:

		http://www.pcre.org/
	 

	Give soundex code for a string:

	soundex ( a n -- a' n' )
	 

	Trim whitespace from strings:

	ltrim ( a n -- a' n' ) trim from the left
	rtrim ( a n -- a' n' ) trim from the right
	trim ( a n -- a' n' ) trim from both sides
	 

	Strings come in two varieties, "Forth" and "Counted".  A "Forth"
	string is two cells on the stack, usually designated in
	stack-diagrams as "a n", meaning 'address' and 'number of
	characters'.  One can display such a string using "type".

	"Counted" strings are just one cell on the stack, an address.
	The first byte (or cell) of this address is a count of characters.
	There are two flavors of counted strings - "cstr" and "lstr".  The
	cstr uses one byte for the count, and so can contain up to 255
	characters (which is usually enough for most purposes), while the
	lstr uses a cell for the count, and is therefore essentially of
	unlimited length.  Reva has no words to print counted strings, but
	they are easily converted to Forth strings using "count" and
	"lcount".  Forth strings may be stored into counted strings using
	"place" and "lplace", and appended with "+place" and "l+place".

	Declaring strings is very easy.  Use the word '"' (that is, one
	double-quote character), followed by ONE space, the desired
	string, and a closing double quote: " This is a Forth string"

	If it is necessary to have double-quotes inside a string, it is
	easily accommodated by using the backslash character:
	" She said, \"Look, Ma - no hands!\""

	If a backslash is necessary, simply use two backslashes in a row.

	All strings created with '"' are NUL terminated, as are counted
	strings.  So one may pass them to external routines which expect a
	NUL terminated string.

	These are words which deal with strings in Reva:

		count lcount place lplace +place +lplace c+place c+lplace
		" ." /char \char chop -chop cmp cmpi lc search split
		zcount zt nul
	 

( a b -- b a )
	Swap the top two stack items 
	see also: stack-ops
 

( arg0...argN N+1 syscall -- result)
	LINUX ONLY: Call the kernel directly using the syscall interface
	NOTE: You really need to know what you are doing to use this
	function.
	see also: lib func
 

( fileid -- n )
	Report on the position in 'fileid' relative to the beginning of
	the file
	see also: file-io 

 ( -- a )
	Variable for anyone to use for any purpose 
	see also:  scratch pad
 

( -- )
	Ends the conditional started by one of the 'if' constructs 
	see also: conditionals
 

( n -- )
	If TOS is zero, does nothing. Otherwise, passes control to the
	most recent "catch"
	see also: catch
 

	These are the predefined codes 'throw' will use from Reva:

		THROW_GENERIC THROW_BADFUNC THROW_BADLIB
	
 

( -- -2 )
	Thrown by 'func' if the function is invoked but has not been
	loaded.
	see also: throw-codes
	 

( -- -3 )
	Thrown by 'lib' if the lib is invoked but has not been loaded.
	see also: throw-codes
	
 

( -- -1 )
	Thrown for any generic error internal to Reva.
	see also: throw-codes
	 

( -- tib )
	Variable holding value of "terminal input buffer" 
	see also:  >in src
 

( -- s m h dd mm yyyy )
	Returns the current time and date 
 

( n <value> -- )
	Sets the value to 'n'.  
	see also: value
	
 

( -- a ) 
	Puts the pointer to the input buffer (TIB) on TOS.
	 

( -- flag )
	Returns logical 'true', e.g. -1 (all bits set)
	see also:  false and or xor not
 

( a b -- b a b )
	Put a copy of top cell under second stack item 
	see also: stack-ops 
 

( a n -- )
	Print a string 
	see also: console-io
 

( -- n )
	WINDOWS ONLY: Handle to USER32 library 
	see also: k32 g32
 

( -- )
	Undoes the return-stack munging done by 'do', permitting use of
	';;' without crashing
	see also: flow-control
 

( -- dict-used code-used )
	Puts the current memory usage (dict,code) on the stack.  
 

	Extra stack to help out with awkward situations:

	>aux ( n -- ) Put 'n' on the auxilliary stack
	aux> ( -- n ) Pop TOS from the auxilliary stack
	aux@ ( -- n ) Peek at TOS from auxilliary stack
	 

	Implements a case ... of ... endof ... endcase construct like ANS.
	Example:

		case 
			1 of cr ." one" endof
			2 of cr ." two" endof
			67 of cr ." sixty-seven" endof
			cr ." default case = " dup .
		endcase
	 

	Utility to tell what the class of a word is:

	classof ( dict -- a n ) Given the dict ptr of a word, tell its class
	classof: ( <name> -- a n ) Same as 'classof' but operate on word following
	 

	Perform an action for each line of a chunk of text:

	eachline ( a n xt -- a n)  The 'xt' is passed the line to operate one
	 

	Implements a form of local variables.
	Example:
		: ltst { v1 v2 | v3  -- n }
			| Locals defined before the vertical slash get initialised
			| from the stack, so ltst must be called with two items on
			| the stack Locals defined after the vertical slash are
			| initialised at compile time to 0. They retain their
			| value between calls (to ltst) which means they are
			| 'static' in 'C' terminology.  The '--' and anything
			| after it are ignored, allowing a complete stack diagram.

			v1 . v2 . v3 .  | v1 and v2 are initialised from the
							| stack, print their values 
			v1 v2 + +to v3  | v3 = v3 + v1 + v2
			1 +to v3        | v3 = v3 + 1
			v3 .        | print v3
			addr v3 @ . | and again, the hard way
			;
	 

	Miscellaneous stuff that doesn't fit elsewhere:

	(.ip) ( n -- a n ) Format an IP address in the normal manner
	.ip ( n -- ) Print an IP address, like .
	EOF ( -- ) stop processing this file
	 

	Very simple multitasking words. See examples/task.f for usage: 
	task:	( -- )	In place of : -- creates a new nameless colon-def which
		is put into the task queue.	
	>task	( xt -- )	Like task:, but takes an xt to put in the task queue.	
	yield	( -- )	Executes the next task in the queue	
	 

	Simple wrapper around the ZLIB compression library.  See the ZLIB
	documentation for detailed information on these words:

	Operations on 'gz' files:
		gzopen ( path mode -- handle)
		gzread ( handle buf len -- #read) 0=end of file -1= error
		gzwrite ( handle buf len -- #written)
		gzseek ( handle offset whence -- offset )
		gztell ( handle -- offset )
		gzclose ( handle -- result )

	Compressing buffers: (note the 'dsize^' is a pointer)
		zlib_compressbound ( len -- maxlen) Max size to compress 'len'
		zlib_compress ( dest dsize^ src ssize -- result )
		zlib_uncompress ( dest dsize^ src ssize -- result )
	 

( n -- )
	Create a value with the value "n".  A value is like a variable in
	that it can be changed, but like a constant in that you don't need
	to use '@' to get its value

	Example:
		12 value joe

		joe 12 =if ... then 

		34 to joe
	see also:  variable constant to 

( <name> -- )
	Create a new variable called "<name>", with an intial value of zero 
	see also:  variable, @ ! on off ++ --
 

( n <name> -- )
	Same as "variable", but initializes with the value "n" 
	see also:  variable
 

( <name> -- )
	Creates a new vocabulary word "<name>". When this word is
	executed, it will provide access to any words defined after it was
	invoked as well as all words prior to its invocation. Use
	"lastvoc" to return to the prior vocabulary. This allows
	semi-private word lists
	see also:  lastvoc loc: loc;
 

 ( n a -- )
	Puts the short (2-bytes) "n" at "a".
	see also: w@
 

( a -- n )
	Gets a short (2-bytes) from "a".
	see also: w!
 

( n -- )
	If TOS is not zero, return to most recent "repeat".
	see also: flow-control
 

 ( a n -- a n 0 | xt 1 | n 2 | n m 3 | 4 )
	Last resort interpreter hook.  This gets called when the
	interpreter cannot determine that a piece of text is a word or a
	number.
	
 

( <opt> -- )
	Display all words currently visible in the dictionary.  If <opt>
	was given, will show all words including <opt> as a substring.
	
	Words which have been defined between "loc:" and "loc;" will not
	be visible, nor will words in a parent vocabulary which were
	defined after the current vocabulary (see "voc:" for more
	information
 

( a n fileid -- )
	Write 'n' bytes from address 'a' to 'fileid'.
	see also: file-io 

( <name> -- )
	Causes the word "<name>" to be executed immediately rather than
	being compiled into the word's definition.  This is mostly useful
	for "forth" or "inline" words whose side-effects are desired
	immediately.
	see also:  p:
 

( a b -- n )
	XOR top two items. like C bitwise operator: a ^ b
	see also:  and or not
 

( z -- a n )
	Convert NUL-terminated string to address-count "Forth" format.
	see also: zt
	see also: strings
 

( a n -- z )
	Zero terminate string "a,n". Must be sure there is space for the
	terminating NUL before using!
	see also: zcount
	see also: strings
 

( -- )
	Comment to end-of-line. Same as \ in ANS Forth
	see also:  (