[RFA,3/3] NEWS and documentation for leading-args related concept and commands.

Message ID 20190624231144.29220-4-philippe.waroquiers@skynet.be
State New, archived
Headers

Commit Message

Philippe Waroquiers June 24, 2019, 11:11 p.m. UTC
  gdb/ChangeLog
2019-06-25  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* NEWS: Mention new leading-args commands.  Mention change
	to the alias command.

gdb/doc/ChangeLog
2019-06-25  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* gdb.texinfo (Command leading args): New node documenting
	'set|show leading-args' and 'set|show enable-leading-args'.
	(Aliases): Document the new '= LEADING-ARGS...' option.
---
 gdb/NEWS            |  18 +++++++
 gdb/doc/gdb.texinfo | 121 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 138 insertions(+), 1 deletion(-)
  

Comments

Eli Zaretskii June 25, 2019, 4:33 p.m. UTC | #1
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Tue, 25 Jun 2019 01:11:44 +0200
> 
> +* Command leading args::        Automatically prepend arguments to commands and aliases

The name of the section sounds too long to me.  How about this
instead:

  * Leading Arguments::            Leading arguments to commands

> +@node Command leading args
> +@section Automatically prepend arguments to commands and aliases

Likewise here.  Also, the section name should have its words
capitalized.

> +If you repetitively use the same arguments or options for a command,
          ^^^^^^^^^^^^
"repeatedly"

> +you can tell @value{GDBN} to automatically prepend these arguments
> +or options to the arguments you type explicitely.
                                        ^^^^^^^^^^^
"explicitly"

> +@code{set enable-leading-args off}.  The leading args of all commands are not cleared, but
> +will not be used till you do @code{set enable-leading-args on}.
                             ^^
"type", not "do".  Also, please use @kbd instead of @code for commands
the user is supposed to type.

> +arguments typed explicitely on the command line.
                   ^^^^^^^^^^^
"explicitly"

Finally, please refill the text so that each line is shorter than 79
columns, otherwise it's hard to read the Texinfo source.

Thanks.
  
Philippe Waroquiers June 25, 2019, 6:22 p.m. UTC | #2
Thanks for the review.

On Tue, 2019-06-25 at 19:33 +0300, Eli Zaretskii wrote:
> > From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Date: Tue, 25 Jun 2019 01:11:44 +0200
> > 
> > +* Command leading args::        Automatically prepend arguments to commands and aliases
> 
> The name of the section sounds too long to me.  How about this
> instead:
> 
>   * Leading Arguments::            Leading arguments to commands
Effectively, it is very long.  However, it looks to me we should somehow
indicate that GDB is doing something automatically.
What about:
* Leading Arguments::            Default leading arguments to commands
?


I will fix all other comments in the next version.

Philippe


> 
> > +@node Command leading args
> > +@section Automatically prepend arguments to commands and aliases
> 
> Likewise here.  Also, the section name should have its words
> capitalized.
> 
> > +If you repetitively use the same arguments or options for a command,
> 
>           ^^^^^^^^^^^^
> "repeatedly"
> 
> > +you can tell @value{GDBN} to automatically prepend these arguments
> > +or options to the arguments you type explicitely.
> 
>                                         ^^^^^^^^^^^
> "explicitly"
> 
> > +@code{set enable-leading-args off}.  The leading args of all commands are not cleared, but
> > +will not be used till you do @code{set enable-leading-args on}.
> 
>                              ^^
> "type", not "do".  Also, please use @kbd instead of @code for commands
> the user is supposed to type.
> 
> > +arguments typed explicitely on the command line.
> 
>                    ^^^^^^^^^^^
> "explicitly"
> 
> Finally, please refill the text so that each line is shorter than 79
> columns, otherwise it's hard to read the Texinfo source.
> 
> Thanks.
  
Eli Zaretskii June 25, 2019, 6:48 p.m. UTC | #3
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: gdb-patches@sourceware.org
> Date: Tue, 25 Jun 2019 20:22:07 +0200
> 
> * Leading Arguments::            Default leading arguments to commands
> ?

