@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/functions
-@node Functions, Macros, Variables, Top
+@node Functions
@chapter Functions
A Lisp program is composed mainly of Lisp functions. This chapter
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.
-* 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
In most computer languages, every function has a name. But in Lisp,
a function in the strictest sense has no name: it is an object which
-can @emph{optionally} be associated with a symbol (e.g.@: @code{car})
+can @emph{optionally} be associated with a symbol (e.g., @code{car})
that serves as the function name. @xref{Function Names}. When a
function has been given a name, we usually also refer to that symbol
-as a ``function'' (e.g.@: we refer to ``the function @code{car}'').
+as a ``function'' (e.g., we refer to ``the function @code{car}'').
In this manual, the distinction between a function name and the
function object itself is usually unimportant, but we will take note
wherever it is relevant.
@table @dfn
@item lambda expression
-A function (in the strict sense, i.e.@: a function object) which is
+A function (in the strict sense, i.e., a function object) which is
written in Lisp. These are described in the following section.
@ifnottex
@xref{Lambda Expressions}.
@cindex primitive
@cindex subr
@cindex built-in function
-A function which is callable from Lisp but is actually written in C.
+A function which is callable from Lisp but is actually written in C@.
Primitives are also called @dfn{built-in functions}, or @dfn{subrs}.
Examples include functions like @code{car} and @code{append}. In
addition, all special forms (see below) are also considered
primitives.
Usually, a function is implemented as a primitive because it is a
-fundamental part of Lisp (e.g.@: @code{car}), or because it provides a
+fundamental part of Lisp (e.g., @code{car}), or because it provides a
low-level interface to operating system services, or because it needs
to run fast. Unlike functions defined in Lisp, primitives can be
modified or added only by changing the C sources and recompiling
@defun functionp object
This function returns @code{t} if @var{object} is any kind of
-function, i.e.@: can be passed to @code{funcall}. Note that
+function, i.e., can be passed to @code{funcall}. Note that
@code{functionp} returns @code{t} for symbols that are function names,
and returns @code{nil} for special forms.
@end defun
@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
A symbol can serve as the name of a function. This happens when the
symbol's @dfn{function cell} (@pxref{Symbol Components}) contains a
-function object (e.g.@: a lambda expression). Then the symbol itself
+function object (e.g., a lambda expression). Then the symbol itself
becomes a valid, callable function, equivalent to the function object
in its function cell.
We usually give a name to a function when it is first created. This
is called @dfn{defining a function}, and it is done with the
-@code{defun} special form.
+@code{defun} macro.
-@defspec defun name argument-list body-forms...
+@defmac defun name args [doc] [declare] [interactive] body@dots{}
@code{defun} is the usual way to define new Lisp functions. It
-defines the symbol @var{name} as a function that looks like this:
+defines the symbol @var{name} as a function with argument list
+@var{args} and body forms given by @var{body}. Neither @var{name} nor
+@var{args} should be quoted.
-@example
-(lambda @var{argument-list} . @var{body-forms})
-@end example
-
-@code{defun} stores this lambda expression in the function cell of
-@var{name}. It returns the value @var{name}, but usually we ignore this
-value.
+@var{doc}, if present, should be a string specifying the function's
+documentation string (@pxref{Function Documentation}). @var{declare},
+if present, should be a @code{declare} form specifying function
+metadata (@pxref{Declare Form}). @var{interactive}, if present,
+should be an @code{interactive} form specifying how the function is to
+be called interactively (@pxref{Interactive Call}).
-As described previously, @var{argument-list} is a list of argument
-names and may include the keywords @code{&optional} and @code{&rest}.
-Also, the first two of the @var{body-forms} may be a documentation
-string and an interactive declaration. @xref{Lambda Components}.
+The return value of @code{defun} is undefined.
Here are some examples:
@example
@group
(defun foo () 5)
- @result{} foo
-@end group
-@group
(foo)
@result{} 5
@end group
@group
(defun bar (a &optional b &rest c)
(list a b c))
- @result{} bar
-@end group
-@group
(bar 1 2 3 4 5)
@result{} (1 2 (3 4 5))
@end group
(forward-word 1)
(backward-char 1)
(capitalize-word 1))
- @result{} capitalize-backwards
@end group
@end example
from doing this, because redefining a function is sometimes done
deliberately, and there is no way to distinguish deliberate
redefinition from unintentional redefinition.
-@end defspec
+@end defmac
@cindex function aliases
-@defun defalias name definition &optional docstring
+@cindex alias, for functions
+@defun defalias name definition &optional doc
@anchor{Definition of defalias}
-This special form defines the symbol @var{name} as a function, with
+This function defines the symbol @var{name} as a function, with
definition @var{definition} (which can be any valid Lisp function).
-It returns @var{definition}.
+Its return value is @emph{undefined}.
-If @var{docstring} is non-@code{nil}, it becomes the function
-documentation of @var{name}. Otherwise, any documentation provided by
+If @var{doc} is non-@code{nil}, it becomes the function documentation
+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
But typically you should use the @code{lambda} macro, or the
@code{function} special form, or the @code{#'} read syntax:
-@defmac lambda args body...
-This macro returns an anonymous function with argument list @var{args}
-and body forms given by @var{body}. In effect, this macro makes
-@code{lambda} forms ``self-quoting'': evaluating a form whose @sc{car}
-is @code{lambda} yields the form itself:
+@defmac lambda args [doc] [interactive] body@dots{}
+This macro returns an anonymous function with argument list
+@var{args}, documentation string @var{doc} (if any), interactive spec
+@var{interactive} (if any), and body forms given by @var{body}.
+
+In effect, this macro makes @code{lambda} forms ``self-quoting'':
+evaluating a form whose @sc{car} is @code{lambda} yields the form
+itself:
@example
(lambda (x) (* x x))
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)
@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
(defun bar (n) (+ n 2))
- @result{} bar
-@end group
-@group
(symbol-function 'bar)
@result{} (lambda (n) (+ n 2))
@end 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,
@example
@group
(defun foo (x) x)
- @result{} foo
-@end group
-@group
(foo 1)
@result{}1
@end group
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.}
As explained in @ref{Variable Scoping}, Emacs can optionally enable
lexical binding of variables. When lexical binding is enabled, any
-named function that you create (e.g.@: with @code{defun}), as well as
+named function that you create (e.g., with @code{defun}), as well as
any anonymous function that you create using the @code{lambda} macro
or the @code{function} special form or the @code{#'} syntax
(@pxref{Anonymous Functions}), is automatically converted into a
-closure.
+@dfn{closure}.
+@cindex closure
A closure is a function that also carries a record of the lexical
environment that existed when the function was defined. When it is
invoked, any lexical variable references within its definition use the
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
-
-You can use @code{make-obsolete} to declare a function obsolete. This
-indicates that the function may be removed at some stage in the future.
+@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
+that the function is obsolete whenever it byte-compiles code
+containing that function, and whenever it displays the documentation
+for that function. In all other respects, an obsolete function
+behaves like any other function.
+
+ The easiest way to mark a function as obsolete is to put a
+@code{(declare (obsolete @dots{}))} form in the function's
+@code{defun} definition. @xref{Declare Form}. Alternatively, you can
+use the @code{make-obsolete} function, described below.
+
+ A macro (@pxref{Macros}) can also be marked obsolete with
+@code{make-obsolete}; this has the same effects as for a function. An
+alias for a function or macro can also be marked as obsolete; this
+makes the alias itself obsolete, not the function or macro which it
+resolves to.
@defun make-obsolete obsolete-name current-name &optional when
-This function makes the byte compiler warn that the function
-@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the
-warning message says to use @var{current-name} instead of
-@var{obsolete-name}. @var{current-name} does not need to be an alias for
-@var{obsolete-name}; it can be a different function with similar
-functionality. If @var{current-name} is a string, it is the warning
-message.
+This function marks @var{obsolete-name} as obsolete.
+@var{obsolete-name} should be a symbol naming a function or macro, or
+an alias for a function or macro.
+
+If @var{current-name} is a symbol, the warning message says to use
+@var{current-name} instead of @var{obsolete-name}. @var{current-name}
+does not need to be an alias for @var{obsolete-name}; it can be a
+different function with similar functionality. @var{current-name} can
+also be a string, which serves as the warning message. The message
+should begin in lower case, and end with a period. It can also be
+@code{nil}, in which case the warning message provides no additional
+details.
If provided, @var{when} should be a string indicating when the function
was first made obsolete---for example, a date or a release number.
@end defun
-You can define a function as an alias and declare it obsolete at the
-same time using the macro @code{define-obsolete-function-alias}:
-
-@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
-This macro marks the function @var{obsolete-name} obsolete and also
-defines it as an alias for the function @var{current-name}. It is
-equivalent to the following:
+@defmac define-obsolete-function-alias obsolete-name current-name &optional when doc
+This convenience macro marks the function @var{obsolete-name} obsolete
+and also defines it as an alias for the function @var{current-name}.
+It is equivalent to the following:
@example
-(defalias @var{obsolete-name} @var{current-name} @var{docstring})
+(defalias @var{obsolete-name} @var{current-name} @var{doc})
(make-obsolete @var{obsolete-name} @var{current-name} @var{when})
@end example
@end defmac
@section Inline Functions
@cindex inline functions
-@defmac defsubst name argument-list body-forms...
-Define an inline function. The syntax is exactly the same as
-@code{defun} (@pxref{Defining Functions}).
-@end defmac
-
- You can define an @dfn{inline function} by using @code{defsubst}
-instead of @code{defun}. An inline function works just like an
-ordinary function except for one thing: when you byte-compile a call
+ An @dfn{inline function} is a function that works just like an
+ordinary function, except for one thing: when you byte-compile a call
to the function (@pxref{Byte Compilation}), the function's definition
-is expanded into the caller.
+is expanded into the caller. To define an inline function, use
+@code{defsubst} instead of @code{defun}.
+
+@defmac defsubst name args [doc] [declare] [interactive] body@dots{}
+This macro defines an inline function. Its syntax is exactly the same
+as @code{defun} (@pxref{Defining Functions}).
+@end defmac
Making a function inline often makes its function calls run faster.
But it also has disadvantages. For one thing, it reduces flexibility;
After an inline function is defined, its inline expansion can be
performed later on in the same file, just like macros.
+@node Declare Form
+@section The @code{declare} Form
+@findex declare
+
+ @code{declare} is a special macro which can be used to add ``meta''
+properties to a function or macro: for example, marking it as
+obsolete, or giving its forms a special @key{TAB} indentation
+convention in Emacs Lisp mode.
+
+@anchor{Definition of declare}
+@defmac declare specs@dots{}
+This macro ignores its arguments and evaluates to @code{nil}; it has
+no run-time effect. However, when a @code{declare} form occurs in the
+@var{declare} argument of a @code{defun} or @code{defsubst} function
+definition (@pxref{Defining Functions}) or a @code{defmacro} macro
+definition (@pxref{Defining Macros}), it appends the properties
+specified by @var{specs} to the function or macro. This work is
+specially performed by @code{defun}, @code{defsubst}, and
+@code{defmacro}.
+
+Each element in @var{specs} should have the form @code{(@var{property}
+@var{args}@dots{})}, which should not be quoted. These have the
+following effects:
+
+@table @code
+@item (advertised-calling-convention @var{signature} @var{when})
+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 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})
+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}.
+This is typically used for macros, though it works for functions too.
+@xref{Indenting Macros}.
+
+@item (obsolete @var{current-name} @var{when})
+Mark the function or macro as obsolete, similar to a call to
+@code{make-obsolete} (@pxref{Obsolete Functions}). @var{current-name}
+should be a symbol (in which case the warning message says to use that
+instead), a string (specifying the warning message), or @code{nil} (in
+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
@section Telling the Compiler that a Function is Defined
@cindex function declaration
@example
In end of data:
-fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
- to be defined.
+fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not
+ known to be defined.
@end example
In fact, @code{gud-find-c-expr} is only used in the function that
without error.
There are some function definitions that @samp{check-declare} does not
-understand (e.g. @code{defstruct} and some other macros). In such cases,
+understand (e.g., @code{defstruct} and some other macros). In such cases,
you can pass a non-@code{nil} @var{fileonly} argument to
@code{declare-function}, meaning to only check that the file exists, not
that it actually defines the function. Note that to do this without
@cindex function safety
@cindex safety of functions
-Some major modes such as SES call functions that are stored in user
-files. (@inforef{Top, ,ses}, for more information on SES.) User
+Some major modes, such as SES, call functions that are stored in user
+files. (@inforef{Top, ,ses}, for more information on SES@.) User
files sometimes have poor pedigrees---you can get a spreadsheet from
someone you've just met, or you can get one through email from someone
you've never met. So it is risky to call a function whose source code
HCoop / bpt / emacs.git / blobdiff