gdb

	* varobj.h (varobj_update_result_t) <new>: New field.
	(varobj_get_child_range, varobj_set_child_range): Declare.
	(varobj_list_children): Update.
	(varobj_enable_pretty_printing, varobj_has_more)
	(varobj_pretty_printed_p): Declare.
	* varobj.c (pretty_printing): New global.
	(varobj_enable_pretty_printing): New function.
	(struct varobj_root) <from, to, constructor, child_iter,
	saved_item>: New fields.
	(varobj_create): Don't call install_default_visualizer.
	(instantiate_pretty_printer): Don't use value_copy.
	(varobj_has_more): New function.
	(restrict_range): New function.
	(install_dynamic_child): Likewise.
	(dynamic_varobj_has_child_method): Likewise.
	(update_dynamic_varobj_children): Remove 'new_and_unchanged'
	argument; add 'new', 'unchanged', 'from', and 'to' arguments.
	Rewrite.
	(varobj_get_num_children): Call update_dynamic_varobj_children.
	(varobj_list_children): Add 'from' and 'to' arguments.  Ignore
	result of update_dynamic_varobj_children.  Don't call
	install_default_visualizer.  Restrict result range.
	(varobj_add_child): Don't call install_default_visualizer.
	(varobj_pretty_printed_p): New function.
	(install_visualizer): Rewrite.  Move earlier in file.
	(install_default_visualizer): Likewise.
	(construct_visualizer): New function.
	(install_new_value_visualizer): Likewise.
	(install_new_value): Don't call release_value.  Special case
	pretty-printed objects.  Use value_incref.  Rearrange "changed"
	logic.
	(varobj_get_child_range): New function.
	(varobj_set_child_range): Likewise.
	(varobj_set_visualizer): Rewrite.
	(varobj_update): Rewrite pretty-printing logic.
	(new_variable): Initialize new fields.
	(free_variable): Destroy new fields.
	(value_of_root): Copy 'from' and 'to'.
	(my_value_of_variable): Handle pretty-printers.
	(value_get_print_value): Rework pretty-printing logic.
	(cplus_describe_child): Don't use release_value.
	* mi/mi-cmds.h (mi_cmd_enable_pretty_printing)
	(mi_cmd_var_set_update_range): Declare.
	* mi/mi-cmds.c (mi_cmds): Add enable-pretty-printing and
	var-set-update-range.
	* mi/mi-cmd-var.c (print_varobj): Update.  Emit "dynamic"
	attribute.
	(mi_cmd_var_create): Emit "has_more" attribute.
	(mi_cmd_var_set_format): Plug memory leak.
	(mi_print_value_p): Replace 'type' argument with 'var'.  Handle
	pretty-printed varobjs.
	(mi_cmd_var_list_children): Accept 'from' and 'to' arguments.
	Emit "has_more" attribute.
	(mi_cmd_var_evaluate_expression): Plug memory leak.
	(mi_cmd_var_assign): Likewise.
	(varobj_update_one): Likewise.  Emit "dynamic", "has_more", and
	"new_children" attributes.
	(mi_cmd_enable_pretty_printing): New function.
	(mi_cmd_var_set_update_range): Likewise.
gdb/doc
	* gdb.texinfo (GDB/MI Variable Objects): Document
	-enable-pretty-printing, -var-set-update-range, dynamic varobjs.
	Expand -var-update documentation.
