<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, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
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>
<link rel="stylesheet" type="text/css" href="../cs.css">
</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.12 Writing new convenience functions</h5>

<p><a name="index-writing-convenience-functions-1792"></a><a name="index-convenience-functions-in-python-1793"></a><a name="index-python-convenience-functions-1794"></a><a name="index-gdb_002eFunction-1795"></a><a name="index-Function-1796"></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; Method on Function: <b>__init__</b><var> name<a name="index-g_t_005f_005finit_005f_005f-on-Function-1797"></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; Method on Function: <b>invoke</b><var> *args<a name="index-invoke-on-Function-1798"></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.

   </body></html>