shape/

lib.rs

mod accepts;
mod case_enum;
mod child_shape;
mod display;
mod from_json;
mod hashing;
mod helpers;
mod simplify;

#[cfg(test)]
mod tests;

pub use accepts::ShapeMismatch;
pub use case_enum::ShapeCase;
pub use child_shape::NamedShapePathKey;
pub use helpers::OffsetRange;

use helpers::Ref;
use indexmap::IndexMap;

/// The `shape::Shape` struct provides a recursive, immutable, reference-counted
/// tree/DAG format for representing and enforcing common structures and usage
/// patterns of JSON-like data.
///
/// The `Shape` system is not bound to any particular programming language, so
/// it does not inherit a data model that it must represent and defend, yet it
/// must adopt/assume _some_ concrete data model, since a type system without a
/// data model to enforce is as useful as a straitjacket on a coat rack. JSON
/// was chosen for its relative simplicity, its ubiquity as a data interchange
/// format used across programming languages, and because JSON is often used in
/// scenarios without a static type system to help catch errors before runtime.
///
/// The `Shape` system has no source syntax for denoting shapes directly, but
/// you can use the `Shape::*` helper functions to create shapes
/// programmatically, in Rust. `Shape::pretty_print()` provides a human-readable
/// representation of a `Shape` for debugging and testing purposes.
///
/// All in all, this _Static `Shape` System_ (SSS) supports the following
/// type-theoretic features:
///
/// - [x] Primitive shapes: `Bool`, `String`, `Int`, `Float`, `Null`
/// - [x] Singleton primitive shapes: `true`, `false`, `"hello"`, `42`, `null`
/// - [x] `Array` shapes, supporting both static tuples and dynamic lists
/// - [x] `Object` shapes, supporting both static fields and dynamic string keys
/// - [x] `One<S1, S2, ...>` union shapes, representing a set of shape
///   alternatives
/// - [x] `All<S1, S2, ...>` intersection shapes, representing a set
///   simultaneous requirements
/// - [x] `shape.field(name)` and `shape.item(index)` methods for accessing the
///   shape of a subproperty of a shape
/// - [x] `Name` shape references, with support for symbolic subproperty shape
///   access
/// - [x] `Error` shapes, representing a failure of shape processing, with
///   support for chains of errors and partial shape data
/// - [x] `None` shapes, representing the absence of a value (helpful for
///   representing optionality of shapes)
/// - [x] `subshape.satisfies(supershape)` and `supershape.accepts(subshape)`
///   methods for testing shape relationships
/// - [x] `shape.accepts_json(json)` method for testing whether concrete JSON
///   data satisfies some expected shape
/// - [x] `shape.pretty_print()` method for debugging and testing

#[derive(Clone, PartialEq, Eq)]
// [`Shape`] enforces the simplification of [`ShapeCase`] variants, because
// there is no way to create a [`Shape`] without simplifying the input
// [`ShapeCase`]. This is a very useful invariant because it allows each
// [`ShapeCase`] to assume its immediate [`Shape`] children have already been
// simplified.
//
// In addition simplification, [`Shape`] supports testing shape-shape acceptance
// (or the equivalent inverse, satisfaction) with `super.accepts(sub)` and/or
// `sub.satisfies(super)`. See also `shape.accepts_json(json)` for testing
// whether concrete JSON data satisfies some expected `shape`.
//
// In the future, we may internalize/canonize shapes to reduce memory usage,
// especially for well-known shapes like `Bool` and `Int` and `String`. This
// would require either thread safety (is `type Ref<T> = std::sync::Arc<T>`
// enough?) or maintaining per-thread canonical shape tables.
pub struct Shape {
    // This field is private, but if you want to match against an immutable
    // reference to the `ShapeCase` variant, use `match shape.case() { ... }`.
    case: Ref<ShapeCase>,

    // Since `Shape` is immutable, we might as well precompute its hashed value.
    //
    // This means `case.compute_hash()` only has to examine the saved hashes of
    // its immediate Shape children, rather than recursively hashing the entire
    // tree every time.
    //
    // However, this approach implicitly requires the `Shape` hierarchy to be a
    // tree (or at least a directed acylic graph), because hashing cycles of
    // `Shape`s (while possible) is less efficient than incrementally hashing
    // each level of a strict hierarchy.
    //
    // That's no great loss, because it's difficult to create `Shape` cycles
    // anyway, given that `Shape`s are immutable.
    case_hash: u64,
}

