Skip to content

find_and_replace

The find_and_replace tag provides a standardized interface for search-and-replace operations across different editors and IDEs (such as VS Code, JetBrains IDEs, or Sublime Text). By defining a common set of actions and voice commands, it allows developers to write application-specific overrides while maintaining a unified voice control vocabulary.

Overview

The directory contains two main files:

  • find_and_replace.py – Declares the user.find_and_replace tag and outlines the abstract actions that target applications must implement.
  • find_and_replace.talon – Maps spoken voice commands to the abstract actions when the user.find_and_replace tag is active.

These files work together to abstract away application-specific hotkeys (such as Ctrl+Shift+F vs. Cmd+Shift+F) into standard voice triggers.

Architecture and Interface Definition

find_and_replace.py

This Python script registers the tag user.find_and_replace with Talon's module system. It defines a set of action signatures inside class Actions without implementing their bodies. These act as an "interface" or abstract base:

  • Global Project Search: find_everywhere(text) and replace_everywhere(text) trigger project-wide search and replace dialogs.
  • Search Toggles: find_toggle_match_by_case(), find_toggle_match_by_word(), and find_toggle_match_by_regex() allow toggling of search parameters.
  • In-File Replacements: replace(text), replace_confirm(), and replace_confirm_all() manage fine-grained search-and-replace operations in the active editor.
  • Occurrence Selection: select_previous_occurrence(text) and select_next_occurrence(text) locate and select specific text patterns without popping open distracting search dialogs.

Target application contexts (defined elsewhere in the repository) implement these actions to bind them to the correct keyboard shortcuts or API calls of that specific editor.

Voice Commands and Capabilities

find_and_replace.talon

When an editor context activates the user.find_and_replace tag, this file becomes active. It inherits the basic user.find tag capabilities and exposes several sets of voice commands:

Project-Wide Searching & Toggles

These commands manage global searches and configure match parameters:

  • hunt all: Triggers a project-wide search.
  • hunt all (pace | paste): Triggers a project-wide search and pastes the system clipboard contents.
  • hunt case / hunt word / hunt expression: Toggles case-sensitivity, whole-word matching, or regular expression matching.

Standard Replacement

These commands manage the standard find-and-replace lifecycle:

  • replace this [<user.text>]: Opens the replacement utility for the active editor.
  • replace all / replace <user.text> all: Initiates project-wide replacements.
  • replace confirm that / replace confirm all: Confirms individual or global replacements.

Quick Target Actions (JetBrains-style Selection)

One of the most powerful features of this tag is the suite of quick target commands. These commands allow you to manipulate, comment, navigate to, or replace the next or previous occurrence of specific text or clipboard contents dynamically.

Each of these commands utilizes the select_next_occurrence or select_previous_occurrence actions, introduces a tiny sleep buffer for reliability, and then executes an editor operation:

  • Deletions: clear last <user.text> / clear next clip selects the match and deletes it.
  • Comments: comment last <user.text> / comment next clip selects the match and toggles the comment status using code.toggle_comment().
  • Navigation: go last <user.text> / go next clip selects the occurrence and moves the cursor to its right.
  • Pasting/Replacing: replace last <user.text> replaces the selection with the clipboard content, whereas paste last <user.text> navigates to the end of the selection first and then pastes.