An auto tiler for macOS
8.8 kB · 194 lines
Markdown
at main

ParcelConfig #

Read, validate, and edit TOML without losing the reader's comments.

Start small #

The app creates ~/.config/parcel/parcel.toml on first launch. Omitted settings use defaults; display overrides inherit the global layout, including individual gap and reserved-edge values.

#:schema https://tangled.org/vinnymac.dev/parcel/raw/main/docs/parcel.schema.json
version = 1

[layout]
default = "side"
portrait-layout = "rows"
ratio = 0.5
gaps = { inner = 8, outer = 8 }

[layout.displays."47CA9DB1-A0EB-446B-B774-79FC512EAE4D"]
default = "columns"

[keybindings]
focus-left = "hyper-h"
stack = false
"space-focus 2" = "hyper-2"
"window-to-space 2 --follow" = "ctrl-alt-shift-2"
space-back-and-forth = "hyper-tab"

[[rules]]
bundle-id = "org.example.notes"
title-contains = "Draft"
action = "float"

Display keys are UUIDs. Rule matchers combine with AND; the last matching rule wins. Each rule needs a matcher and an outcome: action, display, or position. Use either title-contains or title-regex, not both. The older float-rules table is still accepted.

Layout and Space commands #

Layout names are grid, columns, rows, side, tree, bsp, and accordion. layout.portrait-layout defaults to rows on displays taller than they are wide; landscape and square displays use layout.default. Display overrides accept both settings and inherit omitted values. These choose a new workspace's layout. Rotating a display adapts the selected layout without replacing a runtime choice. Reloading a changed orientation-specific default applies it to matching workspaces.

window-cap accepts whole numbers from 0 through 100 and defaults to 3. Positive requests are limited by each layout's display-dependent capability without changing the stored request; 0 explicitly opts out of both limits. Extra windows follow when-full: stack joins the active tile, while float leaves new overflow windows floating. The configurable count presets set-window-cap 1 through set-window-cap 5 set the runtime request; their default shortcuts are Control–Option–Command plus 1 through 5. Presets above the current capability are accepted, with only the effective cap limited. Reloads preserve custom splits and runtime ratio/cap choices when those configuration values have not changed.

Select layouts with layout-grid, layout-columns, layout-rows, layout-side, layout-tree, layout-bsp, or layout-accordion. Tree editing uses split-horizontal and split-vertical to choose the next insertion's axis. join-left, join-right, join-up, and join-down reinsert the focused stack beside a neighbor. Transform the tree with balance, rotate, mirror-horizontal, or mirror-vertical; adjust its split with ratio-increase and ratio-decrease. The unbound main-size presets are ratio-half, ratio-three-fifths, and ratio-two-thirds.

Native Space commands are space-focus N, space-next, space-previous, space-back-and-forth, window-to-space N, window-to-space-next, and window-to-space-previous. The three window-move commands accept --follow. They use enabled Mission Control shortcuts. Desktop numbers are the system's 1–16 numbers, not Space IDs; targets must be on the active display. Moves return unless you use --follow. Space commands have no default bindings. Quote command keys that contain arguments.

general.prefix changes default bindings only. Explicit chords are absolute; hyper expands to Control, Option, Command, and Shift. Chords use physical ANSI keys and print in ctrl-alt-cmd-shift-fn order; opt prints as alt, and the minus key prints as minus. Bind a command to false to remove its shortcut. Count shortcuts add Command to the prefix and use 1 through 5. Snap halves use the prefix plus 6 through 9, keeping inherited defaults distinct for every modifier prefix. Quote count commands in TOML, such as "set-window-cap 2" = "fn-2". Most snap actions are unbound by default. The schema lists bindable commands; DefaultKeybindings.bindings() lists their default shortcuts.

Mouse gestures use nonempty, distinct modifier sets: cmd for swapping and alt-cmd for stacking by default. These do not use the keyboard prefix. Motion preferences never override the system's Reduce Motion setting.

Focus modes #

