Struct rocket_db_pools::figment::Figment

source ·
pub struct Figment { /* private fields */ }
Expand description

Combiner of Providers 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.

§Conflict Resolution

Conflicts arising from two providers providing values for the same key are resolved via one of four strategies: join, adjoin, merge, and admerge. In general, join and adjoin prefer existing values while merge and admerge prefer later values. The ad- strategies additionally concatenate conflicting arrays whereas the non-ad- strategies treat arrays as non-composite values.

The table below summarizes these strategies and their behavior, with the column label referring to the type of the value pointed to by the conflicting keys:

StrategyDictionariesArraysAll Others
joinUnion, RecurseKeep ExistingKeep Existing
adjoinUnion, RecurseConcatenateKeep Existing
mergeUnion, RecurseUse IncomingUse Incoming
admergeUnion, RecurseConcatenateUse Incoming

§Description

If both keys point to a dictionary, the dictionaries are always unioned, irrespective of the strategy, and conflict resolution proceeds recursively with each key in the union.

If both keys point to an array:

  • join uses the existing value
  • merge uses the incoming value
  • adjoin and admerge concatenate the arrays

If both keys point to a non-composite (String, Num, etc.) or values of different kinds (i.e, array and num):

  • join and adjoin use the existing value
  • merge and admerge use the incoming value

For examples, refer to each strategy’s documentation.

§Extraction

The configuration or a subset thereof can be extracted from a Figment in one of several ways:

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:

Implementations§

source§

impl Figment

source

pub fn new() -> Figment

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);
source

pub fn from<T>(provider: T) -> Figment
where T: Provider,

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);
source

pub fn join<T>(self, provider: T) -> Figment
where T: Provider,

Joins provider into the current figment. See conflict resolution for details.

use figment::Figment;
use figment::util::map;
use figment::value::{Dict, Map};

let figment = Figment::new()
    .join(("string", "original"))
    .join(("vec", vec!["item 1"]))
    .join(("map", map!["string" => "inner original"]));

let new_figment = Figment::new()
    .join(("string", "replaced"))
    .join(("vec", vec!["item 2"]))
    .join(("map", map!["string" => "inner replaced", "new" => "value"]))
    .join(("new", "value"));

let figment = figment.join(new_figment); // **join**

let string: String = figment.extract_inner("string").unwrap();
assert_eq!(string, "original"); // existing value retained

let vec: Vec<String> = figment.extract_inner("vec").unwrap();
assert_eq!(vec, vec!["item 1"]); // existing value retained

let map: Map<String, String> = figment.extract_inner("map").unwrap();
assert_eq!(map, map! {
    "string".into() => "inner original".into(), // existing value retained
    "new".into() => "value".into(), // new key added
});

let new: String = figment.extract_inner("new").unwrap();
assert_eq!(new, "value"); // new key added
source

pub fn adjoin<T>(self, provider: T) -> Figment
where T: Provider,

Joins provider into the current figment while concatenating vectors. See conflict resolution for details.

use figment::Figment;
use figment::util::map;
use figment::value::{Dict, Map};

let figment = Figment::new()
    .join(("string", "original"))
    .join(("vec", vec!["item 1"]))
    .join(("map", map!["vec" => vec!["inner item 1"]]));

let new_figment = Figment::new()
    .join(("string", "replaced"))
    .join(("vec", vec!["item 2"]))
    .join(("map", map!["vec" => vec!["inner item 2"], "new" => vec!["value"]]))
    .join(("new", "value"));

let figment = figment.adjoin(new_figment); // **adjoin**

let string: String = figment.extract_inner("string").unwrap();
assert_eq!(string, "original"); // existing value retained

let vec: Vec<String> = figment.extract_inner("vec").unwrap();
assert_eq!(vec, vec!["item 1", "item 2"]); // arrays concatenated

let map: Map<String, Vec<String>> = figment.extract_inner("map").unwrap();
assert_eq!(map, map! {
    "vec".into() => vec!["inner item 1".into(), "inner item 2".into()], // arrays concatenated
    "new".into() => vec!["value".into()], // new key added
});

