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

Message ID 20200516171947.10507-4-philippe.waroquiers@skynet.be
State Superseded
Headers show
Series
  • Allow the user to define default args for aliases
Related show

Commit Message

Shahab Vahedi via Gdb-patches May 16, 2020, 5:19 p.m.
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'.
	(Aliases): Document the new 'DEFAULT-ARGS...' option.
	(Help): Update help aliases text and describe when full alias
	definition is provided.
---
 gdb/NEWS            |  26 ++++++++
 gdb/doc/gdb.texinfo | 146 ++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 166 insertions(+), 6 deletions(-)

-- 
2.20.1

Comments

Eli Zaretskii May 16, 2020, 5:49 p.m. | #1
> Date: Sat, 16 May 2020 19:19:47 +0200

> From: Philippe Waroquiers via Gdb-patches <gdb-patches@sourceware.org>

> 

> gdb/ChangeLog

> YYYY-MM-DD  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

> 

> 	* NEWS: Mention new default-args commands.  Mention change

> 	to the alias command.


This part is OK.

> +You can tell @value{GDBN} to always prepend some default arguments to

> +the list of arguments provided explicitely by the user when using a

                                  ^^^^^^^^^^^
"explicitly"

OK with these nits fixed.

Thanks.

Patch

diff --git a/gdb/NEWS b/gdb/NEWS
index a059fc7aa0..0c4ca5a74c 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -63,10 +63,36 @@  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 ALIAS [DEFAULT-ARGS...]
+show default-args [ALIAS]
+  GDB can now automatically prepend default arguments to the argument list
+  provided explicitely by the user when using a user-defined alias.
+  This allows to define easily more specialised aliases.
+  For example, 'set default-args myownbt -full -frame-arguments all'
+  ensures that myownbt alias will automatically use the options -full
+  -frame-arguments all, without having to retype them for each myownbt
+  invocation.
+
 tui new-layout NAME WINDOW WEIGHT [WINDOW WEIGHT]...
   Define a new TUI layout, specifying its name and the windows that
   will be displayed.
 
+* Changed commands
+
+alias [-a] [--] ALIAS = COMMAND [DEFAULT-ARGS...]
+  The alias command can now directly define default-args
+  to prepend to the argument list provided explicitely by the user.
+  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 ALIAS [DEFAULT-ARGS...]' for more
+  information about default args concept.
+
 * New targets
 
 GNU/Linux/RISC-V (gdbserver)	riscv*-*-linux*
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 8f3301259a..20fc1ebc00 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 aliases default args::        Automatically prepend default arguments to user-defined aliases
 * Help::                        How to ask @value{GDBN} for help
 @end menu
 
@@ -1997,6 +1998,120 @@  uppercase.
 (For more on using the @code{print} command, see @ref{Data, ,Examining
 Data}.)
 
