@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/control
@node Control Structures, Variables, Evaluation, Top
@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
+We control the order of execution of these 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.
level in a file of Lisp code---the forms are executed in the order
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}.
+function evaluates first @var{a} and then @var{b}. The result of
+evaluating @var{b} becomes the value of the function.
Explicit control structures make possible an order of execution other
than sequential.
@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.
+and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in
+that order. These forms are called the @dfn{body} of the @code{progn} form.
The value of the last form in the body becomes the value of the entire
-@code{progn}.
+@code{progn}. @code{(progn)} returns @code{nil}.
@cindex implicit @code{progn}
In the early days of Lisp, @code{progn} was the only way to execute
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 an @code{unwind-protect}, @code{and},
+As a result, @code{progn} is not used as much as it was many years ago.
+It is needed now most often inside an @code{unwind-protect}, @code{and},
@code{or}, or in the @var{then}-part of an @code{if}.
@defspec progn forms@dots{}
@end example
@end defspec
-@tindex when
@defmac when condition then-forms@dots{}
This is a variant of @code{if} where there are no @var{else-forms},
and possibly several @var{then-forms}. In particular,
@end example
@end defmac
-@tindex condition
@defmac unless condition forms@dots{}
This is a variant of @code{if} where there is no @var{then-form}:
@example
@group
+(setq a 5)
(cond ((eq a 'hack) 'foo)
(t "default"))
@result{} "default"
@end example
@noindent
-This expression is a @code{cond} which returns @code{foo} if the value
-of @code{a} is @code{hack}, and returns the string @code{"default"} otherwise.
+This @code{cond} expression returns @code{foo} if the value of @code{a}
+is @code{hack}, and returns the string @code{"default"} otherwise.
@end defspec
Any conditional construct can be expressed with @code{cond} or with
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}.
+@var{conditions}; so @code{and} returns @code{nil} 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.
+the last of them becomes the value of the @code{and} form. Just
+@code{(and)}, with no @var{conditions}, returns @code{t}, appropriate
+because all the @var{conditions} turned out non-@code{nil}. (Think
+about it; which one did not?)
Here is an example. The first condition returns the integer 1, which is
not @code{nil}. Similarly, the second condition returns the integer 2,
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}.
+expression returns @code{nil}. Just @code{(or)}, with no
+@var{conditions}, returns @code{nil}, appropriate because all the
+@var{conditions} turned out @code{nil}. (Think about it; which one
+did not?)
-For example, this expression tests whether @code{x} is either 0 or
-@code{nil}:
+For example, this expression tests whether @code{x} is either
+@code{nil} or the integer zero:
@example
(or (eq x nil) (eq x 0))
@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:
+To write a ``repeat...until'' loop, which will execute something on each
+iteration and then do the end-test, put the body followed by the
+end-test in a @code{progn} as the first argument of @code{while}, as
+shown here:
@example
@group
@noindent
This moves forward one line and continues moving by lines until it
-reaches an empty. It is unusual in that the @code{while} has no body,
-just the end test (which also does the real work of moving point).
+reaches an empty line. It is peculiar in that the @code{while} has no
+body, just the end test (which also does the real work of moving point).
@end defspec
+ The @code{dolist} and @code{dotimes} macros provide convenient ways to
+write two common kinds of loops.
+
+@defmac dolist (var list [result]) body@dots{}
+@tindex dolist
+This construct executes @var{body} once for each element of @var{list},
+using the variable @var{var} to hold the current element. Then it
+returns the value of evaluating @var{result}, or @code{nil} if
+@var{result} is omitted. For example, here is how you could use
+@code{dolist} to define the @code{reverse} function:
+
+@example
+(defun reverse (list)
+ (let (value)
+ (dolist (elt list value)
+ (setq value (cons elt value)))))
+@end example
+@end defmac
+
+@defmac dotimes (var count [result]) body@dots{}
+@tindex dotimes
+This construct executes @var{body} once for each integer from 0
+(inclusive) to @var{count} (exclusive), using the variable @var{var} to
+hold the integer for the current iteration. Then it returns the value
+of evaluating @var{result}, or @code{nil} if @var{result} is omitted.
+Here is an example of using @code{dotimes} do something 100 times:
+
+@example
+(dotimes (i 100)
+ (insert "I will not obey absurd orders\n"))
+@end example
+@end defmac
+
@node Nonlocal Exits
@section Nonlocal Exits
@cindex nonlocal exits
@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.
+@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 except @code{nil}. 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
+@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}.
+If a @code{throw} is executed during the execution of @var{body},
+specifying the same value @var{tag}, the @code{catch} form exits
+immediately; the value it returns is whatever was specified as the
+second argument of @code{throw}.
@end defspec
@defun throw tag value
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))
@subsubsection How to Signal an Error
@cindex signaling errors
+ @dfn{Signalling} an error means beginning error processing. Error
+processing normally aborts all or part of the running program and
+returns to a point that is set up to handle the error
+(@pxref{Processing of Errors}). Here we describe how to signal an
+error.
+
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
+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}.
+ Every error specifies an error message, one way or another. The
+message should state what is wrong (``File does not exist''), not how
+things ought to be (``File must exist''). The convention in Emacs
+Lisp is that error messages should start with a capital letter, but
+should not end with any sort of punctuation.
+
@defun error format-string &rest args
This function signals an error with an error message constructed by
applying @code{format} (@pxref{String Conversion}) to
@example
@group
-(error "You have committed an error.
- Try something else.")
- @error{} You have committed an error.
- Try something else.
+(error "That is an error -- try something else")
+ @error{} That is an error -- try something else
@end group
@group
-(error "You have committed %d errors." 10)
- @error{} You have committed 10 errors.
+(error "You have committed %d errors" 10)
+ @error{} You have committed 10 errors
@end group
@end example
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 that describes the type
+there should be two objects in the list: a predicate that describes the type
that was expected, and the object that failed to fit that type.
@xref{Error Symbols}, for a description of error symbols.
@end group
@group
-(signal 'no-such-error '("My unknown error condition."))
- @error{} peculiar error: "My unknown error condition."
+(signal 'no-such-error '("My unknown error condition"))
+ @error{} peculiar error: "My unknown error condition"
@end group
@end smallexample
@end defun
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.
+the two gets to handle it.
If an error is handled by some @code{condition-case} form, this
ordinarily prevents the debugger from being run, even if
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
+ The @code{condition-case} construct 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 that can be handled).
+@code{catch} (@pxref{Catch and Throw}), 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
+that can be handled).
@defspec condition-case var protected-form handlers@dots{}
This special form establishes the error handlers @var{handlers} around
(condition-case err
;; @r{Protected form.}
(/ dividend divisor)
+@end group
+@group
;; @r{The handler.}
(arith-error ; @r{Condition.}
;; @r{Display the usual message for this error.}
@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}
+Only the @var{body} is protected by the @code{unwind-protect}. If any
+of the @var{cleanup-forms} themselves exits nonlocally (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.
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.)
+temporary buffer becomes current again in time to kill it.)
+
+ Emacs includes a standard macro called @code{with-temp-buffer} which
+expands into more or less the code shown above (@pxref{Current Buffer}).
+Several of the macros defined in this manual use @code{unwind-protect}
+in this way.
@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 that 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.
+ Here is an actual example derived from an FTP package. 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 that 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
@end group
@end smallexample
- This example actually has a small bug: if the user types @kbd{C-g} to
+ This example 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.
-
-@smallexample
-(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 smallexample