Xmethod support in Python.

	* python/py-xmethods.c: New file.
	* python/py-objfile.c (objfile_object): New field 'xmethods'.
	(objfpy_dealloc): XDECREF on the new xmethods field.
	(objfpy_new, objfile_to_objfile_object): Initialize xmethods
	field.
	(objfpy_get_xmethods): New function.
	(objfile_getset): New entry 'xmethods'.
	* python/py-progspace.c (pspace_object): New field 'xmethods'.
	(pspy_dealloc): XDECREF on the new xmethods field.
	(pspy_new, pspace_to_pspace_object): Initialize	xmethods
	field.
	(pspy_get_xmethods): New function.
	(pspace_getset): New entry 'xmethods'.
	* python/python-internal.h: Add declarations for new functions.
	* python/python.c (_initialize_python): Invoke
	gdbpy_initialize_xmethods.
	* python/lib/gdb/__init__.py (xmethods): New
	attribute.
	* python/lib/gdb/xmethod.py: New file.
	* python/lib/gdb/command/xmethods.py: New file.

	testuite/
	* gdb.python/py-xmethods.cc: New testcase to test xmethods.
	* gdb.python/py-xmethods.exp: New tests to test xmethods.
	* gdb.python/py-xmethods.py: Python script supporting the
	new testcase and tests.

3 files changed, 533 insertions, 0 deletions

diff --git a/gdb/python/lib/gdb/__init__.py b/gdb/python/lib/gdb/__init__.py
index 95a76c2..557e168 100644
--- a/gdb/python/lib/gdb/__init__.py
+++ b/gdb/python/lib/gdb/__init__.py
@@ -67,6 +67,8 @@ pretty_printers = []
 
 # Initial type printers.
 type_printers = []
+# Initial xmethod matchers.
+xmethods = []
 # Initial frame filters.
 frame_filters = {}
 
