Opera ECMAScript debugger (remote debugger, Python version)
===========================================================


Description
-----------

This manual is provided as a brief introduction to the Python remote
debugger (in its current state) and the commands it supports.  It will
be updated as support for new commands is added.  At the end there is
a list of "features to be implemented".


How to get started
------------------

- Use a current version of core-2 and the filofax_2 branch (not the
  latest release) of the ecmascript_utils.  You may want to use the
  linear_b branch of the ecmascript module too, since any API changes
  in linear_b will be implemented as soon as possible in filofax_2.

- Make sure the following macros are defined:

    ECMASCRIPT_DEBUGGER
    ECMASCRIPT_ENGINE_DEBUGGER
    ECMASCRIPT_REMOTE_DEBUGGER
    ECMASCRIPT_REMOTE_DEBUGGER_FRONTEND

  This will of course be handled by features in the future.

- Add the following to your configuration file (opera6.ini):

    [Extensions]
    Script Debugger=1
    Remote Script Debugger=1
    Remote Script Debugger IP=xxx.xxx.xxx.xxx

  where "xxx.xxx.xxx.xxx" is the IP address of the computer on which
  the Python remote debugger is run (defaults to "127.0.0.1").  There
  is also a "Remote Script Debugger Port" preference which defaults to
  9999.

  The "Remote Script Debugger" preferences are expected to be
  available starting from version smurf_1_beta_24 of the prefs module.
  Use HEAD until it has been released.

- Start the Python debugger like this:

    python main.py

- Start Opera

Once started, the Python remote debugger is designed to accept any
number of connections from Opera processes (simultaneous or not)
without being restarted.  Opera, on the other hand, will currently
only try to connect once during startup and never again (nor will it
try to reconnect if the connection is lost), so the Python remote
debugger must be started before Opera is started and Opera must be
restarted in order to continue debugging if the connection is lost.


Is it working?
--------------

Typically, if everything is working, the debugger output will be
something like this if you start it and then start Opera:

  Opera ECMAScript debugger

  New session: <operating system>/<platform> [connected to <ip>:<port>]
  Setting new session as current session
  (idle) 

and if you load a page with an inline script in it, the output will be
something like:

  Opera ECMAScript debugger

  New session: <operating system>/<platform> [connected to <ip>:<port>]
  Setting new session as current session
    <first statement in script>
  (stopped) 


Command line arguments
----------------------

Available command line arguments:
   -f
      Emacs gud interface

   -x <FILE>
      Execute commands from <FILE> on startup, then continue as normal.

   -n
      Don't run commands from ~/.esdbinit on startup (done otherwise)

   -p, --listen-port <PORT>
      Listen for connections on given port number (default is 9999)


Supported commands
------------------

@cmd show
show [sessions|threads|scripts|breakpoints]

  Display some information.  Currently supported arguments:

    show sessions

      Displays information about current sessions.

    show threads

      Displays information about all running or stopped (not finished)
      threads in the current session.

    show scripts

      Displays information about all known scripts in the current
      session.

    show breakpoints

      Displays information about all breakpoints in the current session.

@cmd select
select [session|thread] <index>

  Selects current session or thread.  The first argument should be
  "session" or "thread" and the second argument should be an integer
  (the number displayed in front of the session or thread in the
  output of the "show <what>" command.)

@cmd next
next

  Continues execution, stops at the next statement, does not step into
  functions called from the current statement.

@cmd step
step

  Continues exection, stops at the next statement, steps into
  functions called from the current statement.

@cmd finish
finish

  Finishes execution of the current function.

@cmd continue
continue

  Continues execution until a new thread is started or a breakpoint is
  triggered.

@cmd print
print[/s*] expression

  Evaluates the argument in the context of the topmost frame in the
  current thread and displays the result.  Available options are:

    s: convert result to a string and print without escaping
    *: disable magic variables in the expression

@cmd list
list <#script>? [-|line]

  Prints the 10 lines surrounding either the line specified or the
  last line printed if no argument is given.  If the last lines
  printed were printed by the list command, list without an argument
  prints the 10 lines following those lines and list with the argument
  '-' prints the 10 lines preceding those lines.

  If the first argument is an integer prefixed by a "#", lines from
  the script with that index are printed.  If there is no second
  argument, the 10 first lines are printed, otherwise the second
  argument should be an integer, in which case the 10 lines surrounding
  that line are printed.  For a list of scripts (and their indeces),
  see the output from the

    show scripts

  command.

  If any or all of the lines that would be printed do not exist, those
  lines are not printed.
  
  The number 10 is configurable by issuing the command

    set listsize <number>

