summaryrefslogtreecommitdiffstats
path: root/js/src/doc/Debugger/Tutorial-Debugger-Statement.md
diff options
context:
space:
mode:
Diffstat (limited to 'js/src/doc/Debugger/Tutorial-Debugger-Statement.md')
-rw-r--r--js/src/doc/Debugger/Tutorial-Debugger-Statement.md82
1 files changed, 82 insertions, 0 deletions
diff --git a/js/src/doc/Debugger/Tutorial-Debugger-Statement.md b/js/src/doc/Debugger/Tutorial-Debugger-Statement.md
new file mode 100644
index 000000000..58360ff6f
--- /dev/null
+++ b/js/src/doc/Debugger/Tutorial-Debugger-Statement.md
@@ -0,0 +1,82 @@
+Tutorial: Evaluate an Expression When a debugger; Statement Is Executed
+=======================================================================
+
+This page shows how you can try out the [`Debugger` API][debugger] yourself
+using Firefox's Scratchpad. We use the API to evaluate an expression in the web
+page whenever it executes a JavaScript `debugger;` statement.
+
+1) Visit the URL `about:config`, and set the `devtools.chrome.enabled`
+ preference to `true`:
+
+ ![Setting the 'devtools.chrome.enabled' preference][img-chrome-pref]
+
+2) Save the following HTML text to a file, and visit the file in your
+ browser:
+
+ ```language-html
+ <div onclick="var x = 'snoo'; debugger;">Click me!</div>
+ ```
+
+3) Open a developer Scratchpad (Menu button > Developer > Scratchpad), and
+ select "Browser" from the "Environment" menu. (This menu will not be
+ present unless you have changed the preference as explained above.)
+
+ ![Selecting the 'browser' context in the Scratchpad][img-scratchpad-browser]
+
+4) Enter the following code in the Scratchpad:
+
+ ```language-js
+ // This simply defines 'Debugger' in this Scratchpad;
+ // it doesn't actually start debugging anything.
+ Components.utils.import("resource://gre/modules/jsdebugger.jsm");
+ addDebuggerToGlobal(window);
+
+ // Create a 'Debugger' instance.
+ var dbg = new Debugger;
+
+ // Get the current tab's content window, and make it a debuggee.
+ var w = gBrowser.selectedBrowser.contentWindow.wrappedJSObject;
+ dbg.addDebuggee(w);
+
+ // When the debuggee executes a 'debugger' statement, evaluate
+ // the expression 'x' in that stack frame, and show its value.
+ dbg.onDebuggerStatement = function (frame) {
+ alert('hit debugger statement; x = ' + frame.eval('x').return);
+ }
+ ```
+
+5) In the Scratchpad, ensure that no text is selected, and press the "Run"
+ button.
+
+6) Now, click on the text that says "Click me!" in the web page. This runs
+ the `div` element's `onclick` handler. When control reaches the
+ `debugger;` statement, `Debugger` calls your callback function, passing
+ a `Debugger.Frame` instance. Your callback function evaluates the
+ expression `x` in the given stack frame, and displays the alert:
+
+ ![The Debugger callback displaying an alert][img-example-alert]
+
+7) Press "Run" in the Scratchpad again. Now, clicking on the "Click me!"
+ text causes *two* alerts to show---one for each `Debugger`
+ instance.
+
+ Multiple `Debugger` instances can observe the same debuggee. Re-running
+ the code in the Scratchpad created a fresh `Debugger` instance, added
+ the same web page as its debuggee, and then registered a fresh
+ `debugger;` statement handler with the new instance. When you clicked
+ on the `div` element, both of them ran. This shows how any number of
+ `Debugger`-based tools can observe a single web page
+ simultaneously---although, since the order in which their handlers
+ run is not specified, such tools should probably only observe, and not
+ influence, the debuggee's behavior.
+
+8) Close the web page and the Scratchpad.
+
+ Since both the Scratchpad's global object and the debuggee window are
+ now gone, the `Debugger` instances will be garbage collected, since
+ they can no longer have any visible effect on Firefox's behavior. The
+ `Debugger` API tries to interact with garbage collection as
+ transparently as possible; for example, if both a `Debugger.Object`
+ instance and its referent are not reachable, they will both be
+ collected, even while the `Debugger` instance to which the shadow
+ belonged continues to exist.