FORTH Stack Simulator

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








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