# How to Use vorssaint‑utils: 5 Practical Code Examples and Full Architecture Guide

> Explore practical vorssaint-utils code examples and architecture guide. Discover this Swift macOS utility collection and control its features programmatically.

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

---

**vorssaint‑utils** is a Swift macOS utility collection that exposes each feature as an observable service you can programmatically control from your own code.

The repository bundles independent tools—window snapping, text snippets, system monitoring, keep‑awake timers, and more—behind a single menu‑bar application. Every utility lives in `Sources/Vorssaint` and implements the **observable service pattern**, making them easy to script, extend, or embed in custom workflows. This guide demonstrates practical vorssaint‑utils examples drawn directly from the source code.

---

## Getting Started: Importing the Module

Add the package to your Xcode project, then import the `Vorssaint` module defined in [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift):

```swift
import Vorssaint

```

All subsequent examples assume this import is present.

---

## Example 1: Launch the App Programmatically

The `VorssaintMain.run` method provides a thin wrapper around the boot‑strap logic in [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift). You can launch the full application—or run diagnostics—without touching the command line:

```swift
VorssaintMain.run(arguments: ["--selftest"])   // Execute built‑in self‑test
VorssaintMain.run(arguments: [])               // Normal UI launch

```

The same flags available to the binary (`--selftest`, `--sensors`, `--uninstall`) are accepted here. See [`main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/main.swift) for the underlying parsing logic.

---

## Example 2: Trigger Text Snippet Expansion

The `TextSnippetService` manages low‑level event taps that listen for trigger strings and expand them into templates. You can programmatically register snippets:

```swift
let snippet = TextSnippet(
    trigger: "date",
    expansion: .immediate,
    template: "{{date}}",
    enabled: true
)
TextSnippetService.shared.set(snippet: snippet)
TextSnippetService.shared.syncWithPreferences()

```

Key implementation details from [`Sources/Vorssaint/Services/Snippets/TextSnippetService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Snippets/TextSnippetService.swift):

- Snippets persist to `UserDefaults`
- The service maintains an **event tap** for global keyboard monitoring
- Call `syncWithPreferences()` to force‑reload the active trigger set

---

## Example 3: Snap Windows Programmatically

`WindowLayoutService` exposes `move(_:to:animation:)` for calculated window positioning. Snapping the frontmost window left takes two lines:

```swift
guard let frontmost = NSApplication.shared.orderedWindows.first else { return }

WindowLayoutService.shared.move(
    window: frontmost,
    to: .leftHalf,
    animation: .smooth
)

```

The method internally delegates to `WindowEdgeSnapSupport` for frame calculations. Source: [`Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift).

---

## Example 4: Add Files to the Shelf

The **Shelf** is a quick‑drop panel for frequently accessed files. Use `ShelfService` to add links programmatically:

```swift
let fileURL = URL(fileURLWithPath: "/Users/me/Documents/report.pdf")
ShelfService.shared.addLink(title: "Report", url: fileURL)

```

[`Sources/Vorssaint/Services/Shelf/ShelfService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Shelf/ShelfService.swift) handles persistence, drag‑and‑drop UI updates, and link resolution when items are activated.

---

## Example 5: Run a Keep‑Awake Timer

Prevent macOS sleep for a fixed duration—useful for long downloads or presentations:

```swift
KeepAwakeService.shared.startTimer(minutes: 15)
// ...work continues even if lid is closed...

KeepAwakeService.shared.stop()   // Cancel early when done

```

The implementation in `Sources/Vorssaint/Services/KeepAwake` wraps `IOPMAssertionCreateWithName` to create a proper power management assertion.

---

## Architecture: How Services Tie Together

vorssaint‑utils follows a consistent pattern across all utilities:

| Layer | Responsibility | Key File |
|-------|---------------|----------|
| **Entry point** | CLI parsing, defaults registration, app launch | [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) |
| **Lifecycle** | Service instantiation, UI wiring, cleanup | [`Sources/Vorssaint/App/AppDelegate.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/App/AppDelegate.swift) |
| **Features** | Observable services that react to permissions and preferences | `Services/*/*.swift` |
| **UI** | SwiftUI panels mixed with `NSView` subclasses for custom drawing | Instantiated in `AppDelegate` |

Each service conforms to `ObservableObject`, so SwiftUI views automatically refresh when state changes. The **Features** settings page lets users install or uninstall entire utilities—this simply toggles the corresponding service on or off.

---

## Key Source Files Reference

- **Application boot**: [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift)
- **UI and service wiring**: [`Sources/Vorssaint/App/AppDelegate.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/App/AppDelegate.swift)
- **Text snippets**: [`Sources/Vorssaint/Services/Snippets/TextSnippetService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Snippets/TextSnippetService.swift)
- **Window management**: [`Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/WindowLayout/WindowLayoutService.swift)
- **Quick‑drop shelf**: [`Sources/Vorssaint/Services/Shelf/ShelfService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Shelf/ShelfService.swift)
- **System metrics**: [`Sources/Vorssaint/Services/SystemMonitor/SystemMonitor.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/SystemMonitor/SystemMonitor.swift)
- **Update engine**: [`Sources/Vorssaint/Services/Update/UpdateService.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Update/UpdateService.swift)
- **Complete removal**: [`Sources/Vorssaint/Services/Uninstall/AppUninstaller.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/Uninstall/AppUninstaller.swift)

---

## Summary

- **Import once**: `import Vorssaint` exposes all service APIs.
- **Script anything**: Launch flags, snippets, window moves, shelf items, and power assertions all have programmatic interfaces.
- **Observable pattern**: Services publish state changes; UI updates automatically.
- **Modular by design**: Uninstall a feature and its service stops cleanly.

These vorssaint‑utils examples demonstrate how the codebase prioritizes automation and extensibility over a locked‑down GUI.

---

## Frequently Asked Questions

### Can I use vorssaint‑utils without the full menu‑bar app?

Yes. Import the `Vorssaint` module and invoke individual services directly. The `VorssaintMain.run` method exists for complete launches, but `TextSnippetService.shared`, `WindowLayoutService.shared`, and others function independently once imported.

### Where are user settings stored?

Services persist configuration to `UserDefaults` under domain‑specific keys. `TextSnippetService`, for example, serializes snippets to standard preferences, which `syncWithPreferences()` re‑reads at runtime.

### How do I add a new utility to vorssaint‑utils?

Create a new `ObservableObject` service in `Sources/Vorssaint/Services/`, wire it to [`AppDelegate.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/AppDelegate.swift) for lifecycle management, and expose install/uninstall toggles through the Features UI. Follow the existing pattern in `ShelfService` or `KeepAwakeService` for consistency.

### Is there a public API for the system monitor?

The `SystemMonitor` class publishes CPU, GPU, memory, and temperature data. Instantiate it or access a shared instance if exposed, then subscribe to its `ObservableObject` output for real‑time metrics in custom SwiftUI views.