Add provisional metadata ser in named field pos

CHANGELOG.md

@@ -21,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Breaking: Enforce that ron always writes valid UTF-8 ([#488](https://github.com/ron-rs/ron/pull/488))
 - Add convenient `Value::from` impls ([#498](https://github.com/ron-rs/ron/pull/498))
 - Add new extension `explicit_struct_names` which requires that struct names are included during deserialization ([#522](https://github.com/ron-rs/ron/pull/522))
+- Add new metadata serialization support in named field position via `PrettyConfig` ([#544](https://github.com/ron-rs/ron/pull/544))
 - Breaking: Change `PrettyConfig` so that `new_line`, `indentor` and `separator` are all `Cow<'static, str>` instead of `String` ([#546](https://github.com/ron-rs/ron/pull/546))
 
 ### Format Changes

src/lib.rs

@@ -19,6 +19,7 @@ pub mod de;
 pub mod ser;
 
 pub mod error;
+pub mod meta;
 pub mod value;
 
 pub mod extensions;

src/meta.rs

@@ -0,0 +1,365 @@
+use std::collections::HashMap;
+
+use serde_derive::{Deserialize, Serialize};
+
+/// 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
+///
+/// ```
+/// # use ron::{ser::PrettyConfig, meta::Field};
+///
+/// #[derive(serde::Serialize)]
+/// struct Creature {
+///     seconds_since_existing: usize,
+///     linked: Option<Box<Self>>,
+/// }
+///
+/// let mut config = PrettyConfig::default();
+///
+/// config
+///     .meta
+///     .field
+///     // 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.
+///
+/// ```no_run
+/// enum Kind {
+///     A {
+///         field: (),
+///     },  // ^
+///         // cannot be addressed separately because they have the same path
+///     B { // v
+///         field: (),
+///     },
+/// }
+/// ```
+///
+/// ```no_run
+/// struct A {
+///     field: (),
+/// }
+///
+/// struct B {
+///     field: (),
+/// }
+///
+/// type Value = (
+///     A,
+///  // ^
+///  // These are different types, but they share two fields with the same path: `buf` and `len`
+///  // v
+///     B,
+/// );
+/// ```
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, Default)]
+pub struct PathMeta {
+    pub field: Option<Field>,
+}
+
+/// The metadata and inner [`Fields`] of a field.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, Default)]
+pub struct Field {
+    doc: String,
+    fields: Option<Fields>,
+}
+
+impl Field {
+    /// Create a new empty field metadata.
+    #[must_use]
+    pub const fn empty() -> Self {
+        Self {
+            doc: String::new(),
+            fields: None,
+        }
+    }
+
+    /// Create a new field metadata from parts.
+    pub fn new(doc: impl Into<String>, fields: Option<Fields>) -> Self {
+        Self {
+            doc: doc.into(),
+            fields,
+        }
+    }
+
+    /// Get a shared reference to the documentation metadata of this field.
+    #[inline]
+    #[must_use]
+    pub fn doc(&self) -> &str {
+        self.doc.as_str()
+    }
+
+    /// Get a mutable reference to the documentation metadata of this field.
+    #[inline]
+    #[must_use]
+    pub fn doc_mut(&mut self) -> &mut String {
+        &mut self.doc
+    }
+
+    /// Set the documentation metadata of this field.
+    ///
+    /// ```
+    /// # use ron::meta::Field;
+    ///
+    /// let mut field = Field::empty();
+    ///
+    /// assert_eq!(field.doc(), "");
+    ///
+    /// field.with_doc("some meta");
+    ///
+    /// assert_eq!(field.doc(), "some meta");
+    /// ```
+    pub fn with_doc(&mut self, doc: impl Into<String>) -> &mut Self {
+        self.doc = doc.into();
+        self
+    }
+
+    /// Get a shared reference to the inner fields of this field, if it has any.
+    #[must_use]
+    pub fn fields(&self) -> Option<&Fields> {
+        self.fields.as_ref()
+    }
+
+    /// Get a mutable reference to the inner fields of this field, if it has any.
+    pub fn fields_mut(&mut self) -> Option<&mut Fields> {
+        self.fields.as_mut()
+    }
+
+    /// Return whether this field has inner fields.
+    ///
+    /// ```
+    /// # use ron::meta::{Field, Fields};
+    ///
+    /// let mut field = Field::empty();
+    ///
+    /// assert!(!field.has_fields());
+    ///
+    /// field.with_fields(Some(Fields::default()));
+    ///
+    /// assert!(field.has_fields());
+    /// ```
+    #[must_use]
+    pub fn has_fields(&self) -> bool {
+        self.fields.is_some()
+    }
+
+    /// Set the inner fields of this field.
+    ///
+    /// ```
+    /// # use ron::meta::{Field, Fields};
+    ///
+    /// let mut field = Field::empty();
+    ///
+    /// assert!(!field.has_fields());
+    ///
+    /// field.with_fields(Some(Fields::default()));
+    ///
+    /// assert!(field.has_fields());
+    ///
+    /// field.with_fields(None);
+    ///  
+    /// assert!(!field.has_fields());
+    /// ```
+    pub fn with_fields(&mut self, fields: Option<Fields>) -> &mut Self {
+        self.fields = fields;
+        self
+    }
+
+    /// Ergonomic shortcut for building some inner fields.
+    ///
+    /// ```
+    /// # use ron::meta::Field;
+    ///
+    /// let mut field = Field::empty();
+    ///
+    /// field.build_fields(|fields| {
+    ///     fields.field("inner field");
+    /// });
+    ///
+    /// assert_eq!(field.fields().map(|fields| fields.contains("inner field")), Some(true));
+    /// ```
+    pub fn build_fields(&mut self, builder: impl FnOnce(&mut Fields)) -> &mut Self {
+        let mut fields = Fields::default();
+        builder(&mut fields);
+        self.with_fields(Some(fields));
+        self
+    }
+}
+
+/// Mapping of names to [`Field`]s.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, Default)]
+pub struct Fields {
+    fields: HashMap<String, Field>,
+}
+
+impl Fields {
+    /// Return a new, empty metadata field map.
+    #[must_use]
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Return whether this field map contains no fields.
+    ///
+    /// ```
+    /// # use ron::meta::{Fields, Field};
+    ///
+    /// let mut fields = Fields::default();
+    ///
+    /// assert!(fields.is_empty());
+    ///
+    /// fields.insert("", Field::empty());
+    ///
+    /// assert!(!fields.is_empty());
+    /// ```
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.fields.is_empty()
+    }
+
+    /// Return whether this field map contains a field with the given name.
+    ///
+    /// ```
+    /// # use ron::meta::{Fields, Field};
+    ///
+    /// let fields: Fields = [("a thing", Field::empty())].into_iter().collect();
+    ///
+    /// assert!(fields.contains("a thing"));
+    /// assert!(!fields.contains("not a thing"));
+    /// ```
+    pub fn contains(&self, name: impl AsRef<str>) -> bool {
+        self.fields.contains_key(name.as_ref())
+    }
+
+    /// Get a reference to the field with the provided `name`, if it exists.
+    ///
+    /// ```
+    /// # use ron::meta::{Fields, Field};
+    ///
+    /// let fields: Fields = [("a thing", Field::empty())].into_iter().collect();
+    ///
+    /// assert!(fields.get("a thing").is_some());
+    /// assert!(fields.get("not a thing").is_none());
+    /// ```
+    pub fn get(&self, name: impl AsRef<str>) -> Option<&Field> {
+        self.fields.get(name.as_ref())
+    }
+
+    /// Get a mutable reference to the field with the provided `name`, if it exists.
+    ///
+    /// ```
+    /// # use ron::meta::{Fields, Field};
+    ///
+    /// let mut fields: Fields = [("a thing", Field::empty())].into_iter().collect();
+    ///
+    /// assert!(fields.get_mut("a thing").is_some());
+    /// assert!(fields.get_mut("not a thing").is_none());
+    /// ```
+    pub fn get_mut(&mut self, name: impl AsRef<str>) -> Option<&mut Field> {
+        self.fields.get_mut(name.as_ref())
+    }
+
+    /// Insert a field with the given name into the map.
+    ///
+    /// ```
+    /// # use ron::meta::{Fields, Field};
+    ///
+    /// let mut fields = Fields::default();
+    ///
+    /// assert!(fields.insert("field", Field::empty()).is_none());
+    /// assert!(fields.insert("field", Field::empty()).is_some());
+    /// ```
+    pub fn insert(&mut self, name: impl Into<String>, field: Field) -> Option<Field> {
+        self.fields.insert(name.into(), field)
+    }
+
+    /// Remove a field with the given name from the map.
+    ///
+    /// ```
+    /// # use ron::meta::{Fields, Field};
+    ///
+    /// let mut fields: Fields = [("a", Field::empty())].into_iter().collect();
+    ///
+    /// assert_eq!(fields.remove("a"), Some(Field::empty()));
+    /// assert_eq!(fields.remove("a"), None);
+    /// ```
+    pub fn remove(&mut self, name: impl AsRef<str>) -> Option<Field> {
+        self.fields.remove(name.as_ref())
+    }
+
+    /// Get a mutable reference to the field with the provided `name`,
+    /// inserting an empty [`Field`] if it didn't exist.
+    ///
+    /// ```
+    /// # use ron::meta::Fields;
+    ///
+    /// let mut fields = Fields::default();
+    ///
+    /// assert!(!fields.contains("thing"));
+    ///
+    /// fields.field("thing");
+    ///
+    /// assert!(fields.contains("thing"));
+    /// ```
+    pub fn field(&mut self, name: impl Into<String>) -> &mut Field {
+        self.fields.entry(name.into()).or_insert_with(Field::empty)
+    }
+}
+
+impl<K: Into<String>> FromIterator<(K, Field)> for Fields {
+    fn from_iter<T: IntoIterator<Item = (K, Field)>>(iter: T) -> Self {
+        Self {
+            fields: iter.into_iter().map(|(k, v)| (k.into(), v)).collect(),
+        }
+    }
+}