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 storage-root resolution failure without an API break, so it falls back to the current directory when the platform configuration directory cannot be determined (for example, no HOME or %APPDATA% in the environment). For production applications, prefer for_app: it uses an explicit stable application identity instead of deriving one from the executable file name, and it reports resolution failure instead of silently falling back.

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(())
}

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(())
}

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(())
}

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(())
}

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(())
}

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.