pygmy.txt

Embedded magazine source code in the year 1990

   
              SAVE YOUR.COM

   Note that BOOT can be re-vectored as above at anytime, not just when 
meta-compiling.

   The source code in PYGMY.SCR is set up to choose between monochrome and 
color displays automatically.  The word  'VIDEO supplies the two address 
used by RESET to setup the system variables  CRTC  and  VID  to the correct 
addresses for the monitor you are using.

     For a color monitor VID is set to $B800 and CRTC is set to $03D4 and 
for a monochrome monitor, VID is set to $B000 and CRTC is set $03B4.

   Thus, a single version of Pygmy, should run on either color or 
monochrome.  I think Pygmy will now work on all MSDOS & PCDOS systems that 
have video display memory at either $B000 or at $B800.  If you have any 
trouble with it on your system, please send me full details.


Chapter 15                   VOCABULARIES

     PYGMY, like cmFORTH, has two vocabularies: FORTH & COMPILER.  Compiler 
words are immediate by virtue of being in the COMPILER vocabulary. 
INTERPRET only looks up words in FORTH.  When compiling, COMPILER is 
searched first.  A word found in COMPILER is executed immediately otherwise 
FORTH is searched and if the word is found it is compiled.  To force 
compilation of a COMPILER word, precede it with a backslash ( \ ).  This is 
used in place of the FORTH-83 word [COMPILE].  CONTEXT holds the number 
that represents which of the two vocabularies is active.  Whichever it is, 
that is the vocabulary into which new words will be linked.  FORTH & 
COMPILER set CONTEXT to the appropriate number.

     There are also has 2 "spare" vocabularies available for use by the 
meta-compiler.


Chapter 16            ADDITIONAL INFORMATION

   For additional information, browse through all of PYGMY.SCR using the 
editor ( n EDIT ) and the PgDn & PgUp keys.  Search across (F9 in the 
editor, after setting up the search string with F3) is handy for finding a 
particular word's definition or where it is used.  Use search across as a 
substitute for VIEW, which is not available.



Chapter 17                   ADDRESSES


     I'm glad to hear your comments.  I can be reached on GEnie as 
F.SERGEANT or via the post office:
                  Frank Sergeant 
                  809 W. San Antonio St. 
                  San Marcos, Texas  78666


for info on signing up with GEnie dial 1-800-638-9636


Join FIG, send $30 (in North America) to 
   Forth Interest Group        [phone]
   P.O. Box 8231
   San Jose, CA  95155
FIG is a great source for Forth related publications.

East Coast Forth Board bulletin board  [phone]

ACM SIGForth  
    c/o ACM
        Box 12115
        Church Street Station
        New York, NY  10249
        [phone]
     or
        George Shaw [phone]
        Dan Miller  [phone]


Chapter 18                     The Glossary

     If you don't have the printed glossary, use the file PYGMY.SCR and the 
editor's PgUp, PgDn, and F3 F9 search across screens to find the words you 
want more info about.


Chapter 19                     MEMORY MAP

     Pygmy fits in one 64K segment.  DOS loads it at offset $0100.  CS@ 
will fetch the contents of CS (the code segment), in case you need to know 
the absolute address of the program.  The dictionary grows up from low 
memory. The stacks & TIB and disk buffers are in high memory (within the 
one segment).

origin                $0100
boot code             $0100
1st word (null)       $010B
system variables      $0116 - $0147
dictionary continues  $0148
HERE                  $29C5  ( perhaps, if assembler is not loaded)
TIB @                 $F300  ( TIB is $100 bytes below the 1st disk)
                             ( buffer.  The last disk buffer is    )
                             ( always at $F800                     )
1st disk buffer       $F400  
2nd disk buffer       $F800 
data stack pointer    $FE00  ( grows down from FE00)
return stack pointer  $FF00  ( grows down from FF00)


     It also has 2 "spare" vocabularies available for use by the 
meta-compiler.

Chapter 20                      FILES

     MAX-FILES may be open at once.  If you want a different mix, use 
RESET-FILES and open a new set or re-setup the files one by one with UNIT. 
If you then save an image of Pygmy, next time you bring it up, those files 
will be opened for you automatically.

     To install a file, you must say what the starting block number should 
be. I usually set them up in 300 block increments, but you may choose 
whatever increment you wish.  It is no longer important that they be in 
ascending order.  If the third file opened was handled this way   

          NAMEZ: DUMMY.BLK
          600 DUMMY.BLK 2 UNIT
          2 OPEN

then the beginning of the file would be screen 600.  Previous (to 1.3) 
versions allowed you to alter the block numbers with which you accessed a 
file by using the word UNIT which set OFFSET to some value.  In version 
1.3, there is no word OFFSET, and UNIT has an entirely different use!  Now 
UNIT establishes which starting number and file name go with which "unit" 
number.


Chapter 21                  DIRECT THREADED

     Pygmy is direct threaded, with TOS kept in a register (BX) for speed.

     Constants are coded "in-line" rather than by jumping to a central 
constant routine.  This costs 2 bytes per constant but saves 40 cycles (46 
vs 86) on the 8088.  System variables are really coded as constants.  So 
this method helps speed up the system.  Note that the system variable TIB 
returns the address of the address of the terminal input buffer, as in 
figForth.

     Variables don't seem to offer the same advantage and so they still use 
a central routine.

     DEFER/IS deferred words are supported.  EMIT, KEY, KEY?, CR, BOOT, 
