@comment -*-texinfo-*-
@c See the file elisp-jp.texi for copying conditions.
@c 複製の条件はelisp-jp.texiに書いてあります。

@c This file is intended to be used as a section within the Emacs Lisp 
@c Reference Manual.  It may also be used by an independent Edebug User 
@c Manual, edebug.tex, in which case the Edebug node below should be used 
@c with the following links to the Bugs section and to the top level:

@c , Bugs and Todo List, Top, Top

@node Edebug,, Compilation Errors, Debugging
@section Edebug
@cindex Edebug mode
@cindex Edebugモード[edebugもーど]

@cindex Edebug
  Edebug はEmacs Lispプログラムのソース・レベル・デバッガで、
以下のようなことができます。

@itemize @bullet
@item
評価をステップ実行し、各式の前後で止まること。

@item
条件つきまたは無条件のブレークポイントを設定すること。

@item
指定した条件が成立したときに停止すること(グローバル・ブレーク条件)。
@footnote{原著ではここだけグローバル・ブレーク・イベント
(the global break event)
としています。}

@item
遅くあるいは速くトレースすること。
各ストップ・ポイントや各ブレークポイントでしばらく停止すること。

@item
式の結果を表示し、あたかもEdebugの外にいるかのように式を評価すること。

@item 
式のリストを自動的に再評価し、
Edebugが表示を更新するごとにその結果を表示すること。

@item
関数の入口と出口でトレース情報を出力すること。

@item
エラーがおきたときに停止すること。

@item
Edebug自身のフレームを除いたバックトレースを表示すること。

@item
定義形式とマクロの引数評価を指定すること。

@item
おおまかな網羅率検査と頻度計数を得ること。
@end itemize

最初の三つの節を読めば十分にEdebugを使うことができるようになるでしょう。

@menu
* Using Edebug::		Edebug利用入門。
* Instrumenting::		Edebugでデバッグするためには、まず
				  コードの膳立てをする必要があります。
* Modes: Edebug Execution Modes. どのくらいの頻度で停止させるかの実行
				   モード。
* Jumping::			指定した場所へジャンプするコマンド。
* Misc: Edebug Misc.		いろいろなコマンド。
* Breakpoints::			プログラムを停止させるためのブレーク
				  ポイントの設定。
* Trapping Errors::		Edebugでのエラーのトラップ。
* Views: Edebug Views.		Edebugの内側や外側をながめる。
* Eval: Edebug Eval.		Edebugの中で式を評価する。
* Eval List::			Edebugにはいるたびに値を表示する式。
* Printing in Edebug::		印字のカスタマイズ。
* Trace Buffer::		トレース出力をバッファに出す方法。
* Coverage Testing::		評価網羅率の検査法。
* The Outside Context::		Edebugが保存復帰するデータ。
* Instrumenting Macro Calls::	マクロ呼出しをどのように処理するかの指定。
* Options: Edebug Options.	Edebugをカスタマイズするためのオプション
				  変数。
@end menu

@node Using Edebug, Instrumenting, Edebug, Edebug
@subsection Edebug利用入門

  EdebugでLispプログラムをデバッグするには、
まずあなたがデバッグしたいLispコードの@dfn{膳立て(instrument)}を
しなければなりません。
これを簡単に行なう方法は、
まず、
ポイントをマクロや関数定義の中に移動して、
@kbd{C-u C-M-x} (前置引数をつけた@code{eval-defun)}
をすることです。
コードの膳立てをするほかの方法については@ref{Instrumenting}。

  いったん関数が膳立てをされると、
その関数のどのような呼出しもEdebugをアクティブにします。
Edebugをアクティブにすると、
あなたの選択したEdebug実行モードによって、
実行を停止して関数をずっとステップさせたり、
表示を更新しデバッグ用コマンドを調べながら実行を継続させたりすることがで
きます。
デフォルトの実行モードはstepで、
これは実行を停止させます。@xref{Edebug Execution Modes}。

  Edebugの中にいるときは、
デバッグ中のLispコードのソースを示しているEmacsのバッファを、
通常ながめることになります。
これを@dfn{ソース・コード・バッファ(source code buffer)}といいます。
このバッファは一時的に読出し専用です。

  左はしの矢印は関数の実行している箇所を示します。
ポイントははじめ関数が行のどこを実行しているのかを示していますが、
あなたが自分でポイントを動かしてしまうとそうでなくなります。

  もし(以下に示す)@code{fac}の定義の膳立てをして@code{(fac 3)}を実行すると、
以下のようなものが見られるはずです。
ポイントは@code{if}の前の開き括弧にあります。

@example
(defun fac (n)
=>@point{}(if (< 0 n)
      (* n (fac (1- n)))
    1))
@end example

@cindex stop points
@cindex ストップ・ポイント[すとっぷぽいんと]
Edebugが関数中で実行を止められる
場所を@dfn{ストップ・ポイント(stop point)}といいます。
これはリストである部分式の前後と、
変数参照の後に起きます。
以下に関数@code{fac}のストップ・ポイントを終止符で示します。

@example
(defun fac (n)
  .(if .(< 0 n.).
      .(* n. .(fac .(1- n.).).).
    1).)
; (訳注:原文には@code{1-}の前にストップ・ポイントがなかった。)
@end example

ソース・コード・バッファでは、
Emacs Lispモードのコマンドに加えて、
Edebugの特殊なコマンドが有効です。
たとえば、Edebugコマンドの@key{SPC}を押下して、
次のストップ・ポイントまで実行することができます。
@code{fac}にはいった後、
@key{SPC}を1回押下した直後の様子を以下に示します。

@example
(defun fac (n)
=>(if @point{}(< 0 n)
      (* n (fac (1- n)))
    1))
@end example

Edebugが式の後で実行を止めたときは、
その式の値をエコー領域に表示します。

ほかによく使うコマンドとして、
@kbd{b}でストップ・ポイントにブレークポイントを設定したり、
@kbd{g}でブレークポイントまで実行したり、
@kbd{q}でEdebugを抜けて
トップレベルのコマンド・ループに戻ったりすることができます。
@kbd{?}で全Edebugのコマンドの一覧を見ることができます。

@node Instrumenting, Edebug Execution Modes, Using Edebug, Edebug
@subsection Edebugのために膳立てをする

  LispコードをデバッグするのにEdebugを使うためには、
まずはじめにコードの@dfn{膳立て(instrument)}をすることが必要です。
コードの膳立てをすると適切な場所でEdebugを起動するコードを追加します。

@kindex C-M-x
@findex eval-defun (Edebug)
  いったんEdebugをロードすると、
コマンド@kbd{C-M-x} (@code{eval-defun})は再定義されるので、
前置引数をつけて定義上で起動すると、
その定義を評価する前に膳立てをするようになります
(ソース・コード自身は修正しません)。
もし変数@code{edebug-all-defs}が非@code{nil}のとき、
前置引数の意味を反転させます。
このとき@kbd{C-M-x}は前置引数が@emph{ないとき}、
定義の膳立てをします。
@code{edebug-all-defs}のデフォルト値は@code{nil}です。
コマンド@kbd{M-x edebug-all-defs}は、
変数@code{edebug-all-defs}の値をトグルします。

@findex edebug-all-forms
@findex eval-region (Edebug)
@findex eval-current-buffer (Edebug)
  @code{edebug-all-defs}が非@code{nil}のとき、
コマンド@code{eval-region}、
@code{eval-current-buffer}、
@code{eval-buffer}も、
評価する定義の膳立てをします。
同様に、@code{edebug-all-forms}は、
@code{eval-region}が定義をしない形式も含んだ@emph{全}形式の膳立てをすべきかどうかを制御します。
これはロードや、
ミニバッファでの評価には関係ありません。
コマンド@kbd{M-x edebug-all-forms}は、
このオプションをトグルします。

@findex edebug-eval-top-level-form
別なコマンド@kbd{M-x edebug-top-level-form}は、
@code{edebug-all-defs}や@code{edebug-all-forms}の値にかかわらず
全トップレベルの形式の膳立てをします。

Edebugがセッションではじめてのコードの膳立てをしようとするとき、
フック@code{edebug-setup-hook}を作動させてから
これを@code{nil}にします。
使用中のパッケージにまつわるEdebug仕様指定を、
Edebugを使っているときだけロードするのに、
これを使えます。