let new: String = figment.extract_inner("new").unwrap();
assert_eq!(new, "value"); // new key added
source

pub fn merge<T>(self, provider: T) -> Figment
where T: Provider,

Merges provider into the current figment. See conflict resolution for details.

use figment::Figment;
use figment::util::map;
use figment::value::{Dict, Map};

let figment = Figment::new()
    .join(("string", "original"))
    .join(("vec", vec!["item 1"]))
    .join(("map", map!["string" => "inner original"]));

let new_figment = Figment::new()
    .join(("string", "replaced"))
    .join(("vec", vec!["item 2"]))
    .join(("map", map!["string" => "inner replaced", "new" => "value"]))
    .join(("new", "value"));

let figment = figment.merge(new_figment); // **merge**

let string: String = figment.extract_inner("string").unwrap();
assert_eq!(string, "replaced"); // incoming value replaced existing

let vec: Vec<String> = figment.extract_inner("vec").unwrap();
assert_eq!(vec, vec!["item 2"]); // incoming value replaced existing

let map: Map<String, String> = figment.extract_inner("map").unwrap();
assert_eq!(map, map! {
    "string".into() => "inner replaced".into(), // incoming value replaced existing
    "new".into() => "value".into(), // new key added
});

let new: String = figment.extract_inner("new").unwrap();
assert_eq!(new, "value"); // new key added
source

pub fn admerge<T>(self, provider: T) -> Figment
where T: Provider,

Merges provider into the current figment while concatenating vectors. See conflict resolution for details.

use figment::Figment;
use figment::util::map;
use figment::value::{Dict, Map};

let figment = Figment::new()
    .join(("string", "original"))
    .join(("vec", vec!["item 1"]))
    .join(("map", map!["vec" => vec!["inner item 1"]]));

let new_figment = Figment::new()
    .join(("string", "replaced"))
    .join(("vec", vec!["item 2"]))
    .join(("map", map!["vec" => vec!["inner item 2"], "new" => vec!["value"]]))
    .join(("new", "value"));

let figment = figment.admerge(new_figment); // **admerge**

let string: String = figment.extract_inner("string").unwrap();
assert_eq!(string, "replaced"); // incoming value replaced existing

let vec: Vec<String> = figment.extract_inner("vec").unwrap();
assert_eq!(vec, vec!["item 1", "item 2"]); // arrays concatenated

let map: Map<String, Vec<String>> = figment.extract_inner("map").unwrap();
assert_eq!(map, map! {
    "vec".into() => vec!["inner item 1".into(), "inner item 2".into()], // arrays concatenated
    "new".into() => vec!["value".into()], // new key added
});

let new: String = figment.extract_inner("new").unwrap();
assert_eq!(new, "value"); // new key added
source

pub fn select<P>(self, profile: P) -> Figment
where P: Into<Profile>,

Sets the profile to extract from to profile.

§Example
use figment::Figment;

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

pub fn focus(&self, key: &str) -> Figment

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(())
});
source

pub fn extract<'a, T>(&self) -> Result<T, Error>
where T: Deserialize<'a>,

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(())
});
source

pub fn extract_lossy<'a, T>(&self) -> Result<T, Error>
where T: Deserialize<'a>,

As extract, but interpret numbers and booleans more flexibly.

See Value::to_bool_lossy and Value::to_num_lossy for a full explanation of the imputs accepted.

§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": "yes"
        }
    "#)?;

    let config: Config = Figment::new()
        .merge(Toml::file("Config.toml"))
        .merge(Env::prefixed("CONFIG_"))
        .join(Json::file("Config.json"))
        .extract_lossy()?;

    assert_eq!(config, Config {
        name: "env-test".into(),
        numbers: vec![1, 2, 3, 10].into(),
        debug: true
    });

    Ok(())
});
source

