pygmy.txt

Embedded magazine source code in the year 1990

   LMOVE has been renamed MOVEL.  I have my doubts as to which is the
better name.  It still takes a word count rather than a byte count.  I
also have doubts about that and think a byte count would make more
sense, but have not changed it yet.

   Fast DO LOOP are now available from Robert Berkey. (Ver. 1.3 note: ALL 
source code is now in PYGMY.SCR.)

   TYPE ( a # -)  replaces the cmFORTH TYPE ( a - a').  I have also
added  COUNT  and  -TRAILING to support it.  I like the cmFORTH TYPE (
a - a') but the ending address was only used in one or two places so
I've changed it to TYPE$ ( a -).

   NUMBER now understands hexadecimal literals such as  $8000   $FF and
ascii character literals such as   'A   'B   'z.

   .S  has been changed so it shows exactly what is on the stack,
rather than showing 3 values regardless of how many are present.  This
is much prettier, although more expensive.

   The opening greeting also shows the default files that are open.  I
found the first thing I always did was type   .FILES  so I built that
into the default (BOOT word.

   "   has been added for in-line string literals.  At compile time it
compiles the following text up to the ending quote mark as a counted
string.  It then commas in a zero byte, which is not included in the
count.  The purpose of this is to make it easy to setup "asciiz"
strings for DOS.  E.g.  : TST  " this is a string "  TYPE$  ;

   -FIND and CREATE are now DEFER'd words to make experimenting with
these easier.  See next paragraph.

   The file HASH.SCR (ver. 1.3 note: this code has been moved to PYGMY.SCR) 
contains code to do very rapid dictionary searches.  This is not built into 
Pygmy.  If you want to use it, you must load it.  Then hashing is optional  
(  HASH-ON  HASH-OFF).  You can use it for development and then leave it 
off in the final application.  It devotes the 64K segment above Pygmy's 
segment to the hash table.  To find a word probably takes an average of 
less than two compares.  Unfortunately this is not the only factor involved 
in compiling speed.  My quick tests suggest that with HASH-ON the time it 
takes to load an application is approximately 1/3rd less than with 
HASH-OFF.  The larger the dictionary the more time will be saved.


Chapter 9            What Is New With Version 1.3

     File handling has been overhauled.  Everything is now done relative to 
the unit# of the file.  See UNIT, SETTLE, CHOP, OPEN, ?CLOSE, etc.

     ABORT is now a DEFER'd word, to make customizing applications easier.

     For Leonard Morgenstern, NUMBER & LITERAL are now DEFER'd.  (This also 
makes adding the double and quad number extensions easier!)

     (ONEKEY  is the default for KEY.  It returns a single value no matter 
what key is pressed, rather than a single value for some keys and two 
values for other keys, as DOS does.  I MUCH prefer the consistency of a 
single value.

     All the source code is now in a single (block) file.  All the 
documentation is now in a single (text) file.

     Meta-compiling is even easier.

     WORD no longer does BLOCK every time (for faster loading).

     SEE now handles abort"  "  etc. and recognizes non colon words.

     FILES now keeps track of the highest block # in the file. Neither the 
editor nor BLOCK will go outside actual file bounds anymore.

     HOLES added to editor (F9).  SETTLE & CHOP make managing block files 
more convenient.

     Search across now always goes to end of file, no need to set the 
ending screen number.

     THRU no longer uses the data stack, so multi-screen definitions which 
pass arguments on the stack can now be loaded with THRU.

     Added N! ( n a - n) to store n into a, keeping a copy of n

     Changed FOR/NEXT so 0 FOR ... NEXT goes thru loop zero times &  
u FOR ... NEXT goes thru loop  u times.  Robert Berkey suggests spelling it 
?FOR.

     ABORT" now includes the IF.

     Added +UNDER ( a b c - a+c b).

     Added NIP ( a b c - a c).

     Straightened out the redundant EXIT.  


Chapter 10                        TIPS

     Set Caps Lock on.  Most words must be typed in UPPER CASE.

     To abandon changes you have just made in the editor, use Esc to get 
out of the editor then type   EMPTY-BUFFERS

    ?SCROLL  is embedded in WORDS and DU  to let you halt the display
by pressing any key (except Esc).  Press any key again to start it up
again (except Esc).  To bail out, whether you are scrolling or paused,
press Esc.  You can also put ?SCROLL into your own words.  For my tastes, 
this is very much better than the common practice of aborting the display 
when you press the <Enter> key.

    DUMP ( a - a')  and DU ( a # - a') allow you to inspect memory.
DUMP dumps one line and leaves the address of the next line ready for
typing DUMP once more.  DU repeats DUMP for a number of lines.  ?SCROLL
is built in, so feel free to type  0  2000 DU  (you can get out of it
with Esc, or pause with any key).  You'll probably want to say HEX first.

    .FILES ( -) shows the files that are currently open and the block 
numbers associated with them.  You can open ANY type of file; you are not 
limited to Forth style BLOCK files.

     The word ." works either inside or outside of colon definitions.  
There is no need for the abomination  .(    
(Actually there are two  ."s  one is in FORTH and the other is in 
COMPILER.)

     Pygmy recognizes $xxxx as a hex number (e.g.  $2000 or $1FFE) and it 
recognizes character literals as well (e.g.  'A  'B  'C  'z).  The hex 
literals are a great convenience and allow us to stay in DECIMAL more of 
the time.  The character literals allow us to avoid the ugly CHAR & [CHAR] 
or ASCII & [ASCII].

     NOT in Pygmy inverts the truth value on the stack.  It is equivalent 
to 0=.  If you want to invert each bit individually, use  -1 XOR



Chapter 11                    How Files Work

     There are some changes in version 1.3.  I'll discuss the philosophy 
more in another place.

     Pygmy can access a number of files "simultaneously."  As shipped, it 
contains 15 slots or units for files.  This can be changed to a smaller 
number if you wish.  If you must access more (perhaps over 200 files), that 
can be done also, and sample code is included in PYGMY.SCR.  Before you can 
access a file, it must be installed into one of the slots.  This is done by 
the word UNIT.  UNIT establishes the file's starting block number and the 
file's name (as it is known to DOS).  This name can include the full path, 
including drive, for those cases where the file is not in the default 
directory.  The parameters for UNIT are starting-screen#, file-name, and 
unit#.  The file-name is the address of a counted string that ends in a 
zero byte (for the DOS "asciiz" format).  There are several ways to define 
the name.  Most of the time I use the word NAMEZ: which defines a word 
whose name is the string.  For example, 

             NAMEZ: YOURFILE.SCR

defines a Forth word YOURFILE.SCR that returns the address of the counted 
string "YOURFILE.SCR" with the required zero-byte following the name.  Now 
that we've defined the file name, we can install it into unit# 7 and 
declare that its starting block number will be 3000 by typing

             3000 YOURFILE.SCR 7 UNIT

Note, that this does not open, create, check, or do anything with the 
actual file.  Once a file name and starting block number are equated with a 
particular unit#, everything else we want to do to that file is done by 
referring to its unit#, in this case 7.

     To open the file, type

             7 OPEN

     To create a new file, type

             7 MAKE

     To close the file, type

             7 ?CLOSE

     Once you have set up the name and number with UNIT, you can open and 
close the file repeatedly without using the word UNIT again.  If you want 
to use that slot (unit) for a different file, just set up the new name and 
number with UNIT, by typing, for example,

             NAMEZ: MYFILE
             4000 MYFILE 7 UNIT
             7 OPEN

The file that was previously in unit# 7 will be closed automatically before 
the new file is opened.  The question mark on ?CLOSE indicates that it 
closes the file if it is open, but doesn't blow up if the file is not open.

     As shipped, Pygmy version 1.3 has two files that are already installed 
in units 0 & 1.  These are PYGMY.SCR, which contains all the source code, 
and YOURFILE.SCR, which contains 8 blank screens.  These are automatically 
opened for you and ready to go.  YOURFILE.SCR is provided so the new user 
of Pygmy has a file ready to go for his own source code.

     Any time you want to see which files are installed in units, whether 
they are open, or what their starting block numbers are, type

             .FILES

     You are not limited to these files!  Close them all down with 
RESET-FILES if you like, and open your own set.  If you save that image of 
PYGMY  (ie  SAVE TST1.COM), whenever you bring up that image (by typing 
TST1 at the DOS prompt) your custom set of files will automatically be 
opened for you (and the list of names and starting block numbers will be 
displayed).

     When installing file names with UNIT, be sure to give each file a 
different starting block number, so the block numbers do not overlap.  It's 
probably neater to set them up with ascending numbers.  For example, unit 1 
could start with block #0, unit 2 with #300, unit 3 with #600, etc. 
However, that is not necessary in version 1.3.  All block numbers must be 
lower than 8192.

     Each block in the entire system of open files has its unique number.  
There is no need to use the F83 OPEN/FROM CONVEY.  There is no need for 
OFFSET.  To copy a range of blocks, whether to and from the same or 
different files, just say  ( from to #) COPIES   e.g.

             17   300  50  COPIES

to copy the 50 blocks starting at block 17 to the 50 blocks starting at 
block 300.  It is an error if those blocks do not exist.  In earlier 
versions of Pygmy you could extend a file just by accessing a block past 
the end of file.  In version 1.3, the blocks must already exist.  To extend 
a file, either use the word MORE or use F9 from within the editor.  It does 
not work quite like the MORE of F83.  If the file is not empty, the easy 
way to extend it is to get in the editor and move to the last block and use 
the F9 key (which does MORE for you).  For copying a single block you can 
still use COPY.




Chapter 12                  The Assembler

     The 8088/8086 assembler in Pygmy is a regular Forth postfix assembler. 
For examples of how it is used, browse through PYGMY.SCR.

     Begin a code word with CODE and end it with END-CODE, e.g.

         CODE DUP    BX PUSH,   NXT,   END-CODE

     Except in special cases (& then you know what you are doing) code 
words must perform next somehow.  In Pygmy, this code is laid down in-line 
(by the word  NXT,) rather than by a jump to a central next routine.

     If your routine disturbs CS, DS, BP, SP, SI, or BX it must restore it.  
The direction flag must be left clear.

     BP points to the return stack.

     SP points to the data stack.  The top (data) stack item is kept in BX 
rather than on the actual stack.  See example above for DUP.

     DS:SI is Forth's IP register.  AX is Forth's W register, but you may 
use it freely without restoring it.

     The assembler words generally end in a comma, signaling they actively 
comma data into the dictionary.  This is useful for another purpose: as the 
assembler words and the regular Forth words all sit in the same vocabulary 
(FORTH), the comma helps distinguish between similar words, e.g. THEN & 
THEN,


     It is a "structured" assembler with
     
    <set-codes> <condition> IF,   XXXXXX    ELSE,   XXXXXX   THEN,
and 

     XX #, CX MOV, BEGIN,  XXXXX  LOOP,     
etc.