Re: [patch] doc-python: Pretty Printing split user / developer http://sourceware.org/ml/gdb-patches/2010-04/msg00757.html http://sourceware.org/ml/gdb-cvs/2010-04/msg00221.html [ Backported for Fedora. ] ### 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 + + * 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 * gdb.texinfo (Tracepoint Actions): Mention synonymy of actions --- gdb-7.1/gdb/doc/gdb.texinfo.orig 2010-04-22 19:08:30.000000000 +0200 +++ gdb-7.1/gdb/doc/gdb.texinfo 2010-04-22 19:10:41.000000000 +0200 @@ -6727,6 +6727,7 @@ Table}. * 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 @@ -7897,6 +7898,42 @@ Do not pretty print C@t{++} virtual func 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 = @{ + > = @{ + <__gnu_cxx::new_allocator> = @{ + @}, + @}, + members of std::basic_string, + std::allocator >::_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 @@ -19608,8 +19645,8 @@ situation, a Python @code{KeyboardInterr * Exception Handling:: * Auto-loading:: Automatically loading Python code. * Values From Inferior:: Python representation of values. -* 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. * Inferiors In Python:: Python representation of inferiors (processes) * Threads In Python:: Accessing inferior threads from Python. @@ -20241,37 +20278,10 @@ A function internal to @value{GDBN}. Th 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 = @{ - > = @{ - <__gnu_cxx::new_allocator> = @{@}, @}, - members of std::basic_string, std::allocator >::_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. @@ -20359,7 +20369,7 @@ 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 +interface definition above (@pxref{Pretty Printing API}). If a function cannot create a pretty-printer for the value, it should return @code{None}. @@ -20436,7 +20446,7 @@ printers with a specific objfile, @value 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 @@ -21048,7 +21058,7 @@ The @code{pretty_printers} attribute 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. @xref{Pretty Printing}, for more +which is used to format the value. @xref{Pretty Printing API}, for more information. @end defivar @@ -24875,7 +24885,7 @@ then this attribute will not be present. @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: @@ -25047,7 +25057,7 @@ The result may have its own attributes: @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 @@ -25411,7 +25421,7 @@ single argument. @value{GDBN} will call 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