61 lines
3.8 KiB
Markdown
61 lines
3.8 KiB
Markdown
# vamp
|
|
|
|
A modal Rust editor with a replaceable frontend and subprocess-isolated Ruby plugins.
|
|
|
|
## Run
|
|
|
|
Requires current stable Rust and an interactive terminal. Ruby 2.6+ with its standard-library JSON support is required only for configuration/plugins; no Ruby gems are needed to run vamp itself.
|
|
|
|
```sh
|
|
cargo run -- --no-config notes.txt
|
|
cargo run -- --config examples/config.rb notes.txt
|
|
```
|
|
|
|
Without a file, vamp opens an unnamed buffer. A nonexistent file opens an empty buffer. `cargo run -- --help` lists the command-line options.
|
|
|
|
## Getting started
|
|
|
|
Vamp starts in Normal mode. Press `i`, type text, then Esc to return to Normal. Type `:w` and Enter to save, or `:w path` to name an unnamed buffer. Type `:q` and Enter to quit; it refuses unsaved changes in any open buffer. `:q!` explicitly discards changes and quits.
|
|
|
|
| Task | Default keys |
|
|
| --- | --- |
|
|
| Move in Normal | `h`/`j`/`k`/`l` or arrows; `w`/`b`/`e` for words |
|
|
| Enter/leave Insert | `i` / Esc |
|
|
| Save in Normal | Space then `w`, or `:w` then Enter |
|
|
| Undo/redo in Normal | `u` / `U` (Shift+u) |
|
|
| Search in Normal | `/`, type a literal query, Enter; `n`/`N` for next/previous |
|
|
| Select/copy/cut | `v` characterwise or `V` whole rows, move to extend, then `y`/`d` in Visual |
|
|
| Paste in Normal | `p`/`P` after/before the caret or row for linewise fragments; system clipboard by default |
|
|
| Command palette | Ctrl+p; type to filter, arrows select, Enter accepts, Esc cancels |
|
|
| Floating/docked explorer in Normal or Visual | Space then `o` / Space then `e` |
|
|
|
|
Space is the default leader: press its suffix keys in order, not simultaneously. The [editing guide](docs/editing.md) contains the complete key table and behavior reference.
|
|
|
|
## Configuration
|
|
|
|
By default, vamp loads `$XDG_CONFIG_HOME/vamp/config.rb`, or `~/.config/vamp/config.rb` when that environment variable is unset. `--config path` selects a file explicitly; `--no-config` bypasses Ruby entirely and uses defaults.
|
|
|
|
Start with [`examples/config.rb`](examples/config.rb). The [configuration reference](docs/configuration.md) covers preferences, bindings, and native LSP setup. Language servers are **disabled by default**; install a trusted server and explicitly enable it.
|
|
|
|
Ruby configuration and plugins run with your account's filesystem/process permissions. Subprocess isolation is **not a security sandbox**; load only trusted scripts.
|
|
|
|
## Current limits
|
|
|
|
- One visible buffer at a time; no splits/tabs or graphical frontend.
|
|
- Modal editing, not full Vim compatibility: characterwise and linewise Visual selections, but no block selection, named registers, or Vim operators. Search is literal, case-sensitive, and single-line.
|
|
- Native opt-in LSP supports diagnostics, go-to-definition, plain-text hover, and automatic semantic highlighting—not completion, rename, formatting, or code actions.
|
|
- System clipboard access supports macOS and Linux. Separate clipboard mode keeps internal editing available on unsupported/headless environments.
|
|
|
|
Performance and subprocess limits are documented in [development](docs/development.md#performance-and-process-limits).
|
|
|
|
## Documentation
|
|
|
|
| Guide | Contents |
|
|
| --- | --- |
|
|
| [Editing](docs/editing.md) | Keys, motions/counts, selections, repeat, clipboard, search, buffers, explorer, palette, syntax highlighting |
|
|
| [Configuration](docs/configuration.md) | Ruby startup, preferences, action/mode reference, key notation, leader/list/tree bindings, native LSP |
|
|
| [Plugins](docs/plugins.md) | Ruby API, capabilities, effects, asynchronous callbacks, isolation, messaging protocol |
|
|
| [Architecture](docs/architecture.md) | Module ownership, session/frontend contracts, terminal lifecycle, syntax caches, native workers |
|
|
| [Development](docs/development.md) | Verification commands, test organization, performance and process limits |
|
|
| [Project context](CONTEXT.md) | Terminology and configuration-interface conventions |
|