shape/

case_enum.rs

pub(crate) mod all;
pub(crate) mod one;

use indexmap::IndexMap;

use self::all::All;
use self::one::One;
use super::Shape;
use crate::name::Name;
use crate::name::WeakScope;

/// The [`ShapeCase`] enum attempts to capture all the common shapes of JSON
/// values, not just the JSON types themselves, but also patterns of usage (such
/// as using JSON arrays as either static tuples or dynamic lists).
///
/// A [`ShapeCase`] enum variant like [`ShapeCase::One`] may temporarily
/// represent a structure that has not been fully simplified, but simplication
/// is required to turn the [`ShapeCase`] into a `Shape`, using the
/// `ShapeCase::simplify(&self) -> Shape` method.
#[derive(Clone, Debug)]
pub enum ShapeCase {
    /// The `Bool`, `String`, and `Int` variants can either represent a general
    /// shape using `None` for the `Option`, or a specific shape using `Some`.
    /// For example, `ShapeCase::Bool(None)` is a shape satisfied by either true
    /// or false, like the Rust bool type, while `ShapeCase::Bool(Some(true))`
    /// is a shape satisfied only by `true` (and likewise for `false`).
    Bool(Option<bool>),

    /// Similar to [`ShapeCase::Bool`], [`ShapeCase::String`] represents a shape
    /// matching either any string (in the `None` case) or some specific string
    /// (in the `Some` case).
    String(Option<String>),

    /// Similar to [`ShapeCase::Bool`] and [`ShapeCase::String`],
    /// [`ShapeCase::Int`] can represent either any integer or some specific
    /// integer.
    Int(Option<i64>),

    /// [`ShapeCase::Float`] is a shape that captures the set of all floating
    /// point numbers. We do not allow singleton floating point value shapes,
    /// since floating point equality is unreliable.
    Float,

    /// [`ShapeCase::Null`] is a singleton shape whose only possible value is
    /// `null`. Note that [`ShapeCase::Null`] is different from
    /// [`ShapeCase::None`], which represents the absence of a value.
    Null,

    /// [`ShapeCase::Array`] represents a `prefix` of statically known shapes
    /// (like a tuple type), followed by an optional `tail` shape for all other
    /// (dynamic) elements. When only the `prefix` elements are defined, the
    /// `tail` shape is [`ShapeCase::None`]. `ShapeCase::Array(vec![],
    /// ShapeCase::None)` is the shape of an empty array.
    Array { prefix: Vec<Shape>, tail: Shape },

    /// [`ShapeCase::Object`] is a map of statically known field names to field
    /// shapes, together with an optional type for all other string keys. When
    /// dynamic string indexing is disabled, the rest shape will be
    /// [`ShapeCase::None`]. Note that accessing the dynamic map always returns
    /// `ShapeCase::One([rest_shape, ShapeCase::None])`, to reflect the
    /// uncertainty of the shape of dynamic keys not present in the static
    /// fields.
    Object {
        // TODO: track location of keys
        fields: IndexMap<String, Shape>,
        rest: Shape,
    },

    /// A union of shapes, satisfied by values that satisfy any of the shapes in
    /// the set.
    ///
    /// Create using [`Shape::one`].
    One(One),

    /// An intersection of shapes, satisfied by values that satisfy all of the
    /// shapes in the set. When applied to multiple [`ShapeCase::Object`]
    /// shapes, [`ShapeCase::All`] represents merging the fields of the objects,
    /// as reflected by the simplification logic.
    ///
    /// Crete using [`Shape::all`].
    All(All),

    /// [`ShapeCase::Name`] refers to a shape declared with the given [`Name`],
    /// whose non-symbolic structure may not be known until later.
    ///
    /// When the [`ShapeCase::Name`] participates in a
    /// [`crate::name::Namespace`], it may acquire a non-empty [`WeakScope`],
    /// which can enable the symbolic [`Name`] to be resolved in the scope,
    /// providing richer shape information than a [`Name`] alone.
    ///
    /// When shape processing needs to refer to the shape of some subproperty of
    /// an unspecified named shape, it can append subproperty chains to the
    /// immutable [`Name`] structure using methods like `field()` or `item()`
    /// (among other methods) to obtain the nested name. When the named shape is
    /// eventually declared, the nested structure can be used to resolve the
    /// actual shape of the nested property path, using the [`WeakScope`].
    Name(Name, WeakScope),

    /// [`ShapeCase::Unknown`] is a shape that represents any possible JSON
    /// value (including `ShapeCase::None`).
    Unknown,

