2008-10-16 Thiago Jung Bauermann <bauerman@br.ibm.com>

	    Tom Tromey  <tromey@redhat.com>

gdb/
	* Makefile.in (SUBDIR_PYTHON_OBS): Add python-value.o.
	(SUBDIR_PYTHON_SRCS): Add python-value.c.
	(python-value.o): New target.
	* configure.ac (CONFIG_OBS): Add python-value.o.
	(CONFIG_SRCS): Add python/python-value.c
	* configure: Regenerate.
	* python-internal.h (value_object_type): Add external declaration.
	(gdbpy_get_value_from_history, value_to_value_object,
	convert_value_from_python, gdbpy_initialize_values): Add function
	prototype.
	* python/python-value.c: New file.
	* python/python.c (GdbMethods): Add gdbpy_get_value_from_history.
	(_initialize_python): Call gdbpy_initialize_values.
	* python/python.h (values_in_python): Add external declaration.
	* value.c (value_prepend_to_list, value_remove_from_list): New
	functions.
	(preserve_values): Iterate over values_in_python list as well.
	* value.h (value_prepend_to_list, value_remove_from_list): Add
	function prototypes.

gdb/doc/
	* gdb.texinfo. (Values From Inferior): New subsubsection.

gdb/testsuite/
	* gdb.python/python-value.c: New file.
	* gdb.python/python-value.exp: New file.

2 files changed, 63 insertions, 0 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 314a6f0..c784c29 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,7 @@
+2008-10-16  Thiago Jung Bauermann  <bauerman@br.ibm.com>
+
+	* gdb.texinfo. (Values From Inferior): New subsubsection.
+
 2008-10-06  Doug Evans  <dje@google.com>
 
 	* gdb.texinfo (set debug dwarf2-die): Document it.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 67b5fac..d150466 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -17690,6 +17690,7 @@ situation, a Python @code{KeyboardInterrupt} exception is thrown.
 @menu
 * Basic Python::                Basic Python Functions.
 * Exception Handling::
+* Values From Inferior::
 @end menu
 
 @node Basic Python
@@ -17768,6 +17769,64 @@ message as its value, and the Python call stack backtrace at the
 Python statement closest to where the @value{GDBN} error occured as the
 traceback.
 
+@node Values From Inferior
+@subsubsection Values From Inferior
+@cindex values from inferior, with Python
+@cindex python, working with values from inferior
+
+@cindex @code{gdb.Value}
+@value{GDBN} provides values it obtains from the inferior program in
+an object of type @code{gdb.Value}.  @value{GDBN} uses this object
+for its internal bookkeeping of the inferior's values, and for
+fetching values when necessary.
+
+Inferior values that are simple scalars can be used directly in
+Python expressions that are valid for the value's data type.  Here's
+an example for an integer or floating-point value @code{some_val}:
+
+@smallexample
+bar = some_val + 2
+@end smallexample
+
+@noindent
+As result of this, @code{bar} will also be a @code{gdb.Value} object
+whose values are of the same type as those of @code{some_val}.
+
+Inferior values that are structures or instances of some class can
+be accessed using the Python @dfn{dictionary syntax}.  For example, if
+@code{some_val} is a @code{gdb.Value} instance holding a structure, you
+can access its @code{foo} element with:
+
+@smallexample
+bar = some_val['foo']
+@end smallexample
+
+Again, @code{bar} will also be a @code{gdb.Value} object.
+
+For pointer data types, @code{gdb.Value} provides a method for
+dereferencing the pointer to obtain the object it points to.
+
+@defmethod Value dereference
+This method returns a new @code{gdb.Value} object whose contents is
+the object pointed to by the pointer.  For example, if @code{foo} is
+a C pointer to an @code{int}, declared in your C program as
+
+@smallexample
+int *foo;
+@end smallexample
+
+@noindent
+then you can use the corresponding @code{gdb.Value} to access what
+@code{foo} points to like this:
+
+@smallexample
+bar = foo.dereference ()
+@end smallexample
+
+The result @code{bar} will be a @code{gdb.Value} object holding the
+value pointed to by @code{foo}.
+@end defmethod
+
 @node Interpreters
 @chapter Command Interpreters
 @cindex command interpreters