[RFAv4,3/3] NEWS and documentation for default-args related concept and commands.

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

Commit Message

Philippe Waroquiers Feb. 8, 2020, 2:09 p.m. UTC
  gdb/ChangeLog
YYYY-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

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

gdb/doc/ChangeLog
YYYY-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* gdb.texinfo (Command default args): New node documenting
	'set|show default-args' and 'set|show enable-default-args'.
	(Aliases): Document the new 'DEFAULT-ARGS...' option.
---
 gdb/NEWS            |  27 ++++++++++
 gdb/doc/gdb.texinfo | 126 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 152 insertions(+), 1 deletion(-)
  

Comments

Eli Zaretskii Feb. 8, 2020, 2:46 p.m. UTC | #1
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Sat,  8 Feb 2020 15:09:13 +0100
> 
> gdb/ChangeLog
> YYYY-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>
> 
> 	* NEWS: Mention new default-args commands.  Mention change
> 	to the alias command.
> 
> gdb/doc/ChangeLog
> YYYY-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>
> 
> 	* gdb.texinfo (Command default args): New node documenting
> 	'set|show default-args' and 'set|show enable-default-args'.
> 	(Aliases): Document the new 'DEFAULT-ARGS...' option.
> ---
>  gdb/NEWS            |  27 ++++++++++
>  gdb/doc/gdb.texinfo | 126 +++++++++++++++++++++++++++++++++++++++++++-
>  2 files changed, 152 insertions(+), 1 deletion(-)
> 
> diff --git a/gdb/NEWS b/gdb/NEWS
> index d4e2e70f38..a59f9573fd 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -23,6 +23,33 @@ show exec-file-mismatch -- Show exec-file-mismatch handling (ask|warn|off).
>    whether to load the process executable file; if 'warn', just display
>    a warning; if 'off', don't attempt to detect a mismatch.
>  
> +set default-args COMMAND [DEFAULT-ARGS...]
> +show default-args [COMMAND]
> +set enable-default-args [on|off]
> +show enable-default-args
> +  GDB can now automatically prepend default args to a command or alias.

Since we seem to be splitting hair now, at least in the documentation
parts: "prepending ... args to a command" doesn't sound right.  You
actually prepend the default arguments to the command's list of
arguments, right?

> +You can tell @value{GDBN} to always add some default options or
> +arguments to a command.

Same issue here.

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

> +@smallexample
> +(@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \
> +-past-main -past-entry -full

Suggest to indent the second line of the example, to make it more
evident that it's a continuation of the previous line.

> +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

I must admit I don't understand this particular feature.  What does
"with" signify here, and what is the significance of the "--" parts?
IOW, it would help if you deconstructed this example some more,
showing what each part of it does.

> +This can be disabled using @code{set enable-default-args off}.
> +The default args of all commands are not cleared, but

"not cleared by @code{set enable-default-args off}" makes this
sentence more clear, IMO.

And one more question that popped up while reading this: when I invoke
a command that has some default args defined for it, what is recorded
in command history? the full command with the default args, or just
what I typed?

Thanks.
  

Patch

diff --git a/gdb/NEWS b/gdb/NEWS
index d4e2e70f38..a59f9573fd 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -23,6 +23,33 @@  show exec-file-mismatch -- Show exec-file-mismatch handling (ask|warn|off).
   whether to load the process executable file; if 'warn', just display
   a warning; if 'off', don't attempt to detect a mismatch.
 
+set default-args COMMAND [DEFAULT-ARGS...]
+show default-args [COMMAND]
+set enable-default-args [on|off]
+show enable-default-args
+  GDB can now automatically prepend default args to a command or alias.
+  This allows to set default arguments or options for the GDB commands
+  or define easily more specialised aliases.
+  For example, 'set default-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.
+
+* Changed commands
+
+alias [-a] [--] ALIAS = COMMAND [DEFAULT-ARGS...]
+  The alias command can now directly define default-args
+  to prepend to arguments provided by the user on the command line.
+  For example, to have a backtrace with full details, you can define an
+  alias 'bt_ALL' as 'alias bt_ALL = backtrace -entry-values both -frame-arg
+  all -past-main -past-entry -full'.
+  Alias default arguments can also use a set of nested 'with' commands,
+  e.g. 'alias pp10 = with print pretty -- with print elem 10 -- print'
+  defines the alias pp10 that will pretty print a maximum of 10 elements
+  of the given expression (if the expression is an array).
+  See 'set default-args COMMAND [DEFAULT-ARGS...]' for more
+  information about default args concept.
+
 *** Changes in GDB 9
 
 * 'thread-exited' event is now available in the annotations interface.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a2866a2833..fb3c4926c4 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1577,6 +1577,7 @@  show you the alternatives available, if there is more than one possibility).
 * Command Settings::            How to change default behavior of commands
 * Completion::                  Command completion
 * Command Options::             Command options
+* Command default args::        Automatically prepend default arguments to commands and aliases
 * Help::                        How to ask @value{GDBN} for help
 @end menu
 
@@ -1997,6 +1998,116 @@  uppercase.
 (For more on using the @code{print} command, see @ref{Data, ,Examining
 Data}.)
 
+@node Command default args
+@section Automatically prepend default 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 default-args
+@item set default-args @var{command} [@var{default-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 default-args thread apply all -ascending -c
+@end smallexample
+
+Once you have set these default 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{default-args}.
+
+Commands and their aliases do not share their default 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 default-args bt -entry-values no -frame-arguments none
+(@value{GDBP}) set default-args where -entry-values no -frame-argu scalars
+(@value{GDBP}) set default-args backtrace -entry-values no -frame-argu all
+(@value{GDBP}) set default-args info stack -entry-val both -fr all
+(@value{GDBP}) alias bt_ALL = backtrace
+(@value{GDBP}) set default-args bt_ALL -entry-values both -frame-arg all \
+-past-main -past-entry -full
+@end smallexample
+
+You can define an alias and specify its default 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}.)
+
+Default 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
+
+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 default-args @var{command}} (without giving @var{default-args})
+to clear the default args of @var{command}.
+
+@item show default-args [@var{command}]
+
+Use @code{show default-args @var{command}} to show the current values of
+the default args for @var{command}.  For example:
+@smallexample
+(@value{GDBP}) show default-args backtrace
+default-args backtrace = -entry-values no -frame-arguments all
+(@value{GDBP}) show default-args break
+default-args break = <no default args>
+@end smallexample
+
+To show all the commands and aliases that have some default args configured,
+use the command
+@code{show default-args} without giving a @var{command} argument. 
+
+@item set enable-default-args @r{[}on|off@r{]}
+@itemx show enable-default-args
+By default, @value{GDBN} will use the configured default args.
+This can be disabled using @code{set enable-default-args off}.
+The default args of all commands are not cleared, but
+will not be used till you do @code{set enable-default-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 default args.
+
+@end table
+
 @node Help
 @section Getting Help
 @cindex online documentation
@@ -27481,7 +27592,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} [DEFAULT-ARGS...]
 
 @end table
 
@@ -27499,6 +27610,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{default-args} for your alias.
+These @var{default-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{default-args}, see @ref{Command default args,
+,Automatically prepend default 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