    /// Represents the absence of a value, or the shape of a property not
    /// present in an object. Used by the rest parameters of both
    /// [`ShapeCase::Array`] and [`ShapeCase::Object`] to indicate no additional
    /// dynamic elements are allowed, and with [`ShapeCase::One`] to represent
    /// optionality of values, e.g. `One<Bool, None>`.
    None,
}

// Same as default #[derive(PartialEq)] except for ::Name resolution.
impl Eq for ShapeCase {}
impl PartialEq for ShapeCase {
    fn eq(&self, other: &Self) -> bool {
        match (self, other) {
            (Self::Null, Self::Null)
            | (Self::None, Self::None)
            | (Self::Float, Self::Float)
            | (Self::Unknown, Self::Unknown) => true,
            (Self::Bool(a), Self::Bool(b)) => a == b,
            (Self::String(a), Self::String(b)) => a == b,
            (Self::Int(a), Self::Int(b)) => a == b,
            (Self::One(self_shapes), Self::One(other_shapes)) => self_shapes == other_shapes,
            (Self::All(self_shapes), Self::All(other_shapes)) => self_shapes == other_shapes,
            (
                Self::Array {
                    prefix: self_prefix,
                    tail: self_tail,
                },
                Self::Array {
                    prefix: other_prefix,
                    tail: other_tail,
                },
            ) => self_prefix == other_prefix && self_tail == other_tail,
            (
                Self::Object {
                    fields: self_fields,
                    rest: self_rest,
                },
                Self::Object {
                    fields: other_fields,
                    rest: other_rest,
                },
            ) => self_fields == other_fields && self_rest == other_rest,
            // Two ShapeCase::Name values are equal iff their symbolic Names are
            // equal. We deliberately do not recursively compare the shapes they
            // resolve to through their WeakScope: within a given Namespace, the
            // invariant is that any two Name values sharing the same base name
            // refer to the same underlying Shape (see Namespace::insert, which
            // merges colliding names), so recursive comparison would be
            // redundant. Comparing across Namespaces is not meaningful — names
            // are symbolic — and attempting to recurse can diverge on
            // self-referential shapes (e.g. `Foo = List<Foo>`).
            (Self::Name(self_name, _), Self::Name(other_name, _)) => self_name == other_name,
            _ => false,
        }
    }
}

impl ShapeCase {
    #[must_use]
    pub fn is_none(&self) -> bool {
        matches!(self, Self::None)
    }

    #[must_use]
    pub fn is_null(&self) -> bool {
        matches!(self, Self::Null)
    }

    pub(crate) fn nested_base_names(&self) -> impl Iterator<Item = &str> {
        match self {
            Self::Name(name, _weak) => vec![name.base_shape_name()].into_iter(),
            Self::Array { prefix, tail } => {
                let mut names = Vec::new();
                for shape in prefix {
                    names.extend(shape.nested_base_names());
                }
                names.extend(tail.nested_base_names());
                names.into_iter()
            }
            Self::Object { fields, rest } => {
                let mut names = Vec::new();
                for shape in fields.values() {
                    names.extend(shape.nested_base_names());
                }
                names.extend(rest.nested_base_names());
                names.into_iter()
            }
            Self::One(shapes) => shapes
                .iter()
                .flat_map(Shape::nested_base_names)
                .collect::<Vec<_>>()
                .into_iter(),
            Self::All(shapes) => shapes
                .iter()
                .flat_map(Shape::nested_base_names)
                .collect::<Vec<_>>()
                .into_iter(),
            _ => vec![].into_iter(),
        }
    }
}

impl From<bool> for ShapeCase {
    fn from(value: bool) -> Self {
        ShapeCase::Bool(Some(value))
    }
}

impl From<String> for ShapeCase {
    fn from(value: String) -> Self {
        ShapeCase::String(Some(value))
    }
}

impl From<&str> for ShapeCase {
    fn from(value: &str) -> Self {
        ShapeCase::String(Some(value.to_string()))
    }
}

impl From<i64> for ShapeCase {
    fn from(value: i64) -> Self {
        ShapeCase::Int(Some(value))
    }
}

impl PartialEq<&ShapeCase> for ShapeCase {
    fn eq(&self, other: &&ShapeCase) -> bool {
        self == *other
    }
}

impl PartialEq<ShapeCase> for &ShapeCase {
    fn eq(&self, other: &ShapeCase) -> bool {
        *self == other
    }
}

/// Represents a local failure of shape processing. Errors are stored as
/// metadata in [`crate::meta::ShapeMeta`] rather than as a shape variant,
/// allowing any shape to carry error information without changing its
/// structural identity.
#[derive(Clone, Debug, Eq, PartialEq, Hash)]
pub struct Error {
    pub message: String,
}