### Example: Setting Profile for Toml Provider

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/format-providers.md

Demonstrates how to chain the `file` and `profile` methods on a Toml provider.

```rust
use figment2::{Figment, Profile, providers::{Format, Toml}};

let provider = Toml::file("config.toml")
    .profile(Profile::new("production"));
```

--------------------------------

### Complete Figment2 Configuration Example

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/format-providers.md

Demonstrates loading configuration from a TOML file, environment variables, and selecting a specific profile.

```rust
use serde::Deserialize;
use figment2::{Figment, Profile, providers::{Format, Toml, Env}};

#[derive(Deserialize)]
struct Config {
    name: String,
    port: u16,
    debug: Option<bool>,
}

impl Config {
    fn load() -> figment2::error::Result<Config> {
        Figment::new()
            .merge(Toml::file("config.toml").nested())
            .merge(Env::prefixed("APP_"))
            .select(Profile::new("production"))
            .extract()
    }
}

let config = Config::load()?;
```

--------------------------------

### Example: Enabling Nesting for Toml Provider

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/format-providers.md

Illustrates enabling nesting for a Toml provider and selecting a specific profile.

```rust
use figment2::{Figment, providers::{Format, Toml}};

// Config.toml has [default], [staging], [production] sections
let figment = Figment::new()
    .merge(Toml::file("Config.toml").nested());

let config = figment.select("staging").extract()?;
```

--------------------------------

### Implementing metadata() Method

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/provider.md

Example implementation of the required `metadata` method for a custom provider. This method returns metadata identifying the provider and its sources.

```rust
use figment2::{Metadata, Provider};

struct MyProvider;

impl Provider for MyProvider {
    fn metadata(&self) -> Metadata {
        Metadata::named("My Provider Source")
    }
    
    fn data(&self) -> figment2::error::Result<figment2::value::Map<figment2::Profile, figment2::value::Dict>> {
        todo!()
    }
}
```

--------------------------------

### Implementing profile() Method

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/provider.md

Example implementation of the optional `profile` method for a custom provider. This method can optionally return a profile to be set on the Figment.

```rust
use figment2::{Profile, Provider};

impl Provider for MyProvider {
    fn profile(&self) -> Option<Profile> {
        Some(Profile::new("custom"))
    }
    
    // ... other methods
}
```

--------------------------------

### Example: Setting File Requirement for Toml Provider

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/format-providers.md

Shows how to configure a Toml provider to require the existence of its source file.

```rust
use figment2::{Figment, providers::{Format, Toml}};

let provider = Toml::file("config.toml").required(true);
```

--------------------------------

### Complete Value Example: Creation, Finding, and Conversion

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/value.md

Demonstrates the creation of a Value::Dict, finding specific values within it, and converting them to their expected types. This covers common operations when working with dictionary-like values.

```rust
use figment2::value::Value;

// Create a dictionary
let mut dict = figment2::value::Dict::new();
dict.insert("name".into(), Value::String("MyApp".into()));
dict.insert("port".into(), Value::Num(8080.into()));

let config = Value::Dict(dict);

// Find values
assert_eq!(config.find("name"), Some(&Value::String("MyApp".into())));

// Convert
if let Some(str_val) = config.as_dict().and_then(|d| d.get("name")) {
    println!("Name: {}", str_val.as_str().unwrap_or(""));
}
```

--------------------------------

### Nested Environment Variables Example

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/env-provider.md

Demonstrates how environment variable names with double underscores are converted into nested key paths. This is useful for organizing configuration settings.

```shell
DATABASE__HOST=localhost → database.host = "localhost"
DATABASE__PORT=5432      → database.port = 5432
```

--------------------------------

### Load Environment Variables with Prefix and Split

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/env-provider.md

This example demonstrates how to use the `Env` provider with a prefix and a split character. It loads environment variables prefixed with `MY_APP_` and splits them by `_` to map to the `Config` struct fields. Ensure environment variables like `MY_APP_DATABASE_HOST`, `MY_APP_DATABASE_PORT`, and `MY_APP_DEBUG_ENABLED` are set.

```rust
use serde::Deserialize;
use figment2::{Figment, providers::Env};

#[derive(Deserialize)]
struct Config {
    database_host: String,
    database_port: u16,
    debug_enabled: bool,
}

// Read from MY_APP_DATABASE_HOST, MY_APP_DATABASE_PORT, etc.
let config: Config = Figment::new()
    .merge(Env::prefixed("MY_APP_").split('_'))
    .extract()?;
```

--------------------------------

### Implementing data() Method

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/provider.md

Example implementation of the required `data` method for a custom provider. This method returns configuration data as a map of profiles to dictionaries.

```rust
use figment2::{Provider, Metadata, Profile, error::Result, value::{Map, Dict}};

impl Provider for MyProvider {
    fn metadata(&self) -> Metadata {
        Metadata::named("Example")
    }

    fn data(&self) -> Result<Map<Profile, Dict>> {
        let mut dict = Dict::new();
        dict.insert("key".into(), "value".into());
        
        let mut map = Map::new();
        map.insert(Profile::Default, dict);
        Ok(map)
    }
}
```

--------------------------------

### Custom Provider Implementation

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/configuration.md

Provides an example of implementing the `Provider` trait to create a custom configuration source. This custom provider defines its own metadata and data.

