gdb: Parameters In Guile
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.
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 (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 ((guile)Parameters).
Info Catalog
gdb: Commands In Guile
gdb: Guile API
gdb: Progspaces In Guile