Edebugがアクティブな間、
コマンド@kbd{I} (@code{edebug-instrument-callee})は、
もしされていなければ
ポイントの後のリスト形式に呼ばれているマクロや関数定義の膳立てをします。
これはEdebugがその関数のソースの場所がどこかわかっているときだけ可能です。
Edebugをロードすると、
@code{eval-region}は評価する全定義の位置を記録するようになります
(膳立てをしないときでも)。
関数の膳立てをしてからステップする@kbd{i}コマンド
(@pxref{Jumping})を参照してください。

@cindex special forms (Edebug)
@cindex interactive commands (Edebug)
@cindex anonymous lambda expressions (Edebug)
@cindex 特殊形式(Edebug)[とくしゅけいしきedebug]
@cindex 対話的コマンド(Edebug)[たいわてきこまんどedebug]
@cindex 匿名ラムダ式(Edebug)[とくめいらむだしきedebug]
@cindex Common Lisp (Edebug)
@pindex cl.el (Edebug)
@pindex cl-specs.el
  Edebugは、
標準の特殊形式、
式を引数にもつ対話的形式、
匿名ラムダ式、
ほかの定義形式について知っています。
ユーザが定義したマクロが、
マクロ呼出しの引数をどう処理するかは
Edebugにはわからないので、
あなたがEdebugにそれを教えなければなりません。
詳細は@xref{Instrumenting Macro Calls}。

@findex eval-expression (Edebug)
  膳立てを定義から除くには、単に膳立てをしないよう定義を再評価します。
膳立てをしないで形式を評価する二つの方法があります。
@code{load}でファイルから評価する方法と
ミニバッファから@code{eval-expression}
(@kbd{M-:})で評価する方法です。

  Edebugが膳立てをしている間に構文エラーを検出したときは、
誤ったコードにポイントを置き、@code{invalid-read-syntax}
エラーを通知します。

  Edebug内で有効なほかの評価関数については、@xref{Edebug Eval}。

@node Edebug Execution Modes, Jumping, Instrumenting, Edebug
@subsection Edebug実行モード

@cindex Edebug execution modes
@cindex Edebug実行モード[edebugじっこうもーど]
Edebugにはあなたがデバッグしているプログラムを作動させているときの実行モー
ドがいくつかあります。
これらの選択肢を@dfn{Edebug実行モード(Edebug execution mode)}といいます。
主モードや副モードと勘違いしないでください。現在のEdebug実行モードは、
Edebugが(訳注:実行を)停止させるまでにどれだけ実行を継続させるか、
そして、停止させる前に評価の進行状況をどの程度Edebugに表示させるかを、
決定します。

通常は、どのモードでプログラムを継続させるかというコマンドを押下するこ
とで、Edebug実行モードを指定します。これらのコマンドの一覧を示します。@kbd{S}
以外は少なくとも少しの間プログラムの実行を再開します。

@table @kbd
@item S
停止(stop):これ以上プログラムを実行しない。
Edebugのコマンドを待つ(@code{edebug-stop})。

@item @key{SPC}
ステップ(step):次のストップ・ポイントにきたら止める
(@code{edebug-step-mode})。

@item n
次(next):式の後にある次のストップ・ポイントで止める(@code{edebug-next-mode})。
@c Overfull対策
@c (2.04132pt too wide)だから無視。
@ref{Edebug Misc}の@code{edebug-forward-sexp}を参照。

@item t
トレース(trace):各Edebugストップ・ポイントで1秒休む
(@code{edebug-trace-mode})。

@item T
高速トレース(rapid trace):各ストップ・ポイントで表示を更新するが、
休みはしない
(@code{edebug-Trace-fast-mode})。

@item g
進める(go):次のブレークポイントまで作動させる
(@code{edebug-go-mode})。@xref{Breakpoints}。

@item c
続行(continue):各ブレークポイントで1秒休み続行する
(@code{edebug-continue-mode})。

@item C
高速続行(rapid continue):各ブレークポイントへポイントを移動するが、
休まない(@code{edebug-Continue-fast-mode})。

@item G
ノンストップで進める(go non-stop):ブレークポイントを無視する
(@code{edebug-Go-nonstop-mode})。
引き続き@kbd{S}や任意の編集コマンドを押下すると、
プログラムを止めることができます。
@end table

一般に上の表の上の方にある実行モードは、
表の下にあるモードよりプログラムをゆっくり動かしたり、
すぐに止めたりします。

実行中やトレース中にEdebugコマンドを押下して実行に割り込むことができます。
次のストップ・ポイントでEdebugはプログラムを止め、
あなたの押下したコマンドを実行します。
たとえば、実行中の@kbd{t}は、
次のストップ・ポイントからtraceモードに切り替えます。
実行を止め何もさせないようにするには@kbd{S}を使います。

関数がたまたま入力を読み込むものであったとき、
実行を割り込むつもりで押下した文字は、
関数によって代わりに読み込まれます。
プログラムが入力を要求するときについて注意を払っていれば、
そのような予期せぬ結果を避けることができます。

@cindex keyboard macros (Edebug)
@cindex キーボード・マクロ(Edebug)[きーぼーどまくろedebug]
この節のコマンドを含むキーボード・マクロは、うまく働きません。
プログラムに戻ろうとしてEdebugを抜けてもキーボード・マクロの追跡に失敗します。
これを直すのは大変です。
また、Edebugの外で定義したり実行したりするキーボード・マクロは、
Edebugのなかのコマンドには関係ありません。
通常これは長所です。
ですが@code{edebug-continue-kbd-macro}オプションを
参照してください(@pxref{Edebug Options})。

新しいEdebugレベルにはいったときは最初の実行は、
変数@code{edebug-initial-mode}の値となります。
デフォルトではstepモードを指定します。
たとえば、膳立てをされた関数が一つのコマンドから複数回呼ばれた場合、
同じEdebugレベルに複数回はいることもあることに注意してください。


@node Jumping, Edebug Misc, Edebug Execution Modes, Edebug
@subsection ジャンプ

  この節で述べられているコマンドは、
指定した場所に到達するまで実行します。
@kbd{i}以外のすべては、
停止する場所を確立するために一時的なブレークポイントを作り、
そしてgoモードにはいります。
想定したストップ・ポイントの前のブレークポイントも実行を止めます。
ブレークポイントの詳細については@xref{Breakpoints}。

これらのコマンドは非局所脱出のときは期待どおりには働きません。
なぜなら、
非局所脱出はプログラムを止めようと期待した一時的なブレークポイントを、
迂回するからです。

@table @kbd
@item h
ポイントの近くにあるストップ・ポイントまで進める(@code{edebug-goto-here})。

@item f
前方に式一つ分、すすめる
(@code{edebug-forward-sexp})。

@item o
含んでいる式が終わるまでプログラムを作動させる。

@item i
ポイントの後の形式で呼ばれる関数やマクロをステップする。
@end table

@kbd{h}コマンドは一時的なブレークポイントを使って、
ポイントの現在の位置の近くにあるストップ・ポイントまで続行します。
ブレークポイントの詳細については@ref{Breakpoints}を見てください。

@kbd{f}コマンドは、
プログラムの順方向へ式一つ分だけ実行します。
より正確にいえば、
@kbd{C-M-f}で到達する場所に一時的なブレークポイントを置き、
ブレークポイントで停止するようにgoモードで実行します。

前置引数@var{n}をつけると
一時的なブレークポイントはS式@var{n}個分向こうに置かれます。
もし含んでいるリストが、
@var{n}個の要素の前で終わっている場合、
止まる場所は含んでいる式の後になります。

@kbd{C-M-f}で到達する位置が
プログラムが本当に実行をする場所であることを注意してください。
たとえば、@code{cond}の中では、
これが正しくないこともあります。

@kbd{f}コマンドでは柔軟性のため、ストップ・ポイントからではなくポイントから
始めた@code{forward-sexp}を実行します。@emph{現在のストップ・ポイントから}、
式一つ分を実行したいときは、まず@kbd{w}を押下しポイントを動かしてから、@kbd{f}
を押下します。@refill

@kbd{o}コマンドは、
式から「抜け出るまで」続行します。
これはポイントを含むS式の終わりに一時的なブレークポイントを置きます。
含んでいるS式が関数定義自身であるときは、
@kbd{o}は定義中の最後のS式の前まで続行します。
今もしそこにいるなら関数から抜けて止まります。
いいかえると、
最後のS式の後にいなければ、
このコマンドは現在実行中の関数を抜けません。

@kbd{i}コマンドはポイントの後のリスト形式で呼ばれる関数やマクロをステップし、
最初のストップ・ポイントで停止させます。
形式は評価しようとしているものでなくともかまわないことに注意してください。
しかし、形式が評価しようとしている関数呼出しであるなら、
まだ引数の評価が始まらないうちにこのコマンドを使うようにしてください。
評価の始まった後では遅すぎます。

