[−][src]Struct figment::Figment
Combiner of Provider
s for configuration value extraction.
Overview
A Figment
combines providers by merging or joining their provided data.
The combined value or a subset of the combined value can be extracted into
any type that implements Deserialize
. Additionally, values can be nested
in profiles, and a profile can be selected via Figment::select()
for
extraction; the profile to be extracted can be retrieved with
Figment::profile()
and defaults to Profile::Default
. The top-level
docs contain a broad overview of these topics.
Merging vs. Joining
Merging and joining control whether duplicate values are replaced or discarded. A merged value replaces an existing value with the same key, while a joined value is discarded if a value with the same key exists:
use figment::{Figment}; let figment = Figment::from(("key", "original")); let original: String = figment.extract_inner("key").unwrap(); assert_eq!(original, "original"); let figment = figment.merge(("key", "replaced")); let replaced: String = figment.extract_inner("key").unwrap(); assert_eq!(replaced, "replaced"); let figment = figment.join(("key", "joined")); let joined: String = figment.extract_inner("key").unwrap(); assert_eq!(joined, "replaced");
Extraction
The configuration or a subset thereof can be extracted from a Figment
in
one of several ways:
Figment::extract()
, which extracts the complete value into anyT: Deserialize
.Figment::extract_inner()
, which extracts a subset of the value for a given key path.Figment::find_value()
, which returns the raw, serializedValue
for a given key path.
A "key path" is a string of the form a.b.c
(e.g, item
, item.fruits
,
etc.) where each component delimited by a .
is a key for the dictionary of
the preceding key in the path, or the root dictionary if it is the first key
in the path. See Value::find()
for examples.
Metadata
Every value collected by a Figment
is accompanied by metadata. If the
metadata has no source
, the merge
or join
Location
is added as a
source. Metadata
can be retrieved in one of several ways:
Figment::metadata()
, which returns an iterator over all of the metadata for all values.Figment::find_metadata()
, which returns the metadata for a value at a given key path.Figment::get_metadata()
, which returns the metadata for a givenTag
.
Implementations
impl Figment
[src]
pub fn new() -> Self
[src]
Creates a new Figment
with the default profile selected and no
providers.
use figment::Figment; let figment = Figment::new(); assert_eq!(figment.metadata().count(), 0);
pub fn from<T: Provider>(provider: T) -> Self
[src]
Creates a new Figment
with the default profile selected and an initial
provider
.
use figment::Figment; use figment::providers::Env; let figment = Figment::from(Env::raw()); assert_eq!(figment.metadata().count(), 1);
pub fn join<T: Provider>(self, provider: T) -> Self
[src]
Joins provider
into the current figment. See merging vs.
joining for details.
use figment::Figment; use figment::providers::Env; let figment = Figment::new().join(Env::raw()); assert_eq!(figment.metadata().count(), 1);
pub fn merge<T: Provider>(self, provider: T) -> Self
[src]
Merges provider
into the current figment. See merging vs.
joining for details.
use figment::Figment; use figment::providers::Env; let figment = Figment::new().merge(Env::raw()); assert_eq!(figment.metadata().count(), 1);
pub fn select<P: Into<Profile>>(self, profile: P) -> Self
[src]
Sets the profile to extract from to profile
.
Example
use figment::Figment; let figment = Figment::new().select("staging"); assert_eq!(figment.profile(), "staging");
pub fn extract<'a, T: Deserialize<'a>>(&self) -> Result<T>
[src]
Deserializes the collected value into T
.
Example
use serde::Deserialize; use figment::{Figment, providers::{Format, Toml, Json, Env}}; #[derive(Debug, PartialEq, Deserialize)] struct Config { name: String, numbers: Option<Vec<usize>>, debug: bool, } figment::Jail::expect_with(|jail| { jail.create_file("Config.toml", r#" name = "test" numbers = [1, 2, 3, 10] "#)?; jail.set_env("config_name", "env-test"); jail.create_file("Config.json", r#" { "name": "json-test", "debug": true } "#)?; let config: Config = Figment::new() .merge(Toml::file("Config.toml")) .merge(Env::prefixed("CONFIG_")) .join(Json::file("Config.json")) .extract()?; assert_eq!(config, Config { name: "env-test".into(), numbers: vec![1, 2, 3, 10].into(), debug: true }); Ok(()) });
pub fn extract_inner<'a, T: Deserialize<'a>>(&self, key: &str) -> Result<T>
[src]
Deserializes the value at the key
path in the collected value into
T
.
Example
use figment::{Figment, providers::{Format, Toml, Json}}; figment::Jail::expect_with(|jail| { jail.create_file("Config.toml", r#" numbers = [1, 2, 3, 10] "#)?; jail.create_file("Config.json", r#"{ "debug": true } "#)?; let numbers: Vec<usize> = Figment::new() .merge(Toml::file("Config.toml")) .join(Json::file("Config.json")) .extract_inner("numbers")?; assert_eq!(numbers, vec![1, 2, 3, 10]); Ok(()) });
pub fn metadata(&self) -> impl Iterator<Item = &Metadata>
[src]
Returns an iterator over the metadata for all of the collected values in
the order in which they were added to self
.
Example
use figment::{Figment, providers::{Format, Toml, Json}}; let figment = Figment::new() .merge(Toml::file("Config.toml")) .join(Json::file("Config.json")); assert_eq!(figment.metadata().count(), 2); for (i, md) in figment.metadata().enumerate() { match i { 0 => assert!(md.name.starts_with("TOML")), 1 => assert!(md.name.starts_with("JSON")), _ => unreachable!(), } }
pub fn profile(&self) -> &Profile
[src]
Returns the selected profile.
Example
use figment::Figment; let figment = Figment::new(); assert_eq!(figment.profile(), "default"); let figment = figment.select("staging"); assert_eq!(figment.profile(), "staging");
pub fn find_value(&self, key: &str) -> Result<Value>
[src]
Finds the value at key
path in the combined value. See
Value::find()
for details on the syntax for key
.
Example
use serde::Deserialize; use figment::{Figment, providers::{Format, Toml, Json, Env}}; figment::Jail::expect_with(|jail| { jail.create_file("Config.toml", r#" name = "test" [package] name = "my-package" "#)?; jail.create_file("Config.json", r#" { "author": { "name": "Bob" } } "#)?; let figment = Figment::new() .merge(Toml::file("Config.toml")) .join(Json::file("Config.json")); let name = figment.find_value("name")?; assert_eq!(name.as_str(), Some("test")); let package_name = figment.find_value("package.name")?; assert_eq!(package_name.as_str(), Some("my-package")); let author_name = figment.find_value("author.name")?; assert_eq!(author_name.as_str(), Some("Bob")); Ok(()) });
pub fn find_metadata(&self, key: &str) -> Option<&Metadata>
[src]
Finds the metadata for the value at key
path. See Value::find()
for details on the syntax for key
.
Example
use serde::Deserialize; use figment::{Figment, providers::{Format, Toml, Json, Env}}; figment::Jail::expect_with(|jail| { jail.create_file("Config.toml", r#" name = "test" "#)?; jail.create_file("Config.json", r#" { "author": "Bob" } "#)?; let figment = Figment::new() .merge(Toml::file("Config.toml")) .join(Json::file("Config.json")); let name_md = figment.find_metadata("name").unwrap(); assert!(name_md.name.starts_with("TOML")); let author_md = figment.find_metadata("author").unwrap(); assert!(author_md.name.starts_with("JSON")); Ok(()) });
pub fn get_metadata(&self, id: Tag) -> Option<&Metadata>
[src]
Returns the metadata with the given id
if this figment contains a
value with said metadata.
Example
use serde::Deserialize; use figment::{Figment, providers::{Format, Toml, Json, Env}}; figment::Jail::expect_with(|jail| { jail.create_file("Config.toml", r#" name = "test" "#)?; jail.create_file("Config.json", r#" { "author": "Bob" } "#)?; let figment = Figment::new() .merge(Toml::file("Config.toml")) .join(Json::file("Config.json")); let name = figment.find_value("name").unwrap(); let metadata = figment.get_metadata(name.tag()).unwrap(); assert!(metadata.name.starts_with("TOML")); let author = figment.find_value("author").unwrap(); let metadata = figment.get_metadata(author.tag()).unwrap(); assert!(metadata.name.starts_with("JSON")); Ok(()) });
Trait Implementations
impl Clone for Figment
[src]
impl Debug for Figment
[src]
impl Default for Figment
[src]
impl Provider for Figment
[src]
Auto Trait Implementations
impl !RefUnwindSafe for Figment
impl Send for Figment
impl Sync for Figment
impl Unpin for Figment
impl !UnwindSafe for Figment
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
V: MultiLane<T>,