source: project/wiki/eggref/5/coops-utils @ 38899

Last change on this file since 38899 was 38899, checked in by Kon Lovett, 2 months ago

rel 2.1.5

File size: 8.6 KB
Line 
1[[tags: egg]]
2
3== coops-utils
4
5[[toc:]]
6
7
8== Documentation
9
10[[coops]] extensions.
11
12
13=== Argument Conventions
14
15{{INSTANCE}} is a {{coops-instance}}.
16
17{{SLOT}} is a {{symbol}}.
18
19{{INITFORM}} is {{'SLOT OBJECT}}.
20
21{{OBJECT}} is a Scheme {{object}}.
22
23{{CLASS}} is a coops {{class}}.
24
25{{GENERIC}} is a coops {{generic-procedure}}.
26
27{{METHOD}} is a coops {{generic-procedure}} {{method}}.
28Do not apply any but the supplied API to instances of this type!
29
30=== Extras
31
32[[coops]] usage extensions.
33
34==== Usage
35
36<enscript language=scheme>
37(import coops-extras)
38</enscript>
39
40==== slot@
41
42The slot accessor recursion.
43
44<syntax>(slot@ INSTANCE SLOT ...) --> *</syntax>
45
46Returns the slot value of the N'th named slot from {{INSTANCE}}.
47
48<syntax>(slot@ INSTANCE SLOT ... = OBJECT)</syntax>
49
50Sets the slot value of the N'th named slot of {{INSTANCE}} to {{OBJECT}}.
51
52Example:
53
54<enscript language=scheme>
55(import coops coops-extras)
56
57;Needlessly complex for example
58
59(define-class <first> () (next))
60(define-class <second> (<first>) ())
61(define-class <third> (<second>) ())
62
63(define 1st (make <first> 'next (make <second> 'next (make <third> 'next "the end"))))
64
65(slot@ 1st next next next) ;=> "the end"
66
67(slot@ 1st next next next = "still the end")
68(slot@ 1st next next next) ;=> "still the end"
69</enscript>
70
71(From '@' macro by Dan Muresan.)
72
73==== make-copy
74
75<procedure>(make-copy INSTANCE [INITFORM ...]) --> coops-instance</procedure>
76
77Returns a copy of the object {{INSTANCE}}, except where an {{INITFORM}}
78overrides an existing {{SLOT}} value of the {{INSTANCE}}. The copy is a
79shallow copy that shares values with {{INSTANCE}}.
80
81=== Describe
82
83[[coops]] object internals.
84
85==== Usage
86
87<enscript language=scheme>
88(import coops-describe)
89</enscript>
90
91==== describe-object
92
93<procedure>(describe-object INSTANCE [OUT (current-output-port)])</procedure>
94
95Prints information about the {{INSTANCE}} to the {{output-port}} {{OUT}}.
96
97{{describe-object}} is a {{generic-procedure}} specializing the first argument.
98
99A more detailed {{print-object}} for use in a ''REPL''.
100
101==== describe-object-slot
102
103<procedure>(describe-object-slot INSTANCE SLOT [NAME-MAXLEN 32 [OUT (current-output-port)]])</procedure>
104
105Prints information about the {{INSTANCE}}'s {{SLOT}} to the {{output-port}}
106{{OUT}}. Does not append a {{(newline)}}.
107
108{{NAME-MAXLEN}} is the maximum number of single-width characters in a slotname.
109
110
111=== Introspection
112
113[[coops]] predicates and read accessors.
114
115Some [[http://wiki.call-cc.org/eggref/4/tinyclos|TinyCLOS]] inspired property readers.
116
117==== Usage
118
119<enscript language=scheme>
120(import coops-introspection)
121</enscript>
122
123==== instance-of?
124
125<procedure>(instance-of? OBJECT CLASS) --> boolean</procedure>
126
127Is {{OBJECT}} an {{instance}} of the {{CLASS}}?
128
129==== class?
130
131<procedure>(class? OBJECT) --> boolean</procedure>
132
133Is {{OBJECT}} an {{instance}} of the {{<standard-class>}}?
134
135<procedure>(check-class LOC OBJ [ARGNAM]) --> *</procedure>
136<procedure>(error-class LOC OBJ [ARGNAM])</procedure>
137
138==== instance?
139
140<procedure>(instance? OBJECT) --> boolean</procedure>
141
142Is {{OBJECT}} an instance of a basic class. Neither an {{instance}} of
143the {{<standard-class>}} or a primitive such as {{boolean}} or {{vector}}?
144
145<procedure>(check-instance LOC OBJ [ARGNAM]) --> *</procedure>
146<procedure>(error-instance LOC OBJ [ARGNAM])</procedure>
147
148==== primitive-instance?
149
150<procedure>(primitive-instance? OBJECT) --> boolean</procedure>
151
152Is {{OBJECT}} an {{instance}} of the {{<primitive-object>}} class or {{#t}}?
153
154'''Note''' {{#t}} is the default class, without the {{coops-primitive-objects}} module.
155
156==== generic?
157
158<procedure>(generic? OBJECT) --> boolean</procedure>
159
160Synonym for {{generic-procedure?}}.
161
162<procedure>(check-generic LOC OBJ [ARGNAM]) --> *</procedure>
163<procedure>(error-generic LOC OBJ [ARGNAM])</procedure>
164
165==== method?
166
167<procedure>(method? OBJECT) --> boolean</procedure>
168
169Is {{OBJECT}} a {{method}} of a {{generic-procedure}}?
170
171Only useful in the context of a {{generic-*-methods}} procedure result.
172
173<procedure>(check-method LOC OBJ [ARGNAM]) --> *</procedure>
174<procedure>(error-method LOC OBJ [ARGNAM])</procedure>
175
176==== class-precedence-list
177
178<procedure>(class-precedence-list CLASS) --> (list-of class)</procedure>
179
180Returns the superclasses of {{CLASS}}.
181
182==== class-slots
183
184<procedure>(class-slots CLASS) --> (list-of symbol)</procedure>
185
186Returns the slot names of {{CLASS}}.
187
188==== class-direct-supers
189
190<procedure>(class-direct-supers CLASS) --> (list-of class)</procedure>
191
192Returns the uninherited superclasses of {{CLASS}}.
193
194==== class-direct-slots
195
196<procedure>(class-direct-slots CLASS) --> (list-of symbol)</procedure>
197
198Returns the uninherited slot names of {{CLASS}}.
199
200==== generic-anonymous?
201
202<procedure>(generic-anonymous? GENERIC) --> boolean</procedure>
203
204Is {{GENERIC}} an unnamed {{generic-procedure}}.
205
206==== generic-name
207
208<procedure>(generic-name GENERIC) --> (union #f symbol)</procedure>
209
210Returns the name of {{GENERIC}}. The name is {{#f}} for an anonymous generic
211procedure.
212
213==== generic-specialized-arguments
214
215<procedure>(generic-specialized-arguments GENERIC) --> (list-of symbol)</procedure>
216
217The arguments that {{GENERIC}} is specialized upon.
218
219==== generic-primary-methods
220
221<procedure>(generic-primary-methods GENERIC) --> (list-of method)</procedure>
222
223Returns the list of {{#:primary}} methods for {{GENERIC}}.
224
225==== generic-before-methods
226
227<procedure>(generic-before-methods GENERIC) --> (list-of method)</procedure>
228
229Returns the  list of {{#:before}} methods for {{GENERIC}}.
230
231==== generic-after-methods
232
233<procedure>(generic-after-methods GENERIC) --> (list-of method)</procedure>
234
235Returns the list of {{#:after}} methods for {{GENERIC}}.
236
237==== generic-around-methods
238
239<procedure>(generic-around-methods GENERIC) --> (list-of method)</procedure>
240
241Returns the list of {{#:around}} methods for {{GENERIC}}.
242
243==== method-specializers
244
245<procedure>(method-specializers METHOD) --> (list-of class)</procedure>
246
247Returns the classes that specialize {{METHOD}}.
248
249Throws an assertion error when slot not actually list.
250
251==== method-procedure
252
253<procedure>(method-procedure METHOD) --> procedure</procedure>
254
255Returns the {{procedure}} for {{METHOD}}.
256
257Throws an assertion error when slot not actually procedure.
258
259
260== Examples
261
262<enscript language=scheme>
263(import coops coops-introspection)
264
265(define (print-methods generic)
266  (for-each
267    (lambda (m)
268      (print
269        (generic-name generic)
270        " specialized by " (method-specializers m)
271        " as " (method-procedure m)))
272    (generic-primary-methods generic)) )
273</enscript>
274
275
276== Usage
277
278<enscript language=scheme>
279(import coops-utils)
280</enscript>
281
282
283== Requirements
284
285[[srfi 1]]
286[[srfi 13]]
287[[type-checks]]
288[[coops]]
289
290
291== Bugs and Limitations
292
293* The introspection API is brittle, especially the generics portion.
294
295Suggested only for use during ''REPL'' development with [[coops]].
296
297
298== Author
299
300[[/users/kon-lovett|Kon Lovett]]
301
302
303== Version history
304
305; 2.1.5 : Fix {{method?}}, {{instance?}} & {{primitive-instance?}}.
306; 2.1.4 : {{make-copy}} uses ''fresh'' slots.
307; 2.1.3 : Bug #1700.
308; 2.1.2 : {{method-specializers}} & {{method-procedure}} type matches documentation.
309; 2.1.1 : .
310; 2.1.0 : {{describe}} in own module.
311; 2.0.0 : CHICKEN 5 release.
312; 1.2.0 : Add {{make-copy}}.
313; 1.1.0 : Collect TinyCLOS synonyms in own module: {{coops-introspection-tinyclos}}; reexport by {{coops-utils}} DEPRECATED.
314; 1.0.4 : Remove test, remove inlines.
315; 1.0.3 : Add test, fix library requirement.
316; 1.0.2 : Fix {{make/copy}} for objects with uninitialized slots, thanks to Sandra Snan
317; 1.0.1 : Fix {{class-direct-supers}} and {{class-direct-slots}}, minor internal optimization.
318; 1.0.0 : Release for coops 1.92
319; 0.0.3 : * UNMAINTAINED *
320; 0.0.2 :
321; 0.0.1 :
322
323
324== License
325
326Copyright (C) 2010-2017 Kon Lovett. All rights reserved.
327
328Permission is hereby granted, free of charge, to any person obtaining a
329copy of this software and associated documentation files (the Software),
330to deal in the Software without restriction, including without limitation
331the rights to use, copy, modify, merge, publish, distribute, sublicense,
332and/or sell copies of the Software, and to permit persons to whom the
333Software is furnished to do so, subject to the following conditions:
334
335The above copyright notice and this permission notice shall be included
336in all copies or substantial portions of the Software.
337
338THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
339IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
340FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
341THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
342OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
343ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
344OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.