fortrangoingonforty/facsimile / 7e7fe23

+# CLAUDE.md

+

+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

+

+## Project Overview

+

+Facsimile (`fac`) is a terminal text editor written in modern Fortran with VSCode-style keybindings. It uses a gap buffer for text storage and pure ANSI escape sequences for terminal rendering.

+

+## Build Commands

+

+```bash

+# Standard build (recommended)

+make

+

+# Clean and rebuild

+make clean && make

+

+# Development build with comprehensive warnings

+make dev

+

+# Debug build with runtime checks

+make debug

+

+# Show compiler info

+make info

+```

+

+The Makefile auto-detects the platform:

+- **macOS arm64**: Uses gfortran-15 or flang-new from Homebrew

+- **macOS Intel/Linux**: Uses standard gfortran

+

+## Version Management

+

+```bash

+# Check current version

+make version

+

+# Bump versions

+make bump-patch    # 0.9.1 -> 0.9.2

+make bump-minor    # 0.9.1 -> 0.10.0

+make bump-major    # 0.9.1 -> 1.0.0

+

+# Full release build with checklist

+make release

+```

+

+The `VERSION` file is the single source of truth. The Makefile auto-generates `src/version_module.f90`.

+

+## Architecture

+

+### Core Data Flow

+

+```

+Input → input_handler_module → command_handler_module → buffer operations → renderer_module → Terminal

+```

+

+### Key Modules

+

+- **`src/buffer/text_buffer_module.f90`**: Gap buffer implementation for text storage. All operations maintain gap position for efficient insertions.

+

+- **`src/editor_state_module.f90`**: Central state management. Contains `editor_state_t` with tabs, panes, cursors, LSP state, and UI panels. This is the "god object" that gets passed around.

+

+- **`src/terminal/input_handler_module.f90`**: Raw keyboard input processing. Handles escape sequences, mouse events, and key combinations.

+

+- **`src/terminal/renderer_module.f90`**: Screen rendering with ANSI escape sequences. Handles syntax highlighting, status bar, and split panes.

+

+- **`src/commands/command_handler_module.f90`**: Main command dispatch. Maps key inputs to editor actions (~7000 lines).

+

+- **`src/terminal/termios_wrapper.c`**: C wrapper for terminal raw mode via termios.

+

+### Module Dependency Order

+

+The Makefile's `SOURCES` list defines the required compilation order. Fortran modules must be compiled before modules that `use` them. The `.NOTPARALLEL` directive enforces sequential builds.

+

+### UTF-8 Handling

+

+All cursor positions use CHARACTER indices, not byte indices. The `utf8_module` provides conversion functions:

+- `utf8_char_count()` - count characters in string

+- `buffer_byte_to_char_col()` - convert byte position to character column

+- `buffer_char_to_byte_col()` - convert character column to byte position

+

+### Pane/Tab Architecture

+

+```

+editor_state_t

+  └── tabs[]           (multiple open files)

+       └── panes[]     (split views of same file)

+            ├── buffer (text content)

+            ├── cursors[] (multiple cursor support)

+            └── viewport (scroll position)

+```

+

+### LSP Integration

+

+Located in `src/lsp/`. Communicates with language servers via JSON-RPC over stdio:

+- `lsp_server_manager_module.f90` - Server lifecycle management

+- `json_module.f90` - JSON parsing/generation

+- `lsp_client_module.f90` - Request/response handling

+

+## Fortran-Specific Constraints

+

+### Line Length Limit

+Fortran has a 132-character line limit. Unicode characters (like box-drawing `═`) count as multiple bytes. Long lines must be split using `&` continuation:

+

+```fortran

+! Bad - will fail compilation

+line = '═══════════════════════════════════════════════════════════════════'

+

+! Good - split across lines

+line = '═══════════════════════' // &

+       '═══════════════════════' // &

+       '═══════════════════════'

+```

+

+### Module Files

+Compilation generates `.mod` files in the root directory. These are binary module interfaces, not source files.

+

+## Distribution

+

+The project is distributed via three channels:

+- **Homebrew**: `homebrew-facsimile` repo with `facsimile.rb` formula

+- **AUR**: Arch User Repository PKGBUILD

+- **RPM**: Spec file at `~/rpmbuild/SPECS/facsimile.spec`

+

+When releasing, update all three with the new version and SHA256 hash from the GitHub release tarball.

+

+## Testing

+

+```bash

+# LSP module tests

+make test-lsp

+

+# Test LSP with editor

+make test-lsp-editor

+

+# Manual key testing

+./keytest      # Basic key codes

+./keytest_fac  # With fac's termios settings

+```

+

+## Running

+

+```bash

+./fac [filename]        # Open file

+./fac --version         # Show version

+./fac --help            # Show help

+```

+

+Key bindings follow VSCode conventions: Ctrl-S save, Ctrl-Q quit, Ctrl-B file tree, Ctrl-F search, Ctrl-Z undo.

+                                      g_lsp_modified_buffer, g_lsp_ui_changed, g_cursor_only_move

+            ! Skip buffer sync for cursor-only moves (buffer content unchanged)

