# help

word: errno
stack: --
ctx: ~os
ver: 7.0.6
desc:
	Returns the last os-specific error code.  On Windows this maps
	to "GetLastError", on Linux it's 'errno'. 
        


word: [IFTEST]
stack: --
ctx: ~
ver: 7.0.6
desc:
	Used like "[IF]", but only true if the word "TESTING" has been
	defined.  For example, if Reva has been started with the "-t"
	option.
        


word: foreach
stack: xt hi lo --
ctx: ~
ver: 7.0.5
desc:
	One-line loop construct.  Call 'xt' for each value from 'lo'
	to 'hi' (not including 'hi').  

	Example:

	    { . } 20 10 foreach

	This uses an anonymous xt, and will print "10..19".


word: 0;drop
stack: n -- | exit and drop TOS if n=0
ctx: ~
ver: 6.1.13
desc:
	Drops 'n', and returns to calling word if 'n' was zero.

	Example:

		: 0;drop-test  0;drop ." The TOS was not 0!" ;
		1 2 3 0;drop-test
		  The TOS was not 0!
		.s
		  1 2
		3 0 0;drop-test
		.s
		  1 2 3


word: chain
stack: <name> --
ctx: ~
ver: 6.1.7
desc:
	Call the currently set value of a deferred word.  Lets you
	easily override the word and yet use the old value.  

	Example:

		:: dup . chain emit ; is emit


word: exception
stack: EDI ESI EBX EDX ECX EAX EBP ESP EIP except_code -- continueip|0
ctx: ~
ver: 6.1.5
desc:
	Deferred word which is called when an "exception" occurs.
	That is, something like "0 0 !" will generate a GPF which Reva
	will trap.  Your handler can do something useful with this
	information.  

	The return must be one of "0" for "do the system default", or
	the xt of some word you want to gain control after the
	exception.

	You do NOT need to consume the stack, as the stack provided
	for the handler is dynamically allocated from the CPU stack
	(e.g. ESP), and will be automatically released.  By the same
	token, you have about 20 cells of stack space you can use --
	so don't get carried away, just process and return to Reva.

	NOTE: Exception codes are OS specific.  However, you can use
	symbolic constants to refer to most of them if you "need
	os/exceptions".

	NOTE: Exception handlers get a temporary stack - you cannot,
	therefore, use words like ".s" and "depth" which know
	something about the stack, since their knowledge is incorrect.


word: ctrl-c
stack: --
ctx: ~
ver: 6.1.6
desc:
	Deferred word which is called when an "Ctrl+C" occurs.

	You should set a flag if you wish to interrupt an ongoing
	process, and check for that flag in the process to be
	interrupted.

	The default behavior is to print "Break" and call "bye".


word: revaver#
stack: --
ctx: ~reva
ver: 6.1.6
desc:
	Numeric equivalent of the string "revaver".  Currenty, it is
	represented by the hexadecimal:
		00MMmmpp

	So Reva 6.1.5 would be:
		00060105, where
		"MM" is major release number, e.g. "6"
		"mm" is minor release, e.g. "1"
		"pp" is point release, e.g. "5"


word: xchg2
stack: a b --
ctx: ~
ver: 6.1.5
desc:
	Swaps the values pointed to by "a" and "b".  Essentially the
	same as:

	   2dup @ swap @    | a b b' a'
	   rot !	    | a b'
	   swap !
	


word: xt?
stack: <name> -- xt | throw
ctx: ~sys
ver: 6.0.10
desc:
	Parses the next word in the input, and returns its xt or
	throws an exception if it is not a valid word or is not
	visible in the search-order.


word: isa
stack: class-xt a n -- xt | throw
ctx: ~sys
ver: 6.0.10
desc:
	Verifies that the word (a,n) is of the class represented by
	the class-xt passed in.   If it is, it returns the xt of that
	word; otherwise, it throws an exception.


word: with~
stack: <ctx> --
ctx: ~
ver: 6.0.10
desc:
	Puts <ctx> in the search order, underneath the current
	topmost context.  Sort of a "tuck" for contexts.


word: reva
stack: --
ctx: ~
ver: 6.0.9
desc:
	Resets the search-order, and puts the following contexts in
	the search-order:

		~reva ~os ~util ~io ~string ~

	So after executing this word, the "common" Reva words will all
	be available, and mostly Reva will behave as it did before
	version 6.0.8.  

	To set up your own ordering, simply use "reset~" followed by
	whatever contexts you wish ("~" will be first in search-order
	and the only thing in it, after "reset~").


word: only~
stack: <ctx> --
ctx: ~
ver: 6.0.9
desc:
	Makes the context following the only one in the search order.
	This is useful for example if you want to expose only a limited
	set of words.
	
	Example:

		context: ~a
		~a
		: foo ." bar" cr ;
		exit~
		only~ ~a

	After the last statement, the only word visible to the
	interpreter will be "foo".


word: @
stack: a -- n
ctx: ~
desc:
	Returns the cell pointed to by the address in a 
	Be careful not to pass an invalid address to it!


word: allot
stack: n --
ctx: ~
desc:
	Allocate memory by moving "here" by "n" bytes.  Can also be used
	for deallocation from 'here' if given a negative number. 
	


word: "
stack: <str>" -- a n
ctx: ~
desc:
	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"

	NOTE: strings created interactively have a 255 byte limit.
	Compiled strings, do not have that limitation.
	


word: (")
stack: -?
ctx: ~strings
desc:
	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.


word: chop
stack: a n c -- a1 n1
ctx: ~strings
desc:
	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 
	


word: lc
stack: c -- c
ctx: ~strings
desc:
	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).
	


word: split
stack: a n c -- a n false | a1 n1 a2 n2 true
ctx: ~strings
desc:
	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.  

	If "true" is returned, then "(a2,n2)" is the first part of the
	string, and "(a1,n1)" is the latter half.

	Example:
		" Hello, world!" ', split
	Returns "true" on TOS, then the string:
		" Hello"
	followed by:
		"  world!"
	


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


word: scratch
stack: -- a
ctx: ~
desc:
	Returns the address of a 4K buffer which can be used for anything
	by anyone.  Don't rely on it to stay unchanged 
	


word: srcstr
stack: -- a n
ctx: ~sys
desc:
	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.


word: words
stack: <opt> --
ctx: ~
desc:
	Display all words in the topmost context in search order.  If
	<opt> was given, will show all words including <opt> as a
	substring.


word: #!
stack: --
ctx: ~
desc:
	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.
	


word: (seek)
stack: whence offset handle --
ctx: ~io
desc:
	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


word: '
stack: <name> -- xt
ctx: ~
desc:
	Look up the word "<name>" in the dictionary.  Returns the xt of
	the word in question, or 0 if "<name>" doesn't exist.
	


word: find
stack: a n -- xt | a n 0
ctx: ~
desc:
	Look up a word in the dictionary.  Returns the xt of the word in
	question, or the name and 0 on TOS.
	


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


word: alias:
stack: newname oldname --
ctx: ~util
desc:
	Create alias 'newname' for the word 'oldname', keeping the proper
	class semantics of the old word.
	


word: compiling?
stack: -- flag
ctx: ~sys
desc:
	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.


word: value
stack: n <name> --
ctx: ~
desc:
	Create a value named "<name>", 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
	


word: create
stack: <name> --
ctx: ~
desc:
	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-dict', assuming
	it was not hidden subsequently.
	


word: exec
stack: dict --
ctx: ~
ver: 6.1.3
desc:
	Execute the word whose dictionary pointer is at "dict".  This
	will execute with the correct class semantics, unlike
	"execute" which simply calls the address passed it.
	


word: notail
stack: --
ctx: ~
desc:
	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.
	


word: [IF]
stack: n --
ctx: ~
desc:
	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!
	


word: REVAUSERLIB
ctx: ~
desc:
	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)
	


word: needs
stack: <name> --
ctx: ~
desc:
	Locates the file "<name>" in the user library directory or the
	standard library directory includes it if it has not already been
	included.
	


word: libdir
stack: -- a n
ctx: ~
desc:
	Full path to "lib" directory, which is where the standard Reva
	libraries are stored.  The word "needs" uses this to find
	libraries.
	


word: ::
stack: -- xt
ctx: ~
desc:
	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.
	


word: p:
stack: <name> --
ctx: ~
desc:
	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. 
	


word: p[
stack: <name>... ]p --
ctx: ~
ver: 6.1.3
desc:
	Convenience word which executes "p:" for all the words up to
	the first "]p".  Simply permits a cleaner-looking syntax.

	Example:

	One might do:
		p: dup p: drop p: swap
	but this is cleaner looking:	
		p[ dup drop swap ]p

	They are entirely equivalent, however.

	


word: dict?
stack: <name> --
ctx: ~sys
ver: 6.1
desc:
	Puts dict of "<name>" in TOS, or throws -1 and prints "... is
	not a word" if the word does not exist.
	


word: super>
stack: <name> --
ctx: ~
ver: 6.1.8
desc:
	Calls the code just after "does>" in the word "<name>".  Use
	to override or superclass an existing word.

	Example:
		: const   create , does> @ ;
		: const++ create , does> super> const 1+ ;


word: does>
stack: --
ctx: ~
desc:
	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.
	
	


word: prior
stack: <word> --
ctx: ~util
desc:
	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.
	


word: [DEFINED]
stack: <name> -- flag
ctx: ~
desc:
	Returns "true" if the word has been defined, "false" otherwise.
	Intended to be used to take some action based upon runtime
	environmental issues.
	


word: <
stack: m n -- flag
ctx: ~
desc:
	Returns 'true' or 'false' depending on the test "m<n" using
	signed-math.
	
	Example:
		2 3 < .
			prints: -1
		2 -3 < .
			prints: 0

	


word: (.)
stack: n -- a n
ctx: ~
desc:
	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!

	


word: .r
stack: x y --
ctx: ~
desc:
	Prints number 'x' in a field 'y' wide.  Uses '(.r)' to format the
	number and appends a space afterwards, like '.'
	


word: (p.r)
stack: n m c -- a n
ctx: ~
desc:
	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.
	


word: */
stack: a b c -- n
ctx: ~
desc:
	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.

	


word: argv
stack: n -- addr len
ctx: ~
desc:
	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"
	


word: lib
stack: a n <libname>--
ctx: ~
desc:
	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: Returns "0" 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. 

	NOTE: Used to "throw" rather than return "0"

	


word: vfunc:
stack: n <fname> --
ctx: ~
ver: 6.1.7
desc:
	Same as "func:", but for functions which are "void", e.g. they
	don't return a value which we care about.  Convenience
	word which allows us to avoid using "drop" after all such
	words.


