Trait Format

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 file_exact<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 { ... }
}

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 Constants

const NAME: &'static str

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

Required Associated Types

type Error: Error

The data format’s error type.

Required Methods

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

where T: DeserializeOwned,

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 file_exact<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_exact() for more details. The default implementation calls Data::file_exact(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>

where T: DeserializeOwned,

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.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl Format for Toml

const NAME: &'static str = "TOML"

type Error = Error