serde-saphyr 0.0.27

use serde::de::{self, Deserialize, Deserializer, Visitor};
use std::fmt;
use std::marker::PhantomData;

/// Force a sequence to be emitted in flow style: `[a, b, c]`.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct FlowSeq<T>(pub T);

/// Force a mapping to be emitted in flow style: `{k1: v1, k2: v2}`.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct FlowMap<T>(pub T);

/// Add an empty line after the wrapped value when serializing.
///
/// This wrapper is transparent during deserialization and can be nested with
/// other wrappers like `Commented`, `FlowSeq`, etc.
/// ```rust
/// # #[cfg(feature = "serialize")]
/// # {
/// use serde::Serialize;
/// use serde_saphyr::SpaceAfter;
///
/// #[derive(Serialize)]
/// struct Config {
///     first: SpaceAfter<i32>,
///     second: i32,
/// }
///
/// let cfg = Config { first: SpaceAfter(1), second: 2 };
/// let yaml = serde_saphyr::to_string(&cfg).unwrap();
/// // The output will have an empty line after "first: 1"
/// # }
/// ```
/// **Important:** Avoid using this wrapper with `LitStr`/`LitString` as it may add the empty
/// line to the string content. For `FoldStr`/`FoldString` and other YAML values
/// (e.g. `key: value`, quoted scalars), the extra empty line is cosmetic.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct SpaceAfter<T>(pub T);

/// Attach an inline YAML comment to a value when serializing.
///
/// This wrapper lets you annotate a scalar with an inline YAML comment that is
/// emitted after the value when using block style. The typical form is:
/// `value # comment`. This is the most useful when deserializing the anchor
/// reference (so a human reader can see what a referenced value represents).
///
/// Comment is also captured into its field when deserializing YAML.
///
/// Behavior
/// - Block style (default): the comment appears after the scalar on the same line.
/// - Flow style (inside `[ ... ]` or `{ ... }`): comments are suppressed to keep
///   the flow representation compact and unambiguous.
/// - Complex values (sequences/maps/structs): the comment is ignored; only the
///   inner value is serialized to preserve indentation and layout.
/// - Newlines in comments are sanitized to spaces so the comment remains on a
///   single line (e.g., "a\nb" becomes "a b").
/// - Deserialization of `Commented<T>` captures nearby source comments when the
///   `serde-saphyr` deserializer can provide them. Other deserializers treat it
///   transparently and produce an empty comment string.
/// - Comment capture is use-site oriented for replayed YAML. Comments from an
///   anchor definition are not copied through aliases or merge keys; a field
///   materialized by `<<: *defaults` does not inherit comments that were written
///   above the field inside `&defaults`.
/// - For container values, comments attached to the parent value itself are
///   captured only by `Commented<Container>` and are not inherited by the first
///   child field or element. A comment inside the container, directly above a
///   child key or element, is captured by that child.
/// - When an alias to a container is used as a nested value, leading comments
///   above the alias follow the same inside-container rule. For example,
///   `root:\n  # comment\n  *defaults` leaves the comment available to the
///   expanded container's first child rather than capturing it on the alias use.
///
/// Examples
///
/// Basic scalar with a comment in block style:
/// ```rust
/// # #[cfg(feature = "serialize")]
/// # {
/// use serde::Serialize;
///
/// // Re-exported from the crate root
/// use serde_saphyr::Commented;
///
/// let out = serde_saphyr::to_string(&Commented(42, "answer".to_string())).unwrap();
/// assert_eq!(out, "42 # answer\n");
/// # }
/// ```
///
/// As a mapping value, still inline:
/// ```rust
/// # #[cfg(feature = "serialize")]
/// # {
/// use serde::Serialize;
/// use serde_saphyr::Commented;
///
/// #[derive(Serialize)]
/// struct S { xn: Commented<i32> }
///
/// let s = S { xn: Commented(5, "send five starships first".into()) };
/// let out = serde_saphyr::to_string(&s).unwrap();
/// assert_eq!(out, "xn: 5 # send five starships first\n");
/// # }
/// ```
///
/// *Important*: Comments are suppressed in flow contexts (no `#` appears), and
/// ignored for complex inner values during serialization. During deserialization,
/// parent-side comments on a container such as `root: # comment` are captured by
/// `Commented<Container>` only; comments inside the container, directly above the
/// first child key or element, remain available to that child. The same applies
/// to leading comments above a nested alias whose target is a container.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Commented<T>(pub T, pub String);

impl<'de, T: Deserialize<'de>> Deserialize<'de> for FlowSeq<T> {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
        T::deserialize(deserializer).map(FlowSeq)
    }
}

impl<'de, T: Deserialize<'de>> Deserialize<'de> for FlowMap<T> {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
        T::deserialize(deserializer).map(FlowMap)
    }
}

impl<'de, T: Deserialize<'de>> Deserialize<'de> for Commented<T> {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
        struct CommentedVisitor<T>(PhantomData<T>);

        impl<'de, T: Deserialize<'de>> Visitor<'de> for CommentedVisitor<T> {
            type Value = Commented<T>;

            fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
                formatter.write_str("a commented YAML value")
            }

            fn visit_newtype_struct<D>(
                self,
                deserializer: D,
            ) -> std::result::Result<Self::Value, D::Error>
            where
                D: Deserializer<'de>,
            {
                T::deserialize(deserializer).map(|value| Commented(value, String::new()))
            }

            fn visit_seq<A>(self, mut seq: A) -> std::result::Result<Self::Value, A::Error>
            where
                A: de::SeqAccess<'de>,
            {
                let value = seq
                    .next_element()?
                    .ok_or_else(|| de::Error::invalid_length(0, &self))?;
                let comment = seq.next_element()?.unwrap_or_default();
                Ok(Commented(value, comment))
            }
        }

        deserializer.deserialize_newtype_struct("__yaml_commented", CommentedVisitor(PhantomData))
    }
}

impl<'de, T: Deserialize<'de>> Deserialize<'de> for SpaceAfter<T> {
    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> std::result::Result<Self, D::Error> {
        T::deserialize(deserializer).map(SpaceAfter)
    }
}

#[cfg(all(test, feature = "deserialize"))]
mod tests {
    use serde::Deserialize;

    use crate::{Commented, FlowMap, FlowSeq, SpaceAfter};

    #[derive(Debug, Deserialize, PartialEq)]
    struct WrappersDoc {
        seq: FlowSeq<Vec<u32>>,
        map: FlowMap<std::collections::BTreeMap<String, u32>>,
        after: SpaceAfter<String>,
        commented: Commented<bool>,
    }

    #[test]
    fn wrappers_remain_deserializable_without_serialize() {
        let value: WrappersDoc =
            crate::from_str("seq: [1, 2]\nmap: {a: 1}\nafter: hello\ncommented: true\n").unwrap();

        assert_eq!(value.seq, FlowSeq(vec![1, 2]));
        assert_eq!(value.after, SpaceAfter("hello".to_string()));
        assert_eq!(value.commented, Commented(true, String::new()));
        assert_eq!(value.map.0.get("a"), Some(&1));
    }
}