この翻訳は不完全です。英語から この記事を翻訳 してください。

Debugger オブジェクト

コンストラクタとして呼び出されると、Debuggerオブジェクトは新しいDebuggerインスタンスを作成します。

new Debugger([global, …])
デバッガ・オブジェクトを作成し、addDebuggeeメソッドを各グローバル・オブジェクトに適用して初期デバッグ・オブジェクトとして追加します。

Debugger Prototype オブジェクトの Accessor プロパティ

Debugger インスタンスは、プロトタイプから次のアクセサプロパティを継承します。

enabled

この Debugger インスタンスのハンドラ、ブレークポイントなどが現在有効かどうかを示すブール値。これは getter と setter を持つアクセサプロパティです。このプロパティに割り当てると、この Debugger インスタンスが有効または無効になります。インスタンスを有効にするとtrueを返し、そうでない場合はfalseを返します。このプロパティは、新しく作成された Debugger インスタンスでは最初は true です。

このプロパティは、デバッガのコードにデバッグ対象からどのような種類のイベントまたはハンドラまたは「ポイント」を追加するかにかかわらず、単一のコントロールポイントを使用してデバッグ対象から解放されます。

allowUnobservedAsmJS

この Debugger インスタンスの debuggee グローバル内で実行されている asm.js コードが Debugger API ハンドラとブレークポイントに見えないかどうかを示すブール値。これを false に設定すると、先行するasm.js コンパイラが禁止され、asm.js コードが通常の JavaScript として実行されます。これは getter と setter を持つアクセサプロパティです。 新しく作成された Debugger インスタンスでは、最初は false です。

このフラグを true に設定することは、ターゲット JavaScript プログラムのステップデバッグ以外の目的で、Debugger API (例えば、 Debugger.Source) のサブシステムを使用することを意図している。

allowWasmBinarySource
WebAssembly ソースをバイナリ形式で使用できるかどうかを示すブール値。WebAssembly のテキスト生成は無効になります。
collectCoverageInfo

この Debugger インスタンスの各デバッグ対象内でコードカバレッジを有効にする必要があるかどうかを示すブール値。このフラグ値を変更すると、すべての JIT コードが再コンパイルされ、コードカバレッジ計測が追加または削除されます。デバッグ対象のフレームが現在スタック上でアクティブになっているときにこのフラグを変更すると例外が発生します。

これを true に設定すると、コードカバレッジ計測が有効になります。これは Debugger.Script getOffsetsCoverage 関数を介してアクセスできます。場合によっては、コードカバレッジによって、このフラグの変更前の情報が公開されることがあります。コードカバレッジレポートは単調なものなので、デバッガが有効になっているときにスナップショットを作成して出力することができます。

これを false に設定すると、この Debugger インスタンスはコードカバレッジ計測を要求しませんが、計測が存在しないことは保証されません。

uncaughtExceptionHook

null またはデバッグイベントハンドラ、ブレークポイントハンドラ、または同様の関数への呼び出しが何らかの例外をスローしたときに SpiderMonkey が呼び出す関数です。ここでは、デバッグ例外を参照しています。デバッガでスローされた例外はデバッグコードに伝播されません。代わりに SpiderMonkey はこの関数を呼び出します。これは passingdebugger-exception を唯一の引数として渡し、Debugger インスタンスを this の値として渡します。この関数は、デバッグ対象の継続方法を決定する再開値を返す必要があります。

キャッチされていない例外フック自体が "uncaught-hook-exception"例外をスローした場合、SpiderMonkey はデバッガが原因であることを示すメッセージを持つデバッグ対象に新しいエラーオブジェクト、つまり confess-to-debuggee-exception をスローします。またそのメッセージには uncaught-hook-exception と originaldebugger-exception のテキスト記述を含みます。

uncaughtExceptionHook の値が null の場合、SpiderMonkey はデバッガが原因であることを示すメッセージを持つデバッグ対象に例外をスローします。これはデバッガ例外のテキスト記述を含みます。

このプロパティに呼び出し可能な値または null 以外を代入すると、TypeError 例外がスローされます。

