X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/f25df2ab1d2a3bb5b11c92c2c4c7d93ae489b889..03da5d089a8ed035cec443a27259e7d21487a22e:/lispref/functions.texi diff --git a/lispref/functions.texi b/lispref/functions.texi index 0f596cb621..17a96734b1 100644 --- a/lispref/functions.texi +++ b/lispref/functions.texi @@ -1,6 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, +@c 2004, 2005 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/functions @node Functions, Macros, Variables, Top @@ -17,10 +18,12 @@ define them. * Defining Functions:: Lisp expressions for defining functions. * Calling Functions:: How to use an existing function. * Mapping Functions:: Applying a function to each element of a list, etc. -* Anonymous Functions:: Lambda expressions are functions with no names. +* Anonymous Functions:: Lambda expressions are functions with no names. * 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. +* 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. @end menu @@ -51,21 +54,21 @@ macros are not functions. @cindex built-in function A @dfn{primitive} is a function callable from Lisp that is written in C, such as @code{car} or @code{append}. These functions are also called -@dfn{built-in} functions or @dfn{subrs}. (Special forms are also +@dfn{built-in functions}, or @dfn{subrs}. (Special forms are also considered primitives.) -Usually the reason that a function is a primitives is because it is -fundamental, because it provides a low-level interface to operating -system services, or because it needs to run fast. Primitives can be -modified or added only by changing the C sources and recompiling the -editor. See @ref{Writing Emacs Primitives}. +Usually the reason we implement a function as a primitive is either +because it is fundamental, because it provides a low-level interface +to operating system services, or because it needs to run fast. +Primitives can be modified or added only by changing the C sources and +recompiling the editor. See @ref{Writing Emacs Primitives}. @item lambda expression A @dfn{lambda expression} is a function written in Lisp. These are described in the following section. -@ifinfo +@ifnottex @xref{Lambda Expressions}. -@end ifinfo +@end ifnottex @item special form A @dfn{special form} is a primitive that is like a function but does not @@ -79,7 +82,9 @@ Structures}. A @dfn{macro} is a construct defined in Lisp by the programmer. It differs from a function in that it translates a Lisp expression that you write into an equivalent expression to be evaluated instead of the -original expression. @xref{Macros}, for how to define and use macros. +original expression. Macros enable Lisp programmers to do the sorts of +things that special forms can do. @xref{Macros}, for how to define and +use macros. @item command @cindex command @@ -108,6 +113,16 @@ A @dfn{byte-code function} is a function that has been compiled by the byte compiler. @xref{Byte-Code Type}. @end table +@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.) +@end defun + +Unlike @code{functionp}, the next three functions do @emph{not} +treat a symbol as its function definition. + @defun subrp object This function returns @code{t} if @var{object} is a built-in function (i.e., a Lisp primitive). @@ -136,6 +151,16 @@ function. For example: @end example @end defun +@defun subr-arity subr +@tindex subr-arity +This function provides information about the argument list of a +primitive, @var{subr}. The returned value is a pair +@code{(@var{min} . @var{max})}. @var{min} is the minimum number of +args. @var{max} is the maximum number or the symbol @code{many}, for a +function with @code{&rest} arguments, or the symbol @code{unevalled} if +@var{subr} is a special form. +@end defun + @node Lambda Expressions @section Lambda Expressions @cindex lambda expression @@ -150,9 +175,11 @@ function. For example: @end example @noindent -(Such a list is called a @dfn{lambda expression} for historical reasons, -even though it is not really an expression at all---it is not a form -that can be evaluated meaningfully.) +Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it +actually is valid as an expression---it evaluates to itself. In some +other Lisp dialects, a lambda expression is not a valid expression at +all. In either case, its main use is not to be evaluated as an +expression, but to be called as a function. @menu * Lambda Components:: The parts of a lambda expression. @@ -164,7 +191,7 @@ that can be evaluated meaningfully.) @node Lambda Components @subsection Components of a Lambda Expression -@ifinfo +@ifnottex A function written in Lisp (a ``lambda expression'') is a list that looks like this: @@ -175,7 +202,7 @@ looks like this: [@var{interactive-declaration}] @var{body-forms}@dots{}) @end example -@end ifinfo +@end ifnottex @cindex lambda list The first element of a lambda expression is always the symbol @@ -184,7 +211,7 @@ reason functions are defined to start with @code{lambda} is so that other lists, intended for other uses, will not accidentally be valid as functions. - The second element is a list of symbols--the argument variable names. + The second element is a list of symbols---the argument variable names. This is called the @dfn{lambda list}. When a Lisp function is called, the argument values are matched up against the variables in the lambda list, which are given local bindings with the values provided. @@ -263,7 +290,7 @@ that time, they were the only way to bind and initialize local variables. @node Argument List -@subsection Advanced Features of Argument Lists +@subsection Other Features of Argument Lists @kindex wrong-number-of-arguments @cindex argument binding @cindex binding arguments @@ -322,7 +349,8 @@ This is what @code{substring} does; @code{nil} as the third argument to @quotation @b{Common Lisp note:} Common Lisp allows the function to specify what default value to use when an optional argument is omitted; Emacs Lisp -always uses @code{nil}. +always uses @code{nil}. Emacs Lisp does not support ``supplied-p'' +variables that tell you whether an argument was explicitly passed. @end quotation For example, an argument list that looks like this: @@ -343,9 +371,11 @@ is @code{nil}. There is no way to have required arguments following optional ones---it would not make sense. To see why this must be so, suppose that @code{c} in the example were optional and @code{d} were required. -Suppose three actual arguments are given; which variable would the third -argument be for? Similarly, it makes no sense to have any more -arguments (either required or optional) after a @code{&rest} argument. +Suppose three actual arguments are given; which variable would the +third argument be for? Would it be used for the @var{c}, or for +@var{d}? One can argue for both possibilities. Similarly, it makes +no sense to have any more arguments (either required or optional) +after a @code{&rest} argument. Here are some examples of argument lists and proper calls: @@ -374,22 +404,23 @@ actually appears inside the Lisp world and can be used by the Emacs help facilities. @xref{Documentation}, for how the @var{documentation-string} is accessed. - It is a good idea to provide documentation strings for all commands, -and for all other functions in your program that users of your program -should know about; internal functions might as well have only comments, -since comments don't take up any room when your program is loaded. + It is a good idea to provide documentation strings for all the +functions in your program, even those that are called only from within +your program. Documentation strings are like comments, except that they +are easier to access. The first line of the documentation string should stand on its own, because @code{apropos} displays just this first line. It should consist of one or two complete sentences that summarize the function's purpose. - The start of the documentation string is usually indented, but since -these spaces come before the starting double-quote, they are not part of -the string. Some people make a practice of indenting any additional -lines of the string so that the text lines up in the program source. -@emph{This is a mistake.} The indentation of the following lines is -inside the string; what looks nice in the source code will look ugly -when displayed by the help commands. + The start of the documentation string is usually indented in the +source file, but since these spaces come before the starting +double-quote, they are not part of the string. Some people make a +practice of indenting any additional lines of the string so that the +text lines up in the program source. @emph{That is a mistake.} The +indentation of the following lines is inside the string; what looks +nice in the source code will look ugly when displayed by the help +commands. You may wonder how the documentation string could be optional, since there are required components of the function that follow it (the body). @@ -399,6 +430,25 @@ practice, there is no confusion between the first form of the body and the documentation string; if the only body form is a string then it serves both as the return value and as the documentation. + The last line of the documentation string can specify calling +conventions different from the actual function arguments. Write +text like this: + +@example +\(fn @var{arglist}) +@end example + +@noindent +following a blank line, at the beginning of the line, with no newline +following it inside the documentation string. (The @samp{\} is used +to avoid confusing the Emacs motion commands.) The calling convention +specified in this way appears in help messages in place of the one +derived from the actual arguments of the function. + + This feature is particularly useful for macro definitions, since the +arguments written in a macro definition often do not correspond to the +way users think of the parts of the macro call. + @node Function Names @section Naming a Function @cindex function definition @@ -408,7 +458,7 @@ as the return value and as the documentation. In most computer languages, every function has a name; the idea of a function without a name is nonsensical. In Lisp, a function in the strictest sense has no name. It is simply a list whose first element is -@code{lambda}, or a primitive subr-object. +@code{lambda}, a byte-code function object, or a primitive subr-object. However, a symbol can serve as the name of a function. This happens when you put the function in the symbol's @dfn{function cell} @@ -438,8 +488,8 @@ practice). We often identify functions with the symbols used to name them. For example, we often speak of ``the function @code{car}'', not distinguishing between the symbol @code{car} and the primitive -subr-object that is its function definition. For most purposes, there -is no need to distinguish. +subr-object that is its function definition. For most purposes, the +distinction is not important. Even so, keep in mind that a function need not have a unique name. While a given function object @emph{usually} appears in the function cell of only @@ -447,8 +497,13 @@ one symbol, this is just a matter of convenience. It is easy to store it in several symbols using @code{fset}; then each of the symbols is equally well a name for the same function. - A symbol used as a function name may also be used as a variable; -these two uses of a symbol are independent and do not conflict. + A symbol used as a function name may also be used as a variable; these +two uses of a symbol are independent and do not conflict. (Some Lisp +dialects, such as Scheme, do not distinguish between a symbol's value +and its function definition; a symbol's value as a variable is also its +function definition.) If you have not given a symbol a function +definition, you cannot use it as a function; whether the symbol has a +value as a variable makes no difference to this. @node Defining Functions @section Defining Functions @@ -470,10 +525,10 @@ defines the symbol @var{name} as a function that looks like this: @var{name}. It returns the value @var{name}, but usually we ignore this value. -As described previously (@pxref{Lambda Expressions}), -@var{argument-list} is a list of argument names and may include the -keywords @code{&optional} and @code{&rest}. Also, the first two forms -in @var{body-forms} may be a documentation string and an interactive +As described previously, @var{argument-list} is a list of argument +names and may include the keywords @code{&optional} and @code{&rest} +(@pxref{Lambda Expressions}). Also, the first two of the +@var{body-forms} may be a documentation string and an interactive declaration. There is no conflict if the same symbol @var{name} is also used as a @@ -529,14 +584,41 @@ defined is often done deliberately, and there is no way to distinguish deliberate redefinition from unintentional redefinition. @end defspec -@defun defalias name definition +@defun defalias name definition &optional docstring +@anchor{Definition of defalias} This special form defines the symbol @var{name} as a function, with definition @var{definition} (which can be any valid Lisp function). -It's best to use this rather than @code{fset} when defining a function -in a file, because @code{defalias} records which file defined the -function (@pxref{Unloading}), while @code{fset} does not. +It returns @var{definition}. + +If @var{docstring} is non-@code{nil}, it becomes the function +documentation of @var{name}. Otherwise, any documentation provided by +@var{definition} is used. + +The proper place to use @code{defalias} is where a specific function +name is being defined---especially where that name appears explicitly in +the source file being loaded. This is because @code{defalias} records +which file defined the function, just like @code{defun} +(@pxref{Unloading}). + +By contrast, in programs that manipulate function definitions for other +purposes, it is better to use @code{fset}, which does not keep such +records. @xref{Function Cells}. @end defun + You cannot create a new primitive function with @code{defun} or +@code{defalias}, but you can use them to change the function definition of +any symbol, even one such as @code{car} or @code{x-popup-menu} whose +normal definition is a primitive. However, this is risky: for +instance, it is next to impossible to redefine @code{car} without +breaking Lisp completely. Redefining an obscure function such as +@code{x-popup-menu} is less dangerous, but it still may not work as +you expect. If there are calls to the primitive from C code, they +call the primitive's C definition directly, so changing the symbol's +definition will have no effect on them. + + See also @code{defsubst}, which defines a function like @code{defun} +and tells the Lisp compiler to open-code it. @xref{Inline Functions}. + @node Calling Functions @section Calling Functions @cindex function invocation @@ -551,12 +633,12 @@ For example, evaluating the list @code{(concat "a" "b")} calls the function @code{concat} with arguments @code{"a"} and @code{"b"}. @xref{Evaluation}, for a description of evaluation. - When you write a list as an expression in your program, the function -name is part of the program. This means that you choose which function -to call, and how many arguments to give it, when you write the program. -Usually that's just what you want. Occasionally you need to decide at -run time which function to call. To do that, use the functions -@code{funcall} and @code{apply}. + When you write a list as an expression in your program, you specify +which function to call, and how many arguments to give it, in the text +of the program. Usually that's just what you want. Occasionally you +need to compute at run time which function to call. To do that, use +the function @code{funcall}. When you also need to determine at run +time how many arguments to pass, use @code{apply}. @defun funcall function &rest arguments @code{funcall} calls @var{function} with @var{arguments}, and returns @@ -565,11 +647,12 @@ whatever @var{function} returns. Since @code{funcall} is a function, all of its arguments, including @var{function}, are evaluated before @code{funcall} is called. This means that you can use any expression to obtain the function to be -called. It also means that @code{funcall} does not see the expressions -you write for the @var{arguments}, only their values. These values are -@emph{not} evaluated a second time in the act of calling @var{function}; -@code{funcall} enters the normal procedure for calling a function at the -place where the arguments have already been evaluated. +called. It also means that @code{funcall} does not see the +expressions you write for the @var{arguments}, only their values. +These values are @emph{not} evaluated a second time in the act of +calling @var{function}; the operation of @code{funcall} is like the +normal procedure for calling a function, once its arguments have +already been evaluated. The argument @var{function} must be either a Lisp function or a primitive function. Special forms and macros are not allowed, because @@ -596,15 +679,16 @@ above, it never knows them in the first place. @end group @end example -Compare these example with the examples of @code{apply}. +Compare these examples with the examples of @code{apply}. @end defun @defun apply function &rest arguments @code{apply} calls @var{function} with @var{arguments}, just like @code{funcall} but with one difference: the last of @var{arguments} is a -list of arguments to give to @var{function}, rather than a single -argument. We also say that @code{apply} @dfn{spreads} this list so that -each individual element becomes an argument. +list of objects, which are passed to @var{function} as separate +arguments, rather than a single list. We say that @code{apply} +@dfn{spreads} this list so that each individual element becomes an +argument. @code{apply} returns the result of calling @var{function}. As with @code{funcall}, @var{function} must either be a Lisp function or a @@ -635,8 +719,8 @@ primitive function; special forms and macros do not make sense in @end group @end example -For an interesting example of using @code{apply}, see the description of -@code{mapcar}, in @ref{Mapping Functions}. +For an interesting example of using @code{apply}, see @ref{Definition +of mapcar}. @end defun @cindex functionals @@ -645,8 +729,8 @@ find them in data structures (especially in hook variables and property lists) and call them using @code{funcall} or @code{apply}. Functions that accept function arguments are often called @dfn{functionals}. - Sometimes, when you call such a function, it is useful to supply a -no-op function as the argument. Here are two different kinds of no-op + Sometimes, when you call a functional, it is useful to supply a no-op +function as the argument. Here are two different kinds of no-op function: @defun identity arg @@ -661,17 +745,27 @@ This function ignores any arguments and returns @code{nil}. @section Mapping Functions @cindex mapping functions - A @dfn{mapping function} applies a given function to each element of a -list or other collection. Emacs Lisp has three such functions; -@code{mapcar} and @code{mapconcat}, which scan a list, are described -here. For the third mapping function, @code{mapatoms}, see -@ref{Creating Symbols}. + A @dfn{mapping function} applies a given function (@emph{not} a +special form or macro) to each element of a list or other collection. +Emacs Lisp has several such functions; @code{mapcar} and +@code{mapconcat}, which scan a list, are described here. +@xref{Definition of mapatoms}, for the function @code{mapatoms} which +maps over the symbols in an obarray. @xref{Definition of maphash}, +for the function @code{maphash} which maps over key/value associations +in a hash table. + + These mapping functions do not allow char-tables because a char-table +is a sparse array whose nominal range of indices is very large. To map +over a char-table in a way that deals properly with its sparse nature, +use the function @code{map-char-table} (@pxref{Char-Tables}). @defun mapcar function sequence +@anchor{Definition of mapcar} @code{mapcar} applies @var{function} to each element of @var{sequence} in turn, and returns a list of the results. -The argument @var{sequence} may be a list, a vector, or a string. The +The argument @var{sequence} can be any kind of sequence except a +char-table; that is, a list, a vector, a bool-vector, or a string. The result is always a list. The length of the result is the same as the length of @var{sequence}. @@ -693,14 +787,14 @@ length of @var{sequence}. @end group @group -(defun mapcar* (f &rest args) +(defun mapcar* (function &rest args) "Apply FUNCTION to successive cars of all ARGS. Return the list of results." ;; @r{If no list is exhausted,} - (if (not (memq 'nil args)) - ;; @r{apply function to @sc{CAR}s.} - (cons (apply f (mapcar 'car args)) - (apply 'mapcar* f + (if (not (memq nil args)) + ;; @r{apply function to @sc{car}s.} + (cons (apply function (mapcar 'car args)) + (apply 'mapcar* function ;; @r{Recurse for rest of elements.} (mapcar 'cdr args))))) @end group @@ -712,6 +806,13 @@ Return the list of results." @end smallexample @end defun +@defun mapc function sequence +@tindex mapc +@code{mapc} is like @code{mapcar} except that @var{function} is used for +side-effects only---the values it returns are ignored, not collected +into a list. @code{mapc} always returns @var{sequence}. +@end defun + @defun mapconcat function sequence separator @code{mapconcat} applies @var{function} to each element of @var{sequence}: the results, which must be strings, are concatenated. @@ -720,8 +821,10 @@ Between each pair of result strings, @code{mapconcat} inserts the string other suitable punctuation. The argument @var{function} must be a function that can take one -argument and return a string. - +argument and return a string. The argument @var{sequence} can be any +kind of sequence except a char-table; that is, a list, a vector, a +bool-vector, or a string. + @smallexample @group (mapconcat 'symbol-name @@ -779,56 +882,50 @@ 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. Here we pass an anonymous function that multiplies -a number by two: +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. + + Here we define a function @code{change-property} which +uses a function as its third argument: @example @group -(defun double-each (list) - (mapcar '(lambda (x) (* 2 x)) list)) -@result{} double-each +(defun change-property (symbol prop function) + (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 -(double-each '(2 11)) -@result{} (4 22) +(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. - -@defspec function function-object -@cindex function quoting -This special form returns @var{function-object} without evaluating it. -In this, it is equivalent to @code{quote}. However, it serves as a -note to the Emacs Lisp compiler that @var{function-object} is intended -to be used only as a function, and therefore can safely be compiled. -Contrast this with @code{quote}, in @ref{Quoting}. -@end defspec - - Using @code{function} instead of @code{quote} makes a difference -inside a function or macro that you are going to compile. For example: +of simple quotation to quote the anonymous function, like this: @example @group -(defun double-each (list) - (mapcar (function (lambda (x) (* 2 x))) list)) -@result{} double-each -@end group -@group -(double-each '(2 11)) -@result{} (4 22) +(defun double-property (symbol prop) + (change-property symbol prop + (function (lambda (x) (* 2 x))))) @end group @end example -@noindent -If this definition of @code{double-each} is compiled, the anonymous -function is compiled as well. By contrast, in the previous definition -where ordinary @code{quote} is used, the argument passed to -@code{mapcar} is the precise list shown: +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)) @@ -836,22 +933,57 @@ where ordinary @code{quote} is used, the argument passed to @noindent The Lisp compiler cannot assume this list is a function, even though it -looks like one, since it does not know what @code{mapcar} does with the -list. Perhaps @code{mapcar} will check that the @sc{car} of the third -element is the symbol @code{*}! The advantage of @code{function} is -that it tells the compiler to go ahead and compile the constant -function. +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. + + Nowadays it is possible to omit @code{function} entirely, like this: + +@example +@group +(defun double-property (symbol prop) + (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. +comment: @example (function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol} @end example - See @code{documentation} in @ref{Accessing Documentation}, 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}. +For example, + +@example +#'(lambda (x) (* x x)) +@end example + +@noindent +is equivalent to + +@example +(function (lambda (x) (* x x))) +@end example + +@defspec function function-object +@cindex function quoting +This special form returns @var{function-object} without evaluating it. +In this, it is equivalent to @code{quote}. However, it serves as a +note to the Emacs Lisp compiler that @var{function-object} is intended +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. @node Function Cells @section Accessing Function Cell Contents @@ -860,8 +992,8 @@ realistic example using @code{function} and an anonymous function. function cell of the symbol. The functions described here access, test, and set the function cell of symbols. - See also the function @code{indirect-function} in @ref{Function -Indirection}. + See also the function @code{indirect-function}. @xref{Definition of +indirect-function}. @defun symbol-function symbol @kindex void-function @@ -916,13 +1048,14 @@ is a legitimate function. @defun fmakunbound symbol This function makes @var{symbol}'s function cell void, so that a -subsequent attempt to access this cell will cause a @code{void-function} -error. (See also @code{makunbound}, in @ref{Local Variables}.) +subsequent attempt to access this cell will cause a +@code{void-function} error. It returns @var{symbol}. (See also +@code{makunbound}, in @ref{Void Variables}.) @example @group (defun foo (x) x) - @result{} x + @result{} foo @end group @group (foo 1) @@ -930,7 +1063,7 @@ error. (See also @code{makunbound}, in @ref{Local Variables}.) @end group @group (fmakunbound 'foo) - @result{} x + @result{} foo @end group @group (foo 1) @@ -939,24 +1072,29 @@ error. (See also @code{makunbound}, in @ref{Local Variables}.) @end example @end defun -@defun fset symbol object -This function stores @var{object} in the function cell of @var{symbol}. -The result is @var{object}. Normally @var{object} should be a function -or the name of a function, but this is not checked. +@defun fset symbol definition +This function stores @var{definition} in the function cell of +@var{symbol}. The result is @var{definition}. Normally +@var{definition} should be a function or the name of a function, but +this is not checked. The argument @var{symbol} is an ordinary evaluated +argument. There are three normal uses of this function: @itemize @bullet @item -Copying one symbol's function definition to another. (In other words, -making an alternate name for a function.) +Copying one symbol's function definition to another---in other words, +making an alternate name for a function. (If you think of this as the +definition of the new name, you should use @code{defalias} instead of +@code{fset}; see @ref{Definition of defalias}.) @item Giving a symbol a function definition that is not a list and therefore cannot be made with @code{defun}. For example, you can use @code{fset} to give a symbol @code{s1} a function definition which is another symbol @code{s2}; then @code{s1} serves as an alias for whatever definition -@code{s2} presently has. +@code{s2} presently has. (Once again use @code{defalias} instead of +@code{fset} if you think of this as the definition of @code{s1}.) @item In constructs for defining or altering functions. If @code{defun} @@ -964,21 +1102,17 @@ were not a primitive, it could be written in Lisp (as a macro) using @code{fset}. @end itemize -Here are examples of the first two uses: +Here are examples of these uses: @example @group -;; @r{Give @code{first} the same definition @code{car} has.} -(fset 'first (symbol-function 'car)) - @result{} # -@end group -@group -(first '(1 2 3)) - @result{} 1 +;; @r{Save @code{foo}'s definition in @code{old-foo}.} +(fset 'old-foo (symbol-function 'foo)) @end group @group ;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.} +;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)} (fset 'xfirst 'car) @result{} car @end group @@ -1000,32 +1134,55 @@ Here are examples of the first two uses: (fset 'kill-two-lines "\^u2\^k") @result{} "\^u2\^k" @end group + +@group +;; @r{Here is a function that alters other functions.} +(defun copy-function-definition (new old) + "Define NEW with the same function definition as OLD." + (fset new (symbol-function old))) +@end group @end example +@end defun -See also the related function @code{defalias}, in @ref{Defining -Functions}. + @code{fset} is sometimes used to save the old definition of a +function before redefining it. That permits the new definition to +invoke the old definition. But it is unmodular and unclean for a Lisp +file to redefine a function defined elsewhere. If you want to modify +a function defined by another package, it is cleaner to use +@code{defadvice} (@pxref{Advising Functions}). + +@node Obsolete Functions +@section Declaring Functions Obsolete + +You can use @code{make-obsolete} to declare a function obsolete. This +indicates that the function may be removed at some stage in the future. + +@defun make-obsolete obsolete-name current-name &optional when +This function makes the byte compiler warn that the function +@var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the +warning message says to use @var{current-name} instead of +@var{obsolete-name}. @var{current-name} does not need to be an alias for +@var{obsolete-name}; it can be a different function with similar +functionality. If @var{current-name} is a string, it is the warning +message. + +If provided, @var{when} should be a string indicating when the function +was first made obsolete---for example, a date or a release number. @end defun - When writing a function that extends a previously defined function, -the following idiom is often used: +You can define a function as an alias and declare it obsolete at the +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 +defines it as an alias for the function @var{current-name}. It is +equivalent to the following: @example -(fset 'old-foo (symbol-function 'foo)) -(defun foo () - "Just like old-foo, except more so." -@group - (old-foo) - (more-so)) -@end group +(defalias @var{obsolete-name} @var{current-name} @var{docstring}) +(make-obsolete @var{obsolete-name} @var{current-name} @var{when}) @end example - -@noindent -This does not work properly if @code{foo} has been defined to autoload. -In such a case, when @code{foo} calls @code{old-foo}, Lisp attempts -to define @code{old-foo} by loading a file. Since this presumably -defines @code{foo} rather than @code{old-foo}, it does not produce the -proper results. The only way to avoid this problem is to make sure the -file is loaded before moving aside the old definition of @code{foo}. +@end defmac @node Inline Functions @section Inline Functions @@ -1050,20 +1207,104 @@ advantage of inline functions is greatest for small functions, you generally should not make large functions inline. It's possible to define a macro to expand into the same code that an -inline function would execute. But the macro would have a limitation: -you can use it only explicitly---a macro cannot be called with +inline function would execute. (@xref{Macros}.) But the macro would be +limited to direct use in expressions---a macro cannot be called with @code{apply}, @code{mapcar} and so on. Also, it takes some work to -convert an ordinary function into a macro. (@xref{Macros}.) To convert -it into an inline function is very easy; simply replace @code{defun} -with @code{defsubst}. Since each argument of an inline function is -evaluated exactly once, you needn't worry about how many times the -body uses the arguments, as you do for macros. (@xref{Argument -Evaluation}.) +convert an ordinary function into a macro. To convert it into an inline +function is very easy; simply replace @code{defun} with @code{defsubst}. +Since each argument of an inline function is evaluated exactly once, you +needn't worry about how many times the body uses the arguments, as you +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. -Emacs versions prior to 19 did not have inline functions. +@node Function Safety +@section Determining whether a Function is Safe to Call +@cindex function safety +@cindex safety of functions + +Some major modes such as SES call functions that are stored in user +files. (@inforef{Top, ,ses}, for more information on SES.) User +files sometimes have poor pedigrees---you can get a spreadsheet from +someone you've just met, or you can get one through email from someone +you've never met. So it is risky to call a function whose source code +is stored in a user file until you have determined that it is safe. + +@defun unsafep form &optional unsafep-vars +Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or +returns a list that describes why it might be unsafe. The argument +@var{unsafep-vars} is a list of symbols known to have temporary +bindings at this point; it is mainly used for internal recursive +calls. The current buffer is an implicit argument, which provides a +list of buffer-local bindings. +@end defun + +Being quick and simple, @code{unsafep} does a very light analysis and +rejects many Lisp expressions that are actually safe. There are no +known cases where @code{unsafep} returns @code{nil} for an unsafe +expression. However, a ``safe'' Lisp expression can return a string +with a @code{display} property, containing an associated Lisp +expression to be executed after the string is inserted into a buffer. +This associated expression can be a virus. In order to be safe, you +must delete properties from all strings calculated by user code before +inserting them into buffers. + +@ignore +What is a safe Lisp expression? Basically, it's an expression that +calls only built-in functions with no side effects (or only innocuous +ones). Innocuous side effects include displaying messages and +altering non-risky buffer-local variables (but not global variables). + +@table @dfn +@item Safe expression +@itemize +@item +An atom or quoted thing. +@item +A call to a safe function (see below), if all its arguments are +safe expressions. +@item +One of the special forms @code{and}, @code{catch}, @code{cond}, +@code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn}, +@code{while}, and @code{unwind-protect}], if all its arguments are +safe. +@item +A form that creates temporary bindings (@code{condition-case}, +@code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or +@code{let*}), if all args are safe and the symbols to be bound are not +explicitly risky (see @pxref{File Local Variables}). +@item +An assignment using @code{add-to-list}, @code{setq}, @code{push}, or +@code{pop}, if all args are safe and the symbols to be assigned are +not explicitly risky and they already have temporary or buffer-local +bindings. +@item +One of [apply, mapc, mapcar, mapconcat] if the first argument is a +safe explicit lambda and the other args are safe expressions. +@end itemize + +@item Safe function +@itemize +@item +A lambda containing safe expressions. +@item +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. +@end itemize + +The @code{side-effect-free} and @code{safe-function} properties are +provided for built-in functions and for low-level functions and macros +defined in @file{subr.el}. You can assign these properties for the +functions you write. +@end table +@end ignore @node Related Topics @section Other Topics Related to Functions @@ -1094,6 +1335,9 @@ See @ref{Eval}. @item funcall See @ref{Calling Functions}. +@item function +See @ref{Anonymous Functions}. + @item ignore See @ref{Calling Functions}. @@ -1112,10 +1356,16 @@ See @ref{Creating Symbols}. @item mapcar See @ref{Mapping Functions}. +@item map-char-table +See @ref{Char-Tables}. + @item mapconcat See @ref{Mapping Functions}. @item undefined -See @ref{Key Lookup}. +See @ref{Functions for Key Lookup}. @end table +@ignore + arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2 +@end ignore