help text of aliased commands using "with"

Philippe Waroquiers
Fri Jun 10 05:36:45 GMT 2022

On Thu, 2022-06-09 at 11:27 +0200, Simon Sobisch via Gdb wrote:
> Questions:
> 1 Can the alias always be printed? scenario 1 misses the line
>    alias asdf = print"
>    I guess that's possibly a small bug fix.
Before aliases could have default args, the help of a command was
not showing its aliases.

When aliases could have default args, help was changed to show
also the aliases, but only the aliases that have default args.
This behavior is an explicit choice: the help first shows the
complete list of aliases (with or without default args).
It then shows the full alias definition only for aliases that have default args,
as for "simple" aliases, this line does not bring additional information.
Here is the code that implements the logic "show only aliases having default args":
      /* Print the definition of the aliases of CMD that have default args.  */
      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 ())
            fput_alias_definition_styled (alias, stream);
It would of course be trivial to remove the condition "&& !alias.default_args.empty ()".
Question is if this longer help output is really worth. At the time it was developed,
it was deemed better to not output such "simple" aliases twice.

> 2 Is it possible to adjust "alias --" to let its help point to the
>    actual COMMAND?
>    Preferably with the help for the parameters requested?
>From memory, I contemplated doing this when default args was added, but this was
not easy: one reason is because the alias is associated to "its parent
command" (the command to be executed when alias is used).
Also, default args are not typically not validated/parsed. So, the final command of
a chain of "with" is only discovered "at runtime", i.e. when alias is used.
      (gdb) alias groinch-boing-boum = with groinch on -- with boing on -- boum
      (gdb) groinch-boing-boum 
      Undefined set command: "groinch".  Try "help set".
The problem is that gdb does not really have a 'command definition language/syntax':
GDB does (mostly) not separate the parsing of a command and the execution of a command.
Parsing and execution are typically mixed. This is e.g. also visible when using
the "define" command:  
      (gdb) define boum
      Type commands for definition of "boum".
      End with a line saying just "end".
Nothing in the above was parsed or validated.
And we can define boum (including its help) after boum has been used
in a chain of "with".

> Draft output (as in scenario 2 + output of the "with" entries as shown 
> with "help set print elements unlimited"):
> (gdb) help asdfw
> print, asdfa, asdfw, asdf, inspect, p
>   alias -- asdfw = with print elements unlimited
>                 -- with print repeats unlimited
>                 print
> Print value of expression EXP.
> Usage: print [[OPTION]... --] [/FMT] [EXP]
> [... rest of print help]
>   print repeats unlimited
> Set threshold for repeated print elements.
> "unlimited" causes all elements to be individually printed.
>   print elements unlimited
> Set limit on string chars or array elements to print.
> "unlimited" causes there to be no limit.
> 3 If this isn't possible then could the help of "alias --" entries be 
> adjusted to "just show the alias? Draft output for that:
> (gdb) help asdfw
>   alias -- asdfw = with print elements unlimited
>                 -- with print repeats unlimited
>                 print
> Do "help with", "help print" for info on commands executed.
As explained above, an alias of a chain of "with" does not know that at
the end the "print" command will be executed.

I have in a corner a patch that allows to document explicitly an alias.
With this patch, you can do:
      (gdb) alias pretty-boum = with print pretty on -- boum
      (gdb) document pretty-boum 
      Type documentation for "pretty-boum".
      End with a line saying just "end".
      >Doc of the alias launching the command boum with pretty on.
      >Use pretty-boum at your own risk !
      (gdb) help pretty-boum 
      Doc of the alias launching the command boum with pretty on.
      Use pretty-boum at your own risk !
The patch is still missing gdb manual update and tests.
Also, I am thinking that maybe an explicitly documented alias
should not be put in the help output of its "parent" command
based on the assumption that an explicit doc for an alias
is an indication that it should be considered as a "quite different"
command than its parent command.

We might as well contemplate to not output the aliases that are aliasing
the "with" command.


More information about the Gdb mailing list