(これはデバッガのバグを処理する理想的な方法ではありませんが、たとえ不完全であっても、デバッガ開発者にとってより簡単なバックストップとなることが期待されます。例えば、キャッチされない例外フックが alert 機能のようなブラウザレベルの機能にアクセスするかもしれません。この API の実装ではなくても、コンテキストに適した方法でデバッガのエラーを開発者に提示することができます)。

Debugger ハンドラ関数

Debugger インスタンスは、デバッグ対象のコードでイベントが発生したときに SpiderMonkey が呼び出すためのハンドラ関数を格納できるアクセサプロパティを継承します。

以下に説明するイベントの1つがデバッグコードで発生すると、エンジンはデバッグ対象を一時停止し、デバッグ対象を監視している各デバッガインスタンス上の対応するデバッグハンドラを呼び出します。ハンドラ関数は、この値として Debugger インスタンスを受け取ります。ほとんどのハンドラ関数は、デバッグ対象の実行をどのように進めるべきかを示す再開値を返すことができます。

新しい Debugger インスタンスは、各プロパティの初期値が undefined です。デバッグハンドラに割り当てられる値は関数もしくは undefined のどちらかでなければならず、それ以外の場合は TypeError がスローされます。

ハンドラ関数はイベントが発生した同じスレッドで実行されます。それらは、debuggee コンパートメントではなく、所属するコンパートメントで実行されます。

onNewScript(script,global)

Debugger.Script のインスタンススクリプトで表される新しいコードがデバッガのスコープにロードされます。

このメソッドの戻り値は無視されます。

onNewPromise(promise)

Debugger.Object インスタンスの約束によって参照される新しい Promise オブジェクトが、デバッガのスコープ内に割り当てられています。プロミスの割り当てスタックは、Debugger.Object インスタンスの promise の promiseAllocationStack アクセサプロパティを使用して取得できます。

このハンドラメソッドは、デバッグ対象の実行方法を指定する再開値を返さなければなりません。 ただし { return:value } 再開値undefined (“continue normally”) のように扱われ、value は無視されます。

onPromiseSettled(promise)
debuggee スコープ内で割り当てられた Debugger.Object インスタンスの Promise によって参照される Promise オブジェクトが解決済み (完了または拒否) となります。Promise の状態、達成または却下値、割り当ておよび解決スタックは、Debugger.Object インスタンスの Promise の関連するアクセサプロパティを使用して取得できます。


このハンドラメソッドは、デバッグ対象の実行方法を指定する再開値を返さなければなりません。 ただし { return:value } 再開値undefined (“continue normally”) のように扱われ、value は無視されます。

onDebuggerStatement(frame)
Debuggee コードがデバッガ文のインフレームを実行します。このメソッドは、デバッグ対象の実行方法を指定する再開値を返す必要があります。
onEnterFrame(frame)

スタックフレームがコードの実行を開始しようとしています。(当然のことながら、フレームは現在最も新しい「可視フレーム」です)。このメソッドは、デバッグ対象の実行をどのように進めるべきかを指定する再開値を返さなければなりません。

SpiderMonkey は onEnterFrame を呼び出して、目に見えるnon-"debugger" フレームを報告するだけです。

onExceptionUnwind(frame,value)

例外値はスローされ、フレームに伝播します。frame は、最も新しい残りのスタックフレームであり、デバッグ対象のフレームです。このメソッドは、デバッグ対象の実行方法を指定する再開値を返す必要があります。undefined が返された場合、例外は正常に伝播し続けます。フレーム内のコントロールが try ブロックにある場合、コントロールは対応する catch または finally ブロックにジャンプします。それ以外の場合は、フレームがポップされ、例外はフレームの呼び出し元に伝播します。

例外の伝播によって制御が finally ブロックに入ると、例外は一時的に脇に置かれます。finally ブロックが正常に終了すると、例外は伝播を再開し、デバッガの onExceptionUnwind ハンドラが同じフレーム内で再び呼び出されます。(もう1つの可能性は、finally ブロックが return、continue、または break ステートメント、または新しい例外によって終了することです。そのような場合、古い例外は伝播を続けず、破棄されます)。

このハンドラは、過度の再帰またはメモリ不足の例外のためにフレームをアンワインドするときは呼び出されません。

