Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Nesting

Config structs can easily be nested within other Configs using the #[setting(nested)] attribute. Children will be deeply merged and validated alongside the parent.

#![allow(unused)]
fn main() {
#[derive(Config)]
struct ChildConfig {
	// ...
}

#[derive(Config)]
struct ParentConfig {
	#[setting(nested)]
	pub nested: ChildConfig,

	#[setting(nested)]
	pub optional_nested: Option<ChildConfig>,
}

#[derive(Config)]
enum ParentEnum {
	#[setting(nested)]
	Variant(ChildConfig),
}
}

The #[setting(nested)] attribute is required, as the macro will substitute Config with its partial implementation.

Nested values can also be wrapped in collections, like Vec and HashMap. Each item is finalized and validated as a nested config, but the collection is replaced when merged, rather than merging its items. To merge a map of configs by key, use the merge_partials strategy.

A #[setting(nested)] on a variant applies to every value it holds. To hold a nested config alongside plain values, mark the value itself instead. Its config is merged, finalized, and validated as nested, while the other values are replaced, like any other setting.

#![allow(unused)]
fn main() {
#[derive(Config)]
enum ParentEnum {
	Both(#[setting(nested)] ChildConfig, bool),
}
}

Flattening

A nested config can be flattened with #[setting(flatten, nested)] (or serde’s own #[serde(flatten)]), so its settings are written alongside the parent’s own, rather than under the field’s name. A map can be flattened too, which collects every key the other settings don’t.

#![allow(unused)]
fn main() {
#[derive(Config)]
struct ParentConfig {
	pub name: String,

	#[setting(flatten, nested)]
	pub server: ServerConfig,

	#[setting(flatten, nested)]
	pub plugins: HashMap<String, PluginConfig>,
}
}

A config rejects keys that aren’t its settings, unless #[config(allow_unknown_fields)], and serde can only do so for a flattened struct, which takes its keys from the parent’s. So:

  • A config with a flattened map accepts unknown keys, as the map collects them, and rejecting them would reject every key of the map.
  • A flattened config that flattens another can’t be loaded unless both allow unknown fields, as it reads the parent’s keys without taking them, so the parent would reject them. Deriving one fails to compile, naming the fix, rather than failing to load every setting it holds.
#![allow(unused)]
fn main() {
#[derive(Config)]
#[config(allow_unknown_fields)]
struct ServerConfig {
	#[setting(flatten, nested)]
	pub tls: TlsConfig,
}
}

Bare structs

For structs that do not implement the Config trait, you can use them as-is without the #[setting(nested)] attribute. When using bare structs, be aware that all of the functionality provided by our Config trait is not available, like merging and validation.

#![allow(unused)]
fn main() {
struct BareConfig {
	// ...
}

#[derive(Config)]
pub struct ParentConfig {
	pub nested: BareConfig,
}
}