Focus, No peek, and Clean Space start off and apply to the current native Space. Their configurable defaults are prefix+Z, prefix+D, and prefix+P.

#:schema https://tangled.org/vinnymac.dev/parcel/raw/main/docs/parcel.schema.json
[focus-modes]
no-peek-level = 0.25
no-peek-blur = true
clean-space-color = "graphite"

[keybindings]
focus-toggle = "ctrl-alt-z"
no-peek-toggle = "ctrl-alt-d"
clean-space-toggle = "ctrl-alt-p"

No peek accepts levels from 0.1 to 0.9. Backdrops are graphite, mist, or stone. Settings writes the same keys. Toggle modes through the shortcuts, menu, Settings, or CLI; enabled state is temporary, not a startup preference.

Named binding modes #

#:schema https://tangled.org/vinnymac.dev/parcel/raw/main/docs/parcel.schema.json
[keybindings]
"enter-mode resize" = "ctrl-alt-f20"

[mode.resize]
ratio-increase = "right"
ratio-decrease = "left"
"enter-mode move" = "m"
exit-mode = "escape"

[mode.move]
move-left = "h"
"window-to-space-next --follow" = "n"
"enter-mode resize" = "r"
exit-mode = false

A mode name is case-sensitive and uses ASCII letters, digits, underscores, or hyphens. default is reserved, regardless of case. References may precede their mode tables, and empty mode tables are allowed. Each named mode starts with DefaultKeybindings.modeExit; override exit-mode or set it to false to remove it. Other commands have no inherited bindings in a named mode. false disables an action, including a mode entry. Entry targets must name a declared mode even when disabled. Entering another mode switches directly to it; exit-mode returns to the default bindings and is only valid inside a named mode.

Default bindings, including mode entries, must resolve to distinct chords. The same holds within each named mode, including its default exit shortcut. Chords may be reused in different modes. Invalid mode names, actions, targets, values, and conflicts reject the configuration with source locations. Unknown ordinary keys under [keybindings] continue to warn.

BindingAction represents a command, a named-mode entry, or a mode exit. keybindings and defaultModeEntries hold default-mode shortcuts; modes holds each named mode's action-to-chord map. Direct model construction stores those maps as supplied; TOML validation supplies the inherited exit binding. Call validateBindingModes() before applying a directly constructed or mutated configuration. It throws ConfigDiagnostic for invalid names, targets, or conflicting supplied chords without adding bindings or changing the model. Direct named modes may omit an exit shortcut.

Read, edit, and reload #

var document = try TOMLDocument(parsing: source)
let result = ConfigValidator.validate(document)
try document.setValue(.integer(12), forKey: ["layout", "gaps", "inner"])
let updatedSource = document.render()

Leaf edits preserve surrounding text. Replacing a whole collection replaces its formatting too. Edits reparse before committing, so a failed edit leaves the document alone. Dates and times must be quoted as text. Diagnostic lines and columns are one-based and count Unicode scalars.

ConfigStore is an actor. Call createDefaultFileIfMissing() during app startup to write defaultFileContents; it never replaces an existing file and throws on IO failures. reload() only reads. Subscribe to updates() for snapshots, or use startWatching(debounceInterval:) for debounced filesystem updates. Call stopWatching() when the owner is done.

Invalid reads keep the last good configuration. Unknown keys warn; wrong types, bad ranges, unsupported versions, and conflicting shortcuts reject the edit. Setting names use dashes. Underscore spellings are unknown keys: they warn with a dashed-key suggestion and leave that preference unchanged. They are not aliases.

Editor schema and strings #

ConfigJSONSchema.string exports draft 2020-12 JSON Schema. publishedURL is the editor hint's canonical address. prcl schema prints the schema locally, with a final newline. Regenerate docs/parcel.schema.json with swift run prcl schema > docs/parcel.schema.json; a test prevents drift. Portable validators check structure. Parcel also checks chord grammar, native regular expressions, declared mode targets, and effective shortcut conflicts.

Edit diagnostics in the module's String Catalogs. The build plugin compiles localized resources under .build; generated strings are not committed.