+@node Command aliases default args
+@section Automatically prepend default arguments to user-defined aliases
+
+You can tell @value{GDBN} to always prepend some default arguments to
+the list of arguments provided explicitely by the user when using a
+user-defined alias.
+
+@cindex command aliases options, automatically prepend
+@cindex command aliases, default arguments
+
+@table @code
+@kindex set default-args
+@item set default-args @var{alias} [@var{default-args@dots{}}]
+
+If you repeatedly use the same arguments or options for a command, you
+can define an alias for this command and tell @value{GDBN} to
+automatically prepend these arguments or options to the list of
+arguments you type explicitely when using the alias@footnote{@value{GDBN}
+could easily accept default arguments for pre-defined commands and aliases,
+but it was deemed this would be confusing, and so is not allowed.}.
+
+For example, if you often use the command @code{thread apply all}
+specifying to work 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}) alias thread apply asc-all = thread apply all
+(@value{GDBP}) set default-args thread apply asc-all -ascending -c
+@end smallexample
+
+Once you have set these default args, any time you type
+the @code{thread apply asc-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{alias}
+and @var{default-args}.
+
+The different aliases of a command do not share their default args.
+For example, you define a new alias @code{bt_ALL} showing all possible
+information and another alias @code{bt_SMALL} showing very limited information
+using:
+@smallexample
+(@value{GDBP}) alias bt_ALL = backtrace
+(@value{GDBP}) set default-args bt_ALL -entry-values both -frame-arg all \
+   -past-main -past-entry -full
+(@value{GDBP}) alias bt_SMALL = backtrace
+(@value{GDBP}) set default-args bt_SMALL -entry-values no -frame-arg none \
+   -past-main off -past-entry off
+@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 lists 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 elements 10 -- print
+@end smallexample
+This defines the alias  @code{pp10} as being a sequence of 3 commands.
+The first part @code{with print pretty --} temporarily activates the setting
+@code{set print pretty}, then launches the command that follows the separator
+@code{--}.
+The command following the first part is also a @code{with} command that
+temporarily changes the setting @code{set print elements} to 10, then
+launches the command that follows the second separator @code{--}.
+The third part @code{print} is the command the @code{pp10} alias will launch,
+using the temporary values of the settings and the arguments explicitely given
+by the user.
+For more information about the @code{with} command usage,
+see @ref{Command Settings}.
+
+Use @code{set default-args @var{alias}} (without giving @var{default-args})
+to clear the default args of @var{alias}.
+
+@item show default-args [@var{alias}]
+
+Use @code{show default-args @var{alias}} to show the current values of
+the default args for @var{alias}.  For example:
+@smallexample
+(@value{GDBP}) show default-args bt_ALL
+default-args bt_ALL = -entry-values no -frame-arguments all
+(@value{GDBP}) show default-args mybt
+default-args mybt = <no default args>
+@end smallexample
+
+To show all the aliases that have some default args configured,
+use the command
+@code{show default-args} without giving the @var{alias} argument. 
+
+@end table
+
 @node Help
 @section Getting Help
 @cindex online documentation
@@ -2016,7 +2131,7 @@  display a short list of named classes of commands:
 (@value{GDBP}) help
 List of classes of commands:
 
-aliases -- Aliases of other commands
+aliases -- User-defined aliases of other commands
 breakpoints -- Making program stop at certain points
 data -- Examining data
 files -- Specifying and examining files
@@ -2043,8 +2158,9 @@  Command name abbreviations are allowed if unambiguous.
 Using one of the general help classes as an argument, you can get a
 list of the individual commands in that class.  If a command has
 aliases, the aliases are given after the command name, separated by
-commas.  For example, here is the help display for the class
-@code{status}:
+commas.  If an alias has default arguments, the full definition of
+the alias is given after the first line.
+For example, here is the help display for the class @code{status}:
 
 @smallexample
 (@value{GDBP}) help status
@@ -2056,7 +2172,10 @@  List of commands:
 @c to fit in smallbook page size.
 info, inf, i -- Generic command for showing things
         about the program being debugged
-info address -- Describe where symbol SYM is stored.
+info address, iamain  -- Describe where symbol SYM is stored.
+  alias iamain = info address main
+info all-registers -- List of all registers and their contents,
+        for selected stack frame.
 ...
 show, info set -- Generic command for showing things
         about the debugger
@@ -2072,6 +2191,8 @@  With a command name as @code{help} argument, @value{GDBN} displays a
 short paragraph on how to use that command.  If that command has
 one or more aliases, @value{GDBN} will display a first line with
 the command name and all its aliases separated by commas.
+This first line will be followed by the full definition of all aliases
+having default arguments.
 
 @kindex apropos
 @item apropos [-v] @var{regexp}
@@ -2092,7 +2213,7 @@  results in:
 @smallexample
 @group
 alias -- Define a new command that is an alias of an existing command
-aliases -- Aliases of other commands
+aliases -- User-defined aliases of other commands
 @end group
 @end smallexample
 
@@ -27503,7 +27624,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
 
@@ -27520,6 +27641,19 @@  of the command.  Abbreviations are not used in command completion.
 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 aliases default args,
+,Automatically prepend default arguments to user-defined 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