# tree-mumu — Linux `tree`-style pretty-printer for Lava / MuMu values
**tree-mumu** is a small, focused plugin that renders any MuMu **Value** as
a multi-line, Linux `tree`-style diagram. It’s perfect for inspecting nested
arrays/objects and for logging data structures during development.
> Crate: `tree-mumu` → shared library name: **`libmumutree`**
> Works with **core-mumu v0.9.0‑rc.5** or later.
---
## Highlights
- **One function:** `tree:to_string(options, data) -> string`
- UTF box‑drawing glyphs by default (ASCII fallback available)
- Helpful leaf previews (strings, numbers, regex, functions, streams, etc.)
- **Options for quoting/types/index labels/depth capping**
- **Partial application** (including `_` placeholder) for ergonomic reuse
- Deterministic output; safe on cyclic refs (shows `↻`)
---
## Install & Build
You can build and install via Cargo or the included Makefile.
### Using Cargo (local build)
```bash
# Debug
cargo build
# Release
cargo build --release
```
The shared object will be produced as:
- Linux: `target/release/libmumutree.so`
- macOS: `target/release/libmumutree.dylib`
### Using Makefile (recommended for system install)
```bash
# Build (debug)
make
# Build (release)
make release
# Install the release .so/.dylib to /usr/local/lib and run ldconfig (Linux)
sudo make install
# Uninstall
sudo make uninstall
```
> If you prefer a different lib directory: `make install LIBDIR=/path/to/lib`
After installing to a standard library path, you can load the plugin by name:
`extend("tree")`. You can also load it from an explicit path, e.g.:
`extend("/full/path/to/libmumutree.so")`.
---
## Quick Start
```mu
extend("tree")
extend("std")
data = [
user: [name:"Alice", age:30],
items: [1, 2, [3, 4]]
]
// Basic: default UTF box drawing, root label "data"
std:log( tree:to_string([root:"data"], data) )
// ASCII fallback + show leaf types
std:log( tree:to_string([ascii:true, show_types:true], data) )
// Re-usable partially-applied function
to_s = tree:to_string([root:"ROOT", quote_strings:false])
std:log( to_s(data) )
// Placeholders work too
p = tree:to_string(_, _)
q = p([root:"X", index_labels:true])
std:log( q([a:[1,2,3], b:[c:"hi"]]) )
```
### Sample Output (UTF)
```
data
├── user
│ ├── name: "Alice"
│ └── age: 30
└── items
├── [0]: 1
├── [1]: 2
└── [2]
├── [0]: 3
└── [1]: 4
```
> Use `ascii:true` for environments that can’t render UTF box‑drawing glyphs.
---
## API
### `tree:to_string(options, data) -> string`
Renders `data` into a multi‑line string. The first line is the **root label**;
children are laid out with Linux `tree`‑style connectors.
**Options** (a keyed array; all optional):
| `ascii` | bool | `false` | Use ASCII `+--`, `|` instead of UTF box‑drawing. |
| `root` | str | `"<root>"` | Root label for the rendered tree. |
| `quote_strings` | bool | `true` | Quote & escape string leaves. |
| `show_types` | bool | `false` | Append a `(type)` suffix to leaf previews. |
| `index_labels` | bool | `true` | Show `[i]` labels for array items. |
| `max_depth` | int | _none_ | Depth cap (≥0). At the limit a single `…` node is shown. |
**Partial application** is supported:
- `tree:to_string(opts)` → returns a function waiting for `data`
- Placeholders (`_`) may be used on either side:
`tree:to_string(_, data)` or `tree:to_string(opts, _)`
**Leaf previews** try to be compact and helpful:
- Strings (optionally quoted/escaped), numbers, booleans
- Functions show as `[Function]`, streams as `<Stream id=…>`
- Arrays show a compact tag if rendered as a leaf (e.g. `[int; 3]`, `{…}`)
- Regex prints as `Regex(/patternflags/)`
- Cycles are detected and marked with `↻`
---
## Behavior Notes
- The renderer walks **arrays**, **keyed arrays (objects)**, **2‑D arrays**,
**mixed arrays**, and **references** (`&x`). References are de‑referenced,
with cycle detection to avoid infinite recursion.
- When `index_labels:true`, children of arrays are labeled `[0]`, `[1]`, …
- For 2‑D arrays, each row becomes a child under its index.
- When `max_depth` is hit, that branch renders a single `…` node.
---
## Examples
This repository ships two runnable examples:
```text
examples/basic.mu
examples/to_string.mu
```
Run them with your `lava` runner, e.g.:
```bash
lava examples/to_string.mu
```
---
## Loading the Plugin
The Lava/MuMu loader looks for `libmumu<name>.*`. After installation to a
standard location, use:
```mu
extend("tree")
```
Or from a specific file path:
```mu
extend("/usr/local/lib/libmumutree.so") // Linux
// extend("/usr/local/lib/libmumutree.dylib") // macOS
```
---
## Compatibility
- **core-mumu**: v0.9.0‑rc.5+
- Host (native) builds are supported; WASM builds do not expose dynamic loading.
---
## Development
Repository structure (relevant parts):
```
src/
lib.rs // plugin entrypoint (Cargo_lock)
register/ // public bridges
to_string.rs // registers tree:to_string
share/ // rendering internals
glyphs.rs // UTF/ASCII glyph sets, helpers
label.rs // leaf/type labelling
walk.rs // Value -> logical Node tree
render.rs // Node -> lines
to_string.rs // argument parsing + partials
```
### Tests / Local smoke
You can quickly try the renderer using the example scripts above, or in the
REPL by loading the plugin and calling `tree:to_string` directly.
---
## License
Dual-licensed under **MIT OR Apache-2.0**. See `LICENSE-MIT` and `LICENSE-APACHE`.
---
## Acknowledgements
Made for the Lava / MuMu ecosystem. Thanks to all contributors to `core-mumu`
for the excellent interpreter and plugin tooling.