2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
5 @c Free Software Foundation, Inc.
6 @c See the file elisp.texi for copying conditions.
7 @setfilename ../../info/functions
8 @node Functions, Macros, Variables, Top
11 A Lisp program is composed mainly of Lisp functions. This chapter
12 explains what functions are, how they accept arguments, and how to
16 * What Is a Function:: Lisp functions vs. primitives; terminology.
17 * Lambda Expressions:: How functions are expressed as Lisp objects.
18 * Function Names:: A symbol can serve as the name of a function.
19 * Defining Functions:: Lisp expressions for defining functions.
20 * Calling Functions:: How to use an existing function.
21 * Mapping Functions:: Applying a function to each element of a list, etc.
22 * Anonymous Functions:: Lambda expressions are functions with no names.
23 * Function Cells:: Accessing or setting the function definition
25 * Obsolete Functions:: Declaring functions obsolete.
26 * Inline Functions:: Defining functions that the compiler will open code.
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.
33 @node What Is a Function
34 @section What Is a Function?
36 In a general sense, a function is a rule for carrying on a computation
37 given several values called @dfn{arguments}. The result of the
38 computation is called the value of the function. The computation can
39 also have side effects: lasting changes in the values of variables or
40 the contents of data structures.
42 Here are important terms for functions in Emacs Lisp and for other
43 function-like objects.
48 In Emacs Lisp, a @dfn{function} is anything that can be applied to
49 arguments in a Lisp program. In some cases, we use it more
50 specifically to mean a function written in Lisp. Special forms and
51 macros are not functions.
56 @cindex built-in function
57 A @dfn{primitive} is a function callable from Lisp that is written in C,
58 such as @code{car} or @code{append}. These functions are also called
59 @dfn{built-in functions}, or @dfn{subrs}. (Special forms are also
60 considered primitives.)
62 Usually the reason we implement a function as a primitive is either
63 because it is fundamental, because it provides a low-level interface
64 to operating system services, or because it needs to run fast.
65 Primitives can be modified or added only by changing the C sources and
66 recompiling the editor. See @ref{Writing Emacs Primitives}.
68 @item lambda expression
69 A @dfn{lambda expression} is a function written in Lisp.
70 These are described in the following section.
72 @xref{Lambda Expressions}.
76 A @dfn{special form} is a primitive that is like a function but does not
77 evaluate all of its arguments in the usual way. It may evaluate only
78 some of the arguments, or may evaluate them in an unusual order, or
79 several times. Many special forms are described in @ref{Control
84 A @dfn{macro} is a construct defined in Lisp by the programmer. It
85 differs from a function in that it translates a Lisp expression that you
86 write into an equivalent expression to be evaluated instead of the
87 original expression. Macros enable Lisp programmers to do the sorts of
88 things that special forms can do. @xref{Macros}, for how to define and
93 A @dfn{command} is an object that @code{command-execute} can invoke; it
94 is a possible definition for a key sequence. Some functions are
95 commands; a function written in Lisp is a command if it contains an
96 interactive declaration (@pxref{Defining Commands}). Such a function
97 can be called from Lisp expressions like other functions; in this case,
98 the fact that the function is a command makes no difference.
100 Keyboard macros (strings and vectors) are commands also, even though
101 they are not functions. A symbol is a command if its function
102 definition is a command; such symbols can be invoked with @kbd{M-x}.
103 The symbol is a function as well if the definition is a function.
104 @xref{Interactive Call}.
106 @item keystroke command
107 @cindex keystroke command
108 A @dfn{keystroke command} is a command that is bound to a key sequence
109 (typically one to three keystrokes). The distinction is made here
110 merely to avoid confusion with the meaning of ``command'' in non-Emacs
111 editors; for Lisp programs, the distinction is normally unimportant.
113 @item byte-code function
114 A @dfn{byte-code function} is a function that has been compiled by the
115 byte compiler. @xref{Byte-Code Type}.
118 @defun functionp object
119 This function returns @code{t} if @var{object} is any kind of
120 function, i.e.@: can be passed to @code{funcall}. Note that
121 @code{functionp} returns @code{nil} for special forms (@pxref{Special
125 Unlike @code{functionp}, the next three functions do @emph{not}
126 treat a symbol as its function definition.
129 This function returns @code{t} if @var{object} is a built-in function
130 (i.e., a Lisp primitive).
134 (subrp 'message) ; @r{@code{message} is a symbol,}
135 @result{} nil ; @r{not a subr object.}
138 (subrp (symbol-function 'message))
144 @defun byte-code-function-p object
145 This function returns @code{t} if @var{object} is a byte-code
146 function. For example:
150 (byte-code-function-p (symbol-function 'next-line))
156 @defun subr-arity subr
157 This function provides information about the argument list of a
158 primitive, @var{subr}. The returned value is a pair
159 @code{(@var{min} . @var{max})}. @var{min} is the minimum number of
160 args. @var{max} is the maximum number or the symbol @code{many}, for a
161 function with @code{&rest} arguments, or the symbol @code{unevalled} if
162 @var{subr} is a special form.
165 @node Lambda Expressions
166 @section Lambda Expressions
167 @cindex lambda expression
169 A function written in Lisp is a list that looks like this:
172 (lambda (@var{arg-variables}@dots{})
173 @r{[}@var{documentation-string}@r{]}
174 @r{[}@var{interactive-declaration}@r{]}
175 @var{body-forms}@dots{})
179 Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it
180 actually is valid as an expression---it evaluates to itself. In some
181 other Lisp dialects, a lambda expression is not a valid expression at
182 all. In either case, its main use is not to be evaluated as an
183 expression, but to be called as a function.
186 * Lambda Components:: The parts of a lambda expression.
187 * Simple Lambda:: A simple example.
188 * Argument List:: Details and special features of argument lists.
189 * Function Documentation:: How to put documentation in a function.
192 @node Lambda Components
193 @subsection Components of a Lambda Expression
197 A function written in Lisp (a ``lambda expression'') is a list that
201 (lambda (@var{arg-variables}@dots{})
202 [@var{documentation-string}]
203 [@var{interactive-declaration}]
204 @var{body-forms}@dots{})
209 The first element of a lambda expression is always the symbol
210 @code{lambda}. This indicates that the list represents a function. The
211 reason functions are defined to start with @code{lambda} is so that
212 other lists, intended for other uses, will not accidentally be valid as
215 The second element is a list of symbols---the argument variable names.
216 This is called the @dfn{lambda list}. When a Lisp function is called,
217 the argument values are matched up against the variables in the lambda
218 list, which are given local bindings with the values provided.
219 @xref{Local Variables}.
221 The documentation string is a Lisp string object placed within the
222 function definition to describe the function for the Emacs help
223 facilities. @xref{Function Documentation}.
225 The interactive declaration is a list of the form @code{(interactive
226 @var{code-string})}. This declares how to provide arguments if the
227 function is used interactively. Functions with this declaration are called
228 @dfn{commands}; they can be called using @kbd{M-x} or bound to a key.
229 Functions not intended to be called in this way should not have interactive
230 declarations. @xref{Defining Commands}, for how to write an interactive
233 @cindex body of function
234 The rest of the elements are the @dfn{body} of the function: the Lisp
235 code to do the work of the function (or, as a Lisp programmer would say,
236 ``a list of Lisp forms to evaluate''). The value returned by the
237 function is the value returned by the last element of the body.
240 @subsection A Simple Lambda-Expression Example
242 Consider for example the following function:
245 (lambda (a b c) (+ a b c))
249 We can call this function by writing it as the @sc{car} of an
250 expression, like this:
254 ((lambda (a b c) (+ a b c))
260 This call evaluates the body of the lambda expression with the variable
261 @code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.
262 Evaluation of the body adds these three numbers, producing the result 6;
263 therefore, this call to the function returns the value 6.
265 Note that the arguments can be the results of other function calls, as in
270 ((lambda (a b c) (+ a b c))
276 This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
277 4)} from left to right. Then it applies the lambda expression to the
278 argument values 1, 6 and 1 to produce the value 8.
280 It is not often useful to write a lambda expression as the @sc{car} of
281 a form in this way. You can get the same result, of making local
282 variables and giving them values, using the special form @code{let}
283 (@pxref{Local Variables}). And @code{let} is clearer and easier to use.
284 In practice, lambda expressions are either stored as the function
285 definitions of symbols, to produce named functions, or passed as
286 arguments to other functions (@pxref{Anonymous Functions}).
288 However, calls to explicit lambda expressions were very useful in the
289 old days of Lisp, before the special form @code{let} was invented. At
290 that time, they were the only way to bind and initialize local
294 @subsection Other Features of Argument Lists
295 @kindex wrong-number-of-arguments
296 @cindex argument binding
297 @cindex binding arguments
298 @cindex argument lists, features
300 Our simple sample function, @code{(lambda (a b c) (+ a b c))},
301 specifies three argument variables, so it must be called with three
302 arguments: if you try to call it with only two arguments or four
303 arguments, you get a @code{wrong-number-of-arguments} error.
305 It is often convenient to write a function that allows certain
306 arguments to be omitted. For example, the function @code{substring}
307 accepts three arguments---a string, the start index and the end
308 index---but the third argument defaults to the @var{length} of the
309 string if you omit it. It is also convenient for certain functions to
310 accept an indefinite number of arguments, as the functions @code{list}
313 @cindex optional arguments
314 @cindex rest arguments
317 To specify optional arguments that may be omitted when a function
318 is called, simply include the keyword @code{&optional} before the optional
319 arguments. To specify a list of zero or more extra arguments, include the
320 keyword @code{&rest} before one final argument.
322 Thus, the complete syntax for an argument list is as follows:
326 (@var{required-vars}@dots{}
327 @r{[}&optional @var{optional-vars}@dots{}@r{]}
328 @r{[}&rest @var{rest-var}@r{]})
333 The square brackets indicate that the @code{&optional} and @code{&rest}
334 clauses, and the variables that follow them, are optional.
336 A call to the function requires one actual argument for each of the
337 @var{required-vars}. There may be actual arguments for zero or more of
338 the @var{optional-vars}, and there cannot be any actual arguments beyond
339 that unless the lambda list uses @code{&rest}. In that case, there may
340 be any number of extra actual arguments.
342 If actual arguments for the optional and rest variables are omitted,
343 then they always default to @code{nil}. There is no way for the
344 function to distinguish between an explicit argument of @code{nil} and
345 an omitted argument. However, the body of the function is free to
346 consider @code{nil} an abbreviation for some other meaningful value.
347 This is what @code{substring} does; @code{nil} as the third argument to
348 @code{substring} means to use the length of the string supplied.
350 @cindex CL note---default optional arg
352 @b{Common Lisp note:} Common Lisp allows the function to specify what
353 default value to use when an optional argument is omitted; Emacs Lisp
354 always uses @code{nil}. Emacs Lisp does not support ``supplied-p''
355 variables that tell you whether an argument was explicitly passed.
358 For example, an argument list that looks like this:
361 (a b &optional c d &rest e)
365 binds @code{a} and @code{b} to the first two actual arguments, which are
366 required. If one or two more arguments are provided, @code{c} and
367 @code{d} are bound to them respectively; any arguments after the first
368 four are collected into a list and @code{e} is bound to that list. If
369 there are only two arguments, @code{c} is @code{nil}; if two or three
370 arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}
373 There is no way to have required arguments following optional
374 ones---it would not make sense. To see why this must be so, suppose
375 that @code{c} in the example were optional and @code{d} were required.
376 Suppose three actual arguments are given; which variable would the
377 third argument be for? Would it be used for the @var{c}, or for
378 @var{d}? One can argue for both possibilities. Similarly, it makes
379 no sense to have any more arguments (either required or optional)
380 after a @code{&rest} argument.
382 Here are some examples of argument lists and proper calls:
385 ((lambda (n) (1+ n)) ; @r{One required:}
386 1) ; @r{requires exactly one argument.}
388 ((lambda (n &optional n1) ; @r{One required and one optional:}
389 (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
392 ((lambda (n &rest ns) ; @r{One required and one rest:}
393 (+ n (apply '+ ns))) ; @r{1 or more arguments.}
398 @node Function Documentation
399 @subsection Documentation Strings of Functions
400 @cindex documentation of function
402 A lambda expression may optionally have a @dfn{documentation string} just
403 after the lambda list. This string does not affect execution of the
404 function; it is a kind of comment, but a systematized comment which
405 actually appears inside the Lisp world and can be used by the Emacs help
406 facilities. @xref{Documentation}, for how the @var{documentation-string} is
409 It is a good idea to provide documentation strings for all the
410 functions in your program, even those that are called only from within
411 your program. Documentation strings are like comments, except that they
412 are easier to access.
414 The first line of the documentation string should stand on its own,
415 because @code{apropos} displays just this first line. It should consist
416 of one or two complete sentences that summarize the function's purpose.
418 The start of the documentation string is usually indented in the
419 source file, but since these spaces come before the starting
420 double-quote, they are not part of the string. Some people make a
421 practice of indenting any additional lines of the string so that the
422 text lines up in the program source. @emph{That is a mistake.} The
423 indentation of the following lines is inside the string; what looks
424 nice in the source code will look ugly when displayed by the help
427 You may wonder how the documentation string could be optional, since
428 there are required components of the function that follow it (the body).
429 Since evaluation of a string returns that string, without any side effects,
430 it has no effect if it is not the last form in the body. Thus, in
431 practice, there is no confusion between the first form of the body and the
432 documentation string; if the only body form is a string then it serves both
433 as the return value and as the documentation.
435 The last line of the documentation string can specify calling
436 conventions different from the actual function arguments. Write
444 following a blank line, at the beginning of the line, with no newline
445 following it inside the documentation string. (The @samp{\} is used
446 to avoid confusing the Emacs motion commands.) The calling convention
447 specified in this way appears in help messages in place of the one
448 derived from the actual arguments of the function.
450 This feature is particularly useful for macro definitions, since the
451 arguments written in a macro definition often do not correspond to the
452 way users think of the parts of the macro call.
455 @section Naming a Function
456 @cindex function definition
457 @cindex named function
458 @cindex function name
460 In most computer languages, every function has a name; the idea of a
461 function without a name is nonsensical. In Lisp, a function in the
462 strictest sense has no name. It is simply a list whose first element is
463 @code{lambda}, a byte-code function object, or a primitive subr-object.
465 However, a symbol can serve as the name of a function. This happens
466 when you put the function in the symbol's @dfn{function cell}
467 (@pxref{Symbol Components}). Then the symbol itself becomes a valid,
468 callable function, equivalent to the list or subr-object that its
469 function cell refers to. The contents of the function cell are also
470 called the symbol's @dfn{function definition}. The procedure of using a
471 symbol's function definition in place of the symbol is called
472 @dfn{symbol function indirection}; see @ref{Function Indirection}.
474 In practice, nearly all functions are given names in this way and
475 referred to through their names. For example, the symbol @code{car} works
476 as a function and does what it does because the primitive subr-object
477 @code{#<subr car>} is stored in its function cell.
479 We give functions names because it is convenient to refer to them by
480 their names in Lisp expressions. For primitive subr-objects such as
481 @code{#<subr car>}, names are the only way you can refer to them: there
482 is no read syntax for such objects. For functions written in Lisp, the
483 name is more convenient to use in a call than an explicit lambda
484 expression. Also, a function with a name can refer to itself---it can
485 be recursive. Writing the function's name in its own definition is much
486 more convenient than making the function definition point to itself
487 (something that is not impossible but that has various disadvantages in
490 We often identify functions with the symbols used to name them. For
491 example, we often speak of ``the function @code{car},'' not
492 distinguishing between the symbol @code{car} and the primitive
493 subr-object that is its function definition. For most purposes, the
494 distinction is not important.
496 Even so, keep in mind that a function need not have a unique name. While
497 a given function object @emph{usually} appears in the function cell of only
498 one symbol, this is just a matter of convenience. It is easy to store
499 it in several symbols using @code{fset}; then each of the symbols is
500 equally well a name for the same function.
502 A symbol used as a function name may also be used as a variable; these
503 two uses of a symbol are independent and do not conflict. (Some Lisp
504 dialects, such as Scheme, do not distinguish between a symbol's value
505 and its function definition; a symbol's value as a variable is also its
506 function definition.) If you have not given a symbol a function
507 definition, you cannot use it as a function; whether the symbol has a
508 value as a variable makes no difference to this.
510 @node Defining Functions
511 @section Defining Functions
512 @cindex defining a function
514 We usually give a name to a function when it is first created. This
515 is called @dfn{defining a function}, and it is done with the
516 @code{defun} special form.
518 @defspec defun name argument-list body-forms
519 @code{defun} is the usual way to define new Lisp functions. It
520 defines the symbol @var{name} as a function that looks like this:
523 (lambda @var{argument-list} . @var{body-forms})
526 @code{defun} stores this lambda expression in the function cell of
527 @var{name}. It returns the value @var{name}, but usually we ignore this
530 As described previously, @var{argument-list} is a list of argument
531 names and may include the keywords @code{&optional} and @code{&rest}
532 (@pxref{Lambda Expressions}). Also, the first two of the
533 @var{body-forms} may be a documentation string and an interactive
536 There is no conflict if the same symbol @var{name} is also used as a
537 variable, since the symbol's value cell is independent of the function
538 cell. @xref{Symbol Components}.
540 Here are some examples:
553 (defun bar (a &optional b &rest c)
559 @result{} (1 2 (3 4 5))
563 @result{} (1 nil nil)
567 @error{} Wrong number of arguments.
571 (defun capitalize-backwards ()
572 "Upcase the last letter of a word."
578 @result{} capitalize-backwards
582 Be careful not to redefine existing functions unintentionally.
583 @code{defun} redefines even primitive functions such as @code{car}
584 without any hesitation or notification. Redefining a function already
585 defined is often done deliberately, and there is no way to distinguish
586 deliberate redefinition from unintentional redefinition.
589 @cindex function aliases
590 @defun defalias name definition &optional docstring
591 @anchor{Definition of defalias}
592 This special form defines the symbol @var{name} as a function, with
593 definition @var{definition} (which can be any valid Lisp function).
594 It returns @var{definition}.
596 If @var{docstring} is non-@code{nil}, it becomes the function
597 documentation of @var{name}. Otherwise, any documentation provided by
598 @var{definition} is used.
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 open-code it. @xref{Inline Functions}.
625 @node Calling Functions
626 @section Calling Functions
627 @cindex function invocation
628 @cindex calling a function
630 Defining functions is only half the battle. Functions don't do
631 anything until you @dfn{call} them, i.e., tell them to run. Calling a
632 function is also known as @dfn{invocation}.
634 The most common way of invoking a function is by evaluating a list.
635 For example, evaluating the list @code{(concat "a" "b")} calls the
636 function @code{concat} with arguments @code{"a"} and @code{"b"}.
637 @xref{Evaluation}, for a description of evaluation.
639 When you write a list as an expression in your program, you specify
640 which function to call, and how many arguments to give it, in the text
641 of the program. Usually that's just what you want. Occasionally you
642 need to compute at run time which function to call. To do that, use
643 the function @code{funcall}. When you also need to determine at run
644 time how many arguments to pass, use @code{apply}.
646 @defun funcall function &rest arguments
647 @code{funcall} calls @var{function} with @var{arguments}, and returns
648 whatever @var{function} returns.
650 Since @code{funcall} is a function, all of its arguments, including
651 @var{function}, are evaluated before @code{funcall} is called. This
652 means that you can use any expression to obtain the function to be
653 called. It also means that @code{funcall} does not see the
654 expressions you write for the @var{arguments}, only their values.
655 These values are @emph{not} evaluated a second time in the act of
656 calling @var{function}; the operation of @code{funcall} is like the
657 normal procedure for calling a function, once its arguments have
658 already been evaluated.
660 The argument @var{function} must be either a Lisp function or a
661 primitive function. Special forms and macros are not allowed, because
662 they make sense only when given the ``unevaluated'' argument
663 expressions. @code{funcall} cannot provide these because, as we saw
664 above, it never knows them in the first place.
676 (funcall f 'x 'y '(z))
681 @error{} Invalid function: #<subr and>
685 Compare these examples with the examples of @code{apply}.
688 @defun apply function &rest arguments
689 @code{apply} calls @var{function} with @var{arguments}, just like
690 @code{funcall} but with one difference: the last of @var{arguments} is a
691 list of objects, which are passed to @var{function} as separate
692 arguments, rather than a single list. We say that @code{apply}
693 @dfn{spreads} this list so that each individual element becomes an
696 @code{apply} returns the result of calling @var{function}. As with
697 @code{funcall}, @var{function} must either be a Lisp function or a
698 primitive function; special forms and macros do not make sense in
708 @error{} Wrong type argument: listp, z
711 (apply '+ 1 2 '(3 4))
715 (apply '+ '(1 2 3 4))
720 (apply 'append '((a b c) nil (x y z) nil))
721 @result{} (a b c x y z)
725 For an interesting example of using @code{apply}, see @ref{Definition
729 @cindex partial application of functions
731 Sometimes it is useful to fix some of the function's arguments at
732 certain values, and leave the rest of arguments for when the function
733 is actually called. The act of fixing some of the function's
734 arguments is called @dfn{partial application} of the function@footnote{
735 This is related to, but different from @dfn{currying}, which
736 transforms a function that takes multiple arguments in such a way that
737 it can be called as a chain of functions, each one with a single
739 The result is a new function that accepts the rest of
740 arguments and calls the original function with all the arguments
743 Here's how to do partial application in Emacs Lisp:
745 @defun apply-partially func &rest args
746 This function returns a new function which, when called, will call
747 @var{func} with the list of arguments composed from @var{args} and
748 additional arguments specified at the time of the call. If @var{func}
749 accepts @var{n} arguments, then a call to @code{apply-partially} with
750 @w{@code{@var{m} < @var{n}}} arguments will produce a new function of
751 @w{@code{@var{n} - @var{m}}} arguments.
753 Here's how we could define the built-in function @code{1+}, if it
754 didn't exist, using @code{apply-partially} and @code{+}, another
759 (defalias '1+ (apply-partially '+ 1)
760 "Increment argument by one.")
770 It is common for Lisp functions to accept functions as arguments or
771 find them in data structures (especially in hook variables and property
772 lists) and call them using @code{funcall} or @code{apply}. Functions
773 that accept function arguments are often called @dfn{functionals}.
775 Sometimes, when you call a functional, it is useful to supply a no-op
776 function as the argument. Here are two different kinds of no-op
780 This function returns @var{arg} and has no side effects.
783 @defun ignore &rest args
784 This function ignores any arguments and returns @code{nil}.
787 @node Mapping Functions
788 @section Mapping Functions
789 @cindex mapping functions
791 A @dfn{mapping function} applies a given function (@emph{not} a
792 special form or macro) to each element of a list or other collection.
793 Emacs Lisp has several such functions; @code{mapcar} and
794 @code{mapconcat}, which scan a list, are described here.
795 @xref{Definition of mapatoms}, for the function @code{mapatoms} which
796 maps over the symbols in an obarray. @xref{Definition of maphash},
797 for the function @code{maphash} which maps over key/value associations
800 These mapping functions do not allow char-tables because a char-table
801 is a sparse array whose nominal range of indices is very large. To map
802 over a char-table in a way that deals properly with its sparse nature,
803 use the function @code{map-char-table} (@pxref{Char-Tables}).
805 @defun mapcar function sequence
806 @anchor{Definition of mapcar}
807 @code{mapcar} applies @var{function} to each element of @var{sequence}
808 in turn, and returns a list of the results.
810 The argument @var{sequence} can be any kind of sequence except a
811 char-table; that is, a list, a vector, a bool-vector, or a string. The
812 result is always a list. The length of the result is the same as the
813 length of @var{sequence}. For example:
817 (mapcar 'car '((a b) (c d) (e f)))
821 (mapcar 'string "abc")
822 @result{} ("a" "b" "c")
826 ;; @r{Call each function in @code{my-hooks}.}
827 (mapcar 'funcall my-hooks)
831 (defun mapcar* (function &rest args)
832 "Apply FUNCTION to successive cars of all ARGS.
833 Return the list of results."
834 ;; @r{If no list is exhausted,}
835 (if (not (memq nil args))
836 ;; @r{apply function to @sc{car}s.}
837 (cons (apply function (mapcar 'car args))
838 (apply 'mapcar* function
839 ;; @r{Recurse for rest of elements.}
840 (mapcar 'cdr args)))))
844 (mapcar* 'cons '(a b c) '(1 2 3 4))
845 @result{} ((a . 1) (b . 2) (c . 3))
850 @defun mapc function sequence
851 @code{mapc} is like @code{mapcar} except that @var{function} is used for
852 side-effects only---the values it returns are ignored, not collected
853 into a list. @code{mapc} always returns @var{sequence}.
856 @defun mapconcat function sequence separator
857 @code{mapconcat} applies @var{function} to each element of
858 @var{sequence}: the results, which must be strings, are concatenated.
859 Between each pair of result strings, @code{mapconcat} inserts the string
860 @var{separator}. Usually @var{separator} contains a space or comma or
861 other suitable punctuation.
863 The argument @var{function} must be a function that can take one
864 argument and return a string. The argument @var{sequence} can be any
865 kind of sequence except a char-table; that is, a list, a vector, a
866 bool-vector, or a string.
870 (mapconcat 'symbol-name
871 '(The cat in the hat)
873 @result{} "The cat in the hat"
877 (mapconcat (function (lambda (x) (format "%c" (1+ x))))
885 @node Anonymous Functions
886 @section Anonymous Functions
887 @cindex anonymous function
889 In Lisp, a function is a list that starts with @code{lambda}, a
890 byte-code function compiled from such a list, or alternatively a
891 primitive subr-object; names are ``extra.'' Although functions are
892 usually defined with @code{defun} and given names at the same time, it
893 is occasionally more concise to use an explicit lambda expression---an
894 anonymous function. Such a list is valid wherever a function name is.
896 Any method of creating such a list makes a valid function. Even this:
900 (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
901 @result{} (lambda (x) (+ 12 x))
906 This computes a list that looks like @code{(lambda (x) (+ 12 x))} and
907 makes it the value (@emph{not} the function definition!) of
910 Here is how we might call this function:
920 It does @emph{not} work to write @code{(silly 1)}, because this
921 function is not the @emph{function definition} of @code{silly}. We
922 have not given @code{silly} any function definition, just a value as a
925 Most of the time, anonymous functions are constants that appear in
926 your program. For instance, you might want to pass one as an argument
927 to the function @code{mapcar}, which applies any given function to
928 each element of a list (@pxref{Mapping Functions}).
929 @xref{describe-symbols example}, for a realistic example of this.
931 In the following example, we define a @code{change-property}
932 function that takes a function as its third argument, followed by a
933 @code{double-property} function that makes use of
934 @code{change-property} by passing it an anonymous function:
938 (defun change-property (symbol prop function)
939 (let ((value (get symbol prop)))
940 (put symbol prop (funcall function value))))
944 (defun double-property (symbol prop)
945 (change-property symbol prop (lambda (x) (* 2 x))))
950 In the @code{double-property} function, we did not quote the
951 @code{lambda} form. This is permissible, because a @code{lambda} form
952 is @dfn{self-quoting}: evaluating the form yields the form itself.
954 Whether or not you quote a @code{lambda} form makes a difference if
955 you compile the code (@pxref{Byte Compilation}). If the @code{lambda}
956 form is unquoted, as in the above example, the anonymous function is
957 also compiled. Suppose, however, that we quoted the @code{lambda}
962 (defun double-property (symbol prop)
963 (change-property symbol prop '(lambda (x) (* 2 x))))
968 If you compile this, the argument passed to @code{change-property} is
969 the precise list shown:
976 The Lisp compiler cannot assume this list is a function, even though
977 it looks like one, since it does not know what @code{change-property}
978 will do with the list. Perhaps it will check whether the @sc{car} of
979 the third element is the symbol @code{*}!
982 The @code{function} special form explicitly tells the byte-compiler
983 that its argument is a function:
985 @defspec function function-object
986 @cindex function quoting
987 This special form returns @var{function-object} without evaluating it.
988 In this, it is equivalent to @code{quote}. However, it serves as a
989 note to the Emacs Lisp compiler that @var{function-object} is intended
990 to be used only as a function, and therefore can safely be compiled.
991 Contrast this with @code{quote}, in @ref{Quoting}.
994 @cindex @samp{#'} syntax
995 The read syntax @code{#'} is a short-hand for using @code{function}.
996 Generally, it is not necessary to use either @code{#'} or
997 @code{function}; just use an unquoted @code{lambda} form instead.
998 (Actually, @code{lambda} is a macro defined using @code{function}.)
999 The following forms are all equivalent:
1002 #'(lambda (x) (* x x))
1003 (function (lambda (x) (* x x)))
1004 (lambda (x) (* x x))
1007 We sometimes write @code{function} instead of @code{quote} when
1008 quoting the name of a function, but this usage is just a sort of
1012 (function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
1015 @node Function Cells
1016 @section Accessing Function Cell Contents
1018 The @dfn{function definition} of a symbol is the object stored in the
1019 function cell of the symbol. The functions described here access, test,
1020 and set the function cell of symbols.
1022 See also the function @code{indirect-function}. @xref{Definition of
1025 @defun symbol-function symbol
1026 @kindex void-function
1027 This returns the object in the function cell of @var{symbol}. If the
1028 symbol's function cell is void, a @code{void-function} error is
1031 This function does not check that the returned object is a legitimate
1036 (defun bar (n) (+ n 2))
1040 (symbol-function 'bar)
1041 @result{} (lambda (n) (+ n 2))
1048 (symbol-function 'baz)
1054 @cindex void function cell
1055 If you have never given a symbol any function definition, we say that
1056 that symbol's function cell is @dfn{void}. In other words, the function
1057 cell does not have any Lisp object in it. If you try to call such a symbol
1058 as a function, it signals a @code{void-function} error.
1060 Note that void is not the same as @code{nil} or the symbol
1061 @code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
1062 and can be stored into a function cell just as any other object can be
1063 (and they can be valid functions if you define them in turn with
1064 @code{defun}). A void function cell contains no object whatsoever.
1066 You can test the voidness of a symbol's function definition with
1067 @code{fboundp}. After you have given a symbol a function definition, you
1068 can make it void once more using @code{fmakunbound}.
1070 @defun fboundp symbol
1071 This function returns @code{t} if the symbol has an object in its
1072 function cell, @code{nil} otherwise. It does not check that the object
1073 is a legitimate function.
1076 @defun fmakunbound symbol
1077 This function makes @var{symbol}'s function cell void, so that a
1078 subsequent attempt to access this cell will cause a
1079 @code{void-function} error. It returns @var{symbol}. (See also
1080 @code{makunbound}, in @ref{Void Variables}.)
1097 @error{} Symbol's function definition is void: foo
1102 @defun fset symbol definition
1103 This function stores @var{definition} in the function cell of
1104 @var{symbol}. The result is @var{definition}. Normally
1105 @var{definition} should be a function or the name of a function, but
1106 this is not checked. The argument @var{symbol} is an ordinary evaluated
1109 There are three normal uses of this function:
1113 Copying one symbol's function definition to another---in other words,
1114 making an alternate name for a function. (If you think of this as the
1115 definition of the new name, you should use @code{defalias} instead of
1116 @code{fset}; see @ref{Definition of defalias}.)
1119 Giving a symbol a function definition that is not a list and therefore
1120 cannot be made with @code{defun}. For example, you can use @code{fset}
1121 to give a symbol @code{s1} a function definition which is another symbol
1122 @code{s2}; then @code{s1} serves as an alias for whatever definition
1123 @code{s2} presently has. (Once again use @code{defalias} instead of
1124 @code{fset} if you think of this as the definition of @code{s1}.)
1127 In constructs for defining or altering functions. If @code{defun}
1128 were not a primitive, it could be written in Lisp (as a macro) using
1132 Here are examples of these uses:
1136 ;; @r{Save @code{foo}'s definition in @code{old-foo}.}
1137 (fset 'old-foo (symbol-function 'foo))
1141 ;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
1142 ;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)}
1151 (symbol-function 'xfirst)
1155 (symbol-function (symbol-function 'xfirst))
1156 @result{} #<subr car>
1160 ;; @r{Define a named keyboard macro.}
1161 (fset 'kill-two-lines "\^u2\^k")
1166 ;; @r{Here is a function that alters other functions.}
1167 (defun copy-function-definition (new old)
1168 "Define NEW with the same function definition as OLD."
1169 (fset new (symbol-function old)))
1174 @code{fset} is sometimes used to save the old definition of a
1175 function before redefining it. That permits the new definition to
1176 invoke the old definition. But it is unmodular and unclean for a Lisp
1177 file to redefine a function defined elsewhere. If you want to modify
1178 a function defined by another package, it is cleaner to use
1179 @code{defadvice} (@pxref{Advising Functions}).
1181 @node Obsolete Functions
1182 @section Declaring Functions Obsolete
1184 You can use @code{make-obsolete} to declare a function obsolete. This
1185 indicates that the function may be removed at some stage in the future.
1187 @defun make-obsolete obsolete-name current-name &optional when
1188 This function makes the byte compiler warn that the function
1189 @var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the
1190 warning message says to use @var{current-name} instead of
1191 @var{obsolete-name}. @var{current-name} does not need to be an alias for
1192 @var{obsolete-name}; it can be a different function with similar
1193 functionality. If @var{current-name} is a string, it is the warning
1196 If provided, @var{when} should be a string indicating when the function
1197 was first made obsolete---for example, a date or a release number.
1200 You can define a function as an alias and declare it obsolete at the
1201 same time using the macro @code{define-obsolete-function-alias}:
1203 @defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
1204 This macro marks the function @var{obsolete-name} obsolete and also
1205 defines it as an alias for the function @var{current-name}. It is
1206 equivalent to the following:
1209 (defalias @var{obsolete-name} @var{current-name} @var{docstring})
1210 (make-obsolete @var{obsolete-name} @var{current-name} @var{when})
1214 In addition, you can mark a certain a particular calling convention
1215 for a function as obsolete:
1217 @defun set-advertised-calling-convention function signature
1218 This function specifies the argument list @var{signature} as the
1219 correct way to call @var{function}. This causes the Emacs byte
1220 compiler to issue a warning whenever it comes across an Emacs Lisp
1221 program that calls @var{function} any other way (however, it will
1222 still allow the code to be byte compiled).
1224 For instance, in old versions of Emacs the @code{sit-for} function
1225 accepted three arguments, like this
1228 (sit-for seconds milliseconds nodisp)
1231 However, calling @code{sit-for} this way is considered obsolete
1232 (@pxref{Waiting}). The old calling convention is deprecated like
1236 (set-advertised-calling-convention
1237 'sit-for '(seconds &optional nodisp))
1241 @node Inline Functions
1242 @section Inline Functions
1243 @cindex inline functions
1246 You can define an @dfn{inline function} by using @code{defsubst} instead
1247 of @code{defun}. An inline function works just like an ordinary
1248 function except for one thing: when you compile a call to the function,
1249 the function's definition is open-coded into the caller.
1251 Making a function inline makes explicit calls run faster. But it also
1252 has disadvantages. For one thing, it reduces flexibility; if you
1253 change the definition of the function, calls already inlined still use
1254 the old definition until you recompile them.
1256 Another disadvantage is that making a large function inline can increase
1257 the size of compiled code both in files and in memory. Since the speed
1258 advantage of inline functions is greatest for small functions, you
1259 generally should not make large functions inline.
1261 Also, inline functions do not behave well with respect to debugging,
1262 tracing, and advising (@pxref{Advising Functions}). Since ease of
1263 debugging and the flexibility of redefining functions are important
1264 features of Emacs, you should not make a function inline, even if it's
1265 small, unless its speed is really crucial, and you've timed the code
1266 to verify that using @code{defun} actually has performance problems.
1268 It's possible to define a macro to expand into the same code that an
1269 inline function would execute. (@xref{Macros}.) But the macro would be
1270 limited to direct use in expressions---a macro cannot be called with
1271 @code{apply}, @code{mapcar} and so on. Also, it takes some work to
1272 convert an ordinary function into a macro. To convert it into an inline
1273 function is very easy; simply replace @code{defun} with @code{defsubst}.
1274 Since each argument of an inline function is evaluated exactly once, you
1275 needn't worry about how many times the body uses the arguments, as you
1276 do for macros. (@xref{Argument Evaluation}.)
1278 Inline functions can be used and open-coded later on in the same file,
1279 following the definition, just like macros.
1281 @node Declaring Functions
1282 @section Telling the Compiler that a Function is Defined
1283 @cindex function declaration
1284 @cindex declaring functions
1285 @findex declare-function
1287 Byte-compiling a file often produces warnings about functions that the
1288 compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this
1289 indicates a real problem, but usually the functions in question are
1290 defined in other files which would be loaded if that code is run. For
1291 example, byte-compiling @file{fortran.el} used to warn:
1295 fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
1299 In fact, @code{gud-find-c-expr} is only used in the function that
1300 Fortran mode uses for the local value of
1301 @code{gud-find-expr-function}, which is a callback from GUD; if it is
1302 called, the GUD functions will be loaded. When you know that such a
1303 warning does not indicate a real problem, it is good to suppress the
1304 warning. That makes new warnings which might mean real problems more
1305 visible. You do that with @code{declare-function}.
1307 All you need to do is add a @code{declare-function} statement before the
1308 first use of the function in question:
1311 (declare-function gud-find-c-expr "gud.el" nil)
1314 This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
1315 @samp{.el} can be omitted). The compiler takes for granted that that file
1316 really defines the function, and does not check.
1318 The optional third argument specifies the argument list of
1319 @code{gud-find-c-expr}. In this case, it takes no arguments
1320 (@code{nil} is different from not specifying a value). In other
1321 cases, this might be something like @code{(file &optional overwrite)}.
1322 You don't have to specify the argument list, but if you do the
1323 byte compiler can check that the calls match the declaration.
1325 @defmac declare-function function file &optional arglist fileonly
1326 Tell the byte compiler to assume that @var{function} is defined, with
1327 arguments @var{arglist}, and that the definition should come from the
1328 file @var{file}. @var{fileonly} non-@code{nil} means only check that
1329 @var{file} exists, not that it actually defines @var{function}.
1332 To verify that these functions really are declared where
1333 @code{declare-function} says they are, use @code{check-declare-file}
1334 to check all @code{declare-function} calls in one source file, or use
1335 @code{check-declare-directory} check all the files in and under a
1338 These commands find the file that ought to contain a function's
1339 definition using @code{locate-library}; if that finds no file, they
1340 expand the definition file name relative to the directory of the file
1341 that contains the @code{declare-function} call.
1343 You can also say that a function is defined by C code by specifying a
1344 file name ending in @samp{.c} or @samp{.m}. @code{check-declare-file}
1345 looks for these files in the C source code directory. This is useful
1346 only when you call a function that is defined only on certain systems.
1347 Most of the primitive functions of Emacs are always defined so they will
1348 never give you a warning.
1350 Sometimes a file will optionally use functions from an external package.
1351 If you prefix the filename in the @code{declare-function} statement with
1352 @samp{ext:}, then it will be checked if it is found, otherwise skipped
1355 There are some function definitions that @samp{check-declare} does not
1356 understand (e.g. @code{defstruct} and some other macros). In such cases,
1357 you can pass a non-@code{nil} @var{fileonly} argument to
1358 @code{declare-function}, meaning to only check that the file exists, not
1359 that it actually defines the function. Note that to do this without
1360 having to specify an argument list, you should set the @var{arglist}
1361 argument to @code{t} (because @code{nil} means an empty argument list, as
1362 opposed to an unspecified one).
1364 @node Function Safety
1365 @section Determining whether a Function is Safe to Call
1366 @cindex function safety
1367 @cindex safety of functions
1369 Some major modes such as SES call functions that are stored in user
1370 files. (@inforef{Top, ,ses}, for more information on SES.) User
1371 files sometimes have poor pedigrees---you can get a spreadsheet from
1372 someone you've just met, or you can get one through email from someone
1373 you've never met. So it is risky to call a function whose source code
1374 is stored in a user file until you have determined that it is safe.
1376 @defun unsafep form &optional unsafep-vars
1377 Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or
1378 returns a list that describes why it might be unsafe. The argument
1379 @var{unsafep-vars} is a list of symbols known to have temporary
1380 bindings at this point; it is mainly used for internal recursive
1381 calls. The current buffer is an implicit argument, which provides a
1382 list of buffer-local bindings.
1385 Being quick and simple, @code{unsafep} does a very light analysis and
1386 rejects many Lisp expressions that are actually safe. There are no
1387 known cases where @code{unsafep} returns @code{nil} for an unsafe
1388 expression. However, a ``safe'' Lisp expression can return a string
1389 with a @code{display} property, containing an associated Lisp
1390 expression to be executed after the string is inserted into a buffer.
1391 This associated expression can be a virus. In order to be safe, you
1392 must delete properties from all strings calculated by user code before
1393 inserting them into buffers.
1396 What is a safe Lisp expression? Basically, it's an expression that
1397 calls only built-in functions with no side effects (or only innocuous
1398 ones). Innocuous side effects include displaying messages and
1399 altering non-risky buffer-local variables (but not global variables).
1402 @item Safe expression
1405 An atom or quoted thing.
1407 A call to a safe function (see below), if all its arguments are
1410 One of the special forms @code{and}, @code{catch}, @code{cond},
1411 @code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn},
1412 @code{while}, and @code{unwind-protect}], if all its arguments are
1415 A form that creates temporary bindings (@code{condition-case},
1416 @code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or
1417 @code{let*}), if all args are safe and the symbols to be bound are not
1418 explicitly risky (see @pxref{File Local Variables}).
1420 An assignment using @code{add-to-list}, @code{setq}, @code{push}, or
1421 @code{pop}, if all args are safe and the symbols to be assigned are
1422 not explicitly risky and they already have temporary or buffer-local
1425 One of [apply, mapc, mapcar, mapconcat] if the first argument is a
1426 safe explicit lambda and the other args are safe expressions.
1432 A lambda containing safe expressions.
1434 A symbol on the list @code{safe-functions}, so the user says it's safe.
1436 A symbol with a non-@code{nil} @code{side-effect-free} property.
1438 A symbol with a non-@code{nil} @code{safe-function} property. The
1439 value @code{t} indicates a function that is safe but has innocuous
1440 side effects. Other values will someday indicate functions with
1441 classes of side effects that are not always safe.
1444 The @code{side-effect-free} and @code{safe-function} properties are
1445 provided for built-in functions and for low-level functions and macros
1446 defined in @file{subr.el}. You can assign these properties for the
1447 functions you write.
1451 @node Related Topics
1452 @section Other Topics Related to Functions
1454 Here is a table of several functions that do things related to
1455 function calling and function definitions. They are documented
1456 elsewhere, but we provide cross references here.
1460 See @ref{Calling Functions}.
1465 @item call-interactively
1466 See @ref{Interactive Call}.
1468 @item called-interactively-p
1469 See @ref{Distinguish Interactive}.
1472 See @ref{Interactive Call}.
1475 See @ref{Accessing Documentation}.
1481 See @ref{Calling Functions}.
1484 See @ref{Anonymous Functions}.
1487 See @ref{Calling Functions}.
1489 @item indirect-function
1490 See @ref{Function Indirection}.
1493 See @ref{Using Interactive}.
1496 See @ref{Distinguish Interactive}.
1499 See @ref{Creating Symbols}.
1502 See @ref{Mapping Functions}.
1504 @item map-char-table
1505 See @ref{Char-Tables}.
1508 See @ref{Mapping Functions}.
1511 See @ref{Functions for Key Lookup}.
1515 arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2