Crate scuffle_settings

Source
Expand description

A crate designed to provide a simple interface to load and manage settings.

This crate is a wrapper around the config crate and clap crate to provide a simple interface to load and manage settings.

§How to use this

§With scuffle_bootstrap

// Define a config struct like this
// You can use all of the serde attributes to customize the deserialization
#[derive(serde_derive::Deserialize)]
struct MyConfig {
    some_setting: String,
    #[serde(default)]
    some_other_setting: i32,
}

// Implement scuffle_boostrap::ConfigParser for the config struct like this
scuffle_settings::bootstrap!(MyConfig);

/// Our global state
struct Global;

impl scuffle_bootstrap::global::Global for Global {
    type Config = MyConfig;

    async fn init(config: MyConfig) -> anyhow::Result<Arc<Self>> {
        // Here you now have access to the config
        Ok(Arc::new(Self))
    }
}

§Without scuffle_bootstrap

// Define a config struct like this
// You can use all of the serde attributes to customize the deserialization
#[derive(serde_derive::Deserialize)]
struct MyConfig {
    some_setting: String,
    #[serde(default)]
    some_other_setting: i32,
}

// Parsing options
let options = scuffle_settings::Options {
    env_prefix: Some("MY_APP"),
    ..Default::default()
};
// Parse the settings
let settings: MyConfig = scuffle_settings::parse_settings(options)?;

See Options for more information on how to customize parsing.

§Templates

If the templates feature is enabled, the parser will attempt to render the configuration file as a jinja template before processing it.

All environment variables set during execution will be available under the env variable inside the file.

Example TOML file:

some_setting = "${{ env.MY_APP_SECRET }}"

Use ${{ and }} for variables, {% and %} for blocks and {# and #} for comments.

§Command Line Interface

The following options are available for the CLI:

  • --config or -c

    Path to a configuration file. This option can be used multiple times to load multiple files.

  • --override or -o

    Provide an override for a configuration value, in the format KEY=VALUE.

§Feature Flags

§Format Feature Flags

  • toml: Enables TOML support
  • yaml: Enables YAML support
  • json: Enables JSON support
  • json5: Enables JSON5 support
  • ron: Enables RON support
  • ini: Enables INI support

§Status

This crate is currently under development and is not yet stable.

Unit tests are not yet fully implemented. Use at your own risk.

§License

This project is licensed under the MIT or Apache-2.0 license. You can choose between one of them if you use this work.

SPDX-License-Identifier: MIT OR Apache-2.0

Macros§

bootstrap
This macro can be used to integrate with the scuffle_bootstrap ecosystem.
cli
A macro to create a CLI struct

Structs§

Cli
A struct used to define how the CLI should be generated
Options
Options to customize parsing

Enums§

SettingsError
An error that can occur when parsing settings.

Functions§

parse_settings
Parse settings using the given options.