Changes between Version 7 and Version 8 of DebuggerVisualizers

Timestamp:

Aug 6, 2007, 2:06:18 PM (15 years ago)

Author:

fkonvick

Comment:

Initial revision

DebuggerVisualizers

@@ -33 +33 @@
 [[Image(ImprovingBoostDocsSubprojects:boost_debugger_visualizers.png)]]
 
+http://svn.boost.org/trac/boost/wiki/DebuggerVisualizers
+
+----
+
+== About Debugger Visualizers ==
+
+Debugger visualizers enable developers to view data during debugging sessions in a human-friendly way.
+
+Though each debugger UI usually tries to display the data as nicely as possible,
+with complex types such as those of BOOST, the general approach usually does not allow the user
+to quickly get the information she needs.
+That's where debugger visualizers come to help: they are user- or library vendor-defined formatting rules
+that help the debugger UI to deliver data in a comprehensible form.
+
 ----
 
 == Visual Studio 2005 ==
 
-Under construction!
+[http://msdn2.microsoft.com/en-us/vstudio/default.aspx Microsoft Visual Studio 2005] is the first of the Visual Studio versions to support user-customizable debugger visualizers. For CLR languages, such as C#, the possibilities are even more powerful, and documented. Native C++ debugger visualizers are not documented, though it was claimed by some people from Microsoft that some docs are coming - so if you know of some, please let us know!
+
+=== Native C++ Debugger Visualizers for MSVS 2005 ===
+
+The formatting rules are stored in the {{{autoexp.dat}}} text file (the {{{[Visualizer]}}} section)
+which can be found at
+{{{
+Microsoft Visual Studio 8\Common7\Packages\Debugger\autoexp.dat
+}}}
+
+New visualizers can be installed by appending visualizer code to the {{{[Visualizer]}}} section. In the future, we would like to have an installer for this.
+
+==== Existing visualizers ====
+
+Visualizers for {{{boost::multi_index_container}}} stored at http://svn.boost.org/svn/boost/sandbox/boost_docs/sandbox
+
+Other existing visualizers will be added shortly. If you're lacking a visualizer for your favorite type, let us know or write one yourself - it's easy!
+
+=== HOWTO ===
+
+Our main source of knowledge is the [http://www.virtualdub.org/blog/pivot/entry.php?id=120 blog at virtualdub.org]. I'll try to repeat some of the basic info you need to get started.
+
+Visualizers (visualizer '''rules''') have this general format:
+
+{{{
+; Comments start with semicolon
+pattern [| pattern ...] {
+  preview (
+    preview_expression
+  )
+  stringview (
+    stringview_expression
+  )
+  children (
+    children_expression
+  )
+}
+}}}
+
+The {{{stringview}}} section is used for formatting the data to text, HTML or XML
+(not covered by this guide yet).
+The {{{preview}}} section is used to format the data for one-line view.
+This is used in tooltips (when you hover over variables in code editor) and for the watch window.
+The {{{children}}} section enumerates child nodes (for structured types).
+All sections are optional. 
+
+==== Rule pattern matching ====
+
+When visualizing a variable, the IDE looks at its (most derived) type.
+It then looks at all patterns in {{{autoexp.dat}}} and tries to find match.
+My guess is that it chooses the first rule that matches, but there should not be more than one
+matching rule anyway.
+
+Type names are processed as text.
+You can see the exact string that the visualizer sees in the watch window (the "Type" column).
+The bad thing about this is that extremely long type names are cut off at a certain string length.
+Such cropped strings then fail to match the visualizer patterns.
+
+Patterns can contain wildcards.
+(My guess is that the patterns are internally transformed to regular expressions by the IDE.)
+This is great for templates. A wildcard can match one or more template arguments:
+
+{{{
+std::list<*>
+}}}
+
+and (preferred syntax)
+
+{{{
+std::list<*,*>
+}}}
+
+will both match {{{std::list<int>}}} - because it is in fact {{{std::list<int,std::allocator<int> >}}}.
+
+As with marked subexpressions of regular expressions, we can access the actual text that matched the
+wildcards in the rule body's expressions. This text is referred to as {{{$T1, $T2, $T3}}} etc.
+As with shell variable expansion, the {{{$T}}}s are expanded in-place in the expression in which they appear.
+In case of {{{std::list<*>}}}, we have only one wildcard,
+and {{{$T1}}} will be expanded to {{{int,std::allocator<int>}}}.
+In case of {{{std::list<*,*>}}}, {{{$T1}}} expands to {{{int}}} and {{{$T2}}}
+expands to {{{std::allocator<int>}}}.
+This is more usable, because we can access the item type ({{{int}}}) in the expressions.
+
+==== preview section ====
+
+The {{{preview}}} expression produces a string that is used for one-line representation of the data
+in the tooltips and in the watch window.
+Usually, one wants to pick 2 or 3 important members out of the hundreds members of the class.
+
+The following code formats {{{std::list}}} preview:
+
+{{{
+std::list<*,*>{
+  preview
+    (
+      #("[list size=", $e._Mysize, "]")
+    )
+}
+}}}
+
+Note the use of the contatenation operator {{{#(s1, s2, ..., sn )}}}.
+{{{$e}}} refers to the value of the variable being visualized
+(we are accessing the {{{_Mysize}}} member of the {{{std::list}}} implementation).
+
+==== children section ====
+
+When the {{{children}}} section is present, a {{{[+]}}} will appear to the left of the visualized value
+and can be used to expand it (display the children).
+Multiple children can be added using the {{{#(c1, c2, ..., cn)}}} operator,
+and child values can have custom names (and will appear sorted by name):
+{{{
+std::list<*,*>{
+  children
+  (
+    #(
+      first item: $e._Myhead->_Next->_Myval,
+      second item: $e._Myhead->_Next->_Next->_Myval,
+      [third item]: $e._Myhead->_Next->_Next->_Next->_Myval
+    )
+  )
+}
+}}}
+
+This is nice, but we need more to display real structures like lists, arrays and trees.
+There are special processors for these structures:
+
+===== #list =====
+
+{{{#list(head: head_expr size: size_expr next: next_expr) : deref_expr}}} is used to visualize a linked list of values.
+This can be used to visualize {{{std::list}}}:
+{{{
+std::list<*,*>{
+  children
+  (
+    #list(size: $c._Mysize,
+          head: $c._Myhead->_Next,
+          next: _Next
+    ) : $e._Myval
+  )
+}
+}}}
+
+As you can see, we need to know the size of the list, where is the head node of the list,
+and how to get to a node's successor (this is done by accessing the {{{next}}} member of the current node).
+{{{$c}}} refers to the current expression, and in {{{deref_expr}}}, {{{$e}}} refers to the node being displayed.
+
+Alternative approach is {{{#list(head: head_expr skip: skip_expr next: next_expr) : deref_expr}}}.
+Here {{{skip_expr}}} defines node value (probably compared by memory address) which terminates the list traversal.
+Also, if a node is reached twice (cycle detection), it is not displayed and the traversal is stopped.
+
+===== #array =====
+
+{{{#array(expr: array_access_expr, size : size_expr) : deref_expr}}} is similar to {{{#list}}}, but the values
+are accessed by indexing the {{{array_head_expr}}} by indices {{{0, 1, ..., (size_expr-1)}}}.
+In {{{array_access_expr}}}, {{{$i}}} denotes the current index.
+
+There are optional parameters {{{rank}}} and {{{base}}}.
+{{{base}}} offsets the displayed indices of the array items (there must not be any {{{deref_expr}}} for this to work).
+{{{rank}}} can be used to display multidimensional arrays. In this case, {{{size}}} and {{{base}}} are evaluated
+repeatedly and {{{$r}}} in {{{rank_expr}}} and {{{base_expr}}} refers to the current rank being processed.
+
+===== #tree =====
+
+{{{#tree(head: head_expr size: size_expr left: left_expr right:right_expr skip: skip_expr) : deref_expr}}} is used
+to walk a binary tree. It is very similar to {{{#list}}}, the only difference being that the traversal is not linear
+but recursive depth-first. {{{skip_expr}}} is used to tell the shape of the tree (usually {{{skip: 0}}}).
+
+===== conditionals =====
+
+There is a {{{#if (expr) ( then_expr ) #else ( else_expr )}}} construct (with the ___else___ part optional)
+and a {{{#switch(switch_expr) #case case0_value ( case0_expr ) ... #default ( default_expr ) #except ( except_expr ) )}}}
+construct that can be used in the expressions. My guess (haven't tried) is that values matching {{{except_expr}}}
+are not passed to {{{#default}}}.
+
+=== TODO ===
+
+FAQ, examples, common pitfalls, ...
+
+----
+
+== gdb, ddd, others ==
+
+If you are interested, please send an email to the 
+[http://lists.boost.org/mailman/listinfo.cgi/boost-docs boost-docs list]
+telling us that you want to help.
+
+[[Image(CommonImages:help_wanted.png,nolink)]]
 
 ----
@@ -45 +245 @@
 [[Br]][[Image(People:no_picture.png,50)]]
 [[Br]]'''Filip Konvička'''
-[[Br]]''email unknown''
-
-----
-
-== gdb, ddd, others ==
-
-If you are interested, please send an email to the 
-[https://lists.sourceforge.net/lists/listinfo/boost-docs boost-docs list]
-telling us that you want to help.
-
-[[Image(CommonImages:help_wanted.png,nolink)]]
+[[Br]]''filip dot konvicka at logis dot cz''
 
 ----