Crate salak

Salak is a multi layered configuration loader and zero-boilerplate configuration parser, with many predefined sources.

1. About
2. Quick Start
3. Features
   • Predefined Sources
   • Key Convention
   • Value Placeholder Parsing
   • Attributes For Derive
   • Reload Configuration
   • Resource Factory

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.

1. 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
2. Custom arguments source. SalakBuilder::set() can set a single kv, and SalakBuilder::set_args() can set a group of kvs.
3. System environment source. Implemented by source::system_environment.
4. Profile specified file source, eg. app-dev.toml, supports reloading.
5. No profile file source, eg. app.toml, supports reloading.
6. 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.

1. SubKey Format ([a-z][_a-z0-9]+(\[[0-9]+\])*)
   • a
   • a0
   • a_b
   • a[0]
   • a[0][0]
2. Key Format (SubKey(\.SubKey)*)
   • a
   • a.b
   • a.val[0]
   • a_b[0]

Value Placeholder Parsing

1. Placeholder Format
   • ${key} => Get value of key.
   • ${key:default} => Get value of key, if not exists return default.
2. 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")].

1. Struct Header Attribute.
   • #[salak(prefix = "salak.application")], has this attr will auto implement PrefixedFromEnvironment.
2. 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

source	Salak sources.
wrapper	Salak wrapper for configuration parsing.

Macros

app_info	args Generate AppInfo from Cargo.toml.
impl_enum_property	Implement enum as EnumProperty
inline_toml	toml Inline toml file as PropertySource.

Structs

AppInfo	args Application info.
ResourceBuilder	app Resource builder.
Salak	Salak is a wrapper for salak env, all functions that this crate provides will be implemented on it.
SalakBuilder	A builder which can configure for how to build a salak env.
SalakContext	Context for implementing FromEnvironment.
SalakDescContext	derive Context for implementing description.

Enums

Property	Raw property, it is a temprory representation of property, which can be either &str or String, or other values.
PropertyError	Property error for the whole crate.

Traits

AutoDeriveFromEnvironment	derive This trait is automatically derived.
DescFromEnvironment	derive Generate description for this object.
EnumProperty	Any enum implements this trait is automatically implementing IsProperty.
Environment	Environment defines interface for getting values, and reloading configurations.
Factory	app Factory is a resource manager for initializing resource or getting resource from cache.
FromEnvironment	Parsing value from environment by SalakContext.
IsProperty	Any object implements this trait is automatically implmenting crate::FromEnvironment.
PrefixedFromEnvironment	derive FromEnvironment with a configuration prefix, which is required by Environment::get(). Attribute #[salak(prefix = "salak.app")] will implement this trait.
PropertySource	A property source defines how to load properties. salak has some predefined sources, user can provide custom source by implementing this trait.
Resource	app Resource can be initialized in a standard way by Salak.

Derive Macros

FromEnvironment

derive Auto derive FromEnvironment for struct.