diff options
| author | Tom Tromey <tromey@redhat.com> | 2009-05-28 01:05:14 +0000 |
|---|---|---|
| committer | Tom Tromey <tromey@redhat.com> | 2009-05-28 01:05:14 +0000 |
| commit | a6bac58e84001d33b9540e208e9ca6d6ab265bf3 (patch) | |
| tree | 6dc1ea1483f42b9b0995046c029dad43ad45e05c /gdb/doc | |
| parent | 42ae523077b469c09e83845d30ee137a844aacb8 (diff) | |
| download | gdb-a6bac58e84001d33b9540e208e9ca6d6ab265bf3.zip gdb-a6bac58e84001d33b9540e208e9ca6d6ab265bf3.tar.gz gdb-a6bac58e84001d33b9540e208e9ca6d6ab265bf3.tar.bz2 | |
gdb
2009-05-27 Tom Tromey <tromey@redhat.com>
Thiago Jung Bauermann <bauerman@br.ibm.com>
Phil Muldoon <pmuldoon@redhat.com>
Paul Pluzhnikov <ppluzhnikov@google.com>
Vladimir Prus <vladimir@codesourcery.com>
* python/python-value.c (value_object_to_value): New function.
* python/python-internal.h: Include frameobject.h.
(gdbpy_children_cst, gdbpy_to_string_cst, gdbpy_display_hint_cst):
Declare.
(value_object_to_value): Declare.
* printcmd.c (struct format_data) <raw>: New field.
(last_format): Default to 0.
(decode_format): Initialize val.raw. Handle /r flag.
(print_command_1): Initialize fmt.raw and opts.raw.
(output_command): Likewise.
(x_command): Fix initialization of fmt.format. Initialize
fmt.raw.
(display_command): Initialize fmt.raw.
(do_one_display): Set opts.raw.
* python/python.c (gdbpy_to_string_cst, gdbpy_children_cst,
gdbpy_display_hint_cst): New globals.
(_initialize_python): Initialize them. Set gdb.pretty_printers.
* cp-valprint.c: Include python.h.
(cp_print_value): Call apply_val_pretty_printer.
* python/python.h (apply_val_pretty_printer): Declare.
* stack.c (print_this_frame_argument_p): Remove.
(print_frame_args): Compute summary flag. Don't use
print_this_frame_argument_p.
* valprint.c: Include python.h.
(user_print_options): Initialize new fields.
(scalar_type_p): New function.
(val_print): Handle 'raw' and 'summary' modes. Call
apply_val_pretty_printer.
(value_print): Handle 'raw' mode.
* valprint.h (struct value_print_options) <raw, summary>: New
fields.
* Makefile.in (SUBDIR_PYTHON_OBS): Add python-prettyprint.o
(SUBDIR_PYTHON_SRCS): Add python-prettyprint.c.
(python-prettyprint.o): New target.
* python/python-prettyprint.c: New file.
gdb/doc
2009-05-27 Tom Tromey <tromey@redhat.com>
Thiago Jung Bauermann <bauerman@br.ibm.com>
Phil Muldoon <pmuldoon@redhat.com>
* gdb.texinfo (Objfiles In Python): Reference pretty printing.
(Pretty Printing): New node.
(Selecting Pretty-Printers): Likewise.
(Python API): Update.
(Output Formats): Document /r format.
gdb/testsuite
2009-05-27 Tom Tromey <tromey@redhat.com>
Thiago Jung Bauermann <bauerman@br.ibm.com>
Phil Muldoon <pmuldoon@redhat.com>
Paul Pluzhnikov <ppluzhnikov@google.com>
* gdb.python/python-prettyprint.exp: New file.
* gdb.python/python-prettyprint.c: New file.
* gdb.python/python-prettyprint.py: New file.
* gdb.base/display.exp: print/r is now valid.
Diffstat (limited to 'gdb/doc')
| -rw-r--r-- | gdb/doc/ChangeLog | 10 | ||||
| -rw-r--r-- | gdb/doc/gdb.texinfo | 222 |
2 files changed, 231 insertions, 1 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 1677900..2e28f37 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,13 @@ +2009-05-27 Tom Tromey <tromey@redhat.com> + Thiago Jung Bauermann <bauerman@br.ibm.com> + Phil Muldoon <pmuldoon@redhat.com> + + * gdb.texinfo (Objfiles In Python): Reference pretty printing. + (Pretty Printing): New node. + (Selecting Pretty-Printers): Likewise. + (Python API): Update. + (Output Formats): Document /r format. + 2009-05-27 Thiago Jung Bauermann <bauerman@br.ibm.com> Tom Tromey <tromey@redhat.com> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 5fccb30..45e580c 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -6774,6 +6774,12 @@ Without this format, @value{GDBN} displays pointers to and arrays of @code{char}, @w{@code{unsigned char}}, and @w{@code{signed char}} as strings. Single-byte members of a vector are displayed as an integer array. + +@item r +@cindex raw printing +Print using the @samp{raw} formatting. By default, @value{GDBN} will +use a type-specific pretty-printer. The @samp{r} format bypasses any +pretty-printer which might exist for the value's type. @end table For example, to print the program counter in hex (@pxref{Registers}), type @@ -18517,6 +18523,8 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown. * Auto-loading:: Automatically loading Python code. * Values From Inferior:: * Types In Python:: Python representation of types. +* Pretty Printing:: Pretty-printing values. +* Selecting Pretty-Printers:: How GDB chooses a pretty-printer. * Commands In Python:: Implementing new commands in Python. * Functions In Python:: Writing new convenience functions. * Objfiles In Python:: Object files. @@ -19044,6 +19052,217 @@ A function internal to @value{GDBN}. This is the type used to represent convenience functions. @end table +@node Pretty Printing +@subsubsection Pretty Printing + +@value{GDBN} 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@t{++} @code{std::string} looks without a +pretty-printer: + +@smallexample +(@value{GDBP}) 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" + @} +@} +@end smallexample + +After a pretty-printer for @code{std::string} has been installed, only +the contents are printed: + +@smallexample +(@value{GDBP}) print s +$2 = "abcd" +@end smallexample + +A pretty-printer is just an object that holds a value and implements a +specific interface, defined here. + +@defop Operation {pretty printer} children (self) +@value{GDBN} 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 @value{GDBN} value. + +This method is optional. If it does not exist, @value{GDBN} will act +as though the value has no children. +@end defop + +@defop Operation {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 @samp{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 @value{GDBN}: + +@table @samp +@item array +Indicate that the object being printed is ``array-like''. The CLI +uses this to respect parameters such as @code{set print elements} and +@code{set print array}. + +@item 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. + +@item string +Indicate that the object being printed is ``string-like''. If the +printer's @code{to_string} method returns a Python string of some +kind, then @value{GDBN} 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 +@code{set print elements}, and the like. +@end table +@end defop + +@defop Operation {pretty printer} to_string (self) +@value{GDBN} 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 @code{to_string} method exists, +then @value{GDBN} will prepend its result to the values returned by +@code{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 (@pxref{Print Settings}), the CLI may +print just the result of @code{to_string} in a stack trace, omitting +the result of @code{children}. + +If this method returns a string, it is printed verbatim. + +Otherwise, if this method returns an instance of @code{gdb.Value}, +then @value{GDBN} 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 +@code{gdb.Value}, then @value{GDBN} 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 @code{gdb.Value}; other types are not. + +If the result is not one of these types, an exception is raised. +@end defop + +@node Selecting Pretty-Printers +@subsubsection Selecting Pretty-Printers + +The Python list @code{gdb.pretty_printers} contains an array of +functions that have been registered via addition as a pretty-printer. +Each @code{gdb.Objfile} also contains a @code{pretty_printers} +attribute. + +A function on one of these lists is passed a single @code{gdb.Value} +argument and should return a pretty-printer object conforming to the +interface definition above (@pxref{Pretty Printing}). If a function +cannot create a pretty-printer for the value, it should return +@code{None}. + +@value{GDBN} first checks the @code{pretty_printers} attribute of each +@code{gdb.Objfile} and iteratively calls each function in the list for +that @code{gdb.Objfile} until it receives a pretty-printer object. +After these lists have been exhausted, it tries the global +@code{gdb.pretty-printers} list, again calling each function until an +object is returned. + +The order in which the objfiles are searched is not specified. For a +given list, functions are always invoked from the head of the list, +and iterated over sequentially until the end of the list, or a printer +object is returned. + +Here is an example showing how a @code{std::string} printer might be +written: + +@smallexample +class StdStringPrinter: + "Print a std::string" + + def __init__ (self, val): + self.val = val + + def to_string (self): + return self.val['_M_dataplus']['_M_p'] + + def display_hint (self): + return 'string' +@end smallexample + +And here is an example showing how a lookup function for the printer +example above might be written. + +@smallexample +def str_lookup_function (val): + + lookup_tag = val.type.tag + regex = re.compile ("^std::basic_string<char,.*>$") + if lookup_tag == None: + return None + if regex.match (lookup_tag): + return StdStringPrinter (val) + + return None +@end smallexample + +The example lookup function extracts the value's type, and attempts to +match it to a type that it can pretty-print. If it is a type the +printer can pretty-print, it will return a printer object. If not, it +returns @code{None}. + +We recommend that you put your core pretty-printers into a Python +package. If your pretty-printers are for use with a library, we +further recommend embedding a version number into the package name. +This practice will enable @value{GDBN} to load multiple versions of +your pretty-printers at the same time, because they will have +different names. + +You should write auto-loaded code (@pxref{Auto-loading}) such that it +can be evaluated multiple times without changing its meaning. An +ideal auto-load file will consist solely of @code{import}s of your +printer modules, followed by a call to a register pretty-printers with +the current objfile. + +Taken as a whole, this approach will scale nicely to multiple +inferiors, each potentially using a different library version. +Embedding a version number in the Python package name will ensure that +@value{GDBN} is able to load both sets of printers simultaneously. +Then, because the search for pretty-printers is done by objfile, and +because your auto-loaded code took care to register your library's +printers with a specific objfile, @value{GDBN} will find the correct +printers for the specific version of the library used by each +inferior. + +To continue the @code{std::string} example (@pxref{Pretty Printing}), +this code might appear in @code{gdb.libstdcxx.v6}: + +@smallexample +def register_printers (objfile): + objfile.pretty_printers.add (str_lookup_function) +@end smallexample + +@noindent +And then the corresponding contents of the auto-load file would be: + +@smallexample +import gdb.libstdcxx.v6 +gdb.libstdcxx.v6.register_printers (gdb.current_objfile ()) +@end smallexample + @node Commands In Python @subsubsection Commands In Python @@ -19396,7 +19615,8 @@ The @code{pretty_printers} attribute is a list of functions. It is used to look up pretty-printers. A @code{Value} is passed to each function in order; if the function returns @code{None}, then the search continues. Otherwise, the return value should be an object -which is used to format the value. +which is used to format the value. @xref{Pretty Printing}, for more +information. @end defivar @node Frames In Python |