@@ -8,68 +8,78 @@
8| helix-term | Terminal UI |
8| helix-term | Terminal UI |
9| helix-tui | TUI primitives, forked from tui-rs, inspired by Cursive |
9| helix-tui | TUI primitives, forked from tui-rs, inspired by Cursive |
12−
12+This document contains a high-level overview of Helix internals.
13−- server-client architecture via gRPC, UI separate from core
13+
14−- multi cursor based editing and slicing
14+> NOTE: Use `cargo doc --open` for API documentation as well as dependency
15−- WASM based plugins (builtin LSP & fuzzy file finder)
15+> documentation.
17−Structure similar to codemirror:
17+## Core
19−- text (ropes)
19+The core contains basic building blocks used to construct the editor. It is
20−- transactions
20+heavily based on [CodeMirror 6](https://codemirror.net/6/docs/). The primitives
21− - changes
21+are functional: most operations won't modify data in place but instead return
22− - invert changes (generates a revert)
22+a new copy.
23− - annotations (time changed etc)
23+
24− - state effects
24+The main data structure used for representing buffers is a `Rope`. We re-export
25− - additional editor state as facets
25+the excellent [ropey](https://github.com/cessen/ropey) library. Ropes are cheap
26−- snapshots as an async view into current state
26+to clone, and allow us to easily make snapshots of a text state.
27−- selections { anchor (nonmoving), head (moving) from/to } -> SelectionSet with a primary
27+
28− - cursor is just a single range selection
28+Multiple selections are a core editing primitive. Document selections are
29−- markers
29+represented by a `Selection`. Each `Range` in the selection consists of a moving
30− track a position inside text that synchronizes with edits
30+`head` and an immovable `anchor`. A single cursor in the editor is simply
31−- { doc, selection, update(), splice, changes(), facets, tabSize, identUnit, lineSeparator, changeFilter/transactionFilter to modify stuff before }
31+a selection with a single range, with the head and the anchor in the same
32−- view (actual UI)
32+position.
33−- viewport(Lines) -> what's actually visible
33+
34−- extend the view via Decorations (inline styling) or Components (UI)
34+Ropes are modified by constructing an OT-like `Transaction`. It's represents
35− - mark / wieget / line / replace decoration
35+a single coherent change to the document and can be applied to the rope.
36−- commands (transform state)
36+A transaction can be inverted to produce an undo. Selections and marks can be
37−- movement
37+mapped over a transaction to translate to a position in the new text state after
38−- selection extension
38+applying the transaction.
40−- indentation
40+> NOTE: `Transaction::change`/`Transaction::change_by_selection` is the main
41−- keymap (maps keys to commands)
41+> interface used to generate text edits.
42−- history (undo tree via immutable ropes)
42+
43− - undoes transactions via reverts
43+`Syntax` is the interface used to interact with tree-sitter ASTs for syntax
44−- (collab mode)
44+highling and other features.
45−- gutter (line numbers, diagnostic marker, etc) -> ties into UI components
45+
46−- rangeset/span -> mappable over changes (can be a marker primitive?)
46+## View
47−- syntax (treesitter)
47+
48−- fold
48+The `view` layer was supposed to be a frontend-agnostic imperative library that
49−- selections (select mode/multiselect)
49+would build on top of `core` to provide the common editor logic. Currently it's
50−- matchbrackets
50+tied to the terminal UI.
52−- special-chars (shows dots etc for specials)
52+A `Document` ties together the `Rope`, `Selection`(s), `Syntax`, document
53−- panel (for UI: file pickers, search dialogs, etc)
53+`History`, language server (etc.) into a comprehensive representation of an open
54−- tooltip (for UI)
54+file.
56−- lint (async linters)
56+A `View` represents an open split in the UI. It holds the currently open
57−- lsp
57+document ID and other related state.
59−- stream-syntax
59+> NOTE: Multiple views are able to display the same document, so the document
60−- autocomplete
60+> contains selections for each view. To retrieve, `document.selection()` takes
61−- comment (gc, etc for auto commenting)
61+> a `ViewId`.
63−- terminal mode?
63+The `Editor` holds the global state: all the open documents, a tree
64−
64+representation of all the view splits, and a registry of language servers. To
65−- plugins can contain more commands/ui abstractions to use elsewhere
65+open or close files, interact with the editor.
66−- languageData as presets for each language (syntax, indent, comment, etc)
66+
69−- motions/operators/text objects
69+A language server protocol client.
73−- marks
73+The terminal frontend.
75−- conceal for markdown markers, etc
75+The `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.
85+TODO: document Component and rendering related stuff