1<html lang="en"> 2<head> 3<title>Selecting Pretty-Printers - 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="Pretty-Printing-API.html#Pretty-Printing-API" title="Pretty Printing API"> 10<link rel="next" href="Disabling-Pretty_002dPrinters.html#Disabling-Pretty_002dPrinters" title="Disabling 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="Selecting-Pretty-Printers"></a> 44<a name="Selecting-Pretty_002dPrinters"></a> 45<p> 46Next: <a rel="next" accesskey="n" href="Disabling-Pretty_002dPrinters.html#Disabling-Pretty_002dPrinters">Disabling Pretty-Printers</a>, 47Previous: <a rel="previous" accesskey="p" href="Pretty-Printing-API.html#Pretty-Printing-API">Pretty Printing API</a>, 48Up: <a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a> 49<hr> 50</div> 51 52<h5 class="subsubsection">23.2.2.6 Selecting Pretty-Printers</h5> 53 54<p>The Python list <code>gdb.pretty_printers</code> contains an array of 55functions or callable objects that have been registered via addition 56as a pretty-printer. 57Each <code>gdb.Progspace</code> contains a <code>pretty_printers</code> attribute. 58Each <code>gdb.Objfile</code> also contains a <code>pretty_printers</code> 59attribute. 60 61 <p>A function on one of these lists is passed a single <code>gdb.Value</code> 62argument and should return a pretty-printer object conforming to the 63interface definition above (see <a href="Pretty-Printing-API.html#Pretty-Printing-API">Pretty Printing API</a>). If a function 64cannot create a pretty-printer for the value, it should return 65<code>None</code>. 66 67 <p><span class="sc">gdb</span> first checks the <code>pretty_printers</code> attribute of each 68<code>gdb.Objfile</code> in the current program space and iteratively calls 69each enabled function (see <a href="Disabling-Pretty_002dPrinters.html#Disabling-Pretty_002dPrinters">Disabling Pretty-Printers</a>) 70in the list for that <code>gdb.Objfile</code> until it receives 71a pretty-printer object. 72If no pretty-printer is found in the objfile lists, <span class="sc">gdb</span> then 73searches the pretty-printer list of the current program space, 74calling each enabled function until an object is returned. 75After these lists have been exhausted, it tries the global 76<code>gdb.pretty_printers</code> list, again calling each enabled function until an 77object is returned. 78 79 <p>The order in which the objfiles are searched is not specified. For a 80given list, functions are always invoked from the head of the list, 81and iterated over sequentially until the end of the list, or a printer 82object is returned. 83 84 <p>Here is an example showing how a <code>std::string</code> printer might be 85written: 86 87<pre class="smallexample"> class StdStringPrinter: 88 "Print a std::string" 89 90 def __init__ (self, val): 91 self.val = val 92 93 def to_string (self): 94 return self.val['_M_dataplus']['_M_p'] 95 96 def display_hint (self): 97 return 'string' 98</pre> 99 <p>And here is an example showing how a lookup function for the printer 100example above might be written. 101 102<pre class="smallexample"> def str_lookup_function (val): 103 104 lookup_tag = val.type.tag 105 regex = re.compile ("^std::basic_string<char,.*>$") 106 if lookup_tag == None: 107 return None 108 if regex.match (lookup_tag): 109 return StdStringPrinter (val) 110 111 return None 112</pre> 113 <p>The example lookup function extracts the value's type, and attempts to 114match it to a type that it can pretty-print. If it is a type the 115printer can pretty-print, it will return a printer object. If not, it 116returns <code>None</code>. 117 118 <p>We recommend that you put your core pretty-printers into a Python 119package. If your pretty-printers are for use with a library, we 120further recommend embedding a version number into the package name. 121This practice will enable <span class="sc">gdb</span> to load multiple versions of 122your pretty-printers at the same time, because they will have 123different names. 124 125 <p>You should write auto-loaded code (see <a href="Auto_002dloading.html#Auto_002dloading">Auto-loading</a>) such that it 126can be evaluated multiple times without changing its meaning. An 127ideal auto-load file will consist solely of <code>import</code>s of your 128printer modules, followed by a call to a register pretty-printers with 129the current objfile. 130 131 <p>Taken as a whole, this approach will scale nicely to multiple 132inferiors, each potentially using a different library version. 133Embedding a version number in the Python package name will ensure that 134<span class="sc">gdb</span> is able to load both sets of printers simultaneously. 135Then, because the search for pretty-printers is done by objfile, and 136because your auto-loaded code took care to register your library's 137printers with a specific objfile, <span class="sc">gdb</span> will find the correct 138printers for the specific version of the library used by each 139inferior. 140 141 <p>To continue the <code>std::string</code> example (see <a href="Pretty-Printing-API.html#Pretty-Printing-API">Pretty Printing API</a>), 142this code might appear in <code>gdb.libstdcxx.v6</code>: 143 144<pre class="smallexample"> def register_printers (objfile): 145 objfile.pretty_printers.add (str_lookup_function) 146</pre> 147 <p class="noindent">And then the corresponding contents of the auto-load file would be: 148 149<pre class="smallexample"> import gdb.libstdcxx.v6 150 gdb.libstdcxx.v6.register_printers (gdb.current_objfile ()) 151</pre> 152 </body></html> 153 154