<html lang="en">
<head>
<title>Functions In Python - Debugging with GDB</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Debugging with GDB">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Python-API.html#Python-API" title="Python API">
<link rel="prev" href="Parameters-In-Python.html#Parameters-In-Python" title="Parameters In Python">
<link rel="next" href="Progspaces-In-Python.html#Progspaces-In-Python" title="Progspaces In Python">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1988-2019 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software'' and ``Free Software Needs
Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''
-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="Functions-In-Python"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Progspaces-In-Python.html#Progspaces-In-Python">Progspaces In Python</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Parameters-In-Python.html#Parameters-In-Python">Parameters In Python</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Python-API.html#Python-API">Python API</a>
<hr>
</div>

<h5 class="subsubsection">23.2.2.22 Writing new convenience functions</h5>

<p><a name="index-writing-convenience-functions-2217"></a><a name="index-convenience-functions-in-python-2218"></a><a name="index-python-convenience-functions-2219"></a><a name="index-gdb_002eFunction-2220"></a><a name="index-Function-2221"></a>You can implement new convenience functions (see <a href="Convenience-Vars.html#Convenience-Vars">Convenience Vars</a>)
in Python.  A convenience function is an instance of a subclass of the
class <code>gdb.Function</code>.

<div class="defun">
&mdash; Function: <b>Function.__init__</b> (<var>name</var>)<var><a name="index-Function_002e_005f_005finit_005f_005f-2222"></a></var><br>
<blockquote><p>The initializer for <code>Function</code> registers the new function with
<span class="sc">gdb</span>.  The argument <var>name</var> is the name of the function,
a string.  The function will be visible to the user as a convenience
variable of type <code>internal function</code>, whose name is the same as
the given <var>name</var>.

        <p>The documentation for the new function is taken from the documentation
string for the new class. 
</p></blockquote></div>

<div class="defun">
&mdash; Function: <b>Function.invoke</b> (<var>*args</var>)<var><a name="index-Function_002einvoke-2223"></a></var><br>
<blockquote><p>When a convenience function is evaluated, its arguments are converted
to instances of <code>gdb.Value</code>, and then the function's
<code>invoke</code> method is called.  Note that <span class="sc">gdb</span> does not
predetermine the arity of convenience functions.  Instead, all
available arguments are passed to <code>invoke</code>, following the
standard Python calling convention.  In particular, a convenience
function can have default values for parameters without ill effect.

        <p>The return value of this method is used as its value in the enclosing
expression.  If an ordinary Python value is returned, it is converted
to a <code>gdb.Value</code> following the usual rules. 
</p></blockquote></div>

   <p>The following code snippet shows how a trivial convenience function can
be implemented in Python:

<pre class="smallexample">     class Greet (gdb.Function):
       """Return string to greet someone.
     Takes a name as argument."""
     
       def __init__ (self):
         super (Greet, self).__init__ ("greet")
     
       def invoke (self, name):
         return "Hello, %s!" % name.string ()
     
     Greet ()
</pre>
   <p>The last line instantiates the class, and is necessary to trigger the
registration of the function with <span class="sc">gdb</span>.  Depending on how the
Python code is read into <span class="sc">gdb</span>, you may need to import the
<code>gdb</code> module explicitly.

   <p>Now you can use the function in an expression:

<pre class="smallexample">     (gdb) print $greet("Bob")
     $1 = "Hello, Bob!"
</pre>
   </body></html>