Struct ConfigManager 

pub struct ConfigManager<T> { /* private fields */ }

Manages one typed JSON settings file.

ConfigManager<T> stores and loads a complete configuration value of type T. The type must implement Serde Serialize and DeserializeOwned.

The manager is intentionally small. It owns only:

• the directory containing the settings file,
• the settings file name,
• the JSON output format, and
• the save strategy.

Implementations

impl<T> ConfigManager<T>

where T: Serialize + DeserializeOwned,

pub fn new() -> Self

Creates a config manager using the OS-standard config directory and the current executable name.

On Windows desktop apps this resolves under %APPDATA%. Pure UWP apps should use with_root_dir or the optional uwp feature instead.

This constructor cannot report failure without an API break, so it falls back silently in two places instead of erroring:

• if the platform configuration directory cannot be determined (for example, no HOME or %APPDATA% in the environment), it falls back to the current directory (.);
• if the current executable’s name cannot be determined, or is not a safe path component, it falls back to the literal name "app".

The second fallback is a fixed constant. Any two executables that both hit it resolve to the same settings file and can silently read and overwrite each other’s settings. If that is not acceptable, use try_new to fail instead of falling back, or for_app to supply an explicit identity so nothing is derived in the first place.

Examples found in repository

examples/update.rs (line 21)

