[[Image(ImprovingBoostDocs:ibdp.png,nolink)]]

   * [ImprovingBoostDocs Improving Boost Docs]
      * [ImprovingBoostDocs About this project]
      * [BoostDocsRepository Boost docs repository]
      * [UnifiedLookAndFeelProject Unified look and feel project]
      * [HelpingBoostAuthors Helping Boost authors]
      * [GlueDocsProject Glue docs project]
      * [StandardCppLibraryDocumentation Standard C++ Library docs]
      * [DocumentationBestPractices Documentation best practices]
      * [DocumentationTools Documentation tools]
      * [ImprovingBoostDocsSubprojects Subprojects]
           * [BoostDocTest Boost.DocTest ]
           * [BoostHtmlStylesheet Boost HTML stylesheet]
           * [BoostKateSupport Boost Kate support]
           * [BoostPdfStylesheet Boost PDF stylesheet]
           * [BoostSpecificWikiMacros Boost-specific WikiMacros]
           * [BoostTracStylesheet Boost Trac stylesheet]
           * [BoostscriptProject Boostscript]
           * [GoogleSearchBoxProject Google Search box project]
           * [HtmlToDockbookProject HTML to docbook]
           * [QuickbookWikiProcessor Quickbook WikiProcessor]
           * [QuickbookSourceStylesheetProject Quickbook source stylesheet]
           * [SvgIconsSetProject SVG icons set project]
           * [SyntaxHighlightingProject Syntax-highlighting project]
           * [BoostTracSyntaxColoring Trac syntax-coloring]
           * '''[DebuggerVisualizers Debugger visualizers]'''
      * [BrowserTestingChart Browser-testing chart]
      * [LibrariesLogos Logo playground]

----

[[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 2012/2013/2015 ==

Visual Studio 2012 adds a new way of writing visualizers.  There is an article about it here:

[http://code.msdn.microsoft.com/Writing-type-visualizers-2eae77a2]

Visualizers for VS2012/VS2013/VS2015: [http://cppvisualizers.codeplex.com/]

Visualizers for VS2013: [https://visualstudiogallery.msdn.microsoft.com/61f12e7a-bc62-4b2c-b02e-d66014688c2e]

Visualizers and graphical debugging tools for VS2015: [https://visualstudiogallery.msdn.microsoft.com/4b81868b-8901-408f-a28e-25a6580788fb]

== Visual Studio 2005 / 2008 / 2010 ==

[http://msdn.microsoft.com/en-us/vstudio/default.aspx Microsoft Visual Studio 2005] is the first of the Visual Studio versions to support debugger visualizers usable for template classes. 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 [wiki:DebuggerVisualizers#Activedevelopers let us know]!

=== Native C++ Debugger Visualizers for MSVS 2005 / 2008 / 2010 ===

The formatting rules are stored in the {{{autoexp.dat}}} text file (the {{{[Visualizer]}}} section)
which can be found at
{{{
%VSINSTALLDIR%\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 ====

All visualizers are available in the svn at [https://svn.boost.org/svn/boost/sandbox/boost_docs/subprojects/DebuggerVisualizers].
Currently, we support the following Boost types:
 * boost::array, ptr_array, ptr_deque, ptr_list, ptr_map, ptr_multimap, ptr_set, ptr_multiset, ptr_vector
 * boost::bimap
 * boost::interprocess::offset_ptr
 * boost::intrusive::list
 * boost::optional
 * boost::multi_index_container
 * boost::multiprecision
 * boost::shared_ptr
 * boost::posix_time::ptime, boost::posix_time::time_duration (two variants are available)
 * boost::regex
 * boost::variant

There's also an unfinished visualizer for unordered containers attached to #4209. I'm not sure It isn't clear if it's possible to get it to work.

If you're lacking a visualizer for your favorite type, [wiki:DebuggerVisualizers#Activedevelopers let us know] or write one yourself - it's easy!

Note that some older files also exist in the Boost Vault at
[http://boost-consulting.com/vault/index.php?directory=Debug/Visualizers_MSVC_8 Boost Vault/Debug/Visualizers_MSVC_8],
which you can use to upload new visualizers if you create some (though most people just post a message to the Boost Users
mailing list with an attachment).

=== HOWTO ===

Our main source of knowledge is the [http://www.virtualdub.org/blog/pivot/entry.php?id=120 blog at virtualdub.org]
and the experience that we gained doing our own visualizers for Boost.

Some valuable information can also be found in the MSDN articles ''Unsupported Operators and Additional Operators''
and ''Restrictions on Native C++ Expressions''.

I'll try to summarize our current knowledge here.

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 ) #elif ( elif_expr ) ... #else ( else_expr )}}} construct (with the {{{#else}}} parts 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}}}.

=== Problems ===

One problem is when you have a pointer to a base class and you need to cast that to a derived class.
It seems that such type casts are unsupported.

=== TODO ===

FAQ, examples, common pitfalls, ...

----

== Qt Creator ==

Debugging helpers requires Qt Creator to work but it's possible to use them with any debugger supported by this IDE. They are written in Python and are similar to pretty printers.

Helpers for some of the Boost libraries can be found here: https://github.com/awulkiew/debugging-helpers

----

== 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)]]

----

=== Active developers ===

[[Br]][[Image(People:no_picture.png,50)]]
[[Br]]'''Filip Konvička'''
[[Br]]''filip dot konvicka at logis dot cz''

----

   * [ImprovingBoostDocs Improving Boost Docs]
      * [ImprovingBoostDocs About this project]
      * [BoostDocsRepository Boost docs repository]
      * [UnifiedLookAndFeelProject Unified look and feel project]
      * [HelpingBoostAuthors Helping Boost authors]
      * [GlueDocsProject Glue docs project]
      * [StandardCppLibraryDocumentation Standard C++ Library docs]
      * [DocumentationBestPractices Documentation best practices]
      * [DocumentationTools Documentation tools]
      * [ImprovingBoostDocsSubprojects Subprojects]
           * [BoostDocTest Boost.DocTest ]
           * [BoostHtmlStylesheet Boost HTML stylesheet]
           * [BoostKateSupport Boost Kate support]
           * [BoostPdfStylesheet Boost PDF stylesheet]
           * [BoostSpecificWikiMacros Boost-specific WikiMacros]
           * [BoostTracStylesheet Boost Trac stylesheet]
           * [BoostscriptProject Boostscript]
           * [GoogleSearchBoxProject Google Search box project]
           * [HtmlToDockbookProject HTML to docbook]
           * [QuickbookWikiProcessor Quickbook WikiProcessor]
           * [QuickbookSourceStylesheetProject Quickbook source stylesheet]
           * [SvgIconsSetProject SVG icons set project]
           * [SyntaxHighlightingProject Syntax-highlighting project]
           * [BoostTracSyntaxColoring Trac syntax-coloring]
           * '''[DebuggerVisualizers Debugger visualizers]'''
      * [BrowserTestingChart Browser-testing chart]
      * [LibrariesLogos Logo playground]