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), markers and the view.
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), in the statusbar minimodes will be present too, those that receive more keypresses to offer additional functionality, such as finding in files, finding in the current buffer, open files and replacing a character.
libvaxis is in charge of rendering the text and all the interface in Linux, MacOS, FreeBSD, and Android via Termux, while in Windows there is an special GUI.
Thespian is in charge of processes synchronization and allows 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 and need to return an answer, all this without blocking the user interface. Tree-sitter queries to highlight the current file of a particular language and LSPs usually take time by the nature of operations they perform, integration with git and running a shell command via a task all are coordinated thanks to the infrastructure that Thespian provides.
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 several actions that ease developing Flow itself and also are used to offer feedback via logview. To view logs use f11 to toggle the previous messages, or alternatively, open flow with the option --show-logs.
To log something, first, import log
const log = @import("log");
Instantiate the logger, replacing prefix with something meaningful to differentiate from other logging messages.
const logger = log.logger("prefix");
defer logger.deinit();
Log something
logger.print("{} unsaved buffer(s) remaining", .{remaining});
There are situations when you press some keys without the expected behavior happening, to review if flow is getting the keys, the keybindings are associated, and are executing the desired command, or maybe your desktop environment or something else is capturing them, you will want to invoke flow with the option --show-input.