<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE book [
<!ELEMENT book (chapter*)>
<!ELEMENT chapter (title,type,arguments?,package?,description,seealso*,link*,section,file?)>
<!ELEMENT title (#PCDATA)>
<!ELEMENT type (#PCDATA)>
<!ELEMENT arguments (#PCDATA)>
<!ELEMENT package (#PCDATA)>
<!ELEMENT description (#PCDATA)>
<!ELEMENT seealso (#PCDATA)>
<!ELEMENT link (#PCDATA)>
<!ELEMENT section (#PCDATA)>
<!ELEMENT file (#PCDATA)>
]>
<!--
reference/condition-restart.xml

xyzzy 用拡張ライブラリ condition-restart で定義している関数やマクロのリファ
レンスです。

参考:
- へなちょこリファレンス http://xyzzy.s53.xrea.com/wiki/index.php?%A5%EA%A5%D5%A5%A1%A5%EC%A5%F3%A5%B9

この XML の使い方
=================
以下のものが必要です。全てネットインストーラから入手できます。
- info-modoki-mode
- reference.xml
- xy-reference

xy-reference で reference.xml とこの XML ファイルから、info-modoki-mode
で読み込める reference.txt を作っておけば、info-modoki-mode で標準の関数
と同様に condition-restart で定義している関数などのリファレンスを参照で
きるようになります。

    ;; *scratch* などで以下を実行する
    (progn
      (require :xy-reference)
      (xy-reference:2txt))

    ;; info-modoki-mode が既に reference.txt を開いているので閉じる
    (delete-buffer *imm-buffer*)
-->
<book>

<chapter>
<title>select-restart-interactively</title>
<type>Function</type>
<arguments>select-restart-interactively CONDITION</arguments>
<package>editor</package>
<description>
対話的に再起動を選んで起動します。
再起動が用意された環境で select-restart-interactively にコンディション
を与えて実行すると、ウィンドウを分割して与えられたコンディションと有効
な再起動を表示し、ミニバッファから再起動を選ぶことができます。

使用例:
  ;;; ミニバッファで入力した式を評価して、エラーが投げられたら対話的に
  ;;; 再起動を選ぶ
  (handler-bind ((error #'ed::select-restart-interactively))
    (eval (read-sexp "FORM: ")))
</description>
<seealso></seealso>
<link></link>
<section>エラー</section>
<file>condition-restart-support.l</file>
</chapter>

<chapter>
<title>assert</title>
<type>Macro</type>
<arguments>assert TEST-FORM {(PLACE*) {DATUM ARGS*}</arguments>
<package>lisp</package>
<description>
TEST-FORM が true に評価されることを確実にします。

TEST-FORM が false に評価されると、continue 再起動を用意したうえで DATUM
と ARGS で指定されたエラーを投げます。
この continue 再起動を起動すると PLACE* の値をミニバッファで入力した値で
置き換えてから、assert の最初（TEST-FORM の評価）からやり直します。

  TEST-FORM   : true を返すはずの任意の式を指定します。
                1回以上評価されます。
  PLACE       : continue 再起動を起動したときに置き換える場所（setf 可能
                な汎変数）を指定します。
  DATUM, ARGS : 投げるエラーを指定します（error 関数参照）。
                省略した場合は simple-error が投げられます。

</description>
<seealso>check-type</seealso>
<link>[CLHS: Macro assert] http://www.lispworks.com/documentation/HyperSpec/Body/m_assert.htm</link>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>check-type</title>
<type>Macro</type>
<arguments>check-type PLACE TYPESPEC [STRING]</arguments>
<package>lisp</package>
<description>
PLACE の値が TYPESPEC の型であることを確実にします。

もし PLACE の値が TYPESPEC の型ではなかった場合、store-value 再起動を用
意した上で si::check-type-error を投げます。この store-value 再起動を起
動すると、PLACE の値を置き換えて check-type をやり直します。
PLACE の値が TYPESPEC の型であれば check-type 式は nil を返します。

  PLACE    : 調べる場所。setf できる式を指定します。
  TYPESPEC : typep に渡す型指定をクォートせずに指定します。
  STRING   : TYPESPEC を説明する文字列です。
</description>
<seealso>assert</seealso>
<seealso>typep</seealso>
<seealso>deftype</seealso>
<link>[CLHS: Macro check-type] http://www.lispworks.com/documentation/HyperSpec/Body/m_check_.htm</link>
<section>データ型</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>再起動ってなに</title>
<type>Tips</type>
<description>
エラーやコンディションを投げるときに、投げる側でその状況に対応する方法を
選択肢として用意しておく仕組みです。

エラーを投げるときに restart-case や restart-bind で再起動を用意しておく
と、エラーを捕まえたハンドラなどから invoke-restart などで用意された再起
動を起動することができます。この再起動はエラーを投げた側のローカルな環境
にアクセスできるので、変数の値を変更したり、適当なところへ制御を移して別
の値を返したりすることができます。

</description>
<seealso>restart-case</seealso>
<seealso>restart-bind</seealso>
<seealso>invoke-restart</seealso>
<seealso>find-restart</seealso>
<seealso>handler-bind</seealso>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>use-value</title>
<type>Function</type>
<arguments>use-value VALUE &amp;optional CONDITION</arguments>
<package>lisp</package>
<description>
use-value 再起動を起動して、そのときだけ VALUE を使うようにします。
もし有効な use-value 再起動が見つからなかった場合は nil を返します。

use-value 再起動について:
  変数の値がおかしかったりしたときに、そのときだけ代わりの値を使うような
  再起動です。
  変数の値を変更する場合は store-value 再起動を使います。
</description>
<seealso>store-value</seealso>
<link>[CLHS: Function use-value] http://www.lispworks.com/documentation/lw50/CLHS/Body/f_abortc.htm#use-value</link>
<link>[CLHS: Restart use-value] http://www.lispworks.com/documentation/lw50/CLHS/Body/r_use_va.htm</link>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>store-value</title>
<type>Function</type>
<arguments>store-value NEW-VALUE &amp;optional CONDITION</arguments>
<package>lisp</package>
<description>
store-value 再起動を起動して、変数の値を NEW-VALUE に変更します。
もし有効な store-value 再起動が見つからなかった場合は nil を返します。

store-value 再起動について:
  変数や汎変数の値を変更して処理を続行するような再起動です
  store-value 再起動を用意するときは、再起動の概要にどの変数の値を変更
  するのか書いておきましょう。
</description>
<seealso>use-value</seealso>
<seealso>check-type</seealso>
<link>[CLHS: Function store-value] http://www.lispworks.com/documentation/lw50/CLHS/Body/f_abortc.htm#store-value</link>
<link>[CLHS: Restart store-value] http://www.lispworks.com/documentation/lw50/CLHS/Body/r_store_.htm</link>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>continue</title>
<type>Function</type>
<arguments>continue &amp;optional CONDITION</arguments>
<package>lisp</package>
<description>
continue 再起動を起動して、そのまま処理を続行します。
もし有効な continue 再起動が見つからなかった場合は nil を返してます。

  CONDITION : コンディションを指定すると、そのコンディションに対応した
              continue 再起動を探して起動します。

continue 再起動について:
  単純に処理を続行するような再起動です。
  ※ 警告 (warning) を無視するときは muffle-warning を使います。
</description>
<seealso>restart-case</seealso>
<seealso>abort</seealso>
<seealso>muffle-warning</seealso>
<seealso>store-value</seealso>
<seealso>use-value</seealso>
<seealso>invoke-restart</seealso>
<link>[CLHS: Function continue] http://www.lispworks.com/documentation/lw50/CLHS/Body/f_abortc.htm#continue</link>
<link>[CLHS: Restart continue] http://www.lispworks.com/documentation/lw50/CLHS/Body/r_contin.htm</link>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>abort</title>
<type>Function</type>
<arguments>abort &amp;optional CONDITION</arguments>
<package>lisp</package>
<description>
abort 再起動を起動して、処理を中止しようとします。
もし有効な abort 再起動が見つからなかった場合は、silent-quit を投げて
処理を中止するかも{{詳細未定}}。

  CONDITION : コンディションを指定すると、そのコンディションに対応した
              abort 再起動を探して起動します。

abort 再起動について:
  処理を中止するような再起動です。
</description>
<seealso>restart-case</seealso>
<seealso>invoke-restart</seealso>
<link>[CLHS: Function abort] http://www.lispworks.com/documentation/lw51/CLHS/Body/f_abortc.htm</link>
<link>[CLHS: Restart abort] http://www.lispworks.com/documentation/lw50/CLHS/Body/r_abort.htm</link>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>muffle-warning</title>
<type>Function</type>
<arguments>muffle-warning &amp;optional WARNING</arguments>
<package>lisp</package>
<description>
muffle-warning 再起動を起動して、警告を無視します。

  WARNING: 警告を指定すると、その警告に対応した muffle-warning を探して
           起動します。

muffle-warning 再起動について:
  警告を無視する再起動です。warn 関数を参照してください。
</description>
<seealso></seealso>
<link>[CLHS: Function muffle-warning] http://www.lispworks.com/documentation/lw50/CLHS/Body/f_abortc.htm#muffle-warning</link>
<link>[CLHS: Restart muffle-warning] http://www.lispworks.com/documentation/lw50/CLHS/Body/r_muffle.htm</link>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>warn</title>
<type>Function</type>
<arguments>warn DATUM &amp;rest ARGS</arguments>
<package>lisp</package>
<description>
※これは condition-restart.l で上書きされた warn の説明です。
警告（warning コンディション）を投げます。

warn 関数は、警告を投げるときに muffle-warning 再起動を確立しておきます。
この muffle-warning 再起動を起動すると警告を無視することができます。

  DATUM, ARGS : 投げる警告を指定します。error 関数を参照してください。
                DATUM にフォーマット文字列を指定した場合は、simple-warning
                を投げます。

投げられた警告が無視も処理もされずにトップレベルまで到達すると、xyzzy は
警告音を鳴らしたりします（共通設定-&gt;いろいろ で設定できます）が、処理
を中止したりはせず、warn 式からは nil が返ります。
</description>
<seealso>error</seealso>
<seealso>signal</seealso>
<seealso>muffle-warning</seealso>
<link>[CLHS: Function warn] http://www.lispworks.com/documentation/lw50/CLHS/Body/f_warn.htm</link>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>cerror</title>
<type>Function</type>
<arguments>cerror FMT-CONTROL DATUM &amp;rest ARGS</arguments>
<package>lisp</package>
<description>
回復可能なエラーを投げます。

関数 error 同様に DATUM（及び ARGUMENTSS）で指定されたエラーを投げますが、
そのときに再起動 continue を確立しておきます。
この continue 再起動を起動すると cerror 式から nil を返して、その後の処理
を続行させることができます。

  FMT-CONTROL : 再起動の概要を出力するフォーマット文字列です。引数として
                ARGS が与えられます。
  DATUM, ARGS : 投げるエラーを指定します。詳しくは error 関数を参照してく
                ださい。

ARGS は再起動の概要とエラー指定の両方に使われます。エラー指定に必要だけど
概要の出力には不要なものは "~*" で無視することができます。

</description>
<seealso>signal</seealso>
<seealso>error</seealso>
<link>[CLHS: Function cerror] http://www.lispworks.com/documentation/lw51/CLHS/Body/f_cerror.htm#cerror</link>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>invoke-restart-interactively</title>
<type>Function</type>
<arguments>invoke-restart-interactively IDENTIFIER</arguments>
<package>lisp</package>
<description>
再起動を対話的に起動します。
invoke-restart-interactively によって起動された再起動は、restart-case の
:interactive オプションや restart-bind の :interactive-function オプショ
ンで指定された関数を実行することで、再起動の引数を対話的に取得します。

  IDENTIFIER : 再起動の名前（シンボル）か再起動オブジェクトを指定します。

</description>
<seealso>restart-bind</seealso>
<seealso>restart-case</seealso>
<seealso>invoke-restart</seealso>
<link>[CLHS: Function invoke-restart-interactively] http://www.lispworks.com/documentation/lw50/CLHS/Body/f_invo_2.htm#invoke-restart-interactively</link>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>find-restart</title>
<type>Function</type>
<arguments>find-restart IDENTIFIER &amp;optional CONDITION</arguments>
<package>lisp</package>
<description>
指定された再起動を探して返します。見つからなかったら nil を返します。

  IDENTIFIER : 再起動の名前（シンボル）か再起動オブジェクトを指定します。
  CONDITION  : コンディションを指定すると、そのコンディションに対して有効
               な再起動の中から探します。
               restart-bind の :test-function 参照。

再起動の有効/無効について:
  find-restart や compute-restart は restart-bind によって用意された再起動
  の中から探してきますが、コンディションが指定された場合は以下の条件を満た
  す再起動のみが有効になります。
  - TEST-FUNCTION があるなら、TEST-FUNCTION をコンディションを引数に呼び出
    して true が返る。
  - 指定されたコンディションに関連付けられているか、どのコンディションにも
    関連付けられていない。
</description>
<seealso>restart-bind</seealso>
<seealso>restart-case</seealso>
<seealso>compute-restarts</seealso>
<link>[CLHS: Function find-restart] http://www.lispworks.com/documentation/lw50/CLHS/Body/f_find_r.htm#find-restart</link>
<file>condition-restart.l</file>
<section>エラー</section>
</chapter>

<chapter>
<title>invoke-restart</title>
<type>Function</type>
<arguments>invoke-restart IDENTIFIER &amp;rest ARGUMENTS</arguments>
<package>lisp</package>
<description>
IDENTIFIER で指定される再起動を起動します。

  IDENTIFIER : 起動する再起動の名前（シンボル）か再起動オブジェクトを指
               定します。
  ARGUMENTS  : 再起動に渡す引数があれば。

指定された再起動が見つからなかった場合は restart-not-found エラーを投げ
ます。

通常、再起動はどこかへ制御を飛ばすので invoke-restart で再起動を起動する
と制御は戻ってきませんが、起動した再起動が制御を飛ばさなかった（普通に値
を返した）場合、invoke-restart は再起動が返した値をそのまま返します。
</description>
<seealso>find-restart</seealso>
<seealso>restart-case</seealso>
<link>[CLHS: Function invoke-restart] http://www.lispworks.com/documentation/lw50/CLHS/Body/f_invo_1.htm#invoke-restart</link>
<file>condition-restart.l</file>
<section>エラー</section>
</chapter>

<chapter>
<title>compute-restarts</title>
<type>Function</type>
<arguments>compute-restarts &amp;optional CONDITION</arguments>
<package>lisp</package>
<description>
現在の環境で確立されている再起動のリストを返します。

  CONDITION : コンディションを指定すると、そのコンディションに対して有効
              な再起動のみのリストを返します。
</description>
<seealso>restart-case</seealso>
<seealso>restart-bind</seealso>
<seealso>with-simple-restart</seealso>
<seealso>find-restart</seealso>
<seealso>invoke-restart</seealso>
<link>[CLHS: Function compute-restarts] http://www.lispworks.com/documentation/lw50/CLHS/Body/f_comp_1.htm#compute-restarts</link>
<file>condition-restart.l</file>
<section>エラー</section>
</chapter>

<chapter>
<title>with-simple-restart</title>
<type>Macro</type>
<arguments>with-simple-restart (NAME FMT-CONTROL &amp;rest FMT-ARGUMENTS) &amp;body FORMS</arguments>
<package>lisp</package>
<description>
NAME という名前の再起動を確立した環境で FORMS を評価します。
この再起動が起動されると、with-simple-restart 式は多値で nil と t を返し
て終了します。
</description>
<link>[CLHS: Macro with-simple-restart] http://www.lispworks.com/documentation/lw50/CLHS/Body/m_w_smp_.htm#with-simple-restart</link>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>with-condition-restarts</title>
<type>Macro</type>
<arguments>with-condition-restarts CONDITION RESTARTS FORM*</arguments>
<package>lisp</package>
<description>
再起動とコンディションを関連付けます。

{{関連付けるってなによ}}

  CONDITION : 関連付けるコンディションを指定します。
              コンディションの型ではなくコンディションオブジェクトを指定
              します。
  RESTARTS  : 関連付ける再起動のリストを指定します。


find-restart や compute-restarts の引数にコンディションを与えて呼び出すと
そのコンディションに関連付けられた再起動（とどのコンディションにも関連付け
られていない再起動）のみを探すことができます。

例えば、いくつか再起動を用意してコンディション FOO が投げられたとします。
それを捕まえたハンドラが、更にいくつかの再起動を追加で用意して別のコンディ
ション BAR を投げたとします。
さらに上位のハンドラがコンディション BAR を捕まえた時点では、上記の全ての
再起動が有効なままですが、コンディション FOO に関連付けられた再起動は無視
してコンディション BAR に関連付けられた再起動の中から選んで起動することが
できたりします。

</description>
<seealso>restart-case</seealso>
<seealso>find-restart</seealso>
<seealso>compute-restarts</seealso>
<link>[CLHS: Macro with-condition-restarts] http://www.lispworks.com/documentation/HyperSpec/Body/m_w_cnd_.htm#with-condition-restarts</link>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>restart-case</title>
<type>Macro</type>
<arguments>restart-case FORM RESTART-CLAUSE*</arguments>
<package>lisp</package>
<description>
RESTART-CLAUSE で指定された再起動を用意して FORM を評価します。

restart-case で用意された再起動が起動されると、再起動の本体を実行し、
その結果を restart-case 式の結果として返します。

  (restart-case
      FORM
    (NAME LAMBDA-LIST
      {:interactive INTERACTIVE-EXPR}
      {:report REPORT-EXPR}
      {:test TEST-EXPR}
      BODY...)
    ...)

  NAME             : 再起動の名前をシンボルで指定します。
  LAMBDA-LIST      : 再起動の仮引数を指定します。lambda とかで使うことの
                     できる &amp;optional やら &amp;rest やらを使えます。
  BODY             : 再起動の処理本体です。
                     LAMBDA-LIST で指定した仮引数が与えられた引数に束縛
                     された環境で実行され、BODY の結果が restart-case 式
                     の結果となります。

  INTERACTIVE-EXPR : 対話的に起動されたときに、実行される関数を、関数名
                     （シンボルかlambda 式）で指定します。
                     invoke-restart-interactively によってこの再起動が起
                     動されると、この関数が引数なしで呼び出され、戻り値
                     のリストを再起動の処理本体の引数として使用します。
  REPORT-EXPR      : 再起動の概要を説明する文字列か、概要を出力する関数の
                     名前を指定します。
              関数   : 関数名（シンボルか lambda 式）を指定します。
                       関数は出力先のストリームを受け取り、再起動の概要を
                       出力しなければなりません。
              文字列 : 再起動の概要をそのまま文字列で指定します。
  TEST-EXPR        : あるコンディションに対してその再起動が有効か否かを判
                     断する関数の名前を指定します。#' はつけないでください。
                     省略されるとその再起動は全てのコンディションに対して
                     有効になります。

FORM が signal, error, cerror, warn のいずれかで始まる式（か、それに展開
されマクロ呼び出し）だったら、その restart-case で用意される再起動は勝手
に投げられるコンディションに関連付けられます。

</description>
<seealso>invoke-restart</seealso>
<seealso>with-simple-restart</seealso>
<seealso>restart-bind</seealso>
<seealso>with-condition-restarts</seealso>
<link>[CLHS: Function restart-case] http://www.lispworks.com/documentation/lw50/CLHS/Body/m_rst_ca.htm</link>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

<chapter>
<title>restart-bind</title>
<type>Macro</type>
<arguments>restart-bind (&amp;rest RESTARTS) &amp;body BODY</arguments>
<package>lisp</package>
<description>
再起動を用意して BODY を評価します。

  (restart-bind ((NAME RESTART-FUNCTION
                   {:interactive-function INTERACTIVE-FUNCTION}
                   {:report-function REPORT-FUNCTION}
                   {:test-function TEST-FUNCTION})
                 ...)
    BODY...)

  NAME                 : 再起動の名前（シンボル）です。
  RESTART-FUNCTION     : 再起動の処理本体です。関数を指定します。

  INTERACTIVE-FUNCTION : invoke-restart-interactively によって対話的に起
                         動されたときに、RESTART-FUNCTION に与える引数を
                         取得する関数です。
                         この関数は引数なしで実行され、RESTART-FUNCTION
                         に渡す引数のリストを返さなければなりません。
  REPORT-FUNCTION      : 再起動の概要を出力する関数です。
                         引数に出力先のストリームを受け取り、その再起動の
                         概要を出力します。
  TEST-FUNCTION        : 通知されたコンディションに対してその再起動が有効
                         かどうかを判断する関数です。
                         この関数は引数にコンディションを受け取り、与えら
                         れたコンディションについてその再起動が有効だった
                         ら true を返しましょう。

restart-bind は再起動を用意するだけで、それ以上のことをしたい場合は自分で
やらなければなりません（tagbody と go で制御を移すとか）。
大抵の場合は restart-case の方が便利だと思います。
</description>
<seealso>with-simple-restart</seealso>
<seealso>restart-case</seealso>
<seealso>invoke-restart</seealso>
<link>[CLHS: Macro restart-bind] http://www.lispworks.com/documentation/lw50/CLHS/Body/m_rst_bi.htm</link>
<section>エラー</section>
<file>condition-restart.l</file>
</chapter>

</book>
