asm: added simple .SNA writer

[urasm.git] / dox / urforth.txt

proper documentation will follow... maybe.
but please, read this document if you want to use UrForth.
UrForth is not a standard Forth system (it is a mixture of ANS, FIG,
and my own creations), and this document contains valuable bits of
knowledge about some non-standard UrForth features.

one of the non-standard UrForth features is locals support. it is
done like this:
  : myword  ( a b -- c )
    args: a b
    locals: loc1 loc2

    :a TO :loc1
    :b TO :loc2
    :loc1 :loc2 +
  ;
here, "args:" will declare local variables, and automatically fill them
with arguments from the data stack. "locals:" declare "free" locals.
there can be more than one "locals:" section, but all such sections should
come before anything else. to use local, you must prepend its name with a
colon. the usual "TO" word is used to set local values.

"DOES>" works only on CREATEd words.

note that "/MOD" and other such words are the exact opposites of what the
standard says. "/MOD" return stack is "( quot rem )". i.e. the remainder is
always on top. in 83/ANS standards TOS is the quotient.

"ERROR" word accepts address and counter, and is fatal error (it cannot be
CATCHed). there are "?ERROR" and "?NOT-ERROR" words to check error coditions
too.

"VARIABLE" expects initial value on the stack (like in FIG-Forth). but
"DEFER" doesn't, and initialises new defered words with "NOOP" by default.

note that "LITERAL" is not immediate. use "IMM-LITERAL" if you need immediate
version. the same is for "STRLITERAL" -- there is "IMM-STRLITERAL".

there is no "POSTPONE" word. i was never able to understand what the fuck it
does. so "[COMPILE]" simply compiles the next word CFA to the current word,
regardless of its "immediate" flag. and "COMPILE" makes the current compiling
word compile next word on execution.

always use "COMPILE," to compile CFAs to the current word. this guarantees
that your code will survive internal VM changes (mostly). also, look into
"20-base-creatori.f" and "30-ifthen.f" to learn how to compile branches.
there are special words to put branch destinations, and if you will use
them instead of direct "!" or ",", your code will have a better chance to
work if i'll change "BRANCH" to be relative, for example.


some global variables are state-local. also, each state has its own TIB,
independent of other states.

state-local vars are:
BASE
( -- base-addr )
current number base.

TIB
( -- addr )
current TIB.

>IN
( -- ofs )
offset in current TIB.

PAD
( -- pad )
return PAD address. this memory area can be used for storing temporary
values (like strings). you can assume to have at least 4096 bytes there.
WARNING! some words may use PAD for their own needs. this is mostly
         words which does some string manipulation, like building strings
         from parts, and such. note that number conversion buffer is
         independent of PAD.

(STD-TIB-ADDR)
( -- )
default TIB address. WARNING! if this user var contains a handle, that
handle will be freed on destroying the task. if you want to replace the
default TIB, make sure that you will free the old handle (if it is a handle).

STATE
( -- addr )
current system state. `0` for interpretation, any other value for compilation.

CONTEXT
( -- addr )
context vocabulary, i.e. vocabulary that will be used to look for words. note
that there is a stack of vocabularies there (see "ALSO" and other words), and
all of them will be searched after context one.

CURRENT
( -- addr )
this is vocabulary that will be used to record new words. it is only checked
for duplicate word definitions, but otherwise is not participating in word
searching mechanics.

(SELF)
( -- addr )
this is used in OOF. it holds address of the active class instance (object).

(USER-INTERPRET-NEXT-LINE)
( -- addr )
this holds the address of a word which will be called by INTERPRET when it
hits EOL, and needs to read a new line to interpret (or compile).

(EXC-FRAME-PTR)
( -- addr )
this is used in THROW/CATCH implementation, and holds current exception frame
address.

(USER-VAR-USED)
( -- uvar-used-addr )
address of the variable contains first free user area address.

(USER-VAR-ADDR)
( -- uvar-begin-addr )
start address of the user area.

(USER-VAR-SIZE)
( -- uvar-size )
maximum user area size in bytes.



DEBUG:DUMP-STACK
( -- )
dump data stack

DEBUG:BACKTRACE
( -- )
show current backtrace (slow!)

DEBUG:DECOMPILE name
( -- )
decompile given forth word.

SP0!
( -- )
clear data stack.

RP0!
( -- )
clear return stack.

note that address for memory operations may be a handle too. with handles,
low bits are used as offset, so you can directly address some bytes in handle
data area. currently, low 12 bits are reserved for offset, so you can address
4096 bytes inside a handle. but don't hardcode it, use "FORTH:(MAX-HANDLE-OFS)"
constant to get the maximum allowed offset (because it may change in the future).

also, UrForth is 32-bit system, and stores all numbers as little-endian. this
will not change, so you can write your code without checking cell size, or
byte order.


C@
( addr -- value8 )
load 8-bit value.

W@
( addr -- value16 )
load 16-bit value.

@
( addr -- value32 )
load 32-bit value.

C!
( val8 addr -- )
store 8-bit value.

W!
( val16 addr -- )
store 16-bit value.

!
( val32 addr -- )
store 32-bit value.

C,
( val8 -- )
compile 8-bit value.

W,
( val16 -- )
compile 16-bit value.

,
( val -- )
compile 32-bit value.


(LIT)
( -- n )
read 4 bytes immediately following this word, and push them
to the data stack. adjust IP to skip those bytes.

(LITCFA)
( -- n )
read 4 bytes immediately following this word, and push them
to the data stack. adjust IP to skip those bytes. this is
the same as "(LIT)", but used to store CFAs of words. using
different words for different data types helps the debugger
and the decompiler.

(LITVOCID)
( -- n )
the same as "(LIT)", but for vocids.

