From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 9923 invoked by alias); 21 Apr 2010 20:50:59 -0000 Received: (qmail 9912 invoked by uid 22791); 21 Apr 2010 20:50:57 -0000 X-SWARE-Spam-Status: No, hits=-5.4 required=5.0 tests=BAYES_05,RCVD_IN_DNSWL_HI,SPF_HELO_PASS,TW_BJ,T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from mx1.redhat.com (HELO mx1.redhat.com) (209.132.183.28) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Wed, 21 Apr 2010 20:50:52 +0000 Received: from int-mx01.intmail.prod.int.phx2.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id o3LKooKK006077 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Wed, 21 Apr 2010 16:50:50 -0400 Received: from host0.dyn.jankratochvil.net (ovpn01.gateway.prod.ext.phx2.redhat.com [10.5.9.1]) by int-mx01.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id o3LKolRZ007242 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Wed, 21 Apr 2010 16:50:49 -0400 Received: from host0.dyn.jankratochvil.net (localhost [127.0.0.1]) by host0.dyn.jankratochvil.net (8.14.4/8.14.4) with ESMTP id o3LKoldW026062 for ; Wed, 21 Apr 2010 22:50:47 +0200 Received: (from jkratoch@localhost) by host0.dyn.jankratochvil.net (8.14.4/8.14.4/Submit) id o3LKok6s026061 for gdb-patches@sourceware.org; Wed, 21 Apr 2010 22:50:46 +0200 Date: Wed, 21 Apr 2010 20:50:00 -0000 From: Jan Kratochvil To: gdb-patches@sourceware.org Subject: [patch] doc-python: Pretty Printing split user / developer Message-ID: <20100421205046.GA25787@host0.dyn.jankratochvil.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.5.20 (2009-08-17) X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2010-04/txt/msg00705.txt.bz2 Hi, There has been accepted: RFA: update `print' docs http://sourceware.org/ml/gdb-patches/2010-03/msg00236.html but still it got a user comment: [ info '(./gdb.info)Pretty Printing' ] # ... the target for the xref needs to be something more user oriented targeted # at the C/C++/Fortran programmer rather something that goes to part of the # manual discussing the Python API. # # That section is fine right up until you get to: # # A pretty-printer is just an object that holds a value and implements a # specific interface, defined here. # # That is more targeted at the pretty printer developer. which I try to address by the attachment. Is it OK this way? (the "smallexample" parts sure have not been changed at all) Thanks, Jan gdb/doc/ 2010-04-21 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. 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. --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -6731,6 +6731,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 @@ -7901,6 +7902,39 @@ Do not pretty print C@t{++} virtual function tables. 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 @@ -19765,7 +19799,7 @@ 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. +* 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. @@ -20392,37 +20426,13 @@ 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: +@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 +@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. 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. @@ -20514,7 +20524,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}. @@ -20595,7 +20605,7 @@ 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}), +To continue the @code{std::string} example (@pxref{Pretty Printing API}), this code might appear in @code{gdb.libstdcxx.v6}: @smallexample @@ -20961,7 +20971,7 @@ 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. @xref{Pretty Printing}, for more +which is used to format the value. @xref{Pretty Printing API}, for more information. @end defivar @@ -21006,7 +21016,7 @@ 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. @xref{Pretty Printing}, for more +which is used to format the value. @xref{Pretty Printing API}, for more information. @end defivar @@ -25263,7 +25273,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: @@ -25435,7 +25445,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 @@ -25799,7 +25809,7 @@ single argument. @value{GDBN} will call this object with the value of 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