public inbox for archer-commits@sourceware.org
help / color / mirror / Atom feed
* [SCM] archer-tromey-python: * gdb.texinfo (Pretty Printing): Update.
@ 2008-10-17 18:01 tromey
0 siblings, 0 replies; only message in thread
From: tromey @ 2008-10-17 18:01 UTC (permalink / raw)
To: archer-commits
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 <tromey@redhat.com>
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 <tromey@redhat.com>
+
+ * gdb.texinfo (Pretty Printing): Update.
+
2008-10-16 Tom Tromey <tromey@redhat.com>
* 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<char.*>$'] = 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.
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2008-10-17 18:01 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2008-10-17 18:01 [SCM] archer-tromey-python: * gdb.texinfo (Pretty Printing): Update tromey
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).