PFE 0.33.70

generated
(C) Guido U. Draheim
guidod@gmx.de

Core

words + extensions

---

!( value some-cell* -- | value addr* -- [?] ) [ANS]  => "[ANS] FORTH"

store value at addr (sizeof CELL)

primitive code = [p4_store]

---

#( n,n -- n,n' ) [ANS]  => "[ANS] FORTH"

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 #>

primitive code = [p4_sh]

---

#>( n,n -- hold-str-ptr hold-str-len ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_sh_greater]

---

#S( n,n -- 0,0 ) [ANS]  => "[ANS] FORTH"

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 #>

primitive code = [p4_sh_s]

---

(( 'comment<closeparen>' -- ) [ANS]  => "[ANS] FORTH"

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

immediate code = [p4_paren]

---

*( a# b# -- mul-a#' | a b -- mul-a' [??] ) [ANS]  => "[ANS] FORTH"

return the multiply of the two args

primitive code = [p4_star]

---

*/( a# b# c# -- scale-a#' | a b c -- scale-a' [??] ) [ANS]  => "[ANS] FORTH"

regard the b/c as element Q - this word has an advantage over the sequence of * and / by using an intermediate double-cell value

primitive code = [p4_star_slash]

---

*/MOD( a# b# c# -- div-a# mod-a# | a b c -- div-a mod-a [??] ) [ANS]  => "[ANS] FORTH"

has an adavantage over the sequence of * and /MOD by using an intermediate double-cell value.

primitive code = [p4_star_slash_mod]

---

+( a* b# -- a*' | a# b* -- b*' | a# b# -- a#' | a b -- a' [??] ) [ANS]  => "[ANS] FORTH"

return the sum of the two args

primitive code = [p4_plus]

---

+!( value# some-cell* -- | value some* -- [?] ) [ANS]  => "[ANS] FORTH"

add val to the value found in addr

  simulate:
    : +! TUCK @ + SWAP ! ;
  

primitive code = [p4_plus_store]

---

+LOOP( increment# R: some,loop -- ) [ANS]  => "[ANS] FORTH"

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

compiling word = [p4_plus_loop]

---

,( value* -- | value# -- | value -- [?] ) [ANS]  => "[ANS] FORTH"

store the value in the dictionary

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

primitive code = [p4_comma]

---

-( a* b# -- a*' | a# b* -- b*' | a# b# -- a#' | a* b* -- diff-b#' | a b -- a' [??] ) [ANS]  => "[ANS] FORTH"

return the difference of the two arguments

primitive code = [p4_minus]

---

.( value# -- | value* -- [?] | value -- [??] ) [ANS]  => "[ANS] FORTH"

print the numerical value to stdout - uses BASE

primitive code = [p4_dot]

---

."( [string<">] -- ) [ANS]  => "[ANS] FORTH"

print the string to stdout

compiling word = [p4_dot_quote]

---

/( a# b# -- a#' | a b -- a' [???] ) [ANS]  => "[ANS] FORTH"

return the quotient of the two arguments

primitive code = [p4_slash]

---

/MOD( a# b# -- div-a#' mod-a#' | a b -- div-a' mod-a' [??] ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_slash_mod]

---

0<( value -- test-flag ) [ANS]  => "[ANS] FORTH"

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

  simulate:
   : 0< 0 < ;
  

primitive code = [p4_zero_less]

---

0=( 0 -- test-flag! | value! -- 0 | value -- test-flag ) [ANS]  => "[ANS] FORTH"

return a flag that is true if val is just zero

  simulate:
   : 0= 0 = ;
  

primitive code = [p4_zero_equal]

---

1+( value -- value' ) [ANS]  => "[ANS] FORTH"

return the value incremented by one

  simulate:
   : 1+ 1 + ;
  

primitive code = [p4_one_plus]

---

1-( value -- value' ) [ANS]  => "[ANS] FORTH"

return the value decremented by one

  simulate:
    : 1- 1 - ;
  

primitive code = [p4_one_minus]

---

2!( x,x variable* -- ) [ANS]  => "[ANS] FORTH"

double-cell store

primitive code = [p4_two_store]

---

2*( a# -- a#' | a -- a' [??] ) [ANS]  => "[ANS] FORTH"

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

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

primitive code = [p4_two_star]

---

2/( a# -- a#' | a -- a' [??] ) [ANS]  => "[ANS] FORTH"

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

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

primitive code = [p4_two_slash]

---

2@( variable* -- x,x ) [ANS]  => "[ANS] FORTH"

double-cell fetch

primitive code = [p4_two_fetch]

---

2DROP( a b -- ) [ANS]  => "[ANS] FORTH"

double-cell drop, also used to drop two items

primitive code = [p4_two_drop]

---

2DUP( a,a -- a,a a,a ) [ANS]  => "[ANS] FORTH"

double-cell duplication, also used to duplicate two items

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

primitive code = [p4_two_dup]

---

2OVER( a,a b,b -- a,a b,b a,a ) [ANS]  => "[ANS] FORTH"

double-cell over, see OVER and 2DUP

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

primitive code = [p4_two_over]

---

2SWAP( a,a b,b -- b,b a,a ) [ANS]  => "[ANS] FORTH"

double-cell swap, see SWAP and 2DUP

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

primitive code = [p4_two_swap]

---

;( -- ) [ANS] [EXIT] [END]  => "[ANS] FORTH"

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

compiling word = [p4_semicolon]

---

<( a* b* -- test-flag | a# b# -- test-flag | a b -- test-flag [?] ) [ANS]  => "[ANS] FORTH"

return a flag telling if a is lower than b

primitive code = [p4_less_than]

---

<#( -- ) [ANS]  => "[ANS] FORTH"

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.

primitive code = [p4_less_sh]

---

=( a* b* -- test-flag | a# b# -- test-flag | a b -- test-flag [?] ) [ANS]  => "[ANS] FORTH"

return a flag telling if a is equal to b

primitive code = [p4_equals]

---

>( a* b* -- test-flag | a# b# -- test-flag | a b -- test-flag [?] ) [ANS]  => "[ANS] FORTH"

return a flag telling if a is greater than b

primitive code = [p4_greater_than]

---

>BODY( some-xt* -- some-body* ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_to_body]

---

>NUMBER( a,a str-ptr str-len -- a,a' str-ptr' str-len) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_to_number]

---

>R( value -- R: value ) [ANS]  => "[ANS] FORTH"

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

compiling word = [p4_to_r]

---

?DUP( 0 -- 0 | value! -- value! value! | value -- 0 | value! value! ) [ANS]  => "[ANS] FORTH"

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 ;
  

primitive code = [p4_Q_dup]

---

@( value* -- value ) [ANS]  => "[ANS] FORTH"

fetch the value from the variables address

primitive code = [p4_fetch]

---

ABS( value# -- value#' ) [ANS]  => "[ANS] FORTH"

return the absolute value

primitive code = [p4_abs]

---

ACCEPT( buffer-ptr buffer-max -- buffer-len ) [ANS]  => "[ANS] FORTH"

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.

primitive code = [p4_accept]

---

ALIGN( -- ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_align]

---

ALIGNED( addr -- addr' ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_aligned]

---

ALLOT( allot-count -- ) [ANS]  => "[ANS] FORTH"

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.

primitive code = [p4_allot]

---

AND( value mask -- value' ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_and]

---

BEGIN( -- ) [ANS] [LOOP]  => "[ANS] FORTH"

start a control-loop, see WHILE and REPEAT

compiling word = [p4_begin]

---

C!( value# variable#* -- | value# variable* [?] ) [ANS]  => "[ANS] FORTH"

store the byte-value at address, see => !

primitive code = [p4_c_store]

---

C,( value# -- ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_c_comma]

---

C@( value#* -- value# | value* -- value# [?] ) [ANS]  => "[ANS] FORTH"

fetch a byte-value from the address, see @

primitive code = [p4_c_fetch]

---

CELL+( value -- value' ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_cell_plus]

---

CELLS( value# -- value#' ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_cells]

---

CHAR( 'word' -- char# ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_char]

---

CHAR+( value -- value' ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_char_plus]

---

CHARS( value# -- value#' ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_chars]

---

COUNT( string-bstr* -- string-ptr' string-len | some* -- some*' some-len [?] ) [ANS]  => "[ANS] FORTH"

usually before calling TYPE

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

primitive code = [p4_count]

---

CR( -- ) [ANS]  => "[ANS] FORTH"

print a carriage-return/new-line on stdout

primitive code = [p4_cr]

---

DECIMAL( -- ) [ANS]  => "[ANS] FORTH"

set the BASE to 10

  simulate:
    : DECIMAL 10 BASE ! ;
  

primitive code = [p4_decimal]

---

DEPTH( -- depth# ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_depth]

---

DO( end# start# | end* start* -- R: some,loop ) [ANS] [LOOP]  => "[ANS] FORTH"

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

compiling word = [p4_do]

---

DOES>( -- does* ) [ANS] [END] [NEW]  => "[ANS] FORTH"

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)

compiling word = [p4_does]

---

DROP( a -- ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_drop]

---

DUP( a -- a a ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_dup]

---

ELSE( -- ) [HIDDEN]  => "[ANS] FORTH"

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

compiling word = [p4_else]

---

EMIT( char# -- ) [ANS]  => "[ANS] FORTH"

print the char-value on stack to stdout

primitive code = [p4_emit]

---

ENVIRONMENT?( name-ptr name-len -- 0 | ?? name-flag! ) [ANS]  => "[ANS] FORTH"

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 ;
  

primitive code = [p4_environment_Q_core]

---

EVALUATE( str-ptr str-len -- ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_evaluate]

---

EXECUTE( some-xt* -- ??? ) [ANS]  => "[ANS] FORTH"

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

  simulate:
   : EXECUTE >R EXIT ;
  

primitive code = [p4_execute]

---

EXIT( -- ) [ANS] [EXIT]  => "[ANS] FORTH"

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 ;

compiling word = [p4_exit]

---

FILL( mem-ptr mem-len char# -- ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_fill]

---

FIND( name-bstr* -- name-bstr* 0 | name-xt* -1|1 ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_find]

---

FM/MOD( n1,n1# n2# -- div-n1# mod-n1# ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_f_m_slash_mod]

---

HERE( -- here* ) [ANS]  => "[ANS] FORTH"

used with WORD and many compiling words

  simulate:   : HERE DP @ ;
  

primitive code = [p4_here]

---

HOLD( char# -- ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_hold]

---

I( R: some,loop -- S: i# ) [ANS]  => "[ANS] FORTH"

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

compiling word = [p4_i]

---

IF( value -- ) [ANS]  => "[ANS] FORTH"

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.

compiling word = [p4_if]

---

IMMEDIATE( -- ) [ANS]  => "[ANS] FORTH"

make the LATEST word immediate, see also CREATE

primitive code = [p4_immediate]

---

INVERT( value# -- value#' ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_invert]

---

J( R: some,loop -- S: j# ) [ANS]  => "[ANS] FORTH"

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

compiling word = [p4_j]

---

KEY( -- char# ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_key]

---

LEAVE( R: some,loop -- R: some,loop ) [ANS]  => "[ANS] FORTH"

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

compiling word = [p4_leave]

---

LITERAL( C: value -- S: value ) [ANS]  => "[ANS] FORTH"

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)

compiling word = [p4_literal]

---

LOOP( R: some,loop -- ) [ANS] [REPEAT]  => "[ANS] FORTH"

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.

compiling word = [p4_loop]

---

LSHIFT( value# shift-count -- value#' ) [ANS]  => "[ANS] FORTH"

does a bitwise left-shift on value

primitive code = [p4_l_shift]

---

M*( a# b# -- a,a#' ) [ANS]  => "[ANS] FORTH"

multiply and return a double-cell result

primitive code = [p4_m_star]

---

MAX( a# b# -- a#|b# | a* b* -- a*|b* | a b -- a|b [??] ) [ANS]  => "[ANS] FORTH"

return the maximum of a and b

primitive code = [p4_max]

---

MIN( a# b# -- a#|b# | a* b* -- a*|b* | a b -- a|b [??] ) [ANS]  => "[ANS] FORTH"

return the minimum of a and b

primitive code = [p4_min]

---

MOD( a# b# -- mod-a# | a b# -- mod-a# [??] ) [ANS]  => "[ANS] FORTH"

return the module of "a mod b"

primitive code = [p4_mod]

---

MOVE( from-ptr to-ptr move-len -- ) [ANS]  => "[ANS] FORTH"

p4_memcpy an area

primitive code = [p4_move]

---

NEGATE( value# -- value#' ) [ANS]  => "[ANS] FORTH"

return the arithmetic negative of the (signed) cell

  simulate:   : NEGATE -1 * ;
  

primitive code = [p4_negate]

---

OR( a b# -- a' | a# b -- b' | a b -- a' [??] ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_or]

---

OVER( a b -- a b a ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_over]

---

POSTPONE( [word] -- ) [ANS]  => "[ANS] FORTH"

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)

compiling word = [p4_postpone]

---

QUIT( -- ) [EXIT]  => "[ANS] FORTH"

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 ;
  

primitive code = [p4_quit]

---

R>( R: a -- a R: ) [ANS]  => "[ANS] FORTH"

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.

compiling word = [p4_r_from]

---

R@( R: a -- a R: a ) [ANS]  => "[ANS] FORTH"

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!

compiling word = [p4_r_fetch]

---

RECURSE( ? -- ? ) [ANS]  => "[ANS] FORTH"

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 ;
  

immediate code = [p4_recurse]

---

REPEAT( -- ) [ANS] [REPEAT]  => "[ANS] FORTH"

ends an unconditional loop, see BEGIN

compiling word = [p4_repeat]

---

ROT( a b c -- b c a ) [ANS]  => "[ANS] FORTH"

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.

primitive code = [p4_rot]

---

RSHIFT( value# shift-count# -- value#' ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_r_shift]

---

S"( [string<">] -- string-ptr string-len) [ANS]  => "[ANS] FORTH"

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 "

compiling word = [p4_s_quote]

---

S>D( a# -- a,a#' | a -- a,a#' [??] ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_s_to_d]

---

SIGN( a# -- ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_sign]

---

SM/REM( a,a# b# -- div-a# rem-a# ) [ANS]  => "[ANS] FORTH"

see /MOD or FM/MOD or UM/MOD or SM/REM

primitive code = [p4_s_m_slash_rem]

---

SOURCE( -- buffer* IN-offset# ) [ANS]  => "[ANS] FORTH"

the current point of interpret can be gotten through SOURCE. The buffer may flag out TIB or BLK or a FILE and IN gives you the offset therein. Traditionally, if the current SOURCE buffer is used up, REFILL is called that asks for another input-line or input-block. This scheme would have made it impossible to stretch an [IF] ... [THEN] over different blocks, unless [IF] does call REFILL

primitive code = [p4_source]

---

SPACE( -- ) [ANS]  => "[ANS] FORTH"

print a single space to stdout, see SPACES

  simulate:    : SPACE  BL EMIT ;
  

primitive code = [p4_space]

---

SPACES( space-count -- ) [ANS]  => "[ANS] FORTH"

print n space to stdout, actually a loop over n calling SPACE , but the implemenation may take advantage of printing chunks of spaces to speed up the operation.

primitive code = [p4_spaces]

---

SWAP( a b -- b a ) [ANS]  => "[ANS] FORTH"

exchanges the value on top of the stack with the value beneath it

primitive code = [p4_swap]

---

THEN( -- ) [ANS]  => "[ANS] FORTH"

does resolve a branch coming from either IF or ELSE

compiling word = [p4_then]

---

TYPE( string-ptr string-len -- ) [ANS]  => "[ANS] FORTH"

prints the string-buffer to stdout, see COUNT and EMIT

primitive code = [p4_type]

---

U.( value# -- | value -- [?] ) [ANS]  => "[ANS] FORTH"

print unsigned number to stdout

primitive code = [p4_u_dot]

---

U<( a b -- test-flag ) [ANS]  => "[ANS] FORTH"

unsigned comparison, see <

primitive code = [p4_u_less_than]

---

UM*( a# b# -- a,a#' ) [ANS]  => "[ANS] FORTH"

unsigned multiply returning double-cell value

primitive code = [p4_u_m_star]

---

UM/MOD( a,a# b# -- div-a#' mod-a#' ) [ANS]  => "[ANS] FORTH"

see /MOD and SM/REM

primitive code = [p4_u_m_slash_mod]

---

UNLOOP( R: some,loop -- ) [ANS]  => "[ANS] FORTH"

drop the DO .. LOOP runtime variables from the return-stack, usually used just in before an EXIT call. Using this multiple times can unnest multiple nested loops.

compiling word = [p4_unloop]

---

UNTIL( test-flag -- ) [ANS] [REPEAT]  => "[ANS] FORTH"

ends an control-loop, see BEGIN and compare with WHILE

compiling word = [p4_until]

---

WHILE( test-flag -- ) [ANS]  => "[ANS] FORTH"

middle part of a BEGIN .. WHILE .. REPEAT control-loop - if cond is true the code-piece up to REPEAT is 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)

compiling word = [p4_while]

---

WORD( delimiter-char# -- here* ) [ANS]  => "[ANS] FORTH"

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.

primitive code = [p4_word]

---

XOR( a# b# -- a#' ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_xor]

---

[( -- ) [ANS]  => "[ANS] FORTH"

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 ]

immediate code = [p4_left_bracket]

---

[']( [name] -- name-xt* ) [ANS]  => "[ANS] FORTH"

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

compiling word = [p4_bracket_tick]

---

[CHAR]( [word] -- char# ) [ANS]  => "[ANS] FORTH"

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

compiling word = [p4_bracket_char]

---

]( -- ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_right_bracket]

---

.(( [message<closeparen>] -- ) [ANS]  => "[ANS] FORTH"

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.

immediate code = [p4_dot_paren]

---

.R( value# precision# -- | value precision# -- [??] ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_dot_r]

---

0<>( 0 -- 0 | value! -- value-flag! | value -- value-flag ) [ANS]  => "[ANS] FORTH"

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.

primitive code = [p4_zero_not_equals]

---

0>( 0 -- 0 | value! -- value-flag! | value -- value-flag ) [ANS]  => "[ANS] FORTH"

return value greater than zero

  simulate:    : 0> 0 > ;
  

primitive code = [p4_zero_greater]

---

2>R( a,a -- R: a,a ) [ANS]  => "[ANS] FORTH"

save a double-cell value onto the return-stack, see >R

compiling word = [p4_two_to_r]

---

2R>( R: a,a -- a,a R: ) [ANS]  => "[ANS] FORTH"

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

compiling word = [p4_two_r_from]

---

2R@( R: a,a -- a,a R: a,a ) [ANS]  => "[ANS] FORTH"

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"@

compiling word = [p4_two_r_fetch]

---

<>( a b -- a-flag ) [ANS]  => "[ANS] FORTH"

return true if a and b are not equal, see =

primitive code = [p4_not_equals]

---

?DO( end# start# | end* start* -- R: some,loop ) [ANS]  => "[ANS] FORTH"

start a control-loop just like DO - but don't execute atleast once. Instead jump over the code-piece if the loop's variables are not in a range to allow any loop.

compiling word = [p4_Q_do]

---

AGAIN( -- ) [ANS] [REPEAT]  => "[ANS] FORTH"

ends an infinite loop, see BEGIN and compare with WHILE

compiling word = [p4_again]

---

C"( [string<">] -- string-bstr* ) [ANS]  => "[ANS] FORTH"

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"

compiling word = [p4_c_quote]

---

CASE( value -- value ) [ANS]  => "[ANS] FORTH"

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

compiling word = [p4_case]

---

COMPILE,( some-xt* -- ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_compile_comma]

---

CONVERT( a,a# string-bstr* -- a,a# a-len# ) [ANS] [OLD]  => "[ANS] FORTH"

digit conversion, obsolete, superseded by >NUMBER

primitive code = [p4_convert]

---

ENDCASE( value -- ) [ANS]  => "[ANS] FORTH"

ends a CASE construct that may surround multiple sections of OF ... ENDOF code-portions. The ENDCASE has to resolve the branches that are necessary at each ENDOF to point to right after ENDCASE

compiling word = [p4_endcase]

---

ENDOF( -- ) [ANS]  => "[ANS] FORTH"

resolve the branch need at the previous OF to mark a code-piece and leave with an unconditional branch at the next ENDCASE (opened by CASE )

compiling word = [p4_endof]

---

ERASE( buffer-ptr buffer-len -- ) [ANS]  => "[ANS] FORTH"

fill an area will zeros.

  2000 CREATE DUP ALLOT ERASE
  

primitive code = [p4_erase]

---

EXPECT( str-ptr str-len -- ) [ANS] [OLD]  => "[ANS] FORTH"

input handling, see WORD and PARSE and QUERY the input string is placed at str-adr and its length

  in => SPAN - this word is superceded by => ACCEPT
  

primitive code = [p4_expect]

---

HEX( -- ) [ANS]  => "[ANS] FORTH"

set the input/output BASE to hexadecimal

  simulate:        : HEX 16 BASE ! ;
  

primitive code = [p4_hex]

---

NIP( a b -- b ) [ANS]  => "[ANS] FORTH"

drop the value under the top of stack, inverse of TUCK

  simulate:        : NIP SWAP DROP ;
  

primitive code = [p4_nip]

---

OF( value test -- value ) [ANS]  => "[ANS] FORTH"

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

compiling word = [p4_of]

---

PAD( -- pad* ) [ANS]  => "[ANS] FORTH"

transient buffer region

primitive code = [p4_pad]

---

PARSE( delim-char# -- buffer-ptr buffer-len ) [ANS]  => "[ANS] FORTH"

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.

primitive code = [p4_parse]

---

PICK( value ...[n-1] n -- value ...[n-1] value ) [ANS]  => "[ANS] FORTH"

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

    0 PICK -> DUP         1 PICK -> OVER
  

primitive code = [p4_pick]

---

QUERY( -- )  => "[ANS] FORTH"

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

primitive code = [p4_query]

---

REFILL( -- refill-flag ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_refill]

---

RESTORE-INPUT( input...[input-len] input-len -- ) [ANS]  => "[ANS] FORTH"

inverse of SAVE-INPUT

primitive code = [p4_restore_input]

---

ROLL( value ...[n-1] n -- ...[n-1] value ) [ANS]  => "[ANS] FORTH"

the extended form of ROT

     2 ROLL -> ROT
  

primitive code = [p4_roll]

---

SAVE-INPUT( -- input...[input-len] input-len ) [ANS]  => "[ANS] FORTH"

fetch the current state of the input-channel which may be restored with RESTORE-INPUT later

primitive code = [p4_save_input]

---

TO( value [name] -- ) [ANS]  => "[ANS] FORTH"

set the parameter field of name to the value, this is used to change the value of a VALUE and it can be also used to change the value of LOCALS|

compiling word = [p4_to]

---

TUCK( a b -- b a b ) [ANS]  => "[ANS] FORTH"

shove the top-value under the value beneath. See OVER and NIP

  simulate:    : TUCK  SWAP OVER ;
  

primitive code = [p4_tuck]

---

U.R( value# precision# -- ) [ANS]  => "[ANS] FORTH"

print right-aligned in a prec-field, treat value to be unsigned as opposed to => .R

primitive code = [p4_u_dot_r]

---

U>( a b -- a-flag ) [ANS]  => "[ANS] FORTH"

unsigned comparison of a and b, see >

primitive code = [p4_u_greater_than]

---

UNUSED( -- unused-len ) [ANS]  => "[ANS] FORTH"

return the number of cells that are left to be used above HERE

primitive code = [p4_unused]

---

WITHIN( a# b# c# -- a-flag | a* b* c* -- a-flag ) [ANS]  => "[ANS] FORTH"

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

primitive code = [p4_within]

---

[COMPILE]( [word] -- ) [ANS]  => "[ANS] FORTH"

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

immediate code = [p4_bracket_compile]

---

\( [comment<eol>] -- ) [ANS]  => "[ANS] FORTH"

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

immediate code = [p4_backslash]

---

PARSE-WORD( "chars" -- buffer-ptr buffer-len ) [ANS]  => "[ANS] FORTH"

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.

If both PARSE and PARSE-WORD are present, the need for WORD is largely eliminated. Note that Forth200x calls it PARSE-NAME and clarifies that non-empty whitespace-only input is returned as a zero length string as well.

primitive code = [p4_parse_word]

---

PARSE-NAME( "chars" -- buffer-ptr buffer-len ) [Forth200x]  => "[ANS] FORTH"

This word is identical with the PFE implementation PARSE-WORD

The only difference between the 1994 ANS-Forth PARSE-WORD and the 2005 Forth200x PARSE-NAME is in the explicit condition of whitespace-only - while 1994 reads "If the parse area is empty, the resulting string has a zero length." you will find that the 2005 version says "If the parse area is empty or contains only white space, the resulting string has length zero."

primitive code = [p4_parse_word]

---

CFA'( 'name' -- name-xt* ) [FTH]  => "[ANS] FORTH"

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 ' had returned the PFA (not the CFA) and therefore this word was introduced being the SYNONYM of the ans-like word '

primitive code = [p4_tick]

---

STACK-CELLS  => "ENVIRONMENT"

(no description)

primitive code = [p__stack_cells]

---

RETURN-STACK-CELLS  => "ENVIRONMENT"

(no description)

primitive code = [p__return_stack_cells]