shape/

case_enum.rs

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

use std::iter::{empty, once};

use self::all::All;
use self::one::One;
use super::child_shape::NamedShapePathKey;
use super::Shape;
use crate::location::Located;
use indexmap::IndexMap;

/// 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, PartialEq, Eq)]
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,
    /// possibly in the future. When shape processing needs to refer to the
    /// shape of some subproperty of a named shape, it uses the
    /// `Vec<NamedShapePathKey>` subpath to represent the nested shape. When the
    /// named shape is eventually declared, the subpath can be used to resolve
    /// the actual shape of the nested property path.
    //
    /// As of now, the name `String` is expected to be either an identifier or a
    /// variable name like `$root` or `$this` or `$args`, allowing
    /// [`ShapeCase::Name`] to represent types of subproperties of variables as
    /// well as named types from some schema.
    Name(Located<String>, Vec<Located<NamedShapePathKey>>),

    /// [`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,

    /// Represents a local failure of shape processing.
    Error(Error),
}

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)
    }

    #[must_use]
    pub fn error(message: String) -> Self {
        Self::Error(Error {
            message,
            partial: None,
        })
    }

    #[must_use]
    pub fn error_with_partial(message: String, partial: Shape) -> Self {
        Self::Error(Error {
            message,
            partial: Some(partial),
        })
    }

    /// Iterate over all errors within this shape, recursively
    pub fn errors(&self) -> Box<dyn Iterator<Item = &Error> + '_> {
        match self {
            Self::Error(error) => Box::new(once(error)),
            Self::Array { prefix, tail } => {
                Box::new(prefix.iter().flat_map(Shape::errors).chain(tail.errors()))
            }
            Self::Object { fields, rest } => {
                Box::new(fields.values().flat_map(Shape::errors).chain(rest.errors()))
            }
            Self::One(shapes) => Box::new(shapes.iter().flat_map(Shape::errors)),
            Self::All(shapes) => Box::new(shapes.iter().flat_map(Shape::errors)),
            _ => Box::new(empty()),
        }
    }
}

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.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Error {
    pub message: String,
    /// This `partial` shape can be another `ShapeCase::Error` shape, which
    /// allows for chaining of multiple errors.
    pub partial: Option<Shape>,
}

impl From<Error> for ShapeCase {
    fn from(error: Error) -> Self {
        ShapeCase::Error(error)
    }
}