# How Text Snippets Support Clipboard Variables in Vorssaint Utils

> Discover how vorssaint-utils text snippets leverage clipboard variables using the TextSnippetSupport service. Learn how {{clipboard}} placeholders are detected and expanded for dynamic text generation.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: how-to-guide
- Published: 2026-09-09

---

**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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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.

```swift
// 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.

```swift
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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

```swift
// 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`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Snippets/TextSnippetSupport.swift) for logic, [`Sources/Vorssaint/UI/Settings/TextSnippetsSettings.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/UI/Settings/TextSnippetsSettings.swift) for editing, and [`Sources/Vorssaint/UI/SnippetLibraryView.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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.