Skip to main content
Version: 0.7.0

Examples

The crate ships twelve runnable examples in crates/confval/examples/. hcl, toml, and kdl define the same types and differ only in the format they read. The rest demonstrate one feature each, except handwritten, which runs the whole pipeline over a spec written without the derive. Each section below gives the run command. just examples runs them all.

hcl​

The hcl example renders the diagnostics for a failing variant to stderr, then feeds a valid document and prints the lowered config.

cargo run -q -p confval --example hcl --features derive,color,hcl

toml​

The toml example feeds a valid document to show the lowered config.

cargo run -q -p confval --example toml --features derive,color,toml

kdl​

The kdl example renders the diagnostics for a failing variant to stderr, then feeds a valid document, prints the lowered config, and emits the populated spec back to canonical KDL.

cargo run -q -p confval --example kdl --features derive,color,kdl

issue_severity​

The issue_severity example illustrates the difference between an error and a warning.

cargo run -q -p confval --example issue_severity --features derive,color,toml

validate_traversal​

The validate_traversal example shows what validate_all reaches.

cargo run -q -p confval --example validate_traversal --features derive,color,toml

layering​

The layering example assembles one config from a base file, a joined defaults file, the environment, and the command line.

cargo run -q -p confval --example layering --features derive,color,toml,layering

See Layering for how the sources merge and how environment and command line values are coerced.

templates​

The templates example renders a spec back to configuration text.

cargo run -q -p confval --example templates --features derive,color,toml,hcl

The spec populates with its defaults and emits twice per format, once plain and once as a template with each field's doc comment above it. The unset optional pid_file stays out of the plain form and renders in the template as a commented-out entry.

See Templates for how to_fields, to_template, and the emitters fit together.

doc_fallback​

The doc_fallback example shows where a template block's comment comes from.

cargo run -q -p confval --example doc_fallback --features derive,toml

json_diagnostics​

The json_diagnostics example renders a report as JSON for CI and tooling.

cargo run -q -p confval --example json_diagnostics --features derive,serde,toml

narrow​

The narrow example shows the ready-made narrowing helpers that convert spec integers to the widths a runtime type needs. It exercises five of them. The remaining integer widths and their opt_ variants share the same shape.

cargo run -q -p confval --example narrow --features derive,color,toml

representations​

The representations example prints the three views of one loaded spec: the source view of what was set, the populated view after defaults, and the runtime view of the lowered values.

cargo run -q -p confval --example representations --features derive,serde,toml

handwritten​

The handwritten example writes a spec without the derive, for a block whose mode field decides which fields the rest of the block has. Each level of its tree is written the other way from the level above: the root is handwritten, its children are derived, and the tls block inside a derived route is handwritten again. It prints the diagnostics, the runtime config, the populated and source views, the comments a handwritten node drops from a template, and the same model in HCL.

cargo run -q -p confval --example handwritten --features derive,color,toml,hcl

Additional Examples​

Additional examples are available for reference: