* doc/lispref/functions.texi (Advising Functions): New section.
* doc/lispref/modes.texi (Running Hooks): Don't document with-wrapper-hook and run-hook-wrapped any more. (Hooks): Link to the new Advising Functions node. * doc/lispref/elisp.texi (Top): Don't include advice.texi. * doc/lispref/advice.texi: Remove. * doc/lispref/makefile.w32-in (srcs): * doc/lispref/Makefile.in (srcs): Adjust accordingly. * doc/misc/cl.texi (Function Bindings): Fix incorrect description of cl-let.
This commit is contained in:
Stefan Monnier
parent
cd6d07ece2
commit
122ff675df
11 changed files with 334 additions and 867 deletions
|
|
@ -218,7 +218,6 @@ xresources.texi cyd
|
|||
** Check the Lisp manual.
|
||||
|
||||
abbrevs.texi rgm
|
||||
advice.texi cyd
|
||||
anti.texi rgm
|
||||
back.texi rgm
|
||||
backups.texi cyd
|
||||
|
|
|
|||
|
|
@ -1,3 +1,14 @@
|
|||
2014-01-10 Stefan Monnier <monnier@iro.umontreal.ca>
|
||||
|
||||
* functions.texi (Advising Functions): New section.
|
||||
* modes.texi (Running Hooks): Don't document with-wrapper-hook and
|
||||
run-hook-wrapped any more.
|
||||
(Hooks): Link to the new Advising Functions node.
|
||||
* elisp.texi (Top): Don't include advice.texi.
|
||||
* advice.texi: Remove.
|
||||
* makefile.w32-in (srcs):
|
||||
* Makefile.in (srcs): Adjust accordingly.
|
||||
|
||||
2014-01-09 Rüdiger Sonderfeld <ruediger@c-plusplus.de>
|
||||
|
||||
* text.texi (Parsing HTML/XML): Document `shr-insert-document'.
|
||||
|
|
|
|||
|
|
@ -76,7 +76,6 @@ srcs = \
|
|||
$(srcdir)/elisp.texi \
|
||||
$(emacsdir)/emacsver.texi \
|
||||
$(srcdir)/abbrevs.texi \
|
||||
$(srcdir)/advice.texi \
|
||||
$(srcdir)/anti.texi \
|
||||
$(srcdir)/backups.texi \
|
||||
$(srcdir)/buffers.texi \
|
||||
|
|
|
|||
|
|
@ -1,749 +0,0 @@
|
|||
@c -*-texinfo-*-
|
||||
@c This is part of the GNU Emacs Lisp Reference Manual.
|
||||
@c Copyright (C) 1998-1999, 2001-2014 Free Software Foundation, Inc.
|
||||
@c See the file elisp.texi for copying conditions.
|
||||
@node Advising Functions
|
||||
@chapter Advising Emacs Lisp Functions
|
||||
@cindex advising functions
|
||||
|
||||
@cindex piece of advice
|
||||
The @dfn{advice} feature lets you add to the existing definition of
|
||||
a function, by @dfn{advising the function}. A function can have
|
||||
multiple @dfn{pieces of advice}, each of which can be separately
|
||||
defined, and separately enabled or disabled (@pxref{Activation of
|
||||
Advice}). Each piece of advice can alter almost anything about the
|
||||
function, including its argument list, what the function does when it
|
||||
runs, and the value it returns.
|
||||
|
||||
Advice can be useful for altering the behavior of an existing
|
||||
function without having to redefine the whole function. However, it
|
||||
can be a source of bugs, since existing callers to the function may
|
||||
assume the old behavior, and work incorrectly when the behavior is
|
||||
changed by advice. Advice can also cause confusion in debugging, if
|
||||
the person doing the debugging does not notice or remember that the
|
||||
function has been modified by advice.
|
||||
|
||||
For these reasons, advice should be reserved for the cases where you
|
||||
cannot modify a function's behavior in any other way. If it is
|
||||
possible to do the same thing via a hook, that is preferable
|
||||
(@pxref{Hooks}). If you simply want to change what a particular key
|
||||
does, it may be better to write a new command, and remap the old
|
||||
command's key bindings to the new one (@pxref{Remapping Commands}).
|
||||
In particular, Emacs's own source files should not put advice on
|
||||
functions in Emacs. (There are currently a few exceptions to this
|
||||
convention, but we aim to correct them.)
|
||||
|
||||
Macros can also be advised, in much the same way as functions.
|
||||
However, special forms (@pxref{Special Forms}) cannot be advised.
|
||||
|
||||
It is possible to advise a primitive (@pxref{What Is a Function}),
|
||||
but one should typically @emph{not} do so, for two reasons. Firstly,
|
||||
some primitives are used by the advice mechanism, and advising them
|
||||
could cause an infinite recursion. Secondly, many primitives are
|
||||
called directly from C, and such calls ignore advice; hence, one ends
|
||||
up in a confusing situation where some calls (occurring from Lisp
|
||||
code) obey the advice and other calls (from C code) do not.
|
||||
|
||||
@menu
|
||||
* Simple Advice:: A simple example to explain the basics of advice.
|
||||
* Defining Advice:: Detailed description of @code{defadvice}.
|
||||
* Around-Advice:: Wrapping advice around a function's definition.
|
||||
* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}.
|
||||
* Activation of Advice:: Advice doesn't do anything until you activate it.
|
||||
* Enabling Advice:: You can enable or disable each piece of advice.
|
||||
* Preactivation:: Preactivation is a way of speeding up the
|
||||
loading of compiled advice.
|
||||
* Argument Access in Advice:: How advice can access the function's arguments.
|
||||
* Combined Definition:: How advice is implemented.
|
||||
@end menu
|
||||
|
||||
@node Simple Advice
|
||||
@section A Simple Advice Example
|
||||
|
||||
The command @code{next-line} moves point down vertically one or more
|
||||
lines; it is the standard binding of @kbd{C-n}. When used on the last
|
||||
line of the buffer, this command inserts a newline to create a line to
|
||||
move to if @code{next-line-add-newlines} is non-@code{nil} (its default
|
||||
is @code{nil}.)
|
||||
|
||||
Suppose you wanted to add a similar feature to @code{previous-line},
|
||||
which would insert a new line at the beginning of the buffer for the
|
||||
command to move to (when @code{next-line-add-newlines} is
|
||||
non-@code{nil}). How could you do this?
|
||||
|
||||
You could do it by redefining the whole function, but that is not
|
||||
modular. The advice feature provides a cleaner alternative: you can
|
||||
effectively add your code to the existing function definition, without
|
||||
actually changing or even seeing that definition. Here is how to do
|
||||
this:
|
||||
|
||||
@example
|
||||
(defadvice previous-line (before next-line-at-end
|
||||
(&optional arg try-vscroll))
|
||||
"Insert an empty line when moving up from the top line."
|
||||
(if (and next-line-add-newlines (= arg 1)
|
||||
(save-excursion (beginning-of-line) (bobp)))
|
||||
(progn
|
||||
(beginning-of-line)
|
||||
(newline))))
|
||||
@end example
|
||||
|
||||
This expression defines a @dfn{piece of advice} for the function
|
||||
@code{previous-line}. This piece of advice is named
|
||||
@code{next-line-at-end}, and the symbol @code{before} says that it is
|
||||
@dfn{before-advice} which should run before the regular definition of
|
||||
@code{previous-line}. @code{(&optional arg try-vscroll)} specifies
|
||||
how the advice code can refer to the function's arguments.
|
||||
|
||||
When this piece of advice runs, it creates an additional line, in the
|
||||
situation where that is appropriate, but does not move point to that
|
||||
line. This is the correct way to write the advice, because the normal
|
||||
definition will run afterward and will move back to the newly inserted
|
||||
line.
|
||||
|
||||
Defining the advice doesn't immediately change the function
|
||||
@code{previous-line}. That happens when you @dfn{activate} the advice,
|
||||
like this:
|
||||
|
||||
@example
|
||||
(ad-activate 'previous-line)
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
This is what actually begins to use the advice that has been defined so
|
||||
far for the function @code{previous-line}. Henceforth, whenever that
|
||||
function is run, whether invoked by the user with @kbd{C-p} or
|
||||
@kbd{M-x}, or called from Lisp, it runs the advice first, and its
|
||||
regular definition second.
|
||||
|
||||
This example illustrates before-advice, which is one @dfn{class} of
|
||||
advice: it runs before the function's base definition. There are two
|
||||
other advice classes: @dfn{after-advice}, which runs after the base
|
||||
definition, and @dfn{around-advice}, which lets you specify an
|
||||
expression to wrap around the invocation of the base definition.
|
||||
|
||||
@node Defining Advice
|
||||
@section Defining Advice
|
||||
@cindex defining advice
|
||||
@cindex advice, defining
|
||||
|
||||
To define a piece of advice, use the macro @code{defadvice}. A call
|
||||
to @code{defadvice} has the following syntax, which is based on the
|
||||
syntax of @code{defun} and @code{defmacro}, but adds more:
|
||||
|
||||
@findex defadvice
|
||||
@example
|
||||
(defadvice @var{function} (@var{class} @var{name}
|
||||
@r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]}
|
||||
@var{flags}...)
|
||||
@r{[}@var{documentation-string}@r{]}
|
||||
@r{[}@var{interactive-form}@r{]}
|
||||
@var{body-forms}...)
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
Here, @var{function} is the name of the function (or macro) to be
|
||||
advised. From now on, we will write just ``function'' when describing
|
||||
the entity being advised, but this always includes macros.
|
||||
|
||||
In place of the argument list in an ordinary definition, an advice
|
||||
definition calls for several different pieces of information.
|
||||
|
||||
@cindex class of advice
|
||||
@cindex before-advice
|
||||
@cindex after-advice
|
||||
@cindex around-advice
|
||||
@var{class} specifies the @dfn{class} of the advice---one of @code{before},
|
||||
@code{after}, or @code{around}. Before-advice runs before the function
|
||||
itself; after-advice runs after the function itself; around-advice is
|
||||
wrapped around the execution of the function itself. After-advice and
|
||||
around-advice can override the return value by setting
|
||||
@code{ad-return-value}.
|
||||
|
||||
@defvar ad-return-value
|
||||
While advice is executing, after the function's original definition has
|
||||
been executed, this variable holds its return value, which will
|
||||
ultimately be returned to the caller after finishing all the advice.
|
||||
After-advice and around-advice can arrange to return some other value
|
||||
by storing it in this variable.
|
||||
@end defvar
|
||||
|
||||
The argument @var{name} is the name of the advice, a non-@code{nil}
|
||||
symbol. The advice name uniquely identifies one piece of advice, within all
|
||||
the pieces of advice in a particular class for a particular
|
||||
@var{function}. The name allows you to refer to the piece of
|
||||
advice---to redefine it, or to enable or disable it.
|
||||
|
||||
The optional @var{position} specifies where, in the current list of
|
||||
advice of the specified @var{class}, this new advice should be placed.
|
||||
It should be either @code{first}, @code{last} or a number that specifies
|
||||
a zero-based position (@code{first} is equivalent to 0). If no position
|
||||
is specified, the default is @code{first}. Position values outside the
|
||||
range of existing positions in this class are mapped to the beginning or
|
||||
the end of the range, whichever is closer. The @var{position} value is
|
||||
ignored when redefining an existing piece of advice.
|
||||
|
||||
The optional @var{arglist} can be used to define the argument list for
|
||||
the sake of advice. This becomes the argument list of the combined
|
||||
definition that is generated in order to run the advice (@pxref{Combined
|
||||
Definition}). Therefore, the advice expressions can use the argument
|
||||
variables in this list to access argument values.
|
||||
|
||||
The argument list used in advice need not be the same as the argument
|
||||
list used in the original function, but must be compatible with it, so
|
||||
that it can handle the ways the function is actually called. If two
|
||||
pieces of advice for a function both specify an argument list, they must
|
||||
specify the same argument list.
|
||||
|
||||
@xref{Argument Access in Advice}, for more information about argument
|
||||
lists and advice, and a more flexible way for advice to access the
|
||||
arguments.
|
||||
|
||||
The remaining elements, @var{flags}, are symbols that specify further
|
||||
information about how to use this piece of advice. Here are the valid
|
||||
symbols and their meanings:
|
||||
|
||||
@table @code
|
||||
@item activate
|
||||
Activate the advice for @var{function} now. Changes in a function's
|
||||
advice always take effect the next time you activate advice for the
|
||||
function; this flag says to do so, for @var{function}, immediately after
|
||||
defining this piece of advice.
|
||||
|
||||
@cindex forward advice
|
||||
This flag has no immediate effect if @var{function} itself is not defined yet (a
|
||||
situation known as @dfn{forward advice}), because it is impossible to
|
||||
activate an undefined function's advice. However, defining
|
||||
@var{function} will automatically activate its advice.
|
||||
|
||||
@item protect
|
||||
Protect this piece of advice against non-local exits and errors in
|
||||
preceding code and advice. Protecting advice places it as a cleanup in
|
||||
an @code{unwind-protect} form, so that it will execute even if the
|
||||
previous code gets an error or uses @code{throw}. @xref{Cleanups}.
|
||||
|
||||
@item compile
|
||||
Compile the combined definition that is used to run the advice. This
|
||||
flag is ignored unless @code{activate} is also specified.
|
||||
@xref{Combined Definition}.
|
||||
|
||||
@item disable
|
||||
Initially disable this piece of advice, so that it will not be used
|
||||
unless subsequently explicitly enabled. @xref{Enabling Advice}.
|
||||
|
||||
@item preactivate
|
||||
Activate advice for @var{function} when this @code{defadvice} is
|
||||
compiled or macroexpanded. This generates a compiled advised definition
|
||||
according to the current advice state, which will be used during
|
||||
activation if appropriate. @xref{Preactivation}.
|
||||
|
||||
This is useful only if this @code{defadvice} is byte-compiled.
|
||||
@end table
|
||||
|
||||
The optional @var{documentation-string} serves to document this piece of
|
||||
advice. When advice is active for @var{function}, the documentation for
|
||||
@var{function} (as returned by @code{documentation}) combines the
|
||||
documentation strings of all the advice for @var{function} with the
|
||||
documentation string of its original function definition.
|
||||
|
||||
The optional @var{interactive-form} form can be supplied to change the
|
||||
interactive behavior of the original function. If more than one piece
|
||||
of advice has an @var{interactive-form}, then the first one (the one
|
||||
with the smallest position) found among all the advice takes precedence.
|
||||
|
||||
The possibly empty list of @var{body-forms} specifies the body of the
|
||||
advice. The body of an advice can access or change the arguments, the
|
||||
return value, the binding environment, and perform any other kind of
|
||||
side effect.
|
||||
|
||||
@strong{Warning:} When you advise a macro, keep in mind that macros are
|
||||
expanded when a program is compiled, not when a compiled program is run.
|
||||
All subroutines used by the advice need to be available when the byte
|
||||
compiler expands the macro.
|
||||
|
||||
@deffn Command ad-unadvise function
|
||||
This command deletes all pieces of advice from @var{function}.
|
||||
@end deffn
|
||||
|
||||
@deffn Command ad-unadvise-all
|
||||
This command deletes all pieces of advice from all functions.
|
||||
@end deffn
|
||||
|
||||
@node Around-Advice
|
||||
@section Around-Advice
|
||||
|
||||
Around-advice lets you ``wrap'' a Lisp expression ``around'' the
|
||||
original function definition. You specify where the original function
|
||||
definition should go by means of the special symbol @code{ad-do-it}.
|
||||
Where this symbol occurs inside the around-advice body, it is replaced
|
||||
with a @code{progn} containing the forms of the surrounded code. Here
|
||||
is an example:
|
||||
|
||||
@example
|
||||
(defadvice foo (around foo-around)
|
||||
"Ignore case in `foo'."
|
||||
(let ((case-fold-search t))
|
||||
ad-do-it))
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
Its effect is to make sure that case is ignored in
|
||||
searches when the original definition of @code{foo} is run.
|
||||
|
||||
@defvar ad-do-it
|
||||
This is not really a variable, rather a place-holder that looks like a
|
||||
variable. You use it in around-advice to specify the place to run the
|
||||
function's original definition and other ``earlier'' around-advice.
|
||||
@end defvar
|
||||
|
||||
If the around-advice does not use @code{ad-do-it}, then it does not run
|
||||
the original function definition. This provides a way to override the
|
||||
original definition completely. (It also overrides lower-positioned
|
||||
pieces of around-advice).
|
||||
|
||||
If the around-advice uses @code{ad-do-it} more than once, the original
|
||||
definition is run at each place. In this way, around-advice can execute
|
||||
the original definition (and lower-positioned pieces of around-advice)
|
||||
several times. Another way to do that is by using @code{ad-do-it}
|
||||
inside of a loop.
|
||||
|
||||
@node Computed Advice
|
||||
@section Computed Advice
|
||||
|
||||
The macro @code{defadvice} resembles @code{defun} in that the code for
|
||||
the advice, and all other information about it, are explicitly stated in
|
||||
the source code. You can also create advice whose details are computed,
|
||||
using the function @code{ad-add-advice}.
|
||||
|
||||
@defun ad-add-advice function advice class position
|
||||
Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to
|
||||
@var{function} in class @var{class}. The argument @var{advice} has
|
||||
this form:
|
||||
|
||||
@example
|
||||
(@var{name} @var{protected} @var{enabled} @var{definition})
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
Here, @var{protected} and @var{enabled} are flags; if @var{protected}
|
||||
is non-@code{nil}, the advice is protected against non-local exits
|
||||
(@pxref{Defining Advice}), and if @var{enabled} is @code{nil} the
|
||||
advice is initially disabled (@pxref{Enabling Advice}).
|
||||
@var{definition} should have the form
|
||||
|
||||
@example
|
||||
(advice . @var{lambda})
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
where @var{lambda} is a lambda expression; this lambda expression is
|
||||
called in order to perform the advice. @xref{Lambda Expressions}.
|
||||
|
||||
If the @var{function} argument to @code{ad-add-advice} already has one
|
||||
or more pieces of advice in the specified @var{class}, then
|
||||
@var{position} specifies where in the list to put the new piece of
|
||||
advice. The value of @var{position} can either be @code{first},
|
||||
@code{last}, or a number (counting from 0 at the beginning of the
|
||||
list). Numbers outside the range are mapped to the beginning or the
|
||||
end of the range, whichever is closer. The @var{position} value is
|
||||
ignored when redefining an existing piece of advice.
|
||||
|
||||
If @var{function} already has a piece of @var{advice} with the same
|
||||
name, then the position argument is ignored and the old advice is
|
||||
replaced with the new one.
|
||||
@end defun
|
||||
|
||||
@node Activation of Advice
|
||||
@section Activation of Advice
|
||||
@cindex activating advice
|
||||
@cindex advice, activating
|
||||
|
||||
By default, advice does not take effect when you define it---only when
|
||||
you @dfn{activate} advice for the function. However, the advice will
|
||||
be activated automatically if you define or redefine the function
|
||||
later. You can request the activation of advice for a function when
|
||||
you define the advice, by specifying the @code{activate} flag in the
|
||||
@code{defadvice}; or you can activate the advice separately by calling
|
||||
the function @code{ad-activate} or one of the other activation
|
||||
commands listed below.
|
||||
|
||||
Separating the activation of advice from the act of defining it permits
|
||||
you to add several pieces of advice to one function efficiently, without
|
||||
redefining the function over and over as each advice is added. More
|
||||
importantly, it permits defining advice for a function before that
|
||||
function is actually defined.
|
||||
|
||||
When a function's advice is first activated, the function's original
|
||||
definition is saved, and all enabled pieces of advice for that function
|
||||
are combined with the original definition to make a new definition.
|
||||
(Pieces of advice that are currently disabled are not used; see
|
||||
@ref{Enabling Advice}.) This definition is installed, and optionally
|
||||
byte-compiled as well, depending on conditions described below.
|
||||
|
||||
In all of the commands to activate advice, if @var{compile} is
|
||||
@code{t} (or anything but @code{nil} or a negative number), the
|
||||
command also compiles the combined definition which implements the
|
||||
advice. If it is @code{nil} or a negative number, what happens
|
||||
depends on @code{ad-default-compilation-action} as described below.
|
||||
|
||||
@deffn Command ad-activate function &optional compile
|
||||
This command activates all the advice defined for @var{function}.
|
||||
@end deffn
|
||||
|
||||
Activating advice does nothing if @var{function}'s advice is already
|
||||
active. But if there is new advice, added since the previous time you
|
||||
activated advice for @var{function}, it activates the new advice.
|
||||
|
||||
@deffn Command ad-deactivate function
|
||||
This command deactivates the advice for @var{function}.
|
||||
@cindex deactivating advice
|
||||
@c @cindex advice, deactivating "advice, activating" is just above
|
||||
@end deffn
|
||||
|
||||
@deffn Command ad-update function &optional compile
|
||||
This command activates the advice for @var{function}
|
||||
if its advice is already activated. This is useful
|
||||
if you change the advice.
|
||||
@end deffn
|
||||
|
||||
@deffn Command ad-activate-all &optional compile
|
||||
This command activates the advice for all functions.
|
||||
@end deffn
|
||||
|
||||
@deffn Command ad-deactivate-all
|
||||
This command deactivates the advice for all functions.
|
||||
@end deffn
|
||||
|
||||
@deffn Command ad-update-all &optional compile
|
||||
This command activates the advice for all functions
|
||||
whose advice is already activated. This is useful
|
||||
if you change the advice of some functions.
|
||||
@end deffn
|
||||
|
||||
@deffn Command ad-activate-regexp regexp &optional compile
|
||||
This command activates all pieces of advice whose names match
|
||||
@var{regexp}. More precisely, it activates all advice for any function
|
||||
which has at least one piece of advice that matches @var{regexp}.
|
||||
@end deffn
|
||||
|
||||
@deffn Command ad-deactivate-regexp regexp
|
||||
This command deactivates all pieces of advice whose names match
|
||||
@var{regexp}. More precisely, it deactivates all advice for any
|
||||
function which has at least one piece of advice that matches
|
||||
@var{regexp}.
|
||||
@end deffn
|
||||
|
||||
@deffn Command ad-update-regexp regexp &optional compile
|
||||
This command activates pieces of advice whose names match @var{regexp},
|
||||
but only those for functions whose advice is already activated.
|
||||
@cindex reactivating advice
|
||||
|
||||
Reactivating a function's advice is useful for putting into effect all
|
||||
the changes that have been made in its advice (including enabling and
|
||||
disabling specific pieces of advice; @pxref{Enabling Advice}) since the
|
||||
last time it was activated.
|
||||
@end deffn
|
||||
|
||||
@deffn Command ad-start-advice
|
||||
Turn on automatic advice activation when a function is defined or
|
||||
redefined. This is the default mode.
|
||||
@end deffn
|
||||
|
||||
@deffn Command ad-stop-advice
|
||||
Turn off automatic advice activation when a function is defined or
|
||||
redefined.
|
||||
@end deffn
|
||||
|
||||
@defopt ad-default-compilation-action
|
||||
This variable controls whether to compile the combined definition
|
||||
that results from activating advice for a function.
|
||||
|
||||
A value of @code{always} specifies to compile unconditionally.
|
||||
A value of @code{never} specifies never compile the advice.
|
||||
|
||||
A value of @code{maybe} specifies to compile if the byte compiler is
|
||||
already loaded. A value of @code{like-original} specifies to compile
|
||||
the advice if the original definition of the advised function is
|
||||
compiled or a built-in function.
|
||||
|
||||
This variable takes effect only if the @var{compile} argument of
|
||||
@code{ad-activate} (or any of the above functions) did not force
|
||||
compilation.
|
||||
@end defopt
|
||||
|
||||
If the advised definition was constructed during ``preactivation''
|
||||
(@pxref{Preactivation}), then that definition must already be compiled,
|
||||
because it was constructed during byte-compilation of the file that
|
||||
contained the @code{defadvice} with the @code{preactivate} flag.
|
||||
|
||||
@node Enabling Advice
|
||||
@section Enabling and Disabling Advice
|
||||
@cindex enabling advice
|
||||
@cindex advice, enabling and disabling
|
||||
@cindex disabling advice
|
||||
|
||||
Each piece of advice has a flag that says whether it is enabled or
|
||||
not. By enabling or disabling a piece of advice, you can turn it on
|
||||
and off without having to undefine and redefine it. For example, here is
|
||||
how to disable a particular piece of advice named @code{my-advice} for
|
||||
the function @code{foo}:
|
||||
|
||||
@example
|
||||
(ad-disable-advice 'foo 'before 'my-advice)
|
||||
@end example
|
||||
|
||||
This function by itself only changes the enable flag for a piece of
|
||||
advice. To make the change take effect in the advised definition, you
|
||||
must activate the advice for @code{foo} again:
|
||||
|
||||
@example
|
||||
(ad-activate 'foo)
|
||||
@end example
|
||||
|
||||
@deffn Command ad-disable-advice function class name
|
||||
This command disables the piece of advice named @var{name} in class
|
||||
@var{class} on @var{function}.
|
||||
@end deffn
|
||||
|
||||
@deffn Command ad-enable-advice function class name
|
||||
This command enables the piece of advice named @var{name} in class
|
||||
@var{class} on @var{function}.
|
||||
@end deffn
|
||||
|
||||
You can also disable many pieces of advice at once, for various
|
||||
functions, using a regular expression. As always, the changes take real
|
||||
effect only when you next reactivate advice for the functions in
|
||||
question.
|
||||
|
||||
@deffn Command ad-disable-regexp regexp
|
||||
This command disables all pieces of advice whose names match
|
||||
@var{regexp}, in all classes, on all functions.
|
||||
@end deffn
|
||||
|
||||
@deffn Command ad-enable-regexp regexp
|
||||
This command enables all pieces of advice whose names match
|
||||
@var{regexp}, in all classes, on all functions.
|
||||
@end deffn
|
||||
|
||||
@node Preactivation
|
||||
@section Preactivation
|
||||
@cindex preactivating advice
|
||||
@cindex advice, preactivating
|
||||
|
||||
Constructing a combined definition to execute advice is moderately
|
||||
expensive. When a library advises many functions, this can make loading
|
||||
the library slow. In that case, you can use @dfn{preactivation} to
|
||||
construct suitable combined definitions in advance.
|
||||
|
||||
To use preactivation, specify the @code{preactivate} flag when you
|
||||
define the advice with @code{defadvice}. This @code{defadvice} call
|
||||
creates a combined definition which embodies this piece of advice
|
||||
(whether enabled or not) plus any other currently enabled advice for the
|
||||
same function, and the function's own definition. If the
|
||||
@code{defadvice} is compiled, that compiles the combined definition
|
||||
also.
|
||||
|
||||
When the function's advice is subsequently activated, if the enabled
|
||||
advice for the function matches what was used to make this combined
|
||||
definition, then the existing combined definition is used, thus avoiding
|
||||
the need to construct one. Thus, preactivation never causes wrong
|
||||
results---but it may fail to do any good, if the enabled advice at the
|
||||
time of activation doesn't match what was used for preactivation.
|
||||
|
||||
Here are some symptoms that can indicate that a preactivation did not
|
||||
work properly, because of a mismatch.
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
Activation of the advised
|
||||
function takes longer than usual.
|
||||
@item
|
||||
The byte compiler gets
|
||||
loaded while an advised function gets activated.
|
||||
@item
|
||||
@code{byte-compile} is included in the value of @code{features} even
|
||||
though you did not ever explicitly use the byte compiler.
|
||||
@end itemize
|
||||
|
||||
Compiled preactivated advice works properly even if the function itself
|
||||
is not defined until later; however, the function needs to be defined
|
||||
when you @emph{compile} the preactivated advice.
|
||||
|
||||
There is no elegant way to find out why preactivated advice is not being
|
||||
used. What you can do is to trace the function
|
||||
@code{ad-cache-id-verification-code} (with the function
|
||||
@code{trace-function-background}) before the advised function's advice
|
||||
is activated. After activation, check the value returned by
|
||||
@code{ad-cache-id-verification-code} for that function: @code{verified}
|
||||
means that the preactivated advice was used, while other values give
|
||||
some information about why they were considered inappropriate.
|
||||
|
||||
@strong{Warning:} There is one known case that can make preactivation
|
||||
fail, in that a preconstructed combined definition is used even though
|
||||
it fails to match the current state of advice. This can happen when two
|
||||
packages define different pieces of advice with the same name, in the
|
||||
same class, for the same function. But you should avoid that anyway.
|
||||
|
||||
@node Argument Access in Advice
|
||||
@section Argument Access in Advice
|
||||
|
||||
The simplest way to access the arguments of an advised function in the
|
||||
body of a piece of advice is to use the same names that the function
|
||||
definition uses. To do this, you need to know the names of the argument
|
||||
variables of the original function.
|
||||
|
||||
While this simple method is sufficient in many cases, it has a
|
||||
disadvantage: it is not robust, because it hard-codes the argument names
|
||||
into the advice. If the definition of the original function changes,
|
||||
the advice might break.
|
||||
|
||||
Another method is to specify an argument list in the advice itself.
|
||||
This avoids the need to know the original function definition's argument
|
||||
names, but it has a limitation: all the advice on any particular
|
||||
function must use the same argument list, because the argument list
|
||||
actually used for all the advice comes from the first piece of advice
|
||||
for that function.
|
||||
|
||||
A more robust method is to use macros that are translated into the
|
||||
proper access forms at activation time, i.e., when constructing the
|
||||
advised definition. Access macros access actual arguments by their
|
||||
(zero-based) position, regardless of how these actual arguments get
|
||||
distributed onto the argument variables of a function. This is robust
|
||||
because in Emacs Lisp the meaning of an argument is strictly
|
||||
determined by its position in the argument list.
|
||||
|
||||
@defmac ad-get-arg position
|
||||
This returns the actual argument that was supplied at @var{position}.
|
||||
@end defmac
|
||||
|
||||
@defmac ad-get-args position
|
||||
This returns the list of actual arguments supplied starting at
|
||||
@var{position}.
|
||||
@end defmac
|
||||
|
||||
@defmac ad-set-arg position value
|
||||
This sets the value of the actual argument at @var{position} to
|
||||
@var{value}
|
||||
@end defmac
|
||||
|
||||
@defmac ad-set-args position value-list
|
||||
This sets the list of actual arguments starting at @var{position} to
|
||||
@var{value-list}.
|
||||
@end defmac
|
||||
|
||||
Now an example. Suppose the function @code{foo} is defined as
|
||||
|
||||
@example
|
||||
(defun foo (x y &optional z &rest r) ...)
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
and is then called with
|
||||
|
||||
@example
|
||||
(foo 0 1 2 3 4 5 6)
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is
|
||||
@code{(3 4 5 6)} within the body of @code{foo}. Here is what
|
||||
@code{ad-get-arg} and @code{ad-get-args} return in this case:
|
||||
|
||||
@example
|
||||
(ad-get-arg 0) @result{} 0
|
||||
(ad-get-arg 1) @result{} 1
|
||||
(ad-get-arg 2) @result{} 2
|
||||
(ad-get-arg 3) @result{} 3
|
||||
(ad-get-args 2) @result{} (2 3 4 5 6)
|
||||
(ad-get-args 4) @result{} (4 5 6)
|
||||
@end example
|
||||
|
||||
Setting arguments also makes sense in this example:
|
||||
|
||||
@example
|
||||
(ad-set-arg 5 "five")
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
has the effect of changing the sixth argument to @code{"five"}. If this
|
||||
happens in advice executed before the body of @code{foo} is run, then
|
||||
@var{r} will be @code{(3 4 "five" 6)} within that body.
|
||||
|
||||
Here is an example of setting a tail of the argument list:
|
||||
|
||||
@example
|
||||
(ad-set-args 0 '(5 4 3 2 1 0))
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
If this happens in advice executed before the body of @code{foo} is run,
|
||||
then within that body, @var{x} will be 5, @var{y} will be 4, @var{z}
|
||||
will be 3, and @var{r} will be @code{(2 1 0)} inside the body of
|
||||
@code{foo}.
|
||||
|
||||
These argument constructs are not really implemented as Lisp macros.
|
||||
Instead they are implemented specially by the advice mechanism.
|
||||
|
||||
@node Combined Definition
|
||||
@section The Combined Definition
|
||||
|
||||
Suppose that a function has @var{n} pieces of before-advice
|
||||
(numbered from 0 through @var{n}@minus{}1), @var{m} pieces of
|
||||
around-advice and @var{k} pieces of after-advice. Assuming no piece
|
||||
of advice is protected, the combined definition produced to implement
|
||||
the advice for a function looks like this:
|
||||
|
||||
@example
|
||||
(lambda @var{arglist}
|
||||
@r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]}
|
||||
(let (ad-return-value)
|
||||
@r{before-0-body-form}...
|
||||
....
|
||||
@r{before-@var{n}@minus{}1-body-form}...
|
||||
@r{around-0-body-form}...
|
||||
@r{around-1-body-form}...
|
||||
....
|
||||
@r{around-@var{m}@minus{}1-body-form}...
|
||||
(setq ad-return-value
|
||||
@r{apply original definition to @var{arglist}})
|
||||
@r{end-of-around-@var{m}@minus{}1-body-form}...
|
||||
....
|
||||
@r{end-of-around-1-body-form}...
|
||||
@r{end-of-around-0-body-form}...
|
||||
@r{after-0-body-form}...
|
||||
....
|
||||
@r{after-@var{k}@minus{}1-body-form}...
|
||||
ad-return-value))
|
||||
@end example
|
||||
|
||||
Macros are redefined as macros, which means adding @code{macro} to
|
||||
the beginning of the combined definition.
|
||||
|
||||
The interactive form is present if the original function or some piece
|
||||
of advice specifies one. When an interactive primitive function is
|
||||
advised, advice uses a special method: it calls the primitive with
|
||||
@code{call-interactively} so that it will read its own arguments.
|
||||
In this case, the advice cannot access the arguments.
|
||||
|
||||
The body forms of the various advice in each class are assembled
|
||||
according to their specified order. The forms of around-advice @var{l}
|
||||
are included in one of the forms of around-advice @var{l} @minus{} 1.
|
||||
|
||||
The innermost part of the around advice onion is
|
||||
|
||||
@display
|
||||
apply original definition to @var{arglist}
|
||||
@end display
|
||||
|
||||
@noindent
|
||||
whose form depends on the type of the original function. The variable
|
||||
@code{ad-return-value} is set to whatever this returns. The variable is
|
||||
visible to all pieces of advice, which can access and modify it before
|
||||
it is actually returned from the advised function.
|
||||
|
||||
The semantic structure of advised functions that contain protected
|
||||
pieces of advice is the same. The only difference is that
|
||||
@code{unwind-protect} forms ensure that the protected advice gets
|
||||
executed even if some previous piece of advice had an error or a
|
||||
non-local exit. If any around-advice is protected, then the whole
|
||||
around-advice onion is protected as a result.
|
||||
|
|
@ -194,7 +194,6 @@ To view this manual in other formats, click
|
|||
|
||||
* Loading:: Reading files of Lisp code into Lisp.
|
||||
* Byte Compilation:: Compilation makes programs run faster.
|
||||
* Advising Functions:: Adding to the definition of a function.
|
||||
* Debugging:: Tools and tips for debugging Lisp programs.
|
||||
|
||||
* Read and Print:: Converting Lisp objects to text and back.
|
||||
|
|
@ -614,19 +613,6 @@ Byte Compilation
|
|||
* Byte-Code Objects:: The data type used for byte-compiled functions.
|
||||
* Disassembly:: Disassembling byte-code; how to read byte-code.
|
||||
|
||||
Advising Emacs Lisp Functions
|
||||
|
||||
* Simple Advice:: A simple example to explain the basics of advice.
|
||||
* Defining Advice:: Detailed description of @code{defadvice}.
|
||||
* Around-Advice:: Wrapping advice around a function's definition.
|
||||
* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}.
|
||||
* Activation of Advice:: Advice doesn't do anything until you activate it.
|
||||
* Enabling Advice:: You can enable or disable each piece of advice.
|
||||
* Preactivation:: Preactivation is a way of speeding up the
|
||||
loading of compiled advice.
|
||||
* Argument Access in Advice:: How advice can access the function's arguments.
|
||||
* Combined Definition:: How advice is implemented.
|
||||
|
||||
Debugging Lisp Programs
|
||||
|
||||
* Debugger:: A debugger for the Emacs Lisp evaluator.
|
||||
|
|
@ -1561,7 +1547,6 @@ Object Internals
|
|||
@include customize.texi
|
||||
@include loading.texi
|
||||
@include compile.texi
|
||||
@include advice.texi
|
||||
|
||||
@c This includes edebug.texi.
|
||||
@include debugging.texi
|
||||
|
|
|
|||
|
|
@ -21,6 +21,7 @@ define them.
|
|||
* Function Cells:: Accessing or setting the function definition
|
||||
of a symbol.
|
||||
* Closures:: Functions that enclose a lexical environment.
|
||||
* Advising Functions:: Adding to the definition of a function.
|
||||
* Obsolete Functions:: Declaring functions obsolete.
|
||||
* Inline Functions:: Functions that the compiler will expand inline.
|
||||
* Declare Form:: Adding additional information about a function.
|
||||
|
|
@ -1077,12 +1078,10 @@ This function stores @var{definition} in the function cell of
|
|||
this is not checked. The argument @var{symbol} is an ordinary evaluated
|
||||
argument.
|
||||
|
||||
The primary use of this function is as a subroutine by constructs that
|
||||
define or alter functions, like @code{defadvice} (@pxref{Advising
|
||||
Functions}). (If @code{defun} were not a primitive, it could be
|
||||
written as a Lisp macro using @code{fset}.) You can also use it to
|
||||
give a symbol a function definition that is not a list, e.g., a
|
||||
keyboard macro (@pxref{Keyboard Macros}):
|
||||
The primary use of this function is as a subroutine by constructs that define
|
||||
or alter functions, like @code{defun} or @code{advice-add} (@pxref{Advising
|
||||
Functions}). You can also use it to give a symbol a function definition that
|
||||
is not a function, e.g., a keyboard macro (@pxref{Keyboard Macros}):
|
||||
|
||||
@example
|
||||
;; @r{Define a named keyboard macro.}
|
||||
|
|
@ -1133,6 +1132,269 @@ However, the fact that the internal structure of a closure is
|
|||
implementation detail. For this reason, we recommend against directly
|
||||
examining or altering the structure of closure objects.
|
||||
|
||||
@node Advising Functions
|
||||
@section Advising Emacs Lisp Functions
|
||||
@cindex advising functions
|
||||
@cindex piece of advice
|
||||
|
||||
Any variable or object field which holds a function can be modified with the
|
||||
appropriate setter function, such as @code{set-process-filter}, @code{fset}, or
|
||||
@code{setq}, but those can be too blunt, completely throwing away the
|
||||
previous value.
|
||||
|
||||
In order to modify such hooks in a more controlled way, Emacs provides the
|
||||
macros @code{add-function} and @code{remove-function}, which let you modify the
|
||||
existing function value by composing it with another function.
|
||||
|
||||
For example, in order to trace the calls to a process filter, you can use:
|
||||
|
||||
@example
|
||||
(add-function :before (process-filter proc) #'my-tracing-function)
|
||||
@end example
|
||||
|
||||
This will cause the process's output to be passed first to
|
||||
@code{my-tracing-function} and then to the original process filter.
|
||||
When you're done with it, you can revert to the untraced behavior with:
|
||||
|
||||
@example
|
||||
(remove-function (process-filter proc) #'my-tracing-function)
|
||||
@end example
|
||||
|
||||
The argument @code{:before} specifies how the two functions are composed, since
|
||||
there are many different ways to do it. The added function is also called an
|
||||
@emph{advice}.
|
||||
|
||||
The function cell of a symbol can be manipulated similarly, but since it can
|
||||
contain other things than a plain function, you have to use @var{advice-add}
|
||||
and @var{advice-remove} instead, which
|
||||
@c use @var{add-function} and @var{remove-function} internally, but
|
||||
know how to handle cases such as when the function cell holds a macro rather
|
||||
than function, or when the function is autoloaded so the advice's activation
|
||||
needs to be postponed.
|
||||
|
||||
@menu
|
||||
* Advising Primitives:: Primitives to Manipulate Advices
|
||||
* Advising Named Functions:: Advising Named Functions
|
||||
@end menu
|
||||
|
||||
@node Advising Primitives
|
||||
@subsection Primitives to manipulate advice
|
||||
|
||||
@defmac add-function where place function &optional props
|
||||
This macro is the handy way to add the advice @var{function} to the function
|
||||
stored in @var{place} (@pxref{Generalized Variables}).
|
||||
|
||||
@var{where} determines how @var{function} is composed with the
|
||||
existing function. It can be one of the following:
|
||||
|
||||
@table @code
|
||||
@item :before
|
||||
Call @var{function} before the old function. Both functions receive the
|
||||
same arguments, and the return value of the composition is the return value of
|
||||
the old function. More specifically, the composition of the two functions
|
||||
behaves like:
|
||||
@example
|
||||
(lambda (&rest r) (apply @var{function} r) (apply @var{oldfun} r))
|
||||
@end example
|
||||
This is similar to @code{(add-hook @var{hook} @var{function})}, except that it
|
||||
applies to single-function hooks rather than normal hooks.
|
||||
|
||||
@item :after
|
||||
Call @var{function} after the old function. Both functions receive the
|
||||
same arguments, and the return value of the composition is the return value of
|
||||
the old function. More specifically, the composition of the two functions
|
||||
behaves like:
|
||||
@example
|
||||
(lambda (&rest r) (prog1 (apply @var{oldfun} r) (apply @var{function} r)))
|
||||
@end example
|
||||
This is similar to @code{(add-hook @var{hook} @var{function} nil 'append)},
|
||||
except that it applies to single-function hooks rather than normal hooks.
|
||||
|
||||
@item :override
|
||||
This completely replaces the old function with the new one. The old function
|
||||
can of course be recovered if you later call @code{remove-function}.
|
||||
|
||||
@item :around
|
||||
Call @var{function} instead of the old function, but provide the old function
|
||||
as an extra argument to @var{function}. This is the most flexible composition.
|
||||
For example, it lets you call the old function with different arguments, or
|
||||
within a let-binding, or you can sometimes delegate the work to the old
|
||||
function and sometimes override it completely. More specifically, the
|
||||
composition of the two functions behaves like:
|
||||
@example
|
||||
(lambda (&rest r) (apply @var{function} @var{oldfun} r))
|
||||
@end example
|
||||
|
||||
@item :before-while
|
||||
Call @var{function} before the old function and don't call the old
|
||||
function if @var{function} returns @code{nil}. Both functions receive the
|
||||
same arguments, and the return value of the composition is the return value of
|
||||
the old function. More specifically, the composition of the two functions
|
||||
behaves like:
|
||||
@example
|
||||
(lambda (&rest r) (and (apply @var{function} r) (apply @var{oldfun} r)))
|
||||
@end example
|
||||
This is reminiscent of @code{(add-hook @var{hook} @var{function})}, when
|
||||
@var{hook} is run via @code{run-hook-with-args-until-failure}.
|
||||
|
||||
@item :before-until
|
||||
Call @var{function} before the old function and only call the old function if
|
||||
@var{function} returns @code{nil}. More specifically, the composition of the
|
||||
two functions behaves like:
|
||||
@example
|
||||
(lambda (&rest r) (or (apply @var{function} r) (apply @var{oldfun} r)))
|
||||
@end example
|
||||
This is reminiscent of @code{(add-hook @var{hook} @var{function})}, when
|
||||
@var{hook} is run via @code{run-hook-with-args-until-success}.
|
||||
|
||||
@item :after-while
|
||||
Call @var{function} after the old function and only if the old function
|
||||
returned non-@code{nil}. Both functions receive the same arguments, and the
|
||||
return value of the composition is the return value of @var{function}.
|
||||
More specifically, the composition of the two functions behaves like:
|
||||
@example
|
||||
(lambda (&rest r) (and (apply @var{oldfun} r) (apply @var{function} r)))
|
||||
@end example
|
||||
This is reminiscent of @code{(add-hook @var{hook} @var{function} nil 'append)},
|
||||
when @var{hook} is run via @code{run-hook-with-args-until-failure}.
|
||||
|
||||
@item :after-until
|
||||
Call @var{function} after the old function and only if the old function
|
||||
returned @code{nil}. More specifically, the composition of the two functions
|
||||
behaves like:
|
||||
@example
|
||||
(lambda (&rest r) (or (apply @var{oldfun} r) (apply @var{function} r)))
|
||||
@end example
|
||||
This is reminiscent of @code{(add-hook @var{hook} @var{function} nil 'append)},
|
||||
when @var{hook} is run via @code{run-hook-with-args-until-success}.
|
||||
|
||||
@item :filter-args
|
||||
Call @var{function} first and use the result (which should be a list) as the
|
||||
new arguments to pass to the old function. More specifically, the composition
|
||||
of the two functions behaves like:
|
||||
@example
|
||||
(lambda (&rest r) (apply @var{oldfun} (funcall @var{function} r)))
|
||||
@end example
|
||||
|
||||
@item :filter-return
|
||||
Call the old function first and pass the result to @var{function}.
|
||||
More specifically, the composition of the two functions behaves like:
|
||||
@example
|
||||
(lambda (&rest r) (funcall @var{function} (apply @var{oldfun} r)))
|
||||
@end example
|
||||
@end table
|
||||
|
||||
When modifying a variable (whose name will usually end with @code{-function}),
|
||||
you can choose whether @var{function} is used globally or only in the current
|
||||
buffer: if @var{place} is just a symbol, then @var{function} is added to the
|
||||
global value of @var{place}. Whereas if @var{place} is of the form
|
||||
@code{(local @var{symbol})}, where @var{symbol} is an expression which returns
|
||||
the variable name, then @var{function} will only be added in the
|
||||
current buffer.
|
||||
|
||||
Every function added with @code{add-function} can be accompanied by an
|
||||
association list of properties @var{props}. Currently only two of those
|
||||
properties have a special meaning:
|
||||
|
||||
@table @code
|
||||
@item name
|
||||
This gives a name to the advice, which @code{remove-function} can use to
|
||||
identify which function to remove. Typically used when @var{function} is an
|
||||
anonymous function.
|
||||
|
||||
@item depth
|
||||
This specifies where to place the advice, in case several advices are present.
|
||||
By default, the depth is 0. A depth of 100 indicates that this advice should
|
||||
be kept as deep as possible, whereas a depth of -100 indicates that it
|
||||
should stay as the outermost advice. When two advices specify the same depth,
|
||||
the most recently added advice will be outermost.
|
||||
@end table
|
||||
@end defmac
|
||||
|
||||
@defmac remove-function place function
|
||||
This macro removes @var{function} from the function stored in
|
||||
@var{place}. This only works if @var{function} was added to @var{place}
|
||||
using @code{add-function}.
|
||||
|
||||
@var{function} is compared with functions added to @var{place} using
|
||||
@code{equal}, to try and make it work also with lambda expressions. It is
|
||||
additionally compared also with the @code{name} property of the functions added
|
||||
to @var{place}, which can be more reliable than comparing lambda expressions
|
||||
using @code{equal}.
|
||||
@end defmac
|
||||
|
||||
@defun advice-function-member-p advice function-def
|
||||
Return non-@code{nil} if @var{advice} is already in @var{function-def}.
|
||||
Like for @code{remove-function} above, instead of @var{advice} being the actual
|
||||
function, it can also be the @code{name} of the piece of advice.
|
||||
@end defun
|
||||
|
||||
@defun advice-function-mapc f function-def
|
||||
Call the function @var{f} for every advice that was added to
|
||||
@var{function-def}. @var{f} is called with two arguments: the advice function
|
||||
and its properties.
|
||||
@end defun
|
||||
|
||||
@node Advising Named Functions
|
||||
@subsection Advising Named Functions
|
||||
|
||||
A common use of advice is for named functions and macros.
|
||||
Since @var{add-function} does not know how to deal with macros and autoloaded
|
||||
functions, Emacs provides a separate set of functions to manipulate pieces of
|
||||
advice applied to named functions.
|
||||
|
||||
Advice can be useful for altering the behavior of an existing
|
||||
function without having to redefine the whole function. However, it
|
||||
can be a source of bugs, since existing callers to the function may
|
||||
assume the old behavior, and work incorrectly when the behavior is
|
||||
changed by advice. Advice can also cause confusion in debugging, if
|
||||
the person doing the debugging does not notice or remember that the
|
||||
function has been modified by advice.
|
||||
|
||||
For these reasons, advice should be reserved for the cases where you
|
||||
cannot modify a function's behavior in any other way. If it is
|
||||
possible to do the same thing via a hook, that is preferable
|
||||
(@pxref{Hooks}). If you simply want to change what a particular key
|
||||
does, it may be better to write a new command, and remap the old
|
||||
command's key bindings to the new one (@pxref{Remapping Commands}).
|
||||
In particular, Emacs's own source files should not put advice on
|
||||
functions in Emacs. (There are currently a few exceptions to this
|
||||
convention, but we aim to correct them.)
|
||||
|
||||
Macros can also be advised, in much the same way as functions.
|
||||
However, special forms (@pxref{Special Forms}) cannot be advised.
|
||||
|
||||
It is possible to advise a primitive (@pxref{What Is a Function}),
|
||||
but one should typically @emph{not} do so, for two reasons. Firstly,
|
||||
some primitives are used by the advice mechanism, and advising them
|
||||
could cause an infinite recursion. Secondly, many primitives are
|
||||
called directly from C, and such calls ignore advice; hence, one ends
|
||||
up in a confusing situation where some calls (occurring from Lisp
|
||||
code) obey the advice and other calls (from C code) do not.
|
||||
|
||||
@defun advice-add symbol where function &optional props
|
||||
Add the advice @var{function} to the named function @var{symbol}.
|
||||
@var{where} and @var{props} have the same meaning as for @code{add-function}
|
||||
(@pxref{Advising Primitives}).
|
||||
@end defun
|
||||
|
||||
@defun advice-remove symbol function
|
||||
Remove the advice @var{function} from the named function @var{symbol}.
|
||||
@var{function} can also be the @code{name} of an advice.
|
||||
@end defun
|
||||
|
||||
@defun advice-member-p function symbol
|
||||
Return non-@code{nil} if the advice @var{function} is already in the named
|
||||
function @var{symbol}. @var{function} can also be the @code{name} of
|
||||
an advice.
|
||||
@end defun
|
||||
|
||||
@defun advice-mapc function symbol
|
||||
Call @var{function} for every advice that was added to the named function
|
||||
@var{symbol}. @var{function} is called with two arguments: the advice function
|
||||
and its properties.
|
||||
@end defun
|
||||
|
||||
@node Obsolete Functions
|
||||
@section Declaring Functions Obsolete
|
||||
@cindex obsolete functions
|
||||
|
|
|
|||
|
|
@ -49,7 +49,6 @@ texinputdir = $(srcdir)\..\..\nt\envadd.bat \
|
|||
srcs = \
|
||||
$(emacsdir)/emacsver.texi \
|
||||
$(srcdir)/abbrevs.texi \
|
||||
$(srcdir)/advice.texi \
|
||||
$(srcdir)/anti.texi \
|
||||
$(srcdir)/backups.texi \
|
||||
$(srcdir)/buffers.texi \
|
||||
|
|
|
|||
|
|
@ -69,11 +69,13 @@ functions are called with arguments, or their return values are used
|
|||
in some way. The hook's documentation says how the functions are
|
||||
called. You can use @code{add-hook} to add a function to an abnormal
|
||||
hook, but you must write the function to follow the hook's calling
|
||||
convention.
|
||||
convention. By convention, abnormal hook names end in @samp{-functions}.
|
||||
|
||||
By convention, abnormal hook names end in @samp{-functions}. If the
|
||||
variable's name ends in @samp{-function}, then its value is just a single
|
||||
function, not a list of functions.
|
||||
@cindex single-function hook
|
||||
If the variable's name ends in @samp{-function}, then its value is
|
||||
just a single function, not a list of functions. @code{add-hook} cannot be
|
||||
used to modify such a @emph{single function hook}, and you have to use
|
||||
@code{add-function} instead (@pxref{Advising Functions}).
|
||||
|
||||
@menu
|
||||
* Running Hooks:: How to run a hook.
|
||||
|
|
@ -129,47 +131,6 @@ non-@code{nil} value, it returns that value; otherwise it returns
|
|||
@code{nil}.
|
||||
@end defun
|
||||
|
||||
@defmac with-wrapper-hook hook args &rest body
|
||||
This macro runs the abnormal hook @code{hook} as a series of nested
|
||||
``wrapper functions'' around the @var{body} forms. The effect is
|
||||
similar to nested @code{around} advices (@pxref{Around-Advice}).
|
||||
|
||||
Each hook function should accept an argument list consisting of a function
|
||||
@var{fun}, followed by the additional arguments listed in @var{args}.
|
||||
The first hook function is passed a function @var{fun} that, if it is
|
||||
called with arguments @var{args}, performs @var{body} (i.e., the default
|
||||
operation). The @var{fun} passed to each successive hook function is
|
||||
constructed from all the preceding hook functions (and @var{body}); if
|
||||
this @var{fun} is called with arguments @var{args}, it does what the
|
||||
@code{with-wrapper-hook} call would if the preceding hook functions were
|
||||
the only ones in @var{hook}.
|
||||
|
||||
Each hook function may call its @var{fun} argument as many times as it
|
||||
wishes, including never. In that case, such a hook function acts to
|
||||
replace the default definition altogether, and any preceding hook
|
||||
functions. Of course, a subsequent hook function may do the same thing.
|
||||
|
||||
Each hook function definition is used to construct the @var{fun} passed
|
||||
to the next hook function in @var{hook}, if any. The last or
|
||||
``outermost'' @var{fun} is called once to produce the overall effect.
|
||||
|
||||
When might you want to use a wrapper hook? The function
|
||||
@code{filter-buffer-substring} illustrates a common case. There is a
|
||||
basic functionality, performed by @var{body}---in this case, to extract
|
||||
a buffer-substring. Then any number of hook functions can act in
|
||||
sequence to modify that string, before returning the final result.
|
||||
A wrapper-hook also allows for a hook function to completely replace the
|
||||
default definition (by not calling @var{fun}).
|
||||
@end defmac
|
||||
|
||||
@defun run-hook-wrapped hook wrap-function &rest args
|
||||
This function is similar to @code{run-hook-with-args-until-success}.
|
||||
Like that function, it runs the functions on the abnormal hook
|
||||
@code{hook}, stopping at the first one that returns non-@code{nil}.
|
||||
Instead of calling the hook functions directly, though, it actually
|
||||
calls @code{wrap-function} with arguments @code{fun} and @code{args}.
|
||||
@end defun
|
||||
|
||||
@node Setting Hooks
|
||||
@subsection Setting Hooks
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,7 @@
|
|||
2014-01-10 Stefan Monnier <monnier@iro.umontreal.ca>
|
||||
|
||||
* cl.texi (Function Bindings): Fix incorrect description of cl-let.
|
||||
|
||||
2014-01-09 Rüdiger Sonderfeld <ruediger@c-plusplus.de>
|
||||
|
||||
* Makefile.in: Add eww.texi.
|
||||
|
|
@ -18,8 +22,8 @@
|
|||
(Advanced configuration)
|
||||
(Header arguments in Org mode properties): Spelling fixes.
|
||||
(Special blocks): Add #+BEGIN_ABSTRACT as another example.
|
||||
(@LaTeX{} specific attributes): New index entries. Use
|
||||
#+BEGIN_ABSTRACT in the example.
|
||||
(@LaTeX{} specific attributes): New index entries.
|
||||
Use #+BEGIN_ABSTRACT in the example.
|
||||
|
||||
2013-01-07 Nicolas Goaziou <n.goaziou@gmail.com>
|
||||
|
||||
|
|
@ -80,7 +84,7 @@
|
|||
|
||||
2014-01-02 Aidan Gauland <aidalgol@amuri.net>
|
||||
|
||||
* eshell.texi (Command Basics): Removed `Command basics' chapter.
|
||||
* eshell.texi (Command Basics): Remove `Command basics' chapter.
|
||||
|
||||
2014-01-02 Aidan Gauland <aidalgol@amuri.net>
|
||||
|
||||
|
|
@ -200,8 +204,8 @@
|
|||
* org.texi (Orgstruct mode): Fix suggested setting of
|
||||
`orgstruct-heading-prefix-regexp'.
|
||||
|
||||
* org.texi (Export settings): Document
|
||||
`org-export-allow-bind-keywords'.
|
||||
* org.texi (Export settings):
|
||||
Document `org-export-allow-bind-keywords'.
|
||||
|
||||
* org.texi (History and Acknowledgments): Small rephrasing.
|
||||
|
||||
|
|
@ -209,8 +213,8 @@
|
|||
in a year datetree.
|
||||
|
||||
* org.texi (Beamer export, @LaTeX{} and PDF export)
|
||||
(Header and sectioning, @LaTeX{} specific attributes): Enhance
|
||||
style.
|
||||
(Header and sectioning, @LaTeX{} specific attributes):
|
||||
Enhance style.
|
||||
|
||||
* org.texi (Agenda commands): Add a footnote about dragging agenda
|
||||
lines: it does not persist and it does not change the .org files.
|
||||
|
|
@ -229,15 +233,15 @@
|
|||
|
||||
* org.texi (Other built-in back-ends): New section.
|
||||
|
||||
* org.texi (Editing source code): Document
|
||||
`org-edit-src-auto-save-idle-delay' and
|
||||
* org.texi (Editing source code):
|
||||
Document `org-edit-src-auto-save-idle-delay' and
|
||||
`org-edit-src-turn-on-auto-save'.
|
||||
|
||||
* org.texi (External links): Document contributed link types
|
||||
separately.
|
||||
|
||||
* org.texi (Closing items): Document
|
||||
`org-closed-keep-when-no-todo'.
|
||||
* org.texi (Closing items):
|
||||
Document `org-closed-keep-when-no-todo'.
|
||||
|
||||
* org.texi (Export back-ends): Rename from "Export formats".
|
||||
(The Export Dispatcher): Remove reference to
|
||||
|
|
@ -273,8 +277,8 @@
|
|||
(Agenda commands): Move details about filtering commands to
|
||||
the new section, only include a summary here.
|
||||
(Customizing tables in ODT export)
|
||||
(System-wide header arguments, Conflicts, Dynamic blocks): Use
|
||||
spaces for indentation.
|
||||
(System-wide header arguments, Conflicts, Dynamic blocks):
|
||||
Use spaces for indentation.
|
||||
|
||||
* org.texi (Emphasis and monospace): Mention `org-emphasis-alist'.
|
||||
|
||||
|
|
@ -331,8 +335,8 @@
|
|||
(In-buffer settings): Update to reflect changes from the new
|
||||
export engine.
|
||||
|
||||
* org.texi (Matching tags and properties): More examples. Explain
|
||||
group tags expansion as regular expressions.
|
||||
* org.texi (Matching tags and properties): More examples.
|
||||
Explain group tags expansion as regular expressions.
|
||||
|
||||
* org.texi (Tag groups): New section.
|
||||
|
||||
|
|
@ -357,8 +361,8 @@
|
|||
|
||||
* org.texi (Org syntax): New section.
|
||||
|
||||
* org.texi (Orgstruct mode): Document
|
||||
`orgstruct-heading-prefix-regexp'.
|
||||
* org.texi (Orgstruct mode):
|
||||
Document `orgstruct-heading-prefix-regexp'.
|
||||
|
||||
* org.texi (Speeding up your agendas): New section.
|
||||
|
||||
|
|
@ -382,8 +386,8 @@
|
|||
* org.texi: Update the list contributions.
|
||||
|
||||
* org.texi (Agenda commands): Exporting the agenda to an .org file
|
||||
will not copy the subtrees and the inherited tags. Document
|
||||
`org-agenda-filter-by-regexp'.
|
||||
will not copy the subtrees and the inherited tags.
|
||||
Document `org-agenda-filter-by-regexp'.
|
||||
|
||||
* org.texi (Publishing action, Complex example): Fix names of
|
||||
publishing functions.
|
||||
|
|
@ -397,8 +401,8 @@
|
|||
* org.texi (Capture): Mention that org-remember.el is not
|
||||
supported anymore.
|
||||
|
||||
* org.texi (Top, Exporting, Beamer class export): Delete
|
||||
references to the TaskJuggler export.
|
||||
* org.texi (Top, Exporting, Beamer class export):
|
||||
Delete references to the TaskJuggler export.
|
||||
(History and Acknowledgments): Mention that the TaskJuggler has
|
||||
been rewritten by Nicolas and now lives in the contrib/ directory
|
||||
of Org's distribution. Mention that Jambunathan rewrote the HTML
|
||||
|
|
@ -415,16 +419,16 @@
|
|||
(@LaTeX{} and PDF export, Header and sectioning)
|
||||
(Publishing options): Fix LaTeX options names.
|
||||
|
||||
* org.texi (Export options, CSS support, In-buffer settings): Fix
|
||||
references to HTML_LINK_* and HTML_STYLE keywords.
|
||||
* org.texi (Export options, CSS support, In-buffer settings):
|
||||
Fix references to HTML_LINK_* and HTML_STYLE keywords.
|
||||
|
||||
* org.texi (Export options, In-buffer settings): Fix references to
|
||||
#+SELECT_TAGS and #+EXCLUDE_TAGS and remove reference to #+XSLT.
|
||||
|
||||
* org.texi (Top, Markup, Initial text, Images and tables)
|
||||
(@LaTeX{} fragments, @LaTeX{} fragments, Exporting)
|
||||
(Export options, JavaScript support, Beamer class export): Remove
|
||||
references to the DocBook export, which has been deleted.
|
||||
(Export options, JavaScript support, Beamer class export):
|
||||
Remove references to the DocBook export, which has been deleted.
|
||||
(History and Acknowledgments): Mention that DocBook has been
|
||||
deleted, suggest to use the Texinfo exporter instead, then to
|
||||
convert the .texi to DocBook with makeinfo.
|
||||
|
|
@ -433,8 +437,8 @@
|
|||
* org.texi (Deadlines and scheduling): Add a variable to the
|
||||
index. Add documentation about delays for scheduled tasks.
|
||||
|
||||
* org.texi (Emphasis and monospace): Mention
|
||||
`org-fontify-emphasized-text' and
|
||||
* org.texi (Emphasis and monospace):
|
||||
Mention `org-fontify-emphasized-text' and
|
||||
`org-emphasis-regexp-components'.
|
||||
|
||||
* org.texi (References): Small enhancement.
|
||||
|
|
@ -491,7 +495,7 @@
|
|||
|
||||
* org.texi (Extracting source code): Mention the prefix argument
|
||||
to org-babel-tangle.
|
||||
(noweb): Removed erroneous negative.
|
||||
(noweb): Remove erroneous negative.
|
||||
(Specific header arguments): Document new header arguments.
|
||||
Documentation for new tangle-mode header argument.
|
||||
(Top): Documentation for new tangle-mode header argument.
|
||||
|
|
@ -595,8 +599,8 @@
|
|||
* org.texi (Header and sectioning): Add a footnote about the
|
||||
different between LATEX_HEADER_EXTRA and LATEX_HEADER.
|
||||
|
||||
* org.texi (The Export Dispatcher): Document
|
||||
`org-export-in-background'.
|
||||
* org.texi (The Export Dispatcher):
|
||||
Document `org-export-in-background'.
|
||||
|
||||
* org.texi (Footnotes): Export back-ends do not use
|
||||
`org-footnote-normalize' anymore.
|
||||
|
|
@ -618,19 +622,19 @@
|
|||
* org.texi (Include files): Remove reference to :prefix1
|
||||
and :prefix. Give more details for :minlevel.
|
||||
|
||||
* org.texi (Macro replacement): Fix macro name. Update
|
||||
documentation about possible locations and escaping mechanism.
|
||||
* org.texi (Macro replacement): Fix macro name.
|
||||
Update documentation about possible locations and escaping mechanism.
|
||||
|
||||
* org.texi (Table of contents): Update documentation. Document
|
||||
lists of listings and lists of tables. Add documentation for
|
||||
* org.texi (Table of contents): Update documentation.
|
||||
Document lists of listings and lists of tables. Add documentation for
|
||||
optional title and #+TOC: keyword.
|
||||
|
||||
2013-11-12 Rick Frankel <rick@rickster.com>
|
||||
|
||||
* org.texi (results): Add Format section, broken out of Type
|
||||
section to match code.
|
||||
(hlines, colnames): Remove incorrect Emacs Lisp exception. Note
|
||||
that the actual default handling (at least for python and
|
||||
(hlines, colnames): Remove incorrect Emacs Lisp exception.
|
||||
Note that the actual default handling (at least for python and
|
||||
emacs-lisp) does not seem to match the description.
|
||||
|
||||
2013-11-12 Sacha Chua <sacha@sachachua.com> (tiny change)
|
||||
|
|
@ -640,8 +644,8 @@
|
|||
|
||||
2013-11-12 Yasushi Shoji <yashi@atmark-techno.com>
|
||||
|
||||
* org.texi (Resolving idle time): Document
|
||||
`org-clock-x11idle-program-name'.
|
||||
* org.texi (Resolving idle time):
|
||||
Document `org-clock-x11idle-program-name'.
|
||||
|
||||
2013-10-24 Michael Albinus <michael.albinus@gmx.de>
|
||||
|
||||
|
|
@ -882,8 +886,8 @@
|
|||
|
||||
2013-07-29 Michael Albinus <michael.albinus@gmx.de>
|
||||
|
||||
* tramp.texi (Frequently Asked Questions): Mention
|
||||
`tramp-use-ssh-controlmaster-options'.
|
||||
* tramp.texi (Frequently Asked Questions):
|
||||
Mention `tramp-use-ssh-controlmaster-options'.
|
||||
|
||||
2013-07-26 Tassilo Horn <tsdh@gnu.org>
|
||||
|
||||
|
|
@ -927,8 +931,8 @@
|
|||
2013-07-08 Tassilo Horn <tsdh@gnu.org>
|
||||
|
||||
* gnus.texi (lines): Correct description of
|
||||
`gnus-registry-track-extra's default value. Mention
|
||||
`gnus-registry-remove-extra-data'.
|
||||
`gnus-registry-track-extra's default value.
|
||||
Mention `gnus-registry-remove-extra-data'.
|
||||
|
||||
2013-07-06 Lars Ingebrigtsen <larsi@gnus.org>
|
||||
|
||||
|
|
|
|||
|
|
@ -1282,13 +1282,8 @@ cells of symbols rather than on the value cells. Each @var{binding}
|
|||
must be a list of the form @samp{(@var{name} @var{arglist}
|
||||
@var{forms}@dots{})}, which defines a function exactly as if
|
||||
it were a @code{cl-defun} form. The function @var{name} is defined
|
||||
accordingly for the duration of the body of the @code{cl-flet}; then
|
||||
the old function definition, or lack thereof, is restored.
|
||||
|
||||
You can use @code{cl-flet} to disable or modify the behavior of
|
||||
functions (including Emacs primitives) in a temporary, localized fashion.
|
||||
(Compare this with the idea of advising functions.
|
||||
@xref{Advising Functions,,,elisp,GNU Emacs Lisp Reference Manual}.)
|
||||
accordingly but only within the body of the @code{cl-flet}, hiding any external
|
||||
definition if applicable.
|
||||
|
||||
The bindings are lexical in scope. This means that all references to
|
||||
the named functions must appear physically within the body of the
|
||||
|
|
|
|||
1
etc/NEWS
1
etc/NEWS
|
|
@ -905,6 +905,7 @@ It is only available if Emacs is compiled with libxml2 support.
|
|||
symbol_words as a single word, similar to what `subword-mode' does and
|
||||
using the same internal functions.
|
||||
|
||||
+++
|
||||
** New package nadvice.el offers lighter-weight advice facilities.
|
||||
It is layered as:
|
||||
- add-function/remove-function which can be used to add/remove code on any
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue