Crate salak[−][src]
Expand description
Salak is a multi layered configuration loader and zero-boilerplate configuration parser, with many predefined sources.
About
salak
is a multi layered configuration loader with many predefined sources. Also it
is a zero-boilerplate configuration parser which provides an auto-derive procedure macro
to derive FromEnvironment
so that we can parse configuration structs without any additional codes.
Quick Start
A simple example of salak
:
use salak::*;
#[derive(Debug, FromEnvironment)]
#[salak(prefix = "config")]
struct Config {
#[salak(default = false)]
verbose: bool,
optional: Option<String>,
#[salak(name = "val")]
value: i64,
}
let env = Salak::builder()
.set("config.val", "2021")
.build()
.unwrap();
let config = env.get::<Config>().unwrap();
assert_eq!(2021, config.value);
assert_eq!(None, config.optional);
assert_eq!(false, config.verbose);
Features
Predefined Sources
Predefined sources has the following order, Salak
will find by sequence of these orders,
if the property with specified key is found at the current source, than return immediately. Otherwise,
it will search the next source.
- Random source provides a group of keys can return random values.
random.u8
random.u16
random.u32
random.u64
random.u128
random.usize
random.i8
random.i16
random.i32
random.i64
random.i128
random.isize
- Custom arguments source.
SalakBuilder::set()
can set a single kv, andSalakBuilder::set_args()
can set a group of kvs. - System environment source. Implemented by
source::system_environment
. - Profile specified file source, eg.
app-dev.toml
, supports reloading. - No profile file source, eg.
app.toml
, supports reloading. - Custom sources, which can register by
Salak::register()
.
Key Convention
Key is used for search configuration from Environment
, normally it is represented by string.
Key is a group of SubKey separated by dot(.
), and SubKey is a name or a name followed by index.
- SubKey Format (
[a-z][_a-z0-9]+(\[[0-9]+\])*
)a
a0
a_b
a[0]
a[0][0]
- Key Format (
SubKey(\.SubKey)*
)a
a.b
a.val[0]
a_b[0]
Value Placeholder Parsing
- Placeholder Format
${key}
=> Get value ofkey
.${key:default}
=> Get value ofkey
, if not exists returndefault
.
- Escape Format
\$\{key\}
=> Return${key}
.$
,\
,{
,}
must use escape format.
Attributes For Derive
salak
supports some attributes for automatically derive FromEnvironment
.
All attributes have format #[salak(..)]
, eg. #[salak(default = "default value")]
.
- Struct Header Attribute.
#[salak(prefix = "salak.application")]
, has this attr will auto implementPrefixedFromEnvironment
.
- Struct Field Attribute.
#[salak(default = "value")]
, this attr can specify default value.#[salak(name = "key")]
, this attr can specify property key, default convension is use field name.#[salak(desc = "Field Description")]
, this attr can be describe this property.
Reload Configuration
salak
supports reload configurations. Since in rust mutable
and alias can’t be used together, here we introduce a wrapper
wrapper::IORef
for updating values when reloading.
Resource Factory
Resource
defines a standard way to create instance. Factory
provides functions to initialize resource
and cache resource. Please refer to salak_factory for resource usage.
Feature ‘app’ should be open for this feature.
Modules
Macros
args
Generate AppInfo
from Cargo.toml.
Generate a struct which implement as a Service and provides methods to get reference from this struct.
Implement enum as EnumProperty
toml
Inline toml file as PropertySource
.
Structs
args
Application info.
Register dependent resources under same namespace.
Context for implementing Resource
, which can get dependent
resources. If the dependent resource is not initialized yet,
it will be initialized first.
Resource priority.
Resource builder.
Salak is a wrapper for salak env, all functions that this crate provides will be implemented on it.
A builder which can configure for how to build a salak env.
Context for implementing FromEnvironment
.
derive
Context for implementing description.
Enums
Raw property, it is a temprory representation of property, which can be either &str
or String
, or other values.
Property error for the whole crate.
Constants
Traits
This trait is automatically derived.
derive
Generate description for this object.
Any enum implements this trait is automatically implementing IsProperty
.
Environment defines interface for getting values, and reloading configurations.
app
Factory is a resource manager. It provides a group of functions to manage resource and their dependencies. Users may use factory to package all components of one logic unit, such as redis client configuration resource, together.
Parsing value from environment by SalakContext
.
Any object implements this trait is automatically implmenting crate::FromEnvironment
.
derive
FromEnvironment
with a configuration prefix, which is required by Environment::get()
.
Attribute #[salak(prefix = "salak.app")]
will implement this trait.
A property source defines how to load properties.
salak
has some predefined sources, user can
provide custom source by implementing this trait.
app
Resource can be initialized in a standard way by Salak
.
app
A simple resource without config & customizer. Service only care about how to get dependent resources, and do not register any dependent resource.
Derive Macros
derive
Auto derive FromEnvironment
for struct.
derive
and app
Auto derive Service
for struct.