config-rs

config-rs is a layered configuration system for Rust applications designed with support for 12-factor application principles. It allows you to build configuration by layering different sources, such as setting defaults, programmatically overriding values, reading from various file formats, and pulling from environment variables.

Key capabilities:

• Layered Configuration: Combine defaults, explicit values, files, and environment variables.
• Loosely Typed: Values can be read into any supported type that has a reasonable conversion.
• Nested Access: Access nested fields using a subset of JSONPath, supporting child (redis.port) and subscript (databases[0].name) operators.
• Read-Only: Note that this library is designed for reading configuration; it cannot be used to write changed values back to configuration files.

To use specific file formats with config-rs, you must enable the corresponding feature flags in your Cargo.toml. By default, only a minimal set of features may be active. Enable the following flags to add support for specific formats:

• ini: Support for INI files
• json: Support for JSON files
• yaml: Support for YAML files
• toml: Support for TOML files
• ron: Support for RON files
• json5: Support for JSON5 files
• corn: Support for Corn files

The Config system allows merging several types of sources to build a final configuration object. Supported sources include:

• Environment variables: Using the Environment source.
• String literals: Using FileSourceString in well-known formats.
• Files: Using FileSourceFile in well-known formats or custom formats defined via the Format trait.
• Other Config instances: Merging an existing Config object.
• Manual overrides: Using ConfigBuilder::set_override for programmatic control.

The Environment struct allows you to collect environment variables into your configuration hierarchy. You can use it to map environment variables (like APP_DATABASE_URL) to configuration keys (like database.url).

Key features include:

• Prefixing: Limit the source to variables starting with a specific prefix (e.g., APP_).
• Separators: Define how nested keys are represented (e.g., using _ to represent . in configuration).
• Type Parsing: Automatically attempt to parse values as booleans, integers, or floats.
• Case Conversion: Transform keys to specific casing (e.g., kebab-case) using the convert-case feature.

The ConfigBuilder allows you to register multiple configuration sources in a specific order to build a final Config object. The layering order is:

1. Defaults: Loaded first via set_default. These can be overwritten by any other source.
2. Sources: Loaded in the order they are added via add_source or add_async_source. These can be external files, environment variables, etc.
3. Overrides: Loaded last via set_override. These cannot be overwritten by any other source.

Note that adding sources does not perform I/O; I/O only occurs when build() or build_cloned() is called.

Instead of relying on the actual system environment variables, you can provide a custom map to the Environment source. This is useful for unit testing configuration logic without side effects.

# use config::{Environment, Config};
# use serde::Deserialize;
# use std::collections::HashMap;
# use std::convert::TryInto;
# use config::error::Result;

#[test]
fn test_config() -> Result<(), config::ConfigError> {
  #[derive(Clone, Debug, Deserialize)]
  struct MyConfig {
    pub my_string: String,
  }

  let mut env = HashMap::new();
  env.insert("MY_STRING".into(), "my-value".into());

  let source = Environment::default()
    .source(Some(env));

  let config: MyConfig = Config::builder()
    .add_source(source)
    .build()?
    .try_into()?;

  assert_eq!(config.my_string, "my-value");

  Ok(())
}

You can create a File source using a file path or a base name.

• Use File::new(name, format) to create a required file source with a specific format.
• Use File::with_name(base_name) to create a required file source that attempts to automatically discover the format based on registered file extensions.
• Use From<&Path> or From<PathBuf> to convert an existing path into a File<FileSourceFile, FileFormat> source.

You can explicitly set values in the builder using keys (which are parsed as Expression).

• set_default(key, value): Sets a value that can be overwritten by any subsequent source or override.
• set_override(key, value): Sets a value that will not be altered by any defaults, sources, or async sources.
• set_override_option(key, value): Sets an override only if the provided value is Some.

When building a File source, you can chain methods to customize its behavior:

• .format(format): Explicitly sets the file format (must implement FileStoredFormat).
• .required(bool): Sets whether the configuration building process should error if the file is missing. If set to false, a missing file will result in an empty configuration map instead of an error.