diff --git a/gdb/python/lib/gdb/command/xmethods.py b/gdb/python/lib/gdb/command/xmethods.py
new file mode 100644
index 0000000..31f9cdd
--- /dev/null
+++ b/gdb/python/lib/gdb/command/xmethods.py
@@ -0,0 +1,272 @@
+# Xmethod commands.
+# Copyright 2013-2014 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/>.
+
+import gdb
+import re
+
+"""GDB commands for working with xmethods."""
+
+
+def validate_xm_regexp(part_name, regexp):
+    try:
+        return re.compile(regexp)
+    except SyntaxError:
+        raise SyntaxError("Invalid %s regexp: %s", part_name, regexp)
+
+
+def parse_xm_command_args(arg):
+    """Parses the arguments passed to a xmethod command.
+
+    Arguments:
+        arg: The argument string passed to a xmethod command.
+
+    Returns:
+        A 3-tuple: (<locus matching regular expression>,
+                    <matcher matching regular expression>,
+                    <name matching regular experession>)
+    """
+    argv = gdb.string_to_argv(arg)
+    argc = len(argv)
+    if argc > 2:
+        raise SyntaxError("Too many arguments to command.")
+    locus_regexp = ""
+    matcher_name_regexp = ""
+    xm_name_regexp = None
+    if argc >= 1:
+        locus_regexp = argv[0]
+    if argc == 2:
+        parts = argv[1].split(";", 1)
+        matcher_name_regexp = parts[0]
+        if len(parts) > 1:
+            xm_name_regexp = parts[1]
+    if xm_name_regexp:
+        name_re = validate_xm_regexp("xmethod name", xm_name_regexp)
+    else:
+        name_re = None
+    return (validate_xm_regexp("locus", locus_regexp),
+            validate_xm_regexp("matcher name", matcher_name_regexp),
+            name_re)
+
+
+def get_global_method_matchers(locus_re, matcher_re):
+    """Returns a dict of matching globally registered xmethods.
+
+    Arguments:
+        locus_re: Even though only globally registered xmethods are
+                  looked up, they will be looked up only if 'global' matches
+                  LOCUS_RE.
+        matcher_re: The regular expression matching the names of xmethods.
+
+    Returns:
+        A dict of matching globally registered xmethod matchers.  The only
+        key in the dict will be 'global'.
+    """
+    locus_str = "global"
+    xm_dict = { locus_str: [] }
+    if locus_re.match("global"):
+        xm_dict[locus_str].extend(
+            [m for m in gdb.xmethods if matcher_re.match(m.name)])
+    return xm_dict
+
+
+def get_method_matchers_in_loci(loci, locus_re, matcher_re):
+    """Returns a dict of matching registered xmethods in the LOCI.
+
+    Arguments:
+        loci: The list of loci to lookup matching xmethods in.
+        locus_re: Xmethod matchers will be looked up in a particular locus
+                  only if its filename matches the regular expression LOCUS_RE.
+        matcher_re: The regular expression to match the xmethod matcher
+                    names.
+
+    Returns:
+        A dict of matching xmethod matchers.  The keys of the dict are the
+        filenames of the loci the xmethod matchers belong to.
+    """
+    xm_dict = {}
+    for locus in loci:
+        if isinstance(locus, gdb.Progspace):
+            if (not locus_re.match(locus.filename) and
+                not locus_re.match('progspace')):
+                continue
+            locus_type = "progspace"
+        else:
+            if not locus_re.match(locus.filename):
+                continue
+            locus_type = "objfile"
+        locus_str = "%s %s" % (locus_type, locus.filename)
+        xm_dict[locus_str] = [
+            m for m in locus.xmethods if matcher_re.match(m.name)]
+    return xm_dict
+
+
+def print_xm_info(xm_dict, name_re):
+    """Print a dictionary of xmethods."""
+    def get_status_string(method):
+        if not m.enabled:
+            return " [disabled]"
+        else:
+          return ""
+
+    if not xm_dict:
+        return
+    for locus_str in xm_dict:
+        if not xm_dict[locus_str]:
+            continue
+        print ("Xmethods in %s:" % locus_str)
+        for matcher in xm_dict[locus_str]:
+            print ("  %s" % matcher.name)
+            if not matcher.methods:
+                continue
+            for m in matcher.methods:
+                if name_re is None or name_re.match(m.name):
+                    print ("    %s%s" % (m.name, get_status_string(m)))
+
+
+def set_xm_status1(xm_dict, name_re, status):
+    """Set the status (enabled/disabled) of a dictionary of xmethods."""
+    for locus_str, matchers in xm_dict.iteritems():
+        for matcher in matchers:
+            if not name_re:
+                # If the name regex is missing, then set the status of the
+                # matcher and move on.
+                matcher.enabled = status
+                continue
+            if not matcher.methods:
+                # The methods attribute could be None.  Move on.
+                continue
+            for m in matcher.methods:
+                if name_re.match(m.name):
+                    m.enabled = status
+
+
+def set_xm_status(arg, status):
+    """Set the status (enabled/disabled) of xmethods matching ARG.
+    This is a helper function for enable/disable commands.  ARG is the
+    argument string passed to the commands.
+    """
+    locus_re, matcher_re, name_re = parse_xm_command_args(arg)
+    set_xm_status1(get_global_method_matchers(locus_re, matcher_re), name_re,
+                   status)
+    set_xm_status1(
+        get_method_matchers_in_loci(
+            [gdb.current_progspace()], locus_re, matcher_re),
+        name_re,
+        status)
+    set_xm_status1(
+        get_method_matchers_in_loci(gdb.objfiles(), locus_re, matcher_re),
+        name_re,
+        status)
+
+
+class InfoXMethod(gdb.Command):
+    """GDB command to list registered xmethod matchers.
+
+    Usage: info xmethod [locus-regexp [name-regexp]]
+
+    LOCUS-REGEXP is a regular expression matching the location of the
+    xmethod matchers.  If it is omitted, all registered xmethod matchers
+    from all loci are listed.  A locus could be 'global', a regular expression
+    matching the current program space's filename, or a regular expression
+    matching filenames of objfiles.  Locus could be 'progspace' to specify that
+    only xmethods from the current progspace should be listed.
+
+    NAME-REGEXP is a regular expression matching the names of xmethod
+    matchers.  If this omitted for a specified locus, then all registered
+    xmethods in the locus are listed.  To list only a certain xmethods
+    managed by a single matcher, the name regexp can be specified as
+    matcher-name-regexp;xmethod-name-regexp.
+    """
+
+    def __init__(self):
+        super(InfoXMethod, self).__init__("info xmethod",
+                                          gdb.COMMAND_DATA)
+
+    def invoke(self, arg, from_tty):
+        locus_re, matcher_re, name_re = parse_xm_command_args(arg)
+        print_xm_info(get_global_method_matchers(locus_re, matcher_re),
+                      name_re)
+        print_xm_info(
+            get_method_matchers_in_loci(
+                [gdb.current_progspace()], locus_re, matcher_re),
+            name_re)
+        print_xm_info(
+            get_method_matchers_in_loci(gdb.objfiles(), locus_re, matcher_re),
+            name_re)
+
+
+class EnableXMethod(gdb.Command):
+    """GDB command to enable a specified (group of) xmethod(s).
+
+    Usage: enable xmethod [locus-regexp [name-regexp]]
+
+    LOCUS-REGEXP is a regular expression matching the location of the
+    xmethod matchers.  If it is omitted, all registered xmethods matchers
+    from all loci are enabled.  A locus could be 'global', a regular expression
+    matching the current program space's filename, or a regular expression
+    matching filenames of objfiles.  Locus could be 'progspace' to specify that
+    only xmethods from the current progspace should be enabled.
+
+    NAME-REGEXP is a regular expression matching the names of xmethods
+    within a given locus.  If this omitted for a specified locus, then all
+    registered xmethod matchers in the locus are enabled.  To enable only
+    a certain xmethods managed by a single matcher, the name regexp can be
+    specified as matcher-name-regexp;xmethod-name-regexp.
+    """
+
+    def __init__(self):
+        super(EnableXMethod, self).__init__("enable xmethod",
+                                            gdb.COMMAND_DATA)
+
+    def invoke(self, arg, from_tty):
+        set_xm_status(arg, True)
+
+
+class DisableXMethod(gdb.Command):
+    """GDB command to disable a specified (group of) xmethod(s).
+
+    Usage: disable xmethod [locus-regexp [name-regexp]]
+
+    LOCUS-REGEXP is a regular expression matching the location of the
+    xmethod matchers.  If it is omitted, all registered xmethod matchers
+    from all loci are disabled.  A locus could be 'global', a regular
+    expression matching the current program space's filename, or a regular
+    expression filenames of objfiles. Locus could be 'progspace' to specify
+    that only xmethods from the current progspace should be disabled.
+
+    NAME-REGEXP is a regular expression matching the names of xmethods
+    within a given locus.  If this omitted for a specified locus, then all
+    registered xmethod matchers in the locus are disabled.  To disable
+    only a certain xmethods managed by a single matcher, the name regexp
+    can be specified as matcher-name-regexp;xmethod-name-regexp.
+    """
+
+    def __init__(self):
+        super(DisableXMethod, self).__init__("disable xmethod",
+                                             gdb.COMMAND_DATA)
+
+    def invoke(self, arg, from_tty):
+        set_xm_status(arg, False)
+
+
+def register_xmethod_commands():
+    """Installs the xmethod commands."""
+    InfoXMethod()
+    EnableXMethod()
+    DisableXMethod()
+
+
+register_xmethod_commands()
diff --git a/gdb/python/lib/gdb/xmethod.py b/gdb/python/lib/gdb/xmethod.py
new file mode 100644
index 0000000..a2ef18a
--- /dev/null
+++ b/gdb/python/lib/gdb/xmethod.py
@@ -0,0 +1,259 @@
+# Python side of the support for xmethods.
+# Copyright (C) 2013-2014 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.
+
+    Derived classes should override the 'get_arg_types' 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 __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)