fig 3.2.0

//! The non-serde value representation and its serializer.
//!
//! [`Value`] is an owned, format-independent tree mirroring fig's AST node
//! kinds. [`Value::serialize`] builds it through the C value API
//! (`fig_value_*`) and renders it with fig's core serializer — so the binding
//! carries no emitter of its own. With the `serde` feature, [`crate::to_string`]
//! and the editor's typed methods build a `Value` from any `Serialize` type
//! (see [`crate::ser`]); without it, callers construct `Value` directly.

use std::os::raw::c_int;
use std::ptr::{self, NonNull};

use crate::error::Error;
use crate::ffi;
use crate::{Format, SerializeOptions};

/// The kind of a format-specific [`Value::Extended`] scalar. Mirrors the core's
/// `ExtKind` and the C ABI's `FigExtKind`; the discriminants match that ABI.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[non_exhaustive]
pub enum ExtKind {
    /// TOML offset date-time, e.g. `1979-05-27T07:32:00Z`.
    OffsetDateTime,
    /// TOML local date-time, e.g. `1979-05-27T07:32:00`.
    LocalDateTime,
    /// TOML local date, e.g. `1979-05-27`.
    LocalDate,
    /// TOML local time, e.g. `07:32:00`.
    LocalTime,
    /// ZON enum literal, e.g. `.foo` (text is the bare name, without the dot).
    EnumLiteral,
    /// ZON character literal, e.g. `'a'` (text is the decimal codepoint).
    CharLiteral,
    /// A non-finite JSON5 number (`Infinity`/`-Infinity`/`NaN`); text is the
    /// literal as written.
    NumberSpecial,
}

impl ExtKind {
    /// The C ABI enumerator (`FigExtKind`) for this kind.
    fn to_c(self) -> c_int {
        match self {
            ExtKind::OffsetDateTime => 0,
            ExtKind::LocalDateTime => 1,
            ExtKind::LocalDate => 2,
            ExtKind::LocalTime => 3,
            ExtKind::EnumLiteral => 4,
            ExtKind::CharLiteral => 5,
            ExtKind::NumberSpecial => 6,
        }
    }

    /// Map a C ABI `FigExtKind` back to an [`ExtKind`], or `None` if unknown.
    pub(crate) fn from_c(kind: c_int) -> Option<Self> {
        Some(match kind {
            0 => ExtKind::OffsetDateTime,
            1 => ExtKind::LocalDateTime,
            2 => ExtKind::LocalDate,
            3 => ExtKind::LocalTime,
            4 => ExtKind::EnumLiteral,
            5 => ExtKind::CharLiteral,
            6 => ExtKind::NumberSpecial,
            _ => return None,
        })
    }
}

/// An owned, format-independent value tree.
///
/// # Canonical form
///
/// Two of the scalar variants overlap, so the tree has a canonical spelling
/// that every constructor in this crate produces — parsing, `From`, the
/// `ToValue` impls, and the serde serializer alike:
///
/// - **An integer that fits in `i64` is [`Value::Int`]**, whatever Rust type it
///   came from. [`Value::Uint`] holds only magnitudes past `i64::MAX`. This is
///   what keeps `Value::from(3u64) == Value::from(3i64)`; `PartialEq` is
///   structural (it compares variants, as a value tree's equality should), so
///   without the rule the same number could be unequal to itself depending on
///   which door it came in by. The reading accessors ([`Value::as_i64`],
///   [`Value::as_u64`], [`Value::as_f64`]) still span both variants, so a
///   hand-built `Value::Uint(3)` reads back fine — it just isn't `==` to
///   `Value::Int(3)`. Route through `Value::from` (or [`Value::eq_canonical`])
///   rather than constructing `Uint` for a small number.
/// - **A float is compared by IEEE rules under `==`**, which means a value can
///   fail to equal itself: `.nan` is a scalar fig both parses and renders, and
///   `NaN != NaN`. A dirty check written as `if new != old { … }` therefore
///   never converges on a float field holding `.nan`. Use
///   [`Value::eq_canonical`] for that; it compares floats by bit pattern.
#[derive(Clone, Debug, PartialEq)]
pub enum Value {
    Null,
    Bool(bool),
    Int(i64),
    /// An integer too large for `i64`. Canonically this variant holds only
    /// values above `i64::MAX` — see the type-level note on canonical form.
    Uint(u64),
    /// A float, including the non-finite values YAML spells `.inf`/`.nan`
    /// (see [`Value::parse_float`]). Note that `==` on a `NaN` payload is
    /// `false`, as everywhere else in Rust; [`Value::eq_canonical`] is the
    /// reflexive comparison.
    Float(f64),
    Str(String),
    /// A format-specific scalar (TOML datetime, ZON enum/char literal) carried
    /// verbatim. Produced by [`crate::Document::to_value`] when reading TOML/ZON,
    /// and rendered back by [`Value::serialize`]. The serde path instead reads
    /// these as plain strings/integers.
    Extended {
        kind: ExtKind,
        text: String,
    },
    Seq(Vec<Value>),
    /// Mapping entries, in order. Keys are conventionally strings; a non-string
    /// key serializes only to formats whose printer accepts one.
    Map(Vec<(Value, Value)>),
}

impl From<bool> for Value {
    fn from(v: bool) -> Self {
        Value::Bool(v)
    }
}
impl From<i64> for Value {
    fn from(v: i64) -> Self {
        Value::Int(v)
    }
}
impl From<i32> for Value {
    fn from(v: i32) -> Self {
        Value::Int(v as i64)
    }
}
/// Normalises into the canonical integer variant: [`Value::Int`] when the value
/// fits in `i64`, [`Value::Uint`] only past `i64::MAX`. Every other constructor
/// in the crate funnels unsigned integers through here, so a `3` is the same
/// value however it was built.
impl From<u64> for Value {
    fn from(v: u64) -> Self {
        match i64::try_from(v) {
            Ok(i) => Value::Int(i),
            Err(_) => Value::Uint(v),
        }
    }
}
impl From<f64> for Value {
    fn from(v: f64) -> Self {
        Value::Float(v)
    }
}
impl From<&str> for Value {
    fn from(v: &str) -> Self {
        Value::Str(v.to_owned())
    }
}
impl From<String> for Value {
    fn from(v: String) -> Self {
        Value::Str(v)
    }
}
impl From<Vec<Value>> for Value {
    fn from(v: Vec<Value>) -> Self {
        Value::Seq(v)
    }
}
/// Clone a borrowed value into an owned one. This is what lets a `&Value` still
/// satisfy the `impl Into<Value>` value parameters on the editor/embed methods
/// (pass an owned `Value` instead to move rather than clone).
impl From<&Value> for Value {
    fn from(v: &Value) -> Self {
        v.clone()
    }
}

