[Top] [Contents] [Index] [ ? ]

ruby-debug-ide protocol

This file contains specification of the protocol used by ruby-debug-ide.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Summary

This document describes protocol used by ruby-debug-ide for communication between debugger engine and a frontend. It is a work in progress and might, and very likely will, change in the future. If you have any comments or questions please send me an email.

The communication has two parts/sides. First ones are commands sent from a frontend to the debugger engine and the second is the opposite way, answers and events sent from the debugger engine to the frontend.

commands are almost the same as the ones used by CLI ruby-debug. So you might want to contact the ruby-debug-ide document.

answers and events are sent in XML format described in the specification below.

Specification is far from complete. Will be completed as time permits. In the meantime, source code is always the best spec.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. Specification

Terms:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1 Commands


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.1 Adding Breakpoint

Command:

 
  break <script>:<line_no>

Answer:

 
  <breakpointAdded no="<id>" location="<script>:<line_no>"/>

Example:

 
  C: break test.rb:2
  A: <breakpointAdded no="1" location="test.rb:2"/>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.2 Deleting Breakpoint

Command:

 
  delete <breakpoint_id>

Answer:

 
  <breakpointDeleted no="<id>"/>

Example:

 
  C: delete 2
  A: <breakpointDeleted no="2"/>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.3 Enabling Breakpoint

Supported since ruby-debug-ide 0.2.0

Command:

 
  enable <breakpoint_id>

Answer:

 
  <breakpointEnabled bp_id="<id>"/>

Example:

 
  C: enable 2
  A: <breakpointEnabled bp_id="2"/>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.4 Disabling Breakpoint

Supported since ruby-debug-ide 0.2.0

Command:

 
  disable <breakpoint_id>

Answer:

 
  <breakpointDisabled bp_id="<id>"/>

Example:

 
  C: disable 2
  A: <breakpointDisabled bp_id="2"/>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.5 Setting Condition on Breakpoint

Supported since ruby-debug-ide 0.2.0

Command:

 
  condition <script>:<line_no>

Answer:

 
  <conditionSet bp_id="<id>"/>

Example:

 
  C: condition 1 x>5   # Stop on breakpoint 1 only if x>5 is true.
  A: <conditionSet bp_id="1"/>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.6 Exception Breakpoint

Command:

 
  catch <exception_class_name>

Answer:

 
  <catchpointSet exception="<exception_class_name>"/>

Example:

 
  C: catch ZeroDivisionError
  A: <catchpointSet exception="ZeroDivisionError"/>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.7 Threads Listing

Command:

 
  thread list

Answer:

 
  <threads>
    <thread id="<id>" status="<status>"/>
    ....
  </threads>

Example:

 
  C: thread list
  A: <threads>
       <thread id="1" status="run"/>
       <thread id="2" status="sleep"/>
     </threads>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.8 Frames Listing

Command:

 
  where

Answer:

 
  <frames>
    <frame no="<frame_no>" file="<script>" line="<line_no>" current="<boolean>"/>
    <frame no="<frame_no>" file="<script>" line="<line_no>"/>
    ...
  </frames>

Example:

 
  C: where
  A: <frames>
       <frame no="1" file="/path/to/test2.rb" line="3" current="true" />
       <frame no="2" file="/path/to/test.rb" line="3" />
     </frames>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.9 Variables Listing


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.9.1 Local Variables

Example:

 
  C: var local
  A: <variables>
       <variable name="array" kind="local" value="Array (2 element(s))" type="Array" hasChildren="true" objectId="-0x2418a904"/>
     </variables>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.9.2 Instance Variables

Example:

 
  C: var instance some_array
  A: <variables>
       <variable name="[0]" kind="instance" value="1" type="Fixnum" hasChildren="false" objectId="+0x3"/>
       <variable name="[1]" kind="instance" value="2" type="Fixnum" hasChildren="false" objectId="+0x5"/>
     </variables>
 
  C: var instance some_object
  A: <variables>
       <variable name="@y" kind="instance" value="5" type="Fixnum" hasChildren="false" objectId="+0xb"/>
     </variables>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2 Events


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2.1 Breakpoint

Event example:

 
  <breakpoint file="test.rb" line="1" threadId="1"/>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2.2 Suspension

Event example:

 
  <suspended file="/path/to/test.rb" line="2" threadId="1" frames="1"/>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2.3 Exception

Event example:

 
  <exception file="/path/to/test.rb" line="2" type="ZeroDivisionError" message="divided by 0" threadId="1"/>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2.4 Message

Event example:

 
  <message>some text</message>
  <message debug='true'>some debug text</message>

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. Changes

Mentions also related changes in the ruby-debug-ide gem implementation.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1 Changes between 0.4.5 and 0.4.6


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 Changes between 0.4.4 and 0.4.5


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3 Changes between 0.4.3 and 0.4.4


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4 Changes between 0.4.2 and 0.4.3


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.5 Changes between 0.4.1 and 0.4.2


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.6 Changes between 0.4.0 and 0.4.1


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.7 Changes between 0.3.1 and 0.4.0


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.8 Changes between 0.3.4 and 0.3.5


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.9 Changes between 0.3.3 and 0.3.4


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.10 Changes between 0.3.2 and 0.3.3


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.11 Changes between 0.3.1 and 0.3.2


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.12 Changes between 0.3.0 and 0.3.1


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.13 Changes between 0.2.1 and 0.3.0


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.14 Changes between 0.2.0 and 0.2.1


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.15 Changes between 0.1.10 and 0.2.0


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.15.1 New Features


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.15.2 Uncompatible Changes


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated by emdot on May, 21 2009 using texi2html 1.78.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back Previous section in reading order 1.2.2
[ > ] Forward Next section in reading order 1.2.4
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ Up ] Up Up section 1.2
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated by emdot on May, 21 2009 using texi2html 1.78.