X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/142e26a72e9b8bbbec23c6bf7234e9f2544b5f89..97d8273fa2687731d652687cf6b4c7c48dd0661a:/doc/lispref/functions.texi

diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi
index 3a891db871..5f3995ea0c 100644
--- a/doc/lispref/functions.texi
+++ b/doc/lispref/functions.texi
@@ -1,7 +1,7 @@
 @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, 2008  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
@@ -116,7 +116,9 @@ byte compiler.  @xref{Byte-Code Type}.
 
 @defun functionp object
 This function returns @code{t} if @var{object} is any kind of
-function, i.e. can be passed to @code{funcall}.
+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}
@@ -723,6 +725,46 @@ For an interesting example of using @code{apply}, see @ref{Definition
 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
@@ -1266,8 +1308,8 @@ 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-nil means only check that
+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
 
@@ -1377,10 +1419,10 @@ A symbol on the list @code{safe-functions}, so the user says it's safe.
 @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