impl Value {
    /// Render to `format` via fig's core serializer, using default output style.
    /// The value is built through the C value API and emitted by fig, so no
    /// JSON/YAML/TOML/ZON formatting happens in Rust.
    pub fn serialize(&self, format: Format) -> Result<String, Error> {
        self.serialize_with(format, SerializeOptions::default())
    }

    /// Render to `format`, with `options` controlling output style such as
    /// compact vs. pretty-printed JSON.
    pub fn serialize_with(
        &self,
        format: Format,
        options: SerializeOptions,
    ) -> Result<String, Error> {
        self.serialize_ffi(format, options.into())
    }

    /// The raw-options serialize path. Exists so crate-internal callers (the
    /// editors' `value_text`) can set ABI-level options that the public
    /// [`SerializeOptions`] deliberately does not expose (`flow` — inline is a
    /// property of where the text is spliced, not a caller style preference).
    pub(crate) fn serialize_ffi(
        &self,
        format: Format,
        ffi_options: ffi::FigSerializeOptions,
    ) -> Result<String, Error> {
        let mut raw = ptr::null_mut();
        // Safety: `raw` is a valid out-pointer; create sets it or returns non-ok.
        Error::from_status(unsafe { ffi::fig_value_create(&mut raw) })?;
        NonNull::new(raw).ok_or(Error::Internal)?;
        let guard = ValueGuard(raw);

        let root = build(guard.0, self)?;

        let mut ptr_out: *const u8 = ptr::null();
        let mut len: usize = 0;
        let ffi_format: ffi::FigFormat = format.into();
        Error::from_status(unsafe {
            ffi::fig_value_serialize_opts(
                guard.0,
                root,
                ffi_format as i32,
                &ffi_options,
                &mut ptr_out,
                &mut len,
            )
        })?;

        // Safety: on success the ABI guarantees `len` bytes at `ptr_out`, owned
        // by the handle and valid until the next call / destroy. We copy out now.
        let bytes = if len == 0 {
            &[][..]
        } else {
            unsafe { std::slice::from_raw_parts(ptr_out, len) }
        };
        Ok(std::str::from_utf8(bytes)
            .map_err(|_| Error::Utf8)?
            .to_owned())
    }

    /// Report what serializing this value to `format` would silently lose
    /// (values/comments dropped or degraded). The built value has no source
    /// envelopes, so `options.lossless` is ignored. Returns one [`crate::Warning`]
    /// per lossy event (empty if nothing is lost).
    pub fn diagnose(
        &self,
        format: Format,
        options: SerializeOptions,
    ) -> Result<Vec<crate::Warning>, Error> {
        let mut raw = ptr::null_mut();
        Error::from_status(unsafe { ffi::fig_value_create(&mut raw) })?;
        NonNull::new(raw).ok_or(Error::Internal)?;
        let guard = ValueGuard(raw);

        let root = build(guard.0, self)?;
        let ffi_format: ffi::FigFormat = format.into();
        let ffi_options: ffi::FigSerializeOptions = options.into();
        let mut count: usize = 0;
        Error::from_status(unsafe {
            ffi::fig_value_diagnose(guard.0, root, ffi_format as c_int, &ffi_options, &mut count)
        })?;
        let mut out = Vec::with_capacity(count);
        for i in 0..count {
            let mut w = ffi::FigWarning::new();
            Error::from_status(unsafe { ffi::fig_value_warning(guard.0, i, &mut w) })?;
            // Safety: on `OK`, `w` is filled with borrowed path/note bytes valid
            // until the next diagnose on this handle (which we don't call before
            // copying them out here) or its destroy.
            out.push(unsafe { crate::Warning::from_ffi(&w) });
        }
        Ok(out)
    }

    /// `true` if this is [`Value::Null`].
    pub fn is_null(&self) -> bool {
        matches!(self, Value::Null)
    }

    /// `true` if this is a [`Value::Bool`].
    pub fn is_bool(&self) -> bool {
        matches!(self, Value::Bool(_))
    }

    /// The bool, if this is a [`Value::Bool`].
    pub fn as_bool(&self) -> Option<bool> {
        match self {
            Value::Bool(b) => Some(*b),
            _ => None,
        }
    }

    /// `true` if [`Value::as_i64`] would succeed: this is a [`Value::Int`], or a
    /// [`Value::Uint`] that fits in `i64`.
    pub fn is_i64(&self) -> bool {
        self.as_i64().is_some()
    }

    /// The integer, if this is a [`Value::Int`], or a [`Value::Uint`] that fits
    /// in `i64`.
    pub fn as_i64(&self) -> Option<i64> {
        match self {
            Value::Int(i) => Some(*i),
            Value::Uint(u) => i64::try_from(*u).ok(),
            _ => None,
        }
    }

    /// `true` if [`Value::as_u64`] would succeed: this is a [`Value::Uint`], or
    /// a non-negative [`Value::Int`].
    pub fn is_u64(&self) -> bool {
        self.as_u64().is_some()
    }

    /// The integer, if this is a [`Value::Uint`], or a non-negative [`Value::Int`].
    pub fn as_u64(&self) -> Option<u64> {
        match self {
            Value::Uint(u) => Some(*u),
            Value::Int(i) => u64::try_from(*i).ok(),
            _ => None,
        }
    }

    /// `true` if this is a [`Value::Float`]. Unlike [`Value::as_f64`], integers
    /// don't count — this asks whether the value was *stored* as a float, not
    /// whether it's numerically representable as one.
    pub fn is_f64(&self) -> bool {
        matches!(self, Value::Float(_))
    }

    /// The float, if this is a [`Value::Float`]. Also widens a [`Value::Int`]
    /// or [`Value::Uint`] (lossily for magnitudes past `2^53`), matching how
    /// [`crate::convert::FromValue`] reads `f64` fields.
    pub fn as_f64(&self) -> Option<f64> {
        match self {
            Value::Float(f) => Some(*f),
            Value::Int(i) => Some(*i as f64),
            Value::Uint(u) => Some(*u as f64),
            _ => None,
        }
    }