sourceHandler(ASuffusionOfYellow)
このメソッドは決して呼び出されません。それが呼び出されると、矛盾が証明され、デバッガはすべてが真であると仮定し解放されます。
onError(frame,report)

SpiderMonkey はエラーインフォフレームを報告しようとしています。Report はエラーを説明するオブジェクトで、次のプロパティを使用します。

message
完全にフォーマットされたエラーメッセージ。
file
存在する場合、ソースファイル名、URLなど (このプロパティが存在する場合は line プロパティもそうであり、逆も同様です)。
line
存在する場合は、エラーが発生したソース行番号。
lineText
存在する場合、これは違反行のソースコードです。
offset
エラーが発生した lineText 内の文字のインデックス。
warning
これが警告であれば値が存在し、かつ true である。そうでなければ値は存在しない。
strict
このエラーまたは警告が厳密なオプションによるものである (ES strict モードと混同しないでください)
exception
例外がスローされる場合は値が存在し、かつ true である。そうでなければ値は存在しない。
arguments
エラーメッセージに代入される引数を表す文字列の配列。

このメソッドの戻り値は無視されます。

onNewGlobalObject(global)

新しいグローバルオブジェクトである global が作成されます。

このハンドラメソッドはデバッグ対象の実行方法を指定する再開値を返さなければなりません。ただし { return:value } 再開値は未定義 undefined (“continue normally”) のように扱われ、value は無視されます。(ハンドラが新しいグローバルオブジェクトに独自の値を代入できるようにすることは有用ではないようです。)

このハンドラメソッドは、特権コード (Firefoxの "chrome") で動作するデバッガでのみ使用できます。 この Debugger APIによって提供されるほとんどの機能は、APIのユーザーが到達可能なグローバルのみでアクティビティーを監視し、Debugger の到達範囲に関する機能ベースの制限を課します。 ただし、onNewGlobalObject メソッドを使用すると、API ユーザーは JavaScript システム内の任意の場所で発生するすべてのグローバルオブジェクトの作成 (SpiderMonkey 用語では "JSRuntime") を監視し、機能ベースの制限をエスケープできます。 このため、onNewGlobalObject は特権コードでのみ使用できます。

Debugger Prototype オブジェクトの関数プロパティ

以下に説明する関数は Debugger インスタンスを参照して this の値を呼び出すことができます。他の種類のオブジェクトのメソッドとして使用することはできません。

addDebuggee(global)

この Debugger インスタンスがデバッグしているグローバルオブジェクトのセットに global で指定されたグローバルオブジェクトを追加します。指定された global がすでにデバッグ対象である場合、これは効果がありません。指定された global を参照して、この DebuggerDebugger.Object インスタンスを返します。

global の値は、次のいずれかです。

  • グローバルオブジェクト

  • HTML5 の WindowProxy オブジェクト (Firefox の用語では「外側のウィンドウ」)。閲覧コンテキストのアクティブドキュメントのウィンドウオブジェクト (「内部ウィンドウ」)が渡されたかのように扱われます。

  • オブジェクトのクロスコンパートメントラッパー。ラップされたオブジェクトに以前のルールを適用します。

  • この Debugger インスタンスに属する Debugger.Object インスタンス。先の規則を指示対象に適用します。

  • 他の値の型は TypeError として扱われます。(各ルールは与えられたグローバル引数を解決する過程で一度しか適用されないことに注意してください。したがって、例えば、2番目の Debugger.Object を参照する Debugger.Object は、この関数の対象の global を指定しません。)

global で指定されたグローバルは、この Debugger インスタンス自体とは異なるコンパートメントになければなりません。指定されたグローバル区画を追加すると、デバッガとデバッグ区画のサイクルが作成される場合、このメソッドはエラーをスローします。

このメソッドは、指示対象が指定されたグローバルオブジェクトである Debugger.Object インスタンスを返します。

Debugger インスタンスには、デバッグ対象グローバル値の強力な参照は含まれていません。デバッグ対象グローバル値がそれ以外の場合は到達できない場合、デバッガのデバッグセットからドロップされます。(当然、このメソッドが返す Debugger.Object インスタンスは、追加されたグローバルへの強い参照を保持します)。