(LITSTR8)
( -- addr count )
inline byte-counted string literal. note that the string
always have a trailing zero byte (which is not counted),
and always padded so it ends on a 4-byte boundary.

(BRANCH) ( -- )
read next 4 bytes, and set IP to that address.

(TBRANCH)
( flag -- )
skip next 4 bytes if `flag` is 0, otherwise perform "(BRANCH)".

(0BRANCH)
( flag -- )
skip next 4 bytes if `flag` is not 0, otherwise perform "(BRANCH)".

(+0BRANCH)
( num -- )
skip next 4 bytes if `num` is positive or 0, otherwise perform "(BRANCH)".

(+BRANCH)
( num -- )
skip next 4 bytes if `num` is positive (but not 0), otherwise perform "(BRANCH)".

(-BRANCH)
( num -- )
skip next 4 bytes if `num` is negative, otherwise perform "(BRANCH)".

(DATASKIP)
( -- )
read next 4 bytes, advance IP. then increment IP by the read number.
this is used to tell the decompiler that it should skip some inline
data instead of trying to decompile it.

EXECUTE
( cfa )
pop word CFA address, and execute it.

EXECUTE-TAIL
( cfa )
pop word CFA address, and execute it. returning from the executed
word will return to the upper word. i.e. this performs a tail call.


(EXIT)
internal compiler word, placed at the end of colon definition.
pops a number from return stack, and sets IP to that number.

(L-ENTER)
this word is used to implement local variables and arguments.
it doesn't matter how it works, you should not used it anyway.
read the source code, if you're curious.

(L-LEAVE)
this word is used to implement local variables and arguments.
it doesn't matter how it works, you should not used it anyway.
read the source code, if you're curious.

(LOCAL@)
( idx -- value )
read local variable with the given index. indices are 1-based.

(LOCAL!)
( value idx -- )
write local variable with the given index. indices are 1-based.

DUP
( n -- n n )
duplicates a number on the data stack.

?DUP
( n -- n n ) | ( 0 -- 0 )
duplicates a number on the data stack, but only if that number is not 0.

2DUP
( n0 n1 -- n0 n1 n0 n1 )

DROP
( n -- )

2DROP
( n0 n1 -- )

SWAP
( n0 n1 -- n1 n0 )

2SWAP
( n0 n1 -- n1 n0 )

OVER
( n0 n1 -- n0 n1 n0 )

2OVER
( n0 n1 -- n0 n1 n0 )

ROT
( n0 n1 n2 -- n1 n2 n0 )

NROT
( n0 n1 n2 -- n2 n0 n1 )

NIP
( a b -- b )

TUCK
( a b -- b a b )

RDUP
( n -- n n )
the same as "DUP", but for the return stack.

RDROP
( n -- )
the same as "DROP", but for the return stack.

RSWAP
( n0 n1 -- n1 n0 )
the same as "SWAP", but for the return stack.

ROVER
( n0 n1 -- n0 n1 n0 )
the same as "OVER", but for the return stack.

RROT
( n0 n1 n2 -- n1 n2 n0 )
the same as "ROT", but for the return stack.

RNROT
( n0 n1 n2 -- n2 n0 n1 )
the same as "NROT", but for the return stack.

>R
( n -- | n )
move number from the data stack to the return stack.

R>
( | n -- n )
move number from the return stack to the data stack.

R@
( | n -- n | n )
copy number from the return stack to the data stack.

PICK
( idx -- n )
copy n-th element at the data stack. "0 PICK" is the same as "DUP".

RPICK
( idx -- n )
the same as "PICK", but for the return stack.

ROLL
( idx -- n )
move n-th element at the data stack to the top. "1 ROLL" is the same as "SWAP".

RROLL
( idx -- n )
the same as "ROLL", but for the return stack.

REFILL
( -- eofflag )
read next input line. can cross include boundaries. pushes 0 if
there are no more input lines. TIB contents is undefined in this case.

REFILL-NOCROSS
( -- eofflag )
read next input line. cannot cross include boundaries. pushes 0 if
there are no more input lines. TIB contents is undefined in this case.

(TIB-IN)
( -- addr )
get address of the current TIB position.
WARNING! do not try to emulate "TIB-GETCH" and such with this word!
         TIB usually ends with 0 byte, and if you will advance beyond
         that 0, Bad Things will happen.

TIB-PEEKCH
( -- char )
push current TIB char, do not advance >IN.

TIB-PEEKCH-OFS
( ofs -- char )
peek TIB char with the given offset. "0 TIB-PEEKCH-OFS" is the same as "TIB-PEEKCH".

TIB-GETCH
( -- char )
push current TIB char, advance >IN. it is safe to call this even
when you reached the end of TIB. in this case, returned char code
will be 0. i.e. "0" means "end of TIB".

TIB-SKIPCH
( -- )
skip current TIB char. it is safe to call this even when you reached
the end of TIB.


(PARSE)
( delim skip-leading-delim? -- addr count TRUE / FALSE )
does base TIB parsing; never copies anything.
as our reader is line-based, returns FALSE on EOL.
EOL is detected after skipping leading delimiters.
passing -1 as delimiter skips the whole line, and always returns FALSE.
finishing delimiter is always skipped.

PARSE-SKIP-BLANKS
( -- )
skip all chars with codes <=32.

(PARSE-SKIP-COMMENTS)
( allow-multiline? -- )
skip all blanks and comments. if multiline skip is not allowed, reaching
end of TIB while still waiting for the comment terminator is error.
single-line comments are ok, though.

PARSE-SKIP-LINE
( -- )
advance >IN to the end of TIB.

PARSE-NAME
( -- addr count )
parse with leading blanks skipping. doesn't copy anything.
return empty string on EOL.

