comparison lisp/emacs-lisp/advice.el @ 26622:019c7ea59fd9

Many doc fixes.

26621:5df1b3f7ed3a

;;; advice.el --- an overloading mechanism for Emacs Lisp functions

;; Copyright (C) 1993, 1994 Free Software Foundation, Inc.

;; Author: Hans Chalupsky <[e-mail]>
;; Created: 12 Dec 1992
;; Version: advice.el,v 2.14 1994/08/05 03:42:04 hans Exp
;; Keywords: extensions, lisp, tools

;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify

      (ad-set-cache function (symbol-function function) nil)
      (ad-set-cache
       function (symbol-function function) (ad-make-cache-id function)))))

(defun ad-handle-definition (function)
  "Handles re/definition of an advised FUNCTION during de/activation.
If FUNCTION does not have an original definition associated with it and
the current definition is usable, then it will be stored as FUNCTION's
original definition.  If no current definition is available (even in the
case of undefinition) nothing will be done.  In the case of redefinition
the action taken depends on the value of `ad-redefinition-action' (which

;; @@ The top-level advice interface:
;; ==================================

(defun ad-activate (function &optional compile)
  "Activates all the advice information of an advised FUNCTION.
If FUNCTION has a proper original definition then an advised
definition will be generated from FUNCTION's advice info and the
definition of FUNCTION will be replaced with it.  If a previously
cached advised definition was available, it will be used.
The optional COMPILE argument determines whether the resulting function

		      (t (ad-deactivate function)))))))))

(defalias 'ad-activate-on 'ad-activate)

(defun ad-deactivate (function)
  "Deactivates the advice of an actively advised FUNCTION.
If FUNCTION has a proper original definition, then the current
definition of FUNCTION will be replaced with it.  All the advice
information will still be available so it can be activated again with
a call to `ad-activate'."
  (interactive

	  "Update advised definition of: " 'ad-is-active)))
  (if (ad-is-active function)
      (ad-activate function compile)))

(defun ad-unadvise (function)
  "Deactivates FUNCTION and then remove all its advice information.
If FUNCTION was not advised this will be a noop."
  (interactive
   (list (ad-read-advised-function "Unadvise function: ")))
  (cond ((ad-is-advised function)
	 (if (ad-is-active function)

	 (ad-clear-orig-definition function)
	 (ad-set-advice-info function nil)
	 (ad-pop-advised-function function))))

(defun ad-recover (function)
  "Try to recover FUNCTION's original definition and unadvises it.
This is more low-level than `ad-unadvise' because it does not do any
deactivation which might run hooks and get into other trouble.
Use in emergencies."
  ;; Use more primitive interactive behavior here: Accept any symbol that's
  ;; currently defined in obarray, not necessarily with a function definition:
  (interactive
   (list (intern

		(ad-clear-orig-definition function)))
	 (ad-set-advice-info function nil)
	 (ad-pop-advised-function function))))

(defun ad-activate-regexp (regexp &optional compile)
  "Activates functions with an advice name containing a REGEXP match.
See `ad-activate' for documentation on the optional COMPILE argument."
  (interactive
   (list (ad-read-regexp "Activate via advice regexp: ")
	 current-prefix-arg))
  (ad-do-advised-functions (function)
    (if (ad-find-some-advice function 'any regexp)
	(ad-activate function compile))))

(defun ad-deactivate-regexp (regexp)
  "Deactivates functions with an advice name containing REGEXP match."
  (interactive
   (list (ad-read-regexp "Deactivate via advice regexp: ")))
  (ad-do-advised-functions (function)
    (if (ad-find-some-advice function 'any regexp)
	(ad-deactivate function))))

(defun ad-update-regexp (regexp &optional compile)
  "Update functions with an advice name containing a REGEXP match.
See `ad-activate' for documentation on the optional COMPILE argument."
  (interactive
   (list (ad-read-regexp "Update via advice regexp: ")
	 current-prefix-arg))
  (ad-do-advised-functions (function)
    (if (ad-find-some-advice function 'any regexp)
	(ad-update function compile))))

(defun ad-activate-all (&optional compile)
  "Activates all currently advised functions.
See `ad-activate' for documentation on the optional COMPILE argument."
  (interactive "P")
  (ad-do-advised-functions (function)
    (ad-activate function compile)))

(defun ad-deactivate-all ()
  "Deactivates all currently advised functions."
  (interactive)
  (ad-do-advised-functions (function)
    (ad-deactivate function)))

(defun ad-update-all (&optional compile)

  (interactive "P")
  (ad-do-advised-functions (function)
    (ad-update function compile)))

(defun ad-unadvise-all ()
  "Unadvises all currently advised functions."
  (interactive)
  (ad-do-advised-functions (function)
    (ad-unadvise function)))

(defun ad-recover-all ()
  "Recovers all currently advised functions.  Use in emergencies."
  (interactive)
  (ad-do-advised-functions (function)
    (condition-case nil
	(ad-recover function)
      (error nil))))

  (ad-safe-fset 'ad-activate-internal 'ad-activate)
  (ad-enable-advice 'documentation 'after 'ad-advised-docstring)
  (ad-activate 'documentation 'compile))

(defun ad-stop-advice ()
  "Stops the automatic advice handling magic.
You should only need this in case of Advice-related emergencies."
  (interactive)
  ;; Advising `ad-activate-internal' means death!!
  (ad-set-advice-info 'ad-activate-internal nil)
  (ad-disable-advice 'documentation 'after 'ad-advised-docstring)

26622:019c7ea59fd9

;;; advice.el --- an overloading mechanism for Emacs Lisp functions

;; Copyright (C) 1993, 1994 Free Software Foundation, Inc.

;; Author: Hans Chalupsky <[e-mail]>
;; Maintainer: FSF
;; Created: 12 Dec 1992
;; Keywords: extensions, lisp, tools

;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify

      (ad-set-cache function (symbol-function function) nil)
      (ad-set-cache
       function (symbol-function function) (ad-make-cache-id function)))))

(defun ad-handle-definition (function)
  "Handle re/definition of an advised FUNCTION during de/activation.
If FUNCTION does not have an original definition associated with it and
the current definition is usable, then it will be stored as FUNCTION's
original definition.  If no current definition is available (even in the
case of undefinition) nothing will be done.  In the case of redefinition
the action taken depends on the value of `ad-redefinition-action' (which

;; @@ The top-level advice interface:
;; ==================================

(defun ad-activate (function &optional compile)
  "Activate all the advice information of an advised FUNCTION.
If FUNCTION has a proper original definition then an advised
definition will be generated from FUNCTION's advice info and the
definition of FUNCTION will be replaced with it.  If a previously
cached advised definition was available, it will be used.
The optional COMPILE argument determines whether the resulting function

		      (t (ad-deactivate function)))))))))

