2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2011
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/functions
7 @node Functions, Macros, Variables, Top
10 A Lisp program is composed mainly of Lisp functions. This chapter
11 explains what functions are, how they accept arguments, and how to
15 * What Is a Function:: Lisp functions vs. primitives; terminology.
16 * Lambda Expressions:: How functions are expressed as Lisp objects.
17 * Function Names:: A symbol can serve as the name of a function.
18 * Defining Functions:: Lisp expressions for defining functions.
19 * Calling Functions:: How to use an existing function.
20 * Mapping Functions:: Applying a function to each element of a list, etc.
21 * Anonymous Functions:: Lambda expressions are functions with no names.
22 * Function Cells:: Accessing or setting the function definition
24 * Obsolete Functions:: Declaring functions obsolete.
25 * Inline Functions:: Defining functions that the compiler will open code.
26 * Declaring Functions:: Telling the compiler that a function is defined.
27 * Function Safety:: Determining whether a function is safe to call.
28 * Related Topics:: Cross-references to specific Lisp primitives
29 that have a special bearing on how functions work.
32 @node What Is a Function
33 @section What Is a Function?
35 In a general sense, a function is a rule for carrying on a computation
36 given several values called @dfn{arguments}. The result of the
37 computation is called the value of the function. The computation can
38 also have side effects: lasting changes in the values of variables or
39 the contents of data structures.
41 Here are important terms for functions in Emacs Lisp and for other
42 function-like objects.
47 In Emacs Lisp, a @dfn{function} is anything that can be applied to
48 arguments in a Lisp program. In some cases, we use it more
49 specifically to mean a function written in Lisp. Special forms and
50 macros are not functions.
55 @cindex built-in function
56 A @dfn{primitive} is a function callable from Lisp that is written in C,
57 such as @code{car} or @code{append}. These functions are also called
58 @dfn{built-in functions}, or @dfn{subrs}. (Special forms are also
59 considered primitives.)
61 Usually the reason we implement a function as a primitive is either
62 because it is fundamental, because it provides a low-level interface
63 to operating system services, or because it needs to run fast.
64 Primitives can be modified or added only by changing the C sources and
65 recompiling the editor. See @ref{Writing Emacs Primitives}.
67 @item lambda expression
68 A @dfn{lambda expression} is a function written in Lisp.
69 These are described in the following section.
71 @xref{Lambda Expressions}.
75 A @dfn{special form} is a primitive that is like a function but does not
76 evaluate all of its arguments in the usual way. It may evaluate only
77 some of the arguments, or may evaluate them in an unusual order, or
78 several times. Many special forms are described in @ref{Control
83 A @dfn{macro} is a construct defined in Lisp by the programmer. It
84 differs from a function in that it translates a Lisp expression that you
85 write into an equivalent expression to be evaluated instead of the
86 original expression. Macros enable Lisp programmers to do the sorts of
87 things that special forms can do. @xref{Macros}, for how to define and
92 A @dfn{command} is an object that @code{command-execute} can invoke; it
93 is a possible definition for a key sequence. Some functions are
94 commands; a function written in Lisp is a command if it contains an
95 interactive declaration (@pxref{Defining Commands}). Such a function
96 can be called from Lisp expressions like other functions; in this case,
97 the fact that the function is a command makes no difference.
99 Keyboard macros (strings and vectors) are commands also, even though
100 they are not functions. A symbol is a command if its function
101 definition is a command; such symbols can be invoked with @kbd{M-x}.
102 The symbol is a function as well if the definition is a function.
103 @xref{Interactive Call}.
105 @item keystroke command
106 @cindex keystroke command
107 A @dfn{keystroke command} is a command that is bound to a key sequence
108 (typically one to three keystrokes). The distinction is made here
109 merely to avoid confusion with the meaning of ``command'' in non-Emacs
110 editors; for Lisp programs, the distinction is normally unimportant.
112 @item byte-code function
113 A @dfn{byte-code function} is a function that has been compiled by the
114 byte compiler. @xref{Byte-Code Type}.
116 @item autoload object
117 @cindex autoload object
118 An @dfn{autoload object} is a place-holder for a real function. If
119 the autoload object is called, it will make Emacs load the file
120 containing the definition of the real function, and then call the real
124 @defun functionp object
125 This function returns @code{t} if @var{object} is any kind of
126 function, i.e.@: can be passed to @code{funcall}. Note that
127 @code{functionp} returns @code{nil} for special forms (@pxref{Special
131 Unlike @code{functionp}, the next three functions do @emph{not}
132 treat a symbol as its function definition.
135 This function returns @code{t} if @var{object} is a built-in function
136 (i.e., a Lisp primitive).
140 (subrp 'message) ; @r{@code{message} is a symbol,}
141 @result{} nil ; @r{not a subr object.}
144 (subrp (symbol-function 'message))
150 @defun byte-code-function-p object
151 This function returns @code{t} if @var{object} is a byte-code
152 function. For example:
156 (byte-code-function-p (symbol-function 'next-line))
162 @defun subr-arity subr
163 This function provides information about the argument list of a
164 primitive, @var{subr}. The returned value is a pair
165 @code{(@var{min} . @var{max})}. @var{min} is the minimum number of
166 args. @var{max} is the maximum number or the symbol @code{many}, for a
167 function with @code{&rest} arguments, or the symbol @code{unevalled} if
168 @var{subr} is a special form.
171 @node Lambda Expressions
172 @section Lambda Expressions
173 @cindex lambda expression
175 A function written in Lisp is a list that looks like this:
178 (lambda (@var{arg-variables}@dots{})
179 @r{[}@var{documentation-string}@r{]}
180 @r{[}@var{interactive-declaration}@r{]}
181 @var{body-forms}@dots{})
185 Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it
186 actually is valid as an expression---it evaluates to itself. In some
187 other Lisp dialects, a lambda expression is not a valid expression at
188 all. In either case, its main use is not to be evaluated as an
189 expression, but to be called as a function.
192 * Lambda Components:: The parts of a lambda expression.
193 * Simple Lambda:: A simple example.
194 * Argument List:: Details and special features of argument lists.
195 * Function Documentation:: How to put documentation in a function.
198 @node Lambda Components
199 @subsection Components of a Lambda Expression
203 A function written in Lisp (a ``lambda expression'') is a list that
207 (lambda (@var{arg-variables}@dots{})
208 [@var{documentation-string}]
209 [@var{interactive-declaration}]
210 @var{body-forms}@dots{})
215 The first element of a lambda expression is always the symbol
216 @code{lambda}. This indicates that the list represents a function. The
217 reason functions are defined to start with @code{lambda} is so that
218 other lists, intended for other uses, will not accidentally be valid as
221 The second element is a list of symbols---the argument variable names.
222 This is called the @dfn{lambda list}. When a Lisp function is called,
223 the argument values are matched up against the variables in the lambda
224 list, which are given local bindings with the values provided.
225 @xref{Local Variables}.
227 The documentation string is a Lisp string object placed within the
228 function definition to describe the function for the Emacs help
229 facilities. @xref{Function Documentation}.
231 The interactive declaration is a list of the form @code{(interactive
232 @var{code-string})}. This declares how to provide arguments if the
233 function is used interactively. Functions with this declaration are called
234 @dfn{commands}; they can be called using @kbd{M-x} or bound to a key.
235 Functions not intended to be called in this way should not have interactive
236 declarations. @xref{Defining Commands}, for how to write an interactive
239 @cindex body of function
240 The rest of the elements are the @dfn{body} of the function: the Lisp
241 code to do the work of the function (or, as a Lisp programmer would say,
242 ``a list of Lisp forms to evaluate''). The value returned by the
243 function is the value returned by the last element of the body.
246 @subsection A Simple Lambda-Expression Example
248 Consider for example the following function:
251 (lambda (a b c) (+ a b c))
255 We can call this function by writing it as the @sc{car} of an
256 expression, like this:
260 ((lambda (a b c) (+ a b c))
266 This call evaluates the body of the lambda expression with the variable
267 @code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.
268 Evaluation of the body adds these three numbers, producing the result 6;
269 therefore, this call to the function returns the value 6.
271 Note that the arguments can be the results of other function calls, as in
276 ((lambda (a b c) (+ a b c))
282 This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
283 4)} from left to right. Then it applies the lambda expression to the
284 argument values 1, 6 and 1 to produce the value 8.
286 It is not often useful to write a lambda expression as the @sc{car} of
287 a form in this way. You can get the same result, of making local
288 variables and giving them values, using the special form @code{let}
289 (@pxref{Local Variables}). And @code{let} is clearer and easier to use.
290 In practice, lambda expressions are either stored as the function
291 definitions of symbols, to produce named functions, or passed as
292 arguments to other functions (@pxref{Anonymous Functions}).
294 However, calls to explicit lambda expressions were very useful in the
295 old days of Lisp, before the special form @code{let} was invented. At
296 that time, they were the only way to bind and initialize local
300 @subsection Other Features of Argument Lists
301 @kindex wrong-number-of-arguments
302 @cindex argument binding
303 @cindex binding arguments
304 @cindex argument lists, features
306 Our simple sample function, @code{(lambda (a b c) (+ a b c))},
307 specifies three argument variables, so it must be called with three
308 arguments: if you try to call it with only two arguments or four
309 arguments, you get a @code{wrong-number-of-arguments} error.
311 It is often convenient to write a function that allows certain
312 arguments to be omitted. For example, the function @code{substring}
313 accepts three arguments---a string, the start index and the end
314 index---but the third argument defaults to the @var{length} of the
315 string if you omit it. It is also convenient for certain functions to
316 accept an indefinite number of arguments, as the functions @code{list}
319 @cindex optional arguments
320 @cindex rest arguments
323 To specify optional arguments that may be omitted when a function
324 is called, simply include the keyword @code{&optional} before the optional
325 arguments. To specify a list of zero or more extra arguments, include the
326 keyword @code{&rest} before one final argument.
328 Thus, the complete syntax for an argument list is as follows:
332 (@var{required-vars}@dots{}
333 @r{[}&optional @var{optional-vars}@dots{}@r{]}
334 @r{[}&rest @var{rest-var}@r{]})
339 The square brackets indicate that the @code{&optional} and @code{&rest}
340 clauses, and the variables that follow them, are optional.
342 A call to the function requires one actual argument for each of the
343 @var{required-vars}. There may be actual arguments for zero or more of
344 the @var{optional-vars}, and there cannot be any actual arguments beyond
345 that unless the lambda list uses @code{&rest}. In that case, there may
346 be any number of extra actual arguments.
348 If actual arguments for the optional and rest variables are omitted,
349 then they always default to @code{nil}. There is no way for the
350 function to distinguish between an explicit argument of @code{nil} and
351 an omitted argument. However, the body of the function is free to
352 consider @code{nil} an abbreviation for some other meaningful value.
353 This is what @code{substring} does; @code{nil} as the third argument to
354 @code{substring} means to use the length of the string supplied.
356 @cindex CL note---default optional arg
358 @b{Common Lisp note:} Common Lisp allows the function to specify what
359 default value to use when an optional argument is omitted; Emacs Lisp
360 always uses @code{nil}. Emacs Lisp does not support ``supplied-p''
361 variables that tell you whether an argument was explicitly passed.
364 For example, an argument list that looks like this:
367 (a b &optional c d &rest e)
371 binds @code{a} and @code{b} to the first two actual arguments, which are
372 required. If one or two more arguments are provided, @code{c} and
373 @code{d} are bound to them respectively; any arguments after the first
374 four are collected into a list and @code{e} is bound to that list. If
375 there are only two arguments, @code{c} is @code{nil}; if two or three
376 arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}
379 There is no way to have required arguments following optional
380 ones---it would not make sense. To see why this must be so, suppose
381 that @code{c} in the example were optional and @code{d} were required.
382 Suppose three actual arguments are given; which variable would the
383 third argument be for? Would it be used for the @var{c}, or for
384 @var{d}? One can argue for both possibilities. Similarly, it makes
385 no sense to have any more arguments (either required or optional)
386 after a @code{&rest} argument.
388 Here are some examples of argument lists and proper calls:
391 ((lambda (n) (1+ n)) ; @r{One required:}
392 1) ; @r{requires exactly one argument.}
394 ((lambda (n &optional n1) ; @r{One required and one optional:}
395 (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
398 ((lambda (n &rest ns) ; @r{One required and one rest:}
399 (+ n (apply '+ ns))) ; @r{1 or more arguments.}
404 @node Function Documentation
405 @subsection Documentation Strings of Functions
406 @cindex documentation of function
408 A lambda expression may optionally have a @dfn{documentation string} just
409 after the lambda list. This string does not affect execution of the
410 function; it is a kind of comment, but a systematized comment which
411 actually appears inside the Lisp world and can be used by the Emacs help
412 facilities. @xref{Documentation}, for how the @var{documentation-string} is
415 It is a good idea to provide documentation strings for all the
416 functions in your program, even those that are called only from within
417 your program. Documentation strings are like comments, except that they
418 are easier to access.
420 The first line of the documentation string should stand on its own,
421 because @code{apropos} displays just this first line. It should consist
422 of one or two complete sentences that summarize the function's purpose.
424 The start of the documentation string is usually indented in the
425 source file, but since these spaces come before the starting
426 double-quote, they are not part of the string. Some people make a
427 practice of indenting any additional lines of the string so that the
428 text lines up in the program source. @emph{That is a mistake.} The
429 indentation of the following lines is inside the string; what looks
430 nice in the source code will look ugly when displayed by the help
433 You may wonder how the documentation string could be optional, since
434 there are required components of the function that follow it (the body).
435 Since evaluation of a string returns that string, without any side effects,
436 it has no effect if it is not the last form in the body. Thus, in
437 practice, there is no confusion between the first form of the body and the
438 documentation string; if the only body form is a string then it serves both
439 as the return value and as the documentation.
441 The last line of the documentation string can specify calling
442 conventions different from the actual function arguments. Write
450 following a blank line, at the beginning of the line, with no newline
451 following it inside the documentation string. (The @samp{\} is used
452 to avoid confusing the Emacs motion commands.) The calling convention
453 specified in this way appears in help messages in place of the one
454 derived from the actual arguments of the function.
456 This feature is particularly useful for macro definitions, since the
457 arguments written in a macro definition often do not correspond to the
458 way users think of the parts of the macro call.
461 @section Naming a Function
462 @cindex function definition
463 @cindex named function
464 @cindex function name
466 In most computer languages, every function has a name; the idea of a
467 function without a name is nonsensical. In Lisp, a function in the
468 strictest sense has no name. It is simply a list whose first element is
469 @code{lambda}, a byte-code function object, or a primitive subr-object.
471 However, a symbol can serve as the name of a function. This happens
472 when you put the function in the symbol's @dfn{function cell}
473 (@pxref{Symbol Components}). Then the symbol itself becomes a valid,
474 callable function, equivalent to the list or subr-object that its
475 function cell refers to. The contents of the function cell are also
476 called the symbol's @dfn{function definition}. The procedure of using a
477 symbol's function definition in place of the symbol is called
478 @dfn{symbol function indirection}; see @ref{Function Indirection}.
480 In practice, nearly all functions are given names in this way and
481 referred to through their names. For example, the symbol @code{car} works
482 as a function and does what it does because the primitive subr-object
483 @code{#<subr car>} is stored in its function cell.
485 We give functions names because it is convenient to refer to them by
486 their names in Lisp expressions. For primitive subr-objects such as
487 @code{#<subr car>}, names are the only way you can refer to them: there
488 is no read syntax for such objects. For functions written in Lisp, the
489 name is more convenient to use in a call than an explicit lambda
490 expression. Also, a function with a name can refer to itself---it can
491 be recursive. Writing the function's name in its own definition is much
492 more convenient than making the function definition point to itself
493 (something that is not impossible but that has various disadvantages in
496 We often identify functions with the symbols used to name them. For
497 example, we often speak of ``the function @code{car},'' not
498 distinguishing between the symbol @code{car} and the primitive
499 subr-object that is its function definition. For most purposes, the
500 distinction is not important.
502 Even so, keep in mind that a function need not have a unique name. While
503 a given function object @emph{usually} appears in the function cell of only
504 one symbol, this is just a matter of convenience. It is easy to store
505 it in several symbols using @code{fset}; then each of the symbols is
506 equally well a name for the same function.
508 A symbol used as a function name may also be used as a variable; these
509 two uses of a symbol are independent and do not conflict. (Some Lisp
510 dialects, such as Scheme, do not distinguish between a symbol's value
511 and its function definition; a symbol's value as a variable is also its
512 function definition.) If you have not given a symbol a function
513 definition, you cannot use it as a function; whether the symbol has a
514 value as a variable makes no difference to this.
516 @node Defining Functions
517 @section Defining Functions
518 @cindex defining a function
520 We usually give a name to a function when it is first created. This
521 is called @dfn{defining a function}, and it is done with the
522 @code{defun} special form.
524 @defspec defun name argument-list body-forms
525 @code{defun} is the usual way to define new Lisp functions. It
526 defines the symbol @var{name} as a function that looks like this:
529 (lambda @var{argument-list} . @var{body-forms})
532 @code{defun} stores this lambda expression in the function cell of
533 @var{name}. It returns the value @var{name}, but usually we ignore this
536 As described previously, @var{argument-list} is a list of argument
537 names and may include the keywords @code{&optional} and @code{&rest}
538 (@pxref{Lambda Expressions}). Also, the first two of the
539 @var{body-forms} may be a documentation string and an interactive
542 There is no conflict if the same symbol @var{name} is also used as a
543 variable, since the symbol's value cell is independent of the function
544 cell. @xref{Symbol Components}.
546 Here are some examples:
559 (defun bar (a &optional b &rest c)
565 @result{} (1 2 (3 4 5))
569 @result{} (1 nil nil)
573 @error{} Wrong number of arguments.
577 (defun capitalize-backwards ()
578 "Upcase the last letter of a word."
584 @result{} capitalize-backwards
588 Be careful not to redefine existing functions unintentionally.
589 @code{defun} redefines even primitive functions such as @code{car}
590 without any hesitation or notification. Redefining a function already
591 defined is often done deliberately, and there is no way to distinguish
592 deliberate redefinition from unintentional redefinition.
595 @cindex function aliases
596 @defun defalias name definition &optional docstring
597 @anchor{Definition of defalias}
598 This special form defines the symbol @var{name} as a function, with
599 definition @var{definition} (which can be any valid Lisp function).
600 It returns @var{definition}.
602 If @var{docstring} is non-@code{nil}, it becomes the function
603 documentation of @var{name}. Otherwise, any documentation provided by
604 @var{definition} is used.
606 The proper place to use @code{defalias} is where a specific function
607 name is being defined---especially where that name appears explicitly in
608 the source file being loaded. This is because @code{defalias} records
609 which file defined the function, just like @code{defun}
612 By contrast, in programs that manipulate function definitions for other
613 purposes, it is better to use @code{fset}, which does not keep such
614 records. @xref{Function Cells}.
617 You cannot create a new primitive function with @code{defun} or
618 @code{defalias}, but you can use them to change the function definition of
619 any symbol, even one such as @code{car} or @code{x-popup-menu} whose
620 normal definition is a primitive. However, this is risky: for
621 instance, it is next to impossible to redefine @code{car} without
622 breaking Lisp completely. Redefining an obscure function such as
623 @code{x-popup-menu} is less dangerous, but it still may not work as
624 you expect. If there are calls to the primitive from C code, they
625 call the primitive's C definition directly, so changing the symbol's
626 definition will have no effect on them.
628 See also @code{defsubst}, which defines a function like @code{defun}
629 and tells the Lisp compiler to open-code it. @xref{Inline Functions}.
631 @node Calling Functions
632 @section Calling Functions
633 @cindex function invocation
634 @cindex calling a function
636 Defining functions is only half the battle. Functions don't do
637 anything until you @dfn{call} them, i.e., tell them to run. Calling a
638 function is also known as @dfn{invocation}.
640 The most common way of invoking a function is by evaluating a list.
641 For example, evaluating the list @code{(concat "a" "b")} calls the
642 function @code{concat} with arguments @code{"a"} and @code{"b"}.
643 @xref{Evaluation}, for a description of evaluation.
645 When you write a list as an expression in your program, you specify
646 which function to call, and how many arguments to give it, in the text
647 of the program. Usually that's just what you want. Occasionally you
648 need to compute at run time which function to call. To do that, use
649 the function @code{funcall}. When you also need to determine at run
650 time how many arguments to pass, use @code{apply}.
652 @defun funcall function &rest arguments
653 @code{funcall} calls @var{function} with @var{arguments}, and returns
654 whatever @var{function} returns.
656 Since @code{funcall} is a function, all of its arguments, including
657 @var{function}, are evaluated before @code{funcall} is called. This
658 means that you can use any expression to obtain the function to be
659 called. It also means that @code{funcall} does not see the
660 expressions you write for the @var{arguments}, only their values.
661 These values are @emph{not} evaluated a second time in the act of
662 calling @var{function}; the operation of @code{funcall} is like the
663 normal procedure for calling a function, once its arguments have
664 already been evaluated.
666 The argument @var{function} must be either a Lisp function or a
667 primitive function. Special forms and macros are not allowed, because
668 they make sense only when given the ``unevaluated'' argument
669 expressions. @code{funcall} cannot provide these because, as we saw
670 above, it never knows them in the first place.
682 (funcall f 'x 'y '(z))
687 @error{} Invalid function: #<subr and>
691 Compare these examples with the examples of @code{apply}.
694 @defun apply function &rest arguments
695 @code{apply} calls @var{function} with @var{arguments}, just like
696 @code{funcall} but with one difference: the last of @var{arguments} is a
697 list of objects, which are passed to @var{function} as separate
698 arguments, rather than a single list. We say that @code{apply}
699 @dfn{spreads} this list so that each individual element becomes an
702 @code{apply} returns the result of calling @var{function}. As with
703 @code{funcall}, @var{function} must either be a Lisp function or a
704 primitive function; special forms and macros do not make sense in
714 @error{} Wrong type argument: listp, z
717 (apply '+ 1 2 '(3 4))
721 (apply '+ '(1 2 3 4))
726 (apply 'append '((a b c) nil (x y z) nil))
727 @result{} (a b c x y z)
731 For an interesting example of using @code{apply}, see @ref{Definition
735 @cindex partial application of functions
737 Sometimes it is useful to fix some of the function's arguments at
738 certain values, and leave the rest of arguments for when the function
739 is actually called. The act of fixing some of the function's
740 arguments is called @dfn{partial application} of the function@footnote{
741 This is related to, but different from @dfn{currying}, which
742 transforms a function that takes multiple arguments in such a way that
743 it can be called as a chain of functions, each one with a single
745 The result is a new function that accepts the rest of
746 arguments and calls the original function with all the arguments
749 Here's how to do partial application in Emacs Lisp:
751 @defun apply-partially func &rest args
752 This function returns a new function which, when called, will call
753 @var{func} with the list of arguments composed from @var{args} and
754 additional arguments specified at the time of the call. If @var{func}
755 accepts @var{n} arguments, then a call to @code{apply-partially} with
756 @w{@code{@var{m} < @var{n}}} arguments will produce a new function of
757 @w{@code{@var{n} - @var{m}}} arguments.
759 Here's how we could define the built-in function @code{1+}, if it
760 didn't exist, using @code{apply-partially} and @code{+}, another
765 (defalias '1+ (apply-partially '+ 1)
766 "Increment argument by one.")
776 It is common for Lisp functions to accept functions as arguments or
777 find them in data structures (especially in hook variables and property
778 lists) and call them using @code{funcall} or @code{apply}. Functions
779 that accept function arguments are often called @dfn{functionals}.
781 Sometimes, when you call a functional, it is useful to supply a no-op
782 function as the argument. Here are two different kinds of no-op
786 This function returns @var{arg} and has no side effects.
789 @defun ignore &rest args
790 This function ignores any arguments and returns @code{nil}.
793 Emacs Lisp functions can also be user-visible @dfn{commands}. A
794 command is a function that has an @dfn{interactive} specification.
795 You may want to call these functions as if they were called
796 interactively. See @ref{Interactive Call} for details on how to do
799 @node Mapping Functions
800 @section Mapping Functions
801 @cindex mapping functions
803 A @dfn{mapping function} applies a given function (@emph{not} a
804 special form or macro) to each element of a list or other collection.
805 Emacs Lisp has several such functions; @code{mapcar} and
806 @code{mapconcat}, which scan a list, are described here.
807 @xref{Definition of mapatoms}, for the function @code{mapatoms} which
808 maps over the symbols in an obarray. @xref{Definition of maphash},
809 for the function @code{maphash} which maps over key/value associations
812 These mapping functions do not allow char-tables because a char-table
813 is a sparse array whose nominal range of indices is very large. To map
814 over a char-table in a way that deals properly with its sparse nature,
815 use the function @code{map-char-table} (@pxref{Char-Tables}).
817 @defun mapcar function sequence
818 @anchor{Definition of mapcar}
819 @code{mapcar} applies @var{function} to each element of @var{sequence}
820 in turn, and returns a list of the results.
822 The argument @var{sequence} can be any kind of sequence except a
823 char-table; that is, a list, a vector, a bool-vector, or a string. The
824 result is always a list. The length of the result is the same as the
825 length of @var{sequence}. For example:
829 (mapcar 'car '((a b) (c d) (e f)))
833 (mapcar 'string "abc")
834 @result{} ("a" "b" "c")
838 ;; @r{Call each function in @code{my-hooks}.}
839 (mapcar 'funcall my-hooks)
843 (defun mapcar* (function &rest args)
844 "Apply FUNCTION to successive cars of all ARGS.
845 Return the list of results."
846 ;; @r{If no list is exhausted,}
847 (if (not (memq nil args))
848 ;; @r{apply function to @sc{car}s.}
849 (cons (apply function (mapcar 'car args))
850 (apply 'mapcar* function
851 ;; @r{Recurse for rest of elements.}
852 (mapcar 'cdr args)))))
856 (mapcar* 'cons '(a b c) '(1 2 3 4))
857 @result{} ((a . 1) (b . 2) (c . 3))
862 @defun mapc function sequence
863 @code{mapc} is like @code{mapcar} except that @var{function} is used for
864 side-effects only---the values it returns are ignored, not collected
865 into a list. @code{mapc} always returns @var{sequence}.
868 @defun mapconcat function sequence separator
869 @code{mapconcat} applies @var{function} to each element of
870 @var{sequence}: the results, which must be strings, are concatenated.
871 Between each pair of result strings, @code{mapconcat} inserts the string
872 @var{separator}. Usually @var{separator} contains a space or comma or
873 other suitable punctuation.
875 The argument @var{function} must be a function that can take one
876 argument and return a string. The argument @var{sequence} can be any
877 kind of sequence except a char-table; that is, a list, a vector, a
878 bool-vector, or a string.
882 (mapconcat 'symbol-name
883 '(The cat in the hat)
885 @result{} "The cat in the hat"
889 (mapconcat (function (lambda (x) (format "%c" (1+ x))))
897 @node Anonymous Functions
898 @section Anonymous Functions
899 @cindex anonymous function
901 In Lisp, a function is a list that starts with @code{lambda}, a
902 byte-code function compiled from such a list, or alternatively a
903 primitive subr-object; names are ``extra.'' Although functions are
904 usually defined with @code{defun} and given names at the same time, it
905 is occasionally more concise to use an explicit lambda expression---an
906 anonymous function. Such a list is valid wherever a function name is.
908 Any method of creating such a list makes a valid function. Even this:
912 (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
913 @result{} (lambda (x) (+ 12 x))
918 This computes a list that looks like @code{(lambda (x) (+ 12 x))} and
919 makes it the value (@emph{not} the function definition!) of
922 Here is how we might call this function:
932 It does @emph{not} work to write @code{(silly 1)}, because this
933 function is not the @emph{function definition} of @code{silly}. We
934 have not given @code{silly} any function definition, just a value as a
937 Most of the time, anonymous functions are constants that appear in
938 your program. For instance, you might want to pass one as an argument
939 to the function @code{mapcar}, which applies any given function to
940 each element of a list (@pxref{Mapping Functions}).
941 @xref{describe-symbols example}, for a realistic example of this.
943 In the following example, we define a @code{change-property}
944 function that takes a function as its third argument, followed by a
945 @code{double-property} function that makes use of
946 @code{change-property} by passing it an anonymous function:
950 (defun change-property (symbol prop function)
951 (let ((value (get symbol prop)))
952 (put symbol prop (funcall function value))))
956 (defun double-property (symbol prop)
957 (change-property symbol prop (lambda (x) (* 2 x))))
962 In the @code{double-property} function, we did not quote the
963 @code{lambda} form. This is permissible, because a @code{lambda} form
964 is @dfn{self-quoting}: evaluating the form yields the form itself.
966 Whether or not you quote a @code{lambda} form makes a difference if
967 you compile the code (@pxref{Byte Compilation}). If the @code{lambda}
968 form is unquoted, as in the above example, the anonymous function is
969 also compiled. Suppose, however, that we quoted the @code{lambda}
974 (defun double-property (symbol prop)
975 (change-property symbol prop '(lambda (x) (* 2 x))))
980 If you compile this, the argument passed to @code{change-property} is
981 the precise list shown:
988 The Lisp compiler cannot assume this list is a function, even though
989 it looks like one, since it does not know what @code{change-property}
990 will do with the list. Perhaps it will check whether the @sc{car} of
991 the third element is the symbol @code{*}!
994 The @code{function} special form explicitly tells the byte-compiler
995 that its argument is a function:
997 @defspec function function-object
998 @cindex function quoting
999 This special form returns @var{function-object} without evaluating it.
1000 In this, it is equivalent to @code{quote}. However, it serves as a
1001 note to the Emacs Lisp compiler that @var{function-object} is intended
1002 to be used only as a function, and therefore can safely be compiled.
1003 Contrast this with @code{quote}, in @ref{Quoting}.
1006 @cindex @samp{#'} syntax
1007 The read syntax @code{#'} is a short-hand for using @code{function}.
1008 Generally, it is not necessary to use either @code{#'} or
1009 @code{function}; just use an unquoted @code{lambda} form instead.
1010 (Actually, @code{lambda} is a macro defined using @code{function}.)
1011 The following forms are all equivalent:
1014 #'(lambda (x) (* x x))
1015 (function (lambda (x) (* x x)))
1016 (lambda (x) (* x x))
1019 We sometimes write @code{function} instead of @code{quote} when
1020 quoting the name of a function, but this usage is just a sort of
1024 (function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
1027 @node Function Cells
1028 @section Accessing Function Cell Contents
1030 The @dfn{function definition} of a symbol is the object stored in the
1031 function cell of the symbol. The functions described here access, test,
1032 and set the function cell of symbols.
1034 See also the function @code{indirect-function}. @xref{Definition of
1037 @defun symbol-function symbol
1038 @kindex void-function
1039 This returns the object in the function cell of @var{symbol}. If the
1040 symbol's function cell is void, a @code{void-function} error is
1043 This function does not check that the returned object is a legitimate
1048 (defun bar (n) (+ n 2))
1052 (symbol-function 'bar)
1053 @result{} (lambda (n) (+ n 2))
1060 (symbol-function 'baz)
1066 @cindex void function cell
1067 If you have never given a symbol any function definition, we say that
1068 that symbol's function cell is @dfn{void}. In other words, the function
1069 cell does not have any Lisp object in it. If you try to call such a symbol
1070 as a function, it signals a @code{void-function} error.
1072 Note that void is not the same as @code{nil} or the symbol
1073 @code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
1074 and can be stored into a function cell just as any other object can be
1075 (and they can be valid functions if you define them in turn with
1076 @code{defun}). A void function cell contains no object whatsoever.
1078 You can test the voidness of a symbol's function definition with
1079 @code{fboundp}. After you have given a symbol a function definition, you
1080 can make it void once more using @code{fmakunbound}.
1082 @defun fboundp symbol
1083 This function returns @code{t} if the symbol has an object in its
1084 function cell, @code{nil} otherwise. It does not check that the object
1085 is a legitimate function.
1088 @defun fmakunbound symbol
1089 This function makes @var{symbol}'s function cell void, so that a
1090 subsequent attempt to access this cell will cause a
1091 @code{void-function} error. It returns @var{symbol}. (See also
1092 @code{makunbound}, in @ref{Void Variables}.)
1109 @error{} Symbol's function definition is void: foo
1114 @defun fset symbol definition
1115 This function stores @var{definition} in the function cell of
1116 @var{symbol}. The result is @var{definition}. Normally
1117 @var{definition} should be a function or the name of a function, but
1118 this is not checked. The argument @var{symbol} is an ordinary evaluated
1121 There are three normal uses of this function:
1125 Copying one symbol's function definition to another---in other words,
1126 making an alternate name for a function. (If you think of this as the
1127 definition of the new name, you should use @code{defalias} instead of
1128 @code{fset}; see @ref{Definition of defalias}.)
1131 Giving a symbol a function definition that is not a list and therefore
1132 cannot be made with @code{defun}. For example, you can use @code{fset}
1133 to give a symbol @code{s1} a function definition which is another symbol
1134 @code{s2}; then @code{s1} serves as an alias for whatever definition
1135 @code{s2} presently has. (Once again use @code{defalias} instead of
1136 @code{fset} if you think of this as the definition of @code{s1}.)
1139 In constructs for defining or altering functions. If @code{defun}
1140 were not a primitive, it could be written in Lisp (as a macro) using
1144 Here are examples of these uses:
1148 ;; @r{Save @code{foo}'s definition in @code{old-foo}.}
1149 (fset 'old-foo (symbol-function 'foo))
1153 ;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
1154 ;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)}
1163 (symbol-function 'xfirst)
1167 (symbol-function (symbol-function 'xfirst))
1168 @result{} #<subr car>
1172 ;; @r{Define a named keyboard macro.}
1173 (fset 'kill-two-lines "\^u2\^k")
1178 ;; @r{Here is a function that alters other functions.}
1179 (defun copy-function-definition (new old)
1180 "Define NEW with the same function definition as OLD."
1181 (fset new (symbol-function old)))
1186 @code{fset} is sometimes used to save the old definition of a
1187 function before redefining it. That permits the new definition to
1188 invoke the old definition. But it is unmodular and unclean for a Lisp
1189 file to redefine a function defined elsewhere. If you want to modify
1190 a function defined by another package, it is cleaner to use
1191 @code{defadvice} (@pxref{Advising Functions}).
1193 @node Obsolete Functions
1194 @section Declaring Functions Obsolete
1196 You can use @code{make-obsolete} to declare a function obsolete. This
1197 indicates that the function may be removed at some stage in the future.
1199 @defun make-obsolete obsolete-name current-name &optional when
1200 This function makes the byte compiler warn that the function
1201 @var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the
1202 warning message says to use @var{current-name} instead of
1203 @var{obsolete-name}. @var{current-name} does not need to be an alias for
1204 @var{obsolete-name}; it can be a different function with similar
1205 functionality. If @var{current-name} is a string, it is the warning
1208 If provided, @var{when} should be a string indicating when the function
1209 was first made obsolete---for example, a date or a release number.
1212 You can define a function as an alias and declare it obsolete at the
1213 same time using the macro @code{define-obsolete-function-alias}:
1215 @defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
1216 This macro marks the function @var{obsolete-name} obsolete and also
1217 defines it as an alias for the function @var{current-name}. It is
1218 equivalent to the following:
1221 (defalias @var{obsolete-name} @var{current-name} @var{docstring})
1222 (make-obsolete @var{obsolete-name} @var{current-name} @var{when})
1226 In addition, you can mark a certain a particular calling convention
1227 for a function as obsolete:
1229 @defun set-advertised-calling-convention function signature
1230 This function specifies the argument list @var{signature} as the
1231 correct way to call @var{function}. This causes the Emacs byte
1232 compiler to issue a warning whenever it comes across an Emacs Lisp
1233 program that calls @var{function} any other way (however, it will
1234 still allow the code to be byte compiled).
1236 For instance, in old versions of Emacs the @code{sit-for} function
1237 accepted three arguments, like this
1240 (sit-for seconds milliseconds nodisp)
1243 However, calling @code{sit-for} this way is considered obsolete
1244 (@pxref{Waiting}). The old calling convention is deprecated like
1248 (set-advertised-calling-convention
1249 'sit-for '(seconds &optional nodisp))
1253 @node Inline Functions
1254 @section Inline Functions
1255 @cindex inline functions
1258 You can define an @dfn{inline function} by using @code{defsubst} instead
1259 of @code{defun}. An inline function works just like an ordinary
1260 function except for one thing: when you compile a call to the function,
1261 the function's definition is open-coded into the caller.
1263 Making a function inline makes explicit calls run faster. But it also
1264 has disadvantages. For one thing, it reduces flexibility; if you
1265 change the definition of the function, calls already inlined still use
1266 the old definition until you recompile them.
1268 Another disadvantage is that making a large function inline can increase
1269 the size of compiled code both in files and in memory. Since the speed
1270 advantage of inline functions is greatest for small functions, you
1271 generally should not make large functions inline.
1273 Also, inline functions do not behave well with respect to debugging,
1274 tracing, and advising (@pxref{Advising Functions}). Since ease of
1275 debugging and the flexibility of redefining functions are important
1276 features of Emacs, you should not make a function inline, even if it's
1277 small, unless its speed is really crucial, and you've timed the code
1278 to verify that using @code{defun} actually has performance problems.
1280 It's possible to define a macro to expand into the same code that an
1281 inline function would execute. (@xref{Macros}.) But the macro would be
1282 limited to direct use in expressions---a macro cannot be called with
1283 @code{apply}, @code{mapcar} and so on. Also, it takes some work to
1284 convert an ordinary function into a macro. To convert it into an inline
1285 function is very easy; simply replace @code{defun} with @code{defsubst}.
1286 Since each argument of an inline function is evaluated exactly once, you
1287 needn't worry about how many times the body uses the arguments, as you
1288 do for macros. (@xref{Argument Evaluation}.)
1290 Inline functions can be used and open-coded later on in the same file,
1291 following the definition, just like macros.
1293 @node Declaring Functions
1294 @section Telling the Compiler that a Function is Defined
1295 @cindex function declaration
1296 @cindex declaring functions
1297 @findex declare-function
1299 Byte-compiling a file often produces warnings about functions that the
1300 compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this
1301 indicates a real problem, but usually the functions in question are
1302 defined in other files which would be loaded if that code is run. For
1303 example, byte-compiling @file{fortran.el} used to warn:
1307 fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known
1311 In fact, @code{gud-find-c-expr} is only used in the function that
1312 Fortran mode uses for the local value of
1313 @code{gud-find-expr-function}, which is a callback from GUD; if it is
1314 called, the GUD functions will be loaded. When you know that such a
1315 warning does not indicate a real problem, it is good to suppress the
1316 warning. That makes new warnings which might mean real problems more
1317 visible. You do that with @code{declare-function}.
1319 All you need to do is add a @code{declare-function} statement before the
1320 first use of the function in question:
1323 (declare-function gud-find-c-expr "gud.el" nil)
1326 This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
1327 @samp{.el} can be omitted). The compiler takes for granted that that file
1328 really defines the function, and does not check.
1330 The optional third argument specifies the argument list of
1331 @code{gud-find-c-expr}. In this case, it takes no arguments
1332 (@code{nil} is different from not specifying a value). In other
1333 cases, this might be something like @code{(file &optional overwrite)}.
1334 You don't have to specify the argument list, but if you do the
1335 byte compiler can check that the calls match the declaration.
1337 @defmac declare-function function file &optional arglist fileonly
1338 Tell the byte compiler to assume that @var{function} is defined, with
1339 arguments @var{arglist}, and that the definition should come from the
1340 file @var{file}. @var{fileonly} non-@code{nil} means only check that
1341 @var{file} exists, not that it actually defines @var{function}.
1344 To verify that these functions really are declared where
1345 @code{declare-function} says they are, use @code{check-declare-file}
1346 to check all @code{declare-function} calls in one source file, or use
1347 @code{check-declare-directory} check all the files in and under a
1350 These commands find the file that ought to contain a function's
1351 definition using @code{locate-library}; if that finds no file, they
1352 expand the definition file name relative to the directory of the file
1353 that contains the @code{declare-function} call.
1355 You can also say that a function is defined by C code by specifying a
1356 file name ending in @samp{.c} or @samp{.m}. @code{check-declare-file}
1357 looks for these files in the C source code directory. This is useful
1358 only when you call a function that is defined only on certain systems.
1359 Most of the primitive functions of Emacs are always defined so they will
1360 never give you a warning.
1362 Sometimes a file will optionally use functions from an external package.
1363 If you prefix the filename in the @code{declare-function} statement with
1364 @samp{ext:}, then it will be checked if it is found, otherwise skipped
1367 There are some function definitions that @samp{check-declare} does not
1368 understand (e.g. @code{defstruct} and some other macros). In such cases,
1369 you can pass a non-@code{nil} @var{fileonly} argument to
1370 @code{declare-function}, meaning to only check that the file exists, not
1371 that it actually defines the function. Note that to do this without
1372 having to specify an argument list, you should set the @var{arglist}
1373 argument to @code{t} (because @code{nil} means an empty argument list, as
1374 opposed to an unspecified one).
1376 @node Function Safety
1377 @section Determining whether a Function is Safe to Call
1378 @cindex function safety
1379 @cindex safety of functions
1381 Some major modes such as SES call functions that are stored in user
1382 files. (@inforef{Top, ,ses}, for more information on SES.) User
1383 files sometimes have poor pedigrees---you can get a spreadsheet from
1384 someone you've just met, or you can get one through email from someone
1385 you've never met. So it is risky to call a function whose source code
1386 is stored in a user file until you have determined that it is safe.
1388 @defun unsafep form &optional unsafep-vars
1389 Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or
1390 returns a list that describes why it might be unsafe. The argument
1391 @var{unsafep-vars} is a list of symbols known to have temporary
1392 bindings at this point; it is mainly used for internal recursive
1393 calls. The current buffer is an implicit argument, which provides a
1394 list of buffer-local bindings.
1397 Being quick and simple, @code{unsafep} does a very light analysis and
1398 rejects many Lisp expressions that are actually safe. There are no
1399 known cases where @code{unsafep} returns @code{nil} for an unsafe
1400 expression. However, a ``safe'' Lisp expression can return a string
1401 with a @code{display} property, containing an associated Lisp
1402 expression to be executed after the string is inserted into a buffer.
1403 This associated expression can be a virus. In order to be safe, you
1404 must delete properties from all strings calculated by user code before
1405 inserting them into buffers.
1408 What is a safe Lisp expression? Basically, it's an expression that
1409 calls only built-in functions with no side effects (or only innocuous
1410 ones). Innocuous side effects include displaying messages and
1411 altering non-risky buffer-local variables (but not global variables).
1414 @item Safe expression
1417 An atom or quoted thing.
1419 A call to a safe function (see below), if all its arguments are
1422 One of the special forms @code{and}, @code{catch}, @code{cond},
1423 @code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn},
1424 @code{while}, and @code{unwind-protect}], if all its arguments are
1427 A form that creates temporary bindings (@code{condition-case},
1428 @code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or
1429 @code{let*}), if all args are safe and the symbols to be bound are not
1430 explicitly risky (see @pxref{File Local Variables}).
1432 An assignment using @code{add-to-list}, @code{setq}, @code{push}, or
1433 @code{pop}, if all args are safe and the symbols to be assigned are
1434 not explicitly risky and they already have temporary or buffer-local
1437 One of [apply, mapc, mapcar, mapconcat] if the first argument is a
1438 safe explicit lambda and the other args are safe expressions.
1444 A lambda containing safe expressions.
1446 A symbol on the list @code{safe-functions}, so the user says it's safe.
1448 A symbol with a non-@code{nil} @code{side-effect-free} property.
1450 A symbol with a non-@code{nil} @code{safe-function} property. The
1451 value @code{t} indicates a function that is safe but has innocuous
1452 side effects. Other values will someday indicate functions with
1453 classes of side effects that are not always safe.
1456 The @code{side-effect-free} and @code{safe-function} properties are
1457 provided for built-in functions and for low-level functions and macros
1458 defined in @file{subr.el}. You can assign these properties for the
1459 functions you write.
1463 @node Related Topics
1464 @section Other Topics Related to Functions
1466 Here is a table of several functions that do things related to
1467 function calling and function definitions. They are documented
1468 elsewhere, but we provide cross references here.
1472 See @ref{Calling Functions}.
1477 @item call-interactively
1478 See @ref{Interactive Call}.
1480 @item called-interactively-p
1481 See @ref{Distinguish Interactive}.
1484 See @ref{Interactive Call}.
1487 See @ref{Accessing Documentation}.
1493 See @ref{Calling Functions}.
1496 See @ref{Anonymous Functions}.
1499 See @ref{Calling Functions}.
1501 @item indirect-function
1502 See @ref{Function Indirection}.
1505 See @ref{Using Interactive}.
1508 See @ref{Distinguish Interactive}.
1511 See @ref{Creating Symbols}.
1514 See @ref{Mapping Functions}.
1516 @item map-char-table
1517 See @ref{Char-Tables}.
1520 See @ref{Mapping Functions}.
1523 See @ref{Functions for Key Lookup}.