Skip to content

Latest commit

 

History

History
192 lines (140 loc) · 8.13 KB

README.md

File metadata and controls

192 lines (140 loc) · 8.13 KB
Raw

Debug Visualizer

A VS Code extension for visualizing data structures while debugging. Like the VS Code's watch view, but with rich visualizations of the watched value.

Visualization Playground

Click here to explore all available visualizations.

Supported Languages

See demos for demos. These languages and debuggers are verified to work with this extension:

All other languages and debuggers might work too. For languages with Basic Support, only JSON strings can be visualized - you must implement some logic that builds this JSON for your data structure! Fully supported languages offer Data Extractors which convert some well known data structures to json.

Usage

After installing this extension, use the command Debug Visualizer: New View to open a new visualizer view. In this view you can enter an expression that is evaluated and visualized while stepping through your application. This view works the same as the watch view of VS Code, except that the resulting value is presented visually rather than textually and you can only watch one expression (but you can still open multiple windows).

Use the command Debug Visualizer: Use Selection as Expression (Shift + F1) to use the currently selected text as expression in the most recently opened debug visualizer.

Supported Values

Not all values can be processed. Visualizers consume specific JSON data. This extension uses hediet/visualization, a generic visualization framework. You can see in its playground which data can be visualized and how the visualization looks like.

The currently watched expression should evaluate to a JSON Object string, matching the schema of one of the supported visualizers. This JSON string may be surrounded by single or double quotation marks (or none at all) and must not be escaped. A valid example is "{ "kind": { "text": true }, "text": "some text\nmore text" }". Use the watch window to see what an expression evaluates to. This extension simply interprets that result.

For some languages (TypeScript/JavaScript), runtime code is injected to support Data Extractors. A Data Extractor lifts the requirement for the visualized value to be a JSON string and acts as a bridge between custom data structures and the JSON data processed by the visualizers. When multiple Data Extractors are applicable, a preferred one can be selected in the visualization view.

There is a JSON Schema for all supported visualizations and a typescript declaration file.

Selected Demos

Reversing a Doubly Linked List

Random Walk

Ast Visualizer

Table Visualizer

JavaScript/TypeScript Integrated Data Extractors

Data extractors convert arbitrary values into data consumable by visualizers. They live in the debugee. The following data extractors are injected automatically into the debugee by this extension when using the node, node2, extensionHost, chrome or pwa-chrome debug adapter. Custom data extractors can be registered too. See the package @hediet/debug-visualizer-data-extraction and its README for the implementation and its API. Also, a global object of name hedietDbgVis with helper functions is injected.

  • ToString
    • Just calls .toString() on values and treats the result as text.
  • TypeScript AST
    • Direct Visualization of ts.Nodes
    • Visualization of Record<string, ts.Node> and ts.Node[]. If the record contains a key fn, its value is displayed for each node.
  • As Is Data Extractor
    • Treats the data as direct input to the visualizer.
  • Use Method 'getVisualizationData'
    • Calls .getVisualizationData() on values and treats the result as direct input to the visualizer.
  • Plotly y-Values
    • Uses plotly to plot an array of numbers.
  • Object Graph
    • Constructs a graph containing all objects reachable from object the expression evaluates to. Graph is constructed using a breadth search. Stops after 50 nodes.
  • Array Grid
    • Creates Grid visualization data for an array.

UI Features

  • Multi-line Expressions: Press shift+enter to add a new line and ctrl+enter to evaluate the expression. When only having a single line, enter submits the current expression, but when having multiple lines, enter inserts another line break.

Configuration

This extension provides these configuration options:

debugVisualizer.debugAdapterConfigurations

Allows to set expression templates for specific debug adapter types. Example:

"debugVisualizer.debugAdapterConfigurations": {
    "lldb": {
        "expressionTemplate": "script to_json(\"${expr}\")",
        "context": "repl"
    }
}

Configurations here overwrite the built-in support for the corresponding debug adapter type.

debugVisualizer.useChromeKioskMode

Specifies whether to pop out Debug Visualization Views with Chrome in Kiosk Mode. Uses the default browser otherwise or if Chrome is not found. Defaults to true.

debugVisualizer.js.customScriptPaths

Specifies a list of JavaScript files that are injected into the debugee when debugging JavaScript. Each script must assign module.exports with a function of type import("@hediet/debug-visualizer-data-extraction").LoadDataExtractorsFn. Paths must be absolute and can use the variable ${workspaceFolder}. Scripts are automatically reloaded when they are changed.

Example:

// @ts-check
/**
 * @type {import("@hediet/debug-visualizer-data-extraction").LoadDataExtractorsFn}
 */
module.exports = (register, helpers) => {
	register({
		id: "map",
		getExtractions(data, collector, context) {
			if (!(data instanceof Map)) {
				return;
			}

			collector.addExtraction({
				priority: 1000,
				id: "map",
				name: "Map",
				extractData() {
					return helpers.asData({
						kind: { table: true },
						rows: [...data].map(([k, v]) => ({
							key: k,
							value: v,
						})),
					});
				},
			});
		},
	});
};

Use the helpers object to access some magic functions. helpers.find(val => ...) can be used to find an object that is reachable by any variable in scope.

See Also

This extension works very well together with my library @hediet/node-reload for TypeScript/JavaScript. Together, they provide an interactive playground.

Contributing

Feel free to ping me on GitHub by opening an issue! Having runtime infrastructures for languages other than JavaScript would be awesome and I happily accept PRs!