gdb/python: new gdb.ParameterPrefix class

This commit adds a new gdb.ParameterPrefix class to GDB's Python API.

When creating multiple gdb.Parameters, it is often desirable to group
these together under a sub-command, for example, 'set print' has lots
of parameters nested under it, like 'set print address', and 'set
print symbol'.  In the Python API the 'print' part of these commands
are called prefix commands, and are created using gdb.Command objects.

However, as parameters are set via the 'set ....' command list, and
shown through the 'show ....' command list, creating a prefix for a
parameter usually requires two prefix commands to be created, one for
the 'set' command, and one for the 'show' command.

This often leads to some duplication, or at the very least, each user
will end up creating their own helper class to simplify creation of
the two prefix commands.

This commit adds a new gdb.ParameterPrefix class.  Creating a single
instance of this class will create both the 'set' and 'show' prefix
commands, which can then be used while creating the gdb.Parameter.

Here is an example of it in use:

  gdb.ParameterPrefix('my-prefix', gdb.COMMAND_NONE)

This adds 'set my-prefix' and 'show my-prefix', both of which are
prefix commands.  The user can then add gdb.Parameter objects under
these prefixes.

The gdb.ParameterPrefix initialise method also supports documentation
strings, so we can write:

  gdb.ParameterPrefix('my-prefix', gdb.COMMAND_NONE,
      "Configuration setting relating to my special extension.")

which will set the documentation string for the prefix command.

Also, it is possible to support prefix commands that use the `invoke`
functionality to handle unknown sub-commands.  This is done by
sub-classing gdb.ParameterPrefix and overriding either 'invoke_set' or
'invoke_show' to handle the 'set' or 'show' prefix command
respectively.

Reviewed-By: Eli Zaretskii <[email protected]>

Author: T-J-Teru

gdb/NEWS

@@ -144,6 +144,10 @@ info threads [-gid] [-stopped] [-running] [ID]...
      sub-class to the empty string, means GDB will only display the
      set_doc or show_doc strings in the set/show help output.
 
+  ** New gdb.ParameterPrefix class.  This can be used to create 'set'
+     and 'show' gdb.Command prefixes, suitable for use with new
+     gdb.Parameters.
+
 * Guile API
 
   ** New type <gdb:color> for dealing with colors.

gdb/doc/python.texi

@@ -4558,6 +4558,7 @@ documentation string is provided, the default value @samp{This command
 is not documented.} is used.
 @end defun
 
+@anchor{Command.dont_repeat}
 @cindex don't repeat Python command
 @defun Command.dont_repeat ()
 By default, a @value{GDBN} command is repeated when the user enters a
@@ -4568,6 +4569,7 @@ exception).  This is similar to the user command @code{dont-repeat},
 see @ref{Define, dont-repeat}.
 @end defun
 
+@anchor{Command.invoke}
 @defun Command.invoke (argument, from_tty)
 This method is called by @value{GDBN} when this command is invoked.
 
@@ -5260,6 +5262,99 @@ constants provided when the parameter is created.
 The value is @code{gdb.Color} instance.
 @end table
 