fn main() -> app_json_settings::Result<()> {
    let root = std::env::temp_dir().join("app-json-settings-update-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(root)
        .try_with_filename("settings.json")?;

    let updated = manager.update(|settings| {
        settings.launch_count += 1;
        if settings.theme.is_empty() {
            settings.theme = "system".to_string();
        }
    })?;

    println!("settings path: {}", manager.path().display());
    println!("launch count: {}", updated.launch_count);
    println!("theme: {}", updated.theme);

    Ok(())
}

examples/basic.rs (line 31)

fn main() -> app_json_settings::Result<()> {
    // The production desktop form is usually:
    //
    // let manager = ConfigManager::<AppSettings>::for_app("my-gui-app")?;
    //
    // This example uses a temporary root so running it does not write to your
    // real app settings directory.
    let root = std::env::temp_dir().join("app-json-settings-basic-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(root)
        .try_with_filename("settings.json")?;

    let settings = manager.load_or_default()?;

    println!("settings path: {}", manager.path().display());
    println!("theme: {}", settings.theme);
    println!(
        "window: {}x{}",
        settings.window_width, settings.window_height
    );

    Ok(())
}

examples/custom_root.rs (line 24)

fn main() -> app_json_settings::Result<()> {
    // Caller-provided roots are useful for portable apps, tests, sandboxed
    // hosts, and UWP-style apps where the host resolves its own local folder.
    let root = std::env::temp_dir().join("app-json-settings-custom-root-example");

    let manager = ConfigManager::<PortableSettings>::new()
        .with_root_dir(&root)
        .try_with_filename("preferences.json")?;

    let mut settings = manager.load_or_default()?;

    if settings.recent_files.is_empty() {
        settings
            .recent_files
            .push("/example/documents/readme.md".to_string());
        manager.save(&settings)?;
    }

    println!("custom root: {}", root.display());
    println!("settings file: {}", manager.path().display());
    println!("recent files: {:?}", settings.recent_files);

    Ok(())
}

examples/recovery.rs (line 12)

fn main() -> app_json_settings::Result<()> {
    let root = std::env::temp_dir().join("app-json-settings-recovery-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(&root)
        .try_with_filename("settings.json")?;

    // Simulate a settings file left unreadable by an external edit, so this
    // example actually exercises the recovery branch below instead of
    // silently taking the happy path. A real application would not do this;
    // it would simply encounter an already-invalid file.
    std::fs::create_dir_all(&root)?;
    std::fs::write(manager.path(), "not-json")?;

    let settings = match manager.load_or_default() {
        Ok(settings) => settings,
        Err(ConfigError::Deserialize(error)) => {
            eprintln!("settings file is invalid, moving it aside: {error}");

            // The backup carries the same sensitivity as the original
            // settings file. Handle it with the same care you would give
            // the original (see docs/src/save-behavior.md for the Unix
            // permission model this crate applies to the file itself).
            let backup = manager.path().with_extension("json.bak");
            std::fs::rename(manager.path(), &backup)?;
            println!("backed up invalid settings to: {}", backup.display());

            manager.load_or_default()?
        }
        Err(error) => return Err(error),
    };

    println!("settings path: {}", manager.path().display());
    println!("theme: {}", settings.theme);
    println!("launch count: {}", settings.launch_count);

    Ok(())
}

pub fn try_new() -> Result<Self>

Creates a config manager using the OS-standard config directory and the current executable name, failing rather than silently substituting either.

Fail-closed counterpart to new: returns ConfigError::Platform if the platform configuration directory cannot be resolved, or if the current executable’s name cannot be determined or is not a safe path component – the two cases new() papers over with . and "app" respectively. Both failures report through the same variant with distinguishable messages, since adding a dedicated variant would itself be a breaking change: ConfigError is not #[non_exhaustive], so a new variant breaks any exhaustive match on it.

Prefer this over new() when you genuinely want the executable’s derived name but sharing a settings file with another executable that hits the same fallback is not acceptable. If you have a stable application identity to supply instead, prefer for_app, which needs no derivation at all.

pub fn for_app(app_name: &str) -> Result<Self>

Creates a config manager for an explicit application name.

This is the recommended desktop constructor for production apps because the storage directory is stable even if the executable file name changes. The app_name must be a single safe path component, not a path.

Returns ConfigError::Platform if the platform configuration directory cannot be resolved (for example, no HOME or %APPDATA% in the environment). Applications that hit this in practice — typically services or containers without a user environment — should supply a path explicitly with with_root_dir instead.

pub fn at_current_dir(self) -> Self

Stores the settings file in the current working directory.

If the current working directory cannot be determined, falls back to ".". Unlike for_app, this fallback is not surprising here: the caller explicitly asked for working-directory storage, and "." already means “the working directory” to the filesystem.

pub fn with_root_dir<P: Into<PathBuf>>(self, path: P) -> Self

Stores the settings file in a caller-provided directory.

This is the primary compatibility seam for sandboxed hosts, including Pure UWP. The host application may resolve its application data directory and pass it here.

Examples found in repository

examples/update.rs (line 22)

fn main() -> app_json_settings::Result<()> {
    let root = std::env::temp_dir().join("app-json-settings-update-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(root)
        .try_with_filename("settings.json")?;

    let updated = manager.update(|settings| {
        settings.launch_count += 1;
        if settings.theme.is_empty() {
            settings.theme = "system".to_string();
        }
    })?;

    println!("settings path: {}", manager.path().display());
    println!("launch count: {}", updated.launch_count);
    println!("theme: {}", updated.theme);

    Ok(())
}

examples/basic.rs (line 32)

fn main() -> app_json_settings::Result<()> {
    // The production desktop form is usually:
    //
    // let manager = ConfigManager::<AppSettings>::for_app("my-gui-app")?;
    //
    // This example uses a temporary root so running it does not write to your
    // real app settings directory.
    let root = std::env::temp_dir().join("app-json-settings-basic-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(root)
        .try_with_filename("settings.json")?;

    let settings = manager.load_or_default()?;

    println!("settings path: {}", manager.path().display());
    println!("theme: {}", settings.theme);
    println!(
        "window: {}x{}",
        settings.window_width, settings.window_height
    );

    Ok(())
}

examples/custom_root.rs (line 25)

fn main() -> app_json_settings::Result<()> {
    // Caller-provided roots are useful for portable apps, tests, sandboxed
    // hosts, and UWP-style apps where the host resolves its own local folder.
    let root = std::env::temp_dir().join("app-json-settings-custom-root-example");

    let manager = ConfigManager::<PortableSettings>::new()
        .with_root_dir(&root)
        .try_with_filename("preferences.json")?;

    let mut settings = manager.load_or_default()?;

    if settings.recent_files.is_empty() {
        settings
            .recent_files
            .push("/example/documents/readme.md".to_string());
        manager.save(&settings)?;
    }

    println!("custom root: {}", root.display());
    println!("settings file: {}", manager.path().display());
    println!("recent files: {:?}", settings.recent_files);

    Ok(())
}

examples/recovery.rs (line 13)

fn main() -> app_json_settings::Result<()> {
    let root = std::env::temp_dir().join("app-json-settings-recovery-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(&root)
        .try_with_filename("settings.json")?;

    // Simulate a settings file left unreadable by an external edit, so this
    // example actually exercises the recovery branch below instead of
    // silently taking the happy path. A real application would not do this;
    // it would simply encounter an already-invalid file.
    std::fs::create_dir_all(&root)?;
    std::fs::write(manager.path(), "not-json")?;

    let settings = match manager.load_or_default() {
        Ok(settings) => settings,
        Err(ConfigError::Deserialize(error)) => {
            eprintln!("settings file is invalid, moving it aside: {error}");

            // The backup carries the same sensitivity as the original
            // settings file. Handle it with the same care you would give
            // the original (see docs/src/save-behavior.md for the Unix
            // permission model this crate applies to the file itself).
            let backup = manager.path().with_extension("json.bak");
            std::fs::rename(manager.path(), &backup)?;
            println!("backed up invalid settings to: {}", backup.display());

            manager.load_or_default()?
        }
        Err(error) => return Err(error),
    };

    println!("settings path: {}", manager.path().display());
    println!("theme: {}", settings.theme);
    println!("launch count: {}", settings.launch_count);

    Ok(())
}

pub fn at_custom_dir<P: Into<PathBuf>>(self, path: P) -> Self

Stores the settings file in a caller-provided directory.

This method is kept for compatibility with v2.0.x. Prefer with_root_dir in new code.

pub fn with_filename(self, name: &str) -> Self

Changes the settings file name without validation.

This method is retained for v2.x compatibility. New code should prefer try_with_filename, which rejects path-like names such as ../settings.json.

pub fn try_with_filename(self, name: &str) -> Result<Self>

Changes the settings file name after validating it as a plain file name.

The accepted value must be a single file name, not an absolute path and not a relative path containing directory traversal.

Examples found in repository

examples/update.rs (line 23)

fn main() -> app_json_settings::Result<()> {
    let root = std::env::temp_dir().join("app-json-settings-update-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(root)
        .try_with_filename("settings.json")?;

    let updated = manager.update(|settings| {
        settings.launch_count += 1;
        if settings.theme.is_empty() {
            settings.theme = "system".to_string();
        }
    })?;

    println!("settings path: {}", manager.path().display());
    println!("launch count: {}", updated.launch_count);
    println!("theme: {}", updated.theme);

    Ok(())
}

examples/basic.rs (line 33)

fn main() -> app_json_settings::Result<()> {
    // The production desktop form is usually:
    //
    // let manager = ConfigManager::<AppSettings>::for_app("my-gui-app")?;
    //
    // This example uses a temporary root so running it does not write to your
    // real app settings directory.
    let root = std::env::temp_dir().join("app-json-settings-basic-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(root)
        .try_with_filename("settings.json")?;

    let settings = manager.load_or_default()?;

    println!("settings path: {}", manager.path().display());
    println!("theme: {}", settings.theme);
    println!(
        "window: {}x{}",
        settings.window_width, settings.window_height
    );

    Ok(())
}

examples/custom_root.rs (line 26)

fn main() -> app_json_settings::Result<()> {
    // Caller-provided roots are useful for portable apps, tests, sandboxed
    // hosts, and UWP-style apps where the host resolves its own local folder.
    let root = std::env::temp_dir().join("app-json-settings-custom-root-example");

    let manager = ConfigManager::<PortableSettings>::new()
        .with_root_dir(&root)
        .try_with_filename("preferences.json")?;

    let mut settings = manager.load_or_default()?;

    if settings.recent_files.is_empty() {
        settings
            .recent_files
            .push("/example/documents/readme.md".to_string());
        manager.save(&settings)?;
    }

    println!("custom root: {}", root.display());
    println!("settings file: {}", manager.path().display());
    println!("recent files: {:?}", settings.recent_files);

    Ok(())
}

examples/recovery.rs (line 14)

fn main() -> app_json_settings::Result<()> {
    let root = std::env::temp_dir().join("app-json-settings-recovery-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(&root)
        .try_with_filename("settings.json")?;

    // Simulate a settings file left unreadable by an external edit, so this
    // example actually exercises the recovery branch below instead of
    // silently taking the happy path. A real application would not do this;
    // it would simply encounter an already-invalid file.
    std::fs::create_dir_all(&root)?;
    std::fs::write(manager.path(), "not-json")?;

    let settings = match manager.load_or_default() {
        Ok(settings) => settings,
        Err(ConfigError::Deserialize(error)) => {
            eprintln!("settings file is invalid, moving it aside: {error}");

            // The backup carries the same sensitivity as the original
            // settings file. Handle it with the same care you would give
            // the original (see docs/src/save-behavior.md for the Unix
            // permission model this crate applies to the file itself).
            let backup = manager.path().with_extension("json.bak");
            std::fs::rename(manager.path(), &backup)?;
            println!("backed up invalid settings to: {}", backup.display());

            manager.load_or_default()?
        }
        Err(error) => return Err(error),
    };

    println!("settings path: {}", manager.path().display());
    println!("theme: {}", settings.theme);
    println!("launch count: {}", settings.launch_count);

    Ok(())
}

pub fn disable_pretty_json(self) -> Self

Stores JSON in compact form instead of pretty-printed form.

pub fn with_save_mode(self, mode: SaveMode) -> Self

Selects the save strategy.

The default is SaveMode::Atomic. Use SaveMode::Direct only when an application intentionally wants v2.2-style direct overwrite behavior or needs to work around unusual filesystem semantics.

pub fn with_direct_save(self) -> Self

Selects direct overwrite saves.

This is a convenience alias for with_save_mode(SaveMode::Direct).

pub fn save_mode(&self) -> SaveMode

Returns the configured save strategy.

pub fn folder_path(&self) -> &Path

Returns the settings folder path.

pub fn file_name(&self) -> &str

Returns the settings file name.

pub fn path(&self) -> PathBuf

Returns the settings file path.

Examples found in repository

examples/update.rs (line 32)

fn main() -> app_json_settings::Result<()> {
    let root = std::env::temp_dir().join("app-json-settings-update-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(root)
        .try_with_filename("settings.json")?;

    let updated = manager.update(|settings| {
        settings.launch_count += 1;
        if settings.theme.is_empty() {
            settings.theme = "system".to_string();
        }
    })?;

    println!("settings path: {}", manager.path().display());
    println!("launch count: {}", updated.launch_count);
    println!("theme: {}", updated.theme);

    Ok(())
}

examples/basic.rs (line 37)

fn main() -> app_json_settings::Result<()> {
    // The production desktop form is usually:
    //
    // let manager = ConfigManager::<AppSettings>::for_app("my-gui-app")?;
    //
    // This example uses a temporary root so running it does not write to your
    // real app settings directory.
    let root = std::env::temp_dir().join("app-json-settings-basic-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(root)
        .try_with_filename("settings.json")?;

    let settings = manager.load_or_default()?;

    println!("settings path: {}", manager.path().display());
    println!("theme: {}", settings.theme);
    println!(
        "window: {}x{}",
        settings.window_width, settings.window_height
    );

    Ok(())
}

examples/custom_root.rs (line 38)

fn main() -> app_json_settings::Result<()> {
    // Caller-provided roots are useful for portable apps, tests, sandboxed
    // hosts, and UWP-style apps where the host resolves its own local folder.
    let root = std::env::temp_dir().join("app-json-settings-custom-root-example");

    let manager = ConfigManager::<PortableSettings>::new()
        .with_root_dir(&root)
        .try_with_filename("preferences.json")?;

    let mut settings = manager.load_or_default()?;

    if settings.recent_files.is_empty() {
        settings
            .recent_files
            .push("/example/documents/readme.md".to_string());
        manager.save(&settings)?;
    }

    println!("custom root: {}", root.display());
    println!("settings file: {}", manager.path().display());
    println!("recent files: {:?}", settings.recent_files);

    Ok(())
}

examples/recovery.rs (line 21)

fn main() -> app_json_settings::Result<()> {
    let root = std::env::temp_dir().join("app-json-settings-recovery-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(&root)
        .try_with_filename("settings.json")?;

    // Simulate a settings file left unreadable by an external edit, so this
    // example actually exercises the recovery branch below instead of
    // silently taking the happy path. A real application would not do this;
    // it would simply encounter an already-invalid file.
    std::fs::create_dir_all(&root)?;
    std::fs::write(manager.path(), "not-json")?;

    let settings = match manager.load_or_default() {
        Ok(settings) => settings,
        Err(ConfigError::Deserialize(error)) => {
            eprintln!("settings file is invalid, moving it aside: {error}");

            // The backup carries the same sensitivity as the original
            // settings file. Handle it with the same care you would give
            // the original (see docs/src/save-behavior.md for the Unix
            // permission model this crate applies to the file itself).
            let backup = manager.path().with_extension("json.bak");
            std::fs::rename(manager.path(), &backup)?;
            println!("backed up invalid settings to: {}", backup.display());

            manager.load_or_default()?
        }
        Err(error) => return Err(error),
    };

    println!("settings path: {}", manager.path().display());
    println!("theme: {}", settings.theme);
    println!("launch count: {}", settings.launch_count);

    Ok(())
}

pub fn save(&self, config: &T) -> Result<()>

Saves the complete configuration, replacing the existing file content.

Examples found in repository

examples/custom_root.rs (line 34)

fn main() -> app_json_settings::Result<()> {
    // Caller-provided roots are useful for portable apps, tests, sandboxed
    // hosts, and UWP-style apps where the host resolves its own local folder.
    let root = std::env::temp_dir().join("app-json-settings-custom-root-example");

    let manager = ConfigManager::<PortableSettings>::new()
        .with_root_dir(&root)
        .try_with_filename("preferences.json")?;

    let mut settings = manager.load_or_default()?;

    if settings.recent_files.is_empty() {
        settings
            .recent_files
            .push("/example/documents/readme.md".to_string());
        manager.save(&settings)?;
    }

    println!("custom root: {}", root.display());
    println!("settings file: {}", manager.path().display());
    println!("recent files: {:?}", settings.recent_files);

    Ok(())
}

pub fn load(&self) -> Result<T>

Loads a configuration file that is expected to already exist.

impl<T> ConfigManager<T>

where T: Serialize + DeserializeOwned + Default,

pub fn load_or_default(&self) -> Result<T>

Loads the configuration, or creates and saves T::default() on first run.

Examples found in repository

examples/basic.rs (line 35)

fn main() -> app_json_settings::Result<()> {
    // The production desktop form is usually:
    //
    // let manager = ConfigManager::<AppSettings>::for_app("my-gui-app")?;
    //
    // This example uses a temporary root so running it does not write to your
    // real app settings directory.
    let root = std::env::temp_dir().join("app-json-settings-basic-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(root)
        .try_with_filename("settings.json")?;

    let settings = manager.load_or_default()?;

    println!("settings path: {}", manager.path().display());
    println!("theme: {}", settings.theme);
    println!(
        "window: {}x{}",
        settings.window_width, settings.window_height
    );

    Ok(())
}

examples/custom_root.rs (line 28)

fn main() -> app_json_settings::Result<()> {
    // Caller-provided roots are useful for portable apps, tests, sandboxed
    // hosts, and UWP-style apps where the host resolves its own local folder.
    let root = std::env::temp_dir().join("app-json-settings-custom-root-example");

    let manager = ConfigManager::<PortableSettings>::new()
        .with_root_dir(&root)
        .try_with_filename("preferences.json")?;

    let mut settings = manager.load_or_default()?;

    if settings.recent_files.is_empty() {
        settings
            .recent_files
            .push("/example/documents/readme.md".to_string());
        manager.save(&settings)?;
    }

    println!("custom root: {}", root.display());
    println!("settings file: {}", manager.path().display());
    println!("recent files: {:?}", settings.recent_files);

    Ok(())
}

examples/recovery.rs (line 23)

fn main() -> app_json_settings::Result<()> {
    let root = std::env::temp_dir().join("app-json-settings-recovery-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(&root)
        .try_with_filename("settings.json")?;

    // Simulate a settings file left unreadable by an external edit, so this
    // example actually exercises the recovery branch below instead of
    // silently taking the happy path. A real application would not do this;
    // it would simply encounter an already-invalid file.
    std::fs::create_dir_all(&root)?;
    std::fs::write(manager.path(), "not-json")?;

    let settings = match manager.load_or_default() {
        Ok(settings) => settings,
        Err(ConfigError::Deserialize(error)) => {
            eprintln!("settings file is invalid, moving it aside: {error}");

            // The backup carries the same sensitivity as the original
            // settings file. Handle it with the same care you would give
            // the original (see docs/src/save-behavior.md for the Unix
            // permission model this crate applies to the file itself).
            let backup = manager.path().with_extension("json.bak");
            std::fs::rename(manager.path(), &backup)?;
            println!("backed up invalid settings to: {}", backup.display());

            manager.load_or_default()?
        }
        Err(error) => return Err(error),
    };

    println!("settings path: {}", manager.path().display());
    println!("theme: {}", settings.theme);
    println!("launch count: {}", settings.launch_count);

    Ok(())
}

pub fn update<F>(&self, f: F) -> Result<T>

where F: FnOnce(&mut T),

Applies a read-modify-write update and saves the result.

Examples found in repository

examples/update.rs (lines 25-30)

fn main() -> app_json_settings::Result<()> {
    let root = std::env::temp_dir().join("app-json-settings-update-example");
    let manager = ConfigManager::<AppSettings>::new()
        .with_root_dir(root)
        .try_with_filename("settings.json")?;

    let updated = manager.update(|settings| {
        settings.launch_count += 1;
        if settings.theme.is_empty() {
            settings.theme = "system".to_string();
        }
    })?;

    println!("settings path: {}", manager.path().display());
    println!("launch count: {}", updated.launch_count);
    println!("theme: {}", updated.theme);

    Ok(())
}

Trait Implementations

impl<T: Clone> Clone for ConfigManager<T>

fn clone(&self) -> ConfigManager<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for ConfigManager<T>

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

Formats the value using the given formatter.

impl<T> Default for ConfigManager<T>

where T: Serialize + DeserializeOwned,

fn default() -> Self

Returns the “default value” for a type.