A pretty-printer is just an object that holds a value and implements a specific interface, defined here. An example output is provided (see Pretty Printing).
GDB will call this method on a pretty-printer to compute the children of the pretty-printer’s value.
This method must return an object conforming to the Python iterator protocol. Each item returned by the iterator must be a tuple holding two elements. The first element is the “name” of the child; the second element is the child’s value. The value can be any Python object which is convertible to a GDB value.
This method is optional. If it does not exist, GDB will act as though the value has no children.
For efficiency, the
children method should lazily compute its
results. This will let GDB read as few elements as
necessary, for example when various print settings (see Print Settings) or
-var-list-children (see GDB/MI Variable Objects) limit the number of elements to be displayed.
Children may be hidden from display based on the value of ‘set print max-depth’ (see Print Settings).
The CLI may call this method and use its result to change the formatting of a value. The result will also be supplied to an MI consumer as a ‘displayhint’ attribute of the variable being printed.
This method is optional. If it does exist, this method must return a
string or the special value
Some display hints are predefined by GDB:
Indicate that the object being printed is “array-like”. The CLI
uses this to respect parameters such as
set print elements and
set print array.
Indicate that the object being printed is “map-like”, and that the children of this value can be assumed to alternate between keys and values.
Indicate that the object being printed is “string-like”. If the
to_string method returns a Python string of some
kind, then GDB will call its internal language-specific
string-printing function to format the string. For the CLI this means
adding quotation marks, possibly escaping some characters, respecting
set print elements, and the like.
The special value
None causes GDB to apply the default
GDB will call this method to display the string representation of the value passed to the object’s constructor.
When printing from the CLI, if the
to_string method exists,
then GDB will prepend its result to the values returned by
children. Exactly how this formatting is done is dependent on
the display hint, and may change as more hints are added. Also,
depending on the print settings (see Print Settings), the CLI may
print just the result of
to_string in a stack trace, omitting
the result of
If this method returns a string, it is printed verbatim.
Otherwise, if this method returns an instance of
then GDB prints this value. This may result in a call to
If instead the method returns a Python value which is convertible to a
gdb.Value, then GDB performs the conversion and prints
the resulting value. Again, this may result in a call to another
pretty-printer. Python scalars (integers, floats, and booleans) and
strings are convertible to
gdb.Value; other types are not.
Finally, if this method returns
None then no further operations
are peformed in this method and nothing is printed.
If the result is not one of these types, an exception is raised.
GDB provides a function which can be used to look up the
default pretty-printer for a
This function takes a
gdb.Value object as an argument. If a
pretty-printer for this value exists, then it is returned. If no such
printer exists, then this returns