1<html lang="en"> 2<head> 3<title>Type 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="Writing-a-Pretty_002dPrinter.html#Writing-a-Pretty_002dPrinter" title="Writing a Pretty-Printer"> 10<link rel="next" href="Frame-Filter-API.html#Frame-Filter-API" title="Frame Filter API"> 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="Type-Printing-API"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Frame-Filter-API.html#Frame-Filter-API">Frame Filter API</a>, 45Previous: <a rel="previous" accesskey="p" href="Writing-a-Pretty_002dPrinter.html#Writing-a-Pretty_002dPrinter">Writing a Pretty-Printer</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.8 Type Printing API</h5> 51 52<p><a name="index-type-printing-API-for-Python-1877"></a> 53<span class="sc">gdb</span> provides a way for Python code to customize type display. 54This is mainly useful for substituting canonical typedef names for 55types. 56 57 <p><a name="index-type-printer-1878"></a>A <dfn>type printer</dfn> is just a Python object conforming to a certain 58protocol. A simple base class implementing the protocol is provided; 59see <a href="gdb_002etypes.html#gdb_002etypes">gdb.types</a>. A type printer must supply at least: 60 61<div class="defun"> 62— Instance Variable of type_printer: <b>enabled</b><var><a name="index-enabled-1879"></a></var><br> 63<blockquote><p>A boolean which is True if the printer is enabled, and False 64otherwise. This is manipulated by the <code>enable type-printer</code> 65and <code>disable type-printer</code> commands. 66</p></blockquote></div> 67 68<div class="defun"> 69— Instance Variable of type_printer: <b>name</b><var><a name="index-name-1880"></a></var><br> 70<blockquote><p>The name of the type printer. This must be a string. This is used by 71the <code>enable type-printer</code> and <code>disable type-printer</code> 72commands. 73</p></blockquote></div> 74 75<div class="defun"> 76— Method on type_printer: <b>instantiate</b> (<var>self</var>)<var><a name="index-instantiate-on-type_005fprinter-1881"></a></var><br> 77<blockquote><p>This is called by <span class="sc">gdb</span> at the start of type-printing. It is 78only called if the type printer is enabled. This method must return a 79new object that supplies a <code>recognize</code> method, as described below. 80</p></blockquote></div> 81 82 <p>When displaying a type, say via the <code>ptype</code> command, <span class="sc">gdb</span> 83will compute a list of type recognizers. This is done by iterating 84first over the per-objfile type printers (see <a href="Objfiles-In-Python.html#Objfiles-In-Python">Objfiles In Python</a>), 85followed by the per-progspace type printers (see <a href="Progspaces-In-Python.html#Progspaces-In-Python">Progspaces In Python</a>), and finally the global type printers. 86 87 <p><span class="sc">gdb</span> will call the <code>instantiate</code> method of each enabled 88type printer. If this method returns <code>None</code>, then the result is 89ignored; otherwise, it is appended to the list of recognizers. 90 91 <p>Then, when <span class="sc">gdb</span> is going to display a type name, it iterates 92over the list of recognizers. For each one, it calls the recognition 93function, stopping if the function returns a non-<code>None</code> value. 94The recognition function is defined as: 95 96<div class="defun"> 97— Method on type_recognizer: <b>recognize</b> (<var>self, type</var>)<var><a name="index-recognize-on-type_005frecognizer-1882"></a></var><br> 98<blockquote><p>If <var>type</var> is not recognized, return <code>None</code>. Otherwise, 99return a string which is to be printed as the name of <var>type</var>. 100<var>type</var> will be an instance of <code>gdb.Type</code> (see <a href="Types-In-Python.html#Types-In-Python">Types In Python</a>). 101</p></blockquote></div> 102 103 <p><span class="sc">gdb</span> uses this two-pass approach so that type printers can 104efficiently cache information without holding on to it too long. For 105example, it can be convenient to look up type information in a type 106printer and hold it for a recognizer's lifetime; if a single pass were 107done then type printers would have to make use of the event system in 108order to avoid holding information that could become stale as the 109inferior changed. 110 111 </body></html> 112 113