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

Last change on this file since 35337 was 35337, checked in by Kon Lovett, 3 years ago

rel 2.1.0

File size: 7.1 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-decorator</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) -> boolean</procedure>
58
59Is the {{OBJECT}} a {{procedure-decorator}}?
60
61==== decorate-procedure
62
63<procedure>(decorate-procedure PROCEDURE PROCEDURE-DECORATOR [ARGUMENTS ...]) -> procedure</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) -> boolean</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</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-decorator</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) -> boolean</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<enscript language=scheme>
169;create a 'docstring' concept
170(define-procedure-extender docstring procedure-documentation documented-procedure?)
171
172;document something
173(define (foo x) x)
174(documented-procedure? test-proc) ;=> #f
175(set! (procedure-documentation foo) "foo is foo")
176(documented-procedure? test-proc) ;=> #t
177(procedure-documentation test-proc) ;=> "foo is foo"
178</enscript>
179
180
181=== Notes
182
183* The {{decorate-lambda}} interface decorated procedure is not the original
184procedure. Decorating procedure {{foo}} will not change the procedure
185object of {{foo}}, but return a new one.
186
187* The {{procedure-decorator}} interface can rewrite the procedure object.
188Decorating procedure {{foo}} with a {{REPLACE?}} {{procedure-decorator}} changes
189the procedure object of {{foo}}.
190
191
192=== Author
193
194[[/users/kon-lovett|Kon Lovett]]
195
196
197=== Requirements
198
199[[check-errors]]
200
201[[setup-helper]]
202
203
204=== Version history
205
206; 2.1.0 : Add types.
207; 2.0.2 : Fix for ticket #630.
208; 2.0.1 :
209; 2.0.0 : Initial Chicken 4 release
210
211
212=== License
213
214Copyright (c) 2009-2018 Kon Lovett.  All rights reserved.
215
216Permission is hereby granted, free of charge, to any person obtaining a
217copy of this software and associated documentation files (the Software),
218to deal in the Software without restriction, including without limitation
219the rights to use, copy, modify, merge, publish, distribute, sublicense,
220and/or sell copies of the Software, and to permit persons to whom the
221Software is furnished to do so, subject to the following conditions:
222
223The above copyright notice and this permission notice shall be included
224in all copies or substantial portions of the Software.
225
226THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
227IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
228FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
229THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
230OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
231ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
232OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.