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

Last change on this file since 36629 was 36629, checked in by kon, 8 months ago

rel 2.1.0

File size: 8.2 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}}.
79
80=== Describe
81
82[[coops]] object internals.
83
84==== Usage
85
86<enscript language=scheme>
87(import coops-describe)
88</enscript>
89
90==== describe-object
91
92<procedure>(describe-object INSTANCE [OUT (current-output-port)])</procedure>
93
94Prints information about the {{INSTANCE}} to the {{output-port}} {{OUT}}.
95
96{{describe-object}} is a {{generic-procedure}} specializing the first argument.
97
98A more detailed {{print-object}} for use in a ''REPL''.
99
100==== describe-object-slot
101
102<procedure>(describe-object-slot INSTANCE SLOT [NAME-MAXLEN 32 [OUT (current-output-port)]])</procedure>
103
104Prints information about the {{INSTANCE}}'s {{SLOT}} to the {{output-port}}
105{{OUT}}. Does not append a {{(newline)}}.
106
107{{NAME-MAXLEN}} is the maximum number of single-width characters in a slotname.
108
109
110=== Introspection
111
112[[coops]] predicates and read accessors.
113
114Some [[TInyCLOS]] inspired property readers.
115
116==== Usage
117
118<enscript language=scheme>
119(import coops-introspection)
120</enscript>
121
122==== instance-of?
123
124<procedure>(instance-of? OBJECT CLASS) --> boolean</procedure>
125
126Is {{OBJECT}} an {{instance}} of the {{CLASS>}}?
127
128==== class?
129
130<procedure>(class? OBJECT) --> boolean</procedure>
131
132Is {{OBJECT}} an {{instance}} of the {{<standard-class>}}?
133
134<procedure>(check-class LOC OBJ [ARGNAM]) --> *</procedure>
135<procedure>(error-class LOC OBJ [ARGNAM])</procedure>
136
137==== instance?
138
139<procedure>(instance? OBJECT) --> boolean</procedure>
140
141Is {{OBJECT}} an instance of a basic class. Neither an {{instance}} of
142the {{<standard-class>}} or a primitive such as {{boolean}} or {{vector}}?
143
144<procedure>(check-instance LOC OBJ [ARGNAM]) --> *</procedure>
145<procedure>(error-instance LOC OBJ [ARGNAM])</procedure>
146
147==== primitive-instance?
148
149<procedure>(primitive-instance? OBJECT) --> boolean</procedure>
150
151Is {{OBJECT}} an {{instance}} of the {{<primitive-object>}} class?
152
153==== generic?
154
155<procedure>(generic? OBJECT) --> boolean</procedure>
156
157Synonym for {{generic-procedure?}}.
158
159<procedure>(check-generic LOC OBJ [ARGNAM]) --> *</procedure>
160<procedure>(error-generic LOC OBJ [ARGNAM])</procedure>
161
162==== method?
163
164<procedure>(method? OBJECT) --> boolean</procedure>
165
166Is {{OBJECT}} a {{method}} of a {{generic-procedure}}?
167
168"Note" that the current implementation of methods does not depend on the type
169system. This function only validates the form of the argument and can be fooled.
170
171<procedure>(check-method LOC OBJ [ARGNAM]) --> *</procedure>
172<procedure>(error-method LOC OBJ [ARGNAM])</procedure>
173
174==== class-precedence-list
175
176<procedure>(class-precedence-list CLASS) --> (list-of class)</procedure>
177
178Returns the superclasses of {{CLASS}}.
179
180==== class-slots
181
182<procedure>(class-slots CLASS) --> (list-of symbol)</procedure>
183
184Returns the slot names of {{CLASS}}.
185
186==== class-direct-supers
187
188<procedure>(class-direct-supers CLASS) --> (list-of class)</procedure>
189
190Returns the uninherited superclasses of {{CLASS}}.
191
192==== class-direct-slots
193
194<procedure>(class-direct-slots CLASS) --> (list-of symbol)</procedure>
195
196Returns the uninherited slot names of {{CLASS}}.
197
198==== generic-anonymous?
199
200<procedure>(generic-anonymous? GENERIC) --> boolean</procedure>
201
202Is {{GENERIC}} an unnamed {{generic-procedure}}.
203
204==== generic-name
205
206<procedure>(generic-name GENERIC) --> (union #f symbol)</procedure>
207
208Returns the name of {{GENERIC}}. The name is {{#f}} for an anonymous generic
209procedure.
210
211==== generic-specialized-arguments
212
213<procedure>(generic-specialized-arguments GENERIC) --> (list-of symbol)</procedure>
214
215The arguments that {{GENERIC}} is specialized upon.
216
217==== generic-primary-methods
218
219<procedure>(generic-primary-methods GENERIC) --> (list-of method)</procedure>
220
221Returns the list of {{#:primary}} methods for {{GENERIC}}.
222
223==== generic-before-methods
224
225<procedure>(generic-before-methods GENERIC) --> (list-of method)</procedure>
226
227Returns the  list of {{#:before}} methods for {{GENERIC}}.
228
229==== generic-after-methods
230
231<procedure>(generic-after-methods GENERIC) --> (list-of method)</procedure>
232
233Returns the list of {{#:after}} methods for {{GENERIC}}.
234
235==== generic-around-methods
236
237<procedure>(generic-around-methods GENERIC) --> (list-of method)</procedure>
238
239Returns the list of {{#:around}} methods for {{GENERIC}}.
240
241==== method-specializers
242
243<procedure>(method-specializers METHOD) --> (list-of class)</procedure>
244
245Returns the classes that specialize {{METHOD}}.
246
247==== method-procedure
248
249<procedure>(method-procedure METHOD) --> procedure</procedure>
250
251Returns the {{procedure}} for {{METHOD}}.
252
253
254== Examples
255
256<enscript language=scheme>
257(import coops coops-introspection)
258
259(define (print-methods generic)
260  (for-each
261    (lambda (m)
262      (print
263        (generic-name generic)
264        " specialized by " (method-specializers m)
265        " as " (method-procedure m)))
266    (generic-primary-methods generic)) )
267</enscript>
268
269
270== Usage
271
272<enscript language=scheme>
273(import coops-utils)
274</enscript>
275
276
277== Requirements
278
279[[srfi 1]]
280[[srfi 13]]
281[[coops]]
282[[type-checks]]
283
284
285== Bugs and Limitations
286
287* The introspection API is brittle, especially the generics portion.
288
289Suggested only for use during ''REPL'' development with [[coops]].
290
291
292== Author
293
294[[/users/kon-lovett|Kon Lovett]]
295
296
297== Version history
298
299; 2.1.0 : {{describe}} in own module.
300; 2.0.0 : CHICKEN 5 release.
301; 1.2.0 : Add {{make-copy}}.
302; 1.1.0 : Collect TinyCLOS synonyms in own module: {{coops-introspection-tinyclos}}; reexport by {{coops-utils}} DEPRECATED.
303; 1.0.4 : Remove test, remove inlines.
304; 1.0.3 : Add test, fix library requirement.
305; 1.0.2 : Fix {{make/copy}} for objects with uninitialized slots, thanks to Sandra Snan
306; 1.0.1 : Fix {{class-direct-supers}} and {{class-direct-slots}}, minor internal optimization.
307; 1.0.0 : Release for coops 1.92
308; 0.0.3 : * UNMAINTAINED *
309; 0.0.2 :
310; 0.0.1 :
311
312
313== License
314
315Copyright (C) 2010-2017 Kon Lovett. All rights reserved.
316
317Permission is hereby granted, free of charge, to any person obtaining a
318copy of this software and associated documentation files (the Software),
319to deal in the Software without restriction, including without limitation
320the rights to use, copy, modify, merge, publish, distribute, sublicense,
321and/or sell copies of the Software, and to permit persons to whom the
322Software is furnished to do so, subject to the following conditions:
323
324The above copyright notice and this permission notice shall be included
325in all copies or substantial portions of the Software.
326
327THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
328IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
329FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
330THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
331OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
332ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
333OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.