Crate salak

A layered configuration loader with zero-boilerplate configuration management.

1. About
2. Features
3. Placeholder
4. Key Convension
5. Cargo Features
   1. Default features
   2. Optional features
6. Quick Example

About

salak is a rust version of layered configuration loader inspired by spring-boot. salak provide an Environment structure which load properties from various PropertySources. Any structure which impmement FromEnvironment can get from Environment by a key. Feature enable_derive provide rust attributes for auto derive FromEnvironment.

Features

Below are a few of the features which salak supports.

• Auto mapping properties into configuration struct.
  • #[salak(default="value")] set default value.
  • #[salak(name="key")] rename property key.
  • #[salak(prefix="salak.database")] set prefix.
• ** Supports load properties from various sources **
  • Support following random property key.
    • random.u8
    • random.u16
    • random.u32
    • random.i8
    • random.i16
    • random.i32
    • random.i64
  • Load properties from command line arguments.
  • Load properties from system environment.
  • Load properties from toml config file.
  • Load properties from yaml config file.
  • Easy to add a new property source.
• Supports profile(develop/production) based configuration.
• Supports placeholder resolve.
• Supports reload configurations.
• Supports factory builder.

Placeholder

• ${key:default} means get value of key, if not exists then return default.
• ${key} means get value of key, if not exists then return PropertyError::NotFound(_).
• \$\{key\} means escape to ${key}.

Key Convension

• a.b.c is a normal key separated by dot(.).
• a.b[0], a.b[1], a.b[2]… is a group of keys with arrays.

Cargo Features

Default features

1. enable_log, enable log record if enabled.
2. enable_toml, enable toml support.
3. enable_derive, enable auto derive FromEnvironment for struts.

Optional features

1. enable_pico, enable default command line arguments parsing by pico-args.
2. enable_clap, enable default command line arguments parsing by clap.
3. enable_yaml, enable yaml support.
4. enable_rand, enable random value support.

Quick Example

use salak::*;

#[derive(FromEnvironment, Debug)]
pub struct SslConfig {
    key: String,
    pem: String,
}

#[derive(FromEnvironment, Debug)]
#[salak(prefix = "database")]
pub struct DatabaseConfig {
  url: String,
  #[salak(default = "salak")]
  username: String,
  password: Option<String>,
  description: String,
  #[salak(name="ssl")]
  ssl_config: Option<SslConfig>,  
}

std::env::set_var("database.url", "localhost:5432");
std::env::set_var("database.description", "\\$\\{Hello\\}");
let env = Salak::new()
   .with_default_args(auto_read_sys_args_param!()) // This line need enable feature `enable_pico`.
    .add_default::<DatabaseConfig>()
    .add_default_source(inline_toml!("app.toml"))
   .build();

match env.load_config::<DatabaseConfig>() {
    Ok(val) => println!("{:?}", val),
    Err(e) => println!("{}", e),
}

// Output: DatabaseConfig {
//  url: "localhost:5432",
//  username: "salak",
//  password: None,
//  description: "${Hello}",
//  ssl_config: None,
// }

Macros

auto_read_sys_args_param	enable_clap or enable_pico Auto generate SysArgsParam from Cargo.toml.
inline_toml	enable_toml Inline toml file as PropertySource.

Structs

FacRef	Factory smart pointer reference.
FactoryContext	Factory Context.
MapPropertySource	A simple implementation of PropertySource.
PlaceholderResolver	An implementation of Environment that can resolve placeholder for values.
Salak	A wrapper for Environment, which can hide the implementation details.
SalakBuilder	Salak builder.
SourceRegistry	An implementation of Environment for registering PropertySource.
SysArgsParam	enable_clap or enable_pico Command line help info, such as name, version, author, etc.
SysEnvPropertySource	PropertySource read properties from system environment.
Toml	enable_toml PropertySource read properties from toml file.
Yaml	enable_yaml PropertySource read properties from yaml file.

Enums

FactoryScope	Factory builder scope.
Property	Raw property.
PropertyError	Property Error
SysArgsMode	Command line arguments parser mode.

Traits

Environment	An environment for getting properties with mutiple PropertySources, placeholder resolve and other features.
Factory	A factory.
FromEnvironment	Convert from Environment.
FromFactory	Build object from Factory
FromProperty	Convert from Property.
IntoProperty	Convert to Property.
PropertySource	An abstract source loader from various sources, such as command line arguments, system environment, files, etc.

Derive Macros

FromEnvironment

enable_derive Auto derive FromEnvironment for struct.