Xopsy π©Ίπ
The Ultimate Diagnostic Prism for JSON in Rust.
Forged as a byproduct of the Cognitive OS architecture.
xopsy (pronounced zop-see) is a structural pattern matching DSL designed to perform instant diagnostics on serde_json::Value.
Standard Rust pattern matching struggles with the dynamic, nested nature of JSON. xopsy solves this by allowing you to describe the shape you expect and extract data in a single, declarative breath.
"Don't parse. Recognize."
β‘ Signal vs. Noise
Before Xopsy (Standard Serde Pain):
// The "Option Hell" - Buried in noise
if let Some = data.as_object
After Xopsy:
// The Clear Vision
use scope;
scope!;
π¦ Installation
Add this to your Cargo.toml:
[]
= "0.1.0"
= "1.0"
β οΈ Note on Recursion Limit
xopsy relies on recursive macro expansion. For extremely deep JSON structures or very long arrays (e.g., hundreds of elements), you might hit the compiler's default recursion limit.
If you encounter a recursion limit reached error, simply add this attribute to your crate root (main.rs or lib.rs):
// Increase as needed
π Core Features
xopsy provides two powerful macros:
scope!: Immutable Read. Safely extracts values from complex structures using tuple-binding.focus!: Mutable Injection. Drills into the JSON and injects code for modification (Best used with Opejson).
1. The Diagnostics: scope!
Use this when you want to read data without modifying it. It returns the result of the block.
Feature: Drill Syntax & Recursive Capture
use scope;
use json;
2. The Surgery: focus! + Opejson
Use this when you want to modify deep structures.
focus! uses a CPS (Continuation-Passing Style) architecture to safely pass a &mut Value into your code block, bypassing Rust's strict borrowing rules.
The Ultimate Combo: Use Xopsy to find the context, and Opejson to perform the surgery.
use focus;
use suture; // The Scalpel
use json;
Pro Tip: If you need to nest
focus!calls, remember to dereference the variable (e.g.,focus!(*parent_ref, ...)).
π Syntax Guide
The Xopsy DSL is designed to be intuitive and minimal.
| Syntax | Description | Example |
|---|---|---|
?var |
Capture. Binds the value to the variable var. |
"id": ?my_id |
?{ ... } |
Recursive Capture. Validates structure AND captures inner fields. | "user": ?{ "name": ?n } |
"key": val |
Check. Validates that the key exists and equals val. |
"status": 200 |
"a"."b" |
Drill. Syntactic sugar for nested objects. | "system"."cpu": ?usage |
[p1, p2] |
Exact Array. Matches an array of exactly 2 elements. | [10, 20] |
[p1, ..] |
Head Match. Matches start, ignores the rest. | ["header", ..] |
_ |
Wildcard. Matches anything (existence check). | "meta": _ |
null |
Null Check. Explicitly matches JSON null. | "error": null |
π§ Design Philosophy
1. Zero-Overhead Abstraction
Xopsy macros compile down to raw reference checks (if let, ==).
There is no runtime parsing of the pattern string. The "Drill Syntax" ("a"."b") creates pure nested checks at compile time, ensuring maximum performance.
2. The "Inversion" Architecture
To handle Rust's strict borrowing rules (especially &mut), focus! does not "return" values. Instead, it injects your code into the borrow scope (CPS).
This guarantees that the mutable references are valid, distinct, and safe to use, solving the common "fighting the borrow checker" problem when mutating JSON.
π€ Relationship with Opejson
- Opejson is the Scalpel (Write/Mutate).
- Xopsy is the Eye (Read/Locate).
Use them together to build the ultimate JSON manipulation pipeline.
// 1. Locate (Xopsy)
focus!;
License
MIT