CA General (CAM Simulator), V1.0 R1                   Date:  09/27/93


This file describes the implemented FORTH words. 


1 Standard FORTH words

  This section simply lists the implemented FigFORTH words with stack 
  comments but no further explanation is given.

1.1 General words

            !   (n addr --- )
         !CSP   ( --- )
            ,   ( --- pfa )
            (   ( --- )
       (FIND)   ( addr1 addr2 --- pfa st t )
                ( addr1 addr2 --- f )
     (NUMBER)   ( addr1 --- d addr2 )
            *   ( n1 n2 --- n3 )
           */   ( n1 n2 n3 --- n4 n5 )
        */MOD   ( n1 n2 n3 --- n4 n5 )
            +   ( n1 n2 --- n3 )
           +!   ( n addr --- )
           +-   ( n1 n2 --- n3 )
            ,   ( n --- )
            -   ( n1 n2 --- n3 )
         -DUP   ( n --- n n )
                ( 0 --- 0 )
        -FIND   ( --- addr st t )
                ( --- f )
            /   ( n1 n2 --- n3 )
         /MOD   ( n1 n2 --- n3 n4 )
           0<   ( n --- l )
           0=   ( n --- l )
           1+   ( n1 --- n2 )
           1-   ( n1 --- n2 )
           2+   ( n1 --- n2 )
           2-   ( n1 --- n2 )
         2DUP   ( d --- d d )
            :   ( --- )
            ;   ( --- )
           ;S   ( --- )
            <   ( n1 n2 --- l )
            =   ( n1 n2 --- l )
            >   ( n1 n2 --- l )
           >R   ( n --- )
        ?COMP   ( --- )
         ?CSP   ( --- )
       ?ERROR   ( f n --- )
        ?EXEC   ( --- )
       ?PAIRS   ( n n --- )
       ?STACK   ( --- )
            @   ( addr --- n )
          ABS   ( n1 --- n2 )
        ALLOT   ( n --- )
          AND   ( b1 b2 --- b3 )
           C,   ( c --- )
           C@   ( addr --- c )
          CFA   ( pfa --- cfa )
      COMPILE   ( --- )
     CONSTANT   ( n --- )
       CREATE   ( --- )
           D+   ( d1 d2 --- d3 )
          D+-   ( d1 n1 --- d2 )
         DABS   ( d1 --- d2 )
        DIGIT   ( n1 n2 --- n3 t )
                ( n1 n2 --- f )
     DLITERAL   ( d --- )
       DMINUS   ( d --- -d )
         DROP   ( n --- )
          DUP   ( n --- n n )
        ERROR   ( n --- )
      EXECUTE   ( cfa --- )
       FORGET   ( --- )
         HERE   ( --- dp )
    IMMEDIATE   ( --- )
    INTERPRET   ( --- )
       LATEST   ( --- nfa )
          LFA   ( pfa --- lfa )
      LITERAL   ( n --- )
           M*   ( n1 n2 --- d )
           M/   ( d n1 --- n2 n3 ) 
        M/MOD   ( du1 u1 --- u2 du2 )
          MAX   ( n1 n2 --- n3 )
      MESSAGE   ( n --- )
          MIN   ( n1 n2 --- n3 )
        MINUS   ( n --- -n )
          MOD   ( n1 n2 --- n3 )
          NFA   ( pfa --- nfa )
         NOOP   ( --- )
          NOT   ( b1 --- b2 )
       NUMBER   ( addr --- d )
           OR   ( b1 b2 --- b3 )
         OVER   ( n1 n2 --- n1 n2 n1 )
          PFA   ( nfa --- pfa )
            R   ( --- n )
           R>   ( --- n )
          ROT   ( n1 n2 n3 --- n2 n3 n1 )
          RP!   ( --- )
          RP@   ( --- rp )
         S->D   ( n --- d )
       SMUDGE   ( --- )
          SP!   ( --- )
          SP@   ( --- sp )
         SWAP   ( n1 n2 --- n2 n1 )
         TASK   ( --- )
       TOGGLE   ( addr n --- )
     TRAVERSE   ( addr1 n --- addr2 )
           U*   ( u1 u2 --- du )
           U/   ( du1 u1 --- u2 u3 )
                ( du1 u1 --- -1 -1 )
           U<   ( u1 u2 --- l )
         USER   ( n --- )
     VARIABLE   ( n --- )
          XOR   ( b1 b2 --- b3 )
            [   ( --- )
    [COMPILE]   ( --- )
            ]   ( --- )
         WORD   ( n --- )


1.2 Statements

    BEGIN ... AGAIN
    BEGIN ... UNTIL
    BEGIN ... WHILE ... REPEAT
    DO ... LOOP
    DO ... +LOOP
    IF ... ENDIF
    IF ... ELSE ... ENDIF

    END (same as UNTIL)
    I
    I'
    J
    LEAVE
    THEN (same as ENDIF)


1.3 System variables

    STATE
    CSP
    CONTEXT
    CURRENT
    DP
    WIDTH
    SO
    RO
    DPL
    BASE
    FENCE


1.4 Predefined constant

    0
    1
    2
    3
    BL


2 Special words 

  In this section we briefly describe that FORTH words what support the 
  programming of the cellular space.

2.1 General words

        ALPHA   ( --- n )
                gives the least significant bit of COL variable
       ALPHA'   ( --- n )
                1st bit of COL variable
         BETA   ( --- n )
                2nd bit of COL variable
        BETA'   ( --- n )
                3rd bit of COL variable
          BYE   ( --- )
                exiting program
        COLOR   ( --- c )
                the value of the COL variable
     EXCHANGE   ( --- )
                exchanges current cellular space with the shadow space
       EDITIM   ( --- )
                envokes simple image editor (defined in file editor.fth)
                use arrow keys to move cursor, and ctrl + arrows to draw
                to change current color use keys 1 to 8 to set color bits and
                shift + 1 to 8 to clear color bits
      GETSTEP   ( --- s )
                the value of the STNUM variable
        GETXY   ( --- x y )
                coordinates of the cell
        GRAPH   ( --- )
                turns graphic mode on, sets palette
   KEYPRESSED   ( --- l )
                true if any key is pressed
      LOADIM    ( --- )
                loads a 256 color image from a BMP file and treats as an 
                initial configuration
    MAKE-CMAP   ( --- )
                the following word of the input stream definies color 
                palette (it may use words ALPHA, BETA and COLOR)
                (see SET-CMAP)
   MAKE-CYCLE   ( --- ) 
                the following word of the input stream definies run cycle
                (default run cycle is STEP)
                (see RUN)
   MAKE-TABLE   ( --- )
                the following word of the input stream definies a new 
                transition rule
                at most 8 rules can be definied
                (see TRANS)
NEW-EXPERIMENT  ( --- )
                clears all transition rules, executes WARM
         TEXT   ( --- )
                turns graphic momde off
        TRANS   ( --- )
                it applies the transition rule defined by MAKE-TABLE for 
                the current cell
       TOCHIP   ( r g b --- )
                current color is set to r g b
          RUN   ( --- )
                the definied run cycle is performed STEPS times
                (see system variable STEPS)
       SAVEIM   ( --- )
                saves the current configuration into the given file as a 
                256 color image (file format is BMP, saves current palette 
                settings)
     SET-CMAP   ( --- )
                sets the color palette definied by MAKE-CMAP
        SETXY   ( x y --- )
                the system variable XY is set to 256 * x + y
        SHELL   ( --- )
                invokes DOS command interpreter
         SHOW   ( --- )
                displays current configuration
         STEP   ( --- )
                executes TRANS for all cells
       SWAP-A   ( --- )
                exchanges bit planes 0 and 1
         WARM   ( --- )
                system restart
                clears data and return stacks, executes INTERPRET system 
                word


2.2 Bit-planes

    Words to read the state of the current cell:

       CENTER   ( --- n )
                least significant bit of cell state
      CENTER'   ( --- n )
                1st bit of cell state
      CENTERS   ( --- n )
                CENTER' * 2 + CENTER
      BCENTER   ( --- n )
                2nd bit
     BCENTER'   ( --- n )
                3rd bit
     BCENTERS   ( --- n )
                BCENTER' * 2 + BCENTER
      CENTERB   ( --- n )
                cell state (8 bits)


    Words to read the states of the neighbours of the current cell:

        NORTH, EAST, SOUTH, WEST, N.EAST, S.EAST, S.WEST, N.WEST

    These words have the 7 forms definied for CENTER.


    Neighbours for Margolus neighbourhood:

           CW   ( --- n )
                state of neighbouring cell clockwise
          CCW   ( --- n )
                state of neighbouring cell counter-clockwise
          OPP   ( --- n )
                state of the opposite cell


    Words to change the state of the current cell on shadow planes:

        >PLN0   ( n --- )
                sets bit plane 0 to n mod 2
        >PLN1   ( n --- )
                sets bit plane 1 to n mod 2
        >PLN2   ( n --- )
                sets bit plane 2 to n mod 2
        >PLN3   ( n --- )
                sets bit plane 3 to n mod 2
        >PLNA   ( n --- )
                sets bit plane 0 and 1 to n mod 4
        >PLNB   ( n --- )
                sets bit plane 2 and 3 to n mod 4
       >PLNBT   ( n --- )
                sets the 8 bit planes to n mod 256

    Words to change the state of the current cell on current planes:

       >CPLN0   ( n --- )
                sets bit plane 0 to n mod 2
       >CPLN1   ( n --- )
                sets bit plane 1 to n mod 2
       >CPLN2   ( n --- )
                sets bit plane 2 to n mod 2
       >CPLN3   ( n --- )
                sets bit plane 3 to n mod 2
       >CPLNA   ( n --- )
                sets bit plane 0 and 1 to n mod 4
       >CPLNB   ( n --- )
                sets bit plane 2 and 3 to n mod 4
      >CPLNBT   ( n --- )
                sets the 8 bit planes to n mod 256

                
2.3 System variables

          COL   code of current color
        ECMAP   true if color palette is defined (after MAKE-CMAP)
         MAXX   horizontal size of cellular space (between 1 and 255)
         MAXY   vertical size of cellular space (between 1 and 255)
      STEPNUM   number of steps already done
        STEPS   number of step to do
       TABLES   address of first free place in the body of TRANS
           XY   coordinates of current cell (256 * x + y)

