Mercurial > emacs
changeset 6453:974a37e5c414
Initial revision
| author | Richard M. Stallman <rms@gnu.org> |
|---|---|
| date | Mon, 21 Mar 1994 17:36:52 +0000 |
| parents | 8c7032348e93 |
| children | f5abd5d777eb |
| files | lispref/control.texi lispref/intro.texi lispref/loading.texi |
| diffstat | 3 files changed, 2585 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/control.texi Mon Mar 21 17:36:52 1994 +0000 @@ -0,0 +1,1136 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/control +@node Control Structures, Variables, Evaluation, Top +@chapter Control Structures +@cindex special forms for control structures +@cindex control structures + + A Lisp program consists of expressions or @dfn{forms} (@pxref{Forms}). +We control the order of execution of the forms by enclosing them in +@dfn{control structures}. Control structures are special forms which +control when, whether, or how many times to execute the forms they contain. + + The simplest control structure is sequential execution: first form +@var{a}, then form @var{b}, and so on. This is what happens when you +write several forms in succession in the body of a function, or at top +level in a file of Lisp code---the forms are executed in the order they +are written. We call this @dfn{textual order}. For example, if a +function body consists of two forms @var{a} and @var{b}, evaluation of +the function evaluates first @var{a} and then @var{b}, and the +function's value is the value of @var{b}. + + Emacs Lisp provides several kinds of control structure, including +other varieties of sequencing, function calls, conditionals, iteration, +and (controlled) jumps. The built-in control structures are special +forms since their subforms are not necessarily evaluated. You can use +macros to define your own control structure constructs (@pxref{Macros}). + +@menu +* Sequencing:: Evaluation in textual order. +* Conditionals:: @code{if}, @code{cond}. +* Combining Conditions:: @code{and}, @code{or}, @code{not}. +* Iteration:: @code{while} loops. +* Nonlocal Exits:: Jumping out of a sequence. +@end menu + +@node Sequencing +@section Sequencing + + Evaluating forms in the order they are written is the most common +control structure. Sometimes this happens automatically, such as in a +function body. Elsewhere you must use a control structure construct to +do this: @code{progn}, the simplest control construct of Lisp. + + A @code{progn} special form looks like this: + +@example +@group +(progn @var{a} @var{b} @var{c} @dots{}) +@end group +@end example + +@noindent +and it says to execute the forms @var{a}, @var{b}, @var{c} and so on, in +that order. These forms are called the body of the @code{progn} form. +The value of the last form in the body becomes the value of the entire +@code{progn}. + +@cindex implicit @code{progn} + In the early days of Lisp, @code{progn} was the only way to execute +two or more forms in succession and use the value of the last of them. +But programmers found they often needed to use a @code{progn} in the +body of a function, where (at that time) only one form was allowed. So +the body of a function was made into an ``implicit @code{progn}'': +several forms are allowed just as in the body of an actual @code{progn}. +Many other control structures likewise contain an implicit @code{progn}. +As a result, @code{progn} is not used as often as it used to be. It is +needed now most often inside of an @code{unwind-protect}, @code{and}, +@code{or}, or the @var{else}-part of an @code{if}. + +@defspec progn forms@dots{} +This special form evaluates all of the @var{forms}, in textual +order, returning the result of the final form. + +@example +@group +(progn (print "The first form") + (print "The second form") + (print "The third form")) + @print{} "The first form" + @print{} "The second form" + @print{} "The third form" +@result{} "The third form" +@end group +@end example +@end defspec + + Two other control constructs likewise evaluate a series of forms but return +a different value: + +@defspec prog1 form1 forms@dots{} +This special form evaluates @var{form1} and all of the @var{forms}, in +textual order, returning the result of @var{form1}. + +@example +@group +(prog1 (print "The first form") + (print "The second form") + (print "The third form")) + @print{} "The first form" + @print{} "The second form" + @print{} "The third form" +@result{} "The first form" +@end group +@end example + +Here is a way to remove the first element from a list in the variable +@code{x}, then return the value of that former element: + +@example +(prog1 (car x) (setq x (cdr x))) +@end example +@end defspec + +@defspec prog2 form1 form2 forms@dots{} +This special form evaluates @var{form1}, @var{form2}, and all of the +following @var{forms}, in textual order, returning the result of +@var{form2}. + +@example +@group +(prog2 (print "The first form") + (print "The second form") + (print "The third form")) + @print{} "The first form" + @print{} "The second form" + @print{} "The third form" +@result{} "The second form" +@end group +@end example +@end defspec + +@node Conditionals +@section Conditionals +@cindex conditional evaluation + + Conditional control structures choose among alternatives. Emacs Lisp +has two conditional forms: @code{if}, which is much the same as in other +languages, and @code{cond}, which is a generalized case statement. + +@defspec if condition then-form else-forms@dots{} +@code{if} chooses between the @var{then-form} and the @var{else-forms} +based on the value of @var{condition}. If the evaluated @var{condition} is +non-@code{nil}, @var{then-form} is evaluated and the result returned. +Otherwise, the @var{else-forms} are evaluated in textual order, and the +value of the last one is returned. (The @var{else} part of @code{if} is +an example of an implicit @code{progn}. @xref{Sequencing}.) + +If @var{condition} has the value @code{nil}, and no @var{else-forms} are +given, @code{if} returns @code{nil}. + +@code{if} is a special form because the branch which is not selected is +never evaluated---it is ignored. Thus, in the example below, +@code{true} is not printed because @code{print} is never called. + +@example +@group +(if nil + (print 'true) + 'very-false) +@result{} very-false +@end group +@end example +@end defspec + +@defspec cond clause@dots{} +@code{cond} chooses among an arbitrary number of alternatives. Each +@var{clause} in the @code{cond} must be a list. The @sc{car} of this +list is the @var{condition}; the remaining elements, if any, the +@var{body-forms}. Thus, a clause looks like this: + +@example +(@var{condition} @var{body-forms}@dots{}) +@end example + +@code{cond} tries the clauses in textual order, by evaluating the +@var{condition} of each clause. If the value of @var{condition} is +non-@code{nil}, the clause ``succeeds''; then @code{cond} evaluates its +@var{body-forms}, and the value of the last of @var{body-forms} becomes +the value of the @code{cond}. The remaining clauses are ignored. + +If the value of @var{condition} is @code{nil}, the clause ``fails'', so +the @code{cond} moves on to the following clause, trying its +@var{condition}. + +If every @var{condition} evaluates to @code{nil}, so that every clause +fails, @code{cond} returns @code{nil}. + +A clause may also look like this: + +@example +(@var{condition}) +@end example + +@noindent +Then, if @var{condition} is non-@code{nil} when tested, the value of +@var{condition} becomes the value of the @code{cond} form. + +The following example has four clauses, which test for the cases where +the value of @code{x} is a number, string, buffer and symbol, +respectively: + +@example +@group +(cond ((numberp x) x) + ((stringp x) x) + ((bufferp x) + (setq temporary-hack x) ; @r{multiple body-forms} + (buffer-name x)) ; @r{in one clause} + ((symbolp x) (symbol-value x))) +@end group +@end example + +Often we want to execute the last clause whenever none of the previous +clauses was successful. To do this, we use @code{t} as the +@var{condition} of the last clause, like this: @code{(t +@var{body-forms})}. The form @code{t} evaluates to @code{t}, which is +never @code{nil}, so this clause never fails, provided the @code{cond} +gets to it at all. + +For example, + +@example +@group +(cond ((eq a 1) 'foo) + (t "default")) +@result{} "default" +@end group +@end example + +@noindent +This expression is a @code{cond} which returns @code{foo} if the value +of @code{a} is 1, and returns the string @code{"default"} otherwise. +@end defspec + +Both @code{cond} and @code{if} can usually be written in terms of the +other. Therefore, the choice between them is a matter of style. For +example: + +@example +@group +(if @var{a} @var{b} @var{c}) +@equiv{} +(cond (@var{a} @var{b}) (t @var{c})) +@end group +@end example + +@node Combining Conditions +@section Constructs for Combining Conditions + + This section describes three constructs that are often used together +with @code{if} and @code{cond} to express complicated conditions. The +constructs @code{and} and @code{or} can also be used individually as +kinds of multiple conditional constructs. + +@defun not condition +This function tests for the falsehood of @var{condition}. It returns +@code{t} if @var{condition} is @code{nil}, and @code{nil} otherwise. +The function @code{not} is identical to @code{null}, and we recommend +using the name @code{null} if you are testing for an empty list. +@end defun + +@defspec and conditions@dots{} +The @code{and} special form tests whether all the @var{conditions} are +true. It works by evaluating the @var{conditions} one by one in the +order written. + +If any of the @var{conditions} evaluates to @code{nil}, then the result +of the @code{and} must be @code{nil} regardless of the remaining +@var{conditions}; so @code{and} returns right away, ignoring the +remaining @var{conditions}. + +If all the @var{conditions} turn out non-@code{nil}, then the value of +the last of them becomes the value of the @code{and} form. + +Here is an example. The first condition returns the integer 1, which is +not @code{nil}. Similarly, the second condition returns the integer 2, +which is not @code{nil}. The third condition is @code{nil}, so the +remaining condition is never evaluated. + +@example +@group +(and (print 1) (print 2) nil (print 3)) + @print{} 1 + @print{} 2 +@result{} nil +@end group +@end example + +Here is a more realistic example of using @code{and}: + +@example +@group +(if (and (consp foo) (eq (car foo) 'x)) + (message "foo is a list starting with x")) +@end group +@end example + +@noindent +Note that @code{(car foo)} is not executed if @code{(consp foo)} returns +@code{nil}, thus avoiding an error. + +@code{and} can be expressed in terms of either @code{if} or @code{cond}. +For example: + +@example +@group +(and @var{arg1} @var{arg2} @var{arg3}) +@equiv{} +(if @var{arg1} (if @var{arg2} @var{arg3})) +@equiv{} +(cond (@var{arg1} (cond (@var{arg2} @var{arg3})))) +@end group +@end example +@end defspec + +@defspec or conditions@dots{} +The @code{or} special form tests whether at least one of the +@var{conditions} is true. It works by evaluating all the +@var{conditions} one by one in the order written. + +If any of the @var{conditions} evaluates to a non-@code{nil} value, then +the result of the @code{or} must be non-@code{nil}; so @code{or} returns +right away, ignoring the remaining @var{conditions}. The value it +returns is the non-@code{nil} value of the condition just evaluated. + +If all the @var{conditions} turn out @code{nil}, then the @code{or} +expression returns @code{nil}. + +For example, this expression tests whether @code{x} is either 0 or +@code{nil}: + +@example +(or (eq x nil) (eq x 0)) +@end example + +Like the @code{and} construct, @code{or} can be written in terms of +@code{cond}. For example: + +@example +@group +(or @var{arg1} @var{arg2} @var{arg3}) +@equiv{} +(cond (@var{arg1}) + (@var{arg2}) + (@var{arg3})) +@end group +@end example + +You could almost write @code{or} in terms of @code{if}, but not quite: + +@example +@group +(if @var{arg1} @var{arg1} + (if @var{arg2} @var{arg2} + @var{arg3})) +@end group +@end example + +@noindent +This is not completely equivalent because it can evaluate @var{arg1} or +@var{arg2} twice. By contrast, @code{(or @var{arg1} @var{arg2} +@var{arg3})} never evaluates any argument more than once. +@end defspec + +@node Iteration +@section Iteration +@cindex iteration +@cindex recursion + + Iteration means executing part of a program repetitively. For +example, you might want to repeat some computation once for each element +of a list, or once for each integer from 0 to @var{n}. You can do this +in Emacs Lisp with the special form @code{while}: + +@defspec while condition forms@dots{} +@code{while} first evaluates @var{condition}. If the result is +non-@code{nil}, it evaluates @var{forms} in textual order. Then it +reevaluates @var{condition}, and if the result is non-@code{nil}, it +evaluates @var{forms} again. This process repeats until @var{condition} +evaluates to @code{nil}. + +There is no limit on the number of iterations that may occur. The loop +will continue until either @var{condition} evaluates to @code{nil} or +until an error or @code{throw} jumps out of it (@pxref{Nonlocal Exits}). + +The value of a @code{while} form is always @code{nil}. + +@example +@group +(setq num 0) + @result{} 0 +@end group +@group +(while (< num 4) + (princ (format "Iteration %d." num)) + (setq num (1+ num))) + @print{} Iteration 0. + @print{} Iteration 1. + @print{} Iteration 2. + @print{} Iteration 3. + @result{} nil +@end group +@end example + +If you would like to execute something on each iteration before the +end-test, put it together with the end-test in a @code{progn} as the +first argument of @code{while}, as shown here: + +@example +@group +(while (progn + (forward-line 1) + (not (looking-at "^$")))) +@end group +@end example + +@noindent +This moves forward one line and continues moving by lines until an empty +line is reached. +@end defspec + +@node Nonlocal Exits +@section Nonlocal Exits +@cindex nonlocal exits + + A @dfn{nonlocal exit} is a transfer of control from one point in a +program to another remote point. Nonlocal exits can occur in Emacs Lisp +as a result of errors; you can also use them under explicit control. +Nonlocal exits unbind all variable bindings made by the constructs being +exited. + +@menu +* Catch and Throw:: Nonlocal exits for the program's own purposes. +* Examples of Catch:: Showing how such nonlocal exits can be written. +* Errors:: How errors are signaled and handled. +* Cleanups:: Arranging to run a cleanup form if an error happens. +@end menu + +@node Catch and Throw +@subsection Explicit Nonlocal Exits: @code{catch} and @code{throw} + + Most control constructs affect only the flow of control within the +construct itself. The function @code{throw} is the exception to this +rule of normal program execution: it performs a nonlocal exit on +request. (There are other exceptions, but they are for error handling +only.) @code{throw} is used inside a @code{catch}, and jumps back to +that @code{catch}. For example: + +@example +@group +(catch 'foo + (progn + @dots{} + (throw 'foo t) + @dots{})) +@end group +@end example + +@noindent +The @code{throw} transfers control straight back to the corresponding +@code{catch}, which returns immediately. The code following the +@code{throw} is not executed. The second argument of @code{throw} is used +as the return value of the @code{catch}. + + The @code{throw} and the @code{catch} are matched through the first +argument: @code{throw} searches for a @code{catch} whose first argument +is @code{eq} to the one specified. Thus, in the above example, the +@code{throw} specifies @code{foo}, and the @code{catch} specifies the +same symbol, so that @code{catch} is applicable. If there is more than +one applicable @code{catch}, the innermost one takes precedence. + + Executing @code{throw} exits all Lisp constructs up to the matching +@code{catch}, including function calls. When binding constructs such as +@code{let} or function calls are exited in this way, the bindings are +unbound, just as they are when these constructs exit normally +(@pxref{Local Variables}). Likewise, @code{throw} restores the buffer +and position saved by @code{save-excursion} (@pxref{Excursions}), and +the narrowing status saved by @code{save-restriction} and the window +selection saved by @code{save-window-excursion} (@pxref{Window +Configurations}). It also runs any cleanups established with the +@code{unwind-protect} special form when it exits that form. + + The @code{throw} need not appear lexically within the @code{catch} +that it jumps to. It can equally well be called from another function +called within the @code{catch}. As long as the @code{throw} takes place +chronologically after entry to the @code{catch}, and chronologically +before exit from it, it has access to that @code{catch}. This is why +@code{throw} can be used in commands such as @code{exit-recursive-edit} +which throw back to the editor command loop (@pxref{Recursive Editing}). + +@cindex CL note---only @code{throw} in Emacs +@quotation +@b{Common Lisp note:} most other versions of Lisp, including Common Lisp, +have several ways of transferring control nonsequentially: @code{return}, +@code{return-from}, and @code{go}, for example. Emacs Lisp has only +@code{throw}. +@end quotation + +@defspec catch tag body@dots{} +@cindex tag on run time stack +@code{catch} establishes a return point for the @code{throw} function. The +return point is distinguished from other such return points by @var{tag}, +which may be any Lisp object. The argument @var{tag} is evaluated normally +before the return point is established. + +With the return point in effect, @code{catch} evaluates the forms of the +@var{body} in textual order. If the forms execute normally, without +error or nonlocal exit, the value of the last body form is returned from +the @code{catch}. + +If a @code{throw} is done within @var{body} specifying the same value +@var{tag}, the @code{catch} exits immediately; the value it returns is +whatever was specified as the second argument of @code{throw}. +@end defspec + +@defun throw tag value +The purpose of @code{throw} is to return from a return point previously +established with @code{catch}. The argument @var{tag} is used to choose +among the various existing return points; it must be @code{eq} to the value +specified in the @code{catch}. If multiple return points match @var{tag}, +the innermost one is used. + +The argument @var{value} is used as the value to return from that +@code{catch}. + +@kindex no-catch +If no return point is in effect with tag @var{tag}, then a @code{no-catch} +error is signaled with data @code{(@var{tag} @var{value})}. +@end defun + +@node Examples of Catch +@subsection Examples of @code{catch} and @code{throw} + + One way to use @code{catch} and @code{throw} is to exit from a doubly +nested loop. (In most languages, this would be done with a ``go to''.) +Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j} +varying from 0 to 9: + +@example +@group +(defun search-foo () + (catch 'loop + (let ((i 0)) + (while (< i 10) + (let ((j 0)) + (while (< j 10) + (if (foo i j) + (throw 'loop (list i j))) + (setq j (1+ j)))) + (setq i (1+ i)))))) +@end group +@end example + +@noindent +If @code{foo} ever returns non-@code{nil}, we stop immediately and return a +list of @var{i} and @var{j}. If @code{foo} always returns @code{nil}, the +@code{catch} returns normally, and the value is @code{nil}, since that +is the result of the @code{while}. + + Here are two tricky examples, slightly different, showing two +return points at once. First, two return points with the same tag, +@code{hack}: + +@example +@group +(defun catch2 (tag) + (catch tag + (throw 'hack 'yes))) +@result{} catch2 +@end group + +@group +(catch 'hack + (print (catch2 'hack)) + 'no) +@print{} yes +@result{} no +@end group +@end example + +@noindent +Since both return points have tags that match the @code{throw}, it goes to +the inner one, the one established in @code{catch2}. Therefore, +@code{catch2} returns normally with value @code{yes}, and this value is +printed. Finally the second body form in the outer @code{catch}, which is +@code{'no}, is evaluated and returned from the outer @code{catch}. + + Now let's change the argument given to @code{catch2}: + +@example +@group +(defun catch2 (tag) + (catch tag + (throw 'hack 'yes))) +@result{} catch2 +@end group + +@group +(catch 'hack + (print (catch2 'quux)) + 'no) +@result{} yes +@end group +@end example + +@noindent +We still have two return points, but this time only the outer one has the +tag @code{hack}; the inner one has the tag @code{quux} instead. Therefore, +the @code{throw} returns the value @code{yes} from the outer return point. +The function @code{print} is never called, and the body-form @code{'no} is +never evaluated. + +@node Errors +@subsection Errors +@cindex errors + + When Emacs Lisp attempts to evaluate a form that, for some reason, +cannot be evaluated, it @dfn{signals} an @dfn{error}. + + When an error is signaled, Emacs's default reaction is to print an +error message and terminate execution of the current command. This is +the right thing to do in most cases, such as if you type @kbd{C-f} at +the end of the buffer. + + In complicated programs, simple termination may not be what you want. +For example, the program may have made temporary changes in data +structures, or created temporary buffers which should be deleted before +the program is finished. In such cases, you would use +@code{unwind-protect} to establish @dfn{cleanup expressions} to be +evaluated in case of error. Occasionally, you may wish the program to +continue execution despite an error in a subroutine. In these cases, +you would use @code{condition-case} to establish @dfn{error handlers} to +recover control in case of error. + + Resist the temptation to use error handling to transfer control from +one part of the program to another; use @code{catch} and @code{throw} +instead. @xref{Catch and Throw}. + +@menu +* Signaling Errors:: How to report an error. +* Processing of Errors:: What Emacs does when you report an error. +* Handling Errors:: How you can trap errors and continue execution. +* Error Names:: How errors are classified for trapping them. +@end menu + +@node Signaling Errors +@subsubsection How to Signal an Error +@cindex signaling errors + + Most errors are signaled ``automatically'' within Lisp primitives +which you call for other purposes, such as if you try to take the +@sc{car} of an integer or move forward a character at the end of the +buffer; you can also signal errors explicitly with the functions +@code{error} and @code{signal}. + + Quitting, which happens when the user types @kbd{C-g}, is not +considered an error, but it is handled almost like an error. +@xref{Quitting}. + +@defun error format-string &rest args +This function signals an error with an error message constructed by +applying @code{format} (@pxref{String Conversion}) to +@var{format-string} and @var{args}. + +These examples show typical uses of @code{error}: + +@example +@group +(error "You have committed an error. + Try something else.") + @error{} You have committed an error. + Try something else. +@end group + +@group +(error "You have committed %d errors." 10) + @error{} You have committed 10 errors. +@end group +@end example + +@code{error} works by calling @code{signal} with two arguments: the +error symbol @code{error}, and a list containing the string returned by +@code{format}. + +If you want to use your own string as an error message verbatim, don't +just write @code{(error @var{string})}. If @var{string} contains +@samp{%}, it will be interpreted as a format specifier, with undesirable +results. Instead, use @code{(error "%s" @var{string})}. +@end defun + +@defun signal error-symbol data +This function signals an error named by @var{error-symbol}. The +argument @var{data} is a list of additional Lisp objects relevant to the +circumstances of the error. + +The argument @var{error-symbol} must be an @dfn{error symbol}---a symbol +bearing a property @code{error-conditions} whose value is a list of +condition names. This is how Emacs Lisp classifies different sorts of +errors. + +The number and significance of the objects in @var{data} depends on +@var{error-symbol}. For example, with a @code{wrong-type-arg} error, +there are two objects in the list: a predicate which describes the type +that was expected, and the object which failed to fit that type. +@xref{Error Names}, for a description of error symbols. + +Both @var{error-symbol} and @var{data} are available to any error +handlers which handle the error: @code{condition-case} binds a local +variable to a list of the form @code{(@var{error-symbol} .@: +@var{data})} (@pxref{Handling Errors}). If the error is not handled, +these two values are used in printing the error message. + +The function @code{signal} never returns (though in older Emacs versions +it could sometimes return). + +@smallexample +@group +(signal 'wrong-number-of-arguments '(x y)) + @error{} Wrong number of arguments: x, y +@end group + +@group +(signal 'no-such-error '("My unknown error condition.")) + @error{} peculiar error: "My unknown error condition." +@end group +@end smallexample +@end defun + +@cindex CL note---no continuable errors +@quotation +@b{Common Lisp note:} Emacs Lisp has nothing like the Common Lisp +concept of continuable errors. +@end quotation + +@node Processing of Errors +@subsubsection How Emacs Processes Errors + +When an error is signaled, @code{signal} searches for an active +@dfn{handler} for the error. A handler is a sequence of Lisp +expressions designated to be executed if an error happens in part of the +Lisp program. If the error has an applicable handler, the handler is +executed, and control resumes following the handler. The handler +executes in the environment of the @code{condition-case} which +established it; all functions called within that @code{condition-case} +have already been exited, and the handler cannot return to them. + +If there is no applicable handler for the error, the current command is +terminated and control returns to the editor command loop, because the +command loop has an implicit handler for all kinds of errors. The +command loop's handler uses the error symbol and associated data to +print an error message. + +@cindex @code{debug-on-error} use +An error that has no explicit handler may call the Lisp debugger. The +debugger is enabled if the variable @code{debug-on-error} (@pxref{Error +Debugging}) is non-@code{nil}. Unlike error handlers, the debugger runs +in the environment of the error, so that you can examine values of +variables precisely as they were at the time of the error. + +@node Handling Errors +@subsubsection Writing Code to Handle Errors +@cindex error handler +@cindex handling errors + + The usual effect of signaling an error is to terminate the command +that is running and return immediately to the Emacs editor command loop. +You can arrange to trap errors occurring in a part of your program by +establishing an error handler, with the special form +@code{condition-case}. A simple example looks like this: + +@example +@group +(condition-case nil + (delete-file filename) + (error nil)) +@end group +@end example + +@noindent +This deletes the file named @var{filename}, catching any error and +returning @code{nil} if an error occurs. + + The second argument of @code{condition-case} is called the +@dfn{protected form}. (In the example above, the protected form is a +call to @code{delete-file}.) The error handlers go into effect when +this form begins execution and are deactivated when this form returns. +They remain in effect for all the intervening time. In particular, they +are in effect during the execution of subroutines called by this form, +and their subroutines, and so on. This is a good thing, since, strictly +speaking, errors can be signaled only by Lisp primitives (including +@code{signal} and @code{error}) called by the protected form, not by the +protected form itself. + + The arguments after the protected form are handlers. Each handler +lists one or more @dfn{condition names} (which are symbols) to specify +which errors it will handle. The error symbol specified when an error +is signaled also defines a list of condition names. A handler applies +to an error if they have any condition names in common. In the example +above, there is one handler, and it specifies one condition name, +@code{error}, which covers all errors. + + The search for an applicable handler checks all the established handlers +starting with the most recently established one. Thus, if two nested +@code{condition-case} forms offer to handle the same error, the inner of +the two will actually handle it. + + When an error is handled, control returns to the handler. Before this +happens, Emacs unbinds all variable bindings made by binding constructs +that are being exited and executes the cleanups of all +@code{unwind-protect} forms that are exited. Once control arrives at +the handler, the body of the handler is executed. + + After execution of the handler body, execution continues by returning +from the @code{condition-case} form. Because the protected form is +exited completely before execution of the handler, the handler cannot +resume execution at the point of the error, nor can it examine variable +bindings that were made within the protected form. All it can do is +clean up and proceed. + + @code{condition-case} is often used to trap errors that are +predictable, such as failure to open a file in a call to +@code{insert-file-contents}. It is also used to trap errors that are +totally unpredictable, such as when the program evaluates an expression +read from the user. + + Error signaling and handling have some resemblance to @code{throw} and +@code{catch}, but they are entirely separate facilities. An error +cannot be caught by a @code{catch}, and a @code{throw} cannot be handled +by an error handler (though using @code{throw} when there is no suitable +@code{catch} signals an error which can be handled). + +@defspec condition-case var protected-form handlers@dots{} +This special form establishes the error handlers @var{handlers} around +the execution of @var{protected-form}. If @var{protected-form} executes +without error, the value it returns becomes the value of the +@code{condition-case} form; in this case, the @code{condition-case} has +no effect. The @code{condition-case} form makes a difference when an +error occurs during @var{protected-form}. + +Each of the @var{handlers} is a list of the form @code{(@var{conditions} +@var{body}@dots{})}. Here @var{conditions} is an error condition name +to be handled, or a list of condition names; @var{body} is one or more +Lisp expressions to be executed when this handler handles an error. +Here are examples of handlers: + +@smallexample +@group +(error nil) + +(arith-error (message "Division by zero")) + +((arith-error file-error) + (message + "Either division by zero or failure to open a file")) +@end group +@end smallexample + +Each error that occurs has an @dfn{error symbol} which describes what +kind of error it is. The @code{error-conditions} property of this +symbol is a list of condition names (@pxref{Error Names}). Emacs +searches all the active @code{condition-case} forms for a handler which +specifies one or more of these condition names; the innermost matching +@code{condition-case} handles the error. Within this +@code{condition-case}, the first applicable handler handles the error. + +After executing the body of the handler, the @code{condition-case} +returns normally, using the value of the last form in the handler body +as the overall value. + +The argument @var{var} is a variable. @code{condition-case} does not +bind this variable when executing the @var{protected-form}, only when it +handles an error. At that time, it binds @var{var} locally to a list of +the form @code{(@var{error-symbol} . @var{data})}, giving the +particulars of the error. The handler can refer to this list to decide +what to do. For example, if the error is for failure opening a file, +the file name is the second element of @var{data}---the third element of +@var{var}. + +If @var{var} is @code{nil}, that means no variable is bound. Then the +error symbol and associated data are not available to the handler. +@end defspec + +@cindex @code{arith-error} example +Here is an example of using @code{condition-case} to handle the error +that results from dividing by zero. The handler prints out a warning +message and returns a very large number. + +@smallexample +@group +(defun safe-divide (dividend divisor) + (condition-case err + ;; @r{Protected form.} + (/ dividend divisor) + ;; @r{The handler.} + (arith-error ; @r{Condition.} + (princ (format "Arithmetic error: %s" err)) + 1000000))) +@result{} safe-divide +@end group + +@group +(safe-divide 5 0) + @print{} Arithmetic error: (arith-error) +@result{} 1000000 +@end group +@end smallexample + +@noindent +The handler specifies condition name @code{arith-error} so that it will handle only division-by-zero errors. Other kinds of errors will not be handled, at least not by this @code{condition-case}. Thus, + +@smallexample +@group +(safe-divide nil 3) + @error{} Wrong type argument: integer-or-marker-p, nil +@end group +@end smallexample + + Here is a @code{condition-case} that catches all kinds of errors, +including those signaled with @code{error}: + +@smallexample +@group +(setq baz 34) + @result{} 34 +@end group + +@group +(condition-case err + (if (eq baz 35) + t + ;; @r{This is a call to the function @code{error}.} + (error "Rats! The variable %s was %s, not 35." 'baz baz)) + ;; @r{This is the handler; it is not a form.} + (error (princ (format "The error was: %s" err)) + 2)) +@print{} The error was: (error "Rats! The variable baz was 34, not 35.") +@result{} 2 +@end group +@end smallexample + +@node Error Names +@subsubsection Error Symbols and Condition Names +@cindex error symbol +@cindex error name +@cindex condition name +@cindex user-defined error +@kindex error-conditions + + When you signal an error, you specify an @dfn{error symbol} to specify +the kind of error you have in mind. Each error has one and only one +error symbol to categorize it. This is the finest classification of +errors defined by the Emacs Lisp language. + + These narrow classifications are grouped into a hierarchy of wider +classes called @dfn{error conditions}, identified by @dfn{condition +names}. The narrowest such classes belong to the error symbols +themselves: each error symbol is also a condition name. There are also +condition names for more extensive classes, up to the condition name +@code{error} which takes in all kinds of errors. Thus, each error has +one or more condition names: @code{error}, the error symbol if that +is distinct from @code{error}, and perhaps some intermediate +classifications. + + In order for a symbol to be an error symbol, it must have an +@code{error-conditions} property which gives a list of condition names. +This list defines the conditions which this kind of error belongs to. +(The error symbol itself, and the symbol @code{error}, should always be +members of this list.) Thus, the hierarchy of condition names is +defined by the @code{error-conditions} properties of the error symbols. + + In addition to the @code{error-conditions} list, the error symbol +should have an @code{error-message} property whose value is a string to +be printed when that error is signaled but not handled. If the +@code{error-message} property exists, but is not a string, the error +message @samp{peculiar error} is used. +@cindex peculiar error + + Here is how we define a new error symbol, @code{new-error}: + +@example +@group +(put 'new-error + 'error-conditions + '(error my-own-errors new-error)) +@result{} (error my-own-errors new-error) +@end group +@group +(put 'new-error 'error-message "A new error") +@result{} "A new error" +@end group +@end example + +@noindent +This error has three condition names: @code{new-error}, the narrowest +classification; @code{my-own-errors}, which we imagine is a wider +classification; and @code{error}, which is the widest of all. + + Naturally, Emacs will never signal @code{new-error} on its own; only +an explicit call to @code{signal} (@pxref{Errors}) in your code can do +this: + +@example +@group +(signal 'new-error '(x y)) + @error{} A new error: x, y +@end group +@end example + + This error can be handled through any of the three condition names. +This example handles @code{new-error} and any other errors in the class +@code{my-own-errors}: + +@example +@group +(condition-case foo + (bar nil t) + (my-own-errors nil)) +@end group +@end example + + The significant way that errors are classified is by their condition +names---the names used to match errors with handlers. An error symbol +serves only as a convenient way to specify the intended error message +and list of condition names. It would be cumbersome to give +@code{signal} a list of condition names rather than one error symbol. + + By contrast, using only error symbols without condition names would +seriously decrease the power of @code{condition-case}. Condition names +make it possible to categorize errors at various levels of generality +when you write an error handler. Using error symbols alone would +eliminate all but the narrowest level of classification. + + @xref{Standard Errors}, for a list of all the standard error symbols +and their conditions. + +@node Cleanups +@subsection Cleaning Up from Nonlocal Exits + + The @code{unwind-protect} construct is essential whenever you +temporarily put a data structure in an inconsistent state; it permits +you to ensure the data are consistent in the event of an error or throw. + +@defspec unwind-protect body cleanup-forms@dots{} +@cindex cleanup forms +@cindex protected forms +@cindex error cleanup +@cindex unwinding +@code{unwind-protect} executes the @var{body} with a guarantee that the +@var{cleanup-forms} will be evaluated if control leaves @var{body}, no +matter how that happens. The @var{body} may complete normally, or +execute a @code{throw} out of the @code{unwind-protect}, or cause an +error; in all cases, the @var{cleanup-forms} will be evaluated. + +If the @var{body} forms finish normally, @code{unwind-protect} returns +the value of the last @var{body} form, after it evaluates the +@var{cleanup-forms}. If the @var{body} forms do not finish, +@code{unwind-protect} does not return any value in the normal sense. + +Only the @var{body} is actually protected by the @code{unwind-protect}. +If any of the @var{cleanup-forms} themselves exits nonlocally (e.g., via +a @code{throw} or an error), @code{unwind-protect} is @emph{not} +guaranteed to evaluate the rest of them. If the failure of one of the +@var{cleanup-forms} has the potential to cause trouble, then protect it +with another @code{unwind-protect} around that form. + +The number of currently active @code{unwind-protect} forms counts, +together with the number of local variable bindings, against the limit +@code{max-specpdl-size} (@pxref{Local Variables}). +@end defspec + + For example, here we make an invisible buffer for temporary use, and +make sure to kill it before finishing: + +@smallexample +@group +(save-excursion + (let ((buffer (get-buffer-create " *temp*"))) + (set-buffer buffer) + (unwind-protect + @var{body} + (kill-buffer buffer)))) +@end group +@end smallexample + +@noindent +You might think that we could just as well write @code{(kill-buffer +(current-buffer))} and dispense with the variable @code{buffer}. +However, the way shown above is safer, if @var{body} happens to get an +error after switching to a different buffer! (Alternatively, you could +write another @code{save-excursion} around the body, to ensure that the +temporary buffer becomes current in time to kill it.) + +@findex ftp-login + Here is an actual example taken from the file @file{ftp.el}. It creates +a process (@pxref{Processes}) to try to establish a connection to a remote +machine. As the function @code{ftp-login} is highly susceptible to +numerous problems which the writer of the function cannot anticipate, it is +protected with a form that guarantees deletion of the process in the event +of failure. Otherwise, Emacs might fill up with useless subprocesses. + +@smallexample +@group +(let ((win nil)) + (unwind-protect + (progn + (setq process (ftp-setup-buffer host file)) + (if (setq win (ftp-login process host user password)) + (message "Logged in") + (error "Ftp login failed"))) + (or win (and process (delete-process process))))) +@end group +@end smallexample + + This example actually has a small bug: if the user types @kbd{C-g} to +quit, and the quit happens immediately after the function +@code{ftp-setup-buffer} returns but before the variable @code{process} is +set, the process will not be killed. There is no easy way to fix this bug, +but at least it is very unlikely. + + Here is another example which uses @code{unwind-protect} to make sure +to kill a temporary buffer. In this example, the value returned by +@code{unwind-protect} is used. + +@example +(defun shell-command-string (cmd) + "Return the output of the shell command CMD, as a string." + (save-excursion + (set-buffer (generate-new-buffer " OS*cmd")) + (shell-command cmd t) + (unwind-protect + (buffer-string) + (kill-buffer (current-buffer))))) +@end example
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/intro.texi Mon Mar 21 17:36:52 1994 +0000 @@ -0,0 +1,867 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/intro + +@node Copying, Introduction, Top, Top +@comment node-name, next, previous, up +@unnumbered GNU GENERAL PUBLIC LICENSE +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +675 Mass Ave, Cambridge, MA 02139, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@unnumberedsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software---to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate 0 +@item +This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The ``Program'', below, +refers to any such program or work, and a ``work based on the Program'' +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary way, to print or display an +announcement including an appropriate copyright notice and a +notice that there is no warranty (or else, saying that you provide +a warranty) and that users may redistribute the program under +these conditions, and telling the user how to view a copy of this +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + +@item +Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and ``any +later version'', you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + +@item +If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + +@iftex +@heading NO WARRANTY +@end iftex +@ifinfo +@center NO WARRANTY +@end ifinfo + +@item +BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU@. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@unnumberedsec How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and an idea of what it does.} +Copyright (C) 19@var{yy} @var{name of author} + +This program is free software; you can redistribute it and/or +modify it under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 +of the License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + +@smallexample +Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} +Gnomovision comes with ABSOLUTELY NO WARRANTY; for details +type `show w'. This is free software, and you are welcome +to redistribute it under certain conditions; type `show c' +for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{show c}; they could even be mouse-clicks or menu items---whatever +suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the program, if +necessary. Here is a sample; alter the names: + +@smallexample +@group +Yoyodyne, Inc., hereby disclaims all copyright +interest in the program `Gnomovision' +(which makes passes at compilers) written +by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end group +@end smallexample + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. + +@node Introduction, Types of Lisp Object, Copying, Top +@chapter Introduction + + Most of the GNU Emacs text editor is written in the programming +language called Emacs Lisp. You can write new code in Emacs Lisp and +install it as an extension to the editor. However, Emacs Lisp is more +than a mere ``extension language''; it is a full computer programming +language in its own right. You can use it as you would any other +programming language. + + Because Emacs Lisp is designed for use in an editor, it has special +features for scanning and parsing text as well as features for handling +files, buffers, displays, subprocesses, and so on. Emacs Lisp is +closely integrated with the editing facilities; thus, editing commands +are functions that can also conveniently be called from Lisp programs, +and parameters for customization are ordinary Lisp variables. + + This manual describes Emacs Lisp, presuming considerable familiarity +with the use of Emacs for editing. (See @cite{The GNU Emacs Manual}, +for this basic information.) Generally speaking, the earlier chapters +describe features of Emacs Lisp that have counterparts in many +programming languages, and later chapters describe features that are +peculiar to Emacs Lisp or relate specifically to editing. + + This is edition 2.3. + +@menu +* Caveats:: Flaws and a request for help. +* Lisp History:: Emacs Lisp is descended from Maclisp. +* Conventions:: How the manual is formatted. +* Acknowledgements:: The authors, editors, and sponsors of this manual. +@end menu + +@node Caveats +@section Caveats + + This manual has gone through numerous drafts. It is nearly complete +but not flawless. There are a few sections which are not included, +either because we consider them secondary (such as most of the +individual modes) or because they are yet to be written. + + Because we are not able to deal with them completely, we have left out +several parts intentionally. This includes most information about usage +on VMS. + + The manual should be fully correct in what it does cover, and it is +therefore open to criticism on anything it says---from specific examples +and descriptive text, to the ordering of chapters and sections. If +something is confusing, or you find that you have to look at the sources +or experiment to learn something not covered in the manual, then perhaps +the manual should be fixed. Please let us know. + +@iftex + As you use the manual, we ask that you mark pages with corrections so +you can later look them up and send them in. If you think of a simple, +real life example for a function or group of functions, please make an +effort to write it up and send it in. Please reference any comments to +the chapter name, section name, and function name, as appropriate, since +page numbers and chapter and section numbers will change. Also state +the number of the edition which you are criticizing. +@end iftex +@ifinfo + +As you use this manual, we ask that you send corrections as soon as you +find them. If you think of a simple, real life example for a function +or group of functions, please make an effort to write it up and send it +in. Please reference any comments to the node name and function or +variable name, as appropriate. Also state the number of the edition +which you are criticizing. +@end ifinfo + +Please mail comments and corrections to + +@example +bug-lisp-manual@@prep.ai.mit.edu +@end example + +@noindent +We let mail to this list accumulate unread until someone decides to +apply the corrections. Months, and sometimes years, go by between +updates. So please attach no significance to the lack of a reply---your +mail @emph{will} be acted on in due time. If you want to contact the +Emacs maintainers more quickly, send mail to +@code{bug-gnu-emacs@@prep.ai.mit.edu}. + +@display + --Bil Lewis, Dan LaLiberte, Richard Stallman +@end display + +@node Lisp History +@section Lisp History +@cindex Lisp history + + Lisp (LISt Processing language) was first developed in the late 1950s +at the Massachusetts Institute of Technology for research in artificial +intelligence. The great power of the Lisp language makes it superior +for other purposes as well, such as writing editing commands. + +@cindex Maclisp +@cindex Common Lisp + Dozens of Lisp implementations have been built over the years, each +with its own idiosyncrasies. Many of them were inspired by Maclisp, +which was written in the 1960's at MIT's Project MAC. Eventually the +implementors of the descendents of Maclisp came together and developed a +standard for Lisp systems, called Common Lisp. + + GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common +Lisp. If you know Common Lisp, you will notice many similarities. +However, many of the features of Common Lisp have been omitted or +simplified in order to reduce the memory requirements of GNU Emacs. +Sometimes the simplifications are so drastic that a Common Lisp user +might be very confused. We will occasionally point out how GNU Emacs +Lisp differs from Common Lisp. If you don't know Common Lisp, don't +worry about it; this manual is self-contained. + +@node Conventions +@section Conventions + +This section explains the notational conventions that are used in this +manual. You may want to skip this section and refer back to it later. + +@menu +* Some Terms:: Explanation of terms we use in this manual. +* nil and t:: How the symbols @code{nil} and @code{t} are used. +* Evaluation Notation:: The format we use for examples of evaluation. +* Printing Notation:: The format we use for examples that print output. +* Error Messages:: The format we use for examples of errors. +* Buffer Text Notation:: The format we use for buffer contents in examples. +* Format of Descriptions:: Notation for describing functions, variables, etc. +@end menu + +@node Some Terms +@subsection Some Terms + + Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp +printer'' are used to refer to those routines in Lisp that convert +textual representations of Lisp objects into actual objects, and vice +versa. @xref{Printed Representation}, for more details. You, the +person reading this manual, are thought of as ``the programmer'' and are +addressed as ``you''. ``The user'' is the person who uses Lisp programs +including those you write. + +@cindex fonts + Examples of Lisp code appear in this font or form: @code{(list 1 2 +3)}. Names that represent arguments or metasyntactic variables appear +in this font or form: @var{first-number}. + +@node nil and t +@subsection @code{nil} and @code{t} +@cindex @code{nil}, uses of +@cindex truth value +@cindex boolean +@cindex false + + In Lisp, the symbol @code{nil} is overloaded with three meanings: it +is a symbol with the name @samp{nil}; it is the logical truth value +@var{false}; and it is the empty list---the list of zero elements. +When used as a variable, @code{nil} always has the value @code{nil}. + + As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are +identical: they stand for the same object, the symbol @code{nil}. The +different ways of writing the symbol are intended entirely for human +readers. After the Lisp reader has read either @samp{()} or @samp{nil}, +there is no way to determine which representation was actually written +by the programmer. + + In this manual, we use @code{()} when we wish to emphasize that it +means the empty list, and we use @code{nil} when we wish to emphasize +that it means the truth value @var{false}. That is a good convention to use +in Lisp programs also. + +@example +(cons 'foo ()) ; @r{Emphasize the empty list} +(not nil) ; @r{Emphasize the truth value @var{false}} +@end example + +@cindex @code{t} and truth +@cindex true + In contexts where a truth value is expected, any non-@code{nil} value +is considered to be @var{true}. However, @code{t} is the preferred way +to represent the truth value @var{true}. When you need to choose a +value which represents @var{true}, and there is no other basis for +choosing, use @code{t}. The symbol @code{t} always has value @code{t}. + + In Emacs Lisp, @code{nil} and @code{t} are special symbols that always +evaluate to themselves. This is so that you do not need to quote them +to use them as constants in a program. An attempt to change their +values results in a @code{setting-constant} error. @xref{Accessing +Variables}. + +@node Evaluation Notation +@subsection Evaluation Notation +@cindex evaluation notation +@cindex documentation notation + + A Lisp expression that you can evaluate is called a @dfn{form}. +Evaluating a form always produces a result, which is a Lisp object. In +the examples in this manual, this is indicated with @samp{@result{}}: + +@example +(car '(1 2)) + @result{} 1 +@end example + +@noindent +You can read this as ``@code{(car '(1 2))} evaluates to 1''. + + When a form is a macro call, it expands into a new form for Lisp to +evaluate. We show the result of the expansion with +@samp{@expansion{}}. We may or may not show the actual result of the +evaluation of the expanded form. + +@example +(third '(a b c)) + @expansion{} (car (cdr (cdr '(a b c)))) + @result{} c +@end example + + Sometimes to help describe one form we show another form which +produces identical results. The exact equivalence of two forms is +indicated with @samp{@equiv{}}. + +@example +(make-sparse-keymap) @equiv{} (list 'keymap) +@end example + +@node Printing Notation +@subsection Printing Notation +@cindex printing notation + + Many of the examples in this manual print text when they are +evaluated. If you execute the code from an example in a Lisp +Interaction buffer (such as the buffer @samp{*scratch*}), the printed +text is inserted into the buffer. If you execute the example by other +means (such as by evaluating the function @code{eval-region}), it prints +text by displaying it in the echo area. You should be aware that text +displayed in the echo area is truncated to a single line. + + Examples in this manual indicate printed text with @samp{@print{}}, +irrespective of where that text goes. The value returned by evaluating +the form (here @code{bar}) follows on a separate line. + +@example +@group +(progn (print 'foo) (print 'bar)) + @print{} foo + @print{} bar + @result{} bar +@end group +@end example + +@node Error Messages +@subsection Error Messages +@cindex error message notation + + Some examples signal errors. This normally displays an error message +in the echo area. We show the error message on a line starting with +@samp{@error{}}. Note that @samp{@error{}} itself does not appear in +the echo area. + +@example +(+ 23 'x) +@error{} Wrong type argument: integer-or-marker-p, x +@end example + +@node Buffer Text Notation +@subsection Buffer Text Notation +@cindex buffer text notation + + Some examples show modifications to text in a buffer, with ``before'' +and ``after'' versions of the text. These examples show the contents of +the buffer in question between two lines of dashes containing the buffer +name. In addition, @samp{@point{}} indicates the location of point. +(The symbol for point, of course, is not part of the text in the buffer; +it indicates the place @emph{between} two characters where point is +located.) + +@example +---------- Buffer: foo ---------- +This is the @point{}contents of foo. +---------- Buffer: foo ---------- + +(insert "changed ") + @result{} nil +---------- Buffer: foo ---------- +This is the changed @point{}contents of foo. +---------- Buffer: foo ---------- +@end example + +@node Format of Descriptions +@subsection Format of Descriptions +@cindex description format + + Functions, variables, macros, commands, user options, and special +forms are described in this manual in a uniform format. The first +line of a description contains the name of the item followed by its +arguments, if any. +@ifinfo +The category---function, variable, or whatever---appears at the +beginning of the line. +@end ifinfo +@iftex +The category---function, variable, or whatever---is printed next to the +right margin. +@end iftex +The description follows on succeeding lines, sometimes with examples. + +@menu +* A Sample Function Description:: A description of an imaginary + function, @code{foo}. +* A Sample Variable Description:: A description of an imaginary + variable, + @code{electric-future-map}. +@end menu + +@node A Sample Function Description +@subsubsection A Sample Function Description +@cindex function descriptions +@cindex command descriptions +@cindex macro descriptions +@cindex special form descriptions + + In a function description, the name of the function being described +appears first. It is followed on the same line by a list of parameters. +The names used for the parameters are also used in the body of the +description. + + The appearance of the keyword @code{&optional} in the parameter list +indicates that the arguments for subsequent parameters may be omitted +(omitted parameters default to @code{nil}). Do not write +@code{&optional} when you call the function. + + The keyword @code{&rest} (which will always be followed by a single +parameter) indicates that any number of arguments can follow. The value +of the single following parameter will be a list of all these arguments. +Do not write @code{&rest} when you call the function. + + Here is a description of an imaginary function @code{foo}: + +@defun foo integer1 &optional integer2 &rest integers +The function @code{foo} subtracts @var{integer1} from @var{integer2}, +then adds all the rest of the arguments to the result. If @var{integer2} +is not supplied, then the number 19 is used by default. + +@example +(foo 1 5 3 9) + @result{} 16 +(foo 5) + @result{} 14 +@end example + +More generally, + +@example +(foo @var{w} @var{x} @var{y}@dots{}) +@equiv{} +(+ (- @var{x} @var{w}) @var{y}@dots{}) +@end example +@end defun + + Any parameter whose name contains the name of a type (e.g., +@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that +type. A plural of a type (such as @var{buffers}) often means a list of +objects of that type. Parameters named @var{object} may be of any type. +(@xref{Types of Lisp Object}, for a list of Emacs object types.) +Parameters with other sorts of names (e.g., @var{new-file}) are +discussed specifically in the description of the function. In some +sections, features common to parameters of several functions are +described at the beginning. + + @xref{Lambda Expressions}, for a more complete description of optional +and rest arguments. + + Command, macro, and special form descriptions have the same format, +but the word `Function' is replaced by `Command', `Macro', or `Special +Form', respectively. Commands are simply functions that may be called +interactively; macros process their arguments differently from functions +(the arguments are not evaluated), but are presented the same way. + + Special form descriptions use a more complex notation to specify +optional and repeated parameters because they can break the argument +list down into separate arguments in more complicated ways. +@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that @var{optional-arg} is +optional and @samp{@var{repeated-args}@dots{}} stands for zero or more +arguments. Parentheses are used when several arguments are grouped into +additional levels of list structure. Here is an example: + +@defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} +This imaginary special form implements a loop that executes the +@var{body} forms and then increments the variable @var{var} on each +iteration. On the first iteration, the variable has the value +@var{from}; on subsequent iterations, it is incremented by 1 (or by +@var{inc} if that is given). The loop exits before executing @var{body} +if @var{var} equals @var{to}. Here is an example: + +@example +(count-loop (i 0 10) + (prin1 i) (princ " ") + (prin1 (aref vector i)) (terpri)) +@end example + +If @var{from} and @var{to} are omitted, then @var{var} is bound to +@code{nil} before the loop begins, and the loop exits if @var{var} is +non-@code{nil} at the beginning of an iteration. Here is an example: + +@example +(count-loop (done) + (if (pending) + (fixit) + (setq done t))) +@end example + +In this special form, the arguments @var{from} and @var{to} are +optional, but must both be present or both absent. If they are present, +@var{inc} may optionally be specified as well. These arguments are +grouped with the argument @var{var} into a list, to distinguish them +from @var{body}, which includes all remaining elements of the form. +@end defspec + +@node A Sample Variable Description +@subsubsection A Sample Variable Description +@cindex variable descriptions +@cindex option descriptions + + A @dfn{variable} is a name that can hold a value. Although any +variable can be set by the user, certain variables that exist +specifically so that users can change them are called @dfn{user +options}. Ordinary variables and user options are described using a +format like that for functions except that there are no arguments. + + Here is a description of the imaginary @code{electric-future-map} +variable.@refill + +@defvar electric-future-map +The value of this variable is a full keymap used by Electric Command +Future mode. The functions in this map allow you to edit commands you +have not yet thought about executing. +@end defvar + + User option descriptions have the same format, but `Variable' is +replaced by `User Option'. + +@node Acknowledgements +@section Acknowledgements + + This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte, +Richard M. Stallman and Chris Welty, the volunteers of the GNU manual +group, in an effort extending over several years. Robert J. Chassell +helped to review and edit the manual, with the support of the Defense +Advanced Research Projects Agency, ARPA Order 6082, arranged by Warren +A. Hunt, Jr. of Computational Logic, Inc. + + Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom, +Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence +R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly +Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea, +Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki +Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe +Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland +McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson, +Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul +Rockwell, Per Starback, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, +Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty, +Dale Worley, Rusty Wright, and David D. Zuhn.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/lispref/loading.texi Mon Mar 21 17:36:52 1994 +0000 @@ -0,0 +1,582 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/loading +@node Loading, Byte Compilation, Macros, Top +@chapter Loading +@cindex loading +@cindex library +@cindex Lisp library + + Loading a file of Lisp code means bringing its contents into the Lisp +environment in the form of Lisp objects. Emacs finds and opens the +file, reads the text, evaluates each form, and then closes the file. + + The load functions evaluate all the expressions in a file just +as the @code{eval-current-buffer} function evaluates all the +expressions in a buffer. The difference is that the load functions +read and evaluate the text in the file as found on disk, not the text +in an Emacs buffer. + +@cindex top-level form + The loaded file must contain Lisp expressions, either as source code +or, optionally, as byte-compiled code. Each form in the file is called +a @dfn{top-level form}. There is no special format for the forms in a +loadable file; any form in a file may equally well be typed directly +into a buffer and evaluated there. (Indeed, most code is tested this +way.) Most often, the forms are function definitions and variable +definitions. + + A file containing Lisp code is often called a @dfn{library}. Thus, +the ``Rmail library'' is a file containing code for Rmail mode. +Similarly, a ``Lisp library directory'' is a directory of files +containing Lisp code. + +@menu +* How Programs Do Loading:: The @code{load} function and others. +* Autoload:: Setting up a function to autoload. +* Repeated Loading:: Precautions about loading a file twice. +* Features:: Loading a library if it isn't already loaded. +* Unloading:: How to ``unload'' a library that was loaded. +* Hooks for Loading:: Providing code to be run when + particular libraries are loaded. +@end menu + +@node How Programs Do Loading +@section How Programs Do Loading + + Emacs Lisp has several interfaces for loading. For example, +@code{autoload} creates a placeholder object for a function in a file; +trying to call the autoloading function loads the file to get the +function's real definition (@pxref{Autoload}). @code{require} loads a +file if it isn't already loaded (@pxref{Features}). Ultimately, all +these facilities call the @code{load} function to do the work. + +@defun load filename &optional missing-ok nomessage nosuffix +This function finds and opens a file of Lisp code, evaluates all the +forms in it, and closes the file. + +To find the file, @code{load} first looks for a file named +@file{@var{filename}.elc}, that is, for a file whose name is +@var{filename} with @samp{.elc} appended. If such a file exists, it is +loaded. If there is no file by that name, then @code{load} looks for a +file names @file{@var{filename}.el}. If that file exists, it is loaded. +Finally, if neither of those names is found, @code{load} looks for a +file named @var{filename} with nothing appended, and loads it if it +exists. (The @code{load} function is not clever about looking at +@var{filename}. In the perverse case of a file named @file{foo.el.el}, +evaluation of @code{(load "foo.el")} will indeed find it.) + +If the optional argument @var{nosuffix} is non-@code{nil}, then the +suffixes @samp{.elc} and @samp{.el} are not tried. In this case, you +must specify the precise file name you want. + +If @var{filename} is a relative file name, such as @file{foo} or +@file{baz/foo.bar}, @code{load} searches for the file using the variable +@code{load-path}. It appends @var{filename} to each of the directories +listed in @code{load-path}, and loads the first file it finds whose name +matches. The current default directory is tried only if it is specified +in @code{load-path}, where @code{nil} stands for the default directory. +@code{load} tries all three possible suffixes in the first directory in +@code{load-path}, then all three suffixes in the second directory, and +so on. + +If you get a warning that @file{foo.elc} is older than @file{foo.el}, it +means you should consider recompiling @file{foo.el}. @xref{Byte +Compilation}. + +Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear +in the echo area during loading unless @var{nomessage} is +non-@code{nil}. + +@cindex load errors +Any unhandled errors while loading a file terminate loading. If the +load was done for the sake of @code{autoload}, certain kinds of +top-level forms, those which define functions, are undone. + +@kindex file-error +If @code{load} can't find the file to load, then normally it signals the +error @code{file-error} (with @samp{Cannot open load file +@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then +@code{load} just returns @code{nil}. + +@code{load} returns @code{t} if the file loads successfully. +@end defun + +@ignore +@deffn Command load-file filename +This function loads the file @var{filename}. If @var{filename} is an +absolute file name, then it is loaded. If it is relative, then the +current default directory is assumed. @code{load-path} is not used, and +suffixes are not appended. Use this function if you wish to specify +the file to be loaded exactly. +@end deffn + +@deffn Command load-library library +This function loads the library named @var{library}. A library is +nothing more than a file that may be loaded as described earlier. This +function is identical to @code{load}, save that it reads a file name +interactively with completion. +@end deffn +@end ignore + +@defopt load-path +@cindex @code{EMACSLOADPATH} environment variable +The value of this variable is a list of directories to search when +loading files with @code{load}. Each element is a string (which must be +a directory name) or @code{nil} (which stands for the current working +directory). The value of @code{load-path} is initialized from the +environment variable @code{EMACSLOADPATH}, if that exists; otherwise its +default value is specified in @file{emacs/src/paths.h} when Emacs is +built. + +The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH}; +@samp{:} separates directory names, and @samp{.} is used for the current +default directory. Here is an example of how to set your +@code{EMACSLOADPATH} variable from a @code{csh} @file{.login} file: + +@c This overfull hbox is OK. --rjc 16mar92 +@smallexample +setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp +@end smallexample + +Here is how to set it using @code{sh}: + +@smallexample +export EMACSLOADPATH +EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp +@end smallexample + +Here is an example of code you can place in a @file{.emacs} file to add +several directories to the front of your default @code{load-path}: + +@smallexample +(setq load-path + (append (list nil "/user/bil/emacs" + "/usr/local/lisplib" + (expand-file-name "~/emacs")) + load-path)) +@end smallexample + +@c Wordy to rid us of an overfull hbox. --rjc 15mar92 +@noindent +In this example, the path searches the current working directory first, +followed then by the @file{/user/bil/emacs} directory and then by +the @file{/usr/local/lisplib} directory, +which are then followed by the standard directories for Lisp code. + +The command line options @samp{-l} or @samp{-load} specify Lispa library +to load. Since this file might be in the current directory, Emacs 18 +temporarily adds the current directory to the front of @code{load-path} +so the file can be found there. Newer Emacs versions also find such +files in the current directory, but without altering @code{load-path}. +@end defopt + +@defvar load-in-progress +This variable is non-@code{nil} if Emacs is in the process of loading a +file, and it is @code{nil} otherwise. This is how @code{defun} and +@code{provide} determine whether a load is in progress, so that their +effect can be undone if the load fails. +@end defvar + + To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}. + +@node Autoload +@section Autoload +@cindex autoload + + The @dfn{autoload} facility allows you to make a function or macro +available but put off loading its actual definition. The first call to +the function automatically reads the proper file to install the real +definition and other associated code, then runs the real definition +as if it had been loaded all along. + + There are two ways to set up an autoloaded function: by calling +@code{autoload}, and by writing a special ``magic'' comment in the +source before the real definition. @code{autoload} is the low-level +primitive for autoloading; any Lisp program can call @code{autoload} at +any time. Magic comments do nothing on their own; they serve as a guide +for the command @code{update-file-autoloads}, which constructs calls to +@code{autoload} and arranges to execute them when Emacs is built. Magic +comments are the most convenient way to make a function autoload, but +only for packages installed along with Emacs. + +@defun autoload symbol filename &optional docstring interactive type +This function defines the function (or macro) named @var{symbol} so as +to load automatically from @var{filename}. The string @var{filename} +specifies the file to load to get the real definition of @var{function}. + +The argument @var{docstring} is the documentation string for the +function. Normally, this is the identical to the documentation string +in the function definition itself. Specifying the documentation string +in the call to @code{autoload} makes it possible to look at the +documentation without loading the function's real definition. + +If @var{interactive} is non-@code{nil}, then the function can be called +interactively. This lets completion in @kbd{M-x} work without loading +the function's real definition. The complete interactive specification +need not be given here; it's not needed unless the user actually calls +@var{function}, and when that happens, it's time to load the real +definition. + +You can autoload macros and keymaps as well as ordinary functions. +Specify @var{type} as @code{macro} if @var{function} is really a macro. +Specify @var{type} as @code{keymap} if @var{function} is really a +keymap. Various parts of Emacs need to know this information without +loading the real definition. + +@cindex function cell in autoload +If @var{symbol} already has a non-void function definition that is not +an autoload object, @code{autoload} does nothing and returns @code{nil}. +If the function cell of @var{symbol} is void, or is already an autoload +object, then it is defined as an autoload object like this: + +@example +(autoload @var{filename} @var{docstring} @var{interactive} @var{type}) +@end example + +For example, + +@example +(symbol-function 'run-prolog) + @result{} (autoload "prolog" 169681 t nil) +@end example + +@noindent +In this case, @code{"prolog"} is the name of the file to load, 169681 +refers to the documentation string in the @file{emacs/etc/DOC} file +(@pxref{Documentation Basics}), @code{t} means the function is +interactive, and @code{nil} that it is not a macro or a keymap. +@end defun + +@cindex autoload errors + The autoloaded file usually contains other definitions and may require +or provide one or more features. If the file is not completely loaded +(due to an error in the evaluation of its contents), any function +definitions or @code{provide} calls that occurred during the load are +undone. This is to ensure that the next attempt to call any function +autoloading from this file will try again to load the file. If not for +this, then some of the functions in the file might appear defined, but +they might fail to work properly for the lack of certain subroutines +defined later in the file and not loaded successfully. + + If the autoloaded file fails to define the desired Lisp function or +macro, then an error is signaled with data @code{"Autoloading failed to +define function @var{function-name}"}. + +@findex update-file-autoloads +@findex update-directory-autoloads + A magic autoload comment looks like @samp{;;;###autoload}, on a line +by itself, just before the real definition of the function in its +autoloadable source file. The command @kbd{M-x update-file-autoloads} +writes a corresponding @code{autoload} call into @file{loaddefs.el}. +Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}. +@kbd{M-x update-directory-autoloads} is even more powerful; it updates +autoloads for all files in the current directory. + + The same magic comment can copy any kind of form into +@file{loaddefs.el}. If the form following the magic comment is not a +function definition, it is copied verbatim. You can also use a magic +comment to execute a form at build time executing it when the file +itself is loaded. To do this, write the form @dfn{on the same line} as +the magic comment. Since it is in a comment, it does nothing when you +load the source file; but @code{update-file-autoloads} copies it to +@file{loaddefs.el}, where it is executed while building Emacs. + + The following example shows how @code{doctor} is prepared for +autoloading with a magic comment: + +@smallexample +;;;###autoload +(defun doctor () + "Switch to *doctor* buffer and start giving psychotherapy." + (interactive) + (switch-to-buffer "*doctor*") + (doctor-mode)) +@end smallexample + +@noindent +Here's what that produces in @file{loaddefs.el}: + +@smallexample +(autoload 'doctor "doctor" + "\ +Switch to *doctor* buffer and start giving psychotherapy." + t) +@end smallexample + +@noindent +The backslash and newline immediately following the double-quote are a +convention used only in the preloaded Lisp files such as +@file{loaddefs.el}; they tell @code{make-docfile} to put the +documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. + +@node Repeated Loading +@comment node-name, next, previous, up +@section Repeated Loading +@cindex repeated loading + + You may load one file more than once in an Emacs session. For +example, after you have rewritten and reinstalled a function definition +by editing it in a buffer, you may wish to return to the original +version; you can do this by reloading the file it came from. + + When you load or reload files, bear in mind that the @code{load} and +@code{load-library} functions automatically load a byte-compiled file +rather than a non-compiled file of similar name. If you rewrite a file +that you intend to save and reinstall, remember to byte-compile it if +necessary; otherwise you may find yourself inadvertently reloading the +older, byte-compiled file instead of your newer, non-compiled file! + + When writing the forms in a Lisp library file, keep in mind that the +file might be loaded more than once. For example, the choice of +@code{defvar} vs.@: @code{defconst} for defining a variable depends on +whether it is desirable to reinitialize the variable if the library is +reloaded: @code{defconst} does so, and @code{defvar} does not. +(@xref{Defining Variables}.) + + The simplest way to add an element to an alist is like this: + +@example +(setq minor-mode-alist + (cons '(leif-mode " Leif") minor-mode-alist)) +@end example + +@noindent +But this would add multiple elements if the library is reloaded. +To avoid the problem, write this: + +@example +(or (assq 'leif-mode minor-mode-alist) + (setq minor-mode-alist + (cons '(leif-mode " Leif") minor-mode-alist))) +@end example + + Occasionally you will want to test explicitly whether a library has +already been loaded. Here's one way to test, in a library, whether it +has been loaded before: + +@example +(if (not (boundp 'foo-was-loaded)) + @var{execute-first-time-only}) + +(setq foo-was-loaded t) +@end example + +@noindent +If the library uses @code{provide} to provide a named feature, you can +use @code{featurep} to test whether the library has been loaded. +@xref{Features}. + +@node Features +@section Features +@cindex features +@cindex requiring features +@cindex providing features + + @code{provide} and @code{require} are an alternative to +@code{autoload} for loading files automatically. They work in terms of +named @dfn{features}. Autoloading is triggered by calling a specific +function, but a feature is loaded the first time another program asks +for it by name. + + A feature name is a symbol that stands for a collection of functions, +variables, etc. The file that defines them should @dfn{provide} the +feature. Another program that uses them may ensure they are defined by +@dfn{requiring} the feature. This loads the file of definitions if it +hasn't been loaded already. + + To require the presence of a feature, call @code{require} with the +feature name as argument. @code{require} looks in the global variable +@code{features} to see whether the desired feature has been provided +already. If not, it loads the feature from the appropriate file. This +file should call @code{provide} at the top-level to add the feature to +@code{features}; if it fails to do so, @code{require} signals an error. +@cindex load error with require + + Features are normally named after the files that provide them, so that +@code{require} need not be given the file name. + + For example, in @file{emacs/lisp/prolog.el}, +the definition for @code{run-prolog} includes the following code: + +@smallexample +(defun run-prolog () + "Run an inferior Prolog process, input and output via buffer *prolog*." + (interactive) + (require 'comint) + (switch-to-buffer (make-comint "prolog" prolog-program-name)) + (inferior-prolog-mode)) +@end smallexample + +@noindent +The expression @code{(require 'comint)} loads the file @file{comint.el} +if it has not yet been loaded. This ensures that @code{make-comint} is +defined. + +The @file{comint.el} file contains the following top-level expression: + +@smallexample +(provide 'comint) +@end smallexample + +@noindent +This adds @code{comint} to the global @code{features} list, so that +@code{(require 'comint)} will henceforth know that nothing needs to be +done. + +@cindex byte-compiling @code{require} + When @code{require} is used at top-level in a file, it takes effect +when you byte-compile that file (@pxref{Byte Compilation}) as well as +when you load it. This is in case the required package contains macros +that the byte compiler must know about. + + Although top-level calls to @code{require} are evaluated during +byte compilation, @code{provide} calls are not. Therefore, you can +ensure that a file of definitions is loaded before it is byte-compiled +by including a @code{provide} followed by a @code{require} for the same +feature, as in the following example. + +@smallexample +@group +(provide 'my-feature) ; @r{Ignored by byte compiler,} + ; @r{evaluated by @code{load}.} +(require 'my-feature) ; @r{Evaluated by byte compiler.} +@end group +@end smallexample + +@defun provide feature +This function announces that @var{feature} is now loaded, or being +loaded, into the current Emacs session. This means that the facilities +associated with @var{feature} are or will be available for other Lisp +programs. + +The direct effect of calling @code{provide} is to add @var{feature} to +the front of the list @code{features} if it is not already in the list. +The argument @var{feature} must be a symbol. @code{provide} returns +@var{feature}. + +@smallexample +features + @result{} (bar bish) + +(provide 'foo) + @result{} foo +features + @result{} (foo bar bish) +@end smallexample + +If the file isn't completely loaded, due to an error in the evaluating +its contents, any function definitions or @code{provide} calls that +occurred during the load are undone. @xref{Autoload}. +@end defun + +@defun require feature &optional filename +This function checks whether @var{feature} is present in the current +Emacs session (using @code{(featurep @var{feature})}; see below). If it +is not, then @code{require} loads @var{filename} with @code{load}. If +@var{filename} is not supplied, then the name of the symbol +@var{feature} is used as the file name to load. + +If loading the file fails to provide @var{feature}, @code{require} +signals an error, @samp{Required feature @var{feature} was not +provided}. +@end defun + +@defun featurep feature +This function returns @code{t} if @var{feature} has been provided in the +current Emacs session (i.e., @var{feature} is a member of +@code{features}.) +@end defun + +@defvar features +The value of this variable is a list of symbols that are the features +loaded in the current Emacs session. Each symbol was put in this list +with a call to @code{provide}. The order of the elements in the +@code{features} list is not significant. +@end defvar + +@node Unloading +@section Unloading +@cindex unloading + +@c Emacs 19 feature + You can discard the functions and variables loaded by a library to +reclaim memory for other Lisp objects. To do this, use the function +@code{unload-feature}: + +@deffn Command unload-feature feature +This command unloads the library that provided feature @var{feature}. +It undefines all functions and variables defined with @code{defvar}, +@code{defmacro}, @code{defconst}, @code{defsubst} and @code{defalias} by +that library. It then restores any autoloads associated with those +symbols. +@end deffn + + The @code{unload-feature} function is written in Lisp; its actions are +based on the variable @code{load-history}. + +@defvar load-history +This variable's value is an alist connecting library names with the +names of functions and variables they define, the features they provide, +and the features they require. + +Each element is a list and describes one library. The @sc{car} of the +list is the name of the library, as a string. The rest of the list is +composed of these kinds of objects: + +@itemize @bullet +@item +Symbols, which were defined as functions or variables. +@item +Lists of the form @code{(require . @var{feature})} indicating +features that were required. +@item +Lists of the form @code{(provide . @var{feature})} indicating +features that were provided. +@end itemize + +The value of @code{load-history} may have one element whose @sc{car} is +@code{nil}. This element describes definitions made with +@code{eval-buffer} on a buffer that is not visiting a file. +@end defvar + + The command @code{eval-region} updates @code{load-history}, but does so +by adding the symbols defined to the element for the file being visited, +rather than replacing that element. + +@node Hooks for Loading +@section Hooks for Loading +@cindex loading hooks +@cindex hooks for loading + +You can ask for code to be executed if and when a particular library is +loaded, by calling @code{eval-after-load}. + +@defun eval-after-load library form +This function arranges to evaluate @var{form} at the end of loading the +library @var{library}, if and when @var{library} is loaded. + +The library name @var{library} must exactly match the argument of +@code{load}. To get the proper results when an installed library is +found by searching @code{load-path}, you should not include any +directory names in @var{library}. + +An error in @var{form} does not undo the load, but does prevent +execution of the rest of @var{form}. +@end defun + +@defvar after-load-alist +An alist of expressions to evaluate if and when particular libraries are +loaded. Each element looks like this: + +@example +(@var{filename} @var{forms}@dots{}) +@end example + +The function @code{load} checks @code{after-load-alist} in order to +implement @code{eval-after-load}. +@end defvar + +@c Emacs 19 feature