From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15538 invoked by alias); 22 Apr 2010 17:00:57 -0000 Received: (qmail 15416 invoked by uid 22791); 22 Apr 2010 17:00:52 -0000 X-SWARE-Spam-Status: No, hits=-6.8 required=5.0 tests=BAYES_00,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; Thu, 22 Apr 2010 17:00:43 +0000 Received: from int-mx08.intmail.prod.int.phx2.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id o3MH0S0s022780 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 22 Apr 2010 13:00:36 -0400 Received: from host0.dyn.jankratochvil.net (ovpn01.gateway.prod.ext.phx2.redhat.com [10.5.9.1]) by int-mx08.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id o3MGYG08005374 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Thu, 22 Apr 2010 12:34:18 -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 o3MGYFBb032456; Thu, 22 Apr 2010 18:34:15 +0200 Received: (from jkratoch@localhost) by host0.dyn.jankratochvil.net (8.14.4/8.14.4/Submit) id o3MGYFGK032455; Thu, 22 Apr 2010 18:34:15 +0200 Date: Thu, 22 Apr 2010 17:00:00 -0000 From: Jan Kratochvil To: Eli Zaretskii Cc: gdb-patches@sourceware.org Subject: Re: [patch] doc-python: Pretty Printing split user / developer Message-ID: <20100422163415.GA29960@host0.dyn.jankratochvil.net> References: <20100421205046.GA25787@host0.dyn.jankratochvil.net> <83aasw41ka.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <83aasw41ka.fsf@gnu.org> 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/msg00757.txt.bz2 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 + + * 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 --- 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 = @{ + > = @{ + <__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 @@ -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 = @{ - > = @{ - <__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. @@ -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