このデバッガが割り当てられたサイトを追跡中で、グローバルの割り当てサイトを追跡できない場合、このメソッドは Error をスローします。

addAllGlobalsAsDebuggees()

このメソッドは addDebuggee に似ていますが、すべてのコンパートメントのすべてのグローバルオブジェクトをこの Debugger インスタンスのデバッガセットに追加します。このデバッガのコンパートメントをスキップすることに注意してください。

このデバッガが割り当てサイトを追跡中で、一部のグローバルの割り当てサイトを追跡できない場合、このメソッドは Error をスローします。それ以外の場合、このメソッドは undefined を返します。

This method is only available to debuggers running in privileged code (“chrome”, in Firefox). Most functions provided by this Debugger API observe activity in only those globals that are reachable by the API’s user, thus imposing capability-based restrictions on a Debugger’s reach. However, the addAllGlobalsAsDebuggees method allows the API user to monitor all global object creation that occurs anywhere within the JavaScript system (the “JSRuntime”, in SpiderMonkey terms), thereby escaping the capability-based limits. For this reason, addAllGlobalsAsDebuggees is only available to privileged code.

removeDebuggee(global)

Remove the global object designated byglobal from this Debugger instance’s set of debuggees. Return undefined.

This method interpretsglobal using the same rules that addDebuggee does.

Removing a global as a debuggee from this Debugger clears all breakpoints that belong to that Debugger in that global.

removeAllDebuggees()
Remove all the global objects from this Debugger instance’s set of debuggees. Return undefined.
hasDebuggee(global)

Return true if the global object designated byglobal is a debuggee of this Debugger instance.

This method interpretsglobal using the same rules that addDebuggee does.

getDebuggees()

Return an array of distinct Debugger.Object instances whose referents are all the global objects this Debugger instance is debugging.

Since Debugger instances don’t hold strong references to their debuggee globals, if a debuggee global is otherwise unreachable, it may be dropped at any moment from the array this method returns.

getNewestFrame()
Return a Debugger.Frame instance referring to the youngest visible frame currently on the calling thread’s stack, or null if there are no visible frames on the stack.
findSources([query])(not yet implemented)

Return an array of all Debugger.Source instances matchingquery. Each source appears only once in the array.Query is an object whose properties restrict which sources are returned; a source must meet all the criteria given byquery to be returned. Ifquery is omitted, we return all sources of all debuggee scripts.

クエリには次のプロパティがあります。

url
ソースの url プロパティは、この値と等しくなければなりません。
global
The source must have been evaluated in the scope of the given global object. If this property’s value is a Debugger.Object instance belonging to this Debugger instance, then its referent is used. If the object is not a global object, then the global in whose scope it was allocated is used.

結果には、debuggeeでこれまで使用できなくなったソース、たとえば、実行を終了した評価コード、到達不能な関数のソースなどが含まれることに注意してください。 そのようなソースが表示されるかどうかはガベージコレクタの動作によって影響を受けるため、この関数の結果は完全に確定的ではありません。

findScripts([query])

Return an array of Debugger.Script instances for all debuggee scripts matchingquery. Each instance appears only once in the array.Query is an object whose properties restrict which scripts are returned; a script must meet all the criteria given byquery to be returned. Ifquery is omitted, we return the Debugger.Script instances for all debuggee scripts.

Querymay have the following properties:

url
The script’s url property must be equal to this value.
source
The script’s source property must be equal to this value.
line
The script must at least partially cover the given source line. If this property is present, the url property must be present as well.
column
The script must include given column on the line given by the line property. If this property is present, the url and line properties must both be present as well.
innermost
If this property is present and true, the script must be the innermost script covering the given source location; scripts of enclosing code are omitted.
global
The script must be in the scope of the given global object. If this property’s value is a Debugger.Object instance belonging to this Debugger instance, then its referent is used. If the object is not a global object, then the global in whose scope it was allocated is used.

All properties ofquery are optional. Passing an empty object returns all debuggee code scripts.

Note that the result may include Debugger.Script instances for scripts that can no longer ever be used by the debuggee, say, those for eval code that has finished running, or unreachable functions. Whether such scripts appear can be affected by the garbage collector’s behavior, so this function’s behavior is not entirely deterministic.

