@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/control
-@node Control Structures, Variables, Evaluation, Top
+@node Control Structures
@chapter Control Structures
@cindex special forms for control structures
@cindex control structures
@end example
@end defspec
- Two other control constructs likewise evaluate a series of forms but return
-a different value:
+ Two other constructs likewise evaluate a series of forms but return
+different values:
@defspec prog1 form1 forms@dots{}
This special form evaluates @var{form1} and all of the @var{forms}, in
given, @code{if} returns @code{nil}.
@code{if} is a special form because the branch that 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.
+never evaluated---it is ignored. Thus, in this example,
+@code{true} is not printed because @code{print} is never called:
@example
@group
@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.
+@var{body-forms}, and returns the value of the last of @var{body-forms}.
+Any 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}.
+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}.
A clause may also look like this:
@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.
+Then, if @var{condition} is non-@code{nil} when tested, the @code{cond}
+form returns the value of @var{condition}.
+
+If every @var{condition} evaluates to @code{nil}, so that every clause
+fails, @code{cond} returns @code{nil}.
The following example has four clauses, which test for the cases where
the value of @code{x} is a number, string, buffer and symbol,
@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,
+gets to it at all. For example:
@example
@group
@end group
@end example
+@menu
+* Pattern matching case statement::
+@end menu
+
+@node Pattern matching case statement
+@subsection Pattern matching case statement
+@cindex pcase
+@cindex pattern matching
+
+To compare a particular value against various possible cases, the macro
+@code{pcase} can come handy. It takes the following form:
+
+@example
+(pcase @var{exp} @var{branch}1 @var{branch}2 @var{branch}3 @dots{})
+@end example
+
+where each @var{branch} takes the form @code{(@var{upattern}
+@var{body-forms}@dots{})}.
+
+It will first evaluate @var{exp} and then compare the value against each
+@var{upattern} to see which @var{branch} to use, after which it will run the
+corresponding @var{body-forms}. A common use case is to distinguish
+between a few different constant values:
+
+@example
+(pcase (get-return-code x)
+ (`success (message "Done!"))
+ (`would-block (message "Sorry, can't do it now"))
+ (`read-only (message "The shmliblick is read-only"))
+ (`access-denied (message "You do not have the needed rights"))
+ (code (message "Unknown return code %S" code)))
+@end example
+
+In the last clause, @code{code} is a variable that gets bound to the value that
+was returned by @code{(get-return-code x)}.
+
+To give a more complex example, a simple interpreter for a little
+expression language could look like (note that this example requires
+lexical binding):
+
+@example
+(defun evaluate (exp env)
+ (pcase exp
+ (`(add ,x ,y) (+ (evaluate x env) (evaluate y env)))
+ (`(call ,fun ,arg) (funcall (evaluate fun env) (evaluate arg env)))
+ (`(fn ,arg ,body) (lambda (val)
+ (evaluate body (cons (cons arg val) env))))
+ ((pred numberp) exp)
+ ((pred symbolp) (cdr (assq exp env)))
+ (_ (error "Unknown expression %S" exp))))
+@end example
+
+Where @code{`(add ,x ,y)} is a pattern that checks that @code{exp} is a three
+element list starting with the symbol @code{add}, then extracts the second and
+third elements and binds them to the variables @code{x} and @code{y}.
+@code{(pred numberp)} is a pattern that simply checks that @code{exp}
+is a number, and @code{_} is the catch-all pattern that matches anything.
+
+Here are some sample programs including their evaluation results:
+
+@example
+(evaluate '(add 1 2) nil) ;=> 3
+(evaluate '(add x y) '((x . 1) (y . 2))) ;=> 3
+(evaluate '(call (fn x (add 1 x)) 2) nil) ;=> 3
+(evaluate '(sub 1 2) nil) ;=> error
+@end example
+
+There are two kinds of patterns involved in @code{pcase}, called
+@emph{U-patterns} and @emph{Q-patterns}. The @var{upattern} mentioned above
+are U-patterns and can take the following forms:
+
+@table @code
+@item `@var{qpattern}
+This is one of the most common form of patterns. The intention is to mimic the
+backquote macro: this pattern matches those values that could have been built
+by such a backquote expression. Since we're pattern matching rather than
+building a value, the unquote does not indicate where to plug an expression,
+but instead it lets one specify a U-pattern that should match the value at
+that location.
+
+More specifically, a Q-pattern can take the following forms:
+@table @code
+@item (@var{qpattern1} . @var{qpattern2})
+This pattern matches any cons cell whose @code{car} matches @var{QPATTERN1} and
+whose @code{cdr} matches @var{PATTERN2}.
+@item @var{atom}
+This pattern matches any atom @code{equal} to @var{atom}.
+@item ,@var{upattern}
+This pattern matches any object that matches the @var{upattern}.
+@end table
+
+@item @var{symbol}
+A mere symbol in a U-pattern matches anything, and additionally let-binds this
+symbol to the value that it matched, so that you can later refer to it, either
+in the @var{body-forms} or also later in the pattern.
+@item _
+This so-called @emph{don't care} pattern matches anything, like the previous
+one, but unlike symbol patterns it does not bind any variable.
+@item (pred @var{pred})
+This pattern matches if the function @var{pred} returns non-@code{nil} when
+called with the object being matched.
+@item (or @var{upattern1} @var{upattern2}@dots{})
+This pattern matches as soon as one of the argument patterns succeeds.
+All argument patterns should let-bind the same variables.
+@item (and @var{upattern1} @var{upattern2}@dots{})
+This pattern matches only if all the argument patterns succeed.
+@item (guard @var{exp})
+This pattern ignores the object being examined and simply succeeds if @var{exp}
+evaluates to non-@code{nil} and fails otherwise. It is typically used inside
+an @code{and} pattern. For example, @code{(and x (guard (< x 10)))}
+is a pattern which matches any number smaller than 10 and let-binds it to
+the variable @code{x}.
+@end table
+
@node Combining Conditions
@section Constructs for Combining Conditions
@code{catch} in between).
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
+@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
-(@pxref{Cleanups}).
+the narrowing status saved by @code{save-restriction}. It also runs
+any cleanups established with the @code{unwind-protect} special form
+when it exits that form (@pxref{Cleanups}).
The @code{throw} need not appear lexically within the @code{catch}
that it jumps to. It can equally well be called from another function
@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}.
+@code{throw}. The @file{cl-lib} library provides versions of some of
+these. @xref{Blocks and Exits,,,cl,Common Lisp Extensions}.
@end quotation
@defspec catch tag body@dots{}
@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 ``goto.'')
+nested loop. (In most languages, this would be done with a ``goto''.)
Here we compute @code{(foo @var{i} @var{j})} for @var{i} and @var{j}
varying from 0 to 9:
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. @xref{Error Symbols}, for a description of error symbols,
+defined with @code{define-error}. This is how Emacs Lisp classifies different
+sorts of errors. @xref{Error Symbols}, for a description of error symbols,
error conditions and condition names.
If the error is not handled, the two arguments are used in printing
variable to a list of the form @code{(@var{error-symbol} .@:
@var{data})} (@pxref{Handling Errors}).
-The function @code{signal} never returns (though in older Emacs versions
-it could sometimes return).
+The function @code{signal} never returns.
+@c (though in older Emacs versions it sometimes could).
-@smallexample
+@example
@group
(signal 'wrong-number-of-arguments '(x y))
@error{} Wrong number of arguments: x, y
(signal 'no-such-error '("My unknown error condition"))
@error{} peculiar error: "My unknown error condition"
@end group
-@end smallexample
+@end example
+@end defun
+
+@cindex user errors, signaling
+@defun user-error format-string &rest args
+This function behaves exactly like @code{error}, except that it uses
+the error symbol @code{user-error} rather than @code{error}. As the
+name suggests, this is intended to report errors on the part of the
+user, rather than errors in the code itself. For example,
+if you try to use the command @code{Info-history-back} (@kbd{l}) to
+move back beyond the start of your Info browsing history, Emacs
+signals a @code{user-error}. Such errors do not cause entry to the
+debugger, even when @code{debug-on-error} is non-@code{nil}.
+@xref{Error Debugging}.
@end defun
@cindex CL note---no continuable errors
@noindent
This deletes the file named @var{filename}, catching any error and
-returning @code{nil} if an error occurs@footnote{
-Actually, you should use @code{ignore-errors} in such a simple case;
-see below.}.
+returning @code{nil} if an error occurs. (You can use the macro
+@code{ignore-errors} for a simple case like this; see below.)
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
given error will invoke the debugger only if @code{debug-on-error} and
the other usual filtering mechanisms say it should. @xref{Error Debugging}.
+@defmac condition-case-unless-debug var protected-form handlers@dots{}
+The macro @code{condition-case-unless-debug} provides another way to
+handle debugging of such forms. It behaves exactly like
+@code{condition-case}, unless the variable @code{debug-on-error} is
+non-@code{nil}, in which case it does not handle any errors at all.
+@end defmac
+
Once Emacs decides that a certain handler handles the error, it
returns control to that handler. To do so, Emacs unbinds all variable
bindings made by binding constructs that are being exited, and
Lisp expressions to be executed when this handler handles an error.
Here are examples of handlers:
-@smallexample
+@example
@group
(error nil)
(message
"Either division by zero or failure to open a file"))
@end group
-@end smallexample
+@end example
Each error that occurs has an @dfn{error symbol} that describes what
-kind of error it is. The @code{error-conditions} property of this
-symbol is a list of condition names (@pxref{Error Symbols}). Emacs
+kind of error it is, and which describes also a list of condition names
+(@pxref{Error Symbols}). Emacs
searches all the active @code{condition-case} forms for a handler that
specifies one or more of these condition names; the innermost matching
@code{condition-case} handles the error. Within this
@code{condition-case}, for some outer-level handler to catch. Here's
how to do that:
-@smallexample
+@example
(signal (car err) (cdr err))
-@end smallexample
+@end example
@noindent
where @code{err} is the error description variable, the first argument
that results from dividing by zero. The handler displays the error
message (but without a beep), then returns a very large number.
-@smallexample
+@example
@group
(defun safe-divide (dividend divisor)
(condition-case err
@print{} Arithmetic error: (arith-error)
@result{} 1000000
@end group
-@end smallexample
+@end example
@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,
+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 (by this @code{condition-case}). Thus:
-@smallexample
+@example
@group
(safe-divide nil 3)
@error{} Wrong type argument: number-or-marker-p, nil
@end group
-@end smallexample
+@end example
Here is a @code{condition-case} that catches all kinds of errors,
-including those signaled with @code{error}:
+including those from @code{error}:
-@smallexample
+@example
@group
(setq baz 34)
@result{} 34
@print{} The error was: (error "Rats! The variable baz was 34, not 35")
@result{} 2
@end group
-@end smallexample
+@end example
@defmac ignore-errors body@dots{}
This construct executes @var{body}, ignoring any errors that occur
Here's the example at the beginning of this subsection rewritten using
@code{ignore-errors}:
-@smallexample
+@example
@group
(ignore-errors
(delete-file filename))
@end group
-@end smallexample
+@end example
@end defmac
+@defmac with-demoted-errors body@dots{}
+This macro is like a milder version of @code{ignore-errors}. Rather
+than suppressing errors altogether, it converts them into messages.
+Use this form around code that is not expected to signal errors, but
+should be robust if one does occur. Note that this macro uses
+@code{condition-case-unless-debug} rather than @code{condition-case}.
+@end defmac
@node Error Symbols
@subsubsection Error Symbols and Condition Names
@cindex condition name
@cindex user-defined error
@kindex error-conditions
+@kindex define-error
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 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 that 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.
-Because quitting is not considered an error, the value of the
-@code{error-conditions} property of @code{quit} is just @code{(quit)}.
+@defun define-error name message &optional parent
+ In order for a symbol to be an error symbol, it must be defined with
+@code{define-error} which takes a parent condition (defaults to @code{error}).
+This parent defines the conditions that this kind of error belongs to.
+The transitive set of parents always includes the error symbol itself, and the
+symbol @code{error}. Because quitting is not considered an error, the set of
+parents of @code{quit} is just @code{(quit)}.
+@end defun
@cindex peculiar error
- 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
-error symbol has no @code{error-message} property or if the
-@code{error-message} property exists, but is not a string, the error
-message @samp{peculiar error} is used. @xref{Definition of signal}.
+ In addition to its parents, the error symbol has a @var{message} which
+is a string to be printed when that error is signaled but not handled. If that
+message is not valid, the error message @samp{peculiar error} is used.
+@xref{Definition of signal}.
+
+Internally, the set of parents is stored in the @code{error-conditions}
+property of the error symbol and the message is stored in the
+@code{error-message} property of the error symbol.
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"
+(define-error 'new-error "A new error" 'my-own-errors)
@end group
@end example
@noindent
-This error has three condition names: @code{new-error}, the narrowest
+This error has several 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.
+classification; and all the conditions of @code{my-own-errors} which should
+include @code{error}, which is the widest of all.
The error string should start with a capital letter but it should
not end with a period. This is for consistency with the rest of Emacs.
@end group
@end example
- This error can be handled through any of the three condition names.
+ This error can be handled through any of its condition names.
This example handles @code{new-error} and any other errors in the class
@code{my-own-errors}:
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
+ @xref{Standard Errors}, for a list of the main error symbols
and their conditions.
@node Cleanups
For example, here we make an invisible buffer for temporary use, and
make sure to kill it before finishing:
-@smallexample
+@example
@group
(let ((buffer (get-buffer-create " *temp*")))
(with-current-buffer buffer
@var{body-form}
(kill-buffer buffer))))
@end group
-@end smallexample
+@end example
@noindent
You might think that we could just as well write @code{(kill-buffer
event of failure. Otherwise, Emacs might fill up with useless
subprocesses.
-@smallexample
+@example
@group
(let ((win nil))
(unwind-protect
(error "Ftp login failed")))
(or win (and process (delete-process process)))))
@end group
-@end smallexample
+@end example
This example has a small bug: if the user types @kbd{C-g} to
quit, and the quit happens immediately after the function