This document describes in a general way, concepts that help to understand how the code is organized and where to look at when starting to contribute developing Flow Control. Make sure you have read first help.md and use the editor at least in flow mode. We recommend reading the deepwiki description for a more in depth documentation and joining Discord to ask from the simplest. If something does not look accurate on this documentation or in deepwiki. Do not hesitate to ask in the channels and open a PR to improve anything.
The foundational unit is the Buffer that holds the document in memory; there might be various opened files, each one loaded in a buffer. A buffer can be ephemeral, meaning, it is not related to a file, that might be the product of a Task run. Buffers are implementations of ropes that offer multiple services such as insert characters, load from file, write to file, load from string, return as string, tell if it has unsaved changes(dirty), among many others. A buffer can have multiple Selections and Cursors interacting with it. The Buffer Manager offers services around the set of buffers.
A Project initially is the directory where flow is opened at, once opened, it starts processes to discover the files under the directory hierarchy, interact with lsp and git. When flow is opened, only one active project is loaded in the current session. The Project Manager offers services around the set of projects.
When a buffer is active, it has an Editor attached to it; an editor might have associated tree-sitter support, given the file type detected, and offers common services that are aimed to be used by Commands to manipulate the contents of a buffer at a higher level, the selections, cursors, cursor selections CurSel and the View. The commands are used by Modes with Keybindings. The main mode is Flow and the keybindings can be used to map to a mode built up entirely on solely calling already created commands. An example of a mode created by command composition is Emacs mode, for instance, it’s possible to create a nano mode with just keybindings. In the other hand, Vim and Helix modes have particular definitions for commands that interact with the buffers, being modal editors.
Tui governs it all offering support for Palettes that are known in other environments as pickers, as well as offering information through a set of _views (i.e. logview, inputview, inspector_view) and status (i.e. tabs, clock, branch, linenum).
libvaxis is in charge of rendering the text and all the interface in Linux, MacOS, FreeBSD, while in Windows there is an special GUI.
Thespian is in charge of sending messages between different flow components, for example, when a widget needs updating information from changing states of internal data and when components or external processes take time. For example, tree-sitter queries to highlight the current file of a particular language, LSPs, git, running a shell command via a task.
There are plenty of programming languages that use tree-sitter via flow-syntax and whose language servers and formatters are configured via file_type_lsp. Currently one Language Server is supported for each language.
The clipboard is used for copy, paste operations and there is also support to use the system clipboard, copying and pasting to/from it.
Logging support offers various levels to give feedback for various actions that ease developing Flow itself and also are used to offer feedback via logview.
We have some contribution guidelines.