viperus
̶g̶o̶ rust configuration with fangs!
viperus is an (in)complete configuration solution for Rust applications. inspired heavly inspired by the wonderful go package https://github.com/spf13/viper use at your own risk. ;-)
no Go projects h̶a̶s̶ ̶b̶e̶e̶n̶ ̶h̶a̶r̶m̶e̶d̶ are built using Viperus :-)
Recent Changes
- 0.1.10 adapters load cfg data from std:io::Read
- 0.1.9 optional automatic prefixed environment variable mapping,basic error propagation, cleaned dependency
- 0.1.8 add cache feature, modular "featurization"
- 0.1.5 add watch_all files with autoreload
- 0.1.4 add format : java properties files
- 0.1.3 better clap args : default values
- 0.1.2 relaod config from files
- 0.1.1 fixes dcs
- 0.1.0 first release
What is Viperus?
a package that handles some types of configuration modes with differente formats,cli params and environment . It supports:
- setting defaults
- reading from JSON, TOML, YAML, dotenv file ,java properties config files
- reading from environment variables
- reading from Clap command line flags
- setting explicit values
- reload of all files
- whatch config files and reolad all in something changes
- caching
Why Viperus?
beacuse I was migrating some go apps... and a was missing Viper ease of use :-)
Viperus uses the following decreasing precedence order.
- explicit call to
add
- clap flag
- config
- environment variables
- default
Viperus merge configuration from toml,dotenv,json,yaml files and clap options in sigle typed hash structure. with defaults, and type checking
you can create a stand alone Viperus object or "enjoy" a global instance ( thread safe protected with a mutex) via shadow functions load_file|get|add|load_clap that are routed to the static instance.
//add a dotenv config file , keys defautls di env variables
load_file.unwrap;
//add another file
load_file.unwrap;
//automatically map env variable staring with "TEST_" to config keys
set_env_prefix;
automatic_env;
//watch the config and autoreload if something changes
watch_all;
//enable caching -- file reload invalidates cache
// cache i thread safe for the global "static" instance
cache;
let ok=.unwrap;
by the way , Yes I konw globals are evil. but as I was inspired by the go package viper.... if you dislike globals you can opt-out disabling in your cargo.toml the feature "global".
caching
you can enable caching for a x4 speed-up. cache is thread safe only when used with the global instance taht is behing a arc mutex
;
cache
reloading files with an excplicit viperus::reload()
,
or for effect of a file change when file watch is active invalidates the cache.
logging/debug
the crate uses log
facade , and test the env_logger
you can set the env variable to RUST_LOG=viperus=[DEBUG LEVEL] with
[DEBUG LEVEL] = info|warning|debug or RUST_LOG=[DEBUG LEVEL]
features
the crate in "featurized" with the features enabled by default
- feature = "fmt-[format]" with [format] in 'json,end,toml,yaml,javaproperties,clap' enabling the relative format
- feature ="global" enabling the global tread safe configuration
- feature ="watch" enabling the automatic file reload wirh prerequisite feature=global
- feature ="cache" aneglig caching
single featues could be activated in a selective way via cargo.toml
[]
= "0.1.8"
# do not include the default features, and optionally
= false
# cherry-pick individual features
= ["global", "cache","watch","fmt-yaml"]
Examples
you can find some integration tests in the test dir and also in the example folder you can run example with cargo:
cargo run --example cli-clap-yaml --
cargo run --example cli-clap-yaml -- -u http://nowhere/api/v1
the first run print the value from the example.yaml file the second from the cli arg
let matches = new
.arg
.get_matches;
let mut v = new;
//enable clap
v.load_clap;
//enable a yaml json toml file
v.load_file.unwrap;
v.load_file.unwrap;
v.load_file.unwrap;
v.load_file.unwrap;
//link the "v" clap option to the key "verbose"
v.bond_clap;
//add an explicit overload
v.add;
debug!;
//get a typed key
let s: &str = v.get.unwrap;
assert_eq!;
//get a bool from configs or app args
let fVerbose=v..unwrap;
assert_eq!;
Todo
- remote configs
- better error propagation
- stabilize api
- improve documentation and examples
- improve my rust karma