| # Python side of the support for xmethods. |
| # Copyright (C) 2013-2015 Free Software Foundation, Inc. |
| |
| # This program is free software; you can redistribute it and/or modify |
| # it under the terms of the GNU General Public License as published by |
| # the Free Software Foundation; either version 3 of the License, or |
| # (at your option) any later version. |
| # |
| # This program is distributed in the hope that it will be useful, |
| # but WITHOUT ANY WARRANTY; without even the implied warranty of |
| # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| # GNU General Public License for more details. |
| # |
| # You should have received a copy of the GNU General Public License |
| # along with this program. If not, see <http://www.gnu.org/licenses/>. |
| |
| """Utilities for defining xmethods""" |
| |
| import gdb |
| import re |
| import sys |
| |
| |
| if sys.version_info[0] > 2: |
| # Python 3 removed basestring and long |
| basestring = str |
| long = int |
| |
| |
| class XMethod(object): |
| """Base class (or a template) for an xmethod description. |
| |
| Currently, the description requires only the 'name' and 'enabled' |
| attributes. Description objects are managed by 'XMethodMatcher' |
| objects (see below). Note that this is only a template for the |
| interface of the XMethodMatcher.methods objects. One could use |
| this class or choose to use an object which supports this exact same |
| interface. Also, an XMethodMatcher can choose not use it 'methods' |
| attribute. In such cases this class (or an equivalent) is not used. |
| |
| Attributes: |
| name: The name of the xmethod. |
| enabled: A boolean indicating if the xmethod is enabled. |
| """ |
| |
| def __init__(self, name): |
| self.name = name |
| self.enabled = True |
| |
| |
| class XMethodMatcher(object): |
| """Abstract base class for matching an xmethod. |
| |
| When looking for xmethods, GDB invokes the `match' method of a |
| registered xmethod matcher to match the object type and method name. |
| The `match' method in concrete classes derived from this class should |
| return an `XMethodWorker' object, or a list of `XMethodWorker' |
| objects if there is a match (see below for 'XMethodWorker' class). |
| |
| Attributes: |
| name: The name of the matcher. |
| enabled: A boolean indicating if the matcher is enabled. |
| methods: A sequence of objects of type 'XMethod', or objects |
| which have at least the attributes of an 'XMethod' object. |
| This list is used by the 'enable'/'disable'/'info' commands to |
| enable/disable/list the xmethods registered with GDB. See |
| the 'match' method below to know how this sequence is used. |
| This attribute is None if the matcher chooses not have any |
| xmethods managed by it. |
| """ |
| |
| def __init__(self, name): |
| """ |
| Args: |
| name: An identifying name for the xmethod or the group of |
| xmethods returned by the `match' method. |
| """ |
| self.name = name |
| self.enabled = True |
| self.methods = None |
| |
| def match(self, class_type, method_name): |
| """Match class type and method name. |
| |
| In derived classes, it should return an XMethodWorker object, or a |
| sequence of 'XMethodWorker' objects. Only those xmethod workers |
| whose corresponding 'XMethod' descriptor object is enabled should be |
| returned. |
| |
| Args: |
| class_type: The class type (gdb.Type object) to match. |
| method_name: The name (string) of the method to match. |
| """ |
| raise NotImplementedError("XMethodMatcher match") |
| |
| |
| class XMethodWorker(object): |
| """Base class for all xmethod workers defined in Python. |
| |
| An xmethod worker is an object which matches the method arguments, and |
| invokes the method when GDB wants it to. Internally, GDB first invokes the |
| 'get_arg_types' method to perform overload resolution. If GDB selects to |
| invoke this Python xmethod, then it invokes it via the overridden |
| '__call__' method. The 'get_result_type' method is used to implement |
| 'ptype' on the xmethod. |
| |
| Derived classes should override the 'get_arg_types', 'get_result_type' |
| and '__call__' methods. |
| """ |
| |
| def get_arg_types(self): |
| """Return arguments types of an xmethod. |
| |
| A sequence of gdb.Type objects corresponding to the arguments of the |
| xmethod are returned. If the xmethod takes no arguments, then 'None' |
| or an empty sequence is returned. If the xmethod takes only a single |
| argument, then a gdb.Type object or a sequence with a single gdb.Type |
| element is returned. |
| """ |
| raise NotImplementedError("XMethodWorker get_arg_types") |
| |
| def get_result_type(self, *args): |
| """Return the type of the result of the xmethod. |
| |
| Args: |
| args: Arguments to the method. Each element of the tuple is a |
| gdb.Value object. The first element is the 'this' pointer |
| value. These are the same arguments passed to '__call__'. |
| |
| Returns: |
| A gdb.Type object representing the type of the result of the |
| xmethod. |
| """ |
| raise NotImplementedError("XMethodWorker get_result_type") |
| |
| def __call__(self, *args): |
| """Invoke the xmethod. |
| |
| Args: |
| args: Arguments to the method. Each element of the tuple is a |
| gdb.Value object. The first element is the 'this' pointer |
| value. |
| |
| Returns: |
| A gdb.Value corresponding to the value returned by the xmethod. |
| Returns 'None' if the method does not return anything. |
| """ |
| raise NotImplementedError("XMethodWorker __call__") |
| |
| |
| class SimpleXMethodMatcher(XMethodMatcher): |
| """A utility class to implement simple xmethod mathers and workers. |
| |
| See the __init__ method below for information on how instances of this |
| class can be used. |
| |
| For simple classes and methods, one can choose to use this class. For |
| complex xmethods, which need to replace/implement template methods on |
| possibly template classes, one should implement their own xmethod |
| matchers and workers. See py-xmethods.py in testsuite/gdb.python |
| directory of the GDB source tree for examples. |
| """ |
| |
| class SimpleXMethodWorker(XMethodWorker): |
| def __init__(self, method_function, arg_types): |
| self._arg_types = arg_types |
| self._method_function = method_function |
| |
| def get_arg_types(self): |
| return self._arg_types |
| |
| def __call__(self, *args): |
| return self._method_function(*args) |
| |
| |
| def __init__(self, name, class_matcher, method_matcher, method_function, |
| *arg_types): |
| """ |
| Args: |
| name: Name of the xmethod matcher. |
| class_matcher: A regular expression used to match the name of the |
| class whose method this xmethod is implementing/replacing. |
| method_matcher: A regular expression used to match the name of the |
| method this xmethod is implementing/replacing. |
| method_function: A Python callable which would be called via the |
| 'invoke' method of the worker returned by the objects of this |
| class. This callable should accept the object (*this) as the |
| first argument followed by the rest of the arguments to the |
| method. All arguments to this function should be gdb.Value |
| objects. |
| arg_types: The gdb.Type objects corresponding to the arguments that |
| this xmethod takes. It can be None, or an empty sequence, |
| or a single gdb.Type object, or a sequence of gdb.Type objects. |
| """ |
| XMethodMatcher.__init__(self, name) |
| assert callable(method_function), ( |
| "The 'method_function' argument to 'SimpleXMethodMatcher' " |
| "__init__ method should be a callable.") |
| self._method_function = method_function |
| self._class_matcher = class_matcher |
| self._method_matcher = method_matcher |
| self._arg_types = arg_types |
| |
| def match(self, class_type, method_name): |
| cm = re.match(self._class_matcher, str(class_type.unqualified().tag)) |
| mm = re.match(self._method_matcher, method_name) |
| if cm and mm: |
| return SimpleXMethodMatcher.SimpleXMethodWorker( |
| self._method_function, self._arg_types) |
| |
| |
| # A helper function for register_xmethod_matcher which returns an error |
| # object if MATCHER is not having the requisite attributes in the proper |
| # format. |
| |
| def _validate_xmethod_matcher(matcher): |
| if not hasattr(matcher, "match"): |
| return TypeError("Xmethod matcher is missing method: match") |
| if not hasattr(matcher, "name"): |
| return TypeError("Xmethod matcher is missing attribute: name") |
| if not hasattr(matcher, "enabled"): |
| return TypeError("Xmethod matcher is missing attribute: enabled") |
| if not isinstance(matcher.name, basestring): |
| return TypeError("Attribute 'name' of xmethod matcher is not a " |
| "string") |
| if matcher.name.find(";") >= 0: |
| return ValueError("Xmethod matcher name cannot contain ';' in it") |
| |
| |
| # A helper function for register_xmethod_matcher which looks up an |
| # xmethod matcher with NAME in LOCUS. Returns the index of the xmethod |
| # matcher in 'xmethods' sequence attribute of the LOCUS. If NAME is not |
| # found in LOCUS, then -1 is returned. |
| |
| def _lookup_xmethod_matcher(locus, name): |
| for i in range(0, len(locus.xmethods)): |
| if locus.xmethods[i].name == name: |
| return i |
| return -1 |
| |
| |
| def register_xmethod_matcher(locus, matcher, replace=False): |
| """Registers a xmethod matcher MATCHER with a LOCUS. |
| |
| Arguments: |
| locus: The locus in which the xmethods should be registered. |
| It can be 'None' to indicate that the xmethods should be |
| registered globally. Or, it could be a gdb.Objfile or a |
| gdb.Progspace object in which the xmethods should be |
| registered. |
| matcher: The xmethod matcher to register with the LOCUS. It |
| should be an instance of 'XMethodMatcher' class. |
| replace: If True, replace any existing xmethod matcher with the |
| same name in the locus. Otherwise, if a matcher with the same name |
| exists in the locus, raise an exception. |
| """ |
| err = _validate_xmethod_matcher(matcher) |
| if err: |
| raise err |
| if not locus: |
| locus = gdb |
| if locus == gdb: |
| locus_name = "global" |
| else: |
| locus_name = locus.filename |
| index = _lookup_xmethod_matcher(locus, matcher.name) |
| if index >= 0: |
| if replace: |
| del locus.xmethods[index] |
| else: |
| raise RuntimeError("Xmethod matcher already registered with " |
| "%s: %s" % (locus_name, matcher.name)) |
| if gdb.parameter("verbose"): |
| gdb.write("Registering xmethod matcher '%s' with %s' ...\n") |
| locus.xmethods.insert(0, matcher) |