Update architecture.md

docs/architecture.md

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

helix-core/src/lib.rs

@@ -13,7 +13,7 @@ mod position;
 pub mod register;
 pub mod search;
 pub mod selection;
-pub mod state;
+mod state;
 pub mod syntax;
 mod transaction;