Struct figment::value::magic::RelativePathBuf

pub struct RelativePathBuf { /* fields omitted */ }

This is supported on crate feature magic only.

A PathBuf that knows the path of the file it was configured in, if any.

Paths in configuration files are often desired to be relative to the configuration file itself. For example, a path of a/b.html configured in a file /var/config.toml might be desired to resolve as /var/a/b.html. This type makes this possible by simply delcaring the configuration value's type as RelativePathBuf.

Example

use std::path::Path;

use serde::Deserialize;
use figment::{Figment, value::magic::RelativePathBuf, Jail};
use figment::providers::{Env, Format, Toml};

#[derive(Debug, PartialEq, Deserialize)]
struct Config {
    path: RelativePathBuf,
}

Jail::expect_with(|jail| {
    // When a path is declared in a file and deserialized as
    // `RelativePathBuf`, `relative()` will be relative to the file.
    jail.create_file("Config.toml", r#"path = "a/b/c.html""#)?;
    let c: Config = Figment::from(Toml::file("Config.toml")).extract()?;
    assert_eq!(c.path.original(), Path::new("a/b/c.html"));
    assert_eq!(c.path.relative(), jail.directory().join("a/b/c.html"));

    // If a path is declared elsewhere, the "relative" path is the original.
    jail.set_env("PATH", "a/b/c.html");
    let c: Config = Figment::from(Toml::file("Config.toml"))
        .merge(Env::raw().only(&["PATH"]))
        .extract()?;

    assert_eq!(c.path.original(), Path::new("a/b/c.html"));
    assert_eq!(c.path.relative(), Path::new("a/b/c.html"));

    // Absolute paths remain unchanged.
    jail.create_file("Config.toml", r#"path = "/var/c.html""#);
    let c: Config = Figment::from(Toml::file("Config.toml")).extract()?;
    assert_eq!(c.path.original(), Path::new("/var/c.html"));
    assert_eq!(c.path.relative(), Path::new("/var/c.html"));

    Ok(())
});

Implementations

impl RelativePathBuf

pub fn original(&self) -> &Path

This is supported on crate feature magic only.

Returns the path as it was declared, without modification.

Example

use std::path::Path;

use figment::{Figment, value::magic::RelativePathBuf, Jail};
use figment::providers::{Format, Toml};

#[derive(Debug, PartialEq, serde::Deserialize)]
struct Config {
    path: RelativePathBuf,
}

Jail::expect_with(|jail| {
    jail.create_file("Config.toml", r#"path = "hello.html""#)?;
    let c: Config = Figment::from(Toml::file("Config.toml")).extract()?;
    assert_eq!(c.path.original(), Path::new("hello.html"));

    Ok(())
});

pub fn relative(&self) -> PathBuf

This is supported on crate feature magic only.

Returns this path relative to the file it was delcared in, if any. Returns the original if this path was not declared in a file or if the path has a root.

Example

use std::path::Path;

use figment::{Figment, value::magic::RelativePathBuf, Jail};
use figment::providers::{Env, Format, Toml};

#[derive(Debug, PartialEq, serde::Deserialize)]
struct Config {
    path: RelativePathBuf,
}

Jail::expect_with(|jail| {
    jail.create_file("Config.toml", r#"path = "hello.html""#)?;
    let c: Config = Figment::from(Toml::file("Config.toml")).extract()?;
    assert_eq!(c.path.relative(), jail.directory().join("hello.html"));

    jail.set_env("PATH", r#"hello.html"#);
    let c: Config = Figment::from(Env::raw().only(&["PATH"])).extract()?;
    assert_eq!(c.path.relative(), Path::new("hello.html"));

    Ok(())
});

pub fn metadata_path(&self) -> Option<&Path>

This is supported on crate feature magic only.

Returns the path to the file this path was declared in, if any.

Example

use std::path::Path;

use figment::{Figment, value::magic::RelativePathBuf, Jail};
use figment::providers::{Env, Format, Toml};

#[derive(Debug, PartialEq, serde::Deserialize)]
struct Config {
    path: RelativePathBuf,
}

Jail::expect_with(|jail| {
    jail.create_file("Config.toml", r#"path = "hello.html""#)?;
    let c: Config = Figment::from(Toml::file("Config.toml")).extract()?;
    assert_eq!(c.path.metadata_path().unwrap(), jail.directory().join("Config.toml"));

    jail.set_env("PATH", r#"hello.html"#);
    let c: Config = Figment::from(Env::raw().only(&["PATH"])).extract()?;
    assert_eq!(c.path.metadata_path(), None);

    Ok(())
});

Trait Implementations

impl Clone for RelativePathBuf

fn clone(&self) -> RelativePathBuf

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for RelativePathBuf

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for RelativePathBuf

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<P: AsRef<Path>> From<P> for RelativePathBuf

fn from(path: P) -> RelativePathBuf

Performs the conversion.

impl Magic for RelativePathBuf

const NAME: &'static str

const FIELDS: &'static [&'static str]

fn deserialize_from<'de: 'c, 'c, V: Visitor<'de>>(
    de: ConfiguredValueDe<'c>,
    visitor: V
) -> Result<V::Value, Error>

impl PartialEq<RelativePathBuf> for RelativePathBuf

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Serialize for RelativePathBuf

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error> where
    __S: Serializer, 

Serialize this value into the given Serde serializer.