GDB - A GDB commandline like protocol to interact with Xdebug
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Version: 1.0
:Status: draft 1
:Authors: - Derick Rethans <derick@xdebug.org>


.. contents::

1. Description
==============

This document describes a simple GDB-like protocol to interact with
Xdebug with a simple client. The protocol is a text based protocol
for easy implementation and human readability, it is not meant to be
implemented in a GUI debugger.
The protocol provides a means of communication between a debugger engine
(Xdebug) and a debugger client (such as Xdebug 1.3's bundled client).

The structure (and some of the text) in this specification are reused from
the `DBGp specifications <http://xdebug.org/docs-dbgp.php>`_.


2. Terminology
==============

debug client
    A client to interact with the debugger engine.

debugger engine
    The language engine being debugged.

TRUE
    a value defined as TRUE should be a numeric one.

FALSE
    a value defined as FALSE should be a numeric zero.


3. Initiating a debugging session
=================================

The debugger engine initiates a debugging session.  The debugger engine
will make a connection to a listening debug client, then wait for the debug
client to initiate commands.  The debugger engine does not step into the first
line of execution until the IDE issues one of the continuation commands.  The
first thing that should happen in a debug session is that the debug client
sets options with the option command, and sets
any additional data, such as breakpoints.  Debugger engine implementations
should store and data it receives if it is unable to process them prior to
compiling and/or executing code. Only commands from the "init" section
can be used at this stage.


3.1 Standard GDB port
----------------------

The debug client listens by default on port 17869 for debugger connections, but
this port might be configurable.

.. 5.2 Connection Initialization
.. -----------------------------
.. 
.. When a debugger engine connects to either a IDE or proxy, it must send an
.. init packet: ::
.. 
..     <init appid="APPID"
..           idekey="IDE_KEY"
..           session="DBGP_COOKIE"
..           thread="THREAD_ID"
..           parent="PARENT_APPID"
..           language="LANGUAGE_NAME"
..           protocol_version="1.0"
..           fileuri="file://path/to/file">
.. 
.. 
.. Attributes in the init element can include:
..     
..     =============== ========================================================
..     Attribute       Description
..     =============== ========================================================
..     appid           defined by the debugger engine
..     idekey          defined by the user.  The DBGP_IDEKEY environment
..                     variable SHOULD be used if it is available,
..                     otherwise setting this value is debugger engine
..                     implementation specific.  This value may be empty.
..     session         If the environment variable DBGP_COOKIE exists,
..                     then the init packet MUST contain a session
..                     attribute with the value of the variable.  This
..                     allows an IDE to execute a debugger engine, and
..                     maintain some state information between the
..                     execution and the protocol connection.  This value
..                     should not be expected to be set in 'remote'
..                     debugging situations where the IDE is not in
..                     control of the process.  
..     thread_id       the systems thread id
..     parent_appid    the appid of the application that spawned the
..                     process.  When an application is executed, it
..                     should set it's APPID into the environment.
..                     If an APPID already exists, it should first
..                     read that value and use it as the PARENT_APPID.
..     language_name   debugger engine specific, must not contain
..                     additional information, such as version, etc.
..     protocol        The highest version of this protocol supported
..     fileuri         URI of the script file being debugged
..     =============== ========================================================
.. 
.. The IDE responds by dropping socket connection, or starting with
.. debugger commands.
.. 
.. The init packet may have child elements for additional vendor specific
.. data.  These are entirely optional and must not effect behavior
.. of the debugger interaction.  Suggested child elements include: ::
.. 
..     <engine version="1.abcd">product title</engine>
..     <author>author</author>
..     <company>company</company>
..     <license>licensing info</license>
..     <url>url</url>
..     <copyright>xxx</copyright>
.. 
.. 5.3 Just in time debugging and debugger proxies
.. -----------------------------------------------
.. 
.. Proxies are supported to allow multiuser systems work with a defined
.. port for debugging.  Each IDE would listen on a unique port and notify the
.. proxy what port it is listening on, along with a key value that is used by
.. the debugger engine to specify which IDE it should be connected with.
.. 
.. With the exception of the init packet, all communications
.. will be passed through without modifications.  A proxy could also implement
.. support for just in time debugging.  In this case, a debugger engine would
.. break (perhaps on an error or exception) and connect to the proxy.  The proxy
.. would then start the IDE (if it is not already running) and initiate a
.. debugging session with it.
.. 
.. The method for handling just in time debugging is not defined by the protocol
.. and is implementation specific.  One example of how this may work is that the
.. proxy has a configuration file that defines key's for each user, along with
.. the path to the executable that will provide the UI for that user.  The debugger
.. engine would have to know this key value in advance and provide it to the proxy
.. in the init packet (see IDE_KEY in section 5.2).  The proxy would know if the
.. IDE is running, since the IDE should have communicated with the proxy already,
.. if it has not, the proxy could execute the IDE directly.
.. 
.. To support proxies and jit deamons, the IDE should be configured with
.. and ip:port pointing to the proxy/jit.  The IDE then makes a
.. connection to the proxy when it starts and sends the following command: 
.. 
..     IDE command ::
..     
..         proxyinit -a ip:port -k ide_key -m [0|1]
.. 
..     ==  ========================================================
..     -p  the port that the IDE listens for debugging on.  The address
..         is retrieved from the connection information.
..     -k  a IDE key, which the debugger engine will also use in it's
..         debugging init command.  this allows the proxy to match
..         request to IDE.  Typically the user will provide the
..         session key as a configuration item.
..     -m  this tells the demon that the IDE supports (or doesn't)
..         multiple debugger sessions.  if -m is missing, zero or no
..         support is default.
..     ==  ========================================================
.. 
..     IDE command ::
..     
..         proxystop -k ide_key
..     
..     The IDE sends a proxystop command when it wants the proxy
..     server to stop listening for it.
.. 
.. The proxy should respond with a simple XML statement alerting the
.. IDE to an error, or the success of the initialization (see section
.. 6.5 for more details on the error element). ::
.. 
..     <proxyinit success="[0|1]"
..                idekey="{ID}">
..         <error id="app_specific_error_code">
..             <message>UI Usable Message</message>
..         </error>
..     </proxyinit>
.. 
.. Once the IDE has sent this command, and received a confirmation, it
.. disconnects from the proxy.  The IDE will only connect to the proxy
.. when it initially wants to start accepting connections from the proxy,
.. or when it wants to stop accepting connections from the proxy.
.. 
.. 5.3.1 Init Packet Handling
.. ^^^^^^^^^^^^^^^^^^^^^^^^^^
.. 
.. If a proxy receives the init packet (see section 5.2), it will use the
.. idekey attribute to pass the request to the correct IDE, or to do some
.. other operation such as which may be required to implement security or
.. initiate just in time debugging.  The proxy will add the idekey as a attribute
.. to the init packet when it passes it through to the IDE.  The proxy may
.. also add child elements with further information, and must add an
.. attribute to the init element called 'proxied' with the attribute
.. value being the ip address of the debugger engine.  This is the only
.. time the proxy should modify data being passed to the IDE.
.. 
.. 5.3.2 Proxy Errors
.. ^^^^^^^^^^^^^^^^^^
.. 
.. If the proxy must send error data to the IDE, it may send an XML
.. message with the root element named 'proxyerror'.  This message will
.. be in the format of the error packets defined in 6.3 below.
.. 
.. If the proxy must send error data to the debugger engine, it may
.. send the proxyerror command defined in section 7 below.
.. 
.. 5.3.3 Proxy Ports
.. ^^^^^^^^^^^^^^^^^
.. 
.. The proxy listens for IDE connections on port 9001, and for debugger
.. engine connections on port 9000.  As with section 5.1, these ports may
.. be configurable in the implementation.
.. 
.. 5.5 Feature Negotiation
.. -----------------------
.. 
.. Although the IDE may at any time during the debugging session send
.. feature_get or feature_set commands, the IDE should be designed to
.. negotiate the base set of features up front.  Differing languages and
.. debugger engines may operate in many ways, and the IDE should be
.. prepared to handle these differences.  Likewise, the IDE may dictate
.. certain features or capabilities be supported by the debugger engine.
.. In any case, the IDE should strive to work with all debugger engines
.. that support this protocol.  Therefore, this section describes a
.. minimal set of features the debugger engine must support.  These
.. required features are outlined here in the form of discussion,
.. actual implementation of feature arguments are detailed in section 7
.. under the feature_get and feature_set commands.
.. 
.. 
.. 6. Message Packets
.. ==================
.. 
.. The IDE sends simple ASCII commands to the debugger engine.  The
.. debugger engine responds with XML data.  The XML data is prepended
.. with a stringified integer representing the length of the XML data
.. packet.  The length and XML data are separated by a NULL byte.  The
.. XML data is ended with a NULL byte.  Neither the IDE or debugger engine
.. packets may contain NULL bytes within the packet since it is used as
.. a separator.  Binary data must be encoded using base64. ::
.. 
..     IDE:       command [SPACE] [args] -- data [NULL]
..     DEBUGGER:  [NUMBER] [NULL] XML(data) [NULL]
.. 
.. Arguments to the IDE commands are in the same format as common command
.. line arguments, and should be parseable by common code such as getopt,
.. or Pythons Cmd module: ::
.. 
..     command -a value -b value ...
.. 
.. All numbers in the protocol are base 10 string representations, unless
.. the number is noted to be debugger engine specific (eg. the address
.. attribute on property elements).
.. 
.. 6.1 Why not XML both ways?
.. --------------------------
.. 
.. The primary reason is to avoid the requirement that a debugger
.. engine has an XML parser available.  XML is easy to generate, but
.. requires additional libraries for parsing.
.. 
.. 
.. 6.2 Packet Communications
.. -------------------------
.. 
.. The IDE sends a command, then waits for a response from the
.. debugger engine.  If the command is not received in a reasonable
.. time (implementation dependent) it may assume the debugger engine
.. has entered a non-responsive state.  The exception to this is when
.. the IDE sends a 'continuation' command which may not have an immediate response.
.. 
.. 'continuation' commands include, but may not be limited to: run, step_into,
.. step_over, step_out and eval.  When the debugger engine
.. receives such a command, it is considered to have entered a
.. 'run state'.
.. 
.. During a 'continuation' command, the IDE should expect to possibly receive
.. stdin and/or stderr packets from the debugger engine prior to
.. receiving a response to the command itself.  It may also possibly
.. receive error packets from either the debugger engine, or a proxy
.. if one is in use, either prior to the 'continuation' response, or in response
.. to any other command.
.. 
.. Stdout and stderr, if requested by the IDE, may only be sent during
.. commands that have put the debugger engine into a 'run' state.
.. 
.. If the debugger engine supports asynchronous commands, the IDE may also
.. send commands while the debugger engine is in a 'run' state.  These
.. commands should be limited to commands such as the 'break' or 'status'
.. commands for performance reasons, but this protocol does not impose
.. such limitations.  The debugger engine MUST respond to these commands
.. prior to responding to the original 'run' command.
.. 
.. An example of communication between IDE and debugger engines.  (this
.. is not an example of the actual protocol.) ::
.. 
..     IDE:  feature_get supports_async
..     DBG:  yes
..     IDE:  stdin redirect
..     DBG:  ok
..     IDE:  stderr redirect
..     DBG:  ok
..     IDE:  run
..     DBG:  stdin data...
..     DBG:  stdin data...
..     DBG:  reached breakpoint, done running
..     IDE:  give me some variables
..     DBG:  ok, here they are
..     IDE:  evaluate this expression
..     DBG:  stderr data...
..     DBG:  ok, done
..     IDE:  run
..     IDE:  break
..     DBG:  ok, breaking
..     DBG:  at breakpoint, done running
..     IDE:  stop
..     DBG:  good bye
.. 
.. 
.. 6.3 IDE to debugger engine communications
.. -----------------------------------------
.. 
.. A debugging IDE (IDE) sends commands to the debugger engine in
.. the form of command line arguments.  One argument that is included in
.. all commands is the data length.  The data itself is the last part of
.. the command line.  The data may be binary data if the encoding argument
.. is 'binary'. ::
.. 
..     command [SPACE] [arguments] [SPACE] base64(data) [NULL]
.. 
.. Standard arguments for all commands ::
.. 
..     -i      Transaction ID
..             unique for each command generated by the IDE
.. 
.. 6.4 debugger engine to IDE communications
.. -----------------------------------------
.. 
.. The debugger engine always replies or sends XML data.  The standard
.. namespace for the root elements returned from the debugger
.. engine MUST be "urn:debugger_protocol_v1".  Namespaces have been left
.. out in the examples in this document.  The messages sent by the
.. debugger engine must always be NULL terminated.  The XML document tag
.. must always be present to provide XML version and encoding information.
.. 
.. Two base tags are used for the root tags: ::
.. 
..     data_length
..     <?xml version="1.0" encoding="UTF-8"?>
..     <response command="command_name"
..               transaction_id="transaction_id"/>
.. 
..     data_length
..     <?xml version="1.0" encoding="UTF-8"?>
..     <stream type="stdout|stderr">...Base64 Data...</stream>
.. 
.. For simplification, data length and NULL bytes will be left out of the
.. rest of the examples in this document.
.. 
.. 6.5 debugger engine errors
.. --------------------------
.. 
.. A debugger engine may need to relay error information back to the IDE in
.. response to any command.  The debugger engine may add an error element
.. as a child of the response element.  Note that this is not the same
.. as getting language error messages, such as exception data.  This is
.. specifically a debugger engine error in response to a IDE
.. command.  IDEs and debugger engines may elect to support additional
.. child elements in the error element, but should namespace the elements
.. to avoid conflicts with other implementations. ::
.. 
..     <response command="command_name"
..               transaction_id="transaction_id">
..         <error code="error_code" apperr="app_specific_error_code">
..             <message>UI Usable Message</message>
..         </error>
..     </response>
.. 
.. 6.5.1 Error Codes
.. -----------------
.. 
.. The following are predefined error codes for the response to commands:
.. 
.. 000 Command parsing errors ::
.. 
..     0 - no error
..     1 - parse error in command
..     2 - duplicate arguments in command
..     3 - invalid options (ie, missing a required option)
..     4 - Unimplemented command
..     5 - Command not available (Is used for async commands. For instance
..         if the engine is in state "run" than only "break" and "status"
..         are available). 
.. 
.. 100 File related errors ::
.. 
..     100 - can not open file (as a reply to a "source" command if the
..           requested source file can't be opened)
..     101 - stream redirect failed 
.. 
.. 200 Breakpoint, or code flow errors ::
.. 
..     200 - breakpoint could not be set (for some reason the breakpoint
..           could not be set due to problems registering it)
..     201 - breakpoint type not supported (for example I don't support
..           'watch' yet and thus return this error)
..     202 - invalid breakpoint (the IDE tried to set a breakpoint on a
..           line that does not exist in the file (ie "line 0" or lines
..           past the end of the file)
..     203 - no code on breakpoint line (the IDE tried to set a breakpoint
..           on a line which does not have any executable code. The
..           debugger engine is NOT required to return this type if it
..           is impossible to determine if there is code on a given
..           location. (For example, in the PHP debugger backend this
..           will only be returned in some special cases where the current
..           scope falls into the scope of the breakpoint to be set)).
..     204 - Invalid breakpoint state (using an unsupported breakpoint state
..           was attempted)
..     205 - No such breakpoint (used in breakpoint_get etc. to show that
..           there is no breakpoint with the given ID)
..     206 - Error evaluating code (use from eval() (or perhaps
..           property_get for a full name get))
..     207 - Invalid expression (the expression used for a non-eval()
..           was invalid) 
.. 
.. 300 Data errors ::
.. 
..     300 - Can not get property (when the requested property to get did
..           not exist, this is NOT used for an existing but uninitialized
..           property, which just gets the type "uninitialised" (See:
..           PreferredTypeNames)).
..     301 - Stack depth invalid (the -d stack depth parameter did not
..           exist (ie, there were less stack elements than the number
..           requested) or the parameter was < 0)
..     302 - Context invalid (an non existing context was requested) 
.. 
.. 900 Protocol errors ::
.. 
..     900 - Encoding not supported
..     998 - An internal exception in the debugger occurred
..     999 - Unknown error 
.. 
.. 
.. 6.6 file paths
.. --------------
.. 
.. All file paths passed between the IDE and debugger engine must be in
.. the URI format specified by IETF RFC 1738 and 2396, and must be
.. absolute paths.
.. 
.. 6.7 Dynamic code and virtual files
.. ----------------------------------
.. 
.. The protocol reserves the URI scheme 'dbgp' for all virtual
.. files generated and maintained by language engines. Such
.. virtual files are usually managed by a language engine for
.. dynamic code blocks, i.e. code created at runtime, without
.. an association with a regular file. Any IDE seeing an URI
.. with the 'dbgp' scheme has to use the 'source' command (See
.. section 7.14) to obtain the contents of the file from the
.. engine responsible for that URI.
.. 
.. All URIs in that scheme have the form:
.. 
..     dbgp:engine-specific-identifier
.. 
.. The engine-specific-identifier is some string which the debugger engine
.. uses to keep track of the specific virtual file.  The IDE must return
.. the URI to the debugger engine unchanged through the source command to
.. retrieve the virtual file.
.. 
.. 7. Core Commands
.. ================
.. 
.. Both IDE and debugger engine must support all core commands.
.. 
.. 
.. 7.2 Options and Configuration
.. -----------------------------
.. 
.. The feature commands are used to request feature support from the debugger
.. engine. This includes configuration options, some of which may be changed via
.. feature_set, the ability to discover support for implemented commands, and to
.. discover values for various features, such as the language version or name.
.. 
.. An example of usage would be to send a feature request with the string 'stdin'
.. to find out if the engine supports redirection of the stdin stream through the
.. debugger socket. The debugger engine must consider all commands as keys for this
.. command, but may also have keys that are for features that do not map directly
.. to commands.
.. 
.. 7.2.1 Feature Names
.. ^^^^^^^^^^^^^^^^^^^
.. 
.. The following features strings MUST be available: 
.. 
..     ========================= ======= ==========================================
..     language_supports_threads get     [0|1]
..     language_name             get     {eg. PHP, Python, Perl}
..     language_version          get     {version string}
..     encoding                  get     current encoding in use by
..                                       the debugger session
..     protocol_version          get     {for now, always 1}
..     supports_async            get     {for commands such as break}
..     data_encoding             get     optional, allows to turn off
..                                       the default base64 encoding of data. This
..                                       should only be used for development and
..                                       debugging of the debugger engines
..                                       themselves, and not for general use. If
..                                       implemented the value 'base64' must be
..                                       supported to turn back on regular
..                                       encoding. the value 'none' means no
..                                       encoding is in use. all elements that use
..                                       encoding must include an encoding
..                                       attribute.
..     breakpoint_languages      get     some engines may support more than one
..                                       language. This feature returns a string
..                                       which is a comma separated list of
..                                       supported languages. **If the engine does
..                                       not provide this feature, then it is
..                                       assumed that the engine only supports the
..                                       language defined in the feature
..                                       language_name.** One example of this is an
..                                       XSLT debugger engine which supports XSLT,
..                                       XML, HTML and XHTML. An IDE may need this
..                                       information to to know what types of
..                                       breakpoints an engine will accept.
..     multiple_sessions         get|set {0|1}
..     encoding                  get|set {ISO8859-15, UTF-8, etc.}
..     max_children              get|set max number of array or object
..                                       children to initially retrieve
..     max_data                  get|set max amount of variable data to
..                               get|set initially retrieve.
..     max_depth                 get|set maximum depth that the debugger
..                                       engine may return when sending arrays,
..                                       hashs or object structures to the IDE.
..     data_encoding             get|set see feature_get
..     ========================= ======= ==========================================
.. 
.. The following features strings MAY be available, if they are not, the IDE should
.. assume that the feature is not available: 
.. 
..     ========================= ======= ==========================================
..     supports_postmortem       get     [0|1]  This feature lets an IDE know that
..                                       there is benefit to continuing interaction
..                                       during the STOPPING state (sect. 7.1).
..     show_hidden               get|set [0|1]  This feature can get set by the IDE
..                                       if it wants to have more detailed internal
..                                       information on properties (eg. private
..                                       members of classes, etc.)  Zero means that
..                                       hidden members are not shown to the IDE.
..     notify_ok                 get|set [0|1]  See section 8.5
..     ========================= ======= ==========================================
.. 
.. Additionally, all protocol commands supported must have a string,
.. such as the following examples: ::
.. 
..     breakpoint_set
..     break
..     eval
.. 
.. 7.2.3 feature_set
.. ^^^^^^^^^^^^^^^^^
.. 
.. The feature set command allows a IDE to tell the debugger engine what additional
.. capabilities it has. One example of this would be telling the debugger engine
.. whether the IDE supports multiple debugger sessions (for threads, etc.). The
.. debugger engine responds with telling the IDE whether it has enabled the feature
.. or not.
.. 
.. Note: The IDE does not have to listen for additional debugger connections if it
.. does not support debugging multiple sessions. debugger engines must handle
.. connection failures gracefully.
.. 
.. arguments for feature_set include: 
.. 
..     ==      ==========================================
..     -n      feature_name
..     -v      value to be set
..     ==      ==========================================
.. 
.. feature_set can be called at any time during a debug session to
.. change values previously set.  This allows a IDE to change
.. encodings.
.. 
.. debug client ::
.. 
..     feature_set -i transaction_id -n feature-name -v value
.. 
.. debugger engine ::
.. 
..     <response command="feature_set"
..               feature="feature_name"
..               success="0|1"
..               transaction_id="transaction_id"/>
.. 
.. 
.. 7.5 continuation commands
.. -------------------------
.. 
.. resume the execution of the application.
.. 
.. run:
..     starts or resumes the script until a new breakpoint is reached,
..     or the end of the script is reached.
.. 
.. step_into:
..     steps to the next statement, if there is a function call
..     involved it will break on the first statement in that function
.. 
.. step_over:
..     steps to the next statement, if there is a function call on the
..     line from which the step_over is issued then the debugger engine
..     will stop at the statement after the function call in the same
..     scope as from where the command was issued
.. 
.. step_out:
..     steps out of the current scope and breaks on the statement after
..     returning from the current function. (Also called 'finish' in
..     GDB)
.. 
.. stop:
..     ends execution of the script immediately, the debugger engine may
..     not respond, though if possible should be designed to do so.
..     The script will be terminated right away and be followed by a
..     disconnection of the network connection from the IDE (and debugger
..     engine if required in multi request apache processes).
.. 
.. detach (optional):
..     stops interaction with the debugger engine.  Once this command
..     is executed, the IDE will no longer be able to communicate with
..     the debugger engine.  This does not end execution of the script
..     as does the stop command above, but rather detaches from debugging.
..     Support of this continuation command is optional, and the IDE should
..     verify support for it via the feature_get command.  If the IDE has
..     created stdin/stdout/stderr pipes for execution of the script
..     (eg. an interactive shell or other console to catch script output),
..     it should keep those open and usable by the process until the process
..     has terminated normally.
.. 
.. The response to a continue command is a status response (see
.. status above).  The debugger engine does not send this response
.. immediately, but rather when it reaches a breakpoint, or ends
.. execution for any other reason.
.. 
.. debug client ::
.. 
..     run -i transaction_id
.. 
.. debugger engine ::
.. 
..     <response command="run"
..               status="starting"
..               reason="ok"
..               transaction_id="transaction_id"/>
.. 
.. 7.6 breakpoints
.. ---------------
.. 
.. Breakpoints are locations or conditions at which a debugger engine
.. pauses execution, responds to the IDE, and waits for further commands
.. from the IDE.  A failure in any breakpoint commands results in an
.. error defined in `section 6.5`_.
.. 
.. 
.. The following DBGP commands relate to breakpoints:
.. 
..     ==================  =================================================
..     breakpoint_set_     Set a new breakpoint on the session.
..     breakpoint_get_     Get breakpoint info for the given breakpoint id.
..     breakpoint_update_  Update one or more attributes of a breakpoint.
..     breakpoint_remove_  Remove the given breakpoint on the session.
..     breakpoint_list_    Get a list of all of the session's breakpoints.
..     ==================  =================================================
.. 
.. .. _breakpoint_set: `7.6.1 breakpoint_set`_
.. .. _breakpoint_get: `7.6.2 breakpoint_get`_
.. .. _breakpoint_update: `7.6.3 breakpoint_update`_
.. .. _breakpoint_remove: `7.6.4 breakpoint_remove`_
.. .. _breakpoint_list: `7.6.5 breakpoint_list`_
.. 
.. 
.. There are six different breakpoints *types*:
.. 
..     ==============  ===========     =========================================
..     Type            Req'd Attrs     Description
..     ==============  ===========     =========================================
..     line            filename,       break on the given lineno in the given
..                     lineno          file
..     call            function        break on entry into new stack for
..                                     function name
..     return          function        break on exit from stack for function
..                                     name
..     exception       exception       break on exception of the given name
..     conditional     expression      break when the given expression is true
..                                     at the given filename and line number or
..                                     just in given filename
..     watch           expression      break on write of the variable or address
..                                     defined by the expression argument
..     ==============  ===========     =========================================
.. 
.. 
.. A breakpoint has the following attributes. Note that some attributes are only
.. applicable for some breakpoint types.
.. 
..     ==================  ======================================================
..     type                breakpoint type (see table above for valid types)
..     filename            The file the breakpoint is effective in. This must be
..                         a "file://" URI.
..     lineno              Line number on which breakpoint is effective. Line
..                         numbers are 1-based. If an implementation requires a
..                         numeric value to indicate that *lineno* is not set,
..                         it is suggested that -1 be used, although this is not
..                         enforced.
..     state               Current state of the breakpoint. This must be one of
..                         *enabled*, *disabled*.
..     function            Function name for *call* or *return* type
..                         breakpoints.
..     temporary           Flag to define if breakpoint is temporary. A
..                         temporary breakpoint is one that is deleted after its
..                         first use. This is useful for features like "Run to
..                         Cursor".  Once the debugger engine uses a temporary
..                         breakpoint, it should automatically remove the breakpoint
..                         from it's list of valid breakpoints.
..     hit_count           Number of effective hits for the breakpoint in the
..                         current session.  This value is maintained by the
..                         debugger engine (a.k.a.  DBGP client).  A
..                         breakpoint's hit count should be increment whenever
..                         it is considered to break execution (i.e. whenever
..                         debugging comes to this line). If the breakpoint is
..                         *disabled* then the hit count should NOT be
..                         incremented.
..     hit_value           A numeric value used together with the
..                         *hit_condition* to determine if the breakpoint should
..                         pause execution or be skipped.
..     hit_condition       A string indicating a condition to use to compare
..                         *hit_count* and *hit_value*. The following values are
..                         legal:
.. 
..                         `>=`
..                             break if hit_count is greater than or equal to
..                             hit_value [default]
..                         `==`
..                             break if hit_count is equal to hit_value
..                         `%`
..                             break if hit_count is a multiple of hit_value
..     exception           Exception name for *exception* type breakpoints.
..     ==================  ======================================================
.. 
.. Breakpoints should be maintained in the debugger engine at an application
.. level, not the thread level.  Debugger engines that support thread debugging
.. MUST provide breakpoint id's that are global for the application, and must
.. use all breakpoints for all threads where applicable.
.. 
.. As for any other commands, if there is error the debugger engine should
.. return an error response as described in `section 6.5`_.
.. 
.. .. _`section 6.5`: `6.5 debugger engine errors`_
.. 
.. 
.. 7.6.1 breakpoint_set
.. ^^^^^^^^^^^^^^^^^^^^
.. 
.. This command is used by the IDE to set a breakpoint for the session.
.. 
.. IDE to debugger engine::
.. 
..     breakpoint_set -i TRANSACTION_ID [<arguments...>] -- base64(expression)
.. 
.. where the arguments are:
.. 
..     ==================  =====================================================
..     -t TYPE             breakpoint *type*, see below for valid values
..     -s STATE            breakpoint *state* [optional, defaults to "enabled"]
..     -f FILENAME         the *filename* to which the breakpoint belongs
..     -n LINENO           the line number (*lineno*) of the breakpoint
..     -m FUNCTION         *function* name [required for *call* or *return*
..                         breakpoint types]
..     -x EXCEPTION        *exception* name [required for *exception* breakpoint
..                         types]
..     -h HIT_VALUE        hit value (*hit_value*) used with the hit condition
..                         to determine if should break; a value of zero
..                         indicates hit count processing is disabled for this
..                         breakpoint [optional, defaults to zero (i.e.
..                         disabled)]
..     -o HIT_CONDITION    hit condition string (*hit_condition*); see
..                         hit_condition documentation above; BTW 'o' stands for
..                         'operator' [optional, defaults to '>=']
..     -r 0|1              Boolean value indicating if this breakpoint is
..                         *temporary*. [optional, defaults to false]
..     -- EXPRESSION       code *expression*, in the language of the debugger
..                         engine [required for *conditional* breakpoint types]
..     ==================  =====================================================
.. 
.. An example breakpoint_set command for a conditional breakpoint could look
.. like this::
.. 
..     breakpoint_set -i 1 -f test.pl -l 20 -- base64($x > 3)
.. 
.. A unique id for this breakpoint for this session is returned by the debugger
.. engine. This *session breakpoint id* is used by the IDE to identify the
.. breakpoint in other breakpoint commands.
.. 
.. debugger engine to IDE::
.. 
..      <response command="breakpoint_set"
..                transaction_id="TRANSACTION_ID"
..                state="STATE"
..                id="BREAKPOINT_ID"/>
.. 
.. where,
.. 
..     ==================  =====================================================
..     BREAKPOINT_ID       is an arbitrary string that uniquely identifies this
..                         breakpoint in the debugger engine.
..     STATE               the initial state of the breakpoint as set by the
..                         debugger engine
..     ==================  =====================================================
.. 
.. 
.. 7.6.2 breakpoint_get
.. ^^^^^^^^^^^^^^^^^^^^
.. 
.. This command is used by the IDE to get breakpoint information from the
.. debugger engine.
.. 
.. IDE to debugger engine::
.. 
..     breakpoint_get -i TRANSACTION_ID -d BREAKPOINT_ID 
.. 
.. where,
..     
..     ==================  =====================================================
..     BREAKPOINT_ID       is the unique *session breakpoint id* returned by
..                         *breakpoint_set*.
..     ==================  =====================================================
.. 
.. debugger engine to IDE::
.. 
..     <response command="breakpoint_get"
..               transaction_id="TRANSACTION_ID">
..         <breakpoint id="BREAKPOINT_ID"
..                     type="TYPE"
..                     state="STATE"
..                     filename="FILENAME"
..                     lineno="LINENO"
..                     function="FUNCTION"
..                     exception="EXCEPTION"
..                     hit_value="HIT_VALUE"
..                     hit_condition="HIT_CONDITION"
..                     hit_count="HIT_COUNT">
..             <expression>EXPRESSION</expression>
..         </breakpoint>
..     </response>
.. 
.. where each breakpoint attribute is only required if its value is relevant.
.. E.g., the <expression/> child element need only be included if there is an
.. expression defined, the *function* attribute need only be included if this is
.. a *function* breakpoint.
.. 
.. 
.. 7.6.3 breakpoint_update
.. ^^^^^^^^^^^^^^^^^^^^^^^
.. 
.. This command is used by the IDE to update one or more attributes of a
.. breakpoint that was already set on the debugger engine via *breakpoint_set*.
.. 
.. IDE to debugger engine::
.. 
..     breakpoint_update -i TRANSACTION_ID -d BREAKPOINT_ID [<arguments...>]
.. 
.. where the arguments are as follows.  All arguments are optional, however
.. at least one argument should be present.  See breakpoint_set_ for a description of
.. each argument:
.. 
..     ==  ===============  
..     -s  STATE
..     -n  LINENO
..     -h  HIT_VALUE
..     -o  HIT_CONDITION
..     ==  ===============  
.. 
.. debugger engine to IDE::
.. 
..     <response command="breakpoint_update"
..               transaction_id="TRANSACTION_ID"/>
.. 
.. 
.. 7.6.4 breakpoint_remove
.. ^^^^^^^^^^^^^^^^^^^^^^^
.. 
.. This command is used by the IDE to remove the given breakpoint.
.. 
.. IDE to debugger engine::
.. 
..     breakpoint_remove -i TRANSACTION_ID -d BREAKPOINT_ID
.. 
.. debugger engine to IDE::
.. 
..     <response command="breakpoint_remove"
..               transaction_id="TRANSACTION_ID"/>
.. 
.. 
.. 7.6.5 breakpoint_list
.. ^^^^^^^^^^^^^^^^^^^^^
.. 
.. This command is used by the IDE to get breakpoint information for all
.. breakpoints that the debugger engine has.
.. 
.. IDE to debugger engine::
.. 
..     breakpoint_list -i TRANSACTION_ID
.. 
.. debugger engine to IDE::
.. 
..     <response command="breakpoint_list"
..               transaction_id="TRANSACTION_ID">
..         <breakpoint id="BREAKPOINT_ID"
..                     type="TYPE"
..                     state="STATE"
..                     filename="FILENAME"
..                     lineno="LINENO"
..                     function="FUNCTION"
..                     exception="EXCEPTION"
..                     hit_value="HIT_VALUE"
..                     hit_condition="HIT_CONDITION"
..                     hit_count="HIT_COUNT">
..             <expression>EXPRESSION</expression>
..         </breakpoint>
..         <breakpoint ...>...</breakpoint>
..         ...
..     </response>
.. 
.. 
.. 
.. 7.7 stack_depth
.. ---------------
.. 
.. debug client ::
.. 
..     stack-depth -i transaction_id
.. 
.. debugger engine ::
.. 
..     <response command="stack_depth"
..               depth="{NUM}"
..               transaction_id="transaction_id"/>
.. 
.. 
.. 7.8 stack_get
.. -------------
.. 
.. Returns stack information for a given stack depth.  For extended
.. debuggers, multiple file/line's may be returned by having
.. child elements of the stack element.  This is to allow
.. for debuggers, such as XSLT, that have execution and data files.
.. The filename returned should always be the local file
.. system path translated into a file URI, and should include the
.. system name if the engine is not connecting to an ip on the local
.. box: file://systemname/c|/path.  If the stack depth is
.. specified, only one stack element is returned, for the depth
.. requested, though child elements may be returned also.  The
.. current context is stack depth of zero, the 'oldest' context
.. (in some languages known as 'main') is the highest numbered
.. context. 
.. 
..     ==      ==========================================
..     -d      stack depth (optional)
..     ==      ==========================================
.. 
.. debug client ::
.. 
..     stack_get -d {NUM} -i transaction_id
.. 
.. debugger engine ::
.. 
..     <response command="stack_get"
..               transaction_id="transaction_id">
..         <stack level="{NUM}"
..                type="file|eval|?"
..                filename="..."
..                lineno="{NUM}"
..                where=""
..                cmdbegin="line_number:offset"
..                cmdend="line_number:offset"/>
..         <stack level="{NUM}"
..                type="file|eval|?"
..                filename="..."
..                lineno="{NUM}">
..             <input level="{NUM}"
..                    type="file|eval|?"
..                    filename="..."
..                    lineno="{NUM}"/>
..         </stack>
..     </response>
.. 
.. Attributes for the stack element can include:
..     
..     =========   ========================================================
..     Attribute   Description
..     =========   ========================================================
..     level       stack depth for this stack element
..     type        the type of stack frame.  Valid values are file or eval.
..     filename    file URI
..     lineno      1-based line offset into the buffer
..     where       current command name (optional)
..     cmdbegin    line number and text offset from beginning of line
..                 for the current instruction (optional)
..     cmdend      same as cmdbegin, denotes end of current instruction
..     =========   ========================================================
.. 
.. The attributes where, cmdbegin and cmdlength are primarily used
.. for relaying visual information in the IDE.  cmdbegin and cmdend
.. can be used by the IDE for high lighting the command that is
.. currently being debugged.  The where attribute contains the name
.. of the current stack.  This could be the current function name
.. that the user is stepping through.
.. 
.. 
.. 
.. 7.11 Properties, variables and values
.. -------------------------------------
.. 
.. Properties that have children may return an arbitrary depth of
.. children, as defaulted by the debugger engine.  A maximum depth
.. may be defined by the IDE using the feature_set command with the
.. max_depth argument.  The IDE may then use the fullname attribute of
.. a property to dig further into the tree.  Data types are defined
.. further in section 7.12 below.
.. 
.. The number of children sent is defined by the debugger engine
.. unless otherwise defined by sending the feature_set command with
.. the max_children argument. ::
.. 
..     <property
..         name="short_name"
..         fullname="long_name"
..         type="data_type"
..         classname="name_of_object_class"
..         constant="0|1"
..         children="0|1"
..         size="{NUM}"
..         page="{NUM}"
..         pagesize="{NUM}"
..         address="{NUM}"
..         key="language_dependent_key"
..         encoding="base64|none"
..         numchildren="{NUM}">
..     ...encoded Value Data...
..     </property>
.. 
.. Attributes in the property element can include:
..     
..     =============== ========================================================
..     Attribute       Description
..     =============== ========================================================
..     name            variable name.  This is the short part of the
..                     name.  For instance, in PHP:
..                     $v = 0; // short name 'v'
..                     class:$v; // short name 'v'
..     fullname        variable name.  This is the long form of the name
..                     which can be eval'd by the language to retrieve
..                     the value of the variable.
..                     $v = 0; // long name 'v'
..                     class::$v; // short name 'v', long 'class::$v'
..                     $this->v; // short name 'v', long '$this->v'
..     classname       If the type is an object or resource, then the
..                     debugger engine MAY specify the class name
..                     This is an optional attribute.
..     page            if not all the children in the first level are
..                     returned, then the page attribute, in combination
..                     with the pagesize attribute will define where in
..                     the array or object these children should be
..                     located.
..     pagesize        the size of each page of data, defaulted by the
..                     debugger engine, or negotiated with feature_set
..                     and max_children
..     type            language specific data type name
..     facet           provides a hint to the IDE about additional
..                     facets of this value.  These are space separated
..                     names, such as private, protected, public,
..                     constant, etc.
..     size            size of property data in bytes
..     children        true/false whether the property has children
..                     this would be true for objects or array's.
..     numchildren     optional attribute with number of children for
..                     the property.
..     key             language dependent reference for the property.
..                     if the key is available, the IDE SHOULD use it
..                     to retrieve further data for the property
..     address         containing physical memory address
..     encoding        if this is binary data, it should be base64 encoded
..                     with this attribute set
..     =============== ========================================================
.. 
.. 
.. 7.12 Data Types
.. ---------------
.. 
.. Languages may have different names or meanings for data types,
.. however the IDE may want to be able to handle similar data types
.. as the same type.  For this reason, we define a minimal set of
.. standard data types, and a method for specifying more explicit
.. facets on those types.  We provide three different type attributes,
.. and a command to map those types to each other.  The schema type
.. serves as a hint to the IDE as to how to handle this specific data
.. type, if it so chooses to, but should not be considered to be
.. generally supported.  If the debugger engine chooses to support
.. Schema, it should handle all data validation itself.
.. 
.. language type:
..     A language specific name for a data type
.. common type:
..     A name used by the IDE to group data types
..     that are similar or the same
.. schema type:
..     The XML Schema data type name as specified
..     in the W3C Recommendation, XML Schema
..     Part 2: Datatypes located at
..     http://www.w3.org/TR/xmlschema-2/
..     The use of the schema type is completely
..     optional.  The language engine should not
..     expect an IDE to support usage of this
..     attribute.  The IDE identifies support for
..     this in the debugger engine by retrieving
..     the data map, which would contain the
..     schema type attribute.
.. 
.. 
.. 7.12.1 Common Data Types
.. ^^^^^^^^^^^^^^^^^^^^^^^^
.. 
.. This is a list of the common data types supported by this protocol.
.. For ease of documentation, and as hints to the IDE, they are mapped
.. to one or more schema data types, which are documented at
.. http://www.w3.org/TR/xmlschema-2/.  Some non-scalar types are also
.. defined, which do not have direct mappings to the base types defined
.. by XML Schema.
.. 
..     ===========     =======================================================
..     Common Type     Schema Type
..     ===========     =======================================================
..     bool            boolean (The value is always 0 or 1)
..     int             integer, long, short, byte, and signed or
..                     unsigned variants
..     float           float, double, decimal
..     string          string or other string-like data types, such as
..                     dateTime, hexBinary, etc.
..     ===========     =======================================================
.. 
.. Data types that do not map to schema:
.. 
.. null:
..     For example the "None" of Python or
..     the "null" of PHP.  Some languages may not have
..     a method to specify a null type.
.. array:
..     for non-associative arrays, such as
..     List in Python.  Arrays have integers as keys,
..     and the index is put in the name attribute of
..     the property element.
.. hash:
..     for associative arrays, such as Dictionaries
..     in Python.  The only supported key type is a
..     string, which would be in the name attribute of
..     the property.
.. object:
..     An instance of a class.
.. resource:
..     Any data type the language supports that does
..     not map into one of the common types.  This
..     could include pointers in C, various Python
..     types such as Method or Class types, or
..     file descriptors, database resources, etc. in
..     PHP.  Complex types may also be defined by
..     using XML Schema, and mapping a type to the
..     Schema type.  This is a more specialized use
..     of the type mapping, and should be considered
..     experimental, and not generally available in
..     implementations of this protocol.
.. 
.. For the most part, this protocol treats array's and hashes in the
.. same way, placing the key or index into the name attribute of the
.. property element.
.. 
.. 
.. 7.13 property_get, property_set, property_value
.. -----------------------------------------------
.. 
.. Gets/sets a property value.  When retrieving a property with the
.. get method, the maximum data that should be returned is a default
.. defined by the debugger engine unless it has been negotiated using
.. feature_set with max_data.  If the size of the properties data is
.. larger than that, the debugger engine only returns the configured
.. amount, and the IDE should call property_value to get the entire
.. data.  This is to prevent large data from slowing down debugger
.. sessions.  The IDE should implement UI that allows the user to
.. decide whether they want to retrieve all the data.  The IDE should
.. not read more data than the length defined in the packet header.
.. The IDE can determine if there is more data by using the property
.. data length information.  As per the context_get command, the depth
.. of nested elements returned is either defaulted by the debugger
.. engine, or negotiated using feature_set with max_children.
.. 
..     ==      ========================================================
..     -d      stack depth (optional, debugger engine should assume
..             zero if not provided)
..     -c      context id (optional, retrieved by context-names,
..             debugger engine should assume zero if not provided)
..     -n      property long name (required)
..     -m      max data size to retrieve (optional)
..     -t      data type (optional)
..     -p      data page (optional, for arrays, hashes, objects, etc.)
..     -k      property key as retrieved in a property element,
..             optional, used for property_get of children and
..             property_value, required if it was provided by the
..             debugger engine.
..     -a      property address as retrieved in a property element,
..             optional, used for property_set/value, required if it
..             was provided by the debugger engine.
..     ==      ========================================================
.. 
.. debug client ::
.. 
..     property_get -n property_long_name -d {NUM} -i transaction_id
.. 
.. debugger engine ::
.. 
..     <response command="property_get"
..               transaction_id="transaction_id">
..         <property ... />
..         ...
..     </response>
.. 
.. debug client ::
.. 
..     property_set -n property_long_name -d {NUM} -i transaction_id
..              -l data_length -- {DATA}
.. 
.. debugger engine ::
.. 
..     <response command="property_set"
..           success="0|1"
..           transaction_id="transaction_id"/>
.. 
.. debug client ::
.. 
..     property_value -n property_long_name -d {NUM} -i transaction_id
.. 
.. debugger engine ::
.. 
..     <response command="property_value"
..               size="{NUM}"
..               encoding="base64|none"
..               transaction_id="transaction_id">
..         ...data...
..     </response>
.. 
.. 
.. 7.14 source
.. -----------
.. 
.. The body of the request is the URI (retrieved from the stack info),
.. the body of the response is the data contents of the URI.  If the
.. file uri is not provided, then the file for the current context
.. is returned. 
.. 
..     ==      ========================================================
..     -b      begin line (optional)
..     -e      end line (optional)
..     -f      file URI
..     ==      ========================================================
.. 
.. debug client ::
.. 
..     source -i transaction_id -f fileURI
.. 
.. debugger engine ::
.. 
..     <response command="source"
..               success="0|1"
..               transaction_id="transaction_id">
..         ...data source code...
..     </response>
.. 
.. 
.. 
.. 8.3 eval
.. --------
.. 
.. Evaluate a given string within the current execution context.  A
.. property element MAY be returned as a child element of the
.. response, but the IDE MUST NOT expect one.  The string being evaluated
.. may be an expression or a code segment to be executed.  Languages, such
.. as Python, which have separate statements for these, will need to handle
.. both appropriately.  For implementations that need to be more explicit, use
.. the expr or exec commands below.
.. 
.. debug client ::
.. 
..     eval -i transaction_id -- {DATA}
.. 
.. debugger engine ::
.. 
..     <response command="eval"
..           success="0|1"
..           transaction_id="transaction_id">
..           <property .../>
..     </response>
.. 
.. 
.. 
.. 
.. A. ChangeLog
.. ============
.. 
.. 2004-05-12
.. 
.. - 7.2 reorganize the feature names, add a couple missing names
..       (supports_postmortem, show_hidden, notify_ok).
.. 
.. 2004-04-05
.. 
.. - 8.5 New notification support
.. - 8.6 New interact command
.. 
.. 2004-02-20
.. 
.. - 1.2 moved the change log to appendix A
.. - 5 massive reorganization of section 5
.. - 5.3 expanded description of proxies and just in time debugging.
.. - 5.4 expand description of multisession and multithreaded debugging.
.. - 7.2 A new feature name, breakpoint_languages, has been added.  This option
..   is only required if the engine supports more than one language.
.. - 7.2 and 7.3 Remove crufty documentation that still referred to old binary
..   protocol information.
.. - 7.6.1 For conditional breakpoints the expression has been moved to the data
..   section of the command.
.. - 8.3 remove the length argument in the eval command, it is unnecessary.
.. - 8.3 be more explicit about how eval works, add 8.3.1 expr and 8.3.2 exec as
..   additional optional commands that can be used in special implementations.
.. - 8.4 Remove the 'delete' state, this was old and removed in breakpoints.
.. 
.. 2004-01-28
.. 
.. - 7.8 Fix cmdbegin/end attributes for stack_get
.. 
.. 2004-01-09
.. 
.. - 5.1 New DBGP_IDEKEY environment variable
.. 
.. 2004-01-07
.. 
.. - 7.5 renamed the stop and kill commands to detach and stop, added
..   some clarification to the description of the commands.
.. 
.. 2003-12-16
.. 
.. - 7.6, 8.4 re-write the breakpoint and spawnpoint sections to be clearer
.. 
.. 2003-12-09
.. 
.. - 6.7 new section describing dbgp file protocol
.. - 7.6 better document breakpoints
.. 
.. 2003-12-05
.. 
.. - 6 Change the deliminator for command data to '--'.  This conforms to
..   standard getopt libraries.
.. - 7.11 remove the recursive attribute, if an IDE wants to handle
..   circular references, it can do so based on the address attribute if
..   the engine provides it.
.. 
.. 2003-12-02
.. 
.. - 7.6 remove breakpoint_enable/disable, and add breakpoint_update
..   command.  Enable/disable states are changed through breakpoint_update.
.. - 8.4 new (optional) spawnpoint commands
.. 
.. 2003-11-25
.. 
.. - 7.6 Change the breakpoint *hits* and *ignore* attributes to *hit_count*,
..   *hit_value* and *hit_condition* to add functionality available in VS.NET
..   and to simplify usage. Also clarify some other breakpoint attribute legal
..   values.
.. 
.. 2003-11-24
.. 
.. - 7.5 correct the stop command documentation, stop is 'detach', and
..   does not allow for continued interaction.  Document how expressions
..   are returned from breakpoint_get.
.. - 7.8 correct old documentation on the stack element.  Add new
..   attributes: where, cmdbegin, cmdlength.  Provide further documentation
..   about all the attributes.
.. 
.. 2003-11-20
.. 
.. - 5.1 better define session keys vs. ide key for proxy, document how
..   proxy works better.
.. - 7.6 better document attributes and hit option
.. 
.. 2003-11-18
.. 
.. - 7.1 Clarify stopping and stopped states
.. - 7.5 Clarify the stop command
.. - 7.6 Remove 'temporary' as a status for breakpoints, make it an option
..   in the command line.  Remove the 'function' breakpoint type, provide
..   two new types, 'call' and 'return'.  Add 'hits' option to allow a
..   breakpoint to be ignored a number of times before being used.
.. 
.. 2003-11-12
.. 
.. - draft 12
.. - Rest markup tweaks
.. 
.. 2003-11-09
.. 
.. - draft 11
.. - 7.12 new section inserted as 7.12.  This section specifies common
..   data types, and how to map more specific data types to the the common
..   types.
.. - 7.11 two new optional attributes, classname and facet, that provide
..   additional hints to the IDE about the nature of the property.  New
..   key attribute for language specific keys to properties.
.. - 6.5 new section, 6.5.1 for defining common error codes.
.. 
.. 2003-11-05
.. 
.. - spelling fixes
.. - 5.1 change proxy options
.. - 7.6 clarify breakpoint command options
.. - 7.12 fix old text about context names
.. 
.. 2003-10-15
.. 
.. - 6 remove the first NULL in the command structure from IDE to debugger
..   engine.  This makes dealing with those commands easier.
.. - 6.6 NEW File paths must be URI's.
.. - 7 source command returns the source for the current context if no
..   file uri is provided.
.. - 7 added sub-item numbering
.. - 7.1 clarify the status values
.. - 8 added sub-item numbering
.. 
.. 2003-10-09
.. 
.. - 7 remove run_to, unnecessary
.. - 7 remove 'step', there is no generic step command
.. - 7 clarify continuation commands
.. - 7 clarify breakpoints
.. 
.. 2003-10-07
.. 
.. - more layout changes for reStructuredText
.. 
.. 2003-10-06
.. 
.. - reformat to `reStructuredText markup
..   <http://docutils.sourceforge.net/spec/rst/reStructuredText.html>`_
.. - 6 clarify message packets
.. - 6.3 clarify command packets
.. - 7 clarify feature_get/set
.. - 7 allow error results on breakpoints if a type of breakpoint
..   is not supported by a debugger engine.
.. - 7 add recursive attribute to properties, and clarify the
..   address attribute and how recursive data is handled.
.. - 7,8 moved stdin to the optional commands section
.. 
.. 2003-10-02
.. 
.. - 5.1 changed proxy error to be the same as that in 6.5
.. - 5.1 the IDE and proxy ports have been defined to 9000/9001
.. - 5.3 exclude protocol overhead from data size definition
.. - 6.2 changed typo 'stdin and stdout' to 'stdout and stderr'
.. - 6.5 changed error id to error code
.. - 7 removed comments on 'body' from the run commands
.. - 7 clarified 'source' command arguments to be optional
.. - 7 added 'disable' option to stdin/out/err commands
.. - 7 breakpoint arguments and types have been better defined since
..   not all arguments need to be required for all types
.. - 7 the expression breakpoint type has been removed since it is
..   covered by the conditional breakpoint type
.. 
.. 
.. 2003-09-30
.. 
.. - section numbers added, changes below are marked with the section
..   number
.. - 3 Terminology changed (frontend -> IDE, backend -> debugger engine)
.. - 5.1 added response packet from proxy to IDE when IDE issues the
..   proxyinit command.
.. - 5.1 the proxy now adds a proxyclientid to the init packet from
..   the debugger engine when it passes the packet through to the IDE.
.. - 5.1 the proxy must be able to send errors to the IDE, for instance,
..   if it looses the connection to the debugger engine.
.. - 5.1 the proxy must be able to send errors to the Debugger, for
..   instance, if it looses the connection to the IDE.
.. - 5.3 added new section to help better define feature negotiation
..   with feature_get/set commands.
.. - 6 packets have been better defined.  This section has also been
..   reorganized.
.. - 6.2 the communication of packets has been rewritten.
.. - 7 feature_get/set have some modifications.
.. - 7 context_get and property_* commands have been modified to better
..   reflect negotiation of features using the feature_get/set commands.
.. - 7 property_* commands have been commented a bit more, and an
..   additional argument is available for paging arrays, etc.
.. - 7 The definition of the property tag has been modified
.. - 7 stdin command has been modified, the debugger engine may choose
..   to not redirect stdin.
.. - 7 status command modified to support the async state
.. - 7 source command now accepts begin and end line arguments for
..   retrieving only parts of a file.
.. - 7 stack_get now defines an enumeration for the stack
.. - 8 break command clarified so it can only be sent while the debugger
..   engine is in a run state.
.. - 8 eval can return a property as part of the response
.. 
.. */