Fine with me, thanks.
  

Patch

diff --git a/gdb/NEWS b/gdb/NEWS
index 2cc82e8656..2dc3fac4ee 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -46,6 +46,18 @@  pipe -d DELIM COMMAND DELIM SHELL_COMMAND
   With no COMMAND, repeat the last executed command
   and send its output to SHELL_COMMAND.
 
+set leading-args COMMAND [= LEADING-ARGS...]
+show leading-args [COMMAND]
+set enable-leading-args [on|off]
+show enable-leading-args
+  GDB can now automatically prepend leading args to a command or alias.
+  This allows to set default arguments or options for the GDB commands
+  or define easier to use aliases.
+  For example, 'set leading-args backtrace = -full -frame-arguments all'
+  ensures that backtrace will automatically use the options -full
+  -frame-arguments all, without having to retype them for each backtrace
+  command.
+
 set may-call-functions [on|off]
 show may-call-functions
   This controls whether GDB will attempt to call functions in
@@ -102,6 +114,12 @@  apropos [-v] REGEXP
   of matching commands and to use the highlight style to mark
   the documentation parts matching REGEXP.
 
+alias [-a] [--] ALIAS = COMMAND [= LEADING-ARGS...]
+  The alias command can now directly define leading-args
+  to prepend to arguments provided by the user on the command line.
+  See 'set leading-args COMMAND [= LEADING-ARGS...]' for more
+  information about leading args concept.
+
 show style
   The "show style" and its subcommands are now styling
   a style name in their output using its own style, to help
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 55be2ef692..a8ae08ccca 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1563,6 +1563,7 @@  show you the alternatives available, if there is more than one possibility).
 * Command Syntax::              How to give commands to @value{GDBN}
 * Completion::                  Command completion
 * Command Options::             Command options
+* Command leading args::        Automatically prepend arguments to commands and aliases
 * Help::                        How to ask @value{GDBN} for help
 @end menu
 
@@ -1891,6 +1892,111 @@  uppercase.
 (For more on using the @code{print} command, see @ref{Data, ,Examining
 Data}.)
 