pub fn extract_inner<'a, T>(&self, path: &str) -> Result<T, Error>
where T: Deserialize<'a>,

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(())
});
source

pub fn extract_inner_lossy<'a, T>(&self, path: &str) -> Result<T, Error>
where T: Deserialize<'a>,

As extract, but interpret numbers and booleans more flexibly.

See Value::to_bool_lossy and Value::to_num_lossy for a full explanation of the imputs accepted.

§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_lossy("numbers")?;

    assert_eq!(numbers, vec![1, 2, 3, 10]);

    Ok(())
});
source

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

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!(),
    }
}
source

pub fn profile(&self) -> &Profile

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");
source

pub fn profiles(&self) -> impl Iterator<Item = &Profile>

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"]);
source

pub fn find_value(&self, path: &str) -> Result<Value, Error>

Finds the value at path in the combined value.

If there is an error evaluating the combined figment, that error is returned. Otherwise if there is a value at path, returns Ok(value), and if there is no value at path, returns Err of kind MissingField.

See Value::find() for details on the syntax for path.

§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(())
});
source

pub fn contains(&self, path: &str) -> bool

Returns true if the combined figment evaluates successfully and contains a value at path.

See Value::find() for details on the syntax for path.

§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"));

    assert!(figment.contains("name"));
    assert!(figment.contains("package"));
    assert!(figment.contains("package.name"));
    assert!(figment.contains("author"));
    assert!(figment.contains("author.name"));
    assert!(!figment.contains("author.title"));
    Ok(())
});
source

pub fn find_metadata(&self, key: &str) -> Option<&Metadata>

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(())
});
source

pub fn get_metadata(&self, tag: Tag) -> Option<&Metadata>

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§

source§

impl Clone for Figment

source§

fn clone(&self) -> Figment

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Figment

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for Figment

source§

fn default() -> Figment

Returns the “default value” for a type. Read more
source§

impl Provider for Figment

source§

fn metadata(&self) -> Metadata

Returns the Metadata for this provider, identifying itself and its configuration sources.
source§

fn data(&self) -> Result<BTreeMap<Profile, BTreeMap<String, Value>>, Error>

Returns the configuration data.
source§

fn profile(&self) -> Option<Profile>

Optionally returns a profile to set on the Figment this provider is merged into. The profile is only set if self is merged.
source§

impl Trace for Figment

Auto Trait Implementations§

Blanket Implementations§

source§

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

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> AsAny for T
where T: Any,

source§

fn as_any_ref(&self) -> &(dyn Any + 'static)

source§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

source§

impl<'a, T, E> AsTaggedExplicit<'a, E> for T
where T: 'a,

source§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

source§

impl<'a, T, E> AsTaggedImplicit<'a, E> for T
where T: 'a,

source§

fn implicit( self, class: Class, constructed: bool, tag: u32, ) -> TaggedParser<'a, Implicit, Self, E>

source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> Conv for T

source§

fn conv<T>(self) -> T
where Self: Into<T>,

Converts self into T using Into<T>. Read more
source§

impl<T> FmtForward for T

source§

fn fmt_binary(self) -> FmtBinary<Self>
where Self: Binary,

Causes self to use its Binary implementation when Debug-formatted.
source§

fn fmt_display(self) -> FmtDisplay<Self>
where Self: Display,

Causes self to use its Display implementation when Debug-formatted.
source§

fn fmt_lower_exp(self) -> FmtLowerExp<Self>
where Self: LowerExp,

Causes self to use its LowerExp implementation when Debug-formatted.
source§

fn fmt_lower_hex(self) -> FmtLowerHex<Self>
where Self: LowerHex,

Causes self to use its LowerHex implementation when Debug-formatted.
source§

fn fmt_octal(self) -> FmtOctal<Self>
where Self: Octal,

Causes self to use its Octal implementation when Debug-formatted.
source§

fn fmt_pointer(self) -> FmtPointer<Self>
where Self: Pointer,

Causes self to use its Pointer implementation when Debug-formatted.
source§

fn fmt_upper_exp(self) -> FmtUpperExp<Self>
where Self: UpperExp,

Causes self to use its UpperExp implementation when Debug-formatted.
source§

fn fmt_upper_hex(self) -> FmtUpperHex<Self>
where Self: UpperHex,

Causes self to use its UpperHex implementation when Debug-formatted.
source§

fn fmt_list(self) -> FmtList<Self>
where &'a Self: for<'a> IntoIterator,

Formats each item in a sequence. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

impl<T> IntoSql for T

source§

fn into_sql<T>(self) -> Self::Expression

Convert self to an expression for Diesel’s query builder. Read more
source§

fn as_sql<'a, T>(&'a self) -> <&'a Self as AsExpression<T>>::Expression
where &'a Self: AsExpression<T>, T: SqlType + TypedExpressionType,

