Skip to content

text_navigation

This directory contains a powerful pattern-based text navigation and editing module. Instead of relying solely on repetitive cursor movements, this plugin allows you to jump to, select, delete, copy, or cut text relative to specific patterns (such as punctuation, camelCase words, bracketed text, or specific phrases) on the current line or adjacent lines.

Core Architecture

The text navigation system works by capturing a snapshot of the surrounding text using standard editor selections, running regular expressions on that text to find the target pattern, and then calculating and executing the precise sequence of keyboard commands to position the cursor or select the targeted text block.

The implementation is split across the following files:

  • text_navigation.talon: Defines the main voice grammars and provides several fast-access commands for common navigation patterns.
  • text_navigation.py: Implements the text extraction logic, regular expression target matching, and cursor coordinate calculation.
  • navigation_action.talon-list: Enumerates the supported structural editing actions (move, extend, select, clear, cut, copy).
  • before_or_after.talon-list: Provides the positioning modifiers (before or after) that dictate where actions should occur relative to a matched pattern.

Grammar and Voice Command Interface

The primary interface is declared in text_navigation.talon. The main grammar is highly flexible:

navigate [{user.arrow_key}] [{user.navigation_action}] [{user.navigation_target_name}] [{user.before_or_after}] [<user.ordinals>] <user.navigation_target>:

This structure accepts:

  1. Direction (arrow_key): Left, right, up, or down (defaults to right).
  2. Action (navigation_action): What to do when the target is found, such as moving the cursor, extending a selection, or cutting the text. Defined in navigation_action.talon-list.
  3. Scope/Structural Unit (navigation_target_name): The type of block to manipulate (such as a standard word, a small camelCase word, a big whitespace-delimited block, or bracket contents like parens or braces).
  4. Position Modifier (before_or_after): Dictates whether actions apply prior to or following the target. Defined in before_or_after.talon-list.
  5. Occurrence (ordinals): Which instance to target (e.g., "second", "third"). Defaults to the first.
  6. The Pattern Target (navigation_target): The actual character, string, or named pattern to search for.

The file also includes quick-access commands for fast word-level navigation: * word neck / word pre (select next/previous word) * small word neck / small word pre (select next/previous sub-word in camelCase) * big word neck / big word pre (select next/previous whitespace-delimited chunk)

Execution and Text Scanning

Because Talon does not always have access to a direct buffer API in every text editor, text_navigation.py implements "virtual selection parsing" to read text on the screen:

  1. Text Extraction: Based on the requested direction (LEFT, RIGHT, UP, or DOWN), the Python script issues selection actions (e.g., actions.edit.extend_line_start() or extending upward a certain number of lines) and calls actions.edit.selected_text() to pull the surrounding text into memory.
  2. Configurable Boundary: When searching UP or DOWN, the plugin looks up or down a specified number of lines. This maximum limit is governed by the setting text_navigation_max_line_search, which defaults to 10 lines.
  3. Regular Expression Matching:
    • Targets are mapped to regular expressions in the navigation_target_names dictionary. This defines patterns for matching structures like parens (\((.*?)\)), constants ([A-Z_][A-Z_]+), and camelCase components ([A-Z]?[a-z0-9]+).
    • Depending on the direction of search, the engine executes match_forward or match_backwards to locate the target index relative to the cursor's current location.
  4. Cursor Orchestration: Once the target coordinates within the text block are resolved, the script resets the original cursor position and sends discrete keystrokes (go_left, go_right, extend_left, extend_right) to move or select precisely to the matched region, executing the final action (such as copy, cut, or delete) if required.