Module storage 

Settings storage: an application’s preferences in a TOML file in the platform config directory.

theme = "nordic"
language = "tr"

[editor]
tab-width = 4

Keys are dotted paths ("editor.tab-width"); the dots become TOML tables. Loading never fails: a broken file yields located Diagnostics, broken entries are skipped and the rest is used. Saving goes through atomic_write, so a crash never leaves half a file; a file that could not be read completely is kept under its own name with .bak added (settings.toml.bak, code.conf.bak) before it is first overwritten.

The module also holds what every application needs around its own files, settings or not: config_dir and data_dir for the two folders a platform gives an application and state_dir and cache_dir for what it remembers between runs and what it can rebuild, atomic_write for writing any file safely, AppLock for “one instance at a time” and InstanceLock for “wake me when the last instance closes”, machine_name for keeping one file per machine in a folder several machines share, and FolderWatch for hearing about changes in a folder the moment the system sees them.

Applications made to be used together keep their settings in one folder: a Family names it, gives each application its <app>.conf file and a folder beside it, and Family::adopt moves an application’s settings there from the folder it used on its own. documents_dir and Family::workspace_dir say where the user’s own work goes. Family::preferences resolves the language, theme and icons the family’s applications share, and Family::set changes one of them for every application or for one.

An application can describe its keys with a Schema. Loading then checks every key against it, and with Settings::self_heal on it repairs the file: unknown keys are removed, invalid values are replaced by their default, and each repair is reported. Optional keys (Schema::optional) are kept only while valid, and keys under an open prefix (Schema::open) are kept as they are. A missing key is never written: reading it gives None and the application falls back to its default.

Structs

AppLock

An advisory lock on a file, held by the running process for as long as this value lives.

Family

A family of applications that share one settings folder.

FolderChange

One change in a watched folder, as FolderChanges::next reports it.

FolderChanges

The waiting side of a FolderWatch; see FolderChanges::next.

FolderWatch

Watches folders for changes the operating system reports, and never polls.

InstanceLock

A shared or exclusive advisory lock on a file, held for as long as this value lives.

Migration

What Family::adopt did: the files it moved and, for everything it left behind, a diagnostic that names the path and says why.

Preferences

The shared preferences as one application sees them, from Family::preferences.

Resolved

A preference’s value together with where it came from.

Schema

The settings an application knows: every key with what it may hold and its default.

SettingKind

What an optional key may hold, for Schema::optional: the same kinds as the builders with a default (Schema::flag, Schema::text, Schema::choice, Schema::check), without the default.

Settings

An application’s settings: typed values under dotted keys, loaded from and saved to one TOML file.

Enums

FolderChangeKind

What happened in a watched folder; see FolderChange.

Scope

Where Family::set writes a change: the “In every Quvyta application” choice of a settings screen.

SettingValue

A value stored in settings.

Shared

A preference every application of a family shares.

Source

Where a resolved preference came from, so a settings screen can say “follows every Quvyta application” or “only here”.

WriteStep

A step atomic_write has finished, in the order they happen.

Traits

Setting

A Rust type that can be read from and written to settings.

Functions

atomic_write

Writes contents to path so that a crash or a power cut leaves either the file that was there before or the new one, never half of either.

atomic_write_reporting

atomic_write, reporting each step to on_step as it finishes, for a log or a screen that shows what writing a file safely actually does.

cache_dir

Where application app keeps its cache: files it can rebuild at any time, which the user or the system may delete without losing anything.

config_dir

Where application app keeps its settings.

data_dir

Where application app keeps its own data: records, caches it wants to survive, files it wrote itself. Records are not settings, so they do not live next to them.

documents_dir

The user’s Documents folder, where an application puts files the user made and wants to find again in a file manager: projects, exports, notes.

holder_pid

The process id the lock file names, for a message such as “another instance (12345) is running”. None when the file is missing, empty or holds anything but a number.

machine_name

The name of this machine, safe to use inside a file name, such as running-<machine>.toml.

state_dir

Where application app keeps its state: what it remembers between runs that is worth keeping but does not belong to the user’s settings or records, such as the result of its last background check or the tab it was last on.