"Core words + extensions"

core The Core Wordset contains the most of the essential words
for ANS Forth.

Tektronix CTE

%version: bln_mpt1!5.33 %

GNU LGPL

[ANS]

*!( val addr -- )

coreordinary primitive

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

see also HOLD for old-style forth-formatting words
and PRINTF of the C-style formatting - this word
divides the argument by BASE and add it to the
picture space - it should be used inside of <#and #>

coreordinary primitive

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

see also HOLD for old-style forth-formatting words
and PRINTF of the C-style formatting - this word
drops the argument and returns the picture space
buffer

coreordinary primitive

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

see also HOLD for old-style forth-formatting words
and PRINTF of the C-style formatting - this word
does repeat the word # for a number of times, until
the argument becomes zero. Hence the result is always
null - it should be used inside of <# and #>

coreordinary primitive

*(( 'comment' -- )

eat everything up to the next closing paren - treat it
as a comment.

coreimmediate primitive

**( a b -- a*b )

return the multiply of the two args

coreordinary primitive

[ANS] */

no special info, see general notes

coreordinary primitive

[ANS] */MOD

no special info, see general notes

coreordinary primitive

*+( a b -- a+b )

return the sum of the two args

coreordinary primitive

*+!( val addr -- )

add val to the value found in addr

simulate:
: +! TUCK @ + SWAP ! ;

coreordinary primitive

*+LOOP( increment -- )

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

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

coredefining primitive

*;( -- )

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

corecompiling primitive

*<( a b -- cond )

return a flag telling if a is lower than b

coreordinary primitive

*<#( -- )

see also HOLD for old-style forth-formatting words
and PRINTF of the C-style formatting - this word
does initialize the pictured numeric output space.

coreordinary primitive

*=( a b -- cond )

return a flag telling if a is equal to b

coreordinary primitive

*>( a b -- cond )

return a flag telling if a is greater than b

coreordinary 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 +"

coreordinary primitive

[ANS] >IN

no special info, see general notes

corethreadstate 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

coreordinary 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

coreordinary 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.

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.

coreordinary primitive

*ALIGN( -- )

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

coreordinary 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

coreordinary primitive

*ALLOT( count -- )

make room in the dictionary - usually called after
a CREATE word like VARIABLE or VALUEto 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.

coreordinary primitive

*AND( val mask -- val' )

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

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

coreordinary 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

coreordinary primitive

*CHAR( 'word' -- value )

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

coreordinary primitive

*CHAR+( value -- value' )

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

coreordinary 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?)

coreordinary 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 VALUEfor 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.

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

coreordinary 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

corecompiling 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)

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

coreordinary 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

corecompiling primitive

*EMIT( char -- )

print the char-value on stack to stdout

coreordinary 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)

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

simulate:
: EXECUTE >R EXIT ;

coreordinary 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 ;

corecompiling primitive

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

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

coreordinary 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 if the word had
been immediate, -1 otherwise.

coreordinary 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

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.

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

coreordinary primitive

*KEY( -- char )

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

coreordinary primitive

*LEAVE( -- )

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

coreordinary 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:

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

corecompiling 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.

corecompiling primitive

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

does a bitwise left-shift on value

coreordinary primitive

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

multiply and return a double-cell result

coreordinary primitive

*MAX( a b -- c )

return the maximum of a and b

coreordinary primitive

*MIN( a b -- c )

return the minimum of a and b

coreordinary primitive

*MOD( a b -- c )

return the module of "a mod b"

coreordinary primitive

*MOVE( from to length -- )

memcpy an area

coreordinary primitive

*NEGATE( value -- value' )

return the arithmetic negative of the (signed) cell

simulate: : NEGATE -1 * ;

coreordinary primitive

*OR( a b -- ab )

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

coreordinary primitive

*OVER( a b -- a b a )

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

coreordinary 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)

corecompiling 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 QUERYand EVALUATE (otherwise known as INTERPRET )
- in pfe it is defined as a THROW ,

: QUIT -56 THROW ;

coreordinary primitive

*R>( R: a -- a R: )

get back a value from the return-stack that had been saved
there using >R . This is the traditional form of a local
var space that could be accessed with R@ later. If you
need more local variables you should have a look at LOCALS|which does grab some space from the return-stack too, but names
them the way you like.

coreordinary primitive

*R@( R: a -- a R: a )

fetch the (upper-most) value from the return-stack that had
been saved there using >R - This is the traditional form of a local
var space. If you need more local variables you should have a
look at LOCALS| , see also >R and R> . Without LOCALS-EXT
there are useful words like 2R@R'@R"@R!

