X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/9c52bf473cf95c2a00fc551f511db09223d68b47..59367f560857e95efebc6c4662701af711e29b23:/lispref/functions.texi diff --git a/lispref/functions.texi b/lispref/functions.texi index fbcbc64180..ece586f79e 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 +@c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/functions @node Functions, Macros, Variables, Top @@ -21,6 +22,7 @@ define them. * Function Cells:: Accessing or setting the function definition of a symbol. * 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 @@ -54,18 +56,18 @@ such as @code{car} or @code{append}. These functions are also called @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 +81,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 +112,11 @@ 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 macro. +@end defun + @defun subrp object This function returns @code{t} if @var{object} is a built-in function (i.e., a Lisp primitive). @@ -136,6 +145,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 +169,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 +185,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 +196,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,14 +205,15 @@ 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. @xref{Local Variables}. - The documentation string is an actual string that serves to describe -the function for the Emacs help facilities. @xref{Function Documentation}. + The documentation string is a Lisp string object placed within the +function definition to describe the function for the Emacs help +facilities. @xref{Function Documentation}. The interactive declaration is a list of the form @code{(interactive @var{code-string})}. This declares how to provide arguments if the @@ -245,8 +267,8 @@ this example: @noindent This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5 -4)} from left to right. Then it applies the lambda expression applied -to the argument values 1, 6 and 1 to produce the value 8. +4)} from left to right. Then it applies the lambda expression to the +argument values 1, 6 and 1 to produce the value 8. It is not often useful to write a lambda expression as the @sc{car} of a form in this way. You can get the same result, of making local @@ -262,7 +284,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 @@ -277,7 +299,7 @@ arguments to be omitted. For example, the function @code{substring} accepts three arguments---a string, the start index and the end index---but the third argument defaults to the @var{length} of the string if you omit it. It is also convenient for certain functions to -accept an indefinite number of arguments, as the functions @code{and} +accept an indefinite number of arguments, as the functions @code{list} and @code{+} do. @cindex optional arguments @@ -310,18 +332,19 @@ that unless the lambda list uses @code{&rest}. In that case, there may be any number of extra actual arguments. If actual arguments for the optional and rest variables are omitted, -then they always default to @code{nil}. However, the body of the function -is free to consider @code{nil} an abbreviation for some other meaningful -value. This is what @code{substring} does; @code{nil} as the third argument -means to use the length of the string supplied. There is no way for the +then they always default to @code{nil}. There is no way for the function to distinguish between an explicit argument of @code{nil} and -an omitted argument. +an omitted argument. However, the body of the function is free to +consider @code{nil} an abbreviation for some other meaningful value. +This is what @code{substring} does; @code{nil} as the third argument to +@code{substring} means to use the length of the string supplied. @cindex CL note---default optional arg @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: @@ -342,9 +365,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: @@ -373,22 +398,22 @@ 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 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. @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. +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. You may wonder how the documentation string could be optional, since there are required components of the function that follow it (the body). @@ -407,7 +432,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} @@ -446,11 +471,16 @@ 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 Named Functions +@section Defining Functions @cindex defining a function We usually give a name to a function when it is first created. This @@ -471,8 +501,8 @@ 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 +keywords @code{&optional} and @code{&rest}. 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 @@ -530,11 +560,22 @@ deliberate redefinition from unintentional redefinition. @defun defalias name definition This special form defines the symbol @var{name} as a function, with -definition @var{definition}. 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}). +definition @var{definition} (which can be any valid Lisp function). + +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. @end defun + 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 @@ -544,16 +585,18 @@ records which file defined the function (@pxref{Unloading}). anything until you @dfn{call} them, i.e., tell them to run. Calling a function is also known as @dfn{invocation}. - The most common way of invoking a function is by evaluating a list. For -example, evaluating the list @code{(concat "a" "b")} calls the function -@code{concat}. @xref{Evaluation}, for a description of evaluation. + The most common way of invoking a function is by evaluating a list. +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}. +name it calls is written in your 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 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 @@ -593,15 +636,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 this list is @dfn{appended} to the other -arguments. +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 @@ -642,8 +686,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 @@ -659,16 +703,24 @@ This function ignores any arguments and returns @code{nil}. @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; +list or other collection. Emacs Lisp has several 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}. +here. @xref{Creating Symbols}, for the function @code{mapatoms} which +maps over the symbols in an obarray. @xref{Hash Access}, 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 -@code{mapcar} applies @var{function} to each element of @var{sequence} in -turn. The results are made into a @code{nil}-terminated list. +@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}. @@ -690,14 +742,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 + ;; @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 @@ -709,6 +761,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. @@ -717,7 +776,9 @@ 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 @@ -776,56 +837,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)) @@ -833,20 +888,55 @@ 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 +@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 + See @code{documentation} in @ref{Accessing Documentation}, for a realistic example using @code{function} and an anonymous function. @@ -857,6 +947,9 @@ 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}. + @defun symbol-function symbol @kindex void-function This returns the object in the function cell of @var{symbol}. If the @@ -896,8 +989,7 @@ as a function, it signals a @code{void-function} error. @code{void}. The symbols @code{nil} and @code{void} are Lisp objects, and can be stored into a function cell just as any other object can be (and they can be valid functions if you define them in turn with -@code{defun}); but @code{nil} or @code{void} is @emph{an object}. A -void function cell contains no object whatsoever. +@code{defun}). A void function cell contains no object whatsoever. You can test the voidness of a symbol's function definition with @code{fboundp}. After you have given a symbol a function definition, you @@ -912,16 +1004,20 @@ 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}.) +error. (See also @code{makunbound}, in @ref{Void Variables}.) @example @group (defun foo (x) x) - @result{} x + @result{} foo +@end group +@group +(foo 1) + @result{}1 @end group @group (fmakunbound 'foo) - @result{} x + @result{} foo @end group @group (foo 1) @@ -930,22 +1026,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{Defining Functions}.) @item Giving a symbol a function definition that is not a list and therefore -cannot be made with @code{defun}. @xref{Classifying Lists}, for an -example of this usage. +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. (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} @@ -953,21 +1056,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 @@ -989,11 +1088,18 @@ 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 When writing a function that extends a previously defined function, -the following idiom is often used: +the following idiom is sometimes used: @example (fset 'old-foo (symbol-function 'foo)) @@ -1013,8 +1119,9 @@ 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}. -See also the function @code{indirect-function} in @ref{Function -Indirection}. + But it is unmodular and unclean, in any case, for a Lisp file to +redefine a function defined elsewhere. It is cleaner to use the advice +facility (@pxref{Advising Functions}). @node Inline Functions @section Inline Functions @@ -1039,20 +1146,108 @@ 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}.) - -Inline functions can be used and open coded later on in the same file, +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 +@cindex virus detection +@cindex Trojan-horse detection +@cindex DDoS attacks + +Some major modes such as SES (see @pxref{Top,,,ses}) will call +functions that are stored in user files. 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. +Such files can contain viruses and other Trojan horses that could +corrupt your operating system environment, delete your files, or even +turn your computer into a DDoS zombie! To avoid this terrible fate, +you should not 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 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 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. + +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 [and, catch, cond, if, or, prog1, prog2, +progn, while, unwind-protect], if all its arguments are safe. +@item +A form that creates temporary bindings [condition-case, dolist, +dotimes, lambda, let, let*], if all args are safe and the symbols to +be bound are not explicitly risky (see @pxref{File Local Variables}). +@item +An assignment [add-to-list, setq, push, 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-nil @code{side-effect-free} property. +@item +A symbol with a non-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 + + +@c Emacs versions prior to 19 did not have inline functions. @node Related Topics @section Other Topics Related to Functions @@ -1083,6 +1278,9 @@ See @ref{Eval}. @item funcall See @ref{Calling Functions}. +@item function +See @ref{Anonymous Functions}. + @item ignore See @ref{Calling Functions}. @@ -1101,6 +1299,9 @@ See @ref{Creating Symbols}. @item mapcar See @ref{Mapping Functions}. +@item map-char-table +See @ref{Char-Tables}. + @item mapconcat See @ref{Mapping Functions}.