@kbd{i}コマンドはステップしようとしている関数あるいはマクロの膳立てを
(してなければ)します。
これは便利ですが、
陽に膳立てをやめるまではずっと膳立てをされたままになっている、
ということに、
気をつけてください。

@node Edebug Misc, Breakpoints, Jumping, Edebug
@subsection いろいろなEdebugのコマンド

  Edebugのそのほかのいろいろなコマンドについて解説します。

@table @kbd
@item ?
Edebugのヘルプ・メッセージを表示します
(@code{edebug-help})。

@item C-]
一つ前のレベルのコマンド・レベルに戻します
(@code{abort-recursive-edit})。

@item q
トップレベルのエディタ・コマンド・ループに戻ります(@code{top-level})。
これはEdebugの全レベルも含めすべての再帰編集レベルを抜けます。
しかしながら、
膳立てをしたコードで@code{unwind-protect}や@code{condition-case}形式で
保護されたもののせいで、
デバッグに戻されることがあります。

@item Q
@kbd{q}に似ていますが、
保護されたコードがあっても止めません
(@code{top-level-nonstop})。

@item r
わかっている一番最後の式の結果をエコー領域に再表示します
(@code{edebug-previous-result})。

@item d
Edebug自身の関数のそれを明確さのためにのぞいて、
バックトレースを表示します
(@code{edebug-backtrace})。

標準のデバッガのときとは違って、
Edebugのバックトレース・バッファの中では、
デバッガのコマンドは使えません。

実行を継続すると、バックトレース・バッファは自動的にkillされます。
@end table

Edebugの再帰編集からEdebugを再帰的にアクティブにするコマンドを
起動してもかまいません。
Edebugがアクティブなとき、
@kbd{q}でトップレベルまでとりやめたり、
@kbd{C-]}で再帰編集レベルを一つ中断したりできます。
@kbd{d}で評価を保留しているすべてのバックトレースを表示できます。

@node Breakpoints, Trapping Errors, Edebug Misc, Edebug
@subsection ブレークポイント

@cindex breakpoints
@cindex ブレークポイント[ぶれーくぽいんと]
Edebugのstepモードでは次のストップポイントに到達すると実行を止めます。
いったん動き始めたらEdebugが実行を止める方法は三つあります。
それはブレークポイント、
グローバル・ブレーク条件、
ソースのブレークポイントです。

Edebugを使っている間は、
テスト中のプログラムに@dfn{ブレークポイント(breakpoint)}、
実行を止めるべき点を、
指定できます。@ref{Using Edebug}で定義された任意のストップ・ポイントで
ブレークポイントを設定できます。
ブレークポイントを設定したり解除したりする際、
影響をうけるストップ・ポイントは最初のものかあるいは
ソース・コード・バッファのポイントの後にあるものです。
ブレークポイントにまつわるEdebugコマンドは以下のものがあります。

@table @kbd
@item b
ストップ・ポイント、あるいはポイントの後に、
ブレークポイントを置く(@code{edebug-set-breakpoint})。
前置引数を与えるとブレークポイントは一時的になります
(最初にそこでプログラムを止めたときに消えます)。

@item u
ストップ・ポイントあるいはポイントの後にあるブレークポイント(もしあれば)を
解除します(@code{edebug-unset-breakpoint})。

@item x @var{condition} @key{RET}
@var{condition}が非@code{nil}の値に評価したときにかぎって止める、
条件つきのブレークポイントを設定します
(@code{edebug-set-condition-breakpoint})。
前置引数を与えると、
ブレークポイントは一時的になります。

@item B
定義中の次のブレークポイントにポイントを動かします
(@code{edebug-next-breakpoint})。
@end table

Edebugにいる間ブレークポイントを@kbd{b}で設定したり、
@kbd{u}で解除したりすることができます。
まずポイントをあなたの好きなEdebugのストップ・ポイントに動かし、
@kbd{b}や@kbd{u}を押下して設定あるいは解除します。
ブレークポイントのないところで解除しても何の効果もありません。

定義の膳立てをしたり再評価をしたりすると、
その定義内のすべてのブレークポイントはなくなります。

@dfn{条件つきブレークポイント(conditional breakpoint)}は、
プログラムがそこにくるたびに条件を検査します。
条件の評価の結果起きたエラーはすべて無視し、
結果は@code{nil}とみなします。
条件つきブレークポイントを設定するには、
@kbd{x}を使ってミニバッファから条件式を指定します。
以前に確立した条件つきブレークポイントのあるストップ・ポイントに
条件つきブレークポイントを確立すると、
編集ができるようにミニバッファに前の条件式を置きます。

条件つきや無条件のブレークポイントを@dfn{一時的(temporary)}にするには、
設定するコマンドに前置引数を与えます。
一時的なブレークポイントがプログラムを止めたとき、
自動的に解除されます。

EdebugモードがGo-nonstopのとき以外は、
Edebugはブレークポイントで休んだり止まったりします。
Go-nonstopモードのときはすべて無視します。

ブレークポイントの場所を見つけるには、
@kbd{B}コマンドを使います。
これはポイントを、
同じ関数でポイントの後ろにある次のブレークポイントか、
もしそれがなければ最初のブレークポイントに動かします。
このコマンドは実行の継続はしません。
バッファのポイントを動かすだけです。

@menu
* Global Break Condition::	イベントでブレークする。
* Source Breakpoints::  	ソース・コードにブレークポイントを埋め込む。
@end menu


@node Global Break Condition, Source Breakpoints, Breakpoints, Breakpoints
@subsubsection グローバル・ブレーク条件

@cindex stopping on events
@cindex global break condition
@cindex 停止、条件つき実行[ていし、じょうけんつきじっこう]
@cindex 条件つき実行停止[じょうけんつきじっこうていし]
@cindex グローバル・ブレーク条件[ぐろーばるぶれーくじょうけん]
  @dfn{グローバル・ブレーク条件(global break condition)}は、
どこを実行していても、
指定した条件が成立したときに実行を止めます。
Edebugは各ストップ・ポイントでグローバル・ブレーク条件を評価します。
もしこれが非@code{nil}の値に評価したら、
ブレークポイントがあったかのように
実行モードにしたがって止まったり休んだりします。
評価でエラーが起きても実行を止めません。

@findex edebug-set-global-break-condition
@vindex edebug-global-break-condition
@c Overfull対策
@c  @kbd{X}コマンド(@code{edebug-set-global-break-condition})で、
  @kbd{X}コマンド(@code{edebug-set-global-break-condition})を使って、
@code{edebug-global-break-condition}に格納した条件式を、
設定したり編集したりできます。

  グローバル・ブレーク条件は、
あるイベントがコードのどこで起こったかをさがすための最も単純な方法ですが、
これによりコードの実行は非常に遅くなります。
ですから使わないときは条件を@code{nil}にするべきです。

@node Source Breakpoints,  , Global Break Condition, Breakpoints
@subsubsection ソースのブレークポイント

@findex edebug
@cindex source breakpoints
@cindex ソースのブレークポイント[そーすのぶれーくぽいんと]
  定義中の全ブレークポイントは、
あなたが再び膳立てをするたびに、
なくなります。
ブレークポイントがなくならないようにするには、
単にソース・コードから関数@code{edebug}を呼ぶだけの
@dfn{ソースのブレークポイント(source breakpoint)}を書くことができます。
もちろん条件をつけることもできます。
たとえば、
@code{fac}関数では、
以下に示すように1行目に引数が0になったときに止まるようにしています。

@example
(defun fac (n)
  (if (= n 0) (edebug))
  (if (< 0 n)
      (* n (fac (1- n)))
    1))
@end example

@code{fac}の定義が膳立てをされ関数が呼び出されると、
@code{edebug}の呼出しはブレークポイントのように作用します。
実行モードによってEdebugはそこで止まったり休んだりします。

膳立てをされた関数を実行していないときに@code{edebug}を呼び出すと、
その関数は@code{debug}を呼び出します。
@c This may not be a good idea anymore.

@node Trapping Errors, Edebug Views, Breakpoints, Edebug
@subsection エラーのトラップ

通常Emacsは@code{condition-case}でハンドルされないエラーが通知されると、
エラー・メッセージを表示します。
通常Edebugがアクティブな間はハンドルされていないすべてのエラーに反応します。
あなたはオプション@code{edebug-on-error}や@code{edebug-on-quit}で、
これをカスタマイズすることができます。@ref{Edebug Options}を参照してください。