coreordinary primitive

*RECURSE( ? -- ? )

when creating a colon word the name of the currently-created
word is smudged, so that you can redefine a previous word
of the same name simply by using its name. Sometimes however
one wants to recurse into the current definition instead of
calling the older defintion. The RECURSE word does it
exactly this.

traditionally the following code had been in use:
: GREAT-WORD [ UNSMUDGE ] DUP . 1- ?DUP IF GREAT-WORD THEN ;
now use
: GREAT-WORD DUP . 1- ?DUP IF RECURSE THEN ;

rotates the three uppermost values on the stack,
the other direction would be with -ROT - please
have a look at LOCALS| and VAR that can avoid
its use.

coreordinary primitive

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

does a bitwise logical right-shift on value
(ie. the value is considered to be unsigned)

coreordinary primitive

*S"( [string] -- string-address string-length)

if compiling then place the string into the currently
compiled word and on execution the string pops up
again as a double-cell value yielding the string's address
and length. To be most portable this is the word to be
best being used. Compare with C" and non-portable "

corecompiling primitive

*S>D( a -- a,a' )

signed extension of a single-cell value to a double-cell value

coreordinary primitive

*SIGN( a -- )

put the sign of the value into the hold-space, this is
the forth-style output formatting, see HOLD

CREATE a new variable, so that everytime the variable is
name, the address is returned for using with @ and !- be aware that in FIG-forth VARIABLE did take an argument
being the initial value. ANSI-forth does different here.

coredefining primitive

*WHILE( cond -- )

middle part of a BEGIN .. WHILE .. REPEATcontrol-loop - if cond is true the code-piece up to REPEATis executed which will then jump back to BEGIN - and if
the cond is null then WHILE will branch to right after
the REPEAT(compare with UNTIL that forms a BEGIN .. UNTIL loop)

corecompiling primitive

*WORD( delimiter-char -- here-addr )

read the next SOURCE section (thereby moving >IN ) up
to the point reaching $delimiter-char - the text is placed
at HERE - where you will find a counted string. You may
want to use PARSE instead.

coreordinary primitive

*XOR( a b -- ab )

return the bitwise-or of the two arguments - it may be unsafe
use it on logical values. beware.

coreordinary primitive

*[( -- )

leave compiling mode - often used inside of a colon-definition
to make fetch some very constant value and place it into the
currently compiled colon-defintion with , or LITERAL- the corresponding unleave word is ]

coreimmediate primitive

*[']( [name] -- ) immediate

will place the execution token of the following word into
the dictionary. See ' for non-compiling variant.

corecompiling primitive

*[CHAR]( [word] -- char )

in compile-mode, get the (ascii-)value of the first charachter
in the following word and compile it as a literal so that it
will pop up on execution again. See CHAR and forth-83 ASCII

corecompiling primitive

*]( -- )

enter compiling mode - often used inside of a colon-definition
to end a previous [ - you may find a , or LITERALnearby in example texts.

coreordinary primitive

core extension words

[ANS] #TIB

no special info, see general notes

corethreadstate variable

*.(( [message] -- )

print the message to the screen while reading a file. This works
too while compiling, so you can whatch the interpretation/compilation
to go on. Some Forth-implementations won't even accept a ." message"
outside compile-mode while the (current) pfe does.

coreimmediate primitive

*.R( val prec -- )

print with precision - that is to fill
a field of the give prec-with with
right-aligned number from the converted value

coreordinary primitive

*0<>( value -- cond )

returns a logical-value saying if the value was not-zero.
This is most useful in turning a numerical value into a
boolean value that can be fed into bitwise words like
AND and XOR - a simple IF or WHILE doesn't
need it actually.

pop back a double-cell value from the return-stack, see R>and the earlier used 2>R

coreordinary primitive

*2R@( R: a,a -- a,a R: a,a )

fetch a double-cell value from the return-stack, that had been
previously been put there with 2>R - see R@ for single value.
This can partly be a two-cell LOCALS| value, without LOCALS-EXT
there are alos other useful words like 2R!R'@R"@

coreordinary primitive

*:NONAME( -- cs.value )

start a colon nested-word but do not use CREATE - so no name
is given to the colon-definition that follows. When the definition
is finished at the corresponding ; the start-address (ie.
the execution token) can be found on the outer cs.stack that may
be stored used elsewhere then.

in compiling mode place the following string in the current
word and return the address of the counted string on execution.
(in exec-mode use a POCKET and leave the bstring-address of it),
see S" string" and the non-portable " string"

corecompiling primitive

*CASE( comp-value -- comp-value )

start a CASE construct that ends at ENDCASEand compares the value on stack at each OF place

corecompiling primitive

*COMPILE,( xt -- )

place the execution-token on stack into the dictionary - in
traditional forth this is not even the least different than
a simple , but in call-threaded code there's a big
difference - so COMPILE, is the portable one. Unlike
COMPILE , [COMPILE] and POSTPONE this word does
not need the xt to have actually a name, see :NONAME

compare the case-value placed lately with the comp-value
being available since CASE - if they are equal run the
following code-portion up to ENDOF after which the
case-construct ends at the next ENDCASE

corecompiling primitive

*PAD( -- addr )

transient buffer region

coreordinary primitive

*PARSE( delim-char -- buffer-start buffer-count )

parse a piece of input (not much unlike WORD) and place
it into the given buffer. The difference with word is
also that WORD would first skip any delim-char while
PARSE does not and thus may yield that one. In a newer
version, PARSE will not copy but just return the word-span
being seen in the input-buffer - therefore a transient space.

coreordinary primitive

*PICK( n -- value )

pick the nth value from under the top of stack and push it
note that

0 PICK -> DUP 1 PICK -> OVER

coreordinary primitive

*QUERY( -- )

source input: read from terminal using _accept_ with the
returned string to show up in TIB of /TIB size.

coreordinary primitive

*REFILL( -- flag )

try to get a new input line from the SOURCE and set
>IN accordingly. Return a flag if sucessful, which is
always true if the current input comes from a
terminal and which is always false if the current input
comes from EVALUATE - and may be either if the
input comes from a file

CREATE a word and initialize it with value. Using it
later will push the value back onto the stack. Compare with
VARIABLE and CONSTANT - look also for LOCALS| and
VAR

coredefining primitive

*WITHIN( a b c -- cond )

a widely used word, returns ( b <= a a < c ) so
that is very useful to check an index a of an array
to be within range b to c

coreordinary primitive

*[COMPILE]( [word] -- )

while compiling the next word will be place in the currently
defined word no matter if that word is immediate (like IF )
- compare with COMPILE and POSTPONE

coreimmediate primitive

*\( [comment] -- )

eat everything up to the next end-of-line so that it is
getting ignored by the interpreter.

coreimmediate primitive

FORTH

*"( [string] -- bstring ) or perhaps ( [..] -- str-ptr str-len )

This is the non-portable word which is why the ANSI-committee
on forth has created the two other words, namely S" and C" ,
since each implementation (and in pfe configurable) uses another
runtime behaviour. FIG-forth did return bstring which is the configure
default for pfe.

coreimmediate synonym

*PARSE-WORD( "chars" -- c-addr u )

the ANS'94 standard describes this word in a comment
under PARSE, section A.6.2.2008 - quote:

Skip leading spaces and parse name delimited by a space. c-addr
is the address within the input buffer and u is the length of the
selected string. If the parse area is empty, the resulting string
has a zero length.

note that ans'forth does not define <BUILDS and
it suggests to use CREATE directly.

... if you want to write FIG-programs in pure pfe then you have
to use CREATE: to get the FIG-like meaning of CREATE whereas
the ans-forth CREATE is the same as <BUILDS

: <BUILDS BL WORD HEADER DOCREATE A, 0 A, ;

coredefining primitive

FORTH CFA'

no special info, see general notes

coreordinary primitive

[ANS]

*CREATE( 'name' -- )

create a name with runtime ((VAR)) so that everywhere the name is used
the pfa of the name's body is returned. This word is not immediate and
according to the ANS Forth documents it may get directly used in the
first part of a DOES> defining word - in traditional forth systems
the word <BUILDS was used for that and CREATE was defined to be
the first part of a VARIABLE word (compare with CREATE: and the
portable expression 0BUFFER:)

coreforthword synonym

*'( 'name' -- xt )

return the execution token of the following name. This word
is _not_ immediate and may not do what you expect in
compile-mode. See ['] and '> - note that in FIG-forth
the word of the same name had returned the PFA (not the CFA)
and was immediate/smart, so beware when porting forth-code
from FIG-forth to ANSI-forth.

coreforthword synonym

EXTENSIONS

*(MARKER)( str-ptr str-len -- )

create a named marker that you can use to FORGET ,
running the created word will reset the dict/order variables
to the state at the creation of this name.