lazy_static::lazy_static! {
    static ref TRUE_SHAPE: Shape = Shape::new_from_simplified(ShapeCase::Bool(Some(true)));
    static ref FALSE_SHAPE: Shape = Shape::new_from_simplified(ShapeCase::Bool(Some(false)));
    static ref BOOL_SHAPE: Shape = Shape::new_from_simplified(ShapeCase::Bool(None));
    static ref STRING_SHAPE: Shape = Shape::new_from_simplified(ShapeCase::String(None));
    static ref INT_SHAPE: Shape = Shape::new_from_simplified(ShapeCase::Int(None));
    static ref FLOAT_SHAPE: Shape = Shape::new_from_simplified(ShapeCase::Float);
    static ref NULL_SHAPE: Shape = Shape::new_from_simplified(ShapeCase::Null);
    static ref NONE_SHAPE: Shape = Shape::new_from_simplified(ShapeCase::None);
    static ref EMPTY_ARRAY_SHAPE: Shape = Shape::new_from_simplified(ShapeCase::Array {
        prefix: vec![],
        tail: Shape::none(),
    });
    static ref EMPTY_OBJECT_SHAPE: Shape = Shape::new_from_simplified(ShapeCase::Object {
        fields: Shape::empty_map(),
        rest: Shape::none(),
    });
}

impl Shape {
    /// Create a `Shape` from a `ShapeCase` variant that is known to be already
    /// simplified. This method must remain crate-private to protect the
    /// invariant that all `Shape` instances have been simplified.
    pub(crate) fn new_from_simplified(case: ShapeCase) -> Shape {
        let case = Ref::new(case);
        let case_hash = case.compute_hash();
        Shape { case, case_hash }
    }

    /// When boolean helper methods like `.is_none()` and `.is_null()` are not
    /// enough, you can match against the underlying `ShapeCase` by obtaining an
    /// immutable `&ShapeCase` reference using the `shape.case()` method.
    pub fn case(&self) -> &ShapeCase {
        self.case.as_ref()
    }

    /// Returns a `Shape` that accepts any boolean value, `true` or `false`.
    pub fn bool() -> Self {
        BOOL_SHAPE.clone()
    }

    /// Returns a `Shape` that accepts only the specified boolean value.
    pub fn bool_value(value: bool) -> Self {
        if value {
            TRUE_SHAPE.clone()
        } else {
            FALSE_SHAPE.clone()
        }
    }

    /// Returns a `Shape` that accepts any string value.
    pub fn string() -> Self {
        STRING_SHAPE.clone()
    }

    /// Returns a `Shape` that accepts only the specified string value.
    pub fn string_value(value: &str) -> Self {
        Self::new_from_simplified(ShapeCase::String(Some(value.to_string())))
    }

    /// Returns a `Shape` that accepts any integer value.
    pub fn int() -> Self {
        INT_SHAPE.clone()
    }

    /// Returns a `Shape` that accepts only the specified integer value.
    pub fn int_value(value: i64) -> Self {
        Self::new_from_simplified(ShapeCase::Int(Some(value)))
    }

    /// Returns a `Shape` that accepts any floating point value.
    pub fn float() -> Self {
        FLOAT_SHAPE.clone()
    }

    /// Returns a `Shape` that accepts only the JSON `null` value.
    pub fn null() -> Self {
        NULL_SHAPE.clone()
    }

    pub fn is_null(&self) -> bool {
        self.case.is_null()
    }

    /// Returns a symbolic reference to a named shape, potentially not yet
    /// defined.
    ///
    /// In order to add items to the subpath of this named shape, call the
    /// `.field(name)` and/or `.item(index)` methods.
    ///
    /// Note that variable shapes are represented by `ShapeCase::Name` where the
    /// name string includes the initial `$` character.
    pub fn name(name: &str) -> Self {
        Self::new_from_simplified(ShapeCase::Name(name.to_string(), vec![]))
    }