Edebugがエラーに反応するとき、
エラーの前にあった最後のストップ・ポイントを表示します。
この場所は実際にエラーが起きたのとは別の、
膳立てをされていない関数を呼び出している箇所であることがあります。
束縛されていない変数のエラーの場合、
前のブレークポイントは変数を参照しているところからは、
とても離れているかもしれません。
この場合は全バックトレース(@pxref{Edebug Misc})を表示したくなるでしょう。

@c Edebug should be changed for the following: -- dan
Edebugがアクティブなとき
@code{debug-on-error}や@code{debug-on-quit}を変更しても、
Edebugがアクティブでなくなると変更は失われます。
さらにEdebugの再帰編集の間、
これらの変数は、
Edebugの外の値に束縛します。

@node Edebug Views, Edebug Eval, Trapping Errors, Edebug
@subsection Edebugでのながめ

以下のEdebugのコマンドは、
Edebugにはいる前に取得したバッファとウィンドウの状態の外観を見せてくれます。
外側のウィンドウ構成は、
Edebugの外側で有効になる
ウィンドウと(訳注:その)内容の集まりです。

@table @kbd
@item v
一時的に外側のウィンドウ構成をながめる(@code{edebug-view-outside})。

@item p
一時的にポイントを外側の位置に移し、
カレント・バッファの外側を表示します(@code{edebug-bounce-point})。
前置引数@var{n}をつけると
@var{n}秒間休止します。

@item w
ソース・コード・バッファのポイントを、
現在のストップ・ポイントに動かします(@code{edebug-where})。
さらに、
同じバッファを表示している別なウィンドウからこのコマンドを使った場合、
それ以降では、
現在の定義の表示にそのウィンドウを使います。

@item W
@c Its function is not simply to forget the saved configuration -- dan
Edebugが外側のウィンドウ構成を保存したり復帰したりするかどうかをトグルします
(@code{edebug-toggle-save-windows})。

前置引数を与えると
@kbd{W}は選択されたウィンドウの保存復帰についてだけトグルします。
ソース・コード・バッファを表示していないウィンドウを指定するには、
@kbd{C-x X W}をグローバル・キーマップから使わなければなりません。
@end table

@kbd{v}で外側のウィンドウ構成をながめたり、
また、通常には表示されていない場合にも
@kbd{p}でただカレント・バッファのポイントへ跳ね返したりすることができます。
ポイントを動かした後は、
ソース・コード・バッファから@kbd{w}でストップ・ポイントへ戻りたくなるでしょう。

@kbd{W}で保存を@emph{やめる}ときはいつでも、
Edebugは保存した外側のウィンドウ構成を忘れます。
したがって、
保存を@emph{再開した}場合でも、
次に(プログラムを継続して)Edebugを抜けたときに、
現在のウィンドウ構成は変わりません。
しかしながら、
ウィンドウを十分オープンしていないときは、
@samp{*edebug*}と@samp{*edebug-trace*}の自動再表示が、
あなたの見たいバッファとかちあうことがあります。

@node Edebug Eval, Eval List, Edebug Views, Edebug
@subsection 評価

Edebugの中で、
「あたかも」Edebugが走っていないかのように式を評価できます。
Edebugは式の評価と印字にたいして透過的になるようにしています。
副作用を起こす式の評価は
Edebugが陽に保存復帰したものをのぞいて
期待どおりに働きます。
この過程についての詳細は、@xref{The Outside Context}。

@table @kbd
@item e @var{exp} @key{RET}
式@var{exp}をEdebugの外側の文脈で評価します(@code{edebug-eval-expression})。
つまりEdebugは評価への影響を最少化しようとします。

@item M-: @var{exp} @key{RET}
式@var{exp}をEdebug自身の文脈で評価します。

@item C-x C-e
ポイントの前の式をEdebugの外側の文脈で評価します
(@code{edebug-eval-last-sexp})。
@end table

@cindex lexical binding (Edebug)
@cindex 辞書的な束縛(Edebug)[じしょてきなそくばくedebug]
@cindex レキシカル・バインド(Edebug)[れきしかるばいんどedebug]
Edebugは、
@file{cl.el} (バージョン 2.03 かそれ以降)
の
@code{lexical-let} @code{macrolet} @code{symbol-macrolet}
構文要素で生成された、
辞書的に束縛されたシンボルへの参照を含む、
式の評価をサポートします。


@node Eval List, Printing in Edebug, Edebug Eval, Edebug
@subsection 評価リスト・バッファ

@samp{*edebug*}という@dfn{評価リスト・バッファ(evaluation list buffer)}を使って
対話的に式を評価することができます。
また、Edebugが表示を更新するたびに自動的に評価される
式の@dfn{評価リスト(evaluation list)}も使えます。

@table @kbd
@item E
評価リスト・バッファ@samp{*edebug*}に
切り替えます(@code{edebug-visit-eval-list})。
@end table

@samp{*edebug*}バッファでは
Lisp Interactionモード
(@pxref{Lisp Interaction,,, emacs, The GNU Emacs Manual})
のコマンドのほかに以下の特殊なコマンドが使えます。

@table @kbd
@item LFD
外側の文脈でポイントの前の式を評価し、
バッファに値を挿入します
(@code{edebug-eval-print-last-sexp})。

@item C-x C-e
ポイントの前の式をEdebugの外側の文脈で評価します
(@code{edebug-eval-last-sexp})。

@item C-c C-u
バッファの内容から新しい評価リストを作ります
(@code{edebug-update-eval-list})。

@item C-c C-d
ポイントがある評価リスト群を消去します(@code{edebug-delete-eval-item})。

@item C-c C-w
現在のストップ・ポイントのソース・コード・バッファに
戻ります(@code{edebug-where})。
@end table

@kbd{LFD}や@kbd{C-x C-e}で、
@samp{*scratch*}でのように、
評価リスト・ウィンドウの式を評価することができますが、
これらはEdebugの外側の文脈で評価されます。

あなたが対話的に入力した式(とその結果)は実行を継続したときに失われます。
しかし、
実行が止まるたびに評価をする式を含む@dfn{評価リスト(evaluation list)}を
設定することができます。

@cindex evaluation list group
@cindex 評価リスト群[ひょうかりすとぐん]
こうするには評価リスト・バッファの中に
単数または複数の@dfn{評価リスト群(evaluation list group)}を書きます。
評価リスト群には単数または複数のLisp式があります。
各群はコメント行で分割されます。

コマンド@kbd{C-c C-u} (@code{edebug-update-eval-list})は、
バッファをスキャンして各群の1番目の式を用い評価リストを再構築します
(なぜこうするかというと群の2番目の式は前に計算され表示された値だからです)。

無限ループになるので、
膳立てをしたコードを実行する式をつけ加えないように注意してください。
@c There ought to be a way to fix this.

Edebugへの各呼出しは、
後ろに現在の値をつけた各式をバッファに挿入して、
評価リストの再表示を行ないます。
コメント行も挿入するので各式はそれぞれに群をなします。
したがってバッファ・テキストを変えずに@kbd{C-c C-u}をまた押下した場合、
評価リストは実質的には変化しません。

評価リストの評価でエラーが起きたとき、
それが結果であるかのように、
エラー・メッセージが文字列として表示されます。
したがって現在無効な変数を使用する式も、
デバッグに割り込むことはありません。

以下は、
式をいくつか追加した後の評価リスト・ウィンドウの例です。

@smallexample
(current-buffer)
#<buffer *scratch*>
;---------------------------------------------------------------
(selected-window)
#<window 16 on *scratch*>
;---------------------------------------------------------------
(point)
196
;---------------------------------------------------------------
bad-var
"Symbol's value as variable is void: bad-var"
;---------------------------------------------------------------
(recursion-depth)
0
;---------------------------------------------------------------
this-command
eval-last-sexp
;---------------------------------------------------------------
@end smallexample

群を消去するにはポイントを中にもってきて@kbd{C-c C-d}を押下するか、
単に群のテキストを消去してから@kbd{C-c C-u}で評価リストを更新するかします。
新しい式を評価リストに追加するには、
適切な場所に式と新しいコメント行を挿入します
(コメント行にダッシュを挿入する必要はありません---内容は関係ありません)。
そして@kbd{C-c C-u}を押下します。

@samp{*edebug*}を選択した後、
@kbd{C-c C-w}でソース・コード・バッファに戻ることができます。
@samp{*edebug*}バッファは実行を継続したときに抹消され、
次に必要になったとき再生成されます。

