pygmy.dow

copyright 1989-2007 Frank C. Sergeant - frank@pygmy.utoh.org      See the file PYGMY.TXT for documentation.                       BSD/MIT/X-style license, see file license20040130.txt.          All of the source code for Pygmy Forth is contained in the    block file PYGMY.SCR.                                                                                                             This block file, PYGMY.DOW, is the "shadow" file for          PYGMY.SCR.  This can be used as a Glossary.  You can search     this file and PYGMY.SCR from within Pygmy's editor, using       F3 F10 to search across blocks to find information on a         particular word.  Or you can use VIEW <word> then Ctrl-A.                                                                         You can also convert these block files to text files, using   BLK>TXT, and browse the text files with a text editor.                                                                                                                                             This is the load block for creating a new kernel.  It        loads other load blocks to accomplish the overall task of       generating a new version of the kernel and saves it as A1.COM   or B1.COM etc (see the SAVEM or SAVE commands on blocks 1 and   5).                                                                                                                                As I generate new versions of Pygmy I cycle through the      alphabet using names like B1.COM, C1.COM, etc.  Whenever I      change the name on this block I also change it on block 5       in 3 places.                                                                                                                    That way I keep the new versions together as sets, e.g.         A1.COM, A2.COM, A3.COM, and A4.COM, although there is no        particular need to create or keep the intermediate executables  (i.e. A2.COM and A3.COM in the above example).                                                                                     TMAX-FILES determines how many "slots" or units will be      available for files.  It must be a power of 2 (ie 2, 4, 8, 16). Ordinarily, only 15 files will be available due to DOS          limitations.                                                                                                                       TFILES is true (ie -1) if you want to allow loading from     textfiles and is false if you do not want to allow textfiles.                                                                      TNB determines how many disk buffers will be available.  It  must be 1 less than a power of 2 (ie 1, 3, 7, 15).                                                                                 The target image starts at $8000.                                                                                                                                                                                                                                                                                            ( metacompiler load block)                                                                                                         If generating a new kernel goes awry and you wind up with    garbage on the stack, you can uncomment-out the 7 LOAD in       order to use special debugging versions of LOAD and THRU that   show the stack contents after each block is loaded, and let     you start and stop the display by pressing any key.  Look for   the error at the boundary between the blocks that load with     a "stack empty" messages and the blocks that load with a        non-empty stack.                                                                                                                                                                                                                                                                                                                                                                                                                                                ( kernel load block)                                              Include support for loading from text files if TFILES is true.  HEADERS must be on, at least until after the null word is     defined on block 19.  If an entire application is to be         metacompiled with headers off, put HEADERS ON prior to loading  block 19 then put HEADERS OFF after loading block 19, e.g.                HEADERS ON   19 LOAD   HEADERS OFF   20 67 THRU         Patch the address of RESET into boot.                           Patch the file name PYGMY.SCR into the unit# table, so that           it will be opened automatically.                          Initialize the voc-heads for the two vocabularies.              Initialize the target's dictionary pointer.                     Use the right brace to switch the active dictionary space backto host.  The load block that loaded this block (i.e. block 1)  will take care of saving the target image that has been created.                                                                ( extensions load block)                                           WARNING: be sure SET-EDGE is high enough that the lower      dictionary does not run into unPRUNE'd headers in the upper.       This is the load block to use from a new generated kernel    (e.g A1.COM) to extend with the editor, assembler, and various  other words.  Note especially  140 142 THRU.  These 3 blocks    serve as both an index and a set of load blocks for many        optional words.  Simply placing or removing a left parenthesis  in column 1 of those 3 blocks controls which of the options     will be loaded.                                                    YOURFILE.SCR is set up to start at block 2000.  Its          purpose is to hold the source code that _you_ write.  It starts out as 8 blocks long, but you can extend it with the editor's   F9 key to as many blocks as you need.                                                                                                                                                           (  conditional compilation)                                                                                                        Do not use  .IF ... .ELSE  ...  .THEN  inside colon          definitions and do not nest them.  They allow you to compile or not compile various blocks depending on the value of a flag.    See block 4 for an example.  They can also be used for other    purposes (i.e. when you need an interpretive conditional.)                                                                         ?LOAD serves a similar, but more limited purpose.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               These are alternate versions of LOAD and THRU that can       be loaded if you want to follow the progress of the             meta-compilation.  If you load these, then each block number    will appear as that block is loaded, and the stack will be      displayed (by .S).                                                                                                                 This makes it easy to see where things are screwing up if    you are getting trash on the stack.                                                                                                The word XREF is not ordinarily loaded.  It gives a          cross reference of the words in the target dictionary, along    with their future addresses.  Call it between >PRN  and  >SCR   to send the output to the printer.  Call it before PRUNEing and between curly braces.                                           XREF ( -)  print a cross reference of words in active vocab.                                                                                                                                       RAM will be used later by the metacompiler to keep track     of the locations of the system variables.  On the PC the entire kernel is in RAM, but Pygmy on other processors or systems has  the option of running from RAM or ROM.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             These variables hold the address of the corresponding target runtime routines.  These are needed by the meta-compiler so it  can compile the proper code.  As each runtime routine is definedin the target, its address is stored into its corresponding     variable.                                                                                                                       VARIABLE TVAR  ( variable)         VARIABLE TLIT   ( literal)   VARIABLE TCOL  ( docol)            VARIABLE TBRA   ( branch)    VARIABLE T0BR  ( zero branch)      VARIABLE TEXIT  ( exit)      VARIABLE TFOR  ( for)              VARIABLE TNEXT  ( next)      VARIABLE TARR  ( array)            VARIABLE TABORT ( abort")    VARIABLE TDOT  ( dot")             VARIABLE TNULL                                                                                                                                                                                                                                                                                                                                               {   ( -)   switch between host & target spaces.                 }   ( -)   switch between host & target spaces.                                                                                 RECOVER  ( -)  uncompile the 2 bytes for EXIT at the end of         a colon definition.  RECOVER can be used after words that       end in an endless loop, because the EXIT laid down by ; will    never be reached.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              THEAD creates a header except for the view field and a       possible indirect pfa.  It is used by HEAD on the following     block.                                                                                                                                                                                                                                                                                                                          e.g.   |  : NEW-WORD ....  ;   would make NEW-WORD headerless.  It works on all types of words, not just colon definitions.                                                                                                                                                                                                                                                                        HEAD creates a header.  If H/LESS is ON then it switches     dictionary space so the header will vanish when the target      dictionary space is PRUNE'd.  When making a headerless header   it sets up an indirect pfa so that the metacompiler can locate  the actual pfa in order to compile it into other words that     will use this headerless word.  For non-headerless words, HEAD  lays down the view field and then calls THEAD to do the rest    of the work.                                                                                                                       $D6 is used as the "magic" marker in the temporary header's  pfa of a headerless word.  It is chosen because it is an unused opcode value, so should never appear in a headerful word's      pfa.                                                                                                                                                                                                                                                                                                                            forget ( -)   smudges the name field of the most recently          defined target word, making it temporarily un-findable          in the dictionary during metacompile time.                                                                                   These are the metacompiling versions of the compiling words.                                                                    CONSTANT ( n -)  defines a constant in the target dictionary.      Its value cannot be used directly during meta-compilation.                                                                   ARRAY ( a -) ( n -)  ( runtime: n is a word, not byte, index)     defines an array of 16-bit numbers in the target dictionary.                                                                                                                                                                                                                                                                     These words re-link the target dictionary so that the correctvalues will be present in the link fields.                                                                                      SCAN ( lfa - lfa) follows the link fields backwards to find the    next one that is in the target dictionary space.                                                                             TRIM ( lfa new-lfa - new-lfa)  converts the previous link field    address from a physical address to a logical address and        stores it in the current word's link field, then unsmudges      the current word's name field in case it is smudged.                                                                         CLIP ( voc-head -) goes through all the words in a vocabulary,     TRIMing each one, then links the 1st word to the null word.                                                                  PRUNE ( -)  CLIPs each of the target's vocabularies.                                                                               Some regular words need to be re-named so we can still get tothem after we have defined meta-compiler versions of them.                                                                      FORTH' ( -) sets CONTEXT to the host's FORTH vocabulary.                                                                        COMPILER' ( -) sets CONTEXT to the host's COMPILER vocabulary.                                                                                                                                  :'   ( -) starts a colon definition in host's FORTH vocabulary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 LITERAL ( n -) compiles a 16-bit literal into the target.                                                                       ]  ( -)  is the meta-compiler's colon compiler.  It looks up the   next word from the input stream and does something with it.     If the word is in the host's COMPILER, the word is executed.    Else, if the word is in the target's FORTH, the word is         compiled.  Else, if the word is a valid number in the           current base, it is compiled as a literal.  Else, an error      is reported.  Sequence is everything.  This approach, plus      the ability to switch between host & target spaces with         curly braces, is the secret to the simplicity of the            meta-compiler.                                                                                                                                                                                                                                                  Meta-compiler words to create target looping & branching     structures within target colon definitions:                                                                                     BEGIN ( - a) saves the address to branch back to.               UNTIL ( a -) compiles a conditional branch to address a.        AGAIN ( a -) compiles an unconditional branch to address a.     THEN  ( a -) completes a branch started by IF ELSE etc.         IF    ( - a) starts a conditional branch.                       WHILE ( a - a a ) starts another conditional branch.            REPEAT ( a a -) completes a BEGIN WHILE structure.              ELSE   ( a - a) starts the false part of an IF statement.       FOR  ( - a) starts a FOR NEXT loop.                             NEXT ( a -) completes a FOR NEXT loop.                                                                                          \ ( -)  compiles the following word from target's COMPILER.                                                                     ABORT" ( -) ( flag-)  compiles following error message.                                                                         ."     ( -) ( -) compiles following string to be typed later.                                                                   [']    ( -) compiles pfa of following word from target's FORTH         as a 16-bit literal.                                                                                                     FORTH  ( -) sets CONTEXT to target's FORTH.                                                                                     COMPILER ( -) sets CONTEXT to target's COMPILER.                                                                                :  ( -) starts a colon definition in target dictionary.  Note      that it lays down a jump (it's faster) and not a call.                                                                       ;  ( -) ends a colon definition in target dictionary.                                                   End of the Meta-Compiler               Start of the Pygmy Forth Kernel                                                                                     6 & 8 are the CONTEXT values for the target's FORTH &        COMPILER vocabularies.                                                                                                          boot ( -) is where the execution of the PYGMY.COM file starts.       It is made headerless by  | .  It initializes                   the two stack pointers and jumps to the word  RESET.                                                                       $    ( -) is the "null" word.  The dollar sign is not its real       name.  Its real "name" has a length of zero.  It is named       $, then the -2 ALLOT erases the dollar sign and length.         The  0 C,  changes the length to zero.  When null is            executed it exits an endless loop.  This happens, for           example, when the input stream is exhausted.                                                                                                                                               UP must be the first of the system variables.                   At the moment, it looks like we are using 21 system variables   plus the slots for the buffer numbers plus the slots for the    4 vocabularies.  So, the 32 could possibly be reduced to 25     (representing the 21 system variables plus the 4 vocabularies), but we will leave extra cells.                                                                                                  Every task must have 6 cells for user variables.  We leave room in the main terminal task for 44 more cells.  This may be       overkill, but it lets us add many user variables without needingto regenerate the kernel.                                                                                                                                                                                                                                                                                                                                                                       lit ( - n) is the runtime routine for a literal.  It pushes the     following 16-bit word to the data stack.                                                                                    array ( n - a) is the runtime routine for an array.  It pushes      the address of the nth 16-bit entry of the array to the         data stack.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 var ( - a) is the runtime routine for a variable.  It pushes        the address of the variable to the data stack.                                                                              0branch ( n -) If the top of stack is non-zero, the following       in-line address is skipped.  If the top of stack is zero,       a jump to the following in-line address is taken.               "zero branch"                                                                                                               branch  ( -) An unconditional jump to the following in-line         address is taken.                                                                                                           following is how a variable is compiled into the dictionary      VIEW,LINK,NAME,JMP<var>,VALUE                                     2   2    ?      3       2      (# of bytes in each field)                                                                                                                                    docol ( -) is the runtime routine for a colon definition.  It      nests down a level so the following list of addresses will      be executed.  Note that this routine is entered via a JMP and   not a CALL instruction.  This is faster on the 8088/8086.                                                                    dodoes ( -) is the runtime routine for DOES> words.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             for ( u -) is the runtime routine for FOR.  It pushes the loop      count to the return stack and jumps immediately to the          end of the loop.  This works similarly to cmFORTH's -ZERO,      but is built-in.  Because of this, one count of the loop        is thrown away, allowing the body of the loop to be             executed u times instead of u+1 times.  It also means that      the body of the loop is not executed at all when u=0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       next ( -) is the runtime routine for NEXT.  It decrements the        loop count on the return stack.  If the count was not           zero on the previous pass through the loop it branches          back to the beginning of the loop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         EXIT ( -) is the runtime routine of ;  (semi-colon).  It             unnests one level, thus terminating the current word.           It can be used used by itself to force termination of           a word early.  For example,                                        : TST ( n -) IF EXIT THEN ." n is zero" ;                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  System variables.  These are the addresses of ...            PREV  the last referenced buffer                                OLDEST  the oldest loaded buffer                                BUFFERS ( u - a) returns addr of block number of buffer u.      NB ( - Number-of-buffers-less-one) This is a constant.          TIB @ gives addr of terminal input buffer                       H/LESS & HEADERS  flags to allow headerless words               SPAN the number of characters last read by EXPECT               >IN  the offset into TIB or disk block                          BLK  the current block #, or zero when input is from keyboard.  dA   allows ,A and } to relocate the dictionary                 SCR  current block being edited                                 ATTR video attribute that will be applied by .ATTR or CLS       >FIN & FBLK analogous to >IN & BLK but for textfile loading        ( continued on next block )                                                                                                  ( System variables - continued)                                 #TIB & #FIB length of active terminal & file buffers            FIB @ gives address of file input buffer for textfiles          FIBH the handle number that matches current contents of FIB     EBUF buffer address of block being edited                       BASE the current base.  see DECIMAL & HEX                       H    the dictionary pointer.  Some Forths call it DP.           ( followed by room for 4 unnamed vocabulary heads)                                                                              CONTEXT ( - a) holds backwards offset to active vocabulary.        A value of 2 is used for FORTH and a value of 4 for COMPILER.                                                                                                                                                                                                                                                                                                                                ( blank )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       USER variables are local to the current task.                                                                                                                                                                                                                   commonly used numbers are defined as constants: 0   1   -1    2                                                                 ( instead of a central docon, CONSTANTS are defined in-line)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    1+  ( n - n+1)  increments the value on the top of stack (TOS). 1-  ( n - n-1)  decrements the value on TOS.                                                                                    SP!  ( a -) initializes the data stack pointer.                 RP!  ( a -) initializes the return stack pointer.                                                                                   Note that in some Forths, SP! and RP! take their values     from the data stack, and so does Pygmy as of version 1.5.       However, previous versions of Pygmy did not.  Look over any     of your old code that used SP! or RP! to be sure you now        pass a parameter.                                                                                                                                                                                                                                                                                                                                                                               CS@ ( - seg) returns current value of register CS.  All of          Pygmy is in this segment, except possibly the stacks            could be placed elsewhere (but usually are not).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               These words read and write to and from the I/O ports.                                                                        P! ( n port -)                                                  PC! ( c port -)                                                 P@ ( port - n)                                                  PC@ ( port - c)                                                                                                                                                                                 NOP ( -)  This word does nothing (except take up a little time      and a little space).  Its main use is as a place holder.        "no op" (short for "no operation").                                                                                                                                                                                                                                                                                                                                                                                                                         COMP ( a1 a2 len  -  -1 | 0 | +1 ; a1<a2=-1;a1=a2=0) compares      two strings and returns a zero if they are equal.  A non-zero   means they are not equal, with -1 indicating that the 1st       string is less than the 2nd string, and +1 indicating that      the 1st string is greater than the 2nd string.  In this         case, "less than" and "greater than" refer to the strings'      collating sequence.  " AABZ" is less than " ABAZ" and strings   of zero length are considered equal.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            For speed, 2* & 2/ use shift instructions.                                                                                   2*  ( u - u*2)  shifts TOS left one bit.                                                                                        2/  ( u - u/2)  shifts TOS right one bit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       ( stack operators)                                                                                                              DROP ( n -)                                                     NIP  ( a b - b)                                                 ROT ( n1 n2 n3 - n2 n3 n1 )                                     SWAP ( n1 n2 - n2 n1 )                                          OVER ( n1 n2 - n1 n2 n1)                                        DUP ( n - n n)                                                  ?DUP ( n - n n | n) makes a copy of n only if it is non-zero.   2DUP ( d - d d)                                                 2DROP ( d -)                                                                                                                                                                                                                                                                                                                                                                                                                                                    + ( n n - n) adds two numbers.                                                                                                  +UNDER ( a b c - a+c b) increments a by c without disturbing b.                                                                 - ( a b - n) subtracts b from a.  The order of the operands       does make a difference in subtraction and division.             Fortunately, we use the same order in Forth as is used          with in-fix notation (e.g. "7-3" becomes "7 3 -").                                                                            NEGATE ( n - -n)  takes two's complement of n.  It is used to     reverse the sign of a number.                                                                                                 D2* ( l h - l h ) multiplies double number by 2 by shifting left                                                                                                                                   Single operand flag words                                                                                                    0= ( n - f) returns -1 (true) if n is zero and returns 0 if        n is non-zero.  "zero-equal"                                                                                                 NOT ( n - f) does exactly the same thing as 0=.  NOT is used       to invert a truth value on the stack.  In some Forths it is     the name of a word that inverts individual bits.  In Pygmy      you can invert the individual bits with    -1 XOR                                                                            0<  ( n - f)  returns -1 (true) if n is less than zero.            "zero-less-than"                                                                                                                                                                                                                                                                                                                 Bit operators                                                                                                               OR ( n n - n) does a bit by bit OR.                                                                                             XOR ( n n - n) does a bit by bit Exclusive OR.                                                                                  AND ( n n - n) does a bit by bit AND.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Two operand flag words                                                                                                       <  ( n n - f) "less than"                                                                                                       >  ( n n - f) "greater than"                                                                                                    =  ( n n - f) "equals"                                                                                                          U<  ( u u - f) "U less than" does an unsigned compare.                                                                          U>  ( u u - f) "U greater than" ditto                                                                                                                                                                                                                                                                                                                                                                                                                           U/MOD  ( u u - r q)                                                                                                             U/  ( u u - q)                                                                                                                  UM/MOD  ( ud u - r q)                                                                                                           */  ( n1 n2 n3 - n) ( n1*n2 / n3) with double intermediate          product.                                                                                                                    *   ( n n - n)                                                                                                                                                                                                                                                                                                                                                                                                                                                  /  ( dividend divisor - quotient) Signed division.                                                                              M* ( n n - d) multiplies two signed singles giving a signed        double product.                                                                                                              UM* ( u u - ud) ditto but unsigned                                                                                              M/ ( l h n - q) divides a signed double by a signed single,        giving a signed single quotient.                                                                                             UMOD ( u u - r)                                                                                                                                                                                                                                                                                                                 ! ( n a -) stores value n at address a.  "store"                                                                                N! ( n a - n) does same thing as ! except it keeps n.                                                                           @ ( a - n)  fetches the 16-bit contents of address a. "fetch"                                                                   +! ( n a -) increments the value at addr a by n. "plus store"                                                                   C! ( b a -) stores byte value b at address a. "C-store"                                                                         C@ ( a - b) fetches byte value from addr a. "C-fetch"                                                                           2@ ( a - d) fetches the double value from address a. "two-fetch"                                                                2! ( d a -) stores the double value d at address a. "two-store"                                                                                                                                 CMOVE  ( fr to # - ) moves # bytes from fr to to, byte by byte.      "C-move"                                                                                                                   CMOVE> ( fr to # - ) accomplishes almost the same thing              as CMOVE, except the move starts at the high end of the         range (ie at fr+#-1) and works down to fr & to.  This lets      you slide a string up without merely replicating the 1st        byte.  "C-move-up"                                                                                                         FILL ( addr # value -) fills # bytes starting at addr with the       byte value.                                                                                                                                                                                                                                                                                                                   Return stack operators                                       PUSH  ( n -) pushes the value on top of the data stack to the         return stack.  Some people prefer the name >R.            POP   ( - n) retrieves the top value on the return stack and          pushes it onto the data stack.  Some people prefer the          name R>.                                                  R@    ( - n) copies the top value on the return stack to the          data stack, without removing it from the return stack.    I     ( - n) is the down-counting index in a FOR NEXT loop.  It       is identical to R@.  "eye"  However, it is defined later        as a COMPILER word so as not to interfere with the I of         the line editor.                                                                                                          U*/  ( u1 u2 u3 - u) ( u1*u2 / u3) with double intermediate                                                                                                                                     BETWEEN  ( n low hi - f) returns true if n >= low and n <= hi.                                                                  WITHIN  ( n low hi - f) returns true if n >= low and n < hi.      note that x 0 0 WITHIN is always true regardless of the         value of x, that is, x 0 0 WITHIN is equivalent to              x 0 65536 WITHIN                                                                                                              ODD?   return true if number is odd                                                                                             EVEN?  return true if number is even                                                                                                                                                                                                                                                                                                                                                                                                                            ( 3DUP WRAP UBETWEEN 2SWAP 2OVER )                                                                                              3DUP  ( a b c - a b c a b c)                                                                                                    WRAP  (n low high - n')                                          This is like CLAMP except it "wraps around".  If n is less      than low, then return high.  If n is greater than high, then    return low.  Otherwise, return n.                                                                                              UBETWEEN ( u low high - f)                                                                                                      2SWAP ( a b c d - c d a b)                                      2OVER ( a b c d - a b c d a b)                                                                                                                                                                                                                                                                                                  ABS  ( n - u) returns the absolute value of n.                                                                                  MIN  ( n n - n) returns the lower of the two numbers.                                                                           MAX  ( n n - n) returns the higher of the two numbers.                                                                          EXECUTE ( pfa -) executes the word whose parameter field address     is on the stack.  E.g.   ' DUP EXECUTE  is the hard way         to execute DUP.                                                                                                                                                                                                                                                                                                                                                                                                                                            These DEFER'd I/O words can be revectored to suit the occasion.                                                                 DEFAULT-EMIT is a holding place for whatever routine you want      forced back into EMIT by (ABORT and by >SCR - usually (EMIT                                                                  EMIT  ( c -) is a DEFER'd word that displays the character c.   KEY  ( - c) is a DEFER'd word that (waits for and) returns the       value of a key pressed.                                    KEY? ( - f) is a DEFER'd word that returns true if a key press       is pending or false if not.  It doesn't wait.              CR   ( -) is a DEFER'd word that displays a carriage return.                                                                    AT   ( y x -) for positioning the cursor on the display         CUR@ ( - y x) returns the current cursor position               CLS  ( -)     clears the video screen                                                                                           Video functions using the IBM PC or compatible BIOS routines                                                                                                                                                                                                    (AT  ( row col -)                                                                                                               (CUR@  ( - row col)                                                                                                             (EMIT  ( c -)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   Video functions using the IBM PC or compatible BIOS routines                                                                                                                                    CODE AT@ ( - aacc) read attr & char at current cursor pos                                                                                                                                       CODE .ATTR ( # -)  use this word to actually apply the video      attribute stored in ATTR.  The cursor position does not         change.  See how it is used in the following word.                                                                                                                                            (CLS  ( -)   clear the video screen using .ATTR                                                                                                                                                                                                                                                                                 ((KEY   ( - c) calls DOS to get a key.  KEY usually points to          (KEY which uses ((KEY.                                   (KEY?  ( - f) calls DOS to find out if a key has been pressed.         KEY? usually points to this word.                        (BYE ( -) sets cursor at bottom of screen & returns to DOS.               BYE calls this word after FLUSHing the disk buffers.  DOS ( DX CX BX AX - AX carry) calls DOS function $21.  Carry is     usually set if there was an error and cleared if no error.  DOS2 ( DX CX BX AX - DX AX carry) also calls DOS function $21,      but returns more information.                                                                                                    Whether you use DOS or DOS2 or write your own code word to do a dos call depends on the particular function you are        invoking.  If you need the value the function returns in        register DX, then use DOS2.                                                                                                     QUIT is DEFER'd here to eliminate some forward references                                                                       ?SCROLL ( -) lets you halt the display temporarily, just by         stabbing out blindly and pressing any key.  Again               pressing any key will re-start it.  Pressing Esc forces         an abort.  For this to work, ?SCROLL must be inside the         loop of the currently executing word.  It is already built      into WORDS and DU (dump).  You can put it in your own loops     to let you start & stop the display.                        (CR  ( -)  sends a carriage return followed by a line feed.     (KEY ( - c) regularizes the code returned for a keypress, so      that for the extended keys, the most significant bit is set,    rather than returning two codes for them.  It also wraps the    call to (KEY? in a loop with PAUSE to allow other tasks to      execute.                                                      DECIMAL & HEX set the base to ten or sixteen.                                                                                   C@+ ( a - a+1 c) fetches the byte at addr a and increments the      addr.  This is handy for stepping through byte arrays.                                                                      COUNT ( a - a+1 #) converts a counted string into an address                       and count.                                   TYPE  ( a # -) displays # chars, starting at addr a.            TYPE$ ( a -)  displays the counted string at addr a.            -TRAILING ( a # - a #') chops off the ending blanks of a string.SPACE  ( -) displays a space.                                   SPACES ( n -) displays n spaces if n is not less than zero.                                                                                                                                                                                                                                                                                                                                                                                                     EXPECT ( a # -) accepts up to # characters and stores them         starting at a.  It is terminated when either # characters       have been received or when a carriage return is received.       The count of the number of characters stored is placed in       SPAN.  If it is terminated by a carriage return, the carriage   return is not stored and is not included in the count.  Back    Space is the only editing key recognized.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       Numeric Conversion                           HOLD plugs characters into the numeric output string being           built.                                                     DIGIT  converts a digit to its ASCII value.                     <#     starts the numeric output conversion process.            #>     terminates the numeric output conversion process.                  and prints the string (do not follow it with TYPE).   SIGN   plugs a minus sign into the string if TOS is non-zero.   #    produces one digit of the string.                          #S   at least one digit plus all remaining significant digits.  (.)  builds a signed string.                                    .R   displays a signed number, right justified.                 .    displays a signed number.                                  U.R  displays an unsigned number, right justified.              U.   displays an unsigned number.                                                                                                                                                               .H    display the number in hex (and show at least 2 digits)                                                                    DUMP  displays the contents of memory, 16 bytes at a time,            in both hexadecimal and character format, and leaves            the next address on the stack, ready for typing DUMP            once more.  It saves and restores the current base.                                                                                                                                       DU    this is a shorthand to execute DUMP a specific number           of times.  It includes ?SCROLL so it is safe to give            it a large number and then use the Esc key to abort it,         providing the display is slow enough.                                                                                                                                                                                                                                                                                     HERE   returns addr of next free dictionary location.           PAD    returns addr of a (scratch pad) work area.                      It floats above HERE.                                                                                                    ABORT ( -) or ( - blk#) or ( whatever) is a DEFER'd word that       is performed by abort" if TOS is true.                                                                                      abort" ( f -) is the runtime routine for ABORT".  It calls ABORT     if TOS is true, else it jumps past the error message.                                                                      dot"  ( -)  is the runtime routine for  .".  It types the            following in-line string.                                  (")  ( - a) is the runtime routine for ".  It pushes the             address of the following in-line counted string.                                                                                                  Buffer Manager                           ADDRESS  calculates the address of buffer u.                    ABSENT   used by BLOCK.  If block # is                              already in a buffer, its buffer number is stored in PREV,       the return stack is altered so that BLOCK will immediately      terminate, and the address of the buffer is returned.  If       it isn't, it returns u and allows BLOCK to continue.        UPDATED  used by buffer.  It finds the oldest buffer             that was not just PREViously used and sets PREV & OLDEST to     that number.  If the block that was in that buffer has not been changed (UPDATED), it terminates buffer, returning addr of buf. Else it returns addr of buf and block# that must be re-written.UPDATE   marks the most recently accessed buffer as changed.    ESTABLISH   uses the oldest buffer for this block.                                                                                                                                                     Allow multiple block Files open at same time                                                                             MAX-FILES ( - #slots-less-one) Must be a power of 2 less 1.     FILES ( - a) holds handle, number of blocks, and                   address of file name for each file.  Each entry is 6 bytes      long:  handle  number-of-blocks  address-of-name.               When empty or closed, handle is -1.                                                                                          >UNIT#   converts a block number to a unit number.              HANDLE   addr of handle for unit u.                             #BLOCKS  addr of count of full or partial blocks for unit u.    FNAME    addr of file name for unit u.                          RANGE    returns starting and ending block numbers for unit u.                                                                                                                                                                                                                                                                  LBLK   converts a global block number to the local block number        and corresponding handle.  The local block number is            relative to the start of the file.  It also does the            range check to verify the requested block actually              exists.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  .FILE ( u -) displays the file name associated with unit u.                                                                     .FILES ( -) displays the unit#, 1st & last block numbers,          handle number, and file name, for each of the entries in        the FILES array.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 File Positioning Words                      All these words use the handle, not the unit#.  This is a       change from Pygmy version 1.3.                                                                                                  >EOF       moves the DOS file pointer to end of the file.                                                                       POSITION@  file pointer (double number) of this file.                                                                           >POSITION  sets the DOS file pointer to ud bytes                           from the beginning of the file.                                                                                      >BOF       moves the DOS file pointer to beginning of file.                                                                     +POSITION  moves the DOS file pointer n bytes relative                     to the current position (forward or backward).                                                                                                                                       FCLOSE  close a file by its handle.                                                                                             ?CLOSE  closes the file if possible, but ignores errors.                                                                        FOPEN & FMAKE take a file name and try to open or create it.                  They return a handle number and a flag.                                                                           ?OPEN   opens the file if possible, but reports no errors.                                                                      Note that  ?CLOSE and ?OPEN take a unit#                             while FCLOSE, FOPEN, and FMAKE take or return handles.                                                                                                                                                                                                                                                                                                                                     OPEN?   reports whether file with given unit# is currently open.                                                                EXISTS? returns true if the file can be opened and                      its length is greater than zero.  The file is left open.                                                                MAKE    creates a new file.  If a file already existed with             the same name, it is wiped out! It leaves the file open.                                                                ?MAKE   If the file exists it is opened.  Otherwise the                 file is created.  It leaves the file open.                                                                              Note, these words all take unit#.                                                                                                                                                                                                                               FILE-WRITE  write cnt bytes starting from buf                      to the file, starting at its current DOS file pointer, and      advancing the pointer by cnt bytes.                                                                                          FILE-SIZE  double number size of the file & does >EOF                                                                           SET-FILE-SIZE  forces the file to be ud bytes long.                This can shorten a file, so be careful.  For block files, it    is usually more convenient (& safer) to use SETTLE and CHOP     if you want to shorten the file, or use the editor's            F9 Holes key or MORE if you want to extend the file.                                                                         MORE  extends the file.  Be careful, this takes two operands.                                                                   Note, all of these now take handles instead of unit#s.                                                                                                                                          #BYTES-READ  holds number of bytes actually read by last                     call to FILE-READ.                                                                                                 EOF?   returns true if we last read zero bytes from the                file (using FILE-READ).                                                                                                  FILE-READ  reads cnt bytes from the current                        DOS file pointer position of the file and stores them           beginning at buf.  Stores the actual number of bytes read       in #BYTES-READ.  This takes a handle now.                                                                                                                                                                                                                                                                                                                                                                                                                    CLOSE-FILES ( -) closes all the open files in the FILES array.                                                                  RESET-FILES ( -) closes all the open files, and erases all the     data in the FILES array, setting everything to zero, except     the handles, which are set to -1.                                                                                            OPEN-FILES ( -) opens all the files in the FILES array, but        reports no errors.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           buffer  returns the address of the available buffer,                    and writes the previous contents of that buffer back            to the disk if they were changed (marked as updated).                                                                   BUFFER  assigns a buffer to block u and returns its address.            If that buffer already contained an updated block, that         block is written back to the disk.  BUFFER does not             read the new block (u) from the disk.                                                                                   block   reads block u from the disk into buffer at a.  This is          done within BLOCK if that block was absent from the             buffers.                                                                                                                BLOCK   returns the address of the buffer where block u                 is stored.  It reads & writes to disk as necessary.                                                                     FLUSH  assigns all the buffers to dummy block# 32767.  This            forces any updated blocks to be written back to the disk.                                                                BYE    in case you forget, this FLUSHes the buffers before             returning to DOS.                                                                                                        EMPTY-BUFFERS  throws away the buffers without writing             anything back to the disk.  This abandons changes and forces    a re-read of the disk to access any blocks that had been        in buffers.                                                                                                                  COPY  copies one block to another.                                                                                              COPIES   copies a range of blocks.  This can copy                        from one file to another, or within the same file.                                                                                                                                     -LEADING<>  eat the characters from the beginning of a string               while they do not match.                                                                                                                                                            -LEADING=   eat the characters from the beginning of a string               as long as they do match.                                                                                           Above are similar to -TRAILING, but require a character.                                                                                                                                        /STRING     chop a given number of characters off the beginning             of a string.  Could/should we guarantee new length              is not negative so WORD could eliminate 0 MAX ??                                                                                                                                                                                                    READ-LINE  read a CRLF delimited line into the file input           buffer.  It reads the file whose handle is stored in FIBH.      It uses >FIN to index into the file.                                                                                                                                                        -CTRL     replace control characters in a string with blanks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   ?REFILL   refill the file input buffer if necessary, so a                 textfile can be loaded across block boundaries.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       SOURCE   returns the address and count of the current input              stream.  This version is used when loading from                 textfiles is allowed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  SOURCE   returns the address and count of the current input              stream.  This version is used when loading from                 textfiles is not allowed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              WORD  collect the next word from the input stream, bounded by         the given delimiter, put it at HERE and return its              address, which is HERE.                                                                                                   HASH  convert vocabulary number u to the address                   of its vocabulary head (voc-head).  The number of FORTH is 2,   the number of COMPILER is 4.  This number is subtracted from    the address of CONTEXT to get the voc-head.  The voc-head       contains the LFA (Link Field Address) of the most recently      defined word in that vocabulary.  E.g.  2 HASH @ returns the    beginning address of the header of the most recently defined    word in the FORTH vocabulary.  There is room above              CONTEXT for 2 more vocabularies.  The meta-compiler uses        all 4 of them, i.e. 2 for the host and 2 for the target.                                                                                                                                     NONESUCH  this is a marker to indicate an indirect PFA as used            by words that will become headerless.                                                                                 -FIND   given a counted string and vocabulary number, search            the dictionary for a match.  If successful, return              the pfa and a false flag.  If not successful, return            the counted string and a true flag.  The check for the          $D6 byte in the parameter field takes care of the case          of an indirect pfa as found in a headerless word                before its header has been PRUNE'd.                                                                                                                                                                                                                                                                                                                                                                                                                     -DIGIT  converts ascii digit to binary number in current base.                                                                  10*+    multiplies number u by BASE & adds digit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               NUMBER is DEFER'd to make adding double & quad support easy                                                                     (SNUMBER  ( a # - n)   takes address & count and does the work                         for SNUMBER which takes a counted string.                                                                SNUMBER ( a - n) converts the counted string to a 16-bit number   in the current base.  Unlike some Forths, it _does_ use the     count, and does not require the string to be followed by a      space.  A leading $ forces the base to hex for that one         number.  A leading ' returns the ascii value of the following   character.                                                                                                                    Examples of numbers:  $FF40  'A  'a  'z  32750  7                                                                                                                                               -'    gets the next word from the input                               stream and looks it up in vocabulary u.                                                                                   '     looks up next word in input stream in active vocab. "tick"                                                                INTERPRET   Until the input stream is exhausted, step through               it, looking up the words in FORTH and executing                 them if found or trying to convert them to a number.                                                                QUERY   get input from keyboard into TIB                                                                                        (QUIT   This is the main loop.  It repeatedly collects keyboard         input and then interprets it.                                                                                                                                                                                                                                                                                                                                                           (ABORT   is the usual word executed by ABORT (which is             executed by abort" which is compiled by ABORT" - got that?).    It types the error message, tidies up, and restarts the main    loop QUIT.                                                                                                                      IS is not yet defined, so we do the equivalent the hard way.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 LOAD  interprets from block u (rather than from the                   keyboard).  At the end of loading each block, the base          is reset to decimal.                                                                                                      THRU  interprets a range of blocks.  It uses the                  return stack to keep track of the block number to allow using   THRU to load definitions that span more than one block.                                                                                                                                       EVALUATE is similar to LOAD except that it interprets from a      string.  EVALUATE does not reset the BASE to DECIMAL.                                                                                                                                                                                                                                                                                                                                         LOAD                                                            THRU                                                            EVALUATE                                                              Same as previous block except they take care of saving          and restoring the items necessary to allow intermixed           nesting of block and textfile loads.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      FLOAD   load from a textfile, e.g. " UTILITY.TXT" FLOAD                                                                         INCLUDE  this also will load from a textfile, but it allows              the name to follow rather than precede it, e.g.                 INCLUDE UTILITY.TXT                                                                                                    Note the use of quotes with FLOAD but not with INCLUDE.  The    reason is that FLOAD takes a counted string (actually an asciiz counted string, like DOS requires) which can be provided in     various ways, including a string literal such as " UTILITY.TXT".That usage of quotes works either inside colon definitions or   when interpreting.                                                                                                              The textfile to be loaded must not be greater than 64K and it   must have CRLF delimited lines no longer than TMAX/LINE         characters (see block 2).                                                                                                       (LIST   does most of the work for LIST                                                                                          LIST    displays a block (ie screen)                                                                                            CLEAR   erases a block by filling it with blanks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               ALLOT  moves the dictionary pointer H either forward backward.  ,      stores 2-byte number into the next free location in              the dictionary and advances H past it.  "comma"         C,     stores 1-byte number into the next free location                 in the dictionary and advances H past it.  "C-comma"    ,A     commas a 16-bit address into the dictionary, adjusting it        with the reloction value in dA.                         COMPILE  Compile the following word at this word's runtime.     LITERAL  Compile a number so that at run time it will be pushed           to the data stack.  It is DEFER'd                     [      break out of compiling loop.                             ]      This is the heart of the colon compiler.  Get next word          from the input stream.  If the word is in the COMPILER          vocabulary it is executed.  Else, if the word is in             FORTH it is compiled.  Else, if the word is a valid             number it is compiled as a literal.  Else, error.       PREVIOUS  return nfa (name field address) and length of the name     of the most recently defined word in the active vocabulary.SMUDGE   mark the PREVIOUSly defined name field so it cannot       be found in the dictionary, by flipping bit 5 of length byte.COMPILER  make COMPILER the active vocabulary.                  FORTH     make FORTH the active vocabulary.                     does    lay down a jump within the new child to the place in            parent that does the call to the routine dodoes.        [']     compile the address of the following FORTH word as a            literal.                                                DOES>   lay down a call to dodoes so the child will then                execute the following words.                            RECURSIVE   unsmudge the current header right away, so a                    word can be used in its own definition.             ;       end a colon definition.                                                                                                                                                                    These words and those on the following block allow the       relocation of the dictionary when not in the metacompiler, so   that words may be made headerless and so that temporarily neededutilities can be loaded, used to compile (more) permanent words,and then discarded.                                                                                                                Words may be made headerless either one at a time, by        preceding the word with the vertical bar (ie |), or in a group, by preceding the group with  HEADERS OFF and following the groupwith HEADERS ON.  Both methods can be combined without conflict (ie, you do not need to remove the existing vertical bars in    a group when you make the entire group headerless with HEADERS  OFF.                                                                                                                                                                                                                                                               See previous block.  PRUNE makes the headerless headers      vanish, and resets H' to the value in EDGE.  Prior to           PRUNEing, the headerless words will still be visible in the     dictionary.  In this version of TRIM, as opposed to the         metacompiler version, there is no need to adjust addresses by   dA and no need to unsmudge headers.                                                                                                If H' @ is still equal to EDGE @ then there is no need to    PRUNE.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          (HEAD    build the standard header, including the view field.                                                                   The view field could be omitted, thus saving some space.        However, unless memory is very tight, we want the view field    so VIEW ( or its shortcut V ) can pop up the editor on the      block containing a word's definition, e.g.                                                                                            VIEW DUP                                                        V CR                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      HEAD  Create a header, either within the normal dictionary if         the word is not headless or in an out-of-the-way area           (see SET-EDGE) if the word is headless.                         In either case, use (HEAD to build the header.                  For headless words lay down the special NONESUCH marker         (i.e. $D6) to indicate indirection, followed by the             address of the actual pfa.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                STRING  compile the following string from the input                     stream into the dictionary.                                                                                             CREATE   build a header and a jump to dovar.                    :        start a colon definition.                              CONSTANT define a constant and return its value when executed.  VARIABLE define a variable and return its address when executed.CRASH    is the default action of a DEFER'd word that you                have failed to initialize.                             DEFER    define a word that executes the word whose address              is stored in it.                                       IS       initialize a DEFER'd word.                                                                                                                                                                                                                                                                                                                                                             WORDS   display the words in the active vocabulary.                                                                             SP@     get the value of the stack pointer                                                                                      DEPTH   return count of items on the data stack.                                                                                .S      display non-destructively the values on the data stack.         The code looks awkward, but it will work even with              stacks into which we cannot directly address.                   (Although, I'm not sure we would know the DEPTH in              that case.)                                                                                                             ?       display the 16-bit value stored at address.                                                                                                                                                                                                             FILE-NAME:  (  ) ( - a) define an asciiz file name string.         When the new word is executed, leave the counted string's       address on the stack.  E.g.   FILE-NAME: FILE1 C:\TST1.SCR      This is handy to equate a short name to a long string.                                                                       UNIT   Setup a file in the unit# table without opening it.                                                                      OPEN   Setup a file in the unit# table and open it.                                                                             The usual method of opening a file is to say                          " YOURFILE.SCR" 2 OPEN                                                                                                                                                                                                                                                                                                                                                                    SAVEM  save a range of bytes to a file.  This now uses FMAKE           so it does not involve the unit# table at all.                  E.g.   100 2000 SAVEM TST1.COM                                                                                           SAVE   save a memory image of the current Forth                        system to a file.  E.g.    SAVE PYGMY2.COM                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Structures                              1st stack comment is for compile-time & 2nd is for run-time    \ ( -) compiles the following word from the COMPILER vocabulary.BEGIN ( - a) ( -) starts a loop.                                UNTIL ( a -) ( f -) ends a BEGIN ... UNTIL loop.                AGAIN ( a -) ( -) ends a BEGIN ... AGAIN (ie endless) loop.     THEN  ( a -) ( -) ends an IF statement.                         IF    ( - a) ( f -) starts the true part of an IF statement.    WHILE ( a - a a ) ( f -)                                          Part of a  BEGIN .... WHILE ... REPEAT loop.                  REPEAT ( a a -) ( -) Ends a BEGIN ... WHILE ... REPEAT loop.    ELSE   ( a - a) ( -) ends the true part and starts the false      part of an IF statement.                                      FOR  ( - h) ( u -) starts a FOR ... NEXT loop.  Body executes     u times, not u+1 times as in some Forths.                     NEXT ( h -) ( -) ends a FOR ... NEXT loop.                      ABORT"  ( -) ( f -) At compile-time, compile abort" and the        error message.  At run-time, execute ABORT if f is true or      skip over message if f is zero.                              ."  ( -) ( -) compile a string to be displayed at runtime.      (   ( -) Ignore comment up to ending right paren.               IS  ( -) ( pfa - ) store pfa into following DEFER'd word.       "   ( -) ( - a) At compile-time compile following string.  At      run-time, put counted string address on the stack.  The         string is followed by a byte of 00 to make it an asciiz         string that is suitable for a file name for DOS.             (   ( -) Ignore comment up to ending right paren.               ."  ( -) Displays (right now) the following string.             "   ( - a) String literal when interpreting.                    Note that because of the two vocabularies FORTH & COMPILER, we  can have two words named  ."  and do not need to use  .(        Similarly, we can have two words named  "                                                                                       (BOOT  ( -) this is the default word executed by BOOT.                                                                                                                                          BOOT ( -) is the DEFER'd word executed at start up by the word     RESET.  As the default, it executes (BOOT, but you can re-      vector BOOT to your own application's highest level word.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    RESET   Initialize buffer addresses and variables, etc., and     execute BOOT (which can be vectored to your application).       The commented out line with AT and AT@ gets the video display   attribute at the top left corner of the screen and uses it to   initialize ATTR.  CLS then applies that attribute to the        entire display.  This was more useful in the old days before    VGA monitors were standard.  If you know what attribute you     want, you can set it up (e.g.  $1F ATTR !) in (BOOT.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            End of the kernel                                                                                                              #BYE is used to return control to a C program if Pygmy was           embedded in a C wrapper, or perhaps called from a .BAT          file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      CLAMP   restrict a number to a certain range.                                                                                   NFA  convert a pfa (parameter field address) to an nfa (name         field address).  It is no longer as simple as walking           backward in memory until we find a non-ascii byte that          could be a name field length, because that would not work       when used on a headerless word's pfa.  So, we start on          the other end and search the headers until we find one          with a properly matching pfa.  NFA can even find the nfa        of a headerless word providing its header has not been          PRUNE'd yet.  Be careful when using it on headerless            words, as the address will not be good after PRUNEing.          NONESUCH (ie )$D6 is the indicator that the following CELL      holds the address of the PFA (for headerless words).                                                                                                                                       FORGET    trim back the dictionary to exclude the given word              and all the words defined after it.                                                                                             Do not try to FORGET a headerless word!                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  The Editor Starts Here                                                                                          It now accesses the display only through the DEFER'd words   EMIT CR AT CUR@ CLS (did I leave any out?), so by writing your  own versions of (EMIT (CR etc. this editor should work on any   display device that has enough rows and columns.                                                                                   Invoke the editor with EDIT or ED (or possibly VIEW or V)    then control it with function keys, arrow keys, PgDn, etc.                                                                         Most of the editor support words have been made headerless,  except for a few the might have other uses.                                                                                     L       refresh edit block.                                                                                                                                                                                Editor Function Keys                                                                                                 F1  Search from the current cursor location for a particular        string.  It only works on the current block.                F2  Replace with the current replace string.                    F3  Set up the string to search for, and then search for it.    F4  Set up the string to replace with, and then replace with it.F5  Delete the entire line the cursor is on.                    F6  Join the following line to the current line at the cursor.      Characters snake around from the following line.            F7  "Cut" the current line to the cut buffer.  This does not        alter the current line, it just makes a copy.  Cut as many      as you like, they just stack up.  See count on status line. F8  Overlay current line with the oldest line from the cut          buffer, removing it from the cut buffer.  See count on          status line (c=n).                                                     Editor Function Keys  - continued                                                                                    F9  Prompt for the number, then insert that many blank blocks       after the current block, sliding the others up and              extending the file.                                         F10 Search from the current cursor location for a particular        string.  Unlike F1, it is not limited to the current block      but will continue across blocks, stopping when the string       is found or when the end of the file is reached.            Esc Exits from the editor.  If you want to cancel the most          recent changes, after pressing Esc, type EMPTY-BUFFERS.  If     you want to force those changes to be applied to the disk       immediately, type  FLUSH.                                   CR  End the current line, pushing anything to the right to the      following line and every line below it down.  The last line     on the block is lost.                                                  Editor Function Keys  - continued                                                                                    Home  Move cursor to the beginning of the current line.  If           already at the beginning, move cursor to top left corner. End   Move cursor just past the end of text on the current line       (which may be the 1st position of the following line).                                                                    Bksp  Delete the character to the left of the cursor.           Del   Delete the character the cursor is on.                                                                                    Ins   Toggle insert versus overwrite mode (see the "i" on status      line).                                                                                                                       Note that deletions and insertions only affect the current   line except for Bksp.                                                                                                                      Editor Function Keys  - continued                                                                                    Ctrl-A  switch to the alternate block.  This lets you synchro-          nize two ranges of blocks and quickly switch between            the corresponding blocks.  This can be used for shadow          blocks or for comparing two versions of a file (or              two versions of an application in different ranges of           the same file).  The default is that an even thousand is        paired with the next higher odd thousand.  Thus, you            could open PYGMY.SCR at 0 and open PYGMY.DOW at 1000 in         order to switch between the source code block and its           shadow.  You could put another pair of files at 2000 and        3000.  Etc.  See the next block for how to change the           ranges that will be related.                                                                                                                                                                       Editor Function Keys  - continued                                                                                    Alt-A   make the current block the _base_ of one range of               blocks, replacing the oldest of the pair.  Press Alt-A          twice on the same block to return to the default                mentioned on the previous block.  E.g. suppose you              want to compare blocks 2037 and up with blocks                  3102 and up.  First move to block 2037 and press Alt-A,         then move to block 3102 and press Alt-A.  Then Ctrl-A           will alternate between corresponding blocks in those            ranges.                                                                                                                         If Alt-A and Ctrl-A are not placed conveniently for you         on your keyboard, you can change the keys that invoke           ALTERNATE and MARK by editing the editor's SPCL' table.                                                                 Editor                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Editor                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Editor                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          See the discussion a few blocks back on using Ctrl-A & Alt-A.   ALTERNATE and MARK are the words that do the work.  When the    corresponding block to move to is not a valid block, ALTERNATE  does nothing, leaving you on the original block.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   This is the giant case statement for the various special     editor keys.  The numbers correspond to the KEY values returned by ((KEY.  If you want to change the key that a particular      function responds to, get out of the editor and type  KEY .     followed by a carriage return, then press the key you want to   use.  Its corresponding number will then be printed.  Then      edit the SPCL' table to use the key of your choice in place     of the currently assigned key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  BEEP  ( -) emit a Ctrl-G.                                                                                                       ED    ( -)  re-edit the last block.                                                                                             EDIT  ( block# -)  begin editing a new block.                                                                                   Note, that EDIT starts off in the overwrite mode (rather than   the insert mode) but thereafter moving from block to block      and even exiting from the editor and returning with ED will     not change the mode from how you last set it.                                                                                   Esc gets you out of the editor.  Esc will abort a search        across function, as well.                                                                                                                                                                                                                                       HEAVY? ( blk# - f)  return true if block is not entirely blank.                                                                 SETTLE ( 1st last -) within the range of blocks, make the          heavy (non-blank) blocks settle to the bottom.  This            compresses out blank blocks, so that all the blank blocks       will be at the high end of the range.                                                                                        CHOP ( unit# -)   Truncate ending blank blocks from the file       associated with the given unit#. This is similar in concept     to  -TRAILING.                                                                                                                                                                                                                                                                                                                                                                                                  The Assembler Starts Here                                                                                        This is a "structured" assembler.  These structure words:                  IF, WHILE, ELSE, THEN, BEGIN, UNTIL,                            LOOP, LOOP, LOOPZ, LOOPNZ, AGAIN, REPEAT,                                                                        along with these condition words:                                              CS,   0=,   0<,   U<,   CXNZ,                                    <,    >,   U>, ( OV, )                                                                                          allow you to write "label-less" assembly language code.  These  words look similar to structure words used within colon         definitions, except they end in commas.  IF, for example does   not depend on a truth value on the stack as IF does.  Instead   it depends on the condition code register at the time the CODE  word executes.                                                  For example,                                                                                                                         CS, IF, <part to be executed if carry was set>                    ELSE, <part to be executed if carry was not set> THEN,   or                                                                   BEGIN,  <do this part until the zero flag goes true>            0=, UNTIL,                                                                                                                 NOT, inverts the condition that will be tested, as in                CS, NOT, IF, <do this only if carry is not set> THEN,                                                                      using WHILE,                                                         BEGIN,  AX AX TEST, 0<, WHILE, AX INC, 0=, UNTIL, THEN,                                                                                                                                                                                                         An assembly language definition in Forth is called a CODE  word.  It begins with the word CODE followed by the name of the new word, and ends with the word END-CODE.  (Actually, in Pygmy Forth, END-CODE is not necessary.)  Almost always you will end  a CODE word with the word NXT, which will assemble in-line the  instructions for the Forth inner interpreter.  (This "next" has nothing to do with FOR ... NEXT.)                                                                                                    So, we have this form for a CODE word:                                                                                        CODE <name>   <innards in assembly language>  NXT,  END-CODE                                                                      Ordinarily, you would code all of your application in      high level Forth except for, perhaps, the innermost parts of    innermost loops that just have to be a fast a possible.                                                                                                                                                                                                         2^    raise two to the given power, e.g   10 2^ returns 1024.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   #,    indicate the operand is immediate.  See following blocks        for examples.                                                                                                                                                                             W-PTR  indicate operand is a word rather than a byte (byte is          the default).  See following blocks for examples.                                                                        Also, search through the source code in PYGMY.SCR for words     that start with CODE for all sorts of assembly language         examples.                                                                                                                                                                                                                                                                                                                           Register restrictions:                                             AX - you may use this freely.                                   BX - this holds the top of stack.                               CX - you may use this freely.                                   DX - you may use this freely.                                   SI - this is the IP (interpretive pointer).  If you use              it, you must save and restore it.                          DI - you may use this freely.                                   SP - this is the data stack pointer.  If you use it, you             must save and restore it.                                  BP - this is the return stack pointer.  If you use it,               you must save and restore it.                              If you set the direction flag (with STD,) you must clear             it (with CLD,)                                             ES - you may use this freely.                                   DS SS - if you use them, you must save and restore them.                                                                      The operand(s) precede(s) the opcode.   #,  following a    number indicates it is an immediate operand, e.g.                                    $1326 #, AX MOV,                           would assemble code to move the immediate value $1326 into reg  AX.                                                                                                                                 The right paren following a number indicates that number    is an indirect address, eg                                                           $1326 ) AL MOV,                            would assemble code to move the byte at address $1326 into      register AL.                                                                                                                                                                                                                                                                                                                                                                                         When the size of the operand cannot be determinded, e.g.                             $1326 COM,                            a byte-sized operand is assumed.  To override this, use  W-PTR  (which stands for "word pointer") immediately prior to          the opcode, e.g.                                                                          $1326 W-PTR COM,                                                                                                                                                           Note that the Intel mnemonic  NOT,  is not used in this    assembler as the opcode to take the one's complement of         a value.  In this assembler the mnemonic  COM,  is used for     that.  Instead, in this assembler,  NOT,  is used as a          "pseudo opcode" to invert a condition to be tested.                                                                                                                                                                                                                  See the source code listing for the assembler in PYGMY.SCR for additional examples of how to code specific instructions.                                                                        See the source code for the Pygmy Forth kernel, starting   at block 19 of PYGMY.SCR for examples of defining CODE words.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        When in doubt, try it out and use DUMP and DU to examine   memory to see what the assembler actually assembled.  Then, if  necessary, save an image of Pygmy and run it under DEBUG so you can single-step through the code word.                               CODE TST1 xxxx yyyy ssss uuuu zzzz  NXT, END-CODE               HEX ' TST1 U.  ( remember this address - say it is $3F96)       SAVE TST1.COM                                                   BYE                                                        C:\>DEBUG TST1.COM                                              -U 3F96      this makes DEBUG "unassemble" the code word        -G 3F96      this will return you to Forth with a breakpoint                 set at the beginning of the word TST1.  As soon                 as you execute this word you will be back in DEBUG              with a display of the current registers.  Press T               to single step through the definition.                                                                                  Since TOS (top of stack) is kept in the BX register, if    your word consumes it, you must re-fill it.  See examples in    the source code for the kernel, for example DROP or +.                                                                               The macro SWITCH, is handy to exchange SP & BP (the stack  and the return stack pointers).  Normally when you PUSH, or POP,you affect the data stack.  If you SWITCH, you can PUSH, or POP,on the return stack.  Be sure to SWITCH, back again.  Normally, indexed addressing relative to [BP] addresses the return stack. When you SWITCH, you can use this to address the items on the   data stack.  Again, be sure to SWITCH, back.  In each of your   CODE words there should be an even number of SWITCH,            instructions.  It simply assembles a BP SP XCHG, instruction,   but is much easier on my eyes and brain.                                                                                        ( M5 for LDS, LEA, & LES, )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     ( M6 for the rotate & shift instructions )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ( INC, & DEC, instructions )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ( PUSH, & POP, instructions )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   ( IN, OUT, instr )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ( XCHG )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ( TEST, instruction  - almost like ADD, etc. )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  INT,   assembles the usual two-byte interrupt instruction              (even if its parameter is 3)                                                                                             INT3,  assembles the 1-byte INT3 instruction (used for                 break points)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ( CALL, instr  )    HEX                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Notice how easy assembler macros are to write.  They are     defined as colon definitions.  The words  NXT,  and  SWITCH,    do their assembling later, within CODE definitions.                                                                             NXT,  lay down the code for the inner-interpreter's "next",          (which has nothing to do with the NEXT of FOR/NEXT).                                                                       SWITCH,  lay down the code to exchange the contents of               the data stack pointer and the return stack pointer.  This      is used either to allow PUSH, & POP, on the return stack        or to allow adressing the data stack via [BP] - and then        to switch the pointers back.                                                                                                                                                                                                                                                                                               ( more assembly macros)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         ( Assembler)                                                                                                                    << and >> allow you to dump short (or long) snippets of         assembly code to the screen for your inspection.  If you        want to see how a piece of assembly codes gets assembled,       just put it between the brackets, as in the following:                                                                           <<  37 #, LDA,  >>                                                                                                             or                                                                                                                               <<  NXT,  >>                                                                                                                                                                                                                                                                                                                   ( blank )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          These three blocks serve as both an index to various         extensions and utilities you might want to load, and as a set   of load blocks to actually load the ones you select.  When you  type  5 LOAD  to extend a newly created kernel, one of the      things block 5 does is to load 3 extension load blocks with e.g.  140 142 THRU                                                  which causes all the extensions you have selected to be loaded.                                                                    To select an extension, remove the parenthesis in column one.To unselect an extension, restore the parenthesis in column one.                                                                                                                                                                                                                                                                                                                                ( extensions )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ( extensions )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  NEWFILE                                                                                                                            This is an easy way to start a new block file.  If the file  already exists you are given a warning and the original file    is not destroyed.  Otherwise, a new file is created with 8      empty blocks.  You can extend it further from within the editor (by pressing F9).  Or, you can change the 8 in NEWFILE to a     different number.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               T0@     read timer 0 i.e. "timer zero fetch"                                                                                                                                                                                                                    MS      delay for approximately the specified number of                 milliseconds.  It uses timer zero to get a relatively           machine independent timer period.                                                                                               Note, the PAUSE in MS allows other tasks to continue            while the task executing MS is delaying.  Multiple              tasks can run MS without interfering with each other.                                                                                                                                                                                                                                                                                                                                                                                                   VIEW                                                                                                                              you might wish to use this version if you are not loading       the full-screen editor for some reason, such as using the       simpler line editor.                                                                                                            Generally you would use the version on the next block.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        VIEW   pops you into the editor on the block on which the              specified word was defined.                                                                                                                                                              V      is a shorthand version of VIEW, e.g.   V DUP                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             .ID   print the name corresponding to the given pfa                                                                                                                                             SEE   At one time, this word decompiled a colon definition.  Now      we have VIEW to give us the original source code rather         than a decompilation.  Still we might need a limited SEE        to answer the question: What word will the DEFER'd word         CONDENSED actually execute?  If used on a non-DEFER'd           word, it just does nothing.                                                                                                                                                                     E.g.      SEE CONDENSED                                                   SEE EMIT                                                        SEE CR                                                                                                                                                                          NAMEZ:   define an asciiz string whose name is the string.  This         is cute because of the trick that lets the name field           serve double duty as both the name and the string.  But         you mustn't use this for headerless words!                                                                                      This word is not needed as much now that we have an             interpreted string literal and can say                          " YOURFILE.SCR" OPEN   or   " FILTER.SCR" CONSTANT                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        OF THENS from Wil Baden                      OF   At compile time, setup a test for  n1 n2 = IF DROP         THENS   At compile time, complete all the IF statements.  E.g.      : CHOOSE ( n -)                                                      1 OF  THE-LADY                        ELSE                      2 OF  THE-TIGER                       ELSE                     23 OF  THE-PECAN-PIE  THE-ICE-CREAM    ELSE                      4 OF  THE-TV-SET                      ELSE                     75 OF  THE-GORILLA                     ELSE                       ( Otherwise) DROP ." invalid choice"  [ 5 ] THENS  ;    This is a simple general purpose "case" statement, but mostly these days I just use (again, suggested by Wil Baden I think)     : CHOOSE ( n -)                                                    DUP 2 = IF DROP  THE-TIGER  EXIT  THEN                          DUP 4 = IF DROP  THE-TV-SET EXIT  THEN                          DROP <some default action>  ;                                                                                              L@  fetch the 16-bit number from SEG:OFFSET.                        This allows access to memory outside Pygmy's code segment.      "L fetch" for "long fetch"                                                                                                  L!  store the 16-bit number to SEG:OFFSET.                          This allows access to memory outside Pygmy's code segment.      "L store" for "long store"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  LC@  fetch the 8-bit number from SEG:OFFSET.                         This allows access to memory outside Pygmy's code segment.      "L C-fetch" for "long C-fetch"                                                                                                                                                                                                                             LC!  store the 8-bit number to SEG:OFFSET.                           This allows access to memory outside Pygmy's code segment.      "L C-store" for "long C-store"                                                                                                                                                                                                                                                                                                                                                                                                                             ( DOS-EMIT for non-pc compatible MS-DOS computers )             TEMP ( - a)                                                     STD-OUT  This is a variant of EMIT that uses handle 1,            and so can be redirected from the command line.  See your       DOS books.                                                                                                                                                                                    DOS-OUT  This is another variant of EMIT.  It uses the Display           Character function of DOS.                                                                                             >DOS ( -)  Force EMIT to use DOS-OUT.                           >STD ( -)  Force EMIT to use STD-OUT.                             ( compare >PRN & >SCR )                                                                                                                                                                                                                                                                                                       TST-GPH  ( -) shows 128 graphics characters.                                                                                    TST-NON ( -) shows 128 non-graphics characters.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 BYTES ( hhll - ll hh)  break a 16-bit number into two 8-bit                            numbers, msbyte on top of stack                                                                          FLIP ( hhll - llhh)  swap the bytes within a 16-bit word.                            Some people name it  ><                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ( relocate the handle alias table to allow more than 15 files)                                                                  HAT-ON  switch to the new handle alias table, to allow            MAX-FILES to be open at one time.  You must have set FILES=     in your CONFIG.SYS file to at least MAX-FILES plus 5.           Ordinarily DOS limits you to 15 files (plus the 5 standard      handles), but HAT-ON gets around that and, theoretically,       allows over 200 files to be open simultaneously.  You should    test this carefully if you plan to use it.                                                                                    HAT-OFF  restore the handle alias table originally set            up for you by DOS.  This should done before exiting to DOS.                                                                                                                                                                                                                                                                   ( words whose name is its string )                                                                                              NAME: ( -) ( - a) defines a word that returns the address of      its own name.  This version does not put a zero at end of       name.                                                                                                                         NAMEZ: ( -) ( - a) Same as above, but does put a zero at end of   name, making the string a DOS compatible "asciiz" string.       It requires a little trick to make it work.  See previous       discussion several blocks back.                                                                                               .NAME:  ( -) ( -) defines a word that types its own name.                                                                                                                                       The   2 CELLS +   skips over the view and link fields.                                                                                                                                          2/MOD     do a fast  2 U/MOD.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   INDEX  Starting at the given block, display the 1st line of each       block.  Continue until Esc is pressed or eof is reached.        It is designed to blow up at end of the file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ( move anywhere in full PC address space )                                                                                      LCMOVE    "L-C-move" for "long C-move"                                                                                          LCMOVE>   "L-C-move up" for "long C-move up"                                                                                                                                                       These are similar to CMOVE & CMOVE>, but require segment     as well as offset addresses.  They can access memory outside    of Pygmy's code segment.                                                                                                                                                                                                                                                                                                                                                                                                                                        ( list blocks to printer )                                                                                                      (PEMIT   print character to printer LPT1:                                                                                       >PRN ( -) Force EMIT to send to printer.                        >SCR ( -) Force EMIT to send to screen.                                                                                         (Well, >SCR actually forces EMIT back to whatever DEFAULT-EMIT  points to.  Perhaps >SCR should be renamed to >NORMAL with a    separate >SCR that really does force output to the screen.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     .SCR#   print block number.                                                                                                     .LINE   print one line of the block.                                                                                            2LINES  print one line from each of two blocks, side by side.                                                                                                                                   These are used by SHOW, SHOW2, and SHADOW for listing source    code to the printer.                                                                                                                                                                                                                                                                                                                                                                            ( list block file to printer with 3 blocks per page   )                                                                         DEFER .HD    print a heading.  You can re-vector it to print                 a different heading.                                                                                               (.HD     This is the default word executed by .HD.                                                                              SHOW     print a range of blocks to the printer,                         3 blocks per page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     ( make printer print in small type )                                                                                            DEFER CONDENSED   set printer up for 17.5 cpi, or so.                                                                           Here are examples for several printers.  You can comment out    what you don't need, or use them as guides for other printers.                                                                  OKI-CONDENSED ( -) sets OKI printer to small print.                                                                             EPSON-CONDENSED ( -) sets Epson printer to small print, if not,   look it up in your printer manual.                                                                                            LJ-CONDENSED  sets HP Laser Jet II (etc.) to small print.                                                                                                                                                                                                       ( print 2 blocks side by side )                                                                                                 2SCRS   print 2 blocks side by side.                                                                                            SHOW2   print a range of blocks, 6 per page.  Be sure to set            CONDENSED to suit your own printer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     ( shadow )                                                                                                                      2SCRS   print 2 blocks side by side.  One is from                       first range and the other is from the second range.             This is used by SHADOW.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 ( shadow )                                                                                                                      PAGE-CTRL   Used by SHADOW.                                     SHADOW      print 2 ranges of blocks side by side, such as a                source block and its corresponding shadow block.                It prints 6 blocks per page.                                                                                        IBM-PRO     send code to NEC printer to make it emulate the                 IBM PRO-PRINTER.                                                                                                    Example                                                              3600 3650 3900 SHADOW                                        would print source blocks 3600-3650 on the left and shadow      blocks 3900-3950 on the right, 6 blocks total per page.                                                                                                                                                                                                       BELL ( -) beep the pc's speaker, regardless of whether the        current EMIT is set up to handle a Ctrl-G (BEEP).               Warning, this is not multi-tasking friendly.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ( slowly append a range of blocks to a text file  BLK>TXT)                                                                      BLK>TXT   append a range of blocks to a textfile, eliminating             trailing spaces on each line and ending each line               with CRLF.  The textfile must already exist.  The               textfile is extended, not overwritten.  If you need             to create a textfile for use with BLK>TXT you can               do it several ways, but here is one of the simplest:                                                                               " textfile.ext" FMAKE DROP FCLOSE                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  TXT>BLK     create a block file from a textfile.  The CRLFs and             all other control characters are replaced with                  blanks.  Trailing blanks on each line are                       eliminated, then each line shorter than 64                      characters is extended to 64 characters while each              line longer than 64 characters is converted to two              or more 64 character lines.  This does not append               or extend to the destination file, so be careful                not to overwrite a file you want to keep.  The                  destination file does not need to exist prior to                executing  TXT>BLK.                                                                                                                                                                                                                                                                                                 CASE:  define a word made up of a list of paired                  numbers and words.  At run-time, search for a match.            If found, execute the corresponding word.  If no match,         execute the final word (corresponding to 00).  The  number for  the default must be 00 and the default pair must be last.       Numbers can be in any order except 00 must be last.             The list must end with a semi-colon, and numbers can't be       constants, e.g. use 00 instead of 0.                                                                                           : RED ." RED" ;  : BLUE ." BLUE" ; : ORANGE ." ORANGE" ;        : PINK ." PINK" ; : BLACK ." BLACK" ;                                                                                           CASE: COLOR  7 RED 12 BLUE 472 ORANGE 15 PINK 00 BLACK ;                                                                        7 COLOR REDok     472 COLOR ORANGEok   3000 COLOR BLACKok                                                                      additional BIOS Int $10 video words                                                                                             SCROLL-UP                                                                                                                       SCROLL-DOWN                                                                                                                        The first r c are the row and column of the top left corner  of the window.  The second r c are the row and column of the    bottom right corner of the window.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              COLORS                                                                                                                              Run this to see what video attribute you are currently      using or to see what other combinations look like.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Here are some examples of how to set video attributes.  They    do not take effect until a  .ATTR  is executed  (either         directly, or within a word such as  CLS  or EDIT.                                                                                                                                               BLACK ON-BLACK CLS                                                                                                                    should really clear the screen!  (If you do                     this I hope you can touch type at least enough                  to say  COLORS  and then begin pressing the                     F1 and F2 keys until you again get a readable                   combination.                                                                                                                                                                                                                                              ( blank )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       #INPUT    This answers the oft asked question How can I ask the           user for a number, rather than requiring him to type            a number onto the stack first?  e.g.                                                                                             : 37*  ( -)                                                       CR ." Please enter a number between 1 and 10 "                  #INPUT                                                          CR ." That number times 37 is "  37 *  U.                       CR ." Thank you, and come back soon. "    ;                                                                                                                                        (There is not much need for a corresponding string input word    such as $INPUT because we can just use EXPECT or QUERY  )                                                                      ( blank )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       SHELL and its various support words are defined on                    the next several blocks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  FREE is actually "FREE-ALL-EXCEPT" as you tell it how           many 16-byte paragraphs to keep.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                PBLK is the parameter block, consisting of                           2 byte    segment of environment block                          4 byte    dword ptr to command tail                             4 byte    dword ptr to 1st FCB (offset $5C)                     4 byte    dword ptr to 2nd FCB (offset $6C)                                                                                After call to $21/$4B, we may not be able to guarantee DS is    unchanged.  Can we count on a stack existing somewhere for use  by the CS PUSH, instruction?                                                                                                    pgm$ is the command tail to be executed.  It is a counted stringfollowed by a $0D (i.e. an asciiCR instead of an asciiz)                                                                        Do not call (EXEC directly, as the parameter block must be setupfirst.                                                                                                                                                                                                                                                          The pgm$ name must contain the full path (if not                in current directory) and extension.  The /C is necessary to    pass arguments to the command interpreter.  We                  cannot put built-in commands in the pgm$ but must execute       them by putting COMMAND.COM (with full path) in pgm$ and        putting, e.g., " /C DIR" in the tail$ string.                                                                                                                                                   shell is not ordinarily used except to build SHELL and EXEC.                                                                                                                                                                                                                                                                                                                                    SHELL temporarily shells out to DOS until EXIT is typed.                                                                        EXEC  passes a "command" to COMMAND.COM to be executed                                                                          Note the full path to COMMAND.COM is built into the SHELL and   EXEC commands.  If COMMAND.COM is elsewhere than in the root    directory of drive C: then either put a copy there or change    the constant named COMMAND.COM.                                                                                                 Furthermore, we could have a problem if PAD is shared among     various tasks and another task corrupts our string built there.                                                                                                                                                                                                                                                                                                                                 DATE                                                            TIME                                                                                                                                  These fetch the time and date from DOS.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   Multi-line comments when loading from textfiles.                                                                                This new version of left paren will still work when loading     from block files or the keyboard.  Without it, FLOAD'd or       INCLUDE'd textfiles would be limited to comments within a singleline.                                                                                                                            ( This is a single line comment )                                                                                               ( This is                                                          a                                                                multi-                                                           line                                                             comment!  )                                                                                                                                                                                                                                              This allows you to have a block file with a load block that     works regardless of what unit the block file occupies.  Suppose you have a trig package with the following statement in its     block #1                                                                       2 75 UTHRU                                                                                                       if you open the file at unit# 4 you could say  4001 LOAD        and the 2 75 UTHRU would load blocks 4002 thru 4075.  Or, if    you open the file at unit# 7 you could say 7001 LOAD and the    same 2 75 UTHRU would load blocks 7002 thru 7075.                                                                               You would never use ULOAD or UTHRU directly from the keyboard.                                                                                                                                                                                                  ( compare 2 blocks or a range of blocks )                                                                                       Use SCR-COMPS for the quick, gross comparison of two ranges     of blocks.  This identifies which blocks are different, but     does not display the differences.                                                                                               Then, use FINE-COMP to display the detail of the differences    of two blocks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Multi-tasker                                                                                                                    The variables #USER, #SP, #UP determine how much space to allot for a task.                                                                                                                     LOCAL returns addr of USER variable in another task, e.g.        TASK1 BASE LOCAL  returns address of the local variable BASE    from TASK1 rather from the current task.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       PAUSE saves the current task's state by saving reg SI           and BP (ie rstack ptr) on the task's dstack and then saving the dstack pointer into user variable TOS.  Thus, after PAUSE       executes, the old task's data stack area will have                                                                                .                                                               .  ( any application specific data stack items)                 .                                                               SI ( addr of next word to be executed)                          BP ( rstack pointer)                                                                                                                                                                                                                                                                                                                                                                                                                                          TASK: creates a background or control task without a dictionary or terminal input buffer etc.  First it copies user variables   from the current task, then it initializes S0 & R0.  The new    task is not linked into the list of active tasks.                                                                               See TASK! to point a task at a word to execute.                                                                                 See WAKE  SLEEP  STOP  to move tasks into and out of the list       of active tasks.                                                                                                                                                                            SINGLE disables the multi-tasker by vectoring PAUSE to a NOP.                                                                   MULTI enables the multi-tasker by vectoring PAUSE to (PAUSE.                                                                                                                                    #TASKS holds count of the tasks in the active task list                                                                         AWAKE? checks to see if a given task is in the active task list.       If it is, the address of the task that points to the            given task is returned.  Otherwise, a zero is returned.                                                                  The active task list is circular.  It is never empty, as the    main terminal task (sometimes called the OPERATOR task) should  not be put to sleep.  With a single task, the LINK field        of the task contains the address of the single task.                                                                            Executing a task name returns the address of that task, which isthe start of its user variables (i.e. the address of its LINK   field).                                                                                                                           To put taskX to SLEEP, we must alter the LINK of the            previous task so that, instead of it pointing to taskX,         it points to the task that taskX points to.                                                                                                                                                     Note that AWAKE? returns the address of the link that points    to the task.  If there is only one task, this link points to    itself.  The last task must not put itself to sleep.            In fact, it can't, because the TERMINAL task cannot put         itself to sleep.                                                                                                                STOP  allows a task to put itself to SLEEP (unless it is the          TERMINAL task).                                           KILL-PROCESSES puts all tasks to SLEEP except for TERMINAL.      Perhaps it should be named KILL-TASKS.                                                                                                                                                       WAKE                                                                                                                              Spread open the list of active tasks and insert the new task    between the current task and the next task.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   TASK!                                                                                                                           Initialize a task so that, when awakened, it will execute the   specified routine.                                                                                                              The routine to be installed must be an endless loop                or must explicitly put itself to sleep, as there is nothing     above it on its return stack.                                                                                                We use a special version of ABORT so that a non-TERMINAL task   will put itself to sleep (with STOP) rather than doing QUIT.                                                                    Usage:                                                            : ROBOT1 ( -) BEGIN this that PAUSE the-other AGAIN  ;         ' ROBOT1  TASK1  TASK!                                                                                                           As a test, set up two tasks, each of which increments         an associated counter.  One increments its counter 5 times      a second and the other once every two seconds.  Ocassionally    check the counter values, e.g.                                                                                                    C1 ?                                                            C2 ?                                                            C1 ?                                                            C2 ?                                                           etc                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Then, as an additional test, set up two more tasks that       merely display the values of the counters the tasks on the      previous block are incrementing.  Update the counters 10        times a second (probably overkill).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             ( Simple Multitasker Example from spring '99 article )                                                                                                                                          This is example is from the article "How and Why to Use         Multitasking in Forth" submitted to _Forth Dimensions_          3 March 1999.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   ( Main Multitasker Example from spring '99 article )            This is example is from the article "How and Why to Use         Multitasking in Forth" submitted to _Forth Dimensions_          3 March 1999.  See the article for full discussion.                                                                             V@  ( 1st version, as might be used for a real ADC)             V@  ( 2nd version, fake it on the PC by reading the timer)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      This contains the code to allow EMIT to write directly to video RAM rather than using BIOS calls.                                                                                               It was much faster on an XT or other slow                       hardware, less so on a '386, never mind modern hardware.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ( direct video EMIT                      )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ( direct video EMIT    (DEMIT continued  )                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ( direct video EMIT  continued                  )