git.iko.soy/helix
on 376c19e help sign in
helix/docs/architecture.md
111 lines 4.8 kB history raw
2| Crate | Description |
3| ----------- | ----------- |
4| helix-core | Core editing primitives, functional. |
5| helix-lsp | Language server client |
6| helix-dap | Debug Adapter Protocol (DAP) client |
7| helix-loader | Functions for building, fetching, and loading external resources |
8| helix-view | UI abstractions for use in backends, imperative shell. |
9| helix-term | Terminal UI |
10| helix-tui | TUI primitives, forked from tui-rs, inspired by Cursive |
13This document contains a high-level overview of Helix internals.
15> NOTE: Use `cargo doc --open` for API documentation as well as dependency
16> documentation.
18## Core
20The core contains basic building blocks used to construct the editor. It is
21heavily based on [CodeMirror 6](https://codemirror.net/6/docs/). The primitives
22are functional: most operations won't modify data in place but instead return
23a new copy.
25The main data structure used for representing buffers is a `Rope`. We re-export
26the excellent [ropey](https://github.com/cessen/ropey) library. Ropes are cheap
27to clone, and allow us to easily make snapshots of a text state.
29Multiple selections are a core editing primitive. Document selections are
30represented by a `Selection`. Each `Range` in the selection consists of a moving
31`head` and an immovable `anchor`. A single cursor in the editor is simply
32a selection with a single range, with the head and the anchor in the same
33position.
35Ropes are modified by constructing an OT-like `Transaction`. It represents
36a single coherent change to the document and can be applied to the rope.
37A transaction can be inverted to produce an undo. Selections and marks can be
38mapped over a transaction to translate to a position in the new text state after
39applying the transaction.
41> NOTE: `Transaction::change`/`Transaction::change_by_selection` is the main
42> interface used to generate text edits.
44`Syntax` is the interface used to interact with tree-sitter ASTs for syntax
45highlighting and other features.
47## View
49The `view` layer was supposed to be a frontend-agnostic imperative library that
50would build on top of `core` to provide the common editor logic. Currently it's
51tied to the terminal UI.
53A `Document` ties together the `Rope`, `Selection`(s), `Syntax`, document
54`History`, language server (etc.) into a comprehensive representation of an open
55file.
57A `View` represents an open split in the UI. It holds the currently open
58document ID and other related state. Views encapsulate the gutter, status line,
59diagnostics, and the inner area where the code is displayed.
61> NOTE: Multiple views are able to display the same document, so the document
62> contains selections for each view. To retrieve, `document.selection()` takes
63> a `ViewId`.
65`Info` is the autoinfo box that shows hints when awaiting another key with bindings
66like `g` and `m`. It is attached to the viewport as a whole.
68`Surface` is like a buffer to which widgets draw themselves to, and the
69surface is then rendered on the screen on each cycle.
71`Rect`s are areas (simply an x and y coordinate with the origin at the
72screen top left and then a height and width) which are part of a
73`Surface`. They can be used to limit the area to which a `Component` can
74render. For example if we wrap a `Markdown` component in a `Popup`
75(think the documentation popup with space+k), Markdown's render method
76will get a Rect that is the exact size of the popup.
78Widgets are called `Component`s internally, and you can see most of them
79in `helix-term/src/ui`. Some components like `Popup` and `Overlay` can take
80other components as children.
82`Layer`s are how multiple components are displayed, and is simply a
83`Vec<Component>`. Layers are managed by the `Compositor`. On each top
84level render call, the compositor renders each component in the order
85they were pushed into the stack. This makes multiple components "layer"
86on top of one another. Hence we get a file picker displayed over the
87editor, etc.
89The `Editor` holds the global state: all the open documents, a tree
90representation of all the view splits, the configuration, and a registry of
91language servers. To open or close files, interact with the editor.
93## LSP
95A language server protocol client.
97## Term
99The terminal frontend.
101The `main` function sets up a new `Application` that runs the event loop.
103`commands.rs` is probably the most interesting file. It contains all commands
104(actions tied to keybindings).
106`keymap.rs` links commands to key combinations.
109## TUI / Term
111TODO: document Component and rendering related stuff