BASIC & FORTH in Parallel ( 1984 )
by. S.J.Wainwright



ABOUT:

The "FORTH-Stack Simulator" listing appears 
on pages 90 to 95 of the book. The Appendix 
on using the FORTH-Stack Simulator starts on 
page 86 and ends on page 89. ( the Appendix
appears at the end of this document )



CAUTION:

It is not at all well error trapped. A mistake will
create an error message. Entering nothing at
the INPUT line will cause an error. Using /, mod,
/mod, */ and */mod on an EMPTY stack will
create an error. Also "pick" and "roll" must
be preceded by an integer or an error at line 
2080 message will appear. If the second number 
on the Stack is greater than 0 and the top number 
is 0 and a / is entered you will get an error message.
SWAP the two before using /. If you enter a decimal
number ( ie. 3.5 ) you will only get the integer
onto the Stack ( 3 ) and not what is after the decimal
point ( .5 ).

Commands will be explained later.



RUNNING THE PROGRAM &
CONTINUING WHEN THERE IS AN ERROR:

You can start fresh by BREAKing into the
program ( or deleting the quotes at the INPUT line
and using the command STOP ) and RUNning
the program again from the start. Note: This will 
delete variables and you should only do this
if you want to start over again.

The Appendix says to make a warm start with
GO TO 1000 but that doesn't always work. You can
use GO TO 1500 if you ever BREAK into the
program, if there is an error that won't allow you
to continue using GO TO 1000, or you use STOP
at the INPUT line ("L"). RETURN sometimes works
and GO TO 200 will also work, when there is an
error message. 

I'd recommend  GO TO 200 in most cases as it 
takes you straight back to the INPUT line. 



STACK OPERATIONS:

If the operations that can be performed
with the simulator seem limited it is because
it is meant to be used in conjunction with the
book and the examples in it. The simulator doesn't
use all the commands in the book and is only
used to illustrate Stack operations. Nevertheless, 
despite its lack of error trapping, it works properly 
by following the proper procedures and used
correctly. I believe it is a useful and educational 
program, worthy for the benefit of a graphical 
representation of the Stack and what goes on in 
the Stack that you can't see while programming 
in a real FORTH editor ( that I know of ).

The aim of the book is to gently get the reader's
feet wet by learning the first steps of FORTH and
it assumes the reader has some knowledge in
BASIC, using that to teach FORTH by comparison.

Without the book it may seem there is little one 
can do with this program. This is why I will briefly
explain each command here following each
with an example or two so that you may see how
they work and you can try them out for yourself
and then go on and experiment on your own.
Now you can make the most of the simulator
as much as I can with the book. I will only cover 
the operations used by the simulator.

Anything followed by ( FORTH-79 ) just means
that it is a FORTH-79 word. The others are Fig FORTH.
There isn't much difference between them. New words
can be defined to perform functions not available
in a particular flavor of FORTH. This really doesn't mean
much for the Simulator and I thought I'd bring it up
just to share where the words come from.



ZX////ZX////ZX////ZX////ZX////ZX////ZX////ZX////ZX////ZX////



TEACHING THE SIMULATOR
BY EXAMPLE - EXPLANATIONS
OF OPERATIONS AVAILABLE:

( Make sure CAPS LOCK is OFF )

First enter the following numbers:

5 ( ENTER)
7 ( ENTER )
12 ( ENTER )

Note: 'Last in, First out' ... so 
we get the following:

12
7
5

SUGGESTION: Once you have read what each
operator word does, see if you can imagine what
the result will be before scrolling down to the answer
in each part!

-------||-------

ARITHMETIC OPERATIONS:

. 

( an actual 'period' ) Like PRINT, and it POPs the
top number on the Stack off and PRINTS it.

The Stack:

12
7
5

Typing:

.

Will result in the Stack shifting upwards and the
number 12 getting popped off and being printed.

7
5
0

12	( Printed )

-------||-------

+

This will add both numbers on the top of the
Stack and become the top number on the Stack:

7
5
0

