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: Intro to Buffer-Local, Next: Creating Buffer-Local, Up: Buffer-Local Variables
55 Introduction to Buffer-Local Variables
56 --------------------------------------
58 A buffer-local variable has a buffer-local binding associated with a
59 particular buffer. The binding is in effect when that buffer is
60 current; otherwise, it is not in effect. If you set the variable while
61 a buffer-local binding is in effect, the new value goes in that binding,
62 so the global binding is unchanged; this means that the change is
63 visible in that buffer alone.
65 A variable may have buffer-local bindings in some buffers but not in
66 others. The global binding is shared by all the buffers that don't have
67 their own bindings. Thus, if you set the variable in a buffer that does
68 not have a buffer-local binding for it, the new value is visible in all
69 buffers except those with buffer-local bindings. (Here we are assuming
70 that there are no `let'-style local bindings to complicate the issue.)
72 The most common use of buffer-local bindings is for major modes to
73 change variables that control the behavior of commands. For example, C
74 mode and Lisp mode both set the variable `paragraph-start' to specify
75 that only blank lines separate paragraphs. They do this by making the
76 variable buffer-local in the buffer that is being put into C mode or
77 Lisp mode, and then setting it to the new value for that mode.
79 The usual way to make a buffer-local binding is with
80 `make-local-variable', which is what major mode commands use. This
81 affects just the current buffer; all other buffers (including those yet
82 to be created) continue to share the global value.
84 A more powerful operation is to mark the variable as "automatically
85 buffer-local" by calling `make-variable-buffer-local'. You can think
86 of this as making the variable local in all buffers, even those yet to
87 be created. More precisely, the effect is that setting the variable
88 automatically makes the variable local to the current buffer if it is
89 not already so. All buffers start out by sharing the global value of
90 the variable as usual, but any `setq' creates a buffer-local binding
91 for the current buffer. The new value is stored in the buffer-local
92 binding, leaving the (default) global binding untouched. The global
93 value can no longer be changed with `setq'; you need to use
94 `setq-default' to do that.
96 Local variables in a file you edit are also represented by
97 buffer-local bindings for the buffer that holds the file within XEmacs.
98 *Note Auto Major Mode::.
101 File: lispref.info, Node: Creating Buffer-Local, Next: Default Value, Prev: Intro to Buffer-Local, Up: Buffer-Local Variables
103 Creating and Deleting Buffer-Local Bindings
104 -------------------------------------------
106 - Command: make-local-variable variable
107 This function creates a buffer-local binding in the current buffer
108 for VARIABLE (a symbol). Other buffers are not affected. The
109 value returned is VARIABLE.
111 The buffer-local value of VARIABLE starts out as the same value
112 VARIABLE previously had. If VARIABLE was void, it remains void.
115 (setq foo 5) ; Affects all buffers.
117 (make-local-variable 'foo) ; Now it is local in `b1'.
119 foo ; That did not change
121 (setq foo 6) ; Change the value
126 ;; In buffer `b2', the value hasn't changed.
132 Making a variable buffer-local within a `let'-binding for that
133 variable does not work. This is because `let' does not distinguish
134 between different kinds of bindings; it knows only which variable
135 the binding was made for.
137 *Please note:* do not use `make-local-variable' for a hook
138 variable. Instead, use `make-local-hook'. *Note Hooks::.
140 - Command: make-variable-buffer-local variable
141 This function marks VARIABLE (a symbol) automatically
142 buffer-local, so that any subsequent attempt to set it will make it
143 local to the current buffer at the time.
145 The value returned is VARIABLE.
147 - Function: local-variable-p variable buffer &optional after-set
148 This returns `t' if VARIABLE is buffer-local in buffer BUFFER;
151 If optional third arg AFTER-SET is non-`nil', return `t' if SYMBOL
152 would be buffer-local after it is set, regardless of whether it is
155 A `nil' value for BUFFER is _not_ the same as `(current-buffer)',
156 but means "no buffer". Specifically:
158 If BUFFER is `nil' and AFTER-SET is `nil', a return value of `t'
159 indicates that the variable is one of the special built-in
160 variables that is always buffer-local. (This includes
161 `buffer-file-name', `buffer-read-only', `buffer-undo-list', and
164 If BUFFER is `nil' and AFTER-SET is `t', a return value of `t'
165 indicates that the variable has had `make-variable-buffer-local'
168 - Function: buffer-local-variables &optional buffer
169 This function returns a list describing the buffer-local variables
170 in buffer BUFFER. It returns an association list (*note
171 Association Lists::) in which each association contains one
172 buffer-local variable and its value. When a buffer-local variable
173 is void in BUFFER, then it appears directly in the resulting list.
174 If BUFFER is omitted, the current buffer is used.
176 (make-local-variable 'foobar)
178 (make-local-variable 'bind-me)
180 (setq lcl (buffer-local-variables))
181 ;; First, built-in variables local in all buffers:
182 => ((mark-active . nil)
183 (buffer-undo-list nil)
184 (mode-name . "Fundamental")
186 ;; Next, non-built-in local variables.
187 ;; This one is local and void:
189 ;; This one is local and nonvoid:
192 Note that storing new values into the CDRs of cons cells in this
193 list does _not_ change the local values of the variables.
195 - Command: kill-local-variable variable
196 This function deletes the buffer-local binding (if any) for
197 VARIABLE (a symbol) in the current buffer. As a result, the
198 global (default) binding of VARIABLE becomes visible in this
199 buffer. Usually this results in a change in the value of
200 VARIABLE, since the global value is usually different from the
201 buffer-local value just eliminated.
203 If you kill the local binding of a variable that automatically
204 becomes local when set, this makes the global value visible in the
205 current buffer. However, if you set the variable again, that will
206 once again create a local binding for it.
208 `kill-local-variable' returns VARIABLE.
210 This function is a command because it is sometimes useful to kill
211 one buffer-local variable interactively, just as it is useful to
212 create buffer-local variables interactively.
214 - Function: kill-all-local-variables
215 This function eliminates all the buffer-local variable bindings of
216 the current buffer except for variables marked as "permanent". As
217 a result, the buffer will see the default values of most variables.
219 This function also resets certain other information pertaining to
220 the buffer: it sets the local keymap to `nil', the syntax table to
221 the value of `standard-syntax-table', and the abbrev table to the
222 value of `fundamental-mode-abbrev-table'.
224 Every major mode command begins by calling this function, which
225 has the effect of switching to Fundamental mode and erasing most
226 of the effects of the previous major mode. To ensure that this
227 does its job, the variables that major modes set should not be
230 `kill-all-local-variables' returns `nil'.
232 A local variable is "permanent" if the variable name (a symbol) has a
233 `permanent-local' property that is non-`nil'. Permanent locals are
234 appropriate for data pertaining to where the file came from or how to
235 save it, rather than with how to edit the contents.
238 File: lispref.info, Node: Default Value, Prev: Creating Buffer-Local, Up: Buffer-Local Variables
240 The Default Value of a Buffer-Local Variable
241 --------------------------------------------
243 The global value of a variable with buffer-local bindings is also
244 called the "default" value, because it is the value that is in effect
245 except when specifically overridden.
247 The functions `default-value' and `setq-default' access and change a
248 variable's default value regardless of whether the current buffer has a
249 buffer-local binding. For example, you could use `setq-default' to
250 change the default setting of `paragraph-start' for most buffers; and
251 this would work even when you are in a C or Lisp mode buffer that has a
252 buffer-local value for this variable.
254 The special forms `defvar' and `defconst' also set the default value
255 (if they set the variable at all), rather than any local value.
257 - Function: default-value symbol
258 This function returns SYMBOL's default value. This is the value
259 that is seen in buffers that do not have their own values for this
260 variable. If SYMBOL is not buffer-local, this is equivalent to
261 `symbol-value' (*note Accessing Variables::).
263 - Function: default-boundp symbol
264 The function `default-boundp' tells you whether SYMBOL's default
265 value is nonvoid. If `(default-boundp 'foo)' returns `nil', then
266 `(default-value 'foo)' would get an error.
268 `default-boundp' is to `default-value' as `boundp' is to
271 - Special Form: setq-default symbol value
272 This sets the default value of SYMBOL to VALUE. It does not
273 evaluate SYMBOL, but does evaluate VALUE. The value of the
274 `setq-default' form is VALUE.
276 If a SYMBOL is not buffer-local for the current buffer, and is not
277 marked automatically buffer-local, `setq-default' has the same
278 effect as `setq'. If SYMBOL is buffer-local for the current
279 buffer, then this changes the value that other buffers will see
280 (as long as they don't have a buffer-local value), but not the
281 value that the current buffer sees.
284 (make-local-variable 'local)
286 (setq local 'value-in-foo)
288 (setq-default local 'new-default)
292 (default-value 'local)
295 ;; In (the new) buffer `bar':
298 (default-value 'local)
300 (setq local 'another-default)
302 (default-value 'local)
305 ;; Back in buffer `foo':
308 (default-value 'local)
311 - Function: set-default symbol value
312 This function is like `setq-default', except that SYMBOL is
315 (set-default (car '(a b c)) 23)
321 File: lispref.info, Node: Variable Aliases, Prev: Buffer-Local Variables, Up: Variables
326 You can define a variable as an "alias" for another. Any time you
327 reference the former variable, the current value of the latter is
328 returned. Any time you change the value of the former variable, the
329 value of the latter is actually changed. This is useful in cases where
330 you want to rename a variable but still make old code work (*note
333 - Function: defvaralias variable alias
334 This function defines VARIABLE as an alias for ALIAS.
335 Thenceforth, any operations performed on VARIABLE will actually be
336 performed on ALIAS. Both VARIABLE and ALIAS should be symbols.
337 If ALIAS is `nil', remove any aliases for VARIABLE. ALIAS can
338 itself be aliased, and the chain of variable aliases will be
339 followed appropriately. If VARIABLE already has a value, this
340 value will be shadowed until the alias is removed, at which point
341 it will be restored. Currently VARIABLE cannot be a built-in
342 variable, a variable that has a buffer-local value in any buffer,
343 or the symbols `nil' or `t'.
345 - Function: variable-alias variable &optional follow-past-lisp-magic
346 If VARIABLE is aliased to another variable, this function returns
347 that variable. VARIABLE should be a symbol. If VARIABLE is not
348 aliased, this function returns `nil'.
350 - Function: indirect-variable object &optional follow-past-lisp-magic
351 This function returns the variable at the end of OBJECT's
352 variable-alias chain. If OBJECT is a symbol, follow all variable
353 aliases and return the final (non-aliased) symbol. If OBJECT is
354 not a symbol, just return it. Signal a
355 `cyclic-variable-indirection' error if there is a loop in the
356 variable chain of symbols.
359 File: lispref.info, Node: Functions, Next: Macros, Prev: Variables, Up: Top
364 A Lisp program is composed mainly of Lisp functions. This chapter
365 explains what functions are, how they accept arguments, and how to
370 * What Is a Function:: Lisp functions vs. primitives; terminology.
371 * Lambda Expressions:: How functions are expressed as Lisp objects.
372 * Function Names:: A symbol can serve as the name of a function.
373 * Defining Functions:: Lisp expressions for defining functions.
374 * Calling Functions:: How to use an existing function.
375 * Mapping Functions:: Applying a function to each element of a list, etc.
376 * Anonymous Functions:: Lambda expressions are functions with no names.
377 * Function Cells:: Accessing or setting the function definition
379 * Inline Functions:: Defining functions that the compiler will open code.
380 * Related Topics:: Cross-references to specific Lisp primitives
381 that have a special bearing on how functions work.
384 File: lispref.info, Node: What Is a Function, Next: Lambda Expressions, Up: Functions
389 In a general sense, a function is a rule for carrying on a
390 computation given several values called "arguments". The result of the
391 computation is called the value of the function. The computation can
392 also have side effects: lasting changes in the values of variables or
393 the contents of data structures.
395 Here are important terms for functions in XEmacs Lisp and for other
396 function-like objects.
399 In XEmacs Lisp, a "function" is anything that can be applied to
400 arguments in a Lisp program. In some cases, we use it more
401 specifically to mean a function written in Lisp. Special forms and
402 macros are not functions.
405 A "primitive" is a function callable from Lisp that is written in
406 C, such as `car' or `append'. These functions are also called
407 "built-in" functions or "subrs". (Special forms are also
408 considered primitives.)
410 Usually the reason that a function is a primitives is because it is
411 fundamental, because it provides a low-level interface to operating
412 system services, or because it needs to run fast. Primitives can
413 be modified or added only by changing the C sources and
414 recompiling the editor. See *Note Writing Lisp Primitives:
415 (internals)Writing Lisp Primitives.
418 A "lambda expression" is a function written in Lisp. These are
419 described in the following section. *Note Lambda Expressions::.
422 A "special form" is a primitive that is like a function but does
423 not evaluate all of its arguments in the usual way. It may
424 evaluate only some of the arguments, or may evaluate them in an
425 unusual order, or several times. Many special forms are described
426 in *Note Control Structures::.
429 A "macro" is a construct defined in Lisp by the programmer. It
430 differs from a function in that it translates a Lisp expression
431 that you write into an equivalent expression to be evaluated
432 instead of the original expression. Macros enable Lisp
433 programmers to do the sorts of things that special forms can do.
434 *Note Macros::, for how to define and use macros.
437 A "command" is an object that `command-execute' can invoke; it is
438 a possible definition for a key sequence. Some functions are
439 commands; a function written in Lisp is a command if it contains an
440 interactive declaration (*note Defining Commands::). Such a
441 function can be called from Lisp expressions like other functions;
442 in this case, the fact that the function is a command makes no
445 Keyboard macros (strings and vectors) are commands also, even
446 though they are not functions. A symbol is a command if its
447 function definition is a command; such symbols can be invoked with
448 `M-x'. The symbol is a function as well if the definition is a
449 function. *Note Command Overview::.
452 A "keystroke command" is a command that is bound to a key sequence
453 (typically one to three keystrokes). The distinction is made here
454 merely to avoid confusion with the meaning of "command" in
455 non-Emacs editors; for Lisp programs, the distinction is normally
459 A "compiled function" is a function that has been compiled by the
460 byte compiler. *Note Compiled-Function Type::.
462 - Function: subrp object
463 This function returns `t' if OBJECT is a built-in function (i.e.,
466 (subrp 'message) ; `message' is a symbol,
467 => nil ; not a subr object.
468 (subrp (symbol-function 'message))
471 - Function: compiled-function-p object
472 This function returns `t' if OBJECT is a compiled function. For
475 (compiled-function-p (symbol-function 'next-line))
479 File: lispref.info, Node: Lambda Expressions, Next: Function Names, Prev: What Is a Function, Up: Functions
484 A function written in Lisp is a list that looks like this:
486 (lambda (ARG-VARIABLES...)
487 [DOCUMENTATION-STRING]
488 [INTERACTIVE-DECLARATION]
491 Such a list is called a "lambda expression". In XEmacs Lisp, it
492 actually is valid as an expression--it evaluates to itself. In some
493 other Lisp dialects, a lambda expression is not a valid expression at
494 all. In either case, its main use is not to be evaluated as an
495 expression, but to be called as a function.
499 * Lambda Components:: The parts of a lambda expression.
500 * Simple Lambda:: A simple example.
501 * Argument List:: Details and special features of argument lists.
502 * Function Documentation:: How to put documentation in a function.
505 File: lispref.info, Node: Lambda Components, Next: Simple Lambda, Up: Lambda Expressions
507 Components of a Lambda Expression
508 ---------------------------------
510 A function written in Lisp (a "lambda expression") is a list that
513 (lambda (ARG-VARIABLES...)
514 [DOCUMENTATION-STRING]
515 [INTERACTIVE-DECLARATION]
518 The first element of a lambda expression is always the symbol
519 `lambda'. This indicates that the list represents a function. The
520 reason functions are defined to start with `lambda' is so that other
521 lists, intended for other uses, will not accidentally be valid as
524 The second element is a list of symbols-the argument variable names.
525 This is called the "lambda list". When a Lisp function is called, the
526 argument values are matched up against the variables in the lambda
527 list, which are given local bindings with the values provided. *Note
530 The documentation string is a Lisp string object placed within the
531 function definition to describe the function for the XEmacs help
532 facilities. *Note Function Documentation::.
534 The interactive declaration is a list of the form `(interactive
535 CODE-STRING)'. This declares how to provide arguments if the function
536 is used interactively. Functions with this declaration are called
537 "commands"; they can be called using `M-x' or bound to a key.
538 Functions not intended to be called in this way should not have
539 interactive declarations. *Note Defining Commands::, for how to write
540 an interactive declaration.
542 The rest of the elements are the "body" of the function: the Lisp
543 code to do the work of the function (or, as a Lisp programmer would say,
544 "a list of Lisp forms to evaluate"). The value returned by the
545 function is the value returned by the last element of the body.
548 File: lispref.info, Node: Simple Lambda, Next: Argument List, Prev: Lambda Components, Up: Lambda Expressions
550 A Simple Lambda-Expression Example
551 ----------------------------------
553 Consider for example the following function:
555 (lambda (a b c) (+ a b c))
557 We can call this function by writing it as the CAR of an expression,
560 ((lambda (a b c) (+ a b c))
563 This call evaluates the body of the lambda expression with the variable
564 `a' bound to 1, `b' bound to 2, and `c' bound to 3. Evaluation of the
565 body adds these three numbers, producing the result 6; therefore, this
566 call to the function returns the value 6.
568 Note that the arguments can be the results of other function calls,
571 ((lambda (a b c) (+ a b c))
574 This evaluates the arguments `1', `(* 2 3)', and `(- 5 4)' from left to
575 right. Then it applies the lambda expression to the argument values 1,
576 6 and 1 to produce the value 8.
578 It is not often useful to write a lambda expression as the CAR of a
579 form in this way. You can get the same result, of making local
580 variables and giving them values, using the special form `let' (*note
581 Local Variables::). And `let' is clearer and easier to use. In
582 practice, lambda expressions are either stored as the function
583 definitions of symbols, to produce named functions, or passed as
584 arguments to other functions (*note Anonymous Functions::).
586 However, calls to explicit lambda expressions were very useful in the
587 old days of Lisp, before the special form `let' was invented. At that
588 time, they were the only way to bind and initialize local variables.
591 File: lispref.info, Node: Argument List, Next: Function Documentation, Prev: Simple Lambda, Up: Lambda Expressions
593 Advanced Features of Argument Lists
594 -----------------------------------
596 Our simple sample function, `(lambda (a b c) (+ a b c))', specifies
597 three argument variables, so it must be called with three arguments: if
598 you try to call it with only two arguments or four arguments, you get a
599 `wrong-number-of-arguments' error.
601 It is often convenient to write a function that allows certain
602 arguments to be omitted. For example, the function `substring' accepts
603 three arguments--a string, the start index and the end index--but the
604 third argument defaults to the LENGTH of the string if you omit it. It
605 is also convenient for certain functions to accept an indefinite number
606 of arguments, as the functions `list' and `+' do.
608 To specify optional arguments that may be omitted when a function is
609 called, simply include the keyword `&optional' before the optional
610 arguments. To specify a list of zero or more extra arguments, include
611 the keyword `&rest' before one final argument.
613 Thus, the complete syntax for an argument list is as follows:
616 [&optional OPTIONAL-VARS...]
619 The square brackets indicate that the `&optional' and `&rest' clauses,
620 and the variables that follow them, are optional.
622 A call to the function requires one actual argument for each of the
623 REQUIRED-VARS. There may be actual arguments for zero or more of the
624 OPTIONAL-VARS, and there cannot be any actual arguments beyond that
625 unless the lambda list uses `&rest'. In that case, there may be any
626 number of extra actual arguments.
628 If actual arguments for the optional and rest variables are omitted,
629 then they always default to `nil'. There is no way for the function to
630 distinguish between an explicit argument of `nil' and an omitted
631 argument. However, the body of the function is free to consider `nil'
632 an abbreviation for some other meaningful value. This is what
633 `substring' does; `nil' as the third argument to `substring' means to
634 use the length of the string supplied.
636 Common Lisp note: Common Lisp allows the function to specify what
637 default value to use when an optional argument is omitted; XEmacs
638 Lisp always uses `nil'.
640 For example, an argument list that looks like this:
642 (a b &optional c d &rest e)
644 binds `a' and `b' to the first two actual arguments, which are
645 required. If one or two more arguments are provided, `c' and `d' are
646 bound to them respectively; any arguments after the first four are
647 collected into a list and `e' is bound to that list. If there are only
648 two arguments, `c' is `nil'; if two or three arguments, `d' is `nil';
649 if four arguments or fewer, `e' is `nil'.
651 There is no way to have required arguments following optional
652 ones--it would not make sense. To see why this must be so, suppose
653 that `c' in the example were optional and `d' were required. Suppose
654 three actual arguments are given; which variable would the third
655 argument be for? Similarly, it makes no sense to have any more
656 arguments (either required or optional) after a `&rest' argument.
658 Here are some examples of argument lists and proper calls:
660 ((lambda (n) (1+ n)) ; One required:
661 1) ; requires exactly one argument.
663 ((lambda (n &optional n1) ; One required and one optional:
664 (if n1 (+ n n1) (1+ n))) ; 1 or 2 arguments.
667 ((lambda (n &rest ns) ; One required and one rest:
668 (+ n (apply '+ ns))) ; 1 or more arguments.
673 File: lispref.info, Node: Function Documentation, Prev: Argument List, Up: Lambda Expressions
675 Documentation Strings of Functions
676 ----------------------------------
678 A lambda expression may optionally have a "documentation string" just
679 after the lambda list. This string does not affect execution of the
680 function; it is a kind of comment, but a systematized comment which
681 actually appears inside the Lisp world and can be used by the XEmacs
682 help facilities. *Note Documentation::, for how the
683 DOCUMENTATION-STRING is accessed.
685 It is a good idea to provide documentation strings for all the
686 functions in your program, even those that are only called from within
687 your program. Documentation strings are like comments, except that they
688 are easier to access.
690 The first line of the documentation string should stand on its own,
691 because `apropos' displays just this first line. It should consist of
692 one or two complete sentences that summarize the function's purpose.
694 The start of the documentation string is usually indented in the
695 source file, but since these spaces come before the starting
696 double-quote, they are not part of the string. Some people make a
697 practice of indenting any additional lines of the string so that the
698 text lines up in the program source. _This is a mistake._ The
699 indentation of the following lines is inside the string; what looks
700 nice in the source code will look ugly when displayed by the help
703 You may wonder how the documentation string could be optional, since
704 there are required components of the function that follow it (the body).
705 Since evaluation of a string returns that string, without any side
706 effects, it has no effect if it is not the last form in the body.
707 Thus, in practice, there is no confusion between the first form of the
708 body and the documentation string; if the only body form is a string
709 then it serves both as the return value and as the documentation.
712 File: lispref.info, Node: Function Names, Next: Defining Functions, Prev: Lambda Expressions, Up: Functions
717 In most computer languages, every function has a name; the idea of a
718 function without a name is nonsensical. In Lisp, a function in the
719 strictest sense has no name. It is simply a list whose first element is
720 `lambda', or a primitive subr-object.
722 However, a symbol can serve as the name of a function. This happens
723 when you put the function in the symbol's "function cell" (*note Symbol
724 Components::). Then the symbol itself becomes a valid, callable
725 function, equivalent to the list or subr-object that its function cell
726 refers to. The contents of the function cell are also called the
727 symbol's "function definition". The procedure of using a symbol's
728 function definition in place of the symbol is called "symbol function
729 indirection"; see *Note Function Indirection::.
731 In practice, nearly all functions are given names in this way and
732 referred to through their names. For example, the symbol `car' works
733 as a function and does what it does because the primitive subr-object
734 `#<subr car>' is stored in its function cell.
736 We give functions names because it is convenient to refer to them by
737 their names in Lisp expressions. For primitive subr-objects such as
738 `#<subr car>', names are the only way you can refer to them: there is
739 no read syntax for such objects. For functions written in Lisp, the
740 name is more convenient to use in a call than an explicit lambda
741 expression. Also, a function with a name can refer to itself--it can
742 be recursive. Writing the function's name in its own definition is much
743 more convenient than making the function definition point to itself
744 (something that is not impossible but that has various disadvantages in
747 We often identify functions with the symbols used to name them. For
748 example, we often speak of "the function `car'", not distinguishing
749 between the symbol `car' and the primitive subr-object that is its
750 function definition. For most purposes, there is no need to
753 Even so, keep in mind that a function need not have a unique name.
754 While a given function object _usually_ appears in the function cell of
755 only one symbol, this is just a matter of convenience. It is easy to
756 store it in several symbols using `fset'; then each of the symbols is
757 equally well a name for the same function.
759 A symbol used as a function name may also be used as a variable;
760 these two uses of a symbol are independent and do not conflict.
763 File: lispref.info, Node: Defining Functions, Next: Calling Functions, Prev: Function Names, Up: Functions
768 We usually give a name to a function when it is first created. This
769 is called "defining a function", and it is done with the `defun'
772 - Special Form: defun name argument-list body-forms
773 `defun' is the usual way to define new Lisp functions. It defines
774 the symbol NAME as a function that looks like this:
776 (lambda ARGUMENT-LIST . BODY-FORMS)
778 `defun' stores this lambda expression in the function cell of
779 NAME. It returns the value NAME, but usually we ignore this value.
781 As described previously (*note Lambda Expressions::),
782 ARGUMENT-LIST is a list of argument names and may include the
783 keywords `&optional' and `&rest'. Also, the first two forms in
784 BODY-FORMS may be a documentation string and an interactive
787 There is no conflict if the same symbol NAME is also used as a
788 variable, since the symbol's value cell is independent of the
789 function cell. *Note Symbol Components::.
791 Here are some examples:
798 (defun bar (a &optional b &rest c)
806 error--> Wrong number of arguments.
808 (defun capitalize-backwards ()
809 "Upcase the last letter of a word."
815 => capitalize-backwards
817 Be careful not to redefine existing functions unintentionally.
818 `defun' redefines even primitive functions such as `car' without
819 any hesitation or notification. Redefining a function already
820 defined is often done deliberately, and there is no way to
821 distinguish deliberate redefinition from unintentional
824 - Function: define-function name definition
825 - Function: defalias name definition
826 These equivalent special forms define the symbol NAME as a
827 function, with definition DEFINITION (which can be any valid Lisp
830 The proper place to use `define-function' or `defalias' is where a
831 specific function name is being defined--especially where that
832 name appears explicitly in the source file being loaded. This is
833 because `define-function' and `defalias' record which file defined
834 the function, just like `defun'. (*note Unloading::).
836 By contrast, in programs that manipulate function definitions for
837 other purposes, it is better to use `fset', which does not keep
840 See also `defsubst', which defines a function like `defun' and tells
841 the Lisp compiler to open-code it. *Note Inline Functions::.
844 File: lispref.info, Node: Calling Functions, Next: Mapping Functions, Prev: Defining Functions, Up: Functions
849 Defining functions is only half the battle. Functions don't do
850 anything until you "call" them, i.e., tell them to run. Calling a
851 function is also known as "invocation".
853 The most common way of invoking a function is by evaluating a list.
854 For example, evaluating the list `(concat "a" "b")' calls the function
855 `concat' with arguments `"a"' and `"b"'. *Note Evaluation::, for a
856 description of evaluation.
858 When you write a list as an expression in your program, the function
859 name is part of the program. This means that you choose which function
860 to call, and how many arguments to give it, when you write the program.
861 Usually that's just what you want. Occasionally you need to decide at
862 run time which function to call. To do that, use the functions
863 `funcall' and `apply'.
865 - Function: funcall function &rest arguments
866 `funcall' calls FUNCTION with ARGUMENTS, and returns whatever
869 Since `funcall' is a function, all of its arguments, including
870 FUNCTION, are evaluated before `funcall' is called. This means
871 that you can use any expression to obtain the function to be
872 called. It also means that `funcall' does not see the expressions
873 you write for the ARGUMENTS, only their values. These values are
874 _not_ evaluated a second time in the act of calling FUNCTION;
875 `funcall' enters the normal procedure for calling a function at the
876 place where the arguments have already been evaluated.
878 The argument FUNCTION must be either a Lisp function or a
879 primitive function. Special forms and macros are not allowed,
880 because they make sense only when given the "unevaluated" argument
881 expressions. `funcall' cannot provide these because, as we saw
882 above, it never knows them in the first place.
888 (funcall f 'x 'y '(z))
891 error--> Invalid function: #<subr and>
893 Compare these example with the examples of `apply'.
895 - Function: apply function &rest arguments
896 `apply' calls FUNCTION with ARGUMENTS, just like `funcall' but
897 with one difference: the last of ARGUMENTS is a list of arguments
898 to give to FUNCTION, rather than a single argument. We also say
899 that `apply' "spreads" this list so that each individual element
902 `apply' returns the result of calling FUNCTION. As with
903 `funcall', FUNCTION must either be a Lisp function or a primitive
904 function; special forms and macros do not make sense in `apply'.
909 error--> Wrong type argument: listp, z
910 (apply '+ 1 2 '(3 4))
912 (apply '+ '(1 2 3 4))
915 (apply 'append '((a b c) nil (x y z) nil))
918 For an interesting example of using `apply', see the description of
919 `mapcar', in *Note Mapping Functions::.
921 It is common for Lisp functions to accept functions as arguments or
922 find them in data structures (especially in hook variables and property
923 lists) and call them using `funcall' or `apply'. Functions that accept
924 function arguments are often called "functionals".
926 Sometimes, when you call a functional, it is useful to supply a no-op
927 function as the argument. Here are two different kinds of no-op
930 - Function: identity arg
931 This function returns ARG and has no side effects.
933 - Command: ignore &rest args
934 This function ignores any arguments and returns `nil'.
937 File: lispref.info, Node: Mapping Functions, Next: Anonymous Functions, Prev: Calling Functions, Up: Functions
942 A "mapping function" applies a given function to each element of a
943 list or other collection. XEmacs Lisp has several such functions;
944 `mapcar' and `mapconcat', which scan a list, are described here.
945 *Note Creating Symbols::, for the function `mapatoms' which maps over
946 the symbols in an obarray.
948 Mapping functions should never modify the sequence being mapped over.
949 The results are unpredictable.
951 - Function: mapcar function sequence
952 `mapcar' applies FUNCTION to each element of SEQUENCE in turn, and
953 returns a list of the results.
955 The argument SEQUENCE can be any kind of sequence; that is, a
956 list, a vector, a bit vector, or a string. The result is always a
957 list. The length of the result is the same as the length of
962 (mapcar 'car '((a b) (c d) (e f)))
966 (mapcar 'char-to-string "abc")
969 ;; Call each function in `my-hooks'.
970 (mapcar 'funcall my-hooks)
972 (defun mapcar* (f &rest args)
973 "Apply FUNCTION to successive cars of all ARGS.
974 Return the list of results."
975 ;; If no list is exhausted,
976 (if (not (memq 'nil args))
977 ;; apply function to CARs.
978 (cons (apply f (mapcar 'car args))
980 ;; Recurse for rest of elements.
981 (mapcar 'cdr args)))))
983 (mapcar* 'cons '(a b c) '(1 2 3 4))
984 => ((a . 1) (b . 2) (c . 3))
986 - Function: mapconcat function sequence separator
987 `mapconcat' applies FUNCTION to each element of SEQUENCE: the
988 results, which must be strings, are concatenated. Between each
989 pair of result strings, `mapconcat' inserts the string SEPARATOR.
990 Usually SEPARATOR contains a space or comma or other suitable
993 The argument FUNCTION must be a function that can take one
994 argument and return a string. The argument SEQUENCE can be any
995 kind of sequence; that is, a list, a vector, a bit vector, or a
998 (mapconcat 'symbol-name
999 '(The cat in the hat)
1001 => "The cat in the hat"
1003 (mapconcat (function (lambda (x) (format "%c" (1+ x))))
1009 File: lispref.info, Node: Anonymous Functions, Next: Function Cells, Prev: Mapping Functions, Up: Functions
1014 In Lisp, a function is a list that starts with `lambda', a byte-code
1015 function compiled from such a list, or alternatively a primitive
1016 subr-object; names are "extra". Although usually functions are defined
1017 with `defun' and given names at the same time, it is occasionally more
1018 concise to use an explicit lambda expression--an anonymous function.
1019 Such a list is valid wherever a function name is.
1021 Any method of creating such a list makes a valid function. Even
1024 (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
1025 => (lambda (x) (+ 12 x))
1027 This computes a list that looks like `(lambda (x) (+ 12 x))' and makes
1028 it the value (_not_ the function definition!) of `silly'.
1030 Here is how we might call this function:
1035 (It does _not_ work to write `(silly 1)', because this function is not
1036 the _function definition_ of `silly'. We have not given `silly' any
1037 function definition, just a value as a variable.)
1039 Most of the time, anonymous functions are constants that appear in
1040 your program. For example, you might want to pass one as an argument
1041 to the function `mapcar', which applies any given function to each
1042 element of a list. Here we pass an anonymous function that multiplies
1045 (defun double-each (list)
1046 (mapcar '(lambda (x) (* 2 x)) list))
1048 (double-each '(2 11))
1051 In such cases, we usually use the special form `function' instead of
1052 simple quotation to quote the anonymous function.
1054 - Special Form: function function-object
1055 This special form returns FUNCTION-OBJECT without evaluating it.
1056 In this, it is equivalent to `quote'. However, it serves as a
1057 note to the XEmacs Lisp compiler that FUNCTION-OBJECT is intended
1058 to be used only as a function, and therefore can safely be
1059 compiled. Contrast this with `quote', in *Note Quoting::.
1061 Using `function' instead of `quote' makes a difference inside a
1062 function or macro that you are going to compile. For example:
1064 (defun double-each (list)
1065 (mapcar (function (lambda (x) (* 2 x))) list))
1067 (double-each '(2 11))
1070 If this definition of `double-each' is compiled, the anonymous function
1071 is compiled as well. By contrast, in the previous definition where
1072 ordinary `quote' is used, the argument passed to `mapcar' is the
1075 (lambda (x) (* x 2))
1077 The Lisp compiler cannot assume this list is a function, even though it
1078 looks like one, since it does not know what `mapcar' does with the
1079 list. Perhaps `mapcar' will check that the CAR of the third element is
1080 the symbol `*'! The advantage of `function' is that it tells the
1081 compiler to go ahead and compile the constant function.
1083 We sometimes write `function' instead of `quote' when quoting the
1084 name of a function, but this usage is just a sort of comment.
1086 (function SYMBOL) == (quote SYMBOL) == 'SYMBOL
1088 See `documentation' in *Note Accessing Documentation::, for a
1089 realistic example using `function' and an anonymous function.
1092 File: lispref.info, Node: Function Cells, Next: Inline Functions, Prev: Anonymous Functions, Up: Functions
1094 Accessing Function Cell Contents
1095 ================================
1097 The "function definition" of a symbol is the object stored in the
1098 function cell of the symbol. The functions described here access, test,
1099 and set the function cell of symbols.
1101 See also the function `indirect-function' in *Note Function
1104 - Function: symbol-function symbol
1105 This returns the object in the function cell of SYMBOL. If the
1106 symbol's function cell is void, a `void-function' error is
1109 This function does not check that the returned object is a
1110 legitimate function.
1112 (defun bar (n) (+ n 2))
1114 (symbol-function 'bar)
1115 => (lambda (n) (+ n 2))
1118 (symbol-function 'baz)
1121 If you have never given a symbol any function definition, we say that
1122 that symbol's function cell is "void". In other words, the function
1123 cell does not have any Lisp object in it. If you try to call such a
1124 symbol as a function, it signals a `void-function' error.
1126 Note that void is not the same as `nil' or the symbol `void'. The
1127 symbols `nil' and `void' are Lisp objects, and can be stored into a
1128 function cell just as any other object can be (and they can be valid
1129 functions if you define them in turn with `defun'). A void function
1130 cell contains no object whatsoever.
1132 You can test the voidness of a symbol's function definition with
1133 `fboundp'. After you have given a symbol a function definition, you
1134 can make it void once more using `fmakunbound'.
1136 - Function: fboundp symbol
1137 This function returns `t' if SYMBOL has an object in its function
1138 cell, `nil' otherwise. It does not check that the object is a
1139 legitimate function.
1141 - Function: fmakunbound symbol
1142 This function makes SYMBOL's function cell void, so that a
1143 subsequent attempt to access this cell will cause a `void-function'
1144 error. (See also `makunbound', in *Note Local Variables::.)
1153 error--> Symbol's function definition is void: foo
1155 - Function: fset symbol object
1156 This function stores OBJECT in the function cell of SYMBOL. The
1157 result is OBJECT. Normally OBJECT should be a function or the
1158 name of a function, but this is not checked.
1160 There are three normal uses of this function:
1162 * Copying one symbol's function definition to another. (In
1163 other words, making an alternate name for a function.)
1165 * Giving a symbol a function definition that is not a list and
1166 therefore cannot be made with `defun'. For example, you can
1167 use `fset' to give a symbol SYMBOL1 a function definition
1168 which is another symbol SYMBOL2; then SYMBOL1 serves as an
1169 alias for whatever definition SYMBOL2 presently has.
1171 * In constructs for defining or altering functions. If `defun'
1172 were not a primitive, it could be written in Lisp (as a
1173 macro) using `fset'.
1175 Here are examples of the first two uses:
1177 ;; Give `first' the same definition `car' has.
1178 (fset 'first (symbol-function 'car))
1183 ;; Make the symbol `car' the function definition of `xfirst'.
1188 (symbol-function 'xfirst)
1190 (symbol-function (symbol-function 'xfirst))
1193 ;; Define a named keyboard macro.
1194 (fset 'kill-two-lines "\^u2\^k")
1197 See also the related functions `define-function' and `defalias',
1198 in *Note Defining Functions::.
1200 When writing a function that extends a previously defined function,
1201 the following idiom is sometimes used:
1203 (fset 'old-foo (symbol-function 'foo))
1205 "Just like old-foo, except more so."
1209 This does not work properly if `foo' has been defined to autoload. In
1210 such a case, when `foo' calls `old-foo', Lisp attempts to define
1211 `old-foo' by loading a file. Since this presumably defines `foo'
1212 rather than `old-foo', it does not produce the proper results. The
1213 only way to avoid this problem is to make sure the file is loaded
1214 before moving aside the old definition of `foo'.
1216 But it is unmodular and unclean, in any case, for a Lisp file to
1217 redefine a function defined elsewhere.
projects / chise / xemacs-chise.git- / blob