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 LoadEnv;
let a = A ;
println!;
let a = load;
println!;
In this example,
PREFIX_X
is loaded tox
PREFIX_Y
is 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
,HashMap
and 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.
Enums
Since v0.3.0, econf requires enums to implement FromStr trait. Without this implementation, your program will fail to compile. While you can write the FromStr
implementation manually, you can alternatively use strum crate to automatically generate it. strum
provides several useful features, making it a generally recommended choice. See econf/examples/strum.rs for example code.
use LoadEnv;
Nesting
Nested structs are supported.
let a = A ;
let a = load;
In this example,
PREFIX_V1
is loaded toa.v1
PREFIX_V2_V1
is loaded toa.v2.v1
PREFIX_V2_V2
is 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,
let a = A ;
let a = load;
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:
Renaming fields
Load a field with the given name instead of its Rust's field name. This is helpful if the environment variable name and Rust's field name don't match:
License: MIT