+            if (.not. g_cursor_only_move) then

+                if (editor%active_tab_index > 0 .and. editor%active_tab_index <= size(editor%tabs)) then

+                    if (allocated(editor%tabs(editor%active_tab_index)%panes) .and. &

+                        size(editor%tabs(editor%active_tab_index)%panes) > 0) then

+                        ! Get active pane index

+                        status = editor%tabs(editor%active_tab_index)%active_pane_index

+                        if (status > 0 .and. status <= size(editor%tabs(editor%active_tab_index)%panes)) then

+                            ! Copy main buffer back to active pane's buffer

+                            call copy_buffer(editor%tabs(editor%active_tab_index)%panes(status)%buffer, buffer)

+

+                            ! Sync to all instances of this file

+                            if (allocated(editor%tabs(editor%active_tab_index)%panes(status)%filename)) then

+                                call sync_buffer_to_all_instances(editor, &

+                                    editor%tabs(editor%active_tab_index)%panes(status)%filename, buffer)

+                            end if

+                        ! Also update tab buffer for backwards compatibility

+                        call copy_buffer(editor%tabs(editor%active_tab_index)%buffer, buffer)

+                        ! Sync modified flag from buffer to tab

+                        editor%tabs(editor%active_tab_index)%modified = buffer%modified

+                    end if

+                ! Use fast path for cursor-only movements

+                if (g_cursor_only_move) then

+                    call render_cursor_only(buffer, editor, allocated(search_pattern), match_case_sensitive)

+                    g_cursor_only_move = .false.

+                else if (editor%fuss_mode_active) then

+    public :: g_cursor_only_move     ! Flag for cursor-only moves (skip full re-render)

+    ! Flag for cursor-only movements (can skip full re-render)

+    logical :: g_cursor_only_move = .false.

+            g_cursor_only_move = .true.

+            g_cursor_only_move = .true.

+            g_cursor_only_move = .true.

+            g_cursor_only_move = .true.

+    use terminal_io_module, only: terminal_read_char, terminal_read_char_escape

+        ! Read single character using raw mode function (50ms timeout when idle)

+        ! Try to read next character (with fast 5ms timeout for escape sequences)

+        char_code = terminal_read_char_escape()

+            char_code = terminal_read_char_escape()

+                char_code = terminal_read_char_escape()

+                        char_code = terminal_read_char_escape()

+                            char_code = terminal_read_char_escape()

+                char_code = terminal_read_char_escape()

+                char_code = terminal_read_char_escape()

+                char_code = terminal_read_char_escape()

+                        char_code = terminal_read_char_escape()

+                        char_code = terminal_read_char_escape()

+                char_code = terminal_read_char_escape()

+                        char_code = terminal_read_char_escape()

+                        char_code = terminal_read_char_escape()

+            char_code = terminal_read_char_escape()

+            char_code = terminal_read_char_escape()

+                    char_code = terminal_read_char_escape()

+                            char_code = terminal_read_char_escape()

+            char_code = terminal_read_char_escape()

+        char_code = terminal_read_char_escape()

+            char_code = terminal_read_char_escape()

+            char_code = terminal_read_char_escape()

+            char_code = terminal_read_char_escape()

+        char_code = terminal_read_char_escape()

+        char_code = terminal_read_char_escape()

+            char_code = terminal_read_char_escape()

+    public :: read_char_escape, input_available_count

+        function c_input_available_count() bind(C, name="input_available_count")

+            import :: c_int

+            integer(c_int) :: c_input_available_count

+        end function c_input_available_count

+

+

+        function c_read_char_escape() bind(C, name="read_char_escape")

+            import :: c_int

+            integer(c_int) :: c_read_char_escape

+        end function c_read_char_escape

+    function input_available_count() result(count)

+        integer :: count

+        integer(c_int) :: result

+

+        result = c_input_available_count()

+        count = result

+    end function input_available_count

+

+    ! Fast read for escape sequences (5ms timeout instead of 50ms)

+    function read_char_escape() result(ch)

+        integer :: ch

+        integer(c_int) :: result

+

+        result = c_read_char_escape()

+        ch = result

+    end function read_char_escape

+

+    public :: render_cursor_only  ! Fast path for cursor-only updates

+    ! Fast path for cursor-only updates - just update cursor and status bar

+    ! Use this when only cursor position changed, not buffer content

+    subroutine render_cursor_only(buffer, editor, match_mode_active, match_case_sens)

+        type(buffer_t), intent(in) :: buffer

+        type(editor_state_t), intent(inout) :: editor

+        logical, intent(in), optional :: match_mode_active

+        logical, intent(in), optional :: match_case_sens

+

+        ! Just render the status bar and position cursor

+        call render_status_bar(editor, buffer, match_mode_active, match_case_sens)

+

+        ! Handle panes vs single buffer

+        if (size(editor%tabs) > 0 .and. editor%active_tab_index > 0 .and. &

+            editor%active_tab_index <= size(editor%tabs)) then

+            if (allocated(editor%tabs(editor%active_tab_index)%panes)) then

+                if (editor%fuss_mode_active) then

