source: project/wiki/meroon @ 7165

Last change on this file since 7165 was 7165, checked in by Jim Ursetto, 12 years ago

Changes applied for zbigniew (67.167.53.235) through svnwiki:

meroon: mention requirement for -X meroon in doc

File size: 16.4 KB
Line 
1[[toc:]]
2[[tags: egg]]
3
4== Introduction
5
6'''meroon''' is a port of Christian Queinnecs Meroon object system.
7
8== Author
9
10Christian Queinnec (<Christian.Queinnec@polytechnique.fr> or <Christian.Queinnec@INRIA.fr>),
11ported to Chicken by felix.
12
13== History
14
15The Meroon version is Meroon V3 Noel+2 $Revision: 1.1 $
16
17    * 1.9 Generates an .exports file and install documentation. Fixed bug in meroon.scm [Thanks to Stu Glaser]
18    * 1.8 The code is now compiled with -no-trace instead of -d0
19    * 1.7 check-class signals error when call with a non-object [Thanks to Brad Lucier]
20    * 1.6 meroon-error signals a (exn meroon) condition
21    * 1.5 Works now in conjunction with the highlevel macro system (syntax-case)
22    * 1.4 Adapted to new setup scheme
23    * 1.3 Setter syntax is now ...-set! instead of set-...!; allows now native keywords to be used
24    * 1.2 Removed separate library, everything is now included by default
25    * 1.1 Loads (meroon library) automatically, when interpreted or at compile time
26    * 1.0
27
28== Usage
29
30 (require-extension meroon)
31
32When compiling a file that uses meroon, you should also add the {{-X meroon}} or {{-extend meroon}} option to {{csc}}:
33
34 csc -X meroon file.scm
35
36== Requirements
37
38* format
39
40== Documentation
41
42What follows is (a slighlty reformated version of) the official manual page for Meroon. Here a list of things that apply to this particular port:
43
44* This version of Meroon is not configured for support of DSSSL style extended argument lists (i.e. #!optional, #!key, etc...)
45* Setters for instance slots are named CLASSNAME-SLOTNAME-set! instead of set-CLASSNAME-SLOTNAME! (as in the original Meroon)
46* Keywords should be given according to the current keyword style (which defaults to suffix, i.e. "...:").
47* Even though Meroon can be used with the high-level (syntax-case) macro system, it doesn't play well with it's module system, since define-class forms do not expand into pure definitions.
48
49
50== Description
51
52MeroonV3 is an object system written in Scheme that works under
53Chicken, Bigloo, Elk, Gambit, Guile, MacScheme, MIT-Scheme, OScheme, PC
54Scheme, PCS/geneva, Scheme->C, SCM and vscm interpreters. It
55also runs faster when compiled with Bigloo, Gambit and
56Scheme->C, see below.
57
58The  MeroonV3  object system was originally invented for a
59book (in French (InterEditions) and English (Cambridge  U.
60Press)) to describe implementations of Lisp and Scheme. It
61was designed to have a pedagogical, portable but efficient
62implementation,  to support separate compilation yet to be
63powerful enough to unify all the data types of Scheme even
64vectors and strings without restriction of inheritance. It
65thus offers the concept of classes with regular or indexed
66fields,  a  somewhat static initialization protocol, meta­
67classes with code-generation capabilities,  generic  func­
68tions with multimethods among other features.
69
70The  latest version of MeroonV3 can be retrieved by anony­
71mous ftp from ftp.inria.fr (IP number  192.93.2.54)  under
72subdirectory    INRIA/Projects/icsla/Programs.   Questions
73about MeroonV3 (or older versions: MeroonV2 and  Meroonet)
74should be directed towards the mailing list:
75<meroon-info@cornas.inria.fr>
76Ask  to be enlisted in that mailing list by sending a mes­
77sage to:
78<meroon-request@cornas.inria.fr>
79
80
81== Quick Reference Card
82
83MeroonV3 basically offers three macros to define  classes,
84generic functions and methods for them, it also offers one
85form to create instances. Generic functions support multi­
86methods.  By default, many accompanying functions are cre­
87ated when definining a class. To not bother those who know
88what  objects  mean,  the  next  section  tells how to use
89Meroon by example.
90
91
92== Meroon By Example
93
94Define class Point with fields x and y, Object is the root class.
95
96 (define-class Point Object (x y))
97
98recognizer and maker at work.
99
100 (Point? (make-Point 33 22))  ; -> #t
101
102Define an heir to Point with an additional indexed field.
103
104 (define-class NamedPoint Point
105    ((* name :immutable)) )
106
107selector and handy instantiation (with keywords) at work.
108
109 (Point-x (instantiate NamedPoint
110           :name 'joe 'jill
111           :y 33 :x 222 ))    ; -> 222
112
113Define another class with an explicit field initializer (a thunk).
114
115 (define-class ColoredNamedPoint NamedPoint
116   ((= color :initializer (lambda () 'pink))) )
117 
118 (ColoredNamedPoint-color
119  (instantiate ColoredNamedPoint :name 'joe 'jill :y 33 :x 222) )  ; -> pink
120
121maker also exist for indexed fields as well as modifiers. Field x can
122be retrieved as Point-x or ColoredNamedPoint-x.
123
124 (let ((pt (make-ColoredNamedPoint 11 22    2 'joe 'jack   'red)))
125   (set-NamedPoint-x! pt '555)
126   (ColoredNamedPoint-x pt) )         ; -> 555
127
128Define a generic function with a dotted variable.
129
130 (define-generic (foo a (b) . stream)
131   (apply display "default" stream) )
132
133Add a (congruent) method. It is possible to inquire the length of the
134indexed field. It is also possible to call the next method.
135
136 (define-method (foo x (np NamedPoint) . str)
137   (apply display (NamedPoint-name-length np) str)
138   (call-next-method) )
139 
140 (foo (make-ColoredNamedPoint 11 22    2 'joe 'jack   'red)
141      (instantiate Point :y 2 :x 3) )      ; prints "default"
142
143Use of the predefined generic function clone.
144
145 (foo (clone (make-Point 3 2))
146      (instantiate ColoredNamedPoint
147        :color 'red :name 'joe 'jack :x 11 :y 22 ) )  ; prints "2" then "default"
148
149Define a generic function with multimethods and restricts methods to
150be added to subclasses of Point * Point.
151
152 (define-generic (dist (o1 Point) (o2 Point)))
153 
154 (define-method (dist (o1 NamedPoint) (o2 ColoredNamedPoint))
155    (eq? (ColoredPoint-color o1) (ColoredPoint-color o2)) )
156
157
158== Defining Classes
159
160The define-class macro defines a new class named <name-of-
161the-class>,    subclass    of   <name-of-the-super-class>.
162Instances of this new class will contain  all  the  fields
163specified  by  the  super-class  <name-of-the-super-class>
164plus the proper fields, those that appear in  the  define-
165class  form.  A  field specified as <name-of-a-Mono-Field>
166can  be  equivalently  specified  as  (=  <name-of-a-Mono-
167Field>).  A Mono-Field is qualified with an equal sign and
168only holds a  single  value.   A  Poly-Field  (or  indexed
169field)  is  qualified  by a leading star and holds as many
170values as specified when allocating  instances.  Different
171instances  can  have a different number of values in their
172Poly-Fields.  Fields can be mutable or immutable (no modi­
173fiers  are  then  created  for  them); initializers can be
174specified.  It is also possible to mention that the  field
175may  be  uninitialized: every allocation will therefore be
176checked to initialize this field.  The  metaclass  can  be
177imposed, by default it is the MeroonV2-Class.
178
179 (define-class <name-of-the-class> <name-of-the-super-class>
180        ( <name-of-a-Mono-Field>                        |
181          (= <name-of-a-Mono-Field>
182             [ :immutable | :mutable ] [ :maybe-uninitialized ]
183             [ :initializer (lambda () value) ] )       |
184          (* <name-of-a-Poly-Field>
185             [ :immutable | :mutable ] [ :maybe-uninitialized ]
186             [ :initializer (lambda (index) value) ] )
187          ... )
188     [ :metaclass <name-of-the-meta-class> ]
189     [ :immutable ] )
190
191When  a  class  is defined and if it has the default meta­
192class then many accompanying functions are also defined: a
193predicate,  field  readers,  field  writers, indexed field
194length readers as well as a general maker. The  signatures
195of these functions follow:
196
197 (<class-name>? value)
198 
199 (make-<class-name> <value-for-a-mono-field>
200                  | <length> <<length>-values-for-a-poly-field>
201                  ... )
202 
203 (<class-name>-<mono-field-name> object)
204 
205 (<class-name>-<poly-field-name> object index)
206 
207 (set-<class-name>-<mono-field-name>! object value)
208 
209 (set-<class-name>-<poly-field-name>! object index value)
210 
211 (<class-name>-<poly-field-name>-length object)
212
213The  class  object  is  itself an indirect instance of the
214Class metaclass. It can be obtained via the  global  vari­
215able <class-name>-class.
216
217A  generic function, named -><class-name>, is also defined
218to hold coercion methods converting values to instances of
219<class-name>.
220
221
222== Defining Generic Functions
223
224The  define-generic  form defines a generic function named
225<name-of-the-generic-function>, with a list  of  variables
226defined  by  <description-of-the-variables>.  If no appro­
227priate method  is  found  when  the  generic  function  is
228invoked,  the  <optional-default-method>  is invoked or an
229anomaly is provoked.   The  <description-of-the-variables>
230is  similar  to  the  list  of variables of regular lambda
231forms except that  discriminating  variables  appear  sur­
232rounded  by  parentheses.  There can be more than one dis­
233criminating variable.
234
235 (define-generic ( <name-of-the-generic-function>
236                   . <description-of-the-variables> )
237       [ <optional-default-method> ]   )
238 
239 <description-of-the-variables>
240     ::= ( <variable-name>
241           . <description-of-the-variables> )
242      |  ( ( <variable-name> [<maximal-class-allowed>] )
243           . <description-of-the-variables> )
244      |  <variable-name>
245
246The define-method form defines  a  method  on  an  already
247existing  generic  function. The <description-of-the-vari­
248ables> must be congruent to that of the  generic  function
249and  any  discriminating  variable  must specify a <class-
250name> compatible with the <maximal-class-allowed> if  pre­
251sent in the generic function. The <body-of-the-method> may
252use the (call-next-method) form to invoke the method  that
253should have been invoked if the present one was not there.
254It is also possible to use the (next-method?)  predicative
255form to determine if there is a method that can be invoked
256by (call-next-method).
257
258 (define-method ( <name-of-the-generic-function>
259                  . <description-of-the-variables> )
260       <body-of-the-method> )
261 
262 <description-of-the-variables>
263     ::= ( <variable-name>
264           . <description-of-the-variables> )
265      |  ( ( <variable-name> <class-name> )
266           . <description-of-the-variables> )
267      |  <variable-name>
268
269A restriction on multimethods is that it is  forbidden  to
270define  a method that would bring ambiguity. This may only
271occur when defining a multimethod on classes A' x B when a
272multimethod  is already defined on A x B' and A' is a sub­
273class of A while B' is a subclass  of  B.  The  method  to
274apply on A' x B' would be ambiguous.
275
276
277== Allocating Objects
278
279To  ease  the  allocation  of objects, a macro exists that
280provides keywords to define fields in  whatever  order  is
281felt  convenient.  Any  unspecified field gets its initial
282value from its corresponding initializer if  mentioned  in
283the  class  definition  otherwise the field is left unini­
284tialized (that is only possible if  the  :maybe-uninitial­
285ized field option is specified for that field in the class
286definition) and the  associated  reader  will  provoke  an
287anomaly if trying to read such an uninitialized field. The
288initialize!  function is eventually invoked on the result­
289ing object.
290
291 (instantiate <class-name>
292     :<mono-field-name>        value
293     :<poly-field-name>        values ...
294     :<poly-field-name>-length natural
295     ... )
296
297Some other macros exist to ease the creation of instances.
298The duplicate macro allows you  to  create  a  new  object
299based  on  the differences to bring to an original object.
300The co-instantiate macro allows you to instantiate  multi­
301ple  objects  at  the same time, these objects may contain
302mutual (or recursive, or cyclic) references.
303
304
305== Predefined Generic Functions
306
307The following general utility functions  exist  to  access
308fields.   A  field can be read if it has a value.  A field
309can be initialized if it has no value.   A  field  can  be
310inspected  to  know  if it is initialized.  A field can be
311modified if associated to the :mutable  field  option  or,
312not associated to the :immutable field option (by default,
313any field is mutable). In any other cases, an  anomaly  is
314signalled.
315
316 (field-value object mono-field)              -> value
317 (field-value object poly-field index)        -> value
318 
319 (set-field-value! object value mono-field)
320 (set-field-value! object value poly-field index)
321 
322 (initialize-field-value! object value mono-field)
323 (initialize-field-value! object value poly-field index)
324 
325 (field-length object poly-field)             -> length
326 
327 (field-defined? object mono-field)           -> boolean
328 (field-defined? object poly-field index)     -> boolean
329
330The  generic  function clone returns a shallow copy of any
331object.  The generic function initialize!  is  invoked  on
332every  freshly  built  instance. The generic function show
333displays objects. These functions are  there  to  be  cus­
334tomized.
335
336 (clone object)          -> object
337 (initialize! object)    -> object
338 (show object [stream])
339
340There  exist  also  some  predefined coercers like ->Class
341that converts names (symbols) into classes, ->Generic that
342converts names into generic instances.
343
344
345== Predefined Classes
346
347These  are  some  of  the  predefined  classes  with their
348fields. The accompanying functions exist. You can read all
349these  fields  but  it is dangerous to modify them even if
350they are mutable!
351
352 (define-class Object #f ())
353 (define-class Class Object
354   (name number fields super-number subclass-numbers
355         allocator immutable? min-son max-son (* super) ) )
356 (define-class Handy-Class Class ())
357 (define-class MeroonV2-Class Handy-Class ())
358 (define-class Generic Object
359   (behavior name default variables dispatcher top-classes) )
360 (define-class Generic-1 Generic ())
361 (define-class Generic-N Generic ())
362 (define-class Field Object
363   (immutable? name class-number initialized? initializer (* path)) )
364 (define-class Mono-Field Field ())
365 (define-class Poly-Field Field ())
366 (define-class Anomaly Object (category operator message (* hint)))
367
368
369== Library
370
371The  class  of  any  object   can   be   retrieved   using
372object->class.   An object can be tested for class-member­
373ship with is-a?. Classes can be related through subclass?.
374A  generic comparator named egal allows to compare any two
375objects (even circular) to determine if they  are  equiva­
376lent.
377
378 (object->class object)     -> class
379 (is-a? value class)        -> boolean
380 (subclass? class class  )  -> boolean
381 (egal object object)       -> boolean
382
383
384== Debugging
385
386You  can  trace generic functions or inquire your state or
387any object with the following functions:
388
389 (show-generic-trace <generic-name> ...)
390
391without arguments untrace all traced generic functions
392
393 (show-generic-untrace [<generic-name> ...])
394 
395 (show-meroon)                  ; display which Meroon you are using
396 (show-hierarchy [class])       ; show [part of] the tree of classes
397 (show-generic [generic])       ; show methods on [some] generic functions
398 
399 (unveil object [stream])    ; show all the details of an object (even circular)
400
401
402== Compiling with Bigloo
403
404You can compile  modules  using  MeroonV3  features  under
405Bigloo (1.6 and above) very conveniently. The installation
406of MeroonV3 creates a new compiler called  bigloo++.  When
407this compiler compiles a module whose name ends by the oon
408extension then bigloo++ automatically sets up the relevant
409details to compile it. Suppose you have the following mod­
410ule:
411
412 (module test (main start))
413 (define-class Point Object (x y))
414 (define-generic (magnitude (o)))
415 (define-method (magnitude (o Point))
416   (+ (Point-x o) (Point-y o)) )
417 (define (start args)
418   (show (magnitude (make-Point 11 22)))
419   (newline) )
420
421Then you can simply compile it with:
422
423 bigloo++ file.oon ...
424
425But if you prefer another name for your files you have  to
426say  explicitly  that  you  want  to use MeroonV3. In this
427case, just say:
428
429bigloo++ -extend meroon file.scm ...
430
431The bigloo++ compiler can  also  be  called  with  the  -i
432option  as  a  regular interpreter, it then offers you all
433features of MeroonV3.
434
435
436== Interpreting with SCI
437
438You can interpret programs  containing  MeroonV3  features
439under sci very conveniently.  The installation of MeroonV3
440creates a new interpreter called  sci++  that  contains  a
441fully compiled MeroonV3 in it.
442
443
444== More Information
445
446Additional documentation, examples and tricks can be found
447in files:
448
449; Doc/MeroonV3.{dvi,ps} : The reference manual,
450; Doc/oopil.{dvi,ps} : A sort of rationale for MeroonV3.
451; Doc/dispatch.{dvi,ps} : A description of the new dispatching scheme of MeroonV3.
452
453
454== Bugs
455
456Find them, fix them, mail them!
457
458
459== Missing Features
460
461MeroonV3 still refuses to provide multiple inheritance.
462
463
464== License
465
466 Copyright (c) 1990-96 by Christian Queinnec. All rights reserved.
467 
468 This code is released under the Library GNU Public License
Note: See TracBrowser for help on using the repository browser.