Gold Fish 2

home *** CD-ROM | disk | FTP | other *** search

/ Gold Fish 2 / goldfish_vol2_cd1.bin / files / dev / lang / aforth / docs / usingaforth.doc < prev next >

Wrap

Text File | 1994-05-17 | 71.8 KB | 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