home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / developmen / forth129 / FORTH.HLP next >
Text File  |  1995-04-17  |  8KB  |  180 lines
  1. FORTH info
  2. ==========
  3.  
  4. Note: This version of Forth uses a parameter stack that grows upwards. This is of
  5. no consequence unless you start using the sp@ and s0 operators.
  6.  
  7. In the following list, tos stands for 'top of stack'.
  8.  
  9. On the stack, TRUE is represented by a 1, FALSE by a 0.
  10.  
  11. Note that 32bit numbers are stored on the stack as two 16bit numbers.
  12.  
  13. +        Removes 2 numbers from tos and replaces with the sum of the 2 numbers
  14. -        Removes 2 numbers from tos and replaces with the difference
  15. *        Removes 2 numbers from tos and replaces with the product
  16. /        Removes 2 numbers from tos and replaces with the quotient
  17. mod      Removes 2 numbers from tos and replaces with the remainder of division
  18. /mod     Removes 2 numbers from tos and replaces with quotient and remainder
  19. 1+       Adds 1 to the number tos
  20. 2+       Adds 2 to the number tos
  21. 1-       Subtracts 1 from the number tos
  22. 2-       Subtracts 2 from the number tos
  23. 2/       Divides the number tos by 2
  24. 2*       Multiplies the number tos by 2
  25. d+       Adds two 32bit numbers
  26. d-       Subtracts two 32bit numbers
  27. d*       Multiplies two 32bit numbers
  28. d/       Divides two 32bit numbers
  29.  
  30. .        Removes 1 number from tos and prints it as a signed 16bit number
  31. u.       Removes 1 number from tos and prints it as an unsigned 16bit number
  32. d.       Removes 1 32bit number from tos and prints it unsigned 
  33. d-       Removes 2 32bit numbers from tos and subtracts them leaving the result tos
  34. ."       Prints the following string. The string must be terminated by a "
  35. cr       Prints a carriage return/linefeed
  36. emit     Removes 1 number from tos and prints the ascii character of that number
  37. cls      Clears the screen
  38. at       Removes two numbers from the stack and moves the cursor to that position.
  39.          Top left of the screen is 0,0 bottom right is 479,159. The x value should
  40.          be the number on top of the stack.
  41. vlist    Displays all currently defined words.
  42. time     Returns a 32bit number indicating the number of seconds since 1970.
  43. rand     Returns a 32bit random number
  44. seed     Takes a 32bit number off the stack for the random number seed.
  45.          Use 'time seed' to use the time as a seed.
  46. beep     Beeps. 300 5 beep gives a good beep.
  47. draw     Draws a line from the current cursor position to x,y where x,y are taken
  48.          from the stack
  49. box      Draws a box from the current cursor position to x,y where x,y are taken
  50.          from the stack
  51. fill     Fills a box from the current cursor position to x,y where x,y are taken
  52.          from the stack. The third item on the stack indicates set,clear,invert
  53. forget   Removes the word following 'forget' from the dictionary.
  54. variable Creates a variable with the name that follows variable.
  55. allot    Creates an array using the variable just created. MUST be used immediately
  56.          after variable.
  57. @        Takes a number off the stack and returns the value stored at the address
  58.          given by that number.
  59. !        Takes an address off the stack followed by a value and stores the value
  60.          at that address.
  61. <var>    Returns the address of the variable <var>
  62.  
  63. Variables:
  64. ==========
  65. To create a variable with the name 'age' use:
  66.  
  67. variable age
  68.  
  69. Arrays:
  70. =======
  71. To create an array called 'age', 20 long, use:
  72.  
  73. variable age 20 allot
  74.  
  75. To access element 14, use:
  76.  
  77. age 28 + @         to read contents
  78. 45 age 28 + !      to write 45 into element 14
  79.  
  80. The variable is initialised to 0 automatically. The word 'age' will now return
  81. the address of the variable 'age'.
  82.  
  83. Arrays are NOT initialised to 0.
  84.  
  85. To read the value of age:
  86.  
  87. age @ .
  88.  
  89. To write the value of age:
  90.  
  91. <value> age !
  92.  
  93. Other commands:
  94. ===============
  95.  
  96. The following operators all remove two numbers from the stack and compare them. The
  97. result is a 1 or 0 on the stack indicating TRUE or FALSE.
  98.  
  99. <>       Not equal
  100. =        Equal
  101. >        Greater than
  102. >=       Greater than or equal to
  103. <        Less than
  104. <=       Less than or equal to
  105.  
  106. The following operators all remove one number from the stack and compares it with
  107. zero. The result is a 1 or 0 indicating TRUE or FALSE.
  108.  
  109. =0       Equal to zero
  110. 0>       Greater than zero
  111. 0<       Less than zero
  112.  
  113. The following are bitwise logical operators.
  114.  
  115. and      ANDs the two numbers tos and replaces with result
  116. or       ORs  the two numbers tos and replaces with result
  117. xor      XORs the two numbers tos and replaces with result
  118.  
  119. not      Takes the number off the stack. If it is 0, it is replaced with 1.
  120.          If it is non-zero, it is replaced with 0.
  121.  
  122. negate   Changes the sign of the number tos.
  123.  
  124. The following are all stack operators.
  125.  
  126. rot      Removes the 3rd number on the stack and brings it to the top of the stack,
  127.          moving the top two numbers down.
  128. over     Takes the 2nd number on the stack and copies it on top of the stack
  129. swap     Swaps the two numbers at the top of the stack
  130. drop     Removes the number on top of the stack
  131. dup      Makes a copy of the item on top of the stack
  132. stack    Returns the number of items on the stack before this command was executed
  133. sp@      Returns the address of the top of the stack
  134. s0       Returns the address of the bottom of the stack
  135.  
  136. The following are also stack operators. They remove a number from the top of the
  137. stack and then use that number to operate on the stack. In the following description,
  138. n refers to the number removed from the top of the stack.
  139.  
  140. roll     Removes the nth item on the stack and brings it to the top of the stack,
  141.          moving all the other numbers down.
  142. pick     Copies the nth number on the stack at the top of the stack.
  143.  
  144. Note that rot  is effectively the same as '3 roll'
  145. Note that over is effectively the same as '2 pick'
  146.  
  147. The following are control functions:
  148.  
  149. do       Takes two numbers from the stack and places them on the return stack.
  150.          The two numbers are the start and end values of the do..loop.
  151. loop     Increments the loop counter on the return stack and compares it with
  152.          target value. Returns control to the statements following the do statement
  153.          if target not reached.
  154. +loop    Takes a number off the stack and increments the loop counter by that amount.
  155.          Returns control to the statements following the do statement if target not
  156.          reached.
  157. leave    Makes the loop counter value on the return stack the same as the target value.
  158.          The loop will therefore finish when the loop statement is next encounterd.
  159. i        Copies the loop counter value from the return stack and places it on the
  160.          main stack.
  161. i'       Copies the loop target value from the return stack and places on main stack.
  162. j        This takes the loop counter value from the outer of two nested do..loops
  163.          and places it on the stack.
  164. r@       Copies the value at the top of the return stack onto the main stack.
  165. r>       Removes a value from the return stack and places on the main stack.
  166. >r       Removes a value from the main stack and places on the return stack.
  167.  
  168. if...else...then...
  169.          
  170.          When the 'if' is encountered, a number is removed from the stack. If the
  171.          number is zero, the statements between 'else' and 'then' are executed
  172.          followed by the statements after the 'then'.
  173.          If the number removed is non-zero, the statements between the 'if' and the
  174.          'else' are executed, followed by the statements after the 'then'.
  175.  
  176.          Upto 8 levels of 'if...else...then' can be nested.
  177.          
  178.          The 'else' statement is optional, but if present *must* be between IF and
  179.          THEN statements.
  180.