gdb/testsuite
	* lib/mi-support.exp (mi_create_varobj): Update.
	(mi_create_floating_varobj): Likewise.
	(mi_create_dynamic_varobj): New proc.
	(mi_varobj_update): Update.
	(mi_varobj_update_with_type_change): Likewise.
	(mi_varobj_update_kv_helper): New proc.
	(mi_varobj_update_dynamic_helper): Rewrite.
	(mi_varobj_update_dynamic): New proc.
	(mi_list_varobj_children): Update.
	(mi_list_varobj_children_range): Add 'from' and 'to' arguments.
	* gdb.python/python-prettyprint.py (pp_outer): New class.
	(pp_nullstr): Likewise.
	(lookup_function): Register new printers.
	* gdb.python/python-prettyprint.c (struct substruct): New type.
	(struct outerstruct): Likewise.
	(substruct_test): New function.
	(struct nullstr): New type.
	(string_1, string_2): New globals.
	(main): Add new tests.
	* gdb.python/python-mi.exp: Added regression tests.
	* gdb.mi/mi2-var-display.exp: Update.
	* gdb.mi/mi2-var-cmd.exp: Update.
	* gdb.mi/mi2-var-child.exp: Update.
	* gdb.mi/mi2-var-block.exp: Update.
	* gdb.mi/mi-var-invalidate.exp: Update.
	* gdb.mi/mi-var-display.exp: Update.
	* gdb.mi/mi-var-cmd.exp: Update.
	* gdb.mi/mi-var-child.exp: Update.
	* gdb.mi/mi-var-block.exp: Update.
	* gdb.mi/mi-break.exp: Update.
	* gdb.mi/gdb701.exp: Update.

2 files changed, 221 insertions, 19 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index b0e0f6c..5d297b6 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,9 @@
+2009-09-15  Tom Tromey  <tromey@redhat.com>
+
+	* gdb.texinfo (GDB/MI Variable Objects): Document
+	-enable-pretty-printing, -var-set-update-range, dynamic varobjs.
+	Expand -var-update documentation.
+
 2009-09-14  Sergio Durigan Junior <sergiodj@linux.vnet.ibm.com>
 
 	* gdb.texinfo (Set Catchpoints): Documentation about the catch syscall
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 80b4789..5a5f542 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23491,6 +23491,8 @@ access this functionality:
 @item @strong{Operation}
 @tab @strong{Description}
 
+@item @code{-enable-pretty-printing}
+@tab enable Python-based pretty-printing
 @item @code{-var-create}
 @tab create a variable object
 @item @code{-var-delete}
@@ -23519,6 +23521,8 @@ access this functionality:
 @tab update the variable and its children
 @item @code{-var-set-frozen}
 @tab set frozeness attribute
+@item @code{-var-set-update-range}
+@tab set range of children to display on update
 @end multitable
 
 In the next subsection we describe each operation in detail and suggest
@@ -23526,6 +23530,23 @@ how it can be used.
 
 @subheading Description And Use of Operations on Variable Objects
 
+@subheading The @code{-enable-pretty-printing} Command
+@findex -enable-pretty-printing
+
+@smallexample
+-enable-pretty-printing
+@end smallexample
+
+@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 enabled, this feature cannot be disabled.
+
+Note that if Python support has not been compiled into @value{GDBN},
+this command will still succeed (and do nothing).
+
 @subheading The @code{-var-create} Command
 @findex -var-create
 
@@ -23565,15 +23586,61 @@ begin with a @samp{*}), or one of the following:
 @samp{$@var{regname}} --- a CPU register name
 @end itemize
 
+@cindex dynamic varobj
+A varobj's contents 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
+are:
+
+@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 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.
+
+@item dynamic
+This attribute will be present and have the value @samp{1} if the
+varobj is a dynamic varobj.  If the varobj is not a dynamic varobj,
+then this attribute will not be present.
+
+@item displayhint
+A dynamic varobj can supply a display hint to the front end.  The
+value comes directly from the Python pretty-printer object's
+@code{display_hint} method.  @xref{Pretty Printing}.
+@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
 
 
@@ -23651,6 +23718,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
@@ -23658,7 +23729,7 @@ Returns the number of children of a variable object @var{name}:
 @subsubheading Synopsis
 
 @smallexample
- -var-list-children [@var{print-values}] @var{name}
+ -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}]
 @end smallexample
 @anchor{-var-list-children}
 
