X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/9850eff524bd0747a9561f3b4c90dfc3749f4ecb..4c0078d4ab7fa8c234fa8098ec3a9686199edbff:/doc/lispref/functions.texi diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 3a891db871..f3b2375b61 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 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 @@ -22,7 +22,7 @@ define them. * 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 @@ -112,11 +112,20 @@ editors; for Lisp programs, the distinction is normally unimportant. @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} @@ -723,6 +732,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 @@ -741,6 +790,12 @@ This function returns @var{arg} and has no side effects. 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 @@ -775,7 +830,7 @@ length of @var{sequence}. For example: @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 @@ -845,9 +900,9 @@ bool-vector, or a string. 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: @@ -874,17 +929,21 @@ makes it the value (@emph{not} the function definition!) of @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 @@ -892,83 +951,48 @@ uses a function as its third argument: (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 @@ -979,8 +1003,26 @@ to be used only as a function, and therefore can safely be compiled. 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 @@ -1168,7 +1210,7 @@ was first made obsolete---for example, a date or a release number. @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 @@ -1181,6 +1223,33 @@ equivalent to the following: @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 @@ -1235,7 +1304,8 @@ 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. +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 @@ -1266,8 +1336,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 @@ -1282,11 +1352,11 @@ 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 + 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. @@ -1377,10 +1447,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 @@ -1452,7 +1522,3 @@ See @ref{Mapping Functions}. @item undefined See @ref{Functions for Key Lookup}. @end table - -@ignore - arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2 -@end ignore