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