2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
9 A Lisp program is composed mainly of Lisp functions. This chapter
10 explains what functions are, how they accept arguments, and how to
14 * What Is a Function:: Lisp functions vs. primitives; terminology.
15 * Lambda Expressions:: How functions are expressed as Lisp objects.
16 * Function Names:: A symbol can serve as the name of a function.
17 * Defining Functions:: Lisp expressions for defining functions.
18 * Calling Functions:: How to use an existing function.
19 * Mapping Functions:: Applying a function to each element of a list, etc.
20 * Anonymous Functions:: Lambda expressions are functions with no names.
21 * Function Cells:: Accessing or setting the function definition
23 * Closures:: Functions that enclose a lexical environment.
24 * Obsolete Functions:: Declaring functions obsolete.
25 * Inline Functions:: Functions that the compiler will expand inline.
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?
36 @cindex value of function
38 In a general sense, a function is a rule for carrying out a
39 computation given input values called @dfn{arguments}. The result of
40 the computation is called the @dfn{value} or @dfn{return value} of the
41 function. The computation can also have side effects, such as lasting
42 changes in the values of variables or the contents of data structures.
44 In most computer languages, every function has a name. But in Lisp,
45 a function in the strictest sense has no name: it is an object which
46 can @emph{optionally} be associated with a symbol (e.g.@: @code{car})
47 that serves as the function name. @xref{Function Names}. When a
48 function has been given a name, we usually also refer to that symbol
49 as a ``function'' (e.g.@: we refer to ``the function @code{car}'').
50 In this manual, the distinction between a function name and the
51 function object itself is usually unimportant, but we will take note
52 wherever it is relevant.
54 Certain function-like objects, called @dfn{special forms} and
55 @dfn{macros}, also accept arguments to carry out computations.
56 However, as explained below, these are not considered functions in
59 Here are important terms for functions and function-like objects:
62 @item lambda expression
63 A function (in the strict sense, i.e.@: a function object) which is
64 written in Lisp. These are described in the following section.
66 @xref{Lambda Expressions}.
72 @cindex built-in function
73 A function which is callable from Lisp but is actually written in C.
74 Primitives are also called @dfn{built-in functions}, or @dfn{subrs}.
75 Examples include functions like @code{car} and @code{append}. In
76 addition, all special forms (see below) are also considered
79 Usually, a function is implemented as a primitive because it is a
80 fundamental part of Lisp (e.g.@: @code{car}), or because it provides a
81 low-level interface to operating system services, or because it needs
82 to run fast. Unlike functions defined in Lisp, primitives can be
83 modified or added only by changing the C sources and recompiling
84 Emacs. See @ref{Writing Emacs Primitives}.
87 A primitive that is like a function but does not evaluate all of its
88 arguments in the usual way. It may evaluate only some of the
89 arguments, or may evaluate them in an unusual order, or several times.
90 Examples include @code{if}, @code{and}, and @code{while}.
95 A construct defined in Lisp, which differs from a function in that it
96 translates a Lisp expression into another expression which is to be
97 evaluated instead of the original expression. Macros enable Lisp
98 programmers to do the sorts of things that special forms can do.
103 An object which can be invoked via the @code{command-execute}
104 primitive, usually due to the user typing in a key sequence
105 @dfn{bound} to that command. @xref{Interactive Call}. A command is
106 usually a function; if the function is written in Lisp, it is made
107 into a command by an @code{interactive} form in the function
108 definition (@pxref{Defining Commands}). Commands that are functions
109 can also be called from Lisp expressions, just like other functions.
111 Keyboard macros (strings and vectors) are commands also, even though
112 they are not functions. @xref{Keyboard Macros}. We say that a symbol
113 is a command if its function cell contains a command (@pxref{Symbol
114 Components}); such a @dfn{named command} can be invoked with
118 A function object that is much like a lambda expression, except that
119 it also encloses an ``environment'' of lexical variable bindings.
122 @item byte-code function
123 A function that has been compiled by the byte compiler.
124 @xref{Byte-Code Type}.
126 @item autoload object
127 @cindex autoload object
128 A place-holder for a real function. If the autoload object is called,
129 Emacs loads the file containing the definition of the real function,
130 and then calls the real function. @xref{Autoload}.
133 You can use the function @code{functionp} to test if an object is a
136 @defun functionp object
137 This function returns @code{t} if @var{object} is any kind of
138 function, i.e.@: can be passed to @code{funcall}. Note that
139 @code{functionp} returns @code{t} for symbols that are function names,
140 and returns @code{nil} for special forms.
144 Unlike @code{functionp}, the next three functions do @emph{not} treat
145 a symbol as its function definition.
148 This function returns @code{t} if @var{object} is a built-in function
149 (i.e., a Lisp primitive).
153 (subrp 'message) ; @r{@code{message} is a symbol,}
154 @result{} nil ; @r{not a subr object.}
157 (subrp (symbol-function 'message))
163 @defun byte-code-function-p object
164 This function returns @code{t} if @var{object} is a byte-code
165 function. For example:
169 (byte-code-function-p (symbol-function 'next-line))
175 @defun subr-arity subr
176 This function provides information about the argument list of a
177 primitive, @var{subr}. The returned value is a pair
178 @code{(@var{min} . @var{max})}. @var{min} is the minimum number of
179 args. @var{max} is the maximum number or the symbol @code{many}, for a
180 function with @code{&rest} arguments, or the symbol @code{unevalled} if
181 @var{subr} is a special form.
184 @node Lambda Expressions
185 @section Lambda Expressions
186 @cindex lambda expression
188 A lambda expression is a function object written in Lisp. Here is
193 "Return the hyperbolic cosine of X."
194 (* 0.5 (+ (exp x) (exp (- x)))))
198 In Emacs Lisp, such a list is valid as an expression---it evaluates to
199 itself. But its main use is not to be evaluated as an expression, but
200 to be called as a function.
202 A lambda expression, by itself, has no name; it is an @dfn{anonymous
203 function}. Although lambda expressions can be used this way
204 (@pxref{Anonymous Functions}), they are more commonly associated with
205 symbols to make @dfn{named functions} (@pxref{Function Names}).
206 Before going into these details, the following subsections describe
207 the components of a lambda expression and what they do.
210 * Lambda Components:: The parts of a lambda expression.
211 * Simple Lambda:: A simple example.
212 * Argument List:: Details and special features of argument lists.
213 * Function Documentation:: How to put documentation in a function.
216 @node Lambda Components
217 @subsection Components of a Lambda Expression
219 A lambda expression is a list that looks like this:
222 (lambda (@var{arg-variables}@dots{})
223 [@var{documentation-string}]
224 [@var{interactive-declaration}]
225 @var{body-forms}@dots{})
229 The first element of a lambda expression is always the symbol
230 @code{lambda}. This indicates that the list represents a function. The
231 reason functions are defined to start with @code{lambda} is so that
232 other lists, intended for other uses, will not accidentally be valid as
235 The second element is a list of symbols---the argument variable names.
236 This is called the @dfn{lambda list}. When a Lisp function is called,
237 the argument values are matched up against the variables in the lambda
238 list, which are given local bindings with the values provided.
239 @xref{Local Variables}.
241 The documentation string is a Lisp string object placed within the
242 function definition to describe the function for the Emacs help
243 facilities. @xref{Function Documentation}.
245 The interactive declaration is a list of the form @code{(interactive
246 @var{code-string})}. This declares how to provide arguments if the
247 function is used interactively. Functions with this declaration are called
248 @dfn{commands}; they can be called using @kbd{M-x} or bound to a key.
249 Functions not intended to be called in this way should not have interactive
250 declarations. @xref{Defining Commands}, for how to write an interactive
253 @cindex body of function
254 The rest of the elements are the @dfn{body} of the function: the Lisp
255 code to do the work of the function (or, as a Lisp programmer would say,
256 ``a list of Lisp forms to evaluate''). The value returned by the
257 function is the value returned by the last element of the body.
260 @subsection A Simple Lambda Expression Example
262 Consider the following example:
265 (lambda (a b c) (+ a b c))
269 We can call this function by passing it to @code{funcall}, like this:
273 (funcall (lambda (a b c) (+ a b c))
279 This call evaluates the body of the lambda expression with the variable
280 @code{a} bound to 1, @code{b} bound to 2, and @code{c} bound to 3.
281 Evaluation of the body adds these three numbers, producing the result 6;
282 therefore, this call to the function returns the value 6.
284 Note that the arguments can be the results of other function calls, as in
289 (funcall (lambda (a b c) (+ a b c))
295 This evaluates the arguments @code{1}, @code{(* 2 3)}, and @code{(- 5
296 4)} from left to right. Then it applies the lambda expression to the
297 argument values 1, 6 and 1 to produce the value 8.
299 As these examples show, you can use a form with a lambda expression
300 as its @sc{car} to make local variables and give them values. In the
301 old days of Lisp, this technique was the only way to bind and
302 initialize local variables. But nowadays, it is clearer to use the
303 special form @code{let} for this purpose (@pxref{Local Variables}).
304 Lambda expressions are mainly used as anonymous functions for passing
305 as arguments to other functions (@pxref{Anonymous Functions}), or
306 stored as symbol function definitions to produce named functions
307 (@pxref{Function Names}).
310 @subsection Other Features of Argument Lists
311 @kindex wrong-number-of-arguments
312 @cindex argument binding
313 @cindex binding arguments
314 @cindex argument lists, features
316 Our simple sample function, @code{(lambda (a b c) (+ a b c))},
317 specifies three argument variables, so it must be called with three
318 arguments: if you try to call it with only two arguments or four
319 arguments, you get a @code{wrong-number-of-arguments} error.
321 It is often convenient to write a function that allows certain
322 arguments to be omitted. For example, the function @code{substring}
323 accepts three arguments---a string, the start index and the end
324 index---but the third argument defaults to the @var{length} of the
325 string if you omit it. It is also convenient for certain functions to
326 accept an indefinite number of arguments, as the functions @code{list}
329 @cindex optional arguments
330 @cindex rest arguments
333 To specify optional arguments that may be omitted when a function
334 is called, simply include the keyword @code{&optional} before the optional
335 arguments. To specify a list of zero or more extra arguments, include the
336 keyword @code{&rest} before one final argument.
338 Thus, the complete syntax for an argument list is as follows:
342 (@var{required-vars}@dots{}
343 @r{[}&optional @var{optional-vars}@dots{}@r{]}
344 @r{[}&rest @var{rest-var}@r{]})
349 The square brackets indicate that the @code{&optional} and @code{&rest}
350 clauses, and the variables that follow them, are optional.
352 A call to the function requires one actual argument for each of the
353 @var{required-vars}. There may be actual arguments for zero or more of
354 the @var{optional-vars}, and there cannot be any actual arguments beyond
355 that unless the lambda list uses @code{&rest}. In that case, there may
356 be any number of extra actual arguments.
358 If actual arguments for the optional and rest variables are omitted,
359 then they always default to @code{nil}. There is no way for the
360 function to distinguish between an explicit argument of @code{nil} and
361 an omitted argument. However, the body of the function is free to
362 consider @code{nil} an abbreviation for some other meaningful value.
363 This is what @code{substring} does; @code{nil} as the third argument to
364 @code{substring} means to use the length of the string supplied.
366 @cindex CL note---default optional arg
368 @b{Common Lisp note:} Common Lisp allows the function to specify what
369 default value to use when an optional argument is omitted; Emacs Lisp
370 always uses @code{nil}. Emacs Lisp does not support ``supplied-p''
371 variables that tell you whether an argument was explicitly passed.
374 For example, an argument list that looks like this:
377 (a b &optional c d &rest e)
381 binds @code{a} and @code{b} to the first two actual arguments, which are
382 required. If one or two more arguments are provided, @code{c} and
383 @code{d} are bound to them respectively; any arguments after the first
384 four are collected into a list and @code{e} is bound to that list. If
385 there are only two arguments, @code{c} is @code{nil}; if two or three
386 arguments, @code{d} is @code{nil}; if four arguments or fewer, @code{e}
389 There is no way to have required arguments following optional
390 ones---it would not make sense. To see why this must be so, suppose
391 that @code{c} in the example were optional and @code{d} were required.
392 Suppose three actual arguments are given; which variable would the
393 third argument be for? Would it be used for the @var{c}, or for
394 @var{d}? One can argue for both possibilities. Similarly, it makes
395 no sense to have any more arguments (either required or optional)
396 after a @code{&rest} argument.
398 Here are some examples of argument lists and proper calls:
401 (funcall (lambda (n) (1+ n)) ; @r{One required:}
402 1) ; @r{requires exactly one argument.}
404 (funcall (lambda (n &optional n1) ; @r{One required and one optional:}
405 (if n1 (+ n n1) (1+ n))) ; @r{1 or 2 arguments.}
408 (funcall (lambda (n &rest ns) ; @r{One required and one rest:}
409 (+ n (apply '+ ns))) ; @r{1 or more arguments.}
414 @node Function Documentation
415 @subsection Documentation Strings of Functions
416 @cindex documentation of function
418 A lambda expression may optionally have a @dfn{documentation string}
419 just after the lambda list. This string does not affect execution of
420 the function; it is a kind of comment, but a systematized comment
421 which actually appears inside the Lisp world and can be used by the
422 Emacs help facilities. @xref{Documentation}, for how the
423 documentation string is accessed.
425 It is a good idea to provide documentation strings for all the
426 functions in your program, even those that are called only from within
427 your program. Documentation strings are like comments, except that they
428 are easier to access.
430 The first line of the documentation string should stand on its own,
431 because @code{apropos} displays just this first line. It should consist
432 of one or two complete sentences that summarize the function's purpose.
434 The start of the documentation string is usually indented in the
435 source file, but since these spaces come before the starting
436 double-quote, they are not part of the string. Some people make a
437 practice of indenting any additional lines of the string so that the
438 text lines up in the program source. @emph{That is a mistake.} The
439 indentation of the following lines is inside the string; what looks
440 nice in the source code will look ugly when displayed by the help
443 You may wonder how the documentation string could be optional, since
444 there are required components of the function that follow it (the body).
445 Since evaluation of a string returns that string, without any side effects,
446 it has no effect if it is not the last form in the body. Thus, in
447 practice, there is no confusion between the first form of the body and the
448 documentation string; if the only body form is a string then it serves both
449 as the return value and as the documentation.
451 The last line of the documentation string can specify calling
452 conventions different from the actual function arguments. Write
460 following a blank line, at the beginning of the line, with no newline
461 following it inside the documentation string. (The @samp{\} is used
462 to avoid confusing the Emacs motion commands.) The calling convention
463 specified in this way appears in help messages in place of the one
464 derived from the actual arguments of the function.
466 This feature is particularly useful for macro definitions, since the
467 arguments written in a macro definition often do not correspond to the
468 way users think of the parts of the macro call.
471 @section Naming a Function
472 @cindex function definition
473 @cindex named function
474 @cindex function name
476 A symbol can serve as the name of a function. This happens when the
477 symbol's @dfn{function cell} (@pxref{Symbol Components}) contains a
478 function object (e.g.@: a lambda expression). Then the symbol itself
479 becomes a valid, callable function, equivalent to the function object
480 in its function cell.
482 The contents of the function cell are also called the symbol's
483 @dfn{function definition}. The procedure of using a symbol's function
484 definition in place of the symbol is called @dfn{symbol function
485 indirection}; see @ref{Function Indirection}. If you have not given a
486 symbol a function definition, its function cell is said to be
487 @dfn{void}, and it cannot be used as a function.
489 In practice, nearly all functions have names, and are referred to by
490 their names. You can create a named Lisp function by defining a
491 lambda expression and putting it in a function cell (@pxref{Function
492 Cells}). However, it is more common to use the @code{defun} special
493 form, described in the next section.
495 @xref{Defining Functions}.
498 We give functions names because it is convenient to refer to them by
499 their names in Lisp expressions. Also, a named Lisp function can
500 easily refer to itself---it can be recursive. Furthermore, primitives
501 can only be referred to textually by their names, since primitive
502 function objects (@pxref{Primitive Function Type}) have no read
505 A function need not have a unique name. A given function object
506 @emph{usually} appears in the function cell of only one symbol, but
507 this is just a convention. It is easy to store it in several symbols
508 using @code{fset}; then each of the symbols is a valid name for the
511 Note that a symbol used as a function name may also be used as a
512 variable; these two uses of a symbol are independent and do not
513 conflict. (This is not the case in some dialects of Lisp, like
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}. Its return value is @emph{undefined}.
535 As described previously, @var{argument-list} is a list of argument
536 names and may include the keywords @code{&optional} and @code{&rest}.
537 Also, the first two of the @var{body-forms} may be a documentation
538 string and an interactive declaration. @xref{Lambda Components}.
540 Here are some examples:
550 (defun bar (a &optional b &rest c)
553 @result{} (1 2 (3 4 5))
557 @result{} (1 nil nil)
561 @error{} Wrong number of arguments.
565 (defun capitalize-backwards ()
566 "Upcase the last letter of the word at point."
575 Be careful not to redefine existing functions unintentionally.
576 @code{defun} redefines even primitive functions such as @code{car}
577 without any hesitation or notification. Emacs does not prevent you
578 from doing this, because redefining a function is sometimes done
579 deliberately, and there is no way to distinguish deliberate
580 redefinition from unintentional redefinition.
583 @cindex function aliases
584 @defun defalias name definition &optional docstring
585 @anchor{Definition of defalias}
586 This special form defines the symbol @var{name} as a function, with
587 definition @var{definition} (which can be any valid Lisp function).
588 Its return value is @emph{undefined}.
590 If @var{docstring} is non-@code{nil}, it becomes the function
591 documentation of @var{name}. Otherwise, any documentation provided by
592 @var{definition} is used.
594 The proper place to use @code{defalias} is where a specific function
595 name is being defined---especially where that name appears explicitly in
596 the source file being loaded. This is because @code{defalias} records
597 which file defined the function, just like @code{defun}
600 By contrast, in programs that manipulate function definitions for other
601 purposes, it is better to use @code{fset}, which does not keep such
602 records. @xref{Function Cells}.
605 You cannot create a new primitive function with @code{defun} or
606 @code{defalias}, but you can use them to change the function definition of
607 any symbol, even one such as @code{car} or @code{x-popup-menu} whose
608 normal definition is a primitive. However, this is risky: for
609 instance, it is next to impossible to redefine @code{car} without
610 breaking Lisp completely. Redefining an obscure function such as
611 @code{x-popup-menu} is less dangerous, but it still may not work as
612 you expect. If there are calls to the primitive from C code, they
613 call the primitive's C definition directly, so changing the symbol's
614 definition will have no effect on them.
616 See also @code{defsubst}, which defines a function like @code{defun}
617 and tells the Lisp compiler to perform inline expansion on it.
618 @xref{Inline Functions}.
620 @node Calling Functions
621 @section Calling Functions
622 @cindex function invocation
623 @cindex calling a function
625 Defining functions is only half the battle. Functions don't do
626 anything until you @dfn{call} them, i.e., tell them to run. Calling a
627 function is also known as @dfn{invocation}.
629 The most common way of invoking a function is by evaluating a list.
630 For example, evaluating the list @code{(concat "a" "b")} calls the
631 function @code{concat} with arguments @code{"a"} and @code{"b"}.
632 @xref{Evaluation}, for a description of evaluation.
634 When you write a list as an expression in your program, you specify
635 which function to call, and how many arguments to give it, in the text
636 of the program. Usually that's just what you want. Occasionally you
637 need to compute at run time which function to call. To do that, use
638 the function @code{funcall}. When you also need to determine at run
639 time how many arguments to pass, use @code{apply}.
641 @defun funcall function &rest arguments
642 @code{funcall} calls @var{function} with @var{arguments}, and returns
643 whatever @var{function} returns.
645 Since @code{funcall} is a function, all of its arguments, including
646 @var{function}, are evaluated before @code{funcall} is called. This
647 means that you can use any expression to obtain the function to be
648 called. It also means that @code{funcall} does not see the
649 expressions you write for the @var{arguments}, only their values.
650 These values are @emph{not} evaluated a second time in the act of
651 calling @var{function}; the operation of @code{funcall} is like the
652 normal procedure for calling a function, once its arguments have
653 already been evaluated.
655 The argument @var{function} must be either a Lisp function or a
656 primitive function. Special forms and macros are not allowed, because
657 they make sense only when given the ``unevaluated'' argument
658 expressions. @code{funcall} cannot provide these because, as we saw
659 above, it never knows them in the first place.
671 (funcall f 'x 'y '(z))
676 @error{} Invalid function: #<subr and>
680 Compare these examples with the examples of @code{apply}.
683 @defun apply function &rest arguments
684 @code{apply} calls @var{function} with @var{arguments}, just like
685 @code{funcall} but with one difference: the last of @var{arguments} is a
686 list of objects, which are passed to @var{function} as separate
687 arguments, rather than a single list. We say that @code{apply}
688 @dfn{spreads} this list so that each individual element becomes an
691 @code{apply} returns the result of calling @var{function}. As with
692 @code{funcall}, @var{function} must either be a Lisp function or a
693 primitive function; special forms and macros do not make sense in
703 @error{} Wrong type argument: listp, z
706 (apply '+ 1 2 '(3 4))
710 (apply '+ '(1 2 3 4))
715 (apply 'append '((a b c) nil (x y z) nil))
716 @result{} (a b c x y z)
720 For an interesting example of using @code{apply}, see @ref{Definition
724 @cindex partial application of functions
726 Sometimes it is useful to fix some of the function's arguments at
727 certain values, and leave the rest of arguments for when the function
728 is actually called. The act of fixing some of the function's
729 arguments is called @dfn{partial application} of the function@footnote{
730 This is related to, but different from @dfn{currying}, which
731 transforms a function that takes multiple arguments in such a way that
732 it can be called as a chain of functions, each one with a single
734 The result is a new function that accepts the rest of
735 arguments and calls the original function with all the arguments
738 Here's how to do partial application in Emacs Lisp:
740 @defun apply-partially func &rest args
741 This function returns a new function which, when called, will call
742 @var{func} with the list of arguments composed from @var{args} and
743 additional arguments specified at the time of the call. If @var{func}
744 accepts @var{n} arguments, then a call to @code{apply-partially} with
745 @w{@code{@var{m} < @var{n}}} arguments will produce a new function of
746 @w{@code{@var{n} - @var{m}}} arguments.
748 Here's how we could define the built-in function @code{1+}, if it
749 didn't exist, using @code{apply-partially} and @code{+}, another
754 (defalias '1+ (apply-partially '+ 1)
755 "Increment argument by one.")
765 It is common for Lisp functions to accept functions as arguments or
766 find them in data structures (especially in hook variables and property
767 lists) and call them using @code{funcall} or @code{apply}. Functions
768 that accept function arguments are often called @dfn{functionals}.
770 Sometimes, when you call a functional, it is useful to supply a no-op
771 function as the argument. Here are two different kinds of no-op
775 This function returns @var{arg} and has no side effects.
778 @defun ignore &rest args
779 This function ignores any arguments and returns @code{nil}.
782 Some functions are user-visible @dfn{commands}, which can be called
783 interactively (usually by a key sequence). It is possible to invoke
784 such a command exactly as though it was called interactively, by using
785 the @code{call-interactively} function. @xref{Interactive Call}.
787 @node Mapping Functions
788 @section Mapping Functions
789 @cindex mapping functions
791 A @dfn{mapping function} applies a given function (@emph{not} a
792 special form or macro) to each element of a list or other collection.
793 Emacs Lisp has several such functions; this section describes
794 @code{mapcar}, @code{mapc}, and @code{mapconcat}, which map over a
795 list. @xref{Definition of mapatoms}, for the function @code{mapatoms}
796 which maps over the symbols in an obarray. @xref{Definition of
797 maphash}, for the function @code{maphash} which maps over key/value
798 associations in a hash table.
800 These mapping functions do not allow char-tables because a char-table
801 is a sparse array whose nominal range of indices is very large. To map
802 over a char-table in a way that deals properly with its sparse nature,
803 use the function @code{map-char-table} (@pxref{Char-Tables}).
805 @defun mapcar function sequence
806 @anchor{Definition of mapcar}
807 @code{mapcar} applies @var{function} to each element of @var{sequence}
808 in turn, and returns a list of the results.
810 The argument @var{sequence} can be any kind of sequence except a
811 char-table; that is, a list, a vector, a bool-vector, or a string. The
812 result is always a list. The length of the result is the same as the
813 length of @var{sequence}. For example:
817 (mapcar 'car '((a b) (c d) (e f)))
821 (mapcar 'string "abc")
822 @result{} ("a" "b" "c")
826 ;; @r{Call each function in @code{my-hooks}.}
827 (mapcar 'funcall my-hooks)
831 (defun mapcar* (function &rest args)
832 "Apply FUNCTION to successive cars of all ARGS.
833 Return the list of results."
834 ;; @r{If no list is exhausted,}
835 (if (not (memq nil args))
836 ;; @r{apply function to @sc{car}s.}
837 (cons (apply function (mapcar 'car args))
838 (apply 'mapcar* function
839 ;; @r{Recurse for rest of elements.}
840 (mapcar 'cdr args)))))
844 (mapcar* 'cons '(a b c) '(1 2 3 4))
845 @result{} ((a . 1) (b . 2) (c . 3))
850 @defun mapc function sequence
851 @code{mapc} is like @code{mapcar} except that @var{function} is used for
852 side-effects only---the values it returns are ignored, not collected
853 into a list. @code{mapc} always returns @var{sequence}.
856 @defun mapconcat function sequence separator
857 @code{mapconcat} applies @var{function} to each element of
858 @var{sequence}: the results, which must be strings, are concatenated.
859 Between each pair of result strings, @code{mapconcat} inserts the string
860 @var{separator}. Usually @var{separator} contains a space or comma or
861 other suitable punctuation.
863 The argument @var{function} must be a function that can take one
864 argument and return a string. The argument @var{sequence} can be any
865 kind of sequence except a char-table; that is, a list, a vector, a
866 bool-vector, or a string.
870 (mapconcat 'symbol-name
871 '(The cat in the hat)
873 @result{} "The cat in the hat"
877 (mapconcat (function (lambda (x) (format "%c" (1+ x))))
885 @node Anonymous Functions
886 @section Anonymous Functions
887 @cindex anonymous function
889 Although functions are usually defined with @code{defun} and given
890 names at the same time, it is sometimes convenient to use an explicit
891 lambda expression---an @dfn{anonymous function}. Anonymous functions
892 are valid wherever function names are. They are often assigned as
893 variable values, or as arguments to functions; for instance, you might
894 pass one as the @var{function} argument to @code{mapcar}, which
895 applies that function to each element of a list (@pxref{Mapping
896 Functions}). @xref{describe-symbols example}, for a realistic example
899 When defining a lambda expression that is to be used as an anonymous
900 function, you can in principle use any method to construct the list.
901 But typically you should use the @code{lambda} macro, or the
902 @code{function} special form, or the @code{#'} read syntax:
904 @defmac lambda args body...
905 This macro returns an anonymous function with argument list @var{args}
906 and body forms given by @var{body}. In effect, this macro makes
907 @code{lambda} forms ``self-quoting'': evaluating a form whose @sc{car}
908 is @code{lambda} yields the form itself:
912 @result{} (lambda (x) (* x x))
915 The @code{lambda} form has one other effect: it tells the Emacs
916 evaluator and byte-compiler that its argument is a function, by using
917 @code{function} as a subroutine (see below).
920 @defspec function function-object
921 @cindex function quoting
922 This special form returns @var{function-object} without evaluating it.
923 In this, it is similar to @code{quote} (@pxref{Quoting}). But unlike
924 @code{quote}, it also serves as a note to the Emacs evaluator and
925 byte-compiler that @var{function-object} is intended to be used as a
926 function. Assuming @var{function-object} is a valid lambda
927 expression, this has two effects:
931 When the code is byte-compiled, @var{function-object} is compiled into
932 a byte-code function object (@pxref{Byte Compilation}).
935 When lexical binding is enabled, @var{function-object} is converted
936 into a closure. @xref{Closures}.
940 @cindex @samp{#'} syntax
941 The read syntax @code{#'} is a short-hand for using @code{function}.
942 The following forms are all equivalent:
946 (function (lambda (x) (* x x)))
947 #'(lambda (x) (* x x))
950 In the following example, we define a @code{change-property}
951 function that takes a function as its third argument, followed by a
952 @code{double-property} function that makes use of
953 @code{change-property} by passing it an anonymous function:
957 (defun change-property (symbol prop function)
958 (let ((value (get symbol prop)))
959 (put symbol prop (funcall function value))))
963 (defun double-property (symbol prop)
964 (change-property symbol prop (lambda (x) (* 2 x))))
969 Note that we do not quote the @code{lambda} form.
971 If you compile the above code, the anonymous function is also
972 compiled. This would not happen if, say, you had constructed the
973 anonymous function by quoting it as a list:
977 (defun double-property (symbol prop)
978 (change-property symbol prop '(lambda (x) (* 2 x))))
983 In that case, the anonymous function is kept as a lambda expression in
984 the compiled code. The byte-compiler cannot assume this list is a
985 function, even though it looks like one, since it does not know that
986 @code{change-property} intends to use it as a function.
989 @section Accessing Function Cell Contents
991 The @dfn{function definition} of a symbol is the object stored in the
992 function cell of the symbol. The functions described here access, test,
993 and set the function cell of symbols.
995 See also the function @code{indirect-function}. @xref{Definition of
998 @defun symbol-function symbol
999 @kindex void-function
1000 This returns the object in the function cell of @var{symbol}. If the
1001 symbol's function cell is void, a @code{void-function} error is
1004 This function does not check that the returned object is a legitimate
1009 (defun bar (n) (+ n 2))
1010 (symbol-function 'bar)
1011 @result{} (lambda (n) (+ n 2))
1018 (symbol-function 'baz)
1024 @cindex void function cell
1025 If you have never given a symbol any function definition, we say that
1026 that symbol's function cell is @dfn{void}. In other words, the function
1027 cell does not have any Lisp object in it. If you try to call such a symbol
1028 as a function, it signals a @code{void-function} error.
1030 Note that void is not the same as @code{nil} or the symbol
1031 @code{void}. The symbols @code{nil} and @code{void} are Lisp objects,
1032 and can be stored into a function cell just as any other object can be
1033 (and they can be valid functions if you define them in turn with
1034 @code{defun}). A void function cell contains no object whatsoever.
1036 You can test the voidness of a symbol's function definition with
1037 @code{fboundp}. After you have given a symbol a function definition, you
1038 can make it void once more using @code{fmakunbound}.
1040 @defun fboundp symbol
1041 This function returns @code{t} if the symbol has an object in its
1042 function cell, @code{nil} otherwise. It does not check that the object
1043 is a legitimate function.
1046 @defun fmakunbound symbol
1047 This function makes @var{symbol}'s function cell void, so that a
1048 subsequent attempt to access this cell will cause a
1049 @code{void-function} error. It returns @var{symbol}. (See also
1050 @code{makunbound}, in @ref{Void Variables}.)
1064 @error{} Symbol's function definition is void: foo
1069 @defun fset symbol definition
1070 This function stores @var{definition} in the function cell of
1071 @var{symbol}. The result is @var{definition}. Normally
1072 @var{definition} should be a function or the name of a function, but
1073 this is not checked. The argument @var{symbol} is an ordinary evaluated
1076 The primary use of this function is as a subroutine by constructs that
1077 define or alter functions, like @code{defadvice} (@pxref{Advising
1078 Functions}). (If @code{defun} were not a primitive, it could be
1079 written as a Lisp macro using @code{fset}.) You can also use it to
1080 give a symbol a function definition that is not a list, e.g.@: a
1081 keyboard macro (@pxref{Keyboard Macros}):
1084 ;; @r{Define a named keyboard macro.}
1085 (fset 'kill-two-lines "\^u2\^k")
1089 It you wish to use @code{fset} to make an alternate name for a
1090 function, consider using @code{defalias} instead. @xref{Definition of
1097 As explained in @ref{Variable Scoping}, Emacs can optionally enable
1098 lexical binding of variables. When lexical binding is enabled, any
1099 named function that you create (e.g.@: with @code{defun}), as well as
1100 any anonymous function that you create using the @code{lambda} macro
1101 or the @code{function} special form or the @code{#'} syntax
1102 (@pxref{Anonymous Functions}), is automatically converted into a
1105 A closure is a function that also carries a record of the lexical
1106 environment that existed when the function was defined. When it is
1107 invoked, any lexical variable references within its definition use the
1108 retained lexical environment. In all other respects, closures behave
1109 much like ordinary functions; in particular, they can be called in the
1110 same way as ordinary functions.
1112 @xref{Lexical Binding}, for an example of using a closure.
1114 Currently, an Emacs Lisp closure object is represented by a list
1115 with the symbol @code{closure} as the first element, a list
1116 representing the lexical environment as the second element, and the
1117 argument list and body forms as the remaining elements:
1120 ;; @r{lexical binding is enabled.}
1121 (lambda (x) (* x x))
1122 @result{} (closure (t) (x) (* x x))
1126 However, the fact that the internal structure of a closure is
1127 ``exposed'' to the rest of the Lisp world is considered an internal
1128 implementation detail. For this reason, we recommend against directly
1129 examining or altering the structure of closure objects.
1131 @node Obsolete Functions
1132 @section Declaring Functions Obsolete
1134 You can use @code{make-obsolete} to declare a function obsolete. This
1135 indicates that the function may be removed at some stage in the future.
1137 @defun make-obsolete obsolete-name current-name &optional when
1138 This function makes the byte compiler warn that the function
1139 @var{obsolete-name} is obsolete. If @var{current-name} is a symbol, the
1140 warning message says to use @var{current-name} instead of
1141 @var{obsolete-name}. @var{current-name} does not need to be an alias for
1142 @var{obsolete-name}; it can be a different function with similar
1143 functionality. If @var{current-name} is a string, it is the warning
1146 If provided, @var{when} should be a string indicating when the function
1147 was first made obsolete---for example, a date or a release number.
1150 You can define a function as an alias and declare it obsolete at the
1151 same time using the macro @code{define-obsolete-function-alias}:
1153 @defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
1154 This macro marks the function @var{obsolete-name} obsolete and also
1155 defines it as an alias for the function @var{current-name}. It is
1156 equivalent to the following:
1159 (defalias @var{obsolete-name} @var{current-name} @var{docstring})
1160 (make-obsolete @var{obsolete-name} @var{current-name} @var{when})
1164 In addition, you can mark a certain a particular calling convention
1165 for a function as obsolete:
1167 @defun set-advertised-calling-convention function signature when
1168 This function specifies the argument list @var{signature} as the
1169 correct way to call @var{function}. This causes the Emacs byte
1170 compiler to issue a warning whenever it comes across an Emacs Lisp
1171 program that calls @var{function} any other way (however, it will
1172 still allow the code to be byte compiled). @var{when} should be a
1173 string indicating when the variable was first made obsolete (usually a
1174 version number string).
1176 For instance, in old versions of Emacs the @code{sit-for} function
1177 accepted three arguments, like this
1180 (sit-for seconds milliseconds nodisp)
1183 However, calling @code{sit-for} this way is considered obsolete
1184 (@pxref{Waiting}). The old calling convention is deprecated like
1188 (set-advertised-calling-convention
1189 'sit-for '(seconds &optional nodisp) "22.1")
1193 @node Inline Functions
1194 @section Inline Functions
1195 @cindex inline functions
1197 @defmac defsubst name argument-list body-forms...
1198 Define an inline function. The syntax is exactly the same as
1199 @code{defun} (@pxref{Defining Functions}).
1202 You can define an @dfn{inline function} by using @code{defsubst}
1203 instead of @code{defun}. An inline function works just like an
1204 ordinary function except for one thing: when you byte-compile a call
1205 to the function (@pxref{Byte Compilation}), the function's definition
1206 is expanded into the caller.
1208 Making a function inline often makes its function calls run faster.
1209 But it also has disadvantages. For one thing, it reduces flexibility;
1210 if you change the definition of the function, calls already inlined
1211 still use the old definition until you recompile them.
1213 Another disadvantage is that making a large function inline can
1214 increase the size of compiled code both in files and in memory. Since
1215 the speed advantage of inline functions is greatest for small
1216 functions, you generally should not make large functions inline.
1218 Also, inline functions do not behave well with respect to debugging,
1219 tracing, and advising (@pxref{Advising Functions}). Since ease of
1220 debugging and the flexibility of redefining functions are important
1221 features of Emacs, you should not make a function inline, even if it's
1222 small, unless its speed is really crucial, and you've timed the code
1223 to verify that using @code{defun} actually has performance problems.
1225 It's possible to define a macro to expand into the same code that an
1226 inline function would execute (@pxref{Macros}). But the macro would
1227 be limited to direct use in expressions---a macro cannot be called
1228 with @code{apply}, @code{mapcar} and so on. Also, it takes some work
1229 to convert an ordinary function into a macro. To convert it into an
1230 inline function is easy; just replace @code{defun} with
1231 @code{defsubst}. Since each argument of an inline function is
1232 evaluated exactly once, you needn't worry about how many times the
1233 body uses the arguments, as you do for macros.
1235 After an inline function is defined, its inline expansion can be
1236 performed later on in the same file, just like macros.
1238 @node Declaring Functions
1239 @section Telling the Compiler that a Function is Defined
1240 @cindex function declaration
1241 @cindex declaring functions
1242 @findex declare-function
1244 Byte-compiling a file often produces warnings about functions that the
1245 compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this
1246 indicates a real problem, but usually the functions in question are
1247 defined in other files which would be loaded if that code is run. For
1248 example, byte-compiling @file{fortran.el} used to warn:
1252 fortran.el:2152:1:Warning: the function `gud-find-c-expr' is not
1253 known to be defined.
1256 In fact, @code{gud-find-c-expr} is only used in the function that
1257 Fortran mode uses for the local value of
1258 @code{gud-find-expr-function}, which is a callback from GUD; if it is
1259 called, the GUD functions will be loaded. When you know that such a
1260 warning does not indicate a real problem, it is good to suppress the
1261 warning. That makes new warnings which might mean real problems more
1262 visible. You do that with @code{declare-function}.
1264 All you need to do is add a @code{declare-function} statement before the
1265 first use of the function in question:
1268 (declare-function gud-find-c-expr "gud.el" nil)
1271 This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the
1272 @samp{.el} can be omitted). The compiler takes for granted that that file
1273 really defines the function, and does not check.
1275 The optional third argument specifies the argument list of
1276 @code{gud-find-c-expr}. In this case, it takes no arguments
1277 (@code{nil} is different from not specifying a value). In other
1278 cases, this might be something like @code{(file &optional overwrite)}.
1279 You don't have to specify the argument list, but if you do the
1280 byte compiler can check that the calls match the declaration.
1282 @defmac declare-function function file &optional arglist fileonly
1283 Tell the byte compiler to assume that @var{function} is defined, with
1284 arguments @var{arglist}, and that the definition should come from the
1285 file @var{file}. @var{fileonly} non-@code{nil} means only check that
1286 @var{file} exists, not that it actually defines @var{function}.
1289 To verify that these functions really are declared where
1290 @code{declare-function} says they are, use @code{check-declare-file}
1291 to check all @code{declare-function} calls in one source file, or use
1292 @code{check-declare-directory} check all the files in and under a
1295 These commands find the file that ought to contain a function's
1296 definition using @code{locate-library}; if that finds no file, they
1297 expand the definition file name relative to the directory of the file
1298 that contains the @code{declare-function} call.
1300 You can also say that a function is a primitive by specifying a file
1301 name ending in @samp{.c} or @samp{.m}. This is useful only when you
1302 call a primitive that is defined only on certain systems. Most
1303 primitives are always defined, so they will never give you a warning.
1305 Sometimes a file will optionally use functions from an external package.
1306 If you prefix the filename in the @code{declare-function} statement with
1307 @samp{ext:}, then it will be checked if it is found, otherwise skipped
1310 There are some function definitions that @samp{check-declare} does not
1311 understand (e.g. @code{defstruct} and some other macros). In such cases,
1312 you can pass a non-@code{nil} @var{fileonly} argument to
1313 @code{declare-function}, meaning to only check that the file exists, not
1314 that it actually defines the function. Note that to do this without
1315 having to specify an argument list, you should set the @var{arglist}
1316 argument to @code{t} (because @code{nil} means an empty argument list, as
1317 opposed to an unspecified one).
1319 @node Function Safety
1320 @section Determining whether a Function is Safe to Call
1321 @cindex function safety
1322 @cindex safety of functions
1324 Some major modes such as SES call functions that are stored in user
1325 files. (@inforef{Top, ,ses}, for more information on SES.) User
1326 files sometimes have poor pedigrees---you can get a spreadsheet from
1327 someone you've just met, or you can get one through email from someone
1328 you've never met. So it is risky to call a function whose source code
1329 is stored in a user file until you have determined that it is safe.
1331 @defun unsafep form &optional unsafep-vars
1332 Returns @code{nil} if @var{form} is a @dfn{safe} Lisp expression, or
1333 returns a list that describes why it might be unsafe. The argument
1334 @var{unsafep-vars} is a list of symbols known to have temporary
1335 bindings at this point; it is mainly used for internal recursive
1336 calls. The current buffer is an implicit argument, which provides a
1337 list of buffer-local bindings.
1340 Being quick and simple, @code{unsafep} does a very light analysis and
1341 rejects many Lisp expressions that are actually safe. There are no
1342 known cases where @code{unsafep} returns @code{nil} for an unsafe
1343 expression. However, a ``safe'' Lisp expression can return a string
1344 with a @code{display} property, containing an associated Lisp
1345 expression to be executed after the string is inserted into a buffer.
1346 This associated expression can be a virus. In order to be safe, you
1347 must delete properties from all strings calculated by user code before
1348 inserting them into buffers.
1351 What is a safe Lisp expression? Basically, it's an expression that
1352 calls only built-in functions with no side effects (or only innocuous
1353 ones). Innocuous side effects include displaying messages and
1354 altering non-risky buffer-local variables (but not global variables).
1357 @item Safe expression
1360 An atom or quoted thing.
1362 A call to a safe function (see below), if all its arguments are
1365 One of the special forms @code{and}, @code{catch}, @code{cond},
1366 @code{if}, @code{or}, @code{prog1}, @code{prog2}, @code{progn},
1367 @code{while}, and @code{unwind-protect}], if all its arguments are
1370 A form that creates temporary bindings (@code{condition-case},
1371 @code{dolist}, @code{dotimes}, @code{lambda}, @code{let}, or
1372 @code{let*}), if all args are safe and the symbols to be bound are not
1373 explicitly risky (see @pxref{File Local Variables}).
1375 An assignment using @code{add-to-list}, @code{setq}, @code{push}, or
1376 @code{pop}, if all args are safe and the symbols to be assigned are
1377 not explicitly risky and they already have temporary or buffer-local
1380 One of [apply, mapc, mapcar, mapconcat] if the first argument is a
1381 safe explicit lambda and the other args are safe expressions.
1387 A lambda containing safe expressions.
1389 A symbol on the list @code{safe-functions}, so the user says it's safe.
1391 A symbol with a non-@code{nil} @code{side-effect-free} property.
1393 A symbol with a non-@code{nil} @code{safe-function} property. The
1394 value @code{t} indicates a function that is safe but has innocuous
1395 side effects. Other values will someday indicate functions with
1396 classes of side effects that are not always safe.
1399 The @code{side-effect-free} and @code{safe-function} properties are
1400 provided for built-in functions and for low-level functions and macros
1401 defined in @file{subr.el}. You can assign these properties for the
1402 functions you write.
1406 @node Related Topics
1407 @section Other Topics Related to Functions
1409 Here is a table of several functions that do things related to
1410 function calling and function definitions. They are documented
1411 elsewhere, but we provide cross references here.
1415 See @ref{Calling Functions}.
1420 @item call-interactively
1421 See @ref{Interactive Call}.
1423 @item called-interactively-p
1424 See @ref{Distinguish Interactive}.
1427 See @ref{Interactive Call}.
1430 See @ref{Accessing Documentation}.
1436 See @ref{Calling Functions}.
1439 See @ref{Anonymous Functions}.
1442 See @ref{Calling Functions}.
1444 @item indirect-function
1445 See @ref{Function Indirection}.
1448 See @ref{Using Interactive}.
1451 See @ref{Distinguish Interactive}.
1454 See @ref{Creating Symbols}.
1457 See @ref{Mapping Functions}.
1459 @item map-char-table
1460 See @ref{Char-Tables}.
1463 See @ref{Mapping Functions}.
1466 See @ref{Functions for Key Lookup}.