```rust
use figment2::{Provider, Metadata, Profile, error::Result, value::{Map, Dict}};

struct MyProvider;

impl Provider for MyProvider {
    fn metadata(&self) -> Metadata {
        Metadata::named("My Provider")
    }

    fn data(&self) -> Result<Map<Profile, Dict>> {
        let mut dict = Dict::new();
        dict.insert("key".into(), "value".into());
        
        let mut map = Map::new();
        map.insert(Profile::Default, dict);
        Ok(map)
    }
}
```

--------------------------------

### Handling a Single Error

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/error.md

Shows a basic example of extracting configuration data and handling potential errors using a `match` statement.

```rust
use figment2::Figment;

match Figment::new().extract::<MyConfig>() {
    Ok(config) => println!("Loaded: {:?}", config),
    Err(e) => eprintln!("Error: {}", e),
}
```

--------------------------------

### Create Figment from a Provider

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/figment.md

Use `Figment::from()` to initialize a Figment with an initial provider. This is convenient when you have a single starting source for your configuration.

```rust
use figment2::{Figment, providers::Env};

let figment = Figment::from(Env::raw());
assert_eq!(figment.metadata().count(), 1);
```

--------------------------------

### Example Error Message

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/error.md

A concrete example of an error message formatted according to the defined display structure, showing a type mismatch.

```text
invalid type: found sequence, expected u16: `staging.port` in TOML file Config.toml
```

--------------------------------

### Create a New Figment Instance

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/figment.md

Use `Figment::new()` to create an empty Figment with the default profile. This is useful for starting a new configuration setup.

```rust
use figment2::Figment;

let figment = Figment::new();
assert_eq!(figment.profile(), "default");
```

--------------------------------

### Iterate Over All Metadata

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/figment.md

Use the `metadata` method to get an iterator over all metadata entries in the configuration. This is useful for inspecting all metadata without needing a specific key or tag.

```rust
pub fn metadata(&self) -> impl Iterator<Item = &Metadata>
```

--------------------------------

### Get Current Figment Profile

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/figment.md

Retrieves a reference to the currently selected profile within the Figment configuration.

```rust
pub fn profile(&self) -> &Profile
```

--------------------------------

### Create Profile with `new()`

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/profile.md

Shows how to construct a new `Profile` instance using the `new()` method with a given name. Verifies case-insensitive equality.

```rust
use figment2::Profile;

let profile = Profile::new("staging");
assert_eq!(profile, "staging");
assert_eq!(profile, "STAGING"); // Case-insensitive
```

--------------------------------

### Multi-Source Configuration Loading

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/configuration.md

Shows how to combine multiple configuration providers (Serialized, Toml, Env, Json) with different strategies and select a profile based on an environment variable.

```rust
let config: Config = Figment::new()
    .merge(Serialized::defaults(Config::default()))
    .merge(Toml::file("config.toml").nested())
    .merge(Env::prefixed("APP_"))
    .join(Json::file("overrides.json"))
    .select(Profile::from_env("APP_ENV").unwrap_or_default())
    .extract()?;
```

--------------------------------

### Create Toml Configuration Provider

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/INDEX.md

Instantiate a Toml configuration provider to read from a TOML file. This is the first step in loading TOML configurations.

```rust
Toml::file("config.toml")
```

--------------------------------

### Basic Configuration Loading

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/REFERENCE.md

Load configuration from a TOML file and environment variables. Requires `serde` and `figment2` with `toml` feature.

```rust
use serde::Deserialize;
use figment2::{Figment, providers::{Format, Toml, Env}};

#[derive(Deserialize)]
struct Config {
    name: String,
    port: u16,
}

fn main() -> figment2::Result<()> {
    let config: Config = Figment::new()
        .merge(Toml::file("config.toml"))
        .merge(Env::prefixed("APP_"))
        .extract()?;
    
    println!("Running {} on port {}", config.name, config.port);
    Ok(())
}
```

--------------------------------

### Data Provider from File

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/format-providers.md

Creates a Data provider that sources configuration from a file. Relative paths are searched in current and parent directories.

```rust
pub fn file<P: AsRef<Path>>(path: P) -> Self
```

--------------------------------

### Metadata Interpolation for Error Messages

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/provider.md

Custom interpolation can be used to transform key paths for error messages. This example shows how the `Env` provider might format interpolated keys.

```rust
metadata.interpolater(|profile, keys| {
    let uppercase = keys.iter()
        .map(|k| k.to_ascii_uppercase())
        .collect::<Vec<_>>();
    format!("{}_{}", prefix, uppercase.join("_"))
})
```

--------------------------------

### Load TOML configuration from a file

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/configuration.md

Use the `Toml` provider to load configuration from a TOML file. Ensure the 'toml' feature is enabled.

```rust
use figment2::providers::{Format, Toml};

let config = Figment::new()
    .merge(Toml::file("config.toml"))
    .extract::<MyConfig>()?;
```

--------------------------------

### Create File Source using `Source::file`

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/metadata.md

This method creates a `Source::File` variant, specifying the path to the configuration file. The path can be any type that can be converted into `PathBuf`.

```rust
use figment2::Source;

let source = Source::file("config.toml");
```

--------------------------------

### Load Configuration from Multiple Sources

Source: https://github.com/lmmx/figment2/blob/master/README.md