@@ -23671,6 +23742,22 @@ values; and if it is 2 or @code{--simple-values} print the name and
 value for simple data types and just the name for arrays, structures
 and unions.
 
+@var{from} and @var{to}, if specified, indicate the range of children
+to report.  If @var{from} or @var{to} is less than zero, the range is
+reset and all children will be reported.  Otherwise, children starting
+at @var{from} (zero-based) and up to and excluding @var{to} will be
+reported.
+
+If a child range is requested, it will only affect the current call to
+@code{-var-list-children}, but not future calls 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
@@ -23682,13 +23769,21 @@ Name of the variable object created for this child.
 The expression to be shown to the user by the front end to designate this child.
 For example this may be the name of a structure member.
 
+For a dynamic varobj, this value cannot be used to form an
+expression.  There is no way to do this at all with a dynamic varobj.
+
 For C/C@t{++} structures there are several pseudo children returned to
 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.
 
+A dynamic varobj will not report the access qualifying
+pseudo-children, regardless of the language.  This information is not
+available at all with a dynamic varobj.
+
 @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.
@@ -23704,6 +23799,19 @@ Otherwise this result is not present.
 If the variable object is frozen, this variable will be present with a value of 1.
 @end table
 
+The result may have its own attributes:
+
+@table @samp
+@item displayhint
+A dynamic varobj can supply a display hint to the front end.  The
+value 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.
+@end table
+
 @subsubheading Example
 
 @smallexample
@@ -23780,6 +23888,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
@@ -23885,21 +23996,25 @@ With the @samp{*} parameter, if a variable object is bound to a
 currently running thread, it will not be updated, without any
 diagnostic.
 
-@subsubheading Example
+If @code{-var-set-update-range} was previously used on a varobj, then
+only the selected range of children will be reported.
 
-@smallexample
-(gdb)
--var-assign var1 3
-^done,value="3"
-(gdb)
--var-update --all-values var1
-^done,changelist=[@{name="var1",value="3",in_scope="true",
-type_changed="false"@}]
-(gdb)
-@end smallexample
+@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
 @anchor{-var-update}
-The field in_scope may take three values:
+This field is a string which may take one of three values:
 
 @table @code
 @item "true"
@@ -23921,6 +24036,61 @@ objects.
 In the future new values may be added to this list so the front should
 be prepared for this possibility.  @xref{GDB/MI Development and Front Ends, ,@sc{GDB/MI} Development and Front Ends}.
 
+@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 dynamic
+This attribute will be present and have the value @samp{1} if the
+varobj is a dynamic varobj.  If the varobj is not a dynamic varobj,
+then this attribute will not be present.
+
+@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
+(gdb)
+-var-assign var1 3
+^done,value="3"
+(gdb)
+-var-update --all-values var1
+^done,changelist=[@{name="var1",value="3",in_scope="true",
+type_changed="false"@}]
+(gdb)
+@end smallexample
+
 @subheading The @code{-var-set-frozen} Command
 @findex -var-set-frozen
 @anchor{-var-set-frozen}
@@ -23952,6 +24122,32 @@ Unfreezing a variable does not update it, only subsequent
 (gdb)
 @end smallexample
 
+@subheading The @code{-var-set-update-range} command
+@findex -var-set-update-range
+@anchor{-var-set-update-range}
+
+@subsubheading Synopsis
+
+@smallexample
+ -var-set-update-range @var{name} @var{from} @var{to}
+@end smallexample
+
+Set the range of children to be returned by future invocations of
+@code{-var-update}.
+
+@var{from} and @var{to} indicate the range of children to report.  If
+@var{from} or @var{to} is less than zero, the range is reset and all
+children will be reported.  Otherwise, children starting at @var{from}
+(zero-based) and up to and excluding @var{to} will be reported.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-var-set-update-range V 1 2
+^done
+@end smallexample
+
 @subheading The @code{-var-set-visualizer} command
 @findex -var-set-visualizer
 @anchor{-var-set-visualizer}