econf
Loads environment variables into your structs in one shot.
econf allows to override struct fields with environment variables easily. This is useful to build up applications that optionally overrides some configuration with environment variables. Here is the basic usage:
use econf::LoadEnv;
#[derive(Debug, LoadEnv)]
struct A {
x: bool,
y: u64,
}
fn main() {
let a = A {
x: true,
y: 42,
};
println!("Before: {:?}", a);
let a = econf::load(a, "PREFIX");
println!("After: {:?}", a);
}
$ ./app
Before: A { x: true, y: 42 }
After: A { x: true, y: 42 }
$ PREFIX_X=false ./app
Before: A { x: true, y: 42 }
After: A { x: false, y: 42 }
In this example,
PREFIX_Xis loaded toxPREFIX_Yis loaded toy
The environment variables are all upper-case with _ separated.
Why econf?
There are some existing crates that provide similar features but econf is unique in the following ways:
- Supports nesting: Supports nested structs in an intutive manner with a little constraint.
- Supports containers: Supports
Vec,HashMapand various types. - Supplemental: Loads into existing variables in the code without changing the original logic.
- Contributor friendly: Simple code base. Comprehensible with a little study on basic macro usage.
Supported types
- Boolean:
bool - Integer:
isize,usize,i8,i16,i32,i64,i128,u8,u16,u32,u64,u128 - String:
char,String - Float:
f32,f64 - Network:
IpAddr,Ipv4Addr,Ipv6Addr,SocketAddr,SocketAddrV4,SocketAddrV6 - Non-zero types:
NonZeroI128,NonZeroI16,NonZeroI32,NonZeroI64,NonZeroI8,NonZeroIsize,NonZeroU128,NonZeroU16,NonZeroU32,NonZeroU64,NonZeroU8,NonZeroUsize - File system:
PathBuf - Containers:
Vec,HashSet,HashMap,Option,BTreeMap,BTreeSet,BinaryHeap,LinkedList,VecDeque,tuple- Containers are parsed as YAML format. See the tests.
Nesting
Nested structs are supported.
#[derive(LoadEnv)]
struct A {
v1: usize,
v2: B,
}
#[derive(LoadEnv)]
struct B {
v1: usize,
v2: usize,
}
fn main() {
let a = A {
v1: 1,
v2: B {
v1: 2,
v2: 3,
},
};
let a = econf::load(a, "PREFIX");
}
In this example,
PREFIX_V1is loaded toa.v1PREFIX_V2_V1is loaded toa.v2.v1PREFIX_V2_V2is loaded toa.v2.v2
Fields in child structs can be specified by chaining the field names with _ as a separator. However, there're cases that names conflict. For example,
#[derive(LoadEnv)]
struct A {
v2_v1: usize,
v2: B,
}
#[derive(LoadEnv)]
struct B {
v1: usize,
v2: usize,
}
fn main() {
let a = A {
v2_v1: 1,
v2: B {
v1: 2,
v2: 3,
},
};
let a = econf::load(a, "PREFIX");
}
Here PREFIX_V2_V1 corresponds to both a.v2_v1 and a.v2.v1. In this case, econf prints warning through log facade and the value is loaded to both a.v2_v1 and a.v2.v1.
Skipping fields
Fields that do not implement LoadEnv or simply should not be loaded by econf can be skipped by adding the #[econf(skip)] helper attribute:
#[derive(LoadEnv)]
struct A {
x: bool,
#[econf(skip)]
y: u64, // will not be loaded by econf
}
License: MIT
9 Dec 16, 2022
34 Jan 7, 2023
536 Apr 16, 2023
162 Nov 21, 2022
7 Jan 2, 2023
2 Jul 23, 2022
4 Dec 18, 2022
47 Jul 23, 2022
5 Jul 18, 2023
2.1k Jan 3, 2023
13 Oct 31, 2022
11 Jun 15, 2023
1.3k Jan 8, 2023
19 Dec 4, 2023
8 Nov 10, 2022
82 Dec 31, 2022
5 Jul 20, 2022
1.3k Jan 4, 2023
4 Sep 3, 2022
1.4k Dec 27, 2022
16 Dec 17, 2022
1k Jan 5, 2023
46 Feb 19, 2023
6 Nov 13, 2022
409 Dec 25, 2022
2 Apr 19, 2022
4 Dec 28, 2021
2 Jan 4, 2022
65 Sep 8, 2022