This snippet demonstrates loading configuration from a TOML file, environment variables, and a JSON file. It uses `serde` for deserialization into a `Config` struct. Ensure the necessary features like 'toml' are enabled in Cargo.toml.

```rust
use serde::Deserialize;

use figment2::{Figment, providers::{Format, Toml, Json, Env}};

#[derive(Deserialize)]
struct Package {
    name: String,
    authors: Vec<String>,
    publish: Option<bool>,
    // ... and so on ...
}

#[derive(Deserialize)]
struct Config {
    package: Package,
    rustc: Option<String>,
    // ... and so on ...
}

let config: Config = Figment::new()
    .merge(Toml::file("Cargo.toml"))
    .merge(Env::prefixed("CARGO_"))
    .merge(Env::raw().only(&["RUSTC", "RUSTDOC"]))
    .join(Json::file("Cargo.json"))
    .extract()?;
```

--------------------------------

### Split Env Variable Names

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/env-provider.md

The `split` method provides a convenient way to replace a specified character with a dot (`.`) in environment variable names, facilitating the creation of nested configuration keys. For example, `DATABASE__HOST` can become `database.host` by splitting on `'_'`.

```rust
use figment2::{Figment, providers::Env};

// DATABASE__HOST becomes database.host
let env = Env::raw().split('_');
```

--------------------------------

### Constructor: Metadata::from

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/metadata.md

Creates metadata with a given name and source. Use when both name and source information are available.

```rust
#[inline(always)]
pub fn from<N, S>(name: N, source: S) -> Self
    where N: Into<Cow<'static, str>>, S: Into<Source>
```

```rust
use figment2::Metadata;

let metadata = Metadata::from("AWS Config Store", "path/to/value");
assert_eq!(metadata.name, "AWS Config Store");
assert_eq!(metadata.source.unwrap().custom(), Some("path/to/value"));
```

--------------------------------

### Figment2 Library API Documentation

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/COMPLETION_SUMMARY.txt

This section outlines the structure and content of the generated API documentation for the Figment2 library. It details the types of information available, including exported APIs, method signatures, parameter and return types, configuration options, and examples.

```APIDOC
## Figment2 Library Documentation Structure

This documentation provides a detailed reference for the Figment2 Rust library (v0.11.5).

### Documentation Hierarchy:
1.  **README.md**: Provides an overview and starting point.
2.  **INDEX.md**: For quick lookups of types and methods.
3.  **REFERENCE.md**: Explains architecture and common patterns.
4.  **types.md**: Contains reference definitions for all types.
5.  **configuration.md**: Details features, options, and configuration.
6.  **api-reference/***: Contains detailed method documentation, typically organized by type.

### Content Verification:
-   Focuses on factual reference material, excluding marketing or tutorials.
-   Examples are based on actual usage patterns.
-   Only documented explicit behavior is included; no inferred behavior.
-   Parameter and return types are exact matches from the source code.
-   Configuration options, feature gates, source file locations, type aliases, trait implementations, default values, and error handling patterns are fully documented.

### Usage Guidance:
-   **New Users**: Start with README.md, then REFERENCE.md for overview and quick start.
-   **API Reference**: Use INDEX.md or types.md to find types, then navigate to `api-reference/` for detailed method signatures and examples.
-   **Integration**: Consult REFERENCE.md for patterns, configuration.md for features, types.md for type definitions, and `api-reference/` for method details.

### Key Information Provided:
-   Complete API coverage of exported types and methods.
-   Precise parameter and return type documentation.
-   Configuration and feature documentation.
-   Extensive code examples (50+).
-   Detailed documentation for 150+ methods and functions.
-   Cross-linked navigation for easy exploration.
-   Architecture and pattern documentation.
```

--------------------------------

### Preserving Error Context in Nested Deserialization

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/error.md

This Rust snippet demonstrates how Figment preserves the full error path and metadata when deserializing nested structures. It shows an example where a configuration value is invalid, and the resulting error path correctly identifies the location within the nested structs.

```rust
use serde::Deserialize;
use figment2::{Figment, providers::{Format, Toml}};

#[derive(Deserialize)]
struct Database {
    pool: Pool,
}

#[derive(Deserialize)]
struct Pool {
    max_connections: u16,
}

// If max_connections is invalid in the TOML file:
// Error path will be: ["database", "pool", "max_connections"]
// Error metadata will include the TOML file name

```

--------------------------------

### Load YAML configuration from a file

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/configuration.md

Use the `Yaml` provider to load configuration from a YAML file. Ensure the 'yaml' feature is enabled.

```rust
use figment2::providers::{Format, Yaml};

let config = Figment::new()
    .merge(Yaml::file("config.yml"))
    .extract::<MyConfig>()?;
```

--------------------------------

### Implement Custom Configuration Provider

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/INDEX.md

Implement the `Provider` trait to create custom configuration sources. Required methods include `metadata()` and `data()`. Optional methods like `profile()` can also be implemented.

```rust
impl Provider for MyProvider {
    fn metadata(&self) -> Metadata<'_> { ... }
    fn data(&self) -> Result<String, Error> { ... }
    // Optional: fn profile(&self, name: &str) -> Option<Self> { ... }
}
```

--------------------------------

### Profile Management in Rust

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/types.md

Illustrates how to define and select profiles for configuration management using `figment2::Profile`. Constants are used for predefined profiles.

