Figment

Figment provides an Interpreter trait that allows you to control how Value types are converted into Rust types during the deserialization process. This is useful for implementing custom logic for boolean or numeric conversions.

There are two built-in implementations:

• DefaultInterpreter: Performs standard, strict conversions.
• LossyInterpreter: Attempts to perform 'lossy' conversions. For example, it can attempt to convert a string or other type into a boolean or number using lossy logic (to_bool_lossy or to_num_lossy). If the conversion fails, it falls back to the original value.

You can implement your own Interpreter to define custom behavior for interpret_as_bool and interpret_as_num.

use crate::value::{Interpreter, DefaultInterpreter, LossyInterpreter};

// Use the default behavior
let interpreter = DefaultInterpreter;

// Use lossy conversion behavior
let interpreter = LossyInterpreter;

Figment uses Profiles to allow different sets of values to coexist within the same source. By default, Figment uses the Default profile. You can switch profiles using .select(name) during extraction.

Built-in Profiles

• Default: The fallback profile used if no other profile is selected.
• Global: A special profile whose values supersede all other profiles (except when a subsequent provider is merged that contains its own global values).

Nested Providers

Some providers (like Toml or Json) can be configured as .nested(). This treats top-level keys in the source file as profile names (e.g., a [debug] section in TOML becomes the debug profile).

use figment::{Figment, providers::Toml};

// Using .nested() makes top-level keys act as profiles
let figment = Figment::new()
    .merge(Toml::file("Base.toml").nested());

// Extract using the 'debug' profile
let config = figment.select("debug").extract::<Config>()?;

The Serialized<T> provider allows you to source configuration values directly from any type T that implements serde::Serialize.

Unkeyed Data

If you do not provide a key, the serialized value T is expected to be a dictionary (map). It will be emitted directly at the root of the configured profile.

Keyed Data

If you provide a key (e.g., using .key("a.b.c")), the serialized value T can be any valid Value. Figment will automatically create nested dictionaries for every path component delimited by . in the key string. For example, a key of a.b.c results in a structure like { "a": { "b": { "c": T }}}.

Profiles

By default, data is emitted to Profile::Default. You can change this using .profile(P) where P implements Into<Profile>.

use figment::{Figment, providers::Serialized, util::map};
use serde::Deserialize;

#[derive(Debug, PartialEq, Deserialize)]
struct Config {
    numbers: Vec<usize>,
}

// Example: Unkeyed provider (expects a map/dict)
let map = map!["numbers" => &[1, 2, 3]];
let figment = Figment::from(Serialized::from(&map, "default"));
let config: Config = figment.extract().unwrap();
assert_eq!(config, Config { numbers: vec![1, 2, 3] });

A Provider is an abstraction that allows Figment to consume configuration from diverse sources (files, environment variables, network, etc.) through a unified interface.

Relationship with Figment

• Merging: When a provider is merged into a Figment, its data is combined with existing data. If the provider implements profile(), that profile is applied to the Figment during the merge.
• Metadata & Interpolation: Providers use Metadata to tell Figment how to represent the source. A key feature is the interpolater, which allows a provider to translate logical key paths (like database.host) into physical paths (like config/database/host.toml or https://api.com/database/host).

Data Structure

All providers must return data in the format Map<Profile, Dict>. This structure allows Figment to handle multiple configuration profiles (e.g., default, development, production) within a single provider's output.

A Data<F> provider sources configuration values from a file or a string using a specific format F (where F implements the Format trait).

Construction

Instead of constructing Data directly, you typically use the static methods provided by a format type (like Json, Toml, or Yaml). These methods return a Data<F> instance.

Unnested vs Nested Data

• Unnested (Default): The parsed content is emitted into a single profile (defaults to Profile::Default).
• Nested: By calling .nested(), the top-level keys of the source data are treated as profiles. This allows you to use Figment::select("profile_name") to extract specific sections of the configuration.

Metadata and Profiles

• Metadata: A file provider is named [FORMAT_NAME] file and includes the resolved file path. A string provider is named [FORMAT_NAME] source string.

// The `Format` trait must be in-scope to use its methods.
use figment::providers::{Format, Data, Json};

// These two are equivalent, except the former requires the explicit type.
let json = Data::<Json>::file("foo.json");
let json = Json::file("foo.json");

A Profile is a case-insensitive string used to identify and organize configuration layers. Figment uses profiles to distinguish between different configuration contexts (e.g., default, global, or custom profiles like staging).

Profiles are case-insensitive, meaning Profile::new("staging") is equal to Profile::new("STAGING").

Key characteristics:

• Default Profile: Profile::Default (the string "default").
• Global Profile: Profile::Global (the string "global").
• Custom Profiles: Any profile that is neither Default nor Global is considered custom (checked via .is_custom()).
• Case-Insensitivity: Comparisons and prefix checks are performed without regard to case.

use figment::Profile;

let profile = Profile::new("staging");
assert_eq!(profile, "staging");
assert_eq!(profile, "STAGING");

// Check if it is a custom profile
assert!(profile.is_custom());

// Built-in profiles
assert!(!Profile::Default.is_custom());
assert!(!Profile::Global.is_custom());

Figment is a configuration library based on two core concepts:

1. Providers: Types that implement the Provider trait, representing a single configuration source (e.g., a TOML file, environment variables, or a JSON object).
2. Figments: The Figment type, which acts as a container that combines multiple Providers using merge() or join(). A Figment is itself a Provider.

Combining Sources

• merge(provider): Values from the new provider replace values from previous providers if keys overlap.
• join(provider): Values from the new provider are added only if the key does not already exist (no replacement occurs).

Sources are read eagerly; they are processed immediately upon being merged or joined into a Figment.

use figment::{Figment, providers::{Toml, Env, Json}};

let figment = Figment::new()
    .merge(Toml::file("App.toml")) // Overwrites subsequent merges if keys match
    .merge(Env::prefixed("APP_")) // Overwrites if keys match
    .join(Json::file("App.json")); // Only fills holes; does not overwrite

A Tag is an opaque, unique identifier used to associate a configuration value with its Metadata and its Profile.

Key characteristics:

• Retrieval: You can obtain a Tag via the Tagged wrapper or by calling Value::tag().
• Metadata Access: Once you have a Tag, you can retrieve the corresponding metadata using Figment::get_metadata().
• Profile Access: You can determine which profile a value belongs to by calling Tag::profile().
• Default Tag: Tag::Default represents a tag that has no associated metadata and is associated with the Default profile.

use figment::value::Tag;

// Check if a tag is the default tag
assert!(Tag::Default.is_default());

// Check the profile associated with a tag
// Returns Some(Profile::Default) for a default tag
assert_eq!(Tag::Default.profile(), Some(figment::Profile::Default));