@node Printing in Edebug, Trace Buffer, Eval List, Edebug
@subsection Edebugでの印字

@cindex printing (Edebug)
@cindex printing circular structures
@cindex 印字(Edebug)[いんじedebug]
@cindex 印字、循環構造の[いんじ、じゅんかんこうぞうの]
@cindex 循環構造の印字[じゅんかんこうぞうのいんじ]
@pindex cust-print
  もしプログラムの中の式が環状リスト構造を含む値を生成したら、
Edebugがそれを印字しようとしたときにエラーになることがありえます。

@vindex edebug-print-length
@vindex edebug-print-level
  環状構造を処理する一つの方法は、
印字の切り捨てをする@code{print-length}や@code{print-level}を設定することです。
これはEdebugの方でやってくれます。
もし@code{nil}なら@code{print-length}と@code{print-level}を50に束縛します
(実際は@code{edebug-print-length}と@code{edebug-print-level}の値にします)。@xref{Output Variables}。

  環状構造や要素を共有している構造をよりはっきりと印字するのに、
@file{cust-print}パッケージを利用してもかまいません。

  @file{cust-print}をロードしてEdebug専用にカスタム印字をアクティブにするには、
単にコマンド@kbd{M-x edebug-install-custom-print}を使います。
標準の印字関数を復帰するには、
@kbd{M-x edebug-uninstall-custom-print}を使います。

  以下に環状構造を生成するコードの例をあげます。

@example
(setq a '(x y))
(setcar a a))
@end example

