FPH Common Usage

Wil Baden 1998-08-26

Forth Programmer's Handbook, Conklin and Rather

With Forth Programmer's Handbook, ISBN 0-9662156-0-5, as the only current general book about Forth, for portability today's Forth implementations and tutorials should agree with it.

Here are words that are in FPH but not in Standard Forth.

.'   2+   2-   C+!   CONTEXT   CURRENT   CVARIABLE   DASM   DEFER   EMPTY   INCLUDE   IS   L   LOCATE   M-   M/   NOT   T*   T/   VOCABULARY   WH   WHERE   [DEFINED]   [UNDEFINED]  

These words are described as common usage. Some of them are implementation dependent. Others have simple definitions in Standard Forth. Potential definitions for those which can be defined in Standard Forth are given here for systems that are missing them.

Existing definitions are surely superior, especially when implementation dependent.

Comment out definitions that you already have or are improving.

Definitions in Standard Forth by Wil Baden. Any similarity with anyone else's code is coincidental, historical, or inevitable.

TEXT

NOT                 ( x -- flag )
Identical to 0=, used for program clarity to reverse the result of a previous test.
[DEFINED]           ( "name" -- flag )
Search the dictionary for name. If name is found, return TRUE; otherwise return FALSE. Immediate for use in definitions.
[UNDEFINED]         ( "name" -- flag )
Search the dictionary for name. If name is found, return FALSE; otherwise return TRUE. Immediate for use in definitions.
C+!                 ( n addr -- )
Add the low-order byte of n to the byte at addr, removing both from the stack.
Program Text 1
: NOT ( n -- flag ) S" 0= " EVALUATE ; IMMEDIATE

: [DEFINED]         ( "name" -- flag )
    BL WORD FIND NIP 0<> ; IMMEDIATE

: [UNDEFINED]       ( "name" -- flag )
    BL WORD FIND NIP 0= ; IMMEDIATE

: C+! ( n addr -- ) DUP >R C@ + R> C! ;


2+                  ( n -- n+2 )
Add 2 to the top of stack.
2-                  ( n -- n-2 )
Subtract 2 from the top of stack.
INCLUDE             ( "filename" -- )
Include the named file.
DEFER               ( "name" -- )
Define name as an execution vector. When name is executed, the execution token stored in name's data area will be retrieved and its behavior performed. An abort will occur if name is executed before it has been initialized.
IS                  ( xt "name" -- )
Store xt in name, where name is a word defined by DEFER.
Program Text 2
: 2+  ( n -- n+2 )  2 + ;

: 2-  ( n -- n-2 )  2 - ;

: INCLUDE           ( "filename" -- )
    BL WORD COUNT INCLUDED  DECIMAL ;

    : Uninitialized-DEFER  ( -- )
        TRUE ABORT" Uninitialized DEFER." ;

