sim_shape/
lib.rs

1#![forbid(unsafe_code)]
2#![allow(deprecated)]
3#![deny(missing_docs)]
4//! Shape algebra, comparison, and match-hook helpers.
5//!
6//! `sim-shape` supplies concrete `Shape` implementations while the kernel owns
7//! only the open shape protocol.
8//!
9//! ```rust
10//! use std::sync::Arc;
11//!
12//! use sim_kernel::{Cx, DefaultFactory, Expr, NoopEvalPolicy};
13//! use sim_shape::{
14//!     AnyShape, ExactExprShape, ExprKind, ExprKindShape, HookedShape, Shape,
15//!     ShapeRelationKind, TraceMarkHook, relate_shapes,
16//! };
17//!
18//! let mut cx = Cx::new(Arc::new(NoopEvalPolicy), Arc::new(DefaultFactory));
19//! let exact_true = ExactExprShape::new(Expr::Bool(true));
20//! let bool_expr = ExprKindShape::new(ExprKind::Bool);
21//! let relation = relate_shapes(&mut cx, &exact_true, &bool_expr, &[]).unwrap();
22//!
23//! assert_eq!(relation.kind, ShapeRelationKind::LeftSubshape);
24//! assert!(relation.proven);
25//!
26//! let hooked = HookedShape::new(Arc::new(AnyShape), vec![Arc::new(TraceMarkHook)]);
27//! let matched = hooked.check_expr(&mut cx, &Expr::String("trace me".to_owned())).unwrap();
28//! assert!(matched.accepted);
29//! assert!(matched.diagnostics.iter().any(|diagnostic| {
30//!     diagnostic.message.starts_with("shape-hook:mark")
31//! }));
32//! ```
33//!
34//! # Surface
35//!
36//! The engine is organized into private module groups whose public items are
37//! re-exported at the crate root (the modules themselves are not public):
38//!
39//! - `primitives` -- atomic shapes (`AnyShape`, `ExactExprShape`,
40//!   `ExprKindShape`, `ClassShape`, `NumberValueShape`, `ListShape`,
41//!   `FieldShape`) and the combinators and object-grammar parsers built on
42//!   them.
43//! - `algebra` -- boolean and collection shape algebra: `AndShape`,
44//!   `OrShape`, `NotShape`, `RepeatShape`, and `TableShape` with its field and
45//!   extra-field policies.
46//! - `compare` -- shape comparison and subsumption: normalization
47//!   (`normalize_shape`, `ShapeNormalForm`), relation analysis
48//!   (`relate_shapes`, `ShapeRelation`), and `VennShapeSet` set reasoning.
49//! - `citizen` -- citizen integration: class registration, codec, and
50//!   construction for shape objects, plus the `*_class_symbol` accessors.
51//! - `functions` -- the callable shape object: `FunctionObject`,
52//!   `FunctionCase`, overload selection, and shape-as-value wrapping.
53//! - `hooks` -- match-extension hooks: `HookedShape` and the `MatchHook`
54//!   protocol with the built-in hook implementations.
55//! - `parse` -- the shape grammar parser that turns an `Expr` into a `Shape`
56//!   and runs checks against expressions and values.
57//! - `base` -- the base shape vocabulary re-exported from the kernel
58//!   (`Shape`, `ShapeMatch`, `ShapeDoc`, `Bindings`, `ShapeReport`).
59
60mod algebra;
61mod base;
62mod citizen;
63#[cfg(test)]
64mod citizen_tests;
65mod compare;
66mod diagnostics;
67mod functions;
68mod hooks;
69mod options;
70mod parse;
71#[cfg(test)]
72mod parse_tests;
73mod primitives;
74mod recursion;
75#[cfg(test)]
76mod tests;
77
78pub use algebra::{
79    AndShape, NotShape, OrShape, OrStrategy, RepeatShape, TableExtraPolicy, TableFieldSpec,
80    TableShape,
81};
82pub use base::{
83    Bindings, ExprKind, MatchScore, Shape, ShapeBindings, ShapeDoc, ShapeMatch, ShapeReport,
84    check_value_report, insert_shape_satisfaction_claim, satisfies_shape_predicate,
85    shape_report_from_match,
86};
87pub use citizen::{
88    and_shape_class_symbol, any_shape_class_symbol, class_shape_class_symbol,
89    exact_expr_shape_class_symbol, expr_kind_shape_class_symbol, hooked_shape_class_symbol,
90    list_shape_class_symbol, not_shape_class_symbol, or_shape_class_symbol,
91    repeat_shape_class_symbol, table_shape_class_symbol, venn_shape_set_class_symbol,
92};
93pub use compare::{
94    ShapeNormalForm, ShapeNormalKind, ShapeProbe, ShapeRelation, ShapeRelationKind, ShapeWitness,
95    VennShapeSet, normalize_shape, relate_shapes,
96};
97pub use diagnostics::{
98    binding_failure_diagnostic, callable_mismatch_diagnostic, expected_shape_diagnostic,
99    overload_selection_diagnostic,
100};
101pub use functions::{
102    FunctionCase, FunctionObject, NativeFunctionImpl, SelectedCase, ShapeObject, case_result_shape,
103    case_shape, function_cases, overload, shape_value, shape_value_with_encoding,
104};
105pub use hooks::{
106    AcceptOnNoDiagnosticsHook, DiscardOnDiagnosticPrefixHook, HookedShape, MatchHook,
107    MatchHookContext, MatchHookDecision, MatchHookKind, MatchHookObject, MatchHookPhase,
108    MatchHookTargetKind, ScoreFloorHook, TraceMarkHook, accept_on_no_diagnostics_hook_class_symbol,
109    discard_on_diagnostic_prefix_hook_class_symbol, hook_ref_arc, hook_value,
110    score_floor_hook_class_symbol, trace_mark_hook_class_symbol,
111};
112pub use options::{OptionFieldSpec, check_option_map};
113pub use parse::{check_shape_on_expr, check_shape_on_value, parse_shape_expr, shape_error};
114pub use primitives::{
115    AnyShape, CaptureShape, ClassShape, EffectfulShape, ExactExprShape, ExprKindShape, FieldShape,
116    FieldSpec, ListShape, NumberValueShape, ObjectExpr, OneOfShape, PrattShape, ShapeExprParser,
117};
sim_shape/lib.rs

sim_shape/
lib.rs
