1# Pretty-printer utilities. 2# Copyright (C) 2010, 2011 Free Software Foundation, Inc. 3 4# This program is free software; you can redistribute it and/or modify 5# it under the terms of the GNU General Public License as published by 6# the Free Software Foundation; either version 3 of the License, or 7# (at your option) any later version. 8# 9# This program is distributed in the hope that it will be useful, 10# but WITHOUT ANY WARRANTY; without even the implied warranty of 11# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12# GNU General Public License for more details. 13# 14# You should have received a copy of the GNU General Public License 15# along with this program. If not, see <http://www.gnu.org/licenses/>. 16 17"""Utilities for working with pretty-printers.""" 18 19import gdb 20import gdb.types 21import re 22 23 24class PrettyPrinter(object): 25 """A basic pretty-printer. 26 27 Attributes: 28 name: A unique string among all printers for the context in which 29 it is defined (objfile, progspace, or global(gdb)), and should 30 meaningfully describe what can be pretty-printed. 31 E.g., "StringPiece" or "protobufs". 32 subprinters: An iterable object with each element having a `name' 33 attribute, and, potentially, "enabled" attribute. 34 Or this is None if there are no subprinters. 35 enabled: A boolean indicating if the printer is enabled. 36 37 Subprinters are for situations where "one" pretty-printer is actually a 38 collection of several printers. E.g., The libstdc++ pretty-printer has 39 a pretty-printer for each of several different types, based on regexps. 40 """ 41 42 # While one might want to push subprinters into the subclass, it's 43 # present here to formalize such support to simplify 44 # commands/pretty_printers.py. 45 46 def __init__(self, name, subprinters=None): 47 self.name = name 48 self.subprinters = subprinters 49 self.enabled = True 50 51 def __call__(self, val): 52 # The subclass must define this. 53 raise NotImplementedError("PrettyPrinter __call__") 54 55 56class SubPrettyPrinter(object): 57 """Baseclass for sub-pretty-printers. 58 59 Sub-pretty-printers needn't use this, but it formalizes what's needed. 60 61 Attributes: 62 name: The name of the subprinter. 63 enabled: A boolean indicating if the subprinter is enabled. 64 """ 65 66 def __init__(self, name): 67 self.name = name 68 self.enabled = True 69 70 71def register_pretty_printer(obj, printer): 72 """Register pretty-printer PRINTER with OBJ. 73 74 The printer is added to the front of the search list, thus one can override 75 an existing printer if one needs to. 76 77 Arguments: 78 obj: Either an objfile, progspace, or None (in which case the printer 79 is registered globally). 80 printer: Either a function of one argument (old way) or any object 81 which has attributes: name, enabled, __call__. 82 83 Returns: 84 Nothing. 85 86 Raises: 87 TypeError: A problem with the type of the printer. 88 ValueError: The printer's name contains a semicolon ";". 89 90 If the caller wants the printer to be listable and disableable, it must 91 follow the PrettyPrinter API. This applies to the old way (functions) too. 92 If printer is an object, __call__ is a method of two arguments: 93 self, and the value to be pretty-printed. See PrettyPrinter. 94 """ 95 96 # Watch for both __name__ and name. 97 # Functions get the former for free, but we don't want to use an 98 # attribute named __foo__ for pretty-printers-as-objects. 99 # If printer has both, we use `name'. 100 if not hasattr(printer, "__name__") and not hasattr(printer, "name"): 101 raise TypeError("printer missing attribute: name") 102 if hasattr(printer, "name") and not hasattr(printer, "enabled"): 103 raise TypeError("printer missing attribute: enabled") 104 if not hasattr(printer, "__call__"): 105 raise TypeError("printer missing attribute: __call__") 106 107 if obj is None: 108 if gdb.parameter("verbose"): 109 gdb.write("Registering global %s pretty-printer ...\n" % name) 110 obj = gdb 111 else: 112 if gdb.parameter("verbose"): 113 gdb.write("Registering %s pretty-printer for %s ...\n" % 114 (printer.name, obj.filename)) 115 116 if hasattr(printer, "name"): 117 if not isinstance(printer.name, basestring): 118 raise TypeError("printer name is not a string") 119 # If printer provides a name, make sure it doesn't contain ";". 120 # Semicolon is used by the info/enable/disable pretty-printer commands 121 # to delimit subprinters. 122 if printer.name.find(";") >= 0: 123 raise ValueError("semicolon ';' in printer name") 124 # Also make sure the name is unique. 125 # Alas, we can't do the same for functions and __name__, they could 126 # all have a canonical name like "lookup_function". 127 # PERF: gdb records printers in a list, making this inefficient. 128 if (printer.name in 129 [p.name for p in obj.pretty_printers if hasattr(p, "name")]): 130 raise RuntimeError("pretty-printer already registered: %s" % 131 printer.name) 132 133 obj.pretty_printers.insert(0, printer) 134 135 136class RegexpCollectionPrettyPrinter(PrettyPrinter): 137 """Class for implementing a collection of regular-expression based pretty-printers. 138 139 Intended usage: 140 141 pretty_printer = RegexpCollectionPrettyPrinter("my_library") 142 pretty_printer.add_printer("myclass1", "^myclass1$", MyClass1Printer) 143 ... 144 pretty_printer.add_printer("myclassN", "^myclassN$", MyClassNPrinter) 145 register_pretty_printer(obj, pretty_printer) 146 """ 147 148 class RegexpSubprinter(SubPrettyPrinter): 149 def __init__(self, name, regexp, gen_printer): 150 super(RegexpCollectionPrettyPrinter.RegexpSubprinter, self).__init__(name) 151 self.regexp = regexp 152 self.gen_printer = gen_printer 153 self.compiled_re = re.compile(regexp) 154 155 def __init__(self, name): 156 super(RegexpCollectionPrettyPrinter, self).__init__(name, []) 157 158 def add_printer(self, name, regexp, gen_printer): 159 """Add a printer to the list. 160 161 The printer is added to the end of the list. 162 163 Arguments: 164 name: The name of the subprinter. 165 regexp: The regular expression, as a string. 166 gen_printer: A function/method that given a value returns an 167 object to pretty-print it. 168 169 Returns: 170 Nothing. 171 """ 172 173 # NOTE: A previous version made the name of each printer the regexp. 174 # That makes it awkward to pass to the enable/disable commands (it's 175 # cumbersome to make a regexp of a regexp). So now the name is a 176 # separate parameter. 177 178 self.subprinters.append(self.RegexpSubprinter(name, regexp, 179 gen_printer)) 180 181 def __call__(self, val): 182 """Lookup the pretty-printer for the provided value.""" 183 184 # Get the type name. 185 typename = gdb.types.get_basic_type(val.type).tag 186 if not typename: 187 return None 188 189 # Iterate over table of type regexps to determine 190 # if a printer is registered for that type. 191 # Return an instantiation of the printer if found. 192 for printer in self.subprinters: 193 if printer.enabled and printer.compiled_re.search(typename): 194 return printer.gen_printer(val) 195 196 # Cannot find a pretty printer. Return None. 197 return None 198