Struct figment::providers::YamlExtended

pub struct YamlExtended;

Available on crate feature yaml only.

A YAML Extended Format Data provider.

Static constructor methods on YamlExtended return a Data value with a generic marker of YamlExtended. Thus, further use occurs via methods on Data.

use figment::providers::{Format, YamlExtended};

// Source directly from a source string...
let provider = YamlExtended::string("source-string");

// Or read from a file on disk.
let provider = YamlExtended::file("path-to-file");

// Or configured as nested (via Data::nested()):
let provider = YamlExtended::file("path-to-file").nested();

See also YamlExtended::from_str for parsing details.

Implementations

impl YamlExtended

pub fn from_str<'de, T: DeserializeOwned>(s: &'de str) -> Result<T>

This “YAML Extended” format parser implements the draft “Merge Key Language-Independent Type for YAML™ Version 1.1” spec via serde_yaml::Value::apply_merge(). This method is not intended to be used directly but rather indirectly by making use of YamlExtended as a provider. The extension is not part of any officially supported YAML release and is deprecated entirely since YAML 1.2. Using YamlExtended instead of Yaml enables merge keys, allowing YAML like the following to parse with key merges applied:

tasks:
  build: &webpack_shared
    command: webpack
    args: build
    inputs:
      - 'src/**/*'
  start:
    <<: *webpack_shared
    args: start

Example

use serde::Deserialize;
use figment::{Figment, Jail, providers::{Format, Yaml, YamlExtended}};

#[derive(Debug, PartialEq, Deserialize)]
struct Circle {
    x: usize,
    y: usize,
    r: usize,
}

#[derive(Debug, PartialEq, Deserialize)]
struct Config {
    circle1: Circle,
    circle2: Circle,
    circle3: Circle,
}

Jail::expect_with(|jail| {
    jail.create_file("Config.yaml", r#"
        point: &POINT { x: 1, y: 2 }
        radius: &RADIUS
          r: 10

        circle1:
          <<: *POINT
          r: 3

        circle2:
          <<: [ *POINT, *RADIUS ]

        circle3:
          <<: [ *POINT, *RADIUS ]
          y: 14
          r: 20
    "#)?;

    let config: Config = Figment::from(YamlExtended::file("Config.yaml")).extract()?;
    assert_eq!(config, Config {
        circle1: Circle { x: 1, y: 2, r: 3 },
        circle2: Circle { x: 1, y: 2, r: 10 },
        circle3: Circle { x: 1, y: 14, r: 20 },
    });

    // Note that just `Yaml` would fail, since it doesn't support merge.
    let config = Figment::from(Yaml::file("Config.yaml"));
    assert!(config.extract::<Config>().is_err());

    Ok(())
});

Trait Implementations

impl Format for YamlExtended

type Error = Error

The data format’s error type.

const NAME: &'static str = "YAML Extended"

The name of the data format, for instance "JSON" or "TOML".

fn from_str<'de, T: DeserializeOwned>(s: &'de str) -> Result<T, Error>

Parses string as the data format Self as a T or returns an error if the string is an invalid T. Note: This method is not intended to be called directly. Instead, it is intended to be implemented and then used indirectly via the Data::file() or Data::string() methods.

fn file<P: AsRef<Path>>(path: P) -> Data<Self>

Returns a Data provider that sources its values by parsing the file at path as format Self. See Data::file() for more details. The default implementation calls Data::file(path).

fn string(string: &str) -> Data<Self>

Returns a Data provider that sources its values by parsing string as format Self. See Data::string() for more details. The default implementation calls Data::string(string).

fn from_path<T: DeserializeOwned>(path: &Path) -> Result<T, Self::Error>

Parses the file at path as the data format Self as a T or returns an error if the string is an invalid T. The default implementation calls Format::from_str() with the contents of the file. Note: This method is not intended to be called directly. Instead, it is intended to be implemented on special occasions and then used indirectly via the Data::file() or Data::string() methods.