Next: Parameters In Guile, Previous: Writing a Guile Pretty-Printer, Up: Guile API [Contents][Index]
You can implement new GDB CLI commands in Guile. A CLI
command object is created with the make-command
Guile function,
and added to GDB with the register-command!
Guile function.
This two-step approach is taken to separate out the side-effect of adding
the command to GDB from make-command
.
There is no support for multi-line commands, that is commands that
consist of multiple lines and are terminated with end
.
The argument name
is the name of the command. If name
consists of
multiple words, then the initial words are looked for as prefix
commands. In this case, if one of the prefix commands does not exist,
an exception is raised.
The result is the <gdb:command>
object representing the command.
The command is not usable until it has been registered with GDB
with register-command!
.
The rest of the arguments are optional.
The argument invoke
is a procedure of three arguments: self
,
args
and from-tty
. The argument self
is the
<gdb:command>
object representing the command.
The argument args
is a string representing the arguments passed to
the command, after leading and trailing whitespace has been stripped.
The argument from-tty
is a boolean flag and specifies whether the
command should consider itself to have been originated from the user
invoking it interactively. If this function throws an exception,
it is turned into a GDB error
call.
Otherwise, the return value is ignored.
The argument command-class
is one of the ‘COMMAND_
’ constants
defined below. This argument tells GDB how to categorize the
new command in the help system. The default is COMMAND_NONE
.
The argument completer
is either #f
, one of the ‘COMPLETE_
’
constants defined below, or a procedure, also defined below.
This argument tells GDB how to perform completion
for this command. If not provided or if the value is #f
,
then no completion is performed on the command.
The argument prefix
is a boolean flag indicating whether the new
command is a prefix command; sub-commands of this command may be
registered.
The argument doc-string
is help text for the new command.
If no documentation string is provided, the default value “This command is
not documented.” is used.
command
, a <gdb:command>
object, to GDB’s list of commands. It is an error to register a command more than once. The result is unspecified.#t
if object
is a <gdb:command>
object. Otherwise return #f
.
dont-repeat
function. This is similar to the user command dont-repeat
, see dont-repeat.Convert a string to a list of strings split up according to GDB’s argv parsing rules. It is recommended to use this for consistency. Arguments are separated by spaces and may be quoted. Example:
[email protected](guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"") $1 = ("1" "2 \"3" "4 \"5" "6 '7")
Throw a gdb:user-error
exception.
The argument message
is the error message as a format string, like the
fmt
argument to the format
Scheme function.
See Formatted Output in GNU Guile Reference Manual.
The argument args
is a list of the optional arguments of message
.
This is used when the command detects a user error of some kind, say a bad command argument.
(gdb) guile (use-modules (gdb)) (gdb) guile (register-command! (make-command "test-user-error" #:command-class COMMAND_OBSCURE #:invoke (lambda (self arg from-tty) (throw-user-error "Bad argument ~a" arg)))) end (gdb) test-user-error ugh ERROR: Bad argument ugh
If the completer
option to make-command
is a procedure,
it takes three arguments: self
which is the <gdb:command>
object, and text
and word
which are both strings.
The argument text
holds the complete command line up to the cursor’s
location. The argument word
holds the last word of the command line;
this is computed using a word-breaking heuristic.
All forms of completion are handled by this function, that is,
the TAB
and M-?
key bindings (see Completion),
and the complete
command (see complete).
This procedure can return several kinds of values:
completer
to ensure that the
contents actually do complete the word. An empty list is
allowed, it means that there were no completions available. Only
string elements of the list are used; other elements in the
list are ignored.<gdb:iterator>
object, it is iterated over to
obtain the completions. It is up to completer-procedure
to ensure
that the results actually do complete the word. Only
string elements of the result are used; other elements in the
sequence are ignored.When a new command is registered, it will have been declared as a member of
some general class of commands. This is used to classify top-level
commands in the on-line help system; note that prefix commands are not
listed under their own category but rather that of their top-level
command. The available classifications are represented by constants
defined in the gdb
module:
COMMAND_NONE
COMMAND_RUNNING
start
, step
, and continue
are in this category. Type help running at the GDB prompt to see a list of commands in this category.COMMAND_DATA
call
, find
, and print
are in this category. Type help data at the GDB prompt to see a list of commands in this category.COMMAND_STACK
backtrace
, frame
, and return
are in this category. Type help stack at the GDB prompt to see a list of commands in this category.COMMAND_FILES
file
, list
and section
are in this category. Type help files at the GDB prompt to see a list of commands in this category.COMMAND_SUPPORT
help
, make
, and shell
are in this category. Type help support at the GDB prompt to see a list of commands in this category.COMMAND_STATUS
info
’-related command, that is, related to the state of GDB itself. For example, info
, macro
, and show
are in this category. Type help status at the GDB prompt to see a list of commands in this category.COMMAND_BREAKPOINTS
break
, clear
, and delete
are in this category. Type help breakpoints at the GDB prompt to see a list of commands in this category.COMMAND_TRACEPOINTS
trace
, actions
, and tfind
are in this category. Type help tracepoints at the GDB prompt to see a list of commands in this category.COMMAND_USER
COMMAND_OBSCURE
checkpoint
, fork
, and stop
are in this category. Type help obscure at the GDB prompt to see a list of commands in this category.COMMAND_MAINTENANCE
maintenance
and flushregs
commands are in this category. Type help internals at the GDB prompt to see a list of commands in this category.A new command can use a predefined completion function, either by
specifying it via an argument at initialization, or by returning it
from the completer
procedure. These predefined completion
constants are all defined in the gdb
module:
COMPLETE_NONE
COMPLETE_FILENAME
COMPLETE_LOCATION
COMPLETE_COMMAND
COMPLETE_SYMBOL
COMPLETE_EXPRESSION
The following code snippet shows how a trivial CLI command can be implemented in Guile:
(gdb) guile (register-command! (make-command "hello-world" #:command-class COMMAND_USER #:doc "Greet the whole world." #:invoke (lambda (self args from-tty) (display "Hello, World!\n")))) end (gdb) hello-world Hello, World!
Next: Parameters In Guile, Previous: Writing a Guile Pretty-Printer, Up: Guile API [Contents][Index]