Struct LoadSpec 

pub struct LoadSpec<'a> {

    pub key: &'a str,
    pub sources: &'a [Source<'a>],
    pub env_prefix: Option<&'a str>,
    pub search: Option<Search<'a>>,
    pub profile_env: Option<&'a str>,
    pub defaults: Option<&'a Layer>,
    pub remote: Option<&'a Remote>,
    pub secrets_dir: Option<&'a str>,
    pub env_files: &'a [&'a str],
    pub aliases: Option<&'a Aliases>,
    pub env_bindings: Option<&'a EnvBindings>,
    pub flags: Option<&'a Layer>,
    pub overrides: Option<&'a Layer>,
    pub nest: &'a str,
    pub allow_empty_env: bool,
    pub strict_env: bool,
    pub whole_document: bool,
}

Everything the loader needs: which layers, which section, which env prefix.

Prefer new and the with_* methods over a struct literal, so that a later release can add a knob without breaking every call site.

Fields

key: &'a str

The configuration section this maps to, e.g. "db".

sources: &'a [Source<'a>]

Layers, merged left to right. Later sources win.

env_prefix: Option<&'a str>

Environment variable prefix, e.g. "APP_". Combined with key. None ignores the environment entirely.

search: Option<Search<'a>>

Where to look for configuration files by name, if anywhere.

Discovered files are merged before sources, so an explicitly listed file still has the last word.

profile_env: Option<&'a str>

Environment variable naming the active profile, e.g. "APP_ENV".

When it is set to production, every file gains a sibling layer: config.toml is followed by config.production.toml, discovered or listed alike. A variant that does not exist is skipped like any other missing file.

defaults: Option<&'a Layer>

Values below the files: consulted only when nothing else supplies a key.

remote: Option<&'a Remote>

A document fetched from a remote store: above the files, below the environment.

secrets_dir: Option<&'a str>

A directory of single-value files — one file per key, the filename is the key, the contents are the value.

How Docker and Kubernetes mount secrets. Nesting is spelled in the filename with nest, so one setting governs this layer and the environment alike; a directory that is not there is skipped like a missing file.

env_files: &'a [&'a str]

.env files, read as the environment layer rather than as documents.

Merged in order, just below the real environment: a variable somebody exported for this run should beat a file in the repository.

aliases: Option<&'a Aliases>

Old key paths that still resolve, filling a gap rather than overriding.

env_bindings: Option<&'a EnvBindings>

Fields bound to environment variables by name: just above the prefixed environment layer, because a binding is the more specific statement.

flags: Option<&'a Layer>

Values from the command line: above the environment, below overrides.

overrides: Option<&'a Layer>

Values above everything, including the environment.

nest: &'a str

Separator that introduces nesting in an environment variable name.

Defaults to "__", so APP_DB_POOL__MAX_SIZE is pool.max_size. A single separator cannot mean both “word break” and “nesting”, so whatever this is set to, it has to be something a field name will not contain.

allow_empty_env: bool

Whether FOO= counts as set-to-empty.

Defaults to false, which treats it as unset. An unset value rendered into a deployment template leaves exactly FOO=, and letting that blank out a perfectly good configured value is a bad afternoon. Turn it on when empty really is a value you need to be able to send.

strict_env: bool

Rejects environment values from the yes/no/on/off family instead of letting them arrive as strings where a boolean was meant.

whole_document: bool

Whether the documents this reads carry a section header at all.

false — the default — means every top-level key in a document is a section, which is what lets one file serve several configuration types and what key selects out of it.

true means the document is this section’s values — {"host": "0.0.0.0", "port": 8000}, with no server above it. The key still names the load: the environment prefix, the cache entry and what a diagnostic calls this configuration are all still built from it. It simply stops being looked for inside the document. See with_whole_document.

Implementations

impl<'a> LoadSpec<'a>

pub const fn new(key: &'a str, sources: &'a [Source<'a>]) -> Self

A spec that reads sources and selects key, ignoring the environment.

pub const fn with_search(self, name: &'a str, paths: &'a [&'a str]) -> Self

Looks for {name}.{ext} in each of paths, in order.

Every directory that has a match contributes one file, so the search order is the layering order. Discovered files sit below the explicit sources.

pub const fn with_profile_env(self, variable: &'a str) -> Self

Layers a per-profile sibling over every file.

variable names the environment variable holding the profile, so the profile itself is resolved at load time rather than baked in.

pub const fn with_defaults(self, layer: &'a Layer) -> Self

Values consulted only when no file and no variable supplies a key.

pub const fn with_env_files(self, files: &'a [&'a str]) -> Self

.env files, merged just below the real environment.

Needs the dotenv feature; without it, a non-empty list is an error at load time naming the feature rather than a list silently ignored.

pub const fn with_aliases(self, aliases: &'a Aliases) -> Self

Old key paths that still resolve.

pub const fn with_env_bindings(self, bindings: &'a EnvBindings) -> Self

Fields bound to environment variables by name.

pub const fn with_remote(self, remote: &'a Remote) -> Self

A remote store’s document, layered over the files.

pub const fn with_secrets_dir(self, path: &'a str) -> Self

A directory of single-value files, layered just below the .env files and the environment.

One directory level: every regular file in it is one key, named by the file and valued by its contents with a single trailing newline removed. Subdirectories are not descended into — nesting is spelled in the filename with with_nest, which is what a Kubernetes mount produces anyway.

pub const fn with_flags(self, layer: &'a Layer) -> Self

Values from the command line, layered over the environment.

pub const fn with_overrides(self, layer: &'a Layer) -> Self

Values that win over the files, the environment and the flags alike.

pub const fn with_env(self, prefix: &'a str) -> Self

Layers environment variables named {prefix}{KEY}_* over the files.

pub const fn with_nest(self, separator: &'a str) -> Self

Uses separator instead of __ to introduce nesting.

pub const fn with_empty_env(self, allow: bool) -> Self

Treats FOO= as set-to-empty rather than unset.

pub const fn with_strict_env(self, strict: bool) -> Self

Rejects ambiguous environment spellings instead of guessing.

APP_DB_TLS=off reads like a boolean and arrives as the string "off" — silently correct into a String field, silently wrong everywhere else. Strict mode makes the yes/no/on/off family (and null/nil/none) an error naming the variable; write true, false, or the value you actually mean.

pub const fn with_whole_document(self, whole: bool) -> Self

Reads each document as this section’s values, with no section header.

The default layout is one file, several sections: every top-level key names one, and key says which is yours. That is what lets a config.toml hold [db] and [server] for two configuration types that know nothing about each other.

A file that is only this configuration has no use for the header, and a file this crate did not write may not have one to begin with — a container image’s {"host": "0.0.0.0", "port": 8000}, a chart’s rendered values, a file some other tool owns. This says so.

Everything else is unchanged, and that is the point: the environment prefix is still {prefix}{KEY}_, profile variants (config.production.toml) still layer on top, defaults, flags, overrides, aliases, the secrets directory, the cache and every diagnostic all behave exactly as they do for a sectioned load. Only where a document’s values are found changes.

It applies to every document this spec reads — listed files, discovered files, inline text and the remote store’s document — because a load whose sources disagreed about their own shape would be a load nobody could reason about.

Trait Implementations

impl<'a> Clone for LoadSpec<'a>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Copy for LoadSpec<'a>

impl Debug for LoadSpec<'_>

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

Formats the value using the given formatter.