control.texi

@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@documentencoding UTF-8
@node Control Structures
@chapter 制御構造
@cindex 制御構造向けのスペシャルフォーム
@cindex 制御構造

Lispプログラムは、@dfn{式}、すなわち、@dfn{フォーム}（forms、
@pxref{Forms}）から成ります。フォームを@dfn{制御構造}（control
structures）で囲むことで、フォームの実行順序を制御します。
制御構造はスペシャルフォームであり、その内側にあるフォームの実行をいつ行うか、
行わないか、何回行うかを制御します。

@cindex textual order
もっとも単純な実行順序は逐次実行です。
最初のフォーム@var{a}を実行し、それからつぎのフォーム@var{b}を実行し、といった具合です。
関数の本体やLispコードのファイルのトップレベルに複数のフォームを順に書くと、
このようになります。
つまり、書かれている順番にフォームを実行します。
これを@dfn{テキスト上の順序}（textual order）と呼びます。
たとえば、関数本体が2つのフォーム@var{a}と@var{b}から成る場合、
関数を評価すると、まず@var{a}を評価し、つぎに@var{b}を評価して、関数の値は@var{b}の値になります。

明示的な制御構造により、逐次実行以外の実行順序が可能になります。

Emacs Lispには数種類の制御構造があり、
逐次実行の変形、条件付き実行、繰り返し実行、
（制御された）ジャンプなどです。
これらすべては、以下に説明します。
組み込みの制御構造はスペシャルフォームです。
というのは、それらのサブフォームは必ずしも評価しませんし、
逐次評価するわけでもないからです。
マクロを使えば、独自の制御構造の構文を定義できます（@pxref{Macros}）。

@menu
* Sequencing::             Evaluation in textual order.
* Conditionals::           @code{if}, @code{cond}, @code{when}, @code{unless}.
* Combining Conditions::   @code{and}, @code{or}, @code{not}.
* Iteration::              @code{while} loops.
* Generators::             Generic sequences and coroutines.
* Nonlocal Exits::         Jumping out of a sequence.
@end menu

@node Sequencing
@section 逐次実行
@cindex 逐次実行
@cindex 逐次的な実行

現れる順番にフォームを評価することは、
1つのフォームから別のフォームへ制御を移すもっとも一般的な方法です。
関数本体などのある種の文脈では、自動的にこのようになります。
それ以外では、これを行う制御構造の構文を使う必要があります。
@code{progn}がその制御構造で、Lispのもっとも単純な制御構造です。

スペシャルフォーム@code{progn}はつぎのような形です。

@example
@group
(progn @var{a} @var{b} @var{c} @dots{})
@end group
@end example

@noindent
これは、フォーム、@var{a}、@var{b}、@var{c}、…をこの順に評価します。
これらのフォームを@code{progn}フォームの@dfn{本体}と呼びます。
本体の最後のフォームの値が、@code{progn}全体の値になります。
@code{(progn)} は @code{nil}を返します。

@cindex 暗黙の@code{progn}
初期のころのLispでは、@code{progn}は、
2つ以上のフォームを逐次実行しそれらの最後の値を使う唯一の方法でした。
しかし、プログラマは、（当時は）1つのフォームしか許されていない
関数の本体では、
@code{progn}を使う必要がしばしばあることに気づきました。
そのため、関数本体を『暗黙の@code{progn}』にしたのです。
つまり、実際の@code{progn}の本体のように、
複数のフォームを許すようにしたのです。
多くの他の制御構造も、同様に、暗黙の@code{progn}です。
その結果、@code{progn}は、かつてほどは多用されません。
現在では、@code{unwind-protect}、@code{and}、@code{or}の内側や、
@code{if}の@var{then}部分で必要とされるのがほとんどです。

@defspec progn forms@dots{}
このスペシャルフォームは、@var{forms}のフォームすべてを
テキスト上の順に評価し、最後のフォームの結果を返す。

@example
@group
(progn (print "The first form")
       (print "The second form")
       (print "The third form"))
     @print{} "The first form"
     @print{} "The second form"
     @print{} "The third form"
@result{} "The third form"
@end group
@end example
@end defspec

他の2つの制御構造も同様にフォームを逐次評価しますが、
返す値が異なります。

@defspec prog1 form1 forms@dots{}
このスペシャルフォームは、@var{form1}、@var{forms}のフォームすべてを
テキスト上の順に評価し、@var{form1}の結果を返す。

@example
@group
(prog1 (print "The first form")
       (print "The second form")
       (print "The third form"))
     @print{} "The first form"
     @print{} "The second form"
     @print{} "The third form"
@result{} "The first form"
@end group
@end example

変数@code{x}のリストから先頭要素を取り除き、取り除いた要素を返すにはつぎのように書く。

@example
(prog1 (car x) (setq x (cdr x)))
@end example
@end defspec

@defspec prog2 form1 form2 forms@dots{}
このスペシャルフォームは、@var{form1}、@var{form2}、@var{forms}の
フォームすべてをテキスト上の順に評価し、@var{form2}の結果を返す。

@example
@group
(prog2 (print "The first form")
       (print "The second form")
       (print "The third form"))
     @print{} "The first form"
     @print{} "The second form"
     @print{} "The third form"
@result{} "The second form"
@end group
@end example
@end defspec

@node Conditionals
@section 条件付き実行
@cindex 条件付き評価

条件付き制御構造は、選択肢を選びます。
Emacs Lispには、4つの条件付きフォームがあります。
他の言語のものとほとんど同じ@code{if}、
@code{if}の変形である@code{when}や@code{unless}、
一般化したcase文である@code{cond}です。

@defspec if condition then-form else-forms@dots{}
@code{if}は、@var{condition}をもとにして、
@var{then-form}か@var{else-forms}を選ぶ。
@var{condition}が@code{nil}以外に評価されると、
@var{then-form}を評価し、その結果を返す。
さもなければ、@var{else-forms}をテキスト上の順に評価し、
その最後のものの値を返す。
（@code{if}の@var{else}部分は、暗黙の@code{progn}の例である。
@xref{Sequencing}。）

@var{condition}が値@code{nil}であり、かつ、@var{else-forms}がないと、
@code{if}は@code{nil}を返す。

@code{if}がスペシャルフォームであるのは、
選択しなかった分岐をけっして評価しないからである。
したがって、つぎの例では、
@code{print}はけっして呼ばれないため@code{true}は表示されない。

