rob@idacom.uucp (Rob Chapman) (02/23/90)
( A one line comment on each of the words in bot-Forth Kernel Jan 20, 90 RC ) ( ==== Stacks ==== ) SP! ( ? -- ) reset the data stack RP! ( -- ) reset the return stack DEPTH ( -- n ) return the current depth of the data stack ( ==== Data stack operators ==== ) SWAP ( n \ m -- m \ n ) swap the top two items of the stack NUP ( a \ b -- a \ a \ b ) duplicate the second stack item (rhymes with DUP) TUCK ( a \ b -- b \ a \ b ) tuck a copy of the top item under the second item DUP ( n -- n \ n ) duplicate the top item of the stack OVER ( n \ m -- n \ m \ n ) copy the second item to the top of the stack NIP ( n \ m -- m ) drop the second item on the stack DROP ( n -- ) drop the top item of the stack 2DUP ( a \ b -- a \ b \ a \ b ) duplicate the top two items 2DROP ( a \ b -- ) drop the top two items ROT ( a \ b \ c -- b \ c \ a ) rotate the third item to the top of stack ?DUP ( n -- [n] \ n ) duplicate the top item of the stack if it is not 0 ( ==== Return stack operators ==== ) DUP>R ( n -- n ) push a copy of n to the return stack R>DROP ( -- ) drop the top of the return stack >R ( n -- ) push n to the return stack R> ( -- n ) pop n from the return stack R ( -- n ) get a copy of the top item on the return stack ( ==== Math and Logic ==== ) + ( n \ m -- p ) add n to m - ( n \ m -- p ) subtract m from n AND ( n \ m -- p ) AND n with m OR ( n \ m -- p ) OR n with m XOR ( n \ m -- p ) XOR n with m 2* ( n -- m ) shift n left one bit and set bit 0 to 0 2/ ( n -- m ) shift n right one bit but don't change bit 15 U2/ ( n -- m ) shift n right one bit and set bit 15 to 0 NEGATE ( n -- m ) take the two's complement of n NOT ( n -- m ) invert all the bits of n ( ==== Memory access ==== ) @ ( a -- n ) fetch a word from address a ! ( n \ a -- ) store a word at address a C@ ( a -- c ) fetch a byte from address a C! ( c \ a -- ) store a byte at address a +! ( n \ addr -- ) increment the value at address a by n ( ==== Incrementing/Decrementing memory access ==== ) @+ ( a -- n \ a+ ) fetch a word from address a and increment a by 2 @- ( a -- n \ a- ) fetch a word from address a and decrement a by 2 C@+ ( a -- c \ a+ ) fetch a byte from address a and increment a by 1 C@- ( a -- c \ a- ) fetch a byte from address a and decrement a by 1 !+ ( n \ a -- a+ ) store a word at address a and increment a by 2 !- ( n \ a -- a- ) store a word at address a and decrement a by 2 C!+ ( c \ a -- a+ ) store a byte at address a and increment a by 1 C!- ( c \ a -- a- ) store a byte at address a and decrement a by 1 ( ==== Unsigned multiply and unsigned divide ==== ) /MOD ( n \ m -- rem \ quot ) 16 bit unsigned divide with remainder / ( n \ m -- quot ) 16 bit unsigned divide MOD ( n \ m -- rem ) 16 bit modulus * ( n \ m -- nm* ) 16 bit by 16 bit unsigned multiply with a 16 bit result ( ==== Comparison ==== ) NO ( -- 0 ) a false flag YES ( -- -1 ) a true flag 0= ( n -- flag ) return YES if n is 0, else return NO 0< ( n -- flag ) return YES if n is negative, else return NO = ( n \ m -- flag ) return YES if n is equal to m, else return NO < ( n \ m -- flag ) return YES if n is less than m, else return NO > ( n \ m -- flag ) return YES if n is greater than m, else return NO U< ( n \ m -- flag ) same as < but unsigned and used typically for addresses U> ( n \ m -- flag ) same as > but unsigned and used typically for addresses ABS ( n -- n ) take the absolute value of n ( note: 8000 ABS is 8000 ) MAX ( n \ m -- p ) return the maximum of n or m MIN ( n \ m -- p ) return the minimum of n or m ( ==== Memory Manipulation ==== ) BL ( -- n ) the ascii value of blank, hex 20 COUNT ( addr -- addr' \ count ) read a byte and increment addr by 1 CMOVE ( s \ d \ n -- ) move n bytes from a to b <CMOVE ( s \ d \ n -- ) same as CMOVE but going from high to low memory MOVE ( s \ d \ n -- ) move n words (16 bit) from a to b FILL ( a \ n \ c -- ) fill n bytes of memory with c starting at address a ERASE ( a \ n -- ) fill n bytes of memory with 0 starting at address a BLANKS ( a \ n -- ) fill n bytes of memory with 20H starting at address a ( ==== Memory Management ==== ) dp ( -- a ) variable containing the address of the start of free memory HERE ( -- addr ) return the contents of dp ALLOT ( n -- ) allocate n bytes of memory , ( n -- ) store n into free memory and increment dp by 2 C, ( n -- ) store n into free memory and increment dp by 1 EVEN ( -- ) round dp up to an even address ( ==== Header Status Bits ==== ) latest ( -- a ) points to the link field of the most recently defined word +BITS ( bits \ a -- ) set bits of the byte at address a -BITS ( bits \ a -- ) clear bits of the byte at address a LATEST ( -- lfa ) link field address of the latest word IMMEDIATE ( -- ) make the latest word immediate SMUDGE ( -- ) hide the latest word from the interpreter RECURSE ( -- ) reveal the latest word to the interpreter ( ==== Compile state: 0 for interpreting; 80 for compiling ==== ) compile ( -- a ) variable containing current state of compiler ] ( -- ) set state to compile [ ( -- ) set state to interpret ( ==== Queues ===== ) QUEUE ( #words -- ) create a queue with #words entries >Q ( n \ queue -- ) append n to end of queue Q> ( queue -- n ) return first value in queue Q ( queue -- n ) get a copy of first value in queue 0Q ( queue -- ) remove all items from a queue Q? ( queue -- flag ) return number of items in a queue ( ==== BARON Tasker ==== ) peasantq ( -- a ) address of peasant queue EXECUTE ( cfa -- ) execute code at cfa >BARON ( cfa -- ) append a task to the peasant queue BARON ( -- ) execute a task from the peasant queue KILL ( cfa -- ) remove all occurances of a task from the peasantq RUN ( cfa -- ) append a task and remove any other occurances in the peasantq ( ==== Forth character I/O ==== ) keyq ( -- a ) keyboard input queue; checked by KEY emitq ( -- a ) output queue; used by EMIT out ( -- a ) variable holding the number of characters output since CR KEY? ( -- n ) number of items in keyq KEY ( -- char ) get a character from the keyq ?WAIT ( -- ) if the emitq is full, run the baron until emitq not full EMIT ( char -- ) stuff a character in the emitq CR ( -- ) emit a linefeed and a carriage return ?CR ( -- ) call CR if out is not 0 SPACE ( -- ) emit a space SPACES ( n -- ) emit n spaces TYPE ( a \ n -- ) emit n characters from address a PROMPT ( -- ) output the prompt ( ==== Numerical Output ==== ) base ( -- a ) variable containing current base for number I/O HEX ( -- ) set current base to hex BIN ( -- ) set current base to binary DECIMAL ( -- ) set current base to decimal PAD ( -- addr ) a scratch pad area for number conversion HOLD ( char -- ) prepend char to current number string <# ( -- ) start number to string conversion #> ( n -- a \ n ) end number conversion and return address and length SIGN ( m \ n -- n ) prepend sign of m to current number string # ( n -- m ) convert one digit of n and prepend it to current num string #S ( n -- 0 ) convert all digits until n is 0 .R ( n \ m -- ) output n to screen, right justified in field m . ( n -- ) output n to screen ( ==== Parser ==== ) tib ( -- a ) points to terminal input buffer in ( -- ) index into terminal input buffer for parsing INPUT ( -- addr ) current address within input buffer +IN ( addr -- ) increment in by difference from INPUT SKIP ( char -- ) skip over any bytes in tib that equal char SCAN ( char -- ) scan tib until char is found PARSE ( char -- ) copy all characters up until char to HERE WORD ( char -- ) copy all bytes up until char to HERE skipping leading chars ( ( -- ) skip all characters up to and including ) ( ==== Word compiler ==== ) PUSH ( -- n ) push the following word onto the data stack C>LINK ( cfa -- lfa ) convert a code field address to a link field address L>CODE ( lfa -- cfa ) convert a link field address to a code field address COMPILE ( cfa -- ) compile cfa into the dictionary ( ==== Strings ==== ) QUOTE ( -- ) lay down all characters up to " in memory (") ( -- addr ) inner interpreter for " " ( -- addr ) return the address of a count-prefixed string delimited by " (.") ( -- ) inner interpreter for ." ." ( -- ) print out all characters up until " ( ==== Errors ==== ) ABORT ( -- ) reset the return stack ERROR ( -- ) print out any string at HERE and call ABORT ?ERROR ( flag -- ) call ERROR if flag is non-zero ( ==== Number Conversion ==== ) DIGIT ( char -- n \ flag ) try to convert a character to n and return a flag NUMBER ( string -- n ) convert a string to a number n or die trying ( ==== Dictionary Searching ==== ) DIFFER? ( a \ a -- a+ \ a+ \ f ) compare and increment bytes at address's BIT-DIFFER? ( a \ a \ mask -- a+ \ a+ \ f ) DIFFER? using bit mask SAME? ( string \ name \ mask -- flag ) compare string and name with count mask COMPARE ( string \ nfa -- flag ) compare a string to a name field SEARCH? ( string \ >list -- lfa \ yes | -- string \ no ) search list for string FIND? ( -- cfa \ status | -- string \ no ) try to find next word in input stream ?FIND ( -- addr ) try to find next word in input stream or die trying ( ==== Interpreter ==== ) \ ( -- ) compile the next word in the input stream even if it's immediate LITERAL ( n -- [n] ) compile n in memory if in compile mode ' ( -- cfa ) return the code field address of the next word in the input stream INTERPRET ( -- ) interpret the input stream pointed at by tib and in till 0 ( ==== Key collector ==== ) PREPARE ( key -- key ) massage keyboard input COLLECTOR ( -- ) collect keyboard input and interpret when cr is input ( ==== SIO access ==== ) SIO ( -- ) set access page to sio SIO@ ( n -- c ) fetch a character from register n of sio chip SIO! ( c \ n -- ) store a character to register n ( ==== SIO chip: DUART SCN2681 with a 3.6864mhz crystal ==== ) RESET-SIO ( -- ) reset sio chip ( ==== SIO porta primitives ==== ) RX? ( -- flag ) check to see if a byte has been received TX? ( -- flag ) check to see if a byte may be transmitted TX ( char -- ) transmit a byte RX ( -- char ) receive a byte ( ==== Sio port servicing ==== ) sio-in ( -- a ) points to queue used to hold input usually keyq sio-out ( -- a ) points to queue used to hold output usually emitq POLL-SIO ( -- ) poll sio chip for input and output ( ==== Control loop ==== ) INIT ( -- ) initialize everything for Forth to run QUIT ( -- ) main control loop which continuosly executes BARON ( ==== Conditional compilers ==== ) IF ( -- addr ) compile a 'branch if top is 0 instruction' ELSE ( addr -- addr ) compile a branch always ENDIF ( addr -- ) resolve IF branch address THEN ( addr -- ) synonym for ENDIF BEGIN ( -- addr ) record beginning of loop constructs UNTIL ( addr -- ) compile a 'branch back if top is 0 instruction' AGAIN ( addr -- ) compile a branch always back to BEGIN WHILE ( addr -- addr \ addr ) compile a 'branch if top is 0 instruction' REPEAT ( addr \ addr -- ) compile a branch back to BEGIN FOR ( -- addr ) compile setup words for counting loop NEXT ( addr -- ) compile conditional counting branch 0BRANCH ( n -- ) branch to somewhere if n is zero BRANCH ( -- ) branch to somewhere (FOR) ( n -- ) inner interpreter for FOR (NEXT) ( -- ) inner interpreter for NEXT ( ==== Defining Words ==== ) CALLED ( -- ) mark the latest word to be called only; not to be inlined MEASURE ( -- ) record the length of the latest word ?UNIQUE ( -- ) report if the next word in the input stream already exists HEADER ( -- ) create a header for the next word in the input stream FORGET ( -- ) forget all definitions after and including the next input word EXIT ( -- ) exit the current word : ( -- ) start a word definition ; ( -- ) terminate a word definition DATA ( -- ) create a word and have it return the address of space after it VARIABLE ( n -- ) create a variable and initialize it to n CONSTANT ( n -- ) create a constant and set it to n <BUILDS ( -- ) create a header for a word which will be defined by DOES DOES ( -- ) set latest word to execute code after DOES then return DOES> ( -- addr ) same as DOES but leaves child's address is on stack ( ==== File Loader: FF emitted to request a line of input ==== ) INPUT-LINE ( -- ) obtain a line from file server LD ( -- ) ld a file from file server ( ==== Version ==== ) VERSION ( -- ) print out version of bot-Forth