+When creating multiple new parameters using @code{gdb.Parameter}, it
+is often desirable to create a prefix command that can be used to
+group related parameters together, for example, if you wished to add
+the parameters @kbd{plugin-name feature-1} and @kbd{plugin-name
+feature-2}, then the @kbd{plugin-name} would need to be a prefix
+command (@pxref{CLI Commands In Python}).
+
+However, when creating parameters, you will almost always need to
+create two prefix commands, one as a @kbd{set} sub-command, and one as
+a @kbd{show} sub-command.  @value{GDBN} provides the
+@code{gdb.ParameterPrefix} helper class to make creation of these two
+prefixes easier.
+
+@defun ParameterPrefix.__init__ (name, command_class, doc = @code{None})
+The object initializer for @code{ParameterPrefix} registers two new
+@code{gdb.Command} prefixes, one as a @kbd{set} sub-command, and the
+other as a @kbd{show} sub-command.
+
+@var{name}, a string, is the name of the new prefix, without either
+@kbd{set} or @kbd{show}, similar to the @var{name} passed to
+@code{gdb.Parameter} (@pxref{Parameters In Python}).  For example, to
+create the prefixes @kbd{set plugin-name} and @kbd{show plugin-name},
+you would pass the string @kbd{plugin-name}.
+
+@var{command_class} should be one of the @samp{COMMAND_} constants
+(@pxref{CLI Commands In Python}).  This argument tells @value{GDBN} how to
+categorize the new parameter prefixes in the help system.
+
+There are a number of ways in which the help text for the two new
+prefix commands can be provided.  If the @var{doc} parameter is not
+@code{None}, then this will be used as the documentation string for
+both prefix commands.
+
+If @var{doc} is @code{None}, but @code{gdb.ParameterPrefix} has been
+sub-classed, then the prefix command documentation will be taken from
+sub-classes documentation string (i.e., the @code{__doc__} attribute).
+
+If @var{doc} is @code{None}, and there is no @code{__doc__} string,
+then the default value @samp{This command is not documented.} is used.
+
+When writing the help text, keep in mind that the same text is used
+for both the @kbd{set} and @kbd{show} prefix commands.
+@end defun
+
+@defun ParameterPrefix.invoke_set (argument, from_tty)
+If a sub-class defines this method, then @value{GDBN} will call this
+when the prefix command is used with an unknown sub-command.  The
+@var{argument} and @var{from_tty} parameters are the same as for
+@code{gdb.Command.invoke} (@pxref{Command.invoke}).
+
+If this method throws an exception, it is turned into a @value{GDBN}
+@code{error} call.  Otherwise, the return value is ignored.
+
+It is not required that a @code{ParameterPrefix} sub-class override
+this method.  Usually, a parameter prefix only exists as a means to
+group related parameters together.  @value{GDBN} handles this use case
+automatically with no need to implement @code{invoke_set}.
+@end defun
+
+@defun ParameterPrefix.invoke_show (argument, from_tty)
+This is like the @code{invoke_set} method, but for the @kbd{show}
+prefix command.  As with @code{invoke_set}, implementation of this
+method is optional, and usually not required.
+@end defun
+
+@cindex don't repeat Python command
+@defun ParameterPrefix.dont_repeat ()
+Like @code{Command.dont_repeat} (@pxref{Command.dont_repeat}), this
+can be called from @code{ParameterPrefix.invoke_set} or
+@code{ParameterPrefix.invoke_show} to prevent the prefix commands from
+being repeated.
+@end defun
+
+Here is a small example that uses @code{gdb.ParameterPrefix} along
+with @code{gdb.Parameter} to create two new parameters
+@kbd{plugin-name feature-1} and @kbd{plugin-name feature-2}.  As
+neither @code{invoke_set} or @code{invoke_show} is needed, this
+example does not sub-class @code{gdb.ParameterPrefix}:
+
+@smallexample
+class ExampleParam(gdb.Parameter):
+   def __init__ (self, name):
+      super ().__init__ (name, gdb.COMMAND_DATA, gdb.PARAM_BOOLEAN)
+      self.value = True
+
+gdb.ParameterPrefix("plugin-name", gdb.COMMAND_NONE,
+                    """An example parameter prefix.
+
+                    This groups together some parameters.""")
+ExampleParam("plugin-name feature-1")
+ExampleParam("plugin-name feature-2")
+@end smallexample
+
 @node Functions In Python
 @subsubsection Writing new convenience functions
 

gdb/python/lib/gdb/__init__.py

@@ -392,3 +392,121 @@ def _handle_missing_objfile(pspace, buildid, filename):
     return _handle_missing_files(
         pspace, "objfile", lambda h: h(pspace, buildid, filename)
     )
