anderson@ncrcce.StPaul.NCR.COM (Joel Peter Anderson) (10/25/89)
This is part one (of two) of the GeosForth documentation. Since I have un-geosized this document, you will not see the bold used to highlight some words. If you follow the syntax description provided in the text, and are familiar with Forth usage, this should be no problem. If you do have difficulty I would suggest (recommend, encourage) you consult a Forth manual such as 'Starting Forth'. The second thing (or the first, depending on how you look at it) you MUST get is the Geos Programmers Reference - using that and a few hours of effort I have managed to already make a 'scribble' graphic program. My next step? 'GeoDraw', an object oriented drawing tool! -------------------CUT HERE------------------- geosFORTH V1.0 (c) 1989 Nicholas J. Vrtis This version of FORTH for GEOS has been adapted from the figFORTH release-1 6502 definition by: Nicholas J. Vrtis 5863 Pinetree S.E. Kentwood, MI 49508 The original definition was created and supplied by: Forth Interest Group P.O. Box 1105 San Carlos, CA 94070 GEOS is a copyright of Berkely Softworks. This version of geosFORTH is distributed as User Supported software. You may freely copy and distribute this software. The only conditions are that you cannot charge more than a nominal copy/handling fee, and you must not remove the credits. If you find the program useful and interesting, I would like a $10 support fee, or a disk of your software in exchange to the Kentwood address. I have Forth 79 standard version which runs on the native C-64 and includes floating point support and an assembler. If I get enough interest (and support) with this version, I will port that one over to GEOS also. If you send a support fee, I will send back the Forth 79 version if I ever get that converted. As usual, this software has been tested and does not have any bugs that I know of. If you find some, please drop me a line and describe the error or problem. Without some sort of feedback I will not know what needs to be fixed. The definitions are presented in the order of their ASCII sort. The first line of each entry shows a symbolic description of the action of the word on the FORTH stack. The symbols indicate the order of parameters on the stack. The stack is shown in order from left to right, with three dashes (---) indicating the execution point of the word. Symbols to the left of the dashes indicate input parameters, while symbols to the right indicate output parameters. Unless otherwise noted, all references to numbers are for 16 bit signed integers. All arithemetic is implicitly 16 bit signed integer math. The symbols used are: addr memory address b 8 bit byte n 16 bit signed integer number u 16 bit unsigned integer f boolean flag (0=false, non-0=true) ff boolean false flag (0) tf boolean true flag (non-0) Some fig-FORTH words have been redefined in geosFORTH. In general, the operation has not been changed, but some of the internal working have changed in order to adapt them to a GEOS environment. Additional words have been defined for source code editing and access to some of the GEOS routines. I have not added any printer support for the source code. That is left 'as an excercise for the reader'. Source code is a standard GEOS VLIR file with each VLIR record 1024 bytes long. The last byte of the record is a zero. There are no carriage control characters. Read it in, hack it up into 64 character lines and print it. ! n addr --- Store the 16 bit integer n at address addr. !csp --- Save the current stack position in CSP (used as part of compiler checking). # n1 --- n2 Generates from a number n1, the next ASCII character which is placed in an output string. The result n2 is the quotient after division by base, and is maintained for further processing. Used between <# and #> (See #S). #> n --- addr count Terminates numeric output conversion by dropping n, leaving the text address and character count suitable for type. #s n1 --- n2 Generates ASCII text in the text output buffer by the use of #, until a zero number n2 results. Used between <# and #>. ' --- addr Used in the form ' wwww Leaves the parameter field address of the dictionary word wwww. Executes in a colon definition to compile the address as a literal. If the word is not found, an error message is produced. ( --- Starts a comment. All input until the following ) or a null is ignored. Executes during a colon definition to allow comments within a definition. A blank after the leading ( is required. (.") --- The run-time proceedure compiled by ." which prints the following inline text. (;code) --- The run-time proceedure compiled by ;code that rewrites the code field of the most recently defined word to point to the following machine code sequence. (+loop) n --- The run-time proceedure compiled by +loop which increments the loop index by n and tests for loop completion. (abort) --- Executes after an error. This word normally executes abort. (do) --- The run-time proceedure compiled by DO which moves the loop control parameters to the return stack. (find) addr1 addr2 --- pfa b tf (OK) addr1 addr2 --- ff (bad) Searches the dictionary starting at the name field address addr2, matching to the text at addr1. Returns the parameter field address (pfa), the length byte of the name field (b), and a true flag (tf) for a good match. If no match is found, only the false flag (ff) is returned. (loop) --- The run-time proceedure compiled by loop which increments the loop index and tests for loop completion. (number) n1 addr1 --- n2 addr2 Convert ASCII text beginning at addr1+1 with regard to base. The new value is accumulated into n1 being left as n2. Addr2 is the address of the first unconvertable digit. Used by number. * n1 n2 --- prod Leave the signed product of the two signed numbers (n1*n2). + n1 n2 --- n3 Leave the sum of n1+n2 as n3. +! n addr --- Add n to the value at the address. +- n1 n2 --- n3 Apply the sign of n2 to the value of n1, leaving the result as n3. +buf addr1 --- addr2 f Advance the disk buffer address addr1 to the address of the next buffer addr2. The flag f is false when addr2 is the buffer presently pointed to by the variable prev. +loop n1 --- (run time) addr n2 --- (compile time) Used in a colon definition in the form: do ... n1 +loop At run time, +loop selectively controls branching back to the corresponding do based on n1, the current loop index, and the loop limit. The signed increment n1 is added to the index and the total is compared to the loop limit. The branch back to do occurs until the new index is equal or greater than the limit (if n1>0), or until the new index is equal or less than the limit (if n1<0). Upon exiting the loop, the parameters are discarded and execution continues after +loop. At compile time, +loop compiles the run time word (+loop) and the branch offset computed from here to the address left on the stack by do. The value n2 is used for compile time error checking to ensure that the +loop is within a do. +origin n --- addr Add n to the memory address of the origin parameter area leaving addr. The parameter area is located at the start of the program area. , n --- Store n into the next available dictionary location, advancing the dictionary pointer. - n1 n2 --- n3 Leave the difference of n1-n2. --> Continue interpretation with the next disk screen. -dup n --- n (if 0) n --- n n (if <>0) Duplicate n only if it is non-zero. This is usually used to copy a value just before if, to eliminate the need for an else part to drop it. -find --- pfa b tf (found) --- ff (not found) Accepts the next text word (delimited by blanks) in the input stream to here and searches context and then current vocabularies for a matching entry. If found, the dictionary entry's parameter field address (pfa), its length byte (b), and a true flag (tf). Otherwise, only a flase flag (ff) is left. -trailing addr n1 --- addr n2 Adjusts the character count n1 of a text string beginning at address addr to suppress the output of trailing blanks or zeros (i.e. the characters at addr+n1 to addr+n2 are blanks or zeros). . n --- Print a number from a signed 16 bit value, converted according to the numeric base. A trailing blank follows. ." --- Used in the form: ." wwww" Used in a colon definition, ." compiles (.") and an inline string wwww to transmit the text to the screen. The space after the ." is necessary, and will not be included in the inline string. Used outside a colon definition, ." will immediately print the ext until the final " The maximum number of characters is 256. .r n1 n2 --- Print the number n1 right aligned in a field whose width is n2. No following blank is printed. / n1 n2 --- n3 Leave the signed quotient n3=n1/n2. /mod n1 n2 --- n3 n4 Leave the remainder (n3) and the signed quotient of n1/n2. The remainder has the sign of the dividend (n1). 0 1 2 3 --- n These small numbers are used so often that it is worth while to define them as constants. 0< n --- f Leave a true flag if the number is less than zero (negative), otherwise leave a false flag. 0= n --- f Leave a true flag if the number is equal to zero, otherwise leave a false flag. 0branch f --- The run time procedure to conditionally branch. If f is false (0), the following signed inline value is added to the interpretive pointer to branch ahead or back. Compiled by if, until, and while. 1+ n1 --- n2 Increment n1 by 1, leaving n2. 2+ n1 --- n2 Increment n1 by 2, leaving n2. 1- n1 --- n2 Decrement n1 by 1, leaving n2. : Used to define a new word in FORTH, called a colon definition, using the form: : cccc .... ; This creates a dictionary entry defining cccc as equivalent to the following sequence of FORTH word definitionss (...) until the next ;. The compiling process is done by the text interpreter as long as state is non-zero. Other details are that the context vocabulary is set to the current vocabulary and that words with the precedence bit set are executed rather than being comipled (see compile). ; --- Terminate a colon definition and stop further compilation. Compiles ;s. ;s --- Stop interpretation of a screen. ;s is also the runtime word compiled at the end of a colon definition by (;) which returns execution to the calling word. < n1 n2 --- f Leave a true flag if n1 is less than n2; otherwise leave a false flag. <# --- Setup for pictured numeric output formatting using the following form: <# # #s sign #> The conversion is done on a signed number producing text at pad. <builds --- Used within a colon definition with the following form: : cccc <builds .... does> .... ; Each time cccc is executed, <builds defines a new word with a high level execution procedure. Executing cccc in the form: cccc xxxx uses <builds to create a dictionary entry for xxxx with a call to the does> of cccc. When xxxx is later executed, it has the address of its parameter area on the stack and executes the words after does> in cccc. <builds and does> allow run time procedures written in high level rather than assembler level code. = n1 n2 --- f Leave a true flag if n1=n2; otherwise leave a false flag. > n1 n2 --- f Leave if true flag if n1>n2; otherwise leave a false flag. >r n --- Remove a number from the computation (Forth) stack and place as the most accessable on the return stack. Use should be balanced with r> in the same definition. ? addr --- Print the value contained at the address in free format (using .) according to the current base. ?button --- f Leave a flag indicating the current status of the mouse button. True means the button is pressed, false means the button is up. If the mouse is currently not active, a call is made to the UPDATE-MOUSE GEOS routine to get the current status of the button. ?comp --- Issue error message #17 if not compiling. ?csp --- Issue error message #20 if the current stack position differs from the value saved in csp (used to make sure the stack is kept even). ?derror n --- If n is not zero, issue the error message DISK ERROR n and call quit. If n is zero (the normal return from a disk function), n is discarded and processing continue. ?error f n --- Issue error message #n, if the flag (f) is true. ?exec --- Issue error message #18 if not executing. ?loading --- Issue error message #22 if not loading. ?mouse --- n1 n2 Leave the y coordinate (n1), and the x coordinate (n2) of the current mouse position. If the mouse is not turned on (via mouseon), the coordinates will be as they were the last time the mouse was active. ?pairs n1 n2 --- Issue error message #19 if n1 does not equal n2. Used by figForth to indicate that compiled conditionals do not match (begin .... until, if ... endif). ?stack --- Issue error message #?? if the stack is out of bounds. ?vopen --- Checks to see if a GEOS VLIR file is open (usually the source file). Performs no action if it is already open. If the file is not open, executes vopen to open the file named in vfn. @ addr --- n Leave the 16 bit contents of the address addr. abort --- Clears the stacks and enters the execution state, and return control to the terminal input device. abs n --- u Leave the absolute value of n as u. again addr n --- (compile) --- (runtime) Used in a colon definition as: begin .... again At run time, again forces execution to return to just after the corresponding begin. The stack is unchanged. Execution will never leave this loop (unless r> drop is executed one level below). allot n --- Add the signed number to the dictionary pointer (dp). May be used to reserve dictionary space or re-origin memory. and n1 n2 --- n3 Leave the bitwise logical and of n1 and n2 as n3. b/buf --- n This constant leaves the number of bytes per disk buffer (the number read from disk, excluding the screen number control bytes). Each memory buffer is b/buf + 2 bytes long. back addr --- Calculate the backward branch offset from here to addr and compile it into the next available dictionary memory address. base --- addr A user variable containing the current number base used for input and output conversion. begin --- addr n (compile) --- (run time) Used in the colon definition as: begin ... until begin ... again begin ... while ... repeat At run time, begin marks the start of a sequence that may be repetitively executed. It serves as a return point from the corresponding until, again, or repeat. When executing until, a return to begin will occur if the top of the stack is false; for again and repeat a return to begin always occurs. At compile time, begin leaves its return address (addr) and n for compiler error checking. bl --- c A constant that leaves the ASCII value for the "blank" character. blanks addr n --- Fill and area of memory beginning at addr with n "blank" characters. block n --- addr Leave the memory address of the block buffer containing block n. If the block is not already in memory, it is transferred from disk to which ever buffer was least recently written. If the block occupying that buffer has been marked as updated (via update), that block is first written to disk before block n is read in. See also buffer, update, flush. block-read addr n1 n2 --- f Read VLIR record number n2 (up to n1 bytes) into a buffer at address addr. If there is a disk error, the standard GEOS disk error +64 is left as the flag f, otherwise a zero is returned. block-write addr n1 n2 --- f Write n1 bytes to the VLIR record number n2 from buffer at addr. If there is a disk error, the standard GEOS disk error +64 is left as the flag f, otherwise a zero is returned. branch --- The run time word to unconditionally branch. A signed 16 bit inline offset is added to the interpretive pointer (ip) to branch ahead or back. branch is compiled by else, again, repeat. buffer n --- addr Obtain the next memory buffer, assigning it to block n. If the contents of the buffer are marked as updated, the buffer is written to disk before being assigned. The block is not read from the disk. The address left is the first byte within the buffer for data storage (ie. past the 2 byte block number). c! b addr --- Store 8 bits at address addr. c, b --- Store 8 bits into the next available dictionary location, advancing the dictionary pointer. c@ addr --- b Leave the 8 bits contents of addr. cfa pfa --- cfa Convert the parameter field address (pfa) of a definition to it's code field address. clit --- A run time word to take the next dictionary byte and put it on the stack (this is a single byte version fo lit). cls b --- Fill the screen from the GEOS locations windowTop, windowBottom, leftMargin, rightMargin, with the pattern specified by b. cmove addr1 addr2 n --- Move the n number of bytes from addr1 to addr2. The contents are moved from the start of addr1 proceeding towards higher memory. No check is made for overlapping areas. cold --- The cold start word to adjust the dictionary pointer to the original value when geosForth was loaded. The word then restarts the system by calling abort. This word is useful to remove all the application programs and restart geosForth. compile --- When the word containing compile executes, the execution address of the word following compile is copied (compiled) into the dictionary. This allows specific compilation situations to be handled in addition to simply compiling an execution address (which the interpreter already does). constant n --- A defining word used in the form: n constant cccc This creates the word cccc, with it's parameter field containing n. When cccc is later executed, it will push the value of n to the stack. context --- addr A user variable containing a pointer to the vocabulary within which dictionary searches will first begin. cols --- A constant containing the number of pixel columns which will fit on a screen (normally 320). count addr1 --- addr2 n Leave the byte address addr2 and byte count n of a message text beginning at address addr1. It is presumed that the first byte ad addr1 contains the text byte count, and the acutal text starts with the second byte. Typically count is followed by type. cr --- Set the user variable out to zero to move the text cursor to the left edge of the screen. Advance the user variable row by one text line. cr check the resulting text line location against the geos bottom margin value and calls scroll to scroll the screen if needed. create --- A defining word used in the form: create cccc Used by such words as code and constant to create a dictionary header for the Forth word definition. The code field contains the address of the word's parameter field. cccc is created in the current vocabulary. csp --- addr A user variable temporarily storing the stack pointer position, for compilation error checking. current --- addr A user variable containing the vocabulabulary into which new words are compiled. decimal --- Set the numeric conversion base for base 10 (decimal) input and output of numbers. definitions --- Used in the form: cccc definitions Set the current vocabulary to the context vocabulary. In the example, executing vocabulary name cccc made it the context vocabulary and executing definitions made both specify the same vocabulary. depth --- n A word which returns the current number of items on the Forth stack (not counting the n returned by depth). desktop This word exits geosFORTH and returns to the GEOS DeskTop. digit c n1 --- n2 tf (ok) c n1 --- ff (bad) Converts the ASCII character c (using the base n1) to its binary equivalent n2, accompanied by a true flag. If the conversion is invalid, leaves only a false flag. do n1 n2 --- (run time) addr n --- (compile time) At run time, do begins a sequence with repetitive execution controlled by a loop limit n1 and an index. The initial index value is n2. do removes these from the stack. Upon reaching loop, the index is incremented by one. Until the new index equals or exceeds the limit, execution loops back to just after do, otherwise the loop parameters are discarded and execution continues following the loop. Both n1 and n2 are determined at run time and may be the result of other operations. Within a loop, i will copy the current value of the index to the stack. See i, loop, +loop, leave. When compiling within a colon definition, do compiles (do), and leaves the following address addr and n for later error checking. does> --- A word which defines the run time action within a high level defining word. does> alters the code field and first parameter of the new word to execute the sequence of compiled word addresses following does>. Used in combination with <builds. When the does> part executes it begins with the address of the first parameter of the new word on the stack. This allows interpretation using this area or its contents. Typical uses include multidimensional arrays and compiler generation. dp --- addr A user variable, the dictionary pointer, which contains the address of the next free memory above the dictionary. This is the value returned by here, and updated by allot. dpl --- addr A user variable containing the number of digits to the right of the decimal point on integer input. It may be used to hold output column location of a decimal point in user generated formatting. The default value is -1. drop n --- Discard the value currently on top of the stack. dup n --- n n Duplicate the value on top of the stack. else addr1 n1 --- addr2 n2 (compile time) Occurs in a colon definition in the form: if ... else ... endif At run time, else executes after the true part following if. else forces execution to skip over the following false part and resumes exectuion after the endif. It has no stack effect. At compile time else compiles branch reserving a branch offset, and leaves addr2 and n2 for error testing. else also resolves the pending forward branch from if by calculating the offset from addr1 to here and storing it at addr1. emit c --- Transmit ASCII character c to the screen. The user variable out is incremented by the width of the character. empty-buffers --- Mark all the block buffers as empty. Updated blocks are not written to disk. empty-buffers is called as part of loading the geosForth, but is not called as part of cold. -------------------CUT HERE------------------- ------------------------------------------------------------------------- "We know only the strong will survive, But the meek will inherit. So if you've got a coat of arms, oh friend, I suggest we wear it." John Mellencamp. ------------------------------------------------------------------------- anderson@c10sd3.StPaul.NCR.COM |UUCP: {rosevax, crash}!orbit!pnet51!jpa Joel Peter Anderson |ARPA: crash!orbit!pnet51!jpa@nosc.mil NCR Comten / Software engineer |INET: jpa@pnet51.cts.com -------------------------------------------------------------------------