Async I/O

Async loading & saving

In v0.4.0, DotCfg can load and save complete structs with Tokio file I/O. Enable the async feature as shown in the async I/O introduction, then call these methods from an async function.

Choose what missing configuration means

load_async() returns Ok(None) when neither a file nor matching environment values exist. load_or_error_async() returns Error::NotFound instead. load_or_default_async() saves your type's Default value when there is no source. Pick the behavior your application needs.

Rust, inside an async function

let cfg = DotCfg::new("myapp");

// No file and no matching environment values: Ok(None).
let optional: Option<AppConfig> = cfg.load_async().await?;

// Require a source instead of accepting None.
let required: AppConfig = cfg.load_or_error_async().await?;

// Or create and save AppConfig::default() when no source exists.
let ready: AppConfig = cfg.load_or_default_async().await?;

Save a complete value

save_async() serializes the value in the chosen format and writes it to the source's config file. The directory is created when needed.

Rust

let config = AppConfig {
    theme: "dark".into(),
};

cfg.save_async(&config).await?;

To change one field while preserving the rest of the file, use the methods in async key access.

When you have several sources

ConfigStack provides load_async(), load_or_error_async(), and save_async() for layered configuration. Its save method writes only to the selected source. See async ConfigStack.