    /// `true` if this is a [`Value::Str`].
    pub fn is_str(&self) -> bool {
        matches!(self, Value::Str(_))
    }

    /// The string, if this is a [`Value::Str`]. Does not match [`Value::Extended`]
    /// scalars, whose `text` is format-specific rather than a plain string.
    pub fn as_str(&self) -> Option<&str> {
        match self {
            Value::Str(s) => Some(s),
            _ => None,
        }
    }

    /// `true` if this is a [`Value::Extended`] scalar.
    pub fn is_extended(&self) -> bool {
        matches!(self, Value::Extended { .. })
    }

    /// The kind and text, if this is a [`Value::Extended`] scalar.
    pub fn as_extended(&self) -> Option<(ExtKind, &str)> {
        match self {
            Value::Extended { kind, text } => Some((*kind, text.as_str())),
            _ => None,
        }
    }

    /// `true` if this is a [`Value::Seq`].
    pub fn is_seq(&self) -> bool {
        matches!(self, Value::Seq(_))
    }

    /// The elements, if this is a [`Value::Seq`].
    pub fn as_seq(&self) -> Option<&[Value]> {
        match self {
            Value::Seq(items) => Some(items),
            _ => None,
        }
    }

    /// `true` if this is a [`Value::Map`].
    pub fn is_mapping(&self) -> bool {
        matches!(self, Value::Map(_))
    }

    /// The entries, if this is a [`Value::Map`].
    pub fn as_mapping(&self) -> Option<&[(Value, Value)]> {
        match self {
            Value::Map(entries) => Some(entries),
            _ => None,
        }
    }

    /// Structural equality, canonicalised so that a value always equals itself.
    ///
    /// `==` compares the variants exactly, which is what a value tree's equality
    /// should mean — but it inherits two edges from the scalars:
    ///
    /// - `Value::Float(f64::NAN) != Value::Float(f64::NAN)`, by IEEE rules, so
    ///   a value parsed from `x: .nan` is not equal to an identical second parse
    ///   of the same bytes. Here floats compare by **bit pattern**, so it is.
    ///   The flip side of that: `0.0` and `-0.0` are *not* equal here, matching
    ///   the distinct text (`0.0` / `-0.0`) they serialize to.
    /// - [`Value::Int`] and [`Value::Uint`] are distinct variants, so a
    ///   hand-built `Value::Uint(3)` is not `==` to `Value::Int(3)` (the crate's
    ///   own constructors never produce the former — see the type-level note on
    ///   canonical form). Here the two integer variants compare **numerically**.
    ///
    /// Everything else matches `==`, including map comparison being
    /// order-sensitive: entries are an ordered `Vec`, and reordering them
    /// changes the document.
    ///
    /// This is the comparison to use for a round-trip or dirty check —
    /// "would writing this value back change the file?" — where `==` can
    /// report a spurious difference and loop.
    ///
    /// ```
    /// use fig::Value;
    ///
    /// let nan = Value::Float(f64::NAN);
    /// assert!(nan != nan);              // IEEE
    /// assert!(nan.eq_canonical(&nan));  // reflexive
    ///
    /// assert!(Value::Int(3).eq_canonical(&Value::Uint(3)));
    /// assert!(!Value::Float(0.0).eq_canonical(&Value::Float(-0.0)));
    /// ```
    pub fn eq_canonical(&self, other: &Value) -> bool {
        match (self, other) {
            // Bitwise, so `NaN` equals itself and `-0.0` differs from `0.0`.
            (Value::Float(a), Value::Float(b)) => a.to_bits() == b.to_bits(),
            // The one cross-variant pair; `Int`/`Int` and `Uint`/`Uint` fall
            // through to the derived comparison below.
            (Value::Int(i), Value::Uint(u)) | (Value::Uint(u), Value::Int(i)) => {
                u64::try_from(*i).is_ok_and(|i| i == *u)
            }
            (Value::Seq(a), Value::Seq(b)) => {
                a.len() == b.len() && a.iter().zip(b).all(|(x, y)| x.eq_canonical(y))
            }
            (Value::Map(a), Value::Map(b)) => {
                a.len() == b.len()
                    && a.iter()
                        .zip(b)
                        .all(|((ak, av), (bk, bv))| ak.eq_canonical(bk) && av.eq_canonical(bv))
            }
            _ => self == other,
        }
    }

    /// Parse a numeric scalar's text into a `Value`, exactly as reading a
    /// document does — the inverse of the number text fig writes out.
    ///
    /// `is_float` is the scalar's kind, not a guess about its spelling: a float
    /// field holding `3` is `Float(3.0)`, an integer field holding `3` is
    /// `Int(3)`. An integer tries `i64` then `u64`, falling back to a float when
    /// it fits in neither (matching how the deserializer widens); a float goes
    /// through [`Value::parse_float`], so it accepts the `.inf`/`.nan` spellings
    /// fig itself emits.
    ///
    /// Editors and schema layers that turn edited text back into a value should
    /// use this rather than `str::parse`, which rejects `.inf`/`.nan` — a field
    /// holding one would otherwise become a [`Value::Str`] on a no-op edit.
    ///
    /// ```
    /// use fig::Value;
    ///
    /// assert_eq!(Value::parse_number("3", false).unwrap(), Value::Int(3));
    /// assert_eq!(Value::parse_number("3", true).unwrap(), Value::Float(3.0));
    /// assert!(Value::parse_number(".inf", true).unwrap().as_f64().unwrap().is_infinite());
    /// assert!(Value::parse_number("nope", false).is_err());
    /// ```
    pub fn parse_number(raw: &str, is_float: bool) -> Result<Value, Error> {
        if !is_float {
            if let Ok(i) = raw.parse::<i64>() {
                return Ok(Value::Int(i));
            }
            if let Ok(u) = raw.parse::<u64>() {
                // Past `i64::MAX`, so this is the canonical `Uint` range.
                return Ok(Value::Uint(u));
            }
        }
        Value::parse_float(raw)
            .map(Value::Float)
            .ok_or_else(|| Error::Number(raw.to_owned()))
    }