@cmd break
break <#script>? <where>

  Adds a breakpoint at the specified line in the script that the
  current thread's current position is in (if 'where' is a number) or
  at the function that is returned by evaluating 'where' as an
  expression.  When an identical new script is added (such as when the
  page is reloaded in the debugee), all breakpoints in the existing
  script will be copied to the same line in the new script.

  If the first argument is an integer prefixed by a "#", the second
  argument should be a line number, and a breakpoint at the specified
  line in the script with the specified index is added.

@cmd disable
disable <id>

  Disables breakpoint by id.

@cmd enable
enable <id>

  Enables disabled breakpoint by id.

@cmd delete
delete <id>

  Deletes breakpoint by id.

@cmd examine,x
examine[/px+-*] [depth] [{name1,name2,...}] <expression>
x[/px+-*] [depth] [{name1,name2,...}] <expression>

  Displays all properties of the object returned by the expression.
  Available options are:

    p: expand prototype objects recursively
    x: expand property objects recursively
    +: inclusive filter on properties to display (and expand, with 'x')
    -: exception filter on properties to display (and expand, with 'x')
    *: disable magic variables in the expression

  With 'p' and 'x', the optional 'depth' argument specifies how deeply
  objects should be expanded.  The default is 65535, which is probably
  a completely unreasonable default that should be changed to 8 or
  something.

  With '+' and '-', the mandatory filter argument is a comma-separated
  list of property names to include or exclude, surrounded by braces.
  No whitespace is allowed.

@cmd set
set <what> <value>

  Set configuration variable.  Boolean variables accept the values
  "yes", "true", "on" and "1" for true and "no", "false", "off" and
  "0" for false.

  The following boolean variables are supported:

    stop-at-script: stop at all new scripts (threads)
    stop-at-exception: stop when an exception is thrown
    stop-at-error: stop when an error occurs
    stop-at-abort: stop when a script is aborted
    stop-at-gc: stop when the garbage collector has run

  The following numeric variables are supported:

    listsize: number of lines printed by list

  Note: the variables stop-at-* are session local.  When set when
  there is no session, all new sessions wlil inherit the set value
  when they are created.  When set when there is a session, only the
  current session is affected.
        
@cmd execute
execute[/s*] <filename>

  Loads a local file and executes its content in the current context
  (like print, but the contents need not be an expression).  Same
  options as print.

@cmd evaluate
evaluate[/s*] [<<DELIM]

  Reads a script until end-of-file (ctrl-d, may not work, depending on
  terminal capabilities) or until a line containing exactly DELIM
  (like shell "here-documents") and executes it in the current
  context.  Same options as print.

@cmd backtrace,bt,where
backtrace
bt
where

  Lists the current call stack.

@cmd frame
frame <index>

  Selects the index'th frame (as indexed by the backtrace command).

@cmd up
up

  Selects the previous stack frame.

@cmd down
down

  Selects the next stack frame.

@cmd help
help [topic]
? [topic]

  Print help on a topic.  Without arguments it lists the topics.

@end


@cmd variables
Magic variables
---------------

Whenever the result of a command (such as print or execute) or a
function return value is printed, it is printed as

  $1 = <value>

where '1' is that value's id.  In future calls to print, execute,
break, examine (any command that evaluates code) any occurence of $1
will evaluate to that value.

The following special ids are be used for certain special values.
They are always available.

  $n => null
  $u => undefined
  $t => true
  $f => false
  $z => 0
  $e => ""

Furthermore, any time an object is printed, it is printed as

  $$1 = [object <classname>]

or

  $$1 = function <name>() { ... }

where '1' is that object's id.  Any occurence of $$1 in code that is
evaluated by the debugger will evaluate to a reference to that object.

@end


@cmd programmatic breakpoints
Programmatic breakpoints
------------------------

If the debugger is enabled, a single expression statement of the form

  debugger;

in a program will trigger a breakpoint in the debugger.  There is
currently no way to disable these breakpoints.
@end


Features to be implemented
--------------------------

- Some sort of freeing of object ids.  The debugee keeps a map from
  internal ES_Object pointers to external object ids and protects all
  the objects from garbage collection.  Obviously, at some point the
  ids should be freed.  To support long debug sessions, maybe the
  debugger should have a command for flushing the object id map.
