[python] more tests and documentation

[Tom Tromey <tromey at redhat dot com>]

This adds a few tests for the new MI features, and also adds
documentation for them.

Note that -var-set-visualizer is a bit roundabout.  This is to support
things like gdb.get_default_visualizer, which need the value at
visualizer-construction time.  I'm not sure that this is best.

Tom

b/gdb/doc/ChangeLog:
2008-10-22  Tom Tromey  <tromey@redhat.com>

	* gdb.texinfo (Pretty Printing): Remove comments.  Add missing
	'$'.  Document mi_pretty_printers.
	(GDB/MI Variable Objects): Document -var-set-visualizer and
	-var-set-child-range.

b/gdb/testsuite/ChangeLog:
2008-10-22  Tom Tromey  <tromey@redhat.com>

	* lib/mi-support.exp (mi_list_varobj_children_range): New proc.
	(mi_list_varobj_children): Use it.
	* gdb.python/python-mi.exp: Add -var-set-visualizer tests,
	-var-set-child-range tests.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 83c6280..b41175f 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -18017,7 +18017,7 @@ Here is an example showing how a @code{std::string} might be printed:
 def printstdstring(val):
     return val['_M_dataplus']['_M_p']
 
-gdb.cli_pretty_printers['^std::basic_string<char.*>'] = printstdstring
+gdb.cli_pretty_printers['^std::basic_string<char.*>$'] = printstdstring
 @end smallexample
 
 Here is an example of the same printer, using a class:
@@ -18030,9 +18030,16 @@ class StdStringPrinter:
 gdb.cli_pretty_printers['^std::basic_string<char.*>$'] = StdStringPrinter()
 @end smallexample
 
-@c FIXME: describe MI pretty-printer selection
-@c ... but in the MI section, I think
+@subsubsection Selecting MI Pretty-Printers
 
+MI pretty-printers are selected using a dictionary named
+@code{gdb.mi_pretty_printers}.  A key in this dictionary should be a
+regular expression in string form.  A value in this dictionary should
+be a constructor which takes no arguments and which returns a new
+object of the form described above.
+
+@value{GDBN} will consult @code{gdb.mi_pretty_printers} whenever a new
+MI variable object is created.
 
 @node Threads In Python
 @subsubsection Threads In Python
@@ -21778,6 +21785,104 @@ Unfreezing a variable does not update it, only subsequent
 (gdb)
 @end smallexample
 
+@subheading The @code{-var-set-visualizer} command
+@findex -var-set-visualizer
+@anchor{-var-set-visualizer}
+
+@subsubheading Synopsis
+
+@smallexample
+ -var-set-visualizer @var{name} @var{visualizer}
+@end smallexample
+
+@subheading The @code{-var-set-child-range} command
+@findex -var-set-child-range
+@anchor{-var-set-child-range}
+
+Set a visualizer for the variable object @var{name}.
+
+@var{visualizer} is the visualizer to use.  The special value
+@samp{None} means to disable any visualizer in use.
+
+If not @samp{None}, @var{visualizer} must be a Python expression.
+This expression must evaluate to a callable object which accepts a
+single argument.  @value{GDBN} will call this object with the value of
+the varobj @var{name} as an argument.  This function must return an
+object which conforms to the pretty-printing interface (@pxref{Pretty
+Printing}).
+
+The pre-defined function @code{gdb.get_default_visualizer} may be used
+to select a visualizer according to the type of the varobj.  This is
+called when a varobj is created, and so ordinarily is not needed.
+
+@code{gdb.get_default_visualizer} looks in a global dictionary named
+@code{gdb.mi_pretty_printers}.  This works analogously to
+@code{gdb.cli_pretty_printers}.
+
+This feature is only available if Python support is enabled.
+
+@subsubheading Example
+
+Resetting the visualizer:
+
+@smallexample
+(gdb)
+-var-set-visualizer V None
+^done
+@end smallexample
+
+Reselecting the default (type-based) visualizer:
+
+@smallexample
+(gdb)
+-var-set-visualizer V gdb.get_default_visualizer
+^done
+@end smallexample
+
+Suppose @code{SomeClass} is a visualizer class.  A lambda expression
+can be used to instantiate this class for a varobj:
+
+@smallexample
+(gdb)
+-var-set-visualizer V "lambda val: SomeClass()"
+^done
+@end smallexample
+
+@subsubheading Synopsis
+
+@smallexample
+ -var-set-child-range @var{name} @var{from} @var{to}
+@end smallexample
+
+Select a sub-range of the children of the variable object @var{name};
+future calls to @code{-var-list-children} will only report the
+selected range of children.  This allows an MI consumer to avoid
+inefficiencies if the varobj has very many children.
+
+If either @var{from} or @var{to} is less than zero, then sub-range
+selection is disabled, and @code{-var-list-children} will report all
+children.
+
+Otherwise, @var{from} and @var{to} are indexes into the array of
+children.  Children starting at @var{from} and stopping jsut before
+@var{to} will be reported.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+ -var-list-children n
+ ^done,numchild=3,children=[@{name="a",numchild=0,type="int"@},
+ @{name="b",numchild=0,type="int"@},
+ @{name="c",numchild=0,type="int"@}]
+(gdb)
+ -var-set-child-range n 1 2
+(gdb)
+ -var-list-children n
+ ^done,numchild=3,children=[@{name="b",numchild=0,type="int"@},
+ @{name="c",numchild=0,type="int"@}]
+@end smallexample
+
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Data Manipulation
diff --git a/gdb/testsuite/gdb.python/python-mi.exp b/gdb/testsuite/gdb.python/python-mi.exp
index a8730f4..73213ad 100644
--- a/gdb/testsuite/gdb.python/python-mi.exp
+++ b/gdb/testsuite/gdb.python/python-mi.exp
@@ -65,3 +65,54 @@ mi_varobj_update_dynamic container {
     { {container.\[0\]} {\[0\]} 0 int }
     { {container.\[1\]} {\[1\]} 0 int }
 } "varobj update 2"