PARSE
( delim -- addr count TRUE / FALSE )
parse without skipping delimiters; never copies anything.
as our reader is line-based, returns FALSE on EOL.
passing 0 as delimiter skips the whole line, and always returns FALSE.
finishing delimiter is always skipped.

EMIT
( n -- )
print char.

XEMIT
( n -- )
"safe" char printer. all non-printable chars (including newline and such)
will be printed as "?".

LASTCR?
( -- bool )
was last printed char a newline?

LASTCR!
( bool -- )
force-set the flag for "LASTCR?" word.

CR
( -- )
print newline.

SPACE
( -- )
print space.

SPACES
( n -- )
print `n` spaces. if `n` is negative, prints nothing.

ENDCR
( -- )
prints newline if the last printed char was not a newline.

TYPE
( addr count -- )
print the string. negative count is ok, in this case the word prints nothing.

XTYPE
( addr count -- )
the same as "TYPE", but uses "XEMIT".

FLUSH-EMIT
( -- )
output can be buffered. it usually flushed when newline is printed, but
you can flush it manually using this word.

+
( a b -- a+b )

-
( a b -- a-b )

*
( a b -- a*b )

U*
( a b -- a*b )

/
( a b -- a/b )

U/
( a b -- a/b )

MOD
( a b -- a%b )

UMOD
( a b -- a%b )

/MOD
( a b -- a/b, a%b )
note that the results are swaped, contrary to ANS idiocity.
i don't fuckin' know why ANS morons decided to make the stack
effect that contradicts the word name. "/MOD" clearly indicates
that quotient comes first.

U/MOD
( a b -- a/b, a%b )
note that the results are swaped, contrary to ANS idiocity.
i don't fuckin' know why ANS morons decided to make the stack
effect that contradicts the word name. "/MOD" clearly indicates
that quotient comes first.

*/
( a b c -- a*b/c )
this uses 64-bit intermediate value.

U*/
( a b c -- a*b/c )
this uses 64-bit intermediate value.

*/MOD
( a b c -- a*b/c a*b%c )
this uses 64-bit intermediate value.
note that the results are swaped, contrary to ANS idiocity.
i don't fuckin' know why ANS morons decided to make the stack
effect that contradicts the word name. "/MOD" clearly indicates
that quotient comes first.

U*/
( a b c -- a*b/c )
this uses 64-bit intermediate value.

M*
( a b -- lo(a*b) hi(a*b) )
this leaves 64-bit result.

UM*
( a b -- lo(a*b) hi(a*b) )
this leaves 64-bit result.

M/MOD
( alo ahi b -- a/b a%b )
note that the results are swaped, contrary to ANS idiocity.
i don't fuckin' know why ANS morons decided to make the stack
effect that contradicts the word name. "/MOD" clearly indicates
that quotient comes first.

UM/MOD
( alo ahi b -- a/b a%b )
note that the results are swaped, contrary to ANS idiocity.
i don't fuckin' know why ANS morons decided to make the stack
effect that contradicts the word name. "/MOD" clearly indicates
that quotient comes first.

<
( a b -- a<b )

U<
( a b -- a<b )

>
( a b -- a>b )

U>
( a b -- a>b )

<=
( a b -- a<=b )

U<=
( a b -- a<=b )

>=
( a b -- a>=b )

U>=
( a b -- a>=b )

=
( a b -- a=b )

<>
( a b -- a<>b )

NOT
( a -- !a )

LAND
( a b -- a&&b )
logical "and".

LOR
( a b -- a||b )
logical "or".

AND
( a b -- a&b )
bitwise "and".

OR
( a b -- a|b )
bitwise "or".

XOR
( a b -- a^b )
bitwise "xor".

BITNOT
( a -- ~a )

2U*
( u -- u*2 )

2U/
( u -- u*2 )

4U*
( u -- u*4 )

4U/
( u -- u*4 )

ASH
( n count -- )
arithmetic shift; positive `n` shifts to the left.

LSH
( n count -- )
logical shift; positive `n` shifts to the left.

COMPILER:(UNESCAPE)
( addr count -- addr new-count )
process string escapes. modifies string in-place. the resulting string is
never bigger than the source one. negative counts are allowed.

(BASED-NUMBER)
( addr count allowsign? base -- num TRUE / FALSE )
tries to convert the given string to the number, using the given
default base. if "allowsign?" is non-zero, properly process leading
number sign. this words understands numbers in non-default bases too
(like "0x29a", for example).


[
switch to interpretation mode.

]
switch to compilation mode.

(CREATE-WORD-HEADER)
( addr count word-flags -- )
create word header in the dictionary, link word to the current vocabulary.
doesn't create CFA.

(CREATE-NAMELESS-WORD-HEADER)
( word-flags -- )
create nameless word header in the dictionary, link word to the current vocabulary.
doesn't create CFA.

FIND-WORD
( addr count -- cfa TRUE / FALSE)
general word finder. checks wordlist stack, performs colon resolution.

(FIND-WORD-IN-VOC)
( addr count vocid allowhidden? -- cfa TRUE / FALSE)
find word in the given wordlist. does no name resolution, and
doesn't look in parent wordlists.

FIND-WORD-IN-VOC
( addr count vocid -- cfa TRUE / FALSE)
find word in the given wordlist. does no name resolution, and
doesn't look in parent wordlists. skips hidden words.

(FIND-WORD-IN-VOC-AND-PARENTS)
( addr count vocid allowhidden? -- cfa TRUE / FALSE)
find word in the given wordlist. does no name resolution, but searches
parent wordlists if "vocid" is nested.

FIND-WORD-IN-VOC-AND-PARENTS
( addr count vocid -- cfa TRUE / FALSE)
find word in the given wordlist. does no name resolution, but searches
parent wordlists if "vocid" is nested. skips hidden words.

