Crate miniconf

Expand description

§miniconf

miniconf turns selected values inside heterogeneous Rust data into a small runtime-addressable tree. It is no_std by default, uses Serde for leaf payloads, and lets the same settings type serve human tools, compact embedded links, generated schemas, and transport protocols.

Use it when a typed Rust configuration or state tree should be:

accessed one leaf at a time by path or compact key
exposed over a transport without giving that transport ownership of the data
discovered by tools through schema iteration, semantics, and metadata
reused across CLIs, SCPI-like protocols, MQTT, tests, or generated UI/API surfaces

§Quick Start

Derive Tree for the settings type. Fields whose types also implement the Tree* traits become internal nodes; ordinary Serde values are leaves.

use miniconf::{json_core, Tree};

#[derive(Default, Tree)]
struct Settings {
    enabled: bool,
    output: Output,
}

#[derive(Default, Tree)]
struct Output {
    gain: [u16; 2],
}

let mut settings = Settings::default();

json_core::set(&mut settings, "/enabled", b"true").unwrap();
json_core::set(&mut settings, "/output/gain/1", b"42").unwrap();

let mut buf = [0; 8];
let len = json_core::get(&settings, "/output/gain/1", &mut buf).unwrap();

assert!(settings.enabled);
assert_eq!(&buf[..len], b"42");

§Pick The Surface

Start with json_core and slash-separated &str paths for human-facing tools, tests, and protocol sketches. The lower layers are useful when the boundary needs something more specific:

TreeSchema and Schema::nodes() discover leaves; Schema::get() checks one exact key and returns the reached schema.
TreeSerialize and TreeDeserialize serialize or update exactly one selected leaf with any Serde format.
TreeAny gives typed host-side access through core::any::Any.
PathIter, ConstPathIter, JsonPathIter, index slices, and Packed are interchangeable key boundaries through IntoKeys.
postcard with Packed gives compact binary key-value messages.
json_schema builds host/tooling schemas from the same tree.
miniconf_mqtt is the ready-made MQTT transport.

§Tree Shape

Tree is a derive shorthand for TreeSchema, TreeSerialize, TreeDeserialize, and TreeAny. Derive attributes live under #[tree(...)]:

rename = ident changes a field or variant path segment to a Rust identifier.
skip removes a field or variant from the tree.
flatten splices a single unambiguous child tree into its parent.
with = module delegates access to a custom implementation module.
meta(...) attaches schema metadata when the matching metadata feature is enabled.

Use #[tree(with = leaf)] to keep a type as one Serde leaf even if it also implements Tree.

use miniconf::{json_core, leaf, Tree};
use serde::{Deserialize, Serialize};

#[derive(Default, Serialize, Deserialize)]
struct Calibration {
    offset: i32,
    scale: u16,
}

#[derive(Default, Tree)]
struct Settings {
    #[tree(rename = "cal", with = leaf)]
    calibration: Calibration,
}