: DEFER CREATE      ( "name" -- )
    ['] Uninitialized-DEFER ,  DOES> @ EXECUTE ;

: IS                ( xt "name" -- )
    '                             ( xt xt2)
    STATE @ IF
        POSTPONE LITERAL  POSTPONE >BODY  POSTPONE !
    ELSE
        >BODY !
    THEN ; IMMEDIATE


M-                  ( d . n -- d . )
Subtract single number n from double number d..
M/                  ( d . n -- q )
Divide double number d. by single number n.
T*                  ( d . n -- t . . )
Multiply a double number by a single number to get a triple number.
T/                  ( t . . u -- d . )
Divide a triple number by an unsigned number to get a double answer.
M*/                 ( d . n u -- d . )
Multiply d. by n to triple result; divide by u to double result. [Double]
Program Text 3
: M-  ( d . n -- d . )  NEGATE M+ ;

: M/  ( d . n -- q )  SM/REM NIP ;

    : TNEGATE          ( t . . -- -t . . )
        >R  2DUP OR DUP IF DROP  DNEGATE 1  THEN
        R> +  NEGATE ;

: T*                 ( d . n -- t . . )
                     ( d0 d1 n)
    2DUP XOR >R                ( R: sign)
    >R DABS R> ABS
    2>R              ( d0)( R: sign d1 n)
    R@ UM* 0         ( t0 d1 0)
    2R> UM*          ( t0 d1 0 d1*n .)( R: sign)
    D+               ( t0 t1 t2)
    R> 0< IF TNEGATE THEN ;

: T/                 ( t . . u -- d . )
                     ( t0 t1 t2 u)
    OVER >R >R       ( t0 t1 t2)( R: t2 u)
    DUP 0< IF TNEGATE THEN
    R@ UM/MOD        ( t0 rem d1)
    ROT ROT          ( d1 t0 rem)
    R> UM/MOD        ( d1 rem' d0)( R: t2)
    NIP SWAP         ( d0 d1)
    R> 0< IF DNEGATE THEN ;

: M*/  ( d . n u -- d . )  >R T*  R> T/ ;


VOCABULARY          ( "name" -- )
Create a word list name. Subsequent execution of name replaces the first word list in the search order with name. When name is made the compilation word list, new definitions will be added to name's list.
Program Text 4
\  From Standard Forth Rationale A.16.6.2.0715.

: DO-VOCABULARY     ( -- )
    DOES>  @ >R               ( )( R: widnew)
        GET-ORDER  SWAP DROP  ( wid_n ... wid_2 n)
    R> SWAP SET-ORDER ;

: VOCABULARY        ( "name" -- )
    WORDLIST CREATE ,  DO-VOCABULARY ;



EMPTY               ( -- )
Reset the dictionary to a predefined golden state, discarding all definitions and releasing all allocated data space beyond that state.
"When the system starts, or following an EMPTY, the default word list for both CONTEXT and CURRENT is FORTH." FPH 2nd edn, p. 169
POSSIBLY            ( "name" -- )
Execute name if it exists; otherwise, do nothing. Useful implementation factor of ANEW.
ANEW                ( "name" -- )
Compiler directive used in the form: ANEW name. If the word name already exists, it and all subsequent words are forgotten from the current dictionary, then a MARKER word name is created that does nothing. This is usually placed at the start of a file. When the code is reloaded, any prior version is automatically pruned from the dictionary.
Executing name will also cause it to be forgotten, since it is a MARKER word.
Useful implementation factor of EMPTY.
Program Text 5
    : POSSIBLY  ( "name" -- )
        BL WORD FIND  ?DUP AND IF  EXECUTE  THEN ;

    : ANEW  ( "name" -- )  >IN @  POSSIBLY  >IN !  MARKER ;

: EMPTY  ( -- )  S" ANEW --- DECIMAL " EVALUATE ;


Implementation Dependent

.'                  ( addr -- )
Display the name of the nearest definition before addr, and the offset of addr from the beginning of that definition. Implementation dependent.
CONTEXT             ( -- a-addr )
Return a-addr, the address of a cell that contains a pointer to the first word in the search order. Implementation dependent.
CURRENT             ( -- a-addr )
Return a-addr, the address of a cell that contains a pointer to the current compilation word list. Implementation dependent.
CVARIABLE           ( "name" -- )
Define a one-byte variable. Execution of name will return the address of its data space. Typically available only on embedded systems. Implementation dependent.
DASM                ( addr -- )
Begin disassembly at the address addr on top of stack. Implementation dependent.
L                   ( -- )
Show the current source code file or block and the current cursor position in it. If used after a compiling error, point to the source code that caused the error. Implementation dependent.
LOCATE              ( "name" -- )
If name is the name of a definition that has been compiled from source code, display the source code for name. On some systems, the phrase VIEW name performs a similar function. Implementation dependent.
WH                  ( "name" -- )
Short synonym for WHERE, defined for typing convenience. Implementation dependent.
WHERE               ( "name" -- )
Display all the places in the currently compiled program where name has been used, showing any redefinitions separately. Implementation dependent.

These are implementation dependent, and can't have Standard definitions.

Go back to Neil Bawd's home page.