help text of aliased commands using "with"

help text of aliased commands using "with"

[Simon Sobisch]

Using aliases works fine in general; the help only works if there's a 
direct alias.

1 direct alias - nearly fine help:

(gdb) alias asdf = print
(gdb) help asdf
print, asdf, inspect, p
Print value of expression EXP.
Usage: print [[OPTION]... --] [/FMT] [EXP]
[... rest of print help]


2 alias with default arguments - perfect

(gdb) alias asdfa = print -elements unlimited -elements unlimited
(gdb) help asdfa
print, asdfa, asdf, inspect, p
  alias asdfa = print -elements unlimited -elements unlimited
Print value of expression EXP.
Usage: print [[OPTION]... --] [/FMT] [EXP]
[... rest of print help]


3 alias with potentially nested "with", seems broken

(gdb) alias -- asdfw = with print elements unlimited -- with print \
       repeats unlimited -- print
(gdb) help asdfw
with, asdfw, w
   alias asdfw = with print elements unlimited -- with print repeats 
unlimited -- print
Temporarily set SETTING to VALUE, run COMMAND, and restore SETTING.
Usage: with SETTING [VALUE] [-- COMMAND]
Usage: w SETTING [VALUE] [-- COMMAND]
With no COMMAND, repeats the last executed command.

SETTING is any setting you can change with the "set" subcommands.
E.g.:
with language pascal -- print obj
with print elements unlimited -- print obj

You can change multiple settings using nested with, and use
abbreviations for commands and/or values.  E.g.:
   w la p -- w p el u -- p obj



The second one is better than the first, as it lists the alias, too.


The third one shows that the alias is considered to be aliasing the 
"with" command, which is technically understandable, but from a 
user-point of view it is still the COMMAND that is aliased (in this case 
"print").


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.

2 Is it possible to adjust "alias --" to let its help point to the
   actual COMMAND?
   Preferably with the help for the parameters requested?

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.


Simon

Re: help text of aliased commands using "with"

[Philippe Waroquiers]

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".
      (gdb) 
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".
      >bang
      >bing
      >bong
      >end
      (gdb) 
      
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 !
      >end
      (gdb) help pretty-boum 
      Doc of the alias launching the command boum with pretty on.
      Use pretty-boum at your own risk !
      (gdb) 
      
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.


Philippe

Re: help text of aliased commands using "with"

[Simon Sobisch]

Thanks Philippe for taking the time to answer ins such a detail.
I now see that it is not really possible to document the "with" parts.

Dropping the aliases using "with" from "help with" seems to be very 
useful, similar showing the help of the aliased COMMAND when using with 
and default args as a reasonable default.

The addition of allowing aliases to get their own help (currently 
raising an error 'Command "with" is built-in.') would allow the user to 
handle this as deemed useful.
It would be nice to see those additions in GDB 13 :-)

Simon


Am 10.06.2022 um 07:36 schrieb Philippe Waroquiers:
> 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".
>        (gdb)
> 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".
>        >bang
>        >bing
>        >bong
>        >end
>        (gdb)
>        
> 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 !
>        >end
>        (gdb) help pretty-boum
>        Doc of the alias launching the command boum with pretty on.
>        Use pretty-boum at your own risk !
>        (gdb)
>        
> 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.
> 
> 
> Philippe