source: project/wiki/tinyclos @ 1382

Last change on this file since 1382 was 1382, checked in by felix winkelmann, 15 years ago

easyffi related changes

File size: 13.1 KB
Line 
1[[tags:eggs oop]]
2[[toc:]]
3
4
5== Introduction
6
7This extension is a port of Gregor Kiczales '''TinyCLOS''' with numerous
8modifications.
9
10''Note: this extension is only needed for CHICKEN versions 2.424 and higher''
11
12
13==== Defining forms
14
15
16==== define-class
17
18 [syntax] (define-class NAME (SUPERCLASS1 ...) (SLOTNAME1 ...) [METACLASS])
19
20Sets the variable {{NAME}} to a new class (a new instance of
21the class {{<class>}}). {{SUPERCLASS1 ...}} is a list of
22superclasses of the newly created class. If no superclasses are given,
23then {{<object>}} is assumed.  {{SLOTNAME1 ...}} are the names
24of the direct slots of the class. if {{METACLASS}} is provided,
25then the new class-instance is an instance of {{METACLASS}} instead
26of {{<class>}}.
27
28 (define-class NAME (SUPER) (SLOT1 SLOT2) META)
29
30is equivalent to
31
32 (define NAME
33   (make META
34     'name 'NAME
35     'direct-supers (list SUPER)
36     'direct-slots (list 'SLOT1 'SLOT2)) )
37
38Note that slots-names are not required to be symbols, so the following
39is perfectly valid:
40
41 (define hidden-slot (list 'hidden))
42 (define <myclass>
43   (make <class>
44      'direct-supers (list <object>)
45      'direct-slots (list hidden-slot) ) )
46 (define x1 (make <myclass>)
47 (slot-set! x1 hidden-slot 99)
48
49
50==== define-generic
51
52 [syntax] (define-generic NAME [CLASS])
53
54Sets the variable {{NAME}} to contain a fresh generic function
55object without associated methods. If the optional argument {{CLASS}}
56is given, then the generic function will be an instance of that class.
57
58
59==== define-method
60
61 [syntax] (define-method (NAME (VARIABLE1 CLASS1) ... PARAMETERS ...) BODY ...)
62
63Adds a new method with the code {{BODY ...}} to the generic function
64that was assigned to the variable {{NAME}}.  {{CLASS1 ...}} is
65a list if classes that specialize this particular method. The method can
66have additional parameters {{PARAMETERS}}, which do not specialize
67the method any further.  Extended lambda-lists are allowed ({{#!optional, #!key}}
68or {{#!rest}} argument lists), but can not be specialized.
69Inside the body of the method the identifier
70{{call-next-method}} names a procedure of zero arguments that can
71be invoked to call the next applicable method with the same arguments.
72If no generic function is defined under this name, then a fresh generic
73function object is created and assigned to {{NAME}}.
74
75Note that only {{define-generic}} expands into a valid definition,
76so for internal lexically scoped definitions use {{define-generic}}.
77
78Currently methods defined with {{define-method}} should not be
79hidden (via {{(declare (hide ...))}}, nor should such files be compiled
80in {{block}} mode, unless the methods are exported.
81
82
83
84
85
86=== Base language
87
88
89
90
91==== add-method
92
93 [procedure] (add-method GENERIC METHOD)
94
95Adds the method object {{METHOD}} to the list of applicable methods
96for the generic function {{GENERIC}}.
97
98
99==== instance?
100
101 [procedure] (instance? X)
102
103Returns {{#t}} if {{X}} is an instance of a non-primitive
104class.
105
106
107==== make
108
109 [procedure] (make CLASS INITARG ...)
110
111Creates a new instance of {{CLASS}} and passes {{INITARG ...}}
112to the {{initialize}} method of this class.
113
114
115==== make-class
116
117 [procedure] (make-class SUPERCLASSES SLOTNAMES)
118
119Creates a new class object, where {{SUPERCLASSES}} should be the
120list of direct superclass objects and {{SLOTNAMES}} should be a
121list of symbols naming the slots of this class.
122
123
124==== make-generic
125
126 [procedure] (make-generic [NAME])
127
128Creates a new generic function object. If {{NAME}} is specified,
129then it should be a string.
130
131
132==== make-method
133
134 [procedure] (make-method SPECIALIZERS PROC)
135
136Creates a new method object specialized to the list of classes in
137{{SPECIALIZERS}}.
138
139 (define-method (foo (x <bar>)) 123)
140    <=> (add-method foo
141                    (make-method
142                       (list <bar>)
143                       (lambda (call-next-method x) 123)))
144
145
146==== slot-ref
147
148 [procedure] (slot-ref INSTANCE SLOTNAME)
149
150Returns the value of the slot {{SLOTNAME}} of the object
151{{INSTANCE}}.
152
153
154====slot-set! :
155
156 [procedure] (slot-set! INSTANCE SLOTNAME VALUE)
157 [setter] (set! (slot-ref INSTANCE SLOTNAME) VALUE)
158
159Sets the value of the slot {{SLOTNAME}} of the object
160{{INSTANCE}} to {{VALUE}}.
161
162
163
164
165
166=== Introspection
167
168
169
170
171==== class-cpl
172
173 [procedure] (class-cpl CLASS)
174
175Returns the class-precedence-list of {{CLASS}} as a list of classes.
176
177
178==== class-direct-slots
179
180 [procedure] (class-direct-slots CLASS)
181
182Returns the list of direct slots of {{CLASS}} as a list of lists,
183where each sublist contains the name of the slot.
184
185
186==== class-direct-supers
187
188 [procedure] (class-direct-supers CLASS)
189
190Returns the list of direct superclasses of {{CLASS}}.
191
192
193==== class-of
194
195 [procedure] (class-of X)
196
197Returns the class that the object {{X}} is an instance of.
198
199
200==== class-name
201
202 [procedure] (class-name CLASS)
203
204Returns name of {{CLASS}}.
205
206
207==== class-slots
208
209 [procedure] (class-slots CLASS)
210
211Returns the list of all slots of {{CLASS}} and its superclasses
212as a list of lists, where each sublist contains the name of the slot.
213
214
215==== generic-methods
216
217 [procedure] (generic-methods GENERIC)
218
219Returns the list of all methods associated with the generic function
220{{GENERIC}}.
221
222
223==== method-specializers
224
225 [procedure] (method-specializers METHOD)
226
227Returns the list of classes that specialize {{METHOD}}.
228
229
230==== method-procedure
231
232 [procedure] (method-procedure METHOD)
233
234Returns the procedure that contains the body of {{METHOD}}.
235
236
237==== subclass?
238
239 [procedure] (subclass? CLASS1 CLASS2)
240
241Returns {{#t}} is {{CLASS1}} is a subclass of {{CLASS2}},
242or {{#f}} otherwise. Note that the following holds:
243
244<enscript highlight=scheme>
245(subclass? X X) ==> #t
246</enscript>
247
248
249==== instance-of?
250
251 [procedure] (instance-of? X CLASS)
252
253Returns {{#t}} if {{X}} is an instance of {{CLASS}} (or one of its subclasses).
254
255
256
257
258=== Intercessory protocol
259
260These definitions allow interfacing to the Meta Object Protocol
261of TinyCLOS. For serious use, it is recommended to consult
262the source code ({{tinyclos.scm}}).
263
264
265
266==== allocate-instance
267
268 [generic] (allocate-instance CLASS)
269
270Allocates storage for an instance of {{CLASS}} and returns the
271instance.
272
273
274==== compute-apply-generic
275
276 [generic] (compute-apply-generic GENERIC)
277
278Returns a procedure that will be called to apply the generic function
279methods to the arguments.
280
281
282==== compute-apply-methods
283
284 [generic] (compute-apply-methods GENERIC)
285
286Returns a procedure of two arguments, a list of applicable methods
287and a list of arguments and applies the methods.
288
289
290==== compute-methods
291
292 [generic] (compute-methods GENERIC)
293
294Returns a procedure of one argument. The procedure is called with the
295list of actual arguments passed to the generic function and should
296return a list of applicable methods, sorted by precedence.
297
298
299==== compute-cpl
300
301 [generic] (compute-cpl CLASS)
302
303Computes and returns the class-precedence-list of {{CLASS}}.
304
305
306==== compute-getter-and-setter
307
308 [generic] (compute-getter-and-setter CLASS SLOT ALLOCATOR)
309
310Returns two values, the procedures that get and set the contents of the
311slot {{SLOT}}.  {{ALLOCATOR}} is a procedure of one argument that
312gets an initalizer function and returns the getter and setter procedures
313for the allocated slot.
314
315
316==== compute-method-more-specific?
317
318 [generic] (compute-method-more-specific? GENERIC)
319
320Returns a procedure of three arguments (two methods and a list of
321arguments) that returns {{#t}} if the first method is more specific
322than the second one with respect to the list of arguments. Otherwise
323the returned predicate returns {{#f}}.
324
325
326==== compute-slots
327
328 [generic] (compute-slots CLASS)
329
330Computes and returns the list of slots of {{CLASS}}.
331
332
333==== initialize
334
335 [generic] (initialize INSTANCE INITARGS)
336
337Initializes the object {{INSTANCE}}. {{INITARGS}} is the list of
338initialization arguments that were passed to the {{make}} procedure.
339
340
341
342
343
344=== Additional protocol
345
346
347
348
349==== describe-object
350
351 [generic] (describe-object INSTANCE [PORT])
352
353Writes a description of {{INSTANCE}} to {{PORT}}.  Execution of
354the interpreter command {{,d}} will invoke this generic function.
355If {{PORT}} is not given it defaults to the value of {{(current-output-port)}}.
356
357
358==== print-object
359
360 [generic] (print-object INSTANCE [PORT])
361
362Writes a textual representation of {{INSTANCE}} to {{PORT}}.
363Any output of an instance with {{display, write}} and {{print}}
364will invoke this generic function.
365If {{PORT}} is not given it defaults to the value of {{(current-output-port)}}.
366
367
368
369
370
371=== Utility procedures
372
373
374
375
376==== initialize-slots
377
378 [procedure] (initialize-slots INSTANCE INITARGS)
379
380This procedure takes a sequence of alternating slot-names and
381initialization values in {{INITARGS}} and initializes the
382corresponding slots in {{INSTANCE}}.
383
384 (define-class <pos> () (x y))
385 
386 (define-method (initialize (pos <pos>) initargs)
387   (call-next-method)
388   (initialize-slots pos initargs))
389 
390 (define p1 (make <pos> 'x 1 'y 2))
391 (define p2 (make <pos> 'x 3 'y 5))
392
393
394
395
396
397=== Builtin classes
398
399
400The class hierarchy of builtin classes looks like this:
401
402
403 <top>
404   <object>
405     <class>
406       <procedure-class>
407         <procedure>
408         <entity-class>
409           <generic>
410       <primitive-class>
411     <c++-object>
412   <primitive>
413     <void>
414     <boolean>
415     <symbol>
416     <char>
417     <vector>
418     <pair>
419     <number>
420       <integer>
421        <exact>
422       <inexact>
423     <string>
424     <port>
425       <input-port>
426       <output-port>
427     <pointer>
428       <tagged-pointer>
429       <swig-pointer>
430     <locative>
431     <byte-vector>
432       <u8vector>
433       <s8vector>
434       <u16vector>
435       <s16vector>
436       <u32vector>
437       <s32vector>
438       <f32vector>
439       <f64vector>
440     <structure>
441       <char-set>
442       <condition>
443       <continuation>
444       <environment>
445       <hash-table>
446       <lock>
447       <mmap>
448       <mutex>
449       <promise>
450       <queue>
451       <read-table>
452       <regexp>
453       <tcp-listener>
454       <thread>
455       <time>
456     <end-of-file>
457
458
459=== <primitive>
460
461The parent class of the classes of all primitive Scheme objects.
462
463=== boolean
464=== symbol
465=== char
466=== vector
467=== null
468=== pair
469=== number
470=== integer
471=== exact
472=== inexact
473=== string
474=== port
475=== environment
476=== end-of-file
477=== input-port
478=== output-port
479=== procedure
480The classes of primitive Scheme objects.
481
482
483=== byte-vector
484=== structure
485=== hash-table
486=== queue
487The classes of extended data types provided by the various library units.
488
489
490=== class
491The parent class of all class objects.
492     
493
494=== entity-class
495The parent class of objects that can be invoked as a procedure and have slots.
496
497
498=== generic
499The parent class of generic function objects.   
500
501
502=== method
503The parent class of method objects.
504
505
506=== object
507The parent class of all objects.
508
509
510=== procedure-class
511The parent class of objects that can be invoked as a procedure.
512
513
514=== condition
515Class of condition objects.
516
517=== continuation
518Class of continuation objects captured by {{continuation-capture}}.
519
520=== array
521=== char-set
522=== time
523=== u8vector
524=== s8vector
525=== u16vector
526=== s16vector
527=== u32vector
528=== s32vector
529=== f32vector
530=== f64vector
531The classes of data objects provided by the various supported SRFIs.
532
533=== lock
534=== mmap
535Classes of objects used in the {{posix}} library unit.
536
537
538=== pointer
539=== tagged-pointer
540=== swig-pointer
541A machine pointer (untagged, tagged or pointing to SWIG-wrapped data).
542
543     
544=== locative
545A locative.
546
547
548=== promise
549The class of objects returned by {{delay}}.
550
551
552=== tcp-listener
553The class of an object returned by {{tcp-listen}}.
554
555
556=== regexp
557The class of an object returned by {{regexp}}.
558
559
560=== c++-class
561The class of generated wrappers for C++ classes parsed by the "easy"
562Foreign Function interface [[easyffi]].
563
564
565== Authors
566
567Orignal version by Gregor Kiczales, CHICKEN port and performance enhancements by [[felix winkelmann]], some
568of which have been inspired by Eli Barzilays ''Swindle''
569
570== License
571
572 Copyright (c) 2000-2006, Felix L. Winkelmann
573 All rights reserved.
574
575 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
576 conditions are met:
577
578   Redistributions of source code must retain the above copyright notice, this list of conditions and the following
579     disclaimer.
580   Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
581     disclaimer in the documentation and/or other materials provided with the distribution.
582   Neither the name of the author nor the names of its contributors may be used to endorse or promote
583     products derived from this software without specific prior written permission.
584
585 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
586 OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
587 AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
588 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
589 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
590 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
591 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
592 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
593 POSSIBILITY OF SUCH DAMAGE.
594
595== Version History
596
597; 1.0 : moved from base distribution into separate extension
Note: See TracBrowser for help on using the repository browser.