2 releases

0.1.1	Oct 11, 2023
0.1.0	Mar 10, 2023

#10 in #visualize

MIT license

67KB
1.5K SLoC

dot-viewer

dot-viewer is a dot-format graph debugger in TUI, inspired by Vim.

1. Getting Started

a. Prerequisites

i. Graphviz

dot-viewer parses a dot format file using C bindings to Graphviz (v7.0.6).

The system environment should be able to find and include the following header files.

#include <gvc.h>
#include <cgraph.h>

Option 1. Installing Graphviz from Package Manager

Coming from Linux,

$ sudo apt install graphviz-dev

And coming from vanilla Ubuntu, you may want to install these too.

$ sudo apt install build-essentials cmake
$ sudo apt install clang

Coming from Mac,

$ brew install graphviz

And coming from Apple Silicon Mac, and add an environment variable,

export CPATH=/opt/homebrew/include

Option 2. Building Graphviz from Source

Or, try building from the source code following the guide.

ii. xdot.py

dot-viewer renders a subgraph with xdot.py, an interactive dot visualizer.

It is required that xdot is executable in command-line beforehand such that the following works.

$ xdot *.dot

b. Installation

i. Initialize

First initialize and update the submodule dot-graph.

$ git submodule init
$ git submodule update

ii. Run

Then run crate.

$ cargo run --release [path-to-dot-file]

This will open a TUI screen on the terminal.

2. Features

With dot-viewer, users may

traverse the graph in TUI using,

goto next/prev node of the currently selected node
fuzzy search on node name
regex search on node name and attributes

make and export subgraphs using,

subgraph tree selection
applying filter on search matches
neighboring n nodes of the currently selected node

Keybindings

General

Key	Command	Actions
	`:q<C-R>`	quit `dot-viewer`
	`:help<CR>`	show help
`esc`		go back to the main screen

Hit esc to go back to Normal mode whenever you are unsure of what you are doing...

Mode Switches

Key	From	To
`esc`	All	Normal
`/`	Normal	Fuzzy Search
`r`	Normal	Regex Search
`:`	Normal	Command

Normal

Key	Actions
`c`	close the current tab(view)
`h/l`	move focus between current, prevs, nexts list
`j/k`	traverse in focused list
`n/N`	move between matched nodes
`gg`	move to the topmost node in focused list
`G`	move to the bottom node in focused list
`tab`/`backtab`	move between tabs

Search

Key	Actions
`tab`	autocomplete search keyword
`enter`	apply search

e.g., in fuzzy search mode, /g1_s14_t100 and in regex search mode, r\(H: ., D: .\)

Command

Key	Command	Actions
	`filter`	apply filter on current matches, opening a new tab(view)
	`neighbors [depth]`	get up to `depth` neighbors of the current node in a new tab(view)
	`export [(opt) filename]`	export the current tab(view) to dot
	`xdot [(opt) filename]`	launch `xdot` with the filename or `exports/current.dot` by default
	`subgraph`	open a popup showing subgraph tree
`tab`		autocomplete command
`enter`		execute command

All exported files are saved in exports directory in the project root.

Most recently exported file is copied in exports/current.dot.

Key	Actions
`h/j/k/l`	traverse the tree
`enter`	change root to the selected subgraph, opening a new tab(view)

Key	Actions
`h/j/k/l`	traverse help messages

Dependencies

~16–29MB
~421K SLoC