Misc docfixes.
[bpt/emacs.git] / doc / lispref / functions.texi
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/functions
7 @node Functions, Macros, Variables, Top
8 @chapter Functions
9
10 A Lisp program is composed mainly of Lisp functions. This chapter
11 explains what functions are, how they accept arguments, and how to
12 define them.
13
14 @menu
15 * What Is a Function:: Lisp functions vs. primitives; terminology.
16 * Lambda Expressions:: How functions are expressed as Lisp objects.
17 * Function Names:: A symbol can serve as the name of a function.
18 * Defining Functions:: Lisp expressions for defining functions.
19 * Calling Functions:: How to use an existing function.
20 * Mapping Functions:: Applying a function to each element of a list, etc.
21 * Anonymous Functions:: Lambda expressions are functions with no names.
22 * Function Cells:: Accessing or setting the function definition
23 of a symbol.
24 * Closures:: Functions that enclose a lexical environment.
25 * Obsolete Functions:: Declaring functions obsolete.
26 * Inline Functions:: Functions that the compiler will expand inline.
27 * Declaring Functions:: Telling the compiler that a function is defined.
28 * Function Safety:: Determining whether a function is safe to call.
29 * Related Topics:: Cross-references to specific Lisp primitives
30 that have a special bearing on how functions work.
31 @end menu
32
33 @node What Is a Function
34 @section What Is a Function?
35
36 @cindex return value
37 @cindex value of function
38 @cindex argument
39 In a general sense, a function is a rule for carrying out a
40 computation given input values called @dfn{arguments}. The result of
41 the computation is called the @dfn{value} or @dfn{return value} of the
42 function. The computation can also have side effects, such as lasting
43 changes in the values of variables or the contents of data structures.
44
45 In most computer languages, every function has a name. But in Lisp,
46 a function in the strictest sense has no name: it is an object which
47 can @emph{optionally} be associated with a symbol (e.g.@: @code{car})
48 that serves as the function name. @xref{Function Names}. When a
49 function has been given a name, we usually also refer to that symbol
50 as a ``function'' (e.g.@: we refer to ``the function @code{car}'').
51 In this manual, the distinction between a function name and the
52 function object itself is usually unimportant, but we will take note
53 wherever it is relevant.
54
55 Certain function-like objects, called @dfn{special forms} and
56 @dfn{macros}, also accept arguments to carry out computations.
57 However, as explained below, these are not considered functions in
58 Emacs Lisp.
59
60 Here are important terms for functions and function-like objects:
61
62 @table @dfn
63 @item lambda expression
64 A function (in the strict sense, i.e.@: a function object) which is
65 written in Lisp. These are described in the following section.
66 @ifnottex
67 @xref{Lambda Expressions}.
68 @end ifnottex
69
70 @item primitive
71 @cindex primitive
72 @cindex subr
73 @cindex built-in function
74 A function which is callable from Lisp but is actually written in C.
75 Primitives are also called @dfn{built-in functions}, or @dfn{subrs}.
76 Examples include functions like @code{car} and @code{append}. In
77 addition, all special forms (see below) are also considered
78 primitives.
79
80 Usually, a function is implemented as a primitive because it is a
81 fundamental part of Lisp (e.g.@: @code{car}), or because it provides a
82 low-level interface to operating system services, or because it needs
83 to run fast. Unlike functions defined in Lisp, primitives can be
84 modified or added only by changing the C sources and recompiling
85 Emacs. See @ref{Writing Emacs Primitives}.
86
87 @item special form
88 A primitive that is like a function but does not evaluate all of its
89 arguments in the usual way. It may evaluate only some of the
90 arguments, or may evaluate them in an unusual order, or several times.
91 Examples include @code{if}, @code{and}, and @code{while}.
92 @xref{Special Forms}.
93
94 @item macro
95 @cindex macro
96 A construct defined in Lisp, which differs from a function in that it
97 translates a Lisp expression into another expression which is to be
98 evaluated instead of the original expression. Macros enable Lisp
99 programmers to do the sorts of things that special forms can do.
100 @xref{Macros}.
101
102 @item command
103 @cindex command
104 An object which can be invoked via the @code{command-execute}
105 primitive, usually due to the user typing in a key sequence
106 @dfn{bound} to that command. @xref{Interactive Call}. A command is
107 usually a function; if the function is written in Lisp, it is made
108 into a command by an @code{interactive} form in the function
109 definition (@pxref{Defining Commands}). Commands that are functions
110 can also be called from Lisp expressions, just like other functions.
111
112 Keyboard macros (strings and vectors) are commands also, even though
113 they are not functions. @xref{Keyboard Macros}. We say that a symbol
114 is a command if its function cell contains a command (@pxref{Symbol
115 Components}); such a @dfn{named command} can be invoked with
116 @kbd{M-x}.
117
118 @item closure
119 A function object that is much like a lambda expression, except that
120 it also encloses an ``environment'' of lexical variable bindings.
121 @xref{Closures}.
122
123 @item byte-code function
124 A function that has been compiled by the byte compiler.
125 @xref{Byte-Code Type}.
126
127 @item autoload object
128 @cindex autoload object
129 A place-holder for a real function. If the autoload object is called,
130 Emacs loads the file containing the definition of the real function,
131 and then calls the real function. @xref{Autoload}.
132 @end table
133
134 You can use the function @code{functionp} to test if an object is a
135 function:
136
137 @defun functionp object
138 This function returns @code{t} if @var{object} is any kind of
139 function, i.e.@: can be passed to @code{funcall}. Note that
140 @code{functionp} returns @code{t} for symbols that are function names,
141 and returns @code{nil} for special forms.
142 @end defun
143
144 @noindent
145 Unlike @code{functionp}, the next three functions do @emph{not} treat
146 a symbol as its function definition.
147
148 @defun subrp object
149 This function returns @code{t} if @var{object} is a built-in function
150 (i.e., a Lisp primitive).
151
152 @example
153 @group
154 (subrp 'message) ; @r{@code{message} is a symbol,}
155 @result{} nil ; @r{not a subr object.}
156 @end group
157 @group
158 (subrp (symbol-function 'message))
159 @result{} t
160 @end group
161 @end example
162 @end defun
163
164 @defun byte-code-function-p object
165 This function returns @code{t} if @var{object} is a byte-code
166 function. For example:
167
168 @example
169 @group
170 (byte-code-function-p (symbol-function 'next-line))
171 @result{} t
172 @end group
173 @end example
174 @end defun
175
176 @defun subr-arity subr
177 This function provides information about the argument list of a
178 primitive, @var{subr}. The returned value is a pair
179 @code{(@var{min} . @var{max})}. @var{min} is the minimum number of
180 args. @var{max} is the maximum number or the symbol @code{many}, for a
181 function with @code{&rest} arguments, or the symbol @code{unevalled} if
182 @var{subr} is a special form.
183 @end defun
184
185 @node Lambda Expressions
186 @section Lambda Expressions
187 @cindex lambda expression
188
189 A lambda expression is a function object written in Lisp. Here is
190 an example:
191
192 @example
193 (lambda (x)
194 "Return the hyperbolic cosine of X."
195 (* 0.5 (+ (exp x) (exp (- x)))))
196 @end example
197
198 @noindent
199 In Emacs Lisp, such a list is valid as an expression---it evaluates to
200 itself. But its main use is not to be evaluated as an expression, but
201 to be called as a function.
202
203 A lambda expression, by itself, has no name; it is an @dfn{anonymous
204 function}. Although lambda expressions can be used this way
205 (@pxref{Anonymous Functions}), they are more commonly associated with
206 symbols to make @dfn{named functions} (@pxref{Function Names}).
207 Before going into these details, the following subsections describe
208 the components of a lambda expression and what they do.
209
210 @menu
211 * Lambda Components:: The parts of a lambda expression.
212 * Simple Lambda:: A simple example.
213 * Argument List:: Details and special features of argument lists.
214 * Function Documentation:: How to put documentation in a function.
215 @end menu
216
217 @node Lambda Components
218 @subsection Components of a Lambda Expression
219
220 A lambda expression is a list that looks like this:
221
222 @example
223 (lambda (@var{arg-variables}@dots{})
224 [@var{documentation-string}]
225 [@var{interactive-declaration}]
226 @var{body-forms}@dots{})
227 @end example
228
229 @cindex lambda list
230 The first element of a lambda expression is always the symbol
231 @code{lambda}. This indicates that the list represents a function. The
232 reason functions are defined to start with @code{lambda} is so that
233 other lists, intended for other uses, will not accidentally be valid as
234 functions.
235
236 The second element is a list of symbols---the argument variable names.
237 This is called the @dfn{lambda list}. When a Lisp function is called,
238 the argument values are matched up against the variables in the lambda
239 list, which are given local bindings with the values provided.
240 @xref{Local Variables}.
241
242 The documentation string is a Lisp string object placed within the
243 function definition to describe the function for the Emacs help
244 facilities. @xref{Function Documentation}.
245
246 The interactive declaration is a list of the form @code{(interactive
247 @var{code-string})}. This declares how to provide arguments if the
248 function is used interactively. Functions with this declaration are called
249 @dfn{commands}; they can be called using @kbd{M-x} or bound to a key.
250 Functions not intended to be called in this way should not have interactive
251 declarations. @xref{Defining Commands}, for how to write an interactive
252 declaration.
253
254 @cindex body of function
255 The rest of the elements are the @dfn{body} of the function: the Lisp
256 code to do the work of the function (or, as a Lisp programmer would say,
257 ``a list of Lisp forms to evaluate''). The value returned by the
258 function is the value returned by the last element of the body.
259
260 @node Simple Lambda
261 @subsection A Simple Lambda Expression Example
262
263 Consider the following example:
264
265 @example
266 (lambda (a b c) (+ a b c))
267 @end example
268
269 @noindent
270 We can call this function by passing it to @code{funcall}, like this:
271
272 @example
273 @group
274 (funcall (lambda (a b c) (+ a b c))
275 1 2 3)
276 @end group
277 @end example
278
279 @noindent
280 This call evaluates the body of the lambda expression with the variable
281 @code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.
282 Evaluation of the body adds these three numbers, producing the result 6;
283 therefore, this call to the function returns the value 6.
284
285 Note that the arguments can be the results of other function calls, as in
286 this example:
287
288 @example
289 @group
290 (funcall (lambda (a b c) (+ a b c))
291 1 (* 2 3) (- 5 4))
292 @end group
293 @end example
294
295 @noindent
296 This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
297 4)} from left to right. Then it applies the lambda expression to the
298 argument values 1, 6 and 1 to produce the value 8.
299
300 As these examples show, you can use a form with a lambda expression
301 as its @sc{car} to make local variables and give them values. In the
302 old days of Lisp, this technique was the only way to bind and
303 initialize local variables. But nowadays, it is clearer to use the
304 special form @code{let} for this purpose (@pxref{Local Variables}).
305 Lambda expressions are mainly used as anonymous functions for passing
306 as arguments to other functions (@pxref{Anonymous Functions}), or
307 stored as symbol function definitions to produce named functions
308 (@pxref{Function Names}).
309
310 @node Argument List
311 @subsection Other Features of Argument Lists
312 @kindex wrong-number-of-arguments
313 @cindex argument binding
314 @cindex binding arguments
315 @cindex argument lists, features
316
317 Our simple sample function, @code{(lambda (a b c) (+ a b c))},
318 specifies three argument variables, so it must be called with three
319 arguments: if you try to call it with only two arguments or four
320 arguments, you get a @code{wrong-number-of-arguments} error.
321
322 It is often convenient to write a function that allows certain
323 arguments to be omitted. For example, the function @code{substring}
324 accepts three arguments---a string, the start index and the end
325 index---but the third argument defaults to the @var{length} of the
326 string if you omit it. It is also convenient for certain functions to
327 accept an indefinite number of arguments, as the functions @code{list}
328 and @code{+} do.
329
330 @cindex optional arguments
331 @cindex rest arguments
332 @kindex &optional
333 @kindex &rest
334 To specify optional arguments that may be omitted when a function
335 is called, simply include the keyword @code{&optional} before the optional
336 arguments. To specify a list of zero or more extra arguments, include the
337 keyword @code{&rest} before one final argument.
338
339 Thus, the complete syntax for an argument list is as follows:
340
341 @example
342 @group
343 (@var{required-vars}@dots{}
344 @r{[}&optional @var{optional-vars}@dots{}@r{]}
345 @r{[}&rest @var{rest-var}@r{]})
346 @end group
347 @end example
348
349 @noindent
350 The square brackets indicate that the @code{&optional} and @code{&rest}
351 clauses, and the variables that follow them, are optional.
352
353 A call to the function requires one actual argument for each of the
354 @var{required-vars}. There may be actual arguments for zero or more of
355 the @var{optional-vars}, and there cannot be any actual arguments beyond
356 that unless the lambda list uses @code{&rest}. In that case, there may
357 be any number of extra actual arguments.
358
359 If actual arguments for the optional and rest variables are omitted,
360 then they always default to @code{nil}. There is no way for the
361 function to distinguish between an explicit argument of @code{nil} and
362 an omitted argument. However, the body of the function is free to
363 consider @code{nil} an abbreviation for some other meaningful value.
364 This is what @code{substring} does; @code{nil} as the third argument to
365 @code{substring} means to use the length of the string supplied.
366
367 @cindex CL note---default optional arg
368 @quotation
369 @b{Common Lisp note:} Common Lisp allows the function to specify what
370 default value to use when an optional argument is omitted; Emacs Lisp
371 always uses @code{nil}. Emacs Lisp does not support ``supplied-p''
372 variables that tell you whether an argument was explicitly passed.
373 @end quotation
374
375 For example, an argument list that looks like this:
376
377 @example
378 (a b &optional c d &rest e)
379 @end example
380
381 @noindent
382 binds @code{a} and @code{b} to the first two actual arguments, which are
383 required. If one or two more arguments are provided, @code{c} and
384 @code{d} are bound to them respectively; any arguments after the first
385 four are collected into a list and @code{e} is bound to that list. If
386 there are only two arguments, @code{c} is @code{nil}; if two or three
387 arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}
388 is @code{nil}.
389
390 There is no way to have required arguments following optional
391 ones---it would not make sense. To see why this must be so, suppose
392 that @code{c} in the example were optional and @code{d} were required.
393 Suppose three actual arguments are given; which variable would the
394 third argument be for? Would it be used for the @var{c}, or for
395 @var{d}? One can argue for both possibilities. Similarly, it makes
396 no sense to have any more arguments (either required or optional)
397 after a @code{&rest} argument.
398
399 Here are some examples of argument lists and proper calls:
400
401 @example
402 (funcall (lambda (n) (1+ n)) ; @r{One required:}
403 1) ; @r{requires exactly one argument.}
404 @result{} 2
405 (funcall (lambda (n &optional n1) ; @r{One required and one optional:}
406 (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
407 1 2)
408 @result{} 3
409 (funcall (lambda (n &rest ns) ; @r{One required and one rest:}
410 (+ n (apply '+ ns))) ; @r{1 or more arguments.}
411 1 2 3 4 5)
412 @result{} 15
413 @end example
414
415 @node Function Documentation
416 @subsection Documentation Strings of Functions
417 @cindex documentation of function
418
419 A lambda expression may optionally have a @dfn{documentation string}
420 just after the lambda list. This string does not affect execution of
421 the function; it is a kind of comment, but a systematized comment
422 which actually appears inside the Lisp world and can be used by the
423 Emacs help facilities. @xref{Documentation}, for how the
424 documentation string is accessed.
425
426 It is a good idea to provide documentation strings for all the
427 functions in your program, even those that are called only from within
428 your program. Documentation strings are like comments, except that they
429 are easier to access.
430
431 The first line of the documentation string should stand on its own,
432 because @code{apropos} displays just this first line. It should consist
433 of one or two complete sentences that summarize the function's purpose.
434
435 The start of the documentation string is usually indented in the
436 source file, but since these spaces come before the starting
437 double-quote, they are not part of the string. Some people make a
438 practice of indenting any additional lines of the string so that the
439 text lines up in the program source. @emph{That is a mistake.} The
440 indentation of the following lines is inside the string; what looks
441 nice in the source code will look ugly when displayed by the help
442 commands.
443
444 You may wonder how the documentation string could be optional, since
445 there are required components of the function that follow it (the body).
446 Since evaluation of a string returns that string, without any side effects,
447 it has no effect if it is not the last form in the body. Thus, in
448 practice, there is no confusion between the first form of the body and the
449 documentation string; if the only body form is a string then it serves both
450 as the return value and as the documentation.
451
452 The last line of the documentation string can specify calling
453 conventions different from the actual function arguments. Write
454 text like this:
455
456 @example
457 \(fn @var{arglist})
458 @end example
459
460 @noindent
461 following a blank line, at the beginning of the line, with no newline
462 following it inside the documentation string. (The @samp{\} is used
463 to avoid confusing the Emacs motion commands.) The calling convention
464 specified in this way appears in help messages in place of the one
465 derived from the actual arguments of the function.
466
467 This feature is particularly useful for macro definitions, since the
468 arguments written in a macro definition often do not correspond to the
469 way users think of the parts of the macro call.
470
471 @node Function Names
472 @section Naming a Function
473 @cindex function definition
474 @cindex named function
475 @cindex function name
476
477 A symbol can serve as the name of a function. This happens when the
478 symbol's @dfn{function cell} (@pxref{Symbol Components}) contains a
479 function object (e.g.@: a lambda expression). Then the symbol itself
480 becomes a valid, callable function, equivalent to the function object
481 in its function cell.
482
483 The contents of the function cell are also called the symbol's
484 @dfn{function definition}. The procedure of using a symbol's function
485 definition in place of the symbol is called @dfn{symbol function
486 indirection}; see @ref{Function Indirection}. If you have not given a
487 symbol a function definition, its function cell is said to be
488 @dfn{void}, and it cannot be used as a function.
489
490 In practice, nearly all functions have names, and are referred to by
491 their names. You can create a named Lisp function by defining a
492 lambda expression and putting it in a function cell (@pxref{Function
493 Cells}). However, it is more common to use the @code{defun} special
494 form, described in the next section.
495 @ifnottex
496 @xref{Defining Functions}.
497 @end ifnottex
498
499 We give functions names because it is convenient to refer to them by
500 their names in Lisp expressions. Also, a named Lisp function can
501 easily refer to itself---it can be recursive. Furthermore, primitives
502 can only be referred to textually by their names, since primitive
503 function objects (@pxref{Primitive Function Type}) have no read
504 syntax.
505
506 A function need not have a unique name. A given function object
507 @emph{usually} appears in the function cell of only one symbol, but
508 this is just a convention. It is easy to store it in several symbols
509 using @code{fset}; then each of the symbols is a valid name for the
510 same function.
511
512 Note that a symbol used as a function name may also be used as a
513 variable; these two uses of a symbol are independent and do not
514 conflict. (This is not the case in some dialects of Lisp, like
515 Scheme.)
516
517 @node Defining Functions
518 @section Defining Functions
519 @cindex defining a function
520
521 We usually give a name to a function when it is first created. This
522 is called @dfn{defining a function}, and it is done with the
523 @code{defun} special form.
524
525 @defspec defun name argument-list body-forms...
526 @code{defun} is the usual way to define new Lisp functions. It
527 defines the symbol @var{name} as a function that looks like this:
528
529 @example
530 (lambda @var{argument-list} . @var{body-forms})
531 @end example
532
533 @code{defun} stores this lambda expression in the function cell of
534 @var{name}. It returns the value @var{name}, but usually we ignore this
535 value.
536
537 As described previously, @var{argument-list} is a list of argument
538 names and may include the keywords @code{&optional} and @code{&rest}.
539 Also, the first two of the @var{body-forms} may be a documentation
540 string and an interactive declaration. @xref{Lambda Components}.
541
542 Here are some examples:
543
544 @example
545 @group
546 (defun foo () 5)
547 @result{} foo
548 @end group
549 @group
550 (foo)
551 @result{} 5
552 @end group
553
554 @group
555 (defun bar (a &optional b &rest c)
556 (list a b c))
557 @result{} bar
558 @end group
559 @group
560 (bar 1 2 3 4 5)
561 @result{} (1 2 (3 4 5))
562 @end group
563 @group
564 (bar 1)
565 @result{} (1 nil nil)
566 @end group
567 @group
568 (bar)
569 @error{} Wrong number of arguments.
570 @end group
571
572 @group
573 (defun capitalize-backwards ()
574 "Upcase the last letter of the word at point."
575 (interactive)
576 (backward-word 1)
577 (forward-word 1)
578 (backward-char 1)
579 (capitalize-word 1))
580 @result{} capitalize-backwards
581 @end group
582 @end example
583
584 Be careful not to redefine existing functions unintentionally.
585 @code{defun} redefines even primitive functions such as @code{car}
586 without any hesitation or notification. Emacs does not prevent you
587 from doing this, because redefining a function is sometimes done
588 deliberately, and there is no way to distinguish deliberate
589 redefinition from unintentional redefinition.
590 @end defspec
591
592 @cindex function aliases
593 @defun defalias name definition &optional docstring
594 @anchor{Definition of defalias}
595 This special form defines the symbol @var{name} as a function, with
596 definition @var{definition} (which can be any valid Lisp function).
597 It returns @var{definition}.
598
599 If @var{docstring} is non-@code{nil}, it becomes the function
600 documentation of @var{name}. Otherwise, any documentation provided by
601 @var{definition} is used.
602
603 The proper place to use @code{defalias} is where a specific function
604 name is being defined---especially where that name appears explicitly in
605 the source file being loaded. This is because @code{defalias} records
606 which file defined the function, just like @code{defun}
607 (@pxref{Unloading}).
608
609 By contrast, in programs that manipulate function definitions for other
610 purposes, it is better to use @code{fset}, which does not keep such
611 records. @xref{Function Cells}.
612 @end defun
613
614 You cannot create a new primitive function with @code{defun} or
615 @code{defalias}, but you can use them to change the function definition of
616 any symbol, even one such as @code{car} or @code{x-popup-menu} whose
617 normal definition is a primitive. However, this is risky: for
618 instance, it is next to impossible to redefine @code{car} without
619 breaking Lisp completely. Redefining an obscure function such as
620 @code{x-popup-menu} is less dangerous, but it still may not work as
621 you expect. If there are calls to the primitive from C code, they
622 call the primitive's C definition directly, so changing the symbol's
623 definition will have no effect on them.
624
625 See also @code{defsubst}, which defines a function like @code{defun}
626 and tells the Lisp compiler to perform inline expansion on it.
627 @xref{Inline Functions}.
628
629 @node Calling Functions
630 @section Calling Functions
631 @cindex function invocation
632 @cindex calling a function
633
634 Defining functions is only half the battle. Functions don't do
635 anything until you @dfn{call} them, i.e., tell them to run. Calling a
636 function is also known as @dfn{invocation}.
637
638 The most common way of invoking a function is by evaluating a list.
639 For example, evaluating the list @code{(concat "a" "b")} calls the
640 function @code{concat} with arguments @code{"a"} and @code{"b"}.
641 @xref{Evaluation}, for a description of evaluation.
642
643 When you write a list as an expression in your program, you specify
644 which function to call, and how many arguments to give it, in the text
645 of the program. Usually that's just what you want. Occasionally you
646 need to compute at run time which function to call. To do that, use
647 the function @code{funcall}. When you also need to determine at run
648 time how many arguments to pass, use @code{apply}.
649
650 @defun funcall function &rest arguments
651 @code{funcall} calls @var{function} with @var{arguments}, and returns
652 whatever @var{function} returns.
653
654 Since @code{funcall} is a function, all of its arguments, including
655 @var{function}, are evaluated before @code{funcall} is called. This
656 means that you can use any expression to obtain the function to be
657 called. It also means that @code{funcall} does not see the
658 expressions you write for the @var{arguments}, only their values.
659 These values are @emph{not} evaluated a second time in the act of
660 calling @var{function}; the operation of @code{funcall} is like the
661 normal procedure for calling a function, once its arguments have
662 already been evaluated.
663
664 The argument @var{function} must be either a Lisp function or a
665 primitive function. Special forms and macros are not allowed, because
666 they make sense only when given the ``unevaluated'' argument
667 expressions. @code{funcall} cannot provide these because, as we saw
668 above, it never knows them in the first place.
669
670 @example
671 @group
672 (setq f 'list)
673 @result{} list
674 @end group
675 @group
676 (funcall f 'x 'y 'z)
677 @result{} (x y z)
678 @end group
679 @group
680 (funcall f 'x 'y '(z))
681 @result{} (x y (z))
682 @end group
683 @group
684 (funcall 'and t nil)
685 @error{} Invalid function: #<subr and>
686 @end group
687 @end example
688
689 Compare these examples with the examples of @code{apply}.
690 @end defun
691
692 @defun apply function &rest arguments
693 @code{apply} calls @var{function} with @var{arguments}, just like
694 @code{funcall} but with one difference: the last of @var{arguments} is a
695 list of objects, which are passed to @var{function} as separate
696 arguments, rather than a single list. We say that @code{apply}
697 @dfn{spreads} this list so that each individual element becomes an
698 argument.
699
700 @code{apply} returns the result of calling @var{function}. As with
701 @code{funcall}, @var{function} must either be a Lisp function or a
702 primitive function; special forms and macros do not make sense in
703 @code{apply}.
704
705 @example
706 @group
707 (setq f 'list)
708 @result{} list
709 @end group
710 @group
711 (apply f 'x 'y 'z)
712 @error{} Wrong type argument: listp, z
713 @end group
714 @group
715 (apply '+ 1 2 '(3 4))
716 @result{} 10
717 @end group
718 @group
719 (apply '+ '(1 2 3 4))
720 @result{} 10
721 @end group
722
723 @group
724 (apply 'append '((a b c) nil (x y z) nil))
725 @result{} (a b c x y z)
726 @end group
727 @end example
728
729 For an interesting example of using @code{apply}, see @ref{Definition
730 of mapcar}.
731 @end defun
732
733 @cindex partial application of functions
734 @cindex currying
735 Sometimes it is useful to fix some of the function's arguments at
736 certain values, and leave the rest of arguments for when the function
737 is actually called. The act of fixing some of the function's
738 arguments is called @dfn{partial application} of the function@footnote{
739 This is related to, but different from @dfn{currying}, which
740 transforms a function that takes multiple arguments in such a way that
741 it can be called as a chain of functions, each one with a single
742 argument.}.
743 The result is a new function that accepts the rest of
744 arguments and calls the original function with all the arguments
745 combined.
746
747 Here's how to do partial application in Emacs Lisp:
748
749 @defun apply-partially func &rest args
750 This function returns a new function which, when called, will call
751 @var{func} with the list of arguments composed from @var{args} and
752 additional arguments specified at the time of the call. If @var{func}
753 accepts @var{n} arguments, then a call to @code{apply-partially} with
754 @w{@code{@var{m} < @var{n}}} arguments will produce a new function of
755 @w{@code{@var{n} - @var{m}}} arguments.
756
757 Here's how we could define the built-in function @code{1+}, if it
758 didn't exist, using @code{apply-partially} and @code{+}, another
759 built-in function:
760
761 @example
762 @group
763 (defalias '1+ (apply-partially '+ 1)
764 "Increment argument by one.")
765 @end group
766 @group
767 (1+ 10)
768 @result{} 11
769 @end group
770 @end example
771 @end defun
772
773 @cindex functionals
774 It is common for Lisp functions to accept functions as arguments or
775 find them in data structures (especially in hook variables and property
776 lists) and call them using @code{funcall} or @code{apply}. Functions
777 that accept function arguments are often called @dfn{functionals}.
778
779 Sometimes, when you call a functional, it is useful to supply a no-op
780 function as the argument. Here are two different kinds of no-op
781 function:
782
783 @defun identity arg
784 This function returns @var{arg} and has no side effects.
785 @end defun
786
787 @defun ignore &rest args
788 This function ignores any arguments and returns @code{nil}.
789 @end defun
790
791 Some functions are user-visible @dfn{commands}, which can be called
792 interactively (usually by a key sequence). It is possible to invoke
793 such a command exactly as though it was called interactively, by using
794 the @code{call-interactively} function. @xref{Interactive Call}.
795
796 @node Mapping Functions
797 @section Mapping Functions
798 @cindex mapping functions
799
800 A @dfn{mapping function} applies a given function (@emph{not} a
801 special form or macro) to each element of a list or other collection.
802 Emacs Lisp has several such functions; this section describes
803 @code{mapcar}, @code{mapc}, and @code{mapconcat}, which map over a
804 list. @xref{Definition of mapatoms}, for the function @code{mapatoms}
805 which maps over the symbols in an obarray. @xref{Definition of
806 maphash}, for the function @code{maphash} which maps over key/value
807 associations in a hash table.
808
809 These mapping functions do not allow char-tables because a char-table
810 is a sparse array whose nominal range of indices is very large. To map
811 over a char-table in a way that deals properly with its sparse nature,
812 use the function @code{map-char-table} (@pxref{Char-Tables}).
813
814 @defun mapcar function sequence
815 @anchor{Definition of mapcar}
816 @code{mapcar} applies @var{function} to each element of @var{sequence}
817 in turn, and returns a list of the results.
818
819 The argument @var{sequence} can be any kind of sequence except a
820 char-table; that is, a list, a vector, a bool-vector, or a string. The
821 result is always a list. The length of the result is the same as the
822 length of @var{sequence}. For example:
823
824 @example
825 @group
826 (mapcar 'car '((a b) (c d) (e f)))
827 @result{} (a c e)
828 (mapcar '1+ [1 2 3])
829 @result{} (2 3 4)
830 (mapcar 'string "abc")
831 @result{} ("a" "b" "c")
832 @end group
833
834 @group
835 ;; @r{Call each function in @code{my-hooks}.}
836 (mapcar 'funcall my-hooks)
837 @end group
838
839 @group
840 (defun mapcar* (function &rest args)
841 "Apply FUNCTION to successive cars of all ARGS.
842 Return the list of results."
843 ;; @r{If no list is exhausted,}
844 (if (not (memq nil args))
845 ;; @r{apply function to @sc{car}s.}
846 (cons (apply function (mapcar 'car args))
847 (apply 'mapcar* function
848 ;; @r{Recurse for rest of elements.}
849 (mapcar 'cdr args)))))
850 @end group
851
852 @group
853 (mapcar* 'cons '(a b c) '(1 2 3 4))
854 @result{} ((a . 1) (b . 2) (c . 3))
855 @end group
856 @end example
857 @end defun
858
859 @defun mapc function sequence
860 @code{mapc} is like @code{mapcar} except that @var{function} is used for
861 side-effects only---the values it returns are ignored, not collected
862 into a list. @code{mapc} always returns @var{sequence}.
863 @end defun
864
865 @defun mapconcat function sequence separator
866 @code{mapconcat} applies @var{function} to each element of
867 @var{sequence}: the results, which must be strings, are concatenated.
868 Between each pair of result strings, @code{mapconcat} inserts the string
869 @var{separator}. Usually @var{separator} contains a space or comma or
870 other suitable punctuation.
871
872 The argument @var{function} must be a function that can take one
873 argument and return a string. The argument @var{sequence} can be any
874 kind of sequence except a char-table; that is, a list, a vector, a
875 bool-vector, or a string.
876
877 @example
878 @group
879 (mapconcat 'symbol-name
880 '(The cat in the hat)
881 " ")
882 @result{} "The cat in the hat"
883 @end group
884
885 @group
886 (mapconcat (function (lambda (x) (format "%c" (1+ x))))
887 "HAL-8000"
888 "")
889 @result{} "IBM.9111"
890 @end group
891 @end example
892 @end defun
893
894 @node Anonymous Functions
895 @section Anonymous Functions
896 @cindex anonymous function
897
898 Although functions are usually defined with @code{defun} and given
899 names at the same time, it is sometimes convenient to use an explicit
900 lambda expression---an @dfn{anonymous function}. Anonymous functions
901 are valid wherever function names are. They are often assigned as
902 variable values, or as arguments to functions; for instance, you might
903 pass one as the @var{function} argument to @code{mapcar}, which
904 applies that function to each element of a list (@pxref{Mapping
905 Functions}). @xref{describe-symbols example}, for a realistic example
906 of this.
907
908 When defining a lambda expression that is to be used as an anonymous
909 function, you can in principle use any method to construct the list.
910 But typically you should use the @code{lambda} macro, or the
911 @code{function} special form, or the @code{#'} read syntax:
912
913 @defmac lambda args body...
914 This macro returns an anonymous function with argument list @var{args}
915 and body forms given by @var{body}. In effect, this macro makes
916 @code{lambda} forms ``self-quoting'': evaluating a form whose @sc{car}
917 is @code{lambda} yields the form itself:
918
919 @example
920 (lambda (x) (* x x))
921 @result{} (lambda (x) (* x x))
922 @end example
923
924 The @code{lambda} form has one other effect: it tells the Emacs
925 evaluator and byte-compiler that its argument is a function, by using
926 @code{function} as a subroutine (see below).
927 @end defmac
928
929 @defspec function function-object
930 @cindex function quoting
931 This special form returns @var{function-object} without evaluating it.
932 In this, it is similar to @code{quote} (@pxref{Quoting}). But unlike
933 @code{quote}, it also serves as a note to the Emacs evaluator and
934 byte-compiler that @var{function-object} is intended to be used as a
935 function. Assuming @var{function-object} is a valid lambda
936 expression, this has two effects:
937
938 @itemize
939 @item
940 When the code is byte-compiled, @var{function-object} is compiled into
941 a byte-code function object (@pxref{Byte Compilation}).
942
943 @item
944 When lexical binding is enabled, @var{function-object} is converted
945 into a closure. @xref{Closures}.
946 @end itemize
947 @end defspec
948
949 @cindex @samp{#'} syntax
950 The read syntax @code{#'} is a short-hand for using @code{function}.
951 The following forms are all equivalent:
952
953 @example
954 (lambda (x) (* x x))
955 (function (lambda (x) (* x x)))
956 #'(lambda (x) (* x x))
957 @end example
958
959 In the following example, we define a @code{change-property}
960 function that takes a function as its third argument, followed by a
961 @code{double-property} function that makes use of
962 @code{change-property} by passing it an anonymous function:
963
964 @example
965 @group
966 (defun change-property (symbol prop function)
967 (let ((value (get symbol prop)))
968 (put symbol prop (funcall function value))))
969 @end group
970
971 @group
972 (defun double-property (symbol prop)
973 (change-property symbol prop (lambda (x) (* 2 x))))
974 @end group
975 @end example
976
977 @noindent
978 Note that we do not quote the @code{lambda} form.
979
980 If you compile the above code, the anonymous function is also
981 compiled. This would not happen if, say, you had constructed the
982 anonymous function by quoting it as a list:
983
984 @example
985 @group
986 (defun double-property (symbol prop)
987 (change-property symbol prop '(lambda (x) (* 2 x))))
988 @end group
989 @end example
990
991 @noindent
992 In that case, the anonymous function is kept as a lambda expression in
993 the compiled code. The byte-compiler cannot assume this list is a
994 function, even though it looks like one, since it does not know that
995 @code{change-property} intends to use it as a function.
996
997 @node Function Cells
998 @section Accessing Function Cell Contents
999
1000 The @dfn{function definition} of a symbol is the object stored in the
1001 function cell of the symbol. The functions described here access, test,
1002 and set the function cell of symbols.
1003
1004 See also the function @code{indirect-function}. @xref{Definition of
1005 indirect-function}.
1006
1007 @defun symbol-function symbol
1008 @kindex void-function
1009 This returns the object in the function cell of @var{symbol}. If the
1010 symbol's function cell is void, a @code{void-function} error is
1011 signaled.
1012
1013 This function does not check that the returned object is a legitimate
1014 function.
1015
1016 @example
1017 @group
1018 (defun bar (n) (+ n 2))
1019 @result{} bar
1020 @end group
1021 @group
1022 (symbol-function 'bar)
1023 @result{} (lambda (n) (+ n 2))
1024 @end group
1025 @group
1026 (fset 'baz 'bar)
1027 @result{} bar
1028 @end group
1029 @group
1030 (symbol-function 'baz)
1031 @result{} bar
1032 @end group
1033 @end example
1034 @end defun
1035
1036 @cindex void function cell
1037 If you have never given a symbol any function definition, we say that
1038 that symbol's function cell is @dfn{void}. In other words, the function
1039 cell does not have any Lisp object in it. If you try to call such a symbol
1040 as a function, it signals a @code{void-function} error.
1041
1042 Note that void is not the same as @code{nil} or the symbol
1043 @code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
1044 and can be stored into a function cell just as any other object can be
1045 (and they can be valid functions if you define them in turn with
1046 @code{defun}). A void function cell contains no object whatsoever.
1047
1048 You can test the voidness of a symbol's function definition with
1049 @code{fboundp}. After you have given a symbol a function definition, you
1050 can make it void once more using @code{fmakunbound}.
1051
1052 @defun fboundp symbol
1053 This function returns @code{t} if the symbol has an object in its
1054 function cell, @code{nil} otherwise. It does not check that the object
1055 is a legitimate function.
1056 @end defun
1057
1058 @defun fmakunbound symbol
1059 This function makes @var{symbol}'s function cell void, so that a
1060 subsequent attempt to access this cell will cause a
1061 @code{void-function} error. It returns @var{symbol}. (See also
1062 @code{makunbound}, in @ref{Void Variables}.)
1063
1064 @example
1065 @group
1066 (defun foo (x) x)
1067 @result{} foo
1068 @end group
1069 @group
1070 (foo 1)
1071 @result{}1
1072 @end group
1073 @group
1074 (fmakunbound 'foo)
1075 @result{} foo
1076 @end group
1077 @group
1078 (foo 1)
1079 @error{} Symbol's function definition is void: foo
1080 @end group
1081 @end example
1082 @end defun
1083
1084 @defun fset symbol definition
1085 This function stores @var{definition} in the function cell of
1086 @var{symbol}. The result is @var{definition}. Normally
1087 @var{definition} should be a function or the name of a function, but
1088 this is not checked. The argument @var{symbol} is an ordinary evaluated
1089 argument.
1090
1091 The primary use of this function is as a subroutine by constructs that
1092 define or alter functions, like @code{defadvice} (@pxref{Advising
1093 Functions}). (If @code{defun} were not a primitive, it could be
1094 written as a Lisp macro using @code{fset}.) You can also use it to
1095 give a symbol a function definition that is not a list, e.g.@: a
1096 keyboard macro (@pxref{Keyboard Macros}):
1097
1098 @example
1099 ;; @r{Define a named keyboard macro.}
1100 (fset 'kill-two-lines "\^u2\^k")
1101 @result{} "\^u2\^k"
1102 @end example
1103
1104 It you wish to use @code{fset} to make an alternate name for a
1105 function, consider using @code{defalias} instead. @xref{Definition of
1106 defalias}.
1107 @end defun
1108
1109 @node Closures
1110 @section Closures
1111
1112 As explained in @ref{Variable Scoping}, Emacs can optionally enable
1113 lexical binding of variables. When lexical binding is enabled, any
1114 named function that you create (e.g.@: with @code{defun}), as well as
1115 any anonymous function that you create using the @code{lambda} macro
1116 or the @code{function} special form or the @code{#'} syntax
1117 (@pxref{Anonymous Functions}), is automatically converted into a
1118 closure.
1119
1120 A closure is a function that also carries a record of the lexical
1121 environment that existed when the function was defined. When it is
1122 invoked, any lexical variable references within its definition use the
1123 retained lexical environment. In all other respects, closures behave
1124 much like ordinary functions; in particular, they can be called in the
1125 same way as ordinary functions.
1126
1127 @xref{Lexical Binding}, for an example of using a closure.
1128
1129 Currently, an Emacs Lisp closure object is represented by a list
1130 with the symbol @code{closure} as the first element, a list
1131 representing the lexical environment as the second element, and the
1132 argument list and body forms as the remaining elements:
1133
1134 @example
1135 ;; @r{lexical binding is enabled.}
1136 (lambda (x) (* x x))
1137 @result{} (closure (t) (x) (* x x))
1138 @end example
1139
1140 @noindent
1141 However, the fact that the internal structure of a closure is
1142 ``exposed'' to the rest of the Lisp world is considered an internal
1143 implementation detail. For this reason, we recommend against directly
1144 examining or altering the structure of closure objects.
1145
1146 @node Obsolete Functions
1147 @section Declaring Functions Obsolete
1148
1149 You can use @code{make-obsolete} to declare a function obsolete. This
1150 indicates that the function may be removed at some stage in the future.
1151
1152 @defun make-obsolete obsolete-name current-name &optional when
1153 This function makes the byte compiler warn that the function
1154 @var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the
1155 warning message says to use @var{current-name} instead of
1156 @var{obsolete-name}. @var{current-name} does not need to be an alias for
1157 @var{obsolete-name}; it can be a different function with similar
1158 functionality. If @var{current-name} is a string, it is the warning
1159 message.
1160
1161 If provided, @var{when} should be a string indicating when the function
1162 was first made obsolete---for example, a date or a release number.
1163 @end defun
1164
1165 You can define a function as an alias and declare it obsolete at the
1166 same time using the macro @code{define-obsolete-function-alias}:
1167
1168 @defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
1169 This macro marks the function @var{obsolete-name} obsolete and also
1170 defines it as an alias for the function @var{current-name}. It is
1171 equivalent to the following:
1172
1173 @example
1174 (defalias @var{obsolete-name} @var{current-name} @var{docstring})
1175 (make-obsolete @var{obsolete-name} @var{current-name} @var{when})
1176 @end example
1177 @end defmac
1178
1179 In addition, you can mark a certain a particular calling convention
1180 for a function as obsolete:
1181
1182 @defun set-advertised-calling-convention function signature when
1183 This function specifies the argument list @var{signature} as the
1184 correct way to call @var{function}. This causes the Emacs byte
1185 compiler to issue a warning whenever it comes across an Emacs Lisp
1186 program that calls @var{function} any other way (however, it will
1187 still allow the code to be byte compiled). @var{when} should be a
1188 string indicating when the variable was first made obsolete (usually a
1189 version number string).
1190
1191 For instance, in old versions of Emacs the @code{sit-for} function
1192 accepted three arguments, like this
1193
1194 @example
1195 (sit-for seconds milliseconds nodisp)
1196 @end example
1197
1198 However, calling @code{sit-for} this way is considered obsolete
1199 (@pxref{Waiting}). The old calling convention is deprecated like
1200 this:
1201
1202 @example
1203 (set-advertised-calling-convention
1204 'sit-for '(seconds &optional nodisp) "22.1")
1205 @end example
1206 @end defun
1207
1208 @node Inline Functions
1209 @section Inline Functions
1210 @cindex inline functions
1211
1212 @defmac defsubst name argument-list body-forms...
1213 Define an inline function. The syntax is exactly the same as
1214 @code{defun} (@pxref{Defining Functions}).
1215 @end defmac
1216
1217 You can define an @dfn{inline function} by using @code{defsubst}
1218 instead of @code{defun}. An inline function works just like an
1219 ordinary function except for one thing: when you byte-compile a call
1220 to the function (@pxref{Byte Compilation}), the function's definition
1221 is expanded into the caller.
1222
1223 Making a function inline often makes its function calls run faster.
1224 But it also has disadvantages. For one thing, it reduces flexibility;
1225 if you change the definition of the function, calls already inlined
1226 still use the old definition until you recompile them.
1227
1228 Another disadvantage is that making a large function inline can
1229 increase the size of compiled code both in files and in memory. Since
1230 the speed advantage of inline functions is greatest for small
1231 functions, you generally should not make large functions inline.
1232
1233 Also, inline functions do not behave well with respect to debugging,
1234 tracing, and advising (@pxref{Advising Functions}). Since ease of
1235 debugging and the flexibility of redefining functions are important
1236 features of Emacs, you should not make a function inline, even if it's
1237 small, unless its speed is really crucial, and you've timed the code
1238 to verify that using @code{defun} actually has performance problems.
1239
1240 It's possible to define a macro to expand into the same code that an
1241 inline function would execute (@pxref{Macros}). But the macro would
1242 be limited to direct use in expressions---a macro cannot be called
1243 with @code{apply}, @code{mapcar} and so on. Also, it takes some work
1244 to convert an ordinary function into a macro. To convert it into an
1245 inline function is easy; just replace @code{defun} with
1246 @code{defsubst}. Since each argument of an inline function is
1247 evaluated exactly once, you needn't worry about how many times the
1248 body uses the arguments, as you do for macros.
1249
1250 After an inline function is defined, its inline expansion can be
1251 performed later on in the same file, just like macros.
1252
1253 @node Declaring Functions
1254 @section Telling the Compiler that a Function is Defined
1255 @cindex function declaration
1256 @cindex declaring functions
1257 @findex declare-function
1258
1259 Byte-compiling a file often produces warnings about functions that the
1260 compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this
1261 indicates a real problem, but usually the functions in question are
1262 defined in other files which would be loaded if that code is run. For
1263 example, byte-compiling @file{fortran.el} used to warn:
1264
1265 @example
1266 In end of data:
1267 fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
1268 to be defined.
1269 @end example
1270
1271 In fact, @code{gud-find-c-expr} is only used in the function that
1272 Fortran mode uses for the local value of
1273 @code{gud-find-expr-function}, which is a callback from GUD; if it is
1274 called, the GUD functions will be loaded. When you know that such a
1275 warning does not indicate a real problem, it is good to suppress the
1276 warning. That makes new warnings which might mean real problems more
1277 visible. You do that with @code{declare-function}.
1278
1279 All you need to do is add a @code{declare-function} statement before the
1280 first use of the function in question:
1281
1282 @example
1283 (declare-function gud-find-c-expr "gud.el" nil)
1284 @end example
1285
1286 This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
1287 @samp{.el} can be omitted). The compiler takes for granted that that file
1288 really defines the function, and does not check.
1289
1290 The optional third argument specifies the argument list of
1291 @code{gud-find-c-expr}. In this case, it takes no arguments
1292 (@code{nil} is different from not specifying a value). In other
1293 cases, this might be something like @code{(file &optional overwrite)}.
1294 You don't have to specify the argument list, but if you do the
1295 byte compiler can check that the calls match the declaration.
1296
1297 @defmac declare-function function file &optional arglist fileonly
1298 Tell the byte compiler to assume that @var{function} is defined, with
1299 arguments @var{arglist}, and that the definition should come from the
1300 file @var{file}. @var{fileonly} non-@code{nil} means only check that
1301 @var{file} exists, not that it actually defines @var{function}.
1302 @end defmac
1303
1304 To verify that these functions really are declared where
1305 @code{declare-function} says they are, use @code{check-declare-file}
1306 to check all @code{declare-function} calls in one source file, or use
1307 @code{check-declare-directory} check all the files in and under a
1308 certain directory.
1309
1310 These commands find the file that ought to contain a function's
1311 definition using @code{locate-library}; if that finds no file, they
1312 expand the definition file name relative to the directory of the file
1313 that contains the @code{declare-function} call.
1314
1315 You can also say that a function is a primitive by specifying a file
1316 name ending in @samp{.c} or @samp{.m}. This is useful only when you
1317 call a primitive that is defined only on certain systems. Most
1318 primitives are always defined, so they will never give you a warning.
1319
1320 Sometimes a file will optionally use functions from an external package.
1321 If you prefix the filename in the @code{declare-function} statement with
1322 @samp{ext:}, then it will be checked if it is found, otherwise skipped
1323 without error.
1324
1325 There are some function definitions that @samp{check-declare} does not
1326 understand (e.g. @code{defstruct} and some other macros). In such cases,
1327 you can pass a non-@code{nil} @var{fileonly} argument to
1328 @code{declare-function}, meaning to only check that the file exists, not
1329 that it actually defines the function. Note that to do this without
1330 having to specify an argument list, you should set the @var{arglist}
1331 argument to @code{t} (because @code{nil} means an empty argument list, as
1332 opposed to an unspecified one).
1333
1334 @node Function Safety
1335 @section Determining whether a Function is Safe to Call
1336 @cindex function safety
1337 @cindex safety of functions
1338
1339 Some major modes such as SES call functions that are stored in user
1340 files. (@inforef{Top, ,ses}, for more information on SES.) User
1341 files sometimes have poor pedigrees---you can get a spreadsheet from
1342 someone you've just met, or you can get one through email from someone
1343 you've never met. So it is risky to call a function whose source code
1344 is stored in a user file until you have determined that it is safe.
1345
1346 @defun unsafep form &optional unsafep-vars
1347 Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or
1348 returns a list that describes why it might be unsafe. The argument
1349 @var{unsafep-vars} is a list of symbols known to have temporary
1350 bindings at this point; it is mainly used for internal recursive
1351 calls. The current buffer is an implicit argument, which provides a
1352 list of buffer-local bindings.
1353 @end defun
1354
1355 Being quick and simple, @code{unsafep} does a very light analysis and
1356 rejects many Lisp expressions that are actually safe. There are no
1357 known cases where @code{unsafep} returns @code{nil} for an unsafe
1358 expression. However, a ``safe'' Lisp expression can return a string
1359 with a @code{display} property, containing an associated Lisp
1360 expression to be executed after the string is inserted into a buffer.
1361 This associated expression can be a virus. In order to be safe, you
1362 must delete properties from all strings calculated by user code before
1363 inserting them into buffers.
1364
1365 @ignore
1366 What is a safe Lisp expression? Basically, it's an expression that
1367 calls only built-in functions with no side effects (or only innocuous
1368 ones). Innocuous side effects include displaying messages and
1369 altering non-risky buffer-local variables (but not global variables).
1370
1371 @table @dfn
1372 @item Safe expression
1373 @itemize
1374 @item
1375 An atom or quoted thing.
1376 @item
1377 A call to a safe function (see below), if all its arguments are
1378 safe expressions.
1379 @item
1380 One of the special forms @code{and}, @code{catch}, @code{cond},
1381 @code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn},
1382 @code{while}, and @code{unwind-protect}], if all its arguments are
1383 safe.
1384 @item
1385 A form that creates temporary bindings (@code{condition-case},
1386 @code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or
1387 @code{let*}), if all args are safe and the symbols to be bound are not
1388 explicitly risky (see @pxref{File Local Variables}).
1389 @item
1390 An assignment using @code{add-to-list}, @code{setq}, @code{push}, or
1391 @code{pop}, if all args are safe and the symbols to be assigned are
1392 not explicitly risky and they already have temporary or buffer-local
1393 bindings.
1394 @item
1395 One of [apply, mapc, mapcar, mapconcat] if the first argument is a
1396 safe explicit lambda and the other args are safe expressions.
1397 @end itemize
1398
1399 @item Safe function
1400 @itemize
1401 @item
1402 A lambda containing safe expressions.
1403 @item
1404 A symbol on the list @code{safe-functions}, so the user says it's safe.
1405 @item
1406 A symbol with a non-@code{nil} @code{side-effect-free} property.
1407 @item
1408 A symbol with a non-@code{nil} @code{safe-function} property. The
1409 value @code{t} indicates a function that is safe but has innocuous
1410 side effects. Other values will someday indicate functions with
1411 classes of side effects that are not always safe.
1412 @end itemize
1413
1414 The @code{side-effect-free} and @code{safe-function} properties are
1415 provided for built-in functions and for low-level functions and macros
1416 defined in @file{subr.el}. You can assign these properties for the
1417 functions you write.
1418 @end table
1419 @end ignore
1420
1421 @node Related Topics
1422 @section Other Topics Related to Functions
1423
1424 Here is a table of several functions that do things related to
1425 function calling and function definitions. They are documented
1426 elsewhere, but we provide cross references here.
1427
1428 @table @code
1429 @item apply
1430 See @ref{Calling Functions}.
1431
1432 @item autoload
1433 See @ref{Autoload}.
1434
1435 @item call-interactively
1436 See @ref{Interactive Call}.
1437
1438 @item called-interactively-p
1439 See @ref{Distinguish Interactive}.
1440
1441 @item commandp
1442 See @ref{Interactive Call}.
1443
1444 @item documentation
1445 See @ref{Accessing Documentation}.
1446
1447 @item eval
1448 See @ref{Eval}.
1449
1450 @item funcall
1451 See @ref{Calling Functions}.
1452
1453 @item function
1454 See @ref{Anonymous Functions}.
1455
1456 @item ignore
1457 See @ref{Calling Functions}.
1458
1459 @item indirect-function
1460 See @ref{Function Indirection}.
1461
1462 @item interactive
1463 See @ref{Using Interactive}.
1464
1465 @item interactive-p
1466 See @ref{Distinguish Interactive}.
1467
1468 @item mapatoms
1469 See @ref{Creating Symbols}.
1470
1471 @item mapcar
1472 See @ref{Mapping Functions}.
1473
1474 @item map-char-table
1475 See @ref{Char-Tables}.
1476
1477 @item mapconcat
1478 See @ref{Mapping Functions}.
1479
1480 @item undefined
1481 See @ref{Functions for Key Lookup}.
1482 @end table