@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-2013 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
* 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
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
-We can call this function by writing it as the @sc{car} of an
-expression, like this:
+We can call this function by passing it to @code{funcall}, like this:
@example
@group
-((lambda (a b c) (+ a b c))
- 1 2 3)
+(funcall (lambda (a b c) (+ a b c))
+ 1 2 3)
@end group
@end example
@example
@group
-((lambda (a b c) (+ a b c))
- 1 (* 2 3) (- 5 4))
+(funcall (lambda (a b c) (+ a b c))
+ 1 (* 2 3) (- 5 4))
@end group
@end example
Here are some examples of argument lists and proper calls:
-@smallexample
-((lambda (n) (1+ n)) ; @r{One required:}
- 1) ; @r{requires exactly one argument.}
+@example
+(funcall (lambda (n) (1+ n)) ; @r{One required:}
+ 1) ; @r{requires exactly one argument.}
@result{} 2
-((lambda (n &optional n1) ; @r{One required and one optional:}
- (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
- 1 2)
+(funcall (lambda (n &optional n1) ; @r{One required and one optional:}
+ (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
+ 1 2)
@result{} 3
-((lambda (n &rest ns) ; @r{One required and one rest:}
- (+ n (apply '+ ns))) ; @r{1 or more arguments.}
- 1 2 3 4 5)
+(funcall (lambda (n &rest ns) ; @r{One required and one rest:}
+ (+ n (apply '+ ns))) ; @r{1 or more arguments.}
+ 1 2 3 4 5)
@result{} 15
-@end smallexample
+@end example
@node Function Documentation
@subsection Documentation Strings of Functions
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:
-
-@example
-(lambda @var{argument-list} . @var{body-forms})
-@end example
+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.
-@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
+@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.
The proper place to use @code{defalias} is where a specific function
result is always a list. The length of the result is the same as the
length of @var{sequence}. For example:
-@smallexample
+@example
@group
(mapcar 'car '((a b) (c d) (e f)))
@result{} (a c e)
(mapcar* 'cons '(a b c) '(1 2 3 4))
@result{} ((a . 1) (b . 2) (c . 3))
@end group
-@end smallexample
+@end example
@end defun
@defun mapc function sequence
kind of sequence except a char-table; that is, a list, a vector, a
bool-vector, or a string.
-@smallexample
+@example
@group
(mapconcat 'symbol-name
'(The cat in the hat)
"")
@result{} "IBM.9111"
@end group
-@end smallexample
+@end example
@end defun
@node Anonymous Functions
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))
@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
@example
@group
(defun bar (n) (+ n 2))
- @result{} bar
-@end group
-@group
(symbol-function 'bar)
@result{} (lambda (n) (+ n 2))
@end group
@example
@group
(defun foo (x) x)
- @result{} foo
-@end group
-@group
(foo 1)
@result{}1
@end group
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
+give a symbol a function definition that is not a list, e.g., a
keyboard macro (@pxref{Keyboard Macros}):
@example
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
@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.
+ 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
In addition, you can mark a certain a particular calling convention
for a function as obsolete:
-@defun set-advertised-calling-convention function signature
+@defun set-advertised-calling-convention function signature when
This function specifies the argument list @var{signature} as the
correct way to call @var{function}. This causes the Emacs byte
compiler to issue a warning whenever it comes across an Emacs Lisp
program that calls @var{function} any other way (however, it will
-still allow the code to be byte compiled).
+still allow the code to be byte compiled). @var{when} should be a
+string indicating when the variable was first made obsolete (usually a
+version number string).
For instance, in old versions of Emacs the @code{sit-for} function
accepted three arguments, like this
-@smallexample
+@example
(sit-for seconds milliseconds nodisp)
-@end smallexample
+@end example
However, calling @code{sit-for} this way is considered obsolete
(@pxref{Waiting}). The old calling convention is deprecated like
this:
-@smallexample
+@example
(set-advertised-calling-convention
- 'sit-for '(seconds &optional nodisp))
-@end smallexample
+ 'sit-for '(seconds &optional nodisp) "22.1")
+@end example
@end defun
@node Inline Functions
@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 variable 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.
+
+@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.
+@end table
+@end defmac
+
@node Declaring Functions
@section Telling the Compiler that a Function is Defined
@cindex function declaration
defined in other files which would be loaded if that code is run. For
example, byte-compiling @file{fortran.el} used to warn:
-@smallexample
+@example
In end of data:
-fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
- to be defined.
-@end smallexample
+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
Fortran mode uses for the local value of
All you need to do is add a @code{declare-function} statement before the
first use of the function in question:
-@smallexample
+@example
(declare-function gud-find-c-expr "gud.el" nil)
-@end smallexample
+@end example
This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
@samp{.el} can be omitted). The compiler takes for granted that that file
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