23.3.3.12 Parameters In Guile

You can implement new GDB parameters using Guile ¹⁷.

There are many parameters that already exist and can be set in GDB. Two examples are: set follow-fork and set charset. Setting these parameters influences certain behavior in GDB. Similarly, you can define parameters that can be used to influence behavior in custom Guile scripts and commands.

A new parameter is defined with the make-parameter Guile function, and added to GDB with the register-parameter! Guile function. This two-step approach is taken to separate out the side-effect of adding the parameter to GDB from make-parameter.

Parameters are exposed to the user via the set and show commands. See Help.

Scheme Procedure: (make-parameter name [#:command-class command-class] [#:parameter-type parameter-type] [#:enum-list enum-list] [#:set-func set-func] [#:show-func show-func] [#:doc doc] [#:set-doc set-doc] [#:show-doc show-doc] [#:initial-value initial-value])

The argument name is the name of the new parameter. If name consists of multiple words, then the initial words are looked for as prefix parameters. An example of this can be illustrated with the set print set of parameters. If name is print foo, then print will be searched as the prefix parameter. In this case the parameter can subsequently be accessed in GDB as set print foo. If name consists of multiple words, and no prefix parameter group can be found, an exception is raised.

The result is the <gdb:parameter> object representing the parameter. The parameter is not usable until it has been registered with GDB with register-parameter!.

The rest of the arguments are optional.

The argument command-class should be one of the ‘COMMAND_’ constants (see Commands In Guile). This argument tells GDB how to categorize the new parameter in the help system. The default is COMMAND_NONE.

The argument parameter-type should be one of the ‘PARAM_’ constants defined below. This argument tells GDB the type of the new parameter; this information is used for input validation and completion. The default is PARAM_BOOLEAN.

If parameter-type is PARAM_ENUM, then enum-list must be a list of strings. These strings represent the possible values for the parameter.

If parameter-type is not PARAM_ENUM, then the presence of enum-list will cause an exception to be thrown.

The argument set-func is a function of one argument: self which is the <gdb:parameter> object representing the parameter. GDB will call this function when a parameter’s value has been changed via the set API (for example, set foo off). The value of the parameter has already been set to the new value. This function must return a string to be displayed to the user. GDB will add a trailing newline if the string is non-empty. GDB generally doesn’t print anything when a parameter is set, thus typically this function should return ‘""’. A non-empty string result should typically be used for displaying warnings and errors.

The argument show-func is a function of two arguments: self which is the <gdb:parameter> object representing the parameter, and svalue which is the string representation of the current value. GDB will call this function when a parameter’s show API has been invoked (for example, show foo). This function must return a string, and will be displayed to the user. GDB will add a trailing newline.

The argument doc is the help text for the new parameter. If there is no documentation string, a default value is used.

The argument set-doc is the help text for this parameter’s set command.

The argument show-doc is the help text for this parameter’s show command.

The argument initial-value specifies the initial value of the parameter. If it is a function, it takes one parameter, the <gdb:parameter> object and its result is used as the initial value of the parameter. The initial value must be valid for the parameter type, otherwise an exception is thrown.

Scheme Procedure: register-parameter! parameter

Add parameter, a <gdb:parameter> object, to GDB’s list of parameters. It is an error to register a parameter more than once. The result is unspecified.

Scheme Procedure: parameter? object

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

Scheme Procedure: parameter-value parameter

Return the value of parameter which may either be a <gdb:parameter> object or a string naming the parameter.

Scheme Procedure: set-parameter-value! parameter new-value

Assign parameter the value of new-value. The argument parameter must be an object of type <gdb:parameter>. GDB does validation when assignments are made.

When a new parameter is defined, its type must be specified. The available types are represented by constants defined in the gdb module:

PARAM_BOOLEAN

The value is a plain boolean. The Guile boolean values, #t and #f are the only valid values.

PARAM_AUTO_BOOLEAN

The value has three possible states: true, false, and ‘auto’. In Guile, true and false are represented using boolean constants, and ‘auto’ is represented using #:auto.

PARAM_UINTEGER

The value is an unsigned integer. The value of 0 should be interpreted to mean “unlimited”.

PARAM_ZINTEGER

The value is an integer.

PARAM_ZUINTEGER

The value is an unsigned integer.

PARAM_ZUINTEGER_UNLIMITED

The value is an integer in the range ‘[0, INT_MAX]’. A value of ‘-1’ means “unlimited”, and other negative numbers are not allowed.

PARAM_STRING

The value is a string. When the user modifies the string, any escape sequences, such as ‘\t’, ‘\f’, and octal escapes, are translated into corresponding characters and encoded into the current host charset.

PARAM_STRING_NOESCAPE

The value is a string. When the user modifies the string, escapes are passed through untranslated.

PARAM_OPTIONAL_FILENAME

The value is a either a filename (a string), or #f.

PARAM_FILENAME

The value is a filename. This is just like PARAM_STRING_NOESCAPE, but uses file names for completion.

PARAM_ENUM

The value is a string, which must be one of a collection of string constants provided when the parameter is created.