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 <eliz@gnu.org>

1 files changed, 95 insertions, 0 deletions

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 1a2d772..7f801ab 100644
--- a/gdb/doc/python.texi
+++ b/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