docs: write README for Show HN launch
All 10 sections per the launch plan: title, pitch, demo GIF placeholder, Lotus Improv context, quick start, key bindings, installation (Nix/crates.io/ prebuilt), codebase overview, expectations disclaimer, license. Under 100 lines, no badges or TOC. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
96
README.md
Normal file
96
README.md
Normal file
@ -0,0 +1,96 @@
|
|||||||
|
# improvise
|
||||||
|
|
||||||
|
*Terminal pivot-table modeling in the spirit of Lotus Improv — multidimensional cells, formulas over dimensions instead of cell addresses, and vim-style keybindings for reassigning axes on the fly.*
|
||||||
|
|
||||||
|

|
||||||
|
|
||||||
|
## Why this exists
|
||||||
|
|
||||||
|
Lotus Improv (NeXT, 1991) separated data from its presentation: cells were
|
||||||
|
addressed by named dimensions, not grid coordinates, and rearranging a view
|
||||||
|
didn't break formulas. That idea never made it into mainstream tools. Excel
|
||||||
|
pivot tables borrowed the visual rearrangement but kept cell-address formulas.
|
||||||
|
Terminal data tools like sc-im and VisiData do different things well — sc-im is
|
||||||
|
a traditional spreadsheet, VisiData is a data explorer — but neither offers the
|
||||||
|
dimension-keyed data model that made Improv interesting. improvise is a small
|
||||||
|
attempt to bring that model to a modern terminal, with a formula language that
|
||||||
|
references category and item names, views that can be rearranged with a single
|
||||||
|
keystroke, and a plain-text file format you can diff in git.
|
||||||
|
|
||||||
|
## Quick start
|
||||||
|
|
||||||
|
```sh
|
||||||
|
nix develop
|
||||||
|
cargo build --release
|
||||||
|
./target/release/improvise examples/demo.improv
|
||||||
|
```
|
||||||
|
|
||||||
|
Or import your own CSV:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./target/release/improvise import path/to/data.csv
|
||||||
|
```
|
||||||
|
|
||||||
|
## Key bindings to try first
|
||||||
|
|
||||||
|
| Key | Action |
|
||||||
|
|-----|--------|
|
||||||
|
| `T` | Enter tile mode — reassign category axes |
|
||||||
|
| `[` / `]` | Cycle through page-axis items |
|
||||||
|
| `>` | Drill into an aggregated cell |
|
||||||
|
| `<` | Return from drill-down |
|
||||||
|
| `F` | Open the formula panel |
|
||||||
|
| `t` | Transpose rows and columns |
|
||||||
|
| `?` / `F1` | Full key reference |
|
||||||
|
| `:w` | Save |
|
||||||
|
| `:q` | Quit |
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### From source with Nix (preferred)
|
||||||
|
|
||||||
|
```sh
|
||||||
|
nix develop
|
||||||
|
cargo build --release
|
||||||
|
# optionally install to your PATH:
|
||||||
|
cargo install --path .
|
||||||
|
```
|
||||||
|
|
||||||
|
### From crates.io
|
||||||
|
|
||||||
|
```sh
|
||||||
|
cargo install improvise
|
||||||
|
```
|
||||||
|
|
||||||
|
### Prebuilt binaries
|
||||||
|
|
||||||
|
See the [GitHub releases page](https://github.com/fiddlerwoaroof/improvise/releases)
|
||||||
|
for prebuilt binaries (Linux x86_64, macOS Intel and Apple Silicon).
|
||||||
|
|
||||||
|
## What's interesting about the codebase
|
||||||
|
|
||||||
|
The data model stores every cell at the intersection of named categories and
|
||||||
|
items — `(Region=East, Measure=Revenue)` — rather than at a grid address like
|
||||||
|
`B3`. A view is a configuration that assigns each category to a row, column,
|
||||||
|
page, or hidden axis, and the grid layout is computed as a pure function from
|
||||||
|
`(Model, View)` to `GridLayout`. Transposing a pivot is just swapping the row
|
||||||
|
and column assignments; records mode is just assigning the virtual `_Index` and
|
||||||
|
`_Dim` categories to particular axes. The formula language references dimension
|
||||||
|
names (`Profit = Revenue - Cost`), so formulas survive any rearrangement
|
||||||
|
without rewriting. All user actions go through a command/effect pipeline:
|
||||||
|
commands are pure functions that read an immutable context and return a list of
|
||||||
|
effects, which are the only things that mutate state. The same command registry
|
||||||
|
serves both the interactive TUI and the headless `cmd`/`script` CLI
|
||||||
|
subcommands. Models persist to a markdown-like `.improv` format that is
|
||||||
|
human-readable, git-diffable, and optionally gzip-compressed.
|
||||||
|
|
||||||
|
## Expectations
|
||||||
|
|
||||||
|
improvise is a personal project I built for my own use. I'm sharing it because
|
||||||
|
other people might find it useful, but I can't promise active maintenance or
|
||||||
|
feature development. Issues and PRs are welcome but may not get a fast
|
||||||
|
response. If you want to build on it, fork away.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
Reference in New Issue
Block a user