git.iko.soy/helix
on 6c11708 help sign in
helix/docs/architecture.md
85 lines 3.3 kB history raw
2| Crate | Description |
3| ----------- | ----------- |
4| helix-core | Core editing primitives, functional. |
5| helix-syntax | Tree-sitter grammars |
6| helix-lsp | Language server client |
7| helix-view | UI abstractions for use in backends, imperative shell. |
8| helix-term | Terminal UI |
9| helix-tui | TUI primitives, forked from tui-rs, inspired by Cursive |
12This document contains a high-level overview of Helix internals.
14> NOTE: Use `cargo doc --open` for API documentation as well as dependency
15> documentation.
17## Core
19The core contains basic building blocks used to construct the editor. It is
20heavily based on [CodeMirror 6](https://codemirror.net/6/docs/). The primitives
21are functional: most operations won't modify data in place but instead return
22a new copy.
24The main data structure used for representing buffers is a `Rope`. We re-export
25the excellent [ropey](https://github.com/cessen/ropey) library. Ropes are cheap
26to clone, and allow us to easily make snapshots of a text state.
28Multiple selections are a core editing primitive. Document selections are
29represented by a `Selection`. Each `Range` in the selection consists of a moving
30`head` and an immovable `anchor`. A single cursor in the editor is simply
31a selection with a single range, with the head and the anchor in the same
32position.
34Ropes are modified by constructing an OT-like `Transaction`. It's represents
35a single coherent change to the document and can be applied to the rope.
36A transaction can be inverted to produce an undo. Selections and marks can be
37mapped over a transaction to translate to a position in the new text state after
38applying the transaction.
40> NOTE: `Transaction::change`/`Transaction::change_by_selection` is the main
41> interface used to generate text edits.
43`Syntax` is the interface used to interact with tree-sitter ASTs for syntax
44highling and other features.
46## View
48The `view` layer was supposed to be a frontend-agnostic imperative library that
49would build on top of `core` to provide the common editor logic. Currently it's
50tied to the terminal UI.
52A `Document` ties together the `Rope`, `Selection`(s), `Syntax`, document
53`History`, language server (etc.) into a comprehensive representation of an open
54file.
56A `View` represents an open split in the UI. It holds the currently open
57document ID and other related state.
59> NOTE: Multiple views are able to display the same document, so the document
60> contains selections for each view. To retrieve, `document.selection()` takes
61> a `ViewId`.
63The `Editor` holds the global state: all the open documents, a tree
64representation of all the view splits, and a registry of language servers. To
65open or close files, interact with the editor.
67## LSP
69A language server protocol client.
71## Term
73The terminal frontend.
75The `main` function sets up a new `Application` that runs the event loop.
77`commands.rs` is probably the most interesting file. It contains all commands
78(actions tied to keybindings).
80`keymap.rs` links commands to key combinations.
83## TUI / Term
85TODO: document Component and rendering related stuff