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

> Learn how vorssaint-utils expands snippet variables like {{date}} and {{clipboard}} through a three-stage pipeline. Understand date formatting and final substitution.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: internals
- Published: 2026-09-10

---

**Vorssaint-utils expands snippet variables through a three-stage pipeline in [`TextSnippetSupport.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/TextSnippetSupport.swift)** – Contains the core `expand` method and `expandingFormattedDates` helper that implement all variable substitution logic.
- **[`TextSnippetService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/TextSnippetService.swift)** – Observes keyboard events and invokes `TextSnippetSupport.expand` at lines 53-57 when a snippet match is detected.
- **[`TextSnippet.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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:

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

```

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

```

```swift
// 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`](https://github.com/vorssaint/vorssaint-utils/blob/main/TextSnippetSupport.swift) and is invoked by [`TextSnippetService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/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`](https://github.com/vorssaint/vorssaint-utils/blob/main/TextSnippetSupport.swift) within the `expand(replacement:date:clipboard:)` method. This file is called by [`TextSnippetService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/TextSnippetService.swift) (lines 53-57) when keyboard events trigger snippet matches. The [`TextSnippet.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/TextSnippet.swift) file defines the underlying data model for snippet storage, while [`TransientPaste.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/TransientPaste.swift) handles the actual text insertion mechanism for multi-line replacements.