Trait figment::providers::Format

pub trait Format: Sized {
    type Error: Error;

    const NAME: &'static str;

    // Required method
    fn from_str<'de, T: DeserializeOwned>(
        string: &'de str
    ) -> Result<T, Self::Error>;

    // Provided methods
    fn file<P: AsRef<Path>>(path: P) -> Data<Self> { ... }
    fn string(string: &str) -> Data<Self> { ... }
    fn from_path<T: DeserializeOwned>(path: &Path) -> Result<T, Self::Error> { ... }
}

Trait implementable by text-based Data format providers.

Instead of implementing Provider directly, types that refer to data formats, such as [Json] and Toml, implement this trait. By implementing Format, they become Providers indirectly via the Data type, which serves as a provider for all T: Format.

use figment::providers::Format;

// If `T` implements `Format`, `T` is a `Provider`.
// Initialize it with `T::file()` or `T::string()`.
let provider = T::file("foo.fmt");
let provider = T::string("some -- format");

Implementing

There are two primary implementation items:

1. Format::NAME: This should be the name of the data format: "JSON" or "TOML". The string is used in the [metadata for Data].

2. Format::from_str(): This is the core string deserialization method. A typical implementation will simply call an existing method like toml::from_str. For writing a custom data format, see serde’s writing a data format guide.

The default implementations for Format::from_path(), Format::file(), and Format::string() methods should likely not be overwritten.

Required Associated Types

type Error: Error

The data format’s error type.

Required Associated Constants

const NAME: &'static str

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

Required Methods

fn from_str<'de, T: DeserializeOwned>( string: &'de str ) -> Result<T, Self::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.

Provided 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.

Implementors

impl Format for Toml

type Error = Error

const NAME: &'static str = "TOML"