findObjects([query])

Return an array of Debugger.Object instances referring to each live object allocated in the scope of the debuggee globals that matches query. Each instance appears only once in the array. Query is an object whose properties restrict which objects are returned; an object must meet all the criteria given by query to be returned. If query is omitted, we return the Debugger.Object instances for all objects allocated in the scope of debuggee globals.

The query object may have the following properties:

class
If present, only return objects whose internal [[Class]]’s name matches the given string. Note that in some cases, the prototype object for a given constructor has the same [[Class]] as the instances that refer to it, but cannot itself be used as a valid instance of the class. Code gathering objects by class name may need to examine them further before trying to use them.

All properties of query are optional. Passing an empty object returns all objects in debuggee globals.

Unlike findScripts, this function is deterministic and will never return Debugger.Objects referring to previously unreachable objects that had not been collected yet.

clearBreakpoint(handler)
この handler をハンドラーとして使用するこの Debugger インスタンスで設定されたすべてのブレークポイントを削除します。 他のハンドラオブジェクトを使用しているブレークポイントがハンドラと同じ場所に設定されている場合、これらのハンドラはそのまま残ります。
clearAllBreakpoints()
この Debugger インスタンスを使用して設定されたすべてのブレークポイントを削除します。
findAllGlobals()

この JavaScript インスタンスに存在するすべてのグローバルオブジェクトを参照する Debugger.Object インスタンスの配列を返します。

この呼び出しの結果は、JavaScript 実装の詳細によって非決定論的な方法で影響を受ける可能性があります。配列には、デバッグ対象またはシステム内の他のコードが実際に到達できないグローバルオブジェクトを参照する Debugger.Object インスタンスが含まれている場合があります。(当然ながら、関数が返ったら、配列の Debugger.Object インスタンスは参照するグローバルを強く参照します)。

このハンドラメソッドは、特権コード (Firefox の "chrome") で動作するデバッガでのみ使用できます。この Debugger API によって提供されるほとんどの機能は、API のユーザーが到達可能なグローバルのみでアクティビティを監視し、Debugger の到達範囲に関する機能ベースの制限を課します。ただし、findAllGlobals を使用すると、API ユーザーは JavaScript システム内のすべてのグローバルオブジェクト (SpiderMonkey の用語では "JSRuntime") をすべて見つけることができるため、機能ベースの制限を逃れることができます。このため、findAllGlobals は特権コードでのみ使用できます。

makeGlobalObjectReference(global)
指定されたグローバルをデバッグ対象として追加することなく、グローバルで指定されたグローバルオブジェクトであるレファレントを持つ Debugger.Object を返します。global がグローバルオブジェクトを指定していない場合は、TypeError をスローします。Debugger.prototype.addDebuggee と同じ規則を使用して、どのグローバル値が global で指定されているかを判断します。
adoptDebuggeeValue(value)

任意の Debugger が所有するデバッグ対象の値の value が与えられた場合、このDebuggerが所有する同等のデバッグ対象の値を返します。

value がプリミティブ値の場合はそのまま返します。value が任意の Debugger が所有する Debugger.Object の場合、この Debugger が所有する同等の Debugger.Object を返します。それ以外の場合、value が他の種類のオブジェクトであるため、適切なデバッグ対象の値ではない場合は、代わりに TypeError をスローします。

Debugger オブジェクトの静的メソッド

以下で説明する関数は、this の値では呼び出されません。

isCompilableUnit(source)
ソースによって指定されたソースコードの文字列が与えられた場合、文字列が有効な JavaScript ステートメントになり、行が追加された場合は false を返します。それ以外の場合は true を返します。その目的は、インタラクティブなコンパイルをサポートすることです。isCompilableUnit が true になるまでバッファに行を累積し、コンパイラに渡します。

ソースのメタデータ

生成元ファイル:
 
js/src/doc/Debugger/Debugger.md
透かし:
sha256:03b36132885e046a5f213130ba22b1139b473770f7324b842483c09ab7665f7c
変更セット:
e91b2c85aacd

ドキュメントのタグと貢献者

このページの貢献者: silverskyvicto
最終更新者: silverskyvicto,