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.