Imagelibrary/binutils-gdb
1
0
Fork 1
mirror of https://github.com/bminor/binutils-gdb.git synced 2025-12-26 01:07:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Allow to document user-defined aliases.

Browse Source 
Compared to the previous version, this version fixes the comments reported by
Tom Tromey and ensures that the 'help some-user-documented-alias'
shows the alias definition to ensure the user understands this is an
alias even if specifically documented.

When using 'help ALIASNAME', GDB shows the help of the aliased command.
This is a good default behaviour.

However, GDB alias command allows to define aliases with arguments
possibly changing or tuning significantly the behaviour of
the aliased command.  In such a case, showing the help of the aliased
command might not be ideal.

This is particularly true when defining an alias as a set of
nested 'with' followed by a last command to launch, such as:
  (gdb) alias pp10 = with print pretty -- with print elements 10 -- print
Asking 'help pp10' shows the help of the 'with' command, which is
not particularly useful:
  (gdb) help pp10
  with, pp10, w
    alias pp10 = with print pretty -- with print elements 10 -- print
  Temporarily set SETTING to VALUE, run COMMAND, and restore SETTING.
  Usage: with SETTING [VALUE] [-- COMMAND]
  ....

Such an alias can now be documented by the user:
  (gdb) document pp10
  >Pretty printing an expressiong, printing 10 elements.
  >Usage: pp10 [PRINT-COMMAND-OPTIONS] EXP
  >See 'help print' for more information.
  >end
  (gdb) help pp10
    alias pp10 = with print pretty -- with print elements 10 -- print
  Pretty printing an expressiong, printing 10 elements.
  Usage: pp10 [PRINT-COMMAND-OPTIONS] EXP
  See 'help print' for more information.
  (gdb)

When a user-defined alias is documented specifically, help and apropos
use the provided alias documentation instead of the documentation of
the aliased command.

Such a documented alias is also not shown anymore in the help of the
aliased command, and the alias is not listed anymore in the help
of the aliased command.  In particular for cases such as pp10 example above,
indicating that pp10 is an alias of the 'with' command is confusing.
This commit is contained in:
Philippe Waroquiers
2022-04-18 11:21:09 +02:00
parent 8b1a24e546
commit effcf7b144
5 changed files with 146 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
gdb/cli/cli-decode.c
View File

@@ -1349,6 +1349,18 @@ fput_command_name_styled (const cmd_list_element &c, struct ui_file *stream)
prefixname.c_str (), c.name);
}
/* True if ALIAS has a user-defined documentation. */
static bool
user_documented_alias (const cmd_list_element &alias)
{
gdb_assert (alias.is_alias ());
/* Alias is user documented if it has an allocated documentation
that differs from the aliased command. */
return (alias.doc_allocated
&& strcmp (alias.doc, alias.alias_target->doc) != 0);
}
/* Print the definition of alias C using title style for alias
and aliased command. */
@@ -1364,20 +1376,22 @@ fput_alias_definition_styled (const cmd_list_element &c,
gdb_printf (stream, " %s\n", c.default_args.c_str ());
}
/* Print the definition of the aliases of CMD that have default args. */
/* Print the definition of CMD aliases not deprecated and having default args
and not specifically documented by the user. */
static void
fput_aliases_definition_styled (const cmd_list_element &cmd,
struct ui_file *stream)
{
for (const cmd_list_element &alias : cmd.aliases)
if (!alias.cmd_deprecated && !alias.default_args.empty ())
if (!alias.cmd_deprecated
&& !user_documented_alias (alias)
&& !alias.default_args.empty ())
fput_alias_definition_styled (alias, stream);
}
/* If C has one or more aliases, style print the name of C and
the name of its aliases, separated by commas.
/* If C has one or more aliases, style print the name of C and the name of its
aliases not documented specifically by the user, separated by commas.
If ALWAYS_FPUT_C_NAME, print the name of C even if it has no aliases.
If one or more names are printed, POSTFIX is printed after the last name.
*/
@@ -1389,11 +1403,11 @@ fput_command_names_styled (const cmd_list_element &c,
{
/* First, check if we are going to print something. That is, either if
ALWAYS_FPUT_C_NAME is true or if there exists at least one non-deprecated
alias. */
alias not documented specifically by the user. */
auto print_alias = [] (const cmd_list_element &alias)
{
return !alias.cmd_deprecated;
return !alias.cmd_deprecated && !user_documented_alias (alias);
};
bool print_something = always_fput_c_name;
@@ -1474,11 +1488,11 @@ apropos_cmd (struct ui_file *stream,
/* Walk through the commands. */
for (c=commandlist;c;c=c->next)
{
if (c->is_alias ())
if (c->is_alias () && !user_documented_alias (*c))
{
/* Command aliases/abbreviations are skipped to ensure we print the
doc of a command only once, when encountering the aliased
command. */
/* Command aliases/abbreviations not specifically documented by the
user are skipped to ensure we print the doc of a command only once,
when encountering the aliased command. */
continue;
}
@@ -1571,11 +1585,24 @@ help_cmd (const char *command, struct ui_file *stream)
number of this class so that the commands in the class will be
listed. */
/* If the user asked 'help somecommand' and there is no alias,
the false indicates to not output the (single) command name. */
fput_command_names_styled (*c, false, "\n", stream);
fput_aliases_definition_styled (*c, stream);
gdb_puts (c->doc, stream);
if (alias == nullptr || !user_documented_alias (*alias))
{
/* Case of a normal command, or an alias not explictly
documented by the user. */
/* If the user asked 'help somecommand' and there is no alias,
the false indicates to not output the (single) command name. */
fput_command_names_styled (*c, false, "\n", stream);
fput_aliases_definition_styled (*c, stream);
gdb_puts (c->doc, stream);
}
else
{
/* Case of an alias explictly documented by the user.
Only output the alias definition and its explicit documentation. */
fput_alias_definition_styled (*alias, stream);
fput_command_names_styled (*alias, false, "\n", stream);
gdb_puts (alias->doc, stream);
}
gdb_puts ("\n", stream);
if (!c->is_prefix () && !c->is_command_class_help ())