Lines Matching defs:advice
0 ;;; advice.el --- an overloading mechanism for Emacs Lisp functions
29 ;; advice|Hans Chalupsky|hans@cs.buffalo.edu|
31 ;; 1994/08/05 03:42:04|2.14|~/packages/advice.el.Z|
44 ;; This package implements a full-fledged Lisp-style advice mechanism
50 ;; with a piece of advice. Think of a piece of advice as a kind of fancy
61 ;; - Every piece of advice can have its documentation string which will be
64 ;; - The execution of every piece of advice can be protected against error
72 ;; - Separation of advice definition and activation
73 ;; - Forward advice is possible, that is
76 ;; - Forward redefinition is possible because around advice can be used to
82 ;; the advice mechanism.
84 ;; functions depending on what pieces of advice are currently en/disabled
86 ;; regular expressions that match advice names
108 ;; @ Foo games: An advice tutorial ...teaches about Advice by example
120 ;; when they are invoked via their function cell. This means that advice will
126 ;; their advice was activated.
133 ;; others come from the various Lisp advice mechanisms I've come across
138 ;; If you find any bugs, have suggestions for new advice features, find the
148 ;; should know: Once Advice has been started with `ad-start-advice'
151 ;; it will enable automatic advice activation when functions get defined.
152 ;; All of this can be undone at any time with `M-x ad-stop-advice'.
160 ;; - M-x ad-stop-advice (if you think the problem is related to the
168 ;; `ad-activate-all', or `ad-start-advice'. `ad-recover-normality' unadvises
197 ;; Before I go on explaining how advice works, here are four simple examples
229 ;; Below is general documentation of the various features of advice. For more
242 ;; - advices: Short for "pieces of advice".
244 ;; @@ Defining a piece of advice with `defadvice':
246 ;; The main means of defining a piece of advice is the macro `defadvice',
247 ;; there is no interactive way of specifying a piece of advice. A call to
257 ;; <class> is the class of the advice which has to be one of `before',
261 ;; <name> is the name of the advice which has to be a non-nil symbol.
262 ;; Names uniquely identify a piece of advice in a certain advice class,
263 ;; hence, advices can be redefined by defining an advice with the same class
268 ;; the specified <class> this new advice will be placed. <position> has to
272 ;; an already existing advice (see above) then the position argument will
273 ;; be ignored and the position of the already existing advice will be used.
279 ;; argument list in mind will break. If more than one advice specify an
284 ;; advice. All flags can be specified with unambiguous initial substrings.
285 ;; `activate': Specifies that the advice information of the advised
286 ;; function should be activated right after this advice has been
288 ;; `protect': Specifies that this advice should be protected against
292 ;; `disable': Specifies that the defined advice should be disabled, hence,
297 ;; current advice state which will be used during activation
302 ;; An optional <documentation-string> can be supplied to document the advice.
307 ;; interactive behavior of the original function. If more than one advice
312 ;; A possibly empty list of <body-forms> specifies the body of the advice in
313 ;; an implicit progn. The body of an advice can access/change arguments,
319 ;; Suppose a function/macro/subr/special-form has N pieces of before advice,
320 ;; M pieces of around advice and K pieces of after advice. Assuming none of
322 ;; (body-form indices correspond to the position of the respective advice in
323 ;; that advice class):
352 ;; an advice by simply referring to them by their original name, however,
362 ;; original function or from a before/around/after advice. For advised
364 ;; advice we have to use (interactive) and then call the subr interactively
370 ;; before/around/after advice to gain control over argument values that
373 ;; Then the body forms of the various advices in the various classes of advice
374 ;; are assembled in order. The forms of around advice L are normally part of
375 ;; one of the forms of around advice L-1. An around advice can specify where
380 ;; The innermost part of the around advice onion is
384 ;; all pieces of advice which can access and modify it before it gets returned.
387 ;; of advice is the same. The only difference is that `unwind-protect' forms
388 ;; make sure that the protected advice gets executed even if some previous
389 ;; piece of advice had an error or a non-local exit. If any around advice is
390 ;; protected then the whole around advice onion will be protected.
395 ;; advised function in the body of an advice is to refer to them by name. To
396 ;; do that, the advice programmer needs to know either the names of the
398 ;; argument list redefinition given in a piece of advice. While this simple
401 ;; advice. If the definition of the original function changes the advice
404 ;; gets redefined in a non-advice style into a function by the edebug
405 ;; package. If the advice assumes `eval-region' to be a subr it might break
407 ;; same piece of advice across different versions of Emacs. Some subrs in a
409 ;; semantics remain the same, hence, the same piece of advice might be usable
412 ;; As a solution to that advice provides argument list access macros that get
430 ;; this semantics that has to be known by the advice programmer. Then s/he
431 ;; can access these arguments in a piece of advice with some of the
472 ;; arbitrary advised function. To do that within an advice one can use the
476 ;; specifications can then be examined in the body of the advice. For
477 ;; example, somewhere in an advice we could do this:
499 ;; `(sym newdef)' as the argument list of `fset', while advice might use
503 ;; called. Advice automatically takes care of that mapping, hence, the advice
510 ;; When advice constructs the advised definition of a function it has to
516 ;; advice cannot at all determine the argument list of a subr it uses
519 ;; the advice programmer to explicitly tell advice about the argument list
524 ;; is used by advice itself to tell a v18 Emacs about the arguments of `fset'.
540 ;; The definition of an advised function does not change until all its advice
543 ;; invocation of `ad-activate', or if forward advice is enabled (i.e., the
548 ;; all defined and enabled pieces of advice will get combined with the
566 ;; whether the current advice state is consistent with the cached
570 ;; all currently advised function that have a piece of advice with a name that
572 ;; de/activate sets of functions depending on certain advice naming
579 ;; @@@ Reasons for the separation of advice definition and activation:
583 ;; 1) definition of various pieces of advice
584 ;; 2) activation of all advice currently defined and enabled
586 ;; The advantage of this is that various pieces of advice can be defined
589 ;; important advantage is that it allows the implementation of forward advice.
591 ;; `advice-info' property of the function symbol. This accumulation is
594 ;; check whether the function/macro they defined had advice information
595 ;; associated with it. If so and forward advice is enabled, the original
596 ;; definition will be saved, and then the advice will be activated. When a
603 ;; @@ Enabling/disabling pieces or sets of advice:
605 ;; A major motivation for the development of this advice package was to bring
616 ;; at least in my opinion - these overloads would all be done with advice,
618 ;; mechanism of advice could be used to achieve just that.
620 ;; Every piece of advice is associated with an enablement flag. When the
622 ;; activation) only the currently enabled pieces of advice will be considered.
624 ;; dependent on what pieces of advice are currently enabled.
627 ;; piece of advice for some function yet keep it dormant until a certain
629 ;; of that piece of advice. Once the condition is met the advice can be
632 ;; etc. used by advice itself will stay disabled until `ad-start-advice' is
635 ;; by advice will get used only if they are intended to be used.
638 ;; `ad-enable-advice' and `ad-disable-advice'. For example, the following
639 ;; would disable a particular advice of the function `foo':
641 ;; (ad-disable-advice 'foo 'before 'my-advice)
650 ;; used advice to overload all its functions, and that it used the
651 ;; "ange-ftp-" prefix for all its advice names, then we could temporarily
668 ;; A certain piece of advice is considered a match if its name contains a
672 ;; @@ Forward advice, automatic advice activation:
676 ;; Otherwise, proper advice definition and activation would make it necessary
678 ;; advised, which would partly defeat the purpose of the advice mechanism.
680 ;; In the following, "forward advice" always implies its automatic activation
681 ;; once a function gets defined, and not just the accumulation of advice
684 ;; Advice implements forward advice mainly via the following: 1) Separation
685 ;; of advice definition and activation that makes it possible to accumulate
686 ;; advice information without having the original function already defined,
688 ;; for advice information whenever they define a function. If advice
689 ;; information was found then the advice will immediately get activated when
692 ;; Automatic advice activation means, that whenever a function gets defined
694 ;; file, and the function has some advice-info stored with it then that
695 ;; advice will get activated right away.
697 ;; @@@ Enabling automatic advice activation:
699 ;; Automatic advice activation is enabled by default. It can be disabled by
700 ;; doint `M-x ad-stop-advice' and enabled again with `M-x ad-start-advice'.
705 ;; advised function's advice-info so it can be reused, for example, after an
706 ;; intermediate deactivation. Because the advice-info of a function might
730 ;; function plus the advice specified in this `defadvice' (even if it is
731 ;; specified as disabled) and all other currently enabled pieces of advice to
739 ;; advice-info. When it gets activated (can be immediately on execution of the
741 ;; current state of advice and if it is verified the precompiled definition
745 ;; not at all impair the flexibility of the advice mechanism.
747 ;; MORAL: In order get all the efficiency out of preactivation the advice
750 ;; the same as it will be when the advice of that function gets
755 ;; Preactivation and forward advice do not contradict each other. It is
759 ;; its advice gets activated. The only constraint is that at the time the
770 ;; Right now advice does not provide an elegant way to find out whether
782 ;; NOT match the current state of advice gets used nevertheless. That case
783 ;; arises if one package defines a certain piece of advice which gets used
785 ;; very advice (i.e., same function/class/name), and it is the second advice
787 ;; that was the only definition of that advice so far (`ad-add-advice'
788 ;; catches advice redefinitions and clears the cache in such a case).
791 ;; MORAL-II: Redefining somebody else's advice is BAAAAD (to speak with
792 ;; George Walker Bush), and why would you redefine your own advice anyway?
793 ;; Advice is a mechanism to facilitate function redefinition, not advice
795 ;; to undo somebody else's advice try to write a "neutralizing" advice.
804 ;; runtime support and such advice cannot be de/activated or changed as
819 ;; @@ Adding a piece of advice with `ad-add-advice':
821 ;; The non-interactive function `ad-add-advice' can be used to add a piece of
822 ;; advice to some function without using `defadvice'. This is useful if advice
823 ;; has to be added somewhere by a function (also look at `ad-make-advice').
827 ;; There are two special classes of advice called `activation' and
830 ;; form which will be evaluated whenever the advice-info of the advised
836 ;; `file-x-last-fn'. Then we can define the following advice:
842 ;; This will constitute a forward advice for function `file-x-last-fn' which
843 ;; will get activated when `file-x' is loaded (only if forward advice is
844 ;; enabled of course). Because there are no "real" pieces of advice
846 ;; advice will be run during its activation which is equivalent to having a
849 ;; @@ Summary of main advice concepts:
852 ;; A piece of advice gets defined with `defadvice' and added to the
853 ;; `advice-info' property of a function.
855 ;; Every piece of advice has an enablement flag associated with it. Only
865 ;; Reactivate an advised function but only if its advice is currently
867 ;; to date with the current state of advice without also activating
874 ;; state of advice during byte-compilation of a file with a preactivating
879 ;; @@ Summary of interactive advice manipulation functions:
883 ;; advice classes and advice names):
885 ;; - ad-activate to activate the advice of a FUNCTION
886 ;; - ad-deactivate to deactivate the advice of a FUNCTION
887 ;; - ad-update to activate the advice of a FUNCTION unless it was not
889 ;; - ad-unadvise deactivates a FUNCTION and removes all of its advice
892 ;; discards all advice information (a low-level `ad-unadvise').
895 ;; - ad-remove-advice removes a particular piece of advice of a FUNCTION.
897 ;; activate the new state of advice.
898 ;; - ad-enable-advice enables a particular piece of advice of a FUNCTION.
899 ;; - ad-disable-advice disables a particular piece of advice of a FUNCTION.
901 ;; every advice whose name contains a match for a regular
905 ;; - ad-activate-regexp activates all advised function with a matching advice
906 ;; - ad-deactivate-regexp deactivates all advised function with matching advice
907 ;; - ad-update-regexp updates all advised function with a matching advice
916 ;; @@ Summary of forms with special meanings when used within an advice:
933 ;; or wrapped definition should go in an around advice
936 ;; @ Foo games: An advice tutorial
940 ;; First we have to start the advice magic:
942 ;; (ad-start-advice)
956 ;; @@ Defining a simple piece of advice:
958 ;; Now let's define the first piece of advice for `foo'. To do that we
959 ;; use the macro `defadvice' which takes a function name, a list of advice
961 ;; the advice specifiers is the class of the advice, the second is its name,
963 ;; first advice is `before', its name is `fg-add2', its position among the
964 ;; currently defined before advices (none so far) is `first', and the advice
967 ;; advice names in this tutorial will be prefixed with `fg' for `Foo Games'
971 ;; In the body of an advice we can refer to the argument variables of the
973 ;; `foo' will be to actually add 2. All of the advice definitions below only
975 ;; extent. Every piece of advice can have a documentation string which will
986 ;; @@ Specifying the position of an advice:
988 ;; Now we define the second before advice which will cancel the effect of
989 ;; the previous advice. This time we specify the position as 0 which is
991 ;; position of an advice among the list of advices in the same class. This
992 ;; time we already have one before advice hence the position specification
994 ;; of the previous advice will be 1 even though we specified it with `first'
996 ;; the currently defined pieces of advice which by now has changed.
1006 ;; @@ Redefining a piece of advice:
1008 ;; Now we define an advice with the same class and same name but with a
1009 ;; different position. Defining an advice in a class in which an advice with
1011 ;; particular advice, in which case the position argument will be ignored
1012 ;; and the previous position of the redefined piece of advice is used.
1023 ;; The documentation strings of the various pieces of advice are assembled
1024 ;; in order which shows that advice `fg-cancel-add2' is still the first
1025 ;; `before' advice even though we specified position `last' above:
1030 ;; This function is advised with the following advice(s):
1042 ;; advices (there could also be body forms in this advice). The particular
1054 ;; If more than one advice have an interactive declaration, then the one of
1055 ;; the advice with the smallest position will be used (before advices go
1081 ;; Now we'll try some `around' advices. An around advice is a wrapper around
1100 ;; Around advices are assembled like onion skins where the around advice
1101 ;; with position 0 is the outermost skin and the advice at the last position
1130 ;; @@ Controlling advice activation:
1133 ;; the advice immediately after its definition, and that's what we want in
1134 ;; most cases. However, if we define multiple pieces of advice for a single
1135 ;; function then activating every advice immediately is inefficient. A
1136 ;; better way to do this is to only activate the last defined advice.
1148 ;; Now we define another advice and activate which will also activate the
1149 ;; previous advice `fg-times-x'. Note the use of the special variable
1150 ;; `ad-return-value' in the body of the advice which is set to the result of
1164 ;; @@ Protecting advice execution:
1166 ;; Once in a while we define an advice to perform some cleanup action,
1181 ;; To make sure a certain piece of advice gets executed even if some error or
1184 ;; whole around advice onion will be protected):
1240 ;; @@ Enabling and disabling pieces of advice:
1242 ;; Once in a while it is desirable to temporarily disable a piece of advice
1245 ;; neutralize the effect of the advice of one of the packages.
1247 ;; The following disables the after advice `fg-times-x' in the function `foo'.
1248 ;; All that does is to change a flag for this particular advice. All the
1250 ;; position in this advice class, etc.).
1252 ;; (ad-disable-advice 'foo 'after 'fg-times-x)
1266 ;; advice name that contains a match for the regular expression will be
1267 ;; called a match. A special advice class `any' can be used to consider
1268 ;; all advice classes:
1270 ;; (ad-disable-advice 'foo 'any "^fg-.*times")
1280 ;; To enable the disabled advice we could use either `ad-enable-advice'
1281 ;; similar to `ad-disable-advice', or as an alternative `ad-enable-regexp'
1285 ;; advice name conventions. We prefixed all advice names with `fg-', hence
1293 ;; contain some advice matched by the regular expression. This is a save
1294 ;; way to update the activation of advised functions whose advice changed
1305 ;; Another use for the dis/enablement mechanism is to define a piece of advice
1307 ;; then the advice will not be used during activation. The `disable' flag lets
1322 ;; (ad-enable-advice 'foo 'before 'fg-1-more)
1335 ;; without having to reconstruct them if nothing in the advice-info of a
1337 ;; deactivate functions that have a piece of advice defined by a certain
1359 ;; @@ Forward advice:
1361 ;; To enable automatic activation of forward advice we first have to set
1362 ;; `ad-activate-on-definition' to t and restart advice:
1367 ;; (ad-start-advice)
1370 ;; Let's define a piece of advice for an undefined function:
1381 ;; Now we define it and the forward advice will get activated (only because
1382 ;; `ad-activate-on-definition' was t when we started advice above with
1383 ;; `ad-start-advice'):
1393 ;; Redefinition will activate any available advice if the value of
1420 ;; This advice did not affect `fie'...
1426 ;; activated as long as its current advice state is the same as it was during
1475 ;; (ad-get-advice-info 'fum)
1494 ;; function definition and advice information. If it does not match it
1496 ;; from scratch. For example, let's first remove all advice-info for `fum':
1501 ;; And now define a new piece of advice:
1509 ;; current advice state is different from the one at preactivation time. This
1525 ;; definition and advice state at preactivation time must be the same as the
1526 ;; state at activation time. Preactivation does work with forward advice, all
1533 ;; argument in a piece of advice. For many advice applications this is
1538 ;; then a piece of advice written for `eval-region' that was written with
1548 ;; the arguments had been used directly in the definition of the advice.
1560 ;; For example, the following advice adds 1 to each of the 3 arguments:
1572 ;; Now suppose somebody redefines `fuu' with a rest argument. Our advice
1574 ;; advice activation is still in effect, hence, the redefinition of `fuu'
1575 ;; will automatically activate all its advice):
1644 ;; argument of the advice will be interpreted as an argument list
1668 ;; advice programmer to tell advice what the argument list of a certain subr
1676 ;; To tell advice what the argument list of `car' really is we
1683 ;; actually used by advice itself for the advised definition of `fset'):
1689 ;; subr name symbol. When advice looks for a subr argument list it first
1698 ;; slightly different advice code for subrs than for functions. This case
1699 ;; arises when one wants to access subr arguments in a before/around advice
1705 ;; interactive subr will be nil. For example, the following advice for
1728 ;; environments by pieces of advice has an affect during macro expansion
1730 ;; of pieces of advice will occur during macro expansion. To also affect
1732 ;; `ad-return-value' in a piece of after advice. For example:
1760 ;; following (first remove the old advice):
1762 ;; (ad-remove-advice 'foom 'before 'fg-print-x)
1783 ;; flexibility and effectiveness of the advice mechanism. Macros that were
1784 ;; compile-time expanded before the advice was activated will of course never
1800 ;; what you are doing (some of the forward advice behavior is
1801 ;; implemented via advice of the special forms `defun' and `defmacro').
1818 ;; `defadvice' expansion needs quite a few advice functions and variables,
1821 (provide 'advice-preload)
1823 (require 'advice-preload "advice.el")
1829 (defgroup advice nil
1850 :group 'advice)
1863 :group 'advice)
1972 ;; advice-info property of the function symbol. It is stored as an
2016 (defmacro ad-get-advice-info (function)
2017 `(get ,function 'ad-advice-info))
2019 (defmacro ad-set-advice-info (function advice-info)
2020 `(put ,function 'ad-advice-info ,advice-info))
2022 (defmacro ad-copy-advice-info (function)
2023 `(ad-copy-tree (get ,function 'ad-advice-info)))
2026 "Return non-nil if FUNCTION has any advice info associated with it.
2027 This does not mean that the advice is also active."
2028 (list 'ad-get-advice-info function))
2030 (defun ad-initialize-advice-info (function)
2031 "Initialize the advice info for FUNCTION.
2034 (ad-set-advice-info function (list (cons 'active nil))))
2036 (defmacro ad-get-advice-info-field (function field)
2037 "Retrieve the value of the advice info FIELD of FUNCTION."
2038 `(cdr (assq ,field (ad-get-advice-info ,function))))
2040 (defun ad-set-advice-info-field (function field value)
2041 "Destructively modify VALUE of the advice info FIELD of FUNCTION."
2043 (cond ((assq field (ad-get-advice-info function))
2045 (rplacd (assq field (ad-get-advice-info function)) value))
2047 (nconc (ad-get-advice-info function)
2053 (ad-get-advice-info-field function 'active))
2056 ;; @@ Access fns for single pieces of advice and related predicates:
2059 (defun ad-make-advice (name protect enable definition)
2060 "Constructs single piece of advice to be stored in some advice-info.
2063 `(advice lambda ARGLIST [DOCSTRING] [INTERACTIVE-FORM] BODY...)'."
2066 ;; ad-find-advice uses the alist structure directly ->
2068 (defmacro ad-advice-name (advice)
2069 (list 'car advice))
2070 (defmacro ad-advice-protected (advice)
2071 (list 'nth 1 advice))
2072 (defmacro ad-advice-enabled (advice)
2073 (list 'nth 2 advice))
2074 (defmacro ad-advice-definition (advice)
2075 (list 'nth 3 advice))
2077 (defun ad-advice-set-enabled (advice flag)
2078 (rplaca (cdr (cdr advice)) flag))
2081 (memq thing ad-advice-classes))
2092 ;; List of defined advice classes:
2093 (defvar ad-advice-classes '(before around after activation deactivation))
2095 (defun ad-has-enabled-advice (function class)
2097 (ad-dolist (advice (ad-get-advice-info-field function class))
2098 (if (ad-advice-enabled advice) (ad-do-return t))))
2100 (defun ad-has-redefining-advice (function)
2101 "True if FUNCTION's advice info defines at least 1 redefining advice.
2104 (or (ad-has-enabled-advice function 'before)
2105 (ad-has-enabled-advice function 'around)
2106 (ad-has-enabled-advice function 'after))))
2108 (defun ad-has-any-advice (function)
2109 "True if the advice info of FUNCTION defines at least one advice."
2111 (ad-dolist (class ad-advice-classes nil)
2112 (if (ad-get-advice-info-field function class)
2118 (ad-dolist (advice (ad-get-advice-info-field function class))
2119 (if (ad-advice-enabled advice)
2120 (push advice enabled-advices)))
2124 ;; @@ Dealing with automatic advice activation via `fset/defalias':
2128 ;; take care of automatic advice activation, hence, we don't have to
2135 ;; if (get SYM 'ad-advice-info)
2145 ;; turn off automatic advice activation (e.g., when `ad-stop-advice' or
2152 "Automatic advice activation is disabled. `ad-start-advice' enables it."
2157 "Automatic advice activation is disabled. `ad-start-advice' enables it."
2175 ;; The advice-info of an advised function contains its `origname' which is
2187 `(let ((origname (ad-get-advice-info-field ,function 'origname)))
2193 (ad-get-advice-info-field function 'origname) ,definition))
2196 `(fmakunbound (ad-get-advice-info-field ,function 'origname)))
2237 (defvar ad-advice-class-completion-table
2239 ad-advice-classes))
2241 (defun ad-read-advice-class (function &optional prompt default)
2242 "Read a valid advice class with completion from the minibuffer.
2244 be returned on empty input (defaults to the first non-empty advice
2248 (ad-dolist (class ad-advice-classes)
2249 (if (ad-get-advice-info-field function class)
2251 (error "ad-read-advice-class: `%s' has no advices" function)))
2254 ad-advice-class-completion-table nil t)))
2259 (defun ad-read-advice-name (function class &optional prompt)
2260 "Read name of existing advice of CLASS for FUNCTION with completion.
2263 (mapcar (function (lambda (advice)
2264 (list (symbol-name (ad-advice-name advice)))))
2265 (ad-get-advice-info-field function class)))
2268 (error "ad-read-advice-name: `%s' has no %s advice"
2277 (defun ad-read-advice-specification (&optional prompt)
2282 (class (ad-read-advice-class function))
2283 (name (ad-read-advice-name function class)))
2299 ;; @@ Finding, enabling, adding and removing pieces of advice:
2302 (defmacro ad-find-advice (function class name)
2303 "Find the first advice of FUNCTION in CLASS with NAME."
2304 `(assq ,name (ad-get-advice-info-field ,function ,class)))
2306 (defun ad-advice-position (function class name)
2307 "Return position of first advice of FUNCTION in CLASS with NAME."
2308 (let* ((found-advice (ad-find-advice function class name))
2309 (advices (ad-get-advice-info-field function class)))
2310 (if found-advice
2311 (- (length advices) (length (memq found-advice advices))))))
2313 (defun ad-find-some-advice (function class name)
2315 NAME can be a symbol or a regular expression matching part of an advice name.
2316 If CLASS is `any' all valid advice classes will be checked."
2318 (let (found-advice)
2319 (ad-dolist (advice-class ad-advice-classes)
2320 (if (or (eq class 'any) (eq advice-class class))
2321 (setq found-advice
2322 (ad-dolist (advice (ad-get-advice-info-field
2323 function advice-class))
2327 (ad-advice-name advice))))
2328 (eq name (ad-advice-name advice)))
2329 (ad-do-return advice)))))
2330 (if found-advice (ad-do-return found-advice))))))
2332 (defun ad-enable-advice-internal (function class name flag)
2336 affected. If CLASS is `any' advices in all valid advice classes will be
2341 (ad-dolist (advice-class ad-advice-classes)
2342 (if (or (eq class 'any) (eq advice-class class))
2343 (ad-dolist (advice (ad-get-advice-info-field
2344 function advice-class))
2347 name (symbol-name (ad-advice-name advice))))
2348 (eq name (ad-advice-name advice)))
2350 (ad-advice-set-enabled advice flag))))))
2354 (defun ad-enable-advice (function class name)
2355 "Enables the advice of FUNCTION with CLASS and NAME."
2356 (interactive (ad-read-advice-specification "Enable advice of"))
2358 (if (eq (ad-enable-advice-internal function class name t) 0)
2359 (error "ad-enable-advice: `%s' has no %s advice matching `%s'"
2361 (error "ad-enable-advice: `%s' is not advised" function)))
2364 (defun ad-disable-advice (function class name)
2365 "Disable the advice of FUNCTION with CLASS and NAME."
2366 (interactive (ad-read-advice-specification "Disable advice of"))
2368 (if (eq (ad-enable-advice-internal function class name nil) 0)
2369 (error "ad-disable-advice: `%s' has no %s advice matching `%s'"
2371 (error "ad-disable-advice: `%s' is not advised" function)))
2375 If CLASS is `any' all valid advice classes are considered. The number of
2381 (or (ad-enable-advice-internal
2406 (defun ad-remove-advice (function class name)
2407 "Remove FUNCTION's advice with NAME from its advices in CLASS.
2408 If such an advice was found it will be removed from the list of advices
2410 (interactive (ad-read-advice-specification "Remove advice of"))
2412 (let ((advice-to-remove (ad-find-advice function class name)))
2413 (if advice-to-remove
2414 (ad-set-advice-info-field
2416 (delq advice-to-remove (ad-get-advice-info-field function class)))
2417 (error "ad-remove-advice: `%s' has no %s advice `%s'"
2419 (error "ad-remove-advice: `%s' is not advised" function)))
2422 (defun ad-add-advice (function advice class position)
2424 If FUNCTION already has one or more pieces of advice of the specified
2429 name, then the position argument will be ignored and the old advice
2431 If the FUNCTION was not advised already, then its advice info will be
2432 initialized. Redefining a piece of advice whose name is part of the cache-id
2435 (ad-initialize-advice-info function)
2436 (ad-set-advice-info-field
2439 (ad-advice-position function class (ad-advice-name advice)))
2440 (advices (ad-get-advice-info-field function class))
2441 ;; Determine a numerical position for the new advice:
2449 (if (memq (ad-advice-name advice) (ad-get-cache-class-id function class))
2452 (setcar (nthcdr position advices) advice)
2454 (ad-set-advice-info-field function class (cons advice advices))
2456 (cons advice (nthcdr position advices)))))))
2504 ;; see ad-make-advice for the format of advice definitions:
2505 (defmacro ad-advice-p (definition)
2506 ;;"non-nil if DEFINITION is a piece of advice."
2507 `(eq (car-safe ,definition) 'advice))
2528 "Return the lambda expression of a function/macro/advice DEFINITION."
2533 ((ad-advice-p definition)
2610 ((or (ad-advice-p definition)
2636 "Return non-nil if DEFINITION was generated from advice information."
2656 (if (ad-advice-p definition)
2657 'advice)))))
2679 (ad-real-definition (ad-get-advice-info-field function 'origname))))
2696 (let ((symbol (make-symbol "advice-compilation"))
2733 ;; make the same advice work regardless of whether something is a
2978 (defun ad-make-single-advice-docstring (advice class &optional style)
2979 (let ((advice-docstring (ad-docstring (ad-advice-definition advice))))
2981 advice-docstring)
2983 (format "Permanent %s-advice `%s':%s%s"
2984 class (ad-advice-name advice)
2985 (if advice-docstring "\n" "")
2986 (or advice-docstring "")))
2987 (t (if advice-docstring
2988 (format "%s-advice `%s':\n%s"
2990 (ad-advice-name advice)
2991 advice-docstring)
2992 (format "%s-advice `%s'."
2994 (ad-advice-name advice)))))))
3001 strings of the individual pieces of advice which will be formatted
3003 will be interpreted as `default'. The order of the advice documentation
3012 paragraphs advice-docstring ad-usage)
3017 (ad-dolist (class ad-advice-classes)
3018 (ad-dolist (advice (ad-get-enabled-advices function class))
3019 (setq advice-docstring
3020 (ad-make-single-advice-docstring advice class style))
3021 (if advice-docstring
3022 (push advice-docstring paragraphs))))
3038 (ad-dolist (advice (append (ad-get-enabled-advices function 'before)
3041 (let ((arglist (ad-arglist (ad-advice-definition advice))))
3048 (ad-dolist (advice (append (ad-get-enabled-advices function 'before)
3052 (ad-interactive-form (ad-advice-definition advice))))
3061 "Generate an advised definition of FUNCTION from its advice info."
3063 (ad-has-redefining-advice function))
3065 (origname (ad-get-advice-info-field function 'origname))
3148 (ad-dolist (advice befores)
3149 (cond ((and (ad-advice-protected advice)
3155 (ad-advice-definition advice))))))
3158 (ad-body-forms (ad-advice-definition advice)))))))
3161 (ad-dolist (advice (reverse arounds))
3163 ;; protect the complete around advice onion:
3164 (if (ad-advice-protected advice)
3170 (ad-prognify (ad-body-forms (ad-advice-definition advice))))))
3178 (ad-dolist (advice afters)
3179 (cond ((and (ad-advice-protected advice)
3185 (ad-advice-definition advice))))))
3188 (ad-body-forms (ad-advice-definition advice)))))))
3206 "Make hook-form from FUNCTION's advice bodies in class HOOK-NAME."
3208 (mapcar (function (lambda (advice)
3209 (ad-body-forms (ad-advice-definition advice))))
3220 ;; definition if the current advice and function definition state is the
3240 ;; A) a piece of advice used in the cache gets redefined
3247 ;; F) a piece of advice used in the cache got redefined before the
3250 ;; Cases A and B are the normal ones. A is taken care of by `ad-add-advice'
3256 ;; from the one available at caching time (e.g., for forward advice of
3264 ;; piece of advice.
3267 ;; There is no way to avoid this without storing the complete advice definition
3270 ;; The cache-id of a typical advised function with one piece of advice and
3276 `(car (ad-get-advice-info-field ,function 'cache)))
3279 `(cdr (ad-get-advice-info-field ,function 'cache)))
3282 `(ad-set-advice-info-field
3291 (ad-set-advice-info-field function 'cache nil))
3297 (list (mapcar (function (lambda (advice) (ad-advice-name advice)))
3299 (mapcar (function (lambda (advice) (ad-advice-name advice)))
3301 (mapcar (function (lambda (advice) (ad-advice-name advice)))
3322 (ad-dolist (advice advices (null cache-class-id))
3323 (if (ad-advice-enabled advice)
3324 (if (eq (car cache-class-id) (ad-advice-name advice))
3337 (code 'before-advice-mismatch))
3339 (car cache-id) (ad-get-advice-info-field function 'before))
3340 (setq code 'around-advice-mismatch)
3342 (nth 1 cache-id) (ad-get-advice-info-field function 'around))
3343 (setq code 'after-advice-mismatch)
3345 (nth 2 cache-id) (ad-get-advice-info-field function 'after))
3371 ;; of the advice mechanism. Preactivation is a special feature of `defadvice',
3373 ;; - remembering the function's current state (definition and advice-info)
3374 ;; - advising it with the defined piece of advice
3377 ;; make use of all its current active advice and its current definition
3379 ;; - resetting the function's advice and definition state to what it was
3390 (defun ad-preactivate-advice (function advice class position)
3396 (old-advice-info (ad-copy-advice-info function))
3400 (ad-add-advice function advice class position)
3401 (ad-enable-advice function class (ad-advice-name advice))
3408 (ad-set-advice-info function old-advice-info)
3418 ;; for the advised function without keeping any advice information. This
3424 ;; Freezing only considers the advice of the particular `defadvice', other
3427 ;; a frozen advice, frozen advices always use the actual original definition
3429 ;; an already advised function gets redefined with a frozen advice and then
3430 ;; unadvised, the frozen advice remains as the new definition of the function.
3437 (defun ad-make-freeze-definition (function advice class position)
3442 (let* ((name (ad-advice-name advice))
3449 ;; as the original definition of the frozen advice:
3452 (old-advice-info
3454 (ad-copy-advice-info function)))
3467 ;; No we reset all current advice information to nil and
3470 (ad-set-advice-info function nil)
3471 (ad-add-advice function advice class position)
3476 ;; Restore the old advice state:
3477 (ad-set-advice-info function old-advice-info)
3587 ;; @@ The top-level advice interface:
3592 "Activate all the advice information of an advised FUNCTION.
3594 definition will be generated from FUNCTION's advice info and the
3602 Activation of an advised function that has an advice info but no actual
3603 pieces of advice is equivalent to a call to `ad-unadvise'. Activation of
3604 an advised function that has actual pieces of advice but none of them are
3608 (list (ad-read-advised-function "Activate advice of")
3618 (if (not (ad-has-any-advice function))
3620 ;; Otherwise activate the advice:
3621 (cond ((ad-has-redefining-advice function)
3623 (ad-set-advice-info-field function 'active t)
3632 "Deactivate the advice of an actively advised FUNCTION.
3634 definition of FUNCTION will be replaced with it. All the advice
3638 (list (ad-read-advised-function "Deactivate advice of" 'ad-is-active)))
3647 (ad-set-advice-info-field function 'active nil)
3652 "Update the advised definition of FUNCTION if its advice is active.
3661 "Deactivate FUNCTION and then remove all its advice information.
3669 (ad-set-advice-info function nil)
3686 (ad-set-advice-info function nil)
3690 "Activate functions with an advice name containing a REGEXP match.
3691 This activates the advice for each function
3692 that has at least one piece of advice whose name includes a match for REGEXP.
3695 (list (ad-read-regexp "Activate via advice regexp")
3698 (if (ad-find-some-advice function 'any regexp)
3702 "Deactivate functions with an advice name containing REGEXP match.
3703 This deactivates the advice for each function
3704 that has at least one piece of advice whose name includes a match for REGEXP."
3706 (list (ad-read-regexp "Deactivate via advice regexp")))
3708 (if (ad-find-some-advice function 'any regexp)
3712 "Update functions with an advice name containing a REGEXP match.
3713 This reactivates the advice for each function
3714 that has at least one piece of advice whose name includes a match for REGEXP.
3717 (list (ad-read-regexp "Update via advice regexp")
3720 (if (ad-find-some-advice function 'any regexp)
3751 To recover a function means to try to find its original (pre-advice)
3752 definition, and delete all advice.
3769 "Define a piece of advice for FUNCTION (a symbol).
3778 NAME ::= Non-nil symbol that names this piece of advice.
3780 see also `ad-add-advice'.
3786 DOCSTRING ::= Optional documentation for this piece of advice.
3792 `protect': The piece of advice will be protected against non-local exits in
3793 any code that precedes it. If any around-advice of a function is protected
3796 `activate': All advice of FUNCTION will be activated immediately if
3802 `disable': The defined advice will be disabled, hence, it will not be used
3807 advice state that will be used during activation if appropriate. Only use
3811 to this particular single advice. No other advice information will be saved.
3823 (error "defadvice: Invalid advice class: %s" class)
3826 (error "defadvice: Invalid advice name: %s" name)
3846 (advice (ad-make-advice
3849 `(advice lambda ,arglist ,@body)))
3851 (ad-preactivate-advice
3852 function advice class position))))
3857 (ad-make-freeze-definition function advice class position)
3860 (ad-add-advice ',function ',advice ',class ',position)
3932 ;; Use the advice mechanism to advise `documentation' to make it
3957 ;; @@ Starting, stopping and recovering from the advice package magic:
3960 (defun ad-start-advice ()
3961 "Start the automatic advice handling magic."
3964 (ad-set-advice-info 'ad-activate-internal nil)
3966 (ad-enable-advice 'documentation 'after 'ad-advised-docstring)
3969 (defun ad-stop-advice ()
3970 "Stop the automatic advice handling magic.
3974 (ad-set-advice-info 'ad-activate-internal nil)
3975 (ad-disable-advice 'documentation 'after 'ad-advised-docstring)
3980 "Undo all advice related redefinitions and unadvises everything.
3984 (ad-set-advice-info 'ad-activate-internal nil)
3989 (ad-start-advice)
3991 (provide 'advice)
3994 ;;; advice.el ends here