+
+mi_gdb_test "-var-set-visualizer container None" \
+  "\\^done" \
+  "clear visualizer"
+
+mi_gdb_test "-var-update container" \
+  "\\^done,changelist=\\\[\\\]" \
+  "varobj update after clearing"
+
+mi_gdb_test "-var-set-visualizer container gdb.get_default_visualizer" \
+  "\\^done" \
+  "choose default visualizer"
+
+mi_varobj_update_dynamic container {
+    { {container.\[0\]} {\[0\]} 0 int }
+    { {container.\[1\]} {\[1\]} 0 int }
+} "varobj update after choosing default"
+
+mi_gdb_test "-var-set-visualizer container \"lambda val: ContainerPrinter()\"" \
+  "\\^done" \
+  "choose visualizer using expression"
+
+mi_varobj_update_dynamic container {
+    { {container.\[0\]} {\[0\]} 0 int }
+    { {container.\[1\]} {\[1\]} 0 int }
+} "varobj update after choosing via lambda"
+
+mi_gdb_test "-var-set-child-range container 1 2" \
+  "\\^done" \
+  "select child range"
+
+mi_gdb_test "-var-update container" \
+  "\\^done,changelist=\\\[\\\]" \
+  "varobj update after selecting child range"
+
+mi_list_varobj_children_range container 2 {
+    { {container.\[1\]} {\[1\]} 0 int }
+} "list varobj children after selecting child range"
+
+mi_gdb_test "-var-set-child-range container -1 -1" \
+  "\\^done" \
+  "reset child range"
+
+mi_gdb_test "-var-update container" \
+  "\\^done,changelist=\\\[\\\]" \
+  "varobj update after resetting child range"
+
+mi_list_varobj_children container {
+    { {container.\[0\]} {\[0\]} 0 int }
+    { {container.\[1\]} {\[1\]} 0 int }
+} "list varobj children after resetting child range"
diff --git a/gdb/testsuite/lib/mi-support.exp b/gdb/testsuite/lib/mi-support.exp
index 716db9e..cab3593 100644
--- a/gdb/testsuite/lib/mi-support.exp
+++ b/gdb/testsuite/lib/mi-support.exp
@@ -1310,14 +1310,20 @@ proc mi_child_regexp {children add_child} {
 # have no value.
 #
 proc mi_list_varobj_children { varname children testname } {
+    mi_list_varobj_children_range $varname [llength $children] $children \
+      $testname
+}
 
+# Like mi_list_varobj_children, but assumes that a subrange has been
+# selected with -var-set-child-range.  NUMCHILDREN is the total number
+# of children.
+proc mi_list_varobj_children_range {varname numchildren children testname} {
     set options ""
     if {[llength $varname] == 2} {
         set options [lindex $varname 1]
         set varname [lindex $varname 0]
     }
 
-    set numchildren [llength $children]
     set whatever "\"\[^\"\]+\""
 
     set children_exp_j [mi_child_regexp $children 1]