home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / alst-3.04.lha / ALSt-3.04 / manual.txt < prev    next >
Encoding:
Text File  |  1994-07-08  |  40.5 KB  |  1,189 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.        LLLLiiiittttttttlllleeee SSSSmmmmaaaallllllllttttaaaallllkkkk UUUUsssseeeerrrrssss MMMMaaaannnnuuuuaaaallll ---- VVVVeeeerrrrssssiiiioooonnnn TTTThhhhrrrreeeeeeee
  11.  
  12.  
  13.                           Tim Budd
  14.  
  15.                Department of Computer Science
  16.                   Oregon State University
  17.                      Corvallis, Oregon
  18.                          97331 USA
  19.  
  20.  
  21.                           _A_B_S_T_R_A_C_T
  22.  
  23.  
  24.           Version  three  of   Little   Smalltalk   was
  25.      designed  specifically  to  be easy to port to new
  26.      machines and operating systems. This document pro-
  27.      vides  the basic information needed to use Version
  28.      Three of Little Smalltalk, plus information needed
  29.      by  those  wishing to undertake the job of porting
  30.      the system to a new operating environment.
  31.  
  32.  
  33.  
  34.      The first version of Little Smalltalk, although simple,
  35. small  and  fast, was in a number of very critical ways very
  36. Unix specific.  Soon after the publication  of  the  book  _A
  37. _L_i_t_t_l_e  _S_m_a_l_l_t_a_l_k,  requests  started  flooding in asking if
  38. there existed a port to an amazingly large  number  of  dif-
  39. ferent  machines,  such  as  the  IBM PC, the Macintosh, the
  40. Acorn, the Atari, and even such systems as DEC VMS.  Clearly
  41. it   was  beyond  our  capabilities  to  satisfy  all  these
  42. requests, however in an attempt to meet them partway in  the
  43. summer  of  1988  I  designed  a  second  version  of Little
  44. Smalltalk, which was specifically designed to be  less  Unix
  45. specific  and  more  amenable to implementation of different
  46. systems.
  47.  
  48.      This document describes is divided into two parts.   In
  49. part  one  I  describe the basic features of the user inter-
  50. face.  This is essential information for anybody wishing  to
  51. use  the  system.  In part two we give the basic information
  52. needed by anybody wishing to undertake the task  of  porting
  53. version three Little Smalltalk to a new machine.
  54.  
  55. _1.  _G_e_t_t_i_n_g _S_t_a_r_t_e_d
  56.  
  57.      How you get started depends upon what  kind  of  system
  58. you  are  working  on.   Currently  there  are two styles of
  59. interface  supported.   A  line-oriented,  tty  style  stdin
  60. interface  is  available,  which  runs  under Unix and other
  61.  
  62.  
  63.  
  64.                         July 7, 1994
  65.  
  66.  
  67.  
  68.  
  69.  
  70.                            - 2 -
  71.  
  72.  
  73. systems.  There is also a window  based  system  which  runs
  74. under X-windows and on the Mac.
  75.  
  76. _1._1.  _T_h_e _s_t_d_i_n/_s_t_d_o_u_t _i_n_t_e_r_f_a_c_e
  77.  
  78.      Using the stdin/stdout interface,  there  is  a  prompt
  79. (the ``>'' caracter) typed to indicate the system is waiting
  80. for  input.  Expressions  are  read  at  the  keyboard   and
  81. evaluated  following each carrage return.  The result of the
  82. expression is then printed.
  83.  
  84.         >       5 + 7
  85.         12
  86.  
  87. Global variables can be created simply  by  assigning  to  a
  88. name.   The value of an assignment statement is the value of
  89. the right hand side.
  90.  
  91.                 x <- 3
  92.         3
  93.  
  94. Multiple expressions can appear on the same  line  separated
  95. by periods.  Only the last expression is printed.
  96.  
  97.                 y <- 17.  3 + 4
  98.         7
  99.  
  100.  
  101. _1._2.  _T_h_e _w_i_n_d_o_w_i_n_g _i_n_t_e_r_f_a_c_e
  102.  
  103.      The windowing interface is built on top  of  guido  van
  104. rossums  standard window package, and runs on top of systems
  105. that support standard windows.  These include X-11  and  the
  106. Macintosh.
  107.  
  108.      When you start up the system, there will  be  a  single
  109. window  titled  ``workspace''.  You can enter expressions in
  110. the workspace, then select either the menu items  ``do  it''
  111. or  ``print  it''.   Both  will evaluate the expression; the
  112. latter, in addition, will print the result.
  113.  
  114.      A number of other memu  commands  are  also  available.
  115. These permit you to save the current image, exit the system,
  116. or start the browser.
  117.  
  118.      The browser is an interface  permiting  you  to  easily
  119. view  system  code.   Selecting a class in the first pane of
  120. the browser brings up a second pane in which you can  select
  121. methods,  selecting a method brings up a third pane in which
  122. you can view and edit text.  Selecting ``compile'' following
  123. the  editing of text will attempt to compile the method.  If
  124. no errors are reported, the method  is  then  available  for
  125. execution.
  126.  
  127.  
  128.  
  129.  
  130.                         July 7, 1994
  131.  
  132.  
  133.  
  134.  
  135.  
  136.                            - 3 -
  137.  
  138.  
  139. _2.  _E_x_p_l_o_r_i_n_g _a_n_d _C_r_e_a_t_i_n_g
  140.  
  141.      This section  describes  how  to  discover  information
  142. about existing objects and create new objects using the Lit-
  143. tle Smalltalk system (version three). In Smalltalk one  com-
  144. municates  with  objects  by passing messages to them.  Even
  145. the addition message + is treated as a message passed to the
  146. first  object  5, with an argument represented by the second
  147. object. Other messages can be used to  discover  information
  148. about various objects.  The most basic fact you can discover
  149. about an object is its class.  This is given by the  message
  150. ccccllllaaaassssssss, as in the following examples:
  151.  
  152.         >       7 class
  153.         Integer
  154.         >       nil class
  155.         UndefinedObject
  156.  
  157.  
  158.      Occasionally, especially when  programming,  one  would
  159. like  to  ask  whether  the  class of an object matches some
  160. known class.  One way to do this would be to use the message
  161. ====  ====, which tells whether two expressions represent the same
  162. object:
  163.  
  164.         >       ( 7 class = = Integer)
  165.         True
  166.         >       nil class = = Object
  167.         False
  168.  
  169.  
  170.      An easier way is to use the message iiiissssMMMMeeeemmmmbbbbeeeerrrrOOOOffff::::;
  171.  
  172.         >       7 isMemberOf: Integer
  173.         True
  174.         >       nil isMemberOf: Integer
  175.         False
  176.  
  177.  
  178.      Sometimes you want to know if an object is an  instance
  179. of a particular class or one if its subclasses; in this case
  180. the appropriate message is iiiissssKKKKiiiinnnnddddOOOOffff::::.
  181.  
  182.         >       7 isMemberOf: Number
  183.         False
  184.         >       7 isKindOf: Number
  185.         True
  186.  
  187.  
  188.      All objects will respond to the message ddddiiiissssppppllllaaaayyyy by tel-
  189. ling  a little about themselves.  Many just give their class
  190. and their printable representation:
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                         July 7, 1994
  197.  
  198.  
  199.  
  200.  
  201.  
  202.                            - 4 -
  203.  
  204.  
  205.  
  206.         >       7 display
  207.         (Class Integer) 7
  208.         >       nil display
  209.         (Class UndefinedObject) nil
  210.  
  211.  
  212. Others, such as classes, are a little more verbose:
  213.  
  214.         >       Integer display
  215.         Class Name: Integer
  216.         SuperClass: Number
  217.         Instance Variables:
  218.         no instance variables
  219.         Subclasses:
  220.  
  221.  
  222. The display shows that the class IIIInnnntttteeeeggggeeeerrrr is  a  subclass  of
  223. class  NNNNuuuummmmbbbbeeeerrrr  (that  is,  class NNNNuuuummmmbbbbeeeerrrr is the superclass of
  224. IIIInnnntttteeeeggggeeeerrrr).  There are no instance variables for  this  class,
  225. and  it currently has no subclasses. All of this information
  226. could be obtained by means of other messages,  although  the
  227. ddddiiiissssppppllllaaaayyyy form is the easiest.  [ Note: at the moment printing
  228. subclasses takes a second or two.  I'm not sure why.]
  229.  
  230.         >       List variables display
  231.         links
  232.         >       Integer superClass
  233.         Number
  234.         >       Collection subClasses display
  235.         IndexedCollection
  236.         Interval
  237.         List
  238.  
  239. About the only bit of information that is not provided  when
  240. one  passes  the  message  ddddiiiissssppppllllaaaayyyy  to  a class is a list of
  241. methods the class responds to.  There are  two  reasons  for
  242. this  omission;  the  first  is  that this list can often be
  243. quite long, and we don't want to scroll the  other  informa-
  244. tion off the screen before the user has seen it.  The second
  245. reason is that there are really two different questions  the
  246. user  could  be asking.  The first is what methods are actu-
  247. ally implemented in a given class.  A  list  containing  the
  248. set  of methods implemented in a class can be found by pass-
  249. ing the message mmmmeeeetttthhhhooooddddssss to a class.  As we saw with the mes-
  250. sage ssssuuuubbbbCCCCllllaaaasssssssseeeessss shown above, the command ddddiiiissssppppllllaaaayyyy prints this
  251. information out one method to a line:
  252.  
  253.         >       True methods display
  254.         #ifTrue:ifFalse:
  255.         #not
  256.  
  257.  
  258.      A second question that one could ask  is  what  message
  259.  
  260.  
  261.  
  262.                         July 7, 1994
  263.  
  264.  
  265.  
  266.  
  267.  
  268.                            - 5 -
  269.  
  270.  
  271. selectors  an  instance  of  a  given class will respond to,
  272. whether they are inherited from superclasses or are  defined
  273. in  the  given  class.  This set is given in response to the
  274. message rrrreeeessssppppoooonnnnddddssssTTTToooo. [ NOTE: again form some reason  I'm  not
  275. sure of this command seems to take a long time to execute ].
  276.  
  277.         >       True respondsTo display
  278.         #class
  279.         #==
  280.         #hash
  281.         #isNil
  282.         #display
  283.         #=
  284.         #basicSize
  285.         #isMemberOf:
  286.         #notNil
  287.         #print
  288.         #basicAt:put:
  289.         #isKindOf:
  290.         #basicAt:
  291.         #printString
  292.         #or:
  293.         #and:
  294.         #ifFalse:ifTrue:
  295.         #ifTrue:
  296.         #ifFalse:
  297.         #not
  298.         #ifTrue:ifFalse:
  299.  
  300.  
  301.      Alternatively, one can ask whether instances of a given
  302. class will respond to a specific message by writing the mes-
  303. sage selector as a symbol:
  304.  
  305.         >       String respondsTo: #print
  306.         True
  307.         >       String respondsTo: #+
  308.         False
  309.  
  310.  
  311.      The inverse of this would be to ask what  classes  con-
  312. tain  methods  for  a  given message selector.  Class SSSSyyyymmmmbbbboooollll
  313. defines a method to yield just this information:
  314.  
  315.         >       #+ respondsTo display
  316.         Integer
  317.         Number
  318.         Float
  319.  
  320.  
  321.      The method that will be executed in response to a given
  322. message  selector  can  be displayed by means of the message
  323. vvvviiiieeeewwwwMMMMeeeetttthhhhoooodddd::::
  324.  
  325.  
  326.  
  327.  
  328.                         July 7, 1994
  329.  
  330.  
  331.  
  332.  
  333.  
  334.                            - 6 -
  335.  
  336.  
  337.  
  338.         >       Integer viewMethod: #gcd:
  339.         gcd: value
  340.                 (value = 0) ifTrue: [ |^ self ].
  341.                 (self negative) ifTrue: [ |^ self negated gcd: value ].
  342.                 (value negative) ifTrue: [ |^ self gcd: value negated ].
  343.                 (value > self) ifTrue: [ |^ value gcd: self ].
  344.                 |^ value gcd: (self rem: value)
  345.  
  346.  
  347.      Some Smalltalk systems make it very difficult  for  you
  348. to  discover  the  bytecodes  that  a method gets translated
  349. into.  Since the primary goal of Little Smalltalk is to help
  350. the  student  to  discover  how  a  modern  very  high level
  351. language is implemented, it  makes  sense  that  the  system
  352. should  help  you  as  much  as possible discover everything
  353. about its internal structure.  Thus a method, when presented
  354. with  the  message  ddddiiiissssppppllllaaaayyyy,  will  print  out  its bytecode
  355. representation.
  356.  
  357.         >       Char methodNamed: #isAlphabetic ; display
  358.         Method #isAlphabetic
  359.                 isAlphabetic
  360.                         |^ (self isLowercase) or: [ self isUppercase ]
  361.  
  362.         literals
  363.         Array ( #isLowercase #isUppercase )
  364.         bytecodes
  365.         32 2 0
  366.         129 8 1
  367.         144 9 0
  368.         250 15 10
  369.         9 0 9
  370.         32 2 0
  371.         129 8 1
  372.         145 9 1
  373.         242 15 2
  374.         245 15 5
  375.         241 15 1
  376.  
  377.  
  378.      Bytecodes are represented by four bit opcodes and  four
  379. bit  operands, with occasional bytes representing data (more
  380. detail can be found in the book).  The three numbers written
  381. on each line for the bytecodes represent the byte value fol-
  382. lowed by the upper four bits and the lower four bits.
  383.  
  384.  
  385.      If you have written a new class and want to  print  the
  386. class  methods  on  a file you can use the message ffffiiiilllleeeeOOOOuuuutttt::::,
  387. after first creating a file to write to.  Both  classes  and
  388. individual  methods  can  be  filed out, and several classes
  389. and/or methods can be placed in one file.  [ NOTE - file out
  390. doesn't work yet ].
  391.  
  392.  
  393.  
  394.                         July 7, 1994
  395.  
  396.  
  397.  
  398.  
  399.  
  400.                            - 7 -
  401.  
  402.  
  403.  
  404.         >       f <- File new
  405.         >       f name: 'foo.st'
  406.         >       f open: 'w'
  407.         >       Foo fileOut: f
  408.         >       Bar fileOut: f
  409.         >       Object fileOutMethod: #isFoo to: f
  410.         >       f close
  411.  
  412.  
  413. The file ``newfile'' will now have a  printable  representa-
  414. tion  of  the  methods  for the class Foo.  These can subse-
  415. quently be filed back into a different smalltalk image.
  416.  
  417.         >       f <- File new
  418.         >       f name: 'foo.st'
  419.         >       f open: 'r'
  420.         >       f fileIn
  421.         >       2 isFoo
  422.         False
  423.  
  424.  
  425.      Finally, once the user has added classes and  variables
  426. and  made  whatever  other  changes  they  want, the message
  427. ssssaaaavvvveeeeIIIImmmmaaaaggggeeee, passed to the pseudo variable ssssmmmmaaaallllllllttttaaaallllkkkk,  can  be
  428. used to save an entire object image on a file.  If the writ-
  429. ing of the image is successful, a message will be displayed.
  430.  
  431.         >       smalltalk saveImage
  432.         Image name? newimage
  433.         image newimage created
  434.         >
  435.  
  436.  
  437.      Typing control-D causes the interpreter to exit.
  438.  
  439.      When the smalltalk system is restarted, an  alternative
  440. image,  such  as the image just created, can be specified by
  441. giving its name on the argument line:
  442.  
  443.         st newimage
  444.  
  445.  
  446.      Further information on Little Smalltalk can be found in
  447. the book.
  448.  
  449. _3.  _N_e_w _M_e_t_h_o_d_s, _N_e_w _C_l_a_s_s_e_s
  450.  
  451. _3._1.  _S_t_d_i_n/_S_t_d_o_u_t _I_n_t_e_r_f_a_c_e
  452.  
  453.      New  functionality  can  be  added  using  the  message
  454. aaaaddddddddMMMMeeeetttthhhhoooodddd.   When  passed to an instance of CCCCllllaaaassssssss, this mes-
  455. sage drops the user into a standard Unix Editor.  A body for
  456. a  new  method can then be entered.  When the user exits the
  457.  
  458.  
  459.  
  460.                         July 7, 1994
  461.  
  462.  
  463.  
  464.  
  465.  
  466.                            - 8 -
  467.  
  468.  
  469. editor, the method body is compiled.  If it is syntactically
  470. correct, it is added to the methods for the class.  If it is
  471. incorrect, the user is given the option  of  re-editing  the
  472. method.   The  user  is  first  prompted for the name of the
  473. group to which the method belongs.
  474.  
  475.         >       Integer addMethod
  476.          ... drop into editor and enter the following text
  477.         % x
  478.                 |^ ( x + )
  479.          ... exit editor
  480.         compiler error: invalid expression start )
  481.         edit again (yn) ?
  482.          ...
  483.  
  484.  
  485.      In a similar manner, existing methods can be editing by
  486. passing  their  selectors,  as  symbols to the message eeeeddddiiiitttt----
  487. MMMMeeeetttthhhhoooodddd::::.
  488.  
  489.         >       Integer editMethod: #gcd:
  490.          ... drop into editor working on the body of gcd:
  491.  
  492.  
  493.      The name of the editor used by these methods  is  taken
  494. from  a  string  pointed  to  by the global variable _e_d_i_t_o_r.
  495. Different editors can be selected merely by redefining  this
  496. value:
  497.  
  498.         editor <- 'emacs'
  499.  
  500.  
  501.      Adding a new subclass is accomplished  by  sending  the
  502. message aaaaddddddddSSSSuuuubbbbCCCCllllaaaassssssss::::iiiinnnnssssttttaaaannnncccceeeeVVVVaaaarrrriiiiaaaabbbblllleeeeNNNNaaaammmmeeeessss:::: to the superclass
  503. object.  The the first argument is a symbol representing the
  504. name,  the  second  is  a string containing the names of any
  505. instance variables.
  506.  
  507.         >       Object addSubClass: #Foo instanceVariableNames: 'x y'
  508.         Object
  509.                 Foo display
  510.         Class Name: Foo
  511.         SuperClass: Object
  512.         Instance Variables:
  513.         x
  514.         y
  515.  
  516. Once defined, aaaaddddddddMMMMeeeetttthhhhoooodddd and eeeeddddiiiittttMMMMeeeetttthhhhoooodddd:::: can be used to  pro-
  517. vide functionality for the new class.
  518.  
  519.      New classes can also be added using the fileIn  mechan-
  520. ism.
  521.  
  522.  
  523.  
  524.  
  525.  
  526.                         July 7, 1994
  527.  
  528.  
  529.  
  530.  
  531.  
  532.                            - 9 -
  533.  
  534.  
  535. _3._2.  _T_h_e _W_i_n_d_o_w_i_n_g _I_n_t_e_r_f_a_c_e
  536.  
  537.      Using the windowing interface, new classes are  created
  538. by  selecting  the  menu item _a_d_d _c_l_a_s_s in the first browser
  539. window.  New Methods are selected by choosing _n_e_w _m_e_t_h_o_d  in
  540. a subsequent window.
  541.  
  542. _4.  _I_n_c_o_m_p_a_t_i_b_i_l_i_t_i_e_s _w_i_t_h _t_h_e _B_o_o_k
  543.  
  544.      It is unfortunately the case that during the transition
  545. from  version 1 (the version described in the book) and ver-
  546. sion 3, certain changes to the user interface were required.
  547. I will describe these here.
  548.  
  549.      The first incompatibility comes at the very  beginning.
  550. In  version  1  there  were  a  great number of command line
  551. options.  These have all been eliminated in  version  three.
  552. In  version  three  the only command line option is the file
  553. name of an image file.
  554.  
  555.      The interface to the editor has been changed.  In  ver-
  556. sion  one  this  was  handled  by  the  system,  and  not by
  557. Smalltalk code.  This required a  command  format  that  was
  558. clearly  not a Smalltalk command, so that they could be dis-
  559. tinguished.  The convention adopted was to use an APL  style
  560. system command:
  561.  
  562.         )e filename
  563.  
  564. In  version  three  we  have  moved  these  functions   into
  565. Smalltalk  code.   Now  the  problem is just the reverse, we
  566. need a command that is a Smalltalk command.  In addition, in
  567. version  one  entire classes were edited at once, whereas in
  568. version three only individual methods  are  edited.   As  we
  569. have  already noted, the new commands to add or edit methods
  570. are as follows:
  571.  
  572.         _c_l_a_s_s_n_a_m_e addMethod
  573.         _c_l_a_s_s_n_a_m_e editMethod: _m_e_t_h_o_d_n_a_m_e
  574.  
  575.  
  576.      The only other significant syntactic change is the  way
  577. primitive  methods  are  invoked.  In version one these were
  578. either named or numbered, something like the following:
  579.  
  580.         <primitive 37 a b>
  581.         <IntegerAdd a b>
  582.  
  583. In version three we have simply eliminated the keyword pppprrrriiiimmmm----
  584. iiiittttiiiivvvveeee, so primitives now look like:
  585.  
  586.         <37 a b>
  587.  
  588.  
  589.  
  590.  
  591.  
  592.                         July 7, 1994
  593.  
  594.  
  595.  
  596.  
  597.  
  598.                            - 10 -
  599.  
  600.  
  601.      There are far fewer primitives in  version  three,  and
  602. much  more  of  the  system is now performed using Smalltalk
  603. code.
  604.  
  605.      In addition to these syntactic changes, there are vari-
  606. ous  small changes in the class structure.  I hope to have a
  607. document describing these changes at some point, but  as  of
  608. right now the code itself is the best description.
  609.  
  610. _5.  _I_m_p_l_e_m_e_n_t_o_r_s _I_n_f_o_r_m_a_t_i_o_n
  611.  
  612.      The remainder of  this  document  contains  information
  613. necessary  for those wishing to examine or change the source
  614. code for the Little Smalltalk system.
  615.  
  616. _5._1.  _F_i_n_d_i_n_g _Y_o_u_r _W_a_y _A_r_o_u_n_d
  617.  
  618.      In this section we describe the files  that  constitute
  619. version three of the Little Smalltalk system.
  620.  
  621. mmmmeeeemmmmoooorrrryyyy....cccc
  622.      This is the memory manager, the  heart  of  the  Little
  623.      Smalltalk  system.   Although it uses a straightforward
  624.      reference counting scheme,  a  fair  amount  of  design
  625.      effort has gone into making it as fast as possible.  By
  626.      modifying it's associated description file (memory.h) a
  627.      number  of operations can be specified either as macros
  628.      or as function calls.   The  function  calls  generally
  629.      perform  more error checking, and should be used during
  630.      initial development.  Using macros, on the other  hand,
  631.      can  improve  performance dramatically.  At some future
  632.      date we hope to make available both reference  counting
  633.      and garbage collection versions of the memory manager.
  634.  
  635. nnnnaaaammmmeeeessss....cccc
  636.      The only data structures used internally in the  Little
  637.      Smalltalk  system  are  arrays and name tables.  A name
  638.      table is simply an  instance  of  class  DDDDiiiiccccttttiiiioooonnnnaaaarrrryyyy  in
  639.      which keys are symbols.  Name tables are used to imple-
  640.      ment the dictionary of globally accessible values, ssssyyyymmmm----
  641.      bbbboooollllssss, and to implement method tables.  This module pro-
  642.      vides support for reading from name tables.
  643.  
  644. nnnneeeewwwwssss....cccc
  645.      This module contains  several  small  utility  routines
  646.      which create new instances of various standard classes.
  647.  
  648. iiiinnnntttteeeerrrrpppp....cccc
  649.      This module implements the actual bytecode interpreter.
  650.      It  is  the  heart  of the system, where most execution
  651.      time is spent.
  652.  
  653. pppprrrriiiimmmmiiiittttiiiivvvveeee....cccc
  654.      This module contains  the  code  that  is  executed  to
  655.  
  656.  
  657.  
  658.                         July 7, 1994
  659.  
  660.  
  661.  
  662.  
  663.  
  664.                            - 11 -
  665.  
  666.  
  667.      perform primitive operations.  Only the standard primi-
  668.      tives (see the section on primitives)  are  implemented
  669.      in  this  module.   File primitives and system specific
  670.      primitives are implemented in another module,  such  as
  671.      unixio.c for the Unix system and macio.c for the Macin-
  672.      tosh version.
  673.  
  674. uuuunnnniiiixxxxiiiioooo....cccc,,,,ffffiiiilllleeeeiiiinnnn....cccc
  675.      These two modules contains I/O routines.
  676.  
  677. lllleeeexxxx....cccc,,,,ppppaaaarrrrsssseeeerrrr....cccc
  678.      The files lex.c and parser.c are the  lexical  analyzer
  679.      and  parser,  respectively,  for  compiling the textual
  680.      representation  of  methods  into  bytecodes.   In  the
  681.      current   version   parsing  is  done  using  a  simple
  682.      (although large) recursive descent parser.
  683.  
  684. sssstttt....cccc
  685.      The file st.c is the front end for the Unix version  of
  686.      Little  Smalltalk.   On  the  Macintosh  version  it is
  687.      replaced by the pair of files macmain.c and macevent.c.
  688.  
  689. iiiinnnniiiittttiiiiaaaallll....cccc
  690.      This module contains code that reads the module form of
  691.      Smalltalk  code, creating an object image.  This is not
  692.      part of the Smalltalk bytecode interpreter, but is used
  693.      in  building  the  initial  object image (see next sec-
  694.      tion).
  695.  
  696.      There are description files ( .h files, in  standard  C
  697. convention)  which  describe  many  of the modules described
  698. above.  In addition, there is a very important  file  called
  699. env.h   (for  ``environment'').   This  file  describes  the
  700. characteristics of the operating system/machine you are run-
  701. ning  on.   The  general  structure of this file is that the
  702. user provides one definition for their system, for example
  703.  
  704.         # define LIGHTC
  705.  
  706. to indicate using the Lightspeed C compiler  on  the  macin-
  707. tosh,  for example.  Following this are block of code which,
  708. based on this one definition, define other terms  represent-
  709. ing the specific attributes of this system.  Where ever pos-
  710. sible new code should  be  surrounded  by  _i_f_d_e_f  directives
  711. based  on  words  defined  in this manner.  The next section
  712. describes this in more detail.
  713.  
  714. _5._2.  _D_e_f_i_n_i_n_g _S_y_s_t_e_m _C_h_a_r_a_c_t_e_r_i_s_t_i_c_s
  715.  
  716.      There are many ways in which  compilers  and  operating
  717. systems  differ  from each other.  A fair amount of work has
  718. been expanded in making sure the software  will  operate  on
  719. most  machines, which requires that different code fragments
  720. be used on different  systems.   In  large  part  these  are
  721.  
  722.  
  723.  
  724.                         July 7, 1994
  725.  
  726.  
  727.  
  728.  
  729.  
  730.                            - 12 -
  731.  
  732.  
  733. controlled  by  a  single ``meta-define'' in the file env.h.
  734. Setting this one value then causes the expansion of  another
  735. code segment, which then defines many more options.
  736.  
  737.      In the event  that  you  are  attempting  to  port  the
  738. software  to  a system that has not previously been defined,
  739. you will need to decide which set of options to enable.  The
  740. next two sections contain information you may need in making
  741. this determination.
  742.  
  743. _D_e_f_i_n_e _O_p_t_i_o_n_s
  744.  
  745.      Many options are specified merely by giving or not giv-
  746. ing  a  DEFINE  statement  in the file env.h.  The following
  747. table presents the meaning for each of these values:
  748.  
  749. AAAALLLLLLLLOOOOCCCC
  750.      Defined If there is  an  include  file  called  alloc.h
  751.      which defines calloc, malloc, and the like.
  752.  
  753. BBBBIIIINNNNRRRREEEEAAAADDDDWWWWRRRRIIIITTTTEEEE
  754.      Defined if the fopen  specification  for  binary  files
  755.      must  include  the  "b" modifier.  This is true on many
  756.      MS-DOS inspired systems.
  757.  
  758. NNNNOOOOEEEENNNNUUUUMMMMSSSS
  759.      Defined if enumerated datatypes are not supported.   If
  760.      defined, these will be replaced by #define constants.
  761.  
  762. NNNNOOOOTTTTYYYYPPPPEEEEDDDDEEEEFFFF
  763.      Defined if the typedef construct is not supported.   If
  764.      defined, these will be replaced by #define constructs.
  765.  
  766. NNNNOOOOVVVVOOOOIIIIDDDD
  767.      Defined if the void  keyword  is  not  recognized.   If
  768.      defined,  expect _l_i_n_t to complain a lot about functions
  769.      returning  values  which  are  sometimes  (or   always)
  770.      ignored.
  771.  
  772. SSSSIIIIGGGGNNNNAAAALLLLSSSS
  773.      Used  if  _b_o_t_h  the   <signals.h>   package   and   the
  774.      <longjmp.h>  package  are available, and if the routine
  775.      used to set signals is signal.  Incompatible with SSSSSSSSIIIIGGGG----
  776.      NNNNAAAALLLLSSSS.
  777.  
  778. SSSSSSSSIIIIGGGGNNNNAAAALLLLSSSS
  779.      Used  if  _b_o_t_h  the   <signals.h>   package   and   the
  780.      <longjmp.h>  package  are available, and if the routine
  781.      used to set signals is ssignal.  Incompatible with SSSSIIIIGGGG----
  782.      NNNNAAAALLLLSSSS.
  783.  
  784. SSSSTTTTRRRRIIIINNNNGGGG
  785.      Used if the string functions (strcpy,  strcat  and  the
  786.      like)   are   found  in  <string.h>.   This  switch  is
  787.  
  788.  
  789.  
  790.                         July 7, 1994
  791.  
  792.  
  793.  
  794.  
  795.  
  796.                            - 13 -
  797.  
  798.  
  799.      incompatible with SSSSTTTTRRRRIIIINNNNGGGGSSSS.
  800.  
  801. SSSSTTTTRRRRIIIINNNNGGGGSSSS
  802.      Used if the string functions (strcpy,  strcat  and  the
  803.      like)  are found in <strings.h>.  This switch is incom-
  804.      patible with SSSSTTTTRRRRIIIINNNNGGGG.
  805.  
  806. In addition, several routines can optionally be replaced  by
  807. macros  for  greater  efficiency.  See the file memory.h for
  808. more information.
  809.  
  810. _5._3.  _B_u_i_l_d_i_n_g _a_n _I_n_i_t_i_a_l _O_b_j_e_c_t _I_m_a_g_e
  811.  
  812.      There are two programs used  in  the  Little  Smalltalk
  813. system.   The first is the actual bytecode interpreter.  The
  814. use of this program is described in detail  in  other  docu-
  815. ments   (see   ``Exploring   and  Creating'').   The  Little
  816. Smalltalk system requires, to start, a snapshot  representa-
  817. tion  of  memory.   This snapshot is called an object image,
  818. and the purpose of the second program,  the  initial  object
  819. image  maker,  is  to construct an initial object image.  In
  820. theory, the this program need only be run once, by the  sys-
  821. tem  administrator,  and thereafter all users can access the
  822. same standard object image.
  823.  
  824.      The object image format is binary.  However, since  the
  825. format  for binary files will undoubtedly differ from system
  826. to system, the methods which will go into the initial  image
  827. are   distributed  in  textual  form,  called  module  form.
  828. Several modules are combined to create an object image.  The
  829. following  describes the modules distributed on the standard
  830. tape, in the order they should be processed, and their  pur-
  831. poses.
  832.  
  833. bbbbaaaassssiiiicccc....sssstttt
  834.      This module contains  the  basic  classes  and  methods
  835.      which should be common to all implementations of Little
  836.      Smalltalk.
  837.  
  838. mmmmaaaagggg....sssstttt
  839.      This module contains methods for those  objects  having
  840.      magnitude, which are the basic subclasses of Magnitude.
  841.  
  842. ccccoooolllllllleeeecccctttt....sssstttt
  843.      This module contains methods for the  collection  subc-
  844.      lasses.
  845.  
  846. ffffiiiilllleeee....sssstttt
  847.      This module contains the classes and methods  used  for
  848.      file  operations.   Although all implementations should
  849.      try to support these operations, it may not  always  be
  850.      possible on all systems.
  851.  
  852. uuuunnnniiiixxxx....sssstttt
  853.  
  854.  
  855.  
  856.                         July 7, 1994
  857.  
  858.  
  859.  
  860.  
  861.  
  862.                            - 14 -
  863.  
  864.  
  865.      This module contains unix -  specific  commands,  which
  866.      may  differ  from those used under other operating sys-
  867.      tems.
  868.  
  869. mmmmuuuulllltttt....sssstttt
  870.      This  module  contains  code  for  the  multiprocessing
  871.      scheduler.
  872.  
  873. iiiinnnniiiitttt....sssstttt
  874.      This module contains code which is  run  to  initialize
  875.      the  initial  object  image.   These  methods disappear
  876.      after they have been executed.  (or should; they  don't
  877.      really yet).
  878.  
  879. tttteeeesssstttt....sssstttt
  880.      This file contains various test cases.
  881.  
  882. _5._4.  _O_b_j_e_c_t _M_e_m_o_r_y
  883.  
  884.      There are several datatypes, not directly supported  by
  885. C,  that are used in the Little Smalltalk system.  The first
  886. of these is the datatype byte.   A  byte  is  an  eight  bit
  887. unsigned  (hence  positive)  quantity.   On many systems the
  888. appropriate datatype is unsigned char, however on other sys-
  889. tems  this declaration is not recognized and other forms may
  890. be required.  To aid in coverting  to  and  from  bytes  the
  891. macro  byteToInt() is used, which converts a byte value into
  892. an integer.  In addition, the routines byteAt and  byteAtPut
  893. are used to get and put bytes from byte strings.
  894.  
  895.      The other datatype is that  used  to  represent  object
  896. points.   On  most machines in which a short is 16 bits, the
  897. datatype short should suffice.  Much more information on the
  898. memory module can be found in the file memory.h.
  899.  
  900. _5._5.  _T_h_e _B_o_t_t_o_m _E_n_d
  901.  
  902.      The opposite extreme from the front end are those  mes-
  903. sages  that  originate  within the Smalltalk bytecode inter-
  904. preter and must be communicated to the user.  We can  divide
  905. these  into two different classes of communications, editing
  906. operations and input/output operations.  The following  sec-
  907. tions will treat each of these individually.
  908.  
  909. _5._5._1.  _E_d_i_t_i_n_g
  910.  
  911.      We have already mentioned that commands entered by  the
  912. user  are  converted  into  methods,  and passed to the same
  913. method compiler as all other methods.  Before the  user  can
  914. create  a  new method, however, there must be some mechanism
  915. for allowing the user to enter the method.
  916.  
  917.      One approach would be to read the method from the stan-
  918. dard  input,  just  as  commands  are  read.   While easy to
  919.  
  920.  
  921.  
  922.                         July 7, 1994
  923.  
  924.  
  925.  
  926.  
  927.  
  928.                            - 15 -
  929.  
  930.  
  931. implement, this approach would  soon  prove  unsatisfactory,
  932. since  for  every  error  the user would need to reenter the
  933. entire method.  So some form of update, or editing, must  be
  934. provided.   Again,  the  Unix  interface  and  the Macintosh
  935. interface solve this problem in radically different ways.
  936.  
  937. _5._5._1._1.  _E_d_i_t_i_n_g _U_n_d_e_r _U_n_i_x
  938.  
  939.      A request to edit or add a method is given  by  sending
  940. either the message aaaaddddddddMMMMeeeetttthhhhoooodddd or eeeeddddiiiittttMMMMeeeetttthhhhoooodddd:::: to a class.  The
  941. methods for these messages in turn call upon a  common  rou-
  942. tine to perform the actual editing work.
  943.  
  944.         aaaaddddddddMMMMeeeetttthhhhoooodddd
  945.                 self doEdit: ''
  946.  
  947.         eeeeddddiiiittttMMMMeeeetttthhhhoooodddd:::: name
  948.                 self doEdit: ( methods at: name
  949.                         ifAbsent: [ 'no such method ' print. |^ nil ] ) text
  950.  
  951.         ddddooooEEEEddddiiiitttt:::: startingText            | text |
  952.                 text <- startingText.
  953.                 [ text <- text edit.
  954.                   (self addMethodText: text)
  955.                         ifTrue: [ false ]
  956.                         ifFalse: [ smalltalk inquire: 'edit again (yn) ? ' ]
  957.                                 ] whileTrue
  958.  
  959.  
  960.      The Unix and MS-DOS versions of the  system  provide  a
  961. method  eeeeddddiiiitttt  as  part of the functionality of class SSSSttttrrrriiiinnnngggg.
  962. When eeeeddddiiiitttt is passed to a string, an editing  environment  is
  963. established.   The  user  performs  editing  tasks  in  that
  964. environment, and then exits the editing environment.   Under
  965. Unix,  this functionality is implemented using the file sys-
  966. tem.
  967.  
  968.         eeeeddddiiiitttt    | file text |
  969.                 file <- File new;
  970.                         scratchFile;
  971.                         open: 'w';
  972.                         print: self;
  973.                         close.
  974.                 (editor, ' ', file name) unixCommand.
  975.                 file open: 'r'.
  976.                 text <- file asString.
  977.                 file close; delete.
  978.                 |^ text
  979.  
  980.  
  981.      A file is created, and the contents of the string writ-
  982. ten to it.  Then a standard Unix editor (given by the global
  983. variabled eeeeddddiiiittttoooorrrr) is invoked to process the file.  After the
  984. user  exits  the  editor,  the contents of the file are read
  985.  
  986.  
  987.  
  988.                         July 7, 1994
  989.  
  990.  
  991.  
  992.  
  993.  
  994.                            - 16 -
  995.  
  996.  
  997. back as a string, the file is closed and  deleted,  and  the
  998. string  returned.  The command uuuunnnniiiixxxxCCCCoooommmmmmmmaaaannnndddd is implemented as
  999. a primitive, which invokes the system() system call:
  1000.  
  1001.         uuuunnnniiiixxxxCCCCoooommmmmmmmaaaannnndddd
  1002.                 |^ <150 self>
  1003.  
  1004.  
  1005.      Although the eeeeddddiiiitttt message is used by  the  system  only
  1006. for  editing  methods,  it is general enough for any editing
  1007. application and there is no reason why the user  cannot  use
  1008. it  for other purposes.  By the way, the uuuunnnniiiixxxxCCCCoooommmmmmmmaaaannnndddd message
  1009. is also used to implement file deletes.
  1010.  
  1011.         ddddeeeelllleeeetttteeee
  1012.                 ('rm ', name) unixCommand
  1013.  
  1014.  
  1015.      On MS-Dos systems this command  should  be  changed  to
  1016. DDDDEEEELLLL.
  1017.  
  1018.  
  1019. _5._5._1._2.  _E_d_i_t_i_n_g _o_n _t_h_e _M_a_c_i_n_t_o_s_h
  1020.  
  1021.      The  Macintosh  version  takes  an  entirely  different
  1022. approach  to the editing of methods. As in the Unix version,
  1023. the user requests editing using the commands eeeeddddiiiittttMMMMeeeetttthhhhoooodddd:::: and
  1024. aaaaddddddddNNNNeeeewwwwMMMMeeeetttthhhhoooodddd.   And,  as  in the Unix version, these in turn
  1025. invoke a common method.
  1026.  
  1027.         aaaaddddddddMMMMeeeetttthhhhoooodddd
  1028.                 self doEdit: ( self printString, ': new method') text: ''
  1029.  
  1030.  
  1031.         eeeeddddiiiittttMMMMeeeetttthhhhoooodddd:::: name
  1032.                 self doEdit: (self printString, ': ', name)
  1033.                         text: (methods at: name
  1034.                                         ifAbsent: ['no such method' print. |^ nil ]) text
  1035.  
  1036.  
  1037.      Here, however, when the user asks to edit a  method,  a
  1038. new _e_d_i_t_i_n_g _w_i_n_d_o_w is created.
  1039.  
  1040.         ddddooooEEEEddddiiiitttt: title tttteeeexxxxtttt: text        | w |
  1041.                 w <- EditWindow new;
  1042.                         acceptTask: [ self addMethodText: w getString ] ;
  1043.                         title: title; create; print: text; showWindow
  1044.  
  1045.  
  1046.      The edit window is initialized with the current text of
  1047. the  method.   Thereafter,  the user can edit this using the
  1048. standard Macintosh cut and paste conventions.  The user sig-
  1049. nifies  they  are  satisfied with the result by entering the
  1050. command aaaacccccccceeeepppptttt, which causes the _a_c_c_e_p_t_T_a_s_k:   block  to  be
  1051.  
  1052.  
  1053.  
  1054.                         July 7, 1994
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.                            - 17 -
  1061.  
  1062.  
  1063. executed.   This block gets the text of the window (given by
  1064. the message ggggeeeettttSSSSttttrrrriiiinnnngggg)  and  passes  it  to  aaaaddddddddMMMMeeeetttthhhhooooddddTTTTeeeexxxxtttt::::,
  1065. which  compiles  the method, entering it in the method table
  1066. if there are no errors.
  1067.  
  1068. _5._5._2.  _I_n_p_u_t/_O_u_t_p_u_t _c_o_m_m_a_n_d_s
  1069.  
  1070.      Under the Unix system all input/output  operations  are
  1071. performed  using  the  file  system and the global variables
  1072. stdin, stdout and stderr.  Thus the message eeeerrrrrrrroooorrrr::::, in class
  1073. SSSSmmmmaaaallllllllttttaaaallllkkkk,  merely  prints  a  message to the standard error
  1074. output and exits.
  1075.  
  1076.      The macintosh version, although  using  the  same  file
  1077. routines,  does  not  have  any  notion of standard input or
  1078. standard output.  Thus error messages (such as from  eeeerrrrrrrroooorrrr::::)
  1079. result in alert boxes being displayed.
  1080.  
  1081.      There are also error messages that come from inside the
  1082. Smalltalk  interpreter  itself.   These are of two types, as
  1083. follows:
  1084.  
  1085. 1.   System errors.  These are  all  funnelled  through  the
  1086.      routine   sysError().   System  errors  are  caused  by
  1087.      dramatically wrong  conditions,  and  should  generally
  1088.      cause  the  system  to abort after printing the message
  1089.      passed as argument to sysError().
  1090.  
  1091. 2.   Compiler errors.  As we noted earlier, the method  com-
  1092.      piler  is  used  to parse expressions typed directly at
  1093.      the keyboard, so these message can also arise  in  that
  1094.      manner.   These  are all funnelled through the routines
  1095.      compilError()  and  compilWarn().  These  should  print
  1096.      their  arguments (two strings), in an appropriate loca-
  1097.      tion on the users screen.  Execution continues normally
  1098.      after call.
  1099.  
  1100. _5._6.  _P_r_i_m_i_t_i_v_e_s
  1101.  
  1102.      Primitives are the means whereby actions that cannot be
  1103. described  directed  in Smalltalk are performed.  In version
  1104. three of the Little Smalltalk system, primitives are divided
  1105. into three broad categories.
  1106.  
  1107. 1.   Primitives numbered less than 119 are all standard, and
  1108.      both the meaning and the implementation of these should
  1109.      be the same in all implementations of Little Smalltalk.
  1110.      These   are   largely  just  simple  actions,  such  as
  1111.      mathematical operations.
  1112.  
  1113. 2.   Primitives  numbered  120-139  are  reserved  for  file
  1114.      operations.   Although  the meaning of these primitives
  1115.      should  remain  constant  across  all  implementations,
  1116.      their implementation may differ.
  1117.  
  1118.  
  1119.  
  1120.                         July 7, 1994
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.                            - 18 -
  1127.  
  1128.  
  1129. 3.   Primitives number 150-255 are  entirely  implementation
  1130.      specific,  and  thus  in  porting  to  a new system the
  1131.      implementor is free to give these any meaning  desired.
  1132.      For  example  under  the  Unix  version  there  is,  at
  1133.      present, only one such primitive, used to  perform  the
  1134.      system()  call.   On the other hand, the Macintosh ver-
  1135.      sion has dozens of primitives used to implement  graph-
  1136.      ics  functions,  windowing  function,  editing  and the
  1137.      like.
  1138.  
  1139. _6.  _D_i_s_t_r_i_b_u_t_i_o_n _o_f _N_e_w _I_m_p_l_e_m_e_n_t_a_t_i_o_n_s
  1140.  
  1141.      The Little Smalltalk system is entirely public  domain,
  1142. and  any user is free to redistribute it in any fashion they
  1143. wish.  As a service to  the  Smalltalk  community,  I  would
  1144. appreciate it if new implementors could send me a listing of
  1145. changes they make, so that they can be incorporated into one
  1146. standard  distribution.   Correspondence should be addressed
  1147. to:
  1148.  
  1149.         Tim Budd
  1150.         Department of Computer Science
  1151.         Oregon State University
  1152.         Corvallis, Oregon
  1153.         97331 USA
  1154.  
  1155.  
  1156.      Copies of the most  recent  distribution  can  also  be
  1157. obtained by writing to this address.  In mailing out distri-
  1158. butions, there is a  small  charge  for  media  and  mailing
  1159. costs.
  1160.  
  1161. _7.  _N_e_w _F_e_a_t_u_r_e_s
  1162.  
  1163.      If you type ``smalltalk echo'' all input will be echoed
  1164. (tty  interface  only).   Typing smalltalk echo again undoes
  1165. this.  This is useful for reading from scripts.
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.                         July 7, 1994
  1187.  
  1188.  
  1189.