[go: up one dir, main page]

Struct figment::Metadata[−][src]

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

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[src]

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

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: Into<Cow<'static, str>>>(name: T) -> Self[src]

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: Into<Source>>(self, source: S) -> Self[src]

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: Clone + Send + Sync + 'static>(self, f: I) -> Self where
    I: Fn(&Profile, &[&str]) -> String, [src]

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: AsRef<str>>(
    &self,
    profile: &Profile,
    keys: &[K]
) -> String[src]

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[src]

impl Debug for Metadata[src]

impl Default for Metadata[src]

impl PartialEq<Metadata> for Metadata[src]

Auto Trait Implementations

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized, [src]

impl<T> Borrow<T> for T where
    T: ?Sized, [src]

impl<T> BorrowMut<T> for T where
    T: ?Sized, [src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, [src]

impl<T> ToOwned for T where
    T: Clone, [src]

type Owned = T

The resulting type after obtaining ownership.

impl<T, U> TryFrom<U> for T where
    U: Into<T>, [src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, [src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<V, T> VZip<V> for T where
    V: MultiLane<T>,