Typing:

+

Results in:

12
0
0

-------||-------

-

This will subtract both numbers on the top of the
Stack and become the top number on the Stack:

12
0
0

Now type:

14

You should have

14
12
0

So, typing:

-

Results in:

-2
0
0

Why -2? Because we are subtracting 14 from 12 and not
12 from 14. If we want to get a positive answer we need 
to swap the two numbers first. 

( Note: I discovered doing - again
and ENTER also results in a + 2 in the
simulator. I think this is a quirk of the
simulator. )

We'll get to swap later but if you had typed:

swap

the 12 and 14 will "swap" position:

12
14
0

and then typing:

-

would have resulted in 2


-------||-------

*

This will multiply both numbers on the top of the
Stack and become the top number on the Stack:

-2
0
0

So, typing:

*

Will naturally result in:

0
0
0

-------||-------

Time to get more numbers on the stack.

Let's try 21, 34 and 3.

you should see:

3
34
21

-------||-------

/

This will divide both numbers on the top of the
Stack and become the top number on the Stack:

3
34
21

So type:

/

... and we should have:

11
21
0

( Remainder 1 is lost. There are other commands
to preserve them that we'll get to later )

-------||-------

Type:

17 and then 5

You should have:

5
17
11
21

-------||-------

mod

This pops the two top numbers off the Stack. It divides
the second on the Stack by the top off the Stack,
then pushes the remainder to the top of the Stack.

5
17
11
21

Type:

mod

You should have:

2	( 17/5=3 and the remainder is 2. Easy! )
11
21

-------||-------

/mod

This pops the two top numbers off the Stack. It divides
the second on the Stack by the top off the Stack,
then pushes the remainder to the Stack and the
quotient to the Stack so that quotient is at the top
of the Stack and the remainder is second on the Stack.

2
11
21

Type:

/mod

You should see:

5
1
21

-------||-------

*/

This pops the top three numbers off the Stack. it
multiplies the second on the Stack by the third on
the Stack, which is then divided by the number at
the top of the Stack. The result goes to the top of
the Stack.

5
1
21

Typing:

*/

Should result in:

4	( 21*1=21 ... 21/5=4 remainder 1)
0
0

-------||-------

*/mod

Does the same as */ but then the remainder is
pushed onto the Stack and then the quotient is
pushed also. So the remainder will be second
and the quotient first on the Stack.

Let's get those numbers back.

To 'drop' the 4 just do:

drop ( coming later )

The Stack should be all zeros:

0
0
0

Now type 21, 1 and 5 so again we have:

5
1
21	

Now do:

*/mod

You should have:

4	( 21*1=21 ... 21/5=4 ... remainder 1is second on Stack )
1
0

-------||-------

STACK OPERATIONS:

swap

Swaps the two numbers at the top of the stack.

4
1
0

Typing:

swap

Results in:

1
4
0

-------||-------

drop

Drops the top number off the Stack and
the rest of the numbers shift toward the
top of the Stack:

1
4
0

Typing:

drop

Will give:

4
0
0

-------||-------

dup ( FORTH-79 )

DUPlicates the top number on the Stack and
pushes it to the top of the Stack ( BUT NOT 0s ):

4
0
0

Type:

dup

... and you will have:

4
4
0

-------||-------

2dup

( First let's just type 1 then ENTER followed
by + and ENTER to get a better idea and not
have so many fours!!! :-)

5
4
0

2dup is like dup except it duplicates a "double
precision" number at the top of the Stack. Since
double precision numbers occupy two positions
on the Stack it will duplicate both numbers. If single
precision numbers occupy the Stack it will also
duplicate those.

Type:

2dup

... and we should have:

5
4
5
4

-------||-------

over

This will cause the second Stack entry to be duplicated
onto the top of the stack.

5
4
5
4

Type:

over

Result:

4
5
4
5
4

-------||-------

rot

ROTates the third Stack entry to the top
of the Stack:

4
5
4
5
4

Type:

rot

We should have:

4
4
4
5
4

( If you thought we would have:

4
4
5
5
4

we don't, since 4 was the third entry on
the Stack it remains that way using 'rot'
although placing the number 4 at the top.
The 5 is dropped because it would have
been taking this third position on the Stack
where 'rot' originally found a 4 and so the
third entry, 4, remains at the third position
thus dropping the 5, which would have shifted
to third postion, because it drops whatever
would be the third number, even after rotating
the original third Stack number. This is at 
least how I understand 'rot', as far as "this
simulator" is concerned. )


-------||-------

pick ( FORTH-79 )

PICK is preceded by an integer. Example:

n pick

This causes the nth Stack entry to be duplicated onto
the top of the Stack. Normally, if pick is used without
a Stack position number preceding it, it will pop the top
number off the Stack and use it as the 'nth' integer.
( Note: I say "normally" because if pick doesn't have
a Stack number entry before it "in the simulator" you
will get an error message. )

4
4
4
5
4

Type:

4 pick

We have:

5
4
4
4
5
4

-------||-------

roll ( FORTH-79 )

ROLL is preceded by an integer representing a
position in the Stack, much like PICK.

n roll

The nth Stack entry will be rotated to the top of the
Stack. If no number precedes ROLL then the top Stack
entry will be popped off and used as the integer and
then operate on the remaining Stack, similarly to PICK.
( As with PICK, ROLL will result in an error "in this 
simulator" if not preceded by an integer Stack position )

5
4
4
4
5
4

Type:

6 roll

We should have:

4
5
4
4
4
5


-------||-------

stop

Stops the simulator
( If you do this, to continue simply do:

GO TO 200 )

-------||-------



DEFINING YOUR OWN COMMANDS:

:

Use a colon when wanting to define a
new word to perform your own custom
operation. It then goes into the FORTH 
dictionary.

-------||-------

;

The semicolon marks the end of a
colon definition.

-------||-------

defno

Will give you a list of all custom defined
words and their names.

-------||-------

noop

NOOPeration. No change is made to the Stack
AND handy to get out of certain parts of the program
and back to the main Stack display screen. ( For
example, handy with this simulator if you are at 
the Defined Words screen and want to get out 
without using any and want the Stack screen to 
reappear) 

-------||-------

We're about to get into defining your OWN words in FORTH.
You are allowed to do this in the simulator ( even if limited ) so
let's look at an example. I'll make one up now:


DEFINING YOUR OWN WORDS

( You can't use PICK, ROLL, any numbers or other new
defined words of your own, in newly defined words.
Also, only six characters MAX allowed in definitions. )


Let's say we want the second number on the Stack to its
3rd power ( x^3 ) and then popped off the Stack to be PRINTed
on the screen.

The Stack:

4
5
4
4
4
5

First we have to type:

:

To go into Definition mode.

Next we type the name of our new word.
What should we call it? Let's try...

2nd^3p

So we would type:

2nd^3p 

... for - "2nd" Number on the Stack  - To the "3rd Power" - "Print".
- On the SPECTRUM you get ^ holding SHIFT while pressing H
- Make a better name if you like. I'm just doing this as I type.


Now for the procedure:

We want the 2nd number on the Stack to the
3rd power. How do we make this happen?
Can we DROP the top number off? Yes, but what
if we need that number later? Let's Suppose we
do and we work it so we keep the top Stack number
and instead of DROP we do a SWAP.

So type:

swap

The Stack would look like this now if you could see it:

5
4
4
4
4
5

Ok. But we need to multiply this sucker three times.
We can use dup twice or 2dup. DUP twice is two
steps but 2DUP will create 5 4 5 4 etc... and we want
three consecutive fives. It would involve SWAPping the
first two Stack numbers then DROPping the first then
DUPlicating the first again. ( We can't use numbers
in our definitions - look at it this way. When you do use
FORTH it'll seem like a piece of cake without the 
annoying restrictions of the simulator!  :-) 

So we're better off just DUPlicating twice.

Type:

dup

Type again:

dup

Now the Stack would look like this:

5
5
5
4
4
4
4
5

To the 3rd power. We only need to multiply the
first three numbers. From immediate mode
we would just do:

*

... and then that result times the last 5:

*

Right?

So do the same here:

Type:

*

... and again:

*

Now all we need to do is Print it like I said before.
We need the period.

Type:

.


There. We're almost done

To end our definition we need a semicolon.

Type:

;

... and we're taken back to immediate
mode but we dont see the Stack. 

Do:

noop

The screen including the Before and After
Stack should be visible now. 

Before we try our cool new word let's
see if it's in the dictionary by typing:

defno


You should see it. :)

2nd^3p 


Then type:

noop

... to get out of there.

Try our new word:

2nd^3p


Is the Stack:

4
4
4
4
5

???

... and do we get a message saying:

2nd^3p		OK
125		Printed out

???

We did???

Yes!

So do you get the idea???

Good for you!!!

Do 2nd^3p again!!! 


... Okay. Here is just one more simple one.

Say you want to clear the whole Stack. In the simulator
there are 10 positions. We have the word:

drop

... to DROP the top number off the stack.

So to make this new word type:

:

... to go to definition mode.


Let's make a name. I suggest a name that's
easy to remember. So I'll call it:

dropal

... for DROP ALL numbers off the Stack.


As I've said the simulator shows 10 positions. Since DROP
is the only word we have in it, that will pop numbers off ( Besides
. which POPS AND PRINTS the top number off the Stack. You
can try this also if you like. You may want to Print all the numbers
on the Stack, but let's go with DROP for now )

So for each position on the Stack ( 10 ) we would type:

drop

10 times, each time followed by Enter.

drop

drop

drop

drop

drop

drop

drop

drop

drop

drop


Then type:

;

to end the word defintion.

Now if you fill up your Stack and perform:

dropal

You should see all the numbers being DROPped
one by one. Go ahead and try . instead of drop and
this time all the numbers will be POPped off the Stack
except this time they will be PRINTed too.

Make up your own operations/words!
Have fun ...

:-D


ZX////ZX////ZX////ZX////ZX////ZX////ZX////ZX////ZX////ZX////

... and that covers each word you can use in the simulator.
My mini-tutorial may have seemed long and it really isn't. Also I
hope you've seen how it's pretty easy. The simulator only deals
with the ( Parameter ) Stack so you will deal with arithmetic. There
is another Stack that deals with Loops, etc. although that's not
the one we have been practicing here. You can't print text or even
perform direct Reverse Polish Notation ( ie. 4 5 * 1 + 7 / 3 - ) etc.

Also the operators you can use in FORTH are FAR more than
are available in the simulator. The point is to see how the
Stack works, which is important whether you are programming
in FORTH or another language. Even if FORTH isn't your thing
you might find if you are a beginner in another language that
this simulator may be helpful to you.

If this was useful to you, educational, or just fun then
I'm glad you had a good time. It was fun for me to do
and I also learned some stuff along the way. What follows
is the Appendix for using the simulator, I typed straight from 
the book. 

Enjoy!!!

PS- I'm new to FORTH. Just because I wrote this doesn't
mean I'm some guru. If you know of any great FORTH tutorials
for fig FORTH, FORTH-79 and other older FORTHs including
ZX Spectrum FORTH and FORTH for other micros please get
in touch. Even if it's some great "current" implementation of
FORTH you want to let me know about, although I like doing
stuff on micros more I don't mind doing FORTH stuff in Windows
( oh and AMIGA! YES, AMIGA! ) ( I have Leo Brodie's great book
"Starting Forth, but I want more. I want to also manipulate sound,
graphics as well as do all the other stuff )

Since this will probably only be on related sites and not scattered
all over the internet here's my email for this sort of thing:

the.sentinel@charter.net

Thanks!!!

Sunday, 30 May 2004 6:04 am

- the.sentinel

http://webpages.charter.net/the.sentinel/
http://mondodizzy.members.easyspace.com/
http://dizzypetition.members.easyspace.com/

ZX////ZX////ZX////ZX////ZX////ZX////ZX////ZX////ZX////ZX////

( FROM THE BOOK )

Appendix

The FORTH-Stack Simulator



The FORTH-Stack simulator program presented here is
written in Sinclair BASIC and will run on either a 16K or a
48K Sinclair Spectrum. With little modification the simu-
lator should run under most implementations of BASIC. It is
recommended that the FORTH-Stack simulator program is
typed in and SAVEd before the book is used so that the
reader can use the simulator to investigate the properties of
the Stack while he/she is reading about it. If the simulator is
SAVEd with LINE 1,then it will autorun on loading.
     Two types of audio feedback are given to the user. First
the POKE command on line 1 causes a short bleep to be pro-
duced each time a computer key is pressed. Second, the
BEEP command on line 795 causes a slightly longer bleep to
be produced after a FORTH word has been executed, and
indicates that the machine is ready to receive another word.


The Simulator in Action

The FORTH-Stack simulator shows the contents of the Para-
meter Stack before and after a FORTH word is executed, as
shown for example in Figs. 1 and 2. After each FORTH word
is entered, the Stack is updated.

     The simulated stack is 10 positions deep. Empty positions
in the Stack below the data values are shown as zeros by the
simulator, so the simulated Stack never in fact becomes
empty, but rather becomes full of zeros. Although this is an
important difference between the simulated Stack and a true
FORTH Stack it does not affect the ability of the simulator to
perform most of the important Stack operations. An example
of the difference in behaviour between the FORTH-Stack
simulator and a true FORTH-Stack would be in the instance
when nothing has yet been pushed onto the Stack and the 
word . ( which means, pop the value off the top of the Stack

		86


	( This page Shows Figures 1 and 2 )

		87


and print it out ) is typed in. In FORTH, the message STACK
EMPTY would be given. The FORTH-Stack simulator on the
other hand will display:

	0	Printed out

      The simulator will accept numbers but will only keep the
integer part of of the number. Thus, if 2.5 is typed in, 2 will be
pushed onto the top of the Stack.
      The FORTH-Stack simulator will perform the following
arithmetic operations:

	+, -, *, /, mod, /mod, */, and */mod.

It will also perform the following Stack operations:

dup, 2dup, ., drop, swap, over, pick, rot, and roll.


Colon Definitions on the Simulator

It is possible to compile up to ten colon definitions on the
simulator. Each definition can contain up to nineteen words.
      When the simulator prompts the user to enter a Stack
command or a number; if a colon is entered, the simulator
switches into compile mode and prompts the user to enter a
colon definition. The definition is entered one word per line,
starting with the name of the word being defined, and is ter-
minated by a semicolon. When the semicolon is entered, the
simulator switches back into interpret mode and prompts the
user to enter a Stack command or a number. The name of the
defined word is now part of the FORTH-Stack dictionary,
and will execute whenever it is entered. Moreover, as the
new word executes, the Stack effects of each of its component
words are displayed in turn.


Restrictions on Colon Defintions
on the Simulator

    1. All of the arithmetic operators and Stack commands
can be included in a colon definition with the exceptions of
pick and roll, which can only be used in immediate mode.

		88


    2. User defined words which have been defined in colon
definitions cannot be included in other colon definitions.
    3. Numbers cannot be included in colon definitions.


Other Words Available
on the FORTH-Stack Simulator

     stop   This brings the simulator to a halt.
     :    The colon allows the definition of new words.
     ;    The semicolon marks the end of a colon definition.
     defno   Displays the number of new words which have
been defined and gives their names.
     noop    Produces no change on the Stack. This is useful for
redisplaying the Stack after a new word has been defined or
after defno has been executed.

    If something is entered which is not a number, an arith-
metic operator, a Stack operator, or one of the above words,
the program will terminate with a BASIC error message.


Making a Warm Start into the Simulator

A warm start can be made into the simulator by entering
GOTO 1000

		89