ron::ser

Module path_meta

Source
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,
);

Structs§