Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/196.lha/Forth/readme.txt

Text File | 1988-04-28 | 11KB | 282 lines

                        Forth for Amigas.


   These files comprise an implementation of F83 for Amiga's. F83 is a
public domain Forth system written by Henry Laxen and Michael Perry, for
CP/M and IBM pc's. Several other implementations for different computers
are around, although none for Amiga's ( as far as I know ).
See below for the discription of differences with F83.

First the files making up this system.

1- Readme.txt     The file you are reading.
2- Forth          A compiled kernel ready to "run" from the Dos prompt.
3- Akernel.blk    The source for the kernel.
4- Utility.blk    The utilities which make this system useful, see below.
5- Cpu68k.blk     The forth RPN assembler and low level debugger support.
6- Meta.blk       The meta compiler, to generate your own system(s).

NOTE: THE FILE Utility.blk MUST BE RENAMED TO Utilities.blk, THE
      ARC PROGRAM COULDN'T HANDLE THE LENGTH OF THE NAME AND I
      HAD TO SHORTEN IT.
      AFTER UNARCING, PLEASE RENAME IT:
      rename Utility.blk as Utilities.blk

The version of arc program used:
AmigArc version 0.23, compatible with ARC v 5.0.




To start without reading any further:
After unarcing, start the system by entering, from the Dos prompt:

Forth    ( or )
run Forth

This will load the kernel as supplied and start it running. In the Forth
window you can now enter:

open Utilities.blk
and after the system responds with 'ok' enter either:

ok       ( or )
1 load




In more detail. At the Dos prompt you can enter:

[run] Forth [[nnnn] <any acceptable forth command>]

nnnn - specifies the number of bytes allocated to your 'user dictionary'
       and defaults to 64k bytes. The number must be in hex e.g.
       run Forth A000

After the 'Forth' or 'nnnn' you can enter any Forth command or line of
       Forth commands that the kernel can make sense out of. The most
       useful of course would be to load in the Utilities:
       run Forth open Utilities.blk ok
       The ok is a synonym for '1 load' and will load screen 1 of the
       current file. Usually the load screen for the file.




A bit about running the system.

First of all if you are new to Forth it is best that you get some books on
   the language. Some standard books available:

   STARTING FORTH by LEO BRODIE.
   THINKING FORTH by LEO BRODIE.
   MASTERING FORTH by ANITA ANDERSON and MARTIN TRACY

   These books are available from:
   FORTH INTEREST GROUP
   P.O.BOX 8231
   SAN JOSE, CALIFORNIA, 95155
   [phone]

   And a membership with the above group will also be helpful.
   The Forth Interest Group also has a roundtable on GEnie,
   ( General Electric Network for Information Exchange )

Secondly try to print a listing of the system, to peruse at your leisure.


Following is an explanation of some words which will be helpful in under-
standing the system.

view     When entering view <name>, that is view followed by a word you
list     are trying to understand, the system will display the screen that
l        contains the source code.
b        You can list screens by typing l ( the letter 'l' ). This will
n        list the current screen. If you want to list a particular screen,
a        nn list ( e.g. 45 list ) will list that screen.
         To see the next screen: n l
         To see the previous screen: b l
         Each screen has a comment screen, called the shadow screen.
         You can list it by entering: a l
         This will list the shadow, also called the alternate. Some of the
         explanations maybe of help.

listing  If you have a printer attached and have it set for 132 character
open     lines, you can print the entire current file.
file?    The word 'file?' will echo the name of the current file. If you
files    want to change the current file you enter:
show     open Meta.blk
shadow   After that the current file would be Meta.blk. Typing 'listing'
         will print the entire file with shadow screens beside the source
         code screens.  To see which files are currently known by the
         system type: files
         This will show all the files known and open. If a file is known,
         but is not open a double question mark will be printed. (??)
         A lower level word to print the screens on the printer is show
         Show will print 6 screens of code only on a page. It
         requires a start screen number and an end screen number.
         0 11 show, would print two pages of source code screens.
         Shadow show will print a specified number of screens and their
         shadows, 0 11 shadow show would print 4 pages.


see      Is a decompiler. This word will attempt to decompile high level
         words.  The low level words are in code and cannot be decompiled
         by this word.
         To use 'see' : see listing
         This would decompile the word 'listing'. This together with
         view can provide information about the system.


