Commands In Guile - Debugging with GDB

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.

— Scheme Procedure: (make-command name [#:invoke invoke] [#:command-class command-class] [#:completer-class completer] [#:prefix? prefix] [#:doc doc-string])

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.

— Scheme Procedure: register-command! command

Add 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.

— Scheme Procedure: command? object

Return #t if object is a <gdb:command> object. Otherwise return #f.

— Scheme Procedure: dont-repeat

By default, a gdb command is repeated when the user enters a blank line at the command prompt. A command can suppress this behavior by invoking the dont-repeat function. This is similar to the user command dont-repeat, see dont-repeat.

— Scheme Procedure: string->argv string

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:
          scheme@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"")
          $1 = ("1" "2 \"3" "4 \"5" "6 '7")

— Scheme Procedure: throw-user-error message . args

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

— completer: self text word

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:

If the return value is a list, the contents of the list are used as the completions. It is up to 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.
If the return value is a <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.
All other results are treated as though there were no available completions.

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:

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:

The following code snippet shows how a trivial CLI command can be implemented in Guile:

23.3.3.11 Commands In Guile