@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 Copyright (C) 1990-1995, 1998-1999, 2001-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
@item byte-code function
A @dfn{byte-code function} is a function that has been compiled by the
byte compiler. @xref{Byte-Code Type}.
+
+@item autoload object
+@cindex autoload object
+An @dfn{autoload object} is a place-holder for a real function. If
+the autoload object is called, it will make Emacs load the file
+containing the definition of the real function, and then call the real
+function instead.
@end table
@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}
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
This function ignores any arguments and returns @code{nil}.
@end defun
+ Emacs Lisp functions can also be user-visible @dfn{commands}. A
+command is a function that has an @dfn{interactive} specification.
+You may want to call these functions as if they were called
+interactively. See @ref{Interactive Call} for details on how to do
+that.
+
@node Mapping Functions
@section Mapping Functions
@cindex mapping functions
@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:
+If you compile this, the argument passed to @code{change-property} is
+the precise list shown:
@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,
-
-@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
@smallexample
In end of data:
-fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known to be defined.
+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
@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
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
+ 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.
@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
@item undefined
See @ref{Functions for Key Lookup}.
@end table
-
-@ignore
- arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2
-@end ignore