1<html lang="en"> 2<head> 3<title>Pretty Printing API - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Python-API.html#Python-API" title="Python API"> 9<link rel="prev" href="Types-In-Python.html#Types-In-Python" title="Types In Python"> 10<link rel="next" href="Selecting-Pretty_002dPrinters.html#Selecting-Pretty_002dPrinters" title="Selecting Pretty-Printers"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 141998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 15Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation; with the 20Invariant Sections being ``Free Software'' and ``Free Software Needs 21Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 22and with the Back-Cover Texts as in (a) below. 23 24(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 25this GNU Manual. Buying copies from GNU Press supports the FSF in 26developing GNU and promoting software freedom.''--> 27<meta http-equiv="Content-Style-Type" content="text/css"> 28<style type="text/css"><!-- 29 pre.display { font-family:inherit } 30 pre.format { font-family:inherit } 31 pre.smalldisplay { font-family:inherit; font-size:smaller } 32 pre.smallformat { font-family:inherit; font-size:smaller } 33 pre.smallexample { font-size:smaller } 34 pre.smalllisp { font-size:smaller } 35 span.sc { font-variant:small-caps } 36 span.roman { font-family:serif; font-weight:normal; } 37 span.sansserif { font-family:sans-serif; font-weight:normal; } 38--></style> 39<link rel="stylesheet" type="text/css" href="../cs.css"> 40</head> 41<body> 42<div class="node"> 43<a name="Pretty-Printing-API"></a> 44<p> 45Next: <a rel="next" accesskey="n" href="Selecting-Pretty_002dPrinters.html#Selecting-Pretty_002dPrinters">Selecting Pretty-Printers</a>, 46Previous: <a rel="previous" accesskey="p" href="Types-In-Python.html#Types-In-Python">Types In Python</a>, 47Up: <a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a> 48<hr> 49</div> 50 51<h5 class="subsubsection">23.2.2.5 Pretty Printing API</h5> 52 53<p>An example output is provided (see <a href="Pretty-Printing.html#Pretty-Printing">Pretty Printing</a>). 54 55 <p>A pretty-printer is just an object that holds a value and implements a 56specific interface, defined here. 57 58<div class="defun"> 59— Operation on pretty printer: <b>children</b> (<var>self</var>)<var><a name="index-children-on-pretty-printer-1694"></a></var><br> 60<blockquote><p><span class="sc">gdb</span> will call this method on a pretty-printer to compute the 61children of the pretty-printer's value. 62 63 <p>This method must return an object conforming to the Python iterator 64protocol. Each item returned by the iterator must be a tuple holding 65two elements. The first element is the “name” of the child; the 66second element is the child's value. The value can be any Python 67object which is convertible to a <span class="sc">gdb</span> value. 68 69 <p>This method is optional. If it does not exist, <span class="sc">gdb</span> will act 70as though the value has no children. 71</p></blockquote></div> 72 73<div class="defun"> 74— Operation on pretty printer: <b>display_hint</b> (<var>self</var>)<var><a name="index-display_005fhint-on-pretty-printer-1695"></a></var><br> 75<blockquote><p>The CLI may call this method and use its result to change the 76formatting of a value. The result will also be supplied to an MI 77consumer as a ‘<samp><span class="samp">displayhint</span></samp>’ attribute of the variable being 78printed. 79 80 <p>This method is optional. If it does exist, this method must return a 81string. 82 83 <p>Some display hints are predefined by <span class="sc">gdb</span>: 84 85 <dl> 86<dt>‘<samp><span class="samp">array</span></samp>’<dd>Indicate that the object being printed is “array-like”. The CLI 87uses this to respect parameters such as <code>set print elements</code> and 88<code>set print array</code>. 89 90 <br><dt>‘<samp><span class="samp">map</span></samp>’<dd>Indicate that the object being printed is “map-like”, and that the 91children of this value can be assumed to alternate between keys and 92values. 93 94 <br><dt>‘<samp><span class="samp">string</span></samp>’<dd>Indicate that the object being printed is “string-like”. If the 95printer's <code>to_string</code> method returns a Python string of some 96kind, then <span class="sc">gdb</span> will call its internal language-specific 97string-printing function to format the string. For the CLI this means 98adding quotation marks, possibly escaping some characters, respecting 99<code>set print elements</code>, and the like. 100</dl> 101 </p></blockquote></div> 102 103<div class="defun"> 104— Operation on pretty printer: <b>to_string</b> (<var>self</var>)<var><a name="index-to_005fstring-on-pretty-printer-1696"></a></var><br> 105<blockquote><p><span class="sc">gdb</span> will call this method to display the string 106representation of the value passed to the object's constructor. 107 108 <p>When printing from the CLI, if the <code>to_string</code> method exists, 109then <span class="sc">gdb</span> will prepend its result to the values returned by 110<code>children</code>. Exactly how this formatting is done is dependent on 111the display hint, and may change as more hints are added. Also, 112depending on the print settings (see <a href="Print-Settings.html#Print-Settings">Print Settings</a>), the CLI may 113print just the result of <code>to_string</code> in a stack trace, omitting 114the result of <code>children</code>. 115 116 <p>If this method returns a string, it is printed verbatim. 117 118 <p>Otherwise, if this method returns an instance of <code>gdb.Value</code>, 119then <span class="sc">gdb</span> prints this value. This may result in a call to 120another pretty-printer. 121 122 <p>If instead the method returns a Python value which is convertible to a 123<code>gdb.Value</code>, then <span class="sc">gdb</span> performs the conversion and prints 124the resulting value. Again, this may result in a call to another 125pretty-printer. Python scalars (integers, floats, and booleans) and 126strings are convertible to <code>gdb.Value</code>; other types are not. 127 128 <p>Finally, if this method returns <code>None</code> then no further operations 129are peformed in this method and nothing is printed. 130 131 <p>If the result is not one of these types, an exception is raised. 132</p></blockquote></div> 133 134 <p><span class="sc">gdb</span> provides a function which can be used to look up the 135default pretty-printer for a <code>gdb.Value</code>: 136 137 <p><a name="index-gdb_002edefault_005fvisualizer-1697"></a> 138 139<div class="defun"> 140— Function: <b>default_visualizer</b><var> value<a name="index-default_005fvisualizer-1698"></a></var><br> 141<blockquote><p>This function takes a <code>gdb.Value</code> object as an argument. If a 142pretty-printer for this value exists, then it is returned. If no such 143printer exists, then this returns <code>None</code>. 144</p></blockquote></div> 145 146 </body></html> 147 148