pub trait Format: Sized {
    type Error: Error;

    const NAME: &'static str;

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

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

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>(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>(path: P) -> Data<Self>
where P: AsRef<Path>,

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

Object Safety§

This trait is not object safe.

Implementors§

§

impl Format for Toml

§

type Error = Error

§

const NAME: &'static str = "TOML"