1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Default Value, Prev: Creating Buffer-Local, Up: Buffer-Local Variables
55 The Default Value of a Buffer-Local Variable
56 --------------------------------------------
58 The global value of a variable with buffer-local bindings is also
59 called the "default" value, because it is the value that is in effect
60 except when specifically overridden.
62 The functions `default-value' and `setq-default' access and change a
63 variable's default value regardless of whether the current buffer has a
64 buffer-local binding. For example, you could use `setq-default' to
65 change the default setting of `paragraph-start' for most buffers; and
66 this would work even when you are in a C or Lisp mode buffer that has a
67 buffer-local value for this variable.
69 The special forms `defvar' and `defconst' also set the default value
70 (if they set the variable at all), rather than any local value.
72 - Function: default-value symbol
73 This function returns SYMBOL's default value. This is the value
74 that is seen in buffers that do not have their own values for this
75 variable. If SYMBOL is not buffer-local, this is equivalent to
76 `symbol-value' (*note Accessing Variables::).
78 - Function: default-boundp symbol
79 The function `default-boundp' tells you whether SYMBOL's default
80 value is nonvoid. If `(default-boundp 'foo)' returns `nil', then
81 `(default-value 'foo)' would get an error.
83 `default-boundp' is to `default-value' as `boundp' is to
86 - Special Form: setq-default symbol value
87 This sets the default value of SYMBOL to VALUE. It does not
88 evaluate SYMBOL, but does evaluate VALUE. The value of the
89 `setq-default' form is VALUE.
91 If a SYMBOL is not buffer-local for the current buffer, and is not
92 marked automatically buffer-local, `setq-default' has the same
93 effect as `setq'. If SYMBOL is buffer-local for the current
94 buffer, then this changes the value that other buffers will see
95 (as long as they don't have a buffer-local value), but not the
96 value that the current buffer sees.
99 (make-local-variable 'local)
101 (setq local 'value-in-foo)
103 (setq-default local 'new-default)
107 (default-value 'local)
110 ;; In (the new) buffer `bar':
113 (default-value 'local)
115 (setq local 'another-default)
117 (default-value 'local)
120 ;; Back in buffer `foo':
123 (default-value 'local)
126 - Function: set-default symbol value
127 This function is like `setq-default', except that SYMBOL is
130 (set-default (car '(a b c)) 23)
136 File: lispref.info, Node: Variable Aliases, Prev: Buffer-Local Variables, Up: Variables
141 You can define a variable as an "alias" for another. Any time you
142 reference the former variable, the current value of the latter is
143 returned. Any time you change the value of the former variable, the
144 value of the latter is actually changed. This is useful in cases where
145 you want to rename a variable but still make old code work (*note
148 - Function: defvaralias variable alias
149 This function defines VARIABLE as an alias for ALIAS.
150 Thenceforth, any operations performed on VARIABLE will actually be
151 performed on ALIAS. Both VARIABLE and ALIAS should be symbols.
152 If ALIAS is `nil', remove any aliases for VARIABLE. ALIAS can
153 itself be aliased, and the chain of variable aliases will be
154 followed appropriately. If VARIABLE already has a value, this
155 value will be shadowed until the alias is removed, at which point
156 it will be restored. Currently VARIABLE cannot be a built-in
157 variable, a variable that has a buffer-local value in any buffer,
158 or the symbols `nil' or `t'.
160 - Function: variable-alias variable
161 If VARIABLE is aliased to another variable, this function returns
162 that variable. VARIABLE should be a symbol. If VARIABLE is not
163 aliased, this function returns `nil'.
165 - Function: indirect-variable object
166 This function returns the variable at the end of OBJECT's
167 variable-alias chain. If OBJECT is a symbol, follow all variable
168 aliases and return the final (non-aliased) symbol. If OBJECT is
169 not a symbol, just return it. Signal a
170 `cyclic-variable-indirection' error if there is a loop in the
171 variable chain of symbols.
174 File: lispref.info, Node: Functions, Next: Macros, Prev: Variables, Up: Top
179 A Lisp program is composed mainly of Lisp functions. This chapter
180 explains what functions are, how they accept arguments, and how to
185 * What Is a Function:: Lisp functions vs. primitives; terminology.
186 * Lambda Expressions:: How functions are expressed as Lisp objects.
187 * Function Names:: A symbol can serve as the name of a function.
188 * Defining Functions:: Lisp expressions for defining functions.
189 * Calling Functions:: How to use an existing function.
190 * Mapping Functions:: Applying a function to each element of a list, etc.
191 * Anonymous Functions:: Lambda expressions are functions with no names.
192 * Function Cells:: Accessing or setting the function definition
194 * Inline Functions:: Defining functions that the compiler will open code.
195 * Related Topics:: Cross-references to specific Lisp primitives
196 that have a special bearing on how functions work.
199 File: lispref.info, Node: What Is a Function, Next: Lambda Expressions, Up: Functions
204 In a general sense, a function is a rule for carrying on a
205 computation given several values called "arguments". The result of the
206 computation is called the value of the function. The computation can
207 also have side effects: lasting changes in the values of variables or
208 the contents of data structures.
210 Here are important terms for functions in XEmacs Lisp and for other
211 function-like objects.
214 In XEmacs Lisp, a "function" is anything that can be applied to
215 arguments in a Lisp program. In some cases, we use it more
216 specifically to mean a function written in Lisp. Special forms and
217 macros are not functions.
220 A "primitive" is a function callable from Lisp that is written in
221 C, such as `car' or `append'. These functions are also called
222 "built-in" functions or "subrs". (Special forms are also
223 considered primitives.)
225 Usually the reason that a function is a primitives is because it is
226 fundamental, because it provides a low-level interface to operating
227 system services, or because it needs to run fast. Primitives can
228 be modified or added only by changing the C sources and
229 recompiling the editor. See *Note Writing Lisp Primitives:
230 (internals)Writing Lisp Primitives.
233 A "lambda expression" is a function written in Lisp. These are
234 described in the following section. *Note Lambda Expressions::.
237 A "special form" is a primitive that is like a function but does
238 not evaluate all of its arguments in the usual way. It may
239 evaluate only some of the arguments, or may evaluate them in an
240 unusual order, or several times. Many special forms are described
241 in *Note Control Structures::.
244 A "macro" is a construct defined in Lisp by the programmer. It
245 differs from a function in that it translates a Lisp expression
246 that you write into an equivalent expression to be evaluated
247 instead of the original expression. Macros enable Lisp
248 programmers to do the sorts of things that special forms can do.
249 *Note Macros::, for how to define and use macros.
252 A "command" is an object that `command-execute' can invoke; it is
253 a possible definition for a key sequence. Some functions are
254 commands; a function written in Lisp is a command if it contains an
255 interactive declaration (*note Defining Commands::). Such a
256 function can be called from Lisp expressions like other functions;
257 in this case, the fact that the function is a command makes no
260 Keyboard macros (strings and vectors) are commands also, even
261 though they are not functions. A symbol is a command if its
262 function definition is a command; such symbols can be invoked with
263 `M-x'. The symbol is a function as well if the definition is a
264 function. *Note Command Overview::.
267 A "keystroke command" is a command that is bound to a key sequence
268 (typically one to three keystrokes). The distinction is made here
269 merely to avoid confusion with the meaning of "command" in
270 non-Emacs editors; for Lisp programs, the distinction is normally
274 A "compiled function" is a function that has been compiled by the
275 byte compiler. *Note Compiled-Function Type::.
277 - Function: subrp object
278 This function returns `t' if OBJECT is a built-in function (i.e.,
281 (subrp 'message) ; `message' is a symbol,
282 => nil ; not a subr object.
283 (subrp (symbol-function 'message))
286 - Function: compiled-function-p object
287 This function returns `t' if OBJECT is a compiled function. For
290 (compiled-function-p (symbol-function 'next-line))
294 File: lispref.info, Node: Lambda Expressions, Next: Function Names, Prev: What Is a Function, Up: Functions
299 A function written in Lisp is a list that looks like this:
301 (lambda (ARG-VARIABLES...)
302 [DOCUMENTATION-STRING]
303 [INTERACTIVE-DECLARATION]
306 Such a list is called a "lambda expression". In XEmacs Lisp, it
307 actually is valid as an expression--it evaluates to itself. In some
308 other Lisp dialects, a lambda expression is not a valid expression at
309 all. In either case, its main use is not to be evaluated as an
310 expression, but to be called as a function.
314 * Lambda Components:: The parts of a lambda expression.
315 * Simple Lambda:: A simple example.
316 * Argument List:: Details and special features of argument lists.
317 * Function Documentation:: How to put documentation in a function.
320 File: lispref.info, Node: Lambda Components, Next: Simple Lambda, Up: Lambda Expressions
322 Components of a Lambda Expression
323 ---------------------------------
325 A function written in Lisp (a "lambda expression") is a list that
328 (lambda (ARG-VARIABLES...)
329 [DOCUMENTATION-STRING]
330 [INTERACTIVE-DECLARATION]
333 The first element of a lambda expression is always the symbol
334 `lambda'. This indicates that the list represents a function. The
335 reason functions are defined to start with `lambda' is so that other
336 lists, intended for other uses, will not accidentally be valid as
339 The second element is a list of symbols-the argument variable names.
340 This is called the "lambda list". When a Lisp function is called, the
341 argument values are matched up against the variables in the lambda
342 list, which are given local bindings with the values provided. *Note
345 The documentation string is a Lisp string object placed within the
346 function definition to describe the function for the XEmacs help
347 facilities. *Note Function Documentation::.
349 The interactive declaration is a list of the form `(interactive
350 CODE-STRING)'. This declares how to provide arguments if the function
351 is used interactively. Functions with this declaration are called
352 "commands"; they can be called using `M-x' or bound to a key.
353 Functions not intended to be called in this way should not have
354 interactive declarations. *Note Defining Commands::, for how to write
355 an interactive declaration.
357 The rest of the elements are the "body" of the function: the Lisp
358 code to do the work of the function (or, as a Lisp programmer would say,
359 "a list of Lisp forms to evaluate"). The value returned by the
360 function is the value returned by the last element of the body.
363 File: lispref.info, Node: Simple Lambda, Next: Argument List, Prev: Lambda Components, Up: Lambda Expressions
365 A Simple Lambda-Expression Example
366 ----------------------------------
368 Consider for example the following function:
370 (lambda (a b c) (+ a b c))
372 We can call this function by writing it as the CAR of an expression,
375 ((lambda (a b c) (+ a b c))
378 This call evaluates the body of the lambda expression with the variable
379 `a' bound to 1, `b' bound to 2, and `c' bound to 3. Evaluation of the
380 body adds these three numbers, producing the result 6; therefore, this
381 call to the function returns the value 6.
383 Note that the arguments can be the results of other function calls,
386 ((lambda (a b c) (+ a b c))
389 This evaluates the arguments `1', `(* 2 3)', and `(- 5 4)' from left to
390 right. Then it applies the lambda expression to the argument values 1,
391 6 and 1 to produce the value 8.
393 It is not often useful to write a lambda expression as the CAR of a
394 form in this way. You can get the same result, of making local
395 variables and giving them values, using the special form `let' (*note
396 Local Variables::). And `let' is clearer and easier to use. In
397 practice, lambda expressions are either stored as the function
398 definitions of symbols, to produce named functions, or passed as
399 arguments to other functions (*note Anonymous Functions::).
401 However, calls to explicit lambda expressions were very useful in the
402 old days of Lisp, before the special form `let' was invented. At that
403 time, they were the only way to bind and initialize local variables.
406 File: lispref.info, Node: Argument List, Next: Function Documentation, Prev: Simple Lambda, Up: Lambda Expressions
408 Advanced Features of Argument Lists
409 -----------------------------------
411 Our simple sample function, `(lambda (a b c) (+ a b c))', specifies
412 three argument variables, so it must be called with three arguments: if
413 you try to call it with only two arguments or four arguments, you get a
414 `wrong-number-of-arguments' error.
416 It is often convenient to write a function that allows certain
417 arguments to be omitted. For example, the function `substring' accepts
418 three arguments--a string, the start index and the end index--but the
419 third argument defaults to the LENGTH of the string if you omit it. It
420 is also convenient for certain functions to accept an indefinite number
421 of arguments, as the functions `list' and `+' do.
423 To specify optional arguments that may be omitted when a function is
424 called, simply include the keyword `&optional' before the optional
425 arguments. To specify a list of zero or more extra arguments, include
426 the keyword `&rest' before one final argument.
428 Thus, the complete syntax for an argument list is as follows:
431 [&optional OPTIONAL-VARS...]
434 The square brackets indicate that the `&optional' and `&rest' clauses,
435 and the variables that follow them, are optional.
437 A call to the function requires one actual argument for each of the
438 REQUIRED-VARS. There may be actual arguments for zero or more of the
439 OPTIONAL-VARS, and there cannot be any actual arguments beyond that
440 unless the lambda list uses `&rest'. In that case, there may be any
441 number of extra actual arguments.
443 If actual arguments for the optional and rest variables are omitted,
444 then they always default to `nil'. There is no way for the function to
445 distinguish between an explicit argument of `nil' and an omitted
446 argument. However, the body of the function is free to consider `nil'
447 an abbreviation for some other meaningful value. This is what
448 `substring' does; `nil' as the third argument to `substring' means to
449 use the length of the string supplied.
451 Common Lisp note: Common Lisp allows the function to specify what
452 default value to use when an optional argument is omitted; XEmacs
453 Lisp always uses `nil'.
455 For example, an argument list that looks like this:
457 (a b &optional c d &rest e)
459 binds `a' and `b' to the first two actual arguments, which are
460 required. If one or two more arguments are provided, `c' and `d' are
461 bound to them respectively; any arguments after the first four are
462 collected into a list and `e' is bound to that list. If there are only
463 two arguments, `c' is `nil'; if two or three arguments, `d' is `nil';
464 if four arguments or fewer, `e' is `nil'.
466 There is no way to have required arguments following optional
467 ones--it would not make sense. To see why this must be so, suppose
468 that `c' in the example were optional and `d' were required. Suppose
469 three actual arguments are given; which variable would the third
470 argument be for? Similarly, it makes no sense to have any more
471 arguments (either required or optional) after a `&rest' argument.
473 Here are some examples of argument lists and proper calls:
475 ((lambda (n) (1+ n)) ; One required:
476 1) ; requires exactly one argument.
478 ((lambda (n &optional n1) ; One required and one optional:
479 (if n1 (+ n n1) (1+ n))) ; 1 or 2 arguments.
482 ((lambda (n &rest ns) ; One required and one rest:
483 (+ n (apply '+ ns))) ; 1 or more arguments.
488 File: lispref.info, Node: Function Documentation, Prev: Argument List, Up: Lambda Expressions
490 Documentation Strings of Functions
491 ----------------------------------
493 A lambda expression may optionally have a "documentation string" just
494 after the lambda list. This string does not affect execution of the
495 function; it is a kind of comment, but a systematized comment which
496 actually appears inside the Lisp world and can be used by the XEmacs
497 help facilities. *Note Documentation::, for how the
498 DOCUMENTATION-STRING is accessed.
500 It is a good idea to provide documentation strings for all the
501 functions in your program, even those that are only called from within
502 your program. Documentation strings are like comments, except that they
503 are easier to access.
505 The first line of the documentation string should stand on its own,
506 because `apropos' displays just this first line. It should consist of
507 one or two complete sentences that summarize the function's purpose.
509 The start of the documentation string is usually indented in the
510 source file, but since these spaces come before the starting
511 double-quote, they are not part of the string. Some people make a
512 practice of indenting any additional lines of the string so that the
513 text lines up in the program source. _This is a mistake._ The
514 indentation of the following lines is inside the string; what looks
515 nice in the source code will look ugly when displayed by the help
518 You may wonder how the documentation string could be optional, since
519 there are required components of the function that follow it (the body).
520 Since evaluation of a string returns that string, without any side
521 effects, it has no effect if it is not the last form in the body.
522 Thus, in practice, there is no confusion between the first form of the
523 body and the documentation string; if the only body form is a string
524 then it serves both as the return value and as the documentation.
527 File: lispref.info, Node: Function Names, Next: Defining Functions, Prev: Lambda Expressions, Up: Functions
532 In most computer languages, every function has a name; the idea of a
533 function without a name is nonsensical. In Lisp, a function in the
534 strictest sense has no name. It is simply a list whose first element is
535 `lambda', or a primitive subr-object.
537 However, a symbol can serve as the name of a function. This happens
538 when you put the function in the symbol's "function cell" (*note Symbol
539 Components::). Then the symbol itself becomes a valid, callable
540 function, equivalent to the list or subr-object that its function cell
541 refers to. The contents of the function cell are also called the
542 symbol's "function definition". The procedure of using a symbol's
543 function definition in place of the symbol is called "symbol function
544 indirection"; see *Note Function Indirection::.
546 In practice, nearly all functions are given names in this way and
547 referred to through their names. For example, the symbol `car' works
548 as a function and does what it does because the primitive subr-object
549 `#<subr car>' is stored in its function cell.
551 We give functions names because it is convenient to refer to them by
552 their names in Lisp expressions. For primitive subr-objects such as
553 `#<subr car>', names are the only way you can refer to them: there is
554 no read syntax for such objects. For functions written in Lisp, the
555 name is more convenient to use in a call than an explicit lambda
556 expression. Also, a function with a name can refer to itself--it can
557 be recursive. Writing the function's name in its own definition is much
558 more convenient than making the function definition point to itself
559 (something that is not impossible but that has various disadvantages in
562 We often identify functions with the symbols used to name them. For
563 example, we often speak of "the function `car'", not distinguishing
564 between the symbol `car' and the primitive subr-object that is its
565 function definition. For most purposes, there is no need to
568 Even so, keep in mind that a function need not have a unique name.
569 While a given function object _usually_ appears in the function cell of
570 only one symbol, this is just a matter of convenience. It is easy to
571 store it in several symbols using `fset'; then each of the symbols is
572 equally well a name for the same function.
574 A symbol used as a function name may also be used as a variable;
575 these two uses of a symbol are independent and do not conflict.
578 File: lispref.info, Node: Defining Functions, Next: Calling Functions, Prev: Function Names, Up: Functions
583 We usually give a name to a function when it is first created. This
584 is called "defining a function", and it is done with the `defun'
587 - Special Form: defun name argument-list body-forms
588 `defun' is the usual way to define new Lisp functions. It defines
589 the symbol NAME as a function that looks like this:
591 (lambda ARGUMENT-LIST . BODY-FORMS)
593 `defun' stores this lambda expression in the function cell of
594 NAME. It returns the value NAME, but usually we ignore this value.
596 As described previously (*note Lambda Expressions::),
597 ARGUMENT-LIST is a list of argument names and may include the
598 keywords `&optional' and `&rest'. Also, the first two forms in
599 BODY-FORMS may be a documentation string and an interactive
602 There is no conflict if the same symbol NAME is also used as a
603 variable, since the symbol's value cell is independent of the
604 function cell. *Note Symbol Components::.
606 Here are some examples:
613 (defun bar (a &optional b &rest c)
621 error--> Wrong number of arguments.
623 (defun capitalize-backwards ()
624 "Upcase the last letter of a word."
630 => capitalize-backwards
632 Be careful not to redefine existing functions unintentionally.
633 `defun' redefines even primitive functions such as `car' without
634 any hesitation or notification. Redefining a function already
635 defined is often done deliberately, and there is no way to
636 distinguish deliberate redefinition from unintentional
639 - Function: define-function name definition
640 - Function: defalias name definition
641 These equivalent special forms define the symbol NAME as a
642 function, with definition DEFINITION (which can be any valid Lisp
645 The proper place to use `define-function' or `defalias' is where a
646 specific function name is being defined--especially where that
647 name appears explicitly in the source file being loaded. This is
648 because `define-function' and `defalias' record which file defined
649 the function, just like `defun'. (*note Unloading::).
651 By contrast, in programs that manipulate function definitions for
652 other purposes, it is better to use `fset', which does not keep
655 See also `defsubst', which defines a function like `defun' and tells
656 the Lisp compiler to open-code it. *Note Inline Functions::.
659 File: lispref.info, Node: Calling Functions, Next: Mapping Functions, Prev: Defining Functions, Up: Functions
664 Defining functions is only half the battle. Functions don't do
665 anything until you "call" them, i.e., tell them to run. Calling a
666 function is also known as "invocation".
668 The most common way of invoking a function is by evaluating a list.
669 For example, evaluating the list `(concat "a" "b")' calls the function
670 `concat' with arguments `"a"' and `"b"'. *Note Evaluation::, for a
671 description of evaluation.
673 When you write a list as an expression in your program, the function
674 name is part of the program. This means that you choose which function
675 to call, and how many arguments to give it, when you write the program.
676 Usually that's just what you want. Occasionally you need to decide at
677 run time which function to call. To do that, use the functions
678 `funcall' and `apply'.
680 - Function: funcall function &rest arguments
681 `funcall' calls FUNCTION with ARGUMENTS, and returns whatever
684 Since `funcall' is a function, all of its arguments, including
685 FUNCTION, are evaluated before `funcall' is called. This means
686 that you can use any expression to obtain the function to be
687 called. It also means that `funcall' does not see the expressions
688 you write for the ARGUMENTS, only their values. These values are
689 _not_ evaluated a second time in the act of calling FUNCTION;
690 `funcall' enters the normal procedure for calling a function at the
691 place where the arguments have already been evaluated.
693 The argument FUNCTION must be either a Lisp function or a
694 primitive function. Special forms and macros are not allowed,
695 because they make sense only when given the "unevaluated" argument
696 expressions. `funcall' cannot provide these because, as we saw
697 above, it never knows them in the first place.
703 (funcall f 'x 'y '(z))
706 error--> Invalid function: #<subr and>
708 Compare these example with the examples of `apply'.
710 - Function: apply function &rest arguments
711 `apply' calls FUNCTION with ARGUMENTS, just like `funcall' but
712 with one difference: the last of ARGUMENTS is a list of arguments
713 to give to FUNCTION, rather than a single argument. We also say
714 that `apply' "spreads" this list so that each individual element
717 `apply' returns the result of calling FUNCTION. As with
718 `funcall', FUNCTION must either be a Lisp function or a primitive
719 function; special forms and macros do not make sense in `apply'.
724 error--> Wrong type argument: listp, z
725 (apply '+ 1 2 '(3 4))
727 (apply '+ '(1 2 3 4))
730 (apply 'append '((a b c) nil (x y z) nil))
733 For an interesting example of using `apply', see the description of
734 `mapcar', in *Note Mapping Functions::.
736 It is common for Lisp functions to accept functions as arguments or
737 find them in data structures (especially in hook variables and property
738 lists) and call them using `funcall' or `apply'. Functions that accept
739 function arguments are often called "functionals".
741 Sometimes, when you call a functional, it is useful to supply a no-op
742 function as the argument. Here are two different kinds of no-op
745 - Function: identity arg
746 This function returns ARG and has no side effects.
748 - Function: ignore &rest args
749 This function ignores any arguments and returns `nil'.
752 File: lispref.info, Node: Mapping Functions, Next: Anonymous Functions, Prev: Calling Functions, Up: Functions
757 A "mapping function" applies a given function to each element of a
758 list or other collection. XEmacs Lisp has several such functions;
759 `mapcar' and `mapconcat', which scan a list, are described here.
760 *Note Creating Symbols::, for the function `mapatoms' which maps over
761 the symbols in an obarray.
763 Mapping functions should never modify the sequence being mapped over.
764 The results are unpredictable.
766 - Function: mapcar function sequence
767 `mapcar' applies FUNCTION to each element of SEQUENCE in turn, and
768 returns a list of the results.
770 The argument SEQUENCE can be any kind of sequence; that is, a
771 list, a vector, a bit vector, or a string. The result is always a
772 list. The length of the result is the same as the length of
777 (mapcar 'car '((a b) (c d) (e f)))
781 (mapcar 'char-to-string "abc")
784 ;; Call each function in `my-hooks'.
785 (mapcar 'funcall my-hooks)
787 (defun mapcar* (f &rest args)
788 "Apply FUNCTION to successive cars of all ARGS.
789 Return the list of results."
790 ;; If no list is exhausted,
791 (if (not (memq 'nil args))
792 ;; apply function to CARs.
793 (cons (apply f (mapcar 'car args))
795 ;; Recurse for rest of elements.
796 (mapcar 'cdr args)))))
798 (mapcar* 'cons '(a b c) '(1 2 3 4))
799 => ((a . 1) (b . 2) (c . 3))
801 - Function: mapconcat function sequence separator
802 `mapconcat' applies FUNCTION to each element of SEQUENCE: the
803 results, which must be strings, are concatenated. Between each
804 pair of result strings, `mapconcat' inserts the string SEPARATOR.
805 Usually SEPARATOR contains a space or comma or other suitable
808 The argument FUNCTION must be a function that can take one
809 argument and return a string. The argument SEQUENCE can be any
810 kind of sequence; that is, a list, a vector, a bit vector, or a
813 (mapconcat 'symbol-name
814 '(The cat in the hat)
816 => "The cat in the hat"
818 (mapconcat (function (lambda (x) (format "%c" (1+ x))))
824 File: lispref.info, Node: Anonymous Functions, Next: Function Cells, Prev: Mapping Functions, Up: Functions
829 In Lisp, a function is a list that starts with `lambda', a byte-code
830 function compiled from such a list, or alternatively a primitive
831 subr-object; names are "extra". Although usually functions are defined
832 with `defun' and given names at the same time, it is occasionally more
833 concise to use an explicit lambda expression--an anonymous function.
834 Such a list is valid wherever a function name is.
836 Any method of creating such a list makes a valid function. Even
839 (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
840 => (lambda (x) (+ 12 x))
842 This computes a list that looks like `(lambda (x) (+ 12 x))' and makes
843 it the value (_not_ the function definition!) of `silly'.
845 Here is how we might call this function:
850 (It does _not_ work to write `(silly 1)', because this function is not
851 the _function definition_ of `silly'. We have not given `silly' any
852 function definition, just a value as a variable.)
854 Most of the time, anonymous functions are constants that appear in
855 your program. For example, you might want to pass one as an argument
856 to the function `mapcar', which applies any given function to each
857 element of a list. Here we pass an anonymous function that multiplies
860 (defun double-each (list)
861 (mapcar '(lambda (x) (* 2 x)) list))
863 (double-each '(2 11))
866 In such cases, we usually use the special form `function' instead of
867 simple quotation to quote the anonymous function.
869 - Special Form: function function-object
870 This special form returns FUNCTION-OBJECT without evaluating it.
871 In this, it is equivalent to `quote'. However, it serves as a
872 note to the XEmacs Lisp compiler that FUNCTION-OBJECT is intended
873 to be used only as a function, and therefore can safely be
874 compiled. Contrast this with `quote', in *Note Quoting::.
876 Using `function' instead of `quote' makes a difference inside a
877 function or macro that you are going to compile. For example:
879 (defun double-each (list)
880 (mapcar (function (lambda (x) (* 2 x))) list))
882 (double-each '(2 11))
885 If this definition of `double-each' is compiled, the anonymous function
886 is compiled as well. By contrast, in the previous definition where
887 ordinary `quote' is used, the argument passed to `mapcar' is the
892 The Lisp compiler cannot assume this list is a function, even though it
893 looks like one, since it does not know what `mapcar' does with the
894 list. Perhaps `mapcar' will check that the CAR of the third element is
895 the symbol `*'! The advantage of `function' is that it tells the
896 compiler to go ahead and compile the constant function.
898 We sometimes write `function' instead of `quote' when quoting the
899 name of a function, but this usage is just a sort of comment.
901 (function SYMBOL) == (quote SYMBOL) == 'SYMBOL
903 See `documentation' in *Note Accessing Documentation::, for a
904 realistic example using `function' and an anonymous function.
907 File: lispref.info, Node: Function Cells, Next: Inline Functions, Prev: Anonymous Functions, Up: Functions
909 Accessing Function Cell Contents
910 ================================
912 The "function definition" of a symbol is the object stored in the
913 function cell of the symbol. The functions described here access, test,
914 and set the function cell of symbols.
916 See also the function `indirect-function' in *Note Function
919 - Function: symbol-function symbol
920 This returns the object in the function cell of SYMBOL. If the
921 symbol's function cell is void, a `void-function' error is
924 This function does not check that the returned object is a
927 (defun bar (n) (+ n 2))
929 (symbol-function 'bar)
930 => (lambda (n) (+ n 2))
933 (symbol-function 'baz)
936 If you have never given a symbol any function definition, we say that
937 that symbol's function cell is "void". In other words, the function
938 cell does not have any Lisp object in it. If you try to call such a
939 symbol as a function, it signals a `void-function' error.
941 Note that void is not the same as `nil' or the symbol `void'. The
942 symbols `nil' and `void' are Lisp objects, and can be stored into a
943 function cell just as any other object can be (and they can be valid
944 functions if you define them in turn with `defun'). A void function
945 cell contains no object whatsoever.
947 You can test the voidness of a symbol's function definition with
948 `fboundp'. After you have given a symbol a function definition, you
949 can make it void once more using `fmakunbound'.
951 - Function: fboundp symbol
952 This function returns `t' if the symbol has an object in its
953 function cell, `nil' otherwise. It does not check that the object
954 is a legitimate function.
956 - Function: fmakunbound symbol
957 This function makes SYMBOL's function cell void, so that a
958 subsequent attempt to access this cell will cause a `void-function'
959 error. (See also `makunbound', in *Note Local Variables::.)
968 error--> Symbol's function definition is void: foo
970 - Function: fset symbol object
971 This function stores OBJECT in the function cell of SYMBOL. The
972 result is OBJECT. Normally OBJECT should be a function or the
973 name of a function, but this is not checked.
975 There are three normal uses of this function:
977 * Copying one symbol's function definition to another. (In
978 other words, making an alternate name for a function.)
980 * Giving a symbol a function definition that is not a list and
981 therefore cannot be made with `defun'. For example, you can
982 use `fset' to give a symbol `s1' a function definition which
983 is another symbol `s2'; then `s1' serves as an alias for
984 whatever definition `s2' presently has.
986 * In constructs for defining or altering functions. If `defun'
987 were not a primitive, it could be written in Lisp (as a
990 Here are examples of the first two uses:
992 ;; Give `first' the same definition `car' has.
993 (fset 'first (symbol-function 'car))
998 ;; Make the symbol `car' the function definition of `xfirst'.
1003 (symbol-function 'xfirst)
1005 (symbol-function (symbol-function 'xfirst))
1008 ;; Define a named keyboard macro.
1009 (fset 'kill-two-lines "\^u2\^k")
1012 See also the related functions `define-function' and `defalias',
1013 in *Note Defining Functions::.
1015 When writing a function that extends a previously defined function,
1016 the following idiom is sometimes used:
1018 (fset 'old-foo (symbol-function 'foo))
1020 "Just like old-foo, except more so."
1024 This does not work properly if `foo' has been defined to autoload. In
1025 such a case, when `foo' calls `old-foo', Lisp attempts to define
1026 `old-foo' by loading a file. Since this presumably defines `foo'
1027 rather than `old-foo', it does not produce the proper results. The
1028 only way to avoid this problem is to make sure the file is loaded
1029 before moving aside the old definition of `foo'.
1031 But it is unmodular and unclean, in any case, for a Lisp file to
1032 redefine a function defined elsewhere.
1035 File: lispref.info, Node: Inline Functions, Next: Related Topics, Prev: Function Cells, Up: Functions
1040 You can define an "inline function" by using `defsubst' instead of
1041 `defun'. An inline function works just like an ordinary function
1042 except for one thing: when you compile a call to the function, the
1043 function's definition is open-coded into the caller.
1045 Making a function inline makes explicit calls run faster. But it
1046 also has disadvantages. For one thing, it reduces flexibility; if you
1047 change the definition of the function, calls already inlined still use
1048 the old definition until you recompile them. Since the flexibility of
1049 redefining functions is an important feature of XEmacs, you should not
1050 make a function inline unless its speed is really crucial.
1052 Another disadvantage is that making a large function inline can
1053 increase the size of compiled code both in files and in memory. Since
1054 the speed advantage of inline functions is greatest for small
1055 functions, you generally should not make large functions inline.
1057 It's possible to define a macro to expand into the same code that an
1058 inline function would execute. But the macro would have a limitation:
1059 you can use it only explicitly--a macro cannot be called with `apply',
1060 `mapcar' and so on. Also, it takes some work to convert an ordinary
1061 function into a macro. (*Note Macros::.) To convert it into an inline
1062 function is very easy; simply replace `defun' with `defsubst'. Since
1063 each argument of an inline function is evaluated exactly once, you
1064 needn't worry about how many times the body uses the arguments, as you
1065 do for macros. (*Note Argument Evaluation::.)
1067 Inline functions can be used and open-coded later on in the same
1068 file, following the definition, just like macros.
1071 File: lispref.info, Node: Related Topics, Prev: Inline Functions, Up: Functions
1073 Other Topics Related to Functions
1074 =================================
1076 Here is a table of several functions that do things related to
1077 function calling and function definitions. They are documented
1078 elsewhere, but we provide cross references here.
1081 See *Note Calling Functions::.
1084 See *Note Autoload::.
1086 `call-interactively'
1087 See *Note Interactive Call::.
1090 See *Note Interactive Call::.
1093 See *Note Accessing Documentation::.
1099 See *Note Calling Functions::.
1102 See *Note Calling Functions::.
1105 See *Note Function Indirection::.
1108 See *Note Using Interactive::.
1111 See *Note Interactive Call::.
1114 See *Note Creating Symbols::.
1117 See *Note Mapping Functions::.
1120 See *Note Mapping Functions::.
1123 See *Note Key Lookup::.
1126 File: lispref.info, Node: Macros, Next: Loading, Prev: Functions, Up: Top
1131 "Macros" enable you to define new control constructs and other
1132 language features. A macro is defined much like a function, but instead
1133 of telling how to compute a value, it tells how to compute another Lisp
1134 expression which will in turn compute the value. We call this
1135 expression the "expansion" of the macro.
1137 Macros can do this because they operate on the unevaluated
1138 expressions for the arguments, not on the argument values as functions
1139 do. They can therefore construct an expansion containing these
1140 argument expressions or parts of them.
1142 If you are using a macro to do something an ordinary function could
1143 do, just for the sake of speed, consider using an inline function
1144 instead. *Note Inline Functions::.
1148 * Simple Macro:: A basic example.
1149 * Expansion:: How, when and why macros are expanded.
1150 * Compiling Macros:: How macros are expanded by the compiler.
1151 * Defining Macros:: How to write a macro definition.
1152 * Backquote:: Easier construction of list structure.
1153 * Problems with Macros:: Don't evaluate the macro arguments too many times.
1154 Don't hide the user's variables.
1157 File: lispref.info, Node: Simple Macro, Next: Expansion, Up: Macros
1159 A Simple Example of a Macro
1160 ===========================
1162 Suppose we would like to define a Lisp construct to increment a
1163 variable value, much like the `++' operator in C. We would like to
1164 write `(inc x)' and have the effect of `(setq x (1+ x))'. Here's a
1165 macro definition that does the job:
1168 (list 'setq var (list '1+ var)))
1170 When this is called with `(inc x)', the argument `var' has the value
1171 `x'--_not_ the _value_ of `x'. The body of the macro uses this to
1172 construct the expansion, which is `(setq x (1+ x))'. Once the macro
1173 definition returns this expansion, Lisp proceeds to evaluate it, thus
1177 File: lispref.info, Node: Expansion, Next: Compiling Macros, Prev: Simple Macro, Up: Macros
1179 Expansion of a Macro Call
1180 =========================
1182 A macro call looks just like a function call in that it is a list
1183 which starts with the name of the macro. The rest of the elements of
1184 the list are the arguments of the macro.
1186 Evaluation of the macro call begins like evaluation of a function
1187 call except for one crucial difference: the macro arguments are the
1188 actual expressions appearing in the macro call. They are not evaluated
1189 before they are given to the macro definition. By contrast, the
1190 arguments of a function are results of evaluating the elements of the
1193 Having obtained the arguments, Lisp invokes the macro definition just
1194 as a function is invoked. The argument variables of the macro are bound
1195 to the argument values from the macro call, or to a list of them in the
1196 case of a `&rest' argument. And the macro body executes and returns
1197 its value just as a function body does.
1199 The second crucial difference between macros and functions is that
1200 the value returned by the macro body is not the value of the macro call.
1201 Instead, it is an alternate expression for computing that value, also
1202 known as the "expansion" of the macro. The Lisp interpreter proceeds
1203 to evaluate the expansion as soon as it comes back from the macro.
1205 Since the expansion is evaluated in the normal manner, it may contain
1206 calls to other macros. It may even be a call to the same macro, though
1209 You can see the expansion of a given macro call by calling
1212 - Function: macroexpand form &optional environment
1213 This function expands FORM, if it is a macro call. If the result
1214 is another macro call, it is expanded in turn, until something
1215 which is not a macro call results. That is the value returned by
1216 `macroexpand'. If FORM is not a macro call to begin with, it is
1219 Note that `macroexpand' does not look at the subexpressions of
1220 FORM (although some macro definitions may do so). Even if they
1221 are macro calls themselves, `macroexpand' does not expand them.
1223 The function `macroexpand' does not expand calls to inline
1224 functions. Normally there is no need for that, since a call to an
1225 inline function is no harder to understand than a call to an
1228 If ENVIRONMENT is provided, it specifies an alist of macro
1229 definitions that shadow the currently defined macros. Byte
1230 compilation uses this feature.
1233 (list 'setq var (list '1+ var)))
1236 (macroexpand '(inc r))
1239 (defmacro inc2 (var1 var2)
1240 (list 'progn (list 'inc var1) (list 'inc var2)))
1243 (macroexpand '(inc2 r s))
1244 => (progn (inc r) (inc s)) ; `inc' not expanded here.