    /// Parse float text the way fig reads it: `f64::from_str`, plus the
    /// non-finite spellings YAML uses and fig writes — `.inf`, `.Inf`, `.INF`
    /// (with an optional `+`), their negatives, and `.nan`, `.NaN`, `.NAN`.
    /// `None` if the text is not a float at all.
    ///
    /// This is the inverse of the text fig serializes a [`Value::Float`] to, so
    /// a float scalar survives a text round trip unchanged. Rust's own
    /// `"…".parse::<f64>()` is not: it rejects `.inf`/`.nan` and accepts
    /// `inf`/`NaN`, which fig never writes.
    pub fn parse_float(raw: &str) -> Option<f64> {
        match raw {
            ".inf" | ".Inf" | ".INF" | "+.inf" | "+.Inf" | "+.INF" => Some(f64::INFINITY),
            "-.inf" | "-.Inf" | "-.INF" => Some(f64::NEG_INFINITY),
            ".nan" | ".NaN" | ".NAN" => Some(f64::NAN),
            _ => raw.parse::<f64>().ok(),
        }
    }

    /// Index into this value: a string-like [`Index`] looks up a key among a
    /// [`Value::Map`]'s entries (last-wins on duplicates), an integer looks up
    /// a position in a [`Value::Seq`]. `None` if this value isn't the matching
    /// container kind, or the key/index isn't present.
    pub fn get<I: Index>(&self, index: I) -> Option<&Value> {
        index.index_into(self)
    }
}

/// Look up `key` in `entries`, last-wins (later duplicate keys shadow earlier
/// ones). Shared by [`Value::get`]'s `&str`/`String` [`Index`] impls and,
/// behind the `derive` feature, the generated field extraction in
/// [`crate::convert`].
pub(crate) fn map_get<'a>(entries: &'a [(Value, Value)], key: &str) -> Option<&'a Value> {
    entries.iter().rev().find_map(|(k, v)| match k {
        Value::Str(s) if s == key => Some(v),
        _ => None,
    })
}

/// A type that can index into a [`Value`]: a string-like key for a
/// [`Value::Map`], or an integer position for a [`Value::Seq`]. Implemented
/// for `str`, `String`, and `usize` (and `&T` over any of those), and sealed
/// so it can't be implemented outside this crate. Drives both [`Value::get`]
/// and `value[index]`, the way `serde_json::value::Index` does for
/// `serde_json::Value`.
pub trait Index: sealed::Sealed {
    #[doc(hidden)]
    fn index_into<'v>(&self, value: &'v Value) -> Option<&'v Value>;
}

impl Index for str {
    fn index_into<'v>(&self, value: &'v Value) -> Option<&'v Value> {
        match value {
            Value::Map(entries) => map_get(entries, self),
            _ => None,
        }
    }
}
impl Index for String {
    fn index_into<'v>(&self, value: &'v Value) -> Option<&'v Value> {
        self.as_str().index_into(value)
    }
}
impl Index for usize {
    fn index_into<'v>(&self, value: &'v Value) -> Option<&'v Value> {
        match value {
            Value::Seq(items) => items.get(*self),
            _ => None,
        }
    }
}
impl<T: ?Sized + Index> Index for &T {
    fn index_into<'v>(&self, value: &'v Value) -> Option<&'v Value> {
        (**self).index_into(value)
    }
}

mod sealed {
    pub trait Sealed {}
    impl Sealed for str {}
    impl Sealed for String {}
    impl Sealed for usize {}
    impl<T: ?Sized + Sealed> Sealed for &T {}
}

/// `value[key]`/`value[index]`, returning [`Value::Null`] (rather than
/// panicking) when the index is out of range or the wrong container kind —
/// so a chain like `value["a"]["b"][0]` can walk through a mismatch and still
/// be checked with [`Value::is_null`] at the end. Use [`Value::get`] instead
/// for an `Option` that distinguishes "absent" from an actual null.
impl<I: Index> std::ops::Index<I> for Value {
    type Output = Value;

    fn index(&self, index: I) -> &Value {
        static NULL: Value = Value::Null;
        self.get(index).unwrap_or(&NULL)
    }
}

/// Destroys the value handle on drop, so an early `?` return can't leak it.
struct ValueGuard(*mut ffi::FigValue);

impl Drop for ValueGuard {
    fn drop(&mut self) {
        unsafe { ffi::fig_value_destroy(self.0) };
    }
}

/// Build `value` into the handle bottom-up (children before their container),
/// returning the new root node's id.
fn build(handle: *mut ffi::FigValue, value: &Value) -> Result<ffi::FigNodeId, Error> {
    let mut id: ffi::FigNodeId = 0;
    // Safety: `handle` is a live value handle; the out-id is valid; child ids
    // passed to seq/map were returned by earlier builds on this same handle.
    let status = unsafe {
        match value {
            Value::Null => ffi::fig_value_null(handle, &mut id),
            Value::Bool(b) => ffi::fig_value_bool(handle, *b, &mut id),
            Value::Int(n) => ffi::fig_value_int(handle, *n, &mut id),
            Value::Uint(n) => ffi::fig_value_uint(handle, *n, &mut id),
            Value::Float(f) => {
                let text = format_float(*f);
                ffi::fig_value_number(handle, text.as_ptr(), text.len(), true, &mut id)
            }
            Value::Str(s) => ffi::fig_value_string(handle, s.as_ptr(), s.len(), &mut id),
            Value::Extended { kind, text } => {
                ffi::fig_value_extended(handle, kind.to_c(), text.as_ptr(), text.len(), &mut id)
            }
            Value::Seq(items) => {
                let ids = items
                    .iter()
                    .map(|it| build(handle, it))
                    .collect::<Result<Vec<_>, _>>()?;
                ffi::fig_value_seq(handle, ids.as_ptr(), ids.len(), &mut id)
            }
            Value::Map(entries) => {
                let kvs = entries
                    .iter()
                    .map(|(k, v)| {
                        Ok(ffi::FigKeyValue {
                            key: build(handle, k)?,
                            value: build(handle, v)?,
                        })
                    })
                    .collect::<Result<Vec<_>, Error>>()?;
                ffi::fig_value_map(handle, kvs.as_ptr(), kvs.len(), &mut id)
            }
        }
    };
    Error::from_status(status)?;
    Ok(id)
}

