Struct Metadata

pub struct Metadata {
    pub name: Cow<'static, str>,
    pub source: Option<Source>,
    pub provide_location: Option<&'static Location<'static>>,
    /* private fields */
}

Metadata about a configuration value: its source’s name and location.

Overview

Every Value produced by a Figment is Taged with Metadata by its producing Provider. The metadata consists of:

• A name for the source, e.g. “TOML File”.
• The Source itself, if it is known.
• A default or custom interpolater.
• A source Location where a value’s provider was added to the containing figment, if it is known.

This information is used to produce insightful error messages as well as to generate values like RelativePathBuf that know about their configuration source.

Errors

Errors produced by Figments contain the Metadata for the value that caused the error. The Display implementation for Error uses the metadata’s interpolater to display the path to the key for the value that caused the error.

Interpolation

Interpolation takes a figment profile and key path (a.b.c) and turns it into a source-native path. The default interpolater returns a figment key path prefixed with the profile if the profile is custom:

${profile}.${a}.${b}.${c}

Providers are free to implement any interpolater for their metadata. For example, the interpolater for Env uppercases each path key:

use figment::Metadata;

let metadata = Metadata::named("environment variable(s)")
    .interpolater(|profile, path| {
        let keys: Vec<_> = path.iter()
            .map(|k| k.to_ascii_uppercase())
            .collect();

        format!("{}", keys.join("."))
    });

let profile = figment::Profile::Default;
let interpolated = metadata.interpolate(&profile, &["key", "path"]);
assert_eq!(interpolated, "KEY.PATH");

Fields

name: Cow<'static, str>

The name of the configuration source for a given value.

source: Option<Source>

The source of the configuration value, if it is known.

provide_location: Option<&'static Location<'static>>

The source location where this value’s provider was added to the containing figment, if it is known.

Implementations

impl Metadata

pub fn from<N, S>(name: N, source: S) -> Metadata

where N: Into<Cow<'static, str>>, S: Into<Source>,

Creates a new Metadata with the given name and source.

Example

use figment::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"));

pub fn named<T>(name: T) -> Metadata

where T: Into<Cow<'static, str>>,

Creates a new Metadata with the given name and no source.

Example

use figment::Metadata;

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

pub fn source<S>(self, source: S) -> Metadata

where S: Into<Source>,

Sets the source of self to Some(source).

Example

use figment::Metadata;

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

pub fn interpolater<I>(self, f: I) -> Metadata

where I: Clone + Send + Sync + 'static + Fn(&Profile, &[&str]) -> String,

Sets the interpolater of self to the function f. The interpolater can be invoked via Metadata::interpolate().

Example

use figment::Metadata;

let metadata = Metadata::named("environment variable(s)")
    .interpolater(|profile, path| {
        let keys: Vec<_> = path.iter()
            .map(|k| k.to_ascii_uppercase())
            .collect();

        format!("{}", keys.join("."))
    });

let profile = figment::Profile::Default;
let interpolated = metadata.interpolate(&profile, &["key", "path"]);
assert_eq!(interpolated, "KEY.PATH");

pub fn interpolate<K>(&self, profile: &Profile, keys: &[K]) -> String

where K: AsRef<str>,

Runs the interpolater in self on profile and keys.

Example

use figment::{Metadata, Profile};

let url = "ftp://config.dev";
let md = Metadata::named("Network").source(url)
    .interpolater(move |profile, keys| match profile.is_custom() {
        true => format!("{}/{}/{}", url, profile, keys.join("/")),
        false => format!("{}/{}", url, keys.join("/")),
    });

let interpolated = md.interpolate(&Profile::Default, &["key", "path"]);
assert_eq!(interpolated, "ftp://config.dev/key/path");

let profile = Profile::new("static");
let interpolated = md.interpolate(&profile, &["key", "path"]);
assert_eq!(interpolated, "ftp://config.dev/static/key/path");

Trait Implementations

impl Clone for Metadata

fn clone(&self) -> Metadata

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Metadata

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Metadata

fn default() -> Metadata

Returns the “default value” for a type.

impl PartialEq for Metadata

fn eq(&self, other: &Metadata) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.