Label boolean and integer nodes in the natvis view visualizer

Show "boolean:", "int64:" and "uint64:" in front of the value, like
the other node kinds, so a bare number is not ambiguous.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/home/debugging.md

@@ -10,6 +10,13 @@ at its root, a [Natvis](https://learn.microsoft.com/en-us/visualstudio/debugger/
 file that gives `json`/`ordered_json` values a friendly, key/value debugger view instead of showing raw internal
 fields, when debugging with the MSVC debug engine (`cppvsdbg`) in Visual Studio or VS Code.
 
+The file also has visualizers for `json_document` and `json_view` (and their `ordered_json`/editable variants). They
+show the value of the document or view, and its elements as an expandable list. Because a document is only a flat index
+into the source text, the strings of the direct elements are shown, but the elements of nested arrays and objects are
+shown as index nodes (their kind, size, and numbers; strings only by length). Arrays and objects that have been edited
+in a `json_editable_document` are not expanded. The visualizers read the internal layout of the MSVC STL (`std::array`,
+`std::unique_ptr`).
+
 The checked-in visualizers cover namespace variants with zero, one, or two ABI tags. Configurations with three or more
 ABI tags are not covered and may show raw internal fields instead. To generate a Natvis file for such a configuration:
 
@@ -29,7 +36,7 @@ ABI tags are not covered and may show raw internal fields instead. To generate a
 
 4. Use the generated file instead of `nlohmann_json.natvis`.
 
-`--abi-tags` can be repeated for several configurations, and `--all` generates every combination (about 60 MB for 12
+`--abi-tags` can be repeated for several configurations, and `--all` generates every combination (about 60 MB for 11
 ABI tags, doubling with each further tag). See
 [`tools/generate_natvis`](https://github.com/nlohmann/json/tree/develop/tools/generate_natvis) for all options.
 

tools/generate_natvis/README.md

@@ -6,6 +6,11 @@ The checked-in `nlohmann_json.natvis` covers the default namespace (no ABI tags)
 of ABI tags, with both versioned and unversioned namespace variants. Configurations that enable three or more ABI tags
 are not covered by this reduced file; use `--abi-tags` or `--all` (see below) to generate a file for them.
 
+The visualizers of `basic_json_document` and `basic_json_view` live in the same inline namespaces as `basic_json`, so the
+ABI tags apply to them in the same way, and the `view_mode` template argument is covered by a wildcard: it does not
+multiply the namespaces. Each namespace gets three more types (`basic_json_view<*,*>`, `basic_json_document<*,*>`, and
+`detail::view::node`), which roughly doubles the size of the file.
+
 The ABI tag list and the library version are parsed from
 `include/nlohmann/detail/abi_macros.hpp`, so this script must be re-run (via
 `make natvis`) whenever an `NLOHMANN_JSON_ABI_TAG_*` macro is added to that
@@ -35,7 +40,7 @@ version other than the one in `abi_macros.hpp`.
 |-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `--list-tags`     | Print every ABI tag (in namespace order) with the macro that enables it and the `NLOHMANN_JSON_ABI_TAG_*` identifier, then exit.                                                                                                                    |
 | `--abi-tags TAGS` | Add the namespaces of one configuration, given as a comma-separated list of ABI tags (`_diag,_dp,_ns`; the leading underscore is optional, and the order does not matter). Can be repeated for several configurations. Unknown tags are an error. |
-| `--all`           | Generate the namespaces for every combination of ABI tags. The file size doubles with each tag (about 60 MB for 12 tags). Cannot be combined with `--abi-tags`.                                                                                    |
+| `--all`           | Generate the namespaces for every combination of ABI tags. The file size doubles with each tag (about 60 MB for 11 tags). Cannot be combined with `--abi-tags`.                                                                                    |
 | `--output FILE`   | Write the Natvis file to `FILE` instead of `nlohmann_json.natvis` in the repository root.                                                                                                                                                           |
 
 Each configuration gets both the versioned (`json_abi_diag_dp_ns_v3_12_0`) and the unversioned (`json_abi_diag_dp_ns`,

tools/generate_natvis/generate_natvis.py

@@ -95,7 +95,7 @@ if __name__ == '__main__':
                                 'optional) of one configuration to add to the default namespaces; can be repeated')
     selection.add_argument('--all', action='store_true',
                            help='Generate the namespaces for every combination of ABI tags; the file size doubles '
-                                'with each ABI tag (about 60 MB for 12 tags)')
+                                'with each ABI tag (about 60 MB for 11 tags)')
     parser.add_argument('--list-tags', action='store_true',
                         help='List the ABI tags with the macros that enable them, and exit')
     parser.add_argument('--output', metavar='FILE',

tools/generate_natvis/nlohmann_json.natvis.j2

@@ -5,6 +5,39 @@
 <!-- * * * * * * * * AUTO-GENERATED FILE  * * * * * * * * -->
 
 <AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
+{# The children of the container node `node` (a pointer expression) of the document `doc` (a document_data pointer
+   expression). A node is only an index into the source text: strings are read from `doc`, so the strings of the
+   direct children are readable here, but the children of a nested container are shown as nodes (see the node
+   visualizer below). Containers with edits (flag 8, "moved") are not expanded. The node kinds are the numbers of
+   node_kind: 1 object, 2 array, 3 string; the float token is shown only by the node visualizer. #}
+{% macro children(node, doc=none) %}
+            <CustomListItems MaxItemsPerView="1000">
+              <Variable Name="nd" InitialValue="{{ node }}" />
+              <Variable Name="obj" InitialValue="nd != 0 &amp;&amp; (int)nd-&gt;kind == 1" />
+              <Variable Name="n" InitialValue="(nd != 0 &amp;&amp; ((int)nd-&gt;kind == 1 || (int)nd-&gt;kind == 2) &amp;&amp; (nd-&gt;flags &amp; 8) == 0) ? (int)nd-&gt;len : 0" />
+              <Variable Name="p" InitialValue="nd + 1" />
+              <Variable Name="i" InitialValue="0" />
+              <Size>obj ? 2 * n : n</Size>
+              <Loop Condition="i &lt; n">
+{% if doc %}
+                <Item Name="key" Condition="obj">{{ doc }}-&gt;base._Elems[p-&gt;flags &amp; 3] + p-&gt;off,[p-&gt;len]s8</Item>
+{% else %}
+                <Item Name="key" Condition="obj">*p</Item>
+{% endif %}
+                <Exec Condition="obj">p = p + 1</Exec>
+{% if doc %}
+                <Item Name="value" Condition="obj &amp;&amp; (int)p-&gt;kind == 3">{{ doc }}-&gt;base._Elems[p-&gt;flags &amp; 3] + p-&gt;off,[p-&gt;len]s8</Item>
+{% endif %}
+                <Item Name="value" Condition="obj{% if doc %} &amp;&amp; (int)p-&gt;kind != 3{% endif %}">*p</Item>
+{% if doc %}
+                <Item Condition="!obj &amp;&amp; (int)p-&gt;kind == 3">{{ doc }}-&gt;base._Elems[p-&gt;flags &amp; 3] + p-&gt;off,[p-&gt;len]s8</Item>
+{% endif %}
+                <Item Condition="!obj{% if doc %} &amp;&amp; (int)p-&gt;kind != 3{% endif %}">*p</Item>
+                <Exec>p = p + (((int)p-&gt;kind == 1 || (int)p-&gt;kind == 2) ? p-&gt;next : 1)</Exec>
+                <Exec>i = i + 1</Exec>
+              </Loop>
+            </CustomListItems>
+{%- endmacro %}
 {% for ns in namespaces %}
     <!-- Namespace {{ ns }} -->
     <Type Name="{{ ns }}::basic_json&lt;*&gt;">
@@ -62,5 +95,44 @@
     </Type>
 
 {% endfor %}
+
+    <!-- json_view / json_document (include/nlohmann/json_view.hpp). They live in the same inline namespaces as
+         basic_json, so the ABI tags need no extra entries; the view_mode is a template argument that the wildcard
+         covers. A view is a pointer to the document's data and a pointer to a node of its flat index; the
+         strings of the source are found through document_data::base (std::array of the MSVC STL: _Elems). -->
+    <Type Name="{{ ns }}::detail::view::node">
+        <DisplayString Condition="(int)kind == 0">null</DisplayString>
+        <DisplayString Condition="(int)kind == 1">object, size={len}</DisplayString>
+        <DisplayString Condition="(int)kind == 2">array, size={len}</DisplayString>
+        <DisplayString Condition="(int)kind == 3">string, length={len}</DisplayString>
+        <DisplayString Condition="(int)kind == 4">boolean: {(flags &amp; 4) != 0}</DisplayString>
+        <DisplayString Condition="(int)kind == 5">int64: {(__int64)((unsigned __int64)len | ((unsigned __int64)next &lt;&lt; 32))}</DisplayString>
+        <DisplayString Condition="(int)kind == 6">uint64: {(unsigned __int64)len | ((unsigned __int64)next &lt;&lt; 32)}</DisplayString>
+        <DisplayString Condition="(int)kind == 7">float, length={len}</DisplayString>
+        <DisplayString>link</DisplayString>
+        <Expand>
+{{ children('this') }}
+        </Expand>
+    </Type>
+
+    <Type Name="{{ ns }}::basic_json_view&lt;*,*&gt;">
+        <DisplayString Condition="m_node == 0">discarded</DisplayString>
+        <DisplayString Condition="(int)m_node-&gt;kind == 3">{m_doc-&gt;base._Elems[m_node-&gt;flags &amp; 3] + m_node-&gt;off,[m_node-&gt;len]s8}</DisplayString>
+        <DisplayString Condition="(int)m_node-&gt;kind == 7">{m_doc-&gt;base._Elems[m_node-&gt;flags &amp; 3] + m_node-&gt;off,[m_node-&gt;len]s8b}</DisplayString>
+        <DisplayString>{*m_node}</DisplayString>
+        <Expand>
+{{ children('m_node', 'm_doc') }}
+        </Expand>
+    </Type>
+
+    <Type Name="{{ ns }}::basic_json_document&lt;*,*&gt;">
+        <DisplayString Condition="m_data._Mypair._Myval2 == 0 || m_data._Mypair._Myval2-&gt;discarded">discarded</DisplayString>
+        <DisplayString>{*m_data._Mypair._Myval2-&gt;nodes}</DisplayString>
+        <Expand>
+            <Item Name="[source]" Condition="m_data._Mypair._Myval2 != 0">m_data._Mypair._Myval2-&gt;src,[m_data._Mypair._Myval2-&gt;size]s8b</Item>
+            <Item Name="[nodes]" Condition="m_data._Mypair._Myval2 != 0">m_data._Mypair._Myval2-&gt;node_count</Item>
+{{ children('m_data._Mypair._Myval2->nodes', 'm_data._Mypair._Myval2') }}
+        </Expand>
+    </Type>
 {% endfor %}
 </AutoVisualizer>