PFE-SMART Kernel extensions

This wordset is the place to add any additional primitives you might wish. A set of words do already live here that must be bound statically into the main pfe-object to work out smart and nicely.

(IMMEDIATE#) ( -- bit-mask )  

returns the bit-mask to check if a found word is immediate 
    " my-word" FIND IF >FFA C@ (IMMEDIATE#) AND 
                       IF ." immediate" THEN ELSE DROP THEN

reference: p4_immediate_bit in ../src/yours.c:0100, export CO (IMMEDIATE#)

(SMUDGE#) ( -- bit-mask )  

returns the bit-mask to check if a found word is smudge 
    " my-word" FIND IF >FFA C@ (SMUDGE#) AND 
                       IF ." smudge" THEN ELSE DROP THEN

reference: p4_smudge_bit in ../src/yours.c:0110, export CO (SMUDGE#)

>COMPILE ( xt -- )  

does the work of POSTPONE on the execution token that you got from somewhere else - so it checks if the name (that correspond to the execution-token argument) is actually immediate, so it has to be executed to compile something, e.g. IF or THEN - see also POSTPONE , COMPILE , [COMPILE] , INTERPRET

reference: p4_to_compile in ../src/yours.c:0135, export CO >COMPILE

($ word ( -- cs-token )   compile-only
immediate
takes the execution token of the following word and saves it on the compile-stack. The correspondig closing ) will then feed it into >COMPILE - so this pair of word provides you with a prefix-operation syntax that you may have been seen in lisp-like languages. 
   ($ IF ($ 0= A1 @ )) ($ THEN ." hello " )
Note that an opening simple ( paren is a comment.

reference: p4_prefix_begin in ../src/yours.c:0152, export CI ($

) ( cs-token -- )  
immediate
takes the execution-token from ($ and compiles it using >COMPILE

reference: p4_prefix_end in ../src/yours.c:0163, export CI )

@> name ( -- value )  
smart-word
does fetch the value from the PFA of the named item, which may be about everything, including a VARIABLE , VALUE LVALUE , LOCALS| , VAR , DEFER , DOER , DOES> and more.

reference: p4_fetch_from in ../src/yours.c:0199, export CS @>

!> name ( value -- )  
smart-word
actually a synonym for TO but very common amongst forth interpreters

reference: p4_store_to in ../src/yours.c:0696, export CS !>

'> name ( -- xt )  
smart-word
get the execution-token, ie the CFA, of the word following. This word is fully state-smart while the ANSI standard words namely ' and ['] are not.

reference: p4_tick_from in ../src/yours.c:0679, export CS '>

INTO word ( -- pfa )  
smart-word
will return the parameter-field address of the following word. Unlike others, this word will also return the address of LOCALS| and local VAR - so in fact a TO A and INTO A ! are the same. This word is most useful when calling C-exported function with a temporary local-VAR as a return-place argument - so the address of a local has to be given as an arg. Beware that you should not try to save the address anywhere else, since a local's address does always depend of the RP-depth.

reference: p4_into in ../src/yours.c:0733, export CS INTO

VAR name ( -- )  
smart-word
a fully state-smart version, that does either create a VALUE or LVALUE and does always initialize it with null - so unlike either VALUE and LVALUE this word does not take any stack-argument. The name itself stems from javascript.

reference: p4_var in ../src/yours.c:0780, export CS VAR

SMART-INTERPRET-INIT  

creates a set of interpret-words that are used in the inner interpreter, so if a word is unknown to the interpreter-loop it will use the first char of that word, attach it to an "interpret-" prefix, and tries to use that IMMEDIATE-DEFER-word on the rest of the word. This SMART-INTERPRET-INIT will set up words like interpret-" so you can write "hello" instead of " hello" and it creates interpret-\ so that words like \if-unix are ignoring the line if the word \if-unknown is unknown in itself. This is usually not activated on startup.

reference: p4_smart_interpret_init in ../src/yours.c:0298, export CO SMART-INTERPRET-INIT

SMART-INTERPRET-OFF  

disables the SMART-INTERPRET extension in INTERPRET , see SMART-INTERPRET-INIT

reference: p4_smart_interpret_off in ../src/yours.c:0317, export CO SMART-INTERPRET-OFF

SMART-INTERPRET-ON  

enables the SMART-INTERPRET extension in INTERPRET , see SMART-INTERPRET-INIT - the default for smart-interpret is always off

reference: p4_smart_interpret_on in ../src/yours.c:0327, export CO SMART-INTERPRET-ON

<<CPU>> ( -- )  
on-load
the goto-cpu feature will vanish. It had been used to create a multi-forth in a non-threaded environment. This word creates a number of CPU*-immediates that will switch the QUIT-interpret loop to use the other cpu's dictionary.

reference: p4_load_cpus in ../src/yours.c:0357, export CX __cpus__

CPU# ( -- )  

the goto-cpu feature will vanish. It is used to create a multi-forth in a non-threaded environment. This word returns the number of the cpu-dictionary that is currently in use.

reference: p4_cpu_nr in ../src/yours.c:0379, export CO CPU#

.H2 ( value -- )  

print hexadecimal, but with per-byte 0-padding 
   0x0     -> 00
   0xf     -> 0f
   0x12    -> 12
   0x123   -> 0123
   0x1234  -> 1234
   0x12345 -> 012345

reference: p4_dot_h2 in ../src/yours.c:0523, export CO .H2

PRINTF ( args ... format$ -- )  

uses SPRINTF to print to a temporary 256-char buffer and prints it to stdout afterwards. See the example at SPRINTF of what it does internally.

reference: p4_printf in ../src/yours.c:0507, export CO PRINTF

SPRINTF ( args ... format$ dest$ -- len-dest )  

just like the standard sprintf() function in C, but the format is a counted string and accepts %#s to be the format-symbol for a forth-counted string. The result is a zeroterminated string at dest$ having a length being returned. To create a forth-counted string, you could use: 
   variable A 256 ALLOT
   15 " example" " the %#s value is %i" A 1+ SPRINTF A C!
   A COUNT TYPE

reference: p4_sprintf in ../src/yours.c:0497, export CO SPRINTF

LOADF filename ( -- )  

loads a file just like INCLUDE but does also put a MARKER in the LOADED dictionary that you can do a FORGET on to kill everything being loaded from that file.

reference: p4_loadf in ../src/yours.c:0552, export CO LOADF

DEFER word ( -- )  

create a new word with ((DEFER))-semantics 
 simulate:
   : DEFER  CREATE 0, DOES> ( the ((DEFER)) runtime ) 
      @ ?DUP IF EXECUTE THEN ;
declare as "DEFER deferword"
and set as "['] executionword TO deferword"

reference: p4_defer in ../src/lpf83.c:0386, export CO DOER

MAKE word ... ;AND ( -- )  
smart-word
make a seperated piece of code between MAKE and ;AND and on execution of the MAKE the named word is twisted to point to this piece of code. The word is usually a DOER but the current implementation works on DEFER just as well, just as it does on other words who expect to find an execution-token in its PFA. You could even create a colon-word that starts with NOOP and can then make that colon-word be prefixed with the execution of the code piece. This MAKE does even work on LOCALS| and VAR but it is uncertain what that is good for.

reference: p4_make in ../src/yours.c:0617, export CS MAKE

;AND ( -- )  
smart-word
For the code piece between MAKE and ;AND , this word will do just an EXIT . For the code outside of the MAKE construct a branch-around must be resolved then.

reference: p4_semicolon_and in ../src/yours.c:0653, export CS ;AND

[DEFINED] word ( -- nfa|0 )   immediate
immediate
does check for the word using find (so it does not throw like ' ) and puts it on stack. As it is immediate it does work in compile-mode too, so it places its argument in the cs-stack then. This is most useful with a directly following [IF] clause, so that sth. like an [IFDEF] word can be simulated through [DEFINED] word [IF]

reference: p4_bracket_defined in ../src/yours.c:0803, export CI [DEFINED]

[NOT] ( a -- a' )  
immediate
executes 0= but this word is immediate so that it does affect the cs-stack while compiling rather than compiling anything. This is useful just before words like [IF] to provide semantics of an [IFNOT]. It is most useful in conjunction with " [DEFINED] word" as it the sequence "[DEFINED] word [NOT] [IF]" can simulate "[IFNOTDEF] word"

reference: p4_bracket_not in ../src/yours.c:0821, export CI [NOT]