annotate lisp/emacs-lisp/advice.el @ 107843:64cb38b81502

(define-minor-mode): A nil argument to the minor mode turns the mode ON.
author Stefan Monnier <monnier@iro.umontreal.ca>
date Mon, 12 Apr 2010 21:03:04 -0400
parents 2c62b10c201b
children b9c2b845f2e6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1 ;;; advice.el --- an overloading mechanism for Emacs Lisp functions
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2
74466
1d4b1a32fd66 Update copyright years.
Glenn Morris <rgm@gnu.org>
parents: 73251
diff changeset
3 ;; Copyright (C) 1993, 1994, 2000, 2001, 2002, 2003, 2004,
106815
1d1d5d9bd884 Add 2010 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 105372
diff changeset
4 ;; 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
5
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
6 ;; Author: Hans Chalupsky <hans@cs.buffalo.edu>
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
7 ;; Maintainer: FSF
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
8 ;; Created: 12 Dec 1992
5140
9cde7d7fea1f Comment change.
Richard M. Stallman <rms@gnu.org>
parents: 5138
diff changeset
9 ;; Keywords: extensions, lisp, tools
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
10
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
11 ;; This file is part of GNU Emacs.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
12
94655
90a2847062be Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents: 93759
diff changeset
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
14 ;; it under the terms of the GNU General Public License as published by
94655
90a2847062be Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents: 93759
diff changeset
15 ;; the Free Software Foundation, either version 3 of the License, or
90a2847062be Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents: 93759
diff changeset
16 ;; (at your option) any later version.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
17
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
18 ;; GNU Emacs is distributed in the hope that it will be useful,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
21 ;; GNU General Public License for more details.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
22
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
23 ;; You should have received a copy of the GNU General Public License
94655
90a2847062be Switch to recommended form of GPLv3 permissions notice.
Glenn Morris <rgm@gnu.org>
parents: 93759
diff changeset
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
25
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
26 ;; LCD Archive Entry:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
27 ;; advice|Hans Chalupsky|hans@cs.buffalo.edu|
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
28 ;; Overloading mechanism for Emacs Lisp functions|
8458
a95ca44cec95 (ad-subr-arglist): Adapted to new DOC file format.
Richard M. Stallman <rms@gnu.org>
parents: 8445
diff changeset
29 ;; 1994/08/05 03:42:04|2.14|~/packages/advice.el.Z|
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
30
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
31
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
32 ;;; Commentary:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
33
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
34 ;; NOTE: This documentation is slightly out of date. In particular, all the
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
35 ;; references to Emacs-18 are obsolete now, because it is not any longer
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
36 ;; supported by this version of Advice.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
37
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
38 ;; Advice is documented in the Emacs Lisp Manual.
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
39
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
40 ;; @ Introduction:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
41 ;; ===============
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
42 ;; This package implements a full-fledged Lisp-style advice mechanism
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
43 ;; for Emacs Lisp. Advice is a clean and efficient way to modify the
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
44 ;; behavior of Emacs Lisp functions without having to keep personal
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
45 ;; modified copies of such functions around. A great number of such
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
46 ;; modifications can be achieved by treating the original function as a
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
47 ;; black box and specifying a different execution environment for it
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
48 ;; with a piece of advice. Think of a piece of advice as a kind of fancy
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
49 ;; hook that you can attach to any function/macro/subr.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
50
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
51 ;; @ Highlights:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
52 ;; =============
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
53 ;; - Clean definition of multiple, named before/around/after advices
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
54 ;; for functions, macros, subrs and special forms
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
55 ;; - Full control over the arguments an advised function will receive,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
56 ;; the binding environment in which it will be executed, as well as the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
57 ;; value it will return.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
58 ;; - Allows re/definition of interactive behavior for functions and subrs
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
59 ;; - Every piece of advice can have its documentation string which will be
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
60 ;; combined with the original documentation of the advised function at
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
61 ;; call-time of `documentation' for proper command-key substitution.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
62 ;; - The execution of every piece of advice can be protected against error
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
63 ;; and non-local exits in preceding code or advices.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
64 ;; - Simple argument access either by name, or, more portable but as
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
65 ;; efficient, via access macros
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
66 ;; - Allows the specification of a different argument list for the advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
67 ;; version of a function.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
68 ;; - Advised functions can be byte-compiled either at file-compile time
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
69 ;; (see preactivation) or activation time.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
70 ;; - Separation of advice definition and activation
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
71 ;; - Forward advice is possible, that is
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
72 ;; as yet undefined or autoload functions can be advised without having to
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
73 ;; preload the file in which they are defined.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
74 ;; - Forward redefinition is possible because around advice can be used to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
75 ;; completely redefine a function.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
76 ;; - A caching mechanism for advised definition provides for cheap deactivation
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
77 ;; and reactivation of advised functions.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
78 ;; - Preactivation allows efficient construction and compilation of advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
79 ;; definitions at file compile time without giving up the flexibility of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
80 ;; the advice mechanism.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
81 ;; - En/disablement mechanism allows the use of different "views" of advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
82 ;; functions depending on what pieces of advice are currently en/disabled
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
83 ;; - Provides manipulation mechanisms for sets of advised functions via
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
84 ;; regular expressions that match advice names
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
85
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
86 ;; @ How to get Advice for Emacs-18:
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
87 ;; =================================
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
88 ;; `advice18.el', a version of Advice that also works in Emacs-18 is available
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
89 ;; either via anonymous ftp from `ftp.cs.buffalo.edu (128.205.32.9)' with
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
90 ;; pathname `/pub/Emacs/advice18.el', or from one of the Emacs Lisp archive
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
91 ;; sites, or send email to <hans@cs.buffalo.edu> and I'll mail it to you.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
92
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
93 ;; @ Overview, or how to read this file:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
94 ;; =====================================
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
95 ;; NOTE: This documentation is slightly out of date. In particular, all the
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
96 ;; references to Emacs-18 are obsolete now, because it is not any longer
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
97 ;; supported by this version of Advice. An up-to-date version will soon be
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
98 ;; available as an info file (thanks to the kind help of Jack Vinson and
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
99 ;; David M. Smith). Until then you can use `outline-mode' to help you read
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
100 ;; this documentation (set `outline-regexp' to `";; @+"').
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
101 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
102 ;; The four major sections of this file are:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
103 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
104 ;; @ This initial information ...installation, customization etc.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
105 ;; @ Advice documentation: ...general documentation
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
106 ;; @ Foo games: An advice tutorial ...teaches about Advice by example
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
107 ;; @ Advice implementation: ...actual code, yeah!!
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
108 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
109 ;; The latter three are actual headings which you can search for
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
110 ;; directly in case `outline-mode' doesn't work for you.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
111
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
112 ;; @ Restrictions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
113 ;; ===============
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
114 ;; - This version of Advice only works for Emacs 19.26 and later. It uses
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
115 ;; new versions of the built-in functions `fset/defalias' which are not
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
116 ;; yet available in Lucid Emacs, hence, it won't work there.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
117 ;; - Advised functions/macros/subrs will only exhibit their advised behavior
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
118 ;; when they are invoked via their function cell. This means that advice will
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
119 ;; not work for the following:
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
120 ;; + advised subrs that are called directly from other subrs or C-code
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
121 ;; + advised subrs that got replaced with their byte-code during
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
122 ;; byte-compilation (e.g., car)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
123 ;; + advised macros which were expanded during byte-compilation before
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
124 ;; their advice was activated.
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
125
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
126 ;; @ Credits:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
127 ;; ==========
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
128 ;; This package is an extension and generalization of packages such as
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
129 ;; insert-hooks.el written by Noah S. Friedman, and advise.el written by
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
130 ;; Raul J. Acevedo. Some ideas used in here come from these packages,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
131 ;; others come from the various Lisp advice mechanisms I've come across
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
132 ;; so far, and a few are simply mine.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
133
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
134 ;; @ Comments, suggestions, bug reports:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
135 ;; =====================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
136 ;; If you find any bugs, have suggestions for new advice features, find the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
137 ;; documentation wrong, confusing, incomplete, or otherwise unsatisfactory,
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
138 ;; have any questions about Advice, or have otherwise enlightening
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
139 ;; comments feel free to send me email at <hans@cs.buffalo.edu>.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
140
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
141 ;; @ Safety Rules and Emergency Exits:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
142 ;; ===================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
143 ;; Before we begin: CAUTION!!
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
144 ;; Advice provides you with a lot of rope to hang yourself on very
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
145 ;; easily accessible trees, so, here are a few important things you
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
146 ;; should know: Once Advice has been started with `ad-start-advice'
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
147 ;; (which happens automatically when you load this file), it
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
148 ;; generates an advised definition of the `documentation' function, and
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
149 ;; it will enable automatic advice activation when functions get defined.
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
150 ;; All of this can be undone at any time with `M-x ad-stop-advice'.
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
151 ;;
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
152 ;; If you experience any strange behavior/errors etc. that you attribute to
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
153 ;; Advice or to some ill-advised function do one of the following:
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
154
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
155 ;; - M-x ad-deactivate FUNCTION (if you have a definite suspicion what
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
156 ;; function gives you problems)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
157 ;; - M-x ad-deactivate-all (if you don't have a clue what's going wrong)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
158 ;; - M-x ad-stop-advice (if you think the problem is related to the
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
159 ;; advised functions used by Advice itself)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
160 ;; - M-x ad-recover-normality (for real emergencies)
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
161 ;; - If none of the above solves your Advice-related problem go to another
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
162 ;; terminal, kill your Emacs process and send me some hate mail.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
163
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
164 ;; The first three measures have restarts, i.e., once you've figured out
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
165 ;; the problem you can reactivate advised functions with either `ad-activate',
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
166 ;; `ad-activate-all', or `ad-start-advice'. `ad-recover-normality' unadvises
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
167 ;; everything so you won't be able to reactivate any advised functions, you'll
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
168 ;; have to stick with their standard incarnations for the rest of the session.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
169
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
170 ;; IMPORTANT: With Advice loaded always do `M-x ad-deactivate-all' before
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
171 ;; you byte-compile a file, because advised special forms and macros can lead
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
172 ;; to unwanted compilation results. When you are done compiling use
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
173 ;; `M-x ad-activate-all' to go back to the advised state of all your
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
174 ;; advised functions.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
175
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
176 ;; RELAX: Advice is pretty safe even if you are oblivious to the above.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
177 ;; I use it extensively and haven't run into any serious trouble in a long
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
178 ;; time. Just wanted you to be warned.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
179
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
180 ;; @ Customization:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
181 ;; ================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
182
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
183 ;; Look at the documentation of `ad-redefinition-action' for possible values
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
184 ;; of this variable. Its default value is `warn' which will print a warning
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
185 ;; message when an already defined advised function gets redefined with a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
186 ;; new original definition and de/activated.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
187
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
188 ;; Look at the documentation of `ad-default-compilation-action' for possible
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
189 ;; values of this variable. Its default value is `maybe' which will compile
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
190 ;; advised definitions during activation in case the byte-compiler is already
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
191 ;; loaded. Otherwise, it will leave them uncompiled.
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
192
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
193 ;; @ Motivation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
194 ;; =============
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
195 ;; Before I go on explaining how advice works, here are four simple examples
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
196 ;; how this package can be used. The first three are very useful, the last one
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
197 ;; is just a joke:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
198
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
199 ;;(defadvice switch-to-buffer (before existing-buffers-only activate)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
200 ;; "When called interactively switch to existing buffers only, unless
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
201 ;;when called with a prefix argument."
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
202 ;; (interactive
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
203 ;; (list (read-buffer "Switch to buffer: " (other-buffer)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
204 ;; (null current-prefix-arg)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
205 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
206 ;;(defadvice switch-to-buffer (around confirm-non-existing-buffers activate)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
207 ;; "Switch to non-existing buffers only upon confirmation."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
208 ;; (interactive "BSwitch to buffer: ")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
209 ;; (if (or (get-buffer (ad-get-arg 0))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
210 ;; (y-or-n-p (format "`%s' does not exist, create? " (ad-get-arg 0))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
211 ;; ad-do-it))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
212 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
213 ;;(defadvice find-file (before existing-files-only activate)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
214 ;; "Find existing files only"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
215 ;; (interactive "fFind file: "))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
216 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
217 ;;(defadvice car (around interactive activate)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
218 ;; "Make `car' an interactive function."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
219 ;; (interactive "xCar of list: ")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
220 ;; ad-do-it
105372
bd2966850aac Use `called-interactively-p' instead of `interactive-p'.
Juanma Barranquero <lekktu@gmail.com>
parents: 105371
diff changeset
221 ;; (if (called-interactively-p 'interactive)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
222 ;; (message "%s" ad-return-value)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
223
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
224
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
225 ;; @ Advice documentation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
226 ;; =======================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
227 ;; Below is general documentation of the various features of advice. For more
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
228 ;; concrete examples check the corresponding sections in the tutorial part.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
229
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
230 ;; @@ Terminology:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
231 ;; ===============
24875
7177532e6e8b Comment fix.
Karl Heuer <kwzh@gnu.org>
parents: 23946
diff changeset
232 ;; - Emacs, Emacs-19: Emacs as released by the GNU Project
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
233 ;; - Lemacs: Lucid's version of Emacs with major version 19
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
234 ;; - v18: Any Emacs with major version 18 or built as an extension to that
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
235 ;; (such as Epoch)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
236 ;; - v19: Any Emacs with major version 19
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
237 ;; - jwz: Jamie Zawinski - former keeper of Lemacs and creator of the optimizing
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
238 ;; byte-compiler used in v19s.
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
239 ;; - Advice: The name of this package.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
240 ;; - advices: Short for "pieces of advice".
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
241
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
242 ;; @@ Defining a piece of advice with `defadvice':
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
243 ;; ===============================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
244 ;; The main means of defining a piece of advice is the macro `defadvice',
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
245 ;; there is no interactive way of specifying a piece of advice. A call to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
246 ;; `defadvice' has the following syntax which is similar to the syntax of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
247 ;; `defun/defmacro':
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
248 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
249 ;; (defadvice <function> (<class> <name> [<position>] [<arglist>] {<flags>}*)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
250 ;; [ [<documentation-string>] [<interactive-form>] ]
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
251 ;; {<body-form>}* )
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
252
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
253 ;; <function> is the name of the function/macro/subr to be advised.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
254
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
255 ;; <class> is the class of the advice which has to be one of `before',
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
256 ;; `around', `after', `activation' or `deactivation' (the last two allow
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
257 ;; definition of special act/deactivation hooks).
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
258
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
259 ;; <name> is the name of the advice which has to be a non-nil symbol.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
260 ;; Names uniquely identify a piece of advice in a certain advice class,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
261 ;; hence, advices can be redefined by defining an advice with the same class
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
262 ;; and name. Advice names are global symbols, hence, the same name space
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
263 ;; conventions used for function names should be applied.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
264
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
265 ;; An optional <position> specifies where in the current list of advices of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
266 ;; the specified <class> this new advice will be placed. <position> has to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
267 ;; be either `first', `last' or a number that specifies a zero-based
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
268 ;; position (`first' is equivalent to 0). If no position is specified
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
269 ;; `first' will be used as a default. If this call to `defadvice' redefines
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
270 ;; an already existing advice (see above) then the position argument will
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
271 ;; be ignored and the position of the already existing advice will be used.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
272
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
273 ;; An optional <arglist> which has to be a list can be used to define the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
274 ;; argument list of the advised function. This argument list should of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
275 ;; course be compatible with the argument list of the original function,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
276 ;; otherwise functions that call the advised function with the original
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
277 ;; argument list in mind will break. If more than one advice specify an
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
278 ;; argument list then the first one (the one with the smallest position)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
279 ;; found in the list of before/around/after advices will be used.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
280
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
281 ;; <flags> is a list of symbols that specify further information about the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
282 ;; advice. All flags can be specified with unambiguous initial substrings.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
283 ;; `activate': Specifies that the advice information of the advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
284 ;; function should be activated right after this advice has been
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
285 ;; defined. In forward advices `activate' will be ignored.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
286 ;; `protect': Specifies that this advice should be protected against
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
287 ;; non-local exits and errors in preceding code/advices.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
288 ;; `compile': Specifies that the advised function should be byte-compiled.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
289 ;; This flag will be ignored unless `activate' is also specified.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
290 ;; `disable': Specifies that the defined advice should be disabled, hence,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
291 ;; it will not be used in an activation until somebody enables it.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
292 ;; `preactivate': Specifies that the advised function should get preactivated
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
293 ;; at macro-expansion/compile time of this `defadvice'. This
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
294 ;; generates a compiled advised definition according to the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
295 ;; current advice state which will be used during activation
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
296 ;; if appropriate. Only use this if the `defadvice' gets
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
297 ;; actually compiled (with a v18 byte-compiler put the `defadvice'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
298 ;; into the body of a `defun' to accomplish proper compilation).
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
299
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
300 ;; An optional <documentation-string> can be supplied to document the advice.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
301 ;; On call of the `documentation' function it will be combined with the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
302 ;; documentation strings of the original function and other advices.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
303
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
304 ;; An optional <interactive-form> form can be supplied to change/add
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
305 ;; interactive behavior of the original function. If more than one advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
306 ;; has an `(interactive ...)' specification then the first one (the one
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
307 ;; with the smallest position) found in the list of before/around/after
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
308 ;; advices will be used.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
309
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
310 ;; A possibly empty list of <body-forms> specifies the body of the advice in
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
311 ;; an implicit progn. The body of an advice can access/change arguments,
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
312 ;; the return value, the binding environment, and can have all sorts of
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
313 ;; other side effects.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
314
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
315 ;; @@ Assembling advised definitions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
316 ;; ==================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
317 ;; Suppose a function/macro/subr/special-form has N pieces of before advice,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
318 ;; M pieces of around advice and K pieces of after advice. Assuming none of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
319 ;; the advices is protected, its advised definition will look like this
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
320 ;; (body-form indices correspond to the position of the respective advice in
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
321 ;; that advice class):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
322
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
323 ;; ([macro] lambda <arglist>
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
324 ;; [ [<advised-docstring>] [(interactive ...)] ]
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
325 ;; (let (ad-return-value)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
326 ;; {<before-0-body-form>}*
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
327 ;; ....
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
328 ;; {<before-N-1-body-form>}*
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
329 ;; {<around-0-body-form>}*
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
330 ;; {<around-1-body-form>}*
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
331 ;; ....
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
332 ;; {<around-M-1-body-form>}*
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
333 ;; (setq ad-return-value
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
334 ;; <apply original definition to <arglist>>)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
335 ;; {<other-around-M-1-body-form>}*
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
336 ;; ....
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
337 ;; {<other-around-1-body-form>}*
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
338 ;; {<other-around-0-body-form>}*
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
339 ;; {<after-0-body-form>}*
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
340 ;; ....
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
341 ;; {<after-K-1-body-form>}*
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
342 ;; ad-return-value))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
343
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
344 ;; Macros and special forms will be redefined as macros, hence the optional
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
345 ;; [macro] in the beginning of the definition.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
346
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
347 ;; <arglist> is either the argument list of the original function or the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
348 ;; first argument list defined in the list of before/around/after advices.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
349 ;; The values of <arglist> variables can be accessed/changed in the body of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
350 ;; an advice by simply referring to them by their original name, however,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
351 ;; more portable argument access macros are also provided (see below). For
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
352 ;; subrs/special-forms for which neither explicit argument list definitions
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
353 ;; are available, nor their documentation strings contain such definitions
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
354 ;; (as they do v19s), `(&rest ad-subr-args)' will be used.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
355
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
356 ;; <advised-docstring> is an optional, special documentation string which will
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
357 ;; be expanded into a proper documentation string upon call of `documentation'.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
358
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
359 ;; (interactive ...) is an optional interactive form either taken from the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
360 ;; original function or from a before/around/after advice. For advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
361 ;; interactive subrs that do not have an interactive form specified in any
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
362 ;; advice we have to use (interactive) and then call the subr interactively
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
363 ;; if the advised function was called interactively, because the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
364 ;; interactive specification of subrs is not accessible. This is the only
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
365 ;; case where changing the values of arguments will not have an affect
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
366 ;; because they will be reset by the interactive specification of the subr.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
367 ;; If this is a problem one can always specify an interactive form in a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
368 ;; before/around/after advice to gain control over argument values that
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
369 ;; were supplied interactively.
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
370 ;;
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
371 ;; Then the body forms of the various advices in the various classes of advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
372 ;; are assembled in order. The forms of around advice L are normally part of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
373 ;; one of the forms of around advice L-1. An around advice can specify where
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
374 ;; the forms of the wrapped or surrounded forms should go with the special
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
375 ;; keyword `ad-do-it', which will be substituted with a `progn' containing the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
376 ;; forms of the surrounded code.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
377
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
378 ;; The innermost part of the around advice onion is
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
379 ;; <apply original definition to <arglist>>
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
380 ;; whose form depends on the type of the original function. The variable
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
381 ;; `ad-return-value' will be set to its result. This variable is visible to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
382 ;; all pieces of advice which can access and modify it before it gets returned.
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
383 ;;
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
384 ;; The semantic structure of advised functions that contain protected pieces
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
385 ;; of advice is the same. The only difference is that `unwind-protect' forms
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
386 ;; make sure that the protected advice gets executed even if some previous
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
387 ;; piece of advice had an error or a non-local exit. If any around advice is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
388 ;; protected then the whole around advice onion will be protected.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
389
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
390 ;; @@ Argument access in advised functions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
391 ;; ========================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
392 ;; As already mentioned, the simplest way to access the arguments of an
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
393 ;; advised function in the body of an advice is to refer to them by name. To
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
394 ;; do that, the advice programmer needs to know either the names of the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
395 ;; argument variables of the original function, or the names used in the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
396 ;; argument list redefinition given in a piece of advice. While this simple
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
397 ;; method might be sufficient in many cases, it has the disadvantage that it
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
398 ;; is not very portable because it hardcodes the argument names into the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
399 ;; advice. If the definition of the original function changes the advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
400 ;; might break even though the code might still be correct. Situations like
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
401 ;; that arise, for example, if one advises a subr like `eval-region' which
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
402 ;; gets redefined in a non-advice style into a function by the edebug
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
403 ;; package. If the advice assumes `eval-region' to be a subr it might break
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
404 ;; once edebug is loaded. Similar situations arise when one wants to use the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
405 ;; same piece of advice across different versions of Emacs. Some subrs in a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
406 ;; v18 Emacs are functions in v19 and vice versa, but for the most part the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
407 ;; semantics remain the same, hence, the same piece of advice might be usable
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
408 ;; in both Emacs versions.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
409
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
410 ;; As a solution to that advice provides argument list access macros that get
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
411 ;; translated into the proper access forms at activation time, i.e., when the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
412 ;; advised definition gets constructed. Access macros access actual arguments
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
413 ;; by position regardless of how these actual argument get distributed onto
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
414 ;; the argument variables of a function. The rational behind this is that in
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
415 ;; Emacs Lisp the semantics of an argument is strictly determined by its
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
416 ;; position (there are no keyword arguments).
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
417
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
418 ;; Suppose the function `foo' is defined as
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
419 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
420 ;; (defun foo (x y &optional z &rest r) ....)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
421 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
422 ;; and is then called with
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
423 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
424 ;; (foo 0 1 2 3 4 5 6)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
425
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
426 ;; which means that X=0, Y=1, Z=2 and R=(3 4 5 6). The assumption is that
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
427 ;; the semantics of an actual argument is determined by its position. It is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
428 ;; this semantics that has to be known by the advice programmer. Then s/he
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
429 ;; can access these arguments in a piece of advice with some of the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
430 ;; following macros (the arrows indicate what value they will return):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
431
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
432 ;; (ad-get-arg 0) -> 0
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
433 ;; (ad-get-arg 1) -> 1
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
434 ;; (ad-get-arg 2) -> 2
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
435 ;; (ad-get-arg 3) -> 3
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
436 ;; (ad-get-args 2) -> (2 3 4 5 6)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
437 ;; (ad-get-args 4) -> (4 5 6)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
438
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
439 ;; `(ad-get-arg <position>)' will return the actual argument that was supplied
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
440 ;; at <position>, `(ad-get-args <position>)' will return the list of actual
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
441 ;; arguments supplied starting at <position>. Note that these macros can be
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
442 ;; used without any knowledge about the form of the actual argument list of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
443 ;; the original function.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
444
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
445 ;; Similarly, `(ad-set-arg <position> <value-form>)' can be used to set the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
446 ;; value of the actual argument at <position> to <value-form>. For example,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
447 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
448 ;; (ad-set-arg 5 "five")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
449 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
450 ;; will have the effect that R=(3 4 "five" 6) once the original function is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
451 ;; called. `(ad-set-args <position> <value-list-form>)' can be used to set
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
452 ;; the list of actual arguments starting at <position> to <value-list-form>.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
453 ;; For example,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
454 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
455 ;; (ad-set-args 0 '(5 4 3 2 1 0))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
456 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
457 ;; will have the effect that X=5, Y=4, Z=3 and R=(2 1 0) once the original
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
458 ;; function is called.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
459
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
460 ;; All these access macros are text macros rather than real Lisp macros. When
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
461 ;; the advised definition gets constructed they get replaced with actual access
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
462 ;; forms depending on the argument list of the advised function, i.e., after
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
463 ;; that argument access is in most cases as efficient as using the argument
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
464 ;; variable names directly.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
465
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
466 ;; @@@ Accessing argument bindings of arbitrary functions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
467 ;; =======================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
468 ;; Some functions (such as `trace-function' defined in trace.el) need a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
469 ;; method of accessing the names and bindings of the arguments of an
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
470 ;; arbitrary advised function. To do that within an advice one can use the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
471 ;; special keyword `ad-arg-bindings' which is a text macro that will be
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
472 ;; substituted with a form that will evaluate to a list of binding
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
473 ;; specifications, one for every argument variable. These binding
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
474 ;; specifications can then be examined in the body of the advice. For
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
475 ;; example, somewhere in an advice we could do this:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
476 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
477 ;; (let* ((bindings ad-arg-bindings)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
478 ;; (firstarg (car bindings))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
479 ;; (secondarg (car (cdr bindings))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
480 ;; ;; Print info about first argument
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
481 ;; (print (format "%s=%s (%s)"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
482 ;; (ad-arg-binding-field firstarg 'name)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
483 ;; (ad-arg-binding-field firstarg 'value)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
484 ;; (ad-arg-binding-field firstarg 'type)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
485 ;; ....)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
486 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
487 ;; The `type' of an argument is either `required', `optional' or `rest'.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
488 ;; Wherever `ad-arg-bindings' appears a form will be inserted that evaluates
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
489 ;; to the list of bindings, hence, in order to avoid multiple unnecessary
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
490 ;; evaluations one should always bind it to some variable.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
491
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
492 ;; @@@ Argument list mapping:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
493 ;; ==========================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
494 ;; Because `defadvice' allows the specification of the argument list of the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
495 ;; advised function we need a mapping mechanism that maps this argument list
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
496 ;; onto that of the original function. For example, somebody might specify
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
497 ;; `(sym newdef)' as the argument list of `fset', while advice might use
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
498 ;; `(&rest ad-subr-args)' as the argument list of the original function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
499 ;; (depending on what Emacs version is used). Hence SYM and NEWDEF have to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
500 ;; be properly mapped onto the &rest variable when the original definition is
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
501 ;; called. Advice automatically takes care of that mapping, hence, the advice
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
502 ;; programmer can specify an argument list without having to know about the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
503 ;; exact structure of the original argument list as long as the new argument
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
504 ;; list takes a compatible number/magnitude of actual arguments.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
505
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
506 ;; @@@ Definition of subr argument lists:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
507 ;; ======================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
508 ;; When advice constructs the advised definition of a function it has to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
509 ;; know the argument list of the original function. For functions and macros
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
510 ;; the argument list can be determined from the actual definition, however,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
511 ;; for subrs there is no such direct access available. In Lemacs and for some
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
512 ;; subrs in Emacs-19 the argument list of a subr can be determined from
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
513 ;; its documentation string, in a v18 Emacs even that is not possible. If
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
514 ;; advice cannot at all determine the argument list of a subr it uses
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
515 ;; `(&rest ad-subr-args)' which will always work but is inefficient because
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
516 ;; it conses up arguments. The macro `ad-define-subr-args' can be used by
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
517 ;; the advice programmer to explicitly tell advice about the argument list
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
518 ;; of a certain subr, for example,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
519 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
520 ;; (ad-define-subr-args 'fset '(sym newdef))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
521 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
522 ;; is used by advice itself to tell a v18 Emacs about the arguments of `fset'.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
523 ;; The following can be used to undo such a definition:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
524 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
525 ;; (ad-undefine-subr-args 'fset)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
526 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
527 ;; The argument list definition is stored on the property list of the subr
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
528 ;; name symbol. When an argument list could be determined from the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
529 ;; documentation string it will be cached under that property. The general
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
530 ;; mechanism for looking up the argument list of a subr is the following:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
531 ;; 1) look for a definition stored on the property list
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
532 ;; 2) if that failed try to infer it from the documentation string and
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
533 ;; if successful cache it on the property list
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
534 ;; 3) otherwise use `(&rest ad-subr-args)'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
535
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
536 ;; @@ Activation and deactivation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
537 ;; ===============================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
538 ;; The definition of an advised function does not change until all its advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
539 ;; gets actually activated. Activation can either happen with the `activate'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
540 ;; flag specified in the `defadvice', with an explicit call or interactive
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
541 ;; invocation of `ad-activate', or if forward advice is enabled (i.e., the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
542 ;; value of `ad-activate-on-definition' is t) at the time an already advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
543 ;; function gets defined.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
544
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
545 ;; When a function gets first activated its original definition gets saved,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
546 ;; all defined and enabled pieces of advice will get combined with the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
547 ;; original definition, the resulting definition might get compiled depending
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
548 ;; on some conditions described below, and then the function will get
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
549 ;; redefined with the advised definition. This also means that undefined
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
550 ;; functions cannot get activated even though they might be already advised.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
551
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
552 ;; The advised definition will get compiled either if `ad-activate' was called
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
553 ;; interactively with a prefix argument, or called explicitly with its second
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
554 ;; argument as t, or, if `ad-default-compilation-action' justifies it according
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
555 ;; to the current system state. If the advised definition was
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
556 ;; constructed during "preactivation" (see below) then that definition will
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
557 ;; be already compiled because it was constructed during byte-compilation of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
558 ;; the file that contained the `defadvice' with the `preactivate' flag.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
559
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
560 ;; `ad-deactivate' can be used to back-define an advised function to its
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
561 ;; original definition. It can be called interactively or directly. Because
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
562 ;; `ad-activate' caches the advised definition the function can be
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
563 ;; reactivated via `ad-activate' with only minor overhead (it is checked
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
564 ;; whether the current advice state is consistent with the cached
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
565 ;; definition, see the section on caching below).
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
566
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
567 ;; `ad-activate-regexp' and `ad-deactivate-regexp' can be used to de/activate
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
568 ;; all currently advised function that have a piece of advice with a name that
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
569 ;; contains a match for a regular expression. These functions can be used to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
570 ;; de/activate sets of functions depending on certain advice naming
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
571 ;; conventions.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
572
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
573 ;; Finally, `ad-activate-all' and `ad-deactivate-all' can be used to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
574 ;; de/activate all currently advised functions. These are useful to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
575 ;; (temporarily) return to an un/advised state.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
576
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
577 ;; @@@ Reasons for the separation of advice definition and activation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
578 ;; ===================================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
579 ;; As already mentioned, advising happens in two stages:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
580
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
581 ;; 1) definition of various pieces of advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
582 ;; 2) activation of all advice currently defined and enabled
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
583
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
584 ;; The advantage of this is that various pieces of advice can be defined
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
585 ;; before they get combined into an advised definition which avoids
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
586 ;; unnecessary constructions of intermediate advised definitions. The more
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
587 ;; important advantage is that it allows the implementation of forward advice.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
588 ;; Advice information for a certain function accumulates as the value of the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
589 ;; `advice-info' property of the function symbol. This accumulation is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
590 ;; completely independent of the fact that that function might not yet be
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
591 ;; defined. The special forms `defun' and `defmacro' have been advised to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
592 ;; check whether the function/macro they defined had advice information
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
593 ;; associated with it. If so and forward advice is enabled, the original
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
594 ;; definition will be saved, and then the advice will be activated. When a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
595 ;; file is loaded in a v18 Emacs the functions/macros it defines are also
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
596 ;; defined with calls to `defun/defmacro'. Hence, we can forward advise
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
597 ;; functions/macros which will be defined later during a load/autoload of some
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
598 ;; file (for compiled files generated by jwz's byte-compiler in a v19 Emacs
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
599 ;; this is slightly more complicated but the basic idea is the same).
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
600
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
601 ;; @@ Enabling/disabling pieces or sets of advice:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
602 ;; ===============================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
603 ;; A major motivation for the development of this advice package was to bring
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
604 ;; a little bit more structure into the function overloading chaos in Emacs
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
605 ;; Lisp. Many packages achieve some of their functionality by adding a little
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
606 ;; bit (or a lot) to the standard functionality of some Emacs Lisp function.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
607 ;; ange-ftp is a very popular package that achieves its magic by overloading
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
608 ;; most Emacs Lisp functions that deal with files. A popular function that's
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
609 ;; overloaded by many packages is `expand-file-name'. The situation that one
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
610 ;; function is multiply overloaded can arise easily.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
611
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
612 ;; Once in a while it would be desirable to be able to disable some/all
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
613 ;; overloads of a particular package while keeping all the rest. Ideally -
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
614 ;; at least in my opinion - these overloads would all be done with advice,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
615 ;; I know I am dreaming right now... In that ideal case the enable/disable
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
616 ;; mechanism of advice could be used to achieve just that.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
617
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
618 ;; Every piece of advice is associated with an enablement flag. When the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
619 ;; advised definition of a particular function gets constructed (e.g., during
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
620 ;; activation) only the currently enabled pieces of advice will be considered.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
621 ;; This mechanism allows one to have different "views" of an advised function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
622 ;; dependent on what pieces of advice are currently enabled.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
623
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
624 ;; Another motivation for this mechanism is that it allows one to define a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
625 ;; piece of advice for some function yet keep it dormant until a certain
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
626 ;; condition is met. Until then activation of the function will not make use
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
627 ;; of that piece of advice. Once the condition is met the advice can be
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
628 ;; enabled and a reactivation of the function will add its functionality as
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
629 ;; part of the new advised definition. For example, the advices of `defun'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
630 ;; etc. used by advice itself will stay disabled until `ad-start-advice' is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
631 ;; called and some variables have the proper values. Hence, if somebody
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
632 ;; else advised these functions too and activates them the advices defined
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
633 ;; by advice will get used only if they are intended to be used.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
634
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
635 ;; The main interface to this mechanism are the interactive functions
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
636 ;; `ad-enable-advice' and `ad-disable-advice'. For example, the following
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
637 ;; would disable a particular advice of the function `foo':
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
638 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
639 ;; (ad-disable-advice 'foo 'before 'my-advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
640 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
641 ;; This call by itself only changes the flag, to get the proper effect in
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
642 ;; the advised definition too one has to activate `foo' with
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
643 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
644 ;; (ad-activate 'foo)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
645 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
646 ;; or interactively. To disable whole sets of advices one can use a regular
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
647 ;; expression mechanism. For example, let us assume that ange-ftp actually
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
648 ;; used advice to overload all its functions, and that it used the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
649 ;; "ange-ftp-" prefix for all its advice names, then we could temporarily
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
650 ;; disable all its advices with
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
651 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
652 ;; (ad-disable-regexp "^ange-ftp-")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
653 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
654 ;; and the following call would put that actually into effect:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
655 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
656 ;; (ad-activate-regexp "^ange-ftp-")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
657 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
658 ;; A saver way would have been to use
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
659 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
660 ;; (ad-update-regexp "^ange-ftp-")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
661 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
662 ;; instead which would have only reactivated currently actively advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
663 ;; functions, but not functions that were currently deactivated. All these
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
664 ;; functions can also be called interactively.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
665
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
666 ;; A certain piece of advice is considered a match if its name contains a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
667 ;; match for the regular expression. To enable ange-ftp again we would use
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
668 ;; `ad-enable-regexp' and then activate or update again.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
669
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
670 ;; @@ Forward advice, automatic advice activation:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
671 ;; ===============================================
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
672 ;; Because most Emacs Lisp packages are loaded on demand via an autoload
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
673 ;; mechanism it is essential to be able to "forward advise" functions.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
674 ;; Otherwise, proper advice definition and activation would make it necessary
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
675 ;; to preload every file that defines a certain function before it can be
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
676 ;; advised, which would partly defeat the purpose of the advice mechanism.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
677
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
678 ;; In the following, "forward advice" always implies its automatic activation
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
679 ;; once a function gets defined, and not just the accumulation of advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
680 ;; information for a possibly undefined function.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
681
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
682 ;; Advice implements forward advice mainly via the following: 1) Separation
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
683 ;; of advice definition and activation that makes it possible to accumulate
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
684 ;; advice information without having the original function already defined,
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
685 ;; 2) special versions of the built-in functions `fset/defalias' which check
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
686 ;; for advice information whenever they define a function. If advice
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
687 ;; information was found then the advice will immediately get activated when
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
688 ;; the function gets defined.
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
689
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
690 ;; Automatic advice activation means, that whenever a function gets defined
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
691 ;; with either `defun', `defmacro', `fset' or by loading a byte-compiled
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
692 ;; file, and the function has some advice-info stored with it then that
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
693 ;; advice will get activated right away.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
694
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
695 ;; @@@ Enabling automatic advice activation:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
696 ;; =========================================
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
697 ;; Automatic advice activation is enabled by default. It can be disabled by
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
698 ;; doint `M-x ad-stop-advice' and enabled again with `M-x ad-start-advice'.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
699
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
700 ;; @@ Caching of advised definitions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
701 ;; ==================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
702 ;; After an advised definition got constructed it gets cached as part of the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
703 ;; advised function's advice-info so it can be reused, for example, after an
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
704 ;; intermediate deactivation. Because the advice-info of a function might
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
705 ;; change between the time of caching and reuse a cached definition gets
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
706 ;; a cache-id associated with it so it can be verified whether the cached
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
707 ;; definition is still valid (the main application of this is preactivation
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
708 ;; - see below).
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
709
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
710 ;; When an advised function gets activated and a verifiable cached definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
711 ;; is available, then that definition will be used instead of creating a new
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
712 ;; advised definition from scratch. If you want to make sure that a new
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
713 ;; definition gets constructed then you should use `ad-clear-cache' before you
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
714 ;; activate the advised function.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
715
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
716 ;; @@ Preactivation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
717 ;; =================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
718 ;; Constructing an advised definition is moderately expensive. In a situation
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
719 ;; where one package defines a lot of advised functions it might be
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
720 ;; prohibitively expensive to do all the advised definition construction at
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
721 ;; runtime. Preactivation is a mechanism that allows compile-time construction
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
722 ;; of compiled advised definitions that can be activated cheaply during
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
723 ;; runtime. Preactivation uses the caching mechanism to do that. Here's how it
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
724 ;; works:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
725
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
726 ;; When the byte-compiler compiles a `defadvice' that has the `preactivate'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
727 ;; flag specified, it uses the current original definition of the advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
728 ;; function plus the advice specified in this `defadvice' (even if it is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
729 ;; specified as disabled) and all other currently enabled pieces of advice to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
730 ;; construct an advised definition and an identifying cache-id and makes them
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
731 ;; part of the `defadvice' expansion which will then be compiled by the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
732 ;; byte-compiler (to ensure that in a v18 emacs you have to put the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
733 ;; `defadvice' inside a `defun' to get it compiled and then you have to call
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
734 ;; that compiled `defun' in order to actually execute the `defadvice'). When
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
735 ;; the file with the compiled, preactivating `defadvice' gets loaded the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
736 ;; precompiled advised definition will be cached on the advised function's
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
737 ;; advice-info. When it gets activated (can be immediately on execution of the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
738 ;; `defadvice' or any time later) the cache-id gets checked against the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
739 ;; current state of advice and if it is verified the precompiled definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
740 ;; will be used directly (the verification is pretty cheap). If it couldn't get
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
741 ;; verified a new advised definition for that function will be built from
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
742 ;; scratch, hence, the efficiency added by the preactivation mechanism does
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
743 ;; not at all impair the flexibility of the advice mechanism.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
744
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
745 ;; MORAL: In order get all the efficiency out of preactivation the advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
746 ;; state of an advised function at the time the file with the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
747 ;; preactivating `defadvice' gets byte-compiled should be exactly
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
748 ;; the same as it will be when the advice of that function gets
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
749 ;; actually activated. If it is not there is a high chance that the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
750 ;; cache-id will not match and hence a new advised definition will
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
751 ;; have to be constructed at runtime.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
752
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
753 ;; Preactivation and forward advice do not contradict each other. It is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
754 ;; perfectly ok to load a file with a preactivating `defadvice' before the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
755 ;; original definition of the advised function is available. The constructed
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
756 ;; advised definition will be used once the original function gets defined and
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
757 ;; its advice gets activated. The only constraint is that at the time the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
758 ;; file with the preactivating `defadvice' got compiled the original function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
759 ;; definition was available.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
760
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
761 ;; TIPS: Here are some indications that a preactivation did not work the way
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
762 ;; you intended it to work:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
763 ;; - Activation of the advised function takes longer than usual/expected
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
764 ;; - The byte-compiler gets loaded while an advised function gets
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
765 ;; activated
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
766 ;; - `byte-compile' is part of the `features' variable even though you
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
767 ;; did not use the byte-compiler
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
768 ;; Right now advice does not provide an elegant way to find out whether
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
769 ;; and why a preactivation failed. What you can do is to trace the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
770 ;; function `ad-cache-id-verification-code' (with the function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
771 ;; `trace-function-background' defined in my trace.el package) before
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
772 ;; any of your advised functions get activated. After they got
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
773 ;; activated check whether all calls to `ad-cache-id-verification-code'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
774 ;; returned `verified' as a result. Other values indicate why the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
775 ;; verification failed which should give you enough information to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
776 ;; fix your preactivation/compile/load/activation sequence.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
777
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
778 ;; IMPORTANT: There is one case (that I am aware of) that can make
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
779 ;; preactivation fail, i.e., a preconstructed advised definition that does
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
780 ;; NOT match the current state of advice gets used nevertheless. That case
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
781 ;; arises if one package defines a certain piece of advice which gets used
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
782 ;; during preactivation, and another package incompatibly redefines that
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
783 ;; very advice (i.e., same function/class/name), and it is the second advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
784 ;; that is available when the preconstructed definition gets activated, and
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
785 ;; that was the only definition of that advice so far (`ad-add-advice'
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
786 ;; catches advice redefinitions and clears the cache in such a case).
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
787 ;; Catching that would make the cache verification too expensive.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
788
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
789 ;; MORAL-II: Redefining somebody else's advice is BAAAAD (to speak with
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
790 ;; George Walker Bush), and why would you redefine your own advice anyway?
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
791 ;; Advice is a mechanism to facilitate function redefinition, not advice
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
792 ;; redefinition (wait until I write Meta-Advice :-). If you really have
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
793 ;; to undo somebody else's advice try to write a "neutralizing" advice.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
794
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
795 ;; @@ Advising macros and special forms and other dangerous things:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
796 ;; ================================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
797 ;; Look at the corresponding tutorial sections for more information on
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
798 ;; these topics. Here it suffices to point out that the special treatment
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
799 ;; of macros and special forms by the byte-compiler can lead to problems
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
800 ;; when they get advised. Macros can create problems because they get
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
801 ;; expanded at compile time, hence, they might not have all the necessary
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
802 ;; runtime support and such advice cannot be de/activated or changed as
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
803 ;; it is possible for functions. Special forms create problems because they
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
804 ;; have to be advised "into" macros, i.e., an advised special form is a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
805 ;; implemented as a macro, hence, in most cases the byte-compiler will
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
806 ;; not recognize it as a special form anymore which can lead to very strange
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
807 ;; results.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
808 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
809 ;; MORAL: - Only advise macros or special forms when you are absolutely sure
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
810 ;; what you are doing.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
811 ;; - As a safety measure, always do `ad-deactivate-all' before you
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
812 ;; byte-compile a file to make sure that even if some inconsiderate
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
813 ;; person advised some special forms you'll get proper compilation
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
814 ;; results. After compilation do `ad-activate-all' to get back to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
815 ;; the previous state.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
816
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
817 ;; @@ Adding a piece of advice with `ad-add-advice':
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
818 ;; =================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
819 ;; The non-interactive function `ad-add-advice' can be used to add a piece of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
820 ;; advice to some function without using `defadvice'. This is useful if advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
821 ;; has to be added somewhere by a function (also look at `ad-make-advice').
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
822
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
823 ;; @@ Activation/deactivation advices, file load hooks:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
824 ;; ====================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
825 ;; There are two special classes of advice called `activation' and
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
826 ;; `deactivation'. The body forms of these advices are not included into the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
827 ;; advised definition of a function, rather they are assembled into a hook
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
828 ;; form which will be evaluated whenever the advice-info of the advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
829 ;; function gets activated or deactivated. One application of this mechanism
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
830 ;; is to define file load hooks for files that do not provide such hooks
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
831 ;; (v19s already come with a general file-load-hook mechanism, v18s don't).
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
832 ;; For example, suppose you want to print a message whenever `file-x' gets
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
833 ;; loaded, and suppose the last function defined in `file-x' is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
834 ;; `file-x-last-fn'. Then we can define the following advice:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
835 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
836 ;; (defadvice file-x-last-fn (activation file-x-load-hook)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
837 ;; "Executed whenever file-x is loaded"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
838 ;; (if load-in-progress (message "Loaded file-x")))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
839 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
840 ;; This will constitute a forward advice for function `file-x-last-fn' which
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
841 ;; will get activated when `file-x' is loaded (only if forward advice is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
842 ;; enabled of course). Because there are no "real" pieces of advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
843 ;; available for it, its definition will not be changed, but the activation
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
844 ;; advice will be run during its activation which is equivalent to having a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
845 ;; file load hook for `file-x'.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
846
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
847 ;; @@ Summary of main advice concepts:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
848 ;; ===================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
849 ;; - Definition:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
850 ;; A piece of advice gets defined with `defadvice' and added to the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
851 ;; `advice-info' property of a function.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
852 ;; - Enablement:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
853 ;; Every piece of advice has an enablement flag associated with it. Only
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
854 ;; enabled advices are considered during construction of an advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
855 ;; definition.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
856 ;; - Activation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
857 ;; Redefine an advised function with its advised definition. Constructs
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
858 ;; an advised definition from scratch if no verifiable cached advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
859 ;; definition is available and caches it.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
860 ;; - Deactivation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
861 ;; Back-define an advised function to its original definition.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
862 ;; - Update:
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
863 ;; Reactivate an advised function but only if its advice is currently
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
864 ;; active. This can be used to bring all currently advised function up
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
865 ;; to date with the current state of advice without also activating
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
866 ;; currently deactivated functions.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
867 ;; - Caching:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
868 ;; Is the saving of an advised definition and an identifying cache-id so
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
869 ;; it can be reused, for example, for activation after deactivation.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
870 ;; - Preactivation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
871 ;; Is the construction of an advised definition according to the current
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
872 ;; state of advice during byte-compilation of a file with a preactivating
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
873 ;; `defadvice'. That advised definition can then rather cheaply be used
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
874 ;; during activation without having to construct an advised definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
875 ;; from scratch at runtime.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
876
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
877 ;; @@ Summary of interactive advice manipulation functions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
878 ;; ========================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
879 ;; The following interactive functions can be used to manipulate the state
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
880 ;; of advised functions (all of them support completion on function names,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
881 ;; advice classes and advice names):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
882
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
883 ;; - ad-activate to activate the advice of a FUNCTION
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
884 ;; - ad-deactivate to deactivate the advice of a FUNCTION
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
885 ;; - ad-update to activate the advice of a FUNCTION unless it was not
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
886 ;; yet activated or is currently deactivated.
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
887 ;; - ad-unadvise deactivates a FUNCTION and removes all of its advice
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
888 ;; information, hence, it cannot be activated again
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
889 ;; - ad-recover tries to redefine a FUNCTION to its original definition and
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
890 ;; discards all advice information (a low-level `ad-unadvise').
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
891 ;; Use only in emergencies.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
892
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
893 ;; - ad-remove-advice removes a particular piece of advice of a FUNCTION.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
894 ;; You still have to do call `ad-activate' or `ad-update' to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
895 ;; activate the new state of advice.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
896 ;; - ad-enable-advice enables a particular piece of advice of a FUNCTION.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
897 ;; - ad-disable-advice disables a particular piece of advice of a FUNCTION.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
898 ;; - ad-enable-regexp maps over all currently advised functions and enables
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
899 ;; every advice whose name contains a match for a regular
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
900 ;; expression.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
901 ;; - ad-disable-regexp disables matching advices.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
902
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
903 ;; - ad-activate-regexp activates all advised function with a matching advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
904 ;; - ad-deactivate-regexp deactivates all advised function with matching advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
905 ;; - ad-update-regexp updates all advised function with a matching advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
906 ;; - ad-activate-all activates all advised functions
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
907 ;; - ad-deactivate-all deactivates all advised functions
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
908 ;; - ad-update-all updates all advised functions
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
909 ;; - ad-unadvise-all unadvises all advised functions
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
910 ;; - ad-recover-all recovers all advised functions
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
911
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
912 ;; - ad-compile byte-compiles a function/macro if it is compilable.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
913
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
914 ;; @@ Summary of forms with special meanings when used within an advice:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
915 ;; =====================================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
916 ;; ad-return-value name of the return value variable (get/settable)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
917 ;; ad-subr-args name of &rest argument variable used for advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
918 ;; subrs whose actual argument list cannot be
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
919 ;; determined (get/settable)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
920 ;; (ad-get-arg <pos>), (ad-get-args <pos>),
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
921 ;; (ad-set-arg <pos> <value>), (ad-set-args <pos> <value-list>)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
922 ;; argument access text macros to get/set the values of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
923 ;; actual arguments at a certain position
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
924 ;; ad-arg-bindings text macro that returns the actual names, values
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
925 ;; and types of the arguments as a list of bindings. The
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
926 ;; order of the bindings corresponds to the order of the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
927 ;; arguments. The individual fields of every binding (name,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
928 ;; value and type) can be accessed with the function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
929 ;; `ad-arg-binding-field' (see example above).
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
930 ;; ad-do-it text macro that identifies the place where the original
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
931 ;; or wrapped definition should go in an around advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
932
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
933
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
934 ;; @ Foo games: An advice tutorial
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
935 ;; ===============================
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
936 ;; The following tutorial was created in Emacs 18.59. Left-justified
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
937 ;; s-expressions are input forms followed by one or more result forms.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
938 ;; First we have to start the advice magic:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
939 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
940 ;; (ad-start-advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
941 ;; nil
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
942 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
943 ;; We start by defining an innocent looking function `foo' that simply
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
944 ;; adds 1 to its argument X:
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
945 ;;
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
946 ;; (defun foo (x)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
947 ;; "Add 1 to X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
948 ;; (1+ x))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
949 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
950 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
951 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
952 ;; 4
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
953 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
954 ;; @@ Defining a simple piece of advice:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
955 ;; =====================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
956 ;; Now let's define the first piece of advice for `foo'. To do that we
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
957 ;; use the macro `defadvice' which takes a function name, a list of advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
958 ;; specifiers and a list of body forms as arguments. The first element of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
959 ;; the advice specifiers is the class of the advice, the second is its name,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
960 ;; the third its position and the rest are some flags. The class of our
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
961 ;; first advice is `before', its name is `fg-add2', its position among the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
962 ;; currently defined before advices (none so far) is `first', and the advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
963 ;; will be `activate'ed immediately. Advice names are global symbols, hence,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
964 ;; the name space conventions used for function names should be applied. All
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
965 ;; advice names in this tutorial will be prefixed with `fg' for `Foo Games'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
966 ;; (because everybody has the right to be inconsistent all the function names
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
967 ;; used in this tutorial do NOT follow this convention).
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
968 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
969 ;; In the body of an advice we can refer to the argument variables of the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
970 ;; original function by name. Here we add 1 to X so the effect of calling
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
971 ;; `foo' will be to actually add 2. All of the advice definitions below only
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
972 ;; have one body form for simplicity, but there is no restriction to that
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
973 ;; extent. Every piece of advice can have a documentation string which will
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
974 ;; be combined with the documentation of the original function.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
975 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
976 ;; (defadvice foo (before fg-add2 first activate)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
977 ;; "Add 2 to X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
978 ;; (setq x (1+ x)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
979 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
980 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
981 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
982 ;; 5
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
983 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
984 ;; @@ Specifying the position of an advice:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
985 ;; ========================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
986 ;; Now we define the second before advice which will cancel the effect of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
987 ;; the previous advice. This time we specify the position as 0 which is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
988 ;; equivalent to `first'. A number can be used to specify the zero-based
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
989 ;; position of an advice among the list of advices in the same class. This
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
990 ;; time we already have one before advice hence the position specification
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
991 ;; actually has an effect. So, after the following definition the position
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
992 ;; of the previous advice will be 1 even though we specified it with `first'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
993 ;; above, the reason for this is that the position argument is relative to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
994 ;; the currently defined pieces of advice which by now has changed.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
995 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
996 ;; (defadvice foo (before fg-cancel-add2 0 activate)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
997 ;; "Again only add 1 to X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
998 ;; (setq x (1- x)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
999 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1000 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1001 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1002 ;; 4
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1003 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1004 ;; @@ Redefining a piece of advice:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1005 ;; ================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1006 ;; Now we define an advice with the same class and same name but with a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1007 ;; different position. Defining an advice in a class in which an advice with
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1008 ;; that name already exists is interpreted as a redefinition of that
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1009 ;; particular advice, in which case the position argument will be ignored
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1010 ;; and the previous position of the redefined piece of advice is used.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1011 ;; Advice flags can be specified with non-ambiguous initial substrings, hence,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1012 ;; from now on we'll use `act' instead of the verbose `activate'.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1013 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1014 ;; (defadvice foo (before fg-cancel-add2 last act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1015 ;; "Again only add 1 to X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1016 ;; (setq x (1- x)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1017 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1018 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1019 ;; @@ Assembly of advised documentation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1020 ;; =====================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1021 ;; The documentation strings of the various pieces of advice are assembled
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1022 ;; in order which shows that advice `fg-cancel-add2' is still the first
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1023 ;; `before' advice even though we specified position `last' above:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1024 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1025 ;; (documentation 'foo)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1026 ;; "Add 1 to X.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1027 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1028 ;; This function is advised with the following advice(s):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1029 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1030 ;; fg-cancel-add2 (before):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1031 ;; Again only add 1 to X.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1032 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1033 ;; fg-add2 (before):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1034 ;; Add 2 to X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1035 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1036 ;; @@ Advising interactive behavior:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1037 ;; =================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1038 ;; We can make a function interactive (or change its interactive behavior)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1039 ;; by specifying an interactive form in one of the before or around
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1040 ;; advices (there could also be body forms in this advice). The particular
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1041 ;; definition always assigns 5 as an argument to X which gives us 6 as a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1042 ;; result when we call foo interactively:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1043 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1044 ;; (defadvice foo (before fg-inter last act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1045 ;; "Use 5 as argument when called interactively."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1046 ;; (interactive (list 5)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1047 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1048 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1049 ;; (call-interactively 'foo)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1050 ;; 6
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1051 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1052 ;; If more than one advice have an interactive declaration, then the one of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1053 ;; the advice with the smallest position will be used (before advices go
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1054 ;; before around and after advices), hence, the declaration below does
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1055 ;; not have any effect:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1056 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1057 ;; (defadvice foo (before fg-inter2 last act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1058 ;; (interactive (list 6)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1059 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1060 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1061 ;; (call-interactively 'foo)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1062 ;; 6
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1063 ;;
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1064 ;; Let's have a look at what the definition of `foo' looks like now
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1065 ;; (indentation added by hand for legibility):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1066 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1067 ;; (symbol-function 'foo)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1068 ;; (lambda (x)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1069 ;; "$ad-doc: foo$"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1070 ;; (interactive (list 5))
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1071 ;; (let (ad-return-value)
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1072 ;; (setq x (1- x))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1073 ;; (setq x (1+ x))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1074 ;; (setq ad-return-value (ad-Orig-foo x))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1075 ;; ad-return-value))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1076 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1077 ;; @@ Around advices:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1078 ;; ==================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1079 ;; Now we'll try some `around' advices. An around advice is a wrapper around
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1080 ;; the original definition. It can shadow or establish bindings for the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1081 ;; original definition, and it can look at and manipulate the value returned
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1082 ;; by the original function. The position of the special keyword `ad-do-it'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1083 ;; specifies where the code of the original function will be executed. The
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1084 ;; keyword can appear multiple times which will result in multiple calls of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1085 ;; the original function in the resulting advised code. Note, that if we don't
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1086 ;; specify a position argument (i.e., `first', `last' or a number), then
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1087 ;; `first' (or 0) is the default):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1088 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1089 ;; (defadvice foo (around fg-times-2 act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1090 ;; "First double X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1091 ;; (let ((x (* x 2)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1092 ;; ad-do-it))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1093 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1094 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1095 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1096 ;; 7
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1097 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1098 ;; Around advices are assembled like onion skins where the around advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1099 ;; with position 0 is the outermost skin and the advice at the last position
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1100 ;; is the innermost skin which is directly wrapped around the call of the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1101 ;; original definition of the function. Hence, after the next `defadvice' we
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1102 ;; will first multiply X by 2 then add 1 and then call the original
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1103 ;; definition (i.e., add 1 again):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1104 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1105 ;; (defadvice foo (around fg-add-1 last act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1106 ;; "Add 1 to X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1107 ;; (let ((x (1+ x)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1108 ;; ad-do-it))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1109 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1110 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1111 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1112 ;; 8
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1113 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1114 ;; Again, let's see what the definition of `foo' looks like so far:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1115 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1116 ;; (symbol-function 'foo)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1117 ;; (lambda (x)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1118 ;; "$ad-doc: foo$"
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1119 ;; (interactive (list 5))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1120 ;; (let (ad-return-value)
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1121 ;; (setq x (1- x))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1122 ;; (setq x (1+ x))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1123 ;; (let ((x (* x 2)))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1124 ;; (let ((x (1+ x)))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1125 ;; (setq ad-return-value (ad-Orig-foo x))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1126 ;; ad-return-value))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1127 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1128 ;; @@ Controlling advice activation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1129 ;; =================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1130 ;; In every `defadvice' so far we have used the flag `activate' to activate
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1131 ;; the advice immediately after its definition, and that's what we want in
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1132 ;; most cases. However, if we define multiple pieces of advice for a single
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1133 ;; function then activating every advice immediately is inefficient. A
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1134 ;; better way to do this is to only activate the last defined advice.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1135 ;; For example:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1136 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1137 ;; (defadvice foo (after fg-times-x)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1138 ;; "Multiply the result with X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1139 ;; (setq ad-return-value (* ad-return-value x)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1140 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1141 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1142 ;; This still yields the same result as before:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1143 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1144 ;; 8
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1145 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1146 ;; Now we define another advice and activate which will also activate the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1147 ;; previous advice `fg-times-x'. Note the use of the special variable
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1148 ;; `ad-return-value' in the body of the advice which is set to the result of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1149 ;; the original function. If we change its value then the value returned by
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1150 ;; the advised function will be changed accordingly:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1151 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1152 ;; (defadvice foo (after fg-times-x-again act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1153 ;; "Again multiply the result with X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1154 ;; (setq ad-return-value (* ad-return-value x)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1155 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1156 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1157 ;; Now the advices have an effect:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1158 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1159 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1160 ;; 72
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1161 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1162 ;; @@ Protecting advice execution:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1163 ;; ===============================
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1164 ;; Once in a while we define an advice to perform some cleanup action,
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1165 ;; for example:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1166 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1167 ;; (defadvice foo (after fg-cleanup last act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1168 ;; "Do some cleanup."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1169 ;; (print "Let's clean up now!"))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1170 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1171 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1172 ;; However, in case of an error the cleanup won't be performed:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1173 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1174 ;; (condition-case error
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1175 ;; (foo t)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1176 ;; (error 'error-in-foo))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1177 ;; error-in-foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1178 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1179 ;; To make sure a certain piece of advice gets executed even if some error or
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1180 ;; non-local exit occurred in any preceding code, we can protect it by using
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1181 ;; the `protect' keyword. (if any of the around advices is protected then the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1182 ;; whole around advice onion will be protected):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1183 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1184 ;; (defadvice foo (after fg-cleanup prot act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1185 ;; "Do some protected cleanup."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1186 ;; (print "Let's clean up now!"))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1187 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1188 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1189 ;; Now the cleanup form will be executed even in case of an error:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1190 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1191 ;; (condition-case error
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1192 ;; (foo t)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1193 ;; (error 'error-in-foo))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1194 ;; "Let's clean up now!"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1195 ;; error-in-foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1196 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1197 ;; Again, let's see what `foo' looks like:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1198 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1199 ;; (symbol-function 'foo)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1200 ;; (lambda (x)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1201 ;; "$ad-doc: foo$"
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1202 ;; (interactive (list 5))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1203 ;; (let (ad-return-value)
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1204 ;; (unwind-protect
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1205 ;; (progn (setq x (1- x))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1206 ;; (setq x (1+ x))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1207 ;; (let ((x (* x 2)))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1208 ;; (let ((x (1+ x)))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1209 ;; (setq ad-return-value (ad-Orig-foo x))))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1210 ;; (setq ad-return-value (* ad-return-value x))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1211 ;; (setq ad-return-value (* ad-return-value x)))
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1212 ;; (print "Let's clean up now!"))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1213 ;; ad-return-value))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1214 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1215 ;; @@ Compilation of advised definitions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1216 ;; ======================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1217 ;; Finally, we can specify the `compile' keyword in a `defadvice' to say
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1218 ;; that we want the resulting advised function to be byte-compiled
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1219 ;; (`compile' will be ignored unless we also specified `activate'):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1220 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1221 ;; (defadvice foo (after fg-cleanup prot act comp)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1222 ;; "Do some protected cleanup."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1223 ;; (print "Let's clean up now!"))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1224 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1225 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1226 ;; Now `foo' is byte-compiled:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1227 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1228 ;; (symbol-function 'foo)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1229 ;; (lambda (x)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1230 ;; "$ad-doc: foo$"
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1231 ;; (interactive (byte-code "....." [5] 1))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1232 ;; (byte-code "....." [ad-return-value x nil ((byte-code "....." [print "Let's clean up now!"] 2)) * 2 ad-Orig-foo] 6))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1233 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1234 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1235 ;; "Let's clean up now!"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1236 ;; 72
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1237 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1238 ;; @@ Enabling and disabling pieces of advice:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1239 ;; ===========================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1240 ;; Once in a while it is desirable to temporarily disable a piece of advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1241 ;; so that it won't be considered during activation, for example, if two
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1242 ;; different packages advise the same function and one wants to temporarily
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1243 ;; neutralize the effect of the advice of one of the packages.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1244 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1245 ;; The following disables the after advice `fg-times-x' in the function `foo'.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1246 ;; All that does is to change a flag for this particular advice. All the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1247 ;; other information defining it will be left unchanged (e.g., its relative
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1248 ;; position in this advice class, etc.).
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1249 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1250 ;; (ad-disable-advice 'foo 'after 'fg-times-x)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1251 ;; nil
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1252 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1253 ;; For this to have an effect we have to activate `foo':
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1254 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1255 ;; (ad-activate 'foo)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1256 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1257 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1258 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1259 ;; "Let's clean up now!"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1260 ;; 24
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1261 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1262 ;; If we want to disable all multiplication advices in `foo' we can use a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1263 ;; regular expression that matches the names of such advices. Actually, any
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1264 ;; advice name that contains a match for the regular expression will be
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1265 ;; called a match. A special advice class `any' can be used to consider
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1266 ;; all advice classes:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1267 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1268 ;; (ad-disable-advice 'foo 'any "^fg-.*times")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1269 ;; nil
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1270 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1271 ;; (ad-activate 'foo)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1272 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1273 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1274 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1275 ;; "Let's clean up now!"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1276 ;; 5
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1277 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1278 ;; To enable the disabled advice we could use either `ad-enable-advice'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1279 ;; similar to `ad-disable-advice', or as an alternative `ad-enable-regexp'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1280 ;; which will enable matching advices in ALL currently advised functions.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1281 ;; Hence, this can be used to dis/enable advices made by a particular
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1282 ;; package to a set of functions as long as that package obeys standard
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1283 ;; advice name conventions. We prefixed all advice names with `fg-', hence
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1284 ;; the following will do the trick (`ad-enable-regexp' returns the number
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1285 ;; of matched advices):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1286 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1287 ;; (ad-enable-regexp "^fg-")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1288 ;; 9
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1289 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1290 ;; The following will activate all currently active advised functions that
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1291 ;; contain some advice matched by the regular expression. This is a save
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1292 ;; way to update the activation of advised functions whose advice changed
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1293 ;; in some way or other without accidentally also activating currently
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1294 ;; deactivated functions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1295 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1296 ;; (ad-update-regexp "^fg-")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1297 ;; nil
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1298 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1299 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1300 ;; "Let's clean up now!"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1301 ;; 72
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1302 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1303 ;; Another use for the dis/enablement mechanism is to define a piece of advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1304 ;; and keep it "dormant" until a particular condition is satisfied, i.e., until
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1305 ;; then the advice will not be used during activation. The `disable' flag lets
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1306 ;; one do that with `defadvice':
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1307 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1308 ;; (defadvice foo (before fg-1-more dis)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1309 ;; "Add yet 1 more."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1310 ;; (setq x (1+ x)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1311 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1312 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1313 ;; (ad-activate 'foo)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1314 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1315 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1316 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1317 ;; "Let's clean up now!"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1318 ;; 72
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1319 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1320 ;; (ad-enable-advice 'foo 'before 'fg-1-more)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1321 ;; nil
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1322 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1323 ;; (ad-activate 'foo)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1324 ;; foo
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1325 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1326 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1327 ;; "Let's clean up now!"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1328 ;; 160
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1329 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1330 ;; @@ Caching:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1331 ;; ===========
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1332 ;; Advised definitions get cached to allow efficient activation/deactivation
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1333 ;; without having to reconstruct them if nothing in the advice-info of a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1334 ;; function has changed. The following idiom can be used to temporarily
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1335 ;; deactivate functions that have a piece of advice defined by a certain
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1336 ;; package (we save the old definition to check out caching):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1337 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1338 ;; (setq old-definition (symbol-function 'foo))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1339 ;; (lambda (x) ....)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1340 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1341 ;; (ad-deactivate-regexp "^fg-")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1342 ;; nil
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1343 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1344 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1345 ;; 4
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1346 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1347 ;; (ad-activate-regexp "^fg-")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1348 ;; nil
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1349 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1350 ;; (eq old-definition (symbol-function 'foo))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1351 ;; t
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1352 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1353 ;; (foo 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1354 ;; "Let's clean up now!"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1355 ;; 160
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1356 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1357 ;; @@ Forward advice:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1358 ;; ==================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1359 ;; To enable automatic activation of forward advice we first have to set
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1360 ;; `ad-activate-on-definition' to t and restart advice:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1361 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1362 ;; (setq ad-activate-on-definition t)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1363 ;; t
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1364 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1365 ;; (ad-start-advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1366 ;; (ad-activate-defined-function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1367 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1368 ;; Let's define a piece of advice for an undefined function:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1369 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1370 ;; (defadvice bar (before fg-sub-1-more act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1371 ;; "Subtract one more from X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1372 ;; (setq x (1- x)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1373 ;; bar
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1374 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1375 ;; `bar' is not yet defined:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1376 ;; (fboundp 'bar)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1377 ;; nil
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1378 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1379 ;; Now we define it and the forward advice will get activated (only because
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1380 ;; `ad-activate-on-definition' was t when we started advice above with
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1381 ;; `ad-start-advice'):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1382 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1383 ;; (defun bar (x)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1384 ;; "Subtract 1 from X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1385 ;; (1- x))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1386 ;; bar
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1387 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1388 ;; (bar 4)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1389 ;; 2
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1390 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1391 ;; Redefinition will activate any available advice if the value of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1392 ;; `ad-redefinition-action' is either `warn', `accept' or `discard':
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1393 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1394 ;; (defun bar (x)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1395 ;; "Subtract 2 from X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1396 ;; (- x 2))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1397 ;; bar
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1398 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1399 ;; (bar 4)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1400 ;; 1
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1401 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1402 ;; @@ Preactivation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1403 ;; =================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1404 ;; Constructing advised definitions is moderately expensive, hence, it is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1405 ;; desirable to have a way to construct them at byte-compile time.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1406 ;; Preactivation is a mechanism that allows one to do that.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1407 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1408 ;; (defun fie (x)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1409 ;; "Multiply X by 2."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1410 ;; (* x 2))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1411 ;; fie
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1412 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1413 ;; (defadvice fie (before fg-times-4 preact)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1414 ;; "Multiply X by 4."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1415 ;; (setq x (* x 2)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1416 ;; fie
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1417 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1418 ;; This advice did not affect `fie'...
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1419 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1420 ;; (fie 2)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1421 ;; 4
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1422 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1423 ;; ...but it constructed a cached definition that will be used once `fie' gets
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1424 ;; activated as long as its current advice state is the same as it was during
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1425 ;; preactivation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1426 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1427 ;; (setq cached-definition (ad-get-cache-definition 'fie))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1428 ;; (lambda (x) ....)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1429 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1430 ;; (ad-activate 'fie)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1431 ;; fie
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1432 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1433 ;; (eq cached-definition (symbol-function 'fie))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1434 ;; t
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1435 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1436 ;; (fie 2)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1437 ;; 8
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1438 ;;
11035
97da4cb32d03 Comment change.
Richard M. Stallman <rms@gnu.org>
parents: 8458
diff changeset
1439 ;; If you put a preactivating `defadvice' into a Lisp file that gets byte-
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1440 ;; compiled then the constructed advised definition will get compiled by
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1441 ;; the byte-compiler. For that to occur in a v18 emacs you have to put the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1442 ;; `defadvice' inside a `defun' because the v18 compiler does not compile
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1443 ;; top-level forms other than `defun' or `defmacro', for example,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1444 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1445 ;; (defun fg-defadvice-fum ()
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1446 ;; (defadvice fum (before fg-times-4 preact act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1447 ;; "Multiply X by 4."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1448 ;; (setq x (* x 2))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1449 ;; fg-defadvice-fum
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1450 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1451 ;; So far, no `defadvice' for `fum' got executed, but when we compile
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1452 ;; `fg-defadvice-fum' the `defadvice' will be expanded by the byte compiler.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1453 ;; In order for preactivation to be effective we have to have a proper
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1454 ;; definition of `fum' around at preactivation time, hence, we define it now:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1455 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1456 ;; (defun fum (x)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1457 ;; "Multiply X by 2."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1458 ;; (* x 2))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1459 ;; fum
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1460 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1461 ;; Now we compile the defining function which will construct an advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1462 ;; definition during expansion of the `defadvice', compile it and store it
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1463 ;; as part of the compiled `fg-defadvice-fum':
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1464 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1465 ;; (ad-compile-function 'fg-defadvice-fum)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1466 ;; (lambda nil (byte-code ...))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1467 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1468 ;; `fum' is still completely unaffected:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1469 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1470 ;; (fum 2)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1471 ;; 4
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1472 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1473 ;; (ad-get-advice-info 'fum)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1474 ;; nil
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1475 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1476 ;; (fg-defadvice-fum)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1477 ;; fum
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1478 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1479 ;; Now the advised version of `fum' is compiled because the compiled definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1480 ;; constructed during preactivation was used, even though we did not specify
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1481 ;; the `compile' flag:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1482 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1483 ;; (symbol-function 'fum)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1484 ;; (lambda (x)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1485 ;; "$ad-doc: fum$"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1486 ;; (byte-code "....." [ad-return-value x nil * 2 ad-Orig-fum] 4))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1487 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1488 ;; (fum 2)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1489 ;; 8
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1490 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1491 ;; A preactivated definition will only be used if it matches the current
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1492 ;; function definition and advice information. If it does not match it
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1493 ;; will simply be discarded and a new advised definition will be constructed
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1494 ;; from scratch. For example, let's first remove all advice-info for `fum':
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1495 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1496 ;; (ad-unadvise 'fum)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1497 ;; (("fie") ("bar") ("foo") ...)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1498 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1499 ;; And now define a new piece of advice:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1500 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1501 ;; (defadvice fum (before fg-interactive act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1502 ;; "Make fum interactive."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1503 ;; (interactive "nEnter x: "))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1504 ;; fum
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1505 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1506 ;; When we now try to use a preactivation it will not be used because the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1507 ;; current advice state is different from the one at preactivation time. This
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1508 ;; is no tragedy, everything will work as expected just not as efficient,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1509 ;; because a new advised definition has to be constructed from scratch:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1510 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1511 ;; (fg-defadvice-fum)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1512 ;; fum
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1513 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1514 ;; A new uncompiled advised definition got constructed:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1515 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1516 ;; (ad-compiled-p (symbol-function 'fum))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1517 ;; nil
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1518 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1519 ;; (fum 2)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1520 ;; 8
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1521 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1522 ;; MORAL: To get all the efficiency out of preactivation the function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1523 ;; definition and advice state at preactivation time must be the same as the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1524 ;; state at activation time. Preactivation does work with forward advice, all
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1525 ;; that's necessary is that the definition of the forward advised function is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1526 ;; available when the `defadvice' with the preactivation gets compiled.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1527 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1528 ;; @@ Portable argument access:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1529 ;; ============================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1530 ;; So far, we always used the actual argument variable names to access an
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1531 ;; argument in a piece of advice. For many advice applications this is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1532 ;; perfectly ok and keeps advices simple. However, it decreases portability
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1533 ;; of advices because it assumes specific argument variable names. For example,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1534 ;; if one advises a subr such as `eval-region' which then gets redefined by
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1535 ;; some package (e.g., edebug) into a function with different argument names,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1536 ;; then a piece of advice written for `eval-region' that was written with
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1537 ;; the subr arguments in mind will break. Similar situations arise when one
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1538 ;; switches between major Emacs versions, e.g., certain subrs in v18 are
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1539 ;; functions in v19 and vice versa. Also, in v19s subr argument lists
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1540 ;; are available and will be used, while they are not available in v18.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1541 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1542 ;; Argument access text macros allow one to access arguments of an advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1543 ;; function in a portable way without having to worry about all these
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1544 ;; possibilities. These macros will be translated into the proper access forms
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1545 ;; at activation time, hence, argument access will be as efficient as if
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1546 ;; the arguments had been used directly in the definition of the advice.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1547 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1548 ;; (defun fuu (x y z)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1549 ;; "Add 3 numbers."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1550 ;; (+ x y z))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1551 ;; fuu
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1552 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1553 ;; (fuu 1 1 1)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1554 ;; 3
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1555 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1556 ;; Argument access macros specify actual arguments at a certain position.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1557 ;; Position 0 access the first actual argument, position 1 the second etc.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1558 ;; For example, the following advice adds 1 to each of the 3 arguments:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1559 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1560 ;; (defadvice fuu (before fg-add-1-to-all act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1561 ;; "Adds 1 to all arguments."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1562 ;; (ad-set-arg 0 (1+ (ad-get-arg 0)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1563 ;; (ad-set-arg 1 (1+ (ad-get-arg 1)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1564 ;; (ad-set-arg 2 (1+ (ad-get-arg 2))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1565 ;; fuu
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1566 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1567 ;; (fuu 1 1 1)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1568 ;; 6
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1569 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1570 ;; Now suppose somebody redefines `fuu' with a rest argument. Our advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1571 ;; will still work because we used access macros (note, that automatic
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1572 ;; advice activation is still in effect, hence, the redefinition of `fuu'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1573 ;; will automatically activate all its advice):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1574 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1575 ;; (defun fuu (&rest numbers)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1576 ;; "Add NUMBERS."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1577 ;; (apply '+ numbers))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1578 ;; fuu
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1579 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1580 ;; (fuu 1 1 1)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1581 ;; 6
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1582 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1583 ;; (fuu 1 1 1 1 1 1)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1584 ;; 9
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1585 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1586 ;; What's important to notice is that argument access macros access actual
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1587 ;; arguments regardless of how they got distributed onto argument variables.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1588 ;; In Emacs Lisp the semantics of an actual argument is determined purely
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1589 ;; by position, hence, as long as nobody changes the semantics of what a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1590 ;; certain actual argument at a certain position means the access macros
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1591 ;; will do the right thing.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1592 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1593 ;; Because of &rest arguments we need a second kind of access macro that
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1594 ;; can access all actual arguments starting from a certain position:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1595 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1596 ;; (defadvice fuu (before fg-print-args act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1597 ;; "Print all arguments."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1598 ;; (print (ad-get-args 0)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1599 ;; fuu
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1600 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1601 ;; (fuu 1 2 3 4 5)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1602 ;; (1 2 3 4 5)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1603 ;; 18
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1604 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1605 ;; (defadvice fuu (before fg-set-args act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1606 ;; "Swaps 2nd and 3rd arg and discards all the rest."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1607 ;; (ad-set-args 1 (list (ad-get-arg 2) (ad-get-arg 1))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1608 ;; fuu
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1609 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1610 ;; (fuu 1 2 3 4 4 4 4 4 4)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1611 ;; (1 3 2)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1612 ;; 9
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1613 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1614 ;; (defun fuu (x y z)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1615 ;; "Add 3 numbers."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1616 ;; (+ x y z))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1617 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1618 ;; (fuu 1 2 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1619 ;; (1 3 2)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1620 ;; 9
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1621 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1622 ;; @@ Defining the argument list of an advised function:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1623 ;; =====================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1624 ;; Once in a while it might be desirable to advise a function and additionally
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1625 ;; give it an extra argument that controls the advised code, for example, one
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1626 ;; might want to make an interactive function sensitive to a prefix argument.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1627 ;; For such cases `defadvice' allows the specification of an argument list
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1628 ;; for the advised function. Similar to the redefinition of interactive
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1629 ;; behavior, the first argument list specification found in the list of before/
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1630 ;; around/after advices will be used. Of course, the specified argument list
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1631 ;; should be downward compatible with the original argument list, otherwise
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1632 ;; functions that call the advised function with the original argument list
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1633 ;; in mind will break.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1634 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1635 ;; (defun fii (x)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1636 ;; "Add 1 to X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1637 ;; (1+ x))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1638 ;; fii
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1639 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1640 ;; Now we advise `fii' to use an optional second argument that controls the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1641 ;; amount of incrementation. A list following the (optional) position
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1642 ;; argument of the advice will be interpreted as an argument list
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1643 ;; specification. This means you cannot specify an empty argument list, and
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1644 ;; why would you want to anyway?
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1645 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1646 ;; (defadvice fii (before fg-inc-x (x &optional incr) act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1647 ;; "Increment X by INCR (default is 1)."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1648 ;; (setq x (+ x (1- (or incr 1)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1649 ;; fii
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1650 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1651 ;; (fii 3)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1652 ;; 4
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1653 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1654 ;; (fii 3 2)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1655 ;; 5
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1656 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1657 ;; @@ Specifying argument lists of subrs:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1658 ;; ======================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1659 ;; The argument lists of subrs cannot be determined directly from Lisp.
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1660 ;; This means that Advice has to use `(&rest ad-subr-args)' as the
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1661 ;; argument list of the advised subr which is not very efficient. In Lemacs
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1662 ;; subr argument lists can be determined from their documentation string, in
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1663 ;; Emacs-19 this is the case for some but not all subrs. To accommodate
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1664 ;; for the cases where the argument lists cannot be determined (e.g., in a
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1665 ;; v18 Emacs) Advice comes with a specification mechanism that allows the
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1666 ;; advice programmer to tell advice what the argument list of a certain subr
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1667 ;; really is.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1668 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1669 ;; In a v18 Emacs the following will return the &rest idiom:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1670 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1671 ;; (ad-arglist (symbol-function 'car))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1672 ;; (&rest ad-subr-args)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1673 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1674 ;; To tell advice what the argument list of `car' really is we
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1675 ;; can do the following:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1676 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1677 ;; (ad-define-subr-args 'car '(list))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1678 ;; ((list))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1679 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1680 ;; Now `ad-arglist' will return the proper argument list (this method is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1681 ;; actually used by advice itself for the advised definition of `fset'):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1682 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1683 ;; (ad-arglist (symbol-function 'car))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1684 ;; (list)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1685 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1686 ;; The defined argument list will be stored on the property list of the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1687 ;; subr name symbol. When advice looks for a subr argument list it first
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1688 ;; checks for a definition on the property list, if that fails it tries
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1689 ;; to infer it from the documentation string and caches it on the property
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1690 ;; list if it was successful, otherwise `(&rest ad-subr-args)' will be used.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1691 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1692 ;; @@ Advising interactive subrs:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1693 ;; ==============================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1694 ;; For the most part there is no difference between advising functions and
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1695 ;; advising subrs. There is one situation though where one might have to write
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1696 ;; slightly different advice code for subrs than for functions. This case
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1697 ;; arises when one wants to access subr arguments in a before/around advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1698 ;; when the arguments were determined by an interactive call to the subr.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1699 ;; Advice cannot determine what `interactive' form determines the interactive
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1700 ;; behavior of the subr, hence, when it calls the original definition in an
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1701 ;; interactive subr invocation it has to use `call-interactively' to generate
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1702 ;; the proper interactive behavior. Thus up to that call the arguments of the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1703 ;; interactive subr will be nil. For example, the following advice for
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1704 ;; `kill-buffer' will not work in an interactive invocation...
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1705 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1706 ;; (defadvice kill-buffer (before fg-kill-buffer-hook first act preact comp)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1707 ;; (my-before-kill-buffer-hook (ad-get-arg 0)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1708 ;; kill-buffer
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1709 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1710 ;; ...because the buffer argument will be nil in that case. The way out of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1711 ;; this dilemma is to provide an `interactive' specification that mirrors
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1712 ;; the interactive behavior of the unadvised subr, for example, the following
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1713 ;; will do the right thing even when `kill-buffer' is called interactively:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1714 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1715 ;; (defadvice kill-buffer (before fg-kill-buffer-hook first act preact comp)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1716 ;; (interactive "bKill buffer: ")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1717 ;; (my-before-kill-buffer-hook (ad-get-arg 0)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1718 ;; kill-buffer
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1719 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1720 ;; @@ Advising macros:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1721 ;; ===================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1722 ;; Advising macros is slightly different because there are two significant
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1723 ;; time points in the invocation of a macro: Expansion and evaluation time.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1724 ;; For an advised macro instead of evaluating the original definition we
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1725 ;; use `macroexpand', that is, changing argument values and binding
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1726 ;; environments by pieces of advice has an affect during macro expansion
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1727 ;; but not necessarily during evaluation. In particular, any side effects
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1728 ;; of pieces of advice will occur during macro expansion. To also affect
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1729 ;; the behavior during evaluation time one has to change the value of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1730 ;; `ad-return-value' in a piece of after advice. For example:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1731 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1732 ;; (defmacro foom (x)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1733 ;; (` (list (, x))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1734 ;; foom
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1735 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1736 ;; (foom '(a))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1737 ;; ((a))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1738 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1739 ;; (defadvice foom (before fg-print-x act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1740 ;; "Print the value of X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1741 ;; (print x))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1742 ;; foom
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1743 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1744 ;; The following works as expected because evaluation immediately follows
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1745 ;; macro expansion:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1746 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1747 ;; (foom '(a))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1748 ;; (quote (a))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1749 ;; ((a))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1750 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1751 ;; However, the printing happens during expansion (or byte-compile) time:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1752 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1753 ;; (macroexpand '(foom '(a)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1754 ;; (quote (a))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1755 ;; (list (quote (a)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1756 ;;
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1757 ;; If we want it to happen during evaluation time we have to do the
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1758 ;; following (first remove the old advice):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1759 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1760 ;; (ad-remove-advice 'foom 'before 'fg-print-x)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1761 ;; nil
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1762 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1763 ;; (defadvice foom (after fg-print-x act)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1764 ;; "Print the value of X."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1765 ;; (setq ad-return-value
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1766 ;; (` (progn (print (, x))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1767 ;; (, ad-return-value)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1768 ;; foom
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1769 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1770 ;; (macroexpand '(foom '(a)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1771 ;; (progn (print (quote (a))) (list (quote (a))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1772 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1773 ;; (foom '(a))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1774 ;; (a)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1775 ;; ((a))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1776 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1777 ;; While this method might seem somewhat cumbersome, it is very general
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1778 ;; because it allows one to influence macro expansion as well as evaluation.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1779 ;; In general, advising macros should be a rather rare activity anyway, in
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1780 ;; particular, because compile-time macro expansion takes away a lot of the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1781 ;; flexibility and effectiveness of the advice mechanism. Macros that were
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1782 ;; compile-time expanded before the advice was activated will of course never
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1783 ;; exhibit the advised behavior.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1784 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1785 ;; @@ Advising special forms:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1786 ;; ==========================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1787 ;; Now for something that should be even more rare than advising macros:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1788 ;; Advising special forms. Because special forms are irregular in their
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1789 ;; argument evaluation behavior (e.g., `setq' evaluates the second but not
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1790 ;; the first argument) they have to be advised into macros. A dangerous
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1791 ;; consequence of this is that the byte-compiler will not recognize them
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1792 ;; as special forms anymore (well, in most cases) and use their expansion
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1793 ;; rather than the proper byte-code. Also, because the original definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1794 ;; of a special form cannot be `funcall'ed, `eval' has to be used instead
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1795 ;; which is less efficient.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1796 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1797 ;; MORAL: Do not advise special forms unless you are completely sure about
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1798 ;; what you are doing (some of the forward advice behavior is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1799 ;; implemented via advice of the special forms `defun' and `defmacro').
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1800 ;; As a safety measure one should always do `ad-deactivate-all' before
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1801 ;; one byte-compiles a file to avoid any interference of advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1802 ;; special forms.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1803 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1804 ;; Apart from the safety concerns advising special forms is not any different
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1805 ;; from advising plain functions or subrs.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1806
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1807
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1808 ;;; Code:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1809
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1810 ;; @ Advice implementation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1811 ;; ========================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1812
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1813 ;; @@ Compilation idiosyncrasies:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1814 ;; ==============================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1815
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1816 ;; `defadvice' expansion needs quite a few advice functions and variables,
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1817 ;; hence, I need to preload the file before it can be compiled. To avoid
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1818 ;; interference of bogus compiled files I always preload the source file:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1819 (provide 'advice-preload)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1820 ;; During a normal load this is a noop:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1821 (require 'advice-preload "advice.el")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1822
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1823
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
1824 ;; @@ Variable definitions:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
1825 ;; ========================
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
1826
21365
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
1827 (defgroup advice nil
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
1828 "An overloading mechanism for Emacs Lisp functions."
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
1829 :prefix "ad-"
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1830 :link '(custom-manual "(elisp)Advising Functions")
21365
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
1831 :group 'lisp)
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
1832
8458
a95ca44cec95 (ad-subr-arglist): Adapted to new DOC file format.
Richard M. Stallman <rms@gnu.org>
parents: 8445
diff changeset
1833 (defconst ad-version "2.14")
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1834
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1835 ;;;###autoload
21365
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
1836 (defcustom ad-redefinition-action 'warn
104024
cce8d50c4566 Remove leading * from defcustom docs.
Glenn Morris <rgm@gnu.org>
parents: 100908
diff changeset
1837 "Defines what to do with redefinitions during Advice de/activation.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1838 Redefinition occurs if a previously activated function that already has an
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1839 original definition associated with it gets redefined and then de/activated.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1840 In such a case we can either accept the current definition as the new
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1841 original definition, discard the current definition and replace it with the
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1842 old original, or keep it and raise an error. The values `accept', `discard',
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1843 `error' or `warn' govern what will be done. `warn' is just like `accept' but
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1844 it additionally prints a warning message. All other values will be
21365
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
1845 interpreted as `error'."
22577
c129b4c40a0c (ad-redefinition-action,
Andreas Schwab <schwab@suse.de>
parents: 22061
diff changeset
1846 :type '(choice (const accept) (const discard) (const warn)
c129b4c40a0c (ad-redefinition-action,
Andreas Schwab <schwab@suse.de>
parents: 22061
diff changeset
1847 (other :tag "error" error))
21365
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
1848 :group 'advice)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1849
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1850 ;;;###autoload
21365
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
1851 (defcustom ad-default-compilation-action 'maybe
104024
cce8d50c4566 Remove leading * from defcustom docs.
Glenn Morris <rgm@gnu.org>
parents: 100908
diff changeset
1852 "Defines whether to compile advised definitions during activation.
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
1853 A value of `always' will result in unconditional compilation, `never' will
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
1854 always avoid compilation, `maybe' will compile if the byte-compiler is already
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
1855 loaded, and `like-original' will compile if the original definition of the
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1856 advised function is compiled or a built-in function. Every other value will
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1857 be interpreted as `maybe'. This variable will only be considered if the
21365
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
1858 COMPILE argument of `ad-activate' was supplied as nil."
22577
c129b4c40a0c (ad-redefinition-action,
Andreas Schwab <schwab@suse.de>
parents: 22061
diff changeset
1859 :type '(choice (const always) (const never) (const like-original)
c129b4c40a0c (ad-redefinition-action,
Andreas Schwab <schwab@suse.de>
parents: 22061
diff changeset
1860 (other :tag "maybe" maybe))
21365
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
1861 :group 'advice)
db005054f15d Customized.
Stephen Eglen <stephen@gnu.org>
parents: 14169
diff changeset
1862
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1863
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1864
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1865 ;; @@ Some utilities:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1866 ;; ==================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1867
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1868 ;; We don't want the local arguments to interfere with anything
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1869 ;; referenced in the supplied functions => the cryptic casing:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1870 (defun ad-substitute-tree (sUbTrEe-TeSt fUnCtIoN tReE)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1871 "Substitute qualifying subTREEs with result of FUNCTION(subTREE).
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1872 Only proper subtrees are considered, for example, if TREE is (1 (2 (3)) 4)
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1873 then the subtrees will be 1 (2 (3)) 2 (3) 3 4, dotted structures are
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1874 allowed too. Once a qualifying subtree has been found its subtrees will
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1875 not be considered anymore. (ad-substitute-tree 'atom 'identity tree)
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1876 generates a copy of TREE."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1877 (cond ((consp tReE)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1878 (cons (if (funcall sUbTrEe-TeSt (car tReE))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1879 (funcall fUnCtIoN (car tReE))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1880 (if (consp (car tReE))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1881 (ad-substitute-tree sUbTrEe-TeSt fUnCtIoN (car tReE))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1882 (car tReE)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1883 (ad-substitute-tree sUbTrEe-TeSt fUnCtIoN (cdr tReE))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1884 ((funcall sUbTrEe-TeSt tReE)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1885 (funcall fUnCtIoN tReE))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1886 (t tReE)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1887
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1888 ;; this is just faster than `ad-substitute-tree':
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1889 (defun ad-copy-tree (tree)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1890 "Return a copy of the list structure of TREE."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1891 (cond ((consp tree)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1892 (cons (ad-copy-tree (car tree))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1893 (ad-copy-tree (cdr tree))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1894 (t tree)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1895
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1896 (defmacro ad-dolist (varform &rest body)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1897 "A Common-Lisp-style dolist iterator with the following syntax:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1898
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1899 (ad-dolist (VAR INIT-FORM [RESULT-FORM])
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1900 BODY-FORM...)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1901
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1902 which will iterate over the list yielded by INIT-FORM binding VAR to the
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1903 current head at every iteration. If RESULT-FORM is supplied its value will
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1904 be returned at the end of the iteration, nil otherwise. The iteration can be
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1905 exited prematurely with `(ad-do-return [VALUE])'."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1906 (let ((expansion
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1907 `(let ((ad-dO-vAr ,(car (cdr varform)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1908 ,(car varform))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1909 (while ad-dO-vAr
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1910 (setq ,(car varform) (car ad-dO-vAr))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1911 ,@body
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1912 ;;work around a backquote bug:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1913 ;;(` ((,@ '(foo)) (bar))) => (append '(foo) '(((bar)))) wrong
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1914 ;;(` ((,@ '(foo)) (, '(bar)))) => (append '(foo) (list '(bar)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1915 ,'(setq ad-dO-vAr (cdr ad-dO-vAr)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1916 ,(car (cdr (cdr varform))))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1917 ;;ok, this wastes some cons cells but only during compilation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1918 (if (catch 'contains-return
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1919 (ad-substitute-tree
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1920 (function (lambda (subtree)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1921 (cond ((eq (car-safe subtree) 'ad-dolist))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1922 ((eq (car-safe subtree) 'ad-do-return)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1923 (throw 'contains-return t)))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1924 'identity body)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1925 nil)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1926 `(catch 'ad-dO-eXiT ,expansion)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1927 expansion)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1928
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1929 (defmacro ad-do-return (value)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1930 `(throw 'ad-dO-eXiT ,value))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1931
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1932 (if (not (get 'ad-dolist 'lisp-indent-hook))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1933 (put 'ad-dolist 'lisp-indent-hook 1))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1934
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1935
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1936 ;; @@ Save real definitions of subrs used by Advice:
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1937 ;; =================================================
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1938 ;; Advice depends on the real, unmodified functionality of various subrs,
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1939 ;; we save them here so advised versions will not interfere (eventually,
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1940 ;; we will save all subrs used in code generated by Advice):
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1941
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1942 (defmacro ad-save-real-definition (function)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1943 (let ((saved-function (intern (format "ad-real-%s" function))))
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1944 ;; Make sure the compiler is loaded during macro expansion:
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1945 (require 'byte-compile "bytecomp")
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1946 `(if (not (fboundp ',saved-function))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1947 (progn (fset ',saved-function (symbol-function ',function))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1948 ;; Copy byte-compiler properties:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1949 ,@(if (get function 'byte-compile)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1950 `((put ',saved-function 'byte-compile
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1951 ',(get function 'byte-compile))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1952 ,@(if (get function 'byte-opcode)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1953 `((put ',saved-function 'byte-opcode
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1954 ',(get function 'byte-opcode))))))))
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1955
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1956 (defun ad-save-real-definitions ()
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1957 ;; Macro expansion will hardcode the values of the various byte-compiler
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1958 ;; properties into the compiled version of this function such that the
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1959 ;; proper values will be available at runtime without loading the compiler:
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1960 (ad-save-real-definition fset)
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
1961 (ad-save-real-definition documentation))
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1962
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1963 (ad-save-real-definitions)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1964
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1965
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1966 ;; @@ Advice info access fns:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1967 ;; ==========================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1968
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1969 ;; Advice information for a particular function is stored on the
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
1970 ;; advice-info property of the function symbol. It is stored as an
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1971 ;; alist of the following format:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1972 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1973 ;; ((active . t/nil)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1974 ;; (before adv1 adv2 ...)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1975 ;; (around adv1 adv2 ...)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1976 ;; (after adv1 adv2 ...)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1977 ;; (activation adv1 adv2 ...)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1978 ;; (deactivation adv1 adv2 ...)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1979 ;; (origname . <symbol fbound to origdef>)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1980 ;; (cache . (<advised-definition> . <id>)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1981
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1982 ;; List of currently advised though not necessarily activated functions
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1983 ;; (this list is maintained as a completion table):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1984 (defvar ad-advised-functions nil)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1985
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1986 (defmacro ad-pushnew-advised-function (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1987 "Add FUNCTION to `ad-advised-functions' unless its already there."
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1988 `(if (not (assoc (symbol-name ,function) ad-advised-functions))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1989 (setq ad-advised-functions
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1990 (cons (list (symbol-name ,function))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1991 ad-advised-functions))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1992
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1993 (defmacro ad-pop-advised-function (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
1994 "Remove FUNCTION from `ad-advised-functions'."
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1995 `(setq ad-advised-functions
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1996 (delq (assoc (symbol-name ,function) ad-advised-functions)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
1997 ad-advised-functions)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1998
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
1999 (defmacro ad-do-advised-functions (varform &rest body)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2000 "`ad-dolist'-style iterator that maps over `ad-advised-functions'.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2001 \(ad-do-advised-functions (VAR [RESULT-FORM])
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2002 BODY-FORM...)
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2003 On each iteration VAR will be bound to the name of an advised function
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2004 \(a symbol)."
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2005 `(ad-dolist (,(car varform)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2006 ad-advised-functions
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2007 ,(car (cdr varform)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2008 (setq ,(car varform) (intern (car ,(car varform))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2009 ,@body))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2010
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2011 (if (not (get 'ad-do-advised-functions 'lisp-indent-hook))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2012 (put 'ad-do-advised-functions 'lisp-indent-hook 1))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2013
79099
8632fa2db924 (ad-get-advice-info): Change to a function.
Richard M. Stallman <rms@gnu.org>
parents: 78217
diff changeset
2014 (defun ad-get-advice-info (function)
8632fa2db924 (ad-get-advice-info): Change to a function.
Richard M. Stallman <rms@gnu.org>
parents: 78217
diff changeset
2015 (get function 'ad-advice-info))
8632fa2db924 (ad-get-advice-info): Change to a function.
Richard M. Stallman <rms@gnu.org>
parents: 78217
diff changeset
2016
8632fa2db924 (ad-get-advice-info): Change to a function.
Richard M. Stallman <rms@gnu.org>
parents: 78217
diff changeset
2017 (defmacro ad-get-advice-info-macro (function)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2018 `(get ,function 'ad-advice-info))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2019
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2020 (defmacro ad-set-advice-info (function advice-info)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2021 `(put ,function 'ad-advice-info ,advice-info))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2022
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2023 (defmacro ad-copy-advice-info (function)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2024 `(ad-copy-tree (get ,function 'ad-advice-info)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2025
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2026 (defmacro ad-is-advised (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2027 "Return non-nil if FUNCTION has any advice info associated with it.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2028 This does not mean that the advice is also active."
79099
8632fa2db924 (ad-get-advice-info): Change to a function.
Richard M. Stallman <rms@gnu.org>
parents: 78217
diff changeset
2029 (list 'ad-get-advice-info-macro function))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2030
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2031 (defun ad-initialize-advice-info (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2032 "Initialize the advice info for FUNCTION.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2033 Assumes that FUNCTION has not yet been advised."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2034 (ad-pushnew-advised-function function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2035 (ad-set-advice-info function (list (cons 'active nil))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2036
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2037 (defmacro ad-get-advice-info-field (function field)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2038 "Retrieve the value of the advice info FIELD of FUNCTION."
79099
8632fa2db924 (ad-get-advice-info): Change to a function.
Richard M. Stallman <rms@gnu.org>
parents: 78217
diff changeset
2039 `(cdr (assq ,field (ad-get-advice-info-macro ,function))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2040
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2041 (defun ad-set-advice-info-field (function field value)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2042 "Destructively modify VALUE of the advice info FIELD of FUNCTION."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2043 (and (ad-is-advised function)
79099
8632fa2db924 (ad-get-advice-info): Change to a function.
Richard M. Stallman <rms@gnu.org>
parents: 78217
diff changeset
2044 (cond ((assq field (ad-get-advice-info-macro function))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2045 ;; A field with that name is already present:
79099
8632fa2db924 (ad-get-advice-info): Change to a function.
Richard M. Stallman <rms@gnu.org>
parents: 78217
diff changeset
2046 (rplacd (assq field (ad-get-advice-info-macro function)) value))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2047 (t;; otherwise, create a new field with that name:
79099
8632fa2db924 (ad-get-advice-info): Change to a function.
Richard M. Stallman <rms@gnu.org>
parents: 78217
diff changeset
2048 (nconc (ad-get-advice-info-macro function)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2049 (list (cons field value)))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2050
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2051 ;; Don't make this a macro so we can use it as a predicate:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2052 (defun ad-is-active (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2053 "Return non-nil if FUNCTION is advised and activated."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2054 (ad-get-advice-info-field function 'active))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2055
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2056
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2057 ;; @@ Access fns for single pieces of advice and related predicates:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2058 ;; =================================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2059
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2060 (defun ad-make-advice (name protect enable definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2061 "Constructs single piece of advice to be stored in some advice-info.
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2062 NAME should be a non-nil symbol, PROTECT and ENABLE should each be
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2063 either t or nil, and DEFINITION should be a list of the form
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2064 `(advice lambda ARGLIST [DOCSTRING] [INTERACTIVE-FORM] BODY...)'."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2065 (list name protect enable definition))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2066
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2067 ;; ad-find-advice uses the alist structure directly ->
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2068 ;; change if this data structure changes!!
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2069 (defmacro ad-advice-name (advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2070 (list 'car advice))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2071 (defmacro ad-advice-protected (advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2072 (list 'nth 1 advice))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2073 (defmacro ad-advice-enabled (advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2074 (list 'nth 2 advice))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2075 (defmacro ad-advice-definition (advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2076 (list 'nth 3 advice))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2077
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2078 (defun ad-advice-set-enabled (advice flag)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2079 (rplaca (cdr (cdr advice)) flag))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2080
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2081 (defun ad-class-p (thing)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2082 (memq thing ad-advice-classes))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2083 (defun ad-name-p (thing)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2084 (and thing (symbolp thing)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2085 (defun ad-position-p (thing)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2086 (or (natnump thing)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2087 (memq thing '(first last))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2088
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2089
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2090 ;; @@ Advice access functions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2091 ;; ===========================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2092
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2093 ;; List of defined advice classes:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2094 (defvar ad-advice-classes '(before around after activation deactivation))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2095
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2096 (defun ad-has-enabled-advice (function class)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2097 "True if at least one of FUNCTION's advices in CLASS is enabled."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2098 (ad-dolist (advice (ad-get-advice-info-field function class))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2099 (if (ad-advice-enabled advice) (ad-do-return t))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2100
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2101 (defun ad-has-redefining-advice (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2102 "True if FUNCTION's advice info defines at least 1 redefining advice.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2103 Redefining advices affect the construction of an advised definition."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2104 (and (ad-is-advised function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2105 (or (ad-has-enabled-advice function 'before)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2106 (ad-has-enabled-advice function 'around)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2107 (ad-has-enabled-advice function 'after))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2108
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2109 (defun ad-has-any-advice (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2110 "True if the advice info of FUNCTION defines at least one advice."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2111 (and (ad-is-advised function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2112 (ad-dolist (class ad-advice-classes nil)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2113 (if (ad-get-advice-info-field function class)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2114 (ad-do-return t)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2115
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2116 (defun ad-get-enabled-advices (function class)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2117 "Return the list of enabled advices of FUNCTION in CLASS."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2118 (let (enabled-advices)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2119 (ad-dolist (advice (ad-get-advice-info-field function class))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2120 (if (ad-advice-enabled advice)
50800
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
2121 (push advice enabled-advices)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2122 (reverse enabled-advices)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2123
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2124
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2125 ;; @@ Dealing with automatic advice activation via `fset/defalias':
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2126 ;; ================================================================
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2127
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2128 ;; Since Emacs 19.26 the built-in versions of `fset' and `defalias'
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2129 ;; take care of automatic advice activation, hence, we don't have to
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2130 ;; hack it anymore by advising `fset/defun/defmacro/byte-code/etc'.
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2131
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2132 ;; The functionality of the new `fset' is as follows:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2133 ;;
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2134 ;; fset(sym,newdef)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2135 ;; assign NEWDEF to SYM
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2136 ;; if (get SYM 'ad-advice-info)
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
2137 ;; ad-activate-internal(SYM, nil)
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2138 ;; return (symbol-function SYM)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2139 ;;
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2140 ;; Whether advised definitions created by automatic activations will be
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2141 ;; compiled depends on the value of `ad-default-compilation-action'.
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2142
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
2143 ;; Since calling `ad-activate-internal' in the built-in definition of `fset' can
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2144 ;; create major disasters we have to be a bit careful. One precaution is
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
2145 ;; to provide a dummy definition for `ad-activate-internal' which can be used to
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2146 ;; turn off automatic advice activation (e.g., when `ad-stop-advice' or
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2147 ;; `ad-recover-normality' are called). Another is to avoid recursive calls
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
2148 ;; to `ad-activate' by using `ad-with-auto-activation-disabled' where
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2149 ;; appropriate, especially in a safe version of `fset'.
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2150
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
2151 ;; For now define `ad-activate-internal' to the dummy definition:
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
2152 (defun ad-activate-internal (function &optional compile)
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2153 "Automatic advice activation is disabled. `ad-start-advice' enables it."
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2154 nil)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2155
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2156 ;; This is just a copy of the above:
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
2157 (defun ad-activate-internal-off (function &optional compile)
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2158 "Automatic advice activation is disabled. `ad-start-advice' enables it."
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2159 nil)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2160
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
2161 ;; This will be t for top-level calls to `ad-activate-internal-on':
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2162 (defvar ad-activate-on-top-level t)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2163
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2164 (defmacro ad-with-auto-activation-disabled (&rest body)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2165 `(let ((ad-activate-on-top-level nil))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2166 ,@body))
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2167
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2168 (defun ad-safe-fset (symbol definition)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2169 "A safe `fset' which will never call `ad-activate-internal' recursively."
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2170 (ad-with-auto-activation-disabled
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2171 (ad-real-fset symbol definition)))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2172
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2173
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2174 ;; @@ Access functions for original definitions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2175 ;; ============================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2176 ;; The advice-info of an advised function contains its `origname' which is
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2177 ;; a symbol that is fbound to the original definition available at the first
60923
08f8c7042636 * emacs-lisp/advice.el: Replace `legal' with `valid'.
Werner LEMBERG <wl@gnu.org>
parents: 57879
diff changeset
2178 ;; proper activation of the function after a valid re/definition. If the
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2179 ;; original was defined via fcell indirection then `origname' will be defined
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2180 ;; just so. Hence, to get hold of the actual original definition of a function
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2181 ;; we need to use `ad-real-orig-definition'.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2182
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2183 (defun ad-make-origname (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2184 "Make name to be used to call the original FUNCTION."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2185 (intern (format "ad-Orig-%s" function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2186
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2187 (defmacro ad-get-orig-definition (function)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2188 `(let ((origname (ad-get-advice-info-field ,function 'origname)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2189 (if (fboundp origname)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2190 (symbol-function origname))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2191
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2192 (defmacro ad-set-orig-definition (function definition)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2193 `(ad-safe-fset
106966
9e04f0532ba4 * emacs-lisp/advice.el (ad-set-orig-definition): Fix typo (Bug#3541).
Chong Yidong <cyd@stupidchicken.com>
parents: 106870
diff changeset
2194 (ad-get-advice-info-field ,function 'origname) ,definition))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2195
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2196 (defmacro ad-clear-orig-definition (function)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2197 `(fmakunbound (ad-get-advice-info-field ,function 'origname)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2198
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2199
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2200 ;; @@ Interactive input functions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2201 ;; ===============================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2202
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2203 (defun ad-read-advised-function (&optional prompt predicate default)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2204 "Read name of advised function with completion from the minibuffer.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2205 An optional PROMPT will be used to prompt for the function. PREDICATE
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2206 plays the same role as for `try-completion' (which see). DEFAULT will
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2207 be returned on empty input (defaults to the first advised function for
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2208 which PREDICATE returns non-nil)."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2209 (if (null ad-advised-functions)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2210 (error "ad-read-advised-function: There are no advised functions"))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2211 (setq default
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2212 (or default
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2213 (ad-do-advised-functions (function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2214 (if (or (null predicate)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2215 (funcall predicate function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2216 (ad-do-return function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2217 (error "ad-read-advised-function: %s"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2218 "There are no qualifying advised functions")))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2219 (let* ((ad-pReDiCaTe predicate)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2220 (function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2221 (completing-read
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
2222 (format "%s (default %s): " (or prompt "Function") default)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2223 ad-advised-functions
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2224 (if predicate
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2225 (function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2226 (lambda (function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2227 ;; Oops, no closures - the joys of dynamic scoping:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2228 ;; `predicate' clashed with the `predicate' argument
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2229 ;; of Lemacs' `completing-read'.....
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2230 (funcall ad-pReDiCaTe (intern (car function))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2231 t)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2232 (if (equal function "")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2233 (if (ad-is-advised default)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2234 default
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2235 (error "ad-read-advised-function: `%s' is not advised" default))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2236 (intern function))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2237
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2238 (defvar ad-advice-class-completion-table
29579
05016ef95d0f (ad-advice-class-completion-table)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 26627
diff changeset
2239 (mapcar (lambda (class) (list (symbol-name class)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2240 ad-advice-classes))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2241
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2242 (defun ad-read-advice-class (function &optional prompt default)
60923
08f8c7042636 * emacs-lisp/advice.el: Replace `legal' with `valid'.
Werner LEMBERG <wl@gnu.org>
parents: 57879
diff changeset
2243 "Read a valid advice class with completion from the minibuffer.
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2244 An optional PROMPT will be used to prompt for the class. DEFAULT will
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2245 be returned on empty input (defaults to the first non-empty advice
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2246 class of FUNCTION)."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2247 (setq default
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2248 (or default
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2249 (ad-dolist (class ad-advice-classes)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2250 (if (ad-get-advice-info-field function class)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2251 (ad-do-return class)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2252 (error "ad-read-advice-class: `%s' has no advices" function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2253 (let ((class (completing-read
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
2254 (format "%s (default %s): " (or prompt "Class") default)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2255 ad-advice-class-completion-table nil t)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2256 (if (equal class "")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2257 default
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2258 (intern class))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2259
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2260 (defun ad-read-advice-name (function class &optional prompt)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2261 "Read name of existing advice of CLASS for FUNCTION with completion.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2262 An optional PROMPT is used to prompt for the name."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2263 (let* ((name-completion-table
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2264 (mapcar (function (lambda (advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2265 (list (symbol-name (ad-advice-name advice)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2266 (ad-get-advice-info-field function class)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2267 (default
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2268 (if (null name-completion-table)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2269 (error "ad-read-advice-name: `%s' has no %s advice"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2270 function class)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2271 (car (car name-completion-table))))
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
2272 (prompt (format "%s (default %s): " (or prompt "Name") default))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2273 (name (completing-read prompt name-completion-table nil t)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2274 (if (equal name "")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2275 (intern default)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2276 (intern name))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2277
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2278 (defun ad-read-advice-specification (&optional prompt)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2279 "Read a complete function/class/name specification from minibuffer.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2280 The list of read symbols will be returned. The optional PROMPT will
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2281 be used to prompt for the function."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2282 (let* ((function (ad-read-advised-function prompt))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2283 (class (ad-read-advice-class function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2284 (name (ad-read-advice-name function class)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2285 (list function class name)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2286
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2287 ;; Use previous regexp as a default:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2288 (defvar ad-last-regexp "")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2289
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2290 (defun ad-read-regexp (&optional prompt)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2291 "Read a regular expression from the minibuffer."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2292 (let ((regexp (read-from-minibuffer
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
2293 (concat (or prompt "Regular expression")
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
2294 (if (equal ad-last-regexp "") ": "
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
2295 (format " (default %s): " ad-last-regexp))))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2296 (setq ad-last-regexp
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2297 (if (equal regexp "") ad-last-regexp regexp))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2298
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2299
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2300 ;; @@ Finding, enabling, adding and removing pieces of advice:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2301 ;; ===========================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2302
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2303 (defmacro ad-find-advice (function class name)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2304 "Find the first advice of FUNCTION in CLASS with NAME."
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2305 `(assq ,name (ad-get-advice-info-field ,function ,class)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2306
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2307 (defun ad-advice-position (function class name)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2308 "Return position of first advice of FUNCTION in CLASS with NAME."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2309 (let* ((found-advice (ad-find-advice function class name))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2310 (advices (ad-get-advice-info-field function class)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2311 (if found-advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2312 (- (length advices) (length (memq found-advice advices))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2313
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2314 (defun ad-find-some-advice (function class name)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2315 "Find the first of FUNCTION's advices in CLASS matching NAME.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2316 NAME can be a symbol or a regular expression matching part of an advice name.
60923
08f8c7042636 * emacs-lisp/advice.el: Replace `legal' with `valid'.
Werner LEMBERG <wl@gnu.org>
parents: 57879
diff changeset
2317 If CLASS is `any' all valid advice classes will be checked."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2318 (if (ad-is-advised function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2319 (let (found-advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2320 (ad-dolist (advice-class ad-advice-classes)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2321 (if (or (eq class 'any) (eq advice-class class))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2322 (setq found-advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2323 (ad-dolist (advice (ad-get-advice-info-field
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2324 function advice-class))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2325 (if (or (and (stringp name)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2326 (string-match
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2327 name (symbol-name
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2328 (ad-advice-name advice))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2329 (eq name (ad-advice-name advice)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2330 (ad-do-return advice)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2331 (if found-advice (ad-do-return found-advice))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2332
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2333 (defun ad-enable-advice-internal (function class name flag)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2334 "Set enable FLAG of FUNCTION's advices in CLASS matching NAME.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2335 If NAME is a string rather than a symbol then it's interpreted as a regular
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2336 expression and all advices whose name contain a match for it will be
60923
08f8c7042636 * emacs-lisp/advice.el: Replace `legal' with `valid'.
Werner LEMBERG <wl@gnu.org>
parents: 57879
diff changeset
2337 affected. If CLASS is `any' advices in all valid advice classes will be
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2338 considered. The number of changed advices will be returned (or nil if
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2339 FUNCTION was not advised)."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2340 (if (ad-is-advised function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2341 (let ((matched-advices 0))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2342 (ad-dolist (advice-class ad-advice-classes)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2343 (if (or (eq class 'any) (eq advice-class class))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2344 (ad-dolist (advice (ad-get-advice-info-field
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2345 function advice-class))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2346 (cond ((or (and (stringp name)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2347 (string-match
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2348 name (symbol-name (ad-advice-name advice))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2349 (eq name (ad-advice-name advice)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2350 (setq matched-advices (1+ matched-advices))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2351 (ad-advice-set-enabled advice flag))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2352 matched-advices)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2353
70899
b920ab84fba8 (ad-enable-advice, ad-activate, ad-disable-advice): Add autoloads.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
2354 ;;;###autoload
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2355 (defun ad-enable-advice (function class name)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2356 "Enables the advice of FUNCTION with CLASS and NAME."
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
2357 (interactive (ad-read-advice-specification "Enable advice of"))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2358 (if (ad-is-advised function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2359 (if (eq (ad-enable-advice-internal function class name t) 0)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2360 (error "ad-enable-advice: `%s' has no %s advice matching `%s'"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2361 function class name))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2362 (error "ad-enable-advice: `%s' is not advised" function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2363
70899
b920ab84fba8 (ad-enable-advice, ad-activate, ad-disable-advice): Add autoloads.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
2364 ;;;###autoload
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2365 (defun ad-disable-advice (function class name)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2366 "Disable the advice of FUNCTION with CLASS and NAME."
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
2367 (interactive (ad-read-advice-specification "Disable advice of"))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2368 (if (ad-is-advised function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2369 (if (eq (ad-enable-advice-internal function class name nil) 0)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2370 (error "ad-disable-advice: `%s' has no %s advice matching `%s'"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2371 function class name))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2372 (error "ad-disable-advice: `%s' is not advised" function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2373
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2374 (defun ad-enable-regexp-internal (regexp class flag)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2375 "Set enable FLAGs of all CLASS advices whose name contains a REGEXP match.
60923
08f8c7042636 * emacs-lisp/advice.el: Replace `legal' with `valid'.
Werner LEMBERG <wl@gnu.org>
parents: 57879
diff changeset
2376 If CLASS is `any' all valid advice classes are considered. The number of
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2377 affected advices will be returned."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2378 (let ((matched-advices 0))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2379 (ad-do-advised-functions (advised-function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2380 (setq matched-advices
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2381 (+ matched-advices
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2382 (or (ad-enable-advice-internal
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2383 advised-function class regexp flag)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2384 0))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2385 matched-advices))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2386
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2387 (defun ad-enable-regexp (regexp)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2388 "Enables all advices with names that contain a match for REGEXP.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2389 All currently advised functions will be considered."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2390 (interactive
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
2391 (list (ad-read-regexp "Enable advices via regexp")))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2392 (let ((matched-advices (ad-enable-regexp-internal regexp 'any t)))
105372
bd2966850aac Use `called-interactively-p' instead of `interactive-p'.
Juanma Barranquero <lekktu@gmail.com>
parents: 105371
diff changeset
2393 (if (called-interactively-p 'interactive)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2394 (message "%d matching advices enabled" matched-advices))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2395 matched-advices))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2396
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2397 (defun ad-disable-regexp (regexp)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2398 "Disable all advices with names that contain a match for REGEXP.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2399 All currently advised functions will be considered."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2400 (interactive
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
2401 (list (ad-read-regexp "Disable advices via regexp")))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2402 (let ((matched-advices (ad-enable-regexp-internal regexp 'any nil)))
105372
bd2966850aac Use `called-interactively-p' instead of `interactive-p'.
Juanma Barranquero <lekktu@gmail.com>
parents: 105371
diff changeset
2403 (if (called-interactively-p 'interactive)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2404 (message "%d matching advices disabled" matched-advices))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2405 matched-advices))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2406
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2407 (defun ad-remove-advice (function class name)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2408 "Remove FUNCTION's advice with NAME from its advices in CLASS.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2409 If such an advice was found it will be removed from the list of advices
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2410 in that CLASS."
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
2411 (interactive (ad-read-advice-specification "Remove advice of"))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2412 (if (ad-is-advised function)
73251
25e1db3fd0ed (ad-remove-advice, ad-parse-arglist, ad-make-mapped-call):
Juanma Barranquero <lekktu@gmail.com>
parents: 70899
diff changeset
2413 (let ((advice-to-remove (ad-find-advice function class name)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2414 (if advice-to-remove
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2415 (ad-set-advice-info-field
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2416 function class
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2417 (delq advice-to-remove (ad-get-advice-info-field function class)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2418 (error "ad-remove-advice: `%s' has no %s advice `%s'"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2419 function class name)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2420 (error "ad-remove-advice: `%s' is not advised" function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2421
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2422 ;;;###autoload
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2423 (defun ad-add-advice (function advice class position)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2424 "Add a piece of ADVICE to FUNCTION's list of advices in CLASS.
106870
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2425
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2426 ADVICE has the form (NAME PROTECTED ENABLED DEFINITION), where
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2427 NAME is the advice name; PROTECTED is a flag specifying whether
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2428 to protect against non-local exits; ENABLED is a flag specifying
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2429 whether to initially enable the advice; and DEFINITION has the
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2430 form (advice . LAMBDA), where LAMBDA is a lambda expression.
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2431
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2432 If FUNCTION already has a piece of advice with the same name,
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2433 then POSITION is ignored, and the old advice is overwritten with
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2434 the new one.
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2435
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2436 If FUNCTION already has one or more pieces of advice of the
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2437 specified CLASS, then POSITION determines where the new piece
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2438 goes. POSITION can either be `first', `last' or a number (where
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2439 0 corresponds to `first', and numbers outside the valid range are
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2440 mapped to the closest extremal position).
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2441
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2442 If FUNCTION was not advised already, its advice info will be
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2443 initialized. Redefining a piece of advice whose name is part of
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2444 the cache-id will clear the cache.
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2445
3604fe47137d * emacs-lisp/advice.el (ad-add-advice): Doc fix (Bug#5274)
Chong Yidong <cyd@stupidchicken.com>
parents: 106815
diff changeset
2446 See Info node `(elisp)Computed Advice' for detailed documentation."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2447 (cond ((not (ad-is-advised function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2448 (ad-initialize-advice-info function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2449 (ad-set-advice-info-field
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2450 function 'origname (ad-make-origname function))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2451 (let* ((previous-position
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2452 (ad-advice-position function class (ad-advice-name advice)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2453 (advices (ad-get-advice-info-field function class))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2454 ;; Determine a numerical position for the new advice:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2455 (position (cond (previous-position)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2456 ((eq position 'first) 0)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2457 ((eq position 'last) (length advices))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2458 ((numberp position)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2459 (max 0 (min position (length advices))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2460 (t 0))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2461 ;; Check whether we have to clear the cache:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2462 (if (memq (ad-advice-name advice) (ad-get-cache-class-id function class))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2463 (ad-clear-cache function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2464 (if previous-position
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2465 (setcar (nthcdr position advices) advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2466 (if (= position 0)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2467 (ad-set-advice-info-field function class (cons advice advices))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2468 (setcdr (nthcdr (1- position) advices)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2469 (cons advice (nthcdr position advices)))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2470
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2471
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2472 ;; @@ Accessing and manipulating function definitions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2473 ;; ===================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2474
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2475 (defmacro ad-macrofy (definition)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2476 "Take a lambda function DEFINITION and make a macro out of it."
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2477 `(cons 'macro ,definition))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2478
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2479 (defmacro ad-lambdafy (definition)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2480 "Take a macro function DEFINITION and make a lambda out of it."
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2481 `(cdr ,definition))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2482
80879
cdee0fbb5943 (ad-special-forms): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 75346
diff changeset
2483 (defun ad-special-form-p (definition)
94737
f94711def01d (ad-special-form-p): Don't use `iff' in docstring.
Juanma Barranquero <lekktu@gmail.com>
parents: 94655
diff changeset
2484 "Non-nil if and only if DEFINITION is a special form."
80879
cdee0fbb5943 (ad-special-forms): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 75346
diff changeset
2485 (if (and (symbolp definition) (fboundp definition))
cdee0fbb5943 (ad-special-forms): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 75346
diff changeset
2486 (setq definition (indirect-function definition)))
cdee0fbb5943 (ad-special-forms): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 75346
diff changeset
2487 (and (subrp definition) (eq (cdr (subr-arity definition)) 'unevalled)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2488
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2489 (defmacro ad-subr-p (definition)
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2490 ;;"non-nil if DEFINITION is a subr."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2491 (list 'subrp definition))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2492
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2493 (defmacro ad-macro-p (definition)
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2494 ;;"non-nil if DEFINITION is a macro."
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2495 `(eq (car-safe ,definition) 'macro))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2496
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2497 (defmacro ad-lambda-p (definition)
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2498 ;;"non-nil if DEFINITION is a lambda expression."
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2499 `(eq (car-safe ,definition) 'lambda))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2500
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2501 ;; see ad-make-advice for the format of advice definitions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2502 (defmacro ad-advice-p (definition)
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2503 ;;"non-nil if DEFINITION is a piece of advice."
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2504 `(eq (car-safe ,definition) 'advice))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2505
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2506 ;; Emacs/Lemacs cross-compatibility
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2507 ;; (compiled-function-p is an obsolete function in Emacs):
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2508 (if (and (not (fboundp 'byte-code-function-p))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2509 (fboundp 'compiled-function-p))
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2510 (ad-safe-fset 'byte-code-function-p 'compiled-function-p))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2511
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2512 (defmacro ad-compiled-p (definition)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2513 "Return non-nil if DEFINITION is a compiled byte-code object."
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2514 `(or (byte-code-function-p ,definition)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2515 (and (ad-macro-p ,definition)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2516 (byte-code-function-p (ad-lambdafy ,definition)))))
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2517
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2518 (defmacro ad-compiled-code (compiled-definition)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2519 "Return the byte-code object of a COMPILED-DEFINITION."
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2520 `(if (ad-macro-p ,compiled-definition)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2521 (ad-lambdafy ,compiled-definition)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2522 ,compiled-definition))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2523
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2524 (defun ad-lambda-expression (definition)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2525 "Return the lambda expression of a function/macro/advice DEFINITION."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2526 (cond ((ad-lambda-p definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2527 definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2528 ((ad-macro-p definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2529 (ad-lambdafy definition))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2530 ((ad-advice-p definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2531 (cdr definition))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2532 (t nil)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2533
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2534 (defun ad-arglist (definition &optional name)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2535 "Return the argument list of DEFINITION.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2536 If DEFINITION could be from a subr then its NAME should be
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2537 supplied to make subr arglist lookup more efficient."
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2538 (cond ((ad-compiled-p definition)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2539 (aref (ad-compiled-code definition) 0))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2540 ((consp definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2541 (car (cdr (ad-lambda-expression definition))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2542 ((ad-subr-p definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2543 (if name
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2544 (ad-subr-arglist name)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2545 ;; otherwise get it from its printed representation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2546 (setq name (format "%s" definition))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2547 (string-match "^#<subr \\([^>]+\\)>$" name)
50800
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
2548 (ad-subr-arglist (intern (match-string 1 name)))))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2549
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2550 ;; Store subr-args as `((arg1 arg2 ...))' so I can distinguish
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2551 ;; a defined empty arglist `(nil)' from an undefined arglist:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2552 (defmacro ad-define-subr-args (subr arglist)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2553 `(put ,subr 'ad-subr-arglist (list ,arglist)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2554 (defmacro ad-undefine-subr-args (subr)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2555 `(put ,subr 'ad-subr-arglist nil))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2556 (defmacro ad-subr-args-defined-p (subr)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2557 `(get ,subr 'ad-subr-arglist))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2558 (defmacro ad-get-subr-args (subr)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2559 `(car (get ,subr 'ad-subr-arglist)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2560
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2561 (defun ad-subr-arglist (subr-name)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2562 "Retrieve arglist of the subr with SUBR-NAME.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2563 Either use the one stored under the `ad-subr-arglist' property,
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2564 or try to retrieve it from the docstring and cache it under
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2565 that property, or otherwise use `(&rest ad-subr-args)'."
54493
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2566 (if (ad-subr-args-defined-p subr-name)
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2567 (ad-get-subr-args subr-name)
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2568 ;; says jwz: Should use this for Lemacs 19.8 and above:
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2569 ;;((fboundp 'subr-min-args)
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2570 ;; ...)
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2571 ;; says hans: I guess what Jamie means is that I should use the values
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2572 ;; of `subr-min-args' and `subr-max-args' to construct the subr arglist
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2573 ;; without having to look it up via parsing the docstring, e.g.,
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2574 ;; values 1 and 2 would suggest `(arg1 &optional arg2)' as an
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2575 ;; argument list. However, that won't work because there is no
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2576 ;; way to distinguish a subr with args `(a &optional b &rest c)' from
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2577 ;; one with args `(a &rest c)' using that mechanism. Also, the argument
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2578 ;; names from the docstring are more meaningful. Hence, I'll stick with
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2579 ;; the old way of doing things.
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2580 (let ((doc (or (ad-real-documentation subr-name t) "")))
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2581 (if (not (string-match "\n\n\\((.+)\\)\\'" doc))
54509
e20bae3e3270 (ad-subr-arglist): Undo part of last patch.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 54493
diff changeset
2582 ;; Signalling an error leads to bugs during bootstrapping because
e20bae3e3270 (ad-subr-arglist): Undo part of last patch.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 54493
diff changeset
2583 ;; the DOC file is not yet built (which is an error, BTW).
e20bae3e3270 (ad-subr-arglist): Undo part of last patch.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 54493
diff changeset
2584 ;; (error "The usage info is missing from the subr %s" subr-name)
e20bae3e3270 (ad-subr-arglist): Undo part of last patch.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 54493
diff changeset
2585 '(&rest ad-subr-args)
54493
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2586 (ad-define-subr-args
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2587 subr-name
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2588 (cdr (car (read-from-string
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2589 (downcase (match-string 1 doc))))))
d8586f19729a (ad-subr-arglist): Simplify.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 52401
diff changeset
2590 (ad-get-subr-args subr-name)))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2591
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2592 (defun ad-docstring (definition)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2593 "Return the unexpanded docstring of DEFINITION."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2594 (let ((docstring
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2595 (if (ad-compiled-p definition)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2596 (ad-real-documentation definition t)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2597 (car (cdr (cdr (ad-lambda-expression definition)))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2598 (if (or (stringp docstring)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2599 (natnump docstring))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2600 docstring)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2601
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2602 (defun ad-interactive-form (definition)
82192
5800574abbcb (ad-interactive-form): Re-introduce.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82146
diff changeset
2603 "Return the interactive form of DEFINITION.
5800574abbcb (ad-interactive-form): Re-introduce.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82146
diff changeset
2604 Like `interactive-form', but also works on pieces of advice."
5800574abbcb (ad-interactive-form): Re-introduce.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82146
diff changeset
2605 (interactive-form
5800574abbcb (ad-interactive-form): Re-introduce.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82146
diff changeset
2606 (if (ad-advice-p definition)
5800574abbcb (ad-interactive-form): Re-introduce.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82146
diff changeset
2607 (ad-lambda-expression definition)
5800574abbcb (ad-interactive-form): Re-introduce.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82146
diff changeset
2608 definition)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2609
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2610 (defun ad-body-forms (definition)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2611 "Return the list of body forms of DEFINITION."
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2612 (cond ((ad-compiled-p definition)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2613 nil)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2614 ((consp definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2615 (nthcdr (+ (if (ad-docstring definition) 1 0)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2616 (if (ad-interactive-form definition) 1 0))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2617 (cdr (cdr (ad-lambda-expression definition)))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2618
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2619 (defun ad-make-advised-definition-docstring (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2620 "Make an identifying docstring for the advised definition of FUNCTION.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2621 Put function name into the documentation string so we can infer
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2622 the name of the advised function from the docstring. This is needed
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2623 to generate a proper advised docstring even if we are just given a
85302
bc8b741390b0 (documentation): Advice deleted. Doc for advised functions
Richard M. Stallman <rms@gnu.org>
parents: 83896
diff changeset
2624 definition (see the code for `documentation')."
bc8b741390b0 (documentation): Advice deleted. Doc for advised functions
Richard M. Stallman <rms@gnu.org>
parents: 83896
diff changeset
2625 (propertize "Advice doc string" 'ad-advice-info function))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2626
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2627 (defun ad-advised-definition-p (definition)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2628 "Return non-nil if DEFINITION was generated from advice information."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2629 (if (or (ad-lambda-p definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2630 (ad-macro-p definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2631 (ad-compiled-p definition))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2632 (let ((docstring (ad-docstring definition)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2633 (and (stringp docstring)
85302
bc8b741390b0 (documentation): Advice deleted. Doc for advised functions
Richard M. Stallman <rms@gnu.org>
parents: 83896
diff changeset
2634 (get-text-property 0 'ad-advice-info docstring)))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2635
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2636 (defun ad-definition-type (definition)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2637 "Return symbol that describes the type of DEFINITION."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2638 (if (ad-macro-p definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2639 'macro
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2640 (if (ad-subr-p definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2641 (if (ad-special-form-p definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2642 'special-form
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2643 'subr)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2644 (if (or (ad-lambda-p definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2645 (ad-compiled-p definition))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2646 'function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2647 (if (ad-advice-p definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2648 'advice)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2649
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2650 (defun ad-has-proper-definition (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2651 "True if FUNCTION is a symbol with a proper definition.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2652 For that it has to be fbound with a non-autoload definition."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2653 (and (symbolp function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2654 (fboundp function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2655 (not (eq (car-safe (symbol-function function)) 'autoload))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2656
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2657 ;; The following two are necessary for the sake of packages such as
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2658 ;; ange-ftp which redefine functions via fcell indirection:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2659 (defun ad-real-definition (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2660 "Find FUNCTION's definition at the end of function cell indirection."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2661 (if (ad-has-proper-definition function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2662 (let ((definition (symbol-function function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2663 (if (symbolp definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2664 (ad-real-definition definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2665 definition))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2666
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2667 (defun ad-real-orig-definition (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2668 "Find FUNCTION's real original definition starting from its `origname'."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2669 (if (ad-is-advised function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2670 (ad-real-definition (ad-get-advice-info-field function 'origname))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2671
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2672 (defun ad-is-compilable (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2673 "True if FUNCTION has an interpreted definition that can be compiled."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2674 (and (ad-has-proper-definition function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2675 (or (ad-lambda-p (symbol-function function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2676 (ad-macro-p (symbol-function function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2677 (not (ad-compiled-p (symbol-function function)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2678
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2679 (defun ad-compile-function (function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2680 "Byte-compiles FUNCTION (or macro) if it is not yet compiled."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2681 (interactive "aByte-compile function: ")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2682 (if (ad-is-compilable function)
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2683 ;; Need to turn off auto-activation
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2684 ;; because `byte-compile' uses `fset':
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
2685 (ad-with-auto-activation-disabled
46196
73cafacdf14f (ad-compile-function): Disable cl-function warnings if cl is loaded.
Richard M. Stallman <rms@gnu.org>
parents: 45019
diff changeset
2686 (require 'bytecomp)
73cafacdf14f (ad-compile-function): Disable cl-function warnings if cl is loaded.
Richard M. Stallman <rms@gnu.org>
parents: 45019
diff changeset
2687 (let ((symbol (make-symbol "advice-compilation"))
107152
34e2c3832e08 (ad-compile-function): Suppress byte-compiler warnings, since it is annoying
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 106966
diff changeset
2688 (byte-compile-warnings byte-compile-warnings)
34e2c3832e08 (ad-compile-function): Suppress byte-compiler warnings, since it is annoying
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 106966
diff changeset
2689 ;; Don't pop up windows showing byte-compiler warnings.
107153
2c62b10c201b (ad-compile-function): Fix last change.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 107152
diff changeset
2690 (warning-suppress-types '((bytecomp))))
46196
73cafacdf14f (ad-compile-function): Disable cl-function warnings if cl is loaded.
Richard M. Stallman <rms@gnu.org>
parents: 45019
diff changeset
2691 (if (featurep 'cl)
85729
bd2837f89a3b (ad-compile-function): Use byte-compile-disable-warning.
Glenn Morris <rgm@gnu.org>
parents: 85584
diff changeset
2692 (byte-compile-disable-warning 'cl-functions))
41936
2fba35852455 (ad-compile-function):
Richard M. Stallman <rms@gnu.org>
parents: 41608
diff changeset
2693 (fset symbol (symbol-function function))
2fba35852455 (ad-compile-function):
Richard M. Stallman <rms@gnu.org>
parents: 41608
diff changeset
2694 (byte-compile symbol)
2fba35852455 (ad-compile-function):
Richard M. Stallman <rms@gnu.org>
parents: 41608
diff changeset
2695 (fset function (symbol-function symbol))))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2696
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2697
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2698 ;; @@ Constructing advised definitions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2699 ;; ====================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2700 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2701 ;; Main design decisions about the form of advised definitions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2702 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2703 ;; A) How will original definitions be called?
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2704 ;; B) What will argument lists of advised functions look like?
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2705 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2706 ;; Ad A)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2707 ;; I chose to use function indirection for all four types of original
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2708 ;; definitions (functions, macros, subrs and special forms), i.e., create
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2709 ;; a unique symbol `ad-Orig-<name>' which is fbound to the original
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2710 ;; definition and call it according to type and arguments. Functions and
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2711 ;; subrs that don't have any &rest arguments can be called directly in a
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2712 ;; `(ad-Orig-<name> ....)' form. If they have a &rest argument we have to
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2713 ;; use `apply'. Macros will be called with
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2714 ;; `(macroexpand '(ad-Orig-<name> ....))', and special forms also need a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2715 ;; form like that with `eval' instead of `macroexpand'.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2716 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2717 ;; Ad B)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2718 ;; Use original arguments where possible and `(&rest ad-subr-args)'
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2719 ;; otherwise, even though this seems to be more complicated and less
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2720 ;; uniform than a general `(&rest args)' approach. My reason to still
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2721 ;; do it that way is that in most cases my approach leads to the more
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2722 ;; efficient form for the advised function, and portability (e.g., to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2723 ;; make the same advice work regardless of whether something is a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2724 ;; function or a subr) can still be achieved with argument access macros.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2725
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2726
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2727 (defun ad-prognify (forms)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2728 (cond ((<= (length forms) 1)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2729 (car forms))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2730 (t (cons 'progn forms))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2731
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2732 ;; @@@ Accessing argument lists:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2733 ;; =============================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2734
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2735 (defun ad-parse-arglist (arglist)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2736 "Parse ARGLIST into its required, optional and rest parameters.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2737 A three-element list is returned, where the 1st element is the list of
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2738 required arguments, the 2nd is the list of optional arguments, and the 3rd
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2739 is the name of an optional rest parameter (or nil)."
73251
25e1db3fd0ed (ad-remove-advice, ad-parse-arglist, ad-make-mapped-call):
Juanma Barranquero <lekktu@gmail.com>
parents: 70899
diff changeset
2740 (let (required optional rest)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2741 (setq rest (car (cdr (memq '&rest arglist))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2742 (if rest (setq arglist (reverse (cdr (memq '&rest (reverse arglist))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2743 (setq optional (cdr (memq '&optional arglist)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2744 (if optional
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2745 (setq required (reverse (cdr (memq '&optional (reverse arglist)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2746 (setq required arglist))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2747 (list required optional rest)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2748
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2749 (defun ad-retrieve-args-form (arglist)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2750 "Generate a form which evaluates into names/values/types of ARGLIST.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2751 When the form gets evaluated within a function with that argument list
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2752 it will result in a list with one entry for each argument, where the
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2753 first element of each entry is the name of the argument, the second
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2754 element is its actual current value, and the third element is either
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2755 `required', `optional' or `rest' depending on the type of the argument."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2756 (let* ((parsed-arglist (ad-parse-arglist arglist))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2757 (rest (nth 2 parsed-arglist)))
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2758 `(list
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2759 ,@(mapcar (function
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2760 (lambda (req)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2761 `(list ',req ,req 'required)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2762 (nth 0 parsed-arglist))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2763 ,@(mapcar (function
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2764 (lambda (opt)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2765 `(list ',opt ,opt 'optional)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2766 (nth 1 parsed-arglist))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2767 ,@(if rest (list `(list ',rest ,rest 'rest))))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2768
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2769 (defun ad-arg-binding-field (binding field)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2770 (cond ((eq field 'name) (car binding))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2771 ((eq field 'value) (car (cdr binding)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2772 ((eq field 'type) (car (cdr (cdr binding))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2773
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2774 (defun ad-list-access (position list)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2775 (cond ((= position 0) list)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2776 ((= position 1) (list 'cdr list))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2777 (t (list 'nthcdr position list))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2778
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2779 (defun ad-element-access (position list)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2780 (cond ((= position 0) (list 'car list))
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2781 ((= position 1) `(car (cdr ,list)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2782 (t (list 'nth position list))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2783
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2784 (defun ad-access-argument (arglist index)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2785 "Tell how to access ARGLIST's actual argument at position INDEX.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2786 For a required/optional arg it simply returns it, if a rest argument has
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2787 to be accessed, it returns a list with the index and name."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2788 (let* ((parsed-arglist (ad-parse-arglist arglist))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2789 (reqopt-args (append (nth 0 parsed-arglist)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2790 (nth 1 parsed-arglist)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2791 (rest-arg (nth 2 parsed-arglist)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2792 (cond ((< index (length reqopt-args))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2793 (nth index reqopt-args))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2794 (rest-arg
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2795 (list (- index (length reqopt-args)) rest-arg)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2796
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2797 (defun ad-get-argument (arglist index)
105113
1a0de48a918c * emacs-lisp/advice.el (ad-get-argument, ad-set-argument): Doc
Chong Yidong <cyd@stupidchicken.com>
parents: 104024
diff changeset
2798 "Return form to access ARGLIST's actual argument at position INDEX.
1a0de48a918c * emacs-lisp/advice.el (ad-get-argument, ad-set-argument): Doc
Chong Yidong <cyd@stupidchicken.com>
parents: 104024
diff changeset
2799 INDEX counts from zero."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2800 (let ((argument-access (ad-access-argument arglist index)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2801 (cond ((consp argument-access)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2802 (ad-element-access
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2803 (car argument-access) (car (cdr argument-access))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2804 (argument-access))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2805
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2806 (defun ad-set-argument (arglist index value-form)
105113
1a0de48a918c * emacs-lisp/advice.el (ad-get-argument, ad-set-argument): Doc
Chong Yidong <cyd@stupidchicken.com>
parents: 104024
diff changeset
2807 "Return form to set ARGLIST's actual arg at INDEX to VALUE-FORM.
1a0de48a918c * emacs-lisp/advice.el (ad-get-argument, ad-set-argument): Doc
Chong Yidong <cyd@stupidchicken.com>
parents: 104024
diff changeset
2808 INDEX counts from zero."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2809 (let ((argument-access (ad-access-argument arglist index)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2810 (cond ((consp argument-access)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2811 ;; should this check whether there actually is something to set?
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2812 `(setcar ,(ad-list-access
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2813 (car argument-access) (car (cdr argument-access)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2814 ,value-form))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2815 (argument-access
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2816 `(setq ,argument-access ,value-form))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2817 (t (error "ad-set-argument: No argument at position %d of `%s'"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2818 index arglist)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2819
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2820 (defun ad-get-arguments (arglist index)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2821 "Return form to access all actual arguments starting at position INDEX."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2822 (let* ((parsed-arglist (ad-parse-arglist arglist))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2823 (reqopt-args (append (nth 0 parsed-arglist)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2824 (nth 1 parsed-arglist)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2825 (rest-arg (nth 2 parsed-arglist))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2826 args-form)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2827 (if (< index (length reqopt-args))
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2828 (setq args-form `(list ,@(nthcdr index reqopt-args))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2829 (if rest-arg
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2830 (if args-form
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2831 (setq args-form `(nconc ,args-form ,rest-arg))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2832 (setq args-form (ad-list-access (- index (length reqopt-args))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2833 rest-arg))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2834 args-form))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2835
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2836 (defun ad-set-arguments (arglist index values-form)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2837 "Make form to assign elements of VALUES-FORM as actual ARGLIST args.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2838 The assignment starts at position INDEX."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2839 (let ((values-index 0)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2840 argument-access set-forms)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2841 (while (setq argument-access (ad-access-argument arglist index))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2842 (if (symbolp argument-access)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2843 (setq set-forms
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2844 (cons (ad-set-argument
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2845 arglist index
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2846 (ad-element-access values-index 'ad-vAlUeS))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2847 set-forms))
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2848 (setq set-forms
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2849 (cons (if (= (car argument-access) 0)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2850 (list 'setq
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2851 (car (cdr argument-access))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2852 (ad-list-access values-index 'ad-vAlUeS))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2853 (list 'setcdr
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2854 (ad-list-access (1- (car argument-access))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2855 (car (cdr argument-access)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2856 (ad-list-access values-index 'ad-vAlUeS)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2857 set-forms))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2858 ;; terminate loop
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2859 (setq arglist nil))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2860 (setq index (1+ index))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2861 (setq values-index (1+ values-index)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2862 (if (null set-forms)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2863 (error "ad-set-arguments: No argument at position %d of `%s'"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2864 index arglist)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2865 (if (= (length set-forms) 1)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2866 ;; For exactly one set-form we can use values-form directly,...
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2867 (ad-substitute-tree
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2868 (function (lambda (form) (eq form 'ad-vAlUeS)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2869 (function (lambda (form) values-form))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2870 (car set-forms))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2871 ;; ...if we have more we have to bind it to a variable:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2872 `(let ((ad-vAlUeS ,values-form))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2873 ,@(reverse set-forms)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2874 ;; work around the old backquote bug:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
2875 ,'ad-vAlUeS)))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2876
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2877 (defun ad-insert-argument-access-forms (definition arglist)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2878 "Expands arg-access text macros in DEFINITION according to ARGLIST."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2879 (ad-substitute-tree
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2880 (function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2881 (lambda (form)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2882 (or (eq form 'ad-arg-bindings)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2883 (and (memq (car-safe form)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2884 '(ad-get-arg ad-get-args ad-set-arg ad-set-args))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2885 (integerp (car-safe (cdr form)))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2886 (function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2887 (lambda (form)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2888 (if (eq form 'ad-arg-bindings)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2889 (ad-retrieve-args-form arglist)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2890 (let ((accessor (car form))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2891 (index (car (cdr form)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2892 (val (car (cdr (ad-insert-argument-access-forms
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2893 (cdr form) arglist)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2894 (cond ((eq accessor 'ad-get-arg)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2895 (ad-get-argument arglist index))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2896 ((eq accessor 'ad-set-arg)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2897 (ad-set-argument arglist index val))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2898 ((eq accessor 'ad-get-args)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2899 (ad-get-arguments arglist index))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2900 ((eq accessor 'ad-set-args)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2901 (ad-set-arguments arglist index val)))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2902 definition))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2903
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2904 ;; @@@ Mapping argument lists:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2905 ;; ===========================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2906 ;; Here is the problem:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2907 ;; Suppose function foo was called with (foo 1 2 3 4 5), and foo has the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2908 ;; argument list (x y &rest z), and we want to call the function bar which
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2909 ;; has argument list (a &rest b) with a combination of x, y and z so that
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2910 ;; the effect is just as if we had called (bar 1 2 3 4 5) directly.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2911 ;; The mapping should work for any two argument lists.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2912
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2913 (defun ad-map-arglists (source-arglist target-arglist)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2914 "Make `funcall/apply' form to map SOURCE-ARGLIST to TARGET-ARGLIST.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2915 The arguments supplied to TARGET-ARGLIST will be taken from SOURCE-ARGLIST just
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2916 as if they had been supplied to a function with TARGET-ARGLIST directly.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2917 Excess source arguments will be neglected, missing source arguments will be
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2918 supplied as nil. Returns a `funcall' or `apply' form with the second element
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2919 being `function' which has to be replaced by an actual function argument.
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2920 Example: `(ad-map-arglists '(a &rest args) '(w x y z))' will return
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2921 `(funcall function a (car args) (car (cdr args)) (nth 2 args))'."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2922 (let* ((parsed-source-arglist (ad-parse-arglist source-arglist))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2923 (source-reqopt-args (append (nth 0 parsed-source-arglist)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2924 (nth 1 parsed-source-arglist)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2925 (source-rest-arg (nth 2 parsed-source-arglist))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2926 (parsed-target-arglist (ad-parse-arglist target-arglist))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2927 (target-reqopt-args (append (nth 0 parsed-target-arglist)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2928 (nth 1 parsed-target-arglist)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2929 (target-rest-arg (nth 2 parsed-target-arglist))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2930 (need-apply (and source-rest-arg target-rest-arg))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2931 (target-arg-index -1))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2932 ;; This produces ``error-proof'' target function calls with the exception
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2933 ;; of a case like (&rest a) mapped onto (x &rest y) where the actual args
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2934 ;; supplied to A might not be enough to supply the required target arg X
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2935 (append (list (if need-apply 'apply 'funcall) 'function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2936 (cond (need-apply
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2937 ;; `apply' can take care of that directly:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2938 (append source-reqopt-args (list source-rest-arg)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2939 (t (mapcar (function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2940 (lambda (arg)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2941 (setq target-arg-index (1+ target-arg-index))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2942 (ad-get-argument
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2943 source-arglist target-arg-index)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2944 (append target-reqopt-args
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2945 (and target-rest-arg
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2946 ;; If we have a rest arg gobble up
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2947 ;; remaining source args:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2948 (nthcdr (length target-reqopt-args)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2949 source-reqopt-args)))))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2950
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2951 (defun ad-make-mapped-call (source-arglist target-arglist target-function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
2952 "Make form to call TARGET-FUNCTION with args from SOURCE-ARGLIST."
73251
25e1db3fd0ed (ad-remove-advice, ad-parse-arglist, ad-make-mapped-call):
Juanma Barranquero <lekktu@gmail.com>
parents: 70899
diff changeset
2953 (let ((mapped-form (ad-map-arglists source-arglist target-arglist)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2954 (if (eq (car mapped-form) 'funcall)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2955 (cons target-function (cdr (cdr mapped-form)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2956 (prog1 mapped-form
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2957 (setcar (cdr mapped-form) (list 'quote target-function))))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2958
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2959 ;; @@@ Making an advised documentation string:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2960 ;; ===========================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2961 ;; New policy: The documentation string for an advised function will be built
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2962 ;; at the time the advised `documentation' function is called. This has the
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2963 ;; following advantages:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2964 ;; 1) command-key substitutions will automatically be correct
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2965 ;; 2) No wasted string space due to big advised docstrings in caches or
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2966 ;; compiled files that contain preactivations
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2967 ;; The overall overhead for this should be negligible because people normally
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2968 ;; don't lookup documentation for the same function over and over again.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2969
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2970 (defun ad-make-single-advice-docstring (advice class &optional style)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2971 (let ((advice-docstring (ad-docstring (ad-advice-definition advice))))
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2972 (cond ((eq style 'plain)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2973 advice-docstring)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2974 ((eq style 'freeze)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2975 (format "Permanent %s-advice `%s':%s%s"
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2976 class (ad-advice-name advice)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2977 (if advice-docstring "\n" "")
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2978 (or advice-docstring "")))
25208
76f5f50e7742 (ad-make-single-advice-docstring): Treat case with no doctring specially.
Dave Love <fx@gnu.org>
parents: 24875
diff changeset
2979 (t (if advice-docstring
76f5f50e7742 (ad-make-single-advice-docstring): Treat case with no doctring specially.
Dave Love <fx@gnu.org>
parents: 24875
diff changeset
2980 (format "%s-advice `%s':\n%s"
76f5f50e7742 (ad-make-single-advice-docstring): Treat case with no doctring specially.
Dave Love <fx@gnu.org>
parents: 24875
diff changeset
2981 (capitalize (symbol-name class))
76f5f50e7742 (ad-make-single-advice-docstring): Treat case with no doctring specially.
Dave Love <fx@gnu.org>
parents: 24875
diff changeset
2982 (ad-advice-name advice)
76f5f50e7742 (ad-make-single-advice-docstring): Treat case with no doctring specially.
Dave Love <fx@gnu.org>
parents: 24875
diff changeset
2983 advice-docstring)
76f5f50e7742 (ad-make-single-advice-docstring): Treat case with no doctring specially.
Dave Love <fx@gnu.org>
parents: 24875
diff changeset
2984 (format "%s-advice `%s'."
76f5f50e7742 (ad-make-single-advice-docstring): Treat case with no doctring specially.
Dave Love <fx@gnu.org>
parents: 24875
diff changeset
2985 (capitalize (symbol-name class))
76f5f50e7742 (ad-make-single-advice-docstring): Treat case with no doctring specially.
Dave Love <fx@gnu.org>
parents: 24875
diff changeset
2986 (ad-advice-name advice)))))))
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2987
50800
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
2988 (require 'help-fns) ;For help-split-fundoc and help-add-fundoc-usage.
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
2989
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2990 (defun ad-make-advised-docstring (function &optional style)
50800
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
2991 "Construct a documentation string for the advised FUNCTION.
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
2992 It concatenates the original documentation with the documentation
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
2993 strings of the individual pieces of advice which will be formatted
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
2994 according to STYLE. STYLE can be `plain' or `freeze', everything else
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
2995 will be interpreted as `default'. The order of the advice documentation
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
2996 strings corresponds to before/around/after and the individual ordering
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
2997 in any of these classes."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
2998 (let* ((origdef (ad-real-orig-definition function))
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
2999 (origtype (symbol-name (ad-definition-type origdef)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3000 (origdoc
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3001 ;; Retrieve raw doc, key substitution will be taken care of later:
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3002 (ad-real-documentation origdef t))
50800
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
3003 (usage (help-split-fundoc origdoc function))
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
3004 paragraphs advice-docstring ad-usage)
50842
b64d29a02737 (ad-make-advised-docstring): Adjust usage for new help-add-fundoc-usage.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 50800
diff changeset
3005 (setq usage (if (null usage) t (setq origdoc (cdr usage)) (car usage)))
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3006 (if origdoc (setq paragraphs (list origdoc)))
50800
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
3007 (unless (eq style 'plain)
83896
0fc42eec71c0 Johan Bockg? <bojohan at dd.chalmers.se>
Glenn Morris <rgm@gnu.org>
parents: 82192
diff changeset
3008 (push (propertize (concat "This " origtype " is advised.")
0fc42eec71c0 Johan Bockg? <bojohan at dd.chalmers.se>
Glenn Morris <rgm@gnu.org>
parents: 82192
diff changeset
3009 'face 'font-lock-warning-face)
0fc42eec71c0 Johan Bockg? <bojohan at dd.chalmers.se>
Glenn Morris <rgm@gnu.org>
parents: 82192
diff changeset
3010 paragraphs))
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3011 (ad-dolist (class ad-advice-classes)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3012 (ad-dolist (advice (ad-get-enabled-advices function class))
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3013 (setq advice-docstring
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3014 (ad-make-single-advice-docstring advice class style))
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3015 (if advice-docstring
50800
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
3016 (push advice-docstring paragraphs))))
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
3017 (setq origdoc (if paragraphs
85584
91aa73da6526 (ad-make-advised-docstring): Add ad-advice-info text property to doc string.
Juanma Barranquero <lekktu@gmail.com>
parents: 85320
diff changeset
3018 (propertize
91aa73da6526 (ad-make-advised-docstring): Add ad-advice-info text property to doc string.
Juanma Barranquero <lekktu@gmail.com>
parents: 85320
diff changeset
3019 ;; separate paragraphs with blank lines:
91aa73da6526 (ad-make-advised-docstring): Add ad-advice-info text property to doc string.
Juanma Barranquero <lekktu@gmail.com>
parents: 85320
diff changeset
3020 (mapconcat 'identity (nreverse paragraphs) "\n\n")
91aa73da6526 (ad-make-advised-docstring): Add ad-advice-info text property to doc string.
Juanma Barranquero <lekktu@gmail.com>
parents: 85320
diff changeset
3021 'ad-advice-info function)))
50800
7fe53d25e220 (ad-get-enabled-advices, ad-special-forms)
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46196
diff changeset
3022 (help-add-fundoc-usage origdoc usage)))
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3023
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3024 (defun ad-make-plain-docstring (function)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3025 (ad-make-advised-docstring function 'plain))
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3026 (defun ad-make-freeze-docstring (function)
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3027 (ad-make-advised-docstring function 'freeze))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3028
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3029 ;; @@@ Accessing overriding arglists and interactive forms:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3030 ;; ========================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3031
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3032 (defun ad-advised-arglist (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3033 "Find first defined arglist in FUNCTION's redefining advices."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3034 (ad-dolist (advice (append (ad-get-enabled-advices function 'before)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3035 (ad-get-enabled-advices function 'around)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3036 (ad-get-enabled-advices function 'after)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3037 (let ((arglist (ad-arglist (ad-advice-definition advice))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3038 (if arglist
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3039 ;; We found the first one, use it:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3040 (ad-do-return arglist)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3041
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3042 (defun ad-advised-interactive-form (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3043 "Find first interactive form in FUNCTION's redefining advices."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3044 (ad-dolist (advice (append (ad-get-enabled-advices function 'before)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3045 (ad-get-enabled-advices function 'around)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3046 (ad-get-enabled-advices function 'after)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3047 (let ((interactive-form
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3048 (ad-interactive-form (ad-advice-definition advice))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3049 (if interactive-form
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3050 ;; We found the first one, use it:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3051 (ad-do-return interactive-form)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3052
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3053 ;; @@@ Putting it all together:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3054 ;; ============================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3055
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3056 (defun ad-make-advised-definition (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3057 "Generate an advised definition of FUNCTION from its advice info."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3058 (if (and (ad-is-advised function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3059 (ad-has-redefining-advice function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3060 (let* ((origdef (ad-real-orig-definition function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3061 (origname (ad-get-advice-info-field function 'origname))
82146
5868631b2e87 (ad-interactive-p, ad-interactive-form): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82140
diff changeset
3062 (orig-interactive-p (commandp origdef))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3063 (orig-subr-p (ad-subr-p origdef))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3064 (orig-special-form-p (ad-special-form-p origdef))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3065 (orig-macro-p (ad-macro-p origdef))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3066 ;; Construct the individual pieces that we need for assembly:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3067 (orig-arglist (ad-arglist origdef function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3068 (advised-arglist (or (ad-advised-arglist function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3069 orig-arglist))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3070 (advised-interactive-form (ad-advised-interactive-form function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3071 (interactive-form
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3072 (cond (orig-macro-p nil)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3073 (advised-interactive-form)
82146
5868631b2e87 (ad-interactive-p, ad-interactive-form): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82140
diff changeset
3074 ((interactive-form origdef)
5868631b2e87 (ad-interactive-p, ad-interactive-form): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82140
diff changeset
3075 (interactive-form
5868631b2e87 (ad-interactive-p, ad-interactive-form): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82140
diff changeset
3076 (if (and (symbolp function) (get function 'elp-info))
5868631b2e87 (ad-interactive-p, ad-interactive-form): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82140
diff changeset
3077 (aref (get function 'elp-info) 2)
5868631b2e87 (ad-interactive-p, ad-interactive-form): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82140
diff changeset
3078 origdef)))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3079 (orig-form
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3080 (cond ((or orig-special-form-p orig-macro-p)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3081 ;; Special forms and macros will be advised into macros.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3082 ;; The trick is to construct an expansion for the advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3083 ;; macro that does the correct thing when it gets eval'ed.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3084 ;; For macros we'll just use the expansion of the original
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3085 ;; macro and return that. This way compiled advised macros
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3086 ;; will be expanded into something useful. Note that after
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3087 ;; advices have full control over whether they want to
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3088 ;; evaluate the expansion (the value of `ad-return-value')
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3089 ;; at macro expansion time or not. For special forms there
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3090 ;; is no solution that interacts reasonably with the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3091 ;; compiler, hence we just evaluate the original at macro
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3092 ;; expansion time and return the result. The moral of that
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3093 ;; is that one should always deactivate advised special
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3094 ;; forms before one byte-compiles a file.
37304
9ca19dfc32fb (ad-make-advised-definition): Construct
Gerd Moellmann <gerd@gnu.org>
parents: 37056
diff changeset
3095 `(,(if orig-macro-p 'macroexpand 'eval)
9ca19dfc32fb (ad-make-advised-definition): Construct
Gerd Moellmann <gerd@gnu.org>
parents: 37056
diff changeset
3096 (cons ',origname
9ca19dfc32fb (ad-make-advised-definition): Construct
Gerd Moellmann <gerd@gnu.org>
parents: 37056
diff changeset
3097 ,(ad-get-arguments advised-arglist 0))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3098 ((and orig-subr-p
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3099 orig-interactive-p
37304
9ca19dfc32fb (ad-make-advised-definition): Construct
Gerd Moellmann <gerd@gnu.org>
parents: 37056
diff changeset
3100 (not interactive-form)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3101 (not advised-interactive-form))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3102 ;; Check whether we were called interactively
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3103 ;; in order to do proper prompting:
105371
0769a73f1d18 * image-mode.el (image-toggle-display):
Juanma Barranquero <lekktu@gmail.com>
parents: 105113
diff changeset
3104 `(if (called-interactively-p 'any)
37304
9ca19dfc32fb (ad-make-advised-definition): Construct
Gerd Moellmann <gerd@gnu.org>
parents: 37056
diff changeset
3105 (call-interactively ',origname)
66398
df04170ba46b (ad-make-advised-definition): Fix arg-order.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 65680
diff changeset
3106 ,(ad-make-mapped-call advised-arglist
df04170ba46b (ad-make-advised-definition): Fix arg-order.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 65680
diff changeset
3107 orig-arglist
37304
9ca19dfc32fb (ad-make-advised-definition): Construct
Gerd Moellmann <gerd@gnu.org>
parents: 37056
diff changeset
3108 origname)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3109 ;; And now for normal functions and non-interactive subrs
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3110 ;; (or subrs whose interactive behavior was advised):
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3111 (t (ad-make-mapped-call
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3112 advised-arglist orig-arglist origname)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3113
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3114 ;; Finally, build the sucker:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3115 (ad-assemble-advised-definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3116 (cond (orig-macro-p 'macro)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3117 (orig-special-form-p 'special-form)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3118 (t 'function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3119 advised-arglist
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3120 (ad-make-advised-definition-docstring function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3121 interactive-form
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3122 orig-form
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3123 (ad-get-enabled-advices function 'before)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3124 (ad-get-enabled-advices function 'around)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3125 (ad-get-enabled-advices function 'after)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3126
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3127 (defun ad-assemble-advised-definition
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3128 (type args docstring interactive orig &optional befores arounds afters)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3129
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3130 "Assembles an original and its advices into an advised function.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3131 It constructs a function or macro definition according to TYPE which has to
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3132 be either `macro', `function' or `special-form'. ARGS is the argument list
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3133 that has to be used, DOCSTRING if non-nil defines the documentation of the
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3134 definition, INTERACTIVE if non-nil is the interactive form to be used,
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3135 ORIG is a form that calls the body of the original unadvised function,
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3136 and BEFORES, AROUNDS and AFTERS are the lists of advices with which ORIG
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3137 should be modified. The assembled function will be returned."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3138
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3139 (let (before-forms around-form around-form-protected after-forms definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3140 (ad-dolist (advice befores)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3141 (cond ((and (ad-advice-protected advice)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3142 before-forms)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3143 (setq before-forms
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3144 `((unwind-protect
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3145 ,(ad-prognify before-forms)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3146 ,@(ad-body-forms
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3147 (ad-advice-definition advice))))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3148 (t (setq before-forms
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3149 (append before-forms
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3150 (ad-body-forms (ad-advice-definition advice)))))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3151
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3152 (setq around-form `(setq ad-return-value ,orig))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3153 (ad-dolist (advice (reverse arounds))
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3154 ;; If any of the around advices is protected then we
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3155 ;; protect the complete around advice onion:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3156 (if (ad-advice-protected advice)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3157 (setq around-form-protected t))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3158 (setq around-form
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3159 (ad-substitute-tree
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3160 (function (lambda (form) (eq form 'ad-do-it)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3161 (function (lambda (form) around-form))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3162 (ad-prognify (ad-body-forms (ad-advice-definition advice))))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3163
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3164 (setq after-forms
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3165 (if (and around-form-protected before-forms)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3166 `((unwind-protect
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3167 ,(ad-prognify before-forms)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3168 ,around-form))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3169 (append before-forms (list around-form))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3170 (ad-dolist (advice afters)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3171 (cond ((and (ad-advice-protected advice)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3172 after-forms)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3173 (setq after-forms
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3174 `((unwind-protect
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3175 ,(ad-prognify after-forms)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3176 ,@(ad-body-forms
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3177 (ad-advice-definition advice))))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3178 (t (setq after-forms
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3179 (append after-forms
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3180 (ad-body-forms (ad-advice-definition advice)))))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3181
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3182 (setq definition
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3183 `(,@(if (memq type '(macro special-form)) '(macro))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3184 lambda
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3185 ,args
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3186 ,@(if docstring (list docstring))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3187 ,@(if interactive (list interactive))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3188 (let (ad-return-value)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3189 ,@after-forms
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3190 ,(if (eq type 'special-form)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3191 '(list 'quote ad-return-value)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3192 'ad-return-value))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3193
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3194 (ad-insert-argument-access-forms definition args)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3195
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3196 ;; This is needed for activation/deactivation hooks:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3197 (defun ad-make-hook-form (function hook-name)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3198 "Make hook-form from FUNCTION's advice bodies in class HOOK-NAME."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3199 (let ((hook-forms
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3200 (mapcar (function (lambda (advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3201 (ad-body-forms (ad-advice-definition advice))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3202 (ad-get-enabled-advices function hook-name))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3203 (if hook-forms
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3204 (ad-prognify (apply 'append hook-forms)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3205
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3206
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3207 ;; @@ Caching:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3208 ;; ===========
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3209 ;; Generating an advised definition of a function is moderately expensive,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3210 ;; hence, it makes sense to cache it so we can reuse it in appropriate
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3211 ;; circumstances. Of course, it only makes sense to reuse a cached
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3212 ;; definition if the current advice and function definition state is the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3213 ;; same as it was at the time when the cached definition was generated.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3214 ;; For that purpose we associate every cache with an id so we can verify
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3215 ;; if it is still valid at a certain point in time. This id mechanism
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3216 ;; makes it possible to preactivate advised functions, write the compiled
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3217 ;; advised definitions to a file and reuse them during the actual
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3218 ;; activation without having to risk that the resulting definition will be
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3219 ;; incorrect, well, almost.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3220 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3221 ;; A cache id is a list with six elements:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3222 ;; 1) the list of names of enabled before advices
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3223 ;; 2) the list of names of enabled around advices
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3224 ;; 3) the list of names of enabled after advices
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3225 ;; 4) the type of the original function (macro, subr, etc.)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3226 ;; 5) the arglist of the original definition (or t if it was equal to the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3227 ;; arglist of the cached definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3228 ;; 6) t if the interactive form of the original definition was equal to the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3229 ;; interactive form of the cached definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3230 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3231 ;; Here's how a cache can get invalidated or be incorrect:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3232 ;; A) a piece of advice used in the cache gets redefined
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3233 ;; B) the current list of enabled advices is different from the ones used
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3234 ;; for the cache
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3235 ;; C) the type of the original function changed, e.g., a function became a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3236 ;; macro, or a subr became a function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3237 ;; D) the arglist of the original function changed
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3238 ;; E) the interactive form of the original function changed
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3239 ;; F) a piece of advice used in the cache got redefined before the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3240 ;; defadvice with the cached definition got loaded: This is a PROBLEM!
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3241 ;;
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3242 ;; Cases A and B are the normal ones. A is taken care of by `ad-add-advice'
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3243 ;; which clears the cache in such a case, B is easily checked during
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3244 ;; verification at activation time.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3245 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3246 ;; Cases C, D and E have to be considered if one is slightly paranoid, i.e.,
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3247 ;; if one considers the case that the original function could be different
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3248 ;; from the one available at caching time (e.g., for forward advice of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3249 ;; functions that get redefined by some packages - such as `eval-region' gets
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3250 ;; redefined by edebug). All these cases can be easily checked during
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3251 ;; verification. Element 4 of the id lets one check case C, element 5 takes
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3252 ;; care of case D (using t in the equality case saves some space, because the
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3253 ;; arglist can be recovered at validation time from the cached definition),
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3254 ;; and element 6 takes care of case E which is only a problem if the original
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3255 ;; was actually a function whose interactive form was not overridden by a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3256 ;; piece of advice.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3257 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3258 ;; Case F is the only one which will lead to an incorrect advised function.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3259 ;; There is no way to avoid this without storing the complete advice definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3260 ;; in the cache-id which is not feasible.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3261 ;;
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3262 ;; The cache-id of a typical advised function with one piece of advice and
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3263 ;; no arglist redefinition takes 7 conses which is a small price to pay for
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3264 ;; the added efficiency. The validation itself is also pretty cheap, certainly
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3265 ;; a lot cheaper than reconstructing an advised definition.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3266
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3267 (defmacro ad-get-cache-definition (function)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3268 `(car (ad-get-advice-info-field ,function 'cache)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3269
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3270 (defmacro ad-get-cache-id (function)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3271 `(cdr (ad-get-advice-info-field ,function 'cache)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3272
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3273 (defmacro ad-set-cache (function definition id)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3274 `(ad-set-advice-info-field
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3275 ,function 'cache (cons ,definition ,id)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3276
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3277 (defun ad-clear-cache (function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3278 "Clears a previously cached advised definition of FUNCTION.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3279 Clear the cache if you want to force `ad-activate' to construct a new
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3280 advised definition from scratch."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3281 (interactive
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
3282 (list (ad-read-advised-function "Clear cached definition of")))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3283 (ad-set-advice-info-field function 'cache nil))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3284
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3285 (defun ad-make-cache-id (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3286 "Generate an identifying image of the current advices of FUNCTION."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3287 (let ((original-definition (ad-real-orig-definition function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3288 (cached-definition (ad-get-cache-definition function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3289 (list (mapcar (function (lambda (advice) (ad-advice-name advice)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3290 (ad-get-enabled-advices function 'before))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3291 (mapcar (function (lambda (advice) (ad-advice-name advice)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3292 (ad-get-enabled-advices function 'around))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3293 (mapcar (function (lambda (advice) (ad-advice-name advice)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3294 (ad-get-enabled-advices function 'after))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3295 (ad-definition-type original-definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3296 (if (equal (ad-arglist original-definition function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3297 (ad-arglist cached-definition))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3298 t
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3299 (ad-arglist original-definition function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3300 (if (eq (ad-definition-type original-definition) 'function)
82146
5868631b2e87 (ad-interactive-p, ad-interactive-form): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82140
diff changeset
3301 (equal (interactive-form original-definition)
5868631b2e87 (ad-interactive-p, ad-interactive-form): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82140
diff changeset
3302 (interactive-form cached-definition))))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3303
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3304 (defun ad-get-cache-class-id (function class)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3305 "Return the part of FUNCTION's cache id that identifies CLASS."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3306 (let ((cache-id (ad-get-cache-id function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3307 (if (eq class 'before)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3308 (car cache-id)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3309 (if (eq class 'around)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3310 (nth 1 cache-id)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3311 (nth 2 cache-id)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3312
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3313 (defun ad-verify-cache-class-id (cache-class-id advices)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3314 (ad-dolist (advice advices (null cache-class-id))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3315 (if (ad-advice-enabled advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3316 (if (eq (car cache-class-id) (ad-advice-name advice))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3317 (setq cache-class-id (cdr cache-class-id))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3318 (ad-do-return nil)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3319
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3320 ;; There should be a way to monitor if and why a cache verification failed
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3321 ;; in order to determine whether a certain preactivation could be used or
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3322 ;; not. Right now the only way to find out is to trace
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3323 ;; `ad-cache-id-verification-code'. The code it returns indicates where the
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3324 ;; verification failed. Tracing `ad-verify-cache-class-id' might provide
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3325 ;; some additional useful information.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3326
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3327 (defun ad-cache-id-verification-code (function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3328 (let ((cache-id (ad-get-cache-id function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3329 (code 'before-advice-mismatch))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3330 (and (ad-verify-cache-class-id
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3331 (car cache-id) (ad-get-advice-info-field function 'before))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3332 (setq code 'around-advice-mismatch)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3333 (ad-verify-cache-class-id
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3334 (nth 1 cache-id) (ad-get-advice-info-field function 'around))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3335 (setq code 'after-advice-mismatch)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3336 (ad-verify-cache-class-id
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3337 (nth 2 cache-id) (ad-get-advice-info-field function 'after))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3338 (setq code 'definition-type-mismatch)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3339 (let ((original-definition (ad-real-orig-definition function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3340 (cached-definition (ad-get-cache-definition function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3341 (and (eq (nth 3 cache-id) (ad-definition-type original-definition))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3342 (setq code 'arglist-mismatch)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3343 (equal (if (eq (nth 4 cache-id) t)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3344 (ad-arglist original-definition function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3345 (nth 4 cache-id) )
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3346 (ad-arglist cached-definition))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3347 (setq code 'interactive-form-mismatch)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3348 (or (null (nth 5 cache-id))
82146
5868631b2e87 (ad-interactive-p, ad-interactive-form): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82140
diff changeset
3349 (equal (interactive-form original-definition)
5868631b2e87 (ad-interactive-p, ad-interactive-form): Remove.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 82140
diff changeset
3350 (interactive-form cached-definition)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3351 (setq code 'verified))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3352 code))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3353
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3354 (defun ad-verify-cache-id (function)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3355 "True if FUNCTION's cache-id is compatible with its current advices."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3356 (eq (ad-cache-id-verification-code function) 'verified))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3357
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3358
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3359 ;; @@ Preactivation:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3360 ;; =================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3361 ;; Preactivation can be used to generate compiled advised definitions
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3362 ;; at compile time without having to give up the dynamic runtime flexibility
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3363 ;; of the advice mechanism. Preactivation is a special feature of `defadvice',
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3364 ;; it involves the following steps:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3365 ;; - remembering the function's current state (definition and advice-info)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3366 ;; - advising it with the defined piece of advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3367 ;; - clearing its cache
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3368 ;; - generating an interpreted advised definition by activating it, this will
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3369 ;; make use of all its current active advice and its current definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3370 ;; - saving the so generated cached definition and id
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3371 ;; - resetting the function's advice and definition state to what it was
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3372 ;; before the preactivation
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3373 ;; - Returning the saved definition and its id to be used in the expansion of
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3374 ;; `defadvice' to assign it as an initial cache, hence it will be compiled
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3375 ;; at time the `defadvice' gets compiled.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3376 ;; Naturally, for preactivation to be effective it has to be applied/compiled
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3377 ;; at the right time, i.e., when the current state of advices and function
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3378 ;; definition exactly reflects the state at activation time. Should that not
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3379 ;; be the case, the precompiled definition will just be discarded and a new
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3380 ;; advised definition will be generated.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3381
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3382 (defun ad-preactivate-advice (function advice class position)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3383 "Preactivate FUNCTION and returns the constructed cache."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3384 (let* ((function-defined-p (fboundp function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3385 (old-definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3386 (if function-defined-p
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3387 (symbol-function function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3388 (old-advice-info (ad-copy-advice-info function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3389 (ad-advised-functions ad-advised-functions))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3390 (unwind-protect
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3391 (progn
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3392 (ad-add-advice function advice class position)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3393 (ad-enable-advice function class (ad-advice-name advice))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3394 (ad-clear-cache function)
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3395 (ad-activate function -1)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3396 (if (and (ad-is-active function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3397 (ad-get-cache-definition function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3398 (list (ad-get-cache-definition function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3399 (ad-get-cache-id function))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3400 (ad-set-advice-info function old-advice-info)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3401 ;; Don't `fset' function to nil if it was previously unbound:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3402 (if function-defined-p
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3403 (ad-safe-fset function old-definition)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3404 (fmakunbound function)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3405
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3406
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3407 ;; @@ Freezing:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3408 ;; ============
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3409 ;; Freezing transforms a `defadvice' into a redefining `defun/defmacro'
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3410 ;; for the advised function without keeping any advice information. This
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3411 ;; feature was jwz's idea: It generates a dumpable function definition
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3412 ;; whose documentation can be written to the DOC file, and the generated
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3413 ;; code does not need any Advice runtime support. Of course, frozen advices
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3414 ;; cannot be undone.
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3415
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3416 ;; Freezing only considers the advice of the particular `defadvice', other
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3417 ;; already existing advices for the same function will be ignored. To ensure
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3418 ;; proper interaction when an already advised function gets redefined with
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3419 ;; a frozen advice, frozen advices always use the actual original definition
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3420 ;; of the function, i.e., they are always at the core of the onion. E.g., if
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3421 ;; an already advised function gets redefined with a frozen advice and then
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3422 ;; unadvised, the frozen advice remains as the new definition of the function.
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3423
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3424 ;; While multiple freeze advices for a single function or freeze-advising
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3425 ;; of an already advised function are possible, they are better avoided,
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3426 ;; because definition/compile/load ordering is relevant, and it becomes
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3427 ;; incomprehensible pretty quickly.
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3428
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3429 (defun ad-make-freeze-definition (function advice class position)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3430 (if (not (ad-has-proper-definition function))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3431 (error
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3432 "ad-make-freeze-definition: `%s' is not yet defined"
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3433 function))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3434 (let* ((name (ad-advice-name advice))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3435 ;; With a unique origname we can have multiple freeze advices
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3436 ;; for the same function, each overloading the previous one:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3437 (unique-origname
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3438 (intern (format "%s-%s-%s" (ad-make-origname function) class name)))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3439 (orig-definition
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3440 ;; If FUNCTION is already advised, we'll use its current origdef
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3441 ;; as the original definition of the frozen advice:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3442 (or (ad-get-orig-definition function)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3443 (symbol-function function)))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3444 (old-advice-info
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3445 (if (ad-is-advised function)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3446 (ad-copy-advice-info function)))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3447 (real-docstring-fn
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3448 (symbol-function 'ad-make-advised-definition-docstring))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3449 (real-origname-fn
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3450 (symbol-function 'ad-make-origname))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3451 (frozen-definition
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3452 (unwind-protect
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3453 (progn
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3454 ;; Make sure we construct a proper docstring:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3455 (ad-safe-fset 'ad-make-advised-definition-docstring
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3456 'ad-make-freeze-docstring)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3457 ;; Make sure `unique-origname' is used as the origname:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3458 (ad-safe-fset 'ad-make-origname (lambda (x) unique-origname))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3459 ;; No we reset all current advice information to nil and
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3460 ;; generate an advised definition that's solely determined
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3461 ;; by ADVICE and the current origdef of FUNCTION:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3462 (ad-set-advice-info function nil)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3463 (ad-add-advice function advice class position)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3464 ;; The following will provide proper real docstrings as
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3465 ;; well as a definition that will make the compiler happy:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3466 (ad-set-orig-definition function orig-definition)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3467 (ad-make-advised-definition function))
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3468 ;; Restore the old advice state:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3469 (ad-set-advice-info function old-advice-info)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3470 ;; Restore functions:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3471 (ad-safe-fset
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3472 'ad-make-advised-definition-docstring real-docstring-fn)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3473 (ad-safe-fset 'ad-make-origname real-origname-fn))))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3474 (if frozen-definition
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3475 (let* ((macro-p (ad-macro-p frozen-definition))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3476 (body (cdr (if macro-p
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3477 (ad-lambdafy frozen-definition)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3478 frozen-definition))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3479 `(progn
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3480 (if (not (fboundp ',unique-origname))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3481 (fset ',unique-origname
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3482 ;; avoid infinite recursion in case the function
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3483 ;; we want to freeze is already advised:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3484 (or (ad-get-orig-definition ',function)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3485 (symbol-function ',function))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3486 (,(if macro-p 'defmacro 'defun)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3487 ,function
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3488 ,@body))))))
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3489
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3490
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3491 ;; @@ Activation and definition handling:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3492 ;; ======================================
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3493
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3494 (defun ad-should-compile (function compile)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3495 "Return non-nil if the advised FUNCTION should be compiled.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3496 If COMPILE is non-nil and not a negative number then it returns t.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3497 If COMPILE is a negative number then it returns nil.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3498 If COMPILE is nil then the result depends on the value of
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3499 `ad-default-compilation-action' (which see)."
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3500 (if (integerp compile)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3501 (>= compile 0)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3502 (if compile
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3503 compile
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3504 (cond ((eq ad-default-compilation-action 'never)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3505 nil)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3506 ((eq ad-default-compilation-action 'always)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3507 t)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3508 ((eq ad-default-compilation-action 'like-original)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3509 (or (ad-subr-p (ad-get-orig-definition function))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3510 (ad-compiled-p (ad-get-orig-definition function))))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3511 ;; everything else means `maybe':
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3512 (t (featurep 'byte-compile))))))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3513
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3514 (defun ad-activate-advised-definition (function compile)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3515 "Redefine FUNCTION with its advised definition from cache or scratch.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3516 The resulting FUNCTION will be compiled if `ad-should-compile' returns t.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3517 The current definition and its cache-id will be put into the cache."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3518 (let ((verified-cached-definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3519 (if (ad-verify-cache-id function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3520 (ad-get-cache-definition function))))
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3521 (ad-safe-fset function
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3522 (or verified-cached-definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3523 (ad-make-advised-definition function)))
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3524 (if (ad-should-compile function compile)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3525 (ad-compile-function function))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3526 (if verified-cached-definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3527 (if (not (eq verified-cached-definition (symbol-function function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3528 ;; we must have compiled, cache the compiled definition:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3529 (ad-set-cache
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3530 function (symbol-function function) (ad-get-cache-id function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3531 ;; We created a new advised definition, cache it with a proper id:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3532 (ad-clear-cache function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3533 ;; ad-make-cache-id needs the new cached definition:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3534 (ad-set-cache function (symbol-function function) nil)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3535 (ad-set-cache
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3536 function (symbol-function function) (ad-make-cache-id function)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3537
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3538 (defun ad-handle-definition (function)
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3539 "Handle re/definition of an advised FUNCTION during de/activation.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3540 If FUNCTION does not have an original definition associated with it and
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3541 the current definition is usable, then it will be stored as FUNCTION's
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3542 original definition. If no current definition is available (even in the
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3543 case of undefinition) nothing will be done. In the case of redefinition
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3544 the action taken depends on the value of `ad-redefinition-action' (which
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3545 see). Redefinition occurs when FUNCTION already has an original definition
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3546 associated with it but got redefined with a new definition and then
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3547 de/activated. If you do not like the current redefinition action change
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3548 the value of `ad-redefinition-action' and de/activate again."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3549 (let ((original-definition (ad-get-orig-definition function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3550 (current-definition (if (ad-real-definition function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3551 (symbol-function function))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3552 (if original-definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3553 (if current-definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3554 (if (and (not (eq current-definition original-definition))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3555 ;; Redefinition with an advised definition from a
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3556 ;; different function won't count as such:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3557 (not (ad-advised-definition-p current-definition)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3558 ;; we have a redefinition:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3559 (if (not (memq ad-redefinition-action '(accept discard warn)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3560 (error "ad-handle-definition (see its doc): `%s' %s"
22061
eed26995bfad (ad-handle-definition, defadvice): Fix error messages.
Richard M. Stallman <rms@gnu.org>
parents: 21365
diff changeset
3561 function "invalidly redefined")
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3562 (if (eq ad-redefinition-action 'discard)
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3563 (ad-safe-fset function original-definition)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3564 (ad-set-orig-definition function current-definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3565 (if (eq ad-redefinition-action 'warn)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3566 (message "ad-handle-definition: `%s' got redefined"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3567 function))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3568 ;; either advised def or correct original is in place:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3569 nil)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3570 ;; we have an undefinition, ignore it:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3571 nil)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3572 (if current-definition
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3573 ;; we have a first definition, save it as original:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3574 (ad-set-orig-definition function current-definition)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3575 ;; we don't have anything noteworthy:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3576 nil))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3577
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3578
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3579 ;; @@ The top-level advice interface:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3580 ;; ==================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3581
70899
b920ab84fba8 (ad-enable-advice, ad-activate, ad-disable-advice): Add autoloads.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
3582 ;;;###autoload
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3583 (defun ad-activate (function &optional compile)
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3584 "Activate all the advice information of an advised FUNCTION.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3585 If FUNCTION has a proper original definition then an advised
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3586 definition will be generated from FUNCTION's advice info and the
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3587 definition of FUNCTION will be replaced with it. If a previously
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3588 cached advised definition was available, it will be used.
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3589 The optional COMPILE argument determines whether the resulting function
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3590 or a compilable cached definition will be compiled. If it is negative
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3591 no compilation will be performed, if it is positive or otherwise non-nil
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3592 the resulting function will be compiled, if it is nil the behavior depends
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3593 on the value of `ad-default-compilation-action' (which see).
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3594 Activation of an advised function that has an advice info but no actual
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3595 pieces of advice is equivalent to a call to `ad-unadvise'. Activation of
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3596 an advised function that has actual pieces of advice but none of them are
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3597 enabled is equivalent to a call to `ad-deactivate'. The current advised
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3598 definition will always be cached for later usage."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3599 (interactive
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
3600 (list (ad-read-advised-function "Activate advice of")
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3601 current-prefix-arg))
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3602 (if ad-activate-on-top-level
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3603 ;; avoid recursive calls to `ad-activate':
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3604 (ad-with-auto-activation-disabled
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3605 (if (not (ad-is-advised function))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3606 (error "ad-activate: `%s' is not advised" function)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3607 (ad-handle-definition function)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3608 ;; Just return for forward advised and not yet defined functions:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3609 (if (ad-get-orig-definition function)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3610 (if (not (ad-has-any-advice function))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3611 (ad-unadvise function)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3612 ;; Otherwise activate the advice:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3613 (cond ((ad-has-redefining-advice function)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3614 (ad-activate-advised-definition function compile)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3615 (ad-set-advice-info-field function 'active t)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3616 (eval (ad-make-hook-form function 'activation))
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3617 function)
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3618 ;; Here we are if we have all disabled advices:
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3619 (t (ad-deactivate function)))))))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3620
26247
f96b2bc4ef08 (ad-activate-on): Make it an alias for ad-activate.
Gerd Moellmann <gerd@gnu.org>
parents: 26217
diff changeset
3621 (defalias 'ad-activate-on 'ad-activate)
f96b2bc4ef08 (ad-activate-on): Make it an alias for ad-activate.
Gerd Moellmann <gerd@gnu.org>
parents: 26217
diff changeset
3622
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3623 (defun ad-deactivate (function)
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3624 "Deactivate the advice of an actively advised FUNCTION.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3625 If FUNCTION has a proper original definition, then the current
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3626 definition of FUNCTION will be replaced with it. All the advice
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3627 information will still be available so it can be activated again with
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3628 a call to `ad-activate'."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3629 (interactive
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
3630 (list (ad-read-advised-function "Deactivate advice of" 'ad-is-active)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3631 (if (not (ad-is-advised function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3632 (error "ad-deactivate: `%s' is not advised" function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3633 (cond ((ad-is-active function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3634 (ad-handle-definition function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3635 (if (not (ad-get-orig-definition function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3636 (error "ad-deactivate: `%s' has no original definition"
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3637 function)
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3638 (ad-safe-fset function (ad-get-orig-definition function))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3639 (ad-set-advice-info-field function 'active nil)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3640 (eval (ad-make-hook-form function 'deactivation))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3641 function)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3642
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3643 (defun ad-update (function &optional compile)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3644 "Update the advised definition of FUNCTION if its advice is active.
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3645 See `ad-activate' for documentation on the optional COMPILE argument."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3646 (interactive
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3647 (list (ad-read-advised-function
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
3648 "Update advised definition of" 'ad-is-active)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3649 (if (ad-is-active function)
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3650 (ad-activate function compile)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3651
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3652 (defun ad-unadvise (function)
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3653 "Deactivate FUNCTION and then remove all its advice information.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3654 If FUNCTION was not advised this will be a noop."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3655 (interactive
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
3656 (list (ad-read-advised-function "Unadvise function")))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3657 (cond ((ad-is-advised function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3658 (if (ad-is-active function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3659 (ad-deactivate function))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3660 (ad-clear-orig-definition function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3661 (ad-set-advice-info function nil)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3662 (ad-pop-advised-function function))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3663
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3664 (defun ad-recover (function)
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3665 "Try to recover FUNCTION's original definition, and unadvise it.
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3666 This is more low-level than `ad-unadvise' in that it does not do
26627
173f907a5812 Fix last change.
Dave Love <fx@gnu.org>
parents: 26622
diff changeset
3667 deactivation, which might run hooks and get into other trouble.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3668 Use in emergencies."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3669 ;; Use more primitive interactive behavior here: Accept any symbol that's
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3670 ;; currently defined in obarray, not necessarily with a function definition:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3671 (interactive
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3672 (list (intern
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3673 (completing-read "Recover advised function: " obarray nil t))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3674 (cond ((ad-is-advised function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3675 (cond ((ad-get-orig-definition function)
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3676 (ad-safe-fset function (ad-get-orig-definition function))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3677 (ad-clear-orig-definition function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3678 (ad-set-advice-info function nil)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3679 (ad-pop-advised-function function))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3680
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3681 (defun ad-activate-regexp (regexp &optional compile)
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3682 "Activate functions with an advice name containing a REGEXP match.
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3683 This activates the advice for each function
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3684 that has at least one piece of advice whose name includes a match for REGEXP.
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3685 See `ad-activate' for documentation on the optional COMPILE argument."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3686 (interactive
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
3687 (list (ad-read-regexp "Activate via advice regexp")
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3688 current-prefix-arg))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3689 (ad-do-advised-functions (function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3690 (if (ad-find-some-advice function 'any regexp)
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3691 (ad-activate function compile))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3692
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3693 (defun ad-deactivate-regexp (regexp)
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3694 "Deactivate functions with an advice name containing REGEXP match.
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3695 This deactivates the advice for each function
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3696 that has at least one piece of advice whose name includes a match for REGEXP."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3697 (interactive
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
3698 (list (ad-read-regexp "Deactivate via advice regexp")))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3699 (ad-do-advised-functions (function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3700 (if (ad-find-some-advice function 'any regexp)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3701 (ad-deactivate function))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3702
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3703 (defun ad-update-regexp (regexp &optional compile)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3704 "Update functions with an advice name containing a REGEXP match.
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3705 This reactivates the advice for each function
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3706 that has at least one piece of advice whose name includes a match for REGEXP.
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3707 See `ad-activate' for documentation on the optional COMPILE argument."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3708 (interactive
65680
ed770a0a7846 2005-09-24 Emilio C. Lopes <eclig@gmx.net>
Romain Francoise <romain@orebokech.com>
parents: 64751
diff changeset
3709 (list (ad-read-regexp "Update via advice regexp")
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3710 current-prefix-arg))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3711 (ad-do-advised-functions (function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3712 (if (ad-find-some-advice function 'any regexp)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3713 (ad-update function compile))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3714
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3715 (defun ad-activate-all (&optional compile)
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3716 "Activate all currently advised functions.
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3717 See `ad-activate' for documentation on the optional COMPILE argument."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3718 (interactive "P")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3719 (ad-do-advised-functions (function)
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3720 (ad-activate function compile)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3721
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3722 (defun ad-deactivate-all ()
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3723 "Deactivate all currently advised functions."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3724 (interactive)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3725 (ad-do-advised-functions (function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3726 (ad-deactivate function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3727
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3728 (defun ad-update-all (&optional compile)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3729 "Update all currently advised functions.
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3730 With prefix argument, COMPILE resulting advised definitions."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3731 (interactive "P")
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3732 (ad-do-advised-functions (function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3733 (ad-update function compile)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3734
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3735 (defun ad-unadvise-all ()
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3736 "Unadvise all currently advised functions."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3737 (interactive)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3738 (ad-do-advised-functions (function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3739 (ad-unadvise function)))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3740
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3741 (defun ad-recover-all ()
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3742 "Recover all currently advised functions. Use in emergencies.
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3743 To recover a function means to try to find its original (pre-advice)
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3744 definition, and delete all advice.
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3745 This is more low-level than `ad-unadvise' in that it does not do
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3746 deactivation, which might run hooks and get into other trouble."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3747 (interactive)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3748 (ad-do-advised-functions (function)
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3749 (condition-case nil
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3750 (ad-recover function)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3751 (error nil))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3752
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3753
60923
08f8c7042636 * emacs-lisp/advice.el: Replace `legal' with `valid'.
Werner LEMBERG <wl@gnu.org>
parents: 57879
diff changeset
3754 ;; Completion alist of valid `defadvice' flags
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3755 (defvar ad-defadvice-flags
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3756 '(("protect") ("disable") ("activate")
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3757 ("compile") ("preactivate") ("freeze")))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3758
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3759 ;;;###autoload
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3760 (defmacro defadvice (function args &rest body)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3761 "Define a piece of advice for FUNCTION (a symbol).
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3762 The syntax of `defadvice' is as follows:
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3763
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3764 \(defadvice FUNCTION (CLASS NAME [POSITION] [ARGLIST] FLAG...)
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3765 [DOCSTRING] [INTERACTIVE-FORM]
78150
3fcbdd7761c3 (defadvice): Doc fix.
Juanma Barranquero <lekktu@gmail.com>
parents: 75346
diff changeset
3766 BODY...)
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3767
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3768 FUNCTION ::= Name of the function to be advised.
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3769 CLASS ::= `before' | `around' | `after' | `activation' | `deactivation'.
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3770 NAME ::= Non-nil symbol that names this piece of advice.
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3771 POSITION ::= `first' | `last' | NUMBER. Optional, defaults to `first',
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3772 see also `ad-add-advice'.
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3773 ARGLIST ::= An optional argument list to be used for the advised function
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3774 instead of the argument list of the original. The first one found in
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3775 before/around/after-advices will be used.
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3776 FLAG ::= `protect'|`disable'|`activate'|`compile'|`preactivate'|`freeze'.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3777 All flags can be specified with unambiguous initial substrings.
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3778 DOCSTRING ::= Optional documentation for this piece of advice.
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3779 INTERACTIVE-FORM ::= Optional interactive form to be used for the advised
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3780 function. The first one found in before/around/after-advices will be used.
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3781 BODY ::= Any s-expression.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3782
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3783 Semantics of the various flags:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3784 `protect': The piece of advice will be protected against non-local exits in
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3785 any code that precedes it. If any around-advice of a function is protected
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3786 then automatically all around-advices will be protected (the complete onion).
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3787
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3788 `activate': All advice of FUNCTION will be activated immediately if
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3789 FUNCTION has been properly defined prior to this application of `defadvice'.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3790
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3791 `compile': In conjunction with `activate' specifies that the resulting
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3792 advised function should be compiled.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3793
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3794 `disable': The defined advice will be disabled, hence, it will not be used
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3795 during activation until somebody enables it.
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3796
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3797 `preactivate': Preactivates the advised FUNCTION at macro-expansion/compile
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3798 time. This generates a compiled advised definition according to the current
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3799 advice state that will be used during activation if appropriate. Only use
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3800 this if the `defadvice' gets actually compiled.
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3801
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3802 `freeze': Expands the `defadvice' into a redefining `defun/defmacro' according
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3803 to this particular single advice. No other advice information will be saved.
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3804 Frozen advices cannot be undone, they behave like a hard redefinition of
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3805 the advised function. `freeze' implies `activate' and `preactivate'. The
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3806 documentation of the advised function can be dumped onto the `DOC' file
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3807 during preloading.
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3808
80328
349f51baa515 (defadvice): Add usage pattern.
Richard M. Stallman <rms@gnu.org>
parents: 79704
diff changeset
3809 See Info node `(elisp)Advising Functions' for comprehensive documentation.
349f51baa515 (defadvice): Add usage pattern.
Richard M. Stallman <rms@gnu.org>
parents: 79704
diff changeset
3810 usage: (defadvice FUNCTION (CLASS NAME [POSITION] [ARGLIST] FLAG...)
349f51baa515 (defadvice): Add usage pattern.
Richard M. Stallman <rms@gnu.org>
parents: 79704
diff changeset
3811 [DOCSTRING] [INTERACTIVE-FORM]
349f51baa515 (defadvice): Add usage pattern.
Richard M. Stallman <rms@gnu.org>
parents: 79704
diff changeset
3812 BODY...)"
66398
df04170ba46b (ad-make-advised-definition): Fix arg-order.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 65680
diff changeset
3813 (declare (doc-string 3))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3814 (if (not (ad-name-p function))
22061
eed26995bfad (ad-handle-definition, defadvice): Fix error messages.
Richard M. Stallman <rms@gnu.org>
parents: 21365
diff changeset
3815 (error "defadvice: Invalid function name: %s" function))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3816 (let* ((class (car args))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3817 (name (if (not (ad-class-p class))
22061
eed26995bfad (ad-handle-definition, defadvice): Fix error messages.
Richard M. Stallman <rms@gnu.org>
parents: 21365
diff changeset
3818 (error "defadvice: Invalid advice class: %s" class)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3819 (nth 1 args)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3820 (position (if (not (ad-name-p name))
22061
eed26995bfad (ad-handle-definition, defadvice): Fix error messages.
Richard M. Stallman <rms@gnu.org>
parents: 21365
diff changeset
3821 (error "defadvice: Invalid advice name: %s" name)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3822 (setq args (nthcdr 2 args))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3823 (if (ad-position-p (car args))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3824 (prog1 (car args)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3825 (setq args (cdr args))))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3826 (arglist (if (listp (car args))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3827 (prog1 (car args)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3828 (setq args (cdr args)))))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3829 (flags
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3830 (mapcar
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3831 (function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3832 (lambda (flag)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3833 (let ((completion
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3834 (try-completion (symbol-name flag) ad-defadvice-flags)))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3835 (cond ((eq completion t) flag)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3836 ((assoc completion ad-defadvice-flags)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3837 (intern completion))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3838 (t (error "defadvice: Invalid or ambiguous flag: %s"
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3839 flag))))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3840 args))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3841 (advice (ad-make-advice
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3842 name (memq 'protect flags)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3843 (not (memq 'disable flags))
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3844 `(advice lambda ,arglist ,@body)))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3845 (preactivation (if (memq 'preactivate flags)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3846 (ad-preactivate-advice
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3847 function advice class position))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3848 ;; Now for the things to be done at evaluation time:
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3849 (if (memq 'freeze flags)
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3850 ;; jwz's idea: Freeze the advised definition into a dumpable
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3851 ;; defun/defmacro whose docs can be written to the DOC file:
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3852 (ad-make-freeze-definition function advice class position)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3853 ;; the normal case:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3854 `(progn
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3855 (ad-add-advice ',function ',advice ',class ',position)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3856 ,@(if preactivation
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3857 `((ad-set-cache
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3858 ',function
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3859 ;; the function will get compiled:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3860 ,(cond ((ad-macro-p (car preactivation))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3861 `(ad-macrofy
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3862 (function
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3863 ,(ad-lambdafy
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3864 (car preactivation)))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3865 (t `(function
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3866 ,(car preactivation))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3867 ',(car (cdr preactivation)))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3868 ,@(if (memq 'activate flags)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3869 `((ad-activate ',function
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3870 ,(if (memq 'compile flags) t))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3871 ',function))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3872
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3873
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3874 ;; @@ Tools:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3875 ;; =========
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3876
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3877 (defmacro ad-with-originals (functions &rest body)
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3878 "Binds FUNCTIONS to their original definitions and execute BODY.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3879 For any members of FUNCTIONS that are not currently advised the rebinding will
6038
2f1deaa86ee2 Removed all support for Emacs-18:
Richard M. Stallman <rms@gnu.org>
parents: 5746
diff changeset
3880 be a noop. Any modifications done to the definitions of FUNCTIONS will be
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3881 undone on exit of this macro."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3882 (let* ((index -1)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3883 ;; Make let-variables to store current definitions:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3884 (current-bindings
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3885 (mapcar (function
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3886 (lambda (function)
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3887 (setq index (1+ index))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3888 (list (intern (format "ad-oRiGdEf-%d" index))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3889 `(symbol-function ',function))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3890 functions)))
41608
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3891 `(let ,current-bindings
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3892 (unwind-protect
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3893 (progn
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3894 ,@(progn
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3895 ;; Make forms to redefine functions to their
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3896 ;; original definitions if they are advised:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3897 (setq index -1)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3898 (mapcar
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3899 (function
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3900 (lambda (function)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3901 (setq index (1+ index))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3902 `(ad-safe-fset
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3903 ',function
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3904 (or (ad-get-orig-definition ',function)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3905 ,(car (nth index current-bindings))))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3906 functions))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3907 ,@body)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3908 ,@(progn
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3909 ;; Make forms to back-define functions to the definitions
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3910 ;; they had outside this macro call:
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3911 (setq index -1)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3912 (mapcar
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3913 (function
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3914 (lambda (function)
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3915 (setq index (1+ index))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3916 `(ad-safe-fset
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3917 ',function
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3918 ,(car (nth index current-bindings)))))
45db352a0971 Converted backquote to the new style.
Sam Steingold <sds@gnu.org>
parents: 38336
diff changeset
3919 functions))))))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3920
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3921 (if (not (get 'ad-with-originals 'lisp-indent-hook))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3922 (put 'ad-with-originals 'lisp-indent-hook 1))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3923
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3924
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3925 ;; @@ Advising `documentation':
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3926 ;; ============================
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3927 ;; Use the advice mechanism to advise `documentation' to make it
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3928 ;; generate proper documentation strings for advised definitions:
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3929
45019
c726a3eeeb0f (documentation): Add ad-define-subr-args call.
Richard M. Stallman <rms@gnu.org>
parents: 41936
diff changeset
3930 ;; This makes sure we get the right arglist for `documentation'
c726a3eeeb0f (documentation): Add ad-define-subr-args call.
Richard M. Stallman <rms@gnu.org>
parents: 41936
diff changeset
3931 ;; during bootstrapping.
c726a3eeeb0f (documentation): Add ad-define-subr-args call.
Richard M. Stallman <rms@gnu.org>
parents: 41936
diff changeset
3932 (ad-define-subr-args 'documentation '(function &optional raw))
c726a3eeeb0f (documentation): Add ad-define-subr-args call.
Richard M. Stallman <rms@gnu.org>
parents: 41936
diff changeset
3933
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3934 ;; @@ Starting, stopping and recovering from the advice package magic:
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3935 ;; ===================================================================
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3936
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3937 (defun ad-start-advice ()
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3938 "Start the automatic advice handling magic."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3939 (interactive)
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3940 ;; Advising `ad-activate-internal' means death!!
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3941 (ad-set-advice-info 'ad-activate-internal nil)
85302
bc8b741390b0 (documentation): Advice deleted. Doc for advised functions
Richard M. Stallman <rms@gnu.org>
parents: 83896
diff changeset
3942 (ad-safe-fset 'ad-activate-internal 'ad-activate))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3943
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3944 (defun ad-stop-advice ()
26622
019c7ea59fd9 Many doc fixes.
Richard M. Stallman <rms@gnu.org>
parents: 26247
diff changeset
3945 "Stop the automatic advice handling magic.
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3946 You should only need this in case of Advice-related emergencies."
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3947 (interactive)
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3948 ;; Advising `ad-activate-internal' means death!!
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3949 (ad-set-advice-info 'ad-activate-internal nil)
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3950 (ad-safe-fset 'ad-activate-internal 'ad-activate-internal-off))
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3951
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3952 (defun ad-recover-normality ()
26217
5d24b6d99a9f Doc fixes.
Dave Love <fx@gnu.org>
parents: 26206
diff changeset
3953 "Undo all advice related redefinitions and unadvises everything.
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3954 Use only in REAL emergencies."
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3955 (interactive)
26206
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3956 ;; Advising `ad-activate-internal' means death!!
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3957 (ad-set-advice-info 'ad-activate-internal nil)
3d9818475597 (ad-activate-internal): Renamed from
Gerd Moellmann <gerd@gnu.org>
parents: 25260
diff changeset
3958 (ad-safe-fset 'ad-activate-internal 'ad-activate-internal-off)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3959 (ad-recover-all)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3960 (setq ad-advised-functions nil))
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3961
8445
81f7b5d9b990 New handling of automatic advice activation that
Richard M. Stallman <rms@gnu.org>
parents: 6082
diff changeset
3962 (ad-start-advice)
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3963
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3964 (provide 'advice)
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3965
66398
df04170ba46b (ad-make-advised-definition): Fix arg-order.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 65680
diff changeset
3966 ;; arch-tag: 29f8c9a1-8c88-471f-95d7-e28541c6b7c0
4110
ccdff27edd2e Initial revision
Roland McGrath <roland@gnu.org>
parents:
diff changeset
3967 ;;; advice.el ends here