Struct Source 

pub struct Source<'a> { /* private fields */ }

One layer of configuration.

Constructors are const, so a &'static [Source<'static>] can live in a static — which is how the macro emits it. The lifetime is there for everything else: configuration assembled at runtime, fetched over the network, or read from a pipe borrows just as happily.

Implementations

impl<'a> Source<'a>

pub const fn file(path: &'a str, format: Format) -> Self

A file on disk. A file that does not exist is skipped, not an error — listing an optional secrets.toml is the whole point of layering.

pub const fn inline(text: &'a str, format: Format) -> Self

Configuration already in memory: a compiled-in default, a fixture, or something just read off a socket.

figment parses from a string, so anything implementing Read arrives here through std::io::read_to_string rather than through a variant of its own — a reader source would only hide that one line.

use dynamic_config::{load, Format, LoadSpec, Source};
use serde::Deserialize;

#[derive(Deserialize)]
struct Db { host: String }

let mut pipe = std::io::Cursor::new(r#"{"db": {"host": "localhost"}}"#);
let text = std::io::read_to_string(&mut pipe).unwrap();

let sources = [Source::inline(&text, Format::Json)];
let db: Db = load(&LoadSpec::new("db", &sources)).unwrap();

assert_eq!(db.host, "localhost");

pub const fn provider(provider: &'a (dyn Provider + Send + Sync)) -> Self

Available on crate feature figment only.

Configuration from a figment provider of your own.

The three built-in kinds — a file, an encrypted file, inline text — are the ones this crate can describe. A provider is anything figment can read: Serialized::defaults(T), an Env with a filter this crate does not model, a provider you wrote, one from another crate.

use dynamic_config::{load, LoadSpec, Source};
use figment::providers::{Format as _, Json};

// `.nested()` because this crate reads a top-level key as a section.
let provider = Json::string(r#"{"db": {"host": "localhost"}}"#).nested();
let sources = [Source::provider(&provider)];

let db: Db = load(&LoadSpec::new("db", &sources)).unwrap();
assert_eq!(db.host, "localhost");

Two things it is on you to get right

Sections. Every other source here goes through this crate’s own mapping of top-level keys to sections. A provider does not: what it yields is merged as figment sees it, so it has to produce the section as a profile — .nested() on a figment Data provider does exactly that.

Provenance. source_of and every error report the provider’s own metadata name. A provider that describes itself badly produces a diagnostic that describes it badly.

The Send + Sync bound is not decoration: a LoadSpec is moved to another thread by load_async and by the file watcher, so a provider that cannot cross one would take those with it. Every provider figment ships already satisfies it.

pub const fn format(&self) -> Option<Format>

This source’s format, for the kinds that parse text.

None for a provider, which hands over values that are already figment’s and never sees a byte of text.

pub const fn encrypted(path: &'a str, format: Format) -> Self

Configuration in a file that is encrypted on disk.

format is what the plaintext is, so secrets.json.age is Format::Json. Reading it needs a decryptor installed with set_decryptor.

In every other respect it is a file: same precedence, same profile variants, watched the same way, skipped if it is not there.

pub const fn path(&self) -> Option<&'a str>

The file path, if this source is a file — encrypted or not.

Encrypted files are included because everything that asks this question — profile variants, the directories to watch — wants the same answer for both.

pub const fn is_encrypted(&self) -> bool

Whether this source has to be decrypted before it can be parsed.

Trait Implementations

impl<'a> Clone for Source<'a>

fn clone(&self) -> Source<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Copy for Source<'a>

impl Debug for Source<'_>

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

Formats the value using the given formatter.