This is the mail archive of the
archer@sourceware.org
mailing list for the Archer project.
[python] update documentation
- From: Tom Tromey <tromey at redhat dot com>
- To: Project Archer <archer at sourceware dot org>
- Date: Fri, 04 Sep 2009 11:25:01 -0600
- Subject: [python] update documentation
- Reply-to: Tom Tromey <tromey at redhat dot com>
This updates the varobj documentation to reflect current reality, to the
best of my knowledge.
Tom
2009-09-04 Tom Tromey <tromey@redhat.com>
* gdb.texinfo (GDB/MI Variable Objects): Use @value. Define
dynamic varobj. Update -var-list-children and -var-update
documentation.
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 1042303..0e92ac7 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23774,14 +23774,14 @@ how it can be used.
-enable-pretty-printing
@end smallexample
-@var{GDBN} allows Python-based visualizers to affect the output of the
+@value{GDBN} allows Python-based visualizers to affect the output of the
MI variable object commands. However, because there was no way to
implement this in a fully backward-compatible way, a front end must
request that this functionality be enabled.
Once sent, this command cannot be undone.
-Note that if Python support has not been compiled into @var{GDBN},
+Note that if Python support has not been compiled into @value{GDBN},
this command will still succeed.
@subheading The @code{-var-create} Command
@@ -23823,15 +23823,50 @@ begin with a @samp{*}), or one of the following:
@samp{$@var{regname}} --- a CPU register name
@end itemize
+A varobj's may be provided by a Python-based pretty-printer. In this
+case the varobj is known as a @dfn{dynamic varobj}. Dynamic varobjs
+have slightly different semantics in some cases. If the
+@code{-enable-pretty-printing} command is not sent, then @value{GDBN}
+will never create a dynamic varobj. This ensures backward
+compatibility for existing clients.
+
@subsubheading Result
-This operation returns the name, number of children and the type of the
-object created. Type is returned as a string as the ones generated by
-the @value{GDBN} CLI. If a fixed variable object is bound to a
-specific thread, the thread is is also printed:
+This operation returns attributes of the newly-created varobj. These
+include, but are not limited to:
+
+@table @samp
+@item name
+The name of the varobj.
+
+@item numchild
+The number of children of the varobj. This number is not necessarily
+reliable for a dynamic varobj. Instead, you must examine the
+@samp{has_more} attribute.
+
+@item value
+The varobj's scalar value. For a varobj whose type is some sort of
+aggregate (e.g., a @code{struct}), or for a dynamic varobj, this value
+will not be interesting.
+
+@item type
+The varobj's type. This is a string representation of the type, as
+would be printed by the @value{GDBN} CLI.
+
+@item thread-id
+If a fixed variable object is bound to a specific thread, then this is
+the thread's identifier.
+
+@item has_more
+For a dynamic varobj, this indicates whether there appear to be any
+children available. For a non-dynamic varobj, this will be 0.
+@end table
+
+Typical output will look like this:
@smallexample
- name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}"
+ name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}",
+ has_more="@var{has_more}"
@end smallexample
@@ -23909,6 +23944,10 @@ Returns the number of children of a variable object @var{name}:
numchild=@var{n}
@end smallexample
+Note that this number is not completely reliable for a dynamic varobj.
+It will return the current number of children, but more children may
+be available.
+
@subheading The @code{-var-list-children} Command
@findex -var-list-children
@@ -23935,6 +23974,16 @@ reset and all children will be reported. Otherwise, children starting
at @var{from} (zero-based) and ending just before @var{to} will be
reported.
+If a child range is requested, it will not affect the range of
+children reported by a future call to @code{-var-update}. For this,
+you must instead use @code{-var-set-update-range}. The intent of this
+approach is to enable a front end to implement any update approach it
+likes; for example, scrolling a view may cause the front end to
+request more children with @code{-var-list-children}, and then the
+front end could call @code{-var-set-update-range} with a different
+range to ensure that future updates are restricted to just the visible
+items.
+
For each child the following results are returned:
@table @var
@@ -23951,8 +24000,13 @@ designate access qualifiers. For these pseudo children @var{exp} is
@samp{public}, @samp{private}, or @samp{protected}. In this case the
type and value are not present.
+For a dynamic varobj, this value cannot reliably be used to form an
+expression. Also, a dynamic varobj will not report the access
+qualifying pseudo-children, regardless of the language.
+
@item numchild
-Number of children this child has.
+Number of children this child has. For a dynamic varobj, this will be
+0.
@item type
The type of the child.
@@ -23970,7 +24024,12 @@ If the variable object is frozen, this variable will be present with a value of
The result may have its own attributes:
-@table @var
+@table @samp
+@item displayhint
+A dynamic varobj can supply a display hint to the front end. The
+comes directly from the Python pretty-printer object's
+@code{display_hint} method. @xref{Pretty Printing}.
+
@item has_more
This is an integer attribute which is nonzero if there are children
remaining after the end of the selected range.
@@ -24052,6 +24111,9 @@ result can be used only for UI presentation. Typical use of
the @code{-var-info-path-expression} command is creating a
watchpoint from a variable object.
+This command is currently not valid for children of a dynamic varobj,
+and will give an error when invoked on one.
+
For example, suppose @code{C} is a C@t{++} class, derived from class
@code{Base}, and that the @code{Base} class has a member called
@code{m_size}. Assume a variable @code{c} is has the type of
@@ -24160,6 +24222,60 @@ diagnostic.
If @code{-var-set-update-range} was previously used on a varobj, then
only the selected range of children will be reported.
+@code{-var-update} reports all the changed varobjs in a tuple named
+@samp{changelist}.
+
+Each item in the change list is itself a tuple holding:
+
+@table @samp
+@item name
+The name of the varobj.
+
+@item value
+If values were requested for this update, then this field will be
+present and will hold the value of the varobj.
+
+@item in_scope
+This is a string, either @samp{false} if the varobj is not in scope,
+or @samp{true} if it is in scope.
+
+@item type_changed
+This is only present if the varobj is still valid. If the type
+changed, then this will be the string @samp{true}; otherwise it will
+be @samp{false}.
+
+@item new_type
+If the varobj's type changed, then this field will be present and will
+hold the new type.
+
+@item new_num_children
+For a dynamic varobj, if the number of children changed, or if the
+type changed, this will be the new number of children.
+
+The @samp{numchild} field in other varobj responses is generally not
+valid for a dynamic varobj -- it will show the number of children that
+@value{GDBN} knows about, but because dynamic varobjs lazily
+instantiate their children, this will not reflect the number of
+children which may be available.
+
+The @samp{new_num_children} attribute only reports changes to the
+number of children known by @value{GDBN}. This is the only way to
+detect whether an update has removed children (which necessarily can
+only happen at the end of the update range).
+
+@item displayhint
+The display hint, if any.
+
+@item has_more
+This is an integer value, which will be 1 if there are more children
+available outside the varobj's update range.
+
+@item new_children
+If new children were added to a dynamic varobj within the selected
+update range (as set by @code{-var-set-update-range}), then they will
+be listed in this attribute.
+@end table
+
@subsubheading Example
@smallexample