1<html lang="en"> 2<head> 3<title>Parameters In Python - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Python-API.html#Python-API" title="Python API"> 9<link rel="prev" href="Commands-In-Python.html#Commands-In-Python" title="Commands In Python"> 10<link rel="next" href="Functions-In-Python.html#Functions-In-Python" title="Functions In Python"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988-2013 Free Software Foundation, Inc. 14 15Permission is granted to copy, distribute and/or modify this document 16under the terms of the GNU Free Documentation License, Version 1.3 or 17any later version published by the Free Software Foundation; with the 18Invariant Sections being ``Free Software'' and ``Free Software Needs 19Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 20and with the Back-Cover Texts as in (a) below. 21 22(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 23this GNU Manual. Buying copies from GNU Press supports the FSF in 24developing GNU and promoting software freedom.'' 25--> 26<meta http-equiv="Content-Style-Type" content="text/css"> 27<style type="text/css"><!-- 28 pre.display { font-family:inherit } 29 pre.format { font-family:inherit } 30 pre.smalldisplay { font-family:inherit; font-size:smaller } 31 pre.smallformat { font-family:inherit; font-size:smaller } 32 pre.smallexample { font-size:smaller } 33 pre.smalllisp { font-size:smaller } 34 span.sc { font-variant:small-caps } 35 span.roman { font-family:serif; font-weight:normal; } 36 span.sansserif { font-family:sans-serif; font-weight:normal; } 37--></style> 38<link rel="stylesheet" type="text/css" href="../cs.css"> 39</head> 40<body> 41<div class="node"> 42<a name="Parameters-In-Python"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Functions-In-Python.html#Functions-In-Python">Functions In Python</a>, 45Previous: <a rel="previous" accesskey="p" href="Commands-In-Python.html#Commands-In-Python">Commands In Python</a>, 46Up: <a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a> 47<hr> 48</div> 49 50<h5 class="subsubsection">23.2.2.16 Parameters In Python</h5> 51 52<p><a name="index-parameters-in-python-1978"></a><a name="index-python-parameters-1979"></a><a name="index-gdb_002eParameter-1980"></a><a name="index-Parameter-1981"></a>You can implement new <span class="sc">gdb</span> parameters using Python. A new 53parameter is implemented as an instance of the <code>gdb.Parameter</code> 54class. 55 56 <p>Parameters are exposed to the user via the <code>set</code> and 57<code>show</code> commands. See <a href="Help.html#Help">Help</a>. 58 59 <p>There are many parameters that already exist and can be set in 60<span class="sc">gdb</span>. Two examples are: <code>set follow fork</code> and 61<code>set charset</code>. Setting these parameters influences certain 62behavior in <span class="sc">gdb</span>. Similarly, you can define parameters that 63can be used to influence behavior in custom Python scripts and commands. 64 65<div class="defun"> 66— Function: <b>Parameter.__init__</b> (<var>name, command-class, parameter-class </var><span class="roman">[</span><var>, enum-sequence</var><span class="roman">]</span>)<var><a name="index-Parameter_002e_005f_005finit_005f_005f-1982"></a></var><br> 67<blockquote><p>The object initializer for <code>Parameter</code> registers the new 68parameter with <span class="sc">gdb</span>. This initializer is normally invoked 69from the subclass' own <code>__init__</code> method. 70 71 <p><var>name</var> is the name of the new parameter. If <var>name</var> consists 72of multiple words, then the initial words are looked for as prefix 73parameters. An example of this can be illustrated with the 74<code>set print</code> set of parameters. If <var>name</var> is 75<code>print foo</code>, then <code>print</code> will be searched as the prefix 76parameter. In this case the parameter can subsequently be accessed in 77<span class="sc">gdb</span> as <code>set print foo</code>. 78 79 <p>If <var>name</var> consists of multiple words, and no prefix parameter group 80can be found, an exception is raised. 81 82 <p><var>command-class</var> should be one of the ‘<samp><span class="samp">COMMAND_</span></samp>’ constants 83(see <a href="Commands-In-Python.html#Commands-In-Python">Commands In Python</a>). This argument tells <span class="sc">gdb</span> how to 84categorize the new parameter in the help system. 85 86 <p><var>parameter-class</var> should be one of the ‘<samp><span class="samp">PARAM_</span></samp>’ constants 87defined below. This argument tells <span class="sc">gdb</span> the type of the new 88parameter; this information is used for input validation and 89completion. 90 91 <p>If <var>parameter-class</var> is <code>PARAM_ENUM</code>, then 92<var>enum-sequence</var> must be a sequence of strings. These strings 93represent the possible values for the parameter. 94 95 <p>If <var>parameter-class</var> is not <code>PARAM_ENUM</code>, then the presence 96of a fourth argument will cause an exception to be thrown. 97 98 <p>The help text for the new parameter is taken from the Python 99documentation string for the parameter's class, if there is one. If 100there is no documentation string, a default value is used. 101</p></blockquote></div> 102 103<div class="defun"> 104— Variable: <b>Parameter.set_doc</b><var><a name="index-Parameter_002eset_005fdoc-1983"></a></var><br> 105<blockquote><p>If this attribute exists, and is a string, then its value is used as 106the help text for this parameter's <code>set</code> command. The value is 107examined when <code>Parameter.__init__</code> is invoked; subsequent changes 108have no effect. 109</p></blockquote></div> 110 111<div class="defun"> 112— Variable: <b>Parameter.show_doc</b><var><a name="index-Parameter_002eshow_005fdoc-1984"></a></var><br> 113<blockquote><p>If this attribute exists, and is a string, then its value is used as 114the help text for this parameter's <code>show</code> command. The value is 115examined when <code>Parameter.__init__</code> is invoked; subsequent changes 116have no effect. 117</p></blockquote></div> 118 119<div class="defun"> 120— Variable: <b>Parameter.value</b><var><a name="index-Parameter_002evalue-1985"></a></var><br> 121<blockquote><p>The <code>value</code> attribute holds the underlying value of the 122parameter. It can be read and assigned to just as any other 123attribute. <span class="sc">gdb</span> does validation when assignments are made. 124</p></blockquote></div> 125 126 <p>There are two methods that should be implemented in any 127<code>Parameter</code> class. These are: 128 129<div class="defun"> 130— Function: <b>Parameter.get_set_string</b> (<var>self</var>)<var><a name="index-Parameter_002eget_005fset_005fstring-1986"></a></var><br> 131<blockquote><p><span class="sc">gdb</span> will call this method when a <var>parameter</var>'s value has 132been changed via the <code>set</code> API (for example, <kbd>set foo off</kbd>). 133The <code>value</code> attribute has already been populated with the new 134value and may be used in output. This method must return a string. 135</p></blockquote></div> 136 137<div class="defun"> 138— Function: <b>Parameter.get_show_string</b> (<var>self, svalue</var>)<var><a name="index-Parameter_002eget_005fshow_005fstring-1987"></a></var><br> 139<blockquote><p><span class="sc">gdb</span> will call this method when a <var>parameter</var>'s 140<code>show</code> API has been invoked (for example, <kbd>show foo</kbd>). The 141argument <code>svalue</code> receives the string representation of the 142current value. This method must return a string. 143</p></blockquote></div> 144 145 <p>When a new parameter is defined, its type must be specified. The 146available types are represented by constants defined in the <code>gdb</code> 147module: 148 149 150<a name="index-PARAM_005fBOOLEAN-1988"></a> 151<a name="index-gdb_002ePARAM_005fBOOLEAN-1989"></a> 152<dl><dt><code>gdb.PARAM_BOOLEAN</code><dd>The value is a plain boolean. The Python boolean values, <code>True</code> 153and <code>False</code> are the only valid values. 154 155 <p><a name="index-PARAM_005fAUTO_005fBOOLEAN-1990"></a><a name="index-gdb_002ePARAM_005fAUTO_005fBOOLEAN-1991"></a><br><dt><code>gdb.PARAM_AUTO_BOOLEAN</code><dd>The value has three possible states: true, false, and ‘<samp><span class="samp">auto</span></samp>’. In 156Python, true and false are represented using boolean constants, and 157‘<samp><span class="samp">auto</span></samp>’ is represented using <code>None</code>. 158 159 <p><a name="index-PARAM_005fUINTEGER-1992"></a><a name="index-gdb_002ePARAM_005fUINTEGER-1993"></a><br><dt><code>gdb.PARAM_UINTEGER</code><dd>The value is an unsigned integer. The value of 0 should be 160interpreted to mean “unlimited”. 161 162 <p><a name="index-PARAM_005fINTEGER-1994"></a><a name="index-gdb_002ePARAM_005fINTEGER-1995"></a><br><dt><code>gdb.PARAM_INTEGER</code><dd>The value is a signed integer. The value of 0 should be interpreted 163to mean “unlimited”. 164 165 <p><a name="index-PARAM_005fSTRING-1996"></a><a name="index-gdb_002ePARAM_005fSTRING-1997"></a><br><dt><code>gdb.PARAM_STRING</code><dd>The value is a string. When the user modifies the string, any escape 166sequences, such as ‘<samp><span class="samp">\t</span></samp>’, ‘<samp><span class="samp">\f</span></samp>’, and octal escapes, are 167translated into corresponding characters and encoded into the current 168host charset. 169 170 <p><a name="index-PARAM_005fSTRING_005fNOESCAPE-1998"></a><a name="index-gdb_002ePARAM_005fSTRING_005fNOESCAPE-1999"></a><br><dt><code>gdb.PARAM_STRING_NOESCAPE</code><dd>The value is a string. When the user modifies the string, escapes are 171passed through untranslated. 172 173 <p><a name="index-PARAM_005fOPTIONAL_005fFILENAME-2000"></a><a name="index-gdb_002ePARAM_005fOPTIONAL_005fFILENAME-2001"></a><br><dt><code>gdb.PARAM_OPTIONAL_FILENAME</code><dd>The value is a either a filename (a string), or <code>None</code>. 174 175 <p><a name="index-PARAM_005fFILENAME-2002"></a><a name="index-gdb_002ePARAM_005fFILENAME-2003"></a><br><dt><code>gdb.PARAM_FILENAME</code><dd>The value is a filename. This is just like 176<code>PARAM_STRING_NOESCAPE</code>, but uses file names for completion. 177 178 <p><a name="index-PARAM_005fZINTEGER-2004"></a><a name="index-gdb_002ePARAM_005fZINTEGER-2005"></a><br><dt><code>gdb.PARAM_ZINTEGER</code><dd>The value is an integer. This is like <code>PARAM_INTEGER</code>, except 0 179is interpreted as itself. 180 181 <p><a name="index-PARAM_005fENUM-2006"></a><a name="index-gdb_002ePARAM_005fENUM-2007"></a><br><dt><code>gdb.PARAM_ENUM</code><dd>The value is a string, which must be one of a collection string 182constants provided when the parameter is created. 183</dl> 184 185 </body></html> 186 187