Parameters In Guile (Debugging with GDB)
Next: Progspaces In Guile, Previous: Commands In Guile, Up: Guile API [Contents][Index]
23.4.3.12 Parameters In Guile
You can implement new GDB parameters using Guile 20.
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. Ifname
consists of multiple words, then the initial words are looked for as prefix parameters. An example of this can be illustrated with theset print
set of parameters. Ifname
isprint foo
, thenprint
will be searched as the prefix parameter. In this case the parameter can subsequently be accessed in GDB asset print foo
. Ifname
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 withregister-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 isCOMMAND_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 isPARAM_BOOLEAN
.If
parameter-type
isPARAM_ENUM
, thenenum-list
must be a list of strings. These strings represent the possible values for the parameter.If
parameter-type
is notPARAM_ENUM
, then the presence ofenum-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 aparameter
’s value has been changed via theset
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, andsvalue
which is the string representation of the current value. GDB will call this function when aparameter
’sshow
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’sset
command.The argument
show-doc
is the help text for this parameter’sshow
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
ifobject
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 ofnew-value
. The argumentparameter
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
(20)
Note that GDB parameters must not be confused with Guile’s parameter objects (see Parameters in GNU Guile Reference Manual).
Next: Progspaces In Guile, Previous: Commands In Guile, Up: Guile API [Contents][Index]