word: func:
stack: n <fname> --
ctx: ~
desc:
	Creates a word "<fname>" encapsulating a call to the function
	named "<fname>" in the most recently used "lib", taking "n"
	parameters.  If "n" is not correct, the function will crash when
	invoked.

	If you would like to refer to the function by some other name, use
	the word "as" after it, with the name you would prefer.

	NOTE: throws THROW_BAD?UNC 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.

	NOTE: You cannot use ['] or ' on a "func:" and expect to get
	back a code-address.  This is because the "xt" of a "func:"
	contains data - among other things, the address of the
	delay-loaded function itself.  Until the "func:" has been
	successfully called at least once, that address will be zero.

	To get the code-address pertaining to the "func:", you must
	use "func:>xt" , which is not in the main Reva code but in
	"util/misc"
	


word: as
stack: <name> --
ctx: ~
desc:
	Used with "func:" to change the original name of the function to
	a new one. 

	Example: 
		1 func: Sleep as rest

	


word: rol8
stack: n -- n
ctx: ~
desc:
	Rotates the cell 'n' eight bits left.  For example, changes
	$12345678 to $34567812 .  Used by ".x"
	


word: >body
stack: n -- n
ctx: ~util
desc:
	Takes a 'create'd word and returns a pointer to the 'body', e.g.
	the cell which will be on the stack when the "does>" executes.
	


word: getenv
stack: a n -- a1 n1
ctx: ~util
desc:
	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.
	


word: setenv
stack: a1 n1 a2 n3 --
ctx: ~util
ver: 6.1.1
desc:
	Set the environment variable (a1,n1) to the value (a2,n2).
	For example: " PATH" " whatever" setenv
	


word: depth
stack: -- n
ctx: ~util
desc:
	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!

	


word: pick
stack: n -- n
ctx: ~
desc:
	Return the n'th item from the stack. "0 pick" is the same as "dup", 
	"1 pick" is the same as "over".
	


word: file-io
ctx: meta
desc:
	The file-io words supported by Reva are:

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


word: ekey
stack: -- c
ctx: ~io
desc:
	Returns the ASCII value of a keypress as soon as a key has been
	pressed, including special keys.
	


word: accept
stack: a n -- m
ctx: ~io
desc:
	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.
	


word: console-io
ctx: meta
desc:
	The following console I/O words are available in Reva:
	
		cr space emit key key? ekey type accept spaces
	


word: see
stack: <name> --
ctx: ~util
desc:
	Dumps the bytes corresponding to the "xt" of "<name>".
	
	If the library 'debugger' has not been 'need'ed yet, will do a
	dump of the bytes corresponding to the xt.  If that library has
	been 'need'ed, it will try to disassemble.
	


word: ?do
stack: max start --
ctx: ~
desc:
	ANS-compatible '?do'. Iterates from 'start' to 'max'-1.  If 'max'
	and 'start' are equal, will not do any iterations.
	


word: eleave
stack: --
ctx: ~
desc:
	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.
	


word: loop
stack: --
ctx: ~
desc:
	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
	


word: later
stack: --
ctx: ~util
desc:
	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!
	


word: throw-codes
ctx: meta
desc:
	These are the predefined codes 'throw' will use from Reva:

		THROW_GENERIC THROW_BADFUNC THROW_BADLIB THROW_NEEDS
	


word: flow-control
ctx: meta
desc:
	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 0do
	


word: program-control
ctx: meta
desc:
	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.
	


word: help/
stack: <name> --
ctx: ~
ver: 6.0.9
desc:
	Lists all words in the help database which either match the
	given name or whose descriptions contain that name.  The
	search is case-insensitive, and matches partial as well as
	whole matches.


word: classes
ctx: meta
desc:
	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:

		macro
		: in1 ... ;
		: in2 ... ;
		forth

	


word: stack-ops
ctx: meta
desc:
	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 3drop
	
	Information about the stack can be got with:

		.s depth
	


word: r-stack-ops
ctx: meta
desc:
	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
	


word: nul
stack: -- a
ctx: ~
desc:
	Returns an "empty" NUL terminated string.  Good for when you need
	to pass such a string to a C library.
	


word: strings
ctx: meta
desc:
	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.

	NOTE: strings created interactively have a 255 byte limit.
	Compiled strings, as well as strings created using "quote" do
	not have that limitation.
	


word: preprocessor
ctx: meta
desc:
	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: .libs
stack: --
ctx: ~
desc:
	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.
	


word: .funcs
stack: --
ctx: ~
desc:
	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.
	


word: is
stack: xt <name> --
ctx: ~
desc:
	Sets the deferred word "<name>" to execute "xt" when invoked.
	Also set the default behavior of the word.  If you only want to
	set the current-behavior, use ">defer" instead.
	


word: defer
stack: <name> --
ctx: ~
desc:
	Create a deferred word "<name>". Initially this word will do
	nothing.  Must be set to something more useful using "is".  
	


word: exceptions
ctx: meta
ver: 6.1.5
desc:
	Exceptions in Reva include the CPU hardware exceptions like
	"illegal instruction", protection errors like "illegal memory
	write", as well as operator initiated actions such as "Ctrl+C
	pressed".  These are all handled similarly.
	
	This should be contrasted with the "catch"/"throw" mechanism,
	which is a programmer initiated action (usually in response to
	a logic error or resource failure).  Those are also called
	"exceptions", for lack of a better word ...

	The CPU/user exceptions are handled by the "exception" word,
	which needs to pass back the "xt" at which the user wishes to
	continue processing.  The only special exception is "Ctrl+C"
	or "Ctrl+Break", which is handled by calling the "ctrl-c"
	word.


word: deferred-words
ctx: meta
ver: 6.0.4
desc:
	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.
	


word: >defer
stack: xt <name>
ctx: ~
ver: 6.0.4
desc:
	Similar to "is", but does not affect default behavio?.  Changes
	current behavior of the deferred word <name> to the "xt". If you
	want to change the default behavior as well, use "is" instead.
	


word: make
stack: <name>
ctx: ~
ver: 6.0.4
desc:
	Sets the default behavior of a deferred word to the code following
	it.

	Example:

		defer joe
		make joe ." Hi there!" cr ;

	


word: quote
stack: <char> <...>char -- a n
ctx: ~strings
ver: 6.0.4
desc:
	Free-form string entry.  Parses input to find "<char>", which is
	the character which will delimit the string.  Then parses input
	until that character is found.

	Used inside a colon-def, will compile the string.  Used from the
	interpreter, will give a temporary address,count pair which must
	either be consumed immediately or the contents transferred to a
	safe location for later use.
	


word: vector
stack: --
ctx: ~sys
ver: 6.0.4
desc:
	Sets up a noop jump which can be vectored elsewhere.
	Example:
	  
	  : v vector ." hi  there" ;
	  v
	  ' words >defer v
	  v
	


word: z"
stack: <name>" -- z
ctx: ~strings
ver: 6.0.5
desc:
	Create a NUL terminated string (C string) and put just the address
	on TOS.  Essentially the same as using "zt" after a string.
	


word: findprev
stack: dict -- dict2
ctx: ~util
ver: 6.0.6
desc:
	Given a dictionary entry pointer, finds the entry which is just
	before it in the list of entries. 
	


word: inline{
stack: <bytes> <}> --
ctx: ~
ver: 6.0.6
desc:
	Compiles "inline" the (hex) bytes following it.  This is good for
	inline assembly code in a simple way:

	Example:
		: nop inline{ 90 } ;

	If you want the numbers interpreted as other than 'hex', use the
	numeric prefixes.

	NOTE: This does *not* make the word an "inline" word!
	


word: >base>
stack: n --
ctx: ~
ver: 6.0.7
desc:
	Sets the value of "base" to "n" temporarily.  When the calling
	word exists, the "base" will be restored to what it was before.
	


word: {
stack: --
ctx: ~
ver: 6.0.7
desc:
	Begins an "inline callback".  This is a sequence of words
	terminated by "}", which can be called by other words.

	NOTE: used to be called "cb{" and "}cb"
	


word: }
stack: -- xt
ctx: ~
ver: 6.0.7
desc:
	Terminates an "inline callback" begun with "{".  Leaves the xt
	of the callback in TOS, which can be passed to other words as
	needed.
	


word: context:
stack: <name> --
ctx: ~
ver: 6.0.8
desc:
	Create a new context called "<name>".  Invoking the name of
	the context makes it active and topmost in the search order.
	New words get put in the topmost context.

	A new context will be created only if a context by that name
	in the search-order does not exist.  This lets you use, for
	example:

		context: ~mystuff

	in several related files without worrying about the order the
	files are used.


word: |||
stack: --
ctx: ~
ver: 6.0.9
desc:
	Comment to end-of-file.  Useful especially in the library
	files, to place help text in the same file as the code, but
	after all the code.


word: syscall
stack: arg0...argN N+1 syscall -- result
ctx: ~os
os: Linux
desc:
	Call the kernel directly using the syscall interface
	NOTE: You really need to know what you are doing to use this
	function.
	


word: resize
stack: a n -- a2
ctx: ~
desc:
	Resize allocated memory "a" to "n" bytes. Returns the new buffer.
	On failure, returns 0 (NULL pointer). Sets "ioerr".
	


word: open/r
stack: a n -- h
ctx: ~io
desc:
	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.
	


word: (func)
stack: a n lib -- handle
ctx: ~sys
desc:
	Internal word used by 'func:' - you probably don't want to use it.
	Returns a handle to the named funct?on from the library
	


word: (-lib)
stack: handle --
ctx: ~sys
desc:
	You want to use "lib" instead.
	OS code to unload the library handle (which had been created with
	(lib))
	


word: type
stack: a n --
ctx: ~io
desc:
	Print a string (by default to the console).
	NOTE: This word will not type a big string (32K or so) on Windows.
	


word: slurp
stack: addr n -- addr2 n2
ctx: ~util
desc:
	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.
	


word: iterate
stack: xt list --
ctx: ~util
ver: 6.0.7
desc:
	Executes "xt" for each item in "list".  The "xt" must return
	"false" to stop the iteration, or "true" to continue.
	


word: link
stack: value list --
ctx: ~util
ver: 6.0.7
desc:
	Creates a new node in "list" and assigns "value" to it.  The node
	is at the end of the list.  A "list" is simply a variable.
	


word: (.r)
stack: x y -- a n
ctx: ~
desc:
	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.
	
	


word: appname
stack: -- a
ctx: ~util
desc:
	Return a NUL terminated string containing the fully qualified name
	of the actual program file this application started from.
	


word: forth
stack: --
ctx: ~
desc:
	Sets the default class ("default_class") to be "'forth".
	Subsequent words will be of the "forth" class (e.g. "normal" Forth
	words)
	


word: macro
stack: --
ctx: ~
desc:
	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)
	


word: parse
stack: char <text>char -- a n
ctx: ~
desc:
	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.
	


word: include
stack: <name> --
ctx: ~util
desc:
	Read in the file "<name>" and evaluate it. Silent on failure, but
	'ioerr' will be non-zero.

	NOTE: the stack pointer is restored to whatever it was before
	the "include".  That is, if the file to be included push
	values on the stack, those values will NOT be present after
	the "include".  This is intentional.
	


word: base
stack: -- a
ctx: ~
desc:
	Returns a pointer to a variable containing the current base for
	number conversion.

	Example:

		6 2 base ! .

		prints "6" in binary, "110"
	


word: pad
stack: -- a
ctx: ~
desc:
	Return the address of "pad" ( a temporary buffer used by many
	words ).   This buffer is 1024 bytes large.


word: ;
stack: --
ctx: ~
desc:
	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-call elimination".  It also signals that we've stopped
	compiling.
	


word: :
stack: <name> --
ctx: ~
desc:
	Create a new word called "<name>".  Everything between this and
	the corresponding ";" are executed when "<name>" is invoked.
	


word: word?
stack: a n -- a n 0 | xt 1 | n 2 | n m 3 | 4
ctx: ~sys
desc:
	Last resort interpreter hook.  This gets called when the
	interpreter cannot determine that a piece of text is a word or a
	number.
	


word: >single
stack: a n -- m true | a n false
ctx: ~util
desc:
	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.
	


word: ;;
stack: --
ctx: ~
desc:
	Exit the current word without signalling that compilation has
	stopped.  It also applies the "tail-call elimination" that ";"
	does.
	


word: argc
stack: -- n
ctx: ~util
desc:
	One more than the number of command-line arguments passed to Reva.
	So if no arguments were passed, argc is 1  
	


word: src
stack: -- a
ctx: ~sys
desc:
	Address of variable holding current value of ?ource pointer.  If
	that pointer is zero, the input is from the keyboard
	


word: search
stack: a1 n1 a2 n2 -- a3 n3 true | false
ctx: ~strings
desc:
	Look for substring "a2,n2" in "a1,n1". Returns 0 on failure, or the
	matching tail "a3,n3", and true.  The matching substring is
	the first "n2" characters of (a3,n3).  The characters after
	"n3" are the remainder of the original string.
	


word: (call)
stack: func n --
ctx: ~sys
desc:
	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).  
	


word: onstartup
stack: xt --
ctx: ~sys
desc:
	Add the xt to the 'startup handlers list'.  This xt will be
	executed when "cold" is called, just before "appstart" is called.

	It is important that the stack diagram of the xt is ( -- )
	


word: onexit
stack: xt --
ctx: ~sys
desc:
	Add the xt to the 'exit handlers list'.  This xt will be executed
	when "bye" is called

	It is important that the stack diagram of the xt is ( -- )
	


word: padchar
stack: -- a
ctx: ~
desc:
	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
	


word: catch
stack: xt -- throwcode
ctx: ~
desc:
	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. 
	


word: >lz
stack: a n a2 -- a2 m
ctx: ~util
desc:
	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.
	


word: lz>
stack: a n a2 -- a2 n
ctx: ~util
desc:
	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!
	


word: prompt
stack: --
ctx: ~sys
desc:
	Called whenever Reva is waiting for input from the keyboard.  The
	default action is to print "ok> "
	


word: nosavedict
stack: -- a
ctx: ~
ver: 6.0.11
desc:
	Variable which controls whether or not "save" also writes out
	the dictionary.  Setting this to a non-zero value will make
	turnkey applications which have no dictionary.


word: -link
stack: value list --
ctx: ~
ver: 6.1.2
desc:
	Creates a new node in "list" and assigns "value" to it.  The node
	is at the beginning of the list.  A "list" is simply a variable.


