💾 Archived View for mirrors.apple2.org.za › archive › apple.cabi.net › Languages.Programming › QFort… captured on 2023-01-29 at 08:24:32.
View Raw
More Information
-=-=-=-=-=-=-
Glossary
--------
A glossary of QForth words. The format is:
<word> ( <stack-before> -- <stack-after> )
<description of the word>
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.
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<m )
Leaves -1 if n less than m or 0 otherwise.
<> ( 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:
<length><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.