From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 5949 invoked by alias); 17 Oct 2008 18:01:42 -0000 Mailing-List: contact archer-commits-help@sourceware.org; run by ezmlm Sender: Precedence: bulk List-Post: List-Help: List-Subscribe: Received: (qmail 5922 invoked by uid 306); 17 Oct 2008 18:01:41 -0000 Date: Fri, 17 Oct 2008 18:01:00 -0000 Message-ID: <20081017180141.5907.qmail@sourceware.org> From: tromey@sourceware.org To: archer-commits@sourceware.org Subject: [SCM] archer-tromey-python: * gdb.texinfo (Pretty Printing): Update. X-Git-Refname: refs/heads/archer-tromey-python X-Git-Reftype: branch X-Git-Oldrev: b5cdb6e5cfc537b99173fe981e81a87d1ebe4566 X-Git-Newrev: b9f17e4e3873c74786994bda5daae394d69d7948 X-SW-Source: 2008-q4/txt/msg00011.txt.bz2 List-Id: The branch, archer-tromey-python has been updated via b9f17e4e3873c74786994bda5daae394d69d7948 (commit) from b5cdb6e5cfc537b99173fe981e81a87d1ebe4566 (commit) Those revisions listed above that are new to this repository have not appeared on any other notification email. - Log ----------------------------------------------------------------- commit b9f17e4e3873c74786994bda5daae394d69d7948 Author: Tom Tromey Date: Fri Oct 17 11:59:11 2008 -0600 * gdb.texinfo (Pretty Printing): Update. ----------------------------------------------------------------------- Summary of changes: gdb/doc/ChangeLog | 4 +++ gdb/doc/gdb.texinfo | 65 ++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 66 insertions(+), 3 deletions(-) First 500 lines of diff: diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index e8b7f81..4b8143a 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,7 @@ +2008-10-17 Tom Tromey + + * gdb.texinfo (Pretty Printing): Update. + 2008-10-16 Tom Tromey * gdb.texinfo (Basic Python): Document execute's from_tty diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 7ee5f8e..d7b05bc 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -17946,7 +17946,62 @@ Otherwise, it is searched for globally. @subsubsection Pretty Printing @value{GDBN} provides a mechanism to allow pretty-printing of values -using Python code. +using Python code. This mechanism works for both MI and the CLI. + +A pretty-printer is an object that implements a specific interface. +There is no predefined base class for pretty-printers. + +@c FIXME I think perhaps we should nuke header and just use to_string +@c Investigate. + +@defop Operation {pretty printer} header (self, val) +If this method exists, @value{GDBN} may call it when printing a value +from the CLI. In particular, it will be called if the pretty-printer +does not define the @code{to_string} method. The method must return a +string. This string will be displayed before any children of the +value being printed. +@end defop + +@defop Operation {pretty printer} children (self, val) +This method is used by both the MI and CLI code. When printing a +value, @value{GDBN} will call this method to display the children of +@var{val}, an instance of @code{gdb.Value}. + +This method must return an object conforming to the Python iterator +protocol. Each element 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. +@end defop + +@defop Operation {pretty printer} display_hint (self, val) +This method is only used by the MI printer. + +This method must return a string. It will be supplied to the MI +consumer as a @samp{displayhint} attribute of the variable being +printed. + +Currently only one display hint is defined: @samp{map}. This +indicates to the MI consumer that the object being printed is +``map-like'', and that the children of this value can be assumed to +alternate between keys and values. +@end defop + +@defop Operation {pretty printer} to_string (self, val) +This method is used by both the MI and CLI code. When printing a +value, @value{GDBN} will call this method to display the string +representation of @var{val}, an instance of @code{gdb.Value}. + +This method must return a string. + +@c FIXME -- this is where the oddity arises. Don't we do something +@c different for MI? +When printing from the CLI, if the @code{to_string} method exists, +then @value{GDBN} will print its result, and will not call +@code{header} and @code{children}. +@end defop + +@subsubsection Selecting CLI Pretty-Printers The Python dictionary @code{gdb.cli_pretty_printers} maps regular expressions (strings) onto pretty-printers. A pretty-printer is @@ -17960,8 +18015,8 @@ representing the value to be printed. If the pretty-printer is a function, the function is called directly. -If the pretty-printer is an object, the object's @code{to_string} -method is called. +If the pretty-printer is an object, the object's methods are called as +described above. If the pretty-printer returns a string, it is printed. If it returns any Python value that is convertible to a @code{gdb.Value}, then that @@ -17988,6 +18043,10 @@ class StdStringPrinter: gdb.cli_pretty_printers['^std::basic_string$'] = StdStringPrinter() @end smallexample +@c FIXME: describe MI pretty-printer selection +@c ... but in the MI section, I think + + @node Threads In Python @subsubsection Threads In Python hooks/post-receive -- Repository for Project Archer.