```rust
use figment2::Profile;
use figment2::Figment;

const DEVELOPMENT: Profile = Profile::const_new("development");
const PRODUCTION: Profile = Profile::const_new("production");

let figment = Figment::new().select(PRODUCTION);
```

--------------------------------

### Data Provider from Exact File Path

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/format-providers.md

Creates a Data provider that sources configuration from a file at the exact specified path, without searching parent directories.

```rust
pub fn file_exact<P: AsRef<Path>>(path: P) -> Self
```

--------------------------------

### Profile Constructors

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/profile.md

Methods for creating new Profile instances.

```APIDOC
## Constructors

### `new(name: &str)`

Constructs a profile with the given name.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| name | `&str` | Yes | — | Profile name |

**Returns:** `Profile` - A new profile with the given name.

**Example:**
```rust
use figment2::Profile;

let profile = Profile::new("staging");
assert_eq!(profile, "staging");
assert_eq!(profile, "STAGING"); // Case-insensitive
```

### `const_new(name: &'static str)`

A `const` version of `new()` for use in const contexts.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| name | `&'static str` | Yes | — | Static profile name |

**Returns:** `Profile` - A new profile with the given name.

**Example:**
```rust
use figment2::Profile;

const STAGING: Profile = Profile::const_new("staging");
const PRODUCTION: Profile = Profile::const_new("production");

assert_eq!(STAGING, "staging");
```
```

--------------------------------

### Create Profile with `const_new()`

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/profile.md

Demonstrates the use of the `const_new()` method for creating `Profile` instances in constant contexts. Verifies the created profiles.

```rust
use figment2::Profile;

const STAGING: Profile = Profile::const_new("staging");
const PRODUCTION: Profile = Profile::const_new("production");

assert_eq!(STAGING, "staging");
```

--------------------------------

### Define Custom Profiles

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/profile.md

Shows how to define custom profiles using constants or dynamically from environment variables. This allows for environment-specific configurations.

```rust
use figment2::Profile;

const DEVELOPMENT: Profile = Profile::const_new("development");
const STAGING: Profile = Profile::const_new("staging");
const PRODUCTION: Profile = Profile::const_new("production");

// Or dynamically:
fn profile_from_env() -> Profile {
    Profile::from_env("APP_ENV")
        .unwrap_or_else(|| Profile::new("development"))
}
```

--------------------------------

### Data Provider from String

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/format-providers.md

Creates a Data provider that sources configuration directly from a string.

```rust
pub fn string(string: &str) -> Self
```

--------------------------------

### Figment::from()

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/figment.md

Creates a new Figment with the default profile and an initial provider.

```APIDOC
## Figment::from<T: Provider>(provider: T)

### Description
Creates a new `Figment` with the default profile selected and an initial provider.

### Method
`#[track_caller]
pub fn from<T: Provider>(provider: T) -> Self`

### Parameters
#### Path Parameters
- provider (`T: Provider`) - Required - The initial provider to merge

### Returns
`Figment` - A new figment with the provider merged in.

### Example
```rust
use figment2::{Figment, providers::Env};

let figment = Figment::from(Env::raw());
assert_eq!(figment.metadata().count(), 1);
```
```

--------------------------------

### Profile Methods

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/INDEX.md

Methods for working with configuration profiles.

```APIDOC
## Profile::new()

### Description
Creates a new custom profile.

### Method
`new(name)`

### Endpoint
N/A (Method Call)

### Parameters
- **name** - The name of the new profile.

### Request Example
```rust
let profile = Profile::new("custom");
```

### Response
- **Profile** - A new Profile instance.
```

```APIDOC
## Profile::const_new()

### Description
Creates a new custom profile with a const name.

### Method
`const_new(name)`

### Endpoint
N/A (Method Call)

### Parameters
- **name** - The const name of the new profile.

### Request Example
```rust
let profile = Profile::const_new("custom_const");
```

### Response
- **Profile** - A new Profile instance.
```

```APIDOC
## Profile::from_env()

### Description
Creates a profile from environment variables.

### Method
`from_env()`

### Endpoint
N/A (Method Call)

### Parameters
None

### Request Example
```rust
let profile = Profile::from_env();
```

### Response
- **Profile** - A Profile instance created from environment variables.
```

```APIDOC
## Profile::collect()

### Description
Collects all available profiles.

### Method
`collect()`

### Endpoint
N/A (Method Call)

### Parameters
None

### Request Example
```rust
let profiles = Profile::collect();
```

### Response
- **Vec<Profile>** - A vector of all available profiles.
```

--------------------------------

### Default File Search Behavior

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/configuration.md

Demonstrates the default behavior of file-based providers, which search for configuration files in the current directory and its parent directories.

```rust
use figment2::providers::{Format, Toml};

// Searches: ./config.toml, ../config.toml, ../../config.toml, etc.
let provider = Toml::file("config.toml");
```

--------------------------------

### Create File Source Metadata

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/metadata.md

Use this to create metadata indicating a configuration value originated from a file. Ensure the `figment2` crate and `Source` enum are imported.

```rust
use figment2::{Metadata, Source};
use std::path::PathBuf;

let metadata = Metadata::named("TOML file")
    .source(Source::File("config.toml".into()));
```

--------------------------------

### Env Provider Configuration Methods

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/INDEX.md

Methods for configuring the Env provider.

```APIDOC
## Env::profile()

### Description
Sets the profile for the Env provider.

### Method
`profile(name)`

### Endpoint
N/A (Method Call)

### Parameters
- **name** - The name of the profile.

### Request Example
```rust
let env_provider = Env::raw().profile("production");
```

### Response
- **Env** - The configured Env provider.
```

```APIDOC
## Env::lowercase()

### Description
Enables reading environment variables in lowercase.

### Method
`lowercase()`

### Endpoint
N/A (Method Call)

### Parameters
None

### Request Example
```rust
let env_provider = Env::raw().lowercase();
```

### Response
- **Env** - The configured Env provider.
```

```APIDOC
## Env::ignore_empty()

### Description
Ignores empty environment variables.

### Method
`ignore_empty()`

### Endpoint
N/A (Method Call)

### Parameters
None

### Request Example
```rust
let env_provider = Env::raw().ignore_empty();
```

### Response
- **Env** - The configured Env provider.
```

```APIDOC
## Env::parser()

### Description
Sets a custom parser for environment variable values.

### Method
`parser(parser_fn)`

### Endpoint
N/A (Method Call)

### Parameters
- **parser_fn** - A function to parse environment variable values.

### Request Example
```rust
let env_provider = Env::raw().parser(|v| v.parse::<i32>());
```

### Response
- **Env** - The configured Env provider.
```

```APIDOC
## Env::map()

### Description
Maps environment variable names to different keys.

### Method
`map(mapping)`

### Endpoint
N/A (Method Call)

### Parameters
- **mapping** - A map from environment variable names to configuration keys.

### Request Example
```rust
use std::collections::HashMap;
let mut map = HashMap::new();
map.insert("DB_HOST", "database.host");
let env_provider = Env::raw().map(map);
```

### Response
- **Env** - The configured Env provider.
```

```APIDOC
## Env::split()

### Description
Splits environment variable values by a delimiter into arrays.

### Method
`split(delimiter)`

### Endpoint
N/A (Method Call)

### Parameters
- **delimiter** - The delimiter to split values by.

### Request Example
```rust
let env_provider = Env::raw().split(',');
```

### Response
- **Env** - The configured Env provider.
```

```APIDOC
## Env::only()

### Description
Only loads environment variables that match a given pattern.

### Method
`only(pattern)`

### Endpoint
N/A (Method Call)

### Parameters
- **pattern** - A pattern to match environment variable names.

### Request Example
```rust
let env_provider = Env::raw().only("APP_*");
```

### Response
- **Env** - The configured Env provider.
```

```APIDOC
## Env::ignore()

### Description
Ignores environment variables that match a given pattern.

### Method
`ignore(pattern)`

### Endpoint
N/A (Method Call)

### Parameters
- **pattern** - A pattern to ignore environment variable names.

### Request Example
```rust
let env_provider = Env::raw().ignore("TEMP_*");
```

### Response
- **Env** - The configured Env provider.
```

--------------------------------

### Configuration Method: Metadata::source

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/metadata.md

Sets the source for the metadata. This method is chainable and returns self.

```rust
#[inline(always)]
pub fn source<S: Into<Source>>(mut self, source: S) -> Self
```

```rust
use figment2::Metadata;

let metadata = Metadata::named("AWS Config Store")
    .source("config/path");
assert_eq!(metadata.source.unwrap().custom(), Some("config/path"));
```

--------------------------------

### Create Custom Source using `Source::custom`

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/metadata.md

This method creates a `Source::Custom` variant, allowing for a descriptive string for the configuration source. The string can be any type that can be converted into `Cow<'static, str>`.

```rust
use figment2::Source;

let source = Source::custom("AWS Secrets Manager");
```

--------------------------------

### Metadata Creation Methods

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/INDEX.md

Methods for creating Metadata instances.

```APIDOC
## Metadata::from()

### Description
Creates Metadata from a source.

### Method
`from(source)`

### Endpoint
N/A (Method Call)

### Parameters
- **source** - The source to create Metadata from.

### Request Example
```rust
let metadata = Metadata::from("config.toml");
```

### Response
- **Metadata** - A Metadata instance.
```

```APIDOC
## Metadata::named()

### Description
Creates named Metadata.

### Method
`named(name, value)`

### Endpoint
N/A (Method Call)

### Parameters
- **name** - The name of the metadata.
- **value** - The value of the metadata.

### Request Example
```rust
let metadata = Metadata::named("version", "1.0.0");
```

### Response
- **Metadata** - A named Metadata instance.
```

--------------------------------

### Env Provider Creation Methods

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/INDEX.md

Methods for creating Env providers.

```APIDOC
## Env::raw()

### Description
Creates an Env provider that reads raw environment variables.

### Method
`raw()`

### Endpoint
N/A (Method Call)

### Parameters
None

### Request Example
```rust
let env_provider = Env::raw();
```

### Response
- **Env** - An Env provider instance.
```

```APIDOC
## Env::prefixed()

### Description
Creates an Env provider that reads environment variables with a specific prefix.

### Method
`prefixed(prefix)`

### Endpoint
N/A (Method Call)

### Parameters
- **prefix** - The prefix for environment variables.

### Request Example
```rust
let env_provider = Env::prefixed("APP_");
```

### Response
- **Env** - An Env provider instance with a prefix.
```

--------------------------------

### Create Json Provider from String

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/format-providers.md

Creates a `Data` provider that parses a JSON configuration string. The string should be valid JSON.

```rust
use figment2::{Figment, providers::{Format, Json}};

let config_str = r#"{"name":"MyApp","port":8080}"#;
let figment = Figment::from(Json::string(config_str));
```

--------------------------------

### Load Profile from Environment Variable

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/profile.md

Illustrates how to create a `Profile` from an environment variable using `from_env()`. The search for the environment variable is case-insensitive.

```rust
use figment2::Profile;

// If APP_ENV=production is set
let profile = Profile::from_env("APP_ENV");
assert_eq!(profile, Some(Profile::new("production")));
```

--------------------------------

### Custom Value Deserialization with Serde

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/configuration.md

Demonstrates how to use serde attributes, specifically `#[serde(default)]` and `#[serde(alias = "db_host")]`, to customize the deserialization of configuration values into a struct.

```rust
use serde::Deserialize;

#[derive(Deserialize)]
struct Config {
    #[serde(default)]
    debug: bool,
    
    #[serde(alias = "db_host")]
    database_host: String,
}
```

--------------------------------

### string(string: &str)

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/format-providers.md

Returns a Data provider sourcing from a configuration string.

```APIDOC
## `string(string: &str)`

```rust
pub fn string(string: &str) -> Self
```

Returns a `Data` provider sourcing from a configuration string.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| string | `&str` | Yes | — | Configuration data |

**Returns:** `Data<F>` - String-based provider.
```

--------------------------------

### Profile from Environment Variable

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/profile.md

Constructs a profile from an environment variable.

```APIDOC
### Environment Variable

#### `from_env(key: &str)`

Constructs a profile from the value of the environment variable with name `key`. The search for `key` is case-insensitive.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| key | `&str` | Yes | — | Environment variable name |

**Returns:** `Option<Profile>` - The profile from the environment, or `None` if not set.

**Example:**
```rust
use figment2::Profile;

// If APP_ENV=production is set
let profile = Profile::from_env("APP_ENV");
assert_eq!(profile, Some(Profile::new("production")));
```
```

--------------------------------

### select

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/figment.md

Selects a profile to extract configuration from. This method allows you to specify which configuration profile should be active for subsequent operations. It defaults to `Profile::Default` if no profile is explicitly chosen.

```APIDOC
## select<P: Into<Profile>>(self, profile: P)

### Description
Selects a profile to extract configuration from. Defaults to `Profile::Default`.

### Method

```rust
pub fn select<P: Into<Profile>>(mut self, profile: P) -> Self
```

### Parameters
#### Path Parameters
- **profile** (P: Into<Profile>) - Required - The profile to select

### Returns
`Self` - Self with the profile changed.

### Example
```rust
use figment2::Figment;

let figment = Figment::new().select("production");
assert_eq!(figment.profile(), "production");
```
```

--------------------------------

### Create Default Serialized Provider

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/serialized-provider.md

Use `Serialized::defaults` to create a provider for default values. The data is emitted to `Profile::Default`. Ensure the value type implements `serde::Serialize`.

```rust
use serde::Serialize;
use figment2::{Figment, providers::Serialized};

#[derive(Serialize)]
struct Defaults {
    debug: bool,
    timeout: u32,
}

let defaults = Defaults {
    debug: false,
    timeout: 30,
};

let figment = Figment::from(Serialized::defaults(defaults));
```

--------------------------------

### Metadata::from

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/metadata.md

Creates a new Metadata instance with a given name and source. This is useful for associating configuration values with their origin.

```APIDOC
## Metadata::from

### Description
Creates a new Metadata instance with a given name and source. This is useful for associating configuration values with their origin.

### Signature
```rust
pub fn from<N, S>(name: N, source: S) -> Self
    where N: Into<Cow<'static, str>>, S: Into<Source>
```

### Parameters
#### Path Parameters
- **name** (`N: Into<Cow<'static, str>>`) - Required - Provider name (e.g., `"AWS Config"`)
- **source** (`S: Into<Source>`) - Required - Configuration source information

### Returns
`Metadata` - New metadata with name and source.

### Example
```rust
use figment2::Metadata;

let metadata = Metadata::from("AWS Config Store", "path/to/value");
assert_eq!(metadata.name, "AWS Config Store");
assert_eq!(metadata.source.unwrap().custom(), Some("path/to/value"));
```
```

--------------------------------

### Create Toml Provider from File

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/format-providers.md

Creates a `Data` provider that parses a TOML file. If the path is relative, it searches parent directories. Use `file_exact()` to disable this behavior.

```rust
use figment2::{Figment, providers::{Format, Toml}};

let figment = Figment::from(Toml::file("config.toml"));
```

--------------------------------

### Constructor: Metadata::named

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/metadata.md

Creates metadata with only a name, omitting source information. Use when source details are not applicable or available.

```rust
#[inline]
pub fn named(name: T) -> Self
```

```rust
use figment2::Metadata;

let metadata = Metadata::named("AWS Config Store");
assert_eq!(metadata.name, "AWS Config Store");
assert!(metadata.source.is_none());
```

--------------------------------

### Combine Multiple Configuration Providers

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/INDEX.md

Combine multiple configuration providers using merge or join strategies. This allows for complex configuration hierarchies.

```rust
Figment::join(provider1, provider2)
```

```rust
Figment::adjoin(provider1, provider2)
```

--------------------------------

### Select Configuration Profile

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/INDEX.md

Select a specific configuration profile at runtime. This is useful for environment-specific settings or different application modes.

```rust
Figment::select("production")
```

```rust
Profile::from_env()
```

--------------------------------

### Nesting Support in Providers

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/provider.md

Providers that support optional profile nesting should accept an optional `Profile` parameter. If no profile is specified, configuration is read as `Map<Profile, Dict>`; if a profile is specified, it's read as `Dict` and collected into the specified profile.

```rust
pub fn new_with_profile(profile: Option<Profile>) -> Self {
    // Store the profile...
}

fn data(&self) -> Result<Map<Profile, Dict>> {
    match &self.profile {
        Some(profile) => Ok(profile.collect(self.read_dict()?)),
        None => self.read_map(),
    }
}
```

--------------------------------

### Create String Value

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/value.md

Instantiate a Value as a string.

```rust
use figment2::value::Value;

let str_val = Value::String("hello".to_string());
```

--------------------------------

### Default Configuration with Serialized Provider

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/serialized-provider.md

Provide application defaults using a serializable struct and merge with other configuration sources like TOML and environment variables. Ensure the struct implements `Serialize`, `Deserialize`, and `Default` traits.

```rust
use serde::{Serialize, Deserialize};
use figment2::{Figment, providers::{Serialized, Env, Format, Toml}};

#[derive(Serialize, Deserialize)]
struct Config {
    host: String,
    port: u16,
    debug: bool,
}

impl Default for Config {
    fn default() -> Self {
        Config {
            host: "localhost".into(),
            port: 8080,
            debug: false,
        }
    }
}

let config: Config = Figment::new()
    .merge(Serialized::defaults(Config::default()))
    .merge(Toml::file("config.toml"))
    .merge(Env::prefixed("APP_"))
    .extract()?;
```

--------------------------------

### Select Figment Profile for Extraction

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/profile.md

Demonstrates how to select and extract configuration using different profiles in Rust. Use this when you need to load settings specific to a particular environment or configuration set.

```rust
use serde::Deserialize;
use figment2::{Figment, Profile};

#[derive(Deserialize)]
struct Config {
    name: String,
}

let figment = Figment::new();

// Use default profile
let config: Config = figment.extract()?;

// Use custom profile
let config: Config = figment.select("staging").extract()?;
```

--------------------------------

### Handling Multiple Errors

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/error.md

Illustrates how to load configuration that might produce multiple errors and iterate through them using `e.for_each()` for individual handling.

```rust
use figment2::Figment;

fn load_config() -> figment2::error::Result<MyConfig> {
    Figment::new().extract()
}

match load_config() {
    Ok(config) => { /* ... */ },
    Err(e) => {
        e.for_each(|err| {
            eprintln!("  {}", err);
        });
    }
}
```

--------------------------------

### Selecting Profile from Environment Variable

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/configuration.md

Dynamically select a configuration profile based on an environment variable, falling back to a default if not set.

```rust
let profile = Profile::from_env("APP_ENV")
    .unwrap_or(Profile::Default);
let config: Config = Figment::new()
    .select(profile)
    .extract()?;

```

--------------------------------

### Default Environment Variable Parsing

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/configuration.md

Illustrates the default TOML-like syntax used by the `Env` provider for parsing values, including booleans, floats, integers, arrays, dictionaries, and strings.

```text
- `true`, `false` → Boolean
- `1.5` → Float
- `10` → Unsigned integer
- `-10` → Signed integer
- `[1, 2, 3]` → Array
- `{key=value}` → Dictionary
- `"quoted"` → String
- Anything else → Raw string
```

--------------------------------

### TOML Format Provider

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/format-providers.md

Use the Toml provider to load configuration from TOML files or strings. Requires the 'toml' feature.

```rust
use figment2::{Figment, providers::{Format, Toml}};

let figment = Figment::new()
    .merge(Toml::file("app.toml"))
    .merge(Toml::string(r#"\n        [database]\n        host = \"localhost\"\n        port = 5432\n    "#));
```

--------------------------------

### Source::File

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/metadata.md

Represents a configuration source originating from a file. The `file` method constructs this source type.

```APIDOC
## Source::File

### Description
Creates a `File` source, indicating that configuration values are loaded from a file at a specified path.

### Method
`file(path: P)`

### Parameters
#### Path Parameters
- **path** (P: Into<PathBuf>) - Required - The file path from which to load configuration.

### Returns
`Source` - A `Source` enum variant representing a file source.

### Example
```rust
use figment2::Source;

let source = Source::file("config.toml");
```
```

--------------------------------

### Metadata Configuration Methods

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/INDEX.md

Methods for configuring Metadata.

```APIDOC
## Metadata::source()

### Description
Sets the source for the Metadata.

### Method
`source(source)`

### Endpoint
N/A (Method Call)

### Parameters
- **source** - The source of the metadata.

### Request Example
```rust
let metadata = Metadata::from("config.toml").source("file://config.toml");
```

### Response
- **Metadata** - The configured Metadata instance.
```

```APIDOC
## Metadata::interpolater()

### Description
Sets a custom interpolater for the Metadata.

### Method
`interpolater(interpolater)`

### Endpoint
N/A (Method Call)

### Parameters
- **interpolater** - A custom interpolater function.

### Request Example
```rust
let metadata = Metadata::from("config.toml").interpolater(|v| v.to_uppercase());
```

### Response
- **Metadata** - The configured Metadata instance.
```

--------------------------------

### Create Raw Environment Variable Provider

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/INDEX.md

Instantiate a raw environment variable provider to read directly from environment variables. Use this for basic environment variable loading.

```rust
Env::raw()
```

--------------------------------

### Tuple Provider Implementation

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/provider.md

Any tuple of a string key and a `Serialize` value becomes a provider, equivalent to `Serialized::global(key, value)`. The key can be a simple string or a nested path.

```rust
impl<K: AsRef<str>, V: serde::Serialize> Provider for (K, V)
```

```rust
use figment2::Figment;
use serde::Serialize;

#[derive(Serialize)]
struct DbConfig {
    host: String,
    port: u16,
}

let db = DbConfig {
    host: "localhost".into(),
    port: 5432,
};

let figment = Figment::new()
    .merge(("database", db));
```

--------------------------------

### Create Dictionary Value

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/value.md

Instantiate a Value as a dictionary with string keys and Value values.

```rust
use figment2::value::{Value, Dict};

let mut dict = Dict::new();
dict.insert("key".into(), Value::String("value".into()));
let dict_val = Value::Dict(dict);
```

--------------------------------

### Json::string

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/format-providers.md

Creates a Data provider that parses a JSON configuration from a string.

```APIDOC
## Json::string

### Description
Parses a JSON configuration directly from a string.

### Method
`string(s: &str)`

### Parameters
#### Path Parameters
- **s** (`&str`) - Required - The JSON configuration data as a string.

### Returns
`Data<Self>` - A Data provider instance for the JSON string.

### Example
```rust
use figment2::{Figment, providers::{Format, Json}};

let config_str = r#"{"name":"MyApp","port":8080}"#;
let figment = Figment::from(Json::string(config_str));
```
```

--------------------------------

### Figment Query Methods

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/INDEX.md

Methods for querying configuration values and metadata.

```APIDOC
## Figment::find_value()

### Description
Finds a configuration value at a given path.

### Method
`find_value(path)`

### Endpoint
N/A (Method Call)

### Parameters
- **path** - The configuration path to find the value at.

### Request Example
```rust
let value = Figment::new().find_value("api.key");
```

### Response
- **Option<Value>** - The found configuration value, or None.
```

```APIDOC
## Figment::contains()

### Description
Checks if a configuration value exists at a given path.

### Method
`contains(path)`

### Endpoint
N/A (Method Call)

### Parameters
- **path** - The configuration path to check.

### Request Example
```rust
let has_setting = Figment::new().contains("database.username");
```

### Response
- **bool** - True if the path exists, false otherwise.
```

```APIDOC
## Figment::metadata()

### Description
Retrieves all metadata associated with the configuration.

### Method
`metadata()`

### Endpoint
N/A (Method Call)

### Parameters
None

### Request Example
```rust
let meta = Figment::new().metadata();
```

### Response
- **Metadata** - The metadata associated with the configuration.
```

```APIDOC
## Figment::find_metadata()

### Description
Finds metadata associated with a specific configuration path.

### Method
`find_metadata(path)`

### Endpoint
N/A (Method Call)

### Parameters
- **path** - The configuration path to find metadata for.

### Request Example
```rust
let meta = Figment::new().find_metadata("api.url");
```

### Response
- **Option<Metadata>** - The metadata for the path, or None.
```

```APIDOC
## Figment::get_metadata()

### Description
Retrieves metadata associated with a specific configuration path, panicking if not found.

### Method
`get_metadata(path)`

### Endpoint
N/A (Method Call)

### Parameters
- **path** - The configuration path to get metadata for.

### Request Example
```rust
let meta = Figment::new().get_metadata("logging.level");
```

### Response
- **Metadata** - The metadata for the path.
```

--------------------------------

### Create Custom Source Metadata

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/api-reference/metadata.md

Use this to create metadata indicating a configuration value originated from a custom source description. Ensure the `figment2` crate and `Source` enum are imported.

```rust
use figment2::{Metadata, Source};

let metadata = Metadata::named("Remote Config")
    .source(Source::Custom("https://config.example.com".into()));
```

--------------------------------

### Serialized Provider Configuration Methods

Source: https://github.com/lmmx/figment2/blob/master/_autodocs/INDEX.md

Methods for configuring Serialized providers.

```APIDOC
## Serialized::profile()

### Description
Sets the profile for the Serialized provider.

### Method
`profile(name)`

### Endpoint
N/A (Method Call)

### Parameters
- **name** - The name of the profile.

### Request Example
```rust
let serialized_provider = Serialized::defaults().profile("default");
```

### Response
- **Serialized** - The configured Serialized provider.
```

```APIDOC
## Serialized::nested()

### Description
Enables nested configuration loading for the Serialized provider.

### Method
`nested()`

### Endpoint
N/A (Method Call)

### Parameters
None

### Request Example
```rust
let serialized_provider = Serialized::defaults().nested();
```

### Response
- **Serialized** - The configured Serialized provider.
```