# Ramify
Ramify is a Rust library for generating *branch diagrams* to visualize hierarchical data.
```txt
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](https://github.com/alexrutar/ramify#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](https://en.wikipedia.org/wiki/Directed_acyclic_graph)) 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](https://docs.rs/ramify/latest/ramify/) for more detail!
Usage examples can be found in the [examples folder](https://github.com/alexrutar/ramify/tree/master/examples).
The output generated by this crate is [highly configurable](https://docs.rs/ramify/latest/ramify/writer/).
Explore the various styles and configuration options with the `gallery` example:
```sh
cargo build --example gallery --release
./target/release/examples/gallery --help
```
## Gallery
Basic examples with no annotation and various node markers
```txt
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`.
```txt
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`.
```txt
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`
```txt
9
║
║ 8
╚═╗ ╠═╗
7 ║ ║ ║
╚═╣ ║ ║
6 ║ ║ ║
╠═╝ ║ ║
5 ╔═╝ ║
╠═║═╗ ║
╠═╝ ║ ║
║ ╔═╝ ║
║ ║ 4 ║
║ ║ ║ ╚═╗
3 ║ ╚═╗ ║
╠═║═╗ ║ ║
║ ╠═╩═╝ ║
║ 2 ╔═══╝
║ ╠═╝
║ 1
╠═╝
0
```