From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 30130 invoked by alias); 28 Sep 2008 18:19:05 -0000 Received: (qmail 30117 invoked by uid 22791); 28 Sep 2008 18:19:04 -0000 X-Spam-Check-By: sourceware.org Received: from mtaout5.012.net.il (HELO mtaout5.012.net.il) (84.95.2.13) by sourceware.org (qpsmtpd/0.31) with ESMTP; Sun, 28 Sep 2008 18:18:25 +0000 Received: from HOME-C4E4A596F7 ([77.127.170.116]) by i_mtaout5.012.net.il (HyperSendmail v2004.12) with ESMTPA id <0K7X00D1P48FAT70@i_mtaout5.012.net.il> for gdb-patches@sources.redhat.com; Sun, 28 Sep 2008 21:19:28 +0300 (IDT) Date: Sun, 28 Sep 2008 18:19:00 -0000 From: Eli Zaretskii Subject: Re: [rfc] expose gdb values to python In-reply-to: X-012-Sender: halo1@inter.net.il To: Thiago Jung Bauermann Cc: gdb-patches@sources.redhat.com Reply-to: Eli Zaretskii Message-id: References: <1221199426.24580.26.camel@localhost.localdomain> <20080921042657.GB29631@caradoc.them.org> <20080925114659.GA30878@caradoc.them.org> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2008-09/txt/msg00550.txt.bz2 > From: Thiago Jung Bauermann > 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.