This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [patch] doc-python: Pretty Printing split user / developer
On Thu, 22 Apr 2010 05:18:45 +0200, Eli Zaretskii wrote:
> The long lines here need to be wrapped, to become shorter than 72
> characters.
Fixed.
> This menu uses TAB characters. Please convert all of them to spaces
Fixed.
> Using TABs in a Texinfo file is a no-no,
There are more of them, though.
> > +@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 repeats what you just said in the "Pretty Printing" section. I
> don't think we need to repeat that.
It now looks this way but that's probably OK:
# File: gdb.info, Node: Pretty Printing API, Next: Selecting Pretty-Printers,
# Prev: Types In Python, Up: Python API
#
# 23.2.2.6 Pretty Printing API
# ............................
#
# An example output is provided (*note Pretty Printing::).
#
# A pretty-printer is just an object that holds a value and implements
# a specific interface, defined here.
Checked-in.
Thanks,
Jan
http://sourceware.org/ml/gdb-cvs/2010-04/msg00221.html
--- src/gdb/doc/ChangeLog 2010/04/22 04:09:25 1.1053
+++ src/gdb/doc/ChangeLog 2010/04/22 16:32:43 1.1054
@@ -1,3 +1,14 @@
+2010-04-22 Jan Kratochvil <jan.kratochvil@redhat.com>
+
+ * gdb.texinfo (Data): New @menu reference to Pretty Printing.
+ (Python API): Change the reference to Pretty Printing API.
+ (Pretty Printing): Move the user part under the Data node. Reformat
+ the sample output to 72 columns. Create a new reference to Pretty
+ Printing API. Rename the API part ...
+ (Pretty Printing API): To a new node name.
+ (Selecting Pretty-Printers, Progspaces In Python, Objfiles In Python)
+ (GDB/MI Variable Objects): Change references to Pretty Printing API.
+
2010-04-21 Stan Shebs <stan@codesourcery.com>
* gdb.texinfo (Tracepoint Actions): Mention synonymy of actions
--- src/gdb/doc/gdb.texinfo 2010/04/22 04:09:25 1.710
+++ src/gdb/doc/gdb.texinfo 2010/04/22 16:32:43 1.711
@@ -6731,6 +6731,7 @@
* Memory:: Examining memory
* Auto Display:: Automatic display
* Print Settings:: Print settings
+* Pretty Printing:: Python pretty printing
* Value History:: Value history
* Convenience Vars:: Convenience variables
* Registers:: Registers
@@ -7909,6 +7910,42 @@
Show whether C@t{++} virtual function tables are pretty printed, or not.
@end table
+@node Pretty Printing
+@section Pretty Printing
+
+@value{GDBN} provides a mechanism to allow pretty-printing of values using
+Python code. It greatly simplifies 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
+
+With a pretty-printer for @code{std::string} only the contents are printed:
+
+@smallexample
+(@value{GDBP}) print s
+$2 = "abcd"
+@end smallexample
+
+For implementing pretty printers for new types you should read the Python API
+details (@pxref{Pretty Printing API}).
+
@node Value History
@section Value History
@@ -19770,8 +19807,8 @@
* Exception Handling::
* Auto-loading:: Automatically loading Python code.
* Values From Inferior::
-* Types In Python:: Python representation of types.
-* Pretty Printing:: Pretty-printing values.
+* Types In Python:: Python representation of types.
+* Pretty Printing API:: 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.
@@ -20398,37 +20435,10 @@
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:
+@node Pretty Printing API
+@subsubsection Pretty Printing API
-@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
+An example output is provided (@pxref{Pretty Printing}).
A pretty-printer is just an object that holds a value and implements a
specific interface, defined here.
@@ -20520,7 +20530,7 @@
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
+interface definition above (@pxref{Pretty Printing API}). If a function
cannot create a pretty-printer for the value, it should return
@code{None}.
@@ -20601,7 +20611,7 @@
printers for the specific version of the library used by each
inferior.
-To continue the @code{std::string} example (@pxref{Pretty Printing}),
+To continue the @code{std::string} example (@pxref{Pretty Printing API}),
this code might appear in @code{gdb.libstdcxx.v6}:
@smallexample
@@ -20967,7 +20977,7 @@
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. @xref{Pretty Printing}, for more
+which is used to format the value. @xref{Pretty Printing API}, for more
information.
@end defivar
@@ -21012,7 +21022,7 @@
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. @xref{Pretty Printing}, for more
+which is used to format the value. @xref{Pretty Printing API}, for more
information.
@end defivar
@@ -25269,7 +25279,7 @@
@item displayhint
A dynamic varobj can supply a display hint to the front end. The
value comes directly from the Python pretty-printer object's
-@code{display_hint} method. @xref{Pretty Printing}.
+@code{display_hint} method. @xref{Pretty Printing API}.
@end table
Typical output will look like this:
@@ -25441,7 +25451,7 @@
@item displayhint
A dynamic varobj can supply a display hint to the front end. The
value comes directly from the Python pretty-printer object's
-@code{display_hint} method. @xref{Pretty Printing}.
+@code{display_hint} method. @xref{Pretty Printing API}.
@item has_more
This is an integer attribute which is nonzero if there are children
@@ -25805,7 +25815,7 @@
the varobj @var{name} as an argument (this is done so that the same
Python pretty-printing code can be used for both the CLI and MI).
When called, this object must return an object which conforms to the
-pretty-printing interface (@pxref{Pretty Printing}).
+pretty-printing interface (@pxref{Pretty Printing API}).
The pre-defined function @code{gdb.default_visualizer} may be used to
select a visualizer by following the built-in process