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

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

separate slot@ setter entry so not optional in template

File size: 8.5 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?
153
154==== generic?
155
156<procedure>(generic? OBJECT) --> boolean</procedure>
157
158Synonym for {{generic-procedure?}}.
159
160<procedure>(check-generic LOC OBJ [ARGNAM]) --> *</procedure>
161<procedure>(error-generic LOC OBJ [ARGNAM])</procedure>
162
163==== method?
164
165<procedure>(method? OBJECT) --> boolean</procedure>
166
167Is {{OBJECT}} a {{method}} of a {{generic-procedure}}?
168
169'''Note''' that the current implementation of methods does not depend on the type
170system. This function only validates the form of the argument and can be fooled.
171
172<procedure>(check-method LOC OBJ [ARGNAM]) --> *</procedure>
173<procedure>(error-method LOC OBJ [ARGNAM])</procedure>
174
175==== class-precedence-list
176
177<procedure>(class-precedence-list CLASS) --> (list-of class)</procedure>
178
179Returns the superclasses of {{CLASS}}.
180
181==== class-slots
182
183<procedure>(class-slots CLASS) --> (list-of symbol)</procedure>
184
185Returns the slot names of {{CLASS}}.
186
187==== class-direct-supers
188
189<procedure>(class-direct-supers CLASS) --> (list-of class)</procedure>
190
191Returns the uninherited superclasses of {{CLASS}}.
192
193==== class-direct-slots
194
195<procedure>(class-direct-slots CLASS) --> (list-of symbol)</procedure>
196
197Returns the uninherited slot names of {{CLASS}}.
198
199==== generic-anonymous?
200
201<procedure>(generic-anonymous? GENERIC) --> boolean</procedure>
202
203Is {{GENERIC}} an unnamed {{generic-procedure}}.
204
205==== generic-name
206
207<procedure>(generic-name GENERIC) --> (union #f symbol)</procedure>
208
209Returns the name of {{GENERIC}}. The name is {{#f}} for an anonymous generic
210procedure.
211
212==== generic-specialized-arguments
213
214<procedure>(generic-specialized-arguments GENERIC) --> (list-of symbol)</procedure>
215
216The arguments that {{GENERIC}} is specialized upon.
217
218==== generic-primary-methods
219
220<procedure>(generic-primary-methods GENERIC) --> (list-of method)</procedure>
221
222Returns the list of {{#:primary}} methods for {{GENERIC}}.
223
224==== generic-before-methods
225
226<procedure>(generic-before-methods GENERIC) --> (list-of method)</procedure>
227
228Returns the  list of {{#:before}} methods for {{GENERIC}}.
229
230==== generic-after-methods
231
232<procedure>(generic-after-methods GENERIC) --> (list-of method)</procedure>
233
234Returns the list of {{#:after}} methods for {{GENERIC}}.
235
236==== generic-around-methods
237
238<procedure>(generic-around-methods GENERIC) --> (list-of method)</procedure>
239
240Returns the list of {{#:around}} methods for {{GENERIC}}.
241
242==== method-specializers
243
244<procedure>(method-specializers METHOD) --> (list-of class)</procedure>
245
246Returns the classes that specialize {{METHOD}}.
247
248Throws an assertion error when slot not actually list.
249
250==== method-procedure
251
252<procedure>(method-procedure METHOD) --> procedure</procedure>
253
254Returns the {{procedure}} for {{METHOD}}.
255
256Throws an assertion error when slot not actually procedure.
257
258
259== Examples
260
261<enscript language=scheme>
262(import coops coops-introspection)
263
264(define (print-methods generic)
265  (for-each
266    (lambda (m)
267      (print
268        (generic-name generic)
269        " specialized by " (method-specializers m)
270        " as " (method-procedure m)))
271    (generic-primary-methods generic)) )
272</enscript>
273
274
275== Usage
276
277<enscript language=scheme>
278(import coops-utils)
279</enscript>
280
281
282== Requirements
283
284[[srfi 1]]
285[[srfi 13]]
286[[coops]]
287[[type-checks]]
288
289
290== Bugs and Limitations
291
292* The introspection API is brittle, especially the generics portion.
293
294Suggested only for use during ''REPL'' development with [[coops]].
295
296
297== Author
298
299[[/users/kon-lovett|Kon Lovett]]
300
301
302== Version history
303
304; 2.1.4 : {{make-copy}} uses ''fresh'' slots.
305; 2.1.3 : Bug #1700.
306; 2.1.2 : {{method-specializers}} & {{method-procedure}} type matches documentation.
307; 2.1.1 : .
308; 2.1.0 : {{describe}} in own module.
309; 2.0.0 : CHICKEN 5 release.
310; 1.2.0 : Add {{make-copy}}.
311; 1.1.0 : Collect TinyCLOS synonyms in own module: {{coops-introspection-tinyclos}}; reexport by {{coops-utils}} DEPRECATED.
312; 1.0.4 : Remove test, remove inlines.
313; 1.0.3 : Add test, fix library requirement.
314; 1.0.2 : Fix {{make/copy}} for objects with uninitialized slots, thanks to Sandra Snan
315; 1.0.1 : Fix {{class-direct-supers}} and {{class-direct-slots}}, minor internal optimization.
316; 1.0.0 : Release for coops 1.92
317; 0.0.3 : * UNMAINTAINED *
318; 0.0.2 :
319; 0.0.1 :
320
321
322== License
323
324Copyright (C) 2010-2017 Kon Lovett. All rights reserved.
325
326Permission is hereby granted, free of charge, to any person obtaining a
327copy of this software and associated documentation files (the Software),
328to deal in the Software without restriction, including without limitation
329the rights to use, copy, modify, merge, publish, distribute, sublicense,
330and/or sell copies of the Software, and to permit persons to whom the
331Software is furnished to do so, subject to the following conditions:
332
333The above copyright notice and this permission notice shall be included
334in all copies or substantial portions of the Software.
335
336THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
337IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
338FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
339THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
340OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
341ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
342OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.