OS/2 Professional/OS2PRO194.ISO/os2/prgramer/unix/info/elisp.i07

GNU Info File | 1993-06-14 | 50.3 KB | 1,221 lines

This is Info file elisp, produced by Makeinfo-1.47 from the input file
elisp.texi.

   This file documents GNU Emacs Lisp.

   This is edition 1.03 of the GNU Emacs Lisp Reference Manual, for
Emacs Version 18.

   Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA

   Copyright (C) 1990 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.


File: elisp,  Node: Scope,  Next: Extent,  Prev: Variable Scoping,  Up: Variable Scoping

Scope
-----

   Emacs Lisp uses "indefinite scope" for local variable bindings. This
means that any function anywhere in the program text might access a
given binding of a variable.  Consider the following function
definitions:

     (defun binder (x)  ; `x' is bound in `binder'.
        (foo 5))        ; `foo' is some other function.

     (defun user ()     ; `x' is used in `user'.
       (list x))

   In a lexically scoped language, the binding of `x' from `binder'
would never be accessible in `user', because `user' is not textually
contained within the function `binder'.  However, in dynamically scoped
Emacs Lisp, `user' may or may not refer to the binding of `x'
established in `binder', depending on circumstances:

   * If we call `user' directly without calling `binder' at all, then
     whatever binding of `x' is found, it cannot come from `binder'.

   * If we define `foo' as follows and call `binder', then the binding
     made in `binder' will be seen in `user':

          (defun foo (lose)
            (user))

   * If we define `foo' as follows and call `binder', then the binding
     made in `binder' *will not* be seen in `user':

          (defun foo (x)
            (user))

     Here, when `foo' is called by `binder', it binds `x'. (The binding
     in `foo' is said to "shadow" the one made in `binder'.)
     Therefore, `user' will access the `x' bound by `foo' instead of
     the one bound by `binder'.


File: elisp,  Node: Extent,  Next: Impl of Scope,  Prev: Scope,  Up: Variable Scoping

Extent
------

   "Extent" refers to the time during program execution that a variable
name is valid.  In Emacs Lisp, a variable is valid only while the form
that bound it is executing.  This is called "dynamic extent".  "Local"
or "automatic" variables in most languages, including C and Pascal,
have dynamic extent.

   One alternative to dynamic extent is "indefinite extent".  This
means that a variable binding can live on past the exit from the form
that made the binding.  Common Lisp and Scheme, for example, support
this, but Emacs Lisp does not.

   To illustrate this, the function below, `make-add', returns a
function that purports to add N to its own argument M. This would work
in Common Lisp, but it does not work as intended in Emacs Lisp, because
after the call to `make-add' exits, the variable `n' is no longer bound
to the actual argument 2.

     (defun make-add (n)
         (function (lambda (m) (+ n m))))  ; Return a function.
          => make-add
     (fset 'add2 (make-add 2))  ; Define function `add2' with `(make-add 2)'.
          => (lambda (m) (+ n m))
     (add2 4)                   ; Try to add 2 to 4.
     error--> Symbol's value as variable is void: n


File: elisp,  Node: Impl of Scope,  Next: Using Scoping,  Prev: Extent,  Up: Variable Scoping

Implementation of Dynamic Scoping
---------------------------------

   A simple sample implementation (which is not how Emacs Lisp actually
works) may help you understand dynamic binding.  This technique is
called "deep binding" and was used in early Lisp systems.

   Suppose there is a stack of bindings: variable-value pairs.  At entry
to a function or to a `let' form, we can push bindings on the stack for
the arguments or local variables created there.  We can pop those
bindings from the stack at exit from the binding construct.

   We can find the value of a variable by searching the stack from top
to bottom for a binding for that variable; the value from that binding
is the value of the variable.  To set the variable, we search for the
current binding, then store the new value into that binding.

   As you can see, a function's bindings remain in effect as long as it
continues execution, even during its calls to other functions.  That is
why we say the extent of the binding is dynamic.  And any other function
can refer to the bindings, if it uses the same variables while the
bindings are in effect.  That is why we say the scope is indefinite.

   The actual implementation of variable scoping in GNU Emacs Lisp uses
a technique called "shallow binding".  Each variable has a standard
place in which its current value is always found--the value cell of the
symbol.

   In shallow binding, setting the variable works by storing a value in
the value cell.  When a new local binding is created, the local value is
stored in the value cell, and the old value (belonging to a previous
binding) is pushed on a stack.  When a binding is eliminated, the old
value is popped off the stack and stored in the value cell.

   We use shallow binding because it has the same results as deep
binding, but runs faster, since there is never a need to search for a
binding.


File: elisp,  Node: Using Scoping,  Prev: Impl of Scope,  Up: Variable Scoping

Proper Use of Dynamic Scoping
-----------------------------

   Binding a variable in one function and using it in another is a
powerful technique, but if used without restraint, it can make programs
hard to understand.  There are two clean ways to use this technique:

   * Use or bind the variable only in a few related functions, written
     close together in one file.  Such a variable is used for
     communication within one program.

     You should write comments to inform other programmers that they
     can see all uses of the variable before them, and to advise them
     not to add uses elsewhere.

   * Give the variable a well-defined, documented meaning, and make all
     appropriate functions refer to it (but not bind it or set it)
     wherever that meaning is relevant.  For example, the variable
     `case-fold-search' is defined as "non-`nil' means ignore case when
     searching"; various search and replace functions refer to it
     directly or through their subroutines, but do not bind or set it.

     Then you can bind the variable in other programs, knowing reliably
     what the effect will be.


File: elisp,  Node: Buffer-Local Variables,  Prev: Variable Scoping,  Up: Variables

Buffer-Local Variables
======================

   Global and local variable bindings are found in most programming
languages in one form or another.  Emacs also supports another, unusual
kind of variable binding: "buffer-local" bindings, which apply only to
one buffer.  Emacs Lisp is meant for programming editing commands, and
having different values for a variable in different buffers is an
important customization method.

* Menu:

* Intro to Buffer-Local::      Introduction and concepts.
* Creating Buffer-Local::      Creating and destroying buffer-local bindings.
* Default Value::              The default value is seen in buffers
                                 that don't have their own local values.


File: elisp,  Node: Intro to Buffer-Local,  Next: Creating Buffer-Local,  Prev: Buffer-Local Variables,  Up: Buffer-Local Variables

Introduction to Buffer-Local Variables
--------------------------------------

   A buffer-local variable has a buffer-local binding associated with a
particular buffer.  The binding is in effect when that buffer is
current; otherwise, it is not in effect.  If you set the variable while
a buffer-local binding is in effect, the new value goes in that binding,
so the global binding is unchanged; this means that the change is
visible in that buffer alone.

   A variable may have buffer-local bindings in some buffers but not in
others.  The global binding is shared by all the buffers that don't have
their own bindings.  Thus, if you set the variable in a buffer that does
not have a buffer-local binding for it, the new value is visible in all
buffers except those with buffer-local bindings.  (Here we are assuming
that there are no `let'-style local bindings to complicate the issue.)

   The most common use of buffer-local bindings is for major modes to
change variables that control the behavior of commands.  For example, C
mode and Lisp mode both set the variable `paragraph-start' to specify
that only blank lines separate paragraphs.  They do this by making the
variable buffer-local in the buffer that is being put into C mode or
Lisp mode, and then setting it to the new value for that mode.

   The usual way to make a buffer-local binding is with
`make-local-variable', which is what major mode commands use.  This
affects just the current buffer; all other buffers (including those yet
to be created) continue to share the global value.

   A more powerful operation is to mark the variable as "automatically
buffer-local" by calling `make-variable-buffer-local'.  You can think
of this as making the variable local in all buffers, even those yet to
be created.  More precisely, the effect is that setting the variable
automatically makes the variable local to the current buffer if it is
not already so.  All buffers start out by sharing the global value of
the variable as usual, but any `setq' creates a buffer-local binding
for the current buffer.  The new value is stored in the buffer-local
binding, leaving the (default) global binding untouched.  The global
value can no longer be changed with `setq'; you need to use
`setq-default' to do that.

   When a variable has local values in one or more buffers, you can get
Emacs very confused by binding the variable with `let', changing to a
different current buffer in which a different binding is in effect, and
then exiting the `let'.  The best way to preserve your sanity is to
avoid such situations.  If you use `save-excursion' around each piece
of code that changes to a different current buffer, you will not have
this problem.  Here is an example of incorrect code:

     (setq foo 'b)
     (set-buffer "a")
     (make-local-variable 'foo)
     (setq foo 'a)
     (let ((foo 'temp))
       (set-buffer "b")
       ...)
     foo => 'a      ; The old buffer-local value from buffer `a'
                           ; is now the default value.
     (set-buffer "a")
     foo => 'temp   ; The local value that should be gone
                           ; is now the buffer-local value in buffer `a'.

But `save-excursion' as shown here avoids the problem:

     (let ((foo 'temp))
       (save-excursion
         (set-buffer "b")
         ...))

   Local variables in a file you edit are also represented by
buffer-local bindings for the buffer that holds the file within Emacs.
*Note Auto Major Mode::.


File: elisp,  Node: Creating Buffer-Local,  Next: Default Value,  Prev: Intro to Buffer-Local,  Up: Buffer-Local Variables

Creating and Destroying Buffer-local Bindings
---------------------------------------------

 -- Command: make-local-variable SYMBOL
     This function creates a buffer-local binding for SYMBOL in the
     current buffer.  Other buffers are not affected.  The value
     returned is SYMBOL.

     The buffer-local value of SYMBOL starts out as the same value
     SYMBOL previously had.

          ;; In buffer `b1':
          (setq foo 5)                ; Affects all buffers.
               => 5
          (make-local-variable 'foo)  ; Now it is local in `b1'.
               => foo
          foo                         ; That did not change the value.
               => 5
          (setq foo 6)                ; Change the value in `b1'.
               => 6
          foo
               => 6

          ;; In buffer `b2', the value hasn't changed.
          (save-excursion
            (set-buffer "b2")
            foo)
               => 5

 -- Command: make-variable-buffer-local SYMBOL
     This function marks SYMBOL automatically buffer-local, so that any
     attempt to set it will make it local to the current buffer at the
     time.

     The value returned is SYMBOL.

 -- Function: buffer-local-variables &optional BUFFER
     This function tells you what the buffer-local variables are in
     buffer BUFFER.  It returns an association list (*note Association
     Lists::.) in which each association contains one buffer-local
     variable and its value.  If BUFFER is omitted, the current buffer
     is used.

          (setq lcl (buffer-local-variables))
          => ((fill-column . 75)
              (case-fold-search . t)
              ...
              (mark-ring #<marker at 5454 in buffers.texi>)
              (require-final-newline . t))

     Note that storing new values into the CDRs of the elements in this
     list will *not* change the local values of the variables.

 -- Command: kill-local-variable SYMBOL
     This function deletes the buffer-local binding (if any) for SYMBOL
     in the current buffer.  As a result, the global (default) binding
     of SYMBOL becomes visible in this buffer.  Usually this results in
     a change in the value of SYMBOL, since the global value is usually
     different from the buffer-local value just eliminated.

     It is possible to kill the local binding of a variable that
     automatically becomes local when set.  This causes the variable to
     show its global value in the current buffer.  However, if you set
     the variable again, this will once again create a local value.

     `kill-local-variable' returns SYMBOL.

 -- Function: kill-all-local-variables
     This function eliminates all the buffer-local variable bindings of
     the current buffer.  As a result, the buffer will see the default
     values of all variables.  This function also resets certain other
     information pertaining to the buffer: its local keymap is set to
     `nil', its syntax table is set to the value of
     `standard-syntax-table', and its abbrev table is set to the value
     of `fundamental-mode-abbrev-table'.

     Every major mode command begins by calling this function, which
     has the effect of switching to Fundamental mode and erasing most
     of the effects of the previous major mode.

     `kill-all-local-variables' returns `nil'.


File: elisp,  Node: Default Value,  Prev: Creating Buffer-Local,  Up: Buffer-Local Variables

The Default Value of a Buffer-Local Variable
--------------------------------------------

   The global value of a variable with buffer-local bindings is also
called the "default" value, because it is the value that is in effect
except when specifically overridden.

   The functions `default-value' and `setq-default' allow you to access
and change the default value regardless of whether the current buffer
has a buffer-local binding.  For example, you could use `setq-default'
to change the default setting of `paragraph-start' for most buffers;
and this would work even when you are in a C or Lisp mode buffer which
has a buffer-local value for this variable.

 -- Function: default-value SYMBOL
     This function returns SYMBOL's default value.  This is the value
     that is seen in buffers that do not have their own values for this
     variable.  If SYMBOL is not buffer-local, this is equivalent to
     `symbol-value' (*note Accessing Variables::.).

 -- Special Form: setq-default SYMBOL VALUE
     This sets the default value of SYMBOL to VALUE. SYMBOL is not
     evaluated, but VALUE is.  The value of the `setq-default' form is
     VALUE.

     If a SYMBOL is not buffer-local for the current buffer, and is not
     marked automatically buffer-local, this has the same effect as
     `setq'.  If SYMBOL is buffer-local for the current buffer, then
     this changes the value that other buffers will see (as long as they
     don't have a buffer-local value), but not the value that the
     current buffer sees.

          ;; In buffer `foo':
          (make-local-variable 'local)
               => local
          (setq local 'value-in-foo)
               => value-in-foo
          (setq-default local 'new-default)
               => new-default
          local
               => value-in-foo
          (default-value 'local)
               => new-default

          ;; In (the new) buffer `bar':
          local
               => new-default
          (default-value 'local)
               => new-default
          (setq local 'another-default)
               => another-default
          (default-value 'local)
               => another-default

          ;; Back in buffer `foo':
          local
               => value-in-foo
          (default-value 'local)
               => another-default

 -- Function: set-default SYMBOL VALUE
     This function is like `setq-default', except that SYMBOL is
     evaluated.

          (set-default (car '(a b c)) 23)
               => 23
          (default-value 'a)
               => 23


File: elisp,  Node: Functions,  Next: Macros,  Prev: Variables,  Up: Top

Functions
*********

   A Lisp program is composed mainly of Lisp functions.  This chapter
explains what functions are, how they accept arguments, and how to
define them.

* Menu:

* What Is a Function::    Lisp functions vs primitives; terminology.
* Lambda Expressions::    How functions are expressed as Lisp objects.
* Function Names::        A symbol can serve as the name of a function.
* Defining Functions::    Lisp expressions for defining functions.
* Calling Functions::     How to use an existing function.
* Mapping Functions::     Applying a function to each element of a list, etc.
* Anonymous Functions::   Lambda-expressions are functions with no names.
* Function Cells::        Accessing or setting the function definition
                            of a symbol.
* Related Topics::        Cross-references to specific Lisp primitives
                            that have a special bearing on how functions work.


File: elisp,  Node: What Is a Function,  Next: Lambda Expressions,  Prev: Functions,  Up: Functions

What Is a Function?
===================

   In a general sense, a function is a rule for carrying on a
computation given several values called "arguments".  The result of the
computation is called the value of the function.  The computation can
also have side effects: lasting changes in the values of variables or
the contents of data structures.

   Here are important terms for functions in Emacs Lisp and for other
function-like objects.

"function"
     In Emacs Lisp, a "function" is anything that can be applied to
     arguments in a Lisp program.  In some cases, we will use it more
     specifically to mean a function written in Lisp.  Special forms and
     macros are not functions.

"primitive"
     A "primitive" is a function callable from Lisp that is written in
     C, such as `car' or `append'.  These functions are also called
     "built-in" functions or "subrs".  (Special forms are also
     considered primitives.)

     Primitives provide the lowest-level interfaces to editing
     functions or operating system services, or in a few cases they
     perform important operations more quickly than a Lisp program
     could.  Primitives can be modified or added only by changing the C
     sources and recompiling the editor.  See *Note Writing Emacs
     Primitives::.

"lambda expression"
     A "lambda expression" is a function written in Lisp. These are
     described in the following section. *Note Lambda Expressions::.

"special form"
     A "special form" is a primitive that is like a function but does
     not evaluate all of its arguments in the usual way.  It may
     evaluate only some of the arguments, or may evaluate them in an
     unusual order, or several times.  Many special forms are described
     in *Note Control Structures::.

"macro"
     A "macro" is a construct defined in Lisp by the programmer.  It
     differs from a function in that it translates a Lisp expression
     that you write into an equivalent expression to be evaluated
     instead of the original expression.  *Note Macros::, for how to
     define and use macros.

"command"
     A "command" is an object that `command-execute' can invoke; it is
     a possible definition for a key sequence.  Some functions are
     commands; a function written in Lisp is a command if it contains an
     interactive declaration (*note Defining Commands::.).  Such a
     function can be called from Lisp expressions like other functions;
     in this case, the fact that the function is a command makes no
     difference.

     Strings are commands also, even though they are not functions.  A
     symbol is a command if its function definition is a command; such
     symbols can be invoked with `M-x'.  The symbol is a function as
     well if the definition is a function.  *Note Command Overview::.

"keystroke command"
     A "keystroke command" is a command that is bound to a key sequence
     (typically one to three keystrokes).  The distinction is made here
     merely to avoid confusion with the meaning of "command" in
     non-Emacs editors; for programmers, the distinction is normally
     unimportant.

 -- Function: subrp OBJECT
     This function returns `t' if OBJECT is a built-in function (i.e. a
     Lisp primitive).

          (subrp 'message)                ; `message' is a symbol,
               => nil                     ; not a subr object.
          (subrp (symbol-function 'message))
               => t


File: elisp,  Node: Lambda Expressions,  Next: Function Names,  Prev: What Is a Function,  Up: Functions

Lambda Expressions
==================

   A function written in Lisp is a list that looks like this:

     (lambda (ARG-VARIABLES...)
       [DOCUMENTATION-STRING]
       [INTERACTIVE-DECLARATION]
       BODY-FORMS...)

(Such a list is called a "lambda expression", even though it is not an
expression at all, for historical reasons.)

* Menu:

* Lambda Components::       The parts of a lambda expression.
* Simple Lambda::           A simple example.
* Argument List::           Details and special features of argument lists.
* Function Documentation::  How to put documentation in a function.


File: elisp,  Node: Lambda Components,  Next: Simple Lambda,  Prev: Lambda Expressions,  Up: Lambda Expressions

Components of a Lambda Expression
---------------------------------

   A function written in Lisp (a "lambda expression") is a list that
looks like this:

     (lambda (ARG-VARIABLES...)
       [DOCUMENTATION-STRING]
       [INTERACTIVE-DECLARATION]
       BODY-FORMS...)

   The first element of a lambda expression is always the symbol
`lambda'.  This indicates that the list represents a function.  The
reason functions are defined to start with `lambda' is so that other
lists, intended for other uses, will not accidentally be valid as
functions.

   The second element is a list of argument variable names (symbols).
This is called the "lambda list".  When a Lisp function is called, the
argument values are matched up against the variables in the lambda
list, which are given local bindings with the values provided. *Note
Local Variables::.

   The documentation string is an actual string that serves to describe
the function for the Emacs help facilities.  *Note Function
Documentation::.

   The interactive declaration is a list of the form `(interactive
CODE-STRING)'.  This declares how to provide arguments if the function
is used interactively.  Functions with this declaration are called
"commands"; they can be called using `M-x' or bound to a key. Functions
not intended to be called in this way should not have interactive
declarations.  *Note Defining Commands::, for how to write an
interactive declaration.

   The rest of the elements are the "body" of the function: the Lisp
code to do the work of the function (or, as a Lisp programmer would say,
"a list of Lisp forms to evaluate").  The value returned by the
function is the value returned by the last element of the body.


File: elisp,  Node: Simple Lambda,  Next: Argument List,  Prev: Lambda Components,  Up: Lambda Expressions

A Simple Lambda-Expression Example
----------------------------------

   Consider for example the following function:

     (lambda (a b c) (+ a b c))

We can call this function by writing it as the CAR of an expression,
like this:

     ((lambda (a b c) (+ a b c))
      1 2 3)

The body of this lambda expression is evaluated with the variable `a'
bound to 1, `b' bound to 2, and `c' bound to 3. Evaluation of the body
adds these three numbers, producing the result 6; therefore, this call
to the function returns the value 6.

   Note that the arguments can be the results of other function calls,
as in this example:

     ((lambda (a b c) (+ a b c))
      1 (* 2 3) (- 5 4))

Here all the arguments `1', `(* 2 3)', and `(- 5 4)' are evaluated,
left to right.  Then the lambda expression is applied to the argument
values 1, 6 and 1 to produce the value 8.

   It is not often useful to write a lambda expression as the CAR of a
form in this way.  You can get the same result, of making local
variables and giving them values, using the special form `let' (*note
Local Variables::.).  And `let' is clearer and easier to use. In
practice, lambda expressions are either stored as the function
definitions of symbols, to produce named functions, or passed as
arguments to other functions (*note Anonymous Functions::.).

   However, calls to explicit lambda expressions were very useful in the
old days of Lisp, before the special form `let' was invented.  At that
time, they were the only way to bind and initialize local variables.


File: elisp,  Node: Argument List,  Next: Function Documentation,  Prev: Simple Lambda,  Up: Lambda Expressions

Advanced Features of Argument Lists
-----------------------------------

   Our simple sample function, `(lambda (a b c) (+ a b c))', specifies
three argument variables, so it must be called with three arguments: if
you try to call it with only two arguments or four arguments, you will
get a `wrong-number-of-arguments' error.

   It is often convenient to write a function that allows certain
arguments to be omitted.  For example, the function `substring' accepts
three arguments--a string, the start index and the end index--but the
third argument defaults to the end of the string if you omit it.  It is
also convenient for certain functions to accept an indefinite number of
arguments, as the functions `and' and `+' do.

   To specify optional arguments that may be omitted when a function is
called, simply include the keyword `&optional' before the optional
arguments.  To specify a list of zero or more extra arguments, include
the keyword `&rest' before one final argument.

   Thus, the complete syntax for an argument list is as follows:

     (REQUIRED-VARS...
      [&optional OPTIONAL-VARS...]
      [&rest REST-VAR])

The square brackets indicate that the `&optional' and `&rest' clauses,
and the variables that follow them, are optional.

   A call to the function requires one actual argument for each of the
REQUIRED-VARS.  There may be actual arguments for zero or more of the
OPTIONAL-VARS, and there cannot be any more actual arguments than these
unless `&rest' exists.  In that case, there may be any number of extra
actual arguments.

   If actual arguments for the optional and rest variables are omitted,
then they always default to `nil'.  However, the body of the function
is free to consider `nil' an abbreviation for some other meaningful
value.  This is what `substring' does; `nil' as the third argument
means to use the length of the string supplied.  There is no way for the
function to distinguish between an explicit argument of `nil' and an
omitted argument.

     Common Lisp note: Common Lisp allows the function to specify what
     default values will be used when an optional argument is omitted;
     GNU Emacs Lisp always uses `nil'.

   For example, an argument list that looks like this:

     (a b &optional c d &rest e)

binds `a' and `b' to the first two actual arguments, which are
required.  If one or two more arguments are provided, `c' and `d' are
bound to them respectively; any arguments after the first four are
collected into a list and `e' is bound to that list.  If there are only
two arguments, `c' is `nil'; if two or three arguments, `d' is `nil';
if four arguments or fewer, `e' is `nil'.

   There is no way to have required arguments following optional
ones--it would not make sense.  To see why this must be so, suppose
that `c' in the example were optional and `d' were required. If three
actual arguments are given; then which variable would the third
argument be for?  Similarly, it makes no sense to have any more
arguments (either required or optional) after a `&rest' argument.

   Here are some examples of argument lists and proper calls:

     ((lambda (n) (1+ n))                ; One required:
      1)                                 ; requires exactly one argument.
          => 2
     ((lambda (n &optional n1)           ; One required and one optional:
              (if n1 (+ n n1) (1+ n)))   ; 1 or 2 arguments.
      1 2)
          => 3
     ((lambda (n &rest ns)               ; One required and one rest:
              (+ n (apply '+ ns)))       ; 1 or more arguments.
      1 2 3 4 5)
          => 15


File: elisp,  Node: Function Documentation,  Prev: Argument List,  Up: Lambda Expressions

Documentation Strings of Functions
----------------------------------

   A lambda expression may optionally have a "documentation string" just
after the lambda list.  This string does not affect execution of the
function; it is a kind of comment, but a systematized comment which
actually appears inside the Lisp world and can be used by the Emacs help
facilities.  *Note Documentation::, for how the DOCUMENTATION-STRING is
accessed.

   It is a good idea to provide documentation strings for all commands,
and for all other functions in your program that users of your program
should know about; internal functions might as well have only comments,
since comments don't take up any room when your program is loaded.

   The first line of the documentation string should stand on its own,
because `apropos' displays just this first line.  It should consist of
one or two complete sentences that summarize the function's purpose.

   The start of the documentation string is usually indented, but since
these spaces come before the starting double-quote, they are not part of
the string.  Some people make a practice of indenting any additional
lines of the string so that the text lines up.  *This is a mistake.*
The indentation of the following lines is inside the string; what looks
nice in the source code will look ugly when displayed by the help
commands.

   You may wonder how the documentation string could be optional, since
there are required components of the function that follow it (the body).
Since evaluation of a string returns that string, without any side
effects, it has no effect if it is not the last form in the body.
Thus, in practice, there is no confusion between the first form of the
body and the documentation string; if the only body form is a string
then it serves both as the return value and as the documentation.


File: elisp,  Node: Function Names,  Next: Defining Functions,  Prev: Lambda Expressions,  Up: Functions

Naming a Function
=================

   In most computer languages, every function has a name; the idea of a
function without a name is nonsensical.  In Lisp, a function in the
strictest sense has no name.  It is simply a list whose first element is
`lambda', or a primitive subr-object.

   However, a symbol can serve as the name of a function.  This happens
when you put the function in the symbol's "function cell" (*note Symbol
Components::.).  Then the symbol itself becomes a valid, callable
function, equivalent to the list or subr-object that its function cell
refers to.  The contents of the function cell are also called the
symbol's "function definition".

   In practice, nearly all functions are given names in this way and
referred to through their names.  For example, the symbol `car' works
as a function and does what it does because the primitive subr-object
`#<subr car>' is stored in its function cell.

   We give functions names because it is more convenient to refer to
them by their names in other functions.  For primitive subr-objects
such as `#<subr car>', names are the only way you can refer to them:
there is no read syntax for such objects.  For functions written in
Lisp, the name is more convenient to use in a call than an explicit
lambda expression.  Also, a function with a name can refer to
itself--it can be recursive.  Writing the function's name in its own
definition is much more convenient than making the function definition
point to itself (something that is not impossible but that has various
disadvantages in practice).

   Functions are often identified with the symbols used to name them.
For example, we often speak of "the function `car'", not distinguishing
between the symbol `car' and the primitive subr-object that is its
function definition.  For most purposes, there is no need to
distinguish.

   Even so, keep in mind that a function need not have a unique name.
While a given function object *usually* appears in the function cell of
only one symbol, this is just a matter of convenience.  It is very easy
to store it in several symbols using `fset'; then each of the symbols is
equally well a name for the same function.

   A symbol used as a function name may also be used as a variable;
these two uses of a symbol are independent and do not conflict.


File: elisp,  Node: Defining Functions,  Next: Calling Functions,  Prev: Function Names,  Up: Functions

Defining Named Functions
========================

   We usually give a name to a function when it is first created.  This
is called "defining a function", and it is done with the `defun'
special form.

 -- Special Form: defun NAME ARGUMENT-LIST BODY-FORMS
     `defun' is the usual way to define new Lisp functions.  It defines
     the symbol NAME as a function that looks like this:

          (lambda ARGUMENT-LIST . BODY-FORMS)

     This lambda expression is stored in the function cell of NAME. The
     value returned by evaluating the `defun' form is NAME, but usually
     we ignore this value.

     As described previously (*note Lambda Expressions::.),
     ARGUMENT-LIST is a list of argument names and may include the
     keywords `&optional' and `&rest'.  Also, the first two forms in
     BODY-FORMS may be a documentation string and an interactive
     declaration.

     Note that the same symbol NAME may also be used as a global
     variable, since the value cell is independent of the function cell.

     Here are some examples:

          (defun foo () 5)
               => foo
          (foo)
               => 5

          (defun bar (a &optional b &rest c)
              (list a b c))
               => bar
          (bar 1 2 3 4 5)
               => (1 2 (3 4 5))
          (bar 1)
               => (1 nil nil)
          (bar)
          error--> Wrong number of arguments.

          (defun capitalize-backwards ()
            "This function makes the last letter of a word upper case."
            (interactive)
            (backward-word 1)
            (forward-word 1)
            (backward-char 1)
            (capitalize-word 1))
               => capitalize-backwards

     Be careful not to redefine existing functions unintentionally.
     `defun' will redefine even primitive functions such as `car'
     without any hesitation or notification.  Redefining a function
     already defined is often done deliberately, and there is no way to
     distinguish deliberate redefinition from unintentional
     redefinition.


File: elisp,  Node: Calling Functions,  Next: Mapping Functions,  Prev: Defining Functions,  Up: Functions

Calling Functions
=================

   Defining functions is only half the battle.  Functions don't do
anything until you "call" them, i.e., tell them to run.  This process
is also known as "invocation".

   The most common way of invoking a function is by evaluating a list.
For example, evaluating the list `(concat "a" "b")' calls the function
`concat'.  *Note Evaluation::, for a description of evaluation.

   When you write a list as an expression in your program, the function
name is part of the program.  This means that the choice of which
function to call is made when you write the program.  Usually that's
just what you want.  Occasionally you need to decide at run time which
function to call.  Then you can use the functions `funcall' and `apply'.

 -- Function: funcall FUNCTION &rest ARGUMENTS
     `funcall' calls FUNCTION with ARGUMENTS, and returns whatever
     FUNCTION returns.

     Since `funcall' is a function, all of its arguments, including
     FUNCTION, are evaluated before `funcall' is called.  This means
     that you can use any expression to obtain the function to be
     called.  It also means that `funcall' does not see the expressions
     you write for the ARGUMENTS, only their values.  These values are
     *not* evaluated a second time in the act of calling FUNCTION;
     `funcall' enters the normal procedure for calling a function at the
     place where the arguments have already been evaluated.

     The argument FUNCTION must be either a Lisp function or a
     primitive function.  Special forms and macros are not allowed,
     because they make sense only when given the "unevaluated" argument
     expressions.  `funcall' cannot provide these because, as we saw
     above, it never knows them in the first place.

          (setq f 'list)
               => list
          (funcall f 'x 'y 'z)
               => (x y z)
          (funcall f 'x 'y '(z))
               => (x y (z))
          (funcall 'and t nil)
          error--> Invalid function: #<subr and>

     Compare this example with that of `apply'.

 -- Function: apply FUNCTION &rest ARGUMENTS
     `apply' calls FUNCTION with ARGUMENTS, just like `funcall' but
     with one difference: the last of ARGUMENTS is a list of arguments
     to give to FUNCTION, rather than a single argument.  We also say
     that this list is "appended" to the other arguments.

     `apply' returns the result of calling FUNCTION.  As with
     `funcall', FUNCTION must either be a Lisp function or a primitive
     function; special forms and macros do not make sense in `apply'.

          (setq f 'list)
               => list
          (apply f 'x 'y 'z)
          error--> Wrong type argument: listp, z
          (apply '+ 1 2 '(3 4))
               => 10
          (apply '+ '(1 2 3 4))
               => 10

          (apply 'append '((a b c) nil (x y z) nil))
               => (a b c x y z)

     An interesting example of using `apply' is found in the description
     of `mapcar'; see the following section.

   It is common for Lisp functions to accept functions as arguments or
find them in data structures (especially in hook variables and property
lists) and call them using `funcall' or `apply'.  Functions that accept
function arguments are often called "functionals".

   Sometimes, when you call such a function, it is useful to supply a
no-op function as the argument.  Here are two different kinds of no-op
function:

 -- Function: identity ARG
     This function returns ARG and has no side effects.

 -- Function: ignore &rest ARGS
     This function ignores any arguments and returns `nil'.


File: elisp,  Node: Mapping Functions,  Next: Anonymous Functions,  Prev: Calling Functions,  Up: Functions

Mapping Functions
=================

   A "mapping function" applies a given function to each element of a
list or other collection.  Emacs Lisp has three such functions;
`mapcar' and `mapconcat', which scan a list, are described here.  For
the third mapping function, `mapatoms', see *Note Creating Symbols::.

 -- Function: mapcar FUNCTION SEQUENCE
     `mapcar' applies FUNCTION to each element of SEQUENCE in turn.
     The results are made into a `nil'-terminated list.

     The argument SEQUENCE may be a list, a vector or a string.  The
     result is always a list.  The length of the result is the same as
     the length of SEQUENCE.

     For example:

          (mapcar 'car '((a b) (c d) (e f)))
               => (a c e)
          (mapcar '1+ [1 2 3])
               => (2 3 4)
          (mapcar 'char-to-string "abc")
               => ("a" "b" "c")

          ;; Call each function in `my-hooks'.
          (mapcar 'funcall my-hooks)

          (defun mapcar* (f &rest args)
            "Apply FUNCTION to successive cars of all ARGS, until one ends.
          Return the list of results."
            (if (not (memq 'nil args))              ; If no list is exhausted,
                (cons (apply f (mapcar 'car args))  ; Apply function to CARs.
                      (apply 'mapcar* f             ; Recurse for rest of elements.
                             (mapcar 'cdr args)))))

          (mapcar* 'cons '(a b c) '(1 2 3 4))
               => ((a . 1) (b . 2) (c . 3))

 -- Function: mapconcat FUNCTION SEQUENCE SEPARATOR
     `mapconcat' applies FUNCTION to each element of SEQUENCE: the
     results, which must be strings, are concatenated. Between each
     pair of result strings, `mapconcat' inserts the string SEPARATOR.
     Usually SEPARATOR contains a space or comma or other suitable
     punctuation.

     The argument FUNCTION must be a function that can take one
     argument and returns a string.

          (mapconcat 'symbol-name
                     '(The cat in the hat)
                     " ")
               => "The cat in the hat"

          (mapconcat (function (lambda (x) (format "%c" (1+ x))))
                     "HAL-8000"
                     "")
               => "IBM.9111"


File: elisp,  Node: Anonymous Functions,  Next: Function Cells,  Prev: Mapping Functions,  Up: Functions

Anonymous Functions
===================

   In Lisp, a function is a list that starts with `lambda' (or
alternatively a primitive subr-object); names are "extra".  Although
usually functions are defined with `defun' and given names at the same
time, it is occasionally more concise to use an explicit lambda
expression--an anonymous function.  Such a list is valid wherever a
function name is.

   Any method of creating such a list makes a valid function.  Even
this:

     (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
          => (lambda (x) (+ 12 x))

This computes a list that looks like `(lambda (x) (+ 12 x))' and makes
it the value (*not* the function definition!) of `silly'.

   Here is how we might call this function:

     (funcall silly 1)
          => 13

(It does *not* work to write `(silly 1)', because this function is not
the *function definition* of `silly'.  We have not given `silly' any
function definition, just a value as a variable.)

   Most of the time, anonymous functions are constants that appear in
your program.  For example, you might want to pass one as an argument
to the function `mapcar', which applies any given function to each
element of a list.  Here we pass an anonymous function that multiplies
a number by two:

     (defun double-each (list)
       (mapcar '(lambda (x) (* 2 x)) list))
          => double-each
     (double-each '(2 11))
          => (4 22)

In such cases, we usually use the special form `function' instead of
simple quotation to quote the anonymous function.

 -- Special Form: function FUNCTION-OBJECT
     This special form returns FUNCTION-OBJECT without evaluating it.
     In this, it is equivalent to `quote'.  However, it serves as a
     note to the Emacs Lisp compiler that FUNCTION-OBJECT is intended
     to be used only as a function, and therefore can safely be
     compiled. *Note Quoting::, for comparison.

   Using `function' instead of `quote' makes a difference inside a
function or macro that you are going to compile.  For example:

     (defun double-each (list)
       (mapcar (function (lambda (x) (* 2 x))) list))
          => double-each
     (double-each '(2 11))
          => (4 22)

If this definition of `double-each' is compiled, the anonymous function
is compiled as well.  By contrast, in the previous definition where
ordinary `quote' is used, the argument passed to `mapcar' is the
precise list shown:

     (lambda (arg) (+ arg 5))

The Lisp compiler cannot assume this list is a function, even though it
looks like one, since it does not know what `mapcar' does with the
list.  Perhaps `mapcar' will check that the CAR of the third element is
the symbol `+'!  The advantage of `function' is that it tells the
compiler to go ahead and compile the constant function.

   We sometimes write `function' instead of `quote' when quoting the
name of a function, but this usage is just a sort of comment.

     (function SYMBOL) == (quote SYMBOL) == 'SYMBOL

   See `documentation' in *Note Accessing Documentation::, for a
realistic example using `function' and an anonymous function.


File: elisp,  Node: Function Cells,  Next: Related Topics,  Prev: Anonymous Functions,  Up: Functions

Accessing Function Cell Contents
================================

   The "function definition" of a symbol is the object stored in the
function cell of the symbol.  The functions described here access, test,
and set the function cell of symbols.

 -- Function: symbol-function SYMBOL
     This returns the object in the function cell of SYMBOL.  If the
     symbol's function cell is void, a `void-function' error is
     signaled.

     This function does not check that the returned object is a
     legitimate function.

          (defun bar (n) (+ n 2))
               => bar
          (symbol-function 'bar)
               => (lambda (n) (+ n 2))
          (fset 'baz 'bar)
               => bar
          (symbol-function 'baz)
               => bar

   If you have never given a symbol any function definition, we say that
that symbol's function cell is "void".  In other words, the function
cell does not have any Lisp object in it.  If you try to call such a
symbol as a function, it signals a `void-function' error.

   Note that void is not the same as `nil' or the symbol `void'.  The
symbols `nil' and `void' are Lisp objects, and can be stored into a
function cell just as any other object can be (and they can be valid
functions if you define them in turn with `defun'); but `nil' or `void'
is *an object*.  A void function cell contains no object whatsoever.

   You can test the voidness of a symbol's function definition with
`fboundp'.  After you have given a symbol a function definition, you
can make it void once more using `fmakunbound'.

 -- Function: fboundp SYMBOL
     Returns `t' if the symbol has an object in its function cell,
     `nil' otherwise.  It does not check that the object is a legitimate
     function.

 -- Function: fmakunbound SYMBOL
     This function makes SYMBOL's function cell void, so that a
     subsequent attempt to access this cell will cause a `void-function'
     error.  (See also `makunbound', in *Note Local Variables::.)

          (defun foo (x) x)
               => x
          (fmakunbound 'foo)
               => x
          (foo 1)
          error--> Symbol's function definition is void: foo

 -- Function: fset SYMBOL OBJECT
     This function stores OBJECT in the function cell of SYMBOL. The
     result is OBJECT.  Normally OBJECT should be a function or the
     name of a function, but this is not checked.

     There are three normal uses of this function:

        * Copying one symbol's function definition to another.  (In
          other words, making an alternate name for a function.)

        * Giving a symbol a function definition that is not a list and
          therefore cannot be made with `defun'.  *Note Classifying
          Lists::, for an example of this usage.

        * In constructs for defining or altering functions.  If `defun'
          were not a primitive, it could be written in Lisp (as a
          macro) using `fset'.

     Here are examples of the first two uses:

          ;; Give `first' the same definition `car' has.
          (fset 'first (symbol-function 'car))
               => #<subr car>
          (first '(1 2 3))
               => 1

          ;; Make the symbol `car' the function definition of `xfirst'.
          (fset 'xfirst 'car)
               => car
          (xfirst '(1 2 3))
               => 1
          (symbol-function 'xfirst)
               => car
          (symbol-function (symbol-function 'xfirst))
               => #<subr car>

          ;; Define a named keyboard macro.
          (fset 'kill-two-lines "\^u2\^k")
               => "\^u2\^k"

   When writing a function that extends a previously defined function,
the following idiom is often used:

     (fset 'old-foo (symbol-function 'foo))

     (defun foo ()
       "Just like old-foo, except more so."
       (old-foo)
       (more-so))

This does not work properly if `foo' has been defined to autoload. In
such a case, when `foo' calls `old-foo', Lisp will attempt to define
`old-foo' by loading a file.  Since this presumably defines `foo'
rather than `old-foo', it will not produce the proper results.  The
only way to avoid this problem is to make sure the file is loaded
before moving aside the old definition of `foo'.