Crate sim_shape 

Shape algebra, comparison, and match-hook helpers.

sim-shape supplies concrete Shape implementations while the kernel owns only the open shape protocol.

use std::sync::Arc;

use sim_kernel::{Cx, DefaultFactory, Expr, NoopEvalPolicy};
use sim_shape::{
    AnyShape, ExactExprShape, ExprKind, ExprKindShape, HookedShape, Shape,
    ShapeRelationKind, TraceMarkHook, relate_shapes,
};

let mut cx = Cx::new(Arc::new(NoopEvalPolicy), Arc::new(DefaultFactory));
let exact_true = ExactExprShape::new(Expr::Bool(true));
let bool_expr = ExprKindShape::new(ExprKind::Bool);
let relation = relate_shapes(&mut cx, &exact_true, &bool_expr, &[]).unwrap();

assert_eq!(relation.kind, ShapeRelationKind::LeftSubshape);
assert!(relation.proven);

let hooked = HookedShape::new(Arc::new(AnyShape), vec![Arc::new(TraceMarkHook)]);
let matched = hooked.check_expr(&mut cx, &Expr::String("trace me".to_owned())).unwrap();
assert!(matched.accepted);
assert!(matched.diagnostics.iter().any(|diagnostic| {
    diagnostic.message.starts_with("shape-hook:mark")
}));

Surface

The engine is organized into private module groups whose public items are re-exported at the crate root (the modules themselves are not public):

• primitives – atomic shapes (AnyShape, ExactExprShape, ExprKindShape, ClassShape, NumberValueShape, ListShape, FieldShape) and the combinators and object-grammar parsers built on them.
• algebra – boolean and collection shape algebra: AndShape, OrShape, NotShape, RepeatShape, and TableShape with its field and extra-field policies.
• compare – shape comparison and subsumption: normalization (normalize_shape, ShapeNormalForm), relation analysis (relate_shapes, ShapeRelation), and VennShapeSet set reasoning.
• citizen – citizen integration: class registration, codec, and construction for shape objects, plus the *_class_symbol accessors.
• functions – the callable shape object: FunctionObject, FunctionCase, overload selection, and shape-as-value wrapping.
• hooks – match-extension hooks: HookedShape and the MatchHook protocol with the built-in hook implementations.
• parse – the shape grammar parser that turns an Expr into a Shape and runs checks against expressions and values.
• base – the base shape vocabulary re-exported from the kernel (Shape, ShapeMatch, ShapeDoc, Bindings, ShapeReport).

Structs

AcceptOnNoDiagnosticsHook

Accept hook that repairs quiet rejections with score 1.

AndShape

Shape that accepts only when every child shape accepts.

AnyShape

The total shape that accepts every value and expression.

Bindings

Captures produced by a successful match: named values and named exprs.

CaptureShape

A shape that wraps an inner shape and binds the match under a name.

ClassShape

A shape that matches values and expressions of a named class.

DiscardOnDiagnosticPrefixHook

Discard hook that rejects accepted matches containing a diagnostic prefix.

EffectfulShape

A shape that marks its inner shape’s matching as effectful.

ExactExprShape

A shape that matches one exact expression form.

ExprKindShape

A shape that matches expressions of a single ExprKind.

FieldShape

A shape that matches an object form field by field.

FieldSpec

A single field requirement within a FieldShape: a name, a shape, and whether the field must be present.

FunctionCase

One overload case of a FunctionObject: a shape-typed signature paired with the native code that runs when it is selected.

FunctionObject

A callable function object: a named set of shape-typed overload cases with selection driven by case priority and argument match score.

HookedShape

Shape wrapper that runs neutral match hooks around an inner shape.

ListShape

A shape that matches a list positionally, with an optional rest shape.

MatchHookContext

Context supplied to every hook invocation.

MatchHookObject

Opaque runtime object that carries a shape hook.

MatchScore

A match quality score used to rank shapes during overload selection.

NotShape

Shape that accepts when the inner shape rejects.

NumberValueShape

A shape that matches number-domain values and number expressions.

ObjectExpr

The decoded form of an object expression: a class symbol and its fields.

OneOfShape

A shape that matches if any one of its choice shapes matches.

OrShape

Shape that accepts when at least one child shape accepts.

PrattShape

A shape that parses a string expression with a ShapeExprParser before matching.

RepeatShape

Shape for homogeneous list-like values and collection expressions.

ScoreFloorHook

Annotate hook that raises accepted match scores to a minimum floor.

SelectedCase

The case chosen by overload selection together with its match result.

ShapeBindings

Captures produced by a successful match: named values and named exprs.

ShapeDoc

Human-facing description of a Shape: a name plus optional detail lines.

ShapeMatch

The outcome of checking a value or expr against a Shape.

ShapeNormalForm

Structural summary used by conservative shape comparison.

ShapeObject

Runtime object wrapping a Shape so it is usable as a first-class value: a callable matcher, a kernel class, and (optionally) a re-encodable constructor expression.

