Expand description
Path-based metadata to serialize with a value.
Path-based in this context means that the metadata is linked to the data in a relative and hierarchical fashion by tracking the current absolute path of the field being serialized.
§Example
#[derive(serde::Serialize)]
struct Creature {
seconds_since_existing: usize,
linked: Option<Box<Self>>,
}
let mut config = PrettyConfig::default();
config
.path_meta
// The path meta defaults to no root structure,
// so we either provide a prebuilt one or initialize
// an empty one to build.
.get_or_insert_with(Field::empty)
.build_fields(|fields| {
fields
// Get or insert the named field
.field("seconds_since_existing")
.with_doc("Outer seconds_since_existing");
fields
.field("linked")
// Doc metadata is serialized preceded by three forward slashes and a space for each line
.with_doc("Optional.\nProvide another creature to be wrapped.")
// Even though it's another Creature, the fields have different paths, so they are addressed separately.
.build_fields(|fields| {
fields
.field("seconds_since_existing")
.with_doc("Inner seconds_since_existing");
});
});
let value = Creature {
seconds_since_existing: 0,
linked: Some(Box::new(Creature {
seconds_since_existing: 0,
linked: None,
})),
};
let s = ron::ser::to_string_pretty(&value, config).unwrap();
assert_eq!(s, r#"(
/// Outer seconds_since_existing
seconds_since_existing: 0,
/// Optional.
/// Provide another creature to be wrapped.
linked: Some((
/// Inner seconds_since_existing
seconds_since_existing: 0,
linked: None,
)),
)"#);
§Identical paths
Especially in enums and tuples it’s possible for fields to share a path, thus being unable to be addressed separately.
enum Kind {
A {
field: (),
}, // ^
// cannot be addressed separately because they have the same path
B { // v
field: (),
},
}
struct A {
field: (),
}
struct B {
field: (),
}
type Value = (
A,
// ^
// These are different types, but they share the path `field`
// v
B,
);