Crate confy

Zero-boilerplate configuration management

Why?

There are a lot of different requirements when selecting, loading and writing a config, depending on the operating system and other environment factors.

In many applications this burden is left to you, the developer of an application, to figure out where to place the configuration files.

This is where confy comes in.

Idea

confy takes care of figuring out operating system specific and environment paths before reading and writing a configuration.

It gives you easy access to a configuration file which is mirrored into a Rust struct via serde. This way you only need to worry about the layout of your configuration, not where and how to store it.

confy uses the Default trait in Rust to automatically create a new configuration, if none is available to read from yet. This means that you can simply assume your application to have a configuration, which will be created with default values of your choosing, without requiring any special logic to handle creation.

use serde_derive::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct MyConfig {
    version: u8,
    api_key: String,
}

/// `MyConfig` implements `Default`
impl ::std::default::Default for MyConfig {
    fn default() -> Self { Self { version: 0, api_key: "".into() } }
}

fn main() -> Result<(), confy::ConfyError> {
    let cfg: MyConfig = confy::load("my-app-name", None)?;
    Ok(())
}

Serde is a required dependency, and can be added with either the serde_derive crate or serde crate with feature derive as shown below

[dependencies]
serde = { version = "1.0.152", features = ["derive"] } # <- Only one serde version needed (serde or serde_derive)
serde_derive = "1.0.152" # <- Only one serde version needed (serde or serde_derive)
confy = "^0.6"

Updating the configuration is then done via the store function.

Features

Exactly one of the features has to be enabled from the following table.

Tip

to add this crate to your project with the default, toml config do the following: cargo add confy, otherwise do something like: cargo add confy --no-default-features --features yaml_conf, for more info, see cargo docs on features

feature	file format	description
default: toml_conf	toml	considered a reasonable default, uses the standard-compliant toml crate
yaml_conf	yaml	uses the serde_yaml crate
ron_conf	ron	Rusty Object Notation, uses the ron crate
basic_toml_conf	toml	alternative to the default toml_conf, instead of using the toml crate, the basic_toml crate is used, in order to cut down on the number of dependencies, speed up compilation and shrink binary size. DISCLAIMER: this crate is not standard compliant, nor maintained, otherwise should work fine in most situations.

Enums

ConfyError

The errors the confy crate can encounter.

Functions

get_configuration_file_path

Get the configuration file path used by load and store

load

Load an application configuration from disk

load_or_else

Load an application configuration from a specified path.

load_path

Load an application configuration from a specified path.

store

Save changes made to a configuration object

store_path

Save changes made to a configuration object at a specified path

store_path_perms

Save changes made to a configuration object at a specified path

store_perms

Save changes made to a configuration object at a specified path