Glossary -------- A glossary of QForth words. The format is: ( -- ) last update: 07-Jun-96 ============================================================================= ! ( n addr -- ) Store a 16-bit value (n) and the address given (addr). Ex: variable foo ( define foo ) 3422 foo ! ( put the number 3422 into foo ) " ( -- ) Delimiter to mark the end of a string, used with ." and lit". ' ( -- addr ) Places the address of the next word on the stack. Ex: : hi ." Hello" cr ; ( define a simple word ) variable foo ( make a variable ) ' hi foo ! ( save the address of hi's code in foo ) foo @ execute ( causes hi to be run ) ( ( -- ) Begins a comment. ) ( -- ) Ends a comment. Everything between ( and ) is ignored. * ( n m -- m*n ) Multiply two 16-bit numbers and leave the result on the stack. Ex: 23 12 * . displays 276 + ( n m -- m+n ) Add two 16-bit numbers and leave the result on the stack. Ex: 23 12 + . displays 35 +! ( n addr -- ) Add the value n to the contents of address addr. Ex: variable k ( create a variable ) 23 k ! ( put 23 in it ) 12 +! k ( add 12 to it ) k @ . ( display the new value: 35 ) +loop ( n -- ) Add n to the current loop index, n must be positive. Ex: : by-two 10 0 do i . 2 +loop ; ( make a word to count by 2 ) by-two displays: 0 2 4 6 8 , ( n -- ) Compile a 16-bit number off the stack into the dictionary. Useful for creating arrays. Ex: create pts ( create a dictionary entry called pts ) 85 , 10 , ( first point [85,10] ) 50 , 75 , ( second point [50,75] ) 120 , 75 , ( third point [120,75] ) N.B. the final value needs a , after it. - ( n m -- n-m ) Subtract two 16-bit numbers and leave the result on the stack. Ex: 23 12 - . displays 11 . ( n -- ) Display the top of stack as a signed decimal number. ." ( -- ) Compile a string to be displayed when run. End with a ". Definitions only. Ex: : hi ." Greetings!" ; hi displays Greetings! .r ( -- ) Print the return stack on the screen without altering it. .s ( -- ) Print the stack on the screen without altering it. Ex: 2 4 7 .s displays 2 4 7 and leaves them on the stack. / ( n m -- n/m ) Divide two 16-bit numbers and leave the result on the stack. Ex: 23 12 / . displays 1 (integer division) 0< ( n -- 0 or -1 ) If n is less than zero leave a -1 otherwise leave a 0 . 0= ( n -- 0 or -1 ) If n is zero leave a -1 otherwise leave a 0. This is equivalent to a logical NOT. 0> ( n -- 0 or -1 ) If n is greater than zero leave a -1 otherwise leave a zero. 1+ ( n -- n+1 ) Add one to the top of stack. 1- ( n -- n-1 ) Subtract one from the top of stack. 2* ( n -- n*2 ) Multiply n by 2. This is equivalent to a logical shift left. 2+ ( n -- n+2 ) Add two to n. 2- ( n -- n-2 ) Subtract two from n. 2/ ( n -- n/2 ) Divide n by two. This is equivalent to a logical shift right. : ( -- ) Begin a colon definition. The word following is the name of the new definition. All subsequent input is compiled into the definition until a ; is found. Ex: : myWord 12 34 56 + + . cr ; ( create a word called myWord ) ; ( -- ) End a colon definition. Words after the ; will be execute and not compiled. < ( n m -- n ( n m -- n<>m ) Leaves -1 if n not equal m, 0 otherwise. = ( n m -- n=m ) Leaves -1 if n equals m, 0 otherwise. > ( n m -- n>m ) Leaves -1 if n greater than m, 0 otherwise. >r ( n -- ) Put n on the return stack. Useful for holding a value temporarily. Use in a colon definition and be certain to remove it before the word ends. Ex: : 2inc ( a1 a2 n -- ) ( add n to a1 and a2 ) dup >r ( save a copy of n on return stack ) swap +! ( update a2 ) r> swap +! ; ( update a1 ) ? ( addr -- ) Display the contents of addr. Equivalent to addr @ . @ ( addr -- n ) Place the 16-bit number starting at addr on the stack. Ex: variable n 2342 n ! ( make a variable and put a value in it ) n @ . ( displays 2342 ) abs ( n -- |n| ) Replace n with the absolute value of n. allot ( n -- ) Reserve n bytes of dictionary space. Useful for defining arrays or other areas of memory. Ex: create myArray 1000 allot ( create myArray and reserve 1000 bytes ) and ( n m -- ) Logical AND n and m. Returns -1 if both nonzero, 0 otherwise. Useful for complex logical comparisons. Ex: n @ 23 > n @ 74 < and if ." yes" else ." no" then displays "yes" if n>23 and n<74 areg ( -- addr ) Returns the address of the areg variable. The value of areg is loaded into the accumulator before execute calls a machine language routine. Ex: 65 areg ! 65005 execute displays A ( 65005 is COUT ) b.and ( n m -- n^m ) Perform a bitwise logical AND on n and m. Useful for masking bits. Not to be confused with AND above. Ex: 255 127 and . displays -1 since both nonzero 255 127 b.and . displays 127 since 11111111 ^ 01111111 = 01111111 b.clr ( m n -- m^1comp.n ) Perform a ones complement (xor 65535) on n then a logical bitwise AND with m. Ex: 255 255 b.clr . displays 0 since 11111111 ones comp. is 00000000. b.or ( n m -- n(or)m ) Perform a bitwise logical OR of n and m. Ex: 128 1 b.or . displays 129 since 10000000 or 00000001 = 10000001 begin ( -- ) In a colon definition only. Start a WHILE or UNTIL loop. Ex: : one begin key dup . 13 = until ; ( print chars until return ) : two begin key dup 13 <> while . repeat ; bye ( -- ) Quit QForth. c! ( n addr -- ) Store n (lower 8 bits really) at the byte whose address is addr. Useful for manipulating characters and individual bytes. And for entering short machine code programs. Ex: 169 768 c! 65 769 c! 32 770 c! 237 771 c! 253 772 c! 96 773 c! 768 execute displays A c, ( n -- ) Store n (lower 8-bits) in the dictionary. Ex: create abc 65 c, 66 c, 67 c, 0 c, ( string "ABC" ) c@ ( addr -- n ) Return the value of the byte (8-bits) at address addr. Ex: 258 k ! k c@ . displays 2 (low part if 258 = 0000000100000010 ) ch ( n -- ) Set text cursor horizontal position to n < 80. close ( -- ) Close all open disk files. constant ( n -- ) Create a constant whose value is n and name is the next word. Ex: 100 constant MAX MAX . displays 100, note: no @ is needed cr ( -- ) Output a return character. create ( -- ) Take the next word on the input line and make a dictionary entry with that name. Useful for naming areas of dictionary memory such as arrays and strings. Ex: create array ( make the dictionary entry ) 256 allot ( and reserve some bytes ) cv ( n -- ) Change the vertical position to n < 24. drop ( n -- ) Drop n from the stack. dup ( n -- n n ) Duplicate n on the stack. emit ( n -- ) Print the character whose ASCII code it n. erase ( addr len -- ) Zero len bytes of memory starting at addr. execute ( addr -- ) Run a machine code program starting at address addr. The current values of areg, xreg, and yreg are loaded into the A, X, and Y registers before the program is run. Useful for calling loaded assembly language programs. When used with ' and variables it provides a way to store word addresses for defered execution. Ex: : a1 ." one" ; : a2 ." two" ; : a3 ." three" ; create v ' a1 , ' a2 , ' a3 , : ?? 1- 2* v + @ execute cr ; Then 1 ?? displays one 2 ?? displays two 3 ?? displays three expect ( addr len -- ) Accept len characters from the keyboard (not counting backspace) and put them in memory starting at address addr. A return will end the expect. Use span to see how many characters were actually typed. Ex: create buf 100 allot ( an input buffer ) buf 100 expect ( read a line of input ) span . ( print number of characters actually read ) false ( -- 0 ) A constant 0. fclose ( n -- ec ) Close the disk file whose reference number is n = 0, 1, or 2. Returns the result of the operation, 0 = no error, other numbers are the Macintosh error codes (absolute value). fcreate ( addr type aux -- ec ) Create a new disk file of zero length. addr points to the filename, which must end with a zero. Type and aux were for the ProDOS operating system and are ignored but must be present. ec is the result code, 0 = no error. Ex: create ABC 65 c, 66 c, 67 c, 0 c, ( make the filename ) ABC 0 0 fcreate . ( make the file ) fdestroy ( addr -- ec ) Delete a disk file. addr points to the null terminated filename. ec is the result code, 0 = no error. fill ( addr len val -- ) Fill len bytes of memory starting at addr with val. fopen ( file# addr -- ec ) Open file number file# (0,1, 2). addr points to the filename string. The result code is 0 for no error. Ex: create ABC 65 c, 66 c, 67 c, 0 c, 0 ABC fopen . ( open the file ABC ) forget ( -- ) Remove the following word and all words after it from the dictionary. Ex: : one ; : two ; : three ; forget two ( erases two and three ) three <-- error fposition ( file# hi lo -- ec ) Position the file pointer for file file# to the hi*65536+lo-th byte. Ex: 2 0 245 fposition . ( position to the 245-th byte of the file ) fread ( file# buf len -- n ec ) Read a specified number of bytes from the file file#. buf is the address of the input buffer, len is the number requested. n is the number actually read and ec is the error code, 0 = no error. Ex: 0 f fopen drop ( open the file f points to ) 0 b 100 fread drop drop ( read 100 bytes from the file ) fstat ( file# -- ec ) Request information about a file. Most of the information is specific to ProDOS and is ignored. ec is always zero. This word should not be used. fwrite ( file# buf len -- n ec ) Write a specified number of bytes from a buffer to the file file#. buf points to the source and len is the length. n is actual number written and ec is the error code, 0 = no error. Ex: 0 f fopen drop ( open the file ) 0 b 100 fwrite drop drop ( write 100 bytes ) 0 fclose drop i ( -- n ) Within a DO loop, i returns the current index value. Ex: : count 11 1 do i . space loop cr ; count displays 1 2 3 4 5 6 7 8 9 10 j ( -- n ) In a nested DO loop, j returns the outer loop index. Ex: : count 2 0 do 103 101 do i . j . cr loop loop ; count starts as 101 0 key ( -- c ) Wait for a single key stroke from the user and return the ASCII code of the key. leave ( -- ) Leave the current DO loop. Ex: : test 10232 993 do i 23 mod 0= if i leave else then loop ; test exits with 1012 on the stack. lit" ( -- ) Compile a literal string. Ex: : name lit" Biggles" ; ( compile Biggles into the dictionary ) name ( returns the address or the counted string: ) So, name c@ . --> 7 name 1+ c@ emit --> B name 2+ c@ emit --> i , etc. mod ( n m -- n mod m ) Return the remainder of n divided by m. Ex: 27 4 mod . displays 3 since 6 * 4 = 24 and 27 - 24 = 3 negate ( n -- -n ) Change the sign of the top of stack. not ( n -- 0 or -1 ) If n is not zero return 0. true -> false and false -> true. A logical NOT. Ex: -1 not . gives 0 or ( n m -- 0 or -1 ) Logical OR of n and m. True (-1) if either n or m is true (not 0). over ( a b -- a b a ) Copy the next to top stack item. page ( -- ) Clear the screen, graphics and text. r> ( -- n ) Pull a value from the return stack. Use >r and r> in balanced pairs or chaos will ensue. Ex: : nada 34 >r 56 . r> . ; displays 56 34 r@ ( -- n ) Copy the top return stack value to the stack. Does not remove it. Ex: : nada 34 >r 56 . r@ . r> . ; displays 56 34 34 read ( -- ) Compile the source file whose name follows. No spaces allowed in the name. Ex: read intro ( compile the intro file ) repeat ( -- ) Finish a WHILE loop. Colon definition only. Ex: begin key 13 <> while ." nope" cr repeat rot ( a b c -- b c a ) Rotate top three stack items. space ( -- ) Print a space. Equivalent to 32 emit spaces ( n -- ) Print n spaces. span ( -- n ) Return the number of characters read during the most recent 'expect'. string ( -- ) Compile a string into the dictionary, delimited by a ~. Ex: create s string foobar~ s 3 + c@ emit gives b swap ( a b -- b a ) Switch the top two stack values. true ( -- -1 ) Leave a -1 on the stack. u. ( n -- ) Unsigned print of top of stack. Ex: -1 . gives -1 -1 u. gives 65535 u< ( n m -- 0 or -1 ) Unsigned less than comparison. until ( f -- ) Colon definition only. The bottom part of a BEGIN UNTIL loop. The loop exits when f is true. Ex: : ex begin key dup emit 13 = until ; display characters until return pressed. variable ( -- ) Create a dictionary entry for a variable with the next word as the name. Ex: variable sweet-pea 1 sweet-pea ! while ( f -- ) Colon definition only. In a BEGIN WHILE REPEAT loop WHILE executes the part between WHILE and REPEAT as long as f is true. Ex: : ex begin key dup 13 <> while emit repeat ; words ( -- ) Display a list of all the defined words in the order in which they were defined. xor ( n m -- 0 or -1 ) Logical XOR (exclusive-OR) of n and m. Return -1 (true) if either n or m is non-zero but return 0 if both n and m true. One or the other but not both. xreg ( -- addr ) Return the address of the xreg variable. The value of xreg is loaded into the X register just before an EXECUTE. yreg ( -- addr ) Return the address of the yreg variable. The value of yreg is loaded into the Y register just before an EXECUTE. ============================================================================= New words available in version 2.1 and later. depth ( -- n ) Depth of the QForth stack, excluding n. type ( addr len -- ) Type a string on memory. count ( addr -- addr+1 len ) Take a counted string and return an addr len pair. disp ( addr -- ) Like type but displays a null terminated string. here ( -- addr ) Returns an address that is just beyond the end of the dictionary. room ( -- #bytes ) Returns the number of bytes of dictionary remaining. fgetc ( file# -- c ec ) Gets the next character from the open file#. ec is the ProDOS error code, 0 equals no error. fputc ( c file# -- ec ) Put the character c into the open file#. ec is error code. fsize ( file# -- hi lo ) Return the number of byes in the open file, file#. slot/drv ( slot drive -- ) Set the slot and drive number for readblk and writeblk. readblk ( block# buffer -- ec ) Read the 512 byte ProDOS disk block# into the buffer. writeblk ( block# buffer -- ec ) Write the 512 bytes of memory starting at buffer into disk at block# 3+, 3-, 4+, 4- ( n -- n+/-3 or 4) Increment/decrement top of stack. k ( -- n ) In a triply nested loop return the index of the outer most loop. inverse , normal ( -- ) Set the video output accordingly. .$ ( n -- ) Print the top of stack as a 2 or 4 digit hex number.