pub trait TreeSchema {
const SCHEMA: &Schema;
}Expand description
Traversal, iteration of keys in a tree.
See also the sub-traits TreeSerialize, TreeDeserialize, TreeAny.
§Keys
There is a one-to-one relationship between nodes and keys.
The keys used to identify nodes support Keys/IntoKeys. They can be
obtained from other IntoKeys through Schema::transcode().
An iterator of keys for the nodes is available through Schema::nodes().
usizeis modelled after ASN.1 Object Identifiers, seecrate::Indices.&strkeys are sequences of names, like path names. When concatenated, they are separated by some path hierarchy separator, e.g.'/', seecrate::Path, or by some more complex notation, seecrate::JsonPath.crate::Packedis a bit-packed compact compressed notation of hierarchical compound indices.- See the
scpiexample for how to implement case-insensitive, relative, and abbreviated/partial matches.
§Derive macros
Derive macros to automatically implement the correct traits on a struct or enum are available through
crate::TreeSchema, crate::TreeSerialize, crate::TreeDeserialize,
and crate::TreeAny.
A shorthand derive macro that derives all four trait implementations is also available at
crate::Tree.
The derive macros support per-field/per-variant attributes to control the derived trait implementations.
§Rename
The key for named struct fields or enum variants may be changed from the default field ident using
the rename derive macro attribute.
use miniconf::{Path, Tree, TreeSchema};
#[derive(Tree, Default)]
struct S {
#[tree(rename = "OTHER")]
a: f32,
};
let name = S::SCHEMA.transcode::<Path<String, '/'>>([0usize]).unwrap();
assert_eq!(name.0.as_str(), "/OTHER");§Skip
Named fields/variants may be omitted from the derived Tree trait implementations using the
skip attribute.
Note that for tuple structs skipping is only supported for terminal fields:
use miniconf::{Tree};
#[derive(Tree)]
struct S(i32, #[tree(skip)] ());use miniconf::{Tree};
#[derive(Tree)]
struct S(#[tree(skip)] (), i32);§Type
The type to use when accessing the field/variant through TreeDeserialize::probe
can be overridden using the typ derive macro attribute (#[tree(typ="[f32; 4]")]).
§Implementation overrides
#[tree(with=path)]
This overrides the calls to the child node/variant traits using pub functions
and constants in the module at the given path:
(SCHEMA, serialize_by_key, deserialize_by_key, probe_by_key,
ref_any_by_key, mut_any_by_key).
Also use this to relax bounds and deny operations.
#[derive(Tree, Default)]
struct S {
#[tree(with=check)]
b: f32,
}
mod check {
use miniconf::{SerdeError, Deserializer, TreeDeserialize, ValueError, Keys};
pub use miniconf::leaf::{SCHEMA, serialize_by_key, probe_by_key, ref_any_by_key, mut_any_by_key};
pub fn deserialize_by_key<'de, D: Deserializer<'de>>(
value: &mut f32,
keys: impl Keys,
de: D
) -> Result<(), SerdeError<D::Error>> {
let mut new = *value;
new.deserialize_by_key(keys, de)?;
if new < 0.0 {
Err(ValueError::Access("fail").into())
} else {
*value = new;
Ok(())
}
}
}§defer
The defer attribute is a shorthand for with() that defers
child trait implementations to a given expression.
§Array
Blanket implementations of the Tree* traits are provided for homogeneous arrays
[T; N].
§Option
Blanket implementations of the Tree* traits are provided for Option<T>.
These implementations do not alter the path hierarchy and do not consume any items from the keys
iterators. The TreeSchema behavior of an Option is such that the None variant makes the
corresponding part of the tree inaccessible at run-time. It will still be iterated over (e.g.
by Schema::nodes()) but attempts to access it (e.g. TreeSerialize::serialize_by_key(),
TreeDeserialize::deserialize_by_key(), TreeAny::ref_any_by_key(), or
TreeAny::mut_any_by_key()) return the special ValueError::Absent.
This is the same behavior as for other enums that have the Tree* traits derived.
§Tuples
Blanket impementations for the Tree* traits are provided for heterogeneous tuples (T0, T1, ...)
up to length eight.
§Examples
See the crate documentation for a longer example showing how the traits and the derive
macros work.
Required Associated Constants§
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.