PFE 0.33.71

Homepage
SourceForge
Download
Documentation
-Overview
-The PFE Manual
old manual / (book)
-ChangeLog
-Authors
-License (LGPL)
-Wordsets / (book)
-Functions .. (book)
-Dp of ANS Forth
-The 4thTutor
-Forthprimer.pdf
- Old Wordsets
- Old Words List
Forth Links
* Forth Repository
* Taygeta Compilation
* TinyBoot FirmWare
* FiCL, Free Forth
* Research Vienna
* Research Bournemouth
* zForth WebRing
Other Links
* Tektronix/MPT
* Forth Org. (FIG)
* Forth Inc.
* MPE Ltd. Forths
* SF Win32Forth
* PD Win32Forth
* Neil Bawd

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]