pub struct RelativePathBuf { /* private fields */ }
Expand description

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, Serialize};
use figment::{Figment, value::magic::RelativePathBuf, Jail};
use figment::providers::{Env, Format, Toml, Serialized};

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

Jail::expect_with(|jail| {
    // Note that `jail.directory()` is some non-empty path:
    assert_ne!(jail.directory(), Path::new("/"));

    // 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"));
    assert_ne!(c.path.relative(), Path::new("a/b/c.html"));

    // Round-tripping a `RelativePathBuf` preserves path-relativity.
    let c: Config = Figment::from(Serialized::defaults(&c)).extract()?;
    assert_eq!(c.path.original(), Path::new("a/b/c.html"));
    assert_eq!(c.path.relative(), jail.directory().join("a/b/c.html"));
    assert_ne!(c.path.relative(), Path::new("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"));

    // You can use the `From<P: AsRef<Path>>` impl to set defaults:
    let figment = Figment::from(Serialized::defaults(Config {
        path: "some/default/path".into()
    }));

    let default: Config = figment.extract()?;
    assert_eq!(default.path.original(), Path::new("some/default/path"));
    assert_eq!(default.path.relative(), Path::new("some/default/path"));

    jail.create_file("Config.toml", r#"path = "an/override""#)?;
    let overriden: Config = figment.merge(Toml::file("Config.toml")).extract()?;
    assert_eq!(overriden.path.original(), Path::new("an/override"));
    assert_eq!(overriden.path.relative(), jail.directory().join("an/override"));

    Ok(())
});

Serialization

By default, a RelativePathBuf serializes into a structure that can only deserialize as a RelativePathBuf. In particular, a RelativePathBuf does not serialize into a value compatible with PathBuf. To serialize into a Path, use RelativePathBuf::serialize_original() or RelativePathBuf::serialize_relative() together with serde’s serialize_with field attribute:

use std::path::PathBuf;

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

#[derive(Deserialize, Serialize)]
struct Config {
    relative: RelativePathBuf,
    #[serde(serialize_with = "RelativePathBuf::serialize_original")]
    root: RelativePathBuf,
    #[serde(serialize_with = "RelativePathBuf::serialize_relative")]
    temp: RelativePathBuf,
}

Jail::expect_with(|jail| {
    jail.create_file("Config.toml", r#"
        relative = "relative/path"
        root = "root/path"
        temp = "temp/path"
    "#)?;

    // Create a figment with a serialize `Config`.
    let figment = Figment::from(Toml::file("Config.toml"));
    let config = figment.extract::<Config>()?;
    let figment = Figment::from(Serialized::defaults(config));

    // This fails, as expected.
    let relative = figment.extract_inner::<PathBuf>("relative");
    assert!(relative.is_err());

    // These succeed. This one uses the originally written path.
    let root = figment.extract_inner::<PathBuf>("root")?;
    assert_eq!(root, PathBuf::from("root/path"));

    // This one the magic relative path.
    let temp = figment.extract_inner::<PathBuf>("temp")?;
    assert_eq!(temp, jail.directory().join("temp/path"));

    Ok(())
})

Implementations§

source§

impl RelativePathBuf

source

pub fn original(&self) -> &Path

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

pub fn relative(&self) -> PathBuf

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

If the configured path was relative and it was configured from a file, this function returns that path prefixed with that file’s parent directory. Otherwise it returns the original path. Where config_file_path is the location of the configuration file, this corresponds to:

let relative = config_file_path
    .parent()
    .unwrap()
    .join(relative_path_buf.original());
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(())
});
source

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

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

pub fn serialize_original<S>(&self, ser: S) -> Result<S::Ok, S::Error>where S: Serializer,

Serialize self as the original path.

See serialization for more.

Example
use std::path::PathBuf;
use figment::value::magic::RelativePathBuf;
use serde::Serialize;

#[derive(Serialize)]
struct Config {
    #[serde(serialize_with = "RelativePathBuf::serialize_original")]
    path: RelativePathBuf,
}
source

pub fn serialize_relative<S>(&self, ser: S) -> Result<S::Ok, S::Error>where S: Serializer,

Serialize self as the relative path.

See serialization for more.

Example
use std::path::PathBuf;
use figment::value::magic::RelativePathBuf;
use serde::Serialize;

#[derive(Serialize)]
struct Config {
    #[serde(serialize_with = "RelativePathBuf::serialize_relative")]
    path: RelativePathBuf,
}

Trait Implementations§

source§

impl Clone for RelativePathBuf

source§

fn clone(&self) -> RelativePathBuf

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 RelativePathBuf

source§

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

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

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

source§

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

Deserialize this value from the given Serde deserializer. Read more
source§

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

source§

fn from(path: P) -> RelativePathBuf

Converts to this type from the input type.
source§

impl PartialEq<RelativePathBuf> for RelativePathBuf

source§

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

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Serialize for RelativePathBuf

source§

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

Serialize this value into the given Serde serializer. Read more
source§

impl Magic for RelativePathBuf

Auto Trait Implementations§

Blanket Implementations§

source§

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

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

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

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

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

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere 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> Paint for Twhere 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>

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

Example
println!("{}", value.clear());
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> ToOwned for Twhere T: Clone,

§

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, U> TryFrom<U> for Twhere U: Into<T>,

§

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 Twhere U: TryFrom<T>,

§

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> DeserializeOwned for Twhere T: for<'de> Deserialize<'de>,