gdb/

2009-03-05  Tom Tromey  <tromey@redhat.com>

	Add support for convenience functions in Python.
	* Makefile.in (SUBDIR_PYTHON_OBS): Add python-function.o.
	(SUBDIR_PYTHON_SRCS): Add python-function.c.
	(python-function.o): New target.
	* eval.c: Include "python/python.h" and <ctype.h>.
	(evaluate_subexp_standard): Handle values of type
	TYPE_CODE_INTERNAL_FUNCTION.
	* gdbtypes.h (type_code): Add TYPE_CODE_INTERNAL_FUNCTION.
	* parse.c (write_exp_string): Remove duplicate word in comment.
	* python/python-function.c: New file.
	* python/python-internal.h (gdbpy_initialize_functions): Add
	prototype.
	* python/python.c (_initialize_python): Call
	gdbpy_initialize_functions.
	* valprint.c (value_check_printable): Handle values of type
	TYPE_CODE_INTERNAL_FUNCTION.
	* value.c: Include "cli/cli-decode.h".
	(internal_function): New struct.
	(functionlist, internal_fn_type): New static variables.
	(lookup_only_internalvar,
	lookup_internalvar): Add const qualifier to name argument.
	(create_internalvar): Likewise.  Initialize new field.
	(set_internal_var): Fix typo in comment.  Don't allow assignment
	to canonical variable.
	(value_create_internal_function, value_internal_function_name,
	call_internal_function, function_command, function_destroyer,
	add_internal_function): New functions.
	(_initialize_values): Create `function' placeholder command.
	Initialize internal_fn_type.
	* value.h (lookup_only_internalvar, create_internalvar,
	lookup_internalvar): Add const qualifier to name argument.
	(internal_function_fn, add_internal_function, call_internal_function,
	value_internal_function_name): Add prototypes.
	(struct internalvar) <canonical>: New field.

gdb/doc/
2008-03-05  Tom Tromey  <tromey@redhat.com>

	* gdb.texinfo (Convenience Vars): Document convenience functions.
	(Functions In Python): New node.
	(Python API): Update.

gdb/testsuite/
2009-03-05  Thiago Jung Bauermann  <bauerman@br.ibm.com>

	* gdb.python/python-function.exp: New file.

2 files changed, 80 insertions, 0 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index f6e1f57..f8ed002 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,9 @@
+2008-03-20  Tom Tromey  <tromey@redhat.com>
+
+	* gdb.texinfo (Convenience Vars): Document convenience functions.
+	(Functions In Python): New node.
+	(Python API): Update.
+
 2009-03-20  Tom Tromey  <tromey@redhat.com>
 
 	* gdb.texinfo (Character Sets): Remove obsolete text.  Document
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index af577e7..7684092 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -7436,6 +7436,20 @@ On HP-UX systems, if you refer to a function or variable name that
 begins with a dollar sign, @value{GDBN} searches for a user or system
 name first, before it searches for a convenience variable.
 
+@cindex convenience functions
+@value{GDBN} also supplies some @dfn{convenience functions}.  These
+have a syntax similar to convenience variables.  A convenience
+function can be used in an expression just like an ordinary function;
+however, a convenience function is implemented internally to
+@value{GDBN}.
+
+@table @code
+@item help function
+@kindex help function
+@cindex show all convenience functions
+Print a list of all convenience functions.
+@end table
+
 @node Registers
 @section Registers
 
@@ -18178,6 +18192,7 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
 * Exception Handling::
 * Values From Inferior::
 * Commands In Python::          Implementing new commands in Python.
+* Functions In Python::         Writing new convenience functions.
 @end menu
 
 @node Basic Python
@@ -18612,6 +18627,65 @@ registration of the command with @value{GDBN}.  Depending on how the
 Python code is read into @value{GDBN}, you may need to import the
 @code{gdb} module explicitly.
 
+@node Functions In Python
+@subsubsection Writing new convenience functions
+
+@cindex writing convenience functions
+@cindex convenience functions in python
+@cindex python convenience functions
+@tindex gdb.Function
+@tindex Function
+You can implement new convenience functions (@pxref{Convenience Vars})
+in Python.  A convenience function is an instance of a subclass of the
+class @code{gdb.Function}.
+
+@defmethod Function __init__ name
+The initializer for @code{Function} registers the new function with
+@value{GDBN}.  The argument @var{name} 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}, whose name is the same as
+the given @var{name}.
+
+The documentation for the new function is taken from the documentation
+string for the new class.
+@end defmethod
+
+@defmethod Function invoke @var{*args}
+When a convenience function is evaluated, its arguments are converted
+to instances of @code{gdb.Value}, and then the function's
+@code{invoke} method is called.  Note that @value{GDBN} does not
+predetermine the arity of convenience functions.  Instead, all
+available arguments are passed to @code{invoke}, following the
+standard Python calling convention.  In particular, a convenience
+function can have default values for parameters without ill effect.
+
+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} following the usual rules.
+@end defmethod
+
+The following code snippet shows how a trivial convenience function can
+be implemented in Python:
+
+@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 ()
+@end smallexample
+
+The last line instantiates the class, and is necessary to trigger the
+registration of the function with @value{GDBN}.  Depending on how the
+Python code is read into @value{GDBN}, you may need to import the
+@code{gdb} module explicitly.
+
 @node Interpreters
 @chapter Command Interpreters
 @cindex command interpreters