specter-navigator-gadget

Specter Navigator Gadget

Core Concept

Integration of Specter (bidirectional navigation), Navigator (compiled path objects), and 3-MATCH (constraint satisfaction) into a unified system for structure traversal and transformation.

A Navigator is a compiled path expression that can be used for both selecting and transforming values within nested data structures. Each Navigator encodes one or more constraints (Gadgets) from a 3-SAT-like problem space.

Architecture

Key Components

1. Navigator - Compiled path expressions

struct Navigator
    path::Vector{NavigationStep}  # Steps in the traversal
    constraints::Vector{Gadget}   # 3-MATCH constraints
    cache_key::UInt64            # Hash for inline caching
end

2. Gadget - Individual constraint unit

struct Gadget
    name::String
    predicate::Function           # Selection/filtering predicate
    compose_strategy::Symbol      # :all, :any, :sequential
end

3. Navigation Steps (various types)

• ALL - Navigate to all collection members
• keypath(key) - Navigate to dictionary key
• pred(predicate) - Filter by predicate
• SEXP_HEAD / sexp_nth(n) - S-expression navigation
• INDEX(i) - Direct indexing

Compilation Pipeline

Path Expression
    ↓
coerce_nav() - converts to Navigator objects
    ↓
Constraint checking - verifies 3-MATCH satisfiability
    ↓
Inline caching via @late_nav / @compiled_select
    ↓
nav_select() / nav_transform() - execution

API

Macros

@late_nav(path_expr) Compiles and caches a navigation path, returning a reusable Navigator:

nav = @late_nav([ALL, pred(iseven)])
results = nav_select(nav, [1,2,3,4,5], x -> [x])
# => [2, 4]

@compiled_select(path, structure) Combines compilation, caching, and selection in one call:

results = @compiled_select([ALL, pred(iseven)], [1,2,3,4,5])
# => [2, 4]

Core Functions

coerce_nav(path_expr) :: Navigator Converts a path expression to a compiled Navigator object.