create   To start your own file you must first create one. The word create
edit     takes care of that: 10 create myfile.blk
id       The above command creates a file called myfile.blk in the current
load     directory, 10 screens long. You will now have to open the file.
done     To enter source code you can start the editor by typing: 1 edit.
         The system will start the editor on screen #1. It will display
         the contents of the screen and ask for an id. Enter any string,
         the standard is the date and initials. The cursor will now go
         to byte 0 on the screen. You can start entering information.
         The arrow keys will allow moving the cursor around.
         See the editor listings, or view the screens for all the commands.
         After entering some information you can exit the editor by first
         typing a control-c to leave the screen editor, then typing: done.
         This will put you back in the normal Forth area.
         Now type nn load, where nn is the screen number you used. Any
         number except 0 is ok to use.


vocabulary  A confusing part of the system can be the vocabularies.
vocs     Vocabularies are lists of words (routines) which belong together,
words    are normally used in a particular context. They are like seperate
current  dictionaries for different applications. For instance a routine
context  called 'i' in the editor context could mean insert. Yet in
         the regular Forth dictionary 'i' will return the index of a
         do loop. The same word can have multiple meanings, depending on
         the context in which it is used. Somewhat similar to English.
         English also has words which mean different this at different
         times, depending on the context they are used in.
         The context, that is which vocabulary (=dictionary) is searched
         for a word can be displayed by the word: order.
         context: forth forth root
         current: forth
         would be a typical reply to that command. The above means that,
         the context is forth; forth is searched. Then root, if the search
         didn't find the word with the name you specified. If it fails again
         it will try to make a number out of it. If that also fails, the
         system will reply with ?  It doesn't know what you want.
         Current means the dictionary which will receive any new words you
         dream up.
         Say you type editor and then type order:
         context: editor forth root
         current: forth
         Now all words will be looked up in the editor vocabulary, then
         forth, then root. The first one found matching the given name will
         be executed.
         At this point you can type: words
         This will show you all the words defined in the editor vocabulary.
         'See' a few of them if you like.  Switch back to forth by
         typing: forth.  Now type: words. Press any key to stop the listing.
         Enter the word: vocs. This will show you all the defined
         vocabularies. Some are used for a specific purpose. Hidden for
         instance is used in printing.

The books listed above can give you more help. I tried to give you a push
in the right direction.



A little more technical information.

This system is NOT 83 standard, for several reasons. It follows closely
F83 from L&P, but again is NOT identical. An identical system is not
feasable on the Amiga.  If you have used F83, this system will be
familiar enough to start using it.


The compiled kernel:

-  Indirect threaded.
-  Singles are 32 bits. Doubles are 64 bits. A cell is 32 bits. An address
   a single or a pointer are interchangable.
-  Opens a Console.device for window input and output.
-  The size of the user ( or application ) dictionary can be specified at
   startup.
-  Uses a linear dictionary, but not connected to the user dictionary.
-  User dictionary can be 'forgotten'. The kernel can not.
-  Uses BSS memory from the Amiga Roms for disk buffers, in/output buffers.
-  Return stack is 1k, needs Meta compiling for larger stack.
-  Parameter stack size is specified by Amiga Dos. I use 8k. (stack 8000)
-  Both stacks are not in the dictionary space.
-  Supports a method of calling Amiga Rom routines. (But is not the final
   word, on Rom routine calling).
-  current size appr 21 k.

The Meta compiler:

The Meta Compiler produces a run file. This file can be executed from
the Amiga Dos prompt. No linking is required.
Since Amiga Dos requires run files to be relocatable, the Meta compiler
had to be modified to produce a relocation table. 32 Bit relocations are
marked in an array. When the system is saved, the relocation information
is appended to the file.
For this same reason, the system cannot be saved after starting it and
loading some utilities. Only Meta Compiling will produce a run file.
To get some memory from Amiga Dos to use as buffers, Block Storage Section,
was added.  This will allocate some memory at startup, courtesy of the
loader.

To Meta compile, you should forget part of the Utilities, presumably
loaded at startup. I use : forget .4
This will forget the dictionary from the dumping routine on up. The Meta
compiler has a short dump routine.
Next start the Meta Compiler by: open Meta.blk ok
This will start the entire sequence. Be sure to resolve any forward
references.
The system is saved by: Save-target <name>
You must also de-allocate the target image memory by entering: free-target.

I encourage you to take a look at Meta.blk to see what is going on, before
you make any changes.



Finally:
If you find any problems, errors or omissions, or would like to comment,
drop me line. You can leave me E-mail on GEnie ( address: P.APPELMAN )
or if you like, use regular mail.





This system is placed in the public domain, may be freely distributed and
copied, as long as the author is given credit and no copyright notice is
placed upon it.


29 Feb 88                        Peter Appelman
                                 1460 Ghent Ave. apt 704
                                 Burlington Ontario, Canada L7S-1X7