+                    call render_cursor_for_panes_with_tree(editor, 31, editor%screen_cols - 30)

+                else

+                    call render_cursor_for_panes(editor)

+                end if

+                return

+            end if

+        end if

+

+        ! Single buffer mode

+        if (editor%fuss_mode_active) then

+            call render_cursor_in_pane(editor, 31, editor%screen_cols - 30)

+        else

+            call render_cursor(editor, buffer)

+        end if

+    end subroutine render_cursor_only

+

+                               raw_read_char_timeout => read_char_timeout, &

+                               raw_read_char_escape => read_char_escape, &

+                               raw_input_available_count => input_available_count

+    public :: terminal_read_char_escape, terminal_input_available_count

+    ! Fast read for escape sequences (5ms timeout)

+    function terminal_read_char_escape() result(ch)

+        integer :: ch

+        ch = raw_read_char_escape()

+    end function terminal_read_char_escape

+

+    ! Get count of available input bytes

+    function terminal_input_available_count() result(count)

+        integer :: count

+        count = raw_input_available_count()

+    end function terminal_input_available_count

+

+#include <sys/select.h>

+#include <string.h>

+// Input buffer for batching reads

+#define INPUT_BUFFER_SIZE 256

+static unsigned char input_buffer[INPUT_BUFFER_SIZE];

+static int buffer_start = 0;

+static int buffer_end = 0;

+

+    // Control characters: non-blocking reads

+    // We'll use select() for timeout management instead of VTIME

+    raw.c_cc[VMIN] = 0;   // Don't block

+    raw.c_cc[VTIME] = 0;  // No timeout - we use select() instead

+    buffer_start = buffer_end = 0;

+    buffer_start = buffer_end = 0;

+    // First check our buffer

+    if (buffer_start < buffer_end) {

+        return 1;

+    }

+

+    // Then check stdin

+// Get count of available input bytes

+int input_available_count(void) {

+    int buffered = buffer_end - buffer_start;

+    int pending = 0;

+    if (ioctl(STDIN_FILENO, FIONREAD, &pending) == -1) {

+        pending = 0;

+    }

+    return buffered + pending;

+}

+

+// Fill the input buffer with all available data

+static void fill_input_buffer(void) {

+    // Shift remaining data to start of buffer

+    if (buffer_start > 0 && buffer_start < buffer_end) {

+        memmove(input_buffer, input_buffer + buffer_start, buffer_end - buffer_start);

+        buffer_end -= buffer_start;

+        buffer_start = 0;

+    } else if (buffer_start >= buffer_end) {

+        buffer_start = buffer_end = 0;

+    }

+

+    // Read all available data into buffer

+    int space = INPUT_BUFFER_SIZE - buffer_end;

+    if (space > 0) {

+        ssize_t nread = read(STDIN_FILENO, input_buffer + buffer_end, space);

+        if (nread > 0) {

+            buffer_end += nread;

+        }

+    }

+}

+

+// Read a single character with smart timeout

+// - If data is buffered or available, return immediately

+// - Otherwise wait up to timeout_ms for input

+// - Use short timeout (5ms) for escape sequence continuation

+// - Use longer timeout (50ms) for initial wait when idle

+    // Return from buffer if available

+    if (buffer_start < buffer_end) {

+        return input_buffer[buffer_start++];

+    }

+

+    // Try to fill buffer

+    fill_input_buffer();

+    if (buffer_start < buffer_end) {

+        return input_buffer[buffer_start++];

+    }

+

+    // No data available - wait with select()

+    // Use 50ms timeout for responsive feel without busy-waiting

+    fd_set readfds;

+    struct timeval tv;

+

+    FD_ZERO(&readfds);

+    FD_SET(STDIN_FILENO, &readfds);

+    tv.tv_sec = 0;

+    tv.tv_usec = 50000;  // 50ms - good balance of responsiveness and CPU usage

+

+    int ret = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &tv);

+    if (ret > 0) {

+        fill_input_buffer();

+        if (buffer_start < buffer_end) {

+            return input_buffer[buffer_start++];

+        }

+    }

+

+    return -1;  // No input

+}

+

+// Read a character with very short timeout (for escape sequences)

+// This is used when we've already seen ESC and are looking for the rest

+int read_char_escape(void) {

+    // Return from buffer if available

+    if (buffer_start < buffer_end) {

+        return input_buffer[buffer_start++];

+    }

+

+    // Try immediate read first

+    fill_input_buffer();

+    if (buffer_start < buffer_end) {

+        return input_buffer[buffer_start++];

+

+    // Short wait for escape sequence continuation (5ms)

+    fd_set readfds;

+    struct timeval tv;

+

+    FD_ZERO(&readfds);

+    FD_SET(STDIN_FILENO, &readfds);

+    tv.tv_sec = 0;

+    tv.tv_usec = 5000;  // 5ms - fast escape sequence detection

+

+    int ret = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &tv);

+    if (ret > 0) {

+        fill_input_buffer();

+        if (buffer_start < buffer_end) {

+            return input_buffer[buffer_start++];

+        }

+    }

+

+    return -1;