How Text Snippets Support Clipboard Variables in Vorssaint Utils

The text snippets feature in vorssaint-utils supports clipboard variables through the TextSnippetSupport service, which detects {{clipboard}} placeholders via needsClipboard() and expands them at runtime using the expand() method.

Vorssaint's text-snippets engine allows users to embed dynamic clipboard content directly into reusable text templates. By leveraging the TextSnippetSupport service class implemented in Sources/Vorssaint/Services/Snippets/TextSnippetSupport.swift, the system can detect when a snippet requires clipboard access and substitute the {{clipboard}} placeholder with live pasteboard data at expansion time.

Detecting Clipboard Dependencies with needsClipboard()

Before expanding a snippet, the system determines whether the current clipboard contents must be read. The TextSnippetSupport.needsClipboard(_:) method scans the snippet's replacement text for the {{clipboard}} token.

If the placeholder is present, the method returns true, signaling to the UI layer that it must fetch the clipboard contents before performing expansion. This optimization prevents unnecessary pasteboard access for snippets that do not utilize clipboard variables.

// Check if a snippet requires clipboard access
let needsClip = TextSnippetSupport.needsClipboard("clip: {{clipboard}}")
// Returns true, triggering the clipboard fetch operation

Expanding Placeholders Using expand(_:date:clipboard:)

The core substitution logic resides in TextSnippetSupport.expand(_:date:clipboard:). This method accepts the raw snippet text, a date parameter for timestamp variables, and the current clipboard string.

During execution, every occurrence of {{clipboard}} is replaced with the provided clipboard content. If the clipboard parameter is nil, the placeholder is removed entirely rather than left blank in the output.

let rawText = "Thanks,\n{{clipboard}}"
let clipboardContent = NSPasteboard.general.string(forType: .string) ?? ""

let expanded = TextSnippetSupport.expand(
    rawText,
    date: Date(),
    clipboard: clipboardContent
)
// Result: "Thanks,\n[actual clipboard content]"

UI Integration and Architecture

The clipboard variable system integrates across multiple layers of the vorssaint-utils codebase. In Sources/Vorssaint/UI/Settings/TextSnippetsSettings.swift, the snippet editor displays replacement text containing {{clipboard}} tokens as normal text content.

When a user triggers a snippet through SnippetLibraryView.swift or a keyboard shortcut, the UI first calls needsClipboard() to determine if pasteboard access is required. If affirmative, the system retrieves the current clipboard value once and passes it to expand(_:date:clipboard:), producing the final rendered string for insertion into the target application.

Practical Implementation Example

Below is a complete workflow demonstrating clipboard variable support in a signature snippet:

// Define a snippet with clipboard placeholder
let signatureSnippet = TextSnippet(
    trigger: ";sig",
    replacement: "Best regards,\n{{clipboard}}",
    expansion: .afterDelimiter
)

// Runtime expansion logic
if TextSnippetSupport.needsClipboard(signatureSnippet.replacement) {
    let clipContent = NSPasteboard.general.string(forType: .string) ?? ""
    
    let finalText = TextSnippetSupport.expand(
        signatureSnippet.replacement,
        date: Date(),
        clipboard: clipContent
    )
    // Insert finalText into target application
}

When the user types ;sig, the engine expands the trigger into a greeting followed by whatever content was currently on the system clipboard.

Summary

• Clipboard detection: The TextSnippetSupport.needsClipboard(_:) method identifies snippets containing {{clipboard}} placeholders to avoid unnecessary pasteboard reads.
• Runtime substitution: TextSnippetSupport.expand(_:date:clipboard:) performs the actual replacement, handling nil clipboard values by removing the placeholder entirely.
• File architecture: The feature spans Sources/Vorssaint/Services/Snippets/TextSnippetSupport.swift for logic, Sources/Vorssaint/UI/Settings/TextSnippetsSettings.swift for editing, and Sources/Vorssaint/UI/SnippetLibraryView.swift for user interaction.
• User workflow: Snippets can embed {{clipboard}} tokens that render as live clipboard content during expansion, enabling dynamic text templates that adapt to the user's current copy buffer.

Frequently Asked Questions

What happens if the clipboard is empty when expanding a snippet?

If the clipboard contains no string data or is passed as nil, TextSnippetSupport.expand(_:date:clipboard:) removes the {{clipboard}} placeholder entirely from the output. The surrounding text remains intact, but the placeholder itself disappears without leaving blank spaces or error messages.

How does the system know when to read the clipboard?

The system uses TextSnippetSupport.needsClipboard(_:) to scan the snippet's replacement string before expansion. If the scan detects the {{clipboard}} token, the UI layer fetches the pasteboard content once and passes it to the expand method. This design optimizes performance by skipping clipboard access for standard snippets that do not use variables.

Where is the clipboard expansion logic implemented?

According to the vorssaint-utils source code, the expansion logic resides in Sources/Vorssaint/Services/Snippets/TextSnippetSupport.swift. This file contains both the needsClipboard() detection method and the expand() substitution method that processes {{clipboard}} variables at runtime.

Can I use multiple clipboard placeholders in a single snippet?

Yes. The TextSnippetSupport.expand(_:date:clipboard:) method replaces every occurrence of {{clipboard}} in the replacement string with the provided clipboard content. All instances receive the same clipboard value from the single read operation performed at expansion time, ensuring consistency throughout the expanded text.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}