X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/fdc9061358d3654e14bfc1419632e1d6c6c5c13e..77ab81d0545e980c57c0a35510ade29a9e43b4cd:/doc/lispref/functions.texi diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 601644629e..198cc1a1ae 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1,7 +1,8 @@ @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, 2010, 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 +23,8 @@ 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 that have a special bearing on how functions work. @@ -115,9 +117,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} @@ -724,6 +726,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 @@ -776,7 +818,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 @@ -846,9 +888,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: @@ -875,17 +917,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 @@ -893,83 +939,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: - -@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, +If you compile this, the argument passed to @code{change-property} is +the precise list shown: @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 @@ -980,8 +991,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 @@ -1169,7 +1198,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 @@ -1182,6 +1211,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 @@ -1222,6 +1278,89 @@ do for macros. (@xref{Argument Evaluation}.) Inline functions can be used and open-coded later on in the same file, following the definition, just like macros. +@node Declaring Functions +@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 +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: + +@smallexample +In end of data: +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 +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: + +@smallexample +(declare-function gud-find-c-expr "gud.el" nil) +@end smallexample + +This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the +@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} 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. +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 @@ -1296,10 +1435,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