ABORT, NUMBER, LITERAL, -FIND, and CREATE are deferred. 
           ( e.g.  DEFER EMIT   ' (EMIT) IS EMIT    )


Chapter 22               HISTORY & PHILOSOPHY

     Pygmy was based on cmFORTH by Charles Moore.  cmFORTH is designed for 
the NOVIX Forth chip.  cmFORTH doesn't include an assembler as that's not 
needed for the NOVIX.  Also, it doesn't include an editor, as it is 
designed to be used with a host terminal or computer that supplies the disk 
storage and editing facilities.  A Forth for the IBM PC/XT etc., can't do 
without an assembler and editor, and so these have been included as part of 
Pygmy.

     The goal for Pygmy is not to copy cmFORTH exactly, but to use it as a 
starting point for a fast lean Forth that can be used for serious 
application development.

     I've added multiple files (up to 15, but you can change it to fewer if 
you like) open at the same time, and the default set are opened 
automatically.  This was inspired by Dennis Ruffer's notes on GEnie about 
Forth Inc's PolyForth.  If you want up to 200+ files open at once, see the 
supplemental code in PYGMY.SCR.

     The editor is fast and is so much more comfortable than the line 
editor in F83 that I'm satisfied for now.  Still, I don't feel I've 
completely solved the problem of managing source code.  The addition of 
"holes" SETTLE CHOP have helped.

     I want it small & fast, but I want it comfortable too.  I worry that 
it has grown too big.

     I have not added vocabularies. I like the cmFORTH idea of marking 
immediate words by the fact that they are in the COMPILER vocabulary!  
Everything else is in FORTH.  Is this a problem?  I don't think so, for me, 
but it makes for a crowded & busy WORDS listing and forces assembler words 
to end in commas.  

     The auxiliary words can be unlinked from the dictionary to speed up 
searches and to unclutter WORDS somewhat.  See HIDE in the supplemental 
definitions.  I don't, personally, use HIDE, but I've included it for you 
if want it.  

     DO/LOOP have not been included.  If you miss them too much, load them 
(Robert Berkey's version) from PYGMY.SCR screen #171.  I've been enjoying 
using FOR/NEXT and have not missed DO/LOOP.  I changed FOR/NEXT so it does 
the loop n times instead of n+1 times.  This was suggested and inspired by 
Rob Chapman.

     I no longer use cmFORTH's  TYPE ( a - a').  In cmFORTH it expects to 
find a count at the first byte of the address.  Instead I use a regular  
TYPE ( a # -).  In addition there is TYPE$ ( a -) which expects the address 
of a counted string.  It does COUNT TYPE and does not leave an address on 
the stack.

     There are 3 name changes in cmFORTH (& Pygmy) that delight me:  

             new names        old names

                  PUSH               >R
                   POP               R>
                     \        [COMPILE]

I think I always get >R & R> right, but it gives me hell every time I have 
to think about which is which. PUSH & POP are so much better names, in my 
opinion, and so much easier to read.  I don't see how you can try them and 
then go back to >R & R>.  I also prefer \ to [COMPILE].  I like comments in 
parentheses, so do not mind losing \ for that purpose.  Also it is shorter 
and clearer (I think) than [COMPILE] once you get used to it.

     The stack comment for cmFORTH's  M/MOD is ( l h u - q r) but I have 
implemented it as the more familiar ( l h u - r q).  

     Of course, there are extensive changes from cmFORTH because the 
primitives had to be coded in 8088/8086 machine language rather than NOVIX. 
I may have made other changes due to my failing to appreciate the beauty & 
simplicity of how CM did it.  I hope anyone noticing such denseness on my 
part will point it out to me.

     I am far from satisfied that I have found the "perfect" Forth in 
Pygmy.  Overall I am pleased.  There are many areas where Pygmy "works, but 
isn't pretty."  The compromise I like is where you give up something you 
don't want to get something you do want.  When I see one of those it is an 
easy decision.  The more common decision is where you give up something you 
do want for something you think you prefer but aren't quite sure, or where 
you give up something you really want for something you have to have.

     I think there is room for a number of different styles of Forth.  
Speed with lots of primitives in machine language versus ease of porting to 
other microprocessors by having a minimal number of primitives:  I (more or 
less) went for the speed.  I traded off some efficiency in disk access for 
a much more regular and comfortable file interface.  I've supplied the 
hooks for sequential file access (see FILE-READ FILE-WRITE >POSITION >EOF 
>BOF etc.) primarily for accessing data files in various formats, rather 
than for loading source code from text files.  Sometime I want to try for 
raw speed with "Forth owns the whole disk" but I haven't reconciled that 
with my need for co-existing with DOS, which I feel I have to do at this 
time.  I've left out VIEW and substituted a search-across-screens in the 
editor.  But, I've included a fairly complete SEE for colon definitions.  
The supplemental hashing dictionary search mechanism is something I use 
almost all the time (it can be thrown away for the target system).


Chapter 23           How to Print the Source Code

     SHOW prints source code screens 3 per page.  SHOW2 prints source code 
screens 6 per page (your printer must allow 132 character lines).  These 
words are now included in PYGMY.COM, so you don't have to load anything.  
If you are using SHOW2, you must set up the word CONDENSED so it will work 
with your printer.  See screens #83 and #150-155 for more info.  Once you 
have CONDENSED set correctly for your printer,  type

                0  182  SHOW

  or

                0  182  SHOW2

to print the entire contents of PYGMY.SCR.  If you are using an HP LaserJet 
II, IIP, or III, (or many other printers) you can set the characters per 
inch from the front panel (internal font #10 on a II, for example) and just 
set CONDENSED to a NOP  ( e.g.   ' NOP IS CONDENSED ).

       
                         **** The End ****