Re: [RFA, doc RFA] Add gdb.add_command_alias

[Doug Evans <dje at google dot com>]

On Fri, Sep 9, 2011 at 2:13 PM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Fri, ?9 Sep 2011 11:36:36 -0700 (PDT)
>> From: dje@google.com (Doug Evans)
>>
>> Per discussion on IRC, here is a patch to add support for adding
>> command aliases.
>
> I wish people would discuss such issues here, not on IRC. ?These
> discussions should be recorded, for one thing.

Whatever additional discussion one wants to have we can have here.
No worries.

> Me, I don't understand the need for this feature, especially not why
> it should be a Python-only feature. ?Moreover, why do we need to have
> this, when one can easily write a command that just calls an existing
> one, to have the same effect.

Conversely, why does gdb have cli-decode.c:add_com_alias?
IOW, it's more than just writing a command that just calls an existing one.
Python is our extension language and we want to, for example,
allow users to add new functionality to gdb that is on par with gdb's
own internal functionality.  In the case of gdb commands, take for example
the "run" and "print" commands.  There are alias commands of these ("r" and "p")
for good reasons.  This patch extends this capability to commands
created in python.

[For completeness sake,
There is still a capability that internal gdb commands have that python commands
don't: one can add an alias for more than just simple commands.
E.g.

valprint.c:2177:  add_alias_cmd ("p", "print", no_class, 1, &setlist);
valprint.c:2184:  add_alias_cmd ("p", "print", no_class, 1, &showlist);

We've been extending python incrementally, and I'm doing that here
as well.]

btw,

I've been debating whether to implement command aliases with a python
object (akin to how gdb commands are implemented with gdb.Command).
It's not clear an object-oriented approach for command aliases really
brings any functional utility to the table.  It would be consistent
with how commands are treated, at the expense of extra complexity.
I'm open to thoughts on which way to go.

I've also been debating whether to use the name define_command_alias
instead of add_command_alias.
I don't have a strong enough preference to not go with what gdb uses internally.

>> valid_cmd_name_p is more restrictive than it could be.
>> E.g. gdb allows a user-defined command named "42", but
>> "it's easier to relax restrictions than it is to impose them after the fact",
>> so I'm going with this.
>
> Sorry, I don't understand what this is about. ?I guess that was again
> discussed "on IRC" or wherever.

Actually it's just a restriction I've added on my own.
I'm not entirely comfortable with gdb's allowing one to define
user-commands like that, and I don't want to allow this
in python if I don't have to.  At least not in the first pass.
If someone comes up with a compelling argument for
relaxing what valid_cmd_name_p accepts we can cross
that bridge at that time.

>> + ? NOTE: TUI has a few special commands, +, <, >.
>> + ? We don't watch for those here. ?*/
>
> Why not? ?And what does that mean in terms of user expectations?

This is another case of not wanting to have valid_cmd_name_p
accept as legitimate names I'm not comfortable with.
At least not in the first pass.
As far as user expectation goes, I don't see a problem.
What are valid command names is documented, and the current
set of valid names is completely within reason IMO.
[I was thinking of disallowing "-foo", but didn't have a strong
enough opinion so I left it.]
Note that we *can* relax things later if a compelling
argument presents itself, I don't mind taking these particular
kinds of things one step at a time (and often prefer it).

IWBN to allow "!" be an alias for shell, for example,
but gdb currently doesn't allow it.
What special characters are valid and what are not, and why not?
That discussion needn't block this.

[For completeness sake,
Having gdb.Command validate the command name is left for another patch.
E.g., I can define a command named "!" and it will appear in "help" output,
but I can't execute it.
If/when we fix that we can relax valid_cmd_name_p: again,
I don't mind taking these particular kinds of things one step at a time.

bash$ cat foo.py
import gdb

class PlayCommand (gdb.Command):
  """Command to play with."""

  def __init__(self):
    super(PlayCommand, self).__init__("!", gdb.COMMAND_OBSCURE)

  def invoke(self, arg, from_tty):
    """GDB calls this to perform the command."""
    gdb.execute("shell %s" % arg)

PlayCommand()

class Play2Command (gdb.Command):
  """Command to play with."""

  def __init__(self):
    super(Play2Command, self).__init__("bang", gdb.COMMAND_OBSCURE)

  def invoke(self, arg, from_tty):
    """GDB calls this to perform the command."""
    gdb.execute("shell %s" % arg)

Play2Command()
bash$ gdb
(gdb) source foo.py
(gdb) help obscure
Obscure features.

List of commands:

! -- Command to play with
bang -- Command to play with
checkpoint -- Fork a duplicate process (experimental)
compare-sections -- Compare section data on target to the exec file
complete -- List the completions for the rest of the line as a command
monitor -- Send a command to the remote monitor (remote targets only)
python -- Evaluate a Python command
record -- Abbreviated form of "target record" command
record delete -- Delete the rest of execution log and start recording it anew
record goto -- Restore the program to its state at instruction number N
record restore -- Restore the execution log from a file
record save -- Save the execution log to a file
record stop -- Stop the record/replay target
restart -- Restart <n>: restore program context from a checkpoint
stop -- There is no `stop' command

Type "help" followed by command name for full documentation.
Type "apropos word" to search for commands related to "word".
Command name abbreviations are allowed if unambiguous.
(gdb) ! pwd
Undefined command: "".  Try "help".
(gdb) bang pwd
/home/dje/src/play
(gdb)

>> +This is useful, for example, when you want to be able to type a command
>> +with a long name using fewer characters, and the contraction is otherwise
>> +ambiguous. ?It can also we used when you want to give a command an alternate
> ? ? ? ? ? ? ? ? ? ? ? ? ? ^^
> "be"

Righto, thanks.

>> +@var{name} is the name of the new command.
>> [..]
>> +Command names must begin with a letter, dash or underscore,
>> +and must consist of letters, numbers, dashes and underscores.
>
> ?@var{name} is the name of the new command; it must begin with a
> ?letter, dash or underscore, and must consist of letters, numbers,
> ?dashes and underscores.

Ok.

>> +@var{command_class} should be one of the @samp{COMMAND_} constants.
>
> Please add here a cross-reference to where these constants are
> documented.

I was going to do that but since the values are documented
preceding this item on the same page,
and the existing text doesn't use a cross-reference
(and since I forgot how to label the text so that I could
cross-reference it :-))
I punted.

Here's a revised patch.

2011-09-13  Doug Evans  <dje@google.com>

        Add support for adding command aliases from python.
        * NEWS: Mention gdb.add_command_alias.
        * command.h (valid_cmd_name_p): Declare.
        * cli/cli-decode.c (valid_cmd_name_p): New function.
        * python/py-cmd.c (gdbpy_add_com_alias): New function.
        * python/python-internal.h (gdbpy_add_com_alias): Declare.
        * python/python.c (GdbMethods): Add add_command_alias.

        doc/
        * gdb.texinfo (Commands In Python): Document add_command_alias.

        testsuite/
        * gdb.python/py-cmd.exp: Add tests for gdb.add_command_alias.

Attachment: gdb-110913-add-command-alias-2.patch.txt
Description: Text document