PFE - Portable Forth Environment - pfe Forth Wordsets

  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]