@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
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.
@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.
+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 defspec
@defmac when condition then-forms@dots{}
-@tindex when
This is a variant of @code{if} where there are no @var{else-forms},
and possibly several @var{then-forms}. In particular,
@end defmac
@defmac unless condition forms@dots{}
-@tindex condition
This is a variant of @code{if} where there is no @var{then-form}:
@example
@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
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
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
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
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
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
@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.
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,
HCoop / bpt / emacs.git / blobdiff