Skip to content

README.md

Latest commit

 

History

History
299 lines (213 loc) · 13.4 KB

README.md

File metadata and controls

299 lines (213 loc) · 13.4 KB

Debug Visualizer

A VS Code extension for visualizing data structures while debugging. Like the VS Code's watch view, but with custom 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 Rudimentary 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.

You can refresh the evaluation and open the current visualizer view into a new browser window by using the top right buttons. You can also unfold the details pane to select a Data Extractor and a Visualizer.

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

Visualizers consume specific JSON data. See Integrated Visualizers for the schema of supported JSON data.

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" }".

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.

Integrated Visualizers

The following visualizers are built into this extension.

Graph Visualization

Demo. The Graphviz and vis.js visualizers render data that matches the Graph interface.

interface Graph {
	kind: { graph: true };
	nodes: NodeGraphData[];
	edges: EdgeGraphData[];
}

interface NodeGraphData {
	id: string;
	label?: string;
	color?: string;
	shape?: "ellipse" | "box";
}

interface EdgeGraphData {
	from: string;
	to: string;
	label?: string;
	id?: string;
	color?: string;
	dashes?: boolean;
}

The graphviz visualizer uses the SVG viewer to render the SVG created by viz.js.

Plotly Visualization

Demo. The plotly visualizer uses plotly and can visualize JSON data matching the following interface:

export interface Plotly {
	kind: { plotly: true };
	data: Partial<Plotly.Data>[];
}
// See plotly docs for Plotly.Data.

Tree Visualization

The tree visualizer renders data that matches the Tree interface.

interface Tree<TData = unknown> {
	kind: { tree: true };
	root: TreeNode<TData>;
}
interface TreeNode<TExtraData> {
	id: string | undefined;
	name: string;
	value: string | undefined;
	emphasizedValue: string | undefined;
	children: TreeNode<TExtraData>[];
	data: TExtraData;
	isMarked: boolean;
}

AST Visualization

Demo. The AST (Abstract Syntax Tree) visualizer renders data that matches the Ast interface.

interface Ast
	extends Tree<{
			position: number;
			length: number;
		}>,
		Text {
	kind: { text: true; tree: true; ast: true };
}

Additionally to the tree view, the source code is rendered and when selecting an AST node, its span in the source code is highlighted.

Grid Visualization

Visualizes data matching the following interface:

export interface Grid {
	kind: { array: true };
	columnLabels?: { label?: string }[];
	rows: {
		label?: string;
		columns: {
			content?: string;
			tag?: string;
			color?: string;
		}[];
	}[];
	markers?: {
		id: string;

		row: number;
		column: number;
		rows?: number;
		columns?: number;

		label?: string;
		color?: string;
	}[];
}

Text Visualization

The text visualizer renders data that matches the Text interface.

interface Text {
	kind: { text: true };
	text: string;
	mimeType?: string;
	fileName?: string;
}

The mimeType and the file extension of fileName are used for syntax highlighting.

SVG Visualization

The SVG visualizer renders data that matches the Svg interface. The actual SVG data must be stored in text.

interface Svg extends Text {
	kind: { text: true; svg: true };
}

Dot Graph Visualization

The Graphviz Dot visualizer renders data that matches the DotGraph interface.

interface DotGraph extends Text {
	kind: { text: true; dotGraph: true };
}

Viz.js (Graphviz) is used for rendering.

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 'getDebugVisualization'

Calls .getDebugVisualization() 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.

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!