@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004,
-@c 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1998-1999, 2001-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/advising
@node Advising Functions, Debugging, Byte Compilation, Top
@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
+@var{function} in class @var{class}. The argument @var{advice} has
this form:
@example
(@var{name} @var{protected} @var{enabled} @var{definition})
@end example
-Here @var{protected} and @var{enabled} are flags, and @var{definition}
-is the expression that says what the advice should do. If @var{enabled}
-is @code{nil}, this piece of advice is initially disabled
-(@pxref{Enabling Advice}).
+@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
-If @var{function} 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.
+@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
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 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.
+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}.
@section Advising Primitives
@cindex advising primitives
- Advising a primitive function (also called a ``subr'') is risky.
+ Advising a primitive function (@pxref{What Is a Function}) is risky.
Some primitive functions are used by the advice mechanism; advising
them could cause an infinite recursion. Also, many primitive
functions are called directly from C code. Calls to the primitive
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.
-
-@ignore
- arch-tag: 80c135c2-f1c3-4f8d-aa85-f8d8770d307f
-@end ignore