source: project/wiki/meroon @ 6317

Last change on this file since 6317 was 6317, checked in by svnwiki, 12 years ago

Changes applied for JP Theberge (74.56.66.149) through svnwiki:

Added Chicken to the list of supported scheme!

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