17"""Utilities for defining xmethods"""
25 """Base class (or a template) for an xmethod description.
27 Currently, the description requires only the 'name' and 'enabled'
28 attributes. Description objects are managed by
'XMethodMatcher'
29 objects (see below). Note that this
is only a template
for the
30 interface of the XMethodMatcher.methods objects. One could use
31 this
class or choose to use an object which supports this exact same
32 interface. Also, an XMethodMatcher can choose
not use it
'methods'
33 attribute. In such cases this
class (
or an equivalent)
is not used.
36 name: The name of the xmethod.
37 enabled: A boolean indicating
if the xmethod
is enabled.
46 """Abstract base class for matching an xmethod.
48 When looking for xmethods, GDB invokes the `match
' method of a
49 registered xmethod matcher to match the object type and method name.
50 The `match
' method in concrete classes derived from this class should
51 return an `XMethodWorker
' object, or a list of `XMethodWorker'
52 objects
if there
is a match (see below
for 'XMethodWorker' class).
55 name: The name of the matcher.
56 enabled: A boolean indicating
if the matcher
is enabled.
57 methods: A sequence of objects of type
'XMethod',
or objects
58 which have at least the attributes of an
'XMethod' object.
59 This list
is used by the
'enable'/
'disable'/
'info' commands to
60 enable/disable/list the xmethods registered
with GDB. See
61 the
'match' method below to know how this sequence
is used.
62 This attribute
is None if the matcher chooses
not have any
63 xmethods managed by it.
69 name: An identifying name for the xmethod
or the group of
70 xmethods returned by the `match
' method.
76 def match(self, class_type, method_name):
77 """Match class type and method name.
79 In derived classes, it should return an XMethodWorker object,
or a
80 sequence of
'XMethodWorker' objects. Only those xmethod workers
81 whose corresponding
'XMethod' descriptor object
is enabled should be
85 class_type: The
class type (gdb.Type object) to
match.
86 method_name: The name (string) of the method to match.
88 raise NotImplementedError(
"XMethodMatcher match")
92 """Base class for all xmethod workers defined in Python.
94 An xmethod worker is an object which matches the method arguments,
and
95 invokes the method when GDB wants it to. Internally, GDB first invokes the
96 'get_arg_types' method to perform overload resolution. If GDB selects to
97 invoke this Python xmethod, then it invokes it via the overridden
98 '__call__' method. The
'get_result_type' method
is used to implement
99 'ptype' on the xmethod.
101 Derived classes should override the
'get_arg_types',
'get_result_type'
102 and '__call__' methods.
106 """Return arguments types of an xmethod.
108 A sequence of gdb.Type objects corresponding to the arguments of the
109 xmethod are returned. If the xmethod takes no arguments, then 'None'
110 or an empty sequence
is returned. If the xmethod takes only a single
111 argument, then a gdb.Type object
or a sequence
with a single gdb.Type
114 raise NotImplementedError(
"XMethodWorker get_arg_types")
117 """Return the type of the result of the xmethod.
120 args: Arguments to the method. Each element of the tuple is a
121 gdb.Value object. The first element
is the
'this' pointer
122 value. These are the same arguments passed to
'__call__'.
125 A gdb.Type object representing the type of the result of the
128 raise NotImplementedError(
"XMethodWorker get_result_type")
131 """Invoke the xmethod.
134 args: Arguments to the method. Each element of the tuple is a
135 gdb.Value object. The first element
is the
'this' pointer
139 A gdb.Value corresponding to the value returned by the xmethod.
140 Returns
'None' if the method does
not return anything.
142 raise NotImplementedError(
"XMethodWorker __call__")
146 """A utility class to implement simple xmethod mathers and workers.
148 See the __init__ method below for information on how instances of this
151 For simple classes
and methods, one can choose to use this
class. For
152 complex xmethods, which need to replace/implement template methods on
153 possibly template classes, one should implement their own xmethod
154 matchers
and workers. See py-xmethods.py
in testsuite/gdb.python
155 directory of the GDB source tree
for examples.
170 self, name, class_matcher, method_matcher, method_function, *arg_types
174 name: Name of the xmethod matcher.
175 class_matcher: A regular expression used to match the name of the
176 class whose method this xmethod is implementing/replacing.
177 method_matcher: A regular expression used to match the name of the
178 method this xmethod
is implementing/replacing.
179 method_function: A Python callable which would be called via the
180 'invoke' method of the worker returned by the objects of this
181 class. This callable should accept the object (*this)
as the
182 first argument followed by the rest of the arguments to the
183 method. All arguments to this function should be gdb.Value
185 arg_types: The gdb.Type objects corresponding to the arguments that
186 this xmethod takes. It can be
None,
or an empty sequence,
187 or a single gdb.Type object,
or a sequence of gdb.Type objects.
189 XMethodMatcher.__init__(self, name)
190 assert callable(method_function), (
191 "The 'method_function' argument to 'SimpleXMethodMatcher' "
192 "__init__ method should be a callable."
199 def match(self, class_type, method_name):
200 cm = re.match(self.
_class_matcher, str(class_type.unqualified().tag))
214 if not hasattr(matcher,
"match"):
215 return TypeError(
"Xmethod matcher is missing method: match")
216 if not hasattr(matcher,
"name"):
217 return TypeError(
"Xmethod matcher is missing attribute: name")
218 if not hasattr(matcher,
"enabled"):
219 return TypeError(
"Xmethod matcher is missing attribute: enabled")
220 if not isinstance(matcher.name, str):
221 return TypeError(
"Attribute 'name' of xmethod matcher is not a " "string")
222 if matcher.name.find(
";") >= 0:
223 return ValueError(
"Xmethod matcher name cannot contain ';' in it")
233 for i
in range(0, len(locus.xmethods)):
234 if locus.xmethods[i].name == name:
240 """Registers a xmethod matcher MATCHER with a LOCUS.
243 locus: The locus in which the xmethods should be registered.
244 It can be
'None' to indicate that the xmethods should be
245 registered globally. Or, it could be a gdb.Objfile
or a
246 gdb.Progspace object
in which the xmethods should be
248 matcher: The xmethod matcher to register
with the LOCUS. It
249 should be an instance of
'XMethodMatcher' class.
250 replace: If
True, replace any existing xmethod matcher
with the
251 same name
in the locus. Otherwise,
if a matcher
with the same name
252 exists
in the locus,
raise an exception.
260 locus_name =
"global"
262 locus_name = locus.filename
266 del locus.xmethods[index]
269 "Xmethod matcher already registered with "
270 "%s: %s" % (locus_name, matcher.name)
272 if gdb.parameter(
"verbose"):
273 gdb.write(
"Registering xmethod matcher '%s' with %s' ...\n")
274 locus.xmethods.insert(0, matcher)
def __init__(self, method_function, arg_types)
def __call__(self, *args)
def __init__(self, name, class_matcher, method_matcher, method_function, *arg_types)
def match(self, class_type, method_name)
def match(self, class_type, method_name)
def __call__(self, *args)
def get_result_type(self, *args)
def _validate_xmethod_matcher(matcher)
def _lookup_xmethod_matcher(locus, name)
def register_xmethod_matcher(locus, matcher, replace=False)