/// The splice text for an editor value: the value rendered in `format`, minus
/// the trailing newline the serializer appends (the editor owns newline
/// framing).
pub(crate) fn value_text(value: &Value, format: Format) -> Result<String, Error> {
    // The text is spliced inline (`key = <text>`), so for the fig dialect a
    // container must render as flow — its block spelling (`* ` element lines,
    // section headers) only parses as standalone lines and would re-read as a
    // bare string after the splice. Other formats keep their defaults: their
    // block spellings splice correctly (YAML) or don't arise.
    let mut ffi_options: crate::ffi::FigSerializeOptions = SerializeOptions::default().into();
    if format == Format::Fig {
        ffi_options.flow = 1;
    }
    let mut s = value.serialize_ffi(format, ffi_options)?;
    if s.ends_with('\n') {
        s.pop();
    }
    Ok(s)
}

/// Render `value` as splice text honoring `options` — the "width knob" path
/// behind the `*_with` editor/embed methods.
///
/// Unlike [`value_text`], the fig dialect's inline-flow override is NOT forced:
/// a container renders in its natural, width-driven layout, so a block map or
/// sequence spells as a section body (`a = 1` / `* x` lines) instead of freezing
/// inline as flow (`{ a = 1 }`). The core editor re-frames such a block value
/// under the target key (adding the marker run), which the plain inline splice
/// cannot express. `options.width` then tunes how eagerly nested containers
/// break to block. Non-fig formats are unaffected by the flow bit and simply
/// honor `options` as usual.
pub(crate) fn value_text_with(
    value: &Value,
    format: Format,
    options: SerializeOptions,
) -> Result<String, Error> {
    let ffi_options: crate::ffi::FigSerializeOptions = options.into(); // flow = 0
    let mut s = value.serialize_ffi(format, ffi_options)?;
    if s.ends_with('\n') {
        s.pop();
    }
    Ok(s)
}

/// Format a float as the text fig stores in `number.raw`: YAML's `.inf`/`.nan`
/// for the specials, and always a fractional part or an exponent so an integral
/// value still reads back as a float. (fig's value API takes float text rather
/// than a `double`, so the canonical formatting lives here until a typed float
/// entry point is added.)
///
/// Notation is picked the way ryu — and so `serde_json` — picks it: plain
/// decimal only while the value's decimal exponent stays in a readable band,
/// scientific outside it. Rust's own `Display` never uses an exponent, so it
/// would spell `1e300` as 301 literal digits and `1e-7` as `0.0000001`; both
/// are valid but neither is practical. Digits come from `Display`/`LowerExp`
/// either way, which are shortest-round-trip, so the value is unchanged.
fn format_float(f: f64) -> String {
    if f.is_nan() {
        return ".nan".to_string();
    }
    if f.is_infinite() {
        return if f < 0.0 { "-.inf" } else { ".inf" }.to_string();
    }

    // `{:e}` normalizes the mantissa to `[1, 10)`, so its exponent `e` gives
    // `kk = e + 1` with `10^(kk-1) <= |f| < 10^kk` — the quantity ryu bands.
    let sci = format!("{f:e}");
    let (mantissa, exponent) = sci.split_once('e').expect("LowerExp always writes an `e`");
    let e: i32 = exponent
        .parse()
        .expect("LowerExp writes a decimal exponent");
    let kk = e + 1;

    // ryu's `pretty` band for f64: decimal while `-5 < kk <= 16`.
    if (-4..=16).contains(&kk) {
        let s = f.to_string();
        // Ensure the value reads back as a float, not an integer.
        if s.bytes().all(|b| b.is_ascii_digit() || b == b'-') {
            format!("{s}.0")
        } else {
            s
        }
    } else if mantissa.contains('.') {
        sci
    } else {
        // `1e300` -> `1.0e300`: a bare-integer mantissa reads back as an *int*
        // in the formats whose float grammar wants a `.` (YAML 1.1), so pad it
        // for the same reason the decimal branch appends `.0`.
        format!("{mantissa}.0e{exponent}")
    }
}

