X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/eceeb5fca618f3bc0743c2388148dd758229c7c9..64c3533166e1fa517422f89f953cfdaea6ee7bf0:/doc/lispref/control.texi diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index d6dee7ecf9..edf60dd5cc 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1,8 +1,9 @@ @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. -@node Control Structures, Variables, Evaluation, Top +@node Control Structures @chapter Control Structures @cindex special forms for control structures @cindex control structures @@ -93,8 +94,8 @@ order, returning the result of the final form. @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 @@ -159,8 +160,8 @@ If @var{condition} has the value @code{nil}, and no @var{else-forms} are 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 @@ -217,15 +218,11 @@ list is the @var{condition}; the remaining elements, if any, the @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: @@ -234,8 +231,11 @@ 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, @@ -257,9 +257,7 @@ clauses was successful. To do this, we use @code{t} as the @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 @@ -287,6 +285,120 @@ For example: @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 @@ -558,16 +670,14 @@ the @code{catch} in @code{foo-outer} specifies the same symbol, so that @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 @@ -582,7 +692,8 @@ that throw back to the editor command loop (@pxref{Recursive Editing}). @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{} @@ -788,9 +899,8 @@ argument @var{data} is a list of additional Lisp objects relevant to 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 @@ -811,10 +921,10 @@ handlers that handle the error: @code{condition-case} binds a local 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 @@ -824,7 +934,20 @@ it could sometimes return). (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 @@ -990,7 +1113,7 @@ to allow the debugger to run before the handler); @var{body} is one or more Lisp expressions to be executed when this handler handles an error. Here are examples of handlers: -@smallexample +@example @group (error nil) @@ -1000,11 +1123,11 @@ Here are examples of handlers: (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 @@ -1033,9 +1156,9 @@ Sometimes it is necessary to re-throw a signal caught by @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 @@ -1054,7 +1177,7 @@ Here is an example of using @code{condition-case} to handle the error 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 @@ -1075,22 +1198,24 @@ message (but without a beep), then returns a very large number. @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 @@ -1108,7 +1233,7 @@ including those signaled with @code{error}: @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 @@ -1119,18 +1244,21 @@ otherwise, it returns @code{nil}. 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 @@ -1142,6 +1270,7 @@ should be robust if one does occur. Note that this macro uses @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 @@ -1158,42 +1287,38 @@ Thus, each error has one or more condition names: @code{error}, the 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. @@ -1209,7 +1334,7 @@ your code can do this: @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}: @@ -1279,7 +1404,7 @@ Variables}). 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 @@ -1287,7 +1412,7 @@ make sure to kill it before finishing: @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 @@ -1312,7 +1437,7 @@ 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 +@example @group (let ((win nil)) (unwind-protect @@ -1323,7 +1448,7 @@ subprocesses. (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