! | ( n a -- )
Store the cell "n" at address "a"
see also: @
|
" | ( <str>" -- a n )
Create a string by parsing input up to the next double-quote. If
compiling, the string data are put in the heap and the runtime
code will push the address and length of the string on the stack.
If interpreting, the address and length will be put on the stack,
and the string will be allocated from a buffer for transient
strings. In either case, one may put a double quote inside a
string by prefacing it with the '\' (backslash) character:
"\"Hi!\", said Mary"
see also: strings
|
"" | ( -- )
see (") |
#! | ( -- )
Same as "|" - a comment to end-of-line. This permits Linux-scripts to
indicate via a line like:
#! /bin/reva
that they should be interpreted by Reva.
see also: @rem
|
' | ( <name> -- xt | a n 0 )
Look up the word "<name>" in the dictionary. Returns the xt of
the word in question, or the name and 0 on TOS.
see also: '' find (find)
|
'' | ( <name> -- dict | a n 0 )
Similar to "'", but returns the dictionary pointer instead of the xt
see also: ' find (find)
|
'alias | ( xt -- )
Implementation of "alias" class.
|
'forth | ( xt -- )
Implementation of the "forth" class. |
'inline | ( xt -- )
Implementation of the "inline" class. |
'macro | ( xt -- )
Implementation of the "macro" class. |
'notail | ( xt -- )
Implementation of the "notail" class. |
( | ( <text> -- )
Inline comment, most often used to document the stack effects of a word.
Parses until the next ")" character and drops the parsed text
see also: |
|
(") | ( -- )
Compiles the string "a,n" into the 'compiled string area' and
compiles code to push that string on the stack, in 'here'. The
word "" is used by " in interpret mode to place the string in one
of several rotating buffers. |
(-lib) | ( -- )
You want to use "lib" instead.
OS code to unload the library handle (which had been created with
(lib))
see also: lib func
|
(.) | ( n -- a n )
Converts a number to a string using the current "base", without
trailing space. Used by "."
NOTE: The string returned should be saved elsewhere if you won't
use it immediately!
see also: . (.r) .r (p.r) base
|
(.r) | ( x y -- a n )
Converts the number "x" into a string of width "y", using
"padchar" to fill in on the left if necessary. Uses the current
"base" for numeric conversion.
NOTE: The string returned should be saved elsewhere if you won't
use it immediately.
NOTE: Does *not* truncate the outputted number to the width
specified.
see also: .r . (.) (p.r) base
|
(argv) | ( -- )
Pointer to the raw 'argv' data. You probably want 'argv' instead.
see also: argv argc
|
(bye) | ( n -- )
Leave Reva with errorcode "n"
see also: bye
|
(call) | ( func n -- )
Internal word used by 'func' - you probably don't want to use it.
Calls 'func', pushing N params from the Forth stack to the CPU stack.
Cleans up the CPU stack afterwards, and leaves the function result on
TOS (garbage value if a "void" function return).
see also: func lib
|
(create) | ( a n -- )
Same as 'create' but operates on a passed-in string
see also: create header
|
(else) | ( -- )
You don't want to use this word; it's internal to the
various conditionals.
see also: conditionals
|
(env) | ( -- )
Pointer to environment strings array. You probably want "getenv"
see also: getenv
|
(find) | ( a n -- )
Same as "find" but returns the dictionary pointer for the word.
see also: ' '' find
|
(func) | ( a n lib -- handle )
Internal word used by 'func' - you probably don't want to use it.
Returns a handle to the named function from the library
see also: func lib
|
(header) | ( a n -- )
Create a new entry in the dictionary named for the passed-in string.
see also: header
|
(here) | ( -- a )
Returns a pointer to the variable holding the value of 'here'
see also: here
|
(if | ( -- )
You don't want to use this word; it's internal to the
various conditionals.
see also: conditionals |
(include) | ( a n -- )
Same as 'include', but reads the string passed as a file name.
see also: include
|
(lib) | ( -- )
You want to use "lib" instead.
OS code to load the named library. Returns a handle.
see also: lib func
|
(loop) | ( -- )
You don't want this word; see "loop". But since you asked, it
compiles either a short or long jump to the origin of the loop, as
appropriate.
see also: flow-control |
(p.r) | ( n m c -- a n )
Prints the value "n" to a string "m" wide, left-padded with character
"c". The string returned should be saved elsewhere if you won't use it
immediately.
see also: (.r) (.) . .r
|
(s^) | ( -- )
internal: used to implement "
|
(save) | ( -- )
Save the state of the program to the file named.
see also: program-control
|
(seek) | ( whence offset handle -- )
Used to implement "seek"; this word is similar to the Unix "fseek"
word, and has the same semantics. "whence" is one of:
0 - SEEK_SET, from the beginning of the file
1 - SEEK_CUR, relative to the current position, or
2 - SEEK_END, from the end of the file
see also: seek tell file-io
|
(while) | ( -- )
You don't want this word; see "while" and "(loop)"
see also: flow-control
|
* | ( a b -- n )
Multiply top two items (signed): n=a*b
see also: / */ mod /mod + - << >> |
*/ | ( a b c -- n )
Scaled multiplication operator (signed): n=(a*b)/c.
This uses the CPU's internal accuracy, and so does not have
problems of 32-bit overflow errors which using * and / separately
might have.
see also: / * mod /mod + - << >>
|
+ | ( a b -- n )
Add top two items: n=a+b
see also: - / *
|
+! | ( n a -- )
Add "n" to cell at location "a". Same as effect as:
swap over @ + swap !
|
++ | ( a -- )
Increment the cell at location "a".
see also: -- |
+lplace | ( n a lstr -- )
Same as "+place" but for "long" strings over 255 characters
see also: lplace c+lplace strings |
+place | ( n a cstr -- )
Append the string to a cstring, which is up to 255 characters.
see also: place c+place strings |
, | ( n -- )
Put one cell at "here", and increment here by
the number of bytes put there.
see also: 1, 2, 3,
|
- | ( a b -- n )
Subtract b from a: n=a-b
see also: + / *
|
-- | ( a -- )
Decrement the cell at location "a".
see also: ++
|
-chop | ( a n c -- a1 n1)
Same as chop but scans from the end of the string
see also: chop strings
|
-rot | ( a b c -- c a b )
Rotate top three items counter-clockwise
see also: stack-ops
|
. | ( n -- )
Prints a number followed by a space using the default base
see also: base .r (.) (.r) (p.r)
|
." | ( <str>" -- )
Types the string <str>. The same string definition rules apply as
for "
see also: strings
|
.2x | ( n -- )
Print low 8 bits of a number as 2 hex digits, regardless of "base"
see also: .x
|
.funcs | ( -- )
Display list of external functions currently defined. The handle
shown is 0 if the function has not been loaded yet. The word "::"
indicates the func is not directly accessible.
see also: .libs
|
.libs | ( -- )
Display list of libraries currently defined. The handle shown is
0 if the library has not been loaded yet. The word "::" indicates
the lib is not directly accessible.
see also: .funcs
|
.r | ( x y -- )
Prints number 'x' in a field 'y' wide. Uses '(.r)' to format the number
and appends a space afterwards, like '.'
see also: (.r) . (.) (p.r)
|
.rs | ( -- )
Displays (up to) top ten return-stack items.
see also: .s stack-ops
|
.s | ( -- )
Displays (up to) top ten stack items.
see also: .rs stack-ops
|
.ver | ( -- )
Display the version, including OS
|
.x | ( n -- )
Print a number as 8 hex digits, regardless of "base"
see also: .2x |
/ | ( a b -- d )
Divide a by b (signed): n=a/b
see also: * */ mod /mod + - << >>
|
/char | ( a n c -- a1 n1 )
Find character 'c' in string. Returns string beginning with the
character found, or 0 0.
see also: \char strings |
/mod | ( a b -- rem quo )
Divide "a" by "b", place remainder and quotient on stack
see also: / mod
|
00; | ( n -- n | exit in n=0 )
Exit a word if "n" == 0, but does NOT pop TOS.
Does not change the stack it TOS not 0
see also: 0;
|
0; | ( n -- n | exit and drop TOS if n=0 )
Exit a word if "n" == 0, and also pop the stack in that case.
Does not change the stack it TOS not 0
see also: 00; |
0if | ( n -- )
Execute condition if 'n' is zero
see also: conditionals
|
0term | ( a n -- a n )
Forces the string "a,n" to be NUL terminated.
see also: strings
|
1+ | ( n -- n )
Increment TOS: ++n
see also: 1- ++ -- |
1, | ( n -- )
Put one byte at "here", and increment here by
the number of bytes put there.
see also: , 2, 3,
|
1- | ( n -- n )
Decrement TOS: --n
see also: 1+ -- ++
|
2! | ( d 2var -- )
Stores a double (8 bytes) "d" to a memory address "2var".
see also: 2@, 2variable
|
2* | ( n -- 2*n )
Multiply TOS by 2
see also: 2/
|
2, | ( n -- )
Put two bytes at "here", and increment here by
the number of bytes put there.
see also: 1, , 3,
|
2/ | ( n -- 2*n )
Divide TOS by 2
see also: 2*
|
2@ | ( 2var -- d )
Gets a double (8 bytes) from address "2var".
see also: 2!, 2variable
|
2cell+ | ( n -- n )
Advance "n" by two cells (8 bytes)
see also: cell+ |
2drop | ( a b -- )
Drop top two cells
see also: stack-ops
|
2dup | ( a b -- a b a b )
Duplicate top two cells
see also: stack-ops
|
2over | ( a b c d -- a b c d a b )
Copy 3rd and 4th stack items over TOS
see also: stack-ops
|
2swap | ( a b c d -- c d a b )
Swap top doubles
see also: stack-ops
|
2variable | ( <name> -- )
Creates a new variable "<name>" which can hold a double.
see also: 2@, 2!
|
3, | ( n -- )
Put three bytes at "here", and increment here by
the number of bytes put there.
see also: 1, 2, ,
|
3cell+ | ( n -- n )
Advance "n" by three cells (12 bytes)
see also: cell+ |
3dup | ( a b c -- a b c a b c )
Similar to 2dup. This has been used often enough to justify
adding it to the core.
see also: 2dup stack-ops
|
4cell+ | ( n -- n )
Advance "n" by four cells (16 bytes)
see also: cell+ |
: | ( <name> -- )
Create a new word called "<name>". Everything between this and
the corresponding ";" are executed when "<name>" is invoked.
see also: ; ::
|
:: | ( -- xt )
Create a new word without a dictionary entry. "xt" is the pointer
to the compiled code for the word. This is mainly useful for
providing an anonymous function to use as an implmentation of a
defer-ed word.
see also: : ;
|
; | ( -- )
End a word definition started with ":". Compiles a 'return' into
the code space. If the last thing compiled was a call to a word,
optimizes it to a 'jump' to that word - thus implementing
"tail-recursion optimization". Also signals that we've stopped
compiling.
see also: : :: ;; notail
|
;; | ( -- )
Exit the current word without signalling that compilation has stopped.
see also: ; : ::
|
< | ( m n -- flag)
Returns 'true' or 'false' depending on the test "m<n" using
signed-math.
Example:
2 3 < .
prints: -1
2 -3 < .
prints: 0
see also: > = |
<< | ( a b -- n )
Shift a left b bits: n=a*2^b
see also: >> / * + -
|
<>if | ( a b -- )
Execute condition if "a" <> "b" (not-equal)
see also: conditionals
|
<if | ( a b -- )
Execute condition if "a" < "b"
see also: conditionals |
= | ( m n -- flag)
Returns 'true' or 'false' depending on the test "m=n" using
signed-math.
see also: < >
|
=if | ( a b -- )
Execute condition if "a" = "b"
see also: conditionals |
> | ( m n -- flag)
Returns 'true' or 'false' depending on the test "m>n" using
signed-math.
see also: < = |
>> | ( a b -- n )
Shift a right b bits: n=a/2^b
see also: << / * + -
|
>class | ( dict -- a )
Return the class field pointer from a dictionary pointer.
see also: >name >size >xt
|
>digit | ( n -- c )
Convert digit to its ASCII representation
Example:
10 >digit emit
shows 'A'
see also: digit>
|
>if | ( a b -- )
Execute condition if "a" > "b"
see also: conditionals |
>in | ( -- tin )
Variable holding pointer to current location in tib.
see also: src
|
>lit | ( xt -- xt' )
Takes the xt of a 'literal', and returns the value it points to
|
>lz | ( a n a2 -- a2 m )
Compress the buffer "a,n" into the buffer "a2". Returns "a2,m",
where 'm' is the compressed length. The buffer 'a2' must be big
enough to contain 'lzmax' characters - e.g. "n lzmax allocate"
will allocate a buffer big enough to hold the worst-case size of
compressing 'n' bytes. Used by the turnkey code to compress the
dictionary and code data.
see also: lz> lzmax
|
>name | ( dict -- a )
Return the name field pointer from a dictionary pointer.
see also: >class >size >xt
|
>r | ( n -- r:n )
Puts top stack item on return stack
see also: r-stack-ops
|
>rr | ( n -- )
Puts "n" under the top of the return-stack. "tuck" for the
return-stack.
see also: r-stack-ops
|
>single | ( a n -- m true | a n false )
Convert string to a number. TOS will be true or false; true if
the conversion succeeded - then 'm' will be the numeric value;
false if it failed, then 'a n' is the original string.
|
>size | ( dict -- a )
Return the size field pointer from a dictionary pointer.
see also: >name >class >xt
|
>xt | ( dict -- a )
Return the xt field pointer from a dictionary pointer.
see also: >name >class >size
|
?do | ( max start -- )
ANS-compatible '?do'. Iterates from 'start' to 'max'-1. If 'max'
and 'start' are equal, will not do any iterations.
see also: flow-control
| || |
?dup | ( n -- n n )
Duplicates TOS if it's not zero.
see also: stack-ops
|
@ | ( a -- n )
Returns the cell pointed to by the address in a
Be careful not to pass an invalid address to it!
see also: !
|
@execute | ( a -- )
Same as "@ execute" but more efficient
see also: execute
|
@rem | ( -- )
Used for writing Reva "batch" files under Windows
see also: #!
|
[ | ( -- )
Stop compiling and switch to the interpreter
see also: ]
|
['] | ( <name> -- )
Compile xt of "<name>"
see also: ' compile
|
[DEFINED] | ( <name> -- flag )
Returns "true" if the word has been defined, "false" otherwise.
Intended to be used to take some action based upon runtime
environmental issues.
see also: preprocessor
|
[ELSE] | ( -- )
Used with [IF] and [THEN] for conditional compilation
see also: [IF] [THEN] preprocessor
|
[IF] | ( n -- )
Used with [THEN] and [ELSE] for conditional compilation. Exactly
analagous to if/else/then, except that this allows one to compile
based on a condition. The code in the branch not taken is not
compiled and therefore doesn't contribute to the dictionary or
have any side-effects. Similar to "#if ... #endif" in C
NOTE: one may NOT nest [IF]...[THEN] blocks!
see also: [THEN] [ELSE] preprocessor
|
[THEN] | ( -- )
Used with [IF] and [ELSE] for conditional compilation
see also: [IF] [ELSE] preprocessor
|
\char | ( a n c -- a1 n1 )
Same as /char but scans from the end of the string
see also: /char strings
|
] | ( -- )
Return to the compiler
see also: [
|
abs | ( n -- n )
Return absolute value of top stack item.
|
accept | ( a n -- m )
Accepts at most 'n' characters into the buffer at 'a'; returns 'm'
the number of characters read. The ESC key cancels the accept and
returns '0', CR key ends input before 'n' characters have been
read.
see also: console-io
|
again | ( -- )
Return to top of loop started by "repeat"
see also: flow-control
|
alg/enum |
This library implements a simple C-style "enum", allowing you to
quickly create a bunch of constants with increasing values. It
defines:
enum: ( start# -- )
Begins the enumeration from 'start#'.
enum; ( -- )
Terminates the enumeration.
Example:
1 enum: ONE TWO THREE enum;
|
alg/list |
Simple singly-linked list implementation. The following words are
defined:
(list-compare) - variable which holds the 'comparison'
function for this list.
list ( <name> -- )
Creates a new 'list' object
list-append ( list ptr -- )
Appends 'ptr' to the list
list-prepend ( list ptr -- )
Prepends 'ptr' to the list
list-insert ( list ptr -- )
Inserts 'ptr' into the list, using (list-compare) to make
an ordered list
list-find ( list ptr -- closest | list )
Looks for the closest match to 'ptr' (based on
(list-compare)) and returns it, or 'list' if all items in
the list are smaller than 'ptr'
list-do ( list xt -- )
Iterate over list and execute 'xt' for each item. The
'xt' is called with the item on TOS
|
alg/stack |
Arbitrary sized stack. Words are:
stack: ( n <name> -- )
Creates a 'stack' called "<name>", which can hold "n"
cells worth of data.
push ( x stack -- )
Pushes 'x' onto the named stack
pop ( stack -- x )
Pops "x" off the named stack
peek ( stack -- x )
Gets TOS from the named stack, but does not pop it.
|
alg/structs |
Allows "C" style structures.
struct: ( <name> -- xx offset )
Creates a new "struct" called "<name>". Must end with "struct;"
struct; ( xx offset -- )
Terminates a "struct", and sets its "size" field
sizeof ( <name> -- n )
Gets the size of the named structure
field: ( ofs size <name> -- ofs' )
Creates arbitrarily sized field named "<name>".
byte:
short:
long: ( <name> -- ofs' )
Create 1, 2 or 4-byte fields
Example:
struct: mystruct
byte: id
long: hash-code
3 field: tri-byte
struct;
mystruct m1
m1 id + c@ | the id field
m1 tri-byte + @ $ffffff and | the tri-byte field
... etc....
|
alias | ( xt <new> -- )
Create an alias for xt, so saying <new> results in the same.
see also: alias:
|
alias: | ( oldname newname -- )
Create alias 'newname' for the word 'oldname', keeping the proper
class semantics of the old word.
see also: alias
|
align | ( -- )
Align "here" to the next four-byte boundary.
see also: aligned
|
aligned | ( a -- a )
Align the address on TOS to the next four-byte boundary.
see also: align
|
allocate | ( n -- addr )
Allocates memory from the OS.
see also: free, resize
|
allot | ( n -- )
Allocate memory by moving "here" by "n" bytes. Can also be used
for deallocation from 'here' if given a negative number.
|
and | ( a b -- n )
AND top two items, like C bitwise operator: a & b
see also: or not xor
|
ansi |
This library implements a partial and quite incomplete ANS
compatibility layer for Reva. I am not sure if I will put more
effort into maintaining it, as I think it is more effort than it
is worth.
Invoking Reva with the "-a" command-line switch loads this
library.
|
appdir | ( -- a n )
Return the full path to the running program, including trailing
path-separator character
see also: appname libdir pathsep needs
|
appname | ( -- a )
Return a NUL terminated string containing the fully qualified name
of the actual program file this application started from.
see also: appdir
|
appstart | ( -- )
Similar to "main" in C, this is the starting point for the
application itself. Called after 'hello'
see also: hello onstartup onexit
|
argc | ( -- n )
One more than the number of command-line arguments passed to Reva.
So if no arguments were passed, argc is 1
see also: argv
|
argc# | ( -- a )
Internal word used by the startup code to keep track of the current
command-line argument being processed.
|
argcend | ( -- a )
Address of variable holding the index of last 'argv' processed.
see also: argc# argc argv
|
argv | ( n -- addr len )
Get command-line argument "n". The number is in the range 0.."argc". The
first argument, "0 argv" is the name of the program; 1 is the index of the
first user-supplied argument, etc.
If you pass a value that is out of range, it will be clamped to
the proper range. So "-1 argv" is the same as "0 argv"
see also: argc
|
asciiz, | ( a n -- )
Puts the string 'a','n' into a counted-string at 'here' and
adjusts 'here'.
see also: asciizl, |
asciizl, | ( a n -- )
Same as 'asciiz,' but puts a long-counted-string at 'here'.
see also: asciiz,
|
asm |
This library implements:
asm{ ( <asmcode>} -- ) MACRO
This lets you inline assembly language code directly instead of
hard-coding opcodes and poking. Requires that FASM be installed
and available on your system, and will slow down Reva a little
while compiling asm{ blocks.
Example:
: incr asm{ inc eax } ;
Note: lines between "asm{" and "}" MUST be in valid FASM syntax,
one statement per line!
|
back | ( n -- )
Generates code to jump back to the address specified on TOS
see also: flow-control
|
base | ( -- a )
Returns a pointer to a variable containing the current base for
number conversion.
Example:
6 2 base ! .
prints "6" in binary, "110"
see also: . decimal octal hex binary
|
between | ( a b c -- flag )
Returns true if "a">="b" and "a"<="c"
|
binary | ( -- )
Change base to binary (base 2)
see also: hex octal decimal base
|
bye | ( -- )
Same as "0 (bye)"
see also: (bye)
|
c! | ( n a -- )
Store byte "n" at address "a"
see also: c@
|
c+lplace | ( c lstr -- )
Like c+place except for long-strings.
see also: lplace +lplace strings |
c+place | ( c cstr -- )
Append byte "c" to a cstring.
see also: place +place strings |
c@ | ( a -- n )
Return the byte stored at address "a"
see also: c!
|
catch | ( xt -- throwcode )
Execute "xt", catching any throw which may have occurred. If no
throw happened, 'throwcode' is zero - otherwise it's the value
'throw'n
throwcode of zero.
see also: throw
|
cb: | ( xt numparams stacksize <name> -- )
Create a new word whose xt can be used as a callback for a cdecl
function. It is crucial the numparams be correct, or the callback
will crash.
The "xt" is a normal Forth word, and can use any other Forth words
it needs - subject to the 'stacksize' (number of words available
for this callback to push) and subject to any environmental issues
regarding the platform you are running on.
see also: stdcb: |
cell+ | ( n -- n )
Advance "n" by one cell (4 bytes)
see also: cell- |
cell- | ( n -- n )
Diminish "n" by one cell (4 bytes)
see also: cell+
|
cells | ( n -- n )
Return number of bytes required by "n" cells
|
choice | ( xt n -- )
Puts "xt" in the most recent 'choices:' variable, where 'n' is the
value which will cause 'xt' to be executed when the 'choice:'
variable is executed.
see also: choices: default
|
choices: | ( <name> -- )
Creates a new 'choice' variable called '<name>'. This sets up a
sort of 'sparse array' decision tree. Use it like this:
choices: mychoices
' choice1 'a choice
' choice2 'b choice
' choice-default default
Then you use it like:
ekey mychoices
and the appropriate choice gets called.
see also: choice default
|
chop | ( a n c -- a1 n1 )
Scan forward in string "a,n" for character "c". Returns the string up to
the point where that character was found, or the original string if the
character was not found
see also: -chop strings |
classes |
Classes define the behavior of a word when executed by Reva. A
word's class is usually defined at the same time as the word is,
but it can be modified later if desired. The usual technique in
Reva is to define a series of words using the same class,
together; then switch back to the default 'forth' class:
inline
: in1 ... ;
: in2 ... ;
forth
see also: forth macro inline notail 'alias
|
cleanup | ( -- )
Deferred word which is called by the default 'bye'. Useful for closing
files etc.
|
cleanup-libs | ( -- )
Routine called at exit; unloads any libraries which were loaded
via (lib) and ensures that it is safe to do a "save"
see also: atexit save func lib
|
close | ( fileid -- )
Close "fileid" previously opened with 'open/r' 'open/rw' or
'creat'.
see also: file-io |
cmp | ( a1 n1 a2 n2 -- n )
Compare two strings, lexicographically. 0 means equal. Useful for
sorting lists.
see also: cmpi strings
|
cmpi | ( a1 n1 a2 n2 -- n )
Save as 'cmp', but compares ignoring case, e.g. 'A' and 'a' are
equivalent.
see also: cmp strings
|
cold | ( -- )
Resets the Reva virtual-machine to 'startup' state
see also: program-control
|
compile | ( a -- )
Compiles a call to the address "a"
see also: back
|
compiling? | ( -- flag)
Returns a flag telling what the state of the interpreter/compiler
currently is. Useful inside 'macro' class words so they can
behave differently if necessary depending on whether invoked by
the interpreter or the compiler.
|
conditionals |
These are the conditional statements Reva provides:
if <>if 0if <if >if =if else then
|
console-io |
The following console I/O words are available in Reva:
cr space emit key key? ekey type accept spaces
|
constant | ( n -- )
Create a constant with the value "n"
see also: variable value |
count | ( cstr -- a n )
Converts a counted-string to an address-count pair.
see also: place strings |
cr | ( -- )
Output a CR character (move to next line)
see also: console-io |
creat | ( a n -- fileid )
Create a new file for reading and writing.
see also: file-io |
create | ( <name> -- )
Create a named entry <name> in the dictionary. Invoking this name
will cause the address of the item's private data area to be
pushed on the stack. In effect, operating much like 'variable'.
A 'created' item can be located using 'find' or '(find)', assuming
it was not hidden subsequently or created in a 'loc:' block or in
a different 'vocab:'
see also: (create) does> header |
crypt/md5 |
MD5 hash algorithm:
md5 ( a n -- a' n' )
Given an input buffer, returns the string with the 'MD5'
hash.
|
crypt/rc4 |
RC4 symmetric encryption
rc4setup ( a n -- )
Sets up the encryption box to use the password given.
rc4 ( a n -- )
Encrypt the passed-in buffer in-place
|
d0 | ( -- a )
Variable holding value of start of dict space (where dictionary
starts)
see also: h0 s0 str0 rp0 |
date/calendar |
Basic calendar functions. Too many words to document here, look
in the file itself.
|
date/church |
Ecclesiastical calendar.
|
date/hebrew |
Jewish traditional calendar.
|
date/holidays |
Some American holidays.
|
date/islam |
Islamic traditional calendar.
|
date/iso |
ISO calendar
|
date/julian |
Julian calendar
|
date/sedra |
Weekly Torah portion
|
date/util |
Various calendar utility words
|
db/sqlite |
Interface to the SQLite library
sql_open ( a n -- handle )
Opens (or creates) the database named, and returns a
handle to it to be used with the other words
sql_close ( handle -- )
Close the database opened by sql_open
sql_exec ( handle a n -- )
Execute the SQL statement "a,n" on db "handle"
sql_exec_cb ( handle a n cb -- )
Same as 'sql_exec', but calls the passed-in callback for
each for each row of the result.
sql_version ( -- a n )
Gives the string corresponding to the SQLite library
version.
sql_result ( -- a )
Return address of variable containing the result of the
sql_exec...
|
debug/debugger |
A start at debugging words:
name ( xt -- a n ) Takes an 'xt' and returns the name of the
word it represents.
|
decimal | ( -- )
Change base to decimal (10)
see also: hex octal binary base
|
default | ( xt -- )
Makes 'xt' the default "choice" to be executed when nothing else
matches. The default "default" is to do nothing.
see also: choice choice:
|
default_class | ( -- n )
Pointer to a variable containing the class which new words will
use. |
defaulthelp |
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
|
defer | ( <name> -- )
Create a deferred word "<name>". Initially this word will do nothing.
Must be set to something more useful using "is". Deferred words
are useful if you want to change the action a word performs - for
example, a 'print' word which might display to the screen or print
on the printer.
They are also useful when you have to make a word available before
it is defined (called a 'forward reference' in other languages).
A further use is permitting words to be redefined by later users.
Reva for example has 'key' and 'type' (among others) implemented
as deferred words.
see also: defer! defer@ is
|
defer! | ( xt <name> -- )
Create a deferred word "<name>", setting initial value to xt.
see also: defer defer@ is
|
defer@ | ( xt -- xt' )
Given the xt of a deferred word, returns the current value the
word will execute.
see also: defer defer! is
|
delete | ( a n -- )
Delete the named file
see also: file-io |
depth | ( -- n )
Puts the stack depth on the top of the stack. This is the number of
cells currently on the stack.
NOTE: a negative value of 'depth' means the stack underflowed.
This is almost always indicative of a problem!
see also: rdepth stack-ops |
dict | ( a n -- dict )
Given a string, looks it up in the dictionary - just like
"find" does. Returns the dictionary pointer, rather than
the xt.
see also: '' find ' >xt >name >size >class
|
digit> | ( c -- n )
Convert ASCII to the corresponding digit
Example:
'9 digit> .
shows '9'
see also: >digit
|
do | ( max start -- )
ANS-compatible 'do'. Iterates from 'start' to 'max'-1.
see also: flow-control
|
dodoes | ( -- )
Used to implement "does>" |
does> | ( -- )
Change the runtime behavior of a "create"d word. The normal
runtime behavior of a "create"d word is to push the address of its
data area on TOS. "does>" appends whatever code is after it to
the default action.
Example:
: const create , does> @ ;
234 const x
12 const y
Executing 'x' will put '234' on TOS. 'y' will put '12' on TOS.
They do this because they are 'const's which as you can see from
the definition - stash away TOS in the private data area of the
word on word creation; and put that value on TOS when invoked.
see also: create
|
dolstr | ( -- )
internal: used to implement " |
dostr | ( -- )
internal: used to implement " |
dovar | ( -- a )
Returns the address of the code which handles 'variables'.
|
drop | ( a -- )
Drop the top stack item
see also: stack-ops
|
dump | ( a n -- )
Hex dump of the n bytes starting at a. This is a 'traditional'
hex dump.
|
dup | ( a -- a a )
Duplicate the top stack item
see also: stack-ops
|
ekey | ( -- c )
Returns the ASCII value of a keypress as soon as a key has been
pressed, including special keys.
see also: console-io
|
eleave | ( -- )
Quit the innermost do..loop at the end of the loop and continue
processing after the 'loop' word. Essentially the same as
modifying the loop counter so the loop doesn't repeat again.
see also: leave flow-control
|
else | ( -- )
Begin alternate clause of conditional, execute if conditional
false.
see also: conditionals
|
emit | ( c -- )
Print character corresponding to the ASCII value 'c'
see also: console-io
|
eval | ( a n -- )
Interpret the string as if it had been typed in at the console
see also: interp
|
execute | ( xt -- )
Execute the word whose code is at "xt"
see also: @execute
|
false | ( -- flag )
Puts logical 'false' (no bits set, 0) on TOS
see also: true and or xor not
|
file-io |
The file-io words supported by Reva are:
creat open/r open/rw read write fsize
seek tell rename delete stat mtime
|
fill | ( a c b -- )
Fill the memory at "a" with "c" copies of byte "b"
|
find | ( a n -- xt | a n 0 )
Look up a word in the dictionary. Returns the xt of the word in
question, or the name and 0 on TOS.
see also: (find) ' ''
|
finish | ( -- )
Stops the processing of command-line arguments
|
flow-control |
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
|
fnvhash | ( a n -- m)
Returns the FNV-1a hash of the string passed in.
|
forth | ( -- )
Sets the default class ("default_class") to be "'forth".
Subsequent words will be of the "forth" class (e.g. "normal" Forth
words)
see also: macro inline notail classes
|
free | ( a -- )
Free the memory address "a" which had been allocated with
"allocate". Return zero on success.
see also: allocate, resize
|
fsize | ( fileid -- n )
Given an open file handle, return the file size.
see also: file-io |
func | ( a n N <fname>-- )
Creates a word "<fname>" which encapsulates a call to the function
which is located in the most recently used 'lib'.
N is the number of parameters passed to the function, and must
match EXACTLY what the function expects, or it will crash.
It doesn't matter whether the called function is cdecl or stdcall.
Pass in the name of the function and the number of parameters. It
will look in the last 'lib' used or declared.
NOTE: throws THROW_BADFUNC when invoked but the function was not
loaded. This may happen if the library was a different version
than you expected, or if you misspelled the function name.
see also: lib throw-codes
|
g32 | ( -- n )
WINDOWS ONLY: Handle to GDI32 library
see also: u32 k32 lib func
|
getenv | ( a n -- a1 n1 )
Given an environment variable, returns the value of the variable. For
example: " PATH" getenv
NOTE: This word is case-insensitive on Windows, but case-sensitive
on Linux.
see also: (env)
|
getpid | ( -- n )
Get the current process id
|
h0 | ( -- a )
Variable holding value of start of code space (where "here"
starts)
see also: d0 s0 str0 rp0 |
header | ( <name> -- )
Create a named entry "<name>" in the dictionary.
see also: create (header) |
help | ( <name> -- )
Attempts to give help on the word named.
| META-topics: (not words) |
here | ( -- a )
Returns current value of "here", the end of currently allocated
dictionary space.
see also: (here) |
here, | ( a n -- )
Stores "n" bytes from address "a" to "here" and adjusts "here".
|
hex | ( -- )
Change base to hexadecimal (16)
see also: decimal binary octal base
|
hide | ( <name> -- )
Makes the named word no longer visible in dictionary searches.
Sort of an after-the-fact "loc:"
see also: loc: loc; reveal seal
|
hinst | ( -- n )
Return process instance handle
|
i | ( -- ix )
Current index of innermost "do" loop.
see also: flow-control |
if | ( flag -- )
Execute condition if 'flag' is true
see also: conditionals
|
if) | ( -- )
You don't want to use this word; it's internal to the
various conditionals.
see also: conditionals |
ignorecase |
This library changes the behavior of the 'find' family of words to
to a case-insensitive search. Reva by default is case-sensitive,
so "word" and "Word" are not the same. This library makes them
the same, at a cost of substantially decreasing interpretation
speed (if you have a fast machine you won't notice probably).
|
include | ( <name> -- )
Read in the file "<name>" and evaluate it. Silent on failure, but
'ioerr' will be non-zero.
see also: (include) needs ioerr |
inline | ( -- )
Sets the default class ("default_class") to be "'inline".
Subsequent words will be of the "inline" class - e.g, words whose
bodies are copied directly into the compiled code - rather than
the usual, which is to compile a call to the word's code
see also: forth macro notail classes
|
interp | ( -- )
Force the interpreter loop to start again
see also: eval program-control
|
invert | ( n -- n' )
Invert all bits in "n". Same as C "~" operator: n=~n
see also: not negate
|
ioerr | ( -- a )
The address of a variable containing the last "I/O error result",
which is zero for success.
see also: file-io |
is | ( xt <name> -- )
Sets the deferred word "<name>" to execute "xt" when invoked.
see also: defer defer@ defer!
|
j | ( -- ix )
Current index of enclosing "do" loop.
see also: flow-control |
k32 | ( -- n )
WINDOWS ONLY: Handle to KERNEL32 library
see also: g32 u32
|
key | ( -- c )
Returns the ASCII value of a keypress, but only returns when CR has been
pressed
see also: console-io |
key? | ( -- flag )
Returns 'true' if a character is waiting to be read from the
input.
see also: console-io
|
last | ( -- a )
Address of variable holding the address of the most recently
defined dictionary entry
see also: find
|
lastvoc | ( x y -- )
Used after a "voc:" word was executed, to return to the last vocabulary
see also: voc:
|
later | ( -- )
This is a unique flow-control word. What it does is return
immediately to the calling word, and when the calling word exits,
resumes after the 'later'.
Example:
: a ." in a " later ." later, dude!" ;
: b ." in b " a ." after a " ;
b
Prints:
in b in a after a later, dude!
see also: flow-control
|
lc | ( c -- c )
Converts the character 'c' to its lowercase equivalent. NOTE: this is
a simple ANSI transform, and does not work at all correctly for
accented characters (for example).
see also: strings
|
lcount | ( cstr -- a n )
Converts a long-counted-string (>255 chars) to an address-count
pair.
see also: lplace strings
|
leave | ( -- )
Quit the innermost do..loop immediately and continue processing
after the 'loop' word.
see also: eleave flow-control |
lib | ( a n <libname>-- )
Declares a word "<libname>" which encapulates a "dynamic library"
(DLL or SO). When it is declared, it becomes the default library
for new 'func' declarations. When executed, it also becomes the
default library but in addition, puts the handle of the loaded
library on TOS.
NOTE: throws THROW_BADLIB when invoked but the library was not
loaded. This may happen if the library doesn't exist on your
system or if you misspelled the library name.
see also: func throw-codes |
libc | ( -- n )
LINUX ONLY: Returns a "lib" handle for libc.
see also: lib func
|
libdir | ( -- a n )
Full path to "lib" directory, which is where the standard Reva
libraries are stored. The word "needs" uses this to find
libraries.
see also: appdir needs REVAUSERLIB
|
libraries |
The set of words built-in to Reva is impressive considering the
small size of the program. However, Reva also provides additional
words covering a variety of fields, ready for use. These extra
'libraries' are in the 'lib' subdirectory, and are currently:
ansi asm ignorecase
alg/enum alg/list alg/stack alg/structs
crypt/md5 crypt/rc4
date/calendar date/church date/hebrew date/holidays
date/islam date/iso date/julian date/sedra date/util
db/sqlite debug/debugger
math/doubles math/float
net/sockets
os/console os/exception os/registry os/shell
random/gm random/simple
string/justify string/misc string/soundex string/trim
string/regex string/iconv string/unicode
util/auxstack util/classes util/eachline util/many
util/misc util/tasks util/zlib
util/case util/locals
To use any of them, use 'needs'. For example:
needs date/calendar
For help on what they do, just ask help:
help date/calendar
see also: needs
|
literal | ( n -- )
Compile the top stack item into the current word, as a literal.
see also: literal, compile
|
literal, | ( n -- )
Same as "literal" but operates at run-time.
see also: literal compile
|
loc: | ( -- )
Begins a 'local definitions' list
Anything defined between loc: and loc; is "local" and not visible in the
dictionary unless specifically exposed.
see also: loc; reveal hide seal |
loc; | ( -- )
Ends a 'local definitions' list.
see also: loc: reveal hide seal |
loop | ( -- )
If 'i' is less than the top bound for the current "do", return to
the top of the do..loop and increment 'i'; otherwise, fall out of
the do..loop
see also: flow-control
|
lplace | ( a n lstr -- )
Same as "place" but for long strings over 255 characters.
see also: lcount +lplace c+lplace strings
|
lz> | ( a n a2 -- a2 n )
Decompress the (previously compressed) buffer "a,n" into buffer
"a2,n". The 'n' is the uncompressed size of the buffer - so you
need to know this when you call the "lz>" word!
see also: >lz lzmax
|
lzmax | ( n -- m )
Returns the maximum possible size required to compress a buffer of
'n' bytes.
see also: >lz lz>
|
macro | ( -- )
Sets the default class ("default_class") to be "'macro".
Subsequent words will be of the "macro" class - e.g, words which
are executed as soon as they are interpreted (like IMMEDIATE in
ANS)
see also: forth inline notail classes
|
mark | ( <name> -- )
Creates a word which when executed, will revert the system to the
state it had before that word was created. This is very useful
when you want to "play around" with things and remove their
side-effects.
|
math/doubles |
Implementation of double (two-cell) words:
s>d ( n -- d ) Sign-extend the cell 'n' to a double 'd'
d+ ( d1 d2 -- d3) Adds "d1" and "d2" to make "d3"
d- ( d1 d2 -- d3) Subtracts "d2" from "d1" to make "d3"
m+ ( d1 n -- d2 ) Adds the cell 'n' to the double 'd1' to make
the double 'd2'
d= ( d1 d2 -- flag ) Compares the two doubles and returns a flag
dnegate ( d1 -- -d1 ) Changes the sign of 'd1'
dabs ( d1 -- d1 ) Returns the absolute value of 'd1'
fm/mod ( d n -- rem div ) Divides 'd' by 'n', giving the
'floored' remainder and quotient.
m* ( n1 n2 -- d ) Multiplies two cells n1 and n2, giving double 'd'
um* ( u1 u2 -- ud2 ) Same as 'm*' but unsigned math.
udm* ( ud n -- ud1 ) Like um*, but multiplies an unsigned double
>double ( a n -- d true | a n false ) Converts a string to a double
d# ( d1 -- d2 c ) Divide d1 by "base" giving d2, and convert low
digit to character representation. For example:
"12. d#" gives 1 0 50 where '50' is ASCII for '2'
(d.) ( d -- a n ) Like (.) but for doubles
d. ( d -- ) Like . but for doubles
|
math/float |
Implementation of floating-point math words. Uses FPU stack, so
limited to 7 floats on FP stack:
fldcw ( -- n ) Get FP control word from FPU
fstcw ( n -- ) Store new FP control word into FPU
round.trunc round.even round.down round.up ( -- ) change rounding
options for the FPU
finit ( -- ) Initialize the FPU to known default state.
f+ ( f:a f:b -- f:a+b ) Add two floats
f- ( f:a f:b -- f:a-b ) Subtract top float from next to top.
f* ( f:a f:b -- f:a*b ) Multiply two floats
f/ ( f:a f:b -- f:a/b ) Divide two floats
fswap ( f:a f:b -- f:b f:a ) Swap top two FP items
fsin ( f:a -- f:sin[a]) sin(TOFS)
fcos ( f:a -- f:cos[a]) cos(TOFS)
ftan ( f:a -- f:tan[a]) tan(TOFS)
fnegate ( f:a -- f:-a ) Negate TOFS
f0 ( -- f:0.0 ) FP zero to TOFS
f1 ( -- f:1.0 ) FP one to TOFS
fpi ( -- f:pi ) FP pi (3.1415...) to TOFS
fdup ( f:a -- f:a f:a ) Duplicate TOFS
fdrop ( f:a f:b -- f:a ) Drop TOFS
fabs ( f:a -- f:a ) abs(TOFS)
s>f ( n -- f:a ) Convert TOS to TOFS
d>f ( d -- f:a ) Convert double at TOS to TOFS
f! ( addr f:a -- ) Store TOFS into fvariable 'addr'
f@ ( addr -- f:a ) Retrieve TOFS from fvariable 'addr'
f= ( f:a f:b -- flag ) Compare top two floats
ffrac ( f:a -- f:a ) Get fractional part of TOFS
f>s ( f:a -- n ) Convert TOFS to TOS
f>d ( f:a -- d ) Convert TOFS to double on TOS
f*10 ( f:a -- 10*f:a) Multiply TOFS by 10
f/10 ( f:a -- f:a/10) Divide TOFS by 10
10^n ( n -- f:10^n ) Put 10 raised to n'th power on TOFS
str>f ( a n -- f:x ) Convert the string to float and put in TOFS
f ( <fp> -- f:x ) Convert the following text to float and put in TOFS
fvariable ( <name> -- ) Create a variable named <name> to hold a float
fconstant ( f <name> -- ) Put 'f' in a constant <name>
sigdig ( -- a ) Variable holding 'number of significant digits' displayed
(f.) ( f:x -- a n) Convert TOFS to string
f.r ( n f:x -- a n ) Convert TOFS to string 'n' wide
f. ( f:a -- ) Same as . but for floats
|
max | ( a b -- c )
Puts the max (signed) of a and b on TOS: c=max(a,b)
see also: min
|
min | ( a b -- c )
Puts the min (signed) of a and b on TOS: c=min(a,b)
see also: max
|
mod | ( a b -- n )
Divide a by b, and put the modulus (remainder) on TOS: n=a%b
see also: /mod /
|
more | ( n -- )
Set the do-loop to execute 'n' more iterations
see also: flow-control |
move | ( src dst n -- )
Moves "n" bytes from "src" to "dst".
|
ms | ( n -- )
Pauses for n milliseconds
see also: ms@
|
ms@ | ( -- n )
Retrieves current millisecond count, which may be used for timing
see also: ms
|
mtime | ( a n -- n )
Get the last-modified time of the named file, in Unix "seconds
since 1/1/1970" format.
see also: file-io |
needs | ( <name> -- )
Locates the file "<name>" in the user library directory or the
standard library directory includes it if it has not already been
included.
see also: libdir REVAUSERLIB
|
negate | ( n -- n )
Flip the sign of n, same as C "unary -" operator: n=-n
see also: not invert
|
net/sockets |
Socket access library. See generic sockets documentation for
details on how to use (or see examples/smtp.f)
socket ( domain type proto -- sock )
bind ( sock name len -- result )
connect ( sock sockaddr flags -- result )
listen ( sock backlog -- result )
accept ( sock addr len -- result )
gethostbyname ( name -- result ) pass a NUL terminated string
closesocket ( sock -- result )
send ( sock addr len flags -- result )
recv ( sock addr len flags -- result )
sockbad? ( sock -- sock flag )
tcpsock ( -- sock ) Initialize a TCP socket
udbsock ( -- sock ) Initially a UDP socket
host>addr ( a n -- ipaddr ) Get IP address of host
connectsocket ( a n port -- sock ) Connect to named host:port
using TCP If "n" is zero, then "a" is an IP address.
|
newsrc | ( a -- )
Adjusts the input for this eval as starting from "a". Takes care
of adjusting "tin" etc.
|
nip | ( a b c -- a c )
Drop the second stack item
see also: stack-ops
|
noop | ( -- )
Does nothing. This is the default value for 'defer'ed words.
|
not | ( a -- n )
Logical not of a. 0 => -1, !0 => 0, similar to C "!" operator
see also: and or xor
|
notail | ( -- )
Same as "forth", but sets the class as "'notail". This class
supresses the 'tail-recursion-optimizer', and is used when using
the word as the last word in a colon-def causes problems because
the return stack is not what was expected. Some words like ">rr"
use this class. All 'macro' class words also suppress the
tail-optimizer now.
see also: forth macro inline classes
|
nul | ( -- a )
Returns an "empty" NUL terminated string. Good for when you need
to pass such a string to a C library.
|
octal | ( -- )
Change base to octal (base 8)
see also: decimal binary hex base
|
off | ( ptr -- )
Stores a zero at the address 'ptr'. Same as "0 swap !"
see also: on
|
on | ( ptr -- )
Stores a -1 (true) at the address 'ptr'. Same as "true swap !"
see also: off
|
onexit | ( xt -- )
Add the xt to the 'exit handlers list'. This xt will be executed
when "bye" is called
see also: program-control
|
onstartup | ( xt -- )
Add the xt to the 'startup handlers list'. This xt will be
executed when "cold" is called, just before "appstart" is called.
see also: program-control
|
open/r | ( a n -- h )
Open the named file for reading. Sets 'ioerr' appropriately to
indicate failure.
Will fail if the file does not exist or if the user has
insufficient privileges to access it. In these cases, the
value of 'h' is indeterminate.
see also: file-io |
open/rw | ( a n -- h )
Like 'open/r' but open for both reading and writing.
see also: file-io |
or | ( a b -- n )
OR top two items, like C bitwise operator: a | b
see also: and xor not
|
os | ( -- n )
Returns 1 for Linux, 0 for Windows.
see also: osname
|
os/console |
Console I/O:
These colors recognized: black red green yellow blue magenta cyan
white normal bold dim underscore blink reverse concealed
Text attribute modifiers: foreground background color
Position: gotoxy ( row col -- ) savepos ( -- ) restorepos ( -- )
Misc: conRowsCols ( -- rows cols ) cls
|
os/exception |
Not working yet. Will be exception handling.
|
os/registry |
Win32 only: registry functions. See Win32 API docs
RegCloseKey RegOpenKey RegCreateKey RegDeleteKey RegQueryValue
RegQueryValueEx RegSetValue RegSetValueEx RegEnumKey
HKCR HKCU HKLM HKUS REG_NONE REG_SZ REG_EXPAND_SZ REG_BINARY
REG_DWORD
|
os/shell |
Interface to run external programs:
shell ( a n -- n ) Run the command specified by "a,n"
!! ( <to-eol> -- n) Run the command after !!
Both return the exit code of the process run.
|
osname | ( -- a n )
Returns the name of the os.
see also: os
|
over | ( a b -- a b a)
Put copy of second stack item on top of stack
see also: stack-ops
|
p: | ( <name> -- )
Similar to the ANS word POSTPONE. Compiles the "xt" of the word
"<name>" as well as a call to its class-handler. This means that the
word will be executed when the containing word is executed, rather than
being run immediately. Mostly useful for causing a 'macro' word to
execute at run time rather than compile-time.
see also: x:
|
pad | ( -- a )
Return the address of "pad" ( a temporary buffer used by many
words )
|
padchar | ( -- a )
Address of variable holding the value used to 'pad' output
numbers. Default is a space, but can be changed to anything in
order to get special output.
Example:
'* padchar !
234 10 .r
prints: *******234
see also: (.) (.r) (p.r) base
|
parse | ( char <text>char -- a n )
Parse input stream until "char"; returns the string corresponding
to the read portion. The remainder after "char" is still in the
input stream, and will be processed next.
see also: parsews parse/
|
parse/ | ( char <text>char -- a n )
Same as "parse", but handles escaped "\" characters
see also: parse parsews
|
parsews | ( -- a n )
Same as parse, but eliminates any "whitespace" from before or
after the word.
see also: parse parse/
|
pathsep | ( -- c )
Returns an os-specific value for the file-path separator character
|
pdoes | ( -- )
Used to implement "does>"
|
pick | ( n -- n )
Return the n'th item from the stack. "0 pick" is the same as "dup",
"1 pick" is the same as "over".
see also: stack-ops
|
place | ( a n a2 -- )
Store the string "a,n" as a counted string at "a2" - up to 255
characters
see also: count +place strings |
pop>ebx | ( a -- )
Moves the TOS to the CPU register EBX so the following code can
operate on the values in EAX and EBX. Used by words like '+'
etc.
|
preprocessor |
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]
|
prior | ( <word> -- )
Once a word is defined (with ':') any prior version of it is lost
to the interpreter. This word allows invoking the previous
version of "<word>" even though it was hidden from the
interpreter.
Example:
: a ." hi" ;
: a prior a ." there" ;
without the use of 'prior', the second 'a' would recurse forever.
|
program-control |
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.
|
prompt | ( -- )
Called whenever Reva is waiting for input from the keyboard. The
default action is to print "ok> "
see also: program-control
|
r-stack-ops |
Sometimes data are put on the return stack, or it is necessary to
change the return stack somehow.
Reva provides these return-stack manipulation words:
r> >r r@ rdrop rp@ rp0 rpick >rr rr>
Information about the return-stack can be got with:
.rs rdepth
|
r> | ( r:n -- n )
Pops top item off return-stack and pushes it onto the data stack
see also: r-stack-ops
|
r@ | ( -- n )
Puts a copy of the top item on the return-stack onto the data
stack.
see also: r-stack-ops
|
random/gm |
Heavy-duty random numbers, periodicity approx 2^123:
rand ( -- n ) Get the next random number
curseed4 ( -- a b c d ) Get the four-cell seed
seed4 ( a b c d -- ) Set the four-cell seed
|
random/simple |
Simple random numbers from "Starting Forth":
random ( -- n ) Get the next random number
choose ( n -- m ) Return a random number in range 0...n-1
|
rdepth | ( -- n )
Returns depth of the return-stack
see also: depth
|
rdrop | ( r:n -- )
Drop one value from return-stack.
see also: r-stack-ops
|
read | ( a n fileid - n2 )
Reads from 'fileid' into the buffer 'a n'. 'n2' is the number of
bytes read.
see also: file-io |
remains | ( -- n )
How many more loops remain in this do..loop
see also: flow-control |
rename | ( a1 n1 a2 n2 -- )
Rename the file named "a1,n1" to the new name "a2,n2"
see also: file-io |
repeat | ( -- )
Start a loop to be used with "again" or "while"
see also: flow-control
|
reset | ( -- )
Resets stack to initial settings (e.g. drops everything)
see also: cold
|
resize | ( a n -- a2 )
Resize allocated memory "a" to "n" bytes. Returns 0 on success.
see also: allocate, free
|
REVAUSERLIB | (environment variable)
This is an optional environment variable which, if set, must
contain the full path to the user's private library files, similar
to the 'libdir' path (terminated with a / or \ as expected on your
system)
see also: libdir needs
|
revaver | ( -- a n )
String containing the Reva version.
|
reveal | ( <name> -- )
Used inside a loc:...loc; block, makes the word <name> visible
outside that block.
see also: loc: loc; hide seal
|
rot | ( a b c -- b c a )
Rotate top three items clockwise
see also: stack-ops
|
rp0 | ( -- a )
Variable containing the beginning of the return-stack
see also: r-stack-ops
|
rp0 | ( -- a )
Variable holding value of start of return stack space
see also: h0 s0 d0 str0
|
rp@ | ( -- n )
Grab the current value of the return-stack pointer
see also: r-stack-ops
|
rpick | ( n -- m )
Grab the 'nth' value on the return-stack
see also: r-stack-ops
|
rr> | ( -- n )
Removes the second value off the return-stack. "nip" for the
return-stack.
see also: r-stack-ops
|
s0 | ( -- a )
Variable holding value of start of stack space
see also: h0 d0 str0 rp0 |
save | ( <name> -- )
Saves the current Reva to the file "<name>" as a 'turnkey'
program.
see also: program-control
|
scratch | ( -- a )
Returns the address of a 4K buffer which can be used for anything
by anyone. Don't rely on it to stay unchanged
see also: temp pad
|
seal | ( dict -- )
Given the dictionary pointer to a word, makes all words prior to
it invisible in dictionary searches. Do be careful with it, it
cannot be undone! Example:
'' words seal
After doing this, all words defined prior to 'words' are
unavailable (note 'bye' doesn't work now!)
see also: loc: loc;
|
search | ( a1 n1 a2 n2 -- a3 n3 true | false )
Look for substring "a2,n2" in "a1,n1". Returns 0 on failure, or the
matching substring "a3,n3" and true.
see also: strings
|
see | ( <name> -- )
Dumps the bytes corresponding to the "xt" of "<name>", without
disassembling (yet).
|
seek | ( n fileid -- )
Move current position of 'fileid' to n bytes from the beginning of
the file
see also: file-io |
skip | ( n -- )
Increment the loop index in a do..loop by 'n'.
see also: flow-control
|
slurp | ( addr n -- addr2 n2 )
Reads in file given by name and puts a string containing the
entire file on the stack. The string is allocated and needs to be
'free'd. If the 'slurp' failed, the values "0 0" will be on the
stack.
see also: include needs
|
sm/rem | ( d n -- rem div )
Symmetrical divide of a 'double' by a cell, like /mod but one
argument is double.
|
sp | ( -- a )
Puts the current value of the stack pointer (ESI) on TOS.
|
space | ( -- )
Print a space character (ASCII 32)
see also: console-io |
spaces | ( n -- )
Prints 'n' spaces
see also: console-io
|
split | ( a n c -- a n false | a1 n1 a2 n2 true )
Split the string "a,n" at the first occurrence of "c". If the
character was not found, returns original string and false;
otherwise returns the split string and true.
see also: strings
|
src | ( -- a )
Address of variable holding current value of source pointer. If that
pointer is zero, the input is from the keyboard
see also: >in
|
srcstr | ( -- a n )
Returns a string containing the remaining text to be processed by
the interpreter. Mostly for use in 'scan-ahead' processing, for
example by "[IF]" etc.
|
stack-ops |
Manipulation of data on the 'stack' is one of the most important
things to understand in Reva or any Forth. Every word has a
'stack-diagram', which is an explanation of how the word operates
on the stack.
Reva provides these stack manipulation words:
dup drop swap over nip tuck rot -rot pick
2dup 2drop 2swap 2over 3dup
Information about the stack can be got with:
.s depth
|
stat | ( a n -- n )
Get the permissions (file attributes) of the named file.
see also: file-io |
stdcb: | ( xt numparams stacksize <name> -- )
Same as "cb:", but for a stdcall function
see also: cb:
|
stdin | ( -- n )
Return handle of standard-input
see also: stdout
|
stdout | ( -- n )
Return handle of standard-output
see also: stdin
|
str0 | ( -- a )
Variable holding value of start of string space (where compiled
strings are put)
see also: h0 s0 d0 rp0 |
string/iconv |
This is a wrapper around the 'libiconv' character-set conversion
library. You will need 'libiconv.so' on Linux, or the included
'libiconv2.dll' (in the 'bin' directory) to use this on Windows.
Look in the 'libiconv' documentation for how you should use these
words:
iconv_open ( z-to z-from -- desc )
iconv ( desc **in *inleft **out *outleft -- result )
iconv_close ( desc -- result )
iconv_ver ( -- result )
Return an integer which is the libiconv version.
|
string/justify |
Justify and pad strings:
ljust ( a n m -- ) Prints "a,n" in field "m" wide
rjust ( a n m -- ) Prints "a,n" right-justified in field "m" wide
0pad ( a n m -- a' m' ) Pads "a,n" on left with zeroes to width "m"
|
string/misc |
Various and sundry string routines:
spaces ( n -- ) print 'n' spaces
strlwr ( a n -- a n ) lowercase the string
ws? ( c -- flag ) test if 'c' is whitespace
s++ ( a n -- a' n' ) advance string to next character
/string ( a n m -- a' n') advance string 'm' characters
|
string/regex |
Wrapper around the PCRE library. Linux users need to have PCRE
installed (most will already have it). Windows users get
'pcre3.dll' in the 'bin' directory, which needs to be distributed
with any application which uses PCRE.
regex-options ( -- a ) Variable containing PCRE options
These are various option flags to be "or"ed together
PCRE_CASELESS PCRE_MULTILINE PCRE_DOTALL PCRE_EXTENDED
PCRE_ANCHORED PCRE_DOLLAR_ENDONLY PCRE_EXTRA PCRE_NOTBOL
PCRE_NOTEOL PCRE_UNGREEDY PCRE_NOTEMPTY PCRE_UTF8
PCRE_NO_AUTO_CAPTURE PCRE_NO_UTF8_CHECK PCRE_AUTO_CALLOUT
PCRE_PARTIAL
regex: ( a n <name> -- ) Create a compiled 'regex' for use
regex_getmatch ( n -- ) Return submatch "n" (0 is the main match)
regex_find ( a n regex -- 0 | a n #matched) Returns number of
matches, 0 for no match. If #matched is 1 or more, also
returns the main match.
regex_find! ( a1 n1 a2 n2 -- 0 | a n #matched) Same as
'regex_find', but matches against 'a2,n2' instead of a
precompiled regex.
To appreciate the complexities of the regular-expressions
permitted, please look at the PCRE documentation on-line at:
http://www.pcre.org/
|
string/soundex |
Give soundex code for a string:
soundex ( a n -- a' n' )
|
string/trim |
Trim whitespace from strings:
ltrim ( a n -- a' n' ) trim from the left
rtrim ( a n -- a' n' ) trim from the right
trim ( a n -- a' n' ) trim from both sides
|
string/unicode |
|
strings |
Strings come in two varieties, "Forth" and "Counted". A "Forth"
string is two cells on the stack, usually designated in
stack-diagrams as "a n", meaning 'address' and 'number of
characters'. One can display such a string using "type".
"Counted" strings are just one cell on the stack, an address.
The first byte (or cell) of this address is a count of characters.
There are two flavors of counted strings - "cstr" and "lstr". The
cstr uses one byte for the count, and so can contain up to 255
characters (which is usually enough for most purposes), while the
lstr uses a cell for the count, and is therefore essentially of
unlimited length. Reva has no words to print counted strings, but
they are easily converted to Forth strings using "count" and
"lcount". Forth strings may be stored into counted strings using
"place" and "lplace", and appended with "+place" and "l+place".
Declaring strings is very easy. Use the word '"' (that is, one
double-quote character), followed by ONE space, the desired
string, and a closing double quote: " This is a Forth string"
If it is necessary to have double-quotes inside a string, it is
easily accommodated by using the backslash character:
" She said, \"Look, Ma - no hands!\""
If a backslash is necessary, simply use two backslashes in a row.
All strings created with '"' are NUL terminated, as are counted
strings. So one may pass them to external routines which expect a
NUL terminated string.
These are words which deal with strings in Reva:
count lcount place lplace +place +lplace c+place c+lplace
" ." /char \char chop -chop cmp cmpi lc search split
zcount zt nul
|
swap | ( a b -- b a )
Swap the top two stack items
see also: stack-ops
|
syscall | ( arg0...argN N+1 syscall -- result)
LINUX ONLY: Call the kernel directly using the syscall interface
NOTE: You really need to know what you are doing to use this
function.
see also: lib func
|
tell | ( fileid -- n )
Report on the position in 'fileid' relative to the beginning of
the file
see also: file-io |
temp | ( -- a )
Variable for anyone to use for any purpose
see also: scratch pad
|
then | ( -- )
Ends the conditional started by one of the 'if' constructs
see also: conditionals
|
throw | ( n -- )
If TOS is zero, does nothing. Otherwise, passes control to the
most recent "catch"
see also: catch
|
throw-codes |
These are the predefined codes 'throw' will use from Reva:
THROW_GENERIC THROW_BADFUNC THROW_BADLIB
|
THROW_BADFUNC | ( -- -2 )
Thrown by 'func' if the function is invoked but has not been
loaded.
see also: throw-codes
|
THROW_BADLIB | ( -- -3 )
Thrown by 'lib' if the lib is invoked but has not been loaded.
see also: throw-codes
|
THROW_GENERIC | ( -- -1 )
Thrown for any generic error internal to Reva.
see also: throw-codes
|
tib | ( -- tib )
Variable holding value of "terminal input buffer"
see also: >in src
|
time&date | ( -- s m h dd mm yyyy )
Returns the current time and date
|
to | ( n <value> -- )
Sets the value to 'n'.
see also: value
|
tp | ( -- a )
Puts the pointer to the input buffer (TIB) on TOS.
|
true | ( -- flag )
Returns logical 'true', e.g. -1 (all bits set)
see also: false and or xor not
|
tuck | ( a b -- b a b )
Put a copy of top cell under second stack item
see also: stack-ops
|
type | ( a n -- )
Print a string
see also: console-io
|
u32 | ( -- n )
WINDOWS ONLY: Handle to USER32 library
see also: k32 g32
|
unloop | ( -- )
Undoes the return-stack munging done by 'do', permitting use of
';;' without crashing
see also: flow-control
|
used | ( -- dict-used code-used )
Puts the current memory usage (dict,code) on the stack.
|
util/auxstack |
Extra stack to help out with awkward situations:
>aux ( n -- ) Put 'n' on the auxilliary stack
aux> ( -- n ) Pop TOS from the auxilliary stack
aux@ ( -- n ) Peek at TOS from auxilliary stack
|
util/case |
Implements a case ... of ... endof ... endcase construct like ANS.
Example:
case
1 of cr ." one" endof
2 of cr ." two" endof
67 of cr ." sixty-seven" endof
cr ." default case = " dup .
endcase
|
util/classes |
Utility to tell what the class of a word is:
classof ( dict -- a n ) Given the dict ptr of a word, tell its class
classof: ( <name> -- a n ) Same as 'classof' but operate on word following
|
util/eachline |
Perform an action for each line of a chunk of text:
eachline ( a n xt -- a n) The 'xt' is passed the line to operate one
|
util/locals |
Implements a form of local variables.
Example:
: ltst { v1 v2 | v3 -- n }
| Locals defined before the vertical slash get initialised
| from the stack, so ltst must be called with two items on
| the stack Locals defined after the vertical slash are
| initialised at compile time to 0. They retain their
| value between calls (to ltst) which means they are
| 'static' in 'C' terminology. The '--' and anything
| after it are ignored, allowing a complete stack diagram.
v1 . v2 . v3 . | v1 and v2 are initialised from the
| stack, print their values
v1 v2 + +to v3 | v3 = v3 + v1 + v2
1 +to v3 | v3 = v3 + 1
v3 . | print v3
addr v3 @ . | and again, the hard way
;
|
util/misc |
Miscellaneous stuff that doesn't fit elsewhere:
(.ip) ( n -- a n ) Format an IP address in the normal manner
.ip ( n -- ) Print an IP address, like .
EOF ( -- ) stop processing this file
|
util/tasks |
Very simple multitasking words. See examples/task.f for usage:
task: ( -- ) In place of : -- creates a new nameless colon-def which
is put into the task queue.
>task ( xt -- ) Like task:, but takes an xt to put in the task queue.
yield ( -- ) Executes the next task in the queue
|
util/zlib |
Simple wrapper around the ZLIB compression library. See the ZLIB
documentation for detailed information on these words:
Operations on 'gz' files:
gzopen ( path mode -- handle)
gzread ( handle buf len -- #read) 0=end of file -1= error
gzwrite ( handle buf len -- #written)
gzseek ( handle offset whence -- offset )
gztell ( handle -- offset )
gzclose ( handle -- result )
Compressing buffers: (note the 'dsize^' is a pointer)
zlib_compressbound ( len -- maxlen) Max size to compress 'len'
zlib_compress ( dest dsize^ src ssize -- result )
zlib_uncompress ( dest dsize^ src ssize -- result )
|
value | ( n -- )
Create a value with the value "n". A value is like a variable in
that it can be changed, but like a constant in that you don't need
to use '@' to get its value
Example:
12 value joe
joe 12 =if ... then
34 to joe
see also: variable constant to |
variable | ( <name> -- )
Create a new variable called "<name>", with an intial value of zero
see also: variable, @ ! on off ++ --
|
variable, | ( n <name> -- )
Same as "variable", but initializes with the value "n"
see also: variable
|
voc: | ( <name> -- )
Creates a new vocabulary word "<name>". When this word is
executed, it will provide access to any words defined after it was
invoked as well as all words prior to its invocation. Use
"lastvoc" to return to the prior vocabulary. This allows
semi-private word lists
see also: lastvoc loc: loc;
|
w! | ( n a -- )
Puts the short (2-bytes) "n" at "a".
see also: w@
|
w@ | ( a -- n )
Gets a short (2-bytes) from "a".
see also: w!
|
while | ( n -- )
If TOS is not zero, return to most recent "repeat".
see also: flow-control
|
word? | ( a n -- a n 0 | xt 1 | n 2 | n m 3 | 4 )
Last resort interpreter hook. This gets called when the
interpreter cannot determine that a piece of text is a word or a
number.
|
words | ( <opt> -- )
Display all words currently visible in the dictionary. If <opt>
was given, will show all words including <opt> as a substring.
Words which have been defined between "loc:" and "loc;" will not
be visible, nor will words in a parent vocabulary which were
defined after the current vocabulary (see "voc:" for more
information
|
write | ( a n fileid -- )
Write 'n' bytes from address 'a' to 'fileid'.
see also: file-io |
x: | ( <name> -- )
Causes the word "<name>" to be executed immediately rather than
being compiled into the word's definition. This is mostly useful
for "forth" or "inline" words whose side-effects are desired
immediately.
see also: p:
|
xor | ( a b -- n )
XOR top two items. like C bitwise operator: a ^ b
see also: and or not
|
zcount | ( z -- a n )
Convert NUL-terminated string to address-count "Forth" format.
see also: zt
see also: strings
|
zt | ( a n -- z )
Zero terminate string "a,n". Must be sure there is space for the
terminating NUL before using!
see also: zcount
see also: strings
|
| | ( -- )
Comment to end-of-line. Same as \ in ANS Forth
see also: (
|