gdb/python/guile: user created prefix commands get help list

Consider GDB's builtin prefix set/show prefix sub-commands, if they
are invoked with no sub-command name then they work like this:

  (gdb) show print
  print address:  Printing of addresses is on.
  print array:  Pretty formatting of arrays is off.
  print array-indexes:  Printing of array indexes is off.
  print asm-demangle:  Demangling of C++/ObjC names in disassembly listings is off.
  ... cut lots of lines ...
  (gdb) set print
  List of set print subcommands:

  set print address -- Set printing of addresses.
  set print array -- Set pretty formatting of arrays.
  set print array-indexes -- Set printing of array indexes.
  set print asm-demangle -- Set demangling of C++/ObjC names in disassembly listings.
  ... cut lots of lines ...

  Type "help set print" followed by set print subcommand name for full documentation.
  Type "apropos word" to search for commands related to "word".
  Type "apropos -v word" for full documentation of commands related to "word".
  Command name abbreviations are allowed if unambiguous.
  (gdb)

That is 'show print' lists the values of all settings under the
'print' prefix, and 'set print' lists the help text for all settings
under the 'set print' prefix.

Now, if we try to create something similar using the Python API:

  (gdb) python gdb.ParameterPrefix("my-prefix", gdb.COMMAND_NONE)
  (gdb) python gdb.Parameter("my-prefix foo", gdb.COMMAND_OBSCURE, gdb.PARAM_BOOLEAN)
  (gdb) show my-prefix
  (gdb) set my-prefix

Neither 'show my-prefix' or 'set my-prefix' gives us the same details
relating to the sub-commands that we get with the builtin prefix
commands.

This commit aims to address this.

Currently, in cmdpy_init, when a new command is created, we always set
the commands callback function to cmdpy_function.  It is within
cmdpy_function that we spot that the command is a prefix command, and
that there is no gdb.Command.invoke method, and so return early.

This commit changes things so that the rules are now:

  1. For NON prefix commands, we continue to use cmdpy_function.
  2. For prefix commands that do have a gdb.Command.invoke
     method (i.e. can handle unknown sub-commands), continue to use
     cmdpy_function.
  3. For all other prefix commands, don't use cmdpy_function, instead
     use GDB's normal callback function for set/show prefixes.

This requires splitting the current call to add_prefix_cmd into either
a call to add_prefix_cmd, add_show_prefix_cmd, or
add_basic_prefix_cmd, as appropriate.

After these changes, we now see this:

  (gdb) python gdb.ParameterPrefix("my-prefix", gdb.COMMAND_NONE)     │
  (gdb) python gdb.Parameter("my-prefix foo", gdb.COMMAND_OBSCURE, gdb.PARAM_BOOLEAN)
  (gdb) show my-prefix                                                │
  my-prefix foo:  The current value of 'my-prefix foo' is "off".
  (gdb) set my-prefix
  List of "set my-prefix" subcommands:

  set my-prefix foo -- Set the current value of 'my-prefix foo'.

  Type "help set my-prefix" followed by subcommand name for full documentation.
  Type "apropos word" to search for commands related to "word".
  Type "apropos -v word" for full documentation of commands related to "word".
  Command name abbreviations are allowed if unambiguous.
  (gdb)

Which matches how a prefix defined within GDB would act.

I have made the same changes to the Guile API.

2 files changed, 22 insertions, 0 deletions

diff --git a/gdb/doc/guile.texi b/gdb/doc/guile.texi
index 7b3f0a9..9677229 100644
--- a/gdb/doc/guile.texi
+++ b/gdb/doc/guile.texi
@@ -1772,6 +1772,16 @@ invoking it interactively.  If this function throws an exception,
 it is turned into a @value{GDBN} @code{error} call.
 Otherwise, the return value is ignored.
 
+For non-prefix commands, @var{invoke} is required.  For prefix
+commands @var{invoke} is optional.  Only prefix commands that need to
+handle unknown sub-commands should supply @var{invoke}.
+
+For prefix commands that don't supply @var{invoke}, if the prefix
+command is used without a sub-command name then @value{GDBN} will
+display the help text for every sub-command, unless the prefix command
+is a @kbd{show} sub-command, in which case @value{GDBN} will list the
+values of all sub-commands.
+
 The argument @var{command-class} is one of the @samp{COMMAND_} constants
 defined below.  This argument tells @value{GDBN} how to categorize the
 new command in the help system.  The default is @code{COMMAND_NONE}.
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 7f801ab..8f1da60 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -4525,6 +4525,7 @@ You can implement new @value{GDBN} CLI commands in Python.  A CLI
 command is implemented using an instance of the @code{gdb.Command}
 class, most commonly using a subclass.
 
+@anchor{Command.__init__}
 @defun Command.__init__ (name, command_class @r{[}, completer_class @r{[}, prefix@r{]]})
 The object initializer for @code{Command} registers the new command
 with @value{GDBN}.  This initializer is normally invoked from the
@@ -4583,6 +4584,17 @@ that the command came from elsewhere.
 If this method throws an exception, it is turned into a @value{GDBN}
 @code{error} call.  Otherwise, the return value is ignored.
 
+For non-prefix commands (@pxref{Command.__init__}), the @code{invoke}
+method is required.  For prefix commands the @code{invoke} method is
+optional.  Only prefix commands that need to handle unknown
+sub-commands should implement the @code{invoke} method.
+
+For prefix commands that don't implement @code{invoke}, if the prefix
+command is used without a sub-command name then @value{GDBN} will
+display the help text for every sub-command, unless the prefix command
+is a @kbd{show} sub-command, in which case @value{GDBN} will list the
+values of all sub-commands.
+
 @findex gdb.string_to_argv
 To break @var{argument} up into an argv-like string use
 @code{gdb.string_to_argv}.  This function behaves identically to