/// Deserialize into a dynamic `Value` — the read-side mirror of the inherent
/// `Value::serialize`. Lets `from_str::<Value>` build a value tree without a
/// concrete target type (the way `serde_json::Value` is used generically).
#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for Value {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        use serde::Deserialize;
        use serde::de::{MapAccess, SeqAccess, Visitor}; // for the recursive `Value::deserialize` in visit_some

        struct ValueVisitor;

        impl<'de> Visitor<'de> for ValueVisitor {
            type Value = Value;

            fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
                f.write_str("any fig value")
            }

            fn visit_bool<E>(self, v: bool) -> Result<Value, E> {
                Ok(Value::Bool(v))
            }
            fn visit_i64<E>(self, v: i64) -> Result<Value, E> {
                Ok(Value::Int(v))
            }
            // `From<u64>`, not `Value::Uint`, so `3u64` deserializes to the
            // same value a document's `3` reads as (see the canonical-form note
            // on `Value`).
            fn visit_u64<E>(self, v: u64) -> Result<Value, E> {
                Ok(Value::from(v))
            }
            fn visit_i128<E>(self, v: i128) -> Result<Value, E> {
                Ok(i64::try_from(v)
                    .map(Value::Int)
                    .unwrap_or(Value::Float(v as f64)))
            }
            fn visit_u128<E>(self, v: u128) -> Result<Value, E> {
                Ok(u64::try_from(v)
                    .map(Value::from)
                    .unwrap_or(Value::Float(v as f64)))
            }
            fn visit_f64<E>(self, v: f64) -> Result<Value, E> {
                Ok(Value::Float(v))
            }
            fn visit_str<E>(self, v: &str) -> Result<Value, E> {
                Ok(Value::Str(v.to_owned()))
            }
            fn visit_string<E>(self, v: String) -> Result<Value, E> {
                Ok(Value::Str(v))
            }
            fn visit_unit<E>(self) -> Result<Value, E> {
                Ok(Value::Null)
            }
            fn visit_none<E>(self) -> Result<Value, E> {
                Ok(Value::Null)
            }
            fn visit_some<D: serde::Deserializer<'de>>(self, d: D) -> Result<Value, D::Error> {
                Value::deserialize(d)
            }
            fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<Value, A::Error> {
                let mut items = Vec::new();
                while let Some(e) = seq.next_element::<Value>()? {
                    items.push(e);
                }
                Ok(Value::Seq(items))
            }
            fn visit_map<A: MapAccess<'de>>(self, mut map: A) -> Result<Value, A::Error> {
                let mut entries = Vec::new();
                while let Some((k, v)) = map.next_entry::<Value, Value>()? {
                    entries.push((k, v));
                }
                Ok(Value::Map(entries))
            }
        }

        deserializer.deserialize_any(ValueVisitor)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // Exercises the whole build+serialize path with no serde involvement, so it
    // runs under `--no-default-features` too.
    #[test]
    fn builds_and_serializes_to_multiple_formats() {
        let v = Value::Map(vec![
            (Value::Str("name".into()), Value::Str("fig".into())),
            (
                Value::Str("nums".into()),
                Value::Seq(vec![Value::Int(1), Value::Int(2)]),
            ),
        ]);
        assert_eq!(
            v.serialize(Format::Yaml).unwrap(),
            "name: fig\nnums: [1, 2]\n"
        );
        assert_eq!(
            v.serialize(Format::Json).unwrap(),
            "{\n  \"name\": \"fig\",\n  \"nums\": [\n    1,\n    2\n  ]\n}\n",
        );
    }

    #[test]
    fn quotes_and_round_trip_safe_strings() {
        // A colon-space scalar must be single-quoted to stay a string.
        assert_eq!(
            Value::Str("a: b".into()).serialize(Format::Yaml).unwrap(),
            "'a: b'\n"
        );
        // A multi-line string *value* becomes a `|` block scalar (a bare root
        // scalar is double-quoted instead, having no containing line to indent).
        let v = Value::Map(vec![(
            Value::Str("s".into()),
            Value::Str("multi\nline".into()),
        )]);
        assert_eq!(
            v.serialize(Format::Yaml).unwrap(),
            "s: |-\n  multi\n  line\n"
        );
    }

    // Rust's `Display` never uses an exponent, so an unbanded `f.to_string()`
    // would write `1e300` as 301 literal digits and `1e-7` as `0.0000001`.
    #[test]
    fn float_text_switches_to_scientific_outside_the_readable_band() {
        assert_eq!(format_float(1e300), "1.0e300");
        assert_eq!(format_float(-1e300), "-1.0e300");
        assert_eq!(format_float(1e-7), "1.0e-7");
        assert_eq!(format_float(1.5e-7), "1.5e-7");
        assert_eq!(format_float(f64::MAX), "1.7976931348623157e308");
        assert_eq!(format_float(5e-324), "5.0e-324");

        // Inside the band, plain decimal — including the `.0` that keeps an
        // integral value a float. The band edges are ryu's: `10^16` is the
        // first magnitude to go scientific, `10^-6` the first below.
        assert_eq!(format_float(0.0), "0.0");
        assert_eq!(format_float(-0.0), "-0.0");
        assert_eq!(format_float(1.0), "1.0");
        assert_eq!(format_float(0.1), "0.1");
        assert_eq!(format_float(1e-5), "0.00001");
        assert_eq!(format_float(1e-6), "1.0e-6");
        assert_eq!(format_float(1e15), "1000000000000000.0");
        assert_eq!(format_float(1e16), "1.0e16");

        assert_eq!(format_float(f64::NAN), ".nan");
        assert_eq!(format_float(f64::INFINITY), ".inf");
        assert_eq!(format_float(f64::NEG_INFINITY), "-.inf");
    }

    // Every spelling above must survive the round trip as the same `f64`.
    #[test]
    fn float_text_round_trips_bit_exactly() {
        for f in [
            1e300,
            -1e300,
            1e-7,
            1.5e-7,
            f64::MAX,
            5e-324,
            0.0,
            -0.0,
            0.1,
            1e-6,
            1e15,
            1e16,
            123456789012345680000.0,
        ] {
            let text = format_float(f);
            let back = Value::parse_float(&text)
                .unwrap_or_else(|| panic!("`{text}` must parse back as a float"));
            assert_eq!(back.to_bits(), f.to_bits(), "round trip of `{text}`");
        }
    }

    #[test]
    #[cfg(feature = "toml")]
    fn null_value_is_unsupported_in_toml() {
        let v = Value::Map(vec![(Value::Str("k".into()), Value::Null)]);
        assert!(matches!(
            v.serialize(Format::Toml),
            Err(Error::UnsupportedFormat)
        ));
    }

    // The non-serde read path: parse → to_value → serialize round-trips.
    #[test]
    fn document_reads_into_value() {
        use crate::{Document, Format};
        let doc =
            Document::parse(b"title: Hi\nnums:\n- 1\n- 2\nratio: 1.5\n", Format::Yaml).unwrap();
        let v = doc.to_value().unwrap();
        assert_eq!(
            v,
            Value::Map(vec![
                ("title".into(), "Hi".into()),
                ("nums".into(), Value::Seq(vec![1i64.into(), 2i64.into()])),
                ("ratio".into(), 1.5.into()),
            ]),
        );
        // round-trips back out through serialize
        assert_eq!(
            v.serialize(Format::Yaml).unwrap(),
            "title: Hi\nnums: [1, 2]\nratio: 1.5\n"
        );
    }

    // TOML datetimes read into `Value::Extended` and serialize back verbatim,
    // instead of degrading to strings.
    #[test]
    #[cfg(feature = "toml")]
    fn toml_datetimes_round_trip_as_extended() {
        use crate::{Document, ExtKind, Format};
        let src = "d = 2026-06-18\nt = 07:32:00\n";
        let v = Document::parse(src.as_bytes(), Format::Toml)
            .unwrap()
            .to_value()
            .unwrap();
        assert_eq!(
            v,
            Value::Map(vec![
                (
                    "d".into(),
                    Value::Extended {
                        kind: ExtKind::LocalDate,
                        text: "2026-06-18".into()
                    }
                ),
                (
                    "t".into(),
                    Value::Extended {
                        kind: ExtKind::LocalTime,
                        text: "07:32:00".into()
                    }
                ),
            ])
        );
        assert_eq!(v.serialize(Format::Toml).unwrap(), src);
    }

    // ZON enum and char literals read into `Value::Extended` (the char literal
    // surfaces as an `int` kind at the ABI, but is recovered faithfully).
    #[test]
    #[cfg(feature = "zon")]
    fn zon_literals_round_trip_as_extended() {
        use crate::{Document, ExtKind, Format};
        let v = Document::parse(b".{ .mode = .fast, .c = 'a' }", Format::Zon)
            .unwrap()
            .to_value()
            .unwrap();
        assert_eq!(
            v,
            Value::Map(vec![
                (
                    "mode".into(),
                    Value::Extended {
                        kind: ExtKind::EnumLiteral,
                        text: "fast".into()
                    }
                ),
                (
                    "c".into(),
                    Value::Extended {
                        kind: ExtKind::CharLiteral,
                        text: "97".into()
                    }
                ),
            ])
        );
    }

    // A built datetime degrades to a string in JSON → one type-degraded warning.
    #[test]
    fn value_diagnose_reports_degraded_datetime() {
        use crate::{Format, SerializeOptions, WarningCode};
        let v = Value::Map(vec![(
            "when".into(),
            Value::Extended {
                kind: ExtKind::OffsetDateTime,
                text: "1979-05-27T07:32:00Z".into(),
            },
        )]);
        let warns = v
            .diagnose(Format::Json, SerializeOptions::default())
            .unwrap();
        assert_eq!(warns.len(), 1);
        assert_eq!(warns[0].code, WarningCode::TypeDegraded);
        assert_eq!(warns[0].path, "when");
        assert_eq!(warns[0].note, "string");
    }

    // A directly-constructed extended value serializes via the existing write ABI.
    #[test]
    #[cfg(feature = "toml")]
    fn constructed_extended_serializes() {
        let v = Value::Map(vec![(
            "when".into(),
            Value::Extended {
                kind: ExtKind::OffsetDateTime,
                text: "1979-05-27T07:32:00Z".into(),
            },
        )]);
        assert_eq!(
            v.serialize(Format::Toml).unwrap(),
            "when = 1979-05-27T07:32:00Z\n"
        );
    }

    #[test]
    fn accessors_match_kind() {
        assert!(Value::Null.is_null());
        assert!(!Value::Bool(false).is_null());

        assert!(Value::Bool(true).is_bool());
        assert_eq!(Value::Bool(true).as_bool(), Some(true));
        assert_eq!(Value::Int(1).as_bool(), None);

        assert!(Value::Str("hi".into()).is_str());
        assert_eq!(Value::Str("hi".into()).as_str(), Some("hi"));
        assert_eq!(Value::Int(1).as_str(), None);

        let ext = Value::Extended {
            kind: ExtKind::LocalDate,
            text: "2026-06-18".into(),
        };
        assert!(ext.is_extended());
        assert_eq!(ext.as_extended(), Some((ExtKind::LocalDate, "2026-06-18")));
        assert_eq!(Value::Null.as_extended(), None);

        let seq = Value::Seq(vec![1i64.into(), 2i64.into()]);
        assert!(seq.is_seq());
        assert_eq!(seq.as_seq(), Some(&[Value::Int(1), Value::Int(2)][..]));
        assert_eq!(Value::Null.as_seq(), None);

        let map = Value::Map(vec![("a".into(), 1i64.into())]);
        assert!(map.is_mapping());
        assert_eq!(
            map.as_mapping(),
            Some(&[(Value::Str("a".into()), Value::Int(1))][..])
        );
        assert_eq!(Value::Null.as_mapping(), None);
    }

    // `Int`/`Uint` are separate variants, but `as_i64`/`as_u64` widen across
    // them when the value fits — `is_i64`/`is_u64` track exactly what those
    // accessors would succeed on. `is_f64` stays strict to the stored variant,
    // since `as_f64` widens any integer and so is a poor "is this a float" test.
    #[test]
    fn numeric_accessors_widen_between_int_and_uint() {
        assert!(Value::Int(5).is_i64());
        assert_eq!(Value::Int(5).as_i64(), Some(5));
        assert!(Value::Int(5).is_u64());
        assert_eq!(Value::Int(5).as_u64(), Some(5));
        assert!(!Value::Int(-5).is_u64());
        assert_eq!(Value::Int(-5).as_u64(), None);

        assert!(Value::Uint(u64::MAX).is_u64());
        assert_eq!(Value::Uint(u64::MAX).as_u64(), Some(u64::MAX));
        assert!(!Value::Uint(u64::MAX).is_i64());
        assert_eq!(Value::Uint(u64::MAX).as_i64(), None);
        assert!(Value::Uint(5).is_i64());
        assert_eq!(Value::Uint(5).as_i64(), Some(5));

        assert!(Value::Float(1.5).is_f64());
        assert_eq!(Value::Float(1.5).as_f64(), Some(1.5));
        assert!(!Value::Int(5).is_f64());
        assert_eq!(Value::Int(5).as_f64(), Some(5.0));
        assert_eq!(Value::Uint(5).as_f64(), Some(5.0));
        assert_eq!(Value::Bool(true).as_f64(), None);
    }

    // A `.nan`/`.inf` document survives parse -> text -> parse: the same text
    // fig writes reads back as the same float. Without `Value::parse_float`, a
    // caller reaching for `str::parse` turns `.inf` into a quoted string on an
    // edit that changed nothing.
    #[test]
    fn float_specials_round_trip_through_the_public_parser() {
        for (text, expect_nan) in [(".inf", false), ("-.inf", false), (".nan", true)] {
            let v = Value::parse_number(text, true).unwrap();
            assert!(
                v.is_f64(),
                "`{text}` must stay a float, not become a string"
            );
            let f = v.as_f64().unwrap();
            assert_eq!(f.is_nan(), expect_nan);
            // ...and the value renders back to the text it was parsed from.
            assert_eq!(format_float(f), text);
        }
        // `str::parse` rejects the spellings fig writes; `parse_float` is the
        // inverse of `format_float` instead (while still taking Rust's own).
        assert!(".inf".parse::<f64>().is_err());
        assert!(Value::parse_float(".inf").unwrap().is_infinite());
        assert!(Value::parse_float("inf").unwrap().is_infinite());
        assert!(Value::parse_float("nope").is_none());
    }

    // The kind drives the variant, not the spelling: `3` in a float field is a
    // float, and an integer past `u64` widens rather than failing.
    #[test]
    fn parse_number_classifies_by_kind() {
        assert_eq!(Value::parse_number("3", false).unwrap(), Value::Int(3));
        assert_eq!(Value::parse_number("-3", false).unwrap(), Value::Int(-3));
        assert_eq!(Value::parse_number("3", true).unwrap(), Value::Float(3.0));
        assert_eq!(
            Value::parse_number("18446744073709551615", false).unwrap(),
            Value::Uint(u64::MAX)
        );
        // Past `u64`: widens to a float, matching how the deserializer reads it.
        assert!(matches!(
            Value::parse_number("184467440737095516150", false).unwrap(),
            Value::Float(_)
        ));
        assert!(matches!(
            Value::parse_number("zero", false),
            Err(Error::Number(_))
        ));
    }

    // Canonical form: an integer that fits in `i64` is `Int`, whatever door it
    // came in by — `From`, the `ToValue` impls, or the document parser. Without
    // this the same number is unequal to itself under the derived `PartialEq`,
    // even though all three of `as_i64`/`as_u64`/`as_f64` read it identically.
    #[test]
    fn small_unsigned_integers_construct_as_int() {
        assert_eq!(Value::from(3u64), Value::Int(3));
        assert_eq!(Value::from(3u64), Value::from(3i64));

        // `i64::MAX` still fits; one past it is where `Uint` starts.
        assert_eq!(Value::from(i64::MAX as u64), Value::Int(i64::MAX));
        let past = i64::MAX as u64 + 1;
        assert_eq!(Value::from(past), Value::Uint(past));
        assert_eq!(Value::from(u64::MAX), Value::Uint(u64::MAX));

        // Reading still spans both variants, so a hand-built `Uint` is not
        // stranded — it just isn't the canonical spelling.
        assert_eq!(Value::Uint(3).as_i64(), Some(3));
        assert!(Value::Int(3).eq_canonical(&Value::Uint(3)));
    }

    // `.nan` is a scalar fig parses *and* renders, so a document holding one can
    // be re-read into a value that isn't `==` to itself. `eq_canonical` is the
    // comparison that converges — what a dirty check needs.
    #[test]
    fn eq_canonical_is_reflexive_over_nan() {
        let nan = Value::Float(f64::NAN);
        assert!(nan != nan);
        assert!(nan.eq_canonical(&nan));

        // Nested, since a dirty check compares whole trees.
        let doc = |f: f64| {
            Value::Map(vec![(
                "xs".into(),
                Value::Seq(vec![Value::Float(f), Value::Int(1)]),
            )])
        };
        assert!(doc(f64::NAN) != doc(f64::NAN));
        assert!(doc(f64::NAN).eq_canonical(&doc(f64::NAN)));
        assert!(doc(f64::INFINITY).eq_canonical(&doc(f64::INFINITY)));
        assert!(!doc(f64::NAN).eq_canonical(&doc(1.0)));

        // Bitwise, so the two zeros differ — they serialize to different text.
        assert!(Value::Float(0.0) == Value::Float(-0.0));
        assert!(!Value::Float(0.0).eq_canonical(&Value::Float(-0.0)));

        // Everything else still behaves like `==`, order-sensitively.
        assert!(Value::Str("a".into()).eq_canonical(&Value::Str("a".into())));
        assert!(!Value::Str("a".into()).eq_canonical(&Value::Int(1)));
        assert!(!Value::Seq(vec![Value::Int(1)]).eq_canonical(&Value::Seq(vec![])));
        let m = |a: &str, b: &str| {
            Value::Map(vec![(a.into(), Value::Int(1)), (b.into(), Value::Int(2))])
        };
        assert!(m("a", "b").eq_canonical(&m("a", "b")));
        assert!(!m("a", "b").eq_canonical(&m("b", "a")));
    }

    // The `ToValue` impls behind the `derive` feature funnel through the same
    // `From<u64>`, so a `u8` field and an `i64` field holding 3 are one value.
    #[test]
    #[cfg(feature = "derive")]
    fn unsigned_to_value_impls_are_canonical_too() {
        use crate::ToValue;

        assert_eq!(3u8.to_value(), Value::Int(3));
        assert_eq!(3u32.to_value(), Value::Int(3));
        assert_eq!(3usize.to_value(), Value::Int(3));
        assert_eq!(3u64.to_value(), 3i64.to_value());
        assert_eq!(u64::MAX.to_value(), Value::Uint(u64::MAX));
    }

    // The parser has always produced `Int` for a small number; the constructors
    // now agree with it.
    #[test]
    #[cfg(feature = "yaml")]
    fn parsed_and_constructed_integers_agree() {
        use crate::{Document, Format};
        let parsed = Document::parse(b"n: 3\n", Format::Yaml)
            .unwrap()
            .to_value()
            .unwrap();
        assert_eq!(parsed, Value::Map(vec![("n".into(), Value::from(3u64))]));
    }

    #[test]
    fn get_looks_up_by_string_key_or_seq_index() {
        let map = Value::Map(vec![
            ("title".into(), "Hi".into()),
            ("count".into(), 42i64.into()),
            ("title".into(), "Overridden".into()),
            ("nums".into(), Value::Seq(vec![1i64.into(), 2i64.into()])),
        ]);
        // Last-wins on a duplicate key.
        assert_eq!(map.get("title"), Some(&Value::Str("Overridden".into())));
        assert_eq!(map.get("count"), Some(&Value::Int(42)));
        assert_eq!(map.get("missing"), None);
        assert_eq!(Value::Seq(vec![]).get("title"), None);

        // A `String` key works the same as `&str`, and chains through nested
        // lookups by index.
        assert_eq!(map.get(String::from("count")), Some(&Value::Int(42)));
        assert_eq!(map.get("nums").and_then(|v| v.get(1)), Some(&Value::Int(2)));
        assert_eq!(map.get("nums").and_then(|v| v.get(9)), None);
        assert_eq!(Value::Null.get(0), None);
    }

    // `value[key]`/`value[index]` never panics: a mismatched kind or missing
    // key/index reads back as `Value::Null`, same as a `None` from `get`.
    #[test]
    fn index_operator_returns_null_instead_of_panicking() {
        let map = Value::Map(vec![(
            "nums".into(),
            Value::Seq(vec![1i64.into(), 2i64.into()]),
        )]);
        assert_eq!(map["nums"][0], Value::Int(1));
        assert_eq!(map["nums"][9], Value::Null);
        assert_eq!(map["missing"], Value::Null);
        assert_eq!(Value::Null["a"], Value::Null);
        assert_eq!(Value::Null[0], Value::Null);
    }
}