Convert &self to an expression for Diesel’s query builder. Read more
source§

impl<T> Paint for T
where T: ?Sized,

source§

fn fg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the foreground set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like red() and green(), which have the same functionality but are pithier.

§Example

Set foreground color to white using fg():

use yansi::{Paint, Color};

painted.fg(Color::White);

Set foreground color to white using white().

use yansi::Paint;

painted.white();
source§

fn primary(&self) -> Painted<&T>

Returns self with the fg() set to Color::Primary.

§Example
println!("{}", value.primary());
source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to Color::Fixed.

§Example
println!("{}", value.fixed(color));
source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to Color::Rgb.

§Example
println!("{}", value.rgb(r, g, b));
source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to Color::Black.

§Example
println!("{}", value.black());
source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to Color::Red.

§Example
println!("{}", value.red());
source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to Color::Green.

§Example
println!("{}", value.green());
source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::Yellow.

§Example
println!("{}", value.yellow());
source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::Blue.

§Example
println!("{}", value.blue());
source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::Magenta.

§Example
println!("{}", value.magenta());
source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::Cyan.

§Example
println!("{}", value.cyan());
source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to Color::White.

§Example
println!("{}", value.white());
source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlack.

§Example
println!("{}", value.bright_black());
source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightRed.

§Example
println!("{}", value.bright_red());
source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightGreen.

§Example
println!("{}", value.bright_green());
source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightYellow.

§Example
println!("{}", value.bright_yellow());
source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlue.

§Example
println!("{}", value.bright_blue());
source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightMagenta.

§Example
println!("{}", value.bright_magenta());
source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightCyan.

§Example
println!("{}", value.bright_cyan());
source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightWhite.

§Example
println!("{}", value.bright_white());
source§

fn bg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the background set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like on_red() and on_green(), which have the same functionality but are pithier.

§Example

Set background color to red using fg():

use yansi::{Paint, Color};

painted.bg(Color::Red);

Set background color to red using on_red().

use yansi::Paint;

painted.on_red();
source§

fn on_primary(&self) -> Painted<&T>

Returns self with the bg() set to Color::Primary.

§Example
println!("{}", value.on_primary());
source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to Color::Fixed.

§Example
println!("{}", value.on_fixed(color));
source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to Color::Rgb.

§Example
println!("{}", value.on_rgb(r, g, b));
source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::Black.

§Example
println!("{}", value.on_black());
source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::Red.

§Example
println!("{}", value.on_red());
source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::Green.

§Example
println!("{}", value.on_green());
source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::Yellow.

§Example
println!("{}", value.on_yellow());
source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::Blue.

§Example
println!("{}", value.on_blue());
source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::Magenta.

§Example
println!("{}", value.on_magenta());
source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::Cyan.

§Example
println!("{}", value.on_cyan());
source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::White.

§Example
println!("{}", value.on_white());
source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlack.

§Example
println!("{}", value.on_bright_black());
source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightRed.

§Example
println!("{}", value.on_bright_red());
source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightGreen.

§Example
println!("{}", value.on_bright_green());
source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightYellow.

