core

"Core words + extensions"

core [ANS] /* core words */

* ! ( val addr -- )

store value at addr (sizeof CELL)

FORTH/ANS core (dpANS .6.1.0010) ordinary primitive

* # ( n.n -- n.n' )

FORTH/ANS core (dpANS .6.1.0030) ordinary primitive

* #> ( n.n -- str-addr str-len )

FORTH/ANS core ordinary primitive

* #S ( n.n -- n.n ) f

FORTH/ANS core (dpANS .6.1.0050) ordinary primitive

* ( f: a -- n,n )

b is the integer representation of a

we use truncation towards zero.
compare with F>S and its "FROUND>S" / "FTRUNC>S"

FORTH/ANS core (dpANS 11.6.1.0080) immediate primitive

* * ( a b -- a*b )

return the multiply of the two args

FORTH/ANS core (dpANS .6.1.0090) ordinary primitive

*/

[] no special info, see general notes

FORTH/ANS core (dpANS .6.1.0100) ordinary primitive

*/MOD

[] no special info, see general notes

FORTH/ANS core (dpANS .6.1.0110) ordinary primitive

* + ( a b -- a+b )

return the sum of the two args

FORTH/ANS core (dpANS .6.1.0120) ordinary primitive

* +! ( val addr -- )

add val to the value found in addr

 simulate:
   : +! TUCK @ + SWAP ! ;

FORTH/ANS core (dpANS .6.1.0130) ordinary primitive

* +LOOP ( increment -- )

compile ((+LOOP)) which will use the increment
as the loop-offset instead of just 1. See the
DO and LOOP construct.

FORTH/ANS core (dpANS .6.1.0140) compiling primitive

* , ( val -- )

store the value in the dictionary

 simulate:
   : , DP  1 CELLS DP +!  ! ;

FORTH/ANS core (dpANS .6.1.0150) ordinary primitive

* - ( a b -- a-b )

return the difference of the two arguments

FORTH/ANS core (dpANS .6.1.0160) ordinary primitive

* . ( val -- )

print the numerical value to stdout - uses BASE

FORTH/ANS core (dpANS .6.1.0180) ordinary primitive

* ." ( [string<">] -- )

print the string to stdout

FORTH/ANS core compiling primitive

* / ( a b -- a/b )

return the quotient of the two arguments

FORTH/ANS core (dpANS .6.1.0230) ordinary primitive

* /MOD ( a b -- m n )

divide a and b and return both
quotient n and remainder m

FORTH/ANS core (dpANS .6.1.0240) ordinary primitive

* 0< ( val -- cond )

return a flag that is true if val is lower than zero

 simulate:
  : 0< 0 < ;

FORTH/ANS core ordinary primitive

* 0= ( val -- cond )

return a flag that is true if val is just zero

 simulate:
  : 0= 0 = ;

FORTH/ANS core (dpANS .6.1.0270) ordinary primitive

* 1+ ( val -- val+1 )

return the value incremented by one

 simulate:
  : 1+ 1 + ;

FORTH/ANS core (dpANS .6.1.0290) ordinary primitive

* 1- ( val -- val-1 )

return the value decremented by one

 simulate:
   : 1- 1 - ;

FORTH/ANS core (dpANS .6.1.0300) ordinary primitive

* 2! ( a,a addr -- )

double-cell store

FORTH/ANS core (dpANS .6.1.0310) ordinary primitive

* 2* ( a -- a*2 )

multiplies the value with two - but it
does actually use a shift1 to be faster

 simulate:
  : 2* 2 * ; ( canonic) : 2* 1 LSHIFT ; ( usual)

FORTH/ANS core (dpANS .6.1.0320) ordinary primitive

* 2/ ( a -- a/2 )

divides the value by two - but it
does actually use a shift1 to be faster

 simulate:
  : 2/ 2 / ; ( canonic) : 2/ 1 RSHIFT ; ( usual)

FORTH/ANS core (dpANS .6.1.0330) ordinary primitive

* 2@ ( addr -- a,a )

double-cell fetch

FORTH/ANS core (dpANS .6.1.0350) ordinary primitive

