2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
5 @c See the file elisp.texi for copying conditions.
9 A Lisp program is composed mainly of Lisp functions. This chapter
10 explains what functions are, how they accept arguments, and how to
14 * What Is a Function:: Lisp functions vs. primitives; terminology.
15 * Lambda Expressions:: How functions are expressed as Lisp objects.
16 * Function Names:: A symbol can serve as the name of a function.
17 * Defining Functions:: Lisp expressions for defining functions.
18 * Calling Functions:: How to use an existing function.
19 * Mapping Functions:: Applying a function to each element of a list, etc.
20 * Anonymous Functions:: Lambda expressions are functions with no names.
21 * Function Cells:: Accessing or setting the function definition
23 * Closures:: Functions that enclose a lexical environment.
24 * Advising Functions:: Adding to the definition of a function.
25 * Obsolete Functions:: Declaring functions obsolete.
26 * Inline Functions:: Functions that the compiler will expand inline.
27 * Declare Form:: Adding additional information about a function.
28 * Declaring Functions:: Telling the compiler that a function is defined.
29 * Function Safety:: Determining whether a function is safe to call.
30 * Related Topics:: Cross-references to specific Lisp primitives
31 that have a special bearing on how functions work.
34 @node What Is a Function
35 @section What Is a Function?
38 @cindex value of function
40 In a general sense, a function is a rule for carrying out a
41 computation given input values called @dfn{arguments}. The result of
42 the computation is called the @dfn{value} or @dfn{return value} of the
43 function. The computation can also have side effects, such as lasting
44 changes in the values of variables or the contents of data structures.
46 In most computer languages, every function has a name. But in Lisp,
47 a function in the strictest sense has no name: it is an object which
48 can @emph{optionally} be associated with a symbol (e.g., @code{car})
49 that serves as the function name. @xref{Function Names}. When a
50 function has been given a name, we usually also refer to that symbol
51 as a ``function'' (e.g., we refer to ``the function @code{car}'').
52 In this manual, the distinction between a function name and the
53 function object itself is usually unimportant, but we will take note
54 wherever it is relevant.
56 Certain function-like objects, called @dfn{special forms} and
57 @dfn{macros}, also accept arguments to carry out computations.
58 However, as explained below, these are not considered functions in
61 Here are important terms for functions and function-like objects:
64 @item lambda expression
65 A function (in the strict sense, i.e., a function object) which is
66 written in Lisp. These are described in the following section.
68 @xref{Lambda Expressions}.
74 @cindex built-in function
75 A function which is callable from Lisp but is actually written in C@.
76 Primitives are also called @dfn{built-in functions}, or @dfn{subrs}.
77 Examples include functions like @code{car} and @code{append}. In
78 addition, all special forms (see below) are also considered
81 Usually, a function is implemented as a primitive because it is a
82 fundamental part of Lisp (e.g., @code{car}), or because it provides a
83 low-level interface to operating system services, or because it needs
84 to run fast. Unlike functions defined in Lisp, primitives can be
85 modified or added only by changing the C sources and recompiling
86 Emacs. See @ref{Writing Emacs Primitives}.
89 A primitive that is like a function but does not evaluate all of its
90 arguments in the usual way. It may evaluate only some of the
91 arguments, or may evaluate them in an unusual order, or several times.
92 Examples include @code{if}, @code{and}, and @code{while}.
97 A construct defined in Lisp, which differs from a function in that it
98 translates a Lisp expression into another expression which is to be
99 evaluated instead of the original expression. Macros enable Lisp
100 programmers to do the sorts of things that special forms can do.
105 An object which can be invoked via the @code{command-execute}
106 primitive, usually due to the user typing in a key sequence
107 @dfn{bound} to that command. @xref{Interactive Call}. A command is
108 usually a function; if the function is written in Lisp, it is made
109 into a command by an @code{interactive} form in the function
110 definition (@pxref{Defining Commands}). Commands that are functions
111 can also be called from Lisp expressions, just like other functions.
113 Keyboard macros (strings and vectors) are commands also, even though
114 they are not functions. @xref{Keyboard Macros}. We say that a symbol
115 is a command if its function cell contains a command (@pxref{Symbol
116 Components}); such a @dfn{named command} can be invoked with
120 A function object that is much like a lambda expression, except that
121 it also encloses an ``environment'' of lexical variable bindings.
124 @item byte-code function
125 A function that has been compiled by the byte compiler.
126 @xref{Byte-Code Type}.
128 @item autoload object
129 @cindex autoload object
130 A place-holder for a real function. If the autoload object is called,
131 Emacs loads the file containing the definition of the real function,
132 and then calls the real function. @xref{Autoload}.
135 You can use the function @code{functionp} to test if an object is a
138 @defun functionp object
139 This function returns @code{t} if @var{object} is any kind of
140 function, i.e., can be passed to @code{funcall}. Note that
141 @code{functionp} returns @code{t} for symbols that are function names,
142 and returns @code{nil} for special forms.
146 Unlike @code{functionp}, the next three functions do @emph{not} treat
147 a symbol as its function definition.
150 This function returns @code{t} if @var{object} is a built-in function
151 (i.e., a Lisp primitive).
155 (subrp 'message) ; @r{@code{message} is a symbol,}
156 @result{} nil ; @r{not a subr object.}
159 (subrp (symbol-function 'message))
165 @defun byte-code-function-p object
166 This function returns @code{t} if @var{object} is a byte-code
167 function. For example:
171 (byte-code-function-p (symbol-function 'next-line))
177 @defun subr-arity subr
178 This function provides information about the argument list of a
179 primitive, @var{subr}. The returned value is a pair
180 @code{(@var{min} . @var{max})}. @var{min} is the minimum number of
181 args. @var{max} is the maximum number or the symbol @code{many}, for a
182 function with @code{&rest} arguments, or the symbol @code{unevalled} if
183 @var{subr} is a special form.
186 @node Lambda Expressions
187 @section Lambda Expressions
188 @cindex lambda expression
190 A lambda expression is a function object written in Lisp. Here is
195 "Return the hyperbolic cosine of X."
196 (* 0.5 (+ (exp x) (exp (- x)))))
200 In Emacs Lisp, such a list is a valid expression which evaluates to
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.
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.
217 @node Lambda Components
218 @subsection Components of a Lambda Expression
220 A lambda expression is a list that looks like this:
223 (lambda (@var{arg-variables}@dots{})
224 [@var{documentation-string}]
225 [@var{interactive-declaration}]
226 @var{body-forms}@dots{})
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
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}.
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}.
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
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.
261 @subsection A Simple Lambda Expression Example
263 Consider the following example:
266 (lambda (a b c) (+ a b c))
270 We can call this function by passing it to @code{funcall}, like this:
274 (funcall (lambda (a b c) (+ a b c))
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.
285 Note that the arguments can be the results of other function calls, as in
290 (funcall (lambda (a b c) (+ a b c))
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.
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}).
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
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.
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}
330 @cindex optional arguments
331 @cindex rest arguments
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.
339 Thus, the complete syntax for an argument list is as follows:
343 (@var{required-vars}@dots{}
344 @r{[}&optional @var{optional-vars}@dots{}@r{]}
345 @r{[}&rest @var{rest-var}@r{]})
350 The square brackets indicate that the @code{&optional} and @code{&rest}
351 clauses, and the variables that follow them, are optional.
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.
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.
367 @cindex CL note---default optional arg
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.
375 For example, an argument list that looks like this:
378 (a b &optional c d &rest e)
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}
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.
399 Here are some examples of argument lists and proper calls:
402 (funcall (lambda (n) (1+ n)) ; @r{One required:}
403 1) ; @r{requires exactly one argument.}
405 (funcall (lambda (n &optional n1) ; @r{One required and one optional:}
406 (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
409 (funcall (lambda (n &rest ns) ; @r{One required and one rest:}
410 (+ n (apply '+ ns))) ; @r{1 or more arguments.}
415 @node Function Documentation
416 @subsection Documentation Strings of Functions
417 @cindex documentation of function
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.
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.
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.
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
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.
452 The last line of the documentation string can specify calling
453 conventions different from the actual function arguments. Write
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.
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.
472 @section Naming a Function
473 @cindex function definition
474 @cindex named function
475 @cindex function name
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.
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.
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.
496 @xref{Defining Functions}.
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
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
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
517 @node Defining Functions
518 @section Defining Functions
519 @cindex defining a function
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
525 @defmac defun name args [doc] [declare] [interactive] body@dots{}
526 @code{defun} is the usual way to define new Lisp functions. It
527 defines the symbol @var{name} as a function with argument list
528 @var{args} and body forms given by @var{body}. Neither @var{name} nor
529 @var{args} should be quoted.
531 @var{doc}, if present, should be a string specifying the function's
532 documentation string (@pxref{Function Documentation}). @var{declare},
533 if present, should be a @code{declare} form specifying function
534 metadata (@pxref{Declare Form}). @var{interactive}, if present,
535 should be an @code{interactive} form specifying how the function is to
536 be called interactively (@pxref{Interactive Call}).
538 The return value of @code{defun} is undefined.
540 Here are some examples:
550 (defun bar (a &optional b &rest c)
553 @result{} (1 2 (3 4 5))
557 @result{} (1 nil nil)
561 @error{} Wrong number of arguments.
565 (defun capitalize-backwards ()
566 "Upcase the last letter of the word at point."
575 Be careful not to redefine existing functions unintentionally.
576 @code{defun} redefines even primitive functions such as @code{car}
577 without any hesitation or notification. Emacs does not prevent you
578 from doing this, because redefining a function is sometimes done
579 deliberately, and there is no way to distinguish deliberate
580 redefinition from unintentional redefinition.
583 @cindex function aliases
584 @cindex alias, for functions
585 @defun defalias name definition &optional doc
586 @anchor{Definition of defalias}
587 This function defines the symbol @var{name} as a function, with
588 definition @var{definition} (which can be any valid Lisp function).
589 Its return value is @emph{undefined}.
591 If @var{doc} is non-@code{nil}, it becomes the function documentation
592 of @var{name}. Otherwise, any documentation provided by
593 @var{definition} is used.
595 @cindex defalias-fset-function property
596 Internally, @code{defalias} normally uses @code{fset} to set the definition.
597 If @var{name} has a @code{defalias-fset-function} property, however,
598 the associated value is used as a function to call in place of @code{fset}.
600 The proper place to use @code{defalias} is where a specific function
601 name is being defined---especially where that name appears explicitly in
602 the source file being loaded. This is because @code{defalias} records
603 which file defined the function, just like @code{defun}
606 By contrast, in programs that manipulate function definitions for other
607 purposes, it is better to use @code{fset}, which does not keep such
608 records. @xref{Function Cells}.
611 You cannot create a new primitive function with @code{defun} or
612 @code{defalias}, but you can use them to change the function definition of
613 any symbol, even one such as @code{car} or @code{x-popup-menu} whose
614 normal definition is a primitive. However, this is risky: for
615 instance, it is next to impossible to redefine @code{car} without
616 breaking Lisp completely. Redefining an obscure function such as
617 @code{x-popup-menu} is less dangerous, but it still may not work as
618 you expect. If there are calls to the primitive from C code, they
619 call the primitive's C definition directly, so changing the symbol's
620 definition will have no effect on them.
622 See also @code{defsubst}, which defines a function like @code{defun}
623 and tells the Lisp compiler to perform inline expansion on it.
624 @xref{Inline Functions}.
626 @node Calling Functions
627 @section Calling Functions
628 @cindex function invocation
629 @cindex calling a function
631 Defining functions is only half the battle. Functions don't do
632 anything until you @dfn{call} them, i.e., tell them to run. Calling a
633 function is also known as @dfn{invocation}.
635 The most common way of invoking a function is by evaluating a list.
636 For example, evaluating the list @code{(concat "a" "b")} calls the
637 function @code{concat} with arguments @code{"a"} and @code{"b"}.
638 @xref{Evaluation}, for a description of evaluation.
640 When you write a list as an expression in your program, you specify
641 which function to call, and how many arguments to give it, in the text
642 of the program. Usually that's just what you want. Occasionally you
643 need to compute at run time which function to call. To do that, use
644 the function @code{funcall}. When you also need to determine at run
645 time how many arguments to pass, use @code{apply}.
647 @defun funcall function &rest arguments
648 @code{funcall} calls @var{function} with @var{arguments}, and returns
649 whatever @var{function} returns.
651 Since @code{funcall} is a function, all of its arguments, including
652 @var{function}, are evaluated before @code{funcall} is called. This
653 means that you can use any expression to obtain the function to be
654 called. It also means that @code{funcall} does not see the
655 expressions you write for the @var{arguments}, only their values.
656 These values are @emph{not} evaluated a second time in the act of
657 calling @var{function}; the operation of @code{funcall} is like the
658 normal procedure for calling a function, once its arguments have
659 already been evaluated.
661 The argument @var{function} must be either a Lisp function or a
662 primitive function. Special forms and macros are not allowed, because
663 they make sense only when given the ``unevaluated'' argument
664 expressions. @code{funcall} cannot provide these because, as we saw
665 above, it never knows them in the first place.
677 (funcall f 'x 'y '(z))
682 @error{} Invalid function: #<subr and>
686 Compare these examples with the examples of @code{apply}.
689 @defun apply function &rest arguments
690 @code{apply} calls @var{function} with @var{arguments}, just like
691 @code{funcall} but with one difference: the last of @var{arguments} is a
692 list of objects, which are passed to @var{function} as separate
693 arguments, rather than a single list. We say that @code{apply}
694 @dfn{spreads} this list so that each individual element becomes an
697 @code{apply} returns the result of calling @var{function}. As with
698 @code{funcall}, @var{function} must either be a Lisp function or a
699 primitive function; special forms and macros do not make sense in
709 @error{} Wrong type argument: listp, z
712 (apply '+ 1 2 '(3 4))
716 (apply '+ '(1 2 3 4))
721 (apply 'append '((a b c) nil (x y z) nil))
722 @result{} (a b c x y z)
726 For an interesting example of using @code{apply}, see @ref{Definition
730 @cindex partial application of functions
732 Sometimes it is useful to fix some of the function's arguments at
733 certain values, and leave the rest of arguments for when the function
734 is actually called. The act of fixing some of the function's
735 arguments is called @dfn{partial application} of the function@footnote{
736 This is related to, but different from @dfn{currying}, which
737 transforms a function that takes multiple arguments in such a way that
738 it can be called as a chain of functions, each one with a single
740 The result is a new function that accepts the rest of
741 arguments and calls the original function with all the arguments
744 Here's how to do partial application in Emacs Lisp:
746 @defun apply-partially func &rest args
747 This function returns a new function which, when called, will call
748 @var{func} with the list of arguments composed from @var{args} and
749 additional arguments specified at the time of the call. If @var{func}
750 accepts @var{n} arguments, then a call to @code{apply-partially} with
751 @w{@code{@var{m} < @var{n}}} arguments will produce a new function of
752 @w{@code{@var{n} - @var{m}}} arguments.
754 Here's how we could define the built-in function @code{1+}, if it
755 didn't exist, using @code{apply-partially} and @code{+}, another
760 (defalias '1+ (apply-partially '+ 1)
761 "Increment argument by one.")
771 It is common for Lisp functions to accept functions as arguments or
772 find them in data structures (especially in hook variables and property
773 lists) and call them using @code{funcall} or @code{apply}. Functions
774 that accept function arguments are often called @dfn{functionals}.
776 Sometimes, when you call a functional, it is useful to supply a no-op
777 function as the argument. Here are two different kinds of no-op
781 This function returns @var{arg} and has no side effects.
784 @defun ignore &rest args
785 This function ignores any arguments and returns @code{nil}.
788 Some functions are user-visible @dfn{commands}, which can be called
789 interactively (usually by a key sequence). It is possible to invoke
790 such a command exactly as though it was called interactively, by using
791 the @code{call-interactively} function. @xref{Interactive Call}.
793 @node Mapping Functions
794 @section Mapping Functions
795 @cindex mapping functions
797 A @dfn{mapping function} applies a given function (@emph{not} a
798 special form or macro) to each element of a list or other collection.
799 Emacs Lisp has several such functions; this section describes
800 @code{mapcar}, @code{mapc}, and @code{mapconcat}, which map over a
801 list. @xref{Definition of mapatoms}, for the function @code{mapatoms}
802 which maps over the symbols in an obarray. @xref{Definition of
803 maphash}, for the function @code{maphash} which maps over key/value
804 associations in a hash table.
806 These mapping functions do not allow char-tables because a char-table
807 is a sparse array whose nominal range of indices is very large. To map
808 over a char-table in a way that deals properly with its sparse nature,
809 use the function @code{map-char-table} (@pxref{Char-Tables}).
811 @defun mapcar function sequence
812 @anchor{Definition of mapcar}
813 @code{mapcar} applies @var{function} to each element of @var{sequence}
814 in turn, and returns a list of the results.
816 The argument @var{sequence} can be any kind of sequence except a
817 char-table; that is, a list, a vector, a bool-vector, or a string. The
818 result is always a list. The length of the result is the same as the
819 length of @var{sequence}. For example:
823 (mapcar 'car '((a b) (c d) (e f)))
827 (mapcar 'string "abc")
828 @result{} ("a" "b" "c")
832 ;; @r{Call each function in @code{my-hooks}.}
833 (mapcar 'funcall my-hooks)
837 (defun mapcar* (function &rest args)
838 "Apply FUNCTION to successive cars of all ARGS.
839 Return the list of results."
840 ;; @r{If no list is exhausted,}
841 (if (not (memq nil args))
842 ;; @r{apply function to @sc{car}s.}
843 (cons (apply function (mapcar 'car args))
844 (apply 'mapcar* function
845 ;; @r{Recurse for rest of elements.}
846 (mapcar 'cdr args)))))
850 (mapcar* 'cons '(a b c) '(1 2 3 4))
851 @result{} ((a . 1) (b . 2) (c . 3))
856 @defun mapc function sequence
857 @code{mapc} is like @code{mapcar} except that @var{function} is used for
858 side-effects only---the values it returns are ignored, not collected
859 into a list. @code{mapc} always returns @var{sequence}.
862 @defun mapconcat function sequence separator
863 @code{mapconcat} applies @var{function} to each element of
864 @var{sequence}: the results, which must be strings, are concatenated.
865 Between each pair of result strings, @code{mapconcat} inserts the string
866 @var{separator}. Usually @var{separator} contains a space or comma or
867 other suitable punctuation.
869 The argument @var{function} must be a function that can take one
870 argument and return a string. The argument @var{sequence} can be any
871 kind of sequence except a char-table; that is, a list, a vector, a
872 bool-vector, or a string.
876 (mapconcat 'symbol-name
877 '(The cat in the hat)
879 @result{} "The cat in the hat"
883 (mapconcat (function (lambda (x) (format "%c" (1+ x))))
891 @node Anonymous Functions
892 @section Anonymous Functions
893 @cindex anonymous function
895 Although functions are usually defined with @code{defun} and given
896 names at the same time, it is sometimes convenient to use an explicit
897 lambda expression---an @dfn{anonymous function}. Anonymous functions
898 are valid wherever function names are. They are often assigned as
899 variable values, or as arguments to functions; for instance, you might
900 pass one as the @var{function} argument to @code{mapcar}, which
901 applies that function to each element of a list (@pxref{Mapping
902 Functions}). @xref{describe-symbols example}, for a realistic example
905 When defining a lambda expression that is to be used as an anonymous
906 function, you can in principle use any method to construct the list.
907 But typically you should use the @code{lambda} macro, or the
908 @code{function} special form, or the @code{#'} read syntax:
910 @defmac lambda args [doc] [interactive] body@dots{}
911 This macro returns an anonymous function with argument list
912 @var{args}, documentation string @var{doc} (if any), interactive spec
913 @var{interactive} (if any), and body forms given by @var{body}.
915 In effect, this macro makes @code{lambda} forms ``self-quoting'':
916 evaluating a form whose @sc{car} is @code{lambda} yields the form
921 @result{} (lambda (x) (* x x))
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).
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:
940 When the code is byte-compiled, @var{function-object} is compiled into
941 a byte-code function object (@pxref{Byte Compilation}).
944 When lexical binding is enabled, @var{function-object} is converted
945 into a closure. @xref{Closures}.
949 @cindex @samp{#'} syntax
950 The read syntax @code{#'} is a short-hand for using @code{function}.
951 The following forms are all equivalent:
955 (function (lambda (x) (* x x)))
956 #'(lambda (x) (* x x))
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:
966 (defun change-property (symbol prop function)
967 (let ((value (get symbol prop)))
968 (put symbol prop (funcall function value))))
972 (defun double-property (symbol prop)
973 (change-property symbol prop (lambda (x) (* 2 x))))
978 Note that we do not quote the @code{lambda} form.
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:
984 @c Do not unquote this lambda!
987 (defun double-property (symbol prop)
988 (change-property symbol prop '(lambda (x) (* 2 x))))
993 In that case, the anonymous function is kept as a lambda expression in
994 the compiled code. The byte-compiler cannot assume this list is a
995 function, even though it looks like one, since it does not know that
996 @code{change-property} intends to use it as a function.
999 @section Accessing Function Cell Contents
1001 The @dfn{function definition} of a symbol is the object stored in the
1002 function cell of the symbol. The functions described here access, test,
1003 and set the function cell of symbols.
1005 See also the function @code{indirect-function}. @xref{Definition of
1008 @defun symbol-function symbol
1009 @kindex void-function
1010 This returns the object in the function cell of @var{symbol}. It does
1011 not check that the returned object is a legitimate function.
1013 If the function cell is void, the return value is @code{nil}. To
1014 distinguish between a function cell that is void and one set to
1015 @code{nil}, use @code{fboundp} (see below).
1019 (defun bar (n) (+ n 2))
1020 (symbol-function 'bar)
1021 @result{} (lambda (n) (+ n 2))
1028 (symbol-function 'baz)
1034 @cindex void function cell
1035 If you have never given a symbol any function definition, we say
1036 that that symbol's function cell is @dfn{void}. In other words, the
1037 function cell does not have any Lisp object in it. If you try to call
1038 the symbol as a function, Emacs signals a @code{void-function} error.
1040 Note that void is not the same as @code{nil} or the symbol
1041 @code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
1042 and can be stored into a function cell just as any other object can be
1043 (and they can be valid functions if you define them in turn with
1044 @code{defun}). A void function cell contains no object whatsoever.
1046 You can test the voidness of a symbol's function definition with
1047 @code{fboundp}. After you have given a symbol a function definition, you
1048 can make it void once more using @code{fmakunbound}.
1050 @defun fboundp symbol
1051 This function returns @code{t} if the symbol has an object in its
1052 function cell, @code{nil} otherwise. It does not check that the object
1053 is a legitimate function.
1056 @defun fmakunbound symbol
1057 This function makes @var{symbol}'s function cell void, so that a
1058 subsequent attempt to access this cell will cause a
1059 @code{void-function} error. It returns @var{symbol}. (See also
1060 @code{makunbound}, in @ref{Void Variables}.)
1074 @error{} Symbol's function definition is void: foo
1079 @defun fset symbol definition
1080 This function stores @var{definition} in the function cell of
1081 @var{symbol}. The result is @var{definition}. Normally
1082 @var{definition} should be a function or the name of a function, but
1083 this is not checked. The argument @var{symbol} is an ordinary evaluated
1086 The primary use of this function is as a subroutine by constructs that define
1087 or alter functions, like @code{defun} or @code{advice-add} (@pxref{Advising
1088 Functions}). You can also use it to give a symbol a function definition that
1089 is not a function, e.g., a keyboard macro (@pxref{Keyboard Macros}):
1092 ;; @r{Define a named keyboard macro.}
1093 (fset 'kill-two-lines "\^u2\^k")
1097 It you wish to use @code{fset} to make an alternate name for a
1098 function, consider using @code{defalias} instead. @xref{Definition of
1105 As explained in @ref{Variable Scoping}, Emacs can optionally enable
1106 lexical binding of variables. When lexical binding is enabled, any
1107 named function that you create (e.g., with @code{defun}), as well as
1108 any anonymous function that you create using the @code{lambda} macro
1109 or the @code{function} special form or the @code{#'} syntax
1110 (@pxref{Anonymous Functions}), is automatically converted into a
1114 A closure is a function that also carries a record of the lexical
1115 environment that existed when the function was defined. When it is
1116 invoked, any lexical variable references within its definition use the
1117 retained lexical environment. In all other respects, closures behave
1118 much like ordinary functions; in particular, they can be called in the
1119 same way as ordinary functions.
1121 @xref{Lexical Binding}, for an example of using a closure.
1123 Currently, an Emacs Lisp closure object is represented by a list
1124 with the symbol @code{closure} as the first element, a list
1125 representing the lexical environment as the second element, and the
1126 argument list and body forms as the remaining elements:
1129 ;; @r{lexical binding is enabled.}
1130 (lambda (x) (* x x))
1131 @result{} (closure (t) (x) (* x x))
1135 However, the fact that the internal structure of a closure is
1136 ``exposed'' to the rest of the Lisp world is considered an internal
1137 implementation detail. For this reason, we recommend against directly
1138 examining or altering the structure of closure objects.
1140 @node Advising Functions
1141 @section Advising Emacs Lisp Functions
1142 @cindex advising functions
1143 @cindex piece of advice
1145 Any variable or object field which holds a function can be modified with the
1146 appropriate setter function, such as @code{set-process-filter}, @code{fset}, or
1147 @code{setq}, but those can be too blunt, completely throwing away the
1150 In order to modify such hooks in a more controlled way, Emacs provides the
1151 macros @code{add-function} and @code{remove-function}, which let you modify the
1152 existing function value by composing it with another function.
1154 For example, in order to trace the calls to a process filter, you can use:
1157 (add-function :before (process-filter proc) #'my-tracing-function)
1160 This will cause the process's output to be passed first to
1161 @code{my-tracing-function} and then to the original process filter.
1162 When you're done with it, you can revert to the untraced behavior with:
1165 (remove-function (process-filter proc) #'my-tracing-function)
1168 The argument @code{:before} specifies how the two functions are composed, since
1169 there are many different ways to do it. The added function is also called an
1172 The function cell of a symbol can be manipulated similarly, but since it can
1173 contain other things than a plain function, you have to use @code{advice-add}
1174 and @code{advice-remove} instead, which
1175 @c use @code{add-function} and @code{remove-function} internally, but
1176 know how to handle cases such as when the function cell holds a macro rather
1177 than function, or when the function is autoloaded so the advice's activation
1178 needs to be postponed.
1181 * Advising Primitives:: Primitives to Manipulate Advices
1182 * Advising Named Functions:: Advising Named Functions
1185 @node Advising Primitives
1186 @subsection Primitives to manipulate advice
1188 @defmac add-function where place function &optional props
1189 This macro is the handy way to add the advice @var{function} to the function
1190 stored in @var{place} (@pxref{Generalized Variables}).
1192 @var{where} determines how @var{function} is composed with the
1193 existing function. It can be one of the following:
1197 Call @var{function} before the old function. Both functions receive the
1198 same arguments, and the return value of the composition is the return value of
1199 the old function. More specifically, the composition of the two functions
1202 (lambda (&rest r) (apply @var{function} r) (apply @var{oldfun} r))
1204 This is similar to @code{(add-hook @var{hook} @var{function})}, except that it
1205 applies to single-function hooks rather than normal hooks.
1208 Call @var{function} after the old function. Both functions receive the
1209 same arguments, and the return value of the composition is the return value of
1210 the old function. More specifically, the composition of the two functions
1213 (lambda (&rest r) (prog1 (apply @var{oldfun} r) (apply @var{function} r)))
1215 This is similar to @code{(add-hook @var{hook} @var{function} nil 'append)},
1216 except that it applies to single-function hooks rather than normal hooks.
1219 This completely replaces the old function with the new one. The old function
1220 can of course be recovered if you later call @code{remove-function}.
1223 Call @var{function} instead of the old function, but provide the old function
1224 as an extra argument to @var{function}. This is the most flexible composition.
1225 For example, it lets you call the old function with different arguments, or
1226 within a let-binding, or you can sometimes delegate the work to the old
1227 function and sometimes override it completely. More specifically, the
1228 composition of the two functions behaves like:
1230 (lambda (&rest r) (apply @var{function} @var{oldfun} r))
1234 Call @var{function} before the old function and don't call the old
1235 function if @var{function} returns @code{nil}. Both functions receive the
1236 same arguments, and the return value of the composition is the return value of
1237 the old function. More specifically, the composition of the two functions
1240 (lambda (&rest r) (and (apply @var{function} r) (apply @var{oldfun} r)))
1242 This is reminiscent of @code{(add-hook @var{hook} @var{function})}, when
1243 @var{hook} is run via @code{run-hook-with-args-until-failure}.
1246 Call @var{function} before the old function and only call the old function if
1247 @var{function} returns @code{nil}. More specifically, the composition of the
1248 two functions behaves like:
1250 (lambda (&rest r) (or (apply @var{function} r) (apply @var{oldfun} r)))
1252 This is reminiscent of @code{(add-hook @var{hook} @var{function})}, when
1253 @var{hook} is run via @code{run-hook-with-args-until-success}.
1256 Call @var{function} after the old function and only if the old function
1257 returned non-@code{nil}. Both functions receive the same arguments, and the
1258 return value of the composition is the return value of @var{function}.
1259 More specifically, the composition of the two functions behaves like:
1261 (lambda (&rest r) (and (apply @var{oldfun} r) (apply @var{function} r)))
1263 This is reminiscent of @code{(add-hook @var{hook} @var{function} nil 'append)},
1264 when @var{hook} is run via @code{run-hook-with-args-until-failure}.
1267 Call @var{function} after the old function and only if the old function
1268 returned @code{nil}. More specifically, the composition of the two functions
1271 (lambda (&rest r) (or (apply @var{oldfun} r) (apply @var{function} r)))
1273 This is reminiscent of @code{(add-hook @var{hook} @var{function} nil 'append)},
1274 when @var{hook} is run via @code{run-hook-with-args-until-success}.
1277 Call @var{function} first and use the result (which should be a list) as the
1278 new arguments to pass to the old function. More specifically, the composition
1279 of the two functions behaves like:
1281 (lambda (&rest r) (apply @var{oldfun} (funcall @var{function} r)))
1284 @item :filter-return
1285 Call the old function first and pass the result to @var{function}.
1286 More specifically, the composition of the two functions behaves like:
1288 (lambda (&rest r) (funcall @var{function} (apply @var{oldfun} r)))
1292 When modifying a variable (whose name will usually end with @code{-function}),
1293 you can choose whether @var{function} is used globally or only in the current
1294 buffer: if @var{place} is just a symbol, then @var{function} is added to the
1295 global value of @var{place}. Whereas if @var{place} is of the form
1296 @code{(local @var{symbol})}, where @var{symbol} is an expression which returns
1297 the variable name, then @var{function} will only be added in the
1300 Every function added with @code{add-function} can be accompanied by an
1301 association list of properties @var{props}. Currently only two of those
1302 properties have a special meaning:
1306 This gives a name to the advice, which @code{remove-function} can use to
1307 identify which function to remove. Typically used when @var{function} is an
1311 This specifies where to place the advice, in case several advices are present.
1312 By default, the depth is 0. A depth of 100 indicates that this advice should
1313 be kept as deep as possible, whereas a depth of -100 indicates that it
1314 should stay as the outermost advice. When two advices specify the same depth,
1315 the most recently added advice will be outermost.
1319 @defmac remove-function place function
1320 This macro removes @var{function} from the function stored in
1321 @var{place}. This only works if @var{function} was added to @var{place}
1322 using @code{add-function}.
1324 @var{function} is compared with functions added to @var{place} using
1325 @code{equal}, to try and make it work also with lambda expressions. It is
1326 additionally compared also with the @code{name} property of the functions added
1327 to @var{place}, which can be more reliable than comparing lambda expressions
1331 @defun advice-function-member-p advice function-def
1332 Return non-@code{nil} if @var{advice} is already in @var{function-def}.
1333 Like for @code{remove-function} above, instead of @var{advice} being the actual
1334 function, it can also be the @code{name} of the piece of advice.
1337 @defun advice-function-mapc f function-def
1338 Call the function @var{f} for every advice that was added to
1339 @var{function-def}. @var{f} is called with two arguments: the advice function
1343 @node Advising Named Functions
1344 @subsection Advising Named Functions
1346 A common use of advice is for named functions and macros.
1347 Since @code{add-function} does not know how to deal with macros and
1348 autoloaded functions, Emacs provides a separate set of functions to
1349 manipulate pieces of advice applied to named functions.
1351 Advice can be useful for altering the behavior of an existing
1352 function without having to redefine the whole function. However, it
1353 can be a source of bugs, since existing callers to the function may
1354 assume the old behavior, and work incorrectly when the behavior is
1355 changed by advice. Advice can also cause confusion in debugging, if
1356 the person doing the debugging does not notice or remember that the
1357 function has been modified by advice.
1359 For these reasons, advice should be reserved for the cases where you
1360 cannot modify a function's behavior in any other way. If it is
1361 possible to do the same thing via a hook, that is preferable
1362 (@pxref{Hooks}). If you simply want to change what a particular key
1363 does, it may be better to write a new command, and remap the old
1364 command's key bindings to the new one (@pxref{Remapping Commands}).
1365 In particular, Emacs's own source files should not put advice on
1366 functions in Emacs. (There are currently a few exceptions to this
1367 convention, but we aim to correct them.)
1369 Macros can also be advised, in much the same way as functions.
1370 However, special forms (@pxref{Special Forms}) cannot be advised.
1372 It is possible to advise a primitive (@pxref{What Is a Function}),
1373 but one should typically @emph{not} do so, for two reasons. Firstly,
1374 some primitives are used by the advice mechanism, and advising them
1375 could cause an infinite recursion. Secondly, many primitives are
1376 called directly from C, and such calls ignore advice; hence, one ends
1377 up in a confusing situation where some calls (occurring from Lisp
1378 code) obey the advice and other calls (from C code) do not.
1380 @defun advice-add symbol where function &optional props
1381 Add the advice @var{function} to the named function @var{symbol}.
1382 @var{where} and @var{props} have the same meaning as for @code{add-function}
1383 (@pxref{Advising Primitives}).
1386 @defun advice-remove symbol function
1387 Remove the advice @var{function} from the named function @var{symbol}.
1388 @var{function} can also be the @code{name} of an advice.
1391 @defun advice-member-p function symbol
1392 Return non-@code{nil} if the advice @var{function} is already in the named
1393 function @var{symbol}. @var{function} can also be the @code{name} of
1397 @defun advice-mapc function symbol
1398 Call @var{function} for every advice that was added to the named function
1399 @var{symbol}. @var{function} is called with two arguments: the advice function
1403 @node Obsolete Functions
1404 @section Declaring Functions Obsolete
1405 @cindex obsolete functions
1407 You can mark a named function as @dfn{obsolete}, meaning that it may
1408 be removed at some point in the future. This causes Emacs to warn
1409 that the function is obsolete whenever it byte-compiles code
1410 containing that function, and whenever it displays the documentation
1411 for that function. In all other respects, an obsolete function
1412 behaves like any other function.
1414 The easiest way to mark a function as obsolete is to put a
1415 @code{(declare (obsolete @dots{}))} form in the function's
1416 @code{defun} definition. @xref{Declare Form}. Alternatively, you can
1417 use the @code{make-obsolete} function, described below.
1419 A macro (@pxref{Macros}) can also be marked obsolete with
1420 @code{make-obsolete}; this has the same effects as for a function. An
1421 alias for a function or macro can also be marked as obsolete; this
1422 makes the alias itself obsolete, not the function or macro which it
1425 @defun make-obsolete obsolete-name current-name &optional when
1426 This function marks @var{obsolete-name} as obsolete.
1427 @var{obsolete-name} should be a symbol naming a function or macro, or
1428 an alias for a function or macro.
1430 If @var{current-name} is a symbol, the warning message says to use
1431 @var{current-name} instead of @var{obsolete-name}. @var{current-name}
1432 does not need to be an alias for @var{obsolete-name}; it can be a
1433 different function with similar functionality. @var{current-name} can
1434 also be a string, which serves as the warning message. The message
1435 should begin in lower case, and end with a period. It can also be
1436 @code{nil}, in which case the warning message provides no additional
1439 If provided, @var{when} should be a string indicating when the function
1440 was first made obsolete---for example, a date or a release number.
1443 @defmac define-obsolete-function-alias obsolete-name current-name &optional when doc
1444 This convenience macro marks the function @var{obsolete-name} obsolete
1445 and also defines it as an alias for the function @var{current-name}.
1446 It is equivalent to the following:
1449 (defalias @var{obsolete-name} @var{current-name} @var{doc})
1450 (make-obsolete @var{obsolete-name} @var{current-name} @var{when})
1454 In addition, you can mark a certain a particular calling convention
1455 for a function as obsolete:
1457 @defun set-advertised-calling-convention function signature when
1458 This function specifies the argument list @var{signature} as the
1459 correct way to call @var{function}. This causes the Emacs byte
1460 compiler to issue a warning whenever it comes across an Emacs Lisp
1461 program that calls @var{function} any other way (however, it will
1462 still allow the code to be byte compiled). @var{when} should be a
1463 string indicating when the variable was first made obsolete (usually a
1464 version number string).
1466 For instance, in old versions of Emacs the @code{sit-for} function
1467 accepted three arguments, like this
1470 (sit-for seconds milliseconds nodisp)
1473 However, calling @code{sit-for} this way is considered obsolete
1474 (@pxref{Waiting}). The old calling convention is deprecated like
1478 (set-advertised-calling-convention
1479 'sit-for '(seconds &optional nodisp) "22.1")
1483 @node Inline Functions
1484 @section Inline Functions
1485 @cindex inline functions
1487 An @dfn{inline function} is a function that works just like an
1488 ordinary function, except for one thing: when you byte-compile a call
1489 to the function (@pxref{Byte Compilation}), the function's definition
1490 is expanded into the caller. To define an inline function, use
1491 @code{defsubst} instead of @code{defun}.
1493 @defmac defsubst name args [doc] [declare] [interactive] body@dots{}
1494 This macro defines an inline function. Its syntax is exactly the same
1495 as @code{defun} (@pxref{Defining Functions}).
1498 Making a function inline often makes its function calls run faster.
1499 But it also has disadvantages. For one thing, it reduces flexibility;
1500 if you change the definition of the function, calls already inlined
1501 still use the old definition until you recompile them.
1503 Another disadvantage is that making a large function inline can
1504 increase the size of compiled code both in files and in memory. Since
1505 the speed advantage of inline functions is greatest for small
1506 functions, you generally should not make large functions inline.
1508 Also, inline functions do not behave well with respect to debugging,
1509 tracing, and advising (@pxref{Advising Functions}). Since ease of
1510 debugging and the flexibility of redefining functions are important
1511 features of Emacs, you should not make a function inline, even if it's
1512 small, unless its speed is really crucial, and you've timed the code
1513 to verify that using @code{defun} actually has performance problems.
1515 It's possible to define a macro to expand into the same code that an
1516 inline function would execute (@pxref{Macros}). But the macro would
1517 be limited to direct use in expressions---a macro cannot be called
1518 with @code{apply}, @code{mapcar} and so on. Also, it takes some work
1519 to convert an ordinary function into a macro. To convert it into an
1520 inline function is easy; just replace @code{defun} with
1521 @code{defsubst}. Since each argument of an inline function is
1522 evaluated exactly once, you needn't worry about how many times the
1523 body uses the arguments, as you do for macros.
1525 After an inline function is defined, its inline expansion can be
1526 performed later on in the same file, just like macros.
1529 @section The @code{declare} Form
1532 @code{declare} is a special macro which can be used to add ``meta''
1533 properties to a function or macro: for example, marking it as
1534 obsolete, or giving its forms a special @key{TAB} indentation
1535 convention in Emacs Lisp mode.
1537 @anchor{Definition of declare}
1538 @defmac declare specs@dots{}
1539 This macro ignores its arguments and evaluates to @code{nil}; it has
1540 no run-time effect. However, when a @code{declare} form occurs in the
1541 @var{declare} argument of a @code{defun} or @code{defsubst} function
1542 definition (@pxref{Defining Functions}) or a @code{defmacro} macro
1543 definition (@pxref{Defining Macros}), it appends the properties
1544 specified by @var{specs} to the function or macro. This work is
1545 specially performed by @code{defun}, @code{defsubst}, and
1548 Each element in @var{specs} should have the form @code{(@var{property}
1549 @var{args}@dots{})}, which should not be quoted. These have the
1553 @item (advertised-calling-convention @var{signature} @var{when})
1554 This acts like a call to @code{set-advertised-calling-convention}
1555 (@pxref{Obsolete Functions}); @var{signature} specifies the correct
1556 argument list for calling the function or macro, and @var{when} should
1557 be a string indicating when the old argument list was first made obsolete.
1559 @item (debug @var{edebug-form-spec})
1560 This is valid for macros only. When stepping through the macro with
1561 Edebug, use @var{edebug-form-spec}. @xref{Instrumenting Macro Calls}.
1563 @item (doc-string @var{n})
1564 This is used when defining a function or macro which itself will be used to
1565 define entities like functions, macros, or variables. It indicates that
1566 the @var{n}th argument, if any, should be considered
1567 as a documentation string.
1569 @item (indent @var{indent-spec})
1570 Indent calls to this function or macro according to @var{indent-spec}.
1571 This is typically used for macros, though it works for functions too.
1572 @xref{Indenting Macros}.
1574 @item (obsolete @var{current-name} @var{when})
1575 Mark the function or macro as obsolete, similar to a call to
1576 @code{make-obsolete} (@pxref{Obsolete Functions}). @var{current-name}
1577 should be a symbol (in which case the warning message says to use that
1578 instead), a string (specifying the warning message), or @code{nil} (in
1579 which case the warning message gives no extra details). @var{when}
1580 should be a string indicating when the function or macro was first
1583 @item (compiler-macro @var{expander})
1584 This can only be used for functions, and tells the compiler to use
1585 @var{expander} as an optimization function. When encountering a call to the
1586 function, of the form @code{(@var{function} @var{args}@dots{})}, the macro
1587 expander will call @var{expander} with that form as well as with
1588 @var{args}@dots{}, and @var{expander} can either return a new expression to use
1589 instead of the function call, or it can return just the form unchanged,
1590 to indicate that the function call should be left alone. @var{expander} can
1591 be a symbol, or it can be a form @code{(lambda (@var{arg}) @var{body})} in
1592 which case @var{arg} will hold the original function call expression, and the
1593 (unevaluated) arguments to the function can be accessed using the function's
1596 @item (gv-expander @var{expander})
1597 Declare @var{expander} to be the function to handle calls to the macro (or
1598 function) as a generalized variable, similarly to @code{gv-define-expander}.
1599 @var{expander} can be a symbol or it can be of the form @code{(lambda
1600 (@var{arg}) @var{body})} in which case that function will additionally have
1601 access to the macro (or function)'s arguments.
1603 @item (gv-setter @var{setter})
1604 Declare @var{setter} to be the function to handle calls to the macro (or
1605 function) as a generalized variable. @var{setter} can be a symbol in which
1606 case it will be passed to @code{gv-define-simple-setter}, or it can be of the
1607 form @code{(lambda (@var{arg}) @var{body})} in which case that function will
1608 additionally have access to the macro (or function)'s arguments and it will
1609 passed to @code{gv-define-setter}.
1615 @node Declaring Functions
1616 @section Telling the Compiler that a Function is Defined
1617 @cindex function declaration
1618 @cindex declaring functions
1619 @findex declare-function
1621 Byte-compiling a file often produces warnings about functions that the
1622 compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this
1623 indicates a real problem, but usually the functions in question are
1624 defined in other files which would be loaded if that code is run. For
1625 example, byte-compiling @file{fortran.el} used to warn:
1629 fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not
1630 known to be defined.
1633 In fact, @code{gud-find-c-expr} is only used in the function that
1634 Fortran mode uses for the local value of
1635 @code{gud-find-expr-function}, which is a callback from GUD; if it is
1636 called, the GUD functions will be loaded. When you know that such a
1637 warning does not indicate a real problem, it is good to suppress the
1638 warning. That makes new warnings which might mean real problems more
1639 visible. You do that with @code{declare-function}.
1641 All you need to do is add a @code{declare-function} statement before the
1642 first use of the function in question:
1645 (declare-function gud-find-c-expr "gud.el" nil)
1648 This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
1649 @samp{.el} can be omitted). The compiler takes for granted that that file
1650 really defines the function, and does not check.
1652 The optional third argument specifies the argument list of
1653 @code{gud-find-c-expr}. In this case, it takes no arguments
1654 (@code{nil} is different from not specifying a value). In other
1655 cases, this might be something like @code{(file &optional overwrite)}.
1656 You don't have to specify the argument list, but if you do the
1657 byte compiler can check that the calls match the declaration.
1659 @defmac declare-function function file &optional arglist fileonly
1660 Tell the byte compiler to assume that @var{function} is defined, with
1661 arguments @var{arglist}, and that the definition should come from the
1662 file @var{file}. @var{fileonly} non-@code{nil} means only check that
1663 @var{file} exists, not that it actually defines @var{function}.
1666 To verify that these functions really are declared where
1667 @code{declare-function} says they are, use @code{check-declare-file}
1668 to check all @code{declare-function} calls in one source file, or use
1669 @code{check-declare-directory} check all the files in and under a
1672 These commands find the file that ought to contain a function's
1673 definition using @code{locate-library}; if that finds no file, they
1674 expand the definition file name relative to the directory of the file
1675 that contains the @code{declare-function} call.
1677 You can also say that a function is a primitive by specifying a file
1678 name ending in @samp{.c} or @samp{.m}. This is useful only when you
1679 call a primitive that is defined only on certain systems. Most
1680 primitives are always defined, so they will never give you a warning.
1682 Sometimes a file will optionally use functions from an external package.
1683 If you prefix the filename in the @code{declare-function} statement with
1684 @samp{ext:}, then it will be checked if it is found, otherwise skipped
1687 There are some function definitions that @samp{check-declare} does not
1688 understand (e.g., @code{defstruct} and some other macros). In such cases,
1689 you can pass a non-@code{nil} @var{fileonly} argument to
1690 @code{declare-function}, meaning to only check that the file exists, not
1691 that it actually defines the function. Note that to do this without
1692 having to specify an argument list, you should set the @var{arglist}
1693 argument to @code{t} (because @code{nil} means an empty argument list, as
1694 opposed to an unspecified one).
1696 @node Function Safety
1697 @section Determining whether a Function is Safe to Call
1698 @cindex function safety
1699 @cindex safety of functions
1701 Some major modes, such as SES, call functions that are stored in user
1702 files. (@inforef{Top, ,ses}, for more information on SES@.) User
1703 files sometimes have poor pedigrees---you can get a spreadsheet from
1704 someone you've just met, or you can get one through email from someone
1705 you've never met. So it is risky to call a function whose source code
1706 is stored in a user file until you have determined that it is safe.
1708 @defun unsafep form &optional unsafep-vars
1709 Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or
1710 returns a list that describes why it might be unsafe. The argument
1711 @var{unsafep-vars} is a list of symbols known to have temporary
1712 bindings at this point; it is mainly used for internal recursive
1713 calls. The current buffer is an implicit argument, which provides a
1714 list of buffer-local bindings.
1717 Being quick and simple, @code{unsafep} does a very light analysis and
1718 rejects many Lisp expressions that are actually safe. There are no
1719 known cases where @code{unsafep} returns @code{nil} for an unsafe
1720 expression. However, a ``safe'' Lisp expression can return a string
1721 with a @code{display} property, containing an associated Lisp
1722 expression to be executed after the string is inserted into a buffer.
1723 This associated expression can be a virus. In order to be safe, you
1724 must delete properties from all strings calculated by user code before
1725 inserting them into buffers.
1728 What is a safe Lisp expression? Basically, it's an expression that
1729 calls only built-in functions with no side effects (or only innocuous
1730 ones). Innocuous side effects include displaying messages and
1731 altering non-risky buffer-local variables (but not global variables).
1734 @item Safe expression
1737 An atom or quoted thing.
1739 A call to a safe function (see below), if all its arguments are
1742 One of the special forms @code{and}, @code{catch}, @code{cond},
1743 @code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn},
1744 @code{while}, and @code{unwind-protect}], if all its arguments are
1747 A form that creates temporary bindings (@code{condition-case},
1748 @code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or
1749 @code{let*}), if all args are safe and the symbols to be bound are not
1750 explicitly risky (see @pxref{File Local Variables}).
1752 An assignment using @code{add-to-list}, @code{setq}, @code{push}, or
1753 @code{pop}, if all args are safe and the symbols to be assigned are
1754 not explicitly risky and they already have temporary or buffer-local
1757 One of [apply, mapc, mapcar, mapconcat] if the first argument is a
1758 safe explicit lambda and the other args are safe expressions.
1764 A lambda containing safe expressions.
1766 A symbol on the list @code{safe-functions}, so the user says it's safe.
1768 A symbol with a non-@code{nil} @code{side-effect-free} property.
1770 A symbol with a non-@code{nil} @code{safe-function} property. The
1771 value @code{t} indicates a function that is safe but has innocuous
1772 side effects. Other values will someday indicate functions with
1773 classes of side effects that are not always safe.
1776 The @code{side-effect-free} and @code{safe-function} properties are
1777 provided for built-in functions and for low-level functions and macros
1778 defined in @file{subr.el}. You can assign these properties for the
1779 functions you write.
1783 @node Related Topics
1784 @section Other Topics Related to Functions
1786 Here is a table of several functions that do things related to
1787 function calling and function definitions. They are documented
1788 elsewhere, but we provide cross references here.
1792 See @ref{Calling Functions}.
1797 @item call-interactively
1798 See @ref{Interactive Call}.
1800 @item called-interactively-p
1801 See @ref{Distinguish Interactive}.
1804 See @ref{Interactive Call}.
1807 See @ref{Accessing Documentation}.
1813 See @ref{Calling Functions}.
1816 See @ref{Anonymous Functions}.
1819 See @ref{Calling Functions}.
1821 @item indirect-function
1822 See @ref{Function Indirection}.
1825 See @ref{Using Interactive}.
1828 See @ref{Distinguish Interactive}.
1831 See @ref{Creating Symbols}.
1834 See @ref{Mapping Functions}.
1836 @item map-char-table
1837 See @ref{Char-Tables}.
1840 See @ref{Mapping Functions}.
1843 See @ref{Functions for Key Lookup}.