feedc0de/qt-creator
1
0
Fork 0
forked from qt-creator/qt-creator
Code Pull Requests Activity

debugger: update python dumper docs

Browse Source 
Change-Id: I9c7f701d6cbe8eb90278d764f3ba944e5c875101
Reviewed-on: http://codereview.qt.nokia.com/3267
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@nokia.com>
This commit is contained in:
hjk
2011-08-19 13:57:58 +02:00
committed by Leena Miettinen
parent 6235ec5120
commit 0614e07dff
1 changed files with 80 additions and 91 deletions
Download Patch File Download Diff File Expand all files Collapse all files

171
doc/qtcreator.qdoc
View File

@@ -9029,7 +9029,7 @@
parameters:
\list
\o \c d of type \c Dumper
\o \c item of type \c Item
\o \c value of type \c gdb.Value
\endlist
The function has to feed the Dumper object with certain information
@@ -9040,48 +9040,30 @@
Example:
\code
def qdump__QVector(d, item):
d_ptr = item.value["d"]
p_ptr = item.value["p"]
def qdump__QVector(d, value):
d_ptr = value["d"]
p_ptr = value["p"]
alloc = d_ptr["alloc"]
size = d_ptr["size"]
check(0 <= size and size <= alloc and alloc <= 1000 * 1000 * 1000)
check(d_ptr["ref"]["_q_value"] > 0)
checkRef(d_ptr["ref"])
innerType = item.value.type.template_argument(0)
innerType = templateArgument(value.type, 0)
d.putItemCount(size)
d.putNumChild(size)
if d.isExpanded(item):
if d.isExpanded():
p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
with Children(d, [size, 2000], innerType)
charPtr = lookupType("char").pointer()
d.putField("size", size)
with Children(d, size, maxNumChild=2000, childType=innerType, addrBase=p,
addrStep=(p+1).cast(charPtr) - p.cast(charPtr)):
for i in d.childRange():
d.putSubItem(Item(p.dereference(), item.iname, i))
d.putSubItem(i, p.dereference())
p += 1
\endcode
\section2 Item Class
The Item Python class is a thin wrapper around values corresponding to one
line in the \gui{Locals and Expressions} view. The Item members are as follows :
\list
\o \gui{__init__(self, value, parentiname, iname, name = None)} - A
constructor. The object's internal name is created by concatenating
\c parentiname and \c iname. If \c None is passed as \c name, a
serial number is used.
\o \gui{value} - An object of type gdb.Value representing the value to
be displayed.
\o \gui{iname} - The internal name of the object, constituting a dot-separated
list of identifiers, corresponding to the position of the object's
representation in the view.
\o \gui{name} - An optional name. If given, is used in the
\gui{name} column of the view. If not, a simple number in brackets
is used instead.
\endlist
@@ -9091,15 +9073,15 @@
For each line in the \gui{Locals and Expressions} view, a string like the
following needs to be created and channeled to the debugger plugin.
\code
"{iname='some internal name',
addr='object address in memory',
name='contents of the name column',
"{iname='some internal name', # optional
addr='object address in memory', # optional
name='contents of the name column', # optional
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
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',
@@ -9108,6 +9090,16 @@
]}"
\endcode
The value of the \gui{iname} field is the internal name of the object,
constituting a dot-separated list of identifiers, corresponding to the
position of the object's representation in the view. If it is not
present, is it generated by concatenating the parent object's iname,
a dot, and a sequential number.
The value of the\gui{name} field is displayed in the \gui{name} column
of the view. If it is not specified, a simple number in brackets
is used instead.
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 \c iname and
@@ -9115,27 +9107,17 @@
enums, known and unknown structs as well as some convenience methods to
handle common situations.
The Dumper members are the following:
The member functions of the \gui{Dumper} class are the following:
\list
\o \gui{__init__(self)} - Initializes the output to an empty string and
empties the child stack.
empties the child stack. This should not be used in user code.
\o \gui{put(self, value)} - Low level method to directly append to the
output string.
output string. That is also the fastest way to append output.
\o \gui{putCommaIfNeeded(self)} - Appends a comma if the current output
ends in '}', '"' or ']' .
\o \gui{putField(self, name, value)} - Appends a comma if needed, and a
name='value' field.
\o \gui{beginItem(self, name)} - Starts writing a field by writing \c {name='}.
\o \gui{endItem(self)} - Ends writing a field by writing \c {'}.
\o \gui{endChildren(self)} - Ends writing a list of children.
\o \gui{putField(self, name, value)} - Appends a name='value' field.
\o \gui{childRange(self)} - Returns the range of children specified in
the current \c Children scope.
@@ -9150,8 +9132,12 @@
\o \gui{putName(self, name)} - Appends a \c {name='...'} field.
\o \gui{putType(self, type)} - Appends a field \c {type='...'} unless the
\a type coincides with the parent's default child type.
\o \gui{putType(self, type, priority=0)} - Appends a field \c {type='...'}
unless the \a type coincides with the parent's default child type or
\c putType was already called for the current item with a higher
value of \c priority.
\o \gui{putBetterType(self, type)} - Overrides the last recorded \c type.
\o \gui{putNumChild(self, numchild)} - Appends a field \c {numchild='...'}
unless the \c numchild coincides with the parent's default child numchild
@@ -9194,52 +9180,42 @@
\o \gui{putByteArrayValue(self, value)} - Encodes a QByteArray and calls
\c putValue with the correct \c encoding setting.
\o \gui{isExpanded(self, item)} - Checks whether the item with the
internal name \c item.iname is expanded in the view.
\o \gui{isExpanded()} - Checks whether the current item
is expanded in the view.
\o \gui{isExpandedIName(self, iname)} - Checks whether the item with the
internal name \c iname is expanded in the view.
\o \gui{putIntItem(self, name, value)} - Equivalent to:
\o \gui{putIntItem(self, name, value)} - Equivalent to:
\code
self.beginHash()
self.putName(name)
self.putValue(value)
self.putType("int")
self.putNumChild(0)
self.endHash()
with SubItem(self, name):
self.putValue(value)
self.putAddress(value.address)
self.putType("int")
self.putNumChild(0)
\endcode
\o \gui{putBoolItem(self, name, value)} - Equivalent to:
\o \gui{putBoolItem(self, name, value)} - Equivalent to:
\code
self.beginHash()
self.putName(name)
self.putValue(value)
self.putType("bool")
self.putNumChild(0)
self.endHash()
with SubItem(self, name):
self.putValue(value)
self.putType("bool")
self.putNumChild(0)
\endcode
\o \gui{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.
\o \gui{putCallItem(self, name, item, func)} -
\o \gui{putCallItem(self, name, value, func, *args)} -
Uses GDB to call the function \c func on the value specified by
\a {item.value} and output the resulting item. This function is
\a {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.
\o \gui{putItem(self, item)} - The "master function", handling
\o \gui{putItem(self, value)} - The "master function", handling
basic types, references, pointers and enums directly, iterates
over base classes and class members of compound types and calls
\c qdump__* functions whenever appropriate.
\o \gui{putSubItem(self, item)} - Equivalent to:
\o \gui{putSubItem(self, component, value)} - Equivalent to:
\code
with SubItem(self):
self.putItem(item)
with SubItem(self, component):
self.putItem(value)
\endcode
Exceptions raised by nested function calls are caught and all
output produced by \c putItem is replaced by the output of:
@@ -9259,28 +9235,41 @@
use \c Children and \c SubItem \e{Context Managers} to create the nested items.
The \c Children constructor \gui{__init__(self, dumper, numChild = 1,
childType = None, childNumChild = None)} uses one mandatory argument and three
childType = None, childNumChild = None, maxNumChild = None, addrBase = None,
addrStep = None)} uses one mandatory argument and several
optional arguments. The mandatory argument refers to the current \c Dumper
object. The optional arguments can be used to specify the number \c numChild
of children, with type \c childType_ and \c childNumChild_ grandchildren each.
If \c numChild_ is a list of two integers, the first one specifies the actual
number of children and the second the maximum number of children to print.
Similarly, using the \c SubItem class helps to protect individual items.
If \c maxNumChild is specified, only that many children are displayed.
This should be used when dumping container contents that might take
overly long otherwise. The parameters \c addrBase and \c addrStep
can be used to reduce the amount of data produced by the child dumpers.
Address printing for the \e{n}th child item will be suppressed if its address
equals with \e{addrBase + n * addrStep}.
Example:
\code
d.putNumChild(2)
if d.isExpanded(item):
d.putNumChild(2) # Annouce children to make the item expandable in the view.
if d.isExpanded():
with Children(d):
with SubItem(d):
d.putName("key")
d.putItem(Item(key, item.iname, "key"))
d.putItem(key)
with SubItem(d):
d.putName("value")
d.putItem(Item(value, item.iname, "value"))
d.putItem(value)
\endcode
Note that this can be written more conveniently as:
\code
d.putNumChild(2)
if d.isExpanded():
with Children(d):
d.putSubItem("key", key)
d.putSubItem("value", value)
\endcode
\section1 Debugging Helpers for QML
The debugging helpers for QML provide you with code completion for custom modules