word: do_cr
stack: --
ctx: ~
ver: 6.1.3
desc:
	Called whenever the "parsews" sees a CR (character $0a).  The
	default value of this word does nothing; it's intended as a
	hook for those applications which need to know when a newline
	has occurred in the input stream.


word: ;inline
stack: --
ctx: ~
ver: 6.1.2
desc:
	Terminate the current colon-def but make it an "inline" word.
	This replaces the former word "inline", but with much the same
	effect.

	An inlined word cannot call other words, nor jump outside its
	own code.  This is because jumps are relative, and the
	";inline" code will be copied into whatever word uses it.

	Generally (at least on 32-bit x86 platforms), an inlined word
	should be five or fewer bytes.


word: case
stack: --
ctx: ~
ver: 6.0.11
desc:
	Begins a "case ... endcase" construct.  Used instead of
	multiple "if ... else ?.. then".

	Example:

		case
			1 of ... endof
			4 of ... endof
			| default case is here
		endcase

	If none of the cases is handled, it falls through to the
	"default case" section.  The case selector will be in TOS


word: of
stack: n --
ctx: ~
ver: 6.0.11
desc:
	Begins a "case selection".  If the case selector matches 'n',
	then execution continues after the "of".  Otherwise it
	continues after the matching "endof".  Essentially the same
	as:

		n over =if drop ... endif


word: rangeof
stack: low high --
ctx: ~
ver: 6.0.11
desc:
	Same as "of", but the case selector is tested against the
	range (low,high), and the case is selected if the selector is
	"between" (inclusive).


word: makeexename
stack: a n -- a' n'
ctx: ~
ver: 6.0.12
desc:
	Given a base name of a file, returns the "correct" file name
	for an executable.  For example, on Windows:

		" reva" makeexename

	Returns "reva.exe".  On Linux it would return "reva".


word: caught
stack: n -- f
ctx: ~reva
ver: 6.0.12
desc:
	Deferred word.  The default version of it simply prints
	"Caught: " and the value of "n", which is the "throw-code"
	passed to it.

	This word is part of the default Reva "appstart", and you may
	use it to do something different if an unhandled exception is
	thrown.

	Returns 'true' to quit the interpreter.


word: xfind
stack: <name> --
ctx: ~
ver: 6.0.13
desc:
	Looks for the word "<name>" in every context, and prints the
	names of all contexts in which it can be found.


word: push~
stack: --
ctx: ~
ver: 6.0.13
desc:
	Saves the current depth of the context "search order", to be
	restored later using "pop~".  This is intended mainly for
	library authors who might use it like so:

		| order is now: ~ ~util ~strings
		push~
		~sys ~ context: ~xyz
		~xyz
		| order is now: ~xyz ~ ~sys ~ ~util ~strings
			...
		pop~
		| order is now: ~ ~util ~strings

	Essentially it makes managing arbitrary context depth easy.
	Just be aware that one should NOT use "with~", at least not as
	the first context is added, since that will result in an
	incorrect ordering after the final "pop~".  

	This word does NOT save the actual ordering, it merely
	saves the ordering depth.


word: pop~
stack: --
ctx: ~
ver: 6.0.13
desc:
	Companion to "push~", it restores the context search order.

	This word does NOT restore the actual ordering, it merely
	restores the ordering depth.


word: bounds
stack: a n -- a+n a
ctx: ~strings
ver: 6.1.9
desc:
	Converts the string (a,n) into a (endaddress,startaddress)
	suitable for using as arguments to a "do..loop".


word: .used
stack: --
ctx: ~
ver: 6.1.9
desc:
	Prints the memory usage (code and dictionary) of the program,
	besides that used by the Reva core itself.


word: _1+
stack: a b -- a+1 b
ctx: ~
ver: 6.1.9
desc:
	Increment the second stack item.  Like "1+" but for the item
	under TOS.  Much more efficient than "swap 1+ swap"


word: _1-
stack: a b -- a-1 b
ctx: ~
ver: 6.1.9
desc:
	Decrement the second stack item.  Like "1-" but for the item
	under TOS.  Much more efficient than "swap 1- swap"


word: _+
stack: a b n -- a+n b
ctx: ~
ver: 6.1.9
desc:
	Add "n" to the second stack item.  Like "+" but for the item
	under TOS.  Much more efficient than "rot + swap"


word: dictgone
stack: --
ctx: ~
ver: 6.1.9
desc:
	Word which gets called when the dictionary is out of space.
	The default Reva behavior is to print a message and quit.


word: heapgone
stack: --
ctx: ~
ver: 6.1.9
desc:
	Word which gets called when the code area is out of space.
	The default Reva behavior is to print a message and quit.


word: revaused
stack: -- a
ctx: ~
ver: 6.1.9
desc:
	Variable containing the "used" value after Reva has been
	compiled.  Used by ".used" and by "save" and "(save)" to show
	how much space is taken by the current program.


word: ?lib
stack: a n a n <name> --
ctx: ~
ver: 6.0.5
desc:
	REMOVED in 6.1.9
	Convenience wrapper around "lib".
	Load either the Linux or the Windows library as specified.  First
	string is the Linux one, the second string is the Windows version.
	


word: cleanup
stack: --
ctx: ~sys
desc:
	REMOVED in 6.1.2
	Deferred word which is called by the default 'bye'. Useful for
	closing files etc.  


word: inline
stack: --
ctx: ~
desc:
	REMOVED: 6.1.2
	Sets the default class ("default_class") to be "'inline".
	Subsequent words will be o? 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
	


word: loc:
stack: --
ctx: ~
desc:
	REMOVED in 6.0.10
	Begins a 'local definitions' list
	Anything defined between loc: and loc; is "local" and not visible
	in the dictionary unless specifically exposed.
	


word: reveal
stack: <name> --
ctx: ~
desc:
	REMOVED in 6.0.10
	Used inside a loc:...loc; block, makes the word <name> visible
	outside that block.
	


word: defaulthelp
stack: --
ctx: meta
desc:
	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 languages

	Asking for help on a context shows all the words in that context.  Asking for
	help on a library (without the leading "lib/") shows all the words in that
	library.

	Use "help/" to search for the word or a description which may contain that word.


word: help-contexts
ctx: meta
desc:
	These are the contexts known to Reva (ask for help on each one to see which
	words are defined in them):


word: help-libs
ctx: meta
desc:
	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. To use them, see the word "needs".
	These extra 'libraries' are in the 'lib' subdirectory, and are currently:


word: languages1
ctx: meta
desc:
	English is the default language of Reva's help system.  As time progresses,
	support for other languages is being added.  Currently, the languages known
	to Reva are:


word: languages2
ctx: meta
desc:
	To use one of these languages as your primary help language, please set the
	environment variable 'REVALANG' to the language you wish to use.


