source: project/wiki/eggref/5/advice @ 37428

Last change on this file since 37428 was 37428, checked in by Kooda, 17 months ago

Document advice and trace for CHICKEN 5

File size: 3.7 KB
Line 
1[[tags: egg]]
2
3== advice
4
5=== Introduction
6
7The {{advice}} extensions allows modifying the behaviour of
8existing procedures by specifying code that should run before,
9after or instead of the original procedure.
10
11=== Usage
12
13<procedure>(advise MODE PROCEDURE ADVISOR [ID])</procedure>
14
15Adds a "piece of advice" to {{PROCEDURE}}. Depending on {{MODE}}, do
16any of the following:
17
18* if {{MODE}} is the symbol {{before}}, every call to {{PROCEDURE}} will invoke the procedure {{ADVISOR}} with a list of the arguments passed to {{PROCEDURE}} before the original procedure is executed.
19* if {{MODE}} is the symbol {{after}}, every call to {{PROCEDURE}} will invoke the procedure {{ADVISOR}} with a list of the arguments passed to {{PROCEDURE}} after the original procedure is executed.
20* if {{MODE}} is the symbol {{around}}, every call to {{PROCEDURE}} will invoke the procedure {{ADVISOR}} with the next "inner" {{around}} advisor procedure (or the original procedure, if no other {{around}} advice is defined or remaining) and a list of the arguments passed to {{PROCEDURE}}.
21
22{{before}} advice-procedures are invoked in the reverse order: the
23most recently added advisor runs first. {{after}} advice-procedures are invoked in
24the order in which they are added, the most recent one running last.
25The most recently added {{around}} advice-procedures is called with the
26next "inner" advice procedure passed as argument.
27
28The procedure passed as first argument to {{around}} advisors takes its
29arguments in the same manner as the original procedure.
30
31{{advise}} returns an {{ID}} that can be used to identify a particular
32piece of advice. If no ID was given, one will be generated.
33
34<procedure>(unadvise PROCEDURE [ID [MODE]])</procedure>
35
36Removes advice from an advised procedure. Advice can be removed completely
37(no ID or mode given). Specific pieces of advice can be removed by passing
38the advice-ID (as returned by {{advice}}). Alternatively advice for a given
39mode ({{before}}, {{after}} or {{around}}) can be removed (by passing
40{{#f}} as the {{ID}} argument).
41
42=== Authors
43
44[[/users/felix winkelmann|felix winkelmann]]
45
46=== Version
47
48; 0.4 : ported to CHICKEN 5
49; 0.2 : ported to CHICKEN 4
50; 0.1 : Initial version
51
52=== License
53
54 Copyright (c) 2007, Felix L. Winkelmann
55 All rights reserved.
56
57 Redistribution and use in source and binary forms, with or without
58 modification, are permitted provided that the following conditions are met:
59
60   Redistributions of source code must retain the above copyright notice,
61     this list of conditions and the following disclaimer.
62   Redistributions in binary form must reproduce the above copyright notice,
63     this list of conditions and the following disclaimer in the
64     documentation and/or other materials provided with the distribution.
65   Neither the name of the author nor the names of its contributors may be
66     used to endorse or promote products derived from this software without
67     specific prior written permission.
68
69 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
70 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
71 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
72 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
73 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
74 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
75 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
76 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
77 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
78 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
79 POSSIBILITY OF SUCH DAMAGE.
80
Note: See TracBrowser for help on using the repository browser.