§Example
println!("{}", value.on_bright_yellow());
source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlue.

§Example
println!("{}", value.on_bright_blue());
source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightMagenta.

§Example
println!("{}", value.on_bright_magenta());
source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightCyan.

§Example
println!("{}", value.on_bright_cyan());
source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightWhite.

§Example
println!("{}", value.on_bright_white());
source§

fn attr(&self, value: Attribute) -> Painted<&T>

Enables the styling Attribute value.

This method should be used rarely. Instead, prefer to use attribute-specific builder methods like bold() and underline(), which have the same functionality but are pithier.

§Example

Make text bold using attr():

use yansi::{Paint, Attribute};

painted.attr(Attribute::Bold);

Make text bold using using bold().

use yansi::Paint;

painted.bold();
source§

fn bold(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Bold.

§Example
println!("{}", value.bold());
source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Dim.

§Example
println!("{}", value.dim());
source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Italic.

§Example
println!("{}", value.italic());
source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Underline.

§Example
println!("{}", value.underline());

Returns self with the attr() set to Attribute::Blink.

§Example
println!("{}", value.blink());

Returns self with the attr() set to Attribute::RapidBlink.

§Example
println!("{}", value.rapid_blink());
source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Invert.

§Example
println!("{}", value.invert());
source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Conceal.

§Example
println!("{}", value.conceal());
source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Strike.

§Example
println!("{}", value.strike());
source§

fn quirk(&self, value: Quirk) -> Painted<&T>

Enables the yansi Quirk value.

This method should be used rarely. Instead, prefer to use quirk-specific builder methods like mask() and wrap(), which have the same functionality but are pithier.

§Example

Enable wrapping using .quirk():

use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);

Enable wrapping using wrap().

use yansi::Paint;

painted.wrap();
source§

