@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/functions
@node Functions, Macros, Variables, Top
* Function Cells:: Accessing or setting the function definition
of a symbol.
* Obsolete Functions:: Declaring functions obsolete.
-* Inline Functions:: Defining functions that the compiler will open code.
+* Inline Functions:: Defining functions that the compiler will open code.
+* 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.
@defun functionp object
This function returns @code{t} if @var{object} is any kind of
-function, or a special form, or, recursively, a symbol whose function
-definition is a function or special form. (This does not include
-macros.)
+function, i.e.@: can be passed to @code{funcall}. Note that
+@code{functionp} returns @code{nil} for special forms (@pxref{Special
+Forms}).
@end defun
Unlike @code{functionp}, the next three functions do @emph{not}
of mapcar}.
@end defun
+@cindex partial application of functions
+@cindex currying
+ Sometimes it is useful to fix some of the function's arguments at
+certain values, and leave the rest of arguments for when the function
+is actually called. The act of fixing some of the function's
+arguments is called @dfn{partial application} of the function@footnote{
+This is related to, but different from @dfn{currying}, which
+transforms a function that takes multiple arguments in such a way that
+it can be called as a chain of functions, each one with a single
+argument.}.
+The result is a new function that accepts the rest of
+arguments and calls the original function with all the arguments
+combined.
+
+ Here's how to do partial application in Emacs Lisp:
+
+@defun apply-partially func &rest args
+This function returns a new function which, when called, will call
+@var{func} with the list of arguments composed from @var{args} and
+additional arguments specified at the time of the call. If @var{func}
+accepts @var{n} arguments, then a call to @code{apply-partially} with
+@w{@code{@var{m} < @var{n}}} arguments will produce a new function of
+@w{@code{@var{n} - @var{m}}} arguments.
+
+Here's how we could define the built-in function @code{1+}, if it
+didn't exist, using @code{apply-partially} and @code{+}, another
+built-in function:
+
+@example
+@group
+(defalias '1+ (apply-partially '+ 1)
+ "Increment argument by one.")
+@end group
+@group
+(1+ 10)
+ @result{} 11
+@end group
+@end example
+@end defun
+
@cindex functionals
It is common for Lisp functions to accept functions as arguments or
find them in data structures (especially in hook variables and property
@result{} (a c e)
(mapcar '1+ [1 2 3])
@result{} (2 3 4)
-(mapcar 'char-to-string "abc")
+(mapcar 'string "abc")
@result{} ("a" "b" "c")
@end group
In Lisp, a function is a list that starts with @code{lambda}, a
byte-code function compiled from such a list, or alternatively a
-primitive subr-object; names are ``extra.'' Although usually functions
-are defined with @code{defun} and given names at the same time, it is
-occasionally more concise to use an explicit lambda expression---an
+primitive subr-object; names are ``extra.'' Although functions are
+usually defined with @code{defun} and given names at the same time, it
+is occasionally more concise to use an explicit lambda expression---an
anonymous function. Such a list is valid wherever a function name is.
Any method of creating such a list makes a valid function. Even this:
@end example
@noindent
-(It does @emph{not} work to write @code{(silly 1)}, because this function
-is not the @emph{function definition} of @code{silly}. We have not given
-@code{silly} any function definition, just a value as a variable.)
+It does @emph{not} work to write @code{(silly 1)}, because this
+function is not the @emph{function definition} of @code{silly}. We
+have not given @code{silly} any function definition, just a value as a
+variable.
Most of the time, anonymous functions are constants that appear in
-your program. For example, you might want to pass one as an argument to
-the function @code{mapcar}, which applies any given function to each
-element of a list.
+your program. For instance, you might want to pass one as an argument
+to the function @code{mapcar}, which applies any given function to
+each element of a list (@pxref{Mapping Functions}).
+@xref{describe-symbols example}, for a realistic example of this.
- Here we define a function @code{change-property} which
-uses a function as its third argument:
+ In the following example, we define a @code{change-property}
+function that takes a function as its third argument, followed by a
+@code{double-property} function that makes use of
+@code{change-property} by passing it an anonymous function:
@example
@group
(let ((value (get symbol prop)))
(put symbol prop (funcall function value))))
@end group
-@end example
-
-@noindent
-Here we define a function that uses @code{change-property},
-passing it a function to double a number:
-
-@example
-@group
-(defun double-property (symbol prop)
- (change-property symbol prop '(lambda (x) (* 2 x))))
-@end group
-@end example
-
-@noindent
-In such cases, we usually use the special form @code{function} instead
-of simple quotation to quote the anonymous function, like this:
-@example
@group
(defun double-property (symbol prop)
- (change-property symbol prop
- (function (lambda (x) (* 2 x)))))
+ (change-property symbol prop (lambda (x) (* 2 x))))
@end group
@end example
-Using @code{function} instead of @code{quote} makes a difference if you
-compile the function @code{double-property}. For example, if you
-compile the second definition of @code{double-property}, the anonymous
-function is compiled as well. By contrast, if you compile the first
-definition which uses ordinary @code{quote}, the argument passed to
-@code{change-property} is the precise list shown:
-
-@example
-(lambda (x) (* x 2))
-@end example
-
@noindent
-The Lisp compiler cannot assume this list is a function, even though it
-looks like one, since it does not know what @code{change-property} will
-do with the list. Perhaps it will check whether the @sc{car} of the third
-element is the symbol @code{*}! Using @code{function} tells the
-compiler it is safe to go ahead and compile the constant function.
+In the @code{double-property} function, we did not quote the
+@code{lambda} form. This is permissible, because a @code{lambda} form
+is @dfn{self-quoting}: evaluating the form yields the form itself.
- Nowadays it is possible to omit @code{function} entirely, like this:
+Whether or not you quote a @code{lambda} form makes a difference if
+you compile the code (@pxref{Byte Compilation}). If the @code{lambda}
+form is unquoted, as in the above example, the anonymous function is
+also compiled. Suppose, however, that we quoted the @code{lambda}
+form:
@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
@noindent
-This is because @code{lambda} itself implies @code{function}.
-
- We sometimes write @code{function} instead of @code{quote} when
-quoting the name of a function, but this usage is just a sort of
-comment:
-
-@example
-(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
-@end example
-
-@cindex @samp{#'} syntax
- The read syntax @code{#'} is a short-hand for using @code{function}.
-For example,
+If you compile this, the argument passed to @code{change-property} is
+the precise list shown:
@example
-#'(lambda (x) (* x x))
+(lambda (x) (* x 2))
@end example
@noindent
-is equivalent to
+The Lisp compiler cannot assume this list is a function, even though
+it looks like one, since it does not know what @code{change-property}
+will do with the list. Perhaps it will check whether the @sc{car} of
+the third element is the symbol @code{*}!
-@example
-(function (lambda (x) (* x x)))
-@end example
+@findex function
+The @code{function} special form explicitly tells the byte-compiler
+that its argument is a function:
@defspec function function-object
@cindex function quoting
Contrast this with @code{quote}, in @ref{Quoting}.
@end defspec
- @xref{describe-symbols example}, for a realistic example using
-@code{function} and an anonymous function.
+@cindex @samp{#'} syntax
+The read syntax @code{#'} is a short-hand for using @code{function}.
+Generally, it is not necessary to use either @code{#'} or
+@code{function}; just use an unquoted @code{lambda} form instead.
+(Actually, @code{lambda} is a macro defined using @code{function}.)
+The following forms are all equivalent:
+
+@example
+#'(lambda (x) (* x x))
+(function (lambda (x) (* x x)))
+(lambda (x) (* x x))
+@end example
+
+ We sometimes write @code{function} instead of @code{quote} when
+quoting the name of a function, but this usage is just a sort of
+comment:
+
+@example
+(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
+@end example
@node Function Cells
@section Accessing Function Cell Contents
@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}.
+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
@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
+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).
+
+For instance, in old versions of Emacs the @code{sit-for} function
+accepted three arguments, like this
+
+@smallexample
+ (sit-for seconds milliseconds nodisp)
+@end smallexample
+
+However, calling @code{sit-for} this way is considered obsolete
+(@pxref{Waiting}). The old calling convention is deprecated like
+this:
+
+@smallexample
+(set-advertised-calling-convention
+ 'sit-for '(seconds &optional nodisp))
+@end smallexample
+@end defun
+
@node Inline Functions
@section Inline Functions
@cindex inline functions
Inline functions can be used and open-coded later on in the same file,
following the definition, just like macros.
+@node Declaring Functions
+@section Telling the Compiler that a Function is Defined
+@cindex function declaration
+@cindex declaring functions
+@findex declare-function
+
+Byte-compiling a file often produces warnings about functions that the
+compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this
+indicates a real problem, but usually the functions in question are
+defined in other files which would be loaded if that code is run. For
+example, byte-compiling @file{fortran.el} used to warn:
+
+@smallexample
+In end of data:
+fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
+ to be defined.
+@end smallexample
+
+In fact, @code{gud-find-c-expr} is only used in the function that
+Fortran mode uses for the local value of
+@code{gud-find-expr-function}, which is a callback from GUD; if it is
+called, the GUD functions will be loaded. When you know that such a
+warning does not indicate a real problem, it is good to suppress the
+warning. That makes new warnings which might mean real problems more
+visible. You do that with @code{declare-function}.
+
+All you need to do is add a @code{declare-function} statement before the
+first use of the function in question:
+
+@smallexample
+(declare-function gud-find-c-expr "gud.el" nil)
+@end smallexample
+
+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
+really defines the function, and does not check.
+
+ The optional third argument specifies the argument list of
+@code{gud-find-c-expr}. In this case, it takes no arguments
+(@code{nil} is different from not specifying a value). In other
+cases, this might be something like @code{(file &optional overwrite)}.
+You don't have to specify the argument list, but if you do the
+byte compiler can check that the calls match the declaration.
+
+@defmac declare-function function file &optional arglist fileonly
+Tell the byte compiler to assume that @var{function} is defined, with
+arguments @var{arglist}, and that the definition should come from the
+file @var{file}. @var{fileonly} non-@code{nil} means only check that
+@var{file} exists, not that it actually defines @var{function}.
+@end defmac
+
+ To verify that these functions really are declared where
+@code{declare-function} says they are, use @code{check-declare-file}
+to check all @code{declare-function} calls in one source file, or use
+@code{check-declare-directory} check all the files in and under a
+certain directory.
+
+ These commands find the file that ought to contain a function's
+definition using @code{locate-library}; if that finds no file, they
+expand the definition file name relative to the directory of the file
+that contains the @code{declare-function} call.
+
+ You can also say that a function is defined by C code by specifying a
+file name ending in @samp{.c} or @samp{.m}. @code{check-declare-file}
+looks for these files in the C source code directory. This is useful
+only when you call a function that is defined only on certain systems.
+Most of the primitive functions of Emacs are always defined so they will
+never give you a warning.
+
+ Sometimes a file will optionally use functions from an external package.
+If you prefix the filename in the @code{declare-function} statement with
+@samp{ext:}, then it will be checked if it is found, otherwise skipped
+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,
+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
+having to specify an argument list, you should set the @var{arglist}
+argument to @code{t} (because @code{nil} means an empty argument list, as
+opposed to an unspecified one).
+
@node Function Safety
@section Determining whether a Function is Safe to Call
@cindex function safety
@item
A symbol with a non-@code{nil} @code{side-effect-free} property.
@item
-A symbol with a non-@code{nil} @code{safe-function} property. Value t
-indicates a function that is safe but has innocuous side effects.
-Other values will someday indicate functions with classes of side
-effects that are not always safe.
+A symbol with a non-@code{nil} @code{safe-function} property. The
+value @code{t} indicates a function that is safe but has innocuous
+side effects. Other values will someday indicate functions with
+classes of side effects that are not always safe.
@end itemize
The @code{side-effect-free} and @code{safe-function} properties are
HCoop / bpt / emacs.git / blobdiff