+@node Command leading args
+@section Automatically prepend arguments to commands and aliases
+
+You can tell @value{GDBN} to always add some default options or
+arguments to a command.
+
+@cindex command options, automatically prepend
+@cindex command, default arguments
+
+@table @code
+@kindex set leading-args
+@item set leading-args @var{command} [= @var{leading-args@dots{}}]
+
+If you repetitively use the same arguments or options for a command,
+you can tell @value{GDBN} to automatically prepend these arguments
+or options to the arguments you type explicitely.
+
+For example, if you always want to have the command @code{thread apply all}
+working on the threads in ascending order and to continue in case it
+encounters an error, you can tell @value{GDBN} to automatically preprend
+the @code{-ascending} and @code{-c} options by using:
+
+@smallexample
+(@value{GDBP}) set leading-args thread apply all = -ascending -c
+@end smallexample
+
+Once you have set these leading args, any time you type
+the @code{thread apply all} followed by @code{some arguments},
+@value{GDBN} will execute  @code{thread apply all -ascending -c some arguments}.
+
+As usual, unambiguous abbreviations can be used for @var{command} and @var{leading-args}.
+
+Commands and their aliases do not share their leading args.
+So, for example, you can configure the commands @code{bt}, @code{where},
+@code{backtrace} and @code{info stack} to output different levels
+of information and define a new alias @code{bt_ALL} showing all possible information
+using:
+@smallexample
+(@value{GDBP}) set leading-args bt = -entry-values no -frame-arguments none
+(@value{GDBP}) set leading-args where = -entry-values no -frame-argu scalars
+(@value{GDBP}) set leading-args backtrace = -entry-values no -frame-argu all
+(@value{GDBP}) set leading-args info stack = -entry-val both -fr all
+(@value{GDBP}) alias bt_ALL = backtrace
+(@value{GDBP}) set leading-args bt_ALL = -entry-values both -frame-arg all \
+-past-main -past-entry -full
+@end smallexample
+
+You can define an alias and specify its leading args in one command using the shorter to type:
+@smallexample
+(@value{GDBP}) alias bt_ALL = backtrace = -entry-values both -frame-arg all \
+-past-main -past-entry -full
+@end smallexample
+(For more on using the @code{alias} command, see @ref{Aliases}.)
+
+Leading args are not limited to the arguments and options of @var{command}, but can
+specify nested commands if @var{command} accepts such a nested command as argument.
+For example, the below defines @code{faalocalsoftype} that can be used to list
+the frames having locals of a certain type, together with the matching local vars:
+@smallexample
+(@value{GDBP}) alias faalocalsoftype = frame apply all = info locals -q -t
+(@value{GDBP}) faalocalsoftype int
+#1  0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86
+i = 0
+ret = 21845
+@end smallexample
+
+@c Note: the below is referencing the 'with' command, that has still to be pushed by Pedro.
+This is also very useful to define an alias for a set of nested @code{with} commands
+to have a particular combination of temporary settings.  For example, the below
+defines the alias @code{pp10} that pretty prints an expression argument,
+with a maximum of 10 elements if the expression is a string or an array:
+@smallexample
+(@value{GDBP}) alias pp10 = with = print pretty -- with print elem 10 -- print
+@end smallexample
+
+
+Use @code{set leading-args @var{command}} (without giving @var{= LEADING-ARGS}) to clear
+the leading args of @var{command}.
+
+@item show leading-args [@var{command}]
+
+Use @code{show leading-args @var{command}} to show the current values of the leading args
+for @var{command}.  For example:
+@smallexample
+(@value{GDBP}) show leading-args backtrace
+leading-args backtrace = -entry-values no -frame-arguments all
+(@value{GDBP}) show leading-args break
+leading-args break = <no leading args>
+@end smallexample
+
+To show all the commands and aliases that have some leading args configured, use the command
+@code{show leading-args} without giving a @var{command} argument. 
+
+@item set enable-leading-args @r{[}on|off@r{]}
+@itemx show enable-leading-args
+By default, @value{GDBN} will use the configured leading args.  This can be disabled using
+@code{set enable-leading-args off}.  The leading args of all commands are not cleared, but
+will not be used till you do @code{set enable-leading-args on}.
+This can be useful in user defined commands to ensure only the specified set of options
+are used by a command launched by the user-defined command.
+You can also use this setting in the @code{with} command, to temporarily run a command
+without its possibly configured leading args.
+
+@end table
+
 @node Help
 @section Getting Help
 @cindex online documentation
@@ -26937,7 +27043,7 @@  You can define a new alias with the @samp{alias} command.
 @table @code
 
 @kindex alias
-@item alias [-a] [--] @var{ALIAS} = @var{COMMAND}
+@item alias [-a] [--] @var{ALIAS} = @var{COMMAND} [= LEADING-ARGS...]
 
 @end table
 
@@ -26955,6 +27061,19 @@  lists displayed by the @samp{help} command.
 The @samp{--} option specifies the end of options,
 and is useful when @var{ALIAS} begins with a dash.
 
+You can specify @var{leading-args} for your alias.
+These @var{leading-args} will be automatically added before the alias
+arguments typed explicitely on the command line.
+
+For example, the below defines an alias @code{btfullall} that shows all local
+variables and all frame arguments:
+@smallexample
+(@value{GDBP}) alias btfullall = backtrace = -full -frame-arguments all
+@end smallexample
+
+For more information about @var{leading-args}, see @ref{Command leading args,
+,Automatically prepend arguments to commands and aliases}
+
 Here is a simple example showing how to make an abbreviation
 of a command so that there is less to type.
 Suppose you were tired of typing @samp{disas}, the current