COMPILER:?EXEC
check if we are in interpretation mode, and throws an error if we aren't.

COMPILER:?COMP
check if we are in compilation mode, and throws an error if we aren't.

"
string literal.

(VSP@)
( -- vsp )
this word is used internally to work with wordlist stack.

(VSP!)
( vsp -- )
this word is used internally to work with wordlist stack.

(VSP-AT@)
( idx -- value )
this word is used internally to work with wordlist stack.

(VSP-AT!)
( value idx -- )
this word is used internally to work with wordlist stack.

CFA->PFA
( cfa -- pfa )

PFA->CFA
( pfa -- cfa )

CFA->NFA
( cfa -- nfa )

NFA->CFA
( nfa -- cfa )

CFA->LFA
( cfa -- lfa )

LFA->CFA
( lfa -- cfa )

LFA->PFA
( lfa -- pfa )

LFA->BFA
( lfa -- bfa )

LFA->SFA
( lfa -- sfa )

LFA->NFA
( lfa -- nfa )

NFA->LFA
( nfa -- lfa )

CFA->WEND
( cfa -- wend-addr )
convert CFA to word end address.

DEBUG:IP->NFA
( ip -- nfa / 0 )
convert instruction pointer to NFA. return 0 if cannot.

DEBUG:IP->FILE/LINE
( ip -- addr count line TRUE / FALSE )
name is at PAD; it is safe to use PAD, because each task has its
own temp image.

DEBUG:IP->FILE-HASH/LINE
( ip -- len hash line TRUE / FALSE )
return unique file hash and name length instead of string name.
used in debugger.

STRING:=
( a0 c0 a1 c1 -- bool )

STRING:=CI
( a0 c0 a1 c1 -- bool )
case-insensitive compare (only for ASCII).

STRING:HASH
( addr count -- hash )

STRING:HASH-CI
( addr count -- hash )
case-insensitive hash (only for ASCII).

($DEFINE)
( addr count -- )
add new conditional define. case-insensitive (for ASCII).

($UNDEF)
( addr count -- )
remove conditional define. case-insensitive (for ASCII).

($DEFINED?)
( addr count -- bool )
check if we have a conditional define. case-insensitive (for ASCII).

ERROR
( addr count -- )
print error message and abort.

?ERROR
( errflag addr count -- )
if "errflag" is not zero, print error message and abort.

?NOT-ERROR
( errflag addr count -- )
if "errflag" is zero, print error message and abort.

(INCLUDE-DEPTH)
( -- depth )
return number of items in the include stack.

(INCLUDE-FILE-ID)
( isp -- id )
isp 0 is current, then 1, etc.
each include file has unique non-zero id.

(INCLUDE-FILE-LINE)
( isp -- line )

(INCLUDE-FILE-NAME)
( isp -- addr count )
current file name; at PAD.

(INCLUDE)
( addr count soft? system? -- )
push current file to the include stack, open a new one. used internally.

$INCLUDE "str"
immediate word.

$INCLUDE-ONCE "str"
includes file only once; unreliable on shitdoze, i believe.
immediate word.

HANDLE:NEW
( typeid -- hx )
allocate a new handle with the given typeid. typeid is just a number
without any special meaning. any number except "-1" is allowed.
new handle size is 0.

HANDLE:FREE
( hx -- )
deallocate a handle, free all allocated handle memory.
0 is allowed.

HANDLE:TYPEID@
( hx -- typeid )

HANDLE:TYPEID!
( typeid hx -- )

HANDLE:SIZE@
( hx -- size )
0 is allowed.

HANDLE:SIZE!
( size hx -- )
resize memory allocated for handle data.

HANDLE:USED@
( hx -- used )
"used" is just a number, which means nothing for most code.
it is used to implement dynamic arrays.
0 is allowed.

HANDLE:USED!
( size hx -- )

HANDLE:C@
( idx hx -- value )

HANDLE:W@
( idx hx -- value )

HANDLE:@
( idx hx -- value )

HANDLE:C!
( value idx hx -- value )

HANDLE:W!
( value idx hx -- )

HANDLE:!
( value idx hx -- )

HANDLE:LOAD-FILE
( addr count -- stx / FALSE )
load file with the given name into newly allocated handle.
return 0 (FALSE) if there is no such file.

A>
( -- rega )
get address register contents.

>A
( rega -- )
set address register contents.

A-SWAP
( rega -- olda )
swap TOS and the address register.

+1>A
( -- )
increment the address register.

A>R
( -- | rega )
copy the address register to the return stack.

R>A
( | rega -- )
restore the address register from the return stack.

C@A
( -- byte )

W@A
( -- word )

@A
( -- value )

C!A
( byte -- )

W!A
( word -- )

!A
( value -- )

C@A+
( idx -- byte )
safe way to access both dictionary memory, and handle memory.
"idx" is used as offset from address register contents.

W@A+
( idx -- word )
safe way to access both dictionary memory, and handle memory.
"idx" is used as offset from address register contents.

@A+
( idx -- value )
safe way to access both dictionary memory, and handle memory.
"idx" is used as offset from address register contents.

C!A+
( byte idx -- )
safe way to access both dictionary memory, and handle memory.
"idx" is used as offset from address register contents.

W!A+
( word idx -- )
safe way to access both dictionary memory, and handle memory.
"idx" is used as offset from address register contents.

@A+
( value idx -- )
safe way to access both dictionary memory, and handle memory.
"idx" is used as offset from address register contents.

DEBUG:(DECOMPILE-CFA)
( cfa -- )

GET-MSECS
( -- u32 )

(UFO-INTERPRET-FINISHED-ACTION)
( -- )
this is called by main loop when it is out of input stream. internally,
it simply sets a flag to tell the VM that it should stop.

