Module env_config 

Declarative, attribute-driven per-environment configuration: EnvConfig, ConfigSource, and the #[derive(EnvConfig)] macro’s runtime support. Declarative, attribute-driven per-environment configuration.

An EnvConfig struct describes, per field, where to find its value — a TOML key, an opt-in environment-variable suffix, a literal or computed default, and (when the defaults don’t fit) a custom conversion function for either raw form. #[derive(EnvConfig)] generates the wiring; see docs/environments.md for the attribute grammar and crate::environments::Environments::resolve for the common way to build a SourceChain and assemble a struct from it.

Why toml::Value, and why it’s exposed directly

Every source except an environment variable represents its values as toml::Value/toml::Table — not a cli_engine-owned wrapper type. Deliberate, not incidental:

• The file layer (environments.toml) genuinely is TOML; parsing it already produces a toml::Table.
• Compiled-in and in-memory sources (crate::environments::EnvTable, ValueSource) use that same representation so they merge with the file layer key-by-key with no translation between “code-supplied” and “file-supplied” shapes, and so a field’s default conversion (default_from_toml) can lean on toml::Value’s own serde::Deserialize impl — a TOML array becomes a Vec<String> natively, a TOML table becomes a nested struct, with no per-field stringly-typed detour.
• An environment variable is the one genuine exception: it’s always a plain String (an OS-level constraint, not a design choice), so ConfigSource::env_var returns Option<String>, never Option<toml::Value>, and a field’s from_env conversion is always a separate function from its from_toml conversion.

Using toml::Value/toml::Table directly, instead of hiding them behind a cli_engine-owned newtype, means they’re part of this crate’s public API — and a consumer whose toml::Value came from its own direct dependency, rather than this re-export, would need that dependency on the same major version as this crate’s, or the two crates’ toml::Value types are different, incompatible types despite sharing a name. #[derive(EnvConfig)]-generated code always goes through crate::env_config::toml rather than a bare toml:: path for exactly this reason, so the common case (no custom from_toml/to_toml) needs no direct toml dependency in the consumer at all. A consumer writing a custom from_toml/to_toml function or calling ValueSource::with directly should do the same — cli_engine::env_config::toml::Value, not its own toml dependency’s toml::Value — to get the same guarantee.

Re-exports

pub use toml;

Structs

EnvSource

One environment’s source: its name and its merged TOML table (compiled-in table overlaid by the environments.toml file table). Purely a TOML lookup; env-var overrides are handled by a separate EnvVarSource pushed alongside it — see crate::environments::Environments::resolve.

EnvVarSource

A source that only ever answers environment-variable lookups, under a fixed prefix — the app id for the common case.

SourceChain

An ordered chain of ConfigSources. Assembly walks the chain in order; within one source its env var is checked before its TOML value; the first source to answer either wins for that field. Build one with SourceChain::new and SourceChain::push, then pass it to EnvConfig::assemble.

ValueSource

A source backed by values a consumer already has in hand — for example a provider’s own constructor arguments, used as a last-resort fallback tier.

Enums

EnvConfigError

An error assembling an EnvConfig struct.

Traits

ConfigSource

Something a field’s assembly instructions can be checked against: “do you have a TOML-shaped value for this key” and “do you have a string value for an env var with this suffix.” EnvConfig::assemble walks a whole SourceChain of these, in priority order, so more than one kind of fallback source can contribute to the same struct.

EnvConfig

A struct that can be assembled from a SourceChain — implemented by #[derive(EnvConfig)].

Functions

default_from_env

Default string-to-T conversion used when a field has no from_env attribute: T must implement std::str::FromStr.

default_from_toml

Default TOML-to-T conversion used when a field has no from_toml attribute: T must be serde::de::DeserializeOwned.

resolve_field

Walks sources looking for a value for one field: within a source, its env var (if env_suffix is given) is checked before its TOML value; the first source to answer either wins. Returns Ok(None) when no source has the field at all, letting the caller apply a default.

Derive Macros

EnvConfig