home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / developmen / forth129 / README.TXT < prev   
Text File  |  1995-04-17  |  7KB  |  220 lines
  1. Psion 3a/Pocketbook II FORTH language
  2. =====================================
  3.  
  4. BETA TEST VERSION 1.29 - 17/04/95
  5.  
  6. This software is copyright Steve Godfrey
  7.  
  8. These notes assume you are familiar with the Forth language.
  9.  
  10. Installation:
  11.  
  12. Copy Forth.opa into any \APP\       directory
  13. Copy Forth.bin into any \APP\Forth\ directory
  14. Copy Forth.ini into any \APP\Forth\ directory
  15. Copy  Demo.sav into any \APP\Forth\ directory
  16.  
  17. and install Forth.opa in the usual way. Saved files are listed
  18. below the Forth icon on the system screen.
  19.  
  20. The demo has the following words defined: (most pointless!)
  21. -----------------------------------------
  22.  
  23. variable count
  24. variable primes 200 allot
  25. init                        (used by go)
  26. show                        (used by go)
  27. check                       (used by go)
  28. go                          works out 200 prime numbers and prints them
  29. bars                        draws bars on screen (shows use of graphics commands)
  30. 2dup                        (used by fact)
  31. 2drop                       (used by fact)
  32. d1-                         (used by fact)
  33. d0=                         (used by fact)
  34. fact                        (used by n!)
  35. n!                          works out factorial of number on top of stack (upto 13)
  36. primes                      displays prime numbers (uses variables 'primes' and 'count')
  37. rnd                         displays 100 random sized/placed boxes on screen.
  38.  
  39. Please inform me of any suggestions, bugs etc by email to:
  40.  
  41. stevegodfrey@cix.compulink.co.uk
  42. stevegodfrey@warp10.demon.co.uk
  43.  
  44. or arcade user #897
  45.  
  46. ****** WARNING: Mis-use of the Forth language could
  47.                 crash your psion. Please save any
  48.                 unsaved data in other applications
  49.                 before using.
  50.  
  51. The core of this FORTH language is written entirely
  52. in assembler for maximum speed. An OPL front end is
  53. used for simplicity. All commands entered are compiled
  54. before being executed. Any new definitions you create
  55. are compiled ready for future use.
  56.  
  57. Later versions will allow the use of ROM routines
  58. for graphics drawing, serial i/o, sound etc.
  59.  
  60. Words defined in version 1.29 of Psion 3a Forth
  61. -----------------------------------------------
  62.  
  63. forget   time     +        -        *        /        /mod     mod
  64. .        u.       d.       ."       at       cr       do       loop
  65. +loop    if       else     then     drop     dup      emit     i
  66. i'       j        >r       r>       r@       over     pick     roll
  67. rot      swap     vlist    2*       2/       2+       2-       1+
  68. 1-       and      or       not      xor      <>       0>       0<
  69. 0=       d-       leave    cls      negate   >        <        =
  70. <=       >=       sp@      s0       @        stack    variable !
  71. draw     box      fill     d+       d*       d/       beep     allot
  72. seed     rand
  73.  
  74. Notes:
  75. ======
  76.  
  77. A maximum of 32 nested do..loops can be used.
  78.  
  79. A maximum of 8 if statements can be nested.
  80.  
  81. The IF statements can be used with or without the ELSE statement, but if the
  82. ELSE statement is present, it *must* be between an IF and a THEN.
  83.  
  84. There are currently no checks on the state of the stack except with the
  85. . u. and d. functions. It is up to you to make sure that the stack has sufficient
  86. entries for the function used ie 'rot' requires 3 numbers on the stack but
  87. will work without. It may, however, crash the computer.
  88.  
  89. Mis-use of the language will usually give a harmless Panic 60 error, but worst case
  90. could require the psion to be reset, which could lose any unsaved data in
  91. other applications that are running.
  92.  
  93. Each word you enter must be seperated by a space.
  94.  
  95. Defining new words:
  96. ===================
  97.  
  98. You may define new words as follows.
  99.  
  100. : <word> <func1> <func2> <func3> ... ;
  101.  
  102. ie to define a function to print a given number of stars, you could use:
  103.  
  104. : stars 0 do 42 emit loop cr ;
  105.  
  106. You can then type '5 stars' to print 5 stars, or '10 stars' to print 10 stars etc.
  107.  
  108. You can use any defined word in furthur words, eg: another word could then be
  109. defined to print a triangle of stars as follows:
  110.  
  111. : triangle 10 1 do i stars loop ;
  112.  
  113. Entering 'triangle' would produce:
  114.  
  115. *
  116. **
  117. ***
  118. ****
  119. *****
  120. ******
  121. *******
  122. ********
  123. *********
  124.  
  125. Remember that forth uses reverse polish notation for calculations.
  126.  
  127. To add and print the sum of 5 and 7, enter
  128.  
  129. 5 7 + .
  130.  
  131. To print (5*6)+(9-7)*88, enter:
  132.  
  133. 5 6 * 9 7 - 88 * + .
  134.  
  135. / returns the int of the division. mod returns the remainder.
  136. /mod returns both the remainder and the quotient on the stack.
  137.  
  138. Any number of do..loops can be nested, eg:
  139.  
  140. : test 10 0 do 10 0 do i j * . loop cr loop ;
  141.  
  142. which prints the multiplication tables from 0 to 9 (no print formatting
  143. available yet).
  144.  
  145. Strings are used as follows:
  146.  
  147. : sqr dup dup ." The square of " . ." is " * . ;
  148.  
  149. Which produces:
  150.  
  151. >5 sqr
  152. The square of 5 is 25
  153.  
  154. Any space before the terminating " will be printed as part of the string.
  155. The space is not required to work, but you must have a space after the ."
  156.  
  157. You can do a reverse counting loop using +loop. Ie to print 10 to 1 enter
  158.  
  159. 1 10 do i . -1 +loop
  160.  
  161. Or to count in 2s, use
  162.  
  163. 10 0 do i . 2 +loop
  164.  
  165. For long words you can split the definition over several lines, eg:
  166.  
  167. >: stars
  168.     10 1
  169.     do
  170.       i
  171.       0
  172.       do
  173.         42 emit
  174.       loop
  175.       cr
  176.     loop
  177.     ;
  178. >
  179.  
  180. Each definition must end with a ; and start with a :
  181.  
  182. If you try and use an unknown word in a new definition, the new entry
  183. is aborted with an error.
  184.  
  185. If you have an unequal number of dos and loops or ifs, elses and thens
  186. an error will be reported and compilation aborted.
  187.  
  188. You can save the words you have defined using the menu. Any saved
  189. files in the \APP\Forth directory with extension .sav will appear
  190. under the system icon. Starting the language with a saved file
  191. will load the saved definitions. Saved files can be loaded
  192. into DATA for editing. Forgotten words are saved in the
  193. data file, but ignore when reloaded. They can be retrieved
  194. using DATA.
  195.  
  196. SETUP
  197. =====
  198.  
  199. The setup parameters only take effect when you next run FORTH.
  200.  
  201. As a rough guide:
  202.  
  203. Parameter stack uses 2 bytes per item.
  204.  
  205. Return stack uses 4 bytes per do..loop. Return stack of 256 allows 64 nested
  206. do..loops.
  207.  
  208. Dictionary size. Each stored word uses 5 bytes+length of name eg
  209.  
  210. : test 42 emit 34 emit ;
  211.  
  212. uses 9 bytes in the dictionary.
  213.  
  214. Code size is the space allocated to compiled words. 4k should be enough.
  215. (The forth code itself is only 4k-ish!).
  216.  
  217. -----------------------
  218. Steve Godfrey, 17/04/95
  219. -----------------------
  220.