@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Control Structures
@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}.
+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,
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:
+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) (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))))
+ (`(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
@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:
@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{qpattern1 qpattern2..qpatternm}]
+This pattern matches a vector of length @code{M} whose 0..(M-1)th
+elements match @var{QPATTERN1}, @var{QPATTERN2}..@var{QPATTERNm},
+respectively.
@item @var{atom}
This pattern matches any atom @code{equal} to @var{atom}.
@item ,@var{upattern}
@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