Re: [rfc] expose gdb values to python

[Eli Zaretskii <eliz at gnu dot org>]

> From:  Thiago Jung Bauermann <bauerman@br.ibm.com>
> Date:  Sat, 27 Sep 2008 22:18:15 -0300
> 
> > With that in mind, I think we should have as much examples and
> > specific concrete information in these sections as possible, to make
> > it easier for the reader to understand how to use these features
> > without too many detours into Python manuals.  Abstract information,
> > such as references to Python types, will not alone reach that goal.
> 
> I mostly agree, but in some cases I believe examples are not necessary
> because IMHO some basic programming skills can be assumed, and a Python
> integer is the same as an integer in any other language (I believe you are
> referencing to my Python integer example). Examples for such cases will
> most likely be obvious code snippets.
> 
> In any case, I added an example for that. If you think it's helpful, it can
> stay.
> 
> > For example, in the above paragraph, would it help to describe the
> > specific elements and methods of `gdb.Value', or give a couple of
> > examples of their use in real life?  You mention the type and address
> > of the inferior's value, but are there other useful members that the
> > reader would want to know about?  And even for these 2, what kind of
> > data types are they?
> 
> The objective of that paragraph was not to describe features of gdb.Value
> available for direct use, but rather to give to the user a rationale of the
> existence of the gdb.Value object (as opposed to having GDB return native
> Python values). There's not much to describe regarding specific elements
> and methods of gdb.Value since it has no element, and just one method which
> I explicitly list and describe.
> 
> >From your comment above, I see that my text was not clear so I tried to
> rephrase it. What do you think of this version?
> 
> >> +The following method is provided:
> >> +
> >> +@defmethod Value dereference
> >> +If the @code{gdb.Value} object is of a pointer type, you can dereference
> >> +it using the @code{dereference} method.  This gives you a new
> >> +@code{gdb.Value} object for the pointed-to contents.
> >> +@end defmethod
> > 
> > Again, a practical example of using this would be good to have.
> 
> I didn't provide an example originally because I thought that it was clear
> enough from the description what the method does and how to use it. I'm
> providing an example in this version, even though I think it's kind of
> redundant. If you think it helps, it can stay.

Thanks for working on this, the new version is an improvement.  Rather
than responding with another set of comments, I decided to rephrase
your text, interspersed with comments about noteworthy issues.

> +@node Values From Inferior
> +@subsubsection Values From Inferior
> +@cindex values from inferior

 @cindex values from inferior, with Python

(Without the Python qualifier, this index entry is too general.)

> +@cindex python, working with values from inferior in

 @cindex python, working with values from inferior

("in" is redundant.)

> +@value{GDBN} provides values it obtains from the inferior program in an
> +object of type @code{gdb.Value}.  This object is used so that @value{GDBN}
> +can keep track of information related to the value such as its type and
> +location in the inferior, and also to enable @value{GDBN} to fetch its
> +contents from the inferior only when necessary.

  @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.

(this avoids using passive voice -- "object is used ..." -- and also
makes details of no user importance opaque, to avoid questions that
have no useful answers.)

> +You don't need to be aware of such ancillary information in order to use
> +@code{gdb.Value} objects.  You can directly use them in places which make
> +sense for the type of the value they contain.  For instance, you can use
> +the value of an integer variable in the inferior as if it was a Python
> +integer variable.  For example, if @code{some_val} is a @code{gdb.Value}
> +instance holding an integer (or even a floating point value), the following
> +usage is valid:

  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}:

(point out explicitly that this describes how to work with scalar
values.)

> +@smallexample
> +bar = some_val + 2
> +@end smallexample
> +
> +@code{bar} will also be a @code{gdb.Value} object.

  @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}.

> +If the @code{gdb.Value} object is of a structure type or an instance of a
> +class, its elements and methods are provided using dictionary syntax.

  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.

This is okay.

> +The following method is provided:

  For pointer data types, @code{gdb.Value} provides a method for
  dereferencing the pointer to obtain the object it points to.

(avoid passive tense again, and make it clear how this is connected to
the rest of the section.)

> +@defmethod Value dereference
> +If the @code{gdb.Value} object is of a pointer type, you can dereference
> +it using the @code{dereference} method.  This gives you a new
> +@code{gdb.Value} object for the pointed-to contents.  For example, if
> +@code{some_val} is a @code{gdb.Value} instance holding a pointer to an
> +integer (in C, that would be @code{int *}), the statement
> +
> +@smallexample
> +bar = some_val.dereference ()
> +@end smallexample
> +
> +will make @code{bar} a @code{gdb.Value} object holding the integer pointed
> +to by @code{some_val}. @code{bar}  will be of integer type (in C, that
> +would be @code{int}).
> +@end defmethod

  @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 too 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}.

Note how the slightly modified text imposes a more clear structure on
the description: it describes 3 possible categories of data types:
scalars, structs/classes, and pointers, and gives useful information
on how to handle each one of them.

Btw, now that I've written this, I see that this begs a few questions
about other kinds of data types: arrays, strings, and C/C++ unions,
just for starters.  Would it be useful to cover them as well?  Or
maybe they are already covered by one of the above, in which case the
text should mention them as well.

Also, I don't see where we explain how to come by the gdb.Value object
in the first place.  For example, given a variable `foo', how do I
create a gdb.Value object for it?  Do I just use `foo'? i.e., is the
example above (that says "foo.dereference ()" for `foo' that is a C
pointer) valid?  This is also something non-trivial that should be
explained.

Thanks.