@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Functions
define them.
@menu
-* What Is a Function:: Lisp functions vs. primitives; terminology.
-* Lambda Expressions:: How functions are expressed as Lisp objects.
-* Function Names:: A symbol can serve as the name of a function.
-* Defining Functions:: Lisp expressions for defining functions.
-* Calling Functions:: How to use an existing function.
-* Mapping Functions:: Applying a function to each element of a list, etc.
-* Anonymous Functions:: Lambda expressions are functions with no names.
-* Function Cells:: Accessing or setting the function definition
+* What Is a Function:: Lisp functions vs. primitives; terminology.
+* Lambda Expressions:: How functions are expressed as Lisp objects.
+* Function Names:: A symbol can serve as the name of a function.
+* Defining Functions:: Lisp expressions for defining functions.
+* Calling Functions:: How to use an existing function.
+* Mapping Functions:: Applying a function to each element of a list, etc.
+* Anonymous Functions:: Lambda expressions are functions with no names.
+* Function Cells:: Accessing or setting the function definition
of a symbol.
-* Closures:: Functions that enclose a lexical environment.
-* Obsolete Functions:: Declaring functions obsolete.
-* Inline Functions:: Functions that the compiler will expand inline.
-* Declare Form:: Adding additional information about a function.
-* Declaring Functions:: Telling the compiler that a function is defined.
-* Function Safety:: Determining whether a function is safe to call.
-* Related Topics:: Cross-references to specific Lisp primitives
+* 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.
+* Declaring Functions:: Telling the compiler that a function is defined.
+* Function Safety:: Determining whether a function is safe to call.
+* Related Topics:: Cross-references to specific Lisp primitives
that have a special bearing on how functions work.
@end menu
@end example
@noindent
-In Emacs Lisp, such a list is valid as an expression---it evaluates to
-itself. But its main use is not to be evaluated as an expression, but
-to be called as a function.
+In Emacs Lisp, such a list is a valid expression which evaluates to
+a function object.
A lambda expression, by itself, has no name; it is an @dfn{anonymous
function}. Although lambda expressions can be used this way
the components of a lambda expression and what they do.
@menu
-* Lambda Components:: The parts of a lambda expression.
-* Simple Lambda:: A simple example.
-* Argument List:: Details and special features of argument lists.
-* Function Documentation:: How to put documentation in a function.
+* Lambda Components:: The parts of a lambda expression.
+* Simple Lambda:: A simple example.
+* Argument List:: Details and special features of argument lists.
+* Function Documentation:: How to put documentation in a function.
@end menu
@node Lambda Components
@end defmac
@cindex function aliases
+@cindex alias, for functions
@defun defalias name definition &optional doc
@anchor{Definition of defalias}
This function defines the symbol @var{name} as a function, with
of @var{name}. Otherwise, any documentation provided by
@var{definition} is used.
+@cindex defalias-fset-function property
+Internally, @code{defalias} normally uses @code{fset} to set the definition.
+If @var{name} has a @code{defalias-fset-function} property, however,
+the associated value is used as a function to call in place of @code{fset}.
+
The proper place to use @code{defalias} is where a specific function
name is being defined---especially where that name appears explicitly in
the source file being loaded. This is because @code{defalias} records
compiled. This would not happen if, say, you had constructed the
anonymous function by quoting it as a list:
+@c Do not unquote this lambda!
@example
@group
(defun double-property (symbol prop)
- (change-property symbol prop (lambda (x) (* 2 x))))
+ (change-property symbol prop '(lambda (x) (* 2 x))))
@end group
@end example
@defun symbol-function symbol
@kindex void-function
-This returns the object in the function cell of @var{symbol}. If the
-symbol's function cell is void, a @code{void-function} error is
-signaled.
+This returns the object in the function cell of @var{symbol}. It does
+not check that the returned object is a legitimate function.
-This function does not check that the returned object is a legitimate
-function.
+If the function cell is void, the return value is @code{nil}. To
+distinguish between a function cell that is void and one set to
+@code{nil}, use @code{fboundp} (see below).
@example
@group
@end defun
@cindex void function cell
- If you have never given a symbol any function definition, we say that
-that symbol's function cell is @dfn{void}. In other words, the function
-cell does not have any Lisp object in it. If you try to call such a symbol
-as a function, it signals a @code{void-function} error.
+ If you have never given a symbol any function definition, we say
+that that symbol's function cell is @dfn{void}. In other words, the
+function cell does not have any Lisp object in it. If you try to call
+the symbol as a function, Emacs signals a @code{void-function} error.
Note that void is not the same as @code{nil} or the symbol
@code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
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.}
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
+
+When you need to modify a function defined in another library, or when you need
+to modify a hook like @code{@var{foo}-function}, a process filter, or basically
+any variable or object field which holds a function value, you can use the
+appropriate setter function, such as @code{fset} or @code{defun} for named
+functions, @code{setq} for hook variables, or @code{set-process-filter} for
+process filters, but those are often too blunt, completely throwing away the
+previous value.
+
+ The @dfn{advice} feature lets you add to the existing definition of
+a function, by @dfn{advising the function}. This is a cleaner method
+than redefining the whole function.
+
+Emacs's advice system provides two sets of primitives for that: the core set,
+for function values held in variables and object fields (with the corresponding
+primitives being @code{add-function} and @code{remove-function}) and another
+set layered on top of it for named functions (with the main primitives being
+@code{advice-add} and @code{advice-remove}).
+
+For example, in order to trace the calls to the process filter of a process
+@var{proc}, you could use:
+
+@example
+(defun my-tracing-function (proc string)
+ (message "Proc %S received %S" proc string))
+
+(add-function :before (process-filter @var{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 @var{proc}) #'my-tracing-function)
+@end example
+
+Similarly, if you want to trace the execution of the function named
+@code{display-buffer}, you could use:
+
+@example
+(defun his-tracing-function (orig-fun &rest args)
+ (message "display-buffer called with args %S" args)
+ (let ((res (apply orig-fun args)))
+ (message "display-buffer returned %S" res)
+ res))
+
+(advice-add 'display-buffer :around #'his-tracing-function)
+@end example
+
+and when you're tired of seeing this output, you can revert to the untraced
+behavior with:
+
+@example
+(advice-remove 'display-buffer #'his-tracing-function)
+@end example
+
+The arguments @code{:before} and @code{:above} used in the above examples
+specify how the two functions are composed, since there are many different
+ways to do it. The added function is also called an @emph{advice}.
+
+@menu
+* Core Advising Primitives:: Primitives to Manipulate Advices
+* Advising Named Functions:: Advising Named Functions
+* Porting old advices:: Adapting code using the old defadvice
+@end menu
+
+@node Core Advising Primitives
+@subsection Primitives to manipulate advices
+
+@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}).
+
+If @var{function} is not interactive, then the combined function will inherit
+the interactive spec, if any, of the original function. Else, the combined
+function will be interactive and will use the interactive spec of
+@var{function}. One exception: if the interactive spec of @var{function}
+is a function (rather than an expression or a string), then the interactive
+spec of the combined function will be a call to that function with as sole
+argument the interactive spec of the original function. To interpret the spec
+received as argument, use @code{advice-eval-interactive-spec}.
+
+@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
+
+@defun advice-eval-interactive-spec spec
+Evaluate the interactive @var{spec} just like an interactive call to a function
+with such a spec would, and then return the corresponding list of arguments
+that was built. E.g. @code{(advice-eval-interactive-spec "r\nP")} will
+return a list of three elements, containing the boundaries of the region and
+the current prefix argument.
+@end defun
+
+@node Advising Named Functions
+@subsection Advising Named Functions
+
+A common use of advice is for named functions and macros.
+You could just use @code{add-function} as in:
+
+@example
+(add-function :around (symbol-function '@var{fun}) #'his-tracing-function)
+@end example
+
+ But you should use @code{advice-add} and @code{advice-remove} for that
+instead. This separate set of functions to manipulate pieces of advice applied
+to named functions, offers the following extra features compared to
+@code{add-function}: they know how to deal with macros and autoloaded
+functions, they let @code{describe-function} preserve the original docstring as
+well as document the added advice, and they let you add and remove advices
+before a function is even defined.
+
+ @code{advice-add} can be useful for altering the behavior of existing calls
+to 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 Porting old advices
+@subsection Adapting code using the old defadvice
+
+A lot of code uses the old @code{defadvice} mechanism, which is largely made
+obsolete by the new @code{advice-add}, whose implementation and semantics is
+significantly simpler.
+
+An old advice such as:
+
+@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
+
+could be translated in the new advice mechanism into a plain function:
+
+@example
+(defun previous-line--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
+
+Obviously, this does not actually modify @code{previous-line}. For that the
+old advice needed:
+@example
+(ad-activate 'previous-line)
+@end example
+whereas the new advice mechanism needs:
+@example
+(advice-add 'previous-line :before #'previous-line--next-line-at-end)
+@end example
+
+Note that @code{ad-activate} had a global effect: it activated all pieces of
+advice enabled for that specified function. If you wanted to only activate or
+deactivate a particular advice, you needed to @emph{enable} or @emph{disable}
+that advice with @code{ad-enable-advice} and @code{ad-disable-advice}.
+The new mechanism does away with this distinction.
+
+An around advice such as:
+
+@example
+(defadvice foo (around foo-around)
+ "Ignore case in `foo'."
+ (let ((case-fold-search t))
+ ad-do-it))
+(ad-activate 'foo)
+@end example
+
+could translate into:
+
+@example
+(defun foo--foo-around (orig-fun &rest args)
+ "Ignore case in `foo'."
+ (let ((case-fold-search t))
+ (apply orig-fun args)))
+(advice-add 'foo :around #'foo--foo-around)
+@end example
+
+Regarding the advice's @emph{class}, note that the new @code{:before} is not
+quite equivalent to the old @code{before}, because in the old advice you could
+modify the function's arguments (e.g., with @code{ad-set-arg}), and that would
+affect the argument values seen by the original function, whereas in the new
+@code{:before}, modifying an argument via @code{setq} in the advice has no
+effect on the arguments seen by the original function.
+When porting a @code{before} advice which relied on this behavior, you'll need
+to turn it into a new @code{:around} or @code{:filter-args} advice instead.
+
+Similarly an old @code{after} advice could modify the returned value by
+changing @code{ad-return-value}, whereas a new @code{:after} advice cannot, so
+when porting such an old @code{after} advice, you'll need to turn it into a new
+@code{:around} or @code{:filter-return} advice instead.
+
@node Obsolete Functions
@section Declaring Functions Obsolete
+@cindex obsolete functions
You can mark a named function as @dfn{obsolete}, meaning that it may
be removed at some point in the future. This causes Emacs to warn
This acts like a call to @code{set-advertised-calling-convention}
(@pxref{Obsolete Functions}); @var{signature} specifies the correct
argument list for calling the function or macro, and @var{when} should
-be a string indicating when the variable was first made obsolete.
+be a string indicating when the old argument list was first made obsolete.
@item (debug @var{edebug-form-spec})
This is valid for macros only. When stepping through the macro with
Edebug, use @var{edebug-form-spec}. @xref{Instrumenting Macro Calls}.
@item (doc-string @var{n})
-Use element number @var{n}, if any, as the documentation string.
+This is used when defining a function or macro which itself will be used to
+define entities like functions, macros, or variables. It indicates that
+the @var{n}th argument, if any, should be considered
+as a documentation string.
@item (indent @var{indent-spec})
Indent calls to this function or macro according to @var{indent-spec}.
which case the warning message gives no extra details). @var{when}
should be a string indicating when the function or macro was first
made obsolete.
+
+@item (compiler-macro @var{expander})
+This can only be used for functions, and tells the compiler to use
+@var{expander} as an optimization function. When encountering a call to the
+function, of the form @code{(@var{function} @var{args}@dots{})}, the macro
+expander will call @var{expander} with that form as well as with
+@var{args}@dots{}, and @var{expander} can either return a new expression to use
+instead of the function call, or it can return just the form unchanged,
+to indicate that the function call should be left alone. @var{expander} can
+be a symbol, or it can be a form @code{(lambda (@var{arg}) @var{body})} in
+which case @var{arg} will hold the original function call expression, and the
+(unevaluated) arguments to the function can be accessed using the function's
+formal arguments.
+
+@item (gv-expander @var{expander})
+Declare @var{expander} to be the function to handle calls to the macro (or
+function) as a generalized variable, similarly to @code{gv-define-expander}.
+@var{expander} can be a symbol or it can be of the form @code{(lambda
+(@var{arg}) @var{body})} in which case that function will additionally have
+access to the macro (or function)'s arguments.
+
+@item (gv-setter @var{setter})
+Declare @var{setter} to be the function to handle calls to the macro (or
+function) as a generalized variable. @var{setter} can be a symbol in which
+case it will be passed to @code{gv-define-simple-setter}, or it can be of the
+form @code{(lambda (@var{arg}) @var{body})} in which case that function will
+additionally have access to the macro (or function)'s arguments and it will
+passed to @code{gv-define-setter}.
+
@end table
+
@end defmac
@node Declaring Functions
HCoop / bpt / emacs.git / blobdiff