Next: Selecting Pretty-Printers, Previous: Types In Python, Up: Python API

##### 23.2.2.6 Pretty Printing

gdb provides a mechanism to allow pretty-printing of values using Python code. The pretty-printer API allows application-specific code to greatly simplify the display of complex objects. This mechanism works for both MI and the CLI.

For example, here is how a C`++` `std::string` looks without a pretty-printer:

         (gdb) print s
         $1 = {
           static npos = 4294967295,
           _M_dataplus = {
             <std::allocator<char>> = {
               <__gnu_cxx::new_allocator<char>> = {<No data fields>}, <No data fields>},
             members of std::basic_string<char, std::char_traits<char>, std::allocator<char> >::_Alloc_hider:
             _M_p = 0x804a014 "abcd"
           }
         }

After a pretty-printer for `std::string` has been installed, only the contents are printed:

         (gdb) print s
         $2 = "abcd"

A pretty-printer is just an object that holds a value and implements a specific interface, defined here.

— Operation on pretty printer: children (self)

> 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.

— Operation on pretty printer: display_hint (self)

> 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.

> Some display hints are predefined by gdb:

> ``array`'
>   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`.
> ``map`'
>   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.
> ``string`'
>   Indicate that the object being printed is “string-like”. If the printer's `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.

— Operation on pretty printer: to_string (self)

> 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 `children`.

> If this method returns a string, it is printed verbatim.

> Otherwise, if this method returns an instance of `gdb.Value`, then gdb prints this value. This may result in a call to another pretty-printer.

> 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.

> If the result is not one of these types, an exception is raised.