(defalias 'ad-activate-on 'ad-activate)

(defun ad-deactivate (function)
  "Deactivate the advice of an actively advised FUNCTION.
If FUNCTION has a proper original definition, then the current
definition of FUNCTION will be replaced with it.  All the advice
information will still be available so it can be activated again with
a call to `ad-activate'."
  (interactive

	  "Update advised definition of: " 'ad-is-active)))
  (if (ad-is-active function)
      (ad-activate function compile)))

(defun ad-unadvise (function)
  "Deactivate FUNCTION and then remove all its advice information.
If FUNCTION was not advised this will be a noop."
  (interactive
   (list (ad-read-advised-function "Unadvise function: ")))
  (cond ((ad-is-advised function)
	 (if (ad-is-active function)

	 (ad-clear-orig-definition function)
	 (ad-set-advice-info function nil)
	 (ad-pop-advised-function function))))

(defun ad-recover (function)
  "Try to recover FUNCTION's original definition, and unadvise it.
This is more low-level than `ad-unadvise' in that it does not do
deactivation, which might run hooks and get into other trouble."
Use in emergencies."
  ;; Use more primitive interactive behavior here: Accept any symbol that's
  ;; currently defined in obarray, not necessarily with a function definition:
  (interactive
   (list (intern

		(ad-clear-orig-definition function)))
	 (ad-set-advice-info function nil)
	 (ad-pop-advised-function function))))

(defun ad-activate-regexp (regexp &optional compile)
  "Activate functions with an advice name containing a REGEXP match.
This activates the advice for each function
that has at least one piece of advice whose name includes a match for REGEXP.
See `ad-activate' for documentation on the optional COMPILE argument."
  (interactive
   (list (ad-read-regexp "Activate via advice regexp: ")
	 current-prefix-arg))
  (ad-do-advised-functions (function)
    (if (ad-find-some-advice function 'any regexp)
	(ad-activate function compile))))

(defun ad-deactivate-regexp (regexp)
  "Deactivate functions with an advice name containing REGEXP match.
This deactivates the advice for each function
that has at least one piece of advice whose name includes a match for REGEXP."
  (interactive
   (list (ad-read-regexp "Deactivate via advice regexp: ")))
  (ad-do-advised-functions (function)
    (if (ad-find-some-advice function 'any regexp)
	(ad-deactivate function))))

(defun ad-update-regexp (regexp &optional compile)
  "Update functions with an advice name containing a REGEXP match.
This reactivates the advice for each function
that has at least one piece of advice whose name includes a match for REGEXP.
See `ad-activate' for documentation on the optional COMPILE argument."
  (interactive
   (list (ad-read-regexp "Update via advice regexp: ")
	 current-prefix-arg))
  (ad-do-advised-functions (function)
    (if (ad-find-some-advice function 'any regexp)
	(ad-update function compile))))

(defun ad-activate-all (&optional compile)
  "Activate all currently advised functions.
See `ad-activate' for documentation on the optional COMPILE argument."
  (interactive "P")
  (ad-do-advised-functions (function)
    (ad-activate function compile)))

(defun ad-deactivate-all ()
  "Deactivate all currently advised functions."
  (interactive)
  (ad-do-advised-functions (function)
    (ad-deactivate function)))

(defun ad-update-all (&optional compile)

  (interactive "P")
  (ad-do-advised-functions (function)
    (ad-update function compile)))

(defun ad-unadvise-all ()
  "Unadvise all currently advised functions."
  (interactive)
  (ad-do-advised-functions (function)
    (ad-unadvise function)))

(defun ad-recover-all ()
  "Recover all currently advised functions.  Use in emergencies.
To recover a function means to try to find its original (pre-advice)
definition, and delete all advice.
This is more low-level than `ad-unadvise' in that it does not do
deactivation, which might run hooks and get into other trouble."
  (interactive)
  (ad-do-advised-functions (function)
    (condition-case nil
	(ad-recover function)
      (error nil))))

  (ad-safe-fset 'ad-activate-internal 'ad-activate)
  (ad-enable-advice 'documentation 'after 'ad-advised-docstring)
  (ad-activate 'documentation 'compile))

(defun ad-stop-advice ()
  "Stop the automatic advice handling magic.
You should only need this in case of Advice-related emergencies."
  (interactive)
  ;; Advising `ad-activate-internal' means death!!
  (ad-set-advice-info 'ad-activate-internal nil)
  (ad-disable-advice 'documentation 'after 'ad-advised-docstring)