]> code.delx.au - gnu-emacs/blobdiff - doc/lispref/functions.texi
(Terminal I/O Encoding): `keyboard-coding-system' and
[gnu-emacs] / doc / lispref / functions.texi
index 182d26511b1eeccc966188e85a8ea90212a72ceb..5f3995ea0c0c7bcc4644c9088cdcc83ce72533fe 100644 (file)
@@ -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  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,9 +116,9 @@ byte compiler.  @xref{Byte-Code Type}.
 
 @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}
@@ -725,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
@@ -1227,6 +1267,7 @@ following the definition, just like macros.
 @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
@@ -1265,10 +1306,11 @@ 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 arglist
+@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}.
+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
@@ -1289,6 +1331,20 @@ 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
@@ -1363,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