]> git.ipfire.org Git - thirdparty/binutils-gdb.git/commit
gdb/python: new gdb.ParameterPrefix class
authorAndrew Burgess <aburgess@redhat.com>
Sun, 13 Apr 2025 10:26:41 +0000 (11:26 +0100)
committerAndrew Burgess <aburgess@redhat.com>
Tue, 13 May 2025 14:35:26 +0000 (15:35 +0100)
commitef8bee09ef09230e4247ea962698bf5a0b4892cc
tree714ebdd1367c0b00c11ee2e9abc645ec6f857938
parenta0f6a1fd48794595e4750d581b63783fed17345f
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>
gdb/NEWS
gdb/doc/python.texi
gdb/python/lib/gdb/__init__.py
gdb/testsuite/gdb.python/py-parameter-prefix.exp [new file with mode: 0644]