ShapeRelation

Conservative relation report between two shapes.

ShapeReport

The canonical record of a shape check: who was checked against what, the outcome, and the diagnostics.

ShapeWitness

Result of checking one probe against both compared shapes.

TableFieldSpec

One field constraint inside a TableShape.

TableShape

Shape for table values or map expressions with named field constraints.

TraceMarkHook

Mark hook that emits the wrapped shape label before and after matching.

VennShapeSet

Named set of shapes used to build Venn-style regions.

Enums

ExprKind

A coarse classifier over Expr variants, used by grammar shapes.

MatchHookDecision

Hook result interpreted by HookedShape.

MatchHookKind

Capability class for a match hook decision.

MatchHookPhase

Point in the wrapper algorithm where a hook runs.

MatchHookTargetKind

Match target observed by a hook.

OrStrategy

Branch selection policy for OrShape.

ShapeNormalKind

Normalized shape structure understood by comparison helpers.

ShapeProbe

Example value or expression used to gather relation evidence.

ShapeRelationKind

Relation categories reported by ShapeRelation.

TableExtraPolicy

Policy for keys not listed in a TableShape.

Traits

MatchHook

Runtime hook contract for neutral shape match membranes.

Shape

The one shared engine for matching and binding across the runtime.

ShapeExprParser

A parser that turns shape source text into an Expr for PrattShape.

Functions

accept_on_no_diagnostics_hook_class_symbol

Class symbol for the AcceptOnNoDiagnosticsHook citizen (shape/AcceptOnNoDiagnosticsHook).

and_shape_class_symbol

Class symbol for the conjunction shape citizen (shape/And).

any_shape_class_symbol

Class symbol for the Any shape citizen (shape/Any).

binding_failure_diagnostic

Builds a diagnostic for a binding failure inside a capture or destructuring shape.

callable_mismatch_diagnostic

Builds a diagnostic for a callable shape argument mismatch.

case_result_shape

Borrow the result shape of a case, if it declares one.

case_shape

Borrow the argument shape of a single case.

check_shape_on_expr

Check an expression against a shape, returning the resulting match.

check_shape_on_value

Check a runtime value against a shape, returning the resulting match.

check_value_report

Check value against shape_value, building a ShapeReport and publishing the satisfaction claim when accepted.

class_shape_class_symbol

Class symbol for the class-membership shape citizen (shape/Class).

discard_on_diagnostic_prefix_hook_class_symbol

Class symbol for the DiscardOnDiagnosticPrefixHook citizen (shape/DiscardOnDiagnosticPrefixHook).

exact_expr_shape_class_symbol

Class symbol for the exact-expression shape citizen (shape/ExactExpr).

expected_shape_diagnostic

Builds a diagnostic for an expected-shape mismatch.

expr_kind_shape_class_symbol

Class symbol for the expression-kind shape citizen (shape/ExprKind).

function_cases

Borrow the overload cases of a function object.

hook_ref_arc

Extract a hook from a runtime value produced by hook_value.

hook_value

Wrap a hook as an opaque runtime value.

hooked_shape_class_symbol

Class symbol for the hook-wrapped shape citizen (shape/Hooked).

insert_shape_satisfaction_claim

Publish the satisfies-shape claim for an accepted report.

list_shape_class_symbol

Class symbol for the list shape citizen (shape/List).

normalize_shape

Build the conservative comparison normal form for a shape.

not_shape_class_symbol

Class symbol for the negation shape citizen (shape/Not).

or_shape_class_symbol

Class symbol for the disjunction shape citizen (shape/Or).

overload

Merge several functions into one whose cases are the union of theirs.

overload_selection_diagnostic

Builds a diagnostic for overload selection failures or ambiguity.

parse_shape_expr

Build a Shape from a shape-grammar expression.

relate_shapes

Compare two shapes with conservative proof rules plus optional probes.

repeat_shape_class_symbol

Class symbol for the repetition shape citizen (shape/Repeat).

satisfies_shape_predicate

The predicate symbol (core/satisfies-shape) used by satisfaction claims.

score_floor_hook_class_symbol

Class symbol for the ScoreFloorHook citizen (shape/ScoreFloorHook).

shape_error

Build the WrongShape error an expression produces against an expected shape.

shape_report_from_match

Intern a ShapeMatch into a ShapeReport for the given shape and target references.

shape_value

Wrap a shape as a kernel value: an opaque ShapeObject that carries the given symbol as the shape’s name and exposes it as a callable matcher.

shape_value_with_encoding

Like shape_value but also records the constructor encoding so the resulting value can be re-encoded back to its constructor expression.

table_shape_class_symbol

Class symbol for the table shape citizen (shape/Table).

trace_mark_hook_class_symbol

Class symbol for the TraceMarkHook citizen (shape/TraceMarkHook).

venn_shape_set_class_symbol

Class symbol for the Venn-set shape citizen (shape/Venn).

Type Aliases

NativeFunctionImpl

Native implementation backing a single FunctionCase.