home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / jsage / znode3 / uploads / mouse-do.lbr / NUMBERS.IZF / NUMBERS.INF
Encoding:
INI File  |  1993-02-22  |  5.9 KB  |  179 lines
  1.  
  2. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  3. ~ File name:      NUMBERS.INF                                      ~
  4. ~ Last updated:   11/18/84                                         ~
  5. ~ By:             Lee Bradley                                      ~
  6. ~ Remark:         This file attempts to explain the Mouse language ~
  7. ~                 thru example programs, NUMBERS.MSE and           ~
  8. ~                 NUMBERS1.MSE.  All the basic features of         ~
  9. ~                 Mouse are illustrated.                           ~
  10. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  11.  
  12. ~ Here is a program in Mouse which prints out the numbers from 0
  13. ~ to 99.  It skips to a new line each time it has printed five
  14. ~ numbers.
  15. ~
  16. ~
  17. ~ ~ NUMBERS.MSE
  18. ~ "!! Numbers, Numbers, Numbers ... !!!"
  19. ~ 0 n:
  20. ~ (
  21. ~ 100 n. - ^
  22. ~ n. ! 9 !'
  23. ~ 1 n. 5 \ 4 - +
  24. ~ [ "!" ]
  25. ~ n. 1 + n:
  26. ~ )
  27. ~ $
  28. ~
  29. ~ The ~ introduces a comment in Mouse. The "print character string"
  30. ~ command is ". Imbedding a ! in a quoted string is done to produce
  31. ~ carriage returns, ie. blank lines.
  32. ~
  33. ~ The program sets n to 0. Mouse is a "stack" oriented language. When
  34. ~ the Mouse interpreter sees
  35. ~
  36. ~       0 n :
  37. ~
  38. ~ the following takes place.  0 is placed on the stack, then n's address,
  39. ~ which happens to be 14.  Then the colon causes the 0 to be stored in
  40. ~ location 14, ie. at n .  The 0 and the 14 are "popped" off the stack.
  41. ~
  42. ~ The ( introduces a loop.  The expression to the left of a ^ must be
  43. ~ positive for the loop to continue.
  44. ~
  45. ~     ( 100 n . - ^  etc.   )
  46. ~
  47. ~ is equivalent to
  48. ~
  49. ~      while n < 100 do;        or perhaps more closely,
  50. ~      while 100 - n > 0 do;
  51. ~
  52. ~ The . is the "dereferencing" command of Mouse, causing the top of the
  53. ~ stack to be replaced by n's value.
  54. ~
  55. ~      n . ! 9 !'
  56. ~
  57. ~ prints the value of n and then tabs over 8 spaces.  The 9 is the ASCII
  58. ~ value for TAB and the two character command !' means print the ASCII
  59. ~ character on the stack, and then "pop" it off the stack.
  60. ~
  61. ~ The logic to skip to a new line every five numbers is
  62. ~
  63. ~      1 n . 5 \ 4 - + ["!"]
  64. ~
  65. ~ Here's how the code works (it took me a few tries to get this routine to
  66. ~ work).
  67. ~
  68. ~ Place 1 on the stack, then the address of n, then replace the top of
  69. ~ the stack with this number's value modulo 5.  (In our case, n starts at
  70. ~ 0).  Next, take away 4, add this to the 1 and, if ([...]) this value
  71. ~ is positive, issue a carriage return, line feed ie. generate a blank
  72. ~ line.  If you trace this as n increases due to the code
  73. ~
  74. ~      n . 1 + n :
  75. ~
  76. ~ you will see that the new lines occur at just the right moment, ie.
  77. ~ every five numbers!
  78. ~
  79. ~ The $ signals the end of a Mouse program.
  80. ~
  81. ~ All "macros", if any, (there are none in this example) would follow
  82. ~ the $.  If for example we wanted to ask for the upper limit to print
  83. ~ to (instead of hard-coding the 100), and print, and loop until an
  84. ~ upper limit of 0 is entered, we'd turn the code explained above into
  85. ~ a "macro" (subroutine) and pass it the entered value.  Here's the
  86. ~ code.  Notice that since the following lines are not prefixed with
  87. ~ tildes (~), you could actually run this INFormation file as a MouSE
  88. ~ program by typing    MOUSE NUMBERS.INF  .   Try it!
  89.  
  90. ~
  91. ~ NUMBERS1.MSE
  92. (
  93.  "! Upper limit ? "
  94.  ? u :
  95.  u. ^
  96.  "!!"
  97.  #N,u;
  98. )
  99.  
  100. $N
  101.  
  102.  0 n :
  103.  (
  104.  1%. n. - ^
  105.  n. ! 9 !'
  106.  1 n. 5 \ 4 - +
  107.  ["!"]
  108.  n. 1 + n :
  109.  )
  110.  "!"
  111.  
  112. @                   ~ end of macro
  113.  
  114. ~
  115. ~ The ? u :  is the "input and assign to u" code.
  116. ~
  117. ~       #N,u;
  118. ~
  119. ~ calls the macro N, passing it the address of the entered value.
  120. ~ If you responded with a 6 then 17 then 0, this is what would get
  121. ~ printed:
  122. ~
  123. ~
  124. ~ MOUSE.Z80 (2/21/93)
  125. ~
  126. ~ Upper limit? 6
  127. ~
  128. ~ 0     1      2     3     4
  129. ~ 5
  130. ~
  131. ~ Upper limit? 17
  132. ~
  133. ~ 0     1      2     3     4
  134. ~ 5     6      7     8     9
  135. ~ 10    11     12    13    14
  136. ~ 15    16
  137. ~
  138. ~ Upper limit? 0
  139. ~
  140. ~ Leaving ...
  141. ~
  142. ~ This ends (a rather exhaustive I'm afraid) explanation of the Numbers
  143. ~ program.  Most of the key concepts in Mouse programming are illustrated
  144. ~ by this program.
  145. ~
  146. ~ To run the Mouse program, you would type
  147. ~
  148. ~      MOUSE NUMBERS1.MSE
  149. ~
  150. ~ To interrupt a running program, you may use CTRL-C.  Mouse has a
  151. ~ trace feature which is invaluable during debug.  It is turned on by
  152. ~ including a { in the code and turned off with a } .  When on, the
  153. ~ 80 characters surrounding the character about to be executed are
  154. ~ displayed.  Hitting (SPACE BAR) single steps you thru the code.  An
  155. ~ arrow always points to the code about to be executed.  If you hit any
  156. ~ character other than the (SPACE BAR) during debug, the trace will be
  157. ~ turned off and your code will run at full speed (or go haywire).
  158. ~
  159. ~ The first thing that happens during the interpretation process is this:
  160. ~ the source code of your Mouse program gets loaded.  The "macros", if any,
  161. ~ are "compiled".  If you are interested in the details, look over the
  162. ~ source code of the Mouse interpreter.
  163. ~
  164. ~ The interpreter then carries out the instructions, branching to the
  165. ~ appropriate code routine depending on the character encountered.
  166. ~
  167. ~ Blanks are not important in Mouse code.  NB however: there must be
  168. ~ no blank between the $ and the macro letter.  Control codes
  169. ~ (ie. codes less than 32 ASCII) are ignored as well.  The interpreter
  170. ~ executes Mouse programs very quickly.  Nesting "macros" and
  171. ~ recursive code will slow things down.
  172. ~
  173. ~ The Numbers programs discussed above was written to be as readable as
  174. ~ possible.  It could have all been written on two to three lines.  The
  175. ~ interpreter could care less about the carriage returns, line feeds and
  176. ~ blanks.  I tend to put loop delimiters on lines by themselves (LISP
  177. ~ style).   Use what you think makes your code readable.
  178. ~
  179.