How {{date}} and {{clipboard}} Variables Are Expanded in Vorssaint-Utils Snippets

Vorssaint-utils expands snippet variables through a three-stage pipeline in TextSnippetSupport.swift that detects clipboard dependencies, formats dates using DateFormatter, and performs final variable substitution before inserting text into the active application.

Vorssaint-utils implements snippet variable expansion in the pure-logic component TextSnippetSupport. When you trigger a snippet containing tokens like {{date}} or {{clipboard}}, the system processes the replacement text through a specific expansion pipeline that avoids unnecessary pasteboard access and supports custom date formatting patterns.

The Expansion Pipeline

The core expansion logic resides in TextSnippetSupport.expand(replacement, date: Date(), clipboard: ...) as implemented in the vorssaint/vorssaint-utils repository. This function transforms raw snippet templates into final text through three distinct stages.

Stage 1: Clipboard Detection

Before processing any dates, the code checks if the replacement string actually contains a {{clipboard}} token to avoid unnecessary system pasteboard access. The needsClipboard property (lines 12-14 in TextSnippetSupport.swift) scans the template and determines whether to read the clipboard value.

Stage 2: Date and Time Formatting

If the replacement contains no {{…}} tokens, the function returns the original text unchanged (lines 28-29). When date variables are present, the system creates a DateFormatter for the current locale and performs static replacements:

• {{date}} → medium-style date format
• {{time}} → short-style time format
• {{datetime}} → combined date and time string

For custom patterns like {{date:yyyy-MM-dd}} or {{date-tz(America/New_York):HH:mm}}, the expandingFormattedDates method (lines 79-99) extracts each tag, configures a fresh DateFormatter with the supplied pattern and optional timezone, then substitutes the formatted value.

Stage 3: Clipboard Insertion

After date handling completes, the function performs the final replacement of {{clipboard}} with the current pasteboard contents (lines 44-46). This staged approach ensures that date formatting occurs before clipboard content is inserted into the final string.

Implementation Details

According to the vorssaint-utils source code, the expansion workflow spans multiple Swift files:

• TextSnippetSupport.swift – Contains the core expand method and expandingFormattedDates helper that implement all variable substitution logic.
• TextSnippetService.swift – Observes keyboard events and invokes TextSnippetSupport.expand at lines 53-57 when a snippet match is detected.
• TextSnippet.swift – Defines the data model describing snippet triggers and replacement strings.

When TextSnippetService detects a matching trigger, it calls the expansion method and posts the result either via a transient paste or typed keystrokes (lines 54-61).

Code Examples

The following Swift examples demonstrate how TextSnippetSupport.expand processes different variable types:

// Simple date/time expansion
let raw = "Today is {{date}} at {{time}}."
let expanded = TextSnippetSupport.expand(
    raw,
    date: Date(),
    clipboard: nil
)
// Result: "Today is Sep 10, 2026 at 10:15 AM"

// Formatted date with timezone support
let raw = "Report: {{date-tz(America/New_York):yyyy-MM-dd}}"
let expanded = TextSnippetSupport.expand(
    raw,
    date: Date(),
    clipboard: nil
)
// Result: "Report: 2026-09-10"

// Clipboard variable insertion
let raw = "Copy this: {{clipboard}}"
let expanded = TextSnippetSupport.expand(
    raw,
    date: Date(),
    clipboard: "Hello World"
)
// Result: "Copy this: Hello World"

Summary

• Three-stage pipeline: Vorssaint-utils processes variables through detection, date formatting, and clipboard insertion to optimize performance.
• Date formatting: Supports standard {{date}}, {{time}}, and {{datetime}} tokens alongside custom patterns with timezone support via expandingFormattedDates.
• Clipboard optimization: The system only accesses the pasteboard when {{clipboard}} is present, determined by the needsClipboard check.
• Core files: All expansion logic lives in TextSnippetSupport.swift and is invoked by TextSnippetService.swift when snippet triggers are detected via keyboard events.

Frequently Asked Questions

What variables does vorssaint-utils support in snippets?

Vorssaint-utils supports {{date}} for medium-formatted dates, {{time}} for short-formatted times, {{datetime}} for combined date/time strings, and {{clipboard}} for pasteboard contents. It also supports custom date formats using {{date:format-string}} syntax and timezone-specific dates using {{date-tz(TimezoneName):format}} patterns processed by the expandingFormattedDates method.

How does vorssaint-utils handle custom date formats?

Custom date formats are processed by the expandingFormattedDates method in TextSnippetSupport.swift (lines 79-99). This function scans for patterns like {{date:yyyy-MM-dd}}, extracts the format string, creates a new DateFormatter configured with that pattern, and substitutes the result. Timezone variants like {{date-tz(America/New_York):HH:mm}} configure the formatter with the specified timezone before generating the formatted string.

Why does clipboard expansion happen after date expansion?

The expand method in TextSnippetSupport.swift processes {{clipboard}} replacement at lines 44-46, which occurs after the date formatting logic at lines 40-44. This staged approach ensures that any date variables are resolved before the final string assembly, and it allows the system to skip clipboard access entirely if the token isn't present, improving performance and privacy.

Where is the snippet expansion logic located in the source code?

The primary expansion logic resides in TextSnippetSupport.swift within the expand(replacement:date:clipboard:) method. This file is called by TextSnippetService.swift (lines 53-57) when keyboard events trigger snippet matches. The TextSnippet.swift file defines the underlying data model for snippet storage, while TransientPaste.swift handles the actual text insertion mechanism for multi-line replacements.

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