@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 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/functions
@node Functions, Macros, Variables, Top
@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
@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 are
-@samp{not known to be defined} (@pxref{Compiler Errors}). The compiler
-is technically correct, but the code is usually such that when it
-actually runs, the function @emph{will} be defined. For example,
-byte-compiling @file{fortran.el} used to warn:
+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:
-@example
+@smallexample
In end of data:
-fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
-to be defined.
-@end example
+fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known to be defined.
+@end smallexample
-But @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}. This
-would only ever be called from gud, so the warning can safely be
-suppressed. It's nice to do this, so that real warnings are more
-visible.
+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:
-@example
+@smallexample
(declare-function gud-find-c-expr "gud.el" nil)
-@end example
+@end smallexample
This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
-`.el' can be omitted). The file is searched for using
-@code{locate-library}, and failing that it is expanded relative to the
-file containing the @code{declare-function} statement. Functions
-defined in C can also be declared - @file{.c} files are expanded
-relative to the Emacs @file{src/} directory.
-
-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 will check
-that the calls match the declaration.
-
-The functions @code{check-declare-file} and
-@code{check-declare-directory} check that all the
-@code{declare-function} statements in a file or directory are true
-(i.e. that the functions @emph{are} defined in the specified files, and
-have matching argument lists, if these were specified).
+@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}. @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
@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