Crate salak[][src]

Expand description

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

  1. About
  2. Quick Start
  3. Features


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")
let config = env.get::<Config>().unwrap();
assert_eq!(2021, config.value);
assert_eq!(None, config.optional);
assert_eq!(false, config.verbose);


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.
  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.


Salak sources.

Salak wrapper for configuration parsing.


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

Inline toml file as PropertySource.


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.

Context for implementing description.


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.


High prioritt.

Highest prioritt.

Low priority.

Lowest priority.

Normal priority.


This trait is automatically derived.

Generate description for this object.

Any enum implements this trait is automatically implementing IsProperty.

Environment defines interface for getting values, and reloading configurations.

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.

FromEnvironment with a configuration prefix, which is required by Environment::get(). Attribute #[salak(prefix = "")] 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.

Resource can be initialized in a standard way by Salak.

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

Derive Macros

Auto derive FromEnvironment for struct.

Servicederive and app

Auto derive Service for struct.