Next: Progspaces In Guile, Previous: Commands In Guile, Up: Guile API

##### 23.3.3.12 Parameters In Guile

You can implement new gdb parameters using Guile 1.

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.

#### Footnotes

[1] Note that gdb parameters must not be confused with Guile’s parameter objects (see Parameters).