ezcfg

A simple library for simple configuration.

Use

1. Add ezcfg to your Rust project:

cargo add ezcfg

2. Use the crate_cfg or pub_cfg macro to define a struct with your configurable values.
   The types you use must implement FromStr and Display.

use ezcfg::{ crate_cfg, Config };

crate_cfg!{
    MyConfig ["~/.path/to.cfg"]
        version: semver::Version,
        description: String,
        some_value: u8
}

3. The struct created by the crate_cfg macro is public within your crate, while the struct created by pub_cfg is exportable.

let my_config = MyConfig {
    version: semver::Version::new(0, 0, 1),
    description: String::from("This is my configuration"),
    some_value: 69u8,
};

4. Because we enforce a static path, writing to file is very clean.

my_config.write().unwrap();

The file at ~/.path/to.cfg will look like this:

version=0.0.1
description=This is my configuration
some_value=69

5. Reading from file into a struct is similarly tidy.

let mut my_config = MyConfig::read().unwrap();
assert_eq!(my_config.some_value, 69u8);

6. As is updating and overwriting values.

my_config.version = semver::Version::new(0, 0, 2);
my_config.some_value = 42u8;
my_config.write().unwrap();

The file will be changed:

version=0.0.2
description=This is my configuration
some_value=42

7. In addition, the path to the configuration file is easily accessible.

let path = MyConfig::PATH;
assert_eq!(path, "~/.path/to.cfg");

Troubleshooting

Please note that the macros expect a single ident token for each type when defining fields.
To use generic types and full module paths as field types, first set up an alias that describes the desired type in a single identifier token:

// Will fail to compile:
crate_cfg!{
    BadConfig ["~/.badcfg"]
        field: Type<T>,
}

// Do this:
type TypeT = Type<T>;

crate_cfg!{
    OkConfig ["~/.okcfg"]
        field: TypeT,
}

Also note that each line obeys field=value, where value can be any type that is representable in string form, as long as the formatted string does not contain the characters \n or =.

Development

• In 0.1.1, there are different macros for public and private configuration structs.
• In 0.0.2, the empty line bug is fixed.

This crate is mostly complete, and designed to be lightweight and minimal.
New features (e.g., provided methods for Config) may be added later if their absence is salient.

If you encounter any bugs, please leave an issue!