    /// Useful for obtaining the kind of IndexMap this library uses for the
    /// ShapeCase::Object variant.
    pub fn empty_map() -> IndexMap<String, Self> {
        IndexMap::new()
    }

    /// Returns a `Shape` that accepts any object shape, regardless of the other
    /// shape's `fields` or `rest` shape, because an empty object shape `{}`
    /// imposes no expectations on other objects (except that they are objects).
    ///
    /// In the other direction, an empty object shape `{}` can satisfy itself or
    /// any `Dict<V>` shape (where the `Dict` may be dynamically empty), but
    /// cannot satisfy any object shape with non-empty `fields`.
    pub fn empty_object() -> Self {
        EMPTY_OBJECT_SHAPE.clone()
    }

    /// To get a compatible empty mutable [`IndexMap`] without directly
    /// depending on the `indexmap` crate yourself, use `Shape::empty_map()`.
    pub fn object(fields: IndexMap<String, Shape>, rest: Shape) -> Self {
        ShapeCase::Object { fields, rest }.simplify()
    }

    /// Returns a `Shape` that accepts any object shape with the given static
    /// fields, with no dynamic fields considered.
    pub fn record(fields: IndexMap<String, Shape>) -> Self {
        Shape::object(fields, Shape::none())
    }

    /// Returns a `Shape` that accepts any dictionary-like object with dynamic
    /// string properties having a given value shape.
    pub fn dict(value_shape: Shape) -> Self {
        Shape::object(Shape::empty_map(), value_shape)
    }

    /// Arrays, tuples, and lists are all manifestations of the same underlying
    /// [`ShapeCase::Array`] representation.
    pub fn array(prefix: &[Shape], tail: Shape) -> Self {
        let prefix = prefix.to_vec();
        Self::new_from_simplified(ShapeCase::Array { prefix, tail })
    }

    /// A tuple is a [`ShapeCase::Array`] with statically known (though possibly
    /// empty) element shapes and no dynamic tail shape.
    pub fn tuple(shapes: &[Shape]) -> Self {
        Shape::array(shapes, Shape::none())
    }

    /// A `List<S>` is a [`ShapeCase::Array`] with an empty static `prefix` and a
    /// dynamic element shape `S`.
    pub fn list(of: Shape) -> Self {
        Shape::array(&[], of)
    }

    /// Returns a `Shape` that accepts any empty array, returning
    /// `Shape::none()` for all index accesses.
    pub fn empty_array() -> Self {
        EMPTY_ARRAY_SHAPE.clone()
    }

    /// Returns a `ShapeCase::One` union of the given shapes, simplified.
    pub fn one(shapes: &[Shape]) -> Self {
        ShapeCase::One(shapes.iter().cloned().collect()).simplify()
    }

    /// Returns a `ShapeCase::All` intersection of the given shapes, simplified.
    pub fn all(shapes: &[Shape]) -> Self {
        ShapeCase::All(shapes.iter().cloned().collect()).simplify()
    }

    pub fn none() -> Self {
        NONE_SHAPE.clone()
    }

    pub fn is_none(&self) -> bool {
        self.case.is_none()
    }

    /// Report a failure of shape processing.
    pub fn error(message: &str) -> Self {
        Self::new_from_simplified(ShapeCase::error(message))
    }

    pub fn is_error(&self) -> bool {
        matches!(self.case(), ShapeCase::Error { .. })
    }

    /// Report a failure of shape processing associated with a specific source
    /// OffsetRange.
    pub fn error_with_range(message: &str, range: OffsetRange) -> Self {
        Self::new_from_simplified(ShapeCase::error_with_range(message, range))
    }

    /// Report a failure of shape processing associated with a
    /// partial/best-guess shape that may still be useful.
    pub fn error_with_partial(message: &str, partial: Shape) -> Self {
        Self::new_from_simplified(ShapeCase::error_with_partial(message, partial))
    }

    pub fn error_with_range_and_partial(message: &str, range: OffsetRange, partial: Shape) -> Self {
        Self::new_from_simplified(ShapeCase::error_with_range_and_partial(
            message, range, partial,
        ))
    }
}