@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
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{}
+@defmac with-demoted-errors format 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
+It uses the string @var{format} to format the message.
+@var{format} should contain a single @samp{%}-sequence; e.g.,
+@code{"Error: %S"}. Use @code{with-demoted-errors} 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
@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
HCoop / bpt / emacs.git / blobdiff