* 2DROP ( a b -- )

double-cell drop, also used to drop two items

FORTH/ANS core (dpANS .6.1.0370) ordinary primitive

* 2DUP ( a,a -- a,a a,a )

double-cell duplication, also used to duplicate
two items

 simulate:
   : 2DUP OVER OVER ; ( wrong would be : 2DUP DUP DUP ; !!)

FORTH/ANS core (dpANS .6.1.0380) ordinary primitive

* 2OVER ( a,a b,b -- a,a b,b a,a )

double-cell over, see OVER and 2DUP

 simulate:
   : 2OVER SP@ 2 CELLS + 2@ ;

FORTH/ANS core (dpANS .6.1.0400) ordinary primitive

* 2SWAP ( a,a b,b -- b,b a,a )

double-cell swap, see SWAP and 2DUP

 simulate:
   : 2SWAP LOCALS| B1 B2 A1 A2 | B2 B1 A2 A1 ;

FORTH/ANS core (dpANS .6.1.0430) ordinary primitive

* : ( 'name' -- )

create a header for a nesting word and go to compiling
mode then. This word is usually ended with ; but
the execution of the resulting colon-word can also
return with EXIT

FORTH/ANS core (dpANS .6.1.0450) defining primitive

* ; ( -- )

compiles ((;)) which does EXIT the current
colon-definition. It does then end compile-mode
and returns to execute-mode. See : and :NONAME

FORTH/ANS core (dpANS .6.1.0460) compiling primitive

* < ( a b -- cond )

return a flag telling if a is lower than b

FORTH/ANS core (dpANS .6.1.0480) ordinary primitive

* <# ( -- )

FORTH/ANS core (dpANS .6.1.0490) ordinary primitive

* = ( a b -- cond )

return a flag telling if a is equal to b

FORTH/ANS core (dpANS .6.1.0530) ordinary primitive

* > ( a b -- cond )

return a flag telling if a is greater than b

FORTH/ANS core ordinary primitive

