Struct Settings 

pub struct Settings { /* private fields */ }

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

Implementations

impl Settings

pub const THEME: &'static str = "theme"

The key of the theme id.

pub const LANGUAGE: &'static str = "language"

The key of the locale code.

pub const ICONS: &'static str = "icons"

The key of the icon mode: auto, nerd, unicode or ascii.

pub const REDUCED_MOTION: &'static str = "reduced-motion"

The key of the reduced motion flag.

pub const PILLAR: &'static str = "pillar"

The key of the pillar style: thick or thin.

pub const SLIDE: &'static str = "slide"

The key of the selection slide flag.

pub fn in_memory() -> Self

Settings that live only in memory; saving does nothing. For tests and for applications run without a config directory.

pub fn load(app: &str) -> Self

Loads the settings of application app from the platform config directory: $XDG_CONFIG_HOME/<app>/settings.toml or ~/.config/<app>/settings.toml on Linux and other Unix systems, ~/Library/Application Support/<app>/settings.toml on macOS and %APPDATA%\<app>\settings.toml on Windows. Without a home directory the settings stay in memory and a diagnostic says why.

pub fn load_member(family: &Family, app: &str) -> Self

Loads the settings of application app of family from its file in the family’s folder, Family::app_file: ~/.config/quvyta/code.conf for code of Family::QUVYTA on Linux. Without a home directory the settings stay in memory and a diagnostic says why, as with load. Call Family::adopt first to bring the settings over from the folder the application used before.

pub fn member_of(self, family: &Family) -> Self

Marks these settings as those of a member of family, for settings loaded with open from a folder of the application’s choosing; load_member does it itself.

The family’s id ("quvyta" for Family::QUVYTA) is then a valid value of every key Shared names, whatever the schema says: it means “use the family’s shared value”, see Family::preferences. Self-healing keeps it, and theme, language and icon_mode give None for it, so apply leaves those keys to the preferences. Call it before self_heal, which repairs the file as soon as it is turned on.

use qframe::storage::{Family, Schema, Settings};

let text = "theme = \"quvyta\"\nicons = \"quvyta\"\n";
let settings = Settings::parse_str("code.conf", text)
    .member_of(&Family::QUVYTA)
    .schema(Schema::builtin().choice(Settings::THEME, ["monochrome", "nordic"], "monochrome"))
    .self_heal(true);
assert!(settings.diagnostics().is_empty());
assert_eq!(settings.get::<String>(Settings::THEME).as_deref(), Some("quvyta"));
assert_eq!(settings.theme(), None, "follows the family");

pub fn with_diagnostics( self, diagnostics: impl IntoIterator<Item = Diagnostic>, ) -> Self

Puts diagnostics found around loading, such as what Family::adopt left behind, in front of what reading the file found, so diagnostics shows them together. They stay when a schema check runs again.

pub fn open(path: impl Into<PathBuf>) -> Self

Loads settings from path. A missing file is an empty start, not a problem.

pub fn parse_str(file: &str, text: &str) -> Self

Reads settings from TOML text, reporting problems against file. Saving does nothing.

pub fn schema(self, schema: Schema) -> Self

Checks the loaded keys against schema instead of only the built-in keys: keys it does not know and values it does not accept become located warnings. The file is not touched unless self_heal is on.

use qframe::storage::{Schema, Settings};

let text = "language = \"tr\"\ncolor = \"red\"\npillar = \"thick\"\n";
let checked = Settings::parse_str("settings.toml", text).schema(Schema::builtin());
assert_eq!(checked.diagnostics()[0].to_string(), "settings.toml:2:1: warning: `color` is not a known setting; it is ignored");
assert!(checked.value("color").is_some(), "kept while self-healing is off");

pub fn self_heal(self, on: bool) -> Self

Repairs the loaded settings by the schema. Every key is checked on its own: valid keys are kept, unknown keys are removed and invalid values are replaced by their default. An invalid optional key is removed, since it has no default; keys under an open prefix are kept as they are unless a rule declares them. Missing keys are not added. Key order is never a problem and is left as it is. When anything changed, the file as it was is kept under its name with .bak added (settings.toml.bak) and the repaired settings are saved once; every repair is a located warning in diagnostics.

Off by default. Only the application knows all of its keys, so nothing is repaired until a schema is given; the order of the two calls does not matter.

pub fn path(&self) -> Option<&Path>

Where the settings are saved, if anywhere.

pub fn diagnostics(&self) -> &[Diagnostic]

Problems found while loading.

pub fn value(&self, key: &str) -> Option<&SettingValue>

The raw value under key.

pub fn get<T: Setting>(&self, key: &str) -> Option<T>

The value under key as T; None when missing or of another type.

pub fn get_or<T: Setting>(&self, key: &str, default: T) -> T

The value under key as T, or default.

pub fn set<T: Setting>(&mut self, key: &str, value: T) -> bool

Stores value under key. Returns whether anything changed.

pub fn remove(&mut self, key: &str) -> bool

Removes key. Returns whether it existed.

pub fn keys(&self) -> impl Iterator<Item = &str>

Every key, in file order.

pub fn theme(&self) -> Option<String>

The saved theme id; None when the file says to follow the family, see member_of.

pub fn language(&self) -> Option<String>

The saved locale code; None when the file says to follow the family, see member_of.

pub fn icon_mode(&self) -> Option<IconMode>

The saved icon mode.

pub fn reduced_motion(&self) -> Option<bool>

The saved reduced motion flag.

pub fn pillar_style(&self) -> Option<PillarStyle>

The saved pillar style.

pub fn slide(&self) -> Option<bool>

The saved selection slide flag.

pub fn apply<Msg: Send + 'static>(&self) -> Command<Msg>

Commands that switch theme, language, icons, reduced motion, pillar and slide to the saved values; nothing for values that are not saved.

pub fn to_toml(&self) -> String

The settings as TOML text: plain keys first, then one table per dotted prefix.

pub fn save(&mut self) -> Result<()>

Writes the settings to their file atomically, creating the directory when needed. In-memory settings do nothing. A file that was loaded with problems, or that healing changed, is first copied next to itself under its name with .bak added.

Errors

Returns the I/O error when the directory or file cannot be written.

pub fn save_command<Msg: Send + 'static>( &self, done: impl FnOnce(Result<(), String>) -> Msg + Send + 'static, ) -> Command<Msg>

Saves a copy of the settings on a background thread and reports the result, so a slow disk never holds up drawing. Use it right after changing a value in update.

Trait Implementations

impl Clone for Settings

fn clone(&self) -> Settings

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Settings

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Settings

fn default() -> Settings

Returns the “default value” for a type.

impl PartialEq for Settings

fn eq(&self, other: &Settings) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Settings