1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Parameters In Guile</title> 18 19<meta name="description" content="Debugging with GDB: Parameters In Guile"> 20<meta name="keywords" content="Debugging with GDB: Parameters In Guile"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Guile-API.html#Guile-API" rel="up" title="Guile API"> 29<link href="Progspaces-In-Guile.html#Progspaces-In-Guile" rel="next" title="Progspaces In Guile"> 30<link href="Commands-In-Guile.html#Commands-In-Guile" rel="previous" title="Commands In Guile"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Parameters-In-Guile"></a> 65<div class="header"> 66<p> 67Next: <a href="Progspaces-In-Guile.html#Progspaces-In-Guile" accesskey="n" rel="next">Progspaces In Guile</a>, Previous: <a href="Commands-In-Guile.html#Commands-In-Guile" accesskey="p" rel="previous">Commands In Guile</a>, Up: <a href="Guile-API.html#Guile-API" accesskey="u" rel="up">Guile API</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Parameters-In-Guile-1"></a> 71<h4 class="subsubsection">23.3.3.12 Parameters In Guile</h4> 72 73<a name="index-parameters-in-guile"></a> 74<a name="index-guile-parameters"></a> 75<a name="index-Parameter-1"></a> 76<p>You can implement new <small>GDB</small> <em>parameters</em> using Guile 77<a name="DOCF18" href="#FOOT18"><sup>18</sup></a>. 78</p> 79<p>There are many parameters that already exist and can be set in 80<small>GDB</small>. Two examples are: <code>set follow-fork</code> and 81<code>set charset</code>. Setting these parameters influences certain 82behavior in <small>GDB</small>. Similarly, you can define parameters that 83can be used to influence behavior in custom Guile scripts and commands. 84</p> 85<p>A new parameter is defined with the <code>make-parameter</code> Guile function, 86and added to <small>GDB</small> with the <code>register-parameter!</code> Guile function. 87This two-step approach is taken to separate out the side-effect of adding 88the parameter to <small>GDB</small> from <code>make-parameter</code>. 89</p> 90<p>Parameters are exposed to the user via the <code>set</code> and 91<code>show</code> commands. See <a href="Help.html#Help">Help</a>. 92</p> 93<dl> 94<dt><a name="index-_0028make_002dparameter"></a>Scheme Procedure: <strong>(make-parameter</strong> <em>name <span class="roman">[</span>#:command-class command-class<span class="roman">]</span> <span class="roman">[</span>#:parameter-type parameter-type] <span class="roman">[</span>#:enum-list enum-list<span class="roman">]</span> <span class="roman">[</span>#:set-func set-func] <span class="roman">[</span>#:show-func show-func] <span class="roman">[</span>#:doc doc] <span class="roman">[</span>#:set-doc set-doc] <span class="roman">[</span>#:show-doc show-doc] <span class="roman">[</span>#:initial-value initial-value])</em></dt> 95<dd> 96<p>The argument <var>name</var> is the name of the new parameter. If <var>name</var> 97consists of multiple words, then the initial words are looked for as prefix 98parameters. An example of this can be illustrated with the 99<code>set print</code> set of parameters. If <var>name</var> is 100<code>print foo</code>, then <code>print</code> will be searched as the prefix 101parameter. In this case the parameter can subsequently be accessed in 102<small>GDB</small> as <code>set print foo</code>. 103If <var>name</var> consists of multiple words, and no prefix parameter group 104can be found, an exception is raised. 105</p> 106<p>The result is the <code><gdb:parameter></code> object representing the parameter. 107The parameter is not usable until it has been registered with <small>GDB</small> 108with <code>register-parameter!</code>. 109</p> 110<p>The rest of the arguments are optional. 111</p> 112<p>The argument <var>command-class</var> should be one of the ‘<samp>COMMAND_</samp>’ constants 113(see <a href="Commands-In-Guile.html#Commands-In-Guile">Commands In Guile</a>). This argument tells <small>GDB</small> how to 114categorize the new parameter in the help system. 115The default is <code>COMMAND_NONE</code>. 116</p> 117<p>The argument <var>parameter-type</var> should be one of the ‘<samp>PARAM_</samp>’ constants 118defined below. This argument tells <small>GDB</small> the type of the new 119parameter; this information is used for input validation and 120completion. The default is <code>PARAM_BOOLEAN</code>. 121</p> 122<p>If <var>parameter-type</var> is <code>PARAM_ENUM</code>, then 123<var>enum-list</var> must be a list of strings. These strings 124represent the possible values for the parameter. 125</p> 126<p>If <var>parameter-type</var> is not <code>PARAM_ENUM</code>, then the presence 127of <var>enum-list</var> will cause an exception to be thrown. 128</p> 129<p>The argument <var>set-func</var> is a function of one argument: <var>self</var> which 130is the <code><gdb:parameter></code> object representing the parameter. 131<small>GDB</small> will call this function when a <var>parameter</var>’s value has 132been changed via the <code>set</code> API (for example, <kbd>set foo off</kbd>). 133The value of the parameter has already been set to the new value. 134This function must return a string to be displayed to the user. 135<small>GDB</small> will add a trailing newline if the string is non-empty. 136<small>GDB</small> generally doesn’t print anything when a parameter is set, 137thus typically this function should return ‘<samp>""</samp>’. 138A non-empty string result should typically be used for displaying warnings 139and errors. 140</p> 141<p>The argument <var>show-func</var> is a function of two arguments: <var>self</var> which 142is the <code><gdb:parameter></code> object representing the parameter, and 143<var>svalue</var> which is the string representation of the current value. 144<small>GDB</small> will call this function when a <var>parameter</var>’s 145<code>show</code> API has been invoked (for example, <kbd>show foo</kbd>). 146This function must return a string, and will be displayed to the user. 147<small>GDB</small> will add a trailing newline. 148</p> 149<p>The argument <var>doc</var> is the help text for the new parameter. 150If there is no documentation string, a default value is used. 151</p> 152<p>The argument <var>set-doc</var> is the help text for this parameter’s 153<code>set</code> command. 154</p> 155<p>The argument <var>show-doc</var> is the help text for this parameter’s 156<code>show</code> command. 157</p> 158<p>The argument <var>initial-value</var> specifies the initial value of the parameter. 159If it is a function, it takes one parameter, the <code><gdb:parameter></code> 160object and its result is used as the initial value of the parameter. 161The initial value must be valid for the parameter type, 162otherwise an exception is thrown. 163</p></dd></dl> 164 165<dl> 166<dt><a name="index-register_002dparameter_0021"></a>Scheme Procedure: <strong>register-parameter!</strong> <em>parameter</em></dt> 167<dd><p>Add <var>parameter</var>, a <code><gdb:parameter></code> object, to <small>GDB</small>’s 168list of parameters. 169It is an error to register a parameter more than once. 170The result is unspecified. 171</p></dd></dl> 172 173<dl> 174<dt><a name="index-parameter_003f"></a>Scheme Procedure: <strong>parameter?</strong> <em>object</em></dt> 175<dd><p>Return <code>#t</code> if <var>object</var> is a <code><gdb:parameter></code> object. 176Otherwise return <code>#f</code>. 177</p></dd></dl> 178 179<dl> 180<dt><a name="index-parameter_002dvalue"></a>Scheme Procedure: <strong>parameter-value</strong> <em>parameter</em></dt> 181<dd><p>Return the value of <var>parameter</var> which may either be 182a <code><gdb:parameter></code> object or a string naming the parameter. 183</p></dd></dl> 184 185<dl> 186<dt><a name="index-set_002dparameter_002dvalue_0021"></a>Scheme Procedure: <strong>set-parameter-value!</strong> <em>parameter new-value</em></dt> 187<dd><p>Assign <var>parameter</var> the value of <var>new-value</var>. 188The argument <var>parameter</var> must be an object of type <code><gdb:parameter></code>. 189<small>GDB</small> does validation when assignments are made. 190</p></dd></dl> 191 192<p>When a new parameter is defined, its type must be specified. The 193available types are represented by constants defined in the <code>gdb</code> 194module: 195</p> 196<dl compact="compact"> 197<dt><code>PARAM_BOOLEAN</code> 198<a name="index-PARAM_005fBOOLEAN-1"></a> 199</dt> 200<dd><p>The value is a plain boolean. The Guile boolean values, <code>#t</code> 201and <code>#f</code> are the only valid values. 202</p> 203</dd> 204<dt><code>PARAM_AUTO_BOOLEAN</code> 205<a name="index-PARAM_005fAUTO_005fBOOLEAN-1"></a> 206</dt> 207<dd><p>The value has three possible states: true, false, and ‘<samp>auto</samp>’. In 208Guile, true and false are represented using boolean constants, and 209‘<samp>auto</samp>’ is represented using <code>#:auto</code>. 210</p> 211</dd> 212<dt><code>PARAM_UINTEGER</code> 213<a name="index-PARAM_005fUINTEGER-1"></a> 214</dt> 215<dd><p>The value is an unsigned integer. The value of 0 should be 216interpreted to mean “unlimited”. 217</p> 218</dd> 219<dt><code>PARAM_ZINTEGER</code> 220<a name="index-PARAM_005fZINTEGER-1"></a> 221</dt> 222<dd><p>The value is an integer. 223</p> 224</dd> 225<dt><code>PARAM_ZUINTEGER</code> 226<a name="index-PARAM_005fZUINTEGER-1"></a> 227</dt> 228<dd><p>The value is an unsigned integer. 229</p> 230</dd> 231<dt><code>PARAM_ZUINTEGER_UNLIMITED</code> 232<a name="index-PARAM_005fZUINTEGER_005fUNLIMITED-1"></a> 233</dt> 234<dd><p>The value is an integer in the range ‘<samp>[0, INT_MAX]</samp>’. 235A value of ‘<samp>-1</samp>’ means “unlimited”, and other negative 236numbers are not allowed. 237</p> 238</dd> 239<dt><code>PARAM_STRING</code> 240<a name="index-PARAM_005fSTRING-1"></a> 241</dt> 242<dd><p>The value is a string. When the user modifies the string, any escape 243sequences, such as ‘<samp>\t</samp>’, ‘<samp>\f</samp>’, and octal escapes, are 244translated into corresponding characters and encoded into the current 245host charset. 246</p> 247</dd> 248<dt><code>PARAM_STRING_NOESCAPE</code> 249<a name="index-PARAM_005fSTRING_005fNOESCAPE-1"></a> 250</dt> 251<dd><p>The value is a string. When the user modifies the string, escapes are 252passed through untranslated. 253</p> 254</dd> 255<dt><code>PARAM_OPTIONAL_FILENAME</code> 256<a name="index-PARAM_005fOPTIONAL_005fFILENAME-1"></a> 257</dt> 258<dd><p>The value is a either a filename (a string), or <code>#f</code>. 259</p> 260</dd> 261<dt><code>PARAM_FILENAME</code> 262<a name="index-PARAM_005fFILENAME-1"></a> 263</dt> 264<dd><p>The value is a filename. This is just like 265<code>PARAM_STRING_NOESCAPE</code>, but uses file names for completion. 266</p> 267</dd> 268<dt><code>PARAM_ENUM</code> 269<a name="index-PARAM_005fENUM-1"></a> 270</dt> 271<dd><p>The value is a string, which must be one of a collection of string 272constants provided when the parameter is created. 273</p></dd> 274</dl> 275 276<div class="footnote"> 277<hr> 278<h4 class="footnotes-heading">Footnotes</h4> 279 280<h3><a name="FOOT18" href="#DOCF18">(18)</a></h3> 281<p>Note that <small>GDB</small> parameters must not be confused with 282Guile’s parameter objects (see <a href="http://www.gnu.org/software/guile/manual/html_node/Parameters.html#Parameters">Parameters</a> in <cite>GNU Guile 283Reference Manual</cite>).</p> 284</div> 285<hr> 286<div class="header"> 287<p> 288Next: <a href="Progspaces-In-Guile.html#Progspaces-In-Guile" accesskey="n" rel="next">Progspaces In Guile</a>, Previous: <a href="Commands-In-Guile.html#Commands-In-Guile" accesskey="p" rel="previous">Commands In Guile</a>, Up: <a href="Guile-API.html#Guile-API" accesskey="u" rel="up">Guile API</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 289</div> 290 291 292 293</body> 294</html> 295