home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Gold Fish 2
/
goldfish_vol2_cd2.bin
/
bbs
/
dev
/
aforth-1.4.lha
/
AForth
/
docs
/
UsingAFORTH.DOC
< prev
next >
Wrap
Text File
|
1994-05-17
|
74KB
|
2,100 lines
#1zz
A F O R T H
____________________________________________________________
Version 1.00
A FORTH-79 standard implementation for the Amiga z
Stratagem4 AFORTH for the Amiga
Program and Documentation Copyright (c) Stratagem4, 1994.
AMIGA is a Registered Trademark of Commodore-Amiga, Inc.
FORTH is a Registered Trademark of FORTH, Inc.
All rights reserved.
Stratagem4 AFORTH For AmigaDOS
z
A F O R T H
U S E R ' S G U I D E
______________________________________________________________
Version 1.00
A FORTH-79 standard implementation for the Amiga
Stratagem4
125 Broadview Avenue
Rainham
Gillingham
Kent
ME8 9JD
England
Stratagem4 AFORTH For AmigaDOS
z
Stratagem4 AFORTH for the Amiga User's Guide
Copyright (c) Stratagem4, 1994.
AFORTH was written by Steve Martin
Support Address: Stratagem4
125 Broadview Avenue
Rainham
Gillingham
Kent
ME8 9JD
England
Telephone: (0634) 261412
AMIGA is a Registered Trademark of Commodore-Amiga, Inc.
AmigaDOS and Workbench are trademarks of Commodore-Amiga, Inc.
FORTH is a Registered Trademark of FORTH, Inc.
All rights reserved.
Stratagem4 AFORTH For AmigaDOS
z
__________________________________
Table of Contents
__________________________________
Introduction
1
Hardware Requirements 1
AmigaDOS Compatibility 2
Software Requirements 2
Installation
3
Product Registration 3
Diskette System 4
Single drive Workbench copy 4
Multiple drive Workbench copy 4
Single drive CLI copy 5
Multiple drive CLI copy 5
Difficulties 5
Hard Disk System 6
Workbench 6
CLI 6
The Forth Language
7
A Brief History 7
Standard Comparison 8
Environment 8
Files, blocks and buffers 8
Addressing 9
Programming 9
Language Extensions 9
Programming In AFORTH
11
Programming 11
Interpret 11
Compile 12
Example Programs 13
STEPDOWN.F 13
CALENDAR.F 14
DATAFILE.F 14
CASE.F 14
i z
Table of Contents
Appendices
Bibliography
15
FORTH 15
AmigaDOS 17
Motorola 68000 17
FORTH Loading Concepts
18
AFORTH Reference
20
ii
Stratagem4 AFORTH For AmigaDOS
z
Section 1
__________________________________
Introduction
__________________________________
This is a user's guide for the AmigaDOS version of AFORTH. It
explains how to install and operate the AFORTH environment, and it
also discusses the FORTH language as implemented by Stratagem4.
If you are already familiar with FORTH and AmigaDOS, then you
should have no problems using this guide. However, if you are new
to FORTH and/or AmigaDOS, you may find it useful to refer to some
of the publications listed in
Appendix A, Bibliography
.
Hardware Requirements
The Stratagem4 AFORTH environment may be used on any Amiga
computer with at least 512K of main memory and one diskette drive.
Additional memory will be used if it is available.
AFORTH is a very memory efficient implementation, utilizing only
100K when loaded. This provides the complete environment, the
primary dictionary, and a 64K 'page' for your own extension words
and vocabularies.
Extra hardware items you may want to consider are:
- Additional memory
- Additional diskette drive
- A hard disk drive
- A printer
- A colour monitor, 80 column mode is utilized by this
system, you may experience difficulties using it with a
normal television
1 z
Introduction
Please bear in mind that 100K is a minimum requirement to run this
environment, and that any memory used by your own programs is
not, for obvious reasons, included in this calculation.
AmigaDOS Compatibility
The Stratagem4 AFORTH environment, related programs, and
utilities are compatible with AmigaDOS version 1.2 and above, as
are the programs produced by the system, subject to the use of the
correct library calls when needed. If you find any
incompatibilities please contact Stratagem4 at the address
printed on the facing pages of this manual, or telephone the
number printed thereon. At the time of writing AFORTH has been
successfully tested with AmigaDOS versions 1.2, 1.3, 2.0 and 3.0
in various configurations.
Software Requirements
The Stratagem4 AFORTH environment requires the use of a text
editor for the construction of programs. An editor is not
supplied as any editor capable of producing ASCII output is
suitable, experience has shown that people have their own
preferences and should not be required to change. If you do not
own a text editor then MEMACS, supplied on the Extras disk of your
Workbench disk set, or Ed, contained in the C directory of the
Workbench disk, are suitable. We realize that this is an
implementation decision that may offend FORTH purists and we
apologize to those sad souls, a detailed discussion of this, and
other implementation decisions, follows later in this document.
2
Stratagem4 AFORTH For AmigaDOS
z
Section 2
__________________________________
Installation
__________________________________
The Stratagem4 AFORTH environment is a Shareware distribution, as
such we have little control on the form in which it is
distributed. If you received this package directly from us then
it will be in the form of a single diskette ready to be used, you
should, however, make a backup and store the master in a safe
place. Other distribution sources may distribute the package in a
variety of compressed forms, in this case you should follow the
instructions accompanying that distribution. All distribution
methods should lead, eventually, to a single diskette form.
Product Registration
If you received this package as a new product, instead of an
update, you must register with us in order to receive technical
support and future updates. The accompanying document USER.DOC
explains the registration procedure and the Shareware marketing
concept. Please take the time to read the documentation and, if
you continue to find AFORTH useful, register as it may save you
time in the future.
If you experience difficulty installing or using the package
please contact us immediately. You may do this by telephone or in
writing, USER.DOC explains these options more fully.
3 z
Installation
Diskette System
If you do not have a hard disk then you only need to make working
copies of your original AFORTH disk. Below we detail the
procedure for single and multiple diskette drive systems, using
both the CLI and Workbench environments.
1. Single drive Workbench copy
1.1. Insert your AFORTH disk in drive DF0:, this is your
SOURCE disk, ensure that it is write protected.
1.2. Select the disk's icon by left clicking on it.
1.3. Select
1.3.1. COPY from the ICON menu, 2.0 systems and
above, OR
1.3.2. DUPLICATE from WORKBENCH menu, 1.2 systems and
above.
1.4. Follow the on screen requesters, this may take several
disk swaps in lower memory capacity machines.
1.5. On completion of the above steps you will have a
complete working copy of the master diskette.
2. Multiple drive Workbench copy
2.1. Insert your AFORTH disk in one of the drives, this is
your SOURCE disk, ensure that it is write protected.
2.2. Insert an unprotected disk in any other available drive,
this is your DESTINATION disk.
** WARNING ** ALL DATA ON THIS DISKETTE WILL BE
DESTROYED BY THE FOLLOWING PROCEDURE!
2.3. Left click and hold the SOURCE disk's icon.
2.4. Drag the SOURCE icon over the DESTINATION disk's icon.
2.5. Drop the SOURCE icon by releasing the left mouse
button.
2.6. Follow any on screen requesters.
2.7. On completion of the above procedure you will have a
complete working copy of the master diskette.
4
Stratagem4 AFORTH For AmigaDOS
z
Installation
3. Single drive CLI copy
3.1. Type 'DISKCOPY DF0: TO DF0:'<return>.
3.2. Follow the on screen requesters, inserting SOURCE and
DESTINATION diskettes as required.
3.3. On completion of the above procedure you will have a
complete working copy of the master diskette.
4. Multiple drive CLI copy
4.1. Insert your AFORTH disk in one of the drives, this is
your SOURCE disk, ensure that it is write protected.
4.2. Insert an unprotected disk in any other available drive,
this is your DESTINATION disk.
** WARNING ** ALL DATA ON THIS DISKETTE WILL BE
DESTROYED BY THE FOLLOWING PROCEDURE!
4.3. Type 'DISKCOPY DFx: TO DFy:'<return>.
** NOTE ** x AND y SHOULD BE REPLACED BY THE DRIVE
NUMBERS OF YOUR CHOSEN SOURCE AND DESTINATION DRIVES
RESPECTIVELY.
4.4. Follow the on screen requesters.
4.5. On completion of the above procedure you will have a
complete working copy of the master diskette.
5. Difficulties
In case of difficulty with any of the above procedures
consult the documentation which came with your Amiga system.
5
User's Guide
z
Installation
Hard Disk System
If you intend to run AFORTH from a hard disk then installation is
very straight forward. Details follow for both CLI and Workbench
methods. Note that it is assumed you are familiar with the
necessary steps to create directories, if this is a problem please
consult your system documentation.
1. Workbench
1.1. Create a new drawer on the hard disk to hold the AFORTH
programs.
1.2. Open the AFORTH diskette window and drag at least the
AFORTH icon and the PROGS drawer icon to your new
drawer.
1.3. AFORTH is now installed.
2. CLI
2.1. Create a new directory on the hard disk to hold the
AFORTH programs.
2.2. Type 'COPY AFORTH:AFORTH TO <newdrawer>'<return>.
2.3. Type 'COPY AFORTH:PROGS TO <newdrawer> ALL'<return>.
2.4. AFORTH is now installed.
6
Stratagem4 AFORTH For AmigaDOS
z
Section 3
__________________________________
The Forth Language
__________________________________
This section discusses the origination and definition of FORTH, as
described by the 79-Standard document, and the specific
implementation of that standard, on the Amiga, as AFORTH. We are
not providing a language specification,
Appendix A
lists several
sources which fulfil this function.
A general knowledge of FORTH is assumed, although not essential,
and some technical issues are discussed which will be of interest
to those well versed in the language.
Appendix C, AFORTH
Reference
is provided for your convenience and details each word
in the base dictionary by function, you may find it helpful to
refer to this whilst studying this, and the following, section.
A Brief History
Created in the early 1970's by Charles Moore and Elizabeth Rather,
primarily for the control of radio telescopes, FORTH is a fast,
flexible interactive programming language allowing the creation of
applications by means of extensions to the original language base.
It has been used in many diverse fields, from the creation of
video games, to the animation sequences in 'Star Wars'.
FORTH has been promoted in many ways, FORTH,Inc. promote a
commercial version known as polyFORTH, the FORTH Interest Group a
public domain version known as figFORTH. The FORTH Standards
Team, a subset of the FORTH Interest Group, have promoted FORTH-79
and FORTH-83 with some success. In recent years most applications
have been in the field of embedded control systems, ie. vending
machines, production lines, robots, et al. Some recent software,
notably Real 3D version 2, has incorporated an internal FORTH
system proving that there is quite some life left in this peculiar
language yet!
7 z
The FORTH Language
Standard Comparison
AFORTH is a 100% assembly language implementation of the FORTH-79
standard for the Amiga. Most of the original standard has been
implemented without modification. However, various
implementation decisions were taken which have resulted in the
loss of some words, the modification of some standards, and the
addition of new words.
The following list highlights the differences between AFORTH and
the original 79-standard.
1.
Environment
Normally FORTH offers a complete operating system which
replaces that of the host machine. In the case of the Amiga
it was decided that it was not desirable to replace a
perfectly good operating system, indeed we wish to use AFORTH
as a development platform for stand alone, Amiga friendly,
applications. Thus AFORTH provides a multi-tasking console
environment from which the Amiga, and the language, may be
manipulated.
2.
Files, blocks and buffers
The original storage method consisted of addressing the
storage media as a series of 1K 'blocks', a number of virtual
blocks were maintained known as 'screens'. Data and programs
were addressed by a series of block numbers, which you had to
maintain. This is obviously not satisfactory within the
current computing model and we have, therefore, implemented
'file' storage in its common form - by file name.
2.1. The following FORTH-79 words do not exist as a direct
result of this change:
2.1.1. LIST (n ->) List block n and set
SCR to n
2.1.2. SCR (-> addr) System variable
holding listed block number
2.1.3. UPDATE ( -> ) Mark last block
access as updated
2.2. The following FORTH-79 words have been modified, the
79-standard definitions are given here. Refer to
Appendix B
for a detailed discussion and redefinitions.
2.2.1. LOAD (n ->) Interpret block n,
the resume normal input
2.2.2. BLOCK (n -> addr) Leave address of
block n, reading block from storage if
necessary
8
Stratagem4 AFORTH For AmigaDOS
z
The FORTH Language
2.2.3. BUFFER (n -> addr) Assign free buffer
to block n, leaving its address
2.2.4. SAVE-BUFFERS ( -> ) Write all updated
blocks to storage
2.2.5. EMPTY-BUFFERS ( -> ) Mark all buffers as
empty
3.
Addressing
FORTH-79 uses 16 bit addressing, AFORTH implements full 32
bit addressing. This may appear trivial but it impacts many
defined FORTH words and you should be aware of this change
when converting programs from other systems or, indeed, many
of the example programs given in the texts listed in
Appendix
A
.
4.
Programming
FORTH programs are normally entered via a screen editor
written in FORTH, it is important to note that there is no
official standard for the editor, individual FORTH
implementations vary greatly in this area. We have taken the
decision not to provide an editor as any text editor capable
of producing ASCII files will suffice, as AFORTH multitasks
the range available is quite large. Further discussion
regarding this point may be found in Section 4.
5.
Language Extensions
The following words represent extensions added to ease the
changes in implementation, ease the language generally or are
common extensions we felt should be included.
5.1. SYSTEM ( -> )
Return to AmigaDOS
5.2. MODE ( -> addr)
System variable, zero when word is immediate
5.3. VLIST ( -> )
Print each word in dictionary search path from CONTEXT
to beginning
5.4. D>R (d -> )
Move double number to return stack
5.5. DR> ( -> d)
Retrieve double number from return stack
5.6. DR@ ( -> d)
Copy double number from return stack
5.7. C, (byte -> )
Compile byte into latest defined dictionary entry
5.8. D@ (addr -> d)
Fetch double number at address
5.9. D! (d addr -> )
Store double number at address
9
User's Guide
z
The FORTH Language
5.10. N->UD (n1 n2 -> ud1 ud2)
Make top two signed single precision numbers unsigned
double precision numbers
5.11. DROPD (d -> )
Drop double precision number
5.12. DUPD (d -> d d)
Duplicate double precision number
5.13. D- (d1 d2 -> d3)
Double precision subtraction
5.14. D0< (d -> flag)
TRUE if d less than zero
5.15. D0= (d -> flag)
TRUE if d equals zero
5.16. D= (d1 d2 -> flag)
TRUE if d1=d2
5.17. DABS (d -> |d|)
Absolute double value
5.18. D, (d -> )
Compile double value into the dictionary
5.19. S->D (n -> d)
Make single precision number double precision
5.20. 1D+ (d -> d+1)
Add 1 to double precision number
5.21. 2D+ (d -> d+2)
Add 2 to double precision number
5.22. 4D+ (d -> d+4)
Add 4 to double precision number
5.23. 1D- (d -> d-1)
Subtract 1 from double precision number
5.24. 2D- (d -> d-2)
Subtract 2 from double precision number
5.25. 4D- (d -> d-4)
Subtract 4 from double precision number
5.26. D. (d -> )
Print d with one trailing space
5.27. D.R (d n -> )
Print d right justified in field width n
5.28. .R (n1 n2 -> )
Print n1 right justified in field width n2
5.29. EVEN (n -> flag)
TRUE if n is even
5.30. ODD (n -> flag)
TRUE if n is odd
5.31. MYSELF ( -> )
Compile CFA of word we are compiling into itself,
recursion!
5.32. ASCII ( -> n)
Leave ASCII value of <char> following
10
Stratagem4 AFORTH For AmigaDOS
z
Section 4
__________________________________
Programming In AFORTH
__________________________________
This section will describe the programming environment available
within AFORTH. An introduction to FORTH programming is presented
with reference to the examples to be found in the PROGS drawer.
This is not an instruction text, such works may be found in
Appendix A
.
Programming
FORTH is an extensible language, programming involves writing new
words to perform new operations utilizing, mainly, existing words.
All of these words are truly compiled, so you get maximum
performance from the system at all times.
Words are stored in a dictionary which may be divided into
vocabularies. You initially get a dictionary which holds the
FORTH vocabulary. You could conceivably have a database
vocabulary, a game vocabulary, a French vocabulary....any
vocabulary you want!
FORTH has two modes of operation - interpreted and compiled. We
will now examine both modes using small programming examples to
clarify each point.
1.
Interpret
Interpreted mode is the standard interactive mode of
operation seen in languages such as BASIC. From the AFORTH
console type the following:
CR ." Hello world!" CR
and press the return key (from now on we will assume this at
the end of each line, unless stated otherwise). You should
receive the response:
Hello world!
ok
11 z
Programming in AFORTH
the 'ok' is AFORTH's input prompt. This is a fairly trivial
example of interpretive mode, you type some instructions
(providing they fit on one input line!) and AFORTH
immediately responds. Try these few lines:
2 2 * .
2 2 * 2 BASE ! . DECIMAL
10 2 + .
10 2 + 16 BASE ! . DECIMAL
This helps to emphasize the interactive nature of the AFORTH
environment and introduces Reverse Polish Notation (RPN).
RPN is the method by which FORTH performs mathematics, first
we declare the operands and then the operator. Lines 2 and 4
also show the use of the number BASE variable, line two
prints 4 as a binary number and line 4 prints 12 as a
hexadecimal number. The word DECIMAL sets BASE to base ten.
2.
Compile
Compilation is the means by which new words are added to the
FORTH dictionary. Returning to our previous example type the
following:
: HI CR ." Hello world!" CR ;
Congratulations, you have just written your first FORTH
program! So what happened when you pressed return? Nothing?
Type this:
HI
You should receive the response:
Hello world!
ok
The instructions have been compiled and the word HI has been
added to the dictionary. Now, for completeness, type the
following:
FORGET HI
HI
notice the amnesiac response:
HI ? ok
FORTH has forgotten HI, it has been removed from the
dictionary.
12
Stratagem4 AFORTH For AmigaDOS
z
Programming in AFORTH
This method of compilation, ie. on the terminals command
line, is rather limited. You must finish your definition
before the end of the line, 80 characters, is reached or you
get a nasty message. There is no scope for comments using
this method either and, worse still, no way to save your
programs.
The interpreted program method, and line entry compilation,
are ideal modes for testing your programming ideas, they
encourage short, succinct, words and will help you to think
in a modular way but, for real programming purposes, you need
a text editor. You enter your program in the text editor
using comments, indentation and multiple lines, your source
file may include several word definitions, and then you LOAD
it into AFORTH.
The PROGS drawer contain several example programs, replacing
<pathname> with your system path to the PROGS drawer type the
following:
LOAD <pathname>PROGS/CALENDAR.F"
Providing you have entered the path correctly, and installed
AFORTH according to the instructions in this manual, you
should, after a small delay, receive the 'ok' prompt. Type:
VLIST
and you will notice that a number of new words have been
added to the dictionary. You have just loaded and compiled a
complete vocabulary, named calendar, which was entered on a
text editor away from the AFORTH environment. Note that as
AFORTH is a multitasking environment you may have the text
editor loaded simultaneously and flip between the two by
using the screen depth arrangement gadget in the top right
corner of your screen.
Example Programs
As mentioned earlier the PROGS drawer contains several example
programs. These programs have been carefully selected to
demonstrate certain points about programming in FORTH in general,
and AFORTH in particular. Below you will find a list of these
examples together with an explanation of their particular
relevance to AFORTH.
1.
STEPDOWN.F
A simple new programming construct which illustrates how to
build constructs in FORTH and the use of modules in your
development.
13
User's Guide
z
Programming in AFORTH
2.
CALENDAR.F
An example of a large project type, unlike STEPDOWN this
example produces a useful working vocabulary. Once again a
modular approach is exemplified, in this case the equivalent
of assembling the engine parts into a complex drive
mechanism.
3.
DATAFILE.F
This example demonstrates the use of the modified loading
concept to save and load program data. It also offers an
object lesson in FORTH's ability to modify memory addresses
directly. This file also auto-boots its own demonstration
program.
4.
CASE.F
Finally a useful, some would say essential, extension to the
FORTH vocabulary in the form of a CASE construct. The
included word TESTCASE demonstrates the use of this
important new construct.
14
Stratagem4 AFORTH For AmigaDOS
z
Appendix A
_____________________________
Bibliography
_____________________________
Listed below are a number of publications and articles which have
directly, or indirectly, influenced the production of this program
and its documentation. Also included are a number of works
representing further studies the reader may wish to investigate.
FORTH
~~~~~
Davis, Chris [1988]
Roll Your Own Language, article published in October 1988 issue of
Program Now, Intra Press, Intra House, 193 Uxbridge Road, London
W12 9RA, England.
Pountain, Dick [1988]
Changing Reverse Polish To Infix, article published in January
1988 issue of BYTE, One Phoenix Mill Lane, Peterborough, NH 03458,
USA.
The FORTH Standards Team [1984]
FORTH-83, The FORTH Interest Group, PO Box 1105, San Carlos, CA
94070, USA.
Grandis-Harrison, Dick de [1983-1984]
Various articles published monthly from June 1983 to March 1984 in
SOFT, Sportscene Specialist Press Ltd, 14 Rathbone Place, London
W1P 1DE, England.
Winfield, Alan [1983]
The Complete FORTH, ISBN 0-905104-22-6, Sigma Technical Press, 5
Alton Road, Wilmslow, Cheshire SK9 5DY, England.
Winfield, Alan [1983]
Pascal In FORTH, article published in September and October 1983
issues of SOFT, Sportscene Specialist Press Ltd, 14 Rathbone
Place, London W1P 1DE, England.
15 z
Bibliography
Pountain, Dick [1983]
UnPolished FORTH, article published in June 1983 issue of SOFT,
Sportscene Specialist Press Ltd, 14 Rathbone Place, London W1P
1DE, England.
Pountain, Dick [1983]
Raster Is Faster, article published in July 1983 issue of SOFT,
Sportscene Specialist Press Ltd, 14 Rathbone Place, London W1P
1DE, England.
Ting, H C [1983]
Inside F83, Offete Enterprises, 1306 South B Street, San Mateo, CA
94402, USA.
Knecht, K [1982]
Introduction to FORTH, Howard W Sams & Company, 4300 West 62nd
Street, Indianapolis, Indiana 46268, USA.
Brodie, Leo [1981]
Starting FORTH, ISBN 0-13-842922-7, FORTH Inc.
Fritzon, R [1981]
Write your own pseudo-FORTH compiler, article published in
February and March issues of Micro-computing.
Loeliger, R G [1981]
Threaded Interpretive Languages, ISBN 0-07-038360-X, Byte Books.
Katzan, H [1981]
Invitation to FORTH, Petrocelli Books, Research Park, 251 Wall
Street, Princeton, NJ 08540, USA.
Moore, C H [1980]
The Evolution Of FORTH, An Unusual Language, article published in
August 1980 issue of BYTE, One Phoenix Mill Lane, Peterborough, NH
03458, USA.
The FORTH Standards Team [1980]
FORTH-79, The FORTH Interest Group, PO Box 1105, San Carlos, CA
94070, USA.
Rather, E D, L Brodie and C Rosenberg [1979]
Using FORTH, FORTH-79 standard edition, FORTH Inc.
James, J S
FORTH on microcomputers, Dr Dobbs, no 26.
Moore, C H & E D Rather [1974]
FORTH: A new way to program a minicomputer, Astron. Astrophys.
suppl. 15.
16
Stratagem4 AFORTH For AmigaDOS
z
Bibliography
Moore, C H & E D Rather [1973]
The FORTH program for spectral line observing, Proc. IEEE, vol 61
September 1973.
AmigaDOS
~~~~~~~~
Commodore-Amiga Inc. [1986]
The AmigaDOS Manual, ISBN 0-553-34294-0, Bantam Electronic
Publishing, 666 Fifth Avenue, New York, NY 10103, USA.
Commodore-Amiga Inc. [1986]
Amiga ROM Kernel Reference Manual: Exec, ISBN 0-201-11099-7,
Addison-Wesley Publishing Company, Reading, MA, USA.
Commodore-Amiga Inc. [1986]
Amiga ROM Kernel Reference Manual: Libraries and Devices, ISBN
0-201-11078-4, Addison-Wesley Publishing Company, Reading, MA,
USA.
Commodore-Amiga Inc. [1986]
Amiga Intuition Reference Manual, ISBN 0-201-11076-8,
Addison-Wesley Publishing Company, Reading, MA, USA.
Commodore-Amiga Inc. [1986]
Amiga Hardware Reference Manual, ISBN 0-201-11077-6,
Addison-Wesley Publishing Company, Reading, MA, USA.
Mortimore, Eugene P [1986]
Amiga Programmer's Handbook, Volume I, ISBN 0-895880-343-0, SYBEX
Inc., 2021 Challenger Drive #100, Alameda, CA 94501, USA.
Mortimore, Eugene P [1986]
Amiga Programmer's Handbook, Volume II, ISBN 0-895888-384-8,
SYBEX Inc., 2021 Challenger Drive #100, Alameda, CA 94501, USA.
Motorola 68000
~~~~~~~~~~~~~~
Kane, G, D Hawkins and L Leventhal [1987]
68000 Assembly Language Programming 2nd Edition, ISBN
0-07-881232-1, Osborne/McGraw-Hill, 2600 Tenth Street, Berkely, CA
94710, USA.
Motorola Inc. [1986]
The MC68000 User's Manual 5th Edition, ISBN 0-13-541475-X,
Prentice-Hall Inc., Englewood Cliffs, NJ 07632, USA.
Williams, Steve [1985]
Programming The 68000, ISBN 0-89588-133-0, SYBEX Inc., 2021
Challenger Drive #100, Alameda, CA 94501, USA.
17
User's Guide
z
Appendix B
_____________________________
FORTH Loading Concepts
_____________________________
The FORTH-79 Loading Concept
The original FORTH implemented a VIRTUAL MEMORY MODEL for its
storage requirements, that is to say that it divided the storage
medium (disk or cassette) into a series of 'blocks' and loaded a
range of 'blocks' into memory areas known as 'screens'. A
'block' was given an arbitrary size of 1024 bytes (1K), the
editing screen was also 16 lines high and 64 characters wide-
another 1024 bytes.
This storage method was quite adequate for the fairly
unsophisticated computer systems of the time where 16K of RAM was
considered to be 'massive' and floppy disks normally held about
360K of data. Furthermore, the FORTH system normally replaced the
computers native operating system which meant that it was free to
use the storage media in any way it saw fit.
Typically a user would select an arbitrary range of block
numbers, write a program, using a fairly simple screen editor
implemented in FORTH, over a number of screens, saving them
sequentially to the blocks already selected. File names were not
employed and it was necessary to maintain an index of used blocks,
together with a synopsis of their contents. The LOAD command was
used to load these programs back into memory and submit them to
the FORTH interpreter. The command <100 LOAD> would fetch block
100 from the current storage device and submit it to the
interpreter. A special command (normally ==>) would enable the
automatic loading of the next sequential block.
The AFORTH Loading Concept
As you can see the original FORTH concept does not translate
easily to the modern arena, especially when applied to the Amiga
specifically. In the modern context we MUST implement a file
naming mechanism, usurping a perfectly good operating system is
NOT an option. However, we do not need to provide an editor as
18 z
FORTH Loading Concepts
any ASCII text editor can provide us with source files, this also
means that the user is not restricted to some compromise solution
and can use any editor with which s/he is familiar.
As implemented the user can enter simple programs, ie colon
definitions (new WORDs), on the command line but they cannot
exceed the length of the line, 80 characters from colon to
semi-colon. An ASCII source file is the only way in which WORDs
exceeding 80 characters may be entered, this has the side effect
of allowing definitions longer than allowed in the original
standard implementations, the limit then being a screen full. In
the interests of readability and modularity, not to mention
debugging and code maintenance, you should restrict your
definitions to small simple types, building complexity from their
use in other definitions.
Word Summary
BLK
a variable array containing two 32 bit values, first the
address of the current buffer (zero indicates keyboard
input), and second the size of that buffer. This information
is initialized and maintained by LOAD.
BUFFER
attempts to allocate a memory area of the size requested on
the stack, to be Amiga specific we pass a memory type value
as well where: 0=public, 1=chip, 2=fast.
EMPTY-BUFFERS
frees memory allocated by BUFFER.
BLOCK
opens and loads a file into memory, calls BUFFER to obtain
the required memory, leaves a size and address on the stack
and reports any errors to the screen.
SAVE-BUFFERS
saves memory allocated by BUFFER under a given name.
LOAD
opens file with name following, various error reports, calls
BLOCK.
19
User's Guide
z
Appendix C
_____________________________
AFORTH Reference
_____________________________
Listed below, and on the following pages, is the complete FORTH-79
dictionary, as implemented in AFORTH, including details of all
language extensions. For a detailed discussion of the main
variations and deviations from the standard please refer to the
main text.
Stack notation: (stack before -> stack after)
Operand key:
n,n1 .. 16 bit value
d,d1 .. 32 bit value
addr .. 32 bit address
byte .. 16 bit value whose lower 8 bits only are set or
used
char .. 16 bit value whose lower 7 bits only are set or
used
flag .. 16 bit value representing a Boolean flag
zero=false, non-zero=true (the 'true' value is
normally -1)
u .. unsigned number prefix
Stack Manipulation
DUP (n -> n n) Duplicate top of stack
?DUP (n -> n (n)) Duplicate only if non-zero
DUPD (d -> d d) Duplicate double precision
number
DROP (n -> ) Lose top of stack
DROPD (d -> ) Drop double precision number
SWAP (n1 n2 ->
n2 n1) Reverse top two stack items
OVER (n1 n2 ->
n1 n2 n1) Duplicate 2nd item on top
ROT (n1 n2 n3 ->
n2 n3 n1) Rotate 3rd item to top
PICK (n1 -> n2) Duplicate n1th item on top
ROLL (n -> ) Rotate nth item to top
20 z
AFORTH Reference
DEPTH ( -> n) Count the number of items on
the stack, item = 16 bits
>R (n -> ) Move top item to return stack
R> ( -> n) Retrieve item from return stack
R@ ( -> n) Copy n from return stack
D>R (d -> ) Move double number to return
stack
DR> ( -> d) Retrieve double number from
return stack
DR@ ( -> d) Copy double number from return
stack
Comparison
< (n1 n2 ->
flag) TRUE if n1 less than n2
= (n1 n2 ->
flag) TRUE if n1=n2
> (n1 n2 ->
flag) TRUE if n1 greater than n2
0< (n -> flag) TRUE if n is negative
0= (n -> flag) TRUE if n=0
0> (n -> flag) TRUE if n is greater than zero
U< (un1 un2 ->
flag) TRUE if un1 less than un2,
unsigned compare
D< (d1 d2 ->
flag) TRUE if d1 less than d2
D= (d1 d2 -> flag)TRUE if d1=d2
D0< (d -> flag) TRUE if d less than zero
D0= (d -> flag) TRUE if d equals zero
NOT (flag -> -flag)Reverse truth value
Note that this is effective for
all flag producing comparison
operations, ie. FALSE=0,
TRUE=-1, but may be ineffective
in other situations
EVEN (n -> flag) TRUE if n is even
ODD (n -> flag) TRUE if n is odd
Arithmetic and logical
+ (n1 n2 -> sum) Add n1+n2
- (n1 n2 ->
diff) Subtract n1-n2
* (n1 n2 -> prod)Multiply
/ (n1 n2 ->
quot) Divide, n1/n2, quotient rounded
toward zero
MOD (n1 n2 -> rem) Divide, n1/n2, remainder has
sign of n1
21
User's Guide
z
AFORTH Reference
/MOD (n1 n2 ->
rem quot) Divide with remainder and
quotient, n1/n2
*/MOD (n1 n2 n3 ->
rem quot) n1*n2/n3, with double
intermediate
*/ (n1 n2 n3 ->
quot) n1*n2/n3, with double precision
intermediate
U* (un1 un2 ->
ud) Multiply unsigned, leave
unsigned double result
U/MOD (ud un ->
urem uquot) Divide double number by single,
all unsigned, leave unsigned
quotient and remainder
1+ (n -> n+1) Add 1
2+ (n -> n+2) Add 2
1- (n -> n-1) Subtract 1
2- (n -> n-2) Subtract 2
D+ (d1 d2 ->
dsum) Double precision add
D- (d1 d2 -> d3) Double precision subtraction
1D+ (d -> d+1) Add 1 to double precision
number
2D+ (d -> d+2) Add 2 to double precision
number
4D+ (d -> d+4) Add 4 to double precision
number
1D- (d -> d-1) Subtract 1 from double
precision number
2D- (d -> d-2) Subtract 2 from double
precision number
4D- (d -> d-4) Subtract 4 from double
precision number
MAX (n1 n2 -> max) Compare n1 n2 and leave
greater
MIN (n1 n2 -> min) Compare n1 n2 and leave lesser
ABS (n -> |n|) Make absolute value of n
DABS (d -> |d|) Absolute double value
NEGATE (n -> -n) Change sign, 2's complement
DNEGATE (d -> -d) Change sign of double number,
2's complement
AND (n1 n2 -> and) Bitwise logical AND
OR (n1 n2 -> or) Bitwise logical OR
XOR (n1 n2 -> xor) Bitwise logical XOR
22
Stratagem4 AFORTH For AmigaDOS
z
AFORTH Reference
Memory
C@ (addr -> byte) Fetch byte at address
C! (byte addr ->) Store byte at address
@ (addr -> n) Fetch number at address
! (n addr -> ) Store number at address
D@ (addr -> d) Fetch double number at address
D! (d addr -> ) Store double number at address
? (addr -> ) Print the number stored at
address
+! (n addr -> ) Add n into number stored at
address
MOVE (addr1
addr2 n -> ) Move n numbers starting at
addr1 to addr2
CMOVE (addr1
addr2 n -> ) Move n bytes starting at addr1
to addr2
FILL (addr
n byte -> ) Fill n bytes starting at addr
with byte
Control Structures
DO (end start ->) Set up DO..LOOP or +LOOP given
index range
LOOP ( -> ) Add one to index, exit loop
when index>=end
+LOOP (n -> ) Add n to index, if n>=0 exit
when index>=end, else exit
when index=end
I ( -> n) Fetch current loop index value
J ( -> n) Fetch next outer loop index
value
LEAVE ( -> ) Force DO loop termination
IF (flag -> ) Construct IF...THEN,
IF...ELSE...THEN
ELSE ( -> ) In construct IF..ELSE..THEN
THEN ( -> ) In construct IF..THEN,
IF..ELSE..THEN
BEGIN ( -> ) Mark start of UNTIL or WHILE
loop
UNTIL (flag -> ) Construct BEGIN..UNTIL, loop
until flag is true
WHILE (flag -> ) In construct
BEGIN..WHILE..REPEAT
REPEAT ( -> ) Loop while flag true at WHILE
EXIT ( -> ) Prematurely exit this colon
definition
EXECUTE (addr -> ) Execute word whose CFA is at
address
23
User's Guide
z
AFORTH Reference
Character input-output
EMIT (char -> ) Print character
CR ( -> ) Print carriage return and line
feed
SPACE ( -> ) Print one space
SPACES (n -> ) Print n spaces
." ( -> ) Print text delimited by "
TYPE (addr n -> ) Print the string of n
characters at address
COUNT (addr ->
addr+1 n) Fetch count byte n and point to
string
-TRAILING (addr n1 ->
addr n2) Reduce character count by
trailing spaces
ASCII <char> ( -> n) Leave ASCII value of <char>
STATE smart - if compiling
compiles n as LITERAL
KEY ( -> char) Wait for a key press and leave
its ASCII value on the stack
EXPECT (addr n -> ) Read n characters, or until
return, from keyboard into
memory at addr
QUERY ( -> ) Read 80 characters, or until
return, from keyboard to input
buffer
WORD (char -> addr) Read next word from input
stream using char as terminal
delimiter. Leave address of
length byte.
Number input-output
BASE ( -> addr) System variable, current
numerical base
DECIMAL ( -> ) Set BASE to decimal
. (n -> ) Print n with one trailing space
U. (un -> ) Print unsigned with one
trailing space
D. (d -> ) Print d with one trailing space
D.R (d n -> ) Print d right justified in
field width n
.R (n1 n2 -> ) Print n1 right justified in
field width n2
CONVERT (d1 addr1 ->
d2 addr2) Convert string at addr1+1 to
double, add to d1 leaving d2,
addr2 is address of first non-
convertible character or 0 if
converted ok
24
Stratagem4 AFORTH For AmigaDOS
z
AFORTH Reference
<# ( -> ) Begin a formatted number
conversion
S->D (n -> d) Make single precision number
double precision
N->UD (n1 n2 ->
ud1 ud2) Make top two signed single
precision numbers unsigned
double precision numbers
# (ud1 -> ud2) Convert next digit of ud1 and
HOLD it
#S (ud -> 0 0) Convert and HOLD all remaining
significant digits
HOLD (char -> ) Insert character into formatted
string
SIGN (n ud -> ud) HOLD minus sign if n is
negative
#> (ud -> addr n) End formatted number
conversion, drop ud and prepare
string for type
Mass storage input-output
BUFFER (d n ->
d addr) Allocate a memory block of
size d and type n, leave the
size d and address of the
allocated block. Addr will be
zero if the allocation failed.
n=type where 0=PUBLIC, 1=CHIP,
2=FAST
d=size in bytes
BLOCK (addr1 ->
d addr2) Open and read into storage the
file whose name is at addr1,
report errors to the console.
Leaves buffer size, d, and
address, addr2. Both values
will be zero if failed.
LOAD <name> ( -> ) Load and interpret file <name>
SAVE-BUFFERS (d addr1
addr2 -> d
addr1 flag) Write contents of buffer at
addr1, size d, under name at
addr2 to storage. Report all
errors to the console. Leave
the size, address and a flag.
EMPTY-BUFFERS (d addr -> ) Frees memory block at address
of size d, the block should
have been allocated by BUFFER
25
User's Guide
z
AFORTH Reference
Defining words
: <name> ( -> ) Begin colon definition of
<name>
; ( -> ) End colon definition
VARIABLE <name> ( -> ) Define variable <name>.
<name> ( -> addr) Returns PFA when executed
CONSTANT <name> (n -> ) Define constant <name> with
value n.
<name> ( -> n) Returns n when executed.
VOCABULARY <name> ( -> ) Define a vocabulary <name>.
<name> ( -> ) Becomes CONTEXT vocabulary
when executed
CREATE <name> ( -> ) Create an empty dictionary
entry <name>.
<name> ( -> addr) Returns PFA when executed
DOES> ( -> ) Defines run time action of
most recently defined word.
Used to define defining words.
Vocabularies
CONTEXT ( -> addr) System variable, vocabulary for
word searches
CURRENT ( -> addr) System variable, vocabulary for
definitions
FORTH ( -> ) Set CONTEXT to main FORTH
vocabulary
DEFINITIONS ( -> ) Set CURRENT vocabulary to
CONTEXT vocabulary
' <name> ( -> addr) Find PFA of <name>
STATE smart - if compiling
compiles address as a LITERAL
FIND ( -> addr) Find CFA of next word in input
stream
FORGET <name> ( -> ) Forget all definitions back to
<name> inclusive
VLIST ( -> ) Print each word in dictionary
search path from CONTEXT to
beginning
Compiler
C, (byte -> ) Compile byte into latest
defined dictionary entry
, (n -> ) Compile n into latest defined
dictionary entry
D, (d -> ) Compile double value into the
dictionary
ALLOT (n -> ) Add n bytes to the Parameter
Field of the latest defined
dictionary entry
26
Stratagem4 AFORTH For AmigaDOS
z
AFORTH Reference
IMMEDIATE ( -> ) Mark most recently defined
word as immediate
LITERAL (n -> ) Compile n as a literal
STATE ( -> addr) System variable, non-zero when
compiling
MODE ( -> addr) System variable, zero when word
is immediate
[ ( -> ) Stop compiling and start
executing
] ( -> ) Stop executing and start
compiling
COMPILE ( -> ) Compile the CFA in the
following PFA
[COMPILE] ( -> ) Compile the CFA of the
following word even if
immediate
MYSELF ( -> ) Compile CFA of word we are
compiling into itself,
recursion!
Miscellaneous
( ( -> ) Begin comment, terminated by )
HERE ( -> addr) Address of next available
dictionary location
PAD ( -> addr) System variable, address of 256
byte scratchpad
BLK ( -> addr) System variable, details
current input buffer
>IN ( -> addr) System variable, offset into
input buffer
EOF ( -> addr) System variable, TRUE when end
of buffer
DPL ( -> addr) System variable, number of
decimal places in most recently
converted word, -1 if single
precision
SYSTEM ( -> ) Return to AmigaDOS
ABORT ( -> ) Clear all stacks and return
control to keyboard
QUIT ( -> ) Clear return stack and return
control to keyboard
79-STANDARD ( -> ) Verify that system conforms to
FORTH-79 standard
27
User's Guide
z
__________________________________
Index
__________________________________
i z
Index
. 24 Addressing 9
." 24 AFORTH 1, 2, 3, 7, 8
.R 10, 24 disk 4, 5
, 26 diskette 6
: 26 environment 1, 2, 3
; 26 icon 6
! 23 programming
? 23 environment 11
?DUP 20 programs 6
' 26 Standard Comparison
( 27 8
[ 27 AFORTH environment 2
[COMPILE] 27 ALLOT 26
] 27 AmigaDOS 1, 17
+ 21 compatibility 2
+! 23 version 1, 2
+LOOP 23 AND 22
- 21 Arithmetic and logical 21
-TRAILING 24 ASCII 2, 9, 10, 24
* 21 Backup
*/ 22 Difficulties 5
*/MOD 22 Multiple drive CLI 5
/ 21 Multiple drive
/MOD 22 Workbench 4
< 21 Single drive CLI 5
<# 25 Single drive
= 21 Workbench 4
> 21 BASE 12, 24
>IN 27 BEGIN 23
>R 21 BLK 27
# 25 BLOCK 8, 25
#> 25 BUFFER 9, 25
#S 25 C, 9, 26
@ 23 C! 23
0< 21 C@ 23
0= 21 CALENDAR.F 14
0> 21 CASE.F 14
1+ 22 Character input-output 24
1- 22 CMOVE 23
1D+ 10, 22 Comparison 21
1D- 10, 22 Compile 12, 27
2+ 22 Compiler 26
2- 22 CONSTANT 26
2D+ 10, 22 CONTEXT 26
2D- 10, 22 Control Structures 23
4D+ 10, 22 CONVERT 24
4D- 10, 22 COUNT 24
79-STANDARD 27 CR 24
ABORT 27 CREATE 26
ABS 22 CURRENT 26
ii
Stratagem4 AFORTH For AmigaDOS
z
Index
D. 10, 24 FigFORTH 7
D.R 10, 24 FORTH,Inc. 7
D, 10, 26 History 7
D! 9, 23 Interest Group 7
D+ 22 PolyFORTH 7
D- 10, 22 Standards Team 7
D< 21 The,Language 7, 11
D= 10, 21 FORTH purists 2
D>R 9, 21 FORTH-79 7, 8
D@ 9, 23 FORTH-83 7
D0< 10, 21 Hard disk 4
D0= 10, 21 Hard disk install
DABS 10, 22 CLI 6
DATAFILE.F 14 Workbench 6
DECIMAL 12, 24 Hard disk installation
Defining words 26 CLI 6
DEFINITIONS 26 Workbench 6
DEPTH 21 Hard Disk System 6
Diskette System 4 Hardware Requirements 1
Distribution sources 3 HERE 27
DNEGATE 22 HOLD 25
DO 23 I 23
Documentation 3 IF 23
DOES> 26 IMMEDIATE 27
DPL 27 Implementation decisions
DR> 9, 21 2
DR@ 9, 21 Incompatibilities 2
DROP 20 Installation 3
DROPD 10, 20 Installing 3
DUP 20 Interpret 11
DUPD 10, 20 J 23
Ed 2 KEY 24
Editor 2 Language Extensions 9
ELSE 23 LEAVE 23
EMIT 24 LIST 8
EMPTY-BUFFERS 9, 25 LITERAL 27
Environment 8 LOAD 8, 13, 25
EOF 27 Loading
EVEN 10, 21 AFORTH 18
Example Programs 13 FORTH-79 18
EXECUTE 23 LOOP 23
EXIT 23 Mass storage input-output
EXPECT 24 25
Extras disk 2 MAX 22
Files, blocks and buffers MEMACS 2
8 Memory 23
FILL 23 MIN 22
FIND 26 Miscellaneous 27
FORGET 26 MOD 21
FORTH 1, 7, 26 MODE 9, 27
iii
User's Guide
z
Index
Moore, Charles 7 VARIABLE 26
MOVE 23 VLIST 9, 26
MYSELF 10, 27 Vocabularies 26
N->UD 10, 25 VOCABULARY 26
NEGATE 22 WHILE 23
NOT 21 WORD 24
Number input-output 24 Workbench disk 2
ODD 10, 21 Working copies 4
OR 22 XOR 22
OVER 20
PAD 27
PICK 20
Product Registration 3
Programming 9, 11
QUERY 24
QUIT 27
R> 21
R@ 21
Rather, Elizabeth 7
Registration procedure 3
REPEAT 23
Reverse Polish Notation
12
ROLL 20
ROT 20
S->D 10, 25
SAVE-BUFFERS 9, 25
SCR 8
Shareware
distribution 3
marketing 3
SIGN 25
Software Requirements 2
SPACE 24
SPACES 24
Stack Manipulation 20
STATE 27
STEPDOWN.F 13
SWAP 20
SYSTEM 9, 27
Text editor 2, 9
THEN 23
TYPE 24
U. 24
U* 22
U/MOD 22
U< 21
UNTIL 23
UPDATE 8
USER.DOC 3
iv
Stratagem4 AFORTH For AmigaDOS
c
