TOOLS-EXT Programming-Tools + parts of extensions

The ANS Forth defines some "Programming Tools", words to inspect the stack (.S), memory (DUMP), compiled code (SEE) and what words are defined (WORDS).

There are also word that provide some precompiler support and explicit acces to the CS-STACK.

.S ( -- )  
ansi 15.6.1.0220
print the stack content in vertical nice format. tries to show cell-stack and float-stack side-by-side,

Depending on configuration, there are two parameter stacks: for integers and for floating point operations. If both stacks are empty, .S will display the message <stacks empty>.

If only the floating point stack is empty, .S displays the integer stack items in one column, one item per line, both in hex and in decimal like this (the first item is topmost): 

 12345 HEX 67890 .S
    	424080 [00067890]
         12345 [00003039] ok
If both stacks ar not empty, .S displays both stacks, in two columns, one item per line 
 HEX 123456.78E90 ok
 DECIMAL 123456.78E90 .S
    	   291 [00000123]          1.234568E+95
    1164414608 [45678E90] ok
Confusing example? Remember that floating point input only works when the BASE number is DECIMAL. The first number looks like a floating point but it is a goodhex double integer too - the number base is HEX. Thus it is accepted as a hex number. Second try with a decimal base will input the floating point number.

If only the integer stack is empty, .S shows two columns, but he first columns is called <stack empty>, and the second column is the floating point stack, topmost item first.

reference: p4_dot_s in ../src/toolkit.c:0084, export CO .S

DUMP ( addr len -- )  
ansi 15.6.1.1280
show a hex-dump of the given area, if it's more than a screenful it will ask using ?CR

You can easily cause a segmentation fault of something like that by accessing memory that does not belong to the pfe-process.

reference: p4_dump in ../src/toolkit.c:0159, export CO DUMP

SEE word ( -- )  
ansi 15.6.1.2194
decompile word - tries to show it in re-compilable form.

(SEE) tries to display the word as a reasonable indented source text. If you defined your own control structures or use extended control-flow patterns, the indentation may be suboptimal. 

 simulate:
   : SEE  [COMPILE] ' (SEE) ;

reference: p4_see in ../src/toolkit.c:0196, export CO SEE

WORDS ( -- )  
ansi 15.6.1.2465
uses CONTEXT and lists the words defined in that vocabulary. usually the vocabulary to list is named directly in before. 
 example:
    FORTH WORDS  or  LOADED WORDS

reference: p4_words in ../src/toolkit.c:0211, export CO WORDS

AHEAD ( -- DP-mark ORIG-magic )   compile-only
immediate ansi 15.6.2.0702 
 simulate:
   : AHEAD  MARK> (ORIG#) ;

reference: p4_ahead in ../src/toolkit.c:0254, export CI AHEAD

BYE ( -- )   no-return
ansi 15.6.2.0830
should quit the forth environment completly

reference: p4_bye in ../src/toolkit.c:0263, export CO BYE

CS-PICK ( 2a 2b 2c ... n -- 2a 2b 2c ... 2a )  
ansi 15.6.2.1015
pick a value in the compilation-stack - note that the compilation stack _can_ be seperate in some forth-implemenations. In PFE the parameter-stack is used in a double-cell fashion, so CS-PICK would 2PICK a DP-mark and a COMP-magic, see PICK

reference: p4_cs_pick in ../src/toolkit.c:0283, export CO CS-PICK

CS-ROLL ( 2a 2b 2c ... n -- 2b 2c ... 2a )  
ansi 15.6.2.1020
roll a value in the compilation-stack - note that the compilation stack _can_ be seperate in some forth-implemenations. In PFE the parameter-stack is used in a double-cell fashion, so CS-ROLL would 2ROLL a DP-mark and a COMP-magic, see ROLL

reference: p4_cs_roll in ../src/toolkit.c:0296, export CO CS-ROLL

FORGET word ( -- )  
ansi 15.6.2.1580 
 simulate:
   : FORGET  [COMPILE] '  >NAME (FORGET) ; IMMEDIATE

reference: p4_forget in ../src/toolkit.c:0309, export CO FORGET

[ELSE] ( -- )  
immediate ansi 15.6.2.2531
eat up everything upto and including the next [THEN]. count nested [IF] ... [THEN] constructs. see [IF] 
 this word provides a simple pre-compiler mechanism

reference: p4_bracket_else in ../src/toolkit.c:0321, export CI [ELSE]

[IF] ( flag -- )  
immediate ansi 15.6.2.2532
check the condition in the CS-STACK. If true let the following text flow into INTERPRET , otherwise eat up everything upto and including the next [ELSE] or [THEN] . In case of skipping, count nested [IF] ... [THEN] constructs. 
 this word provides a simple pre-compiler mechanism

reference: p4_bracket_if in ../src/toolkit.c:0354, export CI [IF]

NOOP ( -- )  
immediate ansi 15.6.2.2533
do nothing, used as a place-holder where an execution word is needed

reference: p4_noop in ../src/lpf83.c:0074, export CI [THEN]

? ( addr -- )  
ansi 15.6.1.0600
Display the (integer) content of at address addr. This word is sensitive to BASE 
 simulate:
   : ?  @ . ;

reference: p4_question in ../src/toolkit.c:0146, export CO ?

VLIST ( -- )  

The VLIST command had been present in FIG and other forth implementations. It has to list all accessible words. In PFE it list all words in the search order. Well, the point is, that we do really just look into the search order and are then calling WORDS on that Wordl. Uses ?CR

reference: p4_vlist in ../src/toolkit.c:0225, export CO VLIST