Ramify

Ramify is a Rust library for generating branch diagrams to visualize hierarchical data.

0       0        0         0
├┐      ├╮       ├┬┐       ├┬┐
1├┐     1╰╮      │1├┐      │1│
│2│     ├╮│      ││2│      2│└─┐
│3│     2│├╮     │3│├┐     │└─┐│
├┐│     │││3     │┌┘││     ├┬┐││
4││     ├││╯     ││┌┤│     │3│││
 5│     4││      │││4│     4┌┘││
┌┘6     │5│      ││5┌┘      5┌┘│
7       ├─╯      │6┌┘        6┌┘
        6        7┌┘          7
                  8

See the gallery for more images.

To use this library, simply describe the graph structure and associated metadata, and the branch diagram is generated automatically.

This library is specifically designed for ordered data: this library generates output similar to git log --graph --all, rather than the output of tree. A prototypical application is to visualize the undo-tree of a text file. The order is the timestamp of the edit, and the tree structure results from the undo relation.

Key features

• Single-pass layout algorithm which optimizes for width and appearance.
• Memory efficient streaming implementation: new vertices are not requested until the parent vertex has been rendered.
• Robust support for metadata via annotations and custom marker characters.
• Generic over ordered hierarchical data (directed acyclic graphs) with efficient iteration over immediate children.
• Memory-efficient streaming implementation with incremental diagram drawing.
• No unsafe code and no dependencies other than the standard library.

Interested? Check out the API documentation for more detail!

Usage examples can be found in the examples folder.

The output generated by this crate is highly configurable. Explore the various styles and configuration options with the gallery example:

cargo build --example gallery --release
./target/release/examples/gallery --help

Gallery

Basic examples with no annotation and various node markers

 0        0             0         ◊
 ├┬┐      ├┬┐           ├┬┐       ├┬┐
 │1├┐     │1├┬┐         │1│       │✕│
 ││2│     │││2├┬┐       2│└┐      │┌┼┐
 │3││     │││││3├┐      │└┐│      ││◊├┬┐
 │┌┘│     │││││││4      ├┐││      ││││◊│
 ││┌┼┐    ││││5│││      3│││      │◊││││
 │││4│    ││6│┌┘││      ┌┘││      │ ✕│││
 ││5┌┘    ││ 7│┌┘│      │┌┤│      │┌─┘◊│
 │6┌┘     ││┌─┘│ 8      │4││      │◊┌─┘│
 7┌┘      │││  9┌┘      5┌┘│      ├┐│┌─┘
  8       │││┌┬┘│        6┌┤      ✕│││
          ││││a┌┘         7│      ┌┘✕│
          ││b│┌┘           8      ◊┌─┘
          │c┌┘│                   │✕
          │││ d                   ◊
          ││e
          │f
          g

In the remaining examples, gallery is cargo run --example gallery --.

The first example above, with annotations associated with some vertices. Generate with gallery -g annotations -s sharpcorners.

0
├┬┐
│1├┐ An annotation
││││ with two lines
││2│
│3│├┐ Another annotation
│┌┘││
││┌┤│
│││4│ An annotation
│││┌┘ split over
││││  three lines
││5│
│6┌┘
7┌┘
 8

The same example, but with no extra padding and inverted. Generate with gallery -g annotations -s sharpcorners -i.

 8
7└┐
│6└┐
││5└┐
│││4│ An annotation
│││││ split over
│││││ three lines
││└┤│
│└┐││
│3│├┘ Another annotation
││2│
│1││ An annotation
││├┘ with two lines
├┴┘
0

An inverted example with merges, extra space between lines, extra padding between vertices, and box-drawing characters with doubled lines. Generate with gallery -g merge -s doubledlines -i --gutter-width 1 --row-padding 1

9
║
║   8
╚═╗ ╠═╗
7 ║ ║ ║
╚═╣ ║ ║
6 ║ ║ ║
╠═╝ ║ ║
5 ╔═╝ ║
╠═║═╗ ║
╠═╝ ║ ║
║ ╔═╝ ║
║ ║ 4 ║
║ ║ ║ ╚═╗
3 ║ ╚═╗ ║
╠═║═╗ ║ ║
║ ╠═╩═╝ ║
║ 2 ╔═══╝
║ ╠═╝
║ 1
╠═╝
0