Using Debugging Helpers

Dumper Class

For each line in the Locals and Expressions view, a string like the following needs to be created and channeled to the debugger plugin.

 "{iname='some internal name',
   addr='object address in memory',
   name='contents of the name column',
   value='contents of the value column',
   type='contents of the type column',
   numchild='number of children',        // zero/nonzero is sufficient
   childtype='default type of children', // optional
   childnumchild='default number of grandchildren', // optional
   children=[              // only needed if item is expanded in view
      {iname='internal name of first child',
       ... },
      {iname='internal name of second child',
       ... },
      ...
   ]}"

While in theory, you can build up the entire string above manually, it is easier to employ the Dumper Python class for that purpose. The Dumper Python class contains a complete framework to take care of the iname and addr fields, to handle children of simple types, references, pointers, enums, known and unknown structs as well as some convenience methods to handle common situations.

The Dumper members are the following:

• __init__(self) - Initializes the output to an empty string and empties the child stack.
• put(self, value) - Low level method to directly append to the output string.
• putCommaIfNeeded(self) - Appends a comma if the current output ends in '}', '"' or ']' .
• putField(self, name, value) - Appends a comma if needed, and a name='value' field.
• beginItem(self, name) - Starts writing a field by writing name='.
• endItem(self) - Ends writing a field by writing '.
• endChildren(self) - Ends writing a list of children.
• childRange(self) - Returns the range of children specified in the current Children scope.
• putItemCount(self, count) - Appends a field value='<%d items' to the output.
• putEllipsis(self) - Appends fields '{name="<incomplete>",value="",type="",numchild="0"}'. This is automatically done by endChildren if the number of children to print is smaller than the number of actual children.
• putName(self, name) - Appends a name='...' field.
• putType(self, type) - Appends a field type='...' unless the type coincides with the parent's default child type.
• putNumChild(self, numchild) - Appends a field numchild='...' unless the numchild coincides with the parent's default child numchild value.
• putValue(self, value, encoding = None) - Append a file value='...', optionally followed by a field valueencoding='...'. The value needs to be convertible to a string entirely consisting of alphanumerical values. The encoding parameter can be used to specify the encoding in case the real value had to be encoded in some way to meet the alphanumerical-only requirement. Currently the following encodings are supported:
  • 0: unencoded 8 bit data, interpreted as Latin1.
  • 1: base64 encoded 8 bit data, used for QByteArray, double quotes are added.
  • 2: base64 encoded 16 bit data, used for QString, double quotes are added.
  • 3: base64 encoded 32 bit data, double quotes are added.
  • 4: base64 encoded 16 bit data, without quotes (see 2)
  • 5: base64 encoded 8 bit data, without quotes (see 1)
  • 6: %02x encoded 8 bit data (as with QByteArray::toHex), double quotes are added.
  • 7: %04x encoded 16 bit data (as with QByteArray::toHex), double quotes are added.
• putStringValue(self, value) - Encodes a QString and calls putValue with the correct encoding setting.
• putByteArrayValue(self, value) - Encodes a QByteArray and calls putValue with the correct encoding setting.
• isExpanded(self, item) - Checks whether the item with the internal name item.iname is expanded in the view.
• isExpandedIName(self, iname) - Checks whether the item with the internal name iname is expanded in the view.
• putIntItem(self, name, value) - Equivalent to:

       self.beginHash()
       self.putName(name)
       self.putValue(value)
       self.putType("int")
       self.putNumChild(0)
       self.endHash()

• putBoolItem(self, name, value) - Equivalent to:

       self.beginHash()
       self.putName(name)
       self.putValue(value)
       self.putType("bool")
       self.putNumChild(0)
       self.endHash()

• pushOutput(self) - Moves the output string to a safe location from with it is sent to the debugger plugin even if further operations raise an exception.
• putCallItem(self, name, item, func) - Uses GDB to call the function func on the value specified by item.value and output the resulting item. This function is not available when debugging core dumps and it is not available on the Symbian platform due to restrictions imposed by the on-device debugging agent.
• putItem(self, item) - The "master function", handling basic types, references, pointers and enums directly, iterates over base classes and class members of compound types and calls qdump__* functions whenever appropriate.
• putSubItem(self, item) - Equivalent to:

       with SubItem(self):
           self.putItem(item)

  Exceptions raised by nested function calls are caught and all output produced by putItem is replaced by the output of:

           ...
       except RuntimeError:
           d.put('value="<invalid>",type="<unknown>",numchild="0",')

 d.putNumChild(2)
 if d.isExpanded(item):
     with Children(d):
         with SubItem(d):
             d.putName("key")
             d.putItem(Item(key, item.iname, "key"))
         with SubItem(d):
             d.putName("value")
             d.putItem(Item(value, item.iname, "value"))