Struct figment::Figment [−][src]
pub struct Figment { /* fields omitted */ }
Expand description
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 the metadata produced
by the value’s provider. Additionally, Metadata::provide_location
is set
by from
, merge
and join
to the caller’s location. 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
, itself retrieved viaTagged
orValue::tag()
.
Implementations
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);
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);
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);
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);
Sets the profile to extract from to profile
.
Example
use figment::Figment; let figment = Figment::new().select("staging"); assert_eq!(figment.profile(), "staging");
Returns a new Figment
containing only the sub-dictionaries at key
.
This “sub-figment” is a focusing of self
with the property that:
self.find(key + ".sub")
<=>focused.find("sub")
In other words, all values in self
with a key starting with key
are
in focused
without the prefix and vice-versa.
Example
use figment::{Figment, providers::{Format, Toml}}; figment::Jail::expect_with(|jail| { jail.create_file("Config.toml", r#" cat = [1, 2, 3] dog = [4, 5, 6] [subtree] cat = "meow" dog = "woof!" [subtree.bark] dog = true cat = false "#)?; let root = Figment::from(Toml::file("Config.toml")); assert_eq!(root.extract_inner::<Vec<u8>>("cat").unwrap(), vec![1, 2, 3]); assert_eq!(root.extract_inner::<Vec<u8>>("dog").unwrap(), vec![4, 5, 6]); assert_eq!(root.extract_inner::<String>("subtree.cat").unwrap(), "meow"); assert_eq!(root.extract_inner::<String>("subtree.dog").unwrap(), "woof!"); let subtree = root.focus("subtree"); assert_eq!(subtree.extract_inner::<String>("cat").unwrap(), "meow"); assert_eq!(subtree.extract_inner::<String>("dog").unwrap(), "woof!"); assert_eq!(subtree.extract_inner::<bool>("bark.cat").unwrap(), false); assert_eq!(subtree.extract_inner::<bool>("bark.dog").unwrap(), true); let bark = subtree.focus("bark"); assert_eq!(bark.extract_inner::<bool>("cat").unwrap(), false); assert_eq!(bark.extract_inner::<bool>("dog").unwrap(), true); let not_a_dict = root.focus("cat"); assert!(not_a_dict.extract_inner::<bool>("cat").is_err()); assert!(not_a_dict.extract_inner::<bool>("dog").is_err()); Ok(()) });
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(()) });
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(()) });
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!(), } }
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");
Returns an iterator over profiles with valid configurations in this figment. Note: this may not include the selected profile if the selected profile has no configured values.
Example
use figment::{Figment, providers::Serialized}; let figment = Figment::new(); let profiles = figment.profiles().collect::<Vec<_>>(); assert_eq!(profiles.len(), 0); let figment = Figment::new() .join(Serialized::default("key", "hi")) .join(Serialized::default("key", "hey").profile("debug")); let mut profiles = figment.profiles().collect::<Vec<_>>(); profiles.sort(); assert_eq!(profiles, &["debug", "default"]); let figment = Figment::new() .join(Serialized::default("key", "hi").profile("release")) .join(Serialized::default("key", "hi").profile("testing")) .join(Serialized::default("key", "hey").profile("staging")) .select("debug"); let mut profiles = figment.profiles().collect::<Vec<_>>(); profiles.sort(); assert_eq!(profiles, &["release", "staging", "testing"]);
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(()) });
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.set_env("CONF_AUTHOR", "Bob"); let figment = Figment::new() .merge(Toml::file("Config.toml")) .join(Env::prefixed("CONF_").only(&["author"])); 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.contains("CONF_")); assert!(author_md.name.contains("environment")); Ok(()) });
Returns the metadata with the given tag
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
Auto Trait Implementations
impl !RefUnwindSafe for Figment
impl !UnwindSafe for Figment
Blanket Implementations
Mutably borrows from an owned value. Read more
pub fn vzip(self) -> V