let mut settings = Settings::default();
json_core::set(&mut settings, "/cal", br#"{"offset":-3,"scale":10}"#).unwrap();
assert_eq!(settings.calibration.offset, -3);

Structs, enums, arrays, tuples, Option<T>, and standard container types can be combined into larger trees. Option branches and inactive enum variants remain in the static schema but may return ValueError::Absent at runtime.

§Adapting Boundaries

miniconf is transport agnostic. Any channel that can carry a key and a Serde payload can use the tree. Keep transport routing, sessions, and buffering in the transport layer; pass a borrow of the settings tree into miniconf access functions when a message targets the tree.

Use Schema::transcode() to translate one key representation into another. Use NodeIter when publishing, validating, or rendering every leaf; it yields leaves only and exposes the current indices and schema while walking.

§Code Size

The embedded benchmark compares miniconf against a handwritten serial-style router for the same settings tree and value codec. Treat the handwritten router as a routed get/set lower bound, not a feature-equivalent replacement: it omits schema iteration, metadata, key transcoding, generic key backends, and generated reflection. The benchmark reports the static schema payload separately so the routed get/set overhead and reflection data can be judged independently.

§Limits

Internal tree enums support unit, newtype, and skipped variants only. Enums with named fields or multi-field tuple variants should stay leaves or use a manual/custom implementation.
Flattening is accepted only when generated lookup stays structurally unambiguous.
&str key input is always slash-separated. Use explicit iterator types for other syntaxes or separators.
Schema semantics and metadata are feature-gated reflection data. Do not depend on them unless sem, meta-node, or meta-edge is enabled as needed.

§Features

derive: re-export derive macros from miniconf_derive; enabled by default.
json-core: serde_json_core helpers for JSON byte slices.
json: serde_json helpers.
postcard: compact binary helpers using postcard.
sem, meta-node, meta-edge: retain structured schema semantics, node metadata, and parent-child edge metadata. Constructors and derive output accept these payloads in all builds; without the matching feature, they are discarded and schema accessors return None or empty metadata.
trace, schema: serde-reflection tracing and JSON Schema generation.
heapless, heapless-09, alloc, std: support for the corresponding storage and platform layers.

Modules§

compact_schema: Compact paged schema serialization.
deny: Deny access tools.
json: Utilities using serde_json
json_core: TreeSerialize/TreeDeserialize with “JSON and /”.
json_schema: JSON Schema tools.
leaf: Leaf implementation using serde::{Serialize, Deserialize}
passthrough: Passthrough Tree*
postcard: TreeSerialize/TreeDeserialize with postcard.
str_leaf: TryFrom<&str>/AsRef<str> leaf
trace: Schema tracing

Structs§

Chain: Concatenate two normalized key cursors.
ConstPath: Const-specialized output path with named selector segments separated by a const separator.
ConstPathIter: Const-specialized path iterator for boundary key input.
ExactSize: Counting wrapper for iterators with known exact size
Homogeneous: A representative schema item for a homogeneous array
Indices: Sequence of child indices identifying a node in a TreeSchema.
InternalSchema: Static schema payload for an internal node.
JsonPath: JSON-style path notation output.
JsonPathIter: JSON-style path iterator for boundary key input.
KeysIter: Explicit normalized wrapper for iterator-shaped key inputs.
Leaf: Serialize/Deserialize/Any leaf
Lookup: Result of an exact key lookup.
Meta: Immutable schema metadata.
Named: A named schema item
NodeIter: Node iterator
NodeSchema: Shared static schema payload for one tree node.
Numbered: A numbered schema item
Packed: A bit-packed normalized key cursor over multiple child indices.
Path: Output path with named selector segments separated by a separator char.
PathIter: Runtime-separated path iterator for boundary key input.
ResolveError: Error returned by Schema::resolve_into().
Sem: Structured machine-readable schema semantics.
Shape: Metadata about a crate::TreeSchema namespace.

Enums§

DescendError: Errors that can occur while visiting nodes with crate::Schema::descend().
Internal: An internal node with children
KeyError: Errors that can occur when using the Tree traits.
Schema: Static schema for one tree node.
SerdeError: Compound errors
Ty: Compact semantic leaf type.
ValueError: Errors that can occur while accessing a value.

Constants§

MAYBE_ABSENT_SEM: Structured semantics for a node that may be absent at runtime.
ONEOF_SEM: Structured semantics for a mutually exclusive named node.

Traits§

IntoKeys: Boundary input that can be normalized into a Keys cursor.
Key: Convert one selector segment into a child index for an internal node schema.
Keys: Normalized cursor over selector segments.
Transcode: Look up a key path in a Schema and transcode it.
TreeAny: Access any node by a normalized key cursor.
TreeDeserialize: Deserialize a leaf node by a normalized key cursor.
TreeDeserializeOwned: Shorthand for owned deserialization through TreeDeserialize.
TreeSchema: Traversal and iteration of key paths in a tree.
TreeSerialize: Serialize a leaf node by a normalized key cursor.

Derive Macros§

Tree: Derive the TreeSchema, TreeSerialize, TreeDeserialize, and TreeAny traits for a struct or enum.
TreeAny: Derive the TreeAny trait for a struct or enum.
TreeDeserialize: Derive the TreeDeserialize trait for a struct or enum.
TreeSchema: Derive the TreeSchema trait for a struct or enum.
TreeSerialize: Derive the TreeSerialize trait for a struct or enum.

Crate miniconf

Crate miniconf Copy item path

§miniconf

§Quick Start

§Pick The Surface

§Tree Shape

§Adapting Boundaries

§Code Size

§Limits

§Features

Modules§

Structs§

Enums§

Constants§

Traits§

Derive Macros§

Crate miniconf