DOCSEARCHbyAlgolia
Submit Docs

Flow Control Documentation

repository·master·Indexed 24 days ago

https://github.com/neurocyte/flow

A high-performance, TUI-based text editor written in Zig featuring a hybrid rope/piece-table buffer system, tree-sitter syntax highlighting, and support for multiple keybinding modes including Vim, Emacs, and Helix. Documentation covers installation via zig 0.16, CLI usage, configuration management, and system requirements such as 24bit color terminal support and NerdFonts.

Tokens
3.2K
Snippets
7
Records
20
Agent score
30%

What's inside Flow Control

  1. System Requirements for Flow Control

    master

    To ensure full functionality, your environment should meet the following requirements:

    • Terminal: A modern terminal with 24bit color support. Recommended terminals are Kitty, Foot, and Ghostty. Zellij is also supported. Other terminals may have reduced functionality.
    • Keyboard Protocol: Ideally, your terminal should support the kitty keyboard protocol.
    • Fonts: NerdFont support is required (either via terminal font fallback or a patched font).
    • Locale: A UTF-8 locale must be configured.

  2. Use keybindings and commands in Flow Control

    master

    Flow Control supports multiple keybinding modes including Flow (GUI IDE style), Emacs, Vim, and Helix.

    Essential Shortcuts

    • Open Help/Manual: F1
    • Switch Keybinding Mode: F4 (cycles through available modes)
    • Command Palette: ctrl+shift+p or alt+x
    • List All Keybindings/Commands: ctrl+F2

    Customizing Keybindings

    To create or modify keybinding modes:

    1. Open the Command Palette and run the Edit keybindings command.
    2. This saves the current mode to a file and opens it for editing.
    3. To create an entirely new mode, save your customized bindings under a new name in the same directory.
    4. Note: Keybinding changes require a restart of Flow Control to take effect.

  3. Install Flow Control from source

    master

    To build Flow Control, ensure you have zig 0.16 installed. The build process produces a single, statically linked binary that includes all necessary tree-sitter parsers and queries, requiring no additional runtime files.

    Standard Build

    Build with optimizations enabled:

    zig build -Doptimize=ReleaseSafe

    Generic CPU Support

    If you encounter illegal instruction errors on your target machine, add -Dcpu=baseline to the build command to ensure compatibility with older or more generic CPUs:

    zig build -Doptimize=ReleaseSafe -Dcpu=baseline

    Cross-Compilation

    You can cross-compile from any host to various targets using the -Dtarget flag. Note that cross-compiled binaries use generic CPU support by default.

    Examples:

    • Windows (x86_64): zig build -Doptimize=ReleaseSafe -Dtarget=x86_64-windows --prefix zig-out/x86_64-windows
    • macOS: zig build -Doptimize=ReleaseSafe -Dtarget=x86_64-macos-none --prefix zig-out/x86_64-macos
    • Linux (aarch64 musl): zig build -Doptimize=ReleaseSafe -Dtarget=aarch64-linux-musl --prefix zig-out/x86_64-linux

    The resulting binary will be located in zig-out/bin/flow.

  4. Run and use the Flow Control binary

    master

    The Flow Control binary is named flow. You can run it directly or install it to your system path.

    Installation to Path

    To install to a system-wide path (requires sudo):

    sudo cp zig-out/bin/flow /usr/local/bin

    To install to your local user directory using Zig:

    zig build -Doptimize=ReleaseSafe --prefix ~/.local

    Basic Usage

    Open specific files:

    flow fileA.zig fileB.zig

    Note: The last file specified will be the active one. Previous files are added to the recent files list in reverse order. Switch to recent files using Ctrl-e.

    Open at a specific line:

    • Using colon: flow file.txt:123
    • Using Vim-style: flow file.txt +123

    Force a language: Use the --language option to manually set the file type:

    flow --language bash ~/.bash_profile

    Use flow --list-languages to see all supported language names or flow --help for all command line options.

  5. Configure Flow Control

    master

    Configuration in Flow Control is primarily managed dynamically through UI commands.

    Configuration Locations

    • Linux: ~/.config/flow (Config) and ~/.local/state/flow (Logs, traces, and MRU lists).
    • Windows: %APPDATA%\Roaming\flow (Config and State).
    • macOS: Managed by the system in a standard application state directory.

    Managing Configuration Files

    Instead of searching for files manually, use the Command Palette (ctrl+shift+p or alt+x) and look for commands starting with Edit (e.g., Edit file type configuration).

    File Type Configuration

    You can configure existing file types or create new ones by adding a .conf file to the file_type directory. It is recommended to inspect existing configuration files to see available options.

  6. Manage keybind namespaces

    master

    Keybindings in Flow Control are organized into namespaces. You can programmatically manage these namespaces to load or save custom keymap configurations.

    • list_keybind_namespaces(allocator): Returns a list of all available namespace names.
    • read_keybind_namespace(allocator, namespace_name): Reads the content of a specific namespace file.
    • write_keybind_namespace(namespace_name, content): Writes content to a specific namespace file.
    pub fn list_keybind_namespaces(allocator: std.mem.Allocator) ![]const []const u8

pub fn read_keybind_namespace(allocator: std.mem.Allocator, namespace_name: []const u8) ?[]const u8

pub fn write_keybind_namespace(namespace_name: []const u8, content: []const u8) !void

  7. List available themes

    master
    Use list_themes(allocator: std.mem.Allocator) to retrieve a list of available theme names. It scans the theme directory and returns an array of strings representing the filenames (without extensions) of the theme files found.

  9. Check if a path is a directory or a file

    master

    Use these utility functions to verify path types:

    • is_directory(rel_path: []const u8): Returns true if the path exists and is a directory.
    • is_file(rel_path: []const u8): Returns true if the path exists and is a file.

  10. Manage UI themes

    master

    Themes are stored as files that can be read and written to manage the visual appearance of the editor.

    • read_theme(allocator, theme_name): Loads the content of a theme file by name.
    • write_theme(theme_name, content): Saves the provided content to a theme file.
    pub fn read_theme(allocator: std.mem.Allocator, theme_name: []const u8) ?[]const u8

pub fn write_theme(theme_name: []const u8, content: []const u8) !void

  11. Shorten a path for display

    master

    Use shorten_path to truncate long file paths for UI display, replacing the beginning of the path with an ellipsis (…).

    Parameters:

    • buf: The buffer to write the shortened path into.
    • path: The original full path.
    • removed_prefix: An out-parameter that receives the number of characters removed from the start of the path.
    • max_len: The maximum desired length of the resulting string (including the ellipsis).

  12. Read and write configuration files

    master

    Flow Control uses a structured configuration system that supports both JSON and a custom text format. Configuration files are typed based on the Zig struct used to represent them.

    Key Features:

    • Format Support: Supports .json files and a text-based format where each line is key value (where value is a JSON-encoded string).
    • Includes: Configuration structs can include an include_files field (a slice of strings) to merge settings from other files.
    • Automatic Documentation: When writing configuration files via write_config, Flow adds comments explaining the purpose, default values, and expected types for each field. Fields that match their default values are automatically commented out to keep the file clean.
    • Thread Safety: Configuration operations are protected by an internal mutex.

    Usage Pattern: To read a configuration, provide the target type and an allocator. To write, provide the data instance and an allocator.

    pub fn read_config(T: type, allocator: std.mem.Allocator) struct { T, [][]const u8 }

pub fn write_config(data: anytype, allocator: std.mem.Allocator) (ConfigDirError || ConfigWriteError)!void