diff options
| author | Tom Tromey <tromey@adacore.com> | 2024-07-23 10:01:39 -0600 |
|---|---|---|
| committer | Tom Tromey <tromey@adacore.com> | 2024-07-23 11:15:01 -0600 |
| commit | fa8c46f5adeddedc492534302057deb7fcf1939a (patch) | |
| tree | 042c6e6981f57b1f7fa326b42e02ff346e807046 /gdb | |
| parent | 5a2f7d248a50a868152cb357dd05ebcd860ac244 (diff) | |
| download | fsf-binutils-gdb-fa8c46f5adeddedc492534302057deb7fcf1939a.zip fsf-binutils-gdb-fa8c46f5adeddedc492534302057deb7fcf1939a.tar.gz fsf-binutils-gdb-fa8c46f5adeddedc492534302057deb7fcf1939a.tar.bz2 | |
Refine the 'define' documentation
A while ago, an AdaCore user reported some difficulties with the
'define' command. While some of these difficulties are intrinsic, or
at least difficult to change, it seemed sensible to document a couple
of the typical problems -- and to make the text describing argument
substitution a bit more prominent.
Approved-By: Eli Zaretskii <eliz@gnu.org>
Diffstat (limited to 'gdb')
| -rw-r--r-- | gdb/doc/gdb.texinfo | 22 |
1 files changed, 16 insertions, 6 deletions
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index c55913c..147b8d4 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -29228,9 +29228,21 @@ files. @cindex arguments, to user-defined commands A @dfn{user-defined command} is a sequence of @value{GDBN} commands to which you assign a new name as a command. This is done with the -@code{define} command. User commands may accept an unlimited number of arguments -separated by whitespace. Arguments are accessed within the user command -via @code{$arg0@dots{}$argN}. A trivial example: +@code{define} command. + +User commands may accept an unlimited number of arguments separated by +whitespace. Arguments are accessed within the user command via +@code{$arg0@dots{}$argN}. The arguments are text substitutions, so +they may reference variables, use complex expressions, or even perform +inferior functions calls. Note, however, that this textual +substitution means that working with certain arguments is difficult. +For example, there is no way for the user to pass an argument +containing a space; and while stringifying an argument can be done +using an expression like @code{"$arg1"}, this will fail if the +argument contains a quote. For more complicated and robust commands, +we recommend writing them in Python; see @ref{CLI Commands In Python}. + +A trivial example: @smallexample define adder @@ -29247,9 +29259,7 @@ adder 1 2 3 @noindent This defines the command @code{adder}, which prints the sum of -its three arguments. Note the arguments are text substitutions, so they may -reference variables, use complex expressions, or even perform inferior -functions calls. +its three arguments. @cindex argument count in user-defined commands @cindex how many arguments (user-defined commands) |