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 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}.
117 @defun functionp object
118 This function returns @code{t} if @var{object} is any kind of
119 function, or a special form, or, recursively, a symbol whose function
120 definition is a function or special form. (This does not include
124 Unlike @code{functionp}, the next three functions do @emph{not}
125 treat a symbol as its function definition.
128 This function returns @code{t} if @var{object} is a built-in function
129 (i.e., a Lisp primitive).
133 (subrp 'message) ; @r{@code{message} is a symbol,}
134 @result{} nil ; @r{not a subr object.}
137 (subrp (symbol-function 'message))
143 @defun byte-code-function-p object
144 This function returns @code{t} if @var{object} is a byte-code
145 function. For example:
149 (byte-code-function-p (symbol-function 'next-line))
155 @defun subr-arity subr
156 This function provides information about the argument list of a
157 primitive, @var{subr}. The returned value is a pair
158 @code{(@var{min} . @var{max})}. @var{min} is the minimum number of
159 args. @var{max} is the maximum number or the symbol @code{many}, for a
160 function with @code{&rest} arguments, or the symbol @code{unevalled} if
161 @var{subr} is a special form.
164 @node Lambda Expressions
165 @section Lambda Expressions
166 @cindex lambda expression
168 A function written in Lisp is a list that looks like this:
171 (lambda (@var{arg-variables}@dots{})
172 @r{[}@var{documentation-string}@r{]}
173 @r{[}@var{interactive-declaration}@r{]}
174 @var{body-forms}@dots{})
178 Such a list is called a @dfn{lambda expression}. In Emacs Lisp, it
179 actually is valid as an expression---it evaluates to itself. In some
180 other Lisp dialects, a lambda expression is not a valid expression at
181 all. In either case, its main use is not to be evaluated as an
182 expression, but to be called as a function.
185 * Lambda Components:: The parts of a lambda expression.
186 * Simple Lambda:: A simple example.
187 * Argument List:: Details and special features of argument lists.
188 * Function Documentation:: How to put documentation in a function.
191 @node Lambda Components
192 @subsection Components of a Lambda Expression
196 A function written in Lisp (a ``lambda expression'') is a list that
200 (lambda (@var{arg-variables}@dots{})
201 [@var{documentation-string}]
202 [@var{interactive-declaration}]
203 @var{body-forms}@dots{})
208 The first element of a lambda expression is always the symbol
209 @code{lambda}. This indicates that the list represents a function. The
210 reason functions are defined to start with @code{lambda} is so that
211 other lists, intended for other uses, will not accidentally be valid as
214 The second element is a list of symbols---the argument variable names.
215 This is called the @dfn{lambda list}. When a Lisp function is called,
216 the argument values are matched up against the variables in the lambda
217 list, which are given local bindings with the values provided.
218 @xref{Local Variables}.
220 The documentation string is a Lisp string object placed within the
221 function definition to describe the function for the Emacs help
222 facilities. @xref{Function Documentation}.
224 The interactive declaration is a list of the form @code{(interactive
225 @var{code-string})}. This declares how to provide arguments if the
226 function is used interactively. Functions with this declaration are called
227 @dfn{commands}; they can be called using @kbd{M-x} or bound to a key.
228 Functions not intended to be called in this way should not have interactive
229 declarations. @xref{Defining Commands}, for how to write an interactive
232 @cindex body of function
233 The rest of the elements are the @dfn{body} of the function: the Lisp
234 code to do the work of the function (or, as a Lisp programmer would say,
235 ``a list of Lisp forms to evaluate''). The value returned by the
236 function is the value returned by the last element of the body.
239 @subsection A Simple Lambda-Expression Example
241 Consider for example the following function:
244 (lambda (a b c) (+ a b c))
248 We can call this function by writing it as the @sc{car} of an
249 expression, like this:
253 ((lambda (a b c) (+ a b c))
259 This call evaluates the body of the lambda expression with the variable
260 @code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.
261 Evaluation of the body adds these three numbers, producing the result 6;
262 therefore, this call to the function returns the value 6.
264 Note that the arguments can be the results of other function calls, as in
269 ((lambda (a b c) (+ a b c))
275 This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
276 4)} from left to right. Then it applies the lambda expression to the
277 argument values 1, 6 and 1 to produce the value 8.
279 It is not often useful to write a lambda expression as the @sc{car} of
280 a form in this way. You can get the same result, of making local
281 variables and giving them values, using the special form @code{let}
282 (@pxref{Local Variables}). And @code{let} is clearer and easier to use.
283 In practice, lambda expressions are either stored as the function
284 definitions of symbols, to produce named functions, or passed as
285 arguments to other functions (@pxref{Anonymous Functions}).
287 However, calls to explicit lambda expressions were very useful in the
288 old days of Lisp, before the special form @code{let} was invented. At
289 that time, they were the only way to bind and initialize local
293 @subsection Other Features of Argument Lists
294 @kindex wrong-number-of-arguments
295 @cindex argument binding
296 @cindex binding arguments
297 @cindex argument lists, features
299 Our simple sample function, @code{(lambda (a b c) (+ a b c))},
300 specifies three argument variables, so it must be called with three
301 arguments: if you try to call it with only two arguments or four
302 arguments, you get a @code{wrong-number-of-arguments} error.
304 It is often convenient to write a function that allows certain
305 arguments to be omitted. For example, the function @code{substring}
306 accepts three arguments---a string, the start index and the end
307 index---but the third argument defaults to the @var{length} of the
308 string if you omit it. It is also convenient for certain functions to
309 accept an indefinite number of arguments, as the functions @code{list}
312 @cindex optional arguments
313 @cindex rest arguments
316 To specify optional arguments that may be omitted when a function
317 is called, simply include the keyword @code{&optional} before the optional
318 arguments. To specify a list of zero or more extra arguments, include the
319 keyword @code{&rest} before one final argument.
321 Thus, the complete syntax for an argument list is as follows:
325 (@var{required-vars}@dots{}
326 @r{[}&optional @var{optional-vars}@dots{}@r{]}
327 @r{[}&rest @var{rest-var}@r{]})
332 The square brackets indicate that the @code{&optional} and @code{&rest}
333 clauses, and the variables that follow them, are optional.
335 A call to the function requires one actual argument for each of the
336 @var{required-vars}. There may be actual arguments for zero or more of
337 the @var{optional-vars}, and there cannot be any actual arguments beyond
338 that unless the lambda list uses @code{&rest}. In that case, there may
339 be any number of extra actual arguments.
341 If actual arguments for the optional and rest variables are omitted,
342 then they always default to @code{nil}. There is no way for the
343 function to distinguish between an explicit argument of @code{nil} and
344 an omitted argument. However, the body of the function is free to
345 consider @code{nil} an abbreviation for some other meaningful value.
346 This is what @code{substring} does; @code{nil} as the third argument to
347 @code{substring} means to use the length of the string supplied.
349 @cindex CL note---default optional arg
351 @b{Common Lisp note:} Common Lisp allows the function to specify what
352 default value to use when an optional argument is omitted; Emacs Lisp
353 always uses @code{nil}. Emacs Lisp does not support ``supplied-p''
354 variables that tell you whether an argument was explicitly passed.
357 For example, an argument list that looks like this:
360 (a b &optional c d &rest e)
364 binds @code{a} and @code{b} to the first two actual arguments, which are
365 required. If one or two more arguments are provided, @code{c} and
366 @code{d} are bound to them respectively; any arguments after the first
367 four are collected into a list and @code{e} is bound to that list. If
368 there are only two arguments, @code{c} is @code{nil}; if two or three
369 arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}
372 There is no way to have required arguments following optional
373 ones---it would not make sense. To see why this must be so, suppose
374 that @code{c} in the example were optional and @code{d} were required.
375 Suppose three actual arguments are given; which variable would the
376 third argument be for? Would it be used for the @var{c}, or for
377 @var{d}? One can argue for both possibilities. Similarly, it makes
378 no sense to have any more arguments (either required or optional)
379 after a @code{&rest} argument.
381 Here are some examples of argument lists and proper calls:
384 ((lambda (n) (1+ n)) ; @r{One required:}
385 1) ; @r{requires exactly one argument.}
387 ((lambda (n &optional n1) ; @r{One required and one optional:}
388 (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
391 ((lambda (n &rest ns) ; @r{One required and one rest:}
392 (+ n (apply '+ ns))) ; @r{1 or more arguments.}
397 @node Function Documentation
398 @subsection Documentation Strings of Functions
399 @cindex documentation of function
401 A lambda expression may optionally have a @dfn{documentation string} just
402 after the lambda list. This string does not affect execution of the
403 function; it is a kind of comment, but a systematized comment which
404 actually appears inside the Lisp world and can be used by the Emacs help
405 facilities. @xref{Documentation}, for how the @var{documentation-string} is
408 It is a good idea to provide documentation strings for all the
409 functions in your program, even those that are called only from within
410 your program. Documentation strings are like comments, except that they
411 are easier to access.
413 The first line of the documentation string should stand on its own,
414 because @code{apropos} displays just this first line. It should consist
415 of one or two complete sentences that summarize the function's purpose.
417 The start of the documentation string is usually indented in the
418 source file, but since these spaces come before the starting
419 double-quote, they are not part of the string. Some people make a
420 practice of indenting any additional lines of the string so that the
421 text lines up in the program source. @emph{That is a mistake.} The
422 indentation of the following lines is inside the string; what looks
423 nice in the source code will look ugly when displayed by the help
426 You may wonder how the documentation string could be optional, since
427 there are required components of the function that follow it (the body).
428 Since evaluation of a string returns that string, without any side effects,
429 it has no effect if it is not the last form in the body. Thus, in
430 practice, there is no confusion between the first form of the body and the
431 documentation string; if the only body form is a string then it serves both
432 as the return value and as the documentation.
434 The last line of the documentation string can specify calling
435 conventions different from the actual function arguments. Write
443 following a blank line, at the beginning of the line, with no newline
444 following it inside the documentation string. (The @samp{\} is used
445 to avoid confusing the Emacs motion commands.) The calling convention
446 specified in this way appears in help messages in place of the one
447 derived from the actual arguments of the function.
449 This feature is particularly useful for macro definitions, since the
450 arguments written in a macro definition often do not correspond to the
451 way users think of the parts of the macro call.
454 @section Naming a Function
455 @cindex function definition
456 @cindex named function
457 @cindex function name
459 In most computer languages, every function has a name; the idea of a
460 function without a name is nonsensical. In Lisp, a function in the
461 strictest sense has no name. It is simply a list whose first element is
462 @code{lambda}, a byte-code function object, or a primitive subr-object.
464 However, a symbol can serve as the name of a function. This happens
465 when you put the function in the symbol's @dfn{function cell}
466 (@pxref{Symbol Components}). Then the symbol itself becomes a valid,
467 callable function, equivalent to the list or subr-object that its
468 function cell refers to. The contents of the function cell are also
469 called the symbol's @dfn{function definition}. The procedure of using a
470 symbol's function definition in place of the symbol is called
471 @dfn{symbol function indirection}; see @ref{Function Indirection}.
473 In practice, nearly all functions are given names in this way and
474 referred to through their names. For example, the symbol @code{car} works
475 as a function and does what it does because the primitive subr-object
476 @code{#<subr car>} is stored in its function cell.
478 We give functions names because it is convenient to refer to them by
479 their names in Lisp expressions. For primitive subr-objects such as
480 @code{#<subr car>}, names are the only way you can refer to them: there
481 is no read syntax for such objects. For functions written in Lisp, the
482 name is more convenient to use in a call than an explicit lambda
483 expression. Also, a function with a name can refer to itself---it can
484 be recursive. Writing the function's name in its own definition is much
485 more convenient than making the function definition point to itself
486 (something that is not impossible but that has various disadvantages in
489 We often identify functions with the symbols used to name them. For
490 example, we often speak of ``the function @code{car},'' not
491 distinguishing between the symbol @code{car} and the primitive
492 subr-object that is its function definition. For most purposes, the
493 distinction is not important.
495 Even so, keep in mind that a function need not have a unique name. While
496 a given function object @emph{usually} appears in the function cell of only
497 one symbol, this is just a matter of convenience. It is easy to store
498 it in several symbols using @code{fset}; then each of the symbols is
499 equally well a name for the same function.
501 A symbol used as a function name may also be used as a variable; these
502 two uses of a symbol are independent and do not conflict. (Some Lisp
503 dialects, such as Scheme, do not distinguish between a symbol's value
504 and its function definition; a symbol's value as a variable is also its
505 function definition.) If you have not given a symbol a function
506 definition, you cannot use it as a function; whether the symbol has a
507 value as a variable makes no difference to this.
509 @node Defining Functions
510 @section Defining Functions
511 @cindex defining a function
513 We usually give a name to a function when it is first created. This
514 is called @dfn{defining a function}, and it is done with the
515 @code{defun} special form.
517 @defspec defun name argument-list body-forms
518 @code{defun} is the usual way to define new Lisp functions. It
519 defines the symbol @var{name} as a function that looks like this:
522 (lambda @var{argument-list} . @var{body-forms})
525 @code{defun} stores this lambda expression in the function cell of
526 @var{name}. It returns the value @var{name}, but usually we ignore this
529 As described previously, @var{argument-list} is a list of argument
530 names and may include the keywords @code{&optional} and @code{&rest}
531 (@pxref{Lambda Expressions}). Also, the first two of the
532 @var{body-forms} may be a documentation string and an interactive
535 There is no conflict if the same symbol @var{name} is also used as a
536 variable, since the symbol's value cell is independent of the function
537 cell. @xref{Symbol Components}.
539 Here are some examples:
552 (defun bar (a &optional b &rest c)
558 @result{} (1 2 (3 4 5))
562 @result{} (1 nil nil)
566 @error{} Wrong number of arguments.
570 (defun capitalize-backwards ()
571 "Upcase the last letter of a word."
577 @result{} capitalize-backwards
581 Be careful not to redefine existing functions unintentionally.
582 @code{defun} redefines even primitive functions such as @code{car}
583 without any hesitation or notification. Redefining a function already
584 defined is often done deliberately, and there is no way to distinguish
585 deliberate redefinition from unintentional redefinition.
588 @cindex function aliases
589 @defun defalias name definition &optional docstring
590 @anchor{Definition of defalias}
591 This special form defines the symbol @var{name} as a function, with
592 definition @var{definition} (which can be any valid Lisp function).
593 It returns @var{definition}.
595 If @var{docstring} is non-@code{nil}, it becomes the function
596 documentation of @var{name}. Otherwise, any documentation provided by
597 @var{definition} is used.
599 The proper place to use @code{defalias} is where a specific function
600 name is being defined---especially where that name appears explicitly in
601 the source file being loaded. This is because @code{defalias} records
602 which file defined the function, just like @code{defun}
605 By contrast, in programs that manipulate function definitions for other
606 purposes, it is better to use @code{fset}, which does not keep such
607 records. @xref{Function Cells}.
610 You cannot create a new primitive function with @code{defun} or
611 @code{defalias}, but you can use them to change the function definition of
612 any symbol, even one such as @code{car} or @code{x-popup-menu} whose
613 normal definition is a primitive. However, this is risky: for
614 instance, it is next to impossible to redefine @code{car} without
615 breaking Lisp completely. Redefining an obscure function such as
616 @code{x-popup-menu} is less dangerous, but it still may not work as
617 you expect. If there are calls to the primitive from C code, they
618 call the primitive's C definition directly, so changing the symbol's
619 definition will have no effect on them.
621 See also @code{defsubst}, which defines a function like @code{defun}
622 and tells the Lisp compiler to open-code it. @xref{Inline Functions}.
624 @node Calling Functions
625 @section Calling Functions
626 @cindex function invocation
627 @cindex calling a function
629 Defining functions is only half the battle. Functions don't do
630 anything until you @dfn{call} them, i.e., tell them to run. Calling a
631 function is also known as @dfn{invocation}.
633 The most common way of invoking a function is by evaluating a list.
634 For example, evaluating the list @code{(concat "a" "b")} calls the
635 function @code{concat} with arguments @code{"a"} and @code{"b"}.
636 @xref{Evaluation}, for a description of evaluation.
638 When you write a list as an expression in your program, you specify
639 which function to call, and how many arguments to give it, in the text
640 of the program. Usually that's just what you want. Occasionally you
641 need to compute at run time which function to call. To do that, use
642 the function @code{funcall}. When you also need to determine at run
643 time how many arguments to pass, use @code{apply}.
645 @defun funcall function &rest arguments
646 @code{funcall} calls @var{function} with @var{arguments}, and returns
647 whatever @var{function} returns.
649 Since @code{funcall} is a function, all of its arguments, including
650 @var{function}, are evaluated before @code{funcall} is called. This
651 means that you can use any expression to obtain the function to be
652 called. It also means that @code{funcall} does not see the
653 expressions you write for the @var{arguments}, only their values.
654 These values are @emph{not} evaluated a second time in the act of
655 calling @var{function}; the operation of @code{funcall} is like the
656 normal procedure for calling a function, once its arguments have
657 already been evaluated.
659 The argument @var{function} must be either a Lisp function or a
660 primitive function. Special forms and macros are not allowed, because
661 they make sense only when given the ``unevaluated'' argument
662 expressions. @code{funcall} cannot provide these because, as we saw
663 above, it never knows them in the first place.
675 (funcall f 'x 'y '(z))
680 @error{} Invalid function: #<subr and>
684 Compare these examples with the examples of @code{apply}.
687 @defun apply function &rest arguments
688 @code{apply} calls @var{function} with @var{arguments}, just like
689 @code{funcall} but with one difference: the last of @var{arguments} is a
690 list of objects, which are passed to @var{function} as separate
691 arguments, rather than a single list. We say that @code{apply}
692 @dfn{spreads} this list so that each individual element becomes an
695 @code{apply} returns the result of calling @var{function}. As with
696 @code{funcall}, @var{function} must either be a Lisp function or a
697 primitive function; special forms and macros do not make sense in
707 @error{} Wrong type argument: listp, z
710 (apply '+ 1 2 '(3 4))
714 (apply '+ '(1 2 3 4))
719 (apply 'append '((a b c) nil (x y z) nil))
720 @result{} (a b c x y z)
724 For an interesting example of using @code{apply}, see @ref{Definition
729 It is common for Lisp functions to accept functions as arguments or
730 find them in data structures (especially in hook variables and property
731 lists) and call them using @code{funcall} or @code{apply}. Functions
732 that accept function arguments are often called @dfn{functionals}.
734 Sometimes, when you call a functional, it is useful to supply a no-op
735 function as the argument. Here are two different kinds of no-op
739 This function returns @var{arg} and has no side effects.
742 @defun ignore &rest args
743 This function ignores any arguments and returns @code{nil}.
746 @node Mapping Functions
747 @section Mapping Functions
748 @cindex mapping functions
750 A @dfn{mapping function} applies a given function (@emph{not} a
751 special form or macro) to each element of a list or other collection.
752 Emacs Lisp has several such functions; @code{mapcar} and
753 @code{mapconcat}, which scan a list, are described here.
754 @xref{Definition of mapatoms}, for the function @code{mapatoms} which
755 maps over the symbols in an obarray. @xref{Definition of maphash},
756 for the function @code{maphash} which maps over key/value associations
759 These mapping functions do not allow char-tables because a char-table
760 is a sparse array whose nominal range of indices is very large. To map
761 over a char-table in a way that deals properly with its sparse nature,
762 use the function @code{map-char-table} (@pxref{Char-Tables}).
764 @defun mapcar function sequence
765 @anchor{Definition of mapcar}
766 @code{mapcar} applies @var{function} to each element of @var{sequence}
767 in turn, and returns a list of the results.
769 The argument @var{sequence} can be any kind of sequence except a
770 char-table; that is, a list, a vector, a bool-vector, or a string. The
771 result is always a list. The length of the result is the same as the
772 length of @var{sequence}. For example:
776 (mapcar 'car '((a b) (c d) (e f)))
780 (mapcar 'char-to-string "abc")
781 @result{} ("a" "b" "c")
785 ;; @r{Call each function in @code{my-hooks}.}
786 (mapcar 'funcall my-hooks)
790 (defun mapcar* (function &rest args)
791 "Apply FUNCTION to successive cars of all ARGS.
792 Return the list of results."
793 ;; @r{If no list is exhausted,}
794 (if (not (memq nil args))
795 ;; @r{apply function to @sc{car}s.}
796 (cons (apply function (mapcar 'car args))
797 (apply 'mapcar* function
798 ;; @r{Recurse for rest of elements.}
799 (mapcar 'cdr args)))))
803 (mapcar* 'cons '(a b c) '(1 2 3 4))
804 @result{} ((a . 1) (b . 2) (c . 3))
809 @defun mapc function sequence
810 @code{mapc} is like @code{mapcar} except that @var{function} is used for
811 side-effects only---the values it returns are ignored, not collected
812 into a list. @code{mapc} always returns @var{sequence}.
815 @defun mapconcat function sequence separator
816 @code{mapconcat} applies @var{function} to each element of
817 @var{sequence}: the results, which must be strings, are concatenated.
818 Between each pair of result strings, @code{mapconcat} inserts the string
819 @var{separator}. Usually @var{separator} contains a space or comma or
820 other suitable punctuation.
822 The argument @var{function} must be a function that can take one
823 argument and return a string. The argument @var{sequence} can be any
824 kind of sequence except a char-table; that is, a list, a vector, a
825 bool-vector, or a string.
829 (mapconcat 'symbol-name
830 '(The cat in the hat)
832 @result{} "The cat in the hat"
836 (mapconcat (function (lambda (x) (format "%c" (1+ x))))
844 @node Anonymous Functions
845 @section Anonymous Functions
846 @cindex anonymous function
848 In Lisp, a function is a list that starts with @code{lambda}, a
849 byte-code function compiled from such a list, or alternatively a
850 primitive subr-object; names are ``extra.'' Although usually functions
851 are defined with @code{defun} and given names at the same time, it is
852 occasionally more concise to use an explicit lambda expression---an
853 anonymous function. Such a list is valid wherever a function name is.
855 Any method of creating such a list makes a valid function. Even this:
859 (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
860 @result{} (lambda (x) (+ 12 x))
865 This computes a list that looks like @code{(lambda (x) (+ 12 x))} and
866 makes it the value (@emph{not} the function definition!) of
869 Here is how we might call this function:
879 (It does @emph{not} work to write @code{(silly 1)}, because this function
880 is not the @emph{function definition} of @code{silly}. We have not given
881 @code{silly} any function definition, just a value as a variable.)
883 Most of the time, anonymous functions are constants that appear in
884 your program. For example, you might want to pass one as an argument to
885 the function @code{mapcar}, which applies any given function to each
888 Here we define a function @code{change-property} which
889 uses a function as its third argument:
893 (defun change-property (symbol prop function)
894 (let ((value (get symbol prop)))
895 (put symbol prop (funcall function value))))
900 Here we define a function that uses @code{change-property},
901 passing it a function to double a number:
905 (defun double-property (symbol prop)
906 (change-property symbol prop '(lambda (x) (* 2 x))))
911 In such cases, we usually use the special form @code{function} instead
912 of simple quotation to quote the anonymous function, like this:
916 (defun double-property (symbol prop)
917 (change-property symbol prop
918 (function (lambda (x) (* 2 x)))))
922 Using @code{function} instead of @code{quote} makes a difference if you
923 compile the function @code{double-property}. For example, if you
924 compile the second definition of @code{double-property}, the anonymous
925 function is compiled as well. By contrast, if you compile the first
926 definition which uses ordinary @code{quote}, the argument passed to
927 @code{change-property} is the precise list shown:
934 The Lisp compiler cannot assume this list is a function, even though it
935 looks like one, since it does not know what @code{change-property} will
936 do with the list. Perhaps it will check whether the @sc{car} of the third
937 element is the symbol @code{*}! Using @code{function} tells the
938 compiler it is safe to go ahead and compile the constant function.
940 Nowadays it is possible to omit @code{function} entirely, like this:
944 (defun double-property (symbol prop)
945 (change-property symbol prop (lambda (x) (* 2 x))))
950 This is because @code{lambda} itself implies @code{function}.
952 We sometimes write @code{function} instead of @code{quote} when
953 quoting the name of a function, but this usage is just a sort of
957 (function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
960 @cindex @samp{#'} syntax
961 The read syntax @code{#'} is a short-hand for using @code{function}.
965 #'(lambda (x) (* x x))
972 (function (lambda (x) (* x x)))
975 @defspec function function-object
976 @cindex function quoting
977 This special form returns @var{function-object} without evaluating it.
978 In this, it is equivalent to @code{quote}. However, it serves as a
979 note to the Emacs Lisp compiler that @var{function-object} is intended
980 to be used only as a function, and therefore can safely be compiled.
981 Contrast this with @code{quote}, in @ref{Quoting}.
984 @xref{describe-symbols example}, for a realistic example using
985 @code{function} and an anonymous function.
988 @section Accessing Function Cell Contents
990 The @dfn{function definition} of a symbol is the object stored in the
991 function cell of the symbol. The functions described here access, test,
992 and set the function cell of symbols.
994 See also the function @code{indirect-function}. @xref{Definition of
997 @defun symbol-function symbol
998 @kindex void-function
999 This returns the object in the function cell of @var{symbol}. If the
1000 symbol's function cell is void, a @code{void-function} error is
1003 This function does not check that the returned object is a legitimate
1008 (defun bar (n) (+ n 2))
1012 (symbol-function 'bar)
1013 @result{} (lambda (n) (+ n 2))
1020 (symbol-function 'baz)
1026 @cindex void function cell
1027 If you have never given a symbol any function definition, we say that
1028 that symbol's function cell is @dfn{void}. In other words, the function
1029 cell does not have any Lisp object in it. If you try to call such a symbol
1030 as a function, it signals a @code{void-function} error.
1032 Note that void is not the same as @code{nil} or the symbol
1033 @code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
1034 and can be stored into a function cell just as any other object can be
1035 (and they can be valid functions if you define them in turn with
1036 @code{defun}). A void function cell contains no object whatsoever.
1038 You can test the voidness of a symbol's function definition with
1039 @code{fboundp}. After you have given a symbol a function definition, you
1040 can make it void once more using @code{fmakunbound}.
1042 @defun fboundp symbol
1043 This function returns @code{t} if the symbol has an object in its
1044 function cell, @code{nil} otherwise. It does not check that the object
1045 is a legitimate function.
1048 @defun fmakunbound symbol
1049 This function makes @var{symbol}'s function cell void, so that a
1050 subsequent attempt to access this cell will cause a
1051 @code{void-function} error. It returns @var{symbol}. (See also
1052 @code{makunbound}, in @ref{Void Variables}.)
1069 @error{} Symbol's function definition is void: foo
1074 @defun fset symbol definition
1075 This function stores @var{definition} in the function cell of
1076 @var{symbol}. The result is @var{definition}. Normally
1077 @var{definition} should be a function or the name of a function, but
1078 this is not checked. The argument @var{symbol} is an ordinary evaluated
1081 There are three normal uses of this function:
1085 Copying one symbol's function definition to another---in other words,
1086 making an alternate name for a function. (If you think of this as the
1087 definition of the new name, you should use @code{defalias} instead of
1088 @code{fset}; see @ref{Definition of defalias}.)
1091 Giving a symbol a function definition that is not a list and therefore
1092 cannot be made with @code{defun}. For example, you can use @code{fset}
1093 to give a symbol @code{s1} a function definition which is another symbol
1094 @code{s2}; then @code{s1} serves as an alias for whatever definition
1095 @code{s2} presently has. (Once again use @code{defalias} instead of
1096 @code{fset} if you think of this as the definition of @code{s1}.)
1099 In constructs for defining or altering functions. If @code{defun}
1100 were not a primitive, it could be written in Lisp (as a macro) using
1104 Here are examples of these uses:
1108 ;; @r{Save @code{foo}'s definition in @code{old-foo}.}
1109 (fset 'old-foo (symbol-function 'foo))
1113 ;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
1114 ;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)}
1123 (symbol-function 'xfirst)
1127 (symbol-function (symbol-function 'xfirst))
1128 @result{} #<subr car>
1132 ;; @r{Define a named keyboard macro.}
1133 (fset 'kill-two-lines "\^u2\^k")
1138 ;; @r{Here is a function that alters other functions.}
1139 (defun copy-function-definition (new old)
1140 "Define NEW with the same function definition as OLD."
1141 (fset new (symbol-function old)))
1146 @code{fset} is sometimes used to save the old definition of a
1147 function before redefining it. That permits the new definition to
1148 invoke the old definition. But it is unmodular and unclean for a Lisp
1149 file to redefine a function defined elsewhere. If you want to modify
1150 a function defined by another package, it is cleaner to use
1151 @code{defadvice} (@pxref{Advising Functions}).
1153 @node Obsolete Functions
1154 @section Declaring Functions Obsolete
1156 You can use @code{make-obsolete} to declare a function obsolete. This
1157 indicates that the function may be removed at some stage in the future.
1159 @defun make-obsolete obsolete-name current-name &optional when
1160 This function makes the byte compiler warn that the function
1161 @var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the
1162 warning message says to use @var{current-name} instead of
1163 @var{obsolete-name}. @var{current-name} does not need to be an alias for
1164 @var{obsolete-name}; it can be a different function with similar
1165 functionality. If @var{current-name} is a string, it is the warning
1168 If provided, @var{when} should be a string indicating when the function
1169 was first made obsolete---for example, a date or a release number.
1172 You can define a function as an alias and declare it obsolete at the
1173 same time using the macro @code{define-obsolete-function-alias}.
1175 @defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
1176 This macro marks the function @var{obsolete-name} obsolete and also
1177 defines it as an alias for the function @var{current-name}. It is
1178 equivalent to the following:
1181 (defalias @var{obsolete-name} @var{current-name} @var{docstring})
1182 (make-obsolete @var{obsolete-name} @var{current-name} @var{when})
1186 @node Inline Functions
1187 @section Inline Functions
1188 @cindex inline functions
1191 You can define an @dfn{inline function} by using @code{defsubst} instead
1192 of @code{defun}. An inline function works just like an ordinary
1193 function except for one thing: when you compile a call to the function,
1194 the function's definition is open-coded into the caller.
1196 Making a function inline makes explicit calls run faster. But it also
1197 has disadvantages. For one thing, it reduces flexibility; if you
1198 change the definition of the function, calls already inlined still use
1199 the old definition until you recompile them.
1201 Another disadvantage is that making a large function inline can increase
1202 the size of compiled code both in files and in memory. Since the speed
1203 advantage of inline functions is greatest for small functions, you
1204 generally should not make large functions inline.
1206 Also, inline functions do not behave well with respect to debugging,
1207 tracing, and advising (@pxref{Advising Functions}). Since ease of
1208 debugging and the flexibility of redefining functions are important
1209 features of Emacs, you should not make a function inline, even if it's
1210 small, unless its speed is really crucial, and you've timed the code
1211 to verify that using @code{defun} actually has performance problems.
1213 It's possible to define a macro to expand into the same code that an
1214 inline function would execute. (@xref{Macros}.) But the macro would be
1215 limited to direct use in expressions---a macro cannot be called with
1216 @code{apply}, @code{mapcar} and so on. Also, it takes some work to
1217 convert an ordinary function into a macro. To convert it into an inline
1218 function is very easy; simply replace @code{defun} with @code{defsubst}.
1219 Since each argument of an inline function is evaluated exactly once, you
1220 needn't worry about how many times the body uses the arguments, as you
1221 do for macros. (@xref{Argument Evaluation}.)
1223 Inline functions can be used and open-coded later on in the same file,
1224 following the definition, just like macros.
1226 @node Declaring Functions
1227 @section Telling the Compiler that a Function is Defined
1228 @cindex function declaration
1229 @cindex declaring functions
1230 @findex declare-function
1232 Byte-compiling a file often produces warnings about functions that the
1233 compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this
1234 indicates a real problem, but usually the functions in question are
1235 defined in other files which would be loaded if that code is run. For
1236 example, byte-compiling @file{fortran.el} used to warn:
1240 fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not known to be defined.
1243 In fact, @code{gud-find-c-expr} is only used in the function that
1244 Fortran mode uses for the local value of
1245 @code{gud-find-expr-function}, which is a callback from GUD; if it is
1246 called, the GUD functions will be loaded. When you know that such a
1247 warning does not indicate a real problem, it is good to suppress the
1248 warning. That makes new warnings which might mean real problems more
1249 visible. You do that with @code{declare-function}.
1251 All you need to do is add a @code{declare-function} statement before the
1252 first use of the function in question:
1255 (declare-function gud-find-c-expr "gud.el" nil)
1258 This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
1259 @samp{.el} can be omitted). The compiler takes for granted that that file
1260 really defines the function, and does not check.
1262 The optional third argument specifies the argument list of
1263 @code{gud-find-c-expr}. In this case, it takes no arguments
1264 (@code{nil} is different from not specifying a value). In other
1265 cases, this might be something like @code{(file &optional overwrite)}.
1266 You don't have to specify the argument list, but if you do the
1267 byte compiler can check that the calls match the declaration.
1269 @defmac declare-function function file &optional arglist fileonly
1270 Tell the byte compiler to assume that @var{function} is defined, with
1271 arguments @var{arglist}, and that the definition should come from
1272 the file @var{file}. @var{fileonly} non-nil means only check that
1273 @var{file} exists, not that it actually defines @var{function}.
1276 To verify that these functions really are declared where
1277 @code{declare-function} says they are, use @code{check-declare-file}
1278 to check all @code{declare-function} calls in one source file, or use
1279 @code{check-declare-directory} check all the files in and under a
1282 These commands find the file that ought to contain a function's
1283 definition using @code{locate-library}; if that finds no file, they
1284 expand the definition file name relative to the directory of the file
1285 that contains the @code{declare-function} call.
1287 You can also say that a function is defined by C code by specifying
1288 a file name ending in @samp{.c}. @code{check-declare-file} looks for
1289 these files in the C source code directory. This is useful only when
1290 you call a function that is defined only on certain systems. Most
1291 of the primitive functions of Emacs are always defined so they will
1292 never give you a warning.
1294 Sometimes a file will optionally use functions from an external package.
1295 If you prefix the filename in the @code{declare-function} statement with
1296 @samp{ext:}, then it will be checked if it is found, otherwise skipped
1299 There are some function definitions that @samp{check-declare} does not
1300 understand (e.g. @code{defstruct} and some other macros). In such cases,
1301 you can pass a non-@code{nil} @var{fileonly} argument to
1302 @code{declare-function}, meaning to only check that the file exists, not
1303 that it actually defines the function. Note that to do this without
1304 having to specify an argument list, you should set the @var{arglist}
1305 argument to @code{t} (because @code{nil} means an empty argument list, as
1306 opposed to an unspecified one).
1308 @node Function Safety
1309 @section Determining whether a Function is Safe to Call
1310 @cindex function safety
1311 @cindex safety of functions
1313 Some major modes such as SES call functions that are stored in user
1314 files. (@inforef{Top, ,ses}, for more information on SES.) User
1315 files sometimes have poor pedigrees---you can get a spreadsheet from
1316 someone you've just met, or you can get one through email from someone
1317 you've never met. So it is risky to call a function whose source code
1318 is stored in a user file until you have determined that it is safe.
1320 @defun unsafep form &optional unsafep-vars
1321 Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or
1322 returns a list that describes why it might be unsafe. The argument
1323 @var{unsafep-vars} is a list of symbols known to have temporary
1324 bindings at this point; it is mainly used for internal recursive
1325 calls. The current buffer is an implicit argument, which provides a
1326 list of buffer-local bindings.
1329 Being quick and simple, @code{unsafep} does a very light analysis and
1330 rejects many Lisp expressions that are actually safe. There are no
1331 known cases where @code{unsafep} returns @code{nil} for an unsafe
1332 expression. However, a ``safe'' Lisp expression can return a string
1333 with a @code{display} property, containing an associated Lisp
1334 expression to be executed after the string is inserted into a buffer.
1335 This associated expression can be a virus. In order to be safe, you
1336 must delete properties from all strings calculated by user code before
1337 inserting them into buffers.
1340 What is a safe Lisp expression? Basically, it's an expression that
1341 calls only built-in functions with no side effects (or only innocuous
1342 ones). Innocuous side effects include displaying messages and
1343 altering non-risky buffer-local variables (but not global variables).
1346 @item Safe expression
1349 An atom or quoted thing.
1351 A call to a safe function (see below), if all its arguments are
1354 One of the special forms @code{and}, @code{catch}, @code{cond},
1355 @code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn},
1356 @code{while}, and @code{unwind-protect}], if all its arguments are
1359 A form that creates temporary bindings (@code{condition-case},
1360 @code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or
1361 @code{let*}), if all args are safe and the symbols to be bound are not
1362 explicitly risky (see @pxref{File Local Variables}).
1364 An assignment using @code{add-to-list}, @code{setq}, @code{push}, or
1365 @code{pop}, if all args are safe and the symbols to be assigned are
1366 not explicitly risky and they already have temporary or buffer-local
1369 One of [apply, mapc, mapcar, mapconcat] if the first argument is a
1370 safe explicit lambda and the other args are safe expressions.
1376 A lambda containing safe expressions.
1378 A symbol on the list @code{safe-functions}, so the user says it's safe.
1380 A symbol with a non-@code{nil} @code{side-effect-free} property.
1382 A symbol with a non-@code{nil} @code{safe-function} property. Value t
1383 indicates a function that is safe but has innocuous side effects.
1384 Other values will someday indicate functions with classes of side
1385 effects that are not always safe.
1388 The @code{side-effect-free} and @code{safe-function} properties are
1389 provided for built-in functions and for low-level functions and macros
1390 defined in @file{subr.el}. You can assign these properties for the
1391 functions you write.
1395 @node Related Topics
1396 @section Other Topics Related to Functions
1398 Here is a table of several functions that do things related to
1399 function calling and function definitions. They are documented
1400 elsewhere, but we provide cross references here.
1404 See @ref{Calling Functions}.
1409 @item call-interactively
1410 See @ref{Interactive Call}.
1412 @item called-interactively-p
1413 See @ref{Distinguish Interactive}.
1416 See @ref{Interactive Call}.
1419 See @ref{Accessing Documentation}.
1425 See @ref{Calling Functions}.
1428 See @ref{Anonymous Functions}.
1431 See @ref{Calling Functions}.
1433 @item indirect-function
1434 See @ref{Function Indirection}.
1437 See @ref{Using Interactive}.
1440 See @ref{Distinguish Interactive}.
1443 See @ref{Creating Symbols}.
1446 See @ref{Mapping Functions}.
1448 @item map-char-table
1449 See @ref{Char-Tables}.
1452 See @ref{Mapping Functions}.
1455 See @ref{Functions for Key Lookup}.
1459 arch-tag: 39100cdf-8a55-4898-acba-595db619e8e2