@noindent
カスタム印字はこれを@samp{Result: #1=(#1# y)}のように印字します。
@samp{#1=}という表記は、
それ以降に続く構造に@samp{1}というラベルをつけて、
@samp{#1#}という表記は以前につけたラベルの構造を参照します。
この表記はリストやベクタの共有要素を表わすのに使います。

  ほかのプログラムもカスタム印字を利用可能です。
詳しくは@file{cust-print.el}を見てください。

@node Trace Buffer, Coverage Testing, Printing in Edebug, Edebug
@subsection トレース・バッファ
@cindex trace buffer
@cindex トレース・バッファ[とれーすばっふぁ]

  Edebugは、
実行トレースを@samp{*edebug-trace*}という名前のバッファに格納して、
記録しておくことができます。
これは関数の呼出しと戻りのログで、
関数名、引数、値を示すものです。
トレース記録を有効にするには、
@code{edebug-trace}を非@code{nil}の値に設定します。

  トレース・バッファを作ることは、
trace実行モードを使うこととは違います(@pxref{Edebug Execution Modes})。

  トレース記録を有効にしてあるとき、
各関数の呼出しと終了はトレース・バッファに行を追加します。
関数の呼出し記録は@samp{::::@{}に関数名と引数値が
ついたような形になっています。
関数の終了記録は@samp{::::@}}に関数名と関数の結果が
ついたような形になっています。

  項目の中の@samp{:}の数は再帰の深さを示します。
トレース・バッファで、対応する関数呼出しの最初や最後を探すのに、
波括弧を使うことができます。

@findex edebug-print-trace-before
@findex edebug-print-trace-after
  関数@code{edebug-print-trace-before}と、
@code{edebug-print-trace-after}を再定義して、
関数の呼出しと終了のトレース記録をカスタマイズすることができます。

@defmac edebug-tracing string body@dots{}
このマクロは@var{body}形式の実行の前後で追加のトレース情報を要求します。
引数@var{string}はトレース・バッファに置くテキストを指定します。
全引数を評価します。
@code{edebug-tracing}は@var{body}の最後の形式の値を返します。
@end defmac

@defun edebug-trace format-string &rest format-args
この関数は、トレース・バッファにテキストを挿入します。
テキストは@code{(apply 'format @var{format-string} @var{format-args})}で
算出します。
項目をわけるため改行を追加します。
@end defun

  @code{edebug-tracing}と@code{edebug-trace}は、
Edebugがアクティブでないときでもトレース・バッファに行を追加します。

  トレース・バッファへのテキストの追加では、
最後に挿入した行が見えるようにウィンドウのスクロールもします。

@node Coverage Testing, The Outside Context, Trace Buffer, Edebug
@subsection 網羅率検査

@cindex coverage testing
@cindex frequency counts
@cindex performance analysis
@cindex カバレージ・テスト[かばれーじてすと]
@cindex フリケンシー・カウント[ふりけんしーかうんと]
@cindex パフォーマンス・アナリシス[ぱふぉーまんすあなりしす]
@cindex 網羅率検査[もうらりつけんさ]
@cindex 頻度統計[ひんどとうけい]
@cindex 性能解析[せいのうかいせき]
Edebugにはおおざっぱな網羅率検査と実行頻度の表示ができます。
膳立てをされた式の評価の前後では、
実行モードがGo-nonstopのときでも、
みな頻度計数を累積してゆきます。
網羅率検査はかなり高くつくので、
@code{edebug-test-coverage}が非@code{nil}のときにだけ行ないます。
コマンド@kbd{M-x edebug-display-freq-count}は頻度データと網羅率データを
(記録していれば)表示します。

@deffn Command edebug-display-freq-count
このコマンドは頻度計数データを、現在の定義の中の各行に表示します。

頻度計数は各行の後ろにコメントとして現われます。
これは@code{undo}コマンドで取り消すことができます。
計数は式の前の@kbd{(}、
式の後の@kbd{)}、
シンボルの最後の文字の下に現われます。
同じ行の中では前の計数と同じ値の表示はしません。

文字@samp{=}に式の計数がついたものは、
式が評価されるたびにいつも同じ値を返していることを示します。
これはEdebugが記録する唯一の網羅率情報です。

定義の頻度計数と網羅率情報を消すには、再び膳立てをします。
@end deffn

たとえば、ソースにブレークポイントをつけて@code{(fac 5)}を評価し、
@code{edebug-test-coverage}を@code{t}にした後で、
ブレークポイントに到達すると、
計数データは次のようになります。

@example
(defun fac (n)
  (if (= n 0) (edebug))
;#6           1      0 =5 
  (if (< 0 n)
;#5         = 
      (* n (fac (1- n)))
;#    5               0  
    1))
;#   0 
@end example

コメント行は@code{fac}が6回呼ばれたことを示しています。
最初の@code{if}ステートメントは同じ結果を5回返しています。
2番目の@code{if}の条件についても同じことがいえます。
@code{fac}の再帰呼びだしはまったく返っていません。

@node The Outside Context, Edebug Recursive Edit, Coverage Testing, Edebug
@subsection 外側の文脈

Edebugはデバッグ中のプログラムにたいして透過的になるように努めていますが、
そうすることに完全には成功してません。
Edebugは@kbd{e}や評価リスト・バッファで式を評価するとき、
一時的に外側の文脈を復帰して、
透過的になるように努めています。
この節ではEdebugが復帰する文脈と、
Edebugが完全に透過的とはなりきれていないのはどういうところなのかを、
正確に説明します。

@menu
* Checking Whether to Stop::	何をすべきか決めるとき。
* Edebug Display Update::	表示を更新するとき。
* Edebug Recursive Edit::	実行を停止するとき。
@end menu

@node Checking Whether to Stop, Edebug Display Update, The Outside Context, The Outside Context
@subsubsection いつ止めるかのチェック

トレース情報を作ったりプログラムを止めたりするかどうかを決める前であっても、
Edebugにはいるときは常に、
あるデータを保存、復帰する必要があります。

@itemize @bullet
@item 
@code{max-lisp-eval-depth}と@code{max-specpdl-size}は、
スタック上のEdebugの影響のために1増加させておきます。
しかしながら、Edebug使用中でもスタックが不足することはありえます。

@item 
キーボード・マクロの実行状態も保存復帰されます。
Edebugがアクティブな間、
@code{executing-macro}は@code{edebug-continue-kbd-macro}に束縛されます。

@end itemize


@node Edebug Display Update,  , Checking Whether to Stop, The Outside Context
@subsubsection Edebugの表示更新

Edebugが何かを表示する必要のあるとき(たとえば、traceモード中)、
現在のウィンドウ構成(@pxref{Window Configurations})をEdebugの「外側」から保存します。
(プログラムを継続して)Edebugから抜けたとき、
前のウィンドウ構成を復帰します。

Emacsは休んでいるときだけ再表示を行ないます。
通常、実行を継続したときに、
ブレークポイントにおいてか、または、
休まずにステップをした後か、または、
途中で入力を読み込もうとして、
プログラムはEdebugに戻ってきます。
このような場合、Emacsは「外側」の構成を再表示する機会を失います。
割り込みがなければ、
最後にEdebugがアクティブなときと同じウィンドウ構成が見えます。

何かを表示するためEdebugにはいると以下のデータの保存と復帰を生じますが、
このうちいくつかはあえて、
エラーやとりやめのシグナルが起きても復帰しません。

@itemize @bullet
@item 
@cindex current buffer point and mark (Edebug)
@cindex カレント・バッファ・ポイントとマーク(Edebug)[かれんとばっふぁぽいんととまーくedebug]
どのバッファがカレントか、
そしてカレント・バッファのポイントとマークの位置は、
保存と復帰をします。

@item 
@cindex window configuration (Edebug)
@cindex ウィンドウ構成(Edebug)[うぃんどうこうせいedebug]
@code{edebug-save-windows}が非@code{nil}なら(@pxref{Edebug Display Update})
外側のウィンドウ構成は保存と復帰をします。

エラーやとりやめではウィンドウ構成の復帰をしませんが、
外側で選択されたウィンドウは@code{save-excursion}がアクティブでも、
エラーやとりやめで再び選択@emph{されます}。

ウィンドウの開始位置とソース・コード・バッファの水平スクロールは
復帰しませんが、
Edebugの中で表示は一貫性をもっています。

@item
@code{edebug-save-displayed-buffer-points}が非@code{nil}なら、
表示される各バッファのポイントの値は、保存、復帰されます。

@item
変数@code{overlay-arrow-position}と@code{overlay-arrow-string}は保存と、
復帰をします。
したがって再帰編集中に同じバッファのどこからでも安全にEdebugを起動できます。

@item 
@code{cursor-in-echo-area}は局所的に@code{nil}に束縛し、
カーソルがウィンドウに表示されるようにします。
@end itemize

@node Edebug Recursive Edit, Instrumenting Macro Calls, The Outside Context, Edebug
@subsection Edebugの再帰編集

Edebugにはいってユーザからコマンドを実際に読み込んだとき、
以下のデータも保存を(そして後で復帰を)します。

@itemize @bullet
@item
現在の一致データ。@xref{Match Data}。

@item
@code{last-command}、@code{this-command}、@code{last-command-char}、
@code{last-input-char}、@code{last-input-event}、
@code{last-command-event}、@code{last-event-frame}、
@code{last-nonmenu-event}、@code{track-mouse}についてですが、
Edebug中で使用したコマンドはEdebugの外ではこれらの変数に影響を与えません。

@code{this-command-keys}が返すキー・シーケンスは、
Edebugの中でコマンドを実行してしまうと変わってしまって、
Lispではキー・シーケンスを戻すことができません。

Edebugは@code{unread-command-events}の値を保存、復帰することができません。
この変数が自明でない値をもつ間にEdebugにはいると、
デバッグ中のプログラムの実行に影響をあたえます。

@item
Edebug中に複雑なコマンドを実行すると変数@code{command-history}に追加されます。
まれにこれが実行を変えることがあります。

@item
Edebugの中では、再帰の深さがEdebugの外側にくらべて一つ深くなります。
これは自動的に更新される評価リストのウィンドウでは成立しません。

@item
@code{standard-output}と@code{standard-input}は、
@code{recursive-edit}によって@code{nil}に束縛されますが、
Edebugは評価の間、一時的にこれらを復帰します。

@item 
キーボード・マクロ定義の状態は保存、復帰されます。
Edebugがアクティブな間、@code{defining-kbd-macro}は
@code{edebug-continue-kbd-macro}に束縛されます。
@end itemize

@node Instrumenting Macro Calls, Edebug Options, Edebug Recursive Edit, Edebug
@subsection マクロ呼出しの膳立て

EdebugがLispマクロを呼び出す式の膳立てをするとき、
処理を正しく行なうために付加的な情報が必要です。
これは、マクロ呼出しのどの部分式が評価すべき形式なのかを、
決めることができないためです
(評価はマクロ本体の中に明示されているときや、
結果の式が評価されるときあるいはそれ以降に起こることがあります)。
Edebugがこれを正しく処理できるよう、
各マクロの呼出し形式を指定しなければなりません。
それには、
@code{def-edebug-spec}を使い、
与えたマクロへの呼出し形式を定義する必要があります。

@deffn Macro def-edebug-spec macro specification
マクロ@var{macro}の呼出しのどの式が評価すべき形式なのかを指定します。
単純なマクロにたいして、
@var{specification}はいつもマクロ引数の仮引数とよく似ていますが、
指定方法はもっとマクロ引数よりもさらに一般的です。

@var{macro}引数はマクロ名だけでなく実際には任意のシンボルでかまいません。
@end deffn

以下の例では、
このEmacs Lispリファレンス・マニュアル中に登場するマクロ@code{for}の仕様を、
2とおりの等価な仕様指定で定義しています。

@example
(def-edebug-spec for
  (symbolp "from" form "to" form "do" &rest form))

(def-edebug-spec for
  (symbolp ['from form] ['to form] ['do body]))
@end example

次の表に@var{specification}のとりうる値と、
それによって引数の処理がどう変わるかをまとめておきます。

@table @asis
@item @code{t}
全引数について評価の膳立てをします。

@item @code{0}
膳立てをする引数はありません。

@item シンボル
シンボルは、代用するEdebug仕様指定をもたなければなりません。
この間接的な仕様指定は別種の仕様指定が見つかるまで続きます。
別のマクロの仕様指定を継承することができます。

@item リスト
リストの要素は呼出し形式の引数の型を指定します。
仕様指定リストの要素になりえるものは次の節で解説します。
@end table

@menu
* Specification List::		複雑な評価パターンの指定方法。
* Backtracking::		対応に失敗したときEdebugはどうするか。
* Specification Examples::	仕様指定の理解を助けるために。
@end menu


@node Specification List, Backtracking, Instrumenting Macro Calls, Instrumenting Macro Calls
@subsubsection 仕様指定リスト

@cindex Edebug specification list
@cindex Edebug仕様指定リスト[edebugしようしていりすと]
マクロ呼出しの、ある引数は評価され、ある引数は評価されないという場合には、
@dfn{仕様指定リスト(specification list)}がEdebugへの指定として必要です。
仕様指定リスト中のある要素群は、単数あるいは複数の引数と一致し、
別な要素群はそれ以降の要素の処理を修飾します。
後者の方は@dfn{仕様指定キーワード(specification keyword)}といいます。
これは(@code{&optional}のように)@samp{&}で始まるシンボルです。

仕様指定リストは、
それ自身がリストであるような引数に対応する部分リストや、
仲間わけに使うベクタを含んでいることがあります。
このように部分リストやグループは仕様指定リストを
レベルの階層構造に分割します。
仕様指定キーワードは、
それを含むグループや部分リストの残りの部分だけに適用します。

仕様指定リストが選択肢や繰り返しになるとき、
実際のマクロ呼出しへの照合にはバックトラックが必要です。
詳しくは、@xref{Backtracking}。

Edebug仕様指定は正規表現の照合能力にくわえて、
文脈自由文法としての構文要素をもっています。
すなわち、釣り合いのとれた括弧をもつ部分リスト、形式の再帰的処理、
間接仕様指定を経由した再帰といったものです。

次の表はとりうる仕様指定の要素とその意味です。

@table @code
@item sexp
評価されない単一のLispオブジェクト。
@c "unevaluated expression" is not meaningful, because
@c an expression is a Lisp object intended for evaluation.

@item form
評価され膳立てをされる単一の式。

@item place
@findex edebug-unwrap
Common Lispの@code{setf}構文要素のように、
値を格納するところ。

@item body
@code{&rest form}を簡単にしたもの。以下の@code{&rest}を見てください。

@item function-form
関数形式。すなわちquoteされた関数シンボル、quoteされたラムダ式、あるいは
(関数シンボルやラムダ式へ評価する)形式。
これはラムダ式を渡す引数が、
@code{function}ではなく@code{quote}でquoteされることもある場合に、
便利です。
というのはどちらの場合でもラムダ式本体の膳立てをするからです。

@item lambda-expr
quoteしないラムダ式。

@item &optional
@kindex &optional @r{(Edebug)}
仕様指定リストでそれ以降の引数が省略可能であることをあらわします。
一つでも一致しなくなるやいなや、Edebugはこのレベルで照合を止めます。

省略不能な要素に続いていくつかの省略可能な要素がある場合、
@code{[&optional @var{specs}@dots{}]}を使います。
いくつかの要素がすべて一致するかまったく一致しないかということを指定するには、
@code{&optional [@var{specs}@dots{}]}を使います。
以下の@code{defun}の例を見てください。

@item &rest
@kindex &rest @r{(Edebug)}
仕様指定リスト中のそれ以降の要素は0個以上繰り返します。
最後の繰り返しについてはすべてと照合する必要はありません。

いくつかの要素だけを繰り返すには、
@code{[&rest @var{specs}@dots{}]}を使います。
すべての繰り返しで全部が一致する必要のあるときは、
@code{&rest [@var{specs}@dots{}]}を使います。

@item &or
@kindex &or @r{(Edebug)}
仕様指定リスト中の後続する全要素が選択肢です。
選択肢の一つが照合する必要があります。
さもなくば@code{&or}仕様指定は失敗します。

@code{&or}に続く各リスト要素は、単一の選択肢です。
二つ以上のリスト要素を単一の選択肢とするには、
@code{[@dots{}]}でくくります。

@item &not
@kindex &not @r{(Edebug)}
後続の各要素は@code{&or}を使ったときの選択肢のように照合されますが、
一致するものがあると指定は失敗します。
一致するものがないとき、
照合するものは空ですが、
このときに@code{&not}仕様指定は成功します。

@item &define 
@kindex &define @r{(Edebug)}
仕様指定が定義を行なう形式であることを示します。
定義を行なう形式自身は膳立てをされません
(つまりEdebugは定義を行なう形式の前後では止まりません)が、
内側の典型的な形式は膳立てをされます。
@code{&define}キーワードはリスト仕様指定の最初の要素でなければなりません。

@item nil
これは現在の引数リスト・レベルで
照合すべき引数がないときに成功します。
後述する部分リスト仕様指定と逆引用符の例を見てください。

@item gate
@cindex preventing backtracking
@cindex 禁止、バックトラックの[きんし、ばっくとらっくの]
引数とは対応しませんが、
このレベルでの残った仕様指定の照合でgateをとおったバックトラックを禁止します。
これは主に仕様指定の構文エラー・メッセージの生成に使用されます。
詳しくは@ref{Backtracking}を見てください。
また、後述の@code{let}の例も見てください。

@item @var{other-symbol}
@cindex indirect specifications
@cindex 間接仕様指定[かんせつしようしてい]
仕様指定リスト中のほかのすべてのシンボルは、
述語または間接的な仕様指定のはずです。

シンボルにEdebug仕様指定があるなら、
この@dfn{間接的仕様指定(indirect specification)}は
シンボルの代わりに使われる仕様指定リストであるか、
あるいは引数を処理するために呼び出される関数です。
仕様指定はマクロのように@code{def-edebug-spec}で定義されます。
後述の@code{defun}の例を見てください。

それ以外の場合、シンボルは述語でなければなりません。
述語は引数をともなって呼び出され、
この述語が@code{nil}を返すと仕様指定は失敗します。
いずれの場合も、引数の膳立てはされません。

適切な述語には、
@code{symbolp}、@code{integerp}、
@code{stringp}、@code{vectorp}、@code{atom}があります。

@item [@var{elements}@dots{}]
@cindex {[@dots{}] (Edebug)}[{[...] (Edebug)}]
要素のベクタは、
複数の要素を単一の@dfn{グループ仕様指定(group specification)}にまとめます。
この意味はベクタとは関係ありません。

@item "@var{string}"
引数は@var{string}という名前のシンボルでなければなりません。
この仕様指定は、@var{string}という名前のシンボル@var{symbol}を quote した
@code{'@var{symbol}}というものと等価ですが、
文字列形式の方がお薦めです。

@item (vector @var{elements}@dots{})
引数は、
その要素が仕様指定中の@var{elements}と一致するベクタでなければなりません。
後述の逆引用符の例を見てください。

@item (@var{elements}@dots{})
それ以外のリストは@dfn{部分リスト仕様指定(sublist specification)}です。
この引数はリストで、
その要素が仕様指定@var{elements}と一致していなければなりません。

@cindex dotted lists (Edebug)
@cindex ドットつきリスト(Edebug)[どっとつきりすとedebug]
部分リスト仕様指定がドットつきリストであって、
対応するリスト引数がドットつきリストであってもかまいません。
また、ドットつきリスト仕様指定の最後の@sc{cdr}が、別な部分リスト仕様指定
(仲間わけや間接仕様指定、すなわち、@code{(spec . [(more specs@dots{})])})
で、その要素がドットのないリスト引数と一致するもの
であったりしても、かまいません。
これは、後述の逆引用符の例にあるような再帰的仕様指定で、役に立ちます。
このような再帰を終了させる@code{nil}仕様指定については、前述しました。

@code{(specs . nil)}のように書かれる部分リスト仕様指定は、
@code{(specs)}と等価であること、
@code{(specs . (sublist-elements@dots{}))}は、
@code{(specs sublist-elements@dots{})}と等価であることに注意してください。
@end table

@c Need to document extensions with &symbol and :symbol

以下は@code{&define}の後に現われるだけの追加の仕様指定の一覧です。
後述する@code{defun}の例を見てください。

@table @code
@item name
引数のシンボルは定義形式中の名前です。

定義形式には名前のフィールドがなくともかまいません。
複数の名前フィールドがあることもあります。

@item :name
この構文要素は実際の引数とは対応しません。
@code{:name}に続く要素はシンボルでなければなりません。
これは定義にたいして、付加的な名前の成分に使われます。
一意で静的な成分を定義中の名前に追加することができます。
1回以上使うこともできます。

@item arg
引数のシンボルは定義形式の引数の名前です。
しかし、ラムダ・リスト・キーワード(@samp{@code{&}}で始まるシンボル)
は許されていません。

@item lambda-list
@cindex lambda-list (Edebug)
@cindex ラムダ・リスト(Edebug)[らむだりすとedebug]
これはラムダ・リスト、すなわちラムダ式の引数リストと一致します。

@item def-body
引数は定義のコードの本体です。
これは前述の@code{body}に似ていますが、
定義の本体は、
定義にまつわる情報を参照する別なEdebug呼出しで、
膳立てをされていなければなりません。
@code{def-body}は、定義内の形式の最高位のリストに使用します。

@item def-form
引数は定義内で最高位の単一の形式です。
@code{def-body}に似ていますが、
形式のリストではなく、単一の形式と対応します。
特例として@code{def-form}では、
形式を実行するとき追跡情報を出力しません。
後述の@code{interactive}の例を見てください。
@end table

@node Backtracking, Specification Examples, Specification List, Instrumenting Macro Calls
@subsubsection バックトラック

@cindex backtracking
@cindex syntax error (Edebug)
@cindex バックトラック[ばっくとらっく]
@cindex 構文エラー(Edebug)[こうぶんえらーedebug]
仕様指定がどこかで照合に失敗しても、
それだけでは構文エラーを通知されるとはかぎりません。
こういう場合、
選択肢がなくなるまで@dfn{バックトラック(backtracking)}を行ないます。
結局のところ、
引数リストの各要素は
仕様指定中のいずれかの要素と一致しなければなりませんし、
仕様指定中で必須と指定した要素にはいずれかの引数と一致しなければなりません。

後述するある条件の成立した場合、
バックトラックは部分リストやグループの余りの部分にたいして禁止されます。
バックトラックは新しい選択肢が@code{&optional}、
@code{&rest}や@code{&or}で確立されたときに、
再び有効になります。
部分リスト、グループ仕様指定、間接仕様指定を処理する前にも有効になります。

Edebugがもっと細かな構文エラー・メッセージを出せるように、
バックトラックを禁止し別な選択肢をえらぶようにしたいかもしれません。
通常、一致する選択肢がないとき、
Edebugは一致したものがなかったということを知らせてきますが、
一つしかない選択肢の場合には、
どうして一致しなかったのかまで知らせることができます。

まず第一に形式の仕様指定のどれか
(つまり@code{form}、@code{body}、@code{def-form}、
@code{def-body})に照合しているときは、バックトラックが禁止されます。
これらの仕様指定はどんな形式にも一致するため、
どんなエラーも高い水準でではなく形式それ自身の中で起こります。

そして第二にquoteされたシンボルや文字列仕様指定とうまく一致した後にも、
認識された構文要素を示しているということで、
バックトラックは禁止されます。
もし同じシンボルで始まる選択肢の構文要素の集まりがあるなら、
@code{["foo" &or [first case] [second case] ...]}
のようにシンボルを選択肢からくくり出すことにより、
この制約をうまく回避することができます。

第三に@code{gate}仕様指定を使って陽にバックトラックを禁止することもできます。
これ以上高い選択肢がないとわかっているときには便利です。

@node Specification Examples,  , Backtracking, Instrumenting Macro Calls
@subsubsection 仕様指定の例

以下の例でEdebug仕様指定について学習すれば、
理解が深まることでしょう。

@code{let}特殊形式には束縛の列と本体があります。
各束縛はシンボルであるか、
あるいはシンボルと省略可能な値をともなった部分リストです。
以下の仕様指定でいったん部分リストが見つかると、
部分リストの内側の@code{gate}がバックトラックを妨げます。

@example
(def-edebug-spec let
  ((&rest
    &or symbolp (gate symbolp &optional form))
   body))
@end example

@code{defun}、@code{defmacro}、
そして関連づけられた引数リストと@code{interactive}仕様指定で
Edebugが使用する仕様指定は、
以下のとおりです。
対話的な形式は、
実際に関数本体の外側で評価される引数式であるため、
特別扱いすることが必要です。

@smallexample
(def-edebug-spec defmacro defun) ; @r{@code{defun}仕様指定への間接参照。}
(def-edebug-spec defun 
  (&define name lambda-list 
           [&optional stringp]   ; @r{もしあれば、説明文字列と一致する。}
           [&optional ("interactive" interactive)]
           def-body))

(def-edebug-spec lambda-list
  (([&rest arg]
    [&optional ["&optional" arg &rest arg]]
    &optional ["&rest" arg]
    )))

(def-edebug-spec interactive
  (&optional &or stringp def-form))    ; @r{注意: @code{def-form}}
@end smallexample

以下の逆引用符の仕様指定では
ドットつきリストや再帰を終結させる@code{nil}の使い方が、
説明されています。
また、ベクタの成分と照合させる方法も説明します
(再帰が深くなりすぎてだめなので、
Edebugで実際に定義している仕様指定では、
ドットつきリストをサポートしていません)。

@smallexample
(def-edebug-spec ` (backquote-form))   ; @r{簡単のための別名。}

(def-edebug-spec backquote-form
  (&or ([&or "," ",@@"] &or ("quote" backquote-form) form)
       (backquote-form . [&or nil backquote-form])
       (vector &rest backquote-form)
       sexp))
@end smallexample


@node Edebug Options,  , Instrumenting Macro Calls, Edebug
@subsection Edebugのオプション

  Edebugの振舞いを変えるオプションは以下のとおりです。

@defopt edebug-setup-hook
Edebugを使う前に呼び出される関数群。
新しい値が設定されるたびにEdebugはこれらの諸関数を1回ずつ評価し、
その後@code{edebug-setup-hook}を@code{nil}にします。
使っているパッケージにまつわるEdebug仕様指定を、
Edebugとともに使うときにだけロードするようなときに使います。@xref{Instrumenting}。
@end defopt

@defopt edebug-all-defs
もし非@code{nil}なら、
@code{defun}や@code{defmacro}のような通常の定義形式の評価で、
Edebugへの膳立てをします。
これは@code{eval-defun}、@code{eval-region}、@code{eval-buffer}、
@code{eval-current-buffer}に適用されます。

コマンド@kbd{M-x edebug-all-defs}は、
このオプションのトグルを行ないます。@xref{Instrumenting}。
@end defopt

@defopt edebug-all-forms
もし非@code{nil}なら、
コマンド@code{eval-defun}、
@code{eval-region}、@code{eval-buffer}、@code{eval-current-buffer}は、
定義をしない場合でも、
全形式の膳立てを行ないます。
ロードとミニバッファでの評価には適用しません。

コマンド@kbd{M-x edebug-all-forms}は、
このオプションのトグルを行ないます。@xref{Instrumenting}。
@end defopt

@defopt edebug-save-windows
もし非@code{nil}ならば、Edebugはウィンドウ構成の保存と復帰をします。
これには時間がかかりますから、
もしウィンドウ構成を無視するようなプログラムでは、
この変数を@code{nil}にするとよいでしょう。

値がリストのとき、
リスト中のウィンドウだけが保存復帰されます。

Edebugの@kbd{W}コマンドは、
この変数を対話的に変更します。@xref{Edebug Display Update}。
@end defopt

@defopt edebug-save-displayed-buffer-points
これが非@code{nil}のときEdebugは、
表示中の全バッファのポイントの保存と復帰をします。

別なバッファのポイントを保存復帰することは、
選択されていないウィンドウに表示されているバッファの
ポイントを変更するコードをデバッグするときに必要になります。
Edebugあるいはユーザがウィンドウを選択すると、
バッファのポイントはウィンドウのポイント値に移動します。

全バッファでポイントの保存と復帰をするのには、
各ウィンドウを2回選択する必要があるので、
高くつきます。
ですから必要なときだけ使うようにしてください。@xref{Edebug Display Update}。
@end defopt

@defopt edebug-initial-mode
この変数が非@code{nil}のとき、
Edebugが最初にアクティブになったときの実行モードをとります。
とりうる値は、
@code{step}、@code{next}、@code{go}、@code{Go-nonstop}、@code{trace}、
@code{Trace-fast}、@code{continue}、@code{Continue-fast}のいずれかです。

デフォルト値は@code{step}です。

@xref{Edebug Execution Modes}。
@end defopt

@defopt edebug-trace
@findex edebug-print-trace-before
@findex edebug-print-trace-after
非@code{nil}のとき関数の呼出しと終了でトレースを表示します。
@c Overfull対策
@iftex
トレース出力は@samp{*edebug-@linebreak{}trace*}という名前のバッファ
@end iftex
@ifinfo
トレース出力は@samp{*edebug-trace*}という名前のバッファ
@end ifinfo
に1関数の呼出し終了ごとに1行ずつ、
再帰レベルに応じた字下げをして表示されます。

デフォルト値は@code{nil}です。

@xref{Trace Buffer}の@code{edebug-tracing}も参照してください。
@end defopt

@defopt edebug-test-coverage 
もし非@code{nil}なら、
Edebugはデバッグ中のすべての式の網羅率検査をします。
各式の結果を前の結果と比較することによります。
二つの異なる値が見つかったとき網羅率は良好とみなされます。
したがってあなたのコードの網羅率を十分に検査するには、
すべての式を(訳注:少なくとも)1回以上は評価するような、
また、各式が異なる結果を生成するような、
条件下で実行するようにしてください。

頻度計数と定義の網羅率情報を表示するには
@kbd{M-x edebug-display-freq-count}を使います。@xref{Coverage Testing}。
@end defopt

@defopt edebug-continue-kbd-macro 
もし非@code{nil}なら、
Edebugの外側で実行しているキーボード・マクロの実行や、
定義を続行します。@xref{Edebug Execution Modes}。
@end defopt

@defopt edebug-print-length
もし非@code{nil}なら、
Edebugで結果を印字している間@code{print-length}をこの値に束縛します。
デフォルト値は@code{50}です。@xref{Printing in Edebug}。
@end defopt

@defopt edebug-print-level 
もし非@code{nil}なら、
Edebugで結果を印字している間@code{print-level}をこの値に束縛します。
デフォルト値は@code{50}です。
@end defopt

@defopt edebug-print-circle 
もし非@code{nil}なら、
Edebugで結果を印字している間@code{print-circle}をこの値に束縛します。
デフォルト値は@code{nil}です。
@end defopt

@defopt edebug-on-error
@code{debug-on-error}の値が@code{nil}のとき、
Edebugは@code{debug-on-error}をこの値に束縛します。@xref{Trapping Errors}。
@end defopt

@defopt edebug-on-quit
@code{debug-on-quit}の値が@code{nil}のとき、
Edebugは@code{debug-on-quit}をこの値に束縛します。@xref{Trapping Errors}。
@end defopt

  Edebugがアクティブのときに、
@code{edebug-on-error}や@code{edebug-on-quit}の値を変えても、
@emph{次}にEdebugが別なコマンドから起動されるまでは無効です。
@c Not necessarily a deeper command level.
@c A new command is not precisely true, but that is close enough -- dan

@defopt edebug-global-break-condition
もし非@code{nil}なら各ストップ・ポイントで検査される式です。
結果が非nilならブレークします。
エラーは無視します。@xref{Global Break Condition}。
@end defopt