fn mask(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Mask.

§Example
println!("{}", value.mask());
source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Wrap.

§Example
println!("{}", value.wrap());
source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Linger.

§Example
println!("{}", value.linger());
source§

fn clear(&self) -> Painted<&T>

👎Deprecated since 1.0.1: renamed to resetting() due to conflicts with Vec::clear(). The clear() method will be removed in a future release.

Returns self with the quirk() set to Quirk::Clear.

§Example
println!("{}", value.clear());
source§

fn resetting(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Resetting.

§Example
println!("{}", value.resetting());
source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Bright.

§Example
println!("{}", value.bright());
source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::OnBright.

§Example
println!("{}", value.on_bright());
source§

fn whenever(&self, value: Condition) -> Painted<&T>

Conditionally enable styling based on whether the Condition value applies. Replaces any previous condition.

See the crate level docs for more details.

§Example

Enable styling painted only when both stdout and stderr are TTYs:

use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
source§

fn new(self) -> Painted<Self>
where Self: Sized,

Create a new Painted with a default Style. Read more
source§

fn paint<S>(&self, style: S) -> Painted<&Self>
where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
source§

impl<T> Pipe for T
where T: ?Sized,

source§

fn pipe<R>(self, func: impl FnOnce(Self) -> R) -> R
where Self: Sized,

Pipes by value. This is generally the method you want to use. Read more
source§

fn pipe_ref<'a, R>(&'a self, func: impl FnOnce(&'a Self) -> R) -> R
where R: 'a,

Borrows self and passes that borrow into the pipe function. Read more
source§

fn pipe_ref_mut<'a, R>(&'a mut self, func: impl FnOnce(&'a mut Self) -> R) -> R
where R: 'a,

Mutably borrows self and passes that borrow into the pipe function. Read more
source§

fn pipe_borrow<'a, B, R>(&'a self, func: impl FnOnce(&'a B) -> R) -> R
where Self: Borrow<B>, B: 'a + ?Sized, R: 'a,

Borrows self, then passes self.borrow() into the pipe function. Read more
source§

fn pipe_borrow_mut<'a, B, R>( &'a mut self, func: impl FnOnce(&'a mut B) -> R, ) -> R
where Self: BorrowMut<B>, B: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more
source§

fn pipe_as_ref<'a, U, R>(&'a self, func: impl FnOnce(&'a U) -> R) -> R
where Self: AsRef<U>, U: 'a + ?Sized, R: 'a,

Borrows self, then passes self.as_ref() into the pipe function.
source§

fn pipe_as_mut<'a, U, R>(&'a mut self, func: impl FnOnce(&'a mut U) -> R) -> R
where Self: AsMut<U>, U: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.as_mut() into the pipe function.
source§

fn pipe_deref<'a, T, R>(&'a self, func: impl FnOnce(&'a T) -> R) -> R
where Self: Deref<Target = T>, T: 'a + ?Sized, R: 'a,

Borrows self, then passes self.deref() into the pipe function.
source§

fn pipe_deref_mut<'a, T, R>( &'a mut self, func: impl FnOnce(&'a mut T) -> R, ) -> R
where Self: DerefMut<Target = T> + Deref, T: 'a + ?Sized, R: 'a,

Mutably borrows self, then passes self.deref_mut() into the pipe function.
source§

impl<T> Pointable for T

source§

const ALIGN: usize = _

The alignment of pointer.
source§

type Init = T

The type for initializers.
source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T, Conn> RunQueryDsl<Conn> for T

source§

fn execute<'conn, 'query>( self, conn: &'conn mut Conn, ) -> <Conn as AsyncConnection>::ExecuteFuture<'conn, 'query>
where Conn: AsyncConnection + Send, Self: ExecuteDsl<Conn> + 'query,

Executes the given command, returning the number of rows affected. Read more
source§

fn load<'query, 'conn, U>( self, conn: &'conn mut Conn, ) -> AndThen<Self::LoadFuture<'conn>, TryCollect<Self::Stream<'conn>, Vec<U>>, fn(_: Self::Stream<'conn>) -> TryCollect<Self::Stream<'conn>, Vec<U>>>
where U: Send, Conn: AsyncConnection, Self: LoadQuery<'query, Conn, U> + 'query,

Executes the given query, returning a Vec with the returned rows. Read more
source§

fn load_stream<'conn, 'query, U>( self, conn: &'conn mut Conn, ) -> Self::LoadFuture<'conn>
where Conn: AsyncConnection, U: 'conn, Self: LoadQuery<'query, Conn, U> + 'query,

Executes the given query, returning a Stream with the returned rows. Read more
source§

fn get_result<'query, 'conn, U>( self, conn: &'conn mut Conn, ) -> AndThen<Self::LoadFuture<'conn>, Map<StreamFuture<Pin<Box<Self::Stream<'conn>>>>, fn(_: (Option<Result<U, Error>>, Pin<Box<Self::Stream<'conn>>>)) -> Result<U, Error>>, fn(_: Self::Stream<'conn>) -> Map<StreamFuture<Pin<Box<Self::Stream<'conn>>>>, fn(_: (Option<Result<U, Error>>, Pin<Box<Self::Stream<'conn>>>)) -> Result<U, Error>>>
where U: Send + 'conn, Conn: AsyncConnection, Self: LoadQuery<'query, Conn, U> + 'query,

Runs the command, and returns the affected row. Read more
source§

fn get_results<'query, 'conn, U>( self, conn: &'conn mut Conn, ) -> AndThen<Self::LoadFuture<'conn>, TryCollect<Self::Stream<'conn>, Vec<U>>, fn(_: Self::Stream<'conn>) -> TryCollect<Self::Stream<'conn>, Vec<U>>>
where U: Send, Conn: AsyncConnection, Self: LoadQuery<'query, Conn, U> + 'query,

Runs the command, returning an Vec with the affected rows. Read more
source§

fn first<'query, 'conn, U>( self, conn: &'conn mut Conn, ) -> AndThen<<Self::Output as LoadQuery<'query, Conn, U>>::LoadFuture<'conn>, Map<StreamFuture<Pin<Box<<Self::Output as LoadQuery<'query, Conn, U>>::Stream<'conn>>>>, fn(_: (Option<Result<U, Error>>, Pin<Box<<Self::Output as LoadQuery<'query, Conn, U>>::Stream<'conn>>>)) -> Result<U, Error>>, fn(_: <Self::Output as LoadQuery<'query, Conn, U>>::Stream<'conn>) -> Map<StreamFuture<Pin<Box<<Self::Output as LoadQuery<'query, Conn, U>>::Stream<'conn>>>>, fn(_: (Option<Result<U, Error>>, Pin<Box<<Self::Output as LoadQuery<'query, Conn, U>>::Stream<'conn>>>)) -> Result<U, Error>>>
where U: Send + 'conn, Conn: AsyncConnection, Self: LimitDsl, Self::Output: LoadQuery<'query, Conn, U> + Send + 'query,

Attempts to load a single record. Read more
source§

impl<T> Same for T

source§

type Output = T

Should always be Self
source§

impl<T> Tap for T

source§

fn tap(self, func: impl FnOnce(&Self)) -> Self

Immutable access to a value. Read more
source§

fn tap_mut(self, func: impl FnOnce(&mut Self)) -> Self

Mutable access to a value. Read more
source§

fn tap_borrow<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Immutable access to the Borrow<B> of a value. Read more
source§

fn tap_borrow_mut<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Mutable access to the BorrowMut<B> of a value. Read more
source§

fn tap_ref<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Immutable access to the AsRef<R> view of a value. Read more
source§

fn tap_ref_mut<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Mutable access to the AsMut<R> view of a value. Read more
source§

fn tap_deref<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Immutable access to the Deref::Target of a value. Read more
source§

fn tap_deref_mut<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Mutable access to the Deref::Target of a value. Read more
source§

fn tap_dbg(self, func: impl FnOnce(&Self)) -> Self

Calls .tap() only in debug builds, and is erased in release builds.
source§

fn tap_mut_dbg(self, func: impl FnOnce(&mut Self)) -> Self

Calls .tap_mut() only in debug builds, and is erased in release builds.
source§

fn tap_borrow_dbg<B>(self, func: impl FnOnce(&B)) -> Self
where Self: Borrow<B>, B: ?Sized,

Calls .tap_borrow() only in debug builds, and is erased in release builds.
source§

fn tap_borrow_mut_dbg<B>(self, func: impl FnOnce(&mut B)) -> Self
where Self: BorrowMut<B>, B: ?Sized,

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds.
source§

fn tap_ref_dbg<R>(self, func: impl FnOnce(&R)) -> Self
where Self: AsRef<R>, R: ?Sized,

Calls .tap_ref() only in debug builds, and is erased in release builds.
source§

fn tap_ref_mut_dbg<R>(self, func: impl FnOnce(&mut R)) -> Self
where Self: AsMut<R>, R: ?Sized,

Calls .tap_ref_mut() only in debug builds, and is erased in release builds.
source§

fn tap_deref_dbg<T>(self, func: impl FnOnce(&T)) -> Self
where Self: Deref<Target = T>, T: ?Sized,

Calls .tap_deref() only in debug builds, and is erased in release builds.
source§

fn tap_deref_mut_dbg<T>(self, func: impl FnOnce(&mut T)) -> Self
where Self: DerefMut<Target = T> + Deref, T: ?Sized,

Calls .tap_deref_mut() only in debug builds, and is erased in release builds.
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> TryConv for T

source§

fn try_conv<T>(self) -> Result<T, Self::Error>
where Self: TryInto<T>,

Attempts to convert self into T using TryInto<T>. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

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

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T, U> Upcast<T> for U
where T: UpcastFrom<U>,

source§

fn upcast(self) -> T

source§

impl<T, B> UpcastFrom<Counter<T, B>> for T

source§

fn upcast_from(value: Counter<T, B>) -> T

source§

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

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more