* >BODY ( addr -- addr' )

adjust the execution-token (ie. the CFA) to point
to the parameter field (ie. the PFA) of a word.
this is not a constant operation - most words have their
parameters at "1 CELLS +" but CREATE/DOES-words have the
parameters at "2 CELLS +" and ROM/USER words go indirect
with a rom'ed offset i.e. "CELL + @ UP +"

FORTH/ANS core ordinary primitive

>IN

[] no special info, see general notes

FORTH/ANS core threadstate variable

* >NUMBER ( a,a str-adr str-len -- a,a' str-adr' str-len)

try to convert a string into a number, and place
that number at a,a respeciting BASE

FORTH/ANS core ordinary primitive

* >R ( value -- )

save the value onto the return stack. The return
stack must be returned back to clean state before
an exit and you should note that the return-stack
is also touched by the DO ... WHILE loop.
Use R> to clean the stack and R@ to get the
last value put by >R

FORTH/ANS core compiling primitive

* ?DUP ( value -- value|[nothing] )

one of the rare words whose stack-change is
condition-dependet. This word will duplicate
the value only if it is not zero. The usual
place to use it is directly before a control-word
that can go to different places where we can
spare an extra DROP on the is-null-part.
This makes the code faster and often a little
easier to read.

 example:
   : XX BEGIN ?DUP WHILE DUP . 2/ REPEAT ; instead of
   : XX BEGIN DUP WHILE DUP . 2/ REPEAT DROP ;

FORTH/ANS core (dpANS .6.1.0630) ordinary primitive

* @ ( addr -- value )

fetch the value from the variables address

FORTH/ANS core (dpANS .6.1.0650) ordinary primitive

* ABS ( value -- value' )

return the absolute value

FORTH/ANS core (dpANS .6.1.0690) ordinary primitive

* ACCEPT ( a n -- n' )

get a string from terminal into the named input
buffer, returns the number of bytes being stored
in the buffer. May provide line-editing functions.

FORTH/ANS core (dpANS .6.1.0695) ordinary primitive

* ALIGN ( -- )

will make the dictionary aligned, usually to a
cell-boundary, see ALIGNED

FORTH/ANS core (dpANS .6.1.0705) ordinary primitive

* ALIGNED ( addr -- addr' )

uses the value (being usually a dictionary-address)
and increment it to the required alignment for the
dictionary which is usually in CELLS - see also
ALIGN

FORTH/ANS core (dpANS .6.1.0706) ordinary primitive

* ALLOT ( count -- )

make room in the dictionary - usually called after
a CREATE word like VARIABLE or VALUE
to make for an array of variables. Does not
initialize the space allocated from the dictionary-heap.
The count is in bytes - use CELLS ALLOT to allocate
a field of cells.

FORTH/ANS core (dpANS .6.1.0710) ordinary primitive

* AND ( val mask -- val' )

mask with a bitwise and - be careful when applying
it to logical values.

FORTH/ANS core (dpANS .6.1.0720) ordinary primitive

BASE

[] no special info, see general notes

FORTH/ANS core (dpANS .6.1.0750) threadstate variable

* BEGIN ( -- ) compile-time: ( -- cs-marker )

start a control-loop, see WHILE and REPEAT

FORTH/ANS core (dpANS .6.1.0760) compiling primitive

BL

[] no special info, see general notes

FORTH/ANS core (dpANS .6.1.0770) ordinary constant

* C! ( value address -- )

store the byte-value at address, see !

FORTH/ANS core (dpANS .6.1.0850) ordinary primitive

* C, ( value -- )

store a new byte-value in the dictionary, implicit 1 ALLOT,
see ,

FORTH/ANS core (dpANS .6.1.0860) ordinary primitive

* C@ ( addr -- value )

fetch a byte-value from the address, see @

FORTH/ANS core (dpANS .6.1.0870) ordinary primitive

* CELL+ ( value -- value' )

adjust the value by adding a single Cell's width
- the value is often an address or offset, see CELLS

FORTH/ANS core (dpANS .6.1.0880) ordinary primitive

* CELLS ( value -- value' )

scale the value by the sizeof a Cell
the value is then often applied to an address or
fed into ALLOT

FORTH/ANS core (dpANS .6.1.0890) ordinary primitive

* CHAR ( 'word' -- value )

return the (ascii-)value of the following word's
first character.

FORTH/ANS core (dpANS .6.1.0895) ordinary primitive

* CHAR+ ( value -- value' )

increment the value by the sizeof one char
- the value is often a pointer or an offset,
see CHARS

FORTH/ANS core (dpANS .6.1.0897) ordinary primitive

* CHARS ( value -- value' )

scale the value by the sizeof a char
- the value is then often applied to an address or
fed into ALLOT (did you expect that sizeof(p4char)
may actually yield 2 bytes?)

FORTH/ANS core (dpANS .6.1.0898) ordinary primitive

* CONSTANT ( value 'name' -- )

CREATE a new word with runtime ((CONSTANT))
so that the value placed here is returned everytime
the constant's name is used in code. See VALUE
for constant-like names that are expected to change
during execution of the program. In a ROM-able
forth the CONSTANT-value may get into a shared
ROM-area and is never copied to a RAM-address.

FORTH/ANS core (dpANS .6.1.0950) defining primitive

* COUNT ( counted-string -- string-pointer string-length )

usually before calling TYPE

(as an unwarranted extension, this word does try to be idempotent).

FORTH/ANS core (dpANS .6.1.0980) ordinary primitive

* CR ( -- )

print a carriage-return/new-line on stdout

FORTH/ANS core (dpANS .6.1.0990) ordinary primitive

* DECIMAL ( -- )

set the BASE to 10

 simulate:
   : DECIMAL 10 BASE ! ;

FORTH/ANS core (dpANS .6.1.1170) ordinary primitive

* DEPTH ( -- value )

return the depth of the parameter stack before
the call, see SP@ - the return-value is in CELLS

FORTH/ANS core (dpANS .6.1.1200) ordinary primitive

* DO ( end start -- ) ... LOOP

pushes $end and $start onto the return-stack ( >R )
and starts a control-loop that ends with LOOP or
+LOOP and may get a break-out with LEAVE . The
loop-variable can be accessed with I

FORTH/ANS core (dpANS .6.1.1240) compiling primitive

* DOES> ( -- pfa )

does twist the last CREATE word to carry
the (DOES>) runtime. That way, using the
word will execute the code-piece following DOES>
where the pfa of the word is already on stack.
(note: FIG option will leave pfa+cell since does-rt is stored in pfa)

FORTH/ANS core compiling primitive

* DROP ( a -- )

just drop the word on the top of stack, see DUP

FORTH/ANS core (dpANS .6.1.1260) ordinary primitive

* DUP ( a -- a a )

duplicate the cell on top of the stack - so the
two topmost cells have the same value (they are
equal w.r.t = ) , see DROP for the inverse

FORTH/ANS core (dpANS .6.1.1290) ordinary primitive

* ELSE ( -- )

will compile an ((ELSE)) BRANCH that performs an
unconditional jump to the next THEN - and it resolves
an IF for the non-true case

FORTH/ANS core (dpANS .6.1.1310) compiling primitive

* EMIT ( char -- )

print the char-value on stack to stdout

FORTH/ANS core (dpANS .6.1.1320) ordinary primitive

* ENVIRONMENT? ( a1 n1 -- false | ?? true )

check the environment for a property, usually
a condition like questioning the existance of
specified wordset, but it can also return some
implementation properties like "WORDLISTS"
(the length of the search-order) or "#LOCALS"
(the maximum number of locals)

Here it implements the environment queries as a SEARCH-WORDLIST
in a user-visible vocabulary called ENVIRONMENT

 : ENVIRONMENT?
   ['] ENVIRONMENT >WORDLIST SEARCH-WORDLIST
   IF  EXECUTE TRUE ELSE  FALSE THEN ;

FORTH/ANS core (dpANS .6.1.1345) ordinary primitive

* EVALUATE ( str-ptr str-len -- )

INTERPRET the given string, SOURCE id
is -1 during that time.

FORTH/ANS core (dpANS 7.6.1.1360) ordinary primitive

* EXECUTE ( xt -- )

run the execution-token on stack - this will usually
trap if it was null for some reason, see >EXECUTE

 simulate:
  : EXECUTE >R EXIT ;

FORTH/ANS core (dpANS .6.1.1370) ordinary primitive

* EXIT ( -- )

will unnest the current colon-word so it will actually
return the word calling it. This can be found in the
middle of a colon-sequence between : and ;

FORTH/ANS core (dpANS .6.1.1380) compiling primitive

* FILL ( mem-addr mem-length char -- )

fill a memory area with the given char, does now
simply call memset()

FORTH/ANS core (dpANS .6.1.1540) ordinary primitive

* FIND ( bstring -- cfa|bstring -1|0|1 )

looks into the current search-order and tries to find
the name string as the name of a word. Returns its
execution-token or the original-bstring if not found,
along with a flag-like value that is zero if nothing
could be found. Otherwise it will be 1 (a positive value)
if the word had been immediate, -1 otherwise (a negative
value).

FORTH/ANS core (dpANS 16.6.1.1550) ordinary primitive

* FM/MOD ( n1.n1 n2 -- m n )

divide the double-cell value n1 by n2 and return
both (floored) quotient n and remainder m

FORTH/ANS core (dpANS .6.1.1561) ordinary primitive

* HERE ( -- dp-value )

used with WORD and many compiling words

 simulate:   : HERE DP @ ;

FORTH/ANS core (dpANS .6.1.1650) ordinary primitive

* HOLD ( char -- )

the old-style forth-formatting system -- this
word adds a char to the picutred output string.

FORTH/ANS core (dpANS .6.1.1670) ordinary primitive

* I ( -- value )

returns the index-value of the innermost DO .. LOOP

FORTH/ANS core (dpANS .6.1.1680) compiling primitive

* IF ( value -- ) .. THEN

checks the value on the stack (at run-time, not compile-time)
and if true executes the code-piece between IF and the next
ELSE or THEN . Otherwise it has compiled a branch over
to be executed if the value on stack had been null at run-time.

FORTH/ANS core (dpANS .6.1.1700) compiling primitive

* IMMEDIATE ( -- )

make the LATEST word immediate, see also CREATE

FORTH/ANS core (dpANS .6.1.1710) ordinary primitive

* INVERT ( value -- value' )

make a bitwise negation of the value on stack.
see also NEGATE

FORTH/ANS core (dpANS .6.1.1720) ordinary primitive

* J ( -- value )

get the current DO ... LOOP index-value being
the not-innnermost. (the second-innermost...)
see also for the other loop-index-values at
I and K

FORTH/ANS core (dpANS .6.1.1730) compiling primitive

* KEY ( -- char )

return a single character from the keyboard - the
key is not echoed.

FORTH/ANS core (dpANS .6.1.1750) ordinary primitive

* LEAVE ( -- )

quit the innermost DO .. LOOP - it does even
clean the return-stack and branches to the place directly
after the next LOOP

FORTH/ANS core (dpANS .6.1.1760) compiling primitive

* LITERAL ( value -- ) immediate

if compiling this will take the value from the compiling-stack
and puts in dictionary so that it will pop up again at the
run-time of the word currently in creation. This word is used
in compiling words but may also be useful in making a hard-constant
value in some code-piece like this:

 : DCELLS [ 2 CELLS ] LITERAL * ; ( will save a multiplication at runtime)

(in most configurations this word is statesmart and it will do nothing
in interpret-mode. See LITERAL, for a non-immediate variant)

FORTH/ANS core (dpANS .6.1.1780) compiling primitive

* LOOP ( -- )

resolves a previous DO thereby compiling ((LOOP)) which
does increment/decrement the index-value and branch back if
the end-value of the loop has not been reached.

FORTH/ANS core (dpANS .6.1.1800) compiling primitive

* LSHIFT ( value shift-val -- value' )

does a bitwise left-shift on value

FORTH/ANS core (dpANS .6.1.1805) ordinary primitive

* M* ( a b -- m,m )

multiply and return a double-cell result

FORTH/ANS core (dpANS .6.1.1810) ordinary primitive

* MAX ( a b -- c )

return the maximum of a and b

FORTH/ANS core (dpANS .6.1.1870) ordinary primitive

* MIN ( a b -- c )

return the minimum of a and b

FORTH/ANS core (dpANS .6.1.1880) ordinary primitive

* MOD ( a b -- c )

return the module of "a mod b"

FORTH/ANS core (dpANS .6.1.1890) ordinary primitive

* MOVE ( from to length -- )

memcpy an area

FORTH/ANS core (dpANS .6.1.1900) ordinary primitive

* NEGATE ( value -- value' )

return the arithmetic negative of the (signed) cell

 simulate:   : NEGATE -1 * ;

FORTH/ANS core (dpANS .6.1.1910) ordinary primitive

* OR ( a b -- ab )

return the bitwise OR of a and b - unlike AND this
is usually safe to use on logical values

FORTH/ANS core (dpANS .6.1.1980) ordinary primitive

* OVER ( a b -- a b a )

get the value from under the top of stack. The inverse
operation would be TUCK

FORTH/ANS core (dpANS .6.1.1990) ordinary primitive

* POSTPONE ( [word] -- )

will compile the following word at the run-time of the
current-word which is a compiling-word. The point is that
POSTPONE takes care of the fact that word may be
an IMMEDIATE-word that flags for a compiling word, so it
must be executed (and not pushed directly) to compile
sth. later. Choose this word in favour of COMPILE
(for non-immediate words) and [COMPILE] (for immediate
words)

FORTH/ANS core (dpANS .6.1.2033) compiling primitive

* QUIT ( -- ) no-return

this will throw and lead back to the outer-interpreter.
traditionally, the outer-interpreter is called QUIT
in forth itself where the first part of the QUIT-word
had been to clean the stacks (and some other variables)
and then turn to an endless loop containing QUERY
and EVALUATE (otherwise known as INTERPRET )
- in pfe it is defined as a THROW ,

 : QUIT -56 THROW ;

FORTH/ANS core (dpANS .6.1.2050) ordinary primitive