edit

This directory contains the core implementation of cross-platform text editing, navigation, and structured manipulation commands. It establishes a unified, platform-agnostic grammar for operations like selecting, deleting, copying, and wrapping text, while delegating the physical keyboard shortcuts to operating-system-specific layers.

Architecture Overview

The editing subsystem decouples voice commands from the underlying keyboard layouts. It achieves this using a modular, layered architecture:

                  ┌─────────────────────────────────┐
                  │           edit.talon            │  <-- Voice Commands
                  └────────────────┬────────────────┘
                                   │
                                   ▼
                  ┌─────────────────────────────────┐
                  │         edit_command.py         │  <-- Command & Modifier Glue
                  └────────────────┬────────────────┘
                                   │
                  ┌────────────────┴────────────────┐
                  │             edit.py             │  <-- High-Level Core Actions
                  └────────────────┬────────────────┘
                                   │
         ┌─────────────────────────┼─────────────────────────┐
         ▼                         ▼                         ▼
┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│   edit_win.py   │       │   edit_mac.py   │       │  edit_linux.py  │  <-- OS Drivers
└─────────────────┘       └─────────────────┘       └─────────────────┘

1. Voice Bindings: edit.talon defines user-facing commands such as "copy that", "select line", or "clear way left".
2. Command Translation: edit_command.py parses complex edit actions and determines whether they require sequence-based execution or can use a native compound shortcut.
3. High-Level Abstractions: edit.py and helper files define high-level behaviors like smart word selection, clipboard-preserving pastes, and paragraph boundaries.
4. OS Drivers: OS-specific scripts map generic operations (like edit.copy()) to exact key combinations (ctrl-c or cmd-c).

---

Operating System Adapters

Rather than baking platform-specific key combinations into core actions, Talon uses Context matching to register OS-appropriate keyboard shortcuts. This isolates the physical key-sequence discrepancies between platforms:

• edit_linux.py handles standard Linux shortcuts (e.g., ctrl-c for copy, ctrl-left for word movement).
• edit_mac.py overrides shortcuts using Command (cmd) and Option (alt) keys as required by macOS.
• edit_win.py maps Windows shortcuts (such as shift-ctrl-home to select to the start of a document).

---

High-Level Core Actions

edit.py provides generalized commands that aren't natively supported by simple system-wide keys.

Key features include: * Selected Text Retrieval: Uses clipboard capture via clip.capture() to securely pull active selection contents into memory. * Smart Word Selection: Employs heuristic boundary checking. It shifts and expands selection highlights to reliably select a full word while ignoring punctuation or edge-case whitespace. * Clipboard Preservation: Implements paste(text), which updates the clipboard, pastes the contents, and automatically restores the user's previous clipboard contents after a short sleep window.

---

Compound Editing & Grammar Pipeline

To avoid forcing users to dictate separate "select" and "manipulate" actions, the repository provides a grammar combining an Edit Action with an Edit Modifier. This allows commands like "clear line" or "copy way down".

• Edit Actions: edit_command_actions.py specifies the verbs (e.g., select, goBefore, goAfter, copyToClipboard, delete). These verbs are loaded via edit_command_actions.talon-list.
• Edit Modifiers: edit_command_modifiers.py captures the nouns/targets (e.g., paragraph, wordRight, lineEnd, document). These are populated by edit_command_modifiers.talon-list and repeatable variations defined in edit_command_modifiers_repeatable.talon-list.
• Execution Logic: edit_command.py acts as the engine. It combines action-modifier pairs. If a compound sequence is registered (e.g., ("delete", "line") maps to edit.delete_line()), it executes immediately. If no direct shortcut exists, it falls back to selecting the range first and then executing the action. It also introduces configurable micro-delays between keystrokes to ensure compatibility with slower IDEs.

---

Special Navigation & Selections

Paragraph Navigation

Standard OS keyboard bindings do not have concepts for a "paragraph." edit_paragraph.py implements stateful line scanning to find paragraph boundaries.

It reads lines using selection buffers, searching upwards or downwards until it hits a line containing only whitespace. This allows robust execution of paragraph actions: * paragraph_start() and paragraph_end() * select_paragraph() * delete_paragraph()

Chain Navigation

edit_navigation_steps.py allows the user to chain multiple movement vectors into a single command (e.g., "go 2 words left 3 lines down"). It parses individual NavigationStep steps and executes the moves sequentially with optional delays.

---

Delimiters & Padding

The directory provides features to insert and wrap text with matching characters (e.g., brackets, braces, parentheses).

• delimiter_pair.talon-list: Defines pairings of common programming and text symbols (such as round: ( ) or curly: { }).
• delimiter_pair.py: Exposes actions to insert delimiter pairs with the cursor centered between them, or to wrap the current active selection in those delimiters.
• insert_between.py: Implements the lower-level utility that inserts text fragments and moves the cursor backwards to leave it centered inside the boundary.