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 | ## Compatibility Miscellaneous words `ok``` => `"FORTH"` (no description) primitive code = [p4_ok] `COLD``( -- )``[FTH]` => `"FORTH"` cold abort - reinitialize everything and go to `QUIT` routine ... this routine is implemented as a warm-boot in pfe.
        : COLD [ ALSO ENVIRONMENT ] EMPTY SCRIPT-FILE INCLUDED QUIT ;
  primitive code = [p4_cold] `LIT``` => `"FORTH"` (no description) primitive code = [p4_literal_execution] `.LINE``( line# block# -- )``[FTH]` => `"FORTH"` primitive code = [p4_dot_line] `UD.R``( x,x# r# -- )``[FTH]` => `"FORTH"` primitive code = [p4_u_d_dot_r] `UD.``( x,x# -- )``[FTH]` => `"FORTH"` see also `UD`.R primitive code = [p4_u_d_dot] `ID.``( some-nfa* -- )``[FTH]` => `"FORTH"` print the name-field pointed to by the nfa-argument. a synonym for .NAME - but this word is more portable due its heritage from fig-forth. in fig-forth the name-field is effectivly a bstring with some flags, so the nfa's count has to be masked out, e.g.
        : .NAME COUNT 32 AND TYPE ;
  in other pfe configurations, the name might not contain the flags it it just a counted string - and there may be even more possibilities.
        : .NAME COUNT TYPE ;
  you should more and more convert your code to use the sequence `NAME>STRING` `TYPE` which is widely regarded as the better variant. primitive code = [p4_id_dot] `-ROLL``( x...[n-1] y n# -- y x...[n-1] | num# -- )``[FTH]` => `"FORTH"` the inverse of `ROLL` primitive code = [p4_dash_roll] `RANDOM``( n# -- random# )``[FTH]` => `"FORTH"` returns random number with 0 <= n2 < n1)
        : RANDOM ?DUP IF _random SWAP MOD ELSE _random THEN ;
  primitive code = [p4_random] `SRAND``( seed# -- )``[FTH]` => `"FORTH"` primitive code = [p4_srand] `(UNDER+)``( n1 n2 -- n1+n2 n2 )``[FTH]` => `"FORTH"` quicker than
        : (UNDER+) TUCK + SWAP ; or : (UNDER+) DUP UNDER+ ;
  primitive code = [p4_under_plus] `+TO``( val [name] -- )``[FTH]` => `"FORTH"` add the val to the named `VALUE` or `LOCALS|` value compiling word = [p4_plus_to] `BUILD-ARRAY``( x#...[dim] dim# -- memsize# )``[FTH]` => `"FORTH"` writes X, n1, ... nX into the dictionary - returns product n1 * n2 * ... * nX primitive code = [p4_build_array] `ACCESS-ARRAY``( x#...[dim#] array* --- array* value# )``[FTH]` => `"FORTH"` see `BUILD-ARRAY` primitive code = [p4_access_array] `.STATUS``( -- )``[FTH]` => `"FORTH"` display internal variables
        : .STATUS .VERSION .CVERSION .MEMORY .SEARCHPATHS .DICTVARS .REGSUSED ;
  primitive code = [p4_dot_status] `SOURCE-LINE``( -- source-line# )``[FTH]` => `"FORTH"` if `SOURCE` is from `EVALUATE` (or `QUERY` ) then the result is 0 else the line-numbers start from 1 primitive code = [p4_source_line] `SOURCE-NAME``( -- source-name-ptr source-name-len )``[FTH]` => `"FORTH"` if `SOURCE` is from `INCLUDE` then the result is the filename, otherwise a generic name for the SOURCE-ID is given. primitive code = [p4_source_name] `TH'POCKET``( pocket# -- pocket-ptr pocket-len )``[FTH]` => `"FORTH"` returns the specified pocket as a `S"` string reference primitive code = [p4_th_pocket] `POCKET-PAD``( -- pocket-ptr )``[FTH]` => `"FORTH"` This function Returns the next pocket. A pocket has usually the size of a maxstring, see `ENVIRONMENT /STRING` (but can be configured to be different, mostly when MAXPATH > /STRING ) Note that a pocket is a temporary and forth internal functions do sometimes call `POCKET-PAD` too, especially when building filenames and getting a literal (but temporary) string from the keyboard. Functions are not expected to hold references to this transient area any longer than building a name and calling another word with it. Usage of a pocket pad is a good way to make local temporary buffers superfluous that are only used to construct a temporary string that usually gets swallowed by another function.
        depracated code:
          create temp-buffer 255 allot
          : make-temp ( str buf )
                 temp-buffer place  " .tmp" count temp-buffer append
                 temp-buffer count make-file ;
        replace with this:
          : make-temp ( str buf )
               pocket-pad >r
               r place  " .tmp" count r append
               r> count make-file
          ;
  primitive code = [p4_pocket_pad] `W@``( some-wchar* -- some-wchar# | some* -- some# [?] )``[FTH]` => `"FORTH"` fetch a 2byte-val from address primitive code = [p4_w_fetch] `W!``( value# some-wchar* -- | value# wchar* -- [?] )``[FTH]` => `"FORTH"` store a 2byte-val at addressed 2byte-value primitive code = [p4_w_store] `W+!``( value# some-wchar* -- | value# wchar* -- [?] )``[FTH]` => `"FORTH"` add a 2byte-val to addressed 2byte-value primitive code = [p4_w_plus_store] `WL-HASH``( buf-ptr buf-len -- buf-hash# )``[FTH]` => `"FORTH"` calc hash-code for selection of thread in a threaded-vocabulary primitive code = [p4_wl_hash] `TOPMOST``( some-wordlist* -- some-topmost-nfa* )``[FTH]` => `"FORTH"` that last valid word in the specified vocabulary primitive code = [p4_topmost] `LS.WORDS``( -- )``[FTH]` => `"FORTH"` see `WORDS` primitive code = [p4_ls_words] `LS.PRIMITIVES``( -- )``[FTH]` => `"FORTH"` see `WORDS` primitive code = [p4_ls_primitives] `LS.COLON-DEFS``( -- )``[FTH]` => `"FORTH"` see `WORDS` primitive code = [p4_ls_cdefs] `LS.DOES-DEFS``( -- )``[FTH]` => `"FORTH"` see `WORDS` primitive code = [p4_ls_ddefs] `LS.CONSTANTS``( -- )``[FTH]` => `"FORTH"` see `WORDS` primitive code = [p4_ls_constants] `LS.VARIABLES``( -- )``[FTH]` => `"FORTH"` see `WORDS` primitive code = [p4_ls_variables] `LS.VOCABULARIES``( -- )``[FTH]` => `"FORTH"` see `WORDS` primitive code = [p4_ls_vocabularies] `LS.MARKERS``( -- )``[FTH]` => `"FORTH"` see `WORDS` primitive code = [p4_ls_markers] `TAB``( tab-n# -- )``[FTH]` => `"FORTH"` jump to next column divisible by n primitive code = [p4_tab] `BACKSPACE``( -- )``[FTH]` => `"FORTH"` reverse of `SPACE` primitive code = [p4_backspace] `?STOP``( -- stop-flag )``[FTH]` => `"FORTH"` check for 'q' pressed - see => ?CR primitive code = [p4_Q_stop] `START?CR``( -- )``[FTH]` => `"FORTH"` initialized for more-like effect - see => ?CR primitive code = [p4_start_Q_cr] `?CR``( -- cr-flag )``[FTH]` => `"FORTH"` like `CR` , stop 25 lines past `START`?CR primitive code = [p4_Q_cr] `CLOSE-ALL-FILES``( -- )``[FTH]` => `"FORTH"` primitive code = [p4_close_all_files] `.MEMORY``( -- )``[FTH]` => `"FORTH"` primitive code = [p4_dot_memory] `(EMIT)``` => `"FORTH"` (no description) primitive code = [p4_paren_emit] `(EXPECT)``` => `"FORTH"` (no description) primitive code = [p4_paren_expect] `(KEY)``` => `"FORTH"` (no description) primitive code = [p4_paren_key] `(TYPE)``` => `"FORTH"` (no description) primitive code = [p4_paren_type] `STANDARD-I/O``( -- )``[FTH]` => `"FORTH"` initialize `*TYPE*` , `*EMIT*` , `*EXPECT*` and `*KEY*` to point directly to the screen I/O routines, namely `(TYPE)` , `(EMIT)` , `(EXPECT)` , `(KEY)` primitive code = [p4_standard_io] `HELP``( "name" -- )``[FTH] [EXEC]` => `"FORTH"` will load the help module in the background and hand over the parsed name to `(HELP)` to be resolved. If no `(HELP)` word can be loaded, nothing will happen. primitive code = [p4_help] `EDIT-BLOCKFILE``( "name" -- )``[FTH] [EXEC]` => `"FORTH"` will load the edit module in the background and look for a word called `EDIT-BLOCK` that could be used to edit the blockfile. If no `EDIT-BLOCKFILE` word can be loaded, nothing will happen. Otherwise, `OPEN-BLOCKFILE` is called followed by `0` `EDIT-BLOCK` to start editing the file at the first block. primitive code = [p4_edit_blockfile] `ARGC``( -- arg-count )``[FTH]` => `"FORTH"` primitive code = [p4_argc] `ARGV``( arg-n# -- arg-ptr arg-len )``[FTH]` => `"FORTH"` primitive code = [p4_argv] `EXPAND-FN``( name-ptr name-len buf-ptr -- buf-ptr buf-len )``[FTH]` => `"FORTH"`
        : e.g. s" includefile" POCKET-PAD EXPAND-FN ;
  primitive code = [p4_expand_fn] `LOAD"``( [filename<">] -- ??? )``[FTH] [OLD]` => `"FORTH"` load the specified file - this word can be compiled into a word-definition obsolete! use `OPEN-BLOCKFILE` name `LOAD` compiling word = [p4_load_quote] `SYSTEM``( command-ptr command-len -- command-exitcode# )``[FTH]` => `"FORTH"` run a shell command (note: embedded systems have no shell) primitive code = [p4_system] `SYSTEM"``( [command-line<">] -- command-exitcode# )``[FTH] [OLD]` => `"FORTH"` run a shell command (note:embedded systems have no shell) obsolete! use `S"` string" `SYSTEM` compiling word = [p4_system_quote] `CREATE:``( "name" -- )``[FTH]` => `"FORTH"` this creates a name with the `VARIABLE` runtime. Note that this is the FIG-implemenation of `CREATE` whereas in ANS-Forth mode we have a `CREATE` identical to FIG-style ``
        : CREATE: BL WORD $HEADER DOVAR A, ;
  primitive code = [p4_create_var] `BUFFER:``( size# "name" -- )``[FTH]` => `"FORTH"` this creates a name with the `VARIABLE` runtime and `ALLOT`s memory
        : BUFFER: BL WORD $HEADER DOVAR A, ALLOT ;
  primitive code = [p4_buffer_var] `R'@``( R: a b -- a R: a b )``[FTH]` => `"FORTH"` fetch the next-under value from the returnstack. used to interpret the returnstack to hold two `LOCALS|` values. ( `R@` / `2R@` / `R>DROP` / `R"@`) compiling word = [p4_r_tick_fetch] `R'!``( x R: a b -- R: x b )``[FTH]` => `"FORTH"` store the value into the next-under value in the returnstack. used to interpret the returnstack to hold two `LOCALS|` values. see `R'@` for inverse operation compiling word = [p4_r_tick_store] `R"@``( R: a b c -- a R: a b c )``[FTH]` => `"FORTH"` fetch the second-under value from the returnstack. used to interpret the returnstack to hold three `LOCALS|` values. see `R"!` for inverse operation ( `R'@` `R@` / `2R@` / `R>DROP` ) compiling word = [p4_r_quote_fetch] `R"!``( x R: a b c -- R: x b c )``[FTH]` => `"FORTH"` store the value into the second-under value in the returnstack. used to interpret the returnstack to hold three `LOCALS|` values. see `R"@` for inverse operation compiling word = [p4_r_quote_store] `R!``( x R: a -- R: x )``[FTH]` => `"FORTH"` store the value as the topmost value in the returnstack. see `R@` for inverse operation ( `R'@` / `R"@` / `2R@` / `2R!`) compiling word = [p4_r_store] `2R!``( x y R: a b -- R: x y )``[FTH]` => `"FORTH"` store the value as the topmost value in the returnstack. see `2R@` for inverse operation ( `R'@` / `R"@` / `2R@` / `2R!`) compiling word = [p4_two_r_store] `DUP>R``( val -- val R: val )``[FTH]` => `"FORTH"` shortcut, see `R>DROP` note again that the following will fail:
        : DUP>R DUP >R ;
  compiling word = [p4_dup_to_r] `R>DROP``( R: val -- R: )``[FTH]` => `"FORTH"` shortcut (e.g. in CSI-Forth) note that the access to R is configuration dependent - only in a traditional fig-forth each NEST will be one cell wide - in case that there are no `LOCALS|` of course. And remember, the word above reads like the sequence `R>` and `DROP` but that is not quite true.
        : R>DROP R> DROP ; ( is bad - correct might be )  : R>DROP R> R> DROP >R ;
  compiling word = [p4_r_from_drop] `2R>2DROP``( R: a b -- R: )``[FTH]` => `"FORTH"` this is two times `R>DROP` but a bit quicker. it is however really quick compared to the sequence `2R>` and `2DROP` compiling word = [p4_two_r_from_drop] `CLEARSTACK``( -- )``[FTH]` => `"FORTH"` reset the parameter stack to be empty
        : CLEARSTACK  S0 SP! ;
  primitive code = [p4_clearstack] `+UNDER``( n1 x n2 -- n1+n2 x )``[EXT]` => `"FORTH"` quicker than
        : UNDER+  ROT + SWAP ;
Note: the old pfe version of UNDER+ is obsolete as it is in conflict with a comus word of the same name. The behavior of this word will continue to exist under the name of `(UNDER+)`. Users are encouraged to use the comus behavior of UNDER+ which does already exist under the name of `+UNDER`. In the future pfe will be changed to pick up the comus behavior making UNDER+ and +UNDER to be synonyms. In the current version there will be load-time warning on usages of "UNDER+". primitive code = [p4_plus_under] `EXECUTES``( fkey# [word] -- )``[EXT]` => `"FORTH"` stores the execution token of following word into the callback pointer for the specified function-key primitive code = [p4_executes]