source: project/wiki/eggref/4/procedure-decoration @ 28426

Last change on this file since 28426 was 28426, checked in by Kon Lovett, 8 years ago

Fix for ticket #630 rels

File size: 6.6 KB
Line 
1[[tags: egg]]
2[[toc:]]
3
4== procedure-decoration
5
6=== Introduction
7
8Chicken Scheme procedures have attributes, aspects of the procedure object
9that can be operated upon. Such an attribute is known as a "procedure decoration".
10
11This extension provides a facility to perform procedure decoration operations.
12
13
14=== Documentation
15
16An interface for procedure decoration. Similar to the lolevel unit
17{{extend-procedure}} interface but allowing many decorations, not just one.
18
19A {{PREDICATE}} is a procedure of one argument, a procedure decoration. The
20predicate must return a truth value indicating whether the argument is a
21decoration of the proper kind.
22
23A {{DECORATOR}} is a procedure of at least one argument, the current procedure
24decoration, which is {{(void)}} initially. The decorator must return an object
25to replace the current decoration.
26
27
28=== Procedure Decorator
29
30A more sophisticated interface for procedure decoration.
31
32==== make-procedure-decorator
33
34<procedure>(make-procedure-decorator PREDICATE DECORATOR RETRIEVER [#:initializer INITIALIZER] [#:replace? REPLACE?])</procedure>
35
36Returns a new {{procedure-decorator}}.
37
38The {{RETRIEVER}} is a procedure of at least one argument, the current
39procedure decoration, returning the procedure decoration object. Any following
40arguments are from the {{procedure-decoration}} call that will invoke the
41{{RETRIEVER}}.
42
43The {{INITIALIZER}} is a procedure of varying arity, returning the procedure
44decoration initial object. The arguments are from the {{decorate-procedure}}
45call that invokes the {{INITIALIZER}}. The {{INITIALIZER}} is invoked only once
46per procedure to decorate.
47
48The default {{INITIALIZER}} is built from the {{DECORATOR}}. The {{DECORATOR}}
49will be called with a first argument of {{(void)}}, and any other arguments
50from the {{decorate-procedure}} call.
51
52The {{REPLACE?}} flag determines whether the procedure object of a decorated
53procedure will be replaced (become). The default is {{#f}}.
54
55==== procedure-decorator?
56
57<procedure>(procedure-decorator? OBJECT)</procedure>
58
59Is the {{OBJECT}} a {{procedure-decorator}}?
60
61==== decorate-procedure
62
63<procedure>(decorate-procedure PROCEDURE PROCEDURE-DECORATOR [ARGUMENTS ...])</procedure>
64
65Decorate the {{PROCEDURE}} with the {{PROCEDURE-DECORATOR}}.
66
67The {{PROCEDURE-DECORATOR}} {{INITIALIZER}} is called on the first invocation
68for {{PROCEDURE}} and the {{DECORATOR}} on all subsequent invocations.
69
70The optional {{ARGUMENTS}} are passed to the invoked {{PROCEDURE-DECORATOR}}
71constructor, as above.
72
73On the first invocation a {{GC}} will be performed.
74
75Returns the decorated procedure.
76
77==== decorated-procedure?
78
79<procedure>(decorated-procedure? PROCEDURE PROCEDURE-DECORATOR)</procedure>
80
81Is the {{PROCEDURE}} a decorated by {{PROCEDURE-DECORATOR}}?
82
83==== procedure-decoration
84
85<procedure>(procedure-decoration PROCEDURE PROCEDURE-DECORATOR [ARGUMENTS ...])</procedure>
86
87Returns the procedure decoration of {{PROCEDURE-DECORATOR}} for the {{PROCEDURE}}.
88
89The optional {{ARGUMENTS}} are passed to the {{PROCEDURE-DECORATOR}} {{RETRIEVER}}.
90
91==== procedure-decorator-getter-and-setter
92
93<procedure>(procedure-decorator-getter-and-setter PROCEDURE-DECORATOR)</procedure>
94
95Returns a single argument getter, and creates a two argument setter, for the
96{{PROCEDURE-DECORATOR}}.
97
98The getter takes a {{PROCEDURE}} argument. The setter takes {{PROCEDURE}} and
99{{OBJECT}} arguments.
100
101
102=== Procedure Extender
103
104Not to be confused with the lolevel unit {{extend-procedure}} interface.
105
106==== make-procedure-extender
107
108<procedure>(make-procedure-extender TAG)</procedure>
109
110Returns a simple {{PROCEDURE-DECORATOR}} that recognizes its' decorations by
111the {{TAG}} and accepts any object as a decoration.
112
113The {{TAG}} is any object suitable for testing with {{eq?}}.
114
115==== define-procedure-extender
116
117<macro>(define-procedure-extender TAG [GETTER-NAME [PREDICATE-NAME]])</macro>
118
119Creates a functional interface for a {{PROCEDURE-DECORATOR}} that uses the
120{{TAG} symbol.
121
122Defines the {{PROCEDURE-DECORATOR}} as {{TAG-decorator}}.
123
124Defines a procedure named {{GETTER-NAME}} that takes one argument, a decorated
125procedure, and returns the procedure decoration. Creates a corresponding
126setter. The default {{GETTER-NAME}} is {{TAG-decoration}}.
127
128Defines a procedure named {{PREDICATE-NAME}} that takes one argument, a
129procedure, and returns whether the procedure is decorated. The default
130{{PREDICATE-NAME}} is {{TAG-decorated?}}.
131
132
133=== Lambda Decoration Interface
134
135A lower level interface for procedure decoration.
136
137==== decorated-lambda?
138
139<procedure>(decorated-lambda? PROCEDURE PREDICATE)</procedure>
140
141Is the {{PROCEDURE}} decorated per the {{PREDICATE}}?
142
143==== lambda-decoration
144
145<procedure>(lambda-decoration PROCEDURE PREDICATE)</procedure>
146
147Returns an object per the {{PREDICATE}} or {{#f}}.
148
149==== decorate-lambda
150
151<procedure>(decorate-lambda PROCEDURE PREDICATE DECORATOR)</procedure>
152
153Decorate the {{PROCEDURE}} per the {{PREDICATE}} with the result of the
154{{DECORATOR}}.
155
156Returns the decorated procedure.
157
158
159=== Usage
160
161<enscript language=scheme>
162(require-extension procedure-decoration)
163</enscript>
164
165
166=== Examples
167
168
169=== Notes
170
171* The {{decorate-lambda}} interface decorated procedure is not the original
172procedure. Decorating procedure {{foo}} will not change the procedure
173object of {{foo}}, but return a new one.
174
175* The {{procedure-decorator}} interface can rewrite the procedure object.
176Decorating procedure {{foo}} with a {{REPLACE?}} {{procedure-decorator}} changes
177the procedure object of {{foo}}.
178
179
180=== Author
181
182[[/users/kon-lovett|Kon Lovett]]
183
184
185=== Requirements
186
187[[check-errors]]
188
189
190=== Version history
191
192; 2.0.2 : Fix for ticket #630.
193; 2.0.1 :
194; 2.0.0 : Initial Chicken 4 release
195
196
197=== License
198
199Copyright (c) 2009 Kon Lovett.  All rights reserved.
200
201Permission is hereby granted, free of charge, to any person obtaining a
202copy of this software and associated documentation files (the Software),
203to deal in the Software without restriction, including without limitation
204the rights to use, copy, modify, merge, publish, distribute, sublicense,
205and/or sell copies of the Software, and to permit persons to whom the
206Software is furnished to do so, subject to the following conditions:
207
208The above copyright notice and this permission notice shall be included
209in all copies or substantial portions of the Software.
210
211THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
212IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
213FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
214THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
215OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
216ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
217OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.