+
+
+class ParameterPrefix:
+    # A wrapper around gdb.Command for creating set/show prefixes.
+    #
+    # When creating a gdb.Parameter sub-classes, it is sometimes necessary
+    # to first create a gdb.Command object in order to create the needed
+    # command prefix.  However, for parameters, we actually need two
+    # prefixes, a 'set' prefix, and a 'show' prefix.  With this helper
+    # class, a single instance of this class will create both prefixes at
+    # once.
+    #
+    # It is important that this class-level documentation not be a __doc__
+    # string.  Users are expected to sub-class this ParameterPrefix class
+    # and add their own documentation.  If they don't, then GDB will
+    # generate a suitable doc string.  But, if this (parent) class has a
+    # __doc__ sting of its own, then sub-classes will inherit that __doc__
+    # string, and GDB will not understand that it needs to generate one.
+
+    class _PrefixCommand(Command):
+        """A gdb.Command used to implement both the set and show prefixes.
+
+        This documentation string is not used as the prefix command
+        documentation as it is overridden in the __init__ method below."""
+
+        # This private method is connected to the 'invoke' attribute within
+        # this _PrefixCommand object if the containing ParameterPrefix
+        # object has an invoke_set or invoke_show method.
+        #
+        # This method records within self.__delegate which _PrefixCommand
+        # object is currently active, and then calls the correct invoke
+        # method on the delegat object (the ParameterPrefix sub-class
+        # object).
+        #
+        # Recording the currently active _PrefixCommand object is important;
+        # if from the invoke method the user calls dont_repeat, then this is
+        # forwarded to the currently active _PrefixCommand object.
+        def __invoke(self, args, from_tty):
+
+            # A helper class for use as part of a Python 'with' block.
+            # Records which gdb.Command object is currently running its
+            # invoke method.
+            class MarkActiveCallback:
+                # The CMD is a _PrefixCommand object, and the DELEGATE is
+                # the ParameterPrefix class, or sub-class object.  At this
+                # point we simple record both of these within the
+                # MarkActiveCallback object.
+                def __init__(self, cmd, delegate):
+                    self.__cmd = cmd
+                    self.__delegate = delegate
+
+                # Record the currently active _PrefixCommand object within
+                # the outer ParameterPrefix sub-class object.
+                def __enter__(self):
+                    self.__delegate.active_prefix = self.__cmd
+
+                # Once the invoke method has completed, then clear the
+                # _PrefixCommand object that was stored into the outer
+                # ParameterPrefix sub-class object.
+                def __exit__(self, exception_type, exception_value, traceback):
+                    self.__delegate.active_prefix = None
+
+            # The self.__cb attribute is set when the _PrefixCommand object
+            # is created, and is either invoke_set or invoke_show within the
+            # ParameterPrefix sub-class object.
+            assert callable(self.__cb)
+
+            # Record the currently active _PrefixCommand object within the
+            # ParameterPrefix sub-class object, then call the relevant
+            # invoke method within the ParameterPrefix sub-class object.
+            with MarkActiveCallback(self, self.__delegate):
+                self.__cb(args, from_tty)
+
+        @staticmethod
+        def __find_callback(delegate, mode):
+            """The MODE is either 'set' or 'show'.  Look for an invoke_MODE method
+            on DELEGATE, if a suitable method is found, then return it, otherwise,
+            return None.
+            """
+            cb = getattr(delegate, "invoke_" + mode, None)
+            if callable(cb):
+                return cb
+            return None
+
+        def __init__(self, mode, name, cmd_class, delegate, doc=None):
+            """Setup this gdb.Command.  Mode is a string, either 'set' or 'show'.
+            NAME is the name for this prefix command, that is, the
+            words that appear after both 'set' and 'show' in the
+            command name.  CMD_CLASS is the usual enum.  And DELEGATE
+            is the gdb.ParameterPrefix object this prefix is part of.
+            """
+            assert mode == "set" or mode == "show"
+            if doc is None:
+                self.__doc__ = delegate.__doc__
+            else:
+                self.__doc__ = doc
+            self.__cb = self.__find_callback(delegate, mode)
+            self.__delegate = delegate
+            if not self.__cb is None:
+                self.invoke = self.__invoke
+            super().__init__(mode + " " + name, cmd_class, prefix=True)
+
+    def __init__(self, name, cmd_class, doc=None):
+        """Create a _PrefixCommand for both the set and show prefix commands.
+        NAME is the command name without either the leading 'set ' or
+        'show ' strings, and CMD_CLASS is the usual enum value.
+        """
+        self.active_prefix = None
+        self._set_prefix_cmd = self._PrefixCommand("set", name, cmd_class, self, doc)
+        self._show_prefix_cmd = self._PrefixCommand("show", name, cmd_class, self, doc)
+
+    # When called from within an invoke method the self.active_prefix
+    # attribute should be set to a gdb.Command sub-class (a _PrefixCommand
+    # object, see above).  Forward the dont_repeat call to this object to
+    # register the actual command as none repeating.
+    def dont_repeat(self):
+        if self.active_prefix is not None:
+            self.active_prefix.dont_repeat()