word: armasm{
stack: <armasm>... }
ctx: ~
desc:
	Lets you "inline" ARM assembly language code directly instead of
	hard-coding opcodes and poking.  Requires that FASMARM be installed
	and available on your system, and will slow down Reva a little
	while compiling armasm{ blocks.  

	Example:
		: incr armasm{ mov r0,0x34 } ;

	Note: lines between "armasm{" and "}" MUST be in valid FASMARM syntax,
	one statement per line!
   Also: armasm{ produces arm compatible code only and is only useful for generating
   code which is to be run on an arm based system.
	


word: rand
stack: -- n
ctx: ~
desc:
	Get the next random number

	The generate always starts from a known place, so sequences will be
	generated identically.  To get more 'random' behavior, use 'randomize' after
	loading the library.


word: rand
stack: -- n
ctx: ~
desc:
	Get the next random number.

	The generate always starts from a known place, so sequences will be
	generated identically.  To get more 'random' behavior, use 'randomize' after
	loading the library.


word: color
stack: --
ctx: ~os
desc:
    Available console colors are black, blue, green, cyan, red,
    magenta, yellow and white. One may set the current color by
    typing, for example:
       ok> red onGreen

    Note that both foreground and background must be specified.


word: title
stack: a u --
ctx: ~os
desc:
	Set the title of the console window, for example,
            ok> " My Title" title

    Currently Windows only.


word: shell
stack: a n --
ctx: ~os
desc:
	Pass the string (a,n) to the system to execute as an external command.  The
	os-dependent return code is put in "shell_code"


word: shell$
stack: a n -- a n
ctx: ~os
desc:
	Pass the string (a,n) to the system to execute as an external command.  The
	os-dependent return code is put in "shell_code", and the output from the
	command is returned in an allocated string (use 'free' on the string data).


word: !!
stack: <line> --
ctx: ~os
desc:
	Passes the entire line following it to the system to execute as an external
	command.  The os-dependent return code is put in "shell_code"


word: openkey
stack: hkey a n -- hkey
ctx: ~registry
ver: 6.1.6
desc:
	Open the subkey (a,n) of the handle "hkey", returning a handle to the
	opened key.
	The "root" handles are: "HKCR", "HKCU", "HKLM" and "HKUS"
	The Windows error code is in the variable "regerr"


word: createkey
stack: hkey a n -- hkey
ctx: ~registry
ver: 6.1.6
desc:
	Create the subkey (a,n) of the handle "hkey", returning a handle to the
	opened key.
	The "root" handles are: "HKCR", "HKCU", "HKLM" and "HKUS"
	The Windows error code is in the variable "regerr"


word: queryvalue
stack: hkey a n a1 n1 --
ctx: ~registry
ver: 6.1.6
desc:
	Retrieve the value of the key (a,n) from the handle hkey.
	(a1,n1) is the buffer into which the value will be stored.


word: split-path
stack: a n -- a1 n1 a2 n2
ctx: ~os
desc:
	Separates the directory and filename parts of the pathname (a,n).  It works
	identically on all platforms - ie. you can analyze Unix pathnames on Windows
	and vice versa.

	Example: 
		" /abc/hello.txt" split-path


word: add-path
stack: a1 n1 a2 n2 -- a n
ctx: ~os
desc:
	Concatenates (a1,n1) and (a2,n2) using the proper file system delimiter.
	For example: 
		" abc" " hello.txt" 
	results in:
		" abc/hello.txt" on Unix 
	and " abc\hello.txt" on Windows.


word: get-suffix
stack: a n -- a' n'
ctx: ~os
desc:
	Takes a pathname or a filename and returns the suffix, if any.
	The suffix returned includes the "."
	For example:
		/abc           =>
		abc.txt        => .txt


word: has-separator?
stack: a n -- flag
ctx: ~os
desc:
	Returns true if the pathname (a, n) already has a terminating path separator
	and false otherwise.


word: dir
stack: xtfile xtdir a n --
ctx: ~os
ver: 6.0.9
desc:
	Iterate over the directory (a,n), calling the "xtfile" for each file and
	"xtdir" for each directory encountered.  The passed-in xts must consume the
	(a,n) passed to them.


word: fullname
stack: a n -- a n
ctx: ~os
ver: 6.0.9
desc:
	Called from within "dir" or "rdir" and passed the filename passed to the
	callbacks, returns the "full" file name.  That is, the path all the way to
	the file, plus the file name, is returned.


word: create-process0
stack: a n --
ctx: ~process
desc:
	Create a process by executing the program named (a,n), with no parameters.
	Uses the external library "rss_process.dll" (or SO)


word: create-process1
stack: a n a2 n2 --
ctx: ~process
desc:
	Create a process by executing the program named (a,n), with one parameter
	(a2,n2).
	Uses the external library "rss_process.dll" (or SO)


word: create-process2
stack: a n a2 n2 a3 n3 --
ctx: ~process
desc:
	Create a process by executing the program named (a,n), with two parameters
	(a2,n2), (a3,n3).
	Uses the external library "rss_process.dll" (or SO)


word: create-process3
stack: a n a2 n2 ... a4 n4 --
ctx: ~process
desc:
	Create a process by executing the program named (a,n), with three parameters
	(a2,n2) ... (a4,n4).
	Uses the external library "rss_process.dll" (or SO)


word: create-process4
stack: a n a2 n2 ... a5 n5 --
ctx: ~process
desc:
	Create a process by executing the program named (a,n), with four parameters
	(a2,n2) ... (a5,n5).
	Uses the external library "rss_process.dll" (or SO)


word: thread
stack: xt param stacksize -- handle
ctx: ~os
ver: 7.0.6
desc:
	Creates a new 'thread', which is a "lightweight process"

	The "stacksize" is the number of cells you want the thread to have when it
	runs.  "param" is an arbitrary, user-defined parameter, which will be on TOS
	when the thread starts running.  
	
	The "xt" is a normal word, whose stack diagram is ( param -- ).  If it ends,
	the thread is terminated.  Otherwise, it can cause it's own destruction by
	using the "exitthread" word.

	The "handle" should be treated as an opaque structure, and should not be
	manipulated directly.

	On Windows uses the native threading facilities; on Linux uses
	'pthreads.so.0'

	See the "threads.f" example for practical usage.


word: lockmutex
stack: a --
ctx: ~os
ver: 7.0.6
desc:
	Lock the mutex at 'a'.  Will wait until it becomes available.  Remember to
	use 'unlockmutex' or other threads will be unable to lock the mutex.


word: sqlite
stack: --
ctx: ~db
ver: 6.1.8
desc:
	Sets the deferred database access words to use the SQLite bindings.
	This word is automatically called when the this library is used.


word: quote'
stack: a n -- a' n'
ctx: ~db
desc:
	Given a string, returns a new string where every occurrence of the
	single-quote character "'" is replaced by two single-quotes, "''".


word: quote"
stack: a n -- a' n'
ctx: ~db
desc:
	Given a string, returns a new string where every occurrence of the
	dbl-quote character '"' is replaced by two dbl-quotes, '""'.


word: sql_fetch#
stack: handle a n -- m
ctx: ~db
desc:
	Given a SQL string (a,n) and a database handle, returns the result of the
	query as an integer.  This will only be useful for SQL like:

		select sum(amount) from account 


word: sql_fetch$
stack: handle a n -- a' n'
ctx: ~db
desc:
	Given a SQL string (a,n) and a database handle, returns the result of the
	query as a string.  This will only be useful for SQL like:

		select firstname from customer where custid


word: sql_fetch
stack: handle a n xt -- m
ctx: ~db
desc:
	Executes the SQL string (a,n) on the database handle, calling "xt" (a normal
	Reva word) for each row of the result.  Returns the number of rows
	processed.  The "xt" has the stack diagram ( n -- flag ): "n" is the number
	of columns in the result, and the return value is "false" to continue
	processing and "true" to stop.  Inside the callback one may use
	"sql_getcol$" and "sql_getcol#" to return the n'th column of the result.


word: sqlite_exec_cb
stack: handle a n cb --
ctx: ~db
desc:
	Same as "sql_exec", but calls the "cb" (which must be a "callback", not
	a regular Reva word) for each row in the result.


word: getpage
stack: a n xt --
ctx: ~
ver: 7.0.2
desc:
	Retrieves the URL given in (a,n), by calling-back to "xt" for each chunk of
	the page received.  The xt has the stack diagram: ( a n -- ).  That is, it
	is given a 'string' which contains the contents of the page so far.

	The URL given should be in standard format, e.g.:

		http://server.name/uri/to/page.html


word: process
stack: a1 n1 a2 n2 -- 0|-1
ctx: ~cgi
ver: 6.1
desc:
	This word is defined by the user of the library - it is called for each of
	the CGI parameters.  (a1,n1) is the parameter name, (a2,n2) is the parameter
	value.  If you wish to terminate the processing, return 0 otherwise, -1 will
	continue.


word: crlf
stack: -- a n
ctx: ~sockets
desc:
	Returns a string with the two characters CR and LF, which are required for
	many network protocols


word: socket
stack: domain type proto -- sock
ctx: ~sockets
desc:
	Creates a raw socket of the specified type.  See "man 2 socket" on Unix
	systems or the appropriate alternative for Windows systems.


word: bind
stack: sock name len -- result
ctx: ~sockets
desc:
	Binds the socket to the specified local address.  
	Returns 0 for success, or something else for error.


word: listen
stack: sock backlog -- result
ctx: ~sockets
desc:
	Makes the socket listen for incoming connections.
	Returns 0 for success, or something else for error.


word: accept
stack: sock addr len -- result
ctx: ~sockets
desc:
	Accepts an incoming connection from "listen".  The addr,len points to a
	sockaddr structure (but is optional)
	Returns 0 for success, or something else for error.


word: gethostbyname
stack: z -- a
ctx: ~sockets
desc:
	Take the ASCIIZ string of a hostname, and return NULL on error, or a
	'hostent' structure containing information about the specified host


word: connectsocket
stack: a n port -- sock
ctx: ~sockets
desc:
	Connect to the specified host and port with TCP.  If 'n' is non-zero, then
	(a,n) is the name of a server.  If 'n' is zero, then 'a' is an IP address.

	Returns -1 on failure, or a valid socket on success.


word: recvallbufsize
stack: -- n
ctx: ~sockets
ver: 7.0.9
desc:
	Value which controls the size of the buffer allocated and used by "recvall".
	It is 4096 by default, but can be changed to suit the specific application.


word: recvall
stack: sock xt --
ctx: ~sockets
ver: 7.0.9
desc:
	Repeatedly does "recv" on "sock", calling "xt" for each chunk received.

	The stack diagram of "xt" is ( a n -- )  so don't forget to consume the text
	fed in!

	NOTE: The maximum size of 'n' is 'recvallbufsize', which by default is 4096
	but may be changed.  

	NOTE: 'n' may be zero, so check for that case if necessary.


word: send
stack: sock buf len flags -- sent
ctx: ~sockets
desc:
	Low level send function.  Returns the number of characters actually sent,
	which may be fewer than 'len'.


word: escape
stack: a n -- a n
ctx: ~xml
ver: 7.0.5
desc:
	Allocates a new string, which is a copy of the one passed in - except all
	"<" and "&" characters are converted to "&lt;" and "&amp;".


word: parse
stack: xt a n --
ctx: ~xml
ver: 7.0.5
desc:
	Regex-based parser of XML strings.  Parses (a,n) and calls "xt" for each
	(key,value) pair found in the input.

	The xt is called with a stack like ( value valueN key keyN -- )


word: big-done
stack: a --
ctx: ~bigmath
ver: 6.1.6
desc:
	Frees up the memory allocated to the big number "a".  The big number is
	invalid after this and should not be used.


word: big/mod
stack: r q a b --
ctx: ~bigmath
ver: 6.1.6
desc:
	Same as "/mod" for big numbers.  Takes the big numbers "a" and "b" and
	divides them, putting the quotient in "q" and the remainder in "r"


word: big/
stack: q a b --
ctx: ~bigmath
ver: 6.1.6
desc:
	Same as "/" for big numbers.  Takes the big numbers "a" and "b" and
	divides them, putting the quotient in "q"


word: bigmod
stack: r a b --
ctx: ~bigmath
ver: 6.1.6
desc:
	Same as "mod" for big numbers.  Takes the big numbers "a" and "b" and
	divides them, putting the remainder in "r"


word: fcompp
stack: -- f \ float: f1 f2 --
ctx: ~floats
desc:
	Compares the two fp values f1 and f2, popping them off the FP stack and
	putting the result of the comparision in TOS


word: ffloor
stack: float: a -- floor(a)
ctx: ~floats
desc:
	Replaces FTOS with floor(FTOS), which is the integer closest to "a" but less
	than or equal to it.
	Example: 
		fpi ffloor f.
	will print "3.00000" but
		fpi fnegate ffloor f.
	will print "-4.00000"


word: ffrac
stack: float: a -- frac(a)
ctx: ~floats
desc:
	Replaces FTOS with frac(a), which is the fractional portion of "a".
	Example: 
		fpi ffrac f.
	will print "0.14159"


word: fint
stack: float: a -- int(a)
ctx: ~floats
desc:
	Replaces FTOS with int(a), which is the integer portion of "a".
	Example: 
		fpi fint f.
	will print "3.00000", and 
		fpi fnegate fint f.
	will print "-3.00000"


word: fp-decimal-char
stack: -- a
ctx: ~floats
desc:
	Character used to indicate the "decimal point".  That is, digits to the
	right of this character represent the fractional portion of the number.
	Currently only used for input.


word: >float
stack: a n -- flag \ float: -- a |
ctx: ~floats
desc:
	Convert string (a,n) to a FP value if possible.  If successful, FP value is
	in FTOS and -1 is in TOS.  If it fails, FTOS is unaffected and 0 is on TOS


word: f,
stack: float: a --
ctx: ~floats
desc:
	Put the FP value in FTOS into an fvariable located at "here", and pop the FP
	value from the FP stack.


word: fconstant
stack: <name> -- \ float: a --
ctx: ~floats
desc:
	Allocates space for a 10-byte IEEE FP value and initializes it from FTOS.
	That value will be put in FTOS whenever <name> is invoked.


word: d=
stack: d1 d2 -- flag
ctx: ~doubles
desc:
	Compares the two doubles "d1" and "d2", leaving "true" in TOS if they are
	equal, and "false" otherwise.


word: md5
stack: a n -- a' n'
ctx: ~
desc:
	Given a string (a,n) returns the MD5 hash corresponding to it, (a1,n1).
	For example:

		" hello" md5 type

	prints: 
		5d41402abc4b2a76b9719d911017c592


word: rc4
stack: a n --
ctx: ~
desc:
	Encrypt the string (a,n) using the RC4 symmetric encryption algorithm.
	The encryption is performed in-place, e.g. the string is overwritten.
	Requires that "rc4setup" be performed first to set the password.


word: htable
stack: n <name> --
ctx: ~struct
desc:
    Create an OS allocated hash table (double hashed and externally
    chained) with an estimate of the number of entries 'n'. You may
    then specify hash functions for integers and/or strings, or ac-
    cept the defaults. For example (where keys are strings):

       ok> needs alg/htable
       ok> ~struct ~myapp
       ok> 500 htable mytable
       ok> :: fnvhash ; is $hash1
       ok> :: my$hash ; is $hash2

    For convenience, declaring

       ok> mytable

    sets it as the active data structure, so words like 'fnd' and
    'rmvkeys' automatically know to operate on it.


word: (htable)
stack: n xt -- a
ctx: ~struct
desc:
    Used to implement 'htable', but is necessary if you wish to al-
    locate it within a turnkey. For example (where keys are integers):

       500 htable mytable

       : turnkey-table ( --)
            500 ['] mytable (htable) ['] mytable !
            { myhash } is hash1
            { (.) fnvhash } is hash2 ;

       save myapp.exe


word: bestprime
stack: n -- n-prime
ctx: ~struct
desc:
    Find a prime greater than 'n' that isn't too close to a
    power of 2. Useful in determining a hash table's optimal
    distribution size.


word: stack
stack: <name> --
ctx: ~struct
desc:
    Create the header for an allocated stack (or queue), for example:
       ok> needs alg/stack
       ok> ~struct ~myapp
       ok> stack mystack

    For convenience, declaring
       ok> mystack

    sets it as the active data structure, so words like 'psh' and 'pop'
    automatically know to operate on it. If this is not desired use the
    associated sub-word, eg. '(pop)', which then expects a stack point-
    er on the, uh, stack. Any sub-words in alg/list may also be used.


word: pok
stack: data --
ctx: ~struct
desc:
    Replace the active stack's top data element with 'data', or
    if empty, push it on.

    Sub-word: (pok)


word: -pok
stack: data --
ctx: ~struct
desc:
    Replace the active stack's bottom data element with 'data', or
    if empty, push it on.

    Sub-word: (-pok)


word: tuk
stack: --
ctx: ~struct
desc:
    Tuck the top data element below the second data element of the
    active stack.

    Sub-word: (tuk)


word: -hop
stack: --
ctx: ~struct
desc:
    Rotate the top data element to below the third element of the
    active stack.

    Sub-word: (-hop)


word: pik
stack: n --
ctx: ~struct
desc:
    Duplicate the data element located 'n' deep to the top of the active stack.

    Sub-word: (pik)


word: rmn
stack: n --
ctx: ~struct
desc:
    Divide top element of the active stack by 'n', replacing that
    element with the remainder (modulus).

    Sub-word: (rmn)


word: struct:
stack: <name> -- xx offset
ctx: ~
desc:
	Create a "struct", which is similar to the C construct.  One declares a
	struct, then uses the various field creators.  


word: field:
stack: offset size <name> -- offset'
ctx: ~
desc:
	Declares a field named "<name>" in the most recent "struct:".  The field has
	a size "size".  "offset" is carried over from the "struct:" declaration or
	previous "field:" or related words.


word: sallot:
stack: <name> -- a
ctx: ~
ver: 6.0.12
desc:
	Allows you to allocate the memory for a structure within a function.
	Usually you will create a structure variable in interpreter mode like this:
		mystruct myvar

	When you want to create a structure variable within your own function, you
	can do it like this:
		: t
		sallot: mystruct  | t will allocate memory for a structure of 'type' mystruct
		5 over a !        | t will write the value 5 to the field 'a' of this new structure
		;
	And then maybe:
		t a @ . | will print '5'


word: match
stack: n1 n2 -- flag
ctx: ~struct
desc:
    Deferred comparison word for use by the data structure lib-
    raries. '=' is default behaviour.


word: in?
stack: key bucket | a-str u bucket -- t
ctx: ~struct
desc:
    Deferred search word for use by the data structure libraries.
    'dup @' is default behaviour.


word: sort
stack: buffer size --
ctx: ~struct
desc:
    Deferred sort algorithm for use by the data structure libraries.
    'qsort' is default behaviour.


word: ins
stack: data ... --
ctx: ~struct
desc:
    Insert 'data' into the active data structure, with the following
    arguments:

    list, htable, bintree ( data --)
    array, darray ( data a --)
    2array ( data x y --)
    3array ( data x y z --)
    
    Sub-word: (ins)


word: del
stack: data --
ctx: ~struct
desc:
    Find and delete the element 'data' from the active data structure.
    Indirection may be handled by redefining the deferred words 'fetch'
    (default '@') and 'match' (default '=').

    Sub-word: (del)


word: fnd
stack: data -- data-ptr... | false
ctx: ~struct
desc:
    Search for 'data' in the active data structure, returning all
    matching data pointers, or zero if none found. The deferred
    word 'match' (default '=') may be redefined. Indirection may
    be handled by redefining the deferred word 'fetch' (default '@').

    Sub-word: (fnd)


word: itr
stack: xt --
ctx: ~struct
desc:
    Execute 'xt' for each element in the active data structure. 'xt' must return
    'false' to stop iteration, or 'true' to continue.

    Sub-word: iterate


word: srt
stack: --
ctx: ~struct
desc:
    Sort the active data structure using the algorithm defined in
    the deferred word 'srt' (default quicksort) with test 'compare'
    (default '<').

    Sub-word: (srt)


word: prt
stack: --
ctx: ~struct
desc:
    Print the contents of the active data structure. Indirection may
    be handled by redefining the deferred word 'fetch' (default '@').
    
    Sub-word: (prt)


word: all
stack: -- last first
ctx: ~struct
desc:
    Return the address of the first and last cells in the active data
    structure. Useful for providing a do-loop's index and limit.
    
    Sub-word: (all)


word: th
stack: n -- a
ctx: ~struct
desc:
    Return the address of the cell 'n' deep in the active data
    structure. '0 th' is the first cell.

    Sub-word: (th)


word: list
stack: <name> --
ctx: ~struct
desc:
    Create the header for an allocated linked list, for example:

       ok> needs alg/list
       ok> ~struct ~myapp
       ok> list mylist

    For convenience, declaring

       ok> mylist

    sets it as the active data structure, so words like 'ins' and 'del'
    automatically know to operate on it. If this is not desired, use
    the associated sub-words, eg. '(ins)', which then expect a list or
    node pointer on the stack. Any sub-words in alg/stack may also be
    used.


word: lst>buf
stack: list buffer --
ctx: ~struct
desc:
    Copy the contents of 'list' to 'buffer' of at least the same
    size. Indirection may be handled by redefining the deferred
    word 'fetch' (default '@').


word: buf>lst
stack: list buffer --
ctx: ~struct
desc:
    Replace the contents of 'list' with the contents in 'buffer'.
    Indirection may be handled by redefining the deferred word
    'fetch' (default '@').


word: array
stack: size <name> --
ctx: ~struct
desc:
    Create a linear array of fixed size, allocated to OS memory.
    For example:

       ok> needs alg/array
       ok> ~struct ~myapp
       ok> 33 array myarray

    For convenience, declaring

       ok> myarray

    sets it as the active data structure, so words like 'size' and
    'prt' automatically know to operate on it.


word: (array)
stack: size -- a
ctx: ~struct
desc:
    Used to implement 'array', but is necessary if you wish to
    allocate one within a turnkey:

       ok> 33 array myarray
       ok> : makearray  33 (array) ['] myarray ! ;
       ok> ' makearray is appstart
       ok> save myapp.exe


word: darray
stack: size <name> --
ctx: ~struct
desc:
    Create a dynamic linear array that expands when full, and con-
    tracts when half empty (if using 'ins' and 'del'). Resize amount
    may be changed in the deferred word 'newsize', default 25%.


word: xy>c
stack: x y -- a
ctx: ~struct
desc:
    Given coordinates (x,y), return the corresponding cell in
    the active (2-D) array. Origin is first cell, 0,0.


word: c>xy
stack: a -- x y
ctx: ~struct
desc:
    Given a cell in the active (2-D) array, return the corres-
    ponding coordinates (x,y). Origin is first cell, 0,0.


word: xyz>c
stack: x y z -- a
ctx: ~struct
desc:
    Given coordinates (x,y,z), return the corresponding cell in
    the active (3-D) array. Origin is first cell, 0,0,0.


word: c>xyz
stack: a -- x y z
ctx: ~struct
desc:
    Given a cell in the active (3-D) array, return the corres-
    ponding coordinates (x,y,z). Origin is first cell, 0,0,0.


word: regex_find!
stack: a1 n1 a2 n2 -- 0 | a n #matched
ctx: ~strings
desc:
	Easy wrapper for regex search.  Find (a2,n2) in (a1,n1), returning either 0
	for no matches, or the number of matches, followed by the first match.


word: regex_find
stack: a1 n1 regex -- 0 | a n #matched
ctx: ~strings
desc:
	Easy wrapper for regex search.  Find regex in (a1,n1), returning either 0
	for no matches, or the number of matches, followed by the first match.


word: regex_getmatch
stack: n -- a n
ctx: ~strings
desc:
	Retrieve the "n"th match from the most recent regex match.  "0" corresponds
	to the entire matched string, while "1" etc. correspond to parenthesised
	matches.


word: string/regex
ctx: ~strings
desc:
	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.

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

		http://www.pcre.org/
	


word: strnew:
stack: <name> --
ctx: ~strings
ver: 6.1
desc:
	Allocate a named buffer capable of holding either a small counted string or
	a NUL terminated string smaller than 255 bytes.


word: zcat
stack: src dest --
ctx: ~strings
ver: 6.1
desc:
	Append NUL terminated string at "src" to "dest".  It is up to the programmer
	to ensure that "dest" has enough space to accommodate all the string data.


word: strcatf
stack: a1 n1 a2 n2 -- a3 n3
ctx: ~strings
ver: 6.1
desc:
	Append (a2,n2) to (a1,n1) resulting in the string (a3,n3).  The string
	(a3,n3) is always in the "scratch" buffer, and so using this more than once
	will overwrite previous strings (or anything else in "scratch").  It is,
	however, much faster than "strcat".  On the other hand, one may not use
	strings larger than 4091 bytes total.


word: strcat
stack: a1 n1 a2 n2 -- a3 n3
ctx: ~strings
ver: 6.1
desc:
	Append (a2,n2) to (a1,n1) resulting in the string (a3,n3).  The memory at
	"a3" is "allocate"d, so a properly behaving application will take care to
	"free" it.  The resultant string may be as large as memory permits.


word: splitws
stack: a n -- a1 n1 a2 n2 true | a n false
ctx: ~strings
ver: 6.1.5
desc:
    Split string on first occurrence of whitespace. Returns empty strings for initial, trailing,
        or consecutive whitespace. If no whitespace in string, returns unchanged with flag false.


word: strdup
stack: a n -- a' n'
ctx: ~strings
ver: 6.1.9
desc:
	Create a duplicate of the passed-in string, in allocated memory.  The caller
	has the rsponsibility of freeing the memory used by the duplicate.


word: tr
stack: a n a1 n1 a2 n2 --
ctx: ~strings
ver: 7.0.2
desc:
	Like the unix 'tr' utility.  Take source string (a,n) and convert each
	character in (a1,n1) into the corresponding one in (a2,n2).

	Example:

		" (abc)" " ()" " []" tr

	will result in the original string being converted (in-place) into " [abc]"


word: strsplitat
stack: a n off len -- a1 n1 a2 n2
ctx: ~strings
ver: 7.0.2
desc:
	Split the string at offset "off" for "len" characters.  
	Example:
		" abcdefg" 2 3 strsplitat
	gives:
		" ab" and " fg"

	NOTE: This word does *no* checking of the arguments, so if you give it
	garbage you will likely crash.  It is intended to be used by higher level
	words, but is useful on its own.


word: strbreakat
stack: a n off -- a1 n1 a2 n2
ctx: ~strings
ver: 7.0.2
desc:
	Break the string into two strings, at the offset given.
	Example:
		" abcdefg" 2 strbreakat
	gives:
		" ab" and " cdefg"

	NOTE: This word does *no* checking of the arguments, so if you give it
	garbage you will likely crash.  It is intended to be used by higher level
	words, but is useful on its own.


word: strcvt
stack: a n cvt -- a' n'
ctx: ~strings
ver: 6.0.9
desc:
	Converts the string (a,n) using the conversion token "cvt" created via
	"icon_open".  The string is NUL terminated both for single and double byte
	strings, but the NUL terminator is not counted in the string length.
	
	The returned string is "allocate"d so you have to "free" it


word: utf>uni
stack: a n -- a' n'
ctx: ~strings
ver: 6.0.9
desc:
	Converts the string (a,n) from utf-8 encoding to ucs-2le.  Resultant string
	is NUL terminated as well.

	The returned string is "allocate"d so you have to "free" it


word: uni>utf
stack: a n -- a' n'
ctx: ~strings
ver: 6.0.9
desc:
	Converts the string (a,n) from ucs-2 encoding to utf-8le.  Resultant string
	is NUL terminated as well.

	The returned string is "allocate"d so you have to "free" it


word: string/iconv
ctx: ~
desc:
	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.
	


word: dstr
stack: n -- a
ctx: ~strings
ver: 7.0.6
desc:
	Allocate a new dynamic string with space for 'n' characters.  The string
	will grow as needed when "dplace" and "+dplace" are used to add content to
	it.  Remember to call "dfree" on the string to release the memory allocated.


word: dfree
stack: a --
ctx: ~strings
ver: 7.0.6
desc:
	Frees the memory of the dynamic string; after this word, the string is no
	longer valid and accessing it might cause a crash.  Likewise, the dstr
	itself - so don't try to access it.


word: zlib_uncompress
stack: dest destsize^ src srcsize -- result
ctx: ~
desc:
	Decompresses the source buffer into the destination buffer. sourceLen is the
	byte length of the source buffer. Upon entry, destLen is the total size of
	the destination buffer, which must be large enough to hold the entire
	uncompressed data. (The size of the uncompressed data must have been saved
	previously by the compressor and transmitted to the decompressor by some
	mechanism outside the scope of this compression library.) Upon exit, destLen
	is the actual size of the compressed buffer.

	This function can be used to decompress a whole file at once if the input
	file is mmap'ed.

	uncompress returns Z_OK if success, Z_MEM_ERROR if there was not enough
	memory, Z_BUF_ERROR if there was not enough room in the output buffer, or
	Z_DATA_ERROR if the input data was corrupted. 


word: zlib_compress
stack: dest destsize^ src srcsize -- result
ctx: ~
desc:
	Compresses the source buffer into the destination buffer. sourceLen is the
	byte length of the source buffer. Upon entry, destLen is the total size of
	the destination buffer, which must be at least 0.1% larger than sourceLen
	plus 12 bytes. Upon exit, destLen is the actual size of the compressed
	buffer.

	This function can be used to compress a whole file at once if the input file
	is mmap'ed.

	compress returns Z_OK if success, Z_MEM_ERROR if there was not enough
	memory, Z_BUF_ERROR if there was not enough room in the output buffer.


word: zlib_crc32
stack: crc buf len -- crc'
ctx: ~
desc:
	Update a running crc with the bytes buf[0..len-1] and return the updated
	crc. If buf is NULL, this function returns the required initial value for
	the crc. Pre- and post-conditioning (one's complement) is performed within
	this function so it shouldn't be done by the application. Usage example:

		0 value crc
		0 0 0 zlib_crc32 to crc 
		repeat
			num-bytes read-buffer if
				crc buffer num-bytes zlib_crc32 to crc
			then
		while
		...


word: gzclose
stack: handle -- result
ctx: ~
desc:
	Flushes all pending output if necessary, closes the compressed file and
	deallocates all the (de)compression state. The return value is the zlib
	error number (see function gzerror below).


word: gztell
stack: handle -- offset
ctx: ~
desc:
	Returns the starting position for the next gzread or gzwrite on the given
	compressed file. This position represents a number of bytes in the
	uncompressed data stream.

	gztell(file) is equivalent to gzseek(file, 0L, SEEK_CUR) 


word: gzseek
stack: handle offset whence -- offset
ctx: ~
desc:
	Sets the starting position for the next gzread or gzwrite on the given
	compressed file. The offset represents a number of bytes in the uncompressed
	data stream. The whence parameter is defined as in lseek(2); the value
	SEEK_END is not supported.

	If the file is opened for reading, this function is emulated but can be
	extremely slow. If the file is opened for writing, only forward seeks are
	supported ; gzseek then compresses a sequence of zeroes up to the new
	starting position.

	gzseek returns the resulting offset location as measured in bytes from the
	beginning of the uncompressed stream, or -1 in case of error, in particular
	if the file is opened for writing and the new starting position would be
	before the current position. 


word: gzwrite
stack: handle buf len -- written
ctx: ~
desc:
	Writes the given number of uncompressed bytes into the compressed file.
	gzwrite returns the number of uncompressed bytes actually written (0 in case
	of error).


word: gzread
stack: handle buf len -- read
ctx: ~
desc:
	Reads the given number of uncompressed bytes from the compressed file. If
	the input file was not in gzip format, gzread copies the given number of
	bytes into the buffer.

	gzread returns the number of uncompressed bytes actually read (0 for end of
	file, -1 for error). 


word: gzopen
stack: zpath mode -- handle
ctx: ~
desc:
	Opens a gzip (.gz) file for reading or writing. The mode parameter is as in
	fopen ("rb" or "wb") but can also include a compression level ("wb9") or a
	strategy: 'f' for filtered data as in "wb6f", 'h' for Huffman only
	compression as in "wb1h". (See the description of deflateInit2 for more
	information about the strategy parameter.)

	gzopen can be used to read a file which is not in gzip format ; in this case
	gzread will directly read from the file without decompression.

	gzopen returns NULL if the file could not be opened or if there was
	insufficient memory to allocate the (de)compression state 


word: util/zlib
ctx: ~
desc:
	Simple wrapper around the ZLIB compression library.  See the ZLIB
	documentation for detailed information on these words.
		http://www.zlib.net/manual.html


word: snap~
stack: <name> --
ctx: ~
ver: 6.0.11
desc:
	Moved to library "util/contexts" in 6.0.12
	Creates a "snapshot" of the current search-order.  The word
	"<name>" it creates, when invoked, will reset the search order
	to the way it was when "<name>" was created.


word: eachline
stack: a n xt --
ctx: ~strings
desc:
	 Iterates over the string (a,n), calling "xt" with each line as input.  A
	 line is defined as any sequence of characters terminated by a character
	 ASCII "10".

	 The "xt" called must consume the (a,n) passed to it.


word: func:>xt
stack: " name" -- xt
ctx: ~
ver: 7.0.6
desc:
	Given the name of a word created with "func:", will return the code address
	of the function it loads, or 0.  The 0 return result can occur for two
	reasons:

		1) The 'func:' doesn't exist, or
		2) The function it loads has not yet been loaded

	Since "func:" words are demand-loaded, scenario (2) is fairly likely.


word: cellskip
stack: n -- a
ctx: ~struct
desc:
    In a 'do-loop' where the index and limit are the bounds of an array,
    skip to the next cell at the end of the current iteration.


word: mark
stack: <name> --
ctx: ~util
desc:
	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.

	Note: the word will affect only the context in which it was run.
	


word: afunc:
stack: <name> --
ctx: ~
ver: 6.1.11
desc:
	Like "func:" but for arbitrary argument list (cdecl).

	The argument list needs to be finished off with the number of
	arguments to the function in TOS, like:

		arg1 arg2 arg3 arg4 4 func: ...

	The function will return a value in TOS


word: ioports
stack: ver: 6.1.4
ctx: meta
desc:
	Accessing the CPU I/O ports on Windows and Linux is usually only permitted
	to privileged programs.  If you try to use the related words here without
	having acquired permissions for your application, you will probably get a
	crash with some sort of privileged instruction exception.

	Windows users can take advantage of a program called "porttalk":

		http://www.beyondlogic.org/porttalk/porttalk.htm

	Linux users will want to look at the IO Port Programming HOWTO:

		http://tldp.org/HOWTO/IO-Port-Programming.html


word: local[
stack: loc1init loc2init ... --
ctx: ~
desc:
	Begin the definition of a set of local values for use within
   the word being defined. 
   For example:-    local[ loc1 loc2 | loc3 loc4..locn -- ] 
   Locals definition ends with the closing ']'.
   Those defined before the '|' get initialized from the stack.
   Those defined after the '|' are initialized to 0 at 
   compiletime, but retain their value from call to call of the
   word in which they are defined. (like "C" static variables)
   There is no limit to the number of locals that can be defined.
   A local behaves the same way as a value, and can be used with
   'to' '+to' and 'addr'.
   For bacwards compatibility with the old version, the words
   'lto' and '+lto' are retained. 


word: lto
stack: n <local> --
ctx: ~
desc:
   Sets the local to n. (Same as 'to')
   Provided for backwards compatibility only. Use 'to' instead.


word: +lto
stack: n <local> --
ctx: ~
desc:
   Adds n to the local. (Same as '+to')
   Provided for backwards compatibility only. Use '+to' instead.


word: weekday-on-or-before
stack: date k -- date'
ctx: ~date
desc:
	Given a fixed date and a weekday, return a fixed date which is that weekday,
	and as near to the fixed date passed in as possible, within a week before.
	If the passed in date is that weekday, returns that date.


word: weekday-on-or-after
stack: date k -- date'
ctx: ~date
desc:
	Given a fixed date and a weekday, return a fixed date which is that weekday,
	and as near to the fixed date passed in as possible, within a week after.
	If the passed in date is that weekday, returns that date.


word: weekday-nearest
stack: date k -- date'
ctx: ~date
desc:
	Given a fixed date and a weekday, return a fixed date which is that weekday,
	and as near to the fixed date passed in as possible, whether before or
	after, within a week.
	If the passed in date is that weekday, returns that date.


word: weekday-after
stack: date k -- date'
ctx: ~date
desc:
	Given a fixed date and a weekday, return a fixed date which is that weekday,
	and as near to the fixed date passed in as possible, within a week after.


word: weekday-before
stack: date k -- date'
ctx: ~date
desc:
	Given a fixed date and a weekday, return a fixed date which is that weekday,
	and as near to the fixed date passed in as possible, within a week before.


word: nth-weekday
stack: n k mm dd yyyy -- date
ctx: ~date
desc:
	Find the "n"th weekday "k" from Gregorian date MM/DD/YYYY.  If the "n" is
	negative, counts backward.


word: dst?
stack: f -- flag
ctx: ~date
ver: 6.1.4
desc:
	Using US/Canadian rules, return whether or not the fixed date "f" falls
	during Daylight Saving Time (DST).


word: eu-dst?
stack: f -- flag
ctx: ~date
ver: 6.1.4
desc:
	Using European Union rules, return whether or not the fixed date "f" falls
	during Daylight Saving Time (DST).


word: dayname
stack: n -- a n
ctx: ~date
desc:
	Converts the numeric day of week (0-6) to a three character abbreviation.
	For example, "2" -> "Tue"


word: isleap?
stack: yyyy -- flag
ctx: ~date
desc:
	Return true if the input year is a leap year (according to the Gregorian
	rules!).  This will not be correct for Julian era years.


word: hebrew>fixed
stack: mm dd yyyy -- f
ctx: ~date
desc:
	 Return fixed date from Hebrew date. This word is designed so that it works
	 for Hebrew dates month, day, year even if the month has fewer than day days
	 -- in that case the function returns the (day-1)st day after month 1, year.
	 This property is required by the functions hebrew-birthday and yahrzeit.


word: hanukkah
stack: year -- fixed
ctx: ~date
desc:
	 Returns the fixed date on which the first day of Hanukkah falls during the
	 Gregorian year passed in.


word: save-gui
stack: <file> --
ctx: ~ui
desc:
Creates an executable (turnkey) GUI application and exits the current Reva session. On UNIX you could also use save directly.
On Windows this word does the same as save does, but it also patches the created PE file to be a real GUI only application. So Windows doesn't create a DOS window when you start your GUI application.


word: pending-callbacks
stack: -- pending-callbacks-stack-handle
ctx: ~ui-priv
desc:
The GUI library collects all events that need to be processed until you actually process them in this stack.
Usually you will not need to access this stack directly. It is managed automatically by gui-main-loop.


word: cleanup-callback-stack
stack: --
ctx: ~ui-priv
desc:
Cleans the pending callbacks stack. If you call this word all events that may be collected in that stack get lost.
Usually you will not call this word directly.


word: gui-init
stack: --
ctx: ~ui
desc:
This word initializes the GUI library. You absolutely need to call this word before you use any other GUI related word from the ~ui context!
You can reinitialize the GUI library also after a call to gui-release.
Once you included the ui/gui library (with "needs ui/gui") this word becomes a startup handler. So when you create a turnkey GUI application with save-gui or (save-gui) this word will automatically be called at application startup.


word: gui-release
stack: --
ctx: ~ui
desc:
Releases all resources that are obtained by the GUI library.
You MUST NOT use any other GUI related words from the ~ui context after a call to gui-release.
But you can reinitialize the GUI library with gui-init.
Once you included the ui/gui library (with "needs ui/gui") this word becomes a shutdown handler. So when you create a turnkey GUI application with save-gui or (save-gui) this word will automatically be called at application shutdown.


word: gui-map
stack: handle -- handle
ctx: ~ui
desc:
Maps a widget defined with one of the widget creation words from the ~ui context to a native widget.
Usually you will not use this word directly - widgets get automatically mapped when you call show on them or their parent widgets.
Some attributes of some widgets cannot be changed once the widgets are mapped to native widgets. Please look into the IUP documentation for details.


word: gui-next-child
stack: handle lastchild -- nextchild
ctx: ~ui
desc:
You can use this word to traverse a widget tree.
Start with a container widget (for example a dialog or an hbox, vbox, zbox etc.).
The first call looks like "parent 0 gui-next-child" and returns a child widget if there is at least one.
Then you call it repeatedly like: "parent last-child gui-next-child" until it returns 0.


word: show
stack: handle -- handle
ctx: ~ui
desc:
Shows the widget at the default position that is configured for your system.
Also recursively shows all subwidgets of the widget.
So you only need to call show for a dialog and it gets visible with all widgets placed on it.
Showing a widget automatically maps it to its native widget representation. So you don't need to call gui-map explicitly to widgets that you make visible with show

Show is used to display modeless dialogs - use popup to handle modal window handling...


word: hide
stack: handle -- handle
ctx: ~ui
desc:
Makes a widget and all its subwidgets (recursively) invisible. The widgets are not destroyed nor unmapped from their native representations, so you can make them visible again whenever you want with show.


word: popup
stack: handle -- handle
ctx: ~ui
desc:
Makes a widget and all its subwidgets (recursively) visible. Basically popup does the same as what is documented for show.

Use popup to display modal widgets and show to display modeless widgets...


word: spacer
stack: parent -- parent
ctx: ~ui
desc:
A spacer is a specific kind of widgets. It is a virtual widget without a native representation.

A spacer allows you to control where and how many empty space is placed when a dialog gets resized.


word: vbox[
stack: -- handle
ctx: ~ui
desc:
Creates a vbox widget. A vbox is a list of widgets that are arranged vertically.
All widgets you create after vbox[ are placed within the vbox.
You can "close" a vbox widget definition with ]w.


word: vboxs[
stack: -- handle
ctx: ~ui
desc:
Similarly to vbox[ this word creates a vbox widget. A spacer is automatically put at the beginning of the vbox's widget list.
"Close" a vbox definition with ]c.


word: hbox[
stack: -- handle
ctx: ~ui
desc:
Creates an hbox widget which is a list of widgets that are arranged horizontally.
All widgets you create after hbox[ are placed within the hbox.
You can "close" an hbox widget definition with ]w.


word: hboxs[
stack: -- handle
ctx: ~ui
desc:
Similar to hbox[ this word creates an hbox widget. A spacer is automatically inserted at the beginning of the hbox's widget list.
"Close" an hbox definition with ]c.


word: zbox[
stack: -- handle
ctx: ~ui
desc:
A zbox contains a list of widgets. One of these widgets is the active widget and visible, the others are hidden.
Use zbox's when you want to manage a changing area.
"Close" a zbox definition with ]w


word: attri:
stack: a n <name> --
ctx: ~ui
desc:
This word is internal - you will probably not want to use it. It is a helper word set attribute values.


word: attr:
stack: handle a n <name> -- handle
ctx: ~ui
desc:
Sets the attribute <name> to the value (a, n) in the widget specified by handle.
Attributes are the most important way in the gui library to control the application's gui behavior.
For many special attributes there are specific words to access them more simpler.
Please have a look at the IUP documentation for detailed descriptions on which attributes are provided by several kinds of widgets.


word: attr?:
stack: handle <name> -- handle a n
ctx: ~ui
desc:
Returns in (a,n) the value of the attribute <name> in the widget specified by handle.
For many specific widgets the gui library provides specific words to access them more easily.


word: fgcolor
stack: handle a n -- handle
ctx: ~ui
desc:
Set the foreground color of the widget specified by handle.
This is valid for example for text widgets or labels etc.
The string must have the format: "red green blue" with red, green and blue being a decimal value in the range [0,255] each.
So for example " 255 255 255" encodes white " 255 0 0" encodes red and so on.


word: size
stack: handle a n -- handle
ctx: ~ui
desc:
Sets the size of the specified widget.
The widget string has the format " 200x100" where 200 is the width and 100 the height (decimal).
You can also leave out either the width or the height (but not both), so " 200x" changes the width to 200 but leaves the height unchanged.


word: expand
stack: handle -- handle
ctx: ~ui
desc:
Allows a widget to be resized both horizontally and vertically.
Example:
  dialog[
    " quit" button[ expand  action[ ." bye" gui-close]a ]w
  ]d title " my dialog"
This code creates a dialog containing a button widget. When you resize the dialog, the button also gets resized in both directions.


word: tip
stack: handle a n -- handle
ctx: ~ui
desc:
Specifies a tool tip for the widget specified by handle. The tooltip is shown when the user holds the mouse pointer for a while on the widget without moving it too much.


word: setval
stack: handle a n -- handle
ctx: ~ui
desc:
Sets the attribute VALUE to the value specified by (a,n). Many widgets provide a VALUE attribute. Please look at the IUP documentation for details on this.


word: conid?
stack: handle -- handle a n
ctx: ~ui
desc:
Returns the value of the CONID attribute which is the ID of the native widget. This attribute is only valid after a widget has been mapped to a native widget.


word: set-time
stack: handle n -- handle
ctx: ~ui
desc:
Sets the timer interval of the timer widget specified by handle. The timer event will occur every nth millisecond.


word: topmost
stack: handle -- handle
ctx: ~ui
desc:
Pushes the dialog specified by handle to the top of the window stack. This will ensure that the dialog gets visible.


word: caret?
stack: handle -- handle a n
ctx: ~ui
desc:
Returns the position of the caret in an editbox. The result string looks like " XxY" where X is the x position and y the y position.


word: selection?
stack: handle -- handle a n
ctx: ~ui
desc:
Returns the block that is currently being marked in an editbox widget.
The result string has the format " lin1,col1:lin2,col2"


word: split-it
stack: a n c -- n1 n2 -1 | 0
ctx: ~ui
desc:
This word is internally used to split a string into integer values separated by a specific character.
(a, n) must have the form <number>c<number>.

Used internally and probably of low interest for you.


word: label[
stack: a n -- handle
ctx: ~ui
desc:
Creates a label widget initially showing the label (a,n). After label[ you can set several additional attributes for the label (for example the foreground or background color by using fgcolor or bgcolor resp.) and then close the label definition with ]w.


word: button[
stack: a n -- handle
ctx: ~ui
desc:
Creates a button widget initially showing the label (a,n). Close a button definition with ]w.
Between button[ and ]w you can set attributes and specify callbacks for the button widget etc.


word: editbox[
stack: -- handle
ctx: ~ui
desc:
Create an editbox widget. An editbox widget is a text input widget with several lines.
For editboxes it is common to allow expansion (see expand) so that the editbox gets resized together with your dialog window.
Close an editbox definition with ]w.


word: canvas[
stack: -- handle
ctx: ~ui
desc:
Creates a canvas widget. Canvas are mighty widgets to draw stuff on.
You can use canvas widgets as the basis for your own widgets.
You can also use a canvas to contain a cd canvas in which you can draw using primitives for lines, points, circles etc.
You can also connect a canvas to an OpenGL buffer canvas and draw 3D stuff into it.

Close the canvas widget with ]w.

As you see canvas widgets are quite complicated. Please look into the IUP documentation for more details on IUP canvas and study the examples carefully to understand how to work with them with Reva.


word: matrix[
stack: -- handle
ctx: ~ui
desc:
A matrix widget is a table with rows and columns. Matrix widgets are controlled via lots of attributes. Please look into the IUP documentation and into the examples for more details.


word: timer
stack: -- handle
ctx: ~ui
desc:
Creates a timer widget. You don't need to close timer widgets with ]w or ]c or so because timer widgets don't need to be added to parent widgets.


word: type-open
stack: handle -- handle
ctx: ~ui
desc:
Turns a file-dialog into a file open dialog.
Usually you will not need to use this word directly. Use file-open-dialog[ instead.


word: type-save
stack: handle -- handle
ctx: ~ui
desc:
Turns a file-dialog into a file save dialog.
Usually you will not need to use this word directly. Use file-save-dialog[ instead.


word: type-dir
stack: handle -- handle
ctx: ~ui
desc:
Turns a file-dialog into a directory selection dialog.
Usually you will not need to use this word directly. Use dir-dialog[ instead.


word: file-dialog[
stack: -- handle
ctx: ~ui
desc:
Creates a file dialog. You will usually not use this general word, but one of the more specific words: Close the dialog definition with ]fd.
file-open-dialog[, file-save-dialog[ or dir-dialog[


word: ]c
stack: parenthandle handle -- parenthandle
ctx: ~ui
desc:
Adds a spacer to the widget specified by handle and adds the handle widget to the widget specified by parenthandle.
]c is used for container widgets that are created with an initial spacer widget, for example widgets that are created via vboxs[ or hboxs[ etc.


word: ]w
stack: parenthandle handle -- parenthandle
ctx: ~ui
desc:
Closes a widget definition (of the handle widget) and adds the handle widget to the parenthandle widget.


word: toolbar[
stack: -- handle
ctx: ~ui
desc:
Create a toolbar widget. Close the definition with ]t.
A toolbar widget is in fact only a vertical widget that is placed on the top of a dialog. Thus the toolbar must be the first widget created within a dialog. Don't use dialogs[ (but only dialog[) if you want to use toolbars.


word: frame[
stack: a n -- a n handle handle
ctx: ~ui
desc:
Creates a group box with the label (a,n) around the widgets that it contains. Close the frame group definition with ]fr.


word: cbox[
stack: -- handle
ctx: ~ui
desc:
Creates a cbox which is a container that contains widgets with fixed x and y coordinates.
Each child widget must contain a CX and a CY attribute before it gets mapped to its native representation.


word: gui-loop-step
stack: -- continuationcode
ctx: ~ui
desc:
Processes the next event in the event loop if there is any. Returns gui-close when an event handler returned gui-close and gui-default otherwise.


word: gui-ignore
stack: -- -1
ctx: ~ui
desc:
A return code used within callbacks to flag that the event shall be ignored and not further processed.


word: gui-continue
stack: -- -4
ctx: ~ui
desc:
A return code used within callbacks to flag that the event shall be propagated to the next event handler.


word: ui-copyright
stack: -- a n
ctx: ~ui
desc:
Returns a string that reproduces a valid copyright notice from tecgraf, the owner of the IUP gui toolkit. You must reproduce this copyright notice somewhere in your program and your documentation. Please refer to the IUP license for details.


word: gui-main-loop
stack: --
ctx: ~ui
desc:
Blocks the application and repeatedly processes events until one event handler (callback) returns gui-close.


word: action
stack: handle xt -- handle
ctx: ~ui
desc:
Sets the ACTION callback. This is the default callback for the canonical operation on most widgets (for example for a button click).


word: action[
stack: <text> --
ctx: ~ui
desc:
Starts the definition of an inline callback for the ACTION event. Stop the definition with ]a.
Used like this:
  dialog[
    " quit" button[ action[ ." ok, bye!" gui-close ]a ]w
  ]d title " myDialog"


word: iup
stack: -- libhandle
ctx: ~iup
desc:
The handle of the IUP library. Usually you will not need to use this word.
Have a look into the IUP documentation if you want to use IUP directly.
You will find the IUP homepage in the internet at: http://www.tecgraf.puc-rio.br/iup/


word: gethelp
stack: a n --
ctx: ~help
desc:
	This is the word actually called by "help".  It knows how to query the help
	database for the word (a,n).


word: lang:
stack: <text> --
ctx: ~help
ver: 7.0.9
desc:
	Sets the language for the help to <text>.  For example:
	   help de

	will use the German help text.  


word: help~
stack: <text> --
ctx: ~
ver: 7.0.10
desc:
	Finds all words containing "<text>" as some part of the word, for which help
	has been defined.  Displays them in dotted-context format.   That is, the
	word "@" in the context "~" is displayed as "~.@"


word: callback
stack: --
ctx: ~
ver: 7.0.10
desc:
	Indicates this word is a "callback", meant to be called from C code.  The
	word 'callback' must be the first in the new word being defined.  It sets up
	a mechanism whereby normal Reva words can be called.

	NOTE: The amount of data stack available is very limited inside a callback -
	currently not more than 64 words.  It is therefore important to limit the
	use of the stack inside a callback!

	Access to the parameters passed to the callback is via the word 'cb-param'.

	Example:

		: my-callback  callback  0 cb-param . cr ;
	
	REPLACES cb:


word: callback-std
stack: --
ctx: ~
ver: 7.0.10
desc:
	Same as 'callback', but called from code using the 'stdcall' convention
	(typically Windows callbacks).  Everything mentioned in 'callback' applies
	to 'callback-std', but there is one difference.

	A 'stdcall' word needs to 'pop' parameters it was passed.  So the usual ';'
	word is not sufficient.  There is an additional word, 'cb-ret', which is
	required to appear within the body of the callback.  It need only be called
	before the actual return from the callback occurs.

	REPLACES stdcb:


word: asm{
stack: <asm>... }
ctx: ~
desc:
	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!
	


word: choices:
stack: <name> --
ctx: ~
desc:
	MOVED TO choices in 6.0.11
	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.


word: choice
stack: xt n --
ctx: ~
desc:
	MOVED TO choices in 6.0.11
	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.


word: default
stack: xt --
ctx: ~
desc:
	MOVED TO choices in 6.0.11
	Makes 'xt' the default "choice" to be executed when nothing else
	matches.  The default "default" is to do nothing.


word: test:
stack: <name>...; -- flag
ctx: ~
desc:
	This word introduces a unit-test.  The rest of the line on which 'test:'
	appears is the name of the test, which will be displayed if there is an
	error.  If tests are defined inside a library or other file, then they
	should be enclosed in a "IFTEST" block:

	Example:
		
		[IFTEST]
		~test
		test: unit test #1
			dup / 1 = ;

		...

		test
		[THEN]
		
	The test is an anonymous word, and is terminated with ";".  It should return
	true or false (true means success). 


word: test
stack: --
ctx: ~
desc:
	This runs all tests which have been defined, and displays the results
	(including timing and totals).


word: blab
stack: a n --
ctx: ~
desc:
	Since normal I/O is superceded for the duration of tests, printing notices
	etc. is done with this word.  It's a version of 'type' which works inside a
	test.


word: verbose
stack: --
ctx: ~test
desc:
	Set this to 'true' in order to make the test suite report the name of each
	test as it is performed.


word: elapsed
stack: -- a n
ctx: ~
desc:
	Used in conjunction with 'start-time'.  Produces a string showing the
	elapsed milliseconds since 'start-time'.

	Example:

		test: very important
			start-time
			...
			elapsed blab ;
			
	This will print "very important: nnn ms"


# lang

lang: de
desc:
        Legt den letzten Fehlercode auf den Stack. Unter Windows wird das 
        Wort mit der Funktion "GetLastError", unter Linux mit der Variablen 
        'errno' verbunden.
        


lang: de
desc:
        Wird wie "[IF]" benutzt, aber [IFTEST] ist nur dann wahr wenn 
        das Wort "TESTING" definiert wurde. Z.b. wenn Reva mit der "-t"
        Option gestartet wurde.
        


lang: de
desc:
        Einzeiliges Schleifen Konstrukt.  'xt' wird für jeden Wert von
        'lo' bis 'hi' ('hi' ausgeschlossen) aufgerufen  

	Beispiel:

	    { . } 20 10 foreach

        Hier wird ein anonymer 'xt' zur Augabe der Zahlen von "10..19" benutzt.


lang: de
desc:
        Ausgabe der betriebssystemabhängigen Zeilende. Unter Windows
        ist das CR-LF unter Linux ist dies LF


lang: de
desc:
        Bricht die Ausführung des Wortes ab wenn "n" gleich 0 
        ("n" == 0) ist. Der Test auf 0 entfernt den TOS.        
        
        Beispiel:
        
        ok> : 0;drop-test 0;drop ." Auf dem TOS war keine 0 !" ;

        ok> 1 2 3 0;drop-test
        Auf dem TOS war keine 0 !
        ok> .s
        (2) 1 2
        ok>
        
        ok> 1 2 0 0;drop-test

        ok> .s
        (2) 1 2
        ok>        


lang: de
desc:
        Beendet ein anonymes Codefragment, das gestartet wurde mit "}}" 
        und führt es unmittelbar aus.       


lang: de
desc:
	Das deferred Wort wird gerufen bei auftreten von "Ctrl+C"

	Es sollte ein Flag gesetzt werden wenn ein laufender Prozess
	unterbrochen werden sollte.

	Das normale Verhalten ist die Ausgabe von "Break" und der 
	Aufruf von "bye" 


lang: de
desc:
	Numerisches äquivalent des Strings "revaver". Zur Zeit wird
	er repräsentiert durch den hexadezimalen Wert
		00MMmmpp

	Für Reva 6.1.5 wäre das:
		00060105, wobei
		"MM" das Hauptrelease, hier "6"
		"mm" das Nebenrelease, hier "1"
		"pp" das aktuelle Release, hier "5"			
	


lang: de
desc:
	Tauscht die Werte unter den Adressen "a" und "b". Grundsätzlich
	das gleiche wie:	

	   2dup @ swap @    | a b b' a'
	   rot !	    | a b'
	   swap !
	


lang: de
desc:
	Parst das nächste Wort von der Eingabe und gibt den xt 
	zurück. Ist das Wort nicht gültig oder wird es nicht
	in der Suchordnung gefunden wird eine Exception geworfen.


lang: de
desc:
	Überprüft das Wort (a,n) ob es ein Repräsentant von "class-xt" 
	ist. Wenn ja gibt es den xt des Wortes zurück ansonsten wird
	eine Exception geworfen.


lang: de
desc:
	Gibt den Inhalt der Zelle zurück auf den die Adresse
	a verweißt. Achtung bei Zugriffen auf ungültige 
	Adressen.


lang: de
desc:
	Setzt den String 'a','n' in einen "counted-string" an der Stelle
	'here' und richtet 'here' neu ein.


lang: de
desc:
	Reserviert Speicher durch verschieben von "here" um "n" Bytes. Kann 
	auch benutzt werden um den Speicher zu deallokieren durch Eingabe 
	einer negativen Zahl


lang: de
desc:
	Konvertiert ein Zeichen 'c' in einen Kleinbuchstaben.
	Bemerkung: Dies ist eine einfache ANSI Transformation und 
	funktioniert z.b. nicht korrekt mit akzentuierten Zeichen.


lang: de
desc:
	Inline Kommentar, oft benutzt zur Dokumentation von Stack-Effekten
	eines Wortes. Parst den Text bis zum nächsten ")"  Zeichen und entfernt
	ihn. 


lang: de
desc:
	Zeigt alle Wörter aus dem obersten Kontext der Suchreichenfolge.
	Falls <opt> angegeben wurde, werden alle Wörter angezeigt die den 
	Teilstring enthalten.


lang: de
desc:
	Zeilenkommentar. Das gleiche wie "|". Wird benutzt 
	Reva Batch-Files unter Windows zu erstellen.	 


lang: de
desc:
	Schaut nach dem Wort "<name>" im Verzeichnis und gibt den xt des 
	Wortes zurück. Sollte das Wort nicht existieren, wird 0 gibt
	zurück.


lang: de
desc:
        Schaut nach einem Wort im Wortverzeichnis und gibt falls vorhanden
        den xt des Wortes auf den Stack zurück. Ist kein Eintrag vorhanden
        wird der gesuchte Wortname und 0 auf den Stack geschoben.         
        
        


lang: de
desc:
        Bricht die Ausführung des Wortes ab wenn "n" gleich 0 
        ("n" == 0) ist und die 0 wird vom TOS entfernt. Ist
        "n" ungleich 0 ("n" != 0) wird der TOS nicht verändert.              


lang: de
desc:
        Bricht die Ausführung des Wortes ab wenn "n" gleich 0 ("n" == 0) ist
        Der TOS wird dabei nicht verändert.


lang: de
desc:
	Erstellt eine Variable "Value" mit dem Namen "Name" und dem Wert 
	"n". Ein "value" gibt wie "variable" die Möglichkeit einen Wert 
	zu speichern. Ausgelesen wird ein "value" aber wie eine Konstante. 
	Also mit einfacher Angabe des Namens "Name". Einer Variable die 
	mit "value" deklariert wurde, wird mit "to" ein Wert zu gewiesen.
	
	
	Beispiel:
	        12 value joe
	        
	        joe 12 =if ... then
	        
	        34 to joe


lang: de
desc:
        Wird mit [THEN] und [ELSE] für bedingte Übersetzung benutzt.
        Das Verhalten ist identisch mit if/else/then. Nur der übersetzte 
        Code wird ins Vokabular geschrieben. Seiteneffekte sind daher 
        ausgeschlossen. 
        kompilieren abhängig von Bedingungen. Nur der co


lang: de
desc:
        Versteckt das Wort im Wortverzeichnis sodass es nicht mehr im 
        Suchpfad liegt.
        


lang: de
desc:
	Dies ist eine optionale Umgebungsvariable. Ist sie gesetzt, dann
	muss die den vollen Pfad zu den privaten Dateien des Benutzer 
	enthalten. ähnlich wie "libdir". Der Pfad wir beendet je nach OS 
	mit / oder \.


lang: de
desc:
	Lokalisiert die Datei "<name>" im Verzeichnis der Benutzerbibliothek
	oder im Verzeichnis der Standardbibliothek. Wenn die Datei noch nicht
	eingebunden wurde, wird sie nun eingebunden.


lang: de
desc:
	Vollständiger Pfad zum "lib" Verzeichnis. Der Ort an dem die Reva
	Bibliotheken gespeichert sind. "libdir" wird von "needs"  benutzt
	um die Bibliotheken zu finden.


lang: de
desc:
	Legt das Verzeichnis von "<name>" auf den TOS, oder wirft eine -1 Ausnahme
	und gibt "... is not a word" ( "... ist kein Wort" ) aus falls das Wort
	nicht existiert.


lang: de
desc:
	Gibt "true" zurück falls das Wort definiert ist, andernfalls "false".
	Ist vorgesehen um  Aktionen, abhängig von der Laufzeitumgebung, auszuführen.


lang: de
desc:
	ODER Verknüpfung der ersten beiden Stackeinträge. 
	Funktioniert wie der Bit-Operator in C: a | b
	


lang: de
desc:
	Exclusiv-ODER Verknüpfung der ersten beiden Stackeinträge. 
	Funktioniert wie der Bit-Operator in C: a ^ b
	


lang: de
desc:
	Gibt den vollständigen Pfad des laufenden Programms zurück.
	Einschließlich den Pfadtrennzeichen.
	


lang: de
desc:
	Wird mit "func:" benutzt um der Funktion einen neuen Namen zu geben.
	
	Beispiel: 
		1 func: Sleep as rest
	


lang: de
desc:
                Gibt den Namen des Betriebssystem zurück.
                
                Beispiel:
                
                ok> osname type
                Windows
                ok>
                


lang: de
desc:
        Gibt den Wert einer Umgebungsvariable zurück.
        
        Beispiel:
        " PATH" getenv
        
        Anmerkung: Das Wort ist unabhängig von der Groß-und Kleinschreibung unter
        Windows aber abhängig unter Linux.  


lang: de
desc:
        Setzt die Umgebungsvariable (a1,n1) auf den Wert (a2,n2). 
        
        Beispiel:
        " PATH" " was auch immmer" setenv


lang: de
desc:
        Führe das nächste Wort aus wenn "a" kleiner "b" ist.
        
        Beispiel:
        
        ok> : test 4 5 <if ." Hallo" then ;

        ok> test
        Hallo
        ok> : test2 5 4  <if ." Hallo" then ;

        ok> test2

        ok>
        


lang: de
desc:
        Zeigt eine Liste der aktuell eingebundenen Bibliotheken an. Ist die 
        Bibliothek nocht nicht geladen weil sie z.b. noch nicht benutzt wird,
        ist das Handle 0. Das Wort "::" zeigt an, dass man auf die Bibliothek
        keinen direkten Zugriff hat.


lang: de
desc:
        Erzeugt ein "deferred" Wort "<name>". Dieses Wort hat am Anfang
        noch keine Funktion und erhält erst durch eine Zuweisung mit "is" 
        eine sinnvolle Funktion.


lang: de
desc:
        Das gleiche wie "0 do" aber effizienter. Iteriert von 0 bis 'max'-1
        
        Beispiel:
        
        ok> : 10- 10 0do ." -" loop cr ;

        ok> 10-
        ----------------


lang: de
desc:
        Startet einen "inline callback". Dabei handelt es sich um
        eine Sequenz von Wörter die mit "}" beendet wurden und 
        von anderen Wörter aufgerufen werden kann.
        
        Anmerkung: Verwendet werden soll "cb{" und "}cb"
        
        Beispiel
        


lang: de
desc:
        Ähnlich wie "0;", aber das zweite Element auf dem Stack wird auch 
        noch entfernt falls "n" gleich 0 ("n" == 0) ist.
        
        Beispiel: 
        
        ok> : 0drop;-test 0drop; ." Wort wurde regulär beendet" ;

        ok> 1 2 3 0drop;-test
        Wort wurde regulär beendet
        ok> .s
        (3) 1 2 3
        
        ok> 1 2 0 0drop;-test
        
        ok> .s
        (1) 1
        ok>


lang: de
desc:
        Legt den ASCII Wert der gedrückten Taste auf den Stack. 
        "key" wartet bis CR gedrückt wird.
        
        Beispiel:
         
        ok> key
        a

        ok>
        ok> .s
        (1) -159
        ok> emit
        a
        ok> 
        
        


lang: de
desc:
        Gibt das Zeichen aus mit dem ASCII Wert "c".
        
        Beispiel:
        
        ok> 65 emit
        A              


lang: de
desc:
        Gibt einen String auf das Ausgabemedium aus. Die Standardausgabe
        ist der Bildschirm.
        Achtung: "type" gibt keine Strings aus die größer 32k sind.
        
        Beispiel:
        
        ok> " Hallo Ron" .s type
        (2) 1127705 9 Hallo Ron
        ok>


lang: de
desc:
        Liest die Datei mit dem gegegbenen Namen auf dem Stack und legt
        die gesamte Datei als String auf den Stack.  Der Speicher ist 
        reserviert und muss wieder freigegeben werden. Schlägt "slurp" fehl
        steht 0 0 auf dem Stack.


lang: de
desc:
        Erstellt neue Wörterbucheinträge aus den mit Leerzeichen getrennten 
        Teilstrings auf dem Stack. 


lang: de
desc:
        Variable die angibt ob das Wörterbuch mit gespeichert wird. Ist
        die Variable mit einem Wert ungleich 0 belegt, dann wird eine
        Turnkey-Anwendung ohne Wörterbuch erzeugt.


lang: de
desc:
        Konvertiert einen String (Adresse, Byteanzahl) in die 
        Form (Endadresse, Startadresse)


lang: de
desc:
    Dekrementiert das zweite Element auf dem Stack. Ähnlich wie "1-" 
    aber viel effezienter als "swap  1- swap" 
    
    Beispiel:
    
    ok> 2 3 .s
    (2) 2 3
    ok> _1+ .s
    (2) 3 3
    


lang: de
desc:
        Wörter die aufgerufen werden falls das Wörterbuch voll ist.
        Das normale Verhalten von Reva ist die Ausgabe einer Meldung
        und sein beenden.