@example
@group
(if nil
    (print 'true)
  'very-false)
@result{} very-false
@end group
@end example
@end defspec

@defmac when condition then-forms@dots{}
@tindex when
これは@code{if}の変形であり、@var{else-forms}がなく、
@var{then-forms}は複数のフォームでもよい。
特に、

@example
(when @var{condition} @var{a} @var{b} @var{c})
@end example

@noindent
は、つぎとまったく等価である。

@example
(if @var{condition} (progn @var{a} @var{b} @var{c}) nil)
@end example
@end defmac

@defmac unless condition forms@dots{}
@tindex condition
これは@var{then-form}がない@code{if}の変形である。

@example
(unless @var{condition} @var{a} @var{b} @var{c})
@end example

@noindent
は、つぎとまったく等価である。

@example
(if @var{condition} nil
   @var{a} @var{b} @var{c})
@end example
@end defmac

@defspec cond clause@dots{}
@code{cond}は任意個数の選択肢から1つを選ぶ。
@code{cond}の各節@var{clause}はリストである必要がある。
このリストの@sc{car}が@var{condition}（条件）である。
残りの要素は、あれば、@var{body-forms}（本体フォーム）である。
つまり、各節はつぎのようになる。

@example
(@var{condition} @var{body-forms}@dots{})
@end example

@code{cond}は、各節の@var{condition}を評価して、
各節をテキスト上の順に試す。
@var{condition}の値が@code{nil}以外であれば、
その節は『成功』する。
そうすると、@code{cond}はその節の@var{body-forms}を評価し、
@var{body-forms}の最後の値が返される。
残りの節は無視する。

@var{condition}の値が@code{nil}であると、
その節は『失敗』し、
@code{cond}はつぎの節へ移りその@var{condition}を試す。

節@var{clause}は、つぎの形式でもよい。

@example
(@var{condition})
@end example

@noindent
この場合、@var{condition}が@code{nil}以外であると、
@var{condition}が@code{cond}フォームの値になる。

If every @var{condition} evaluates to @code{nil}, so that every clause
fails, @code{cond} returns @code{nil}.

以下の例には4つの節があり、
@code{x}の値が、数、文字列、バッファ、シンボルかどうか調べる。

@example
@group
(cond ((numberp x) x)
      ((stringp x) x)
      ((bufferp x)
       (setq temporary-hack x) ; @r{1つの節に}
       (buffer-name x))        ; @r{複数個の本体フォーム}
      ((symbolp x) (symbol-value x)))
@end group
@end example

最後の節を除くそれよりまえの節がどれも成功しないときには、
最後の節を実行したいことがしばしばある。
これを行うには、@code{(t @var{body-forms})}のように
最後の節の@var{condition}に@code{t}を使う。
フォーム@code{t}は@code{t}と評価され、けっして@code{nil}ではない。
そのため、@code{cond}がこの節に達したときには、
この節が失敗することはない。たとえば、つぎのとおり。

@example
@group
(setq a 5)
(cond ((eq a 'hack) 'foo)
      (t "default"))
@result{} "default"
@end group
@end example

@noindent
この式は、@code{a}の値が@code{hack}のときには@code{foo}を返し、
さもなければ文字列@code{"default"}を返す@code{cond}である。
@end defspec

任意の条件付き構造は、@code{cond}や@code{if}で表現できます。
したがって、どちらを使うかは好みの問題です。
たとえば、つぎのとおりです。

@example
@group
(if @var{a} @var{b} @var{c})
@equiv{}
(cond (@var{a} @var{b}) (t @var{c}))
@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{qpattern1} @var{qpattern2} @dots{} @var{qpatternm}]
This pattern matches a vector of length @var{M} whose 0..(@var{M}-1)th
elements match @var{qpattern1}, @var{qpattern2} @dots{} @var{qpatternm},
respectively.
@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 条件の組み合わせ

本節では、@code{if}や@code{cond}とともに用いて複雑な条件を表現するために
しばしば使われる3つの構造を説明します。
@code{and}や@code{or}の構造は、
複数の条件付き構造の一種として単独で使うこともできます。

@defun not condition
この関数は、@var{condition}が偽であるかどうか調べる。
@var{condition}が@code{nil}であれば@code{t}を返し、
さもなければ@code{nil}を返す。
関数@code{not}は@code{null}と同一であるが、
空リストかどうか調べる場合には、@code{null}を使うことを勧める。
@end defun

@defspec and conditions@dots{}
スペシャルフォーム@code{and}は、
すべての@var{conditions}が真であるかどうか調べる。
@var{conditions}を1つ1つ書かれた順に評価して調べる。

@var{conditions}のどれかが@code{nil}に評価されると、
@code{and}の結果は、残りの@var{conditions}に関係なく、@code{nil}になる。
つまり、@code{and}はただちに@code{nil}を返し、
@var{conditions}の残りを無視する。

@var{conditions}すべてが@code{nil}以外であることがわかると、
それらの最後の値がフォーム@code{and}の値となる。
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?)

例を示そう。
最初の条件は整数1を返し、これは@code{nil}ではない。
同様に、2番目の条件は整数2を返し、@code{nil}ではない。
3番目の条件は@code{nil}なので、残りの条件を評価しない。

@example
@group
(and (print 1) (print 2) nil (print 3))
     @print{} 1
     @print{} 2
@result{} nil
@end group
@end example

@code{and}を使ったより現実的な例はつぎのとおり。

@example
@group
(if (and (consp foo) (eq (car foo) 'x))
    (message "foo is a list starting with x"))
@end group
@end example

@noindent
@code{(consp foo)}が@code{nil}を返すと@code{(car foo)}は実行されず、
そのためエラーを回避することに注意。

@code{and}は、@code{if}や@code{cond}で表現できる。
たとえば、つぎのとおり。

@example
@group
(and @var{arg1} @var{arg2} @var{arg3})
@equiv{}
(if @var{arg1} (if @var{arg2} @var{arg3}))
@equiv{}
(cond (@var{arg1} (cond (@var{arg2} @var{arg3}))))
@end group
@end example
@end defspec

@defspec or conditions@dots{}
スペシャルフォーム@code{or}は、
@var{conditions}の少なくとも1つが真であるかどうか調べる。
@var{conditions}を1つ1つ書かれた順に評価して調べる。

@var{conditions}のどれかが@code{nil}以外に評価されると、
@code{or}の結果は@code{nil}以外になる。
そして、@code{or}はただちに完了し、
@var{conditions}の残りを無視する。
戻り値は、@code{nil}以外に評価された値である。

@var{conditions}すべてが@code{nil}であることがわかると、
@code{or}は@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?)

たとえば、つぎの式は、@code{x}が0か@code{nil}であることを調べる。

@example
(or (eq x nil) (eq x 0))
@end example

@code{and}構造と同様に、@code{or}は@code{cond}で書き表せる。
たとえば、つぎのとおり。

@example
@group
(or @var{arg1} @var{arg2} @var{arg3})
@equiv{}
(cond (@var{arg1})
      (@var{arg2})
      (@var{arg3}))
@end group
@end example

@code{or}を@code{if}で書くこともだいたいできるが、
途中で抜け出せない。

@example
@group
(if @var{arg1} @var{arg1}
  (if @var{arg2} @var{arg2}
    @var{arg3}))
@end group
@end example

@noindent
これは完全には同一ではない。
というのは、@var{arg1}や@var{arg2}を2度評価するからである。
一方、@code{(or @var{arg1} @var{arg2} @var{arg3})}は、
どの引数も一度だけ評価する。
@end defspec

@node Iteration
@section 繰り返し
@cindex 繰り返し
@cindex 再帰

繰り返しとは、プログラムのある部分を何度も実行することです。
たとえば、リストの各要素や0から@var{n}の各整数について
1回ずつある計算を行いたい場合です。
Emacs Lispでこれを行うには、スペシャルフォーム@code{while}を使います。

@defspec while condition forms@dots{}
@code{while}は、まず@var{condition}を評価する。
結果が@code{nil}以外であれば、@var{forms}をテキスト上の順で評価する。
そして、@var{condition}を評価し直し、その結果が@code{nil}以外であれば、
再度@var{forms}を評価する。
この処理を@var{condition}が@code{nil}に評価されるまで繰り返す。

繰り返し回数に制限はない。
ループは、@var{condition}が@code{nil}に評価される、
エラーが発生する、@code{throw}によりループから抜け出す
（@pxref{Nonlocal Exits}）のいずれかが起こるまで繰り返される。

フォーム@code{while}の値はつねに@code{nil}である。

@example
@group
(setq num 0)
     @result{} 0
@end group
@group
(while (< num 4)
  (princ (format "Iteration %d." num))
  (setq num (1+ num)))
     @print{} Iteration 0.
     @print{} Iteration 1.
     @print{} Iteration 2.
     @print{} Iteration 3.
     @result{} nil
@end group
@end example

終了検査のまえに各繰り返しごとに実行したいことがあれば、
以下のように、それらと終了検査を@code{progn}でまとめたものを
@code{while}の第1引数にする。

@example
@group
(while (progn
         (forward-line 1)
         (not (looking-at "^$"))))
@end group
@end example

@noindent
これは、1行先へ移動し、空行に達するまで、移動を繰り返す。
この@code{while}には本体がなく、
終了検査（かつポイントを実際に動かす）だけであるという点で、
風変わりである。
@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{}
This construct executes @var{body} once for each element of
@var{list}, binding the variable @var{var} locally 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{}
This construct executes @var{body} once for each integer from 0
(inclusive) to @var{count} (exclusive), binding the variable @var{var}
to 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} to do something 100 times:

@example
(dotimes (i 100)
  (insert "I will not obey absurd orders\n"))
@end example
@end defmac

@node Generators
@section Generators
@cindex generators

  A @dfn{generator} is a function that produces a potentially-infinite
stream of values.  Each time the function produces a value, it
suspends itself and waits for a caller to request the next value.

@defmac iter-defun name args [doc] [declare] [interactive] body@dots{}
@code{iter-defun} defines a generator function.  A generator function
has the same signature as a normal function, but works differently.
Instead of executing @var{body} when called, a generator function
returns an iterator object.  That iterator runs @var{body} to generate
values, emitting a value and pausing where @code{iter-yield} or
@code{iter-yield-from} appears.  When @var{body} returns normally,
@code{iter-next} signals @code{iter-end-of-sequence} with @var{body}'s
result as its condition data.

Any kind of Lisp code is valid inside @var{body}, but
@code{iter-yield} and @code{iter-yield-from} cannot appear inside
@code{unwind-protect} forms.

@end defmac

@defmac iter-lambda args [doc] [interactive] body@dots{}
@code{iter-lambda} produces an unnamed generator function that works
just like a generator function produced with @code{iter-defun}.
@end defmac

@defmac iter-yield value
When it appears inside a generator function, @code{iter-yield}
indicates that the current iterator should pause and return
@var{value} from @code{iter-next}.  @code{iter-yield} evaluates to the
@code{value} parameter of next call to @code{iter-next}.
@end defmac

@defmac iter-yield-from iterator
@code{iter-yield-from} yields all the values that @var{iterator}
produces and evaluates to the value that @var{iterator}'s generator
function returns normally.  While it has control, @var{iterator}
receives values sent to the iterator using @code{iter-next}.
@end defmac

  To use a generator function, first call it normally, producing a
@dfn{iterator} object.  An iterator is a specific instance of a
generator.  Then use @code{iter-next} to retrieve values from this
iterator.  When there are no more values to pull from an iterator,
@code{iter-next} raises an @code{iter-end-of-sequence} condition with
the iterator's final value.

It's important to note that generator function bodies only execute
inside calls to @code{iter-next}.  A call to a function defined with
@code{iter-defun} produces an iterator; you must ``drive'' this
iterator with @code{iter-next} for anything interesting to happen.
Each call to a generator function produces a @emph{different}
iterator, each with its own state.

@defun iter-next iterator value
Retrieve the next value from @var{iterator}.  If there are no more
values to be generated (because @var{iterator}'s generator function
returned), @code{iter-next} signals the @code{iter-end-of-sequence}
condition; the data value associated with this condition is the value
with which @var{iterator}'s generator function returned.

@var{value} is sent into the iterator and becomes the value to which
@code{iter-yield} evaluates.  @var{value} is ignored for the first
@code{iter-next} call to a given iterator, since at the start of
@var{iterator}'s generator function, the generator function is not
evaluating any @code{iter-yield} form.
@end defun

@defun iter-close iterator
If @var{iterator} is suspended inside an @code{unwind-protect}'s
@code{bodyform} and becomes unreachable, Emacs will eventually run
unwind handlers after a garbage collection pass.  (Note that
@code{iter-yield} is illegal inside an @code{unwind-protect}'s
@code{unwindforms}.)  To ensure that these handlers are run before
then, use @code{iter-close}.
@end defun

Some convenience functions are provided to make working with
iterators easier:

@defmac iter-do (var iterator) body @dots{}
Run @var{body} with @var{var} bound to each value that
@var{iterator} produces.
@end defmac

The Common Lisp loop facility also contains features for working with
iterators.  See @xref{Loop Facility,,,cl,Common Lisp Extensions}.

The following piece of code demonstrates some important principles of
working with iterators.

@example
(iter-defun my-iter (x)
  (iter-yield (1+ (iter-yield (1+ x))))
   ;; Return normally
  -1)

(let* ((iter (my-iter 5))
       (iter2 (my-iter 0)))
  ;; Prints 6
  (print (iter-next iter))
  ;; Prints 9
  (print (iter-next iter 8))
  ;; Prints 1; iter and iter2 have distinct states
  (print (iter-next iter2 nil))

  ;; We expect the iter sequence to end now
  (condition-case x
      (iter-next iter)
    (iter-end-of-sequence
      ;; Prints -1, which my-iter returned normally
      (print (cdr x)))))
@end example

@node Nonlocal Exits
@section 非ローカル脱出
@cindex 非ローカル脱出

@dfn{非ローカル脱出}（nonlocal exit）とは、
プログラムのある場所から別の離れた場所へ制御を移すことです。
Emacs Lispでは、エラーの結果として非ローカル脱出が発生します。
非ローカル脱出は、明示的な制御にも使えます。
非ローカル脱出は、脱出対象の構造で作成したすべての変数束縛を解きます。

@menu
* Catch and Throw::     Nonlocal exits for the program's own purposes.
* Examples of Catch::   Showing how such nonlocal exits can be written.
* Errors::              How errors are signaled and handled.
* Cleanups::            Arranging to run a cleanup form if an error happens.
@end menu

@node Catch and Throw
@subsection 明示的な非ローカル脱出：@code{ }@code{catch}と@code{throw}

ほとんどの制御構造は、その構造内での制御の流れだけに影響します。
関数@code{throw}は、通常のプログラム実行のこのような規則の例外です。
つまり、要求に従って非ローカルな脱出を行います。
（ほかにも例外はあるが、それらはエラー処理のためだけである。）
@code{throw}は@code{catch}の内側で使い、
その@code{catch}へ戻ります。

@example
@group
(defun foo-outer ()
  (catch 'foo
    (foo-inner)))

(defun foo-inner ()
  @dots{}
  (if x
      (throw 'foo t))
  @dots{})
@end group
@end example

@noindent
フォーム@code{throw}を実行すると、対応する@code{catch}へ制御が戻り、
ただちに終了します。
@code{throw}に続くコードは実行されません。
@code{throw}の第2引数は、@code{catch}の戻り値として使われます。

関数@code{throw}は、その第1引数に基づいて対応する@code{catch}を探します。
つまり、@code{catch}の第1引数が
@code{throw}に指定されたものに@code{eq}であるものを探します。
そのような@code{catch}が複数個ある場合には、
もっとも内側のものを優先します。
したがって、上の例では、@code{throw}は@code{foo}を指定し、
@code{foo-outer}の@code{catch}は同じシンボルを指定しているので、
その@code{catch}を使います
（ただし、これらのあいだには他の一致する@code{catch}がないとして）。

@code{throw}の実行により、
対応する@code{catch}までのすべてのLispの構造を抜け出します。
これには関数呼び出しも含みます。
@code{let}や関数呼び出しなどの束縛を作る構造からもこのように抜け出すので、
通常どおり抜け出す場合と同様に束縛を解きます
（@pxref{Local Variables}）。
同様に、@code{throw}は、@code{save-excursion}（@pxref{Excursions}）で
保存したバッファや位置情報、
@code{save-restriction}で保存したナロイング状態も復元します。
さらに、スペシャルフォーム@code{unwind-protect}で設定した後始末を
このフォームから抜け出すときに実行します（@pxref{Cleanups}）。

@code{throw}は、テキスト上で、
ジャンプ先である@code{catch}の内側に現れる必要はありません。
@code{catch}内から呼ばれた別の関数からも戻ることもできます。
@code{throw}の実行が、
時間的に@code{catch}に入ったあとで、かつ、それから抜けるまえである限り、
対応する@code{catch}を参照できます。
エディタコマンドループ（@pxref{Recursive Editing}）から抜ける
@code{exit-recursive-edit}などのコマンドで
@code{throw}を使えるのは、このような理由からです。

@cindex CLに関した注意－－Emacsでは@code{throw}のみ
@quotation
@b{Common Lispに関した注意：}
Common Lispを含むほとんどの他のLispには、
非逐次的に制御を移す方法がいくつかある。
たとえば、@code{return}、@code{return-from}、@code{go}。
Emacs Lispには@code{throw}しかない。
@file{cl-lib}ライブラリは、上記の幾つかを提供する。
@xref{Blocks and Exits,,,cl,Common Lisp Extensions}。
@end quotation

@defspec catch tag body@dots{}
@cindex 実行時スタック上のタグ
@code{catch}は、関数@code{throw}向けに戻り位置を確立する。
その戻り位置は、@var{tag}によって他の戻り位置と区別され、
@code{nil}以外ならば任意のLispオブジェクトでよい。
引数@var{tag}は、戻り位置を確立するまえに、通常どおり評価される。

戻り位置を確立してから、@code{catch}は、@var{body}のフォームを
テキスト上の順に評価する。
エラーや非ローカル脱出なしにフォームの実行が普通に終了した場合、
@code{catch}は、最後の本体フォームの値を返す。

@var{body}の内側で、@var{tag}と同じ値を指定した@code{throw}が実行されると、
@code{catch}はただちに終了する。
このとき返す値は、@code{throw}の第2引数に指定されたものである。
@end defspec

@defun throw tag value
@code{throw}の目的は、
@code{catch}でまえもって確立しておいた戻り位置へ復帰することである。
引数@var{tag}は、さまざまな既存の戻り位置から選ぶために使い、
@code{catch}で指定した値と@code{eq}である必要がある。
@var{tag}に複数の戻り位置が一致する場合には、もっとも内側のものを使う。

引数@var{value}は、対応する@code{catch}の戻り値として使う。

@kindex no-catch
タグ@var{tag}である有効な戻り位置がなければ、
@code{(@var{tag} @var{value})}を伴ったエラー@code{no-catch}を通知する。
@end defun

@node Examples of Catch
@subsection @code{catch}と@code{throw}の例

@code{catch}と@code{throw}の使い方の1つは、
2重のループからの脱出です。
（ほとんどの言語では、これを『go to』で行うであろう。）
ここでは、@var{i}と@var{j}を0から9に変えながら、
@code{(foo @var{i} @var{j})}を計算します。

@example
@group
(defun search-foo ()
  (catch 'loop
    (let ((i 0))
      (while (< i 10)
        (let ((j 0))
          (while (< j 10)
            (if (foo i j)
                (throw 'loop (list i j)))
            (setq j (1+ j))))
        (setq i (1+ i))))))
@end group
@end example

@noindent
@code{foo}がある時点で@code{nil}以外を返すと、
ただちに止まって@var{i}と@var{j}のリストを返します。
@code{foo}がつねに@code{nil}を返すと、
@code{catch}は通常どおりに戻り、
@code{while}の結果である@code{nil}を返します。

2つの巧妙な例をあげましょう。
多少異なる2つの戻り位置が同時に存在します。
まず、同じタグ@code{hack}で2つの戻り位置があります。

@example
@group
(defun catch2 (tag)
  (catch tag
    (throw 'hack 'yes)))
@result{} catch2
@end group

@group
(catch 'hack 
  (print (catch2 'hack))
  'no)
@print{} yes
@result{} no
@end group
@end example

@noindent
どちらの戻り位置も@code{throw}に一致するタグなので、
内側のもの、つまり、@code{catch2}で確立したものに戻ります。
したがって、@code{catch2}は値@code{yes}で通常どおり戻り、
この値が表示されます。
最後に、外側の@code{catch}の2番目の本体フォーム、
つまり、@code{'no}が評価され、外側の@code{catch}から戻ります。

今度は、@code{catch2}に指定する引数を変更してみます。

@example
@group
(catch 'hack
  (print (catch2 'quux))
  'no)
@result{} yes
@end group
@end example

@noindent
ここでも2つの戻り位置がありますが、
今度は外側のものだけがタグ@code{hack}です。
内側のものはタグ@code{quux}です。
したがって、@code{throw}により、外側の@code{catch}が値@code{yes}を返します。
関数@code{print}はけっして呼ばれず、
本体フォーム@code{'no}もけっして評価されません。

@node Errors
@subsection エラー
@cindex エラー

Emacs Lispが、なんらかの理由で評価できないフォームを評価しようとしたときには、
Emacs Lispは@dfn{エラー}（error）を@dfn{通知}（signals）します。

エラーが通知されると、Emacsのデフォルトの動作は、
エラーメッセージを表示し、現在のコマンドの実行を終了します。
バッファの末尾で@kbd{C-f}を打ったときなどのように、
これはほとんどの場合、適切なことです。

複雑なプログラムでは、単に終了するだけでは満足できないこともあります。
たとえば、プログラムではデータ構造に一時的な変更を加えていたり、
プログラム終了時には削除する必要がある一時的なバッファを作成するでしょう。
そのような場合には、@code{unwind-protect}を使って、
エラー発生時に評価される@dfn{後始末式}（cleanup expressions）を
確立しておきます。
（@xref{Cleanups}。）
場合によっては、サブルーティンでエラーが発生しても、
プログラムの実行を継続したいこともあるでしょう。
このような場合には、@code{condition-case}を使って、
エラー状態から制御を回復するための
@dfn{エラーハンドラ}（error handlers）を確立しておきます。

エラー処理を用いてプログラムのある場所から別の場所へ制御を移す、
という誘惑には耐えてください。
そのかわりに@code{catch}と@code{throw}を使いましょう。
@xref{Catch and Throw}。

@menu
* Signaling Errors::      How to report an error.
* Processing of Errors::  What Emacs does when you report an error.
* Handling Errors::       How you can trap errors and continue execution.
* Error Symbols::         How errors are classified for trapping them.
@end menu

@node Signaling Errors
@subsubsection エラーの通知方法
@cindex エラー通知

   @dfn{Signaling} 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.

ほとんどのエラーは、他の目的で呼び出したLisp関数の内部で『自動的』に
通知されます。
整数の@sc{car}を計算しようとしたり、
バッファの末尾で1文字進めようとしたりしたときなどです。
関数@code{error}や関数@code{signal}で、
明示的にエラーを通知することもできます。

ユーザーが@kbd{C-g}を打ったときに発生する中断は、
エラーとは考えませんが、エラーのように扱います。
@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
この関数は、@var{format-string}と@var{args}に
@code{format}（@pxref{Formatting Strings}）を適用して作った
エラーメッセージを伴ったエラーを通知する。

@code{error}の典型的な使い方を以下に示す。

@example
@group
(error "That is an error -- try something else")
     @error{} That is an error -- try something else
@end group

@group
(error "You have committed %d errors" 10)
     @error{} You have committed 10 errors
@end group
@end example

@code{error}は、2つの引数、
エラーシンボル@code{error}と@code{format}が返す文字列を含むリスト
で@code{signal}を呼び出すことで動作する。

@strong{警告：}
独自のエラーメッセージをそのまま使いたい場合に、
単に@code{(error @var{string})}とは書かないこと。
@var{string}に@samp{%}が含まれていると、
それは書式付け指定と解釈され、予測不能な結果を招く。
そのかわりに、@code{(error "%s" @var{string})}を使う。
@end defun

@defun signal error-symbol data
@anchor{Definition of signal}
この関数は、@var{error-symbol}という名前のエラーを通知する。
引数@var{data}は、エラーの状況に関連したLispオブジェクトのリストである。

引数@var{error-symbol}は、@code{define-error}によって定義された
@dfn{エラーシンボル}（error symbol）である必要がある。
これにより、Emacsはエラーの異なる種類を分類する。
エラーシンボルや条件、条件名については、@xref{Error Symbols}。

If the error is not handled, the two arguments are used in printing
the error message.  Normally, this error message is provided by the
@code{error-message} property of @var{error-symbol}.  If @var{data} is
non-@code{nil}, this is followed by a colon and a comma separated list
of the unevaluated elements of @var{data}.  For @code{error}, the
error message is the @sc{car} of @var{data} (that must be a string).
Subcategories of @code{file-error} are handled specially.

@var{data}のオブジェクトの個数と重要性は@var{error-symbol}に依存する。
たとえば、エラー@code{wrong-type-argument}では、
リストには2つのオブジェクトがあるはずで、
予期した型を表す述語とその型に一致しなかったオブジェクトである。

@var{error-symbol}と@var{data}の両者は、
任意のエラーハンドラで利用できる。
@code{condition-case}は、ローカル変数に
フォーム@code{(@var{error-symbol} .@: @var{data})}のリストを束縛する
（@pxref{Handling Errors}）。
エラーが処理されないと、これらの2つの値はエラーメッセージの表示に使われる。

関数@code{signal}はけっして戻らない
@c (though in older Emacs versions it sometimes could).

@example
@group
(signal 'wrong-number-of-arguments '(x y))
     @error{} Wrong number of arguments: x, y
@end group

@group
(signal 'no-such-error '("My unknown error condition"))
     @error{} peculiar error: "My unknown error condition"
@end group
@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に関した注意－－継続可能なエラーはない
@quotation
@b{Common Lispに関した注意：}@code{ }
Emacsには、Common lispの継続可能なエラーの概念に相当するものはない。
@end quotation

@node Processing of Errors
@subsubsection Emacsのエラー処理方法

エラーが通知されると、@code{signal}は、
エラーに対する有効な@dfn{ハンドラ}（handler）を探します。
ハンドラは、Lispプログラムの一部でエラーが発生した場合に
実行されるように指定されたLisp式の列です。
エラーに対して適用可能なハンドラがあると、
そのハンドラが実行され、ハンドラに続いて制御は復旧します。
ハンドラは、そのハンドラを設定した@code{condition-case}の環境で実行されます。
@code{condition-case}の内側で呼び出された関数はすべて終了しているので、
ハンドラからそれらへ戻ることはできません。

エラーに適用可能なハンドラがなければ、
現在のコマンドは終了し、制御はエディタコマンドループへ戻ります。
（コマンドループには、
すべての種類のエラーに対する暗黙のハンドラがあるからです。）
コマンドループのハンドラは、エラーシンボルと関連するデータを使って
エラーメッセージを表示します。
You can use the variable
@code{command-error-function} to control how this is done:

@defvar command-error-function
This variable, if non-@code{nil}, specifies a function to use to
handle errors that return control to the Emacs command loop.  The
function should take three arguments: @var{data}, a list of the same
form that @code{condition-case} would bind to its variable;
@var{context}, a string describing the situation in which the error
occurred, or (more often) @code{nil}; and @var{caller}, the Lisp
function which called the primitive that signaled the error.
@end defvar

@cindex @code{debug-on-error}の利用
明示的なハンドラがないエラーは、Lispデバッガを呼び出すこともあります。
変数@code{debug-on-error}（@xref{Error Debugging}）が
@code{nil}以外であると、デバッガが有効になります。
エラーハンドラと違って、デバッガはエラーの環境で実行されるので、
エラー時の変数の正確な値を調べることができます。

@node Handling Errors
@subsubsection エラーハンドラの書き方
@cindex エラーハンドラ
@cindex エラーを処理する

エラーを通知することの普通の効果は、
実行中のコマンドを終了し、Emacsのエディタコマンドループにただちに戻ります。
読者のプログラムの一部で発生したエラーを捕捉するようにするには、
スペシャルフォーム@code{condition-case}を使ってエラーハンドラを設定します。
単純な例はつぎのようになります。

@example
@group
(condition-case nil
    (delete-file filename)
  (error nil))
@end group
@end example

@noindent
これは@var{filename}という名前のファイルを削除しますが、
エラーが発生するとどんなエラーでも捕捉して@code{nil}を返します。
（このような単純な場合では、マクロ@code{ignore-errors}を使うこともできます。
詳細は下記参照。）

@code{condition-case}構造は、@code{insert-file-contents}の呼び出しで
ファイルのオープンに失敗するなどの予測可能なエラーを捕捉するために
しばしば使われます。
プログラムがユーザーから読み取った式を評価する場合のように、
まったく予測不可能なエラーを捕捉するためにも使われます。

@code{condition-case}の第2引数を
@dfn{保護されたフォーム}（protected form）と呼びます。
（上の例では、保護されたフォームは@code{delete-file}の呼び出し。）
このフォームの実行を開始するとエラーハンドラが有効になり、
このフォームから戻るとエラーハンドラは取り除かれます。
そのあいだは、つねにエラーハンドラは有効です。
特に、このフォームから呼び出される関数の実行中、
それらのサブルーティンの実行中などには、エラーハンドラは有効です。
これは大切なことで、厳密にいえば、
エラーが通知されるのは、保護されたフォームから呼び出された
（@code{signal}や@code{error}を含む）Lisp基本関数の実行中であって、
保護されたフォームそのものからではないからです。

保護されたフォームのうしろにある引数は、ハンドラです。
各ハンドラは1つ以上の（シンボルである）@dfn{条件名}
（condition names）を列挙し、処理するエラーを指定します。
エラーが通知されたときのエラーシンボルも条件名のリストを定義します。
それらに共通の条件名があるとき、
エラーハンドラがエラーに適用されます。
上の例では、1つのハンドラがあり、条件名は1つ、@code{error}を指定しています。
この条件名はすべてのエラーを意味します。

適用可能なハンドラの探索では、
もっとも最近に確立されたハンドラから始めて、
確立されたすべてのハンドラを調べます。
したがって、フォーム@code{condition-case}が2つ入れ子になっていて
同じ名前のハンドラを確立していると、内側のものが実際に処理を受け持ちます。

フォーム@code{condition-case}でエラーが処理されるときには、
@code{debug-on-error}でエラーによりデバッガを起動するように指定してあっても
デバッガは実行されません。

@code{condition-case}で捕捉されるエラーをデバッグしたいときには、
変数@code{debug-on-signal}に@code{nil}以外の値を設定します。
また、条件に@code{debug}を指定することで、下記に示すように
特定のハンドラにおいてデバッガを優先して起動させることができます。

@example
@group
(condition-case nil
    (delete-file filename)
  ((debug error) nil))
@end group
@end example

@noindent
The effect of @code{debug} here is only to prevent
@code{condition-case} from suppressing the call to the debugger.  Any
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

一度、Emacsが特定のエラーハンドラがエラーを処理すると決めた場合、制御を当該ハンドラに返します。
そうするために、Emacsは、抜け出し対象となる束縛作成構造が設定した
すべての変数束縛を解き、抜け出し対象となるフォーム@code{unwind-protect}
すべての後始末を実行します。
ハンドラに制御が移ると、ハンドラの本体を実行します。

ハンドラ本体の実行を完了すると、
フォーム@code{condition-case}から戻ります。
ハンドラを実行するまえに保護されたフォームから完全に抜けているので、
ハンドラでは、エラー発生時点から再開したり、
保護されたフォームの内側で作られた変数束縛を調べたりすることはできません。
ハンドラでできることは、後始末をして先へ進むことだけです。

エラー通知とエラー処理は、@code{throw}と@code{catch}に多少似ています
（@pxref{Catch and Throw}）が、
それらはまったく別の機能です。
@code{catch}ではエラーを捕捉できませんし、
エラーハンドラでは@code{throw}を処理できません
（しかしながら、適切な@code{catch}がない@code{throw}を使うと、
処理できるエラーを通知する）。

@defspec condition-case var protected-form handlers@dots{}
このスペシャルフォームは、@var{protected-form}の実行中は
エラーハンドラ@var{handlers}を確立する。
@var{protected-form}がエラーなしに完了すると、
その戻り値がフォーム@code{condition-case}の値になる。
この場合、@code{condition-case}はなんの効果もない。
フォーム@code{condition-case}で違いがでるのは、
@var{protected-form}の実行中にエラーが起こった場合である。

各@var{handlers}は、@code{(@var{conditions} @var{body}@dots{})}の形式の
リストである。
ここで@var{conditions}は、処理すべきエラーの条件名か条件名
（@code{debug}を含めることで、ハンドラより先にデバッガを起動させることができる）
のリストである。
@var{body}は1つ以上のLisp式であり、
このハンドラがエラーを処理するときに実行される。
ハンドラの例を示す。

@example
@group
(error nil)

(arith-error (message "Division by zero"))

((arith-error file-error)
 (message
  "Either division by zero or failure to open a file"))
@end group
@end example

生起する各エラーには、
そのエラーの種類を表す@dfn{エラーシンボル}（error symbol）がある。
そのシンボルの属性@code{error-conditions}は、
条件名のリストである（@pxref{Error Symbols}）。
Emacsは、有効なフォーム@code{condition-case}すべてを探索し、
これらの条件名を1つ以上指定したハンドラを探す。
もっとも内側の一致する@code{condition-case}がエラーを処理する。
この@code{condition-case}の内側では、
適用可能な最初のハンドラがエラーを処理する。

ハンドラの本体の実行を完了すると、
@code{condition-case}は通常のように戻り、
ハンドラの本体の最後のフォームの値を全体としての値に使う。

@cindex エラー記述
引数@var{var}は変数である。
@code{condition-case}は、@var{protected-form}を実行するときには
この変数を束縛せず、エラーを処理するときだけ束縛する。
そのとき、@var{var}はローカルに@dfn{エラー記述}
（error description）に束縛される。
これは、エラーの詳細を与えるリストである。
エラー記述は、@code{(@var{error-symbol} . @var{data})}の形式である。
ハンドラは、動作を決定するためにこのリストを参照できる。
たとえば、ファイルのオープンに失敗したエラーであれば、
@var{data}の第2要素、エラー記述の第3要素がファイル名である。

@var{var}が@code{nil}であると、変数を束縛しなことを意味する。
そうすると、ハンドラではエラーシンボルと関連するデータを使えない。

@cindex rethrow a signal
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:

@example
  (signal (car err) (cdr err))
@end example

@noindent
where @code{err} is the error description variable, the first argument
to @code{condition-case} whose error condition you want to re-throw.
@xref{Definition of signal}.
@end defspec

@defun error-message-string error-descriptor
この関数は、指定したエラー記述に対するエラーメッセージ文字列を返す。
エラーに対する普通のエラーメッセージを表示して、
エラーを処理したい場合に便利である。@xref{Definition of signal}。
@end defun

@cindex @code{arith-error}の例
ゼロ除算の結果であるエラーを処理する@code{condition-case}の使用例を示します。
ハンドラはエラーメッセージを（ベルを鳴らさずに）表示して、
大きな数を返します。

@example
@group
(defun safe-divide (dividend divisor)
  (condition-case err                
      ;; @r{保護されたフォーム}
      (/ dividend divisor)              
@end group
@group
    ;; @r{ハンドラ}
    (arith-error                        ; @r{条件}
     ;; @r{このエラーに対する普通のメッセージを表示する}
     (message "%s" (error-message-string err))
     1000000)))
@result{} safe-divide
@end group

@group
(safe-divide 5 0)
     @print{} Arithmetic error: (arith-error)
@result{} 1000000
@end group
@end example

@noindent
ハンドラは条件名@code{arith-error}を指定しているので、
ゼロ除算エラーだけを処理します。
少なくともこの@code{condition-case}では他の種類のエラーは処理しません。
したがって、つぎのようになります

@example
@group
(safe-divide nil 3)
     @error{} Wrong type argument: number-or-marker-p, nil
@end group
@end example

以下は、@code{error}で通知されるエラーも含めて、
すべての種類のエラーを捕捉する@code{condition-case}です。

@example
@group
(setq baz 34)
     @result{} 34
@end group

@group
(condition-case err
    (if (eq baz 35)
        t
      ;; @r{これは関数@code{error}の呼び出し}
      (error "Rats!  The variable %s was %s, not 35" 'baz baz))
  ;; @r{これはハンドラ。フォームではない}
  (error (princ (format "The error was: %s" err)) 
         2))
@print{} The error was: (error "Rats!  The variable baz was 34, not 35")
@result{} 2
@end group
@end example

@defmac ignore-errors body@dots{}
This construct executes @var{body}, ignoring any errors that occur
during its execution.  If the execution is without error,
@code{ignore-errors} returns the value of the last form in @var{body};
otherwise, it returns @code{nil}.

Here's the example at the beginning of this subsection rewritten using
@code{ignore-errors}:

@example
@group
  (ignore-errors
   (delete-file filename))
@end group
@end example
@end defmac

@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.
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

@node Error Symbols
@subsubsection エラーシンボルと条件名
@cindex エラーシンボル
@cindex エラー名
@cindex 条件名
@cindex ユーザー定義エラー
@kindex error-conditions

エラーを通知するときには、読者が意図するエラーの種類を指定する
@dfn{エラーシンボル}（error symbol）を指定します。
各エラーには、それを分類する一意な名前があります。
これは、Emacs Lisp言語で定義されたエラーを細分類したものです。

これらの細分類は、@dfn{エラー条件}（error conditions）と呼ばれる
より大きなクラスの階層にまとめられています。
エラー条件は、@dfn{条件名}（condition names）で識別します。
もっとも細かい分類は、エラーシンボルそのものです。
各エラーシンボルは条件名でもあります。
より大きなクラスを表す条件名@code{error}もあります。
これはすべての種類のエラー（@code{quit}を除く）を表します。
したがって、各エラーには、1つ以上の条件名があります。
つまり、@code{error}、@code{error}とは別のエラーシンボル、あるいは、
その中間の分類に属するものです。

@defun define-error name message &optional parent
あるシンボルがエラーシンボルであるためには、そのシンボルは、
@code{define-error}によって定義されなければなりません。
この関数は引数として親の状態（デフォルトは@code{error}）を取ります。
この親はこの種のエラーが所属する状態を定義します。
親の遷移的集合は常に、エラーシンボル自身と @code{error}を含みます。
quitはエラーとは考慮されないため、@code{quit}の親は単に@code{(quit)}となります。
@end defun

@cindex peculiarエラー
@code{error-conditions}リストに加えて、
エラーシンボルには、属性@code{message}も持ち、
この属性の値は、そのエラーが通知されたのに処理されないときに表示される文字列です。
もしメッセージが適切でなければ、
エラーメッセージ@samp{peculiar error}を使います。
@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.

以下に、新たなエラーシンボル@code{new-error}の定義方法を示します。

@example
@group
(define-error 'new-error "A new error" 'my-own-errors)
@end group
@end example

@noindent
このエラーには、3つの条件名があります。
もっとも細かい分類である@code{new-error}、
それより大きな分類とであると考えている@code{my-own-errors}、
もっとも大きな分類である@code{error}です。

エラー文字列は大文字で始めるべきですが、ピリオドで終えません。
これは、Emacsの他の慣習と整合をとるためです。

普通、Emacs自身が@code{new-error}を通知することはありえません。
つぎのように、読者のコードで明示的に
@code{signal}（@pxref{Definition of signal}）を呼んだときだけです。

@example
@group
(signal 'new-error '(x y))
     @error{} A new error: x, y
@end group
@end example

このエラーは、3つの条件名のどれでも処理できます。
つぎの例は、@code{new-error}と
クラス@code{my-own-errors}の任意の他のエラーを処理します。

@example
@group
(condition-case foo
    (bar nil t)
  (my-own-errors nil))
@end group
@end example

エラーを分類する重要な方法は、それらの条件名によることです。
つまり、エラーに一致するハンドラを探すために条件名を使います。
エラーシンボルは、意図したエラーメッセージと条件名のリストを指定する
簡便な方法を提供するだけです。
@code{signal}に、1つのエラーシンボルではなく、
条件名のリストを指定するのではわずらわしいでしょう。

一方、条件名なしにエラーシンボルだけを使うのでは、
@code{condition-case}の能力をいちじるしく損ないます。
条件名があることで、エラーハンドラを書くときにさまざまなレベルに
一般化してエラーを分類できるのです。
エラーシンボルだけを使ったのでは、
最細分類以外のレベルを削除してしまうことになります。

すべての標準エラー名とそれらの条件名については、
@xref{Standard Errors}。

@node Cleanups
@subsection 非ローカル脱出時の後始末

@code{unwind-protect}構造は、データ構造を一時的に整合性のない状態に
するときには本質的です。
この構造により、エラーや非ローカル脱出が起こったときに、
データの整合性を回復できます。

@defspec unwind-protect body-form cleanup-forms@dots{}
@cindex 後始末フォーム
@cindex 保護されたフォーム
@cindex エラーの後始末
@code{unwind-protect}は、@var{body-form}からどのように制御が離れた場合にも
@var{cleanup-forms}の実行を保証する。
@var{body-form}は通常どおり完了するか、
@code{throw}を実行して@code{unwind-protect}から脱出するか、
エラーを引き起こす。
いずれの場合でも、@var{cleanup-forms}は評価される。

フォーム@var{body-form}が正常に終了すると、
@code{unwind-protect}は、@var{cleanup-forms}を評価したあとに、
フォーム@var{body-form}の最後の値を返す。
フォーム@var{body-form}が完了しなかった場合、
@code{unwind-protect}は普通の意味での値は返さない。

@code{unwind-protect}が保護するのは@var{body}だけである。
@var{cleanup-forms}そのもののどれかが（@code{throw}やエラーで）
非ローカル脱出を行うと、@code{unwind-protect}は、
@var{cleanup-forms}の残りを評価することを保証@emph{しない}。
@var{cleanup-forms}のどれかが失敗するとトラブルになる危険性がある場合には、
@var{cleanup-forms}を別の@code{unwind-protect}で保護する。

フォーム@code{unwind-protect}の現在の入れ子の個数は、
ローカル変数束縛の個数とともに数えられ、
@code{max-specpdl-size}に制限されている（@xref{Local Variables}）。
@end defspec

たとえば、表示しないバッファを一時的に作成し、
終了前に確実にそれを消去したいとしましょう。

@example
@group
(let ((buffer (get-buffer-create " *temp*")))
  (with-current-buffer buffer
    (unwind-protect
        @var{body-form}
      (kill-buffer buffer))))
@end group
@end example

@noindent
変数@code{buffer}を使わずに@code{(kill-buffer
(current-buffer))}と
書くだけで十分だと考えるかもしれません。
しかし、別のバッファに切り替えたあとで@var{body-form}でエラーが発生した場合には、
上の方法はより安全です。
（あるいは、@var{body-form}の周りに別の@code{save-excursion}を書いて、
一時バッファを消去するときに、それがカレントバッファになることを
保証する。）

Emacsには、上のようなコードに展開される@code{with-temp-buffer}という
標準マクロがあります（@pxref{Current Buffer}）。
本書で定義しているマクロのいくつかでは、
このように@code{unwind-protect}を使っています。

@findex ftp-login
ファイル@file{ftp.el}から持ってきた実際の例を示しましょう。
リモートの計算機への接続を確立するプロセス（@pxref{Processes}）を作ります。
関数@code{ftp-login}は、その関数の作成者が予想できないほどの
数多くの問題に対してとても敏感ですから、
失敗したときにプロセスを消去することを保証するフォームで保護します。
さもないと、Emacsは、無用なサブプロセスで満たされてしまいます。

@example
@group
(let ((win nil))
  (unwind-protect
      (progn
        (setq process (ftp-setup-buffer host file))
        (if (setq win (ftp-login process host user password))
            (message "Logged in")
          (error "Ftp login failed")))
    (or win (and process (delete-process process)))))
@end group
@end example

この例には、小さなバグが1つあります。
ユーザーが@kbd{C-g}を打って中断しようとして、かつ、
関数@code{ftp-setup-buffer}の終了後に
変数@code{process}を設定するまえに実際に中断が行われると、
プロセスは消去されません。
このバグを直す簡単な方法はありませんが、
少なくとも、ほとんど起こりえません。