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_infoargs

Generate AppInfo from Cargo.toml.

generate_service

Generate a struct which implement as a Service and provides methods to get reference from this struct.

impl_enum_property

Implement enum as EnumProperty

inline_tomltoml

Inline toml file as PropertySource.

Structs

AppInfoargs

Application info.

FactoryBuilderapp

Register dependent resources under same namespace.

FactoryContextapp

Context for implementing Resource, which can get dependent resources. If the dependent resource is not initialized yet, it will be initialized first.

Ordered

Resource priority.

ResourceBuilderapp

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.

SalakDescContextderive

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.

Constants

PRIORITY_HIGHapp

High prioritt.

PRIORITY_HIGHESTapp

Highest prioritt.

PRIORITY_LOWapp

Low priority.

PRIORITY_LOWESTapp

Lowest priority.

PRIORITY_NORMALapp

Normal priority.

Traits

AutoDeriveFromEnvironmentderive

This trait is automatically derived.

DescFromEnvironmentderive

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.

Factoryapp

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.

FromEnvironment

Parsing value from environment by SalakContext.

IsProperty

Any object implements this trait is automatically implmenting crate::FromEnvironment.

PrefixedFromEnvironmentderive

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.

Resourceapp

Resource can be initialized in a standard way by Salak.

Serviceapp

A simple resource without config & customizer. Service only care about how to get dependent resources, and do not register any dependent resource.

Derive Macros

FromEnvironmentderive

Auto derive FromEnvironment for struct.

Servicederive and app

Auto derive Service for struct.