(UFO-INTERPRET-NEXT-LINE)
( -- continue? )
default word used to read next input line. return FALSE to exit from
"INTERPRET".

(INTERPRET-PARSE-NAME)
( -- addr count / FALSE )
called by INTERPRET to read next word from the input stream. calls
"(INTERPRET-NEXT-LINE)" to refill lines. return FALSE (without address)
to exit from "INTERPRET", or next parsed word.

(USER-INTERPRET-NEXT-LINE)
user variable, holds address of "get next line" word. default value is
CFA of "(UFO-INTERPRET-NEXT-LINE)".

(INTERPRET-NEXT-LINE)
( -- continue? )
peek "(USER-INTERPRET-NEXT-LINE)" and call read CFA.

HERE
( -- dp )
push current dictionary pointer to the data stack.
NOTE: there are actually two DPs -- normal, and temporary. "(DP-TEMP)" is
the temp one, and if it is 0, "(DP)" is used. UrForth has 1MB temp area
(that's where PAD is too), it had different addresses, and vocabularies
created in that area are not linked to the main voclink list. this is used,
for example, in locals engine, to store names of locals. so if you're using
locals in your word, do not use temp area while compiling that word.

LATEST-LFA
( -- lfa )
push LFA of the latest defined word in the current vocabulary. note that
"smudge" bit doesn't matter here, it is always the last word you created
header for. this includes "nonamed" words (which have empty string as a name).

NOOP
( -- )
does nothing. at all.

COMPILER:(CTLID-COLON)
( -- ctlid-colon )
semicolon expects this on the data stack.

' <name>
( -- cfa )
find word, push its CFA to the data stack. note that the tick
is NOT immediate. use "[']" if you need to compile next word CFA.

:
start new word definition.

;
end new word definition.

ALIAS oldword newword
( -- )
"newword" will do exactly the same as "oldword". word attributes
will be copied too (hidden, immediate, etc.).

LATEST-CFA
( -- cfa )

LATEST-PFA
( -- pfa )

LATEST-NFA
( -- nfa )

LATEST-SFA
( -- sfa )

~AND
( a b -- a&~b )

SWAP!
( addr value -- )

OR!
( value addr -- )

~AND!
( value addr -- )

XOR!
( value addr -- )

IMMEDIATE
mark last defined word as immediate (or remove immediate mark if it is already set).

(HIDDEN)
mark last defined word as hidden. DO NOT USE. this is obsolete feature,
and it will be removed. it is here for compatibility with my other Forth system.

(PUBLIC)
the opposite of "(HIDDEN)".

-FIND-REQUIRED
alias for the tick.

PARSE-SKIP-COMMENTS
( -- )
skip all comments and blanks, multiline mode.

PARSE-SKIP-LINE-COMMENTS
skip all comments and blanks, single line mode.

(SET-DEF-WORD-FLAGS)
( flg -- )
add (OR) default flag for new words.
word flags are:
  (WFLAG-IMMEDIATE)
  (WFLAG-SMUDGE)
  (WFLAG-NORETURN)
  (WFLAG-HIDDEN)
  (WFLAG-CBLOCK)
  (WFLAG-VOCAB)
  (WFLAG-SCOLON)
  (WFLAG-PROTECTED)

(RESET-DEF-WORD-FLAGS)
( flg -- )
remove (~AND) default flag for new words.

<PUBLIC-WORDS>
( -- )
all following words will be public.

<HIDDEN-WORDS>
( -- )
all following words will be hidden.

<PROTECTED-WORDS>
( -- )
all following words will be protected. you cannot redefine
protected words.

<UNPROTECTED-WORDS>
( -- )
all following words will not be protected.

ONLY
( -- )
clear the wordlist stack.

ALSO
( -- )
push context vocabulary onto the wordlist stack.

PREVIOUS
( -- )
pop vocabulary from the wordlist stack, and make in context.

DEFINITIONS
( -- )
make context vocabulary also current. "current" is the vocabulary
that will receive new word definitions. "context" is the vocabulary
that will be used to search words.

1+
( a -- a+1 )

2+
( a -- a+2 )

4+
( a -- a+2 )

1-
( a -- a-1 )

2-
( a -- a-2 )

4-
( a -- a-2 )

0=
( n -- n==0 )

0<>
( n -- n<>0 )

0<
( n -- n==0 )

0<=
( n -- n==0 )

0>
( n -- n<>0 )

0>=
( n -- n<>0 )

NOTNOT
( a -- !!a )

ABS
( a -- |a| )

SIGN?
( n -- -1|0|1 )

NEGATE
( n -- -n )

LSHIFT
( n count -- n )

RSHIFT
( n count -- n )

ARSHIFT
( n count -- n )

SHL
( n count -- n )

SHR
( n count -- n )

SAL
( n count -- n )

SAR
( n count -- n )

LO-WORD
( a -- a&0xffff )

HI-WORD
( a -- [a>>16]&0xffff )

LO-BYTE
( a -- a&0xff )

HI-BYTE
( a -- [a>>8]&0xff )

0!
( addr -- )

1!
( addr -- )

+!
( n addr -- )

-!
( n addr -- )

1+!
( addr -- )

1-!
( addr -- )

BCOUNT
( addr -- addr+1 count )

COUNT
( addr -- addr+4 count )

HEX
( -- )

DECIMAL
( -- )

OCTAL
( -- )

BINARY
( -- )

WITHIN
( value a b -- value>=a&&value<b )

UWITHIN
( value a b -- value>=a&&value<b )

BOUNDS?
( value a b -- value>=a&&value<=b )
numbers are unsigned.

(HANDLE-ADDR?)
( addr -- )
check if the given addres is actually a handle.

COMPILER:SET-SMUDGE
( -- )
set "smudge" bit for the latest word.

COMPILER:RESET-SMUDGE
( -- )
reset "smudge" bit for the latest word.

COMPILER:SET-WARG
( warg -- )
set argument type for the latest word. each word has "argument type" field,
which inditates word argument type in the compiled code. arguments are:
  (WARG-NONE)
  (WARG-BRANCH)
  (WARG-LIT)
  (WARG-C4STRZ)
  (WARG-CFA)
  (WARG-CBLOCK)
  (WARG-VOCID)
  (WARG-C1STRZ)

(WARG-MASK)
( -- mask )
this mask can be used to get only argument type bits from the first NFA cell.

COMPILER:(GET-NEW-WORD-FLAGS)
( -- flags )
get sanitized new word flags. currently, only "hidden" and "protected" flags
are retained, all other flags will be reset.

COMPILER:(CREATE-HEADER)
( addr count -- )
create new named word header with the default flags. additionally, sets
"smudge" flag on the new word.

COMPILER:(CREATE-NAMELESS)
( -- cfa )
create new nameless word header with the default flags. additionally, sets
"smudge" and "hidden" flags on the new word.
return CFA address of the new word. CFA contents is not filled yet.

COMPILER:(MK-CONST-VAR)
( value cfaidx -- )
don't bother using this.

COMPILER:FORTH-WORD?
( cfa -- bool )
check if the given word is normal Forth word (i.e. defined with the colon).

COMPILE
( cfa -- )
compiles CFA to be executed.

use the following words to compile branch destinations. this way your code
will be independent of branch instruction operand format.

;; usage:
;;  compile (0branch)
;;  (mark>)
;;  ...
;;  (resolve>)
;;
;;  (<mark)
;;  ...
;;  compile (branch)
;;  (<resolve)

COMPILER:(BRANCH-ADDR!)
( destaddr addr -- )
write "branch to destaddr" address to addr.

COMPILER:(BRANCH-ADDR@)
( addr -- dest )  @ ;
read branch address.


COMPILER:(<J-MARK)
( -- addr )
return addr suitable for "(<J-RESOLVE)".

COMPILER:(<J-CHAIN)
( addr -- addr )
use after "(<J-MARK)" to reserve jump and append it to jump chain.

COMPILER:(<J-RESOLVE)
( addr -- )
patch "forward jump" address to HERE. "addr" is the result of "(<J-MARK)".

COMPILER:(MARK-J>)
reserve room for branch address, return addr suitable for "(RESOLVE-J>)".

COMPILER:(CHAIN-J>)
use after "(MARK-J>)" to reserve jump and append it to jump chain.

COMPILER:(RESOLVE-J>)
( addr -- )
compile "forward jump" (possibly chain) from address to HERE. addr is the
result of "(MARK-J>)". this resolves the whole "jump chain".


COMPILER:?PAIRS
( a b -- )
throw error if a <> b.

?2PAIRS
( a b c -- )
throw error if a <> b and a <> c.

LITERAL
( C:n -- )
( E:n -- n )
compile number from the data stack as literal. NOT IMMEDIATE.

IMM-LITERAL
( C:n -- )
( E:n -- n )
immediate version of "LITERAL".

STRLITERAL
( C:addr count -- )
( E: -- addr count )

IMM-STRLITERAL
immediate version of the previous word.

CFALITERAL
( C:cfa -- )
( E:cfa -- cfa )

IMM-CFALITERAL
( C:cfa -- )
( E:cfa -- cfa )

[COMPILE] <wordname>
force the next word to be compiled as normal word, even if it is an immediate one.

[']
compile next word CFA as CFA literal.

COMPILER:(COMPILE-CFA-LITERAL)
( cfa -- )
compile cfa literal to be compiled. ;-)

COMPILER:END-COMPILE-FORTH-WORD
( -- )
push colon ctlid and call ";".


COMPILE <wordname>
compile next word to the currently defining word.

[CHAR] <char>
( -- ch )
push/compile first char of the next word as char code.
note that words with more than one char will cause an error.

RECURSE
recursively call the currently defining word. this is required
due to currently defining word being invisible yet (because it
is not finished).

RECURSE-TAIL
tail-call recursion.

CONSTANT <name>
( value -- )
create new constant.

VARIABLE <name>
( value -- )
create new variable.

(CREATE)
( addr count -- )
this is what "CREATE" is using to create a new word.

CREATE <name>
( -- )
create new word. when executed, this new word will push its PFA.
note that new word is not smudged.

CREATE;
( -- )
finish CREATEd word. this is required to correctly set SFA.
note that "DOES>" automatically takes care of SFA, so you don't have
to call this if you're using "DOES>".

(DOES>)
( doer-addr -- )
patch CREATEd word. put doer address to its CFA, VM will do the rest.
this is used internally by the compiler.

(SET-DOER)
( doer-pfa cfa -- )
makes CFA word to execute "doer-pfa" as doer.
this is used internally by the compiler. do not try to understand this.

DOES>
( -- )  ( pfa )
the usual Forth "CREATE" -- "DOES>" support.

4 CONSTANT CELL
ANS idiocity.

ALIAS 4U* CELLS  ( n -- n*cells )
ANS idiocity.

ALIAS 4+  CELL+  ( n -- n+cell )
ANS idiocity.

ALIAS 4-  CELL-  ( n -- n-cell )
ANS idiocity.

+CELLS
( a n -- a+n*cells )
ANS idiocity.

-CELLS
( a n -- a+n*cells )
ANS idiocity.

.( text)
immediately print the text.

." text"
compile text printer.

N-ALLOT
( n -- stard-addr )
allocate n *bytes* in the current DP, return the address of
the first allocated byte.

ALLOT
( n -- )
allocate n *bytes* in the current DP.

ALIGN-HERE
( -- )
align DP to 4-byte boundary.

COMPILER:(NEW-WORDLIST)
( parentvocid need-hashtable? -- vocid )
create new empty wordlist.

COMPILER:(CREATE-NAMED-VOCAB)
( vocid addr count -- )
create vocabulary word.

COMPILER:(CREATE-VOCAB) <vocname>
( vocid -- )
create vocabulary word.

COMPILER:(IS-VOC-WORD?)
( cfa -- bool )
check if the given CFA defined as a vocabulary header.

COMPILER:(WORD->VOCID)
( cfa -- vocid )
get vocid from the vocabulary word. doesn't check arguments.

COMPILER:(VOCID-PARENT@)
( vocid -- vocid )
get vocid parent vocabulary. return 0 if there is no parent.
doesn't check arguments.

COMPILER:(VOCID-PARENT!)
( parent-vocid vocid -- )
set vocid parent vocabulary. doesn't check arguments.

COMPILER:(VOCID-TYPEID@)
( vocid -- typeid )
internal helper for STRUCT support.

COMPILER:(VOCID-TYPEID!)
internal helper for STRUCT support.

(VOCABULARY-EX)
( addr count parent need-hashtbl? -- )
useful low-level words to create vocabs with already parsed names.

(VOCABULARY)
( addr count -- )

(SIMPLE-VOCABULARY)
( addr count -- )
creates vocabulary without a hash table.

(NESTED-VOCABULARY)
( addr count -- )

(SIMPLE-NESTED-VOCABULARY)
( addr count -- )

VOCABULARY <vocname>

SIMPLE-VOCABULARY <vocname>

NESTED-VOCABULARY <vocname>

SIMPLE-NESTED-VOCABULARY <vocname>

VOCID: <vocname>
( -- vocid )
return vocid for the given vocabulary. this word is immediate.

VOC-LATEST
( vocid -- latest )
return latest word LFA for the given vocid.

ALSO-DEFS: <vocname>
( -- )
this does "ALSO <vocname> DEFINITIONS"

PREV-DEFS
( -- )
this does "PREVIOUS DEFINITIONS".

VOCAB-IF-NONE <vocname>
create vocabulary if we don't have such word yet.

NESTED-VOCAB-IF-NONE <vocname>
create nested vocabulary if we don't have such word yet.

SIMPLE-VOCAB-IF-NONE <vocname>
create vocabulary if we don't have such word yet.

SIMPLE-NESTED-VOCAB-IF-NONE <vocname>
create nested vocabulary if we don't have such word yet.

-TO  ( n -- )  \ name
decrement value by n.

+TO  ( n -- )  \ name
increment value by n.

-1-TO  ( -- )  \ name
decrement value by 1.

+1-TO  ( -- )  \ name
increment value by 1.

0-TO  ( -- )  \ name
write 0 to value.

... FORTH:(TO-EXTENDER) ...
( addr count FALSE -- addr count FALSE / TRUE )
"TO" can be extended to support things it doesn't know about yet.
after parsing a name, "(TO-EXTENDER)" will be called (this is
scattered colon word). note that due to how scattered colon works,
you'd better DON'T use "EXIT", but pass a flag if you need to stop
further processing. also, do not forget to check the flag at the
start of your extender, because some other extender may already
did its work before yours.

... FORTH:(EXIT-EXTENDER) ...
( -- )
this scattered colon word allows you to extend "EXIT". "EXIT" is
the immediate word that compiles word leaving instructions. you
can compile your cleanup code before the standard cleanup.

... FORTH:(INTERPRET-CHECK-WORD) ...
( addr count FALSE -- addr count FALSE / TRUE )
this is called by INTERPRET before the standard word processing.

... FORTH:(INTERPRET-WORD-NOT-FOUND) ...
( addr count FALSE -- addr count FALSE / TRUE )
this is called by INTERPRET when word resolution failed.


UrForth supports cooperative multitasking. it is also used to implement
interactive debugger. tasks are called "execution states", or simply
"states".

MTASK:NEW-STATE
( cfa -- stid )
create new state, return state id.

MTASK:FREE-STATE
( stid -- )
free state. state id should be valid, and should not be an active state.

MTASK:STATE-NAME@
( stid -- addr count )
copy state name to PAD.

MTASK:STATE-NAME!
( addr count stid -- )
set new state name. maximum name length is 127 chars. state name
should not include char with code 0.

MTASK:STATE-FIRST
( -- stid )
get first state in the list of all created states. this is used to
iterate over all states.
WARNING! do not mutate state list while iterating! result will be UB.

MTASK:STATE-NEXT
( stid -- stid / 0 )
get next state id. used to iterate over all states.
WARNING! do not mutate state list while iterating! result will be UB.

MTASK:YIELD-TO
( ... argc stid -- )
yield to another state. move argc numbers from the current state data
stack to the new state data stack. push args to the new state data
stack, and then push current state id. i.e. new state data stack will
look like this:
  ( ... argc old-stid )
it is ok to swith to the currently active state (it is a no-op).

MTASK:SET-SELF-AS-DEBUGGER
( -- )
register current task as system debugger. you can yeild from the debugger
after this.

DEBUG:(BP)
( -- )
breakpoint. debugger task receives debugge stid on the data stack,
and `-1` as yield argument count. i.e. debugger stack will be:
  ( -1 old-stid )

MTASK:DEBUGGER-RESUME
( stid -- )
resume debugee execution.

MTASK:DEBUGGER-SINGLE-STEP
( stid -- )
execute one debuggee instruction, and return to debugger.
this is basically "YIELD", but to use in the debugger
(and it doesn't pass any arguments). debugger stack will be:
  ( -2 old-stid )

MTASK:STATE-IP@
( stid -- ip )
get state instruction pointer.

MTASK:STATE-IP!
( ip stid -- )
set state instruction pointer.

MTASK:STATE-A>
( stid -- regA )
get address register contents.

MTASK:STATE->A
( rega stid -- )
set address register contents.

MTASK:STATE-USER@
( addr stid -- valie )
get other state user area cell.

MTASK:STATE-USER!
( value addr stid -- )
set other state user area cell.

MTASK:STATE-RPOPCFA@
( -- flag )
VM has special mode when it gets next CFA from the return stack
instead of the address pointed by IP. this is used to implement
"EXECUTE", for example. use this word to retrieve that flag.

MTASK:STATE-RPOPCFA!
( flag -- )
VM has special mode when it gets next CFA from the return stack
instead of the address pointed by IP. this is used to implement
"EXECUTE", for example. use this word to set that flag.

MTASK:ACTIVE-STATE
( -- stid )
return state id of the currently executing state.

MTASK:YIELDED-FROM
( -- stid / 0 )
return state which called "MTASK:YIELD-TO" last.

MTASK:STATE-SP@
( stid -- depth )
get the data stack depth for the given state.

MTASK:STATE-RP@
( stid -- depth )
get the return stack depth for the given state.

MTASK:STATE-LP@
( stid -- lp )
get local stack ptr.

MTASK:STATE-LBP@
( stid -- lbp )
get local stack base ptr.

MTASK:STATE-SP!
( depth stid -- )
set the data stack depth for the given state.

MTASK:STATE-RP!
( stid -- depth )
set the return stack depth for the given state.

MTASK:STATE-LP!
( lp stid -- )
set local stack ptr.

MTASK:STATE-LBP!
( lbp stid -- )
set local stack base ptr.

MTASK:STATE-DS@
( idx stid -- value )
read the data stack of the given state. note that the index is bound-checked.

MTASK:STATE-RS@
( idx stid -- value )
read the return stack of the given state. note that the index is bound-checked.

MTASK:STATE-LS@
( idx stid -- value )
read the locals stack of the given state. note that the index is bound-checked.

MTASK:STATE-DS!
( value idx stid -- )
write the data stack of the given state. note that the index is bound-checked.
i.e. if you want to push some value, increase stack depth first.

MTASK:STATE-RS!
( value idx stid -- )
write the return stack of the given state. note that the index is bound-checked.
i.e. if you want to push some value, increase stack depth first.

MTASK:STATE-LS!
( value idx stid -- )
write the locals stack of the given state. note that the index is bound-checked.
i.e. if you want to push some value, increase stack depth first.


there are some words to work with TTY (only GNU/Linux).

TTY:TTY?
( -- bool )
check if input and output are valid TTY(s).

TTY:RAW?
( -- bool )
check if current TTY mode is raw.

TTY:SIZE
( -- width height )
get TTY size. for non-TTYs retur default 80x24.

TTY:SET-RAW
( -- success-bool )
switch TTY to raw mode.

TTY:SET-COOKED
( -- success-bool )
switch TTY to cooked mode.

TTY:RAW-EMIT
( n -- )
type char without any filtering or safety nets.

TTY:RAW-TYPE
( addr count -- )
type string without any filtering or safety nets.

TTY:RAW-FLUSH
( -- )
the output of the two words above is buffered. this words flushes
the buffer. buffering is done because raw TTY is mostly used to
build user interfaces, and sending accumulated terminal commands
in one big chunk looks much better (most terminal emulators will
process the whole chunk before refreshing their windows).

TTY:RAW-READCH
( -- ch / -1 )
-1 returned on error, or on EOF.
read one char (without any interpretation) if TTY is in raw mode.
note that 0 is a valid char (it is used to send Ctrl+Space in some
terminal emulators). also note that there is no way to tell if we
hit a EOF, or some error occured. in practice, it doesn't matter,
because in both cases it means that TTY is unusable anymore.

TTY:RAW-READY?
( -- bool )
check if raw TTY has some data to read.


file i/o words.

FILES:ERRNO
( -- errno )
last libc `errno`. can be used after failure to inspect error code.

FILES:UNLINK
( addr count -- success? )
delete file.

FILES:OPEN-R/O
( addr count -- handle TRUE / FALSE )
open file for reading. `handle` is always positive.

FILES:OPEN-R/W
( addr count -- handle TRUE / FALSE )
open file for writing. `handle` is always positive.

FILES:CREATE
( addr count -- handle TRUE / FALSE )
create new file, or truncate existing. `handle` can be any number, including
`0` and negative numbers.

FILES:CLOSE
( handle -- success? )
close opened file.

FILES:TELL
( handle -- ofs TRUE / FALSE )
get current file position.

FILES:SEEK-EX
( ofs whence handle -- TRUE / FALSE )
set current file position. `whence` can be one of "FILES:SEEK-SET",
"FILES:SEEK-CUR", "FILES:SEEK-END".

FILES:SEEK
( ofs handle -- TRUE / FALSE )
set current file position. the same as calling "SEEK-EX" with `whence`
equal to "SEEK-SET".

FILES:SIZE
( handle -- size TRUE / FALSE )
get file size. `handle` cannot be 0.
WARNING! on failure on valid handle, file position for that handle is undefined.

FILES:READ
( addr count handle -- rdsize TRUE / FALSE )
read bytes from file. this word can read less bytes than requirested. `count`
can be 0 (in this case the function always succeeds). note that this function
can read 0 bytes, and this is success too.

FILES:READ-EXACT
( addr count handle -- TRUE / FALSE )
read bytes from file. reading less then requested number of bytes is error.
`count` can be 0 (in this case the function always succeeds).

FILES:WRITE
( addr count handle -- TRUE / FALSE )
write bytes from file. writing less bytes than requested is error. `count`
can be 0 (in this case the function always succeeds).