X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/ba3dafc8c940c5c26edf0dd5e22c0c59a3b89dad..255d07dc33fc9b78acd47348372b1016ca27d210:/lispref/functions.texi diff --git a/lispref/functions.texi b/lispref/functions.texi index 67d68e40a9..427389b4a6 100644 --- a/lispref/functions.texi +++ b/lispref/functions.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 -@c Free Software Foundation, Inc. +@c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../info/functions @node Functions, Macros, Variables, Top @@ -18,10 +18,11 @@ 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. * 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 @@ -56,10 +57,10 @@ such as @code{car} or @code{append}. These functions are also called considered 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}. +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. @@ -112,10 +113,15 @@ 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. +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). @@ -410,7 +416,7 @@ of one or two complete sentences that summarize the function's purpose. 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 +@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. @@ -422,6 +428,20 @@ 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. This feature is +particularly useful for macro definitions. The @samp{\} is used to +avoid confusing the Emacs motion commands. + @node Function Names @section Naming a Function @cindex function definition @@ -557,9 +577,15 @@ defined is often done deliberately, and there is no way to distinguish deliberate redefinition from unintentional redefinition. @end defspec -@defun defalias name definition +@anchor{Definition of defalias} +@defun defalias name definition &optional docstring This special form defines the symbol @var{name} as a function, with definition @var{definition} (which can be any valid Lisp function). +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 @@ -572,6 +598,17 @@ purposes, it is better to use @code{fset}, which does not keep such records. @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}. @@ -675,8 +712,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 @@ -701,19 +738,21 @@ 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 several such functions; -@code{mapcar} and @code{mapconcat}, which scan a list, are described -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. + 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}). +@anchor{Definition of mapcar} @defun mapcar function sequence @code{mapcar} applies @var{function} to each element of @var{sequence} in turn, and returns a list of the results. @@ -745,10 +784,10 @@ length of @var{sequence}. "Apply FUNCTION to successive cars of all ARGS. Return the list of results." ;; @r{If no list is exhausted,} - (if (not (memq 'nil args)) + (if (not (memq nil args)) ;; @r{apply function to @sc{car}s.} - (cons (apply function (mapcar 'car args)) - (apply 'mapcar* function + (cons (apply function (mapcar 'car args)) + (apply 'mapcar* function ;; @r{Recurse for rest of elements.} (mapcar 'cdr args))))) @end group @@ -778,7 +817,7 @@ The argument @var{function} must be a function that can take one 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 @@ -840,7 +879,7 @@ 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 + Here we define a function @code{change-property} which uses a function as its third argument: @example @@ -914,7 +953,7 @@ comment: @cindex @samp{#'} syntax The read syntax @code{#'} is a short-hand for using @code{function}. -For example, +For example, @example #'(lambda (x) (* x x)) @@ -936,8 +975,8 @@ 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. + @xref{describe-symbols example}, for a realistic example using +@code{function} and an anonymous function. @node Function Cells @section Accessing Function Cell Contents @@ -946,8 +985,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 @@ -1002,8 +1041,9 @@ 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{Void 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 @@ -1039,7 +1079,7 @@ There are three normal uses of this 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}.) +@code{fset}; see @ref{Definition of defalias}.) @item Giving a symbol a function definition that is not a list and therefore @@ -1157,7 +1197,92 @@ 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. -@c 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 @@ -1216,6 +1341,9 @@ See @ref{Char-Tables}. 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