DOCSEARCHbyAlgolia
Submit Docs

Cursorless Documentation

website·Indexed 33 days ago

https://www.cursorless.org/docs

Documentation for Cursorless, featuring a comprehensive guide to spoken forms, syntax, and IDs for scopes and modifiers. It covers a wide range of structural targets including XML tags, function calls, LaTeX sections, and programming language elements across C++, Java, JavaScript, Python, Rust, and Swift.

Tokens
97.5K
Snippets
331
Records
905
Agent score
68%

What's inside Cursorless

  1. Overview of the Talon Community draft editor plugin

    The draft editor is a Talon Community plugin designed for revising text in a full-featured text editor before inserting it back into the original application. This is particularly useful for composing long messages in applications with limited text field editing or poor voice-control support.

    Workflow:

    1. The plugin opens a new tab in a pre-running editor application.
    2. It optionally copies selected text from the original application into the editor.
    3. It remembers the original window context.
    4. Upon submission, the plugin closes the temporary tab, returns focus to the original window, and pastes the revised text (replacing any existing selection if present).

  2. Overview of Cursorless modal keyboard mode

    Cursorless features an experimental modal keyboard interface that allows users to switch into a dedicated 'Cursorless mode'. In this mode, you can control Cursorless by moving a highlight around the editor and performing actions on the highlighted target without needing modifier keys. Commands are built incrementally: first target a mark, then apply scopes or modifiers, and finally perform an action (e.g., Target -> Scope -> Action).

  3. Understand Rust scope definitions for Cursorless

    Cursorless uses specific scope definitions for the Rust language to handle text manipulation, insertion, and iteration. These scopes define how the editor identifies boundaries for elements like anonymous functions, argument lists, and individual parameters. Key behaviors include whether an insertion delimiter should be empty or include a newline based on whether the target code is single-line or multi-line.

  4. Manage hat token map snapshots for command phrase consistency

    To support long chained command phrases, Cursorless uses a snapshot of the hat token map. This ensures that commands referring to a decorated token continue to refer to the same logical token throughout the entire phrase, regardless of document changes. While the physical ranges of tokens are updated to stay current as the document changes, the logical token retains the same key in the hat token map for the duration of the phrase.

    The synchronization process works as follows:

    1. The voice engine 'touches' a file in the signals subdirectory of the command server communication directory after a phrase is parsed but before execution starts.
    2. Cursorless checks the version of this signal file via the command server signal API before reading or updating the hat token map.
    3. If the signal version has changed since the last snapshot, Cursorless takes a new snapshot and uses it until the next signal is emitted.

    Because signal transmission is asynchronous, Cursorless must verify the signal version immediately before any map read or update operation.

  5. Understand Ruby scope definitions for Cursorless

    Cursorless uses specific scope definitions for Ruby to handle text selection and manipulation. These scopes include:

    • Anonymous Functions: Lambdas and arrow functions.
    • Argument Lists: Both actual arguments (in calls) and formal parameters (in declarations), spanning empty, single-line, and multi-line formats.
    • Arguments/Parameters: Individual elements within a list, with specific handling for multi-line insertions (requiring newlines).
    • Branches: Logic structures including if/elif/else, switch cases, ternary expressions, and try/catch/finally blocks.

  6. Understand Cursorless monorepo script architecture

    The Cursorless monorepo uses a standardized set of script names to ensure consistency across different package types. The architecture distinguishes between Internal packages (consumed only within the repo) and Top-level application packages (distributable artifacts).

  7. Understand how Cursorless assigns hats to tokens

    Cursorless assigns hats to tokens in visible editors whenever the cursor moves, the document is edited, or the view is scrolled. The assignment follows these core principles:

    1. Ranking: Tokens are processed in order of 'rank' based on proximity to the cursor. Higher-ranked tokens (closer to the cursor) select their hats first.
    2. Hat Quality (Penalty): Hats are weighted by the number of syllables required to speak them. Lower penalties are preferred:
      • Gray dot: 0 penalty (e.g., "air")
      • Colored dot: 1 penalty (e.g., "blue air")
      • Gray shape: 1 penalty (e.g., "fox air")
      • Colored shape: 2 penalty (e.g., "blue fox air")
    3. Selection Process: For each token, Cursorless identifies available hats based on enabled settings, token characters, and hats already claimed by higher-ranked tokens. It then filters these candidates based on the cursorless.experimental.hatStability setting before finalizing the selection to either keep an existing hat or claim a new one.

  8. Get started with Cursorless tutorials

    New users can learn basic concepts and commands through the following resources:

    • Cursorless tutorial videos: A YouTube series covering fundamental concepts.
    • Interactive Tutorial: Available in-browser or directly inside VS Code.

  9. Use the statement Cursorless ID to target code blocks

    The statement Cursorless ID (default spoken form: state) is used to target various types of programming statements across multiple languages. Depending on the language and the specific syntax of the code, the statement ID can resolve to different types of blocks, including:

  10. Understand Cursorless Unicode and normalization behavior

    By default, Cursorless provides first-class support for Unicode. When constructing hats, it ignores capitalization and accents/diacritics. For example, the tokens 'africa', 'áfrica', 'Africa', and 'África' are all treated as the same for hat selection (e.g., using "take air").

    For non-letter Unicode symbols that are not speakable by default (such as emojis or Chinese characters), Cursorless uses a special character called "special". To select a symbol with a blue hat, you would say "take blue special". The spoken form "special" can be customized in user settings.

  11. Understand Cursorless test categories and contexts

    Cursorless employs three main categories of tests executed across four distinct environments:

    Test Categories:

    • Recorded tests: End-to-end/subcutaneous tests that verify the IDE state after a command. Generated via the test case recorder.
    • Scope tests: Verify scope definitions across supported languages using a test document and a snapshot of expected scopes.
    • Other tests: Traditional unit tests and handwritten subcutaneous tests.

    Execution Contexts:

    • Unit tests: Neutral context for testing small logic units (functions).
    • VS Code: Tests requiring a VS Code environment to verify IDE integration.
    • Neovim: A subset of recorded tests and Lua unit tests to verify Neovim interaction.
    • Talon: Local tests verifying that spoken commands produce the expected command payloads.

  12. Understand CSS language scopes in Cursorless

    Cursorless uses specific scopes to identify and manipulate elements within CSS files. These scopes allow the tool to distinguish between different structural elements such as selectors, units, and function calls for targeted editing and navigation.