1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Pretty Printing API</title> 18 19<meta name="description" content="Debugging with GDB: Pretty Printing API"> 20<meta name="keywords" content="Debugging with GDB: Pretty Printing API"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Python-API.html#Python-API" rel="up" title="Python API"> 29<link href="Selecting-Pretty_002dPrinters.html#Selecting-Pretty_002dPrinters" rel="next" title="Selecting Pretty-Printers"> 30<link href="Types-In-Python.html#Types-In-Python" rel="previous" title="Types In Python"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Pretty-Printing-API"></a> 65<div class="header"> 66<p> 67Next: <a href="Selecting-Pretty_002dPrinters.html#Selecting-Pretty_002dPrinters" accesskey="n" rel="next">Selecting Pretty-Printers</a>, Previous: <a href="Types-In-Python.html#Types-In-Python" accesskey="p" rel="previous">Types In Python</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Pretty-Printing-API-1"></a> 71<h4 class="subsubsection">23.2.2.5 Pretty Printing API</h4> 72<a name="index-python-pretty-printing-api"></a> 73 74<p>A pretty-printer is just an object that holds a value and implements a 75specific interface, defined here. An example output is provided 76(see <a href="Pretty-Printing.html#Pretty-Printing">Pretty Printing</a>). 77</p> 78<dl> 79<dt><a name="index-pretty_005fprinter_002echildren"></a>Function: <strong>pretty_printer.children</strong> <em>(self)</em></dt> 80<dd><p><small>GDB</small> will call this method on a pretty-printer to compute the 81children of the pretty-printer’s value. 82</p> 83<p>This method must return an object conforming to the Python iterator 84protocol. Each item returned by the iterator must be a tuple holding 85two elements. The first element is the “name” of the child; the 86second element is the child’s value. The value can be any Python 87object which is convertible to a <small>GDB</small> value. 88</p> 89<p>This method is optional. If it does not exist, <small>GDB</small> will act 90as though the value has no children. 91</p> 92<p>For efficiency, the <code>children</code> method should lazily compute its 93results. This will let <small>GDB</small> read as few elements as 94necessary, for example when various print settings (see <a href="Print-Settings.html#Print-Settings">Print Settings</a>) or <code>-var-list-children</code> (see <a href="GDB_002fMI-Variable-Objects.html#GDB_002fMI-Variable-Objects">GDB/MI Variable Objects</a>) limit the number of elements to be displayed. 95</p> 96<p>Children may be hidden from display based on the value of ‘<samp>set 97print max-depth</samp>’ (see <a href="Print-Settings.html#Print-Settings">Print Settings</a>). 98</p></dd></dl> 99 100<dl> 101<dt><a name="index-pretty_005fprinter_002edisplay_005fhint"></a>Function: <strong>pretty_printer.display_hint</strong> <em>(self)</em></dt> 102<dd><p>The CLI may call this method and use its result to change the 103formatting of a value. The result will also be supplied to an MI 104consumer as a ‘<samp>displayhint</samp>’ attribute of the variable being 105printed. 106</p> 107<p>This method is optional. If it does exist, this method must return a 108string or the special value <code>None</code>. 109</p> 110<p>Some display hints are predefined by <small>GDB</small>: 111</p> 112<dl compact="compact"> 113<dt>‘<samp>array</samp>’</dt> 114<dd><p>Indicate that the object being printed is “array-like”. The CLI 115uses this to respect parameters such as <code>set print elements</code> and 116<code>set print array</code>. 117</p> 118</dd> 119<dt>‘<samp>map</samp>’</dt> 120<dd><p>Indicate that the object being printed is “map-like”, and that the 121children of this value can be assumed to alternate between keys and 122values. 123</p> 124</dd> 125<dt>‘<samp>string</samp>’</dt> 126<dd><p>Indicate that the object being printed is “string-like”. If the 127printer’s <code>to_string</code> method returns a Python string of some 128kind, then <small>GDB</small> will call its internal language-specific 129string-printing function to format the string. For the CLI this means 130adding quotation marks, possibly escaping some characters, respecting 131<code>set print elements</code>, and the like. 132</p></dd> 133</dl> 134 135<p>The special value <code>None</code> causes <small>GDB</small> to apply the default 136display rules. 137</p></dd></dl> 138 139<dl> 140<dt><a name="index-pretty_005fprinter_002eto_005fstring"></a>Function: <strong>pretty_printer.to_string</strong> <em>(self)</em></dt> 141<dd><p><small>GDB</small> will call this method to display the string 142representation of the value passed to the object’s constructor. 143</p> 144<p>When printing from the CLI, if the <code>to_string</code> method exists, 145then <small>GDB</small> will prepend its result to the values returned by 146<code>children</code>. Exactly how this formatting is done is dependent on 147the display hint, and may change as more hints are added. Also, 148depending on the print settings (see <a href="Print-Settings.html#Print-Settings">Print Settings</a>), the CLI may 149print just the result of <code>to_string</code> in a stack trace, omitting 150the result of <code>children</code>. 151</p> 152<p>If this method returns a string, it is printed verbatim. 153</p> 154<p>Otherwise, if this method returns an instance of <code>gdb.Value</code>, 155then <small>GDB</small> prints this value. This may result in a call to 156another pretty-printer. 157</p> 158<p>If instead the method returns a Python value which is convertible to a 159<code>gdb.Value</code>, then <small>GDB</small> performs the conversion and prints 160the resulting value. Again, this may result in a call to another 161pretty-printer. Python scalars (integers, floats, and booleans) and 162strings are convertible to <code>gdb.Value</code>; other types are not. 163</p> 164<p>Finally, if this method returns <code>None</code> then no further operations 165are peformed in this method and nothing is printed. 166</p> 167<p>If the result is not one of these types, an exception is raised. 168</p></dd></dl> 169 170<p><small>GDB</small> provides a function which can be used to look up the 171default pretty-printer for a <code>gdb.Value</code>: 172</p> 173<a name="index-gdb_002edefault_005fvisualizer"></a> 174<dl> 175<dt><a name="index-gdb_002edefault_005fvisualizer-1"></a>Function: <strong>gdb.default_visualizer</strong> <em>(value)</em></dt> 176<dd><p>This function takes a <code>gdb.Value</code> object as an argument. If a 177pretty-printer for this value exists, then it is returned. If no such 178printer exists, then this returns <code>None</code>. 179</p></dd></dl> 180 181<hr> 182<div class="header"> 183<p> 184Next: <a href="Selecting-Pretty_002dPrinters.html#Selecting-Pretty_002dPrinters" accesskey="n" rel="next">Selecting Pretty-Printers</a>, Previous: <a href="Types-In-Python.html#Types-In-Python" accesskey="p" rel="previous">Types In Python</a>, Up: <a href="Python-API.html#Python-API" accesskey="u" rel="up">Python API</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 185</div> 186 187 188 189</body> 190</html> 191