       ͻ
        Lesson 4 Part 110  F-PC 3.5 Tutorial by Jack Brown 
       ͼ


In the part 10 of lesson 4 we saw how we could write words that could be
used to access, manipulate, enter, display  etc the contents of an
array.  It is very important that you, the Forth programmer, carefully
design the names and functions of the words that access your arrays.
Poor choice of names and function can result in unreadable and
difficult to maintain code.  Forth is one of the few ( possibly only)
language that allows you the freedom to create your own syntax and data
structure interfaces.  If you were not impressed with the MARBLES array
and the wordset used to access and modify its elements you have missed
the point and should go back and study the MARBLES further.

                      Ŀ
                        Personal Stacks.  
                      

In order to understand Forth's data stack a little better we are going
to create our own personal stack.  You see Forth's data stack is little
more than an array with a word set for manipulating its elements.
Type in the following definitions into the file PSTACK.SEQ

\ Create an array to be used for a 10 number stack.
  CREATE  P-STACK  20 ALLOT  \ Stack will hold 10 16bit numbers.

  VARIABLE P-INDEX           \ Holds the value of user stack pointer.

\ Clear and initialize the Personal user stack.
: P-CLEAR  ( -- D) ( ?? -- P)
           0 P-INDEX !  P-STACK 20 ERASE ;

\ Return number of elements on the user stack to Forth's data stack.
: P-DEPTH  ( -- n  D)   P-INDEX @ 2/ ;

\ Increment user stack pointer with error checking.
: P-INC    ( -- D)
           P-INDEX @ 20 =
           IF ." P-OVERFLOW"  P-CLEAR
           ELSE 2 P-INDEX +! THEN ;

\ Decrement user stack pointer with error checking.
: P-DEC    ( -- D)
           P-INDEX @ 0=
           IF ." P-UNDERFLOW"
           ELSE -2 P-INDEX +! THEN ;

\ Move number from Forth's data stack to the P-stack.
: >P       ( n -- D)  ( -- n P)
           P-INC P-INDEX @ P-STACK + ! ;

\ Copy current top number of P-stack to top of Forth's
\ data stack. Note: P-stack is not changed.
: P@       ( --   n D)  ( n  --  n P)
           P-INDEX @ P-STACK + @  ;

\ Move number from top of P-stack to top of Forth's
\ data stack. Note: Number is removed from P-stack.
: P>       ( -- n D)  ( n -- P)
           P@ P-DEC ;

\ Display all numbers on the P-stack.
: .P       ( -- )
           P-DEPTH ?DUP
           IF 1+ 1 ?DO I 2* P-STACK + @ 8 .R LOOP
           ELSE ." P-STACK EMPTY" THEN ;

\ Here are some examples of the execution.
P-CLEAR <enter> ok
.P <enter> P-STACK EMPTY ok
123 >P <enter> ok
.P  <enter>    123 ok
456 >P <enter> ok
.P     <enter>   123     456 ok
.S  <enter> Stack Empty.  ok
P@  <enter> ok
.S  <enter> [1]    456  ok
.P  <enter>    123     456 ok
P>  <enter> ok
.S  <enter> [2]    456     456  ok
.P  <enter>    123 ok

ķ
 Problem 4.18 
Ľ
Do you understand how the word .P works?  Provide me with a version
that has detailed comments ( a comment for every word or two ).

ķ
 Problem 4.19  
Ľ
Personal User Stacks.
Write Forth words for the following user stack operations. They should
leave the data stack unchanged.

 PDUP  PDROP PSWAP POVER PROT -PROT PTUCK PNIP 2PDUP 3PDUP 2PSWAP
 2PDROP 2POVER

Hint:  : PSWAP ( n m -- m n P)  P> P> SWAP >P >P ;

Have we left out any important operators?  Could you make
P+ P- P* and P/ ????

Ŀ
  Please move to Lesson 4 Part 120  

