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

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 を指定しません。)

The global designated byglobal must be in a different compartment than this Debugger instance itself. If adding the designated global’s compartment would create a cycle of debugger and debuggee compartments, this method throws an error.

This method returns the Debugger.Object instance whose referent is the designated global object.

The Debugger instance does not hold a strong reference to its debuggee globals: if a debuggee global is not otherwise reachable, then it is dropped from the Debugger’s set of debuggees. (Naturally, the Debugger.Object instance this method returns does hold a strong reference to the added global.)

If this debugger is tracking allocation sites and cannot track allocation sites forglobal, this method throws an Error.

addAllGlobalsAsDebuggees()

This method is like addDebuggee, but adds all the global objects from all compartments to this Debugger instance’s set of debuggees. Note that it skips this debugger’s compartment.

If this debugger is tracking allocation sites and cannot track allocation sites for some global, this method throws an Error. Otherwise this method returns 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.

Querymay have the following properties:

url
The source’s url property must be equal to this value.
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)
Remove all breakpoints set in this Debugger instance that usehandler as their handler. Note that, if breakpoints using other handler objects are set at the same location(s) ashandler, they remain in place.
clearAllBreakpoints()
Remove all breakpoints set using this Debugger instance.
findAllGlobals()

Return an array of Debugger.Object instances referring to all the global objects present in this JavaScript instance.

The results of this call can be affected in non-deterministic ways by the details of the JavaScript implementation. The array may include Debugger.Object instances referring to global objects that are not actually reachable by the debuggee or any other code in the system. (Naturally, once the function has returned, the array’s Debugger.Object instances strongly reference the globals they refer to.)

This handler 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, findAllGlobals allows the API user to find all global objects anywhere within the JavaScript system (the “JSRuntime”, in SpiderMonkey terms), thereby escaping the capability-based limits. For this reason, findAllGlobals is only available to privileged code.

makeGlobalObjectReference(global)
Return the Debugger.Object whose referent is the global object designated byglobal, without adding the designated global as a debuggee. Ifglobal does not designate a global object, throw a TypeError. Determine which global is designated byglobal using the same rules as Debugger.prototype.addDebuggee.
adoptDebuggeeValue(value)

Given a debuggee value value owned by an arbitrary Debugger, return an equivalent debuggee value owned by this Debugger.

If value is a primitive value, return it unchanged. If value is a Debugger.Object owned by an arbitrary Debugger, return an equivalent Debugger.Object owned by this Debugger. Otherwise, if value is some other kind of object, and hence not a proper debuggee value, throw a TypeError instead.

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

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

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

ソースのメタデータ

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

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

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