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//! - `grammar` -- codec-neutral grammar graph lowering plus the seed JSON
56//!   Schema renderer used by existing model-runner contracts.
57//! - `parse` -- the shape grammar parser that turns an `Expr` into a `Shape`
58//!   and runs checks against expressions and values.
59//! - `recursive` -- recursive shape descriptors with named definitions and
60//!   bounded reference checks.
61//! - `base` -- the base shape vocabulary re-exported from the kernel
62//!   (`Shape`, `ShapeMatch`, `ShapeDoc`, `Bindings`, `ShapeReport`).
63
64mod algebra;
65mod base;
66mod citizen;
67#[cfg(test)]
68mod citizen_tests;
69mod compare;
70mod diagnostics;
71#[cfg(test)]
72mod duplicate_key_tests;
73mod duplicate_keys;
74mod functions;
75mod grammar;
76mod hooks;
77mod options;
78mod parse;
79#[cfg(test)]
80mod parse_tests;
81mod primitives;
82mod recursion;
83mod recursive;
84#[cfg(test)]
85mod tests;
86
87pub use algebra::{
88    AndShape, NotShape, OrShape, OrStrategy, RepeatShape, TableExtraPolicy, TableFieldSpec,
89    TableShape,
90};
91pub use base::{
92    Bindings, ExprKind, MatchScore, Shape, ShapeBindings, ShapeDoc, ShapeMatch, ShapeReport,
93    check_value_report, insert_shape_satisfaction_claim, satisfies_shape_predicate,
94    shape_report_from_match,
95};
96pub use citizen::{
97    and_shape_class_symbol, any_shape_class_symbol, class_shape_class_symbol,
98    exact_expr_shape_class_symbol, expr_kind_shape_class_symbol, hooked_shape_class_symbol,
99    list_shape_class_symbol, not_shape_class_symbol, or_shape_class_symbol,
100    repeat_shape_class_symbol, shape_def_ref_class_symbol, shape_defs_class_symbol,
101    table_shape_class_symbol, venn_shape_set_class_symbol,
102};
103pub use compare::{
104    ShapeNormalForm, ShapeNormalKind, ShapeProbe, ShapeRelation, ShapeRelationKind, ShapeWitness,
105    VennShapeSet, normalize_shape, relate_shapes,
106};
107pub use diagnostics::{
108    binding_failure_diagnostic, callable_mismatch_diagnostic, expected_shape_diagnostic,
109    overload_selection_diagnostic,
110};
111pub use functions::{
112    FunctionCase, FunctionObject, NativeFunctionImpl, SelectedCase, ShapeObject, case_result_shape,
113    case_shape, function_cases, overload, shape_value, shape_value_with_encoding,
114};
115pub use grammar::{
116    GrammarDialect, GrammarGraph, GrammarPosition, GrammarRenderer, GrammarTarget, Production,
117    ShapeGrammar, TerminalAtom, shape_grammar, shape_grammar_graph, shape_json_schema,
118};
119pub use hooks::{
120    AcceptOnNoDiagnosticsHook, DiscardOnDiagnosticPrefixHook, HookedShape, MatchHook,
121    MatchHookContext, MatchHookDecision, MatchHookKind, MatchHookObject, MatchHookPhase,
122    MatchHookTargetKind, ScoreFloorHook, TraceMarkHook, accept_on_no_diagnostics_hook_class_symbol,
123    discard_on_diagnostic_prefix_hook_class_symbol, hook_ref_arc, hook_value,
124    score_floor_hook_class_symbol, trace_mark_hook_class_symbol,
125};
126pub use options::{OptionFieldSpec, check_option_map};
127pub use parse::{check_shape_on_expr, check_shape_on_value, parse_shape_expr, shape_error};
128pub use primitives::{
129    AnyShape, CaptureShape, ClassShape, EffectfulShape, ExactExprShape, ExprKindShape, FieldShape,
130    FieldSpec, ListShape, NumberValueShape, ObjectExpr, OneOfShape, PrattShape, ShapeExprParser,
131};
132pub use recursive::{ShapeDefRef, ShapeDefs};
sim_shape/lib.rs

sim_shape/
lib.rs
