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

sim_shape/
lib.rs
