assert_struct/

lib.rs

//! # assert-struct: Ergonomic Structural Assertions
//!
//! `assert-struct` is a procedural macro that enables clean, readable assertions for complex
//! data structures without verbose field-by-field comparisons. When assertions fail, it provides
//! clear, actionable error messages showing exactly what went wrong, including field paths and
//! expected vs actual values.
//!
//! This comprehensive guide teaches you how to use `assert-struct` effectively in your tests.
//! After reading this documentation, you'll be familiar with all capabilities and able to
//! leverage the full power of structural assertions.
//!
//! # Table of Contents
//!
//! - [Quick Start](#quick-start)
//! - [Core Concepts](#core-concepts)
//!   - [Basic Assertions](#basic-assertions)
//!   - [Partial Matching](#partial-matching)
//!   - [Nested Structures](#nested-structures)
//! - [Pattern Types](#pattern-types)
//!   - [Comparison Operators](#comparison-operators)
//!   - [Equality Operators](#equality-operators)
//!   - [Range Patterns](#range-patterns)
//!   - [Regex Patterns](#regex-patterns)
//!   - [Method Call Patterns](#method-call-patterns)
//! - [Data Types](#data-types)
//!   - [Collections (Vec/Slice)](#collections-vecslice)
//!   - [Set Patterns](#set-patterns)
//!   - [Maps (HashMap/BTreeMap)](#maps-hashmapbtreemap)
//!   - [Tuples](#tuples)
//!   - [Enums (Option/Result/Custom)](#enums-optionresultcustom)
//!   - [Smart Pointers](#smart-pointers)
//! - [Error Messages](#error-messages)
//! - [Advanced Usage](#advanced-usage)
//!   - [Dynamic Value Types](#dynamic-value-types)
//!
//! # Quick Start
//!
//! Add to your `Cargo.toml`:
//!
//! ```toml
//! [dev-dependencies]
//! assert-struct = "0.2"
//! ```
//!
//! Basic example:
//!
//! ```rust
//! use assert_struct::assert_struct;
//!
//! #[derive(Debug)]
//! struct User {
//!     name: String,
//!     age: u32,
//!     email: String,
//! }
//!
//! let user = User {
//!     name: "Alice".to_string(),
//!     age: 30,
//!     email: "alice@example.com".to_string(),
//! };
//!
//! // Only check the fields you care about
//! assert_struct!(user, User {
//!     name: "Alice",
//!     age: 30,
//!     ..  // Ignore email
//! });
//! ```
//!
//! # Core Concepts
//!
//! ## Basic Assertions
//!
//! The simplest use case is asserting all fields of a struct:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Point { x: i32, y: i32 }
//! let point = Point { x: 10, y: 20 };
//!
//! assert_struct!(point, Point {
//!     x: 10,
//!     y: 20,
//! });
//! ```
//!
//! String fields work naturally with string literals:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Message { text: String, urgent: bool }
//! let msg = Message {
//!     text: "Hello world".to_string(),
//!     urgent: false,
//! };
//!
//! assert_struct!(msg, Message {
//!     text: "Hello world",  // No .to_string() needed!
//!     urgent: false,
//! });
//! ```
//!
//! ## Partial Matching
//!
//! Use `..` to ignore fields you don't want to check:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct User { id: u64, name: String, email: String, created_at: String }
//! # let user = User {
//! #     id: 1,
//! #     name: "Alice".to_string(),
//! #     email: "alice@example.com".to_string(),
//! #     created_at: "2024-01-01".to_string(),
//! # };
//! // Only verify name and email, ignore id and created_at
//! assert_struct!(user, User {
//!     name: "Alice",
//!     email: "alice@example.com",
//!     ..
//! });
//! ```
//!
//! ## Nested Structures
//!
//! Assert on deeply nested data without repetitive field access:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Order { customer: Customer, total: f64 }
//! # #[derive(Debug)]
//! # struct Customer { name: String, address: Address }
//! # #[derive(Debug)]
//! # struct Address { city: String, country: String }
//! # let order = Order {
//! #     customer: Customer {
//! #         name: "Bob".to_string(),
//! #         address: Address { city: "Paris".to_string(), country: "France".to_string() }
//! #     },
//! #     total: 99.99
//! # };
//! assert_struct!(order, Order {
//!     customer: Customer {
//!         name: "Bob",
//!         address: Address {
//!             city: "Paris",
//!             country: "France",
//!         },
//!     },
//!     total: 99.99,
//! });
//!
//! // Or with partial matching
//! assert_struct!(order, Order {
//!     customer: Customer {
//!         name: "Bob",
//!         address: Address { city: "Paris", .. },
//!         ..
//!     },
//!     ..
//! });
//!
//! // Direct nested field access (no need to nest structs)
//! assert_struct!(order, Order {
//!     customer.name: "Bob",
//!     customer.address.city: "Paris",
//!     customer.address.country: "France",
//!     total: > 50.0,
//!     ..
//! });
//! ```
//!
//! # Pattern Types
//!
//! ## Comparison Operators
//!
//! Use comparison operators for numeric assertions:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Metrics { cpu: f64, memory: u64, requests: u32 }
//! # let metrics = Metrics { cpu: 75.5, memory: 1024, requests: 150 };
//! assert_struct!(metrics, Metrics {
//!     cpu: < 80.0,          // Less than 80%
//!     memory: <= 2048,      // At most 2GB
//!     requests: > 100,      // More than 100
//! });
//! ```
//!
//! All comparison operators work: `<`, `<=`, `>`, `>=`
//!
//! ## Equality Operators
//!
//! Use explicit equality for clarity:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Status { code: i32, active: bool }
//! # let status = Status { code: 200, active: true };
//! assert_struct!(status, Status {
//!     code: == 200,         // Explicit equality
//!     active: != false,     // Not equal to false
//! });
//! ```
//!
//! ## Range Patterns
//!
//! Use ranges for boundary checks:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Person { age: u32, score: f64 }
//! # let person = Person { age: 25, score: 87.5 };
//! assert_struct!(person, Person {
//!     age: 18..=65,         // Working age range
//!     score: 0.0..100.0,    // Valid score range
//! });
//! ```
//!
//! ## Regex Patterns
//!
//! Match string patterns with regular expressions (requires `regex` feature, enabled by default):
//!
//! ```rust
//! # #[cfg(feature = "regex")]
//! # {
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Account { username: String, email: String }
//! # let account = Account {
//! #     username: "alice_doe".to_string(),
//! #     email: "alice@company.com".to_string(),
//! # };
//! assert_struct!(account, Account {
//!     username: =~ r"^[a-z_]+$",        // Lowercase and underscores
//!     email: =~ r"@company\.com$",      // Company email domain
//! });
//! # }
//! ```
//!
//! ## Method Call Patterns
//!
//! Call methods on fields and assert on their results:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # use std::collections::HashMap;
//! # #[derive(Debug)]
//! # struct Data {
//! #     content: String,
//! #     items: Vec<i32>,
//! #     metadata: Option<String>,
//! #     cache: HashMap<String, i32>,
//! # }
//! # let mut map = HashMap::new();
//! # map.insert("key1".to_string(), 42);
//! # let data = Data {
//! #     content: "hello world".to_string(),
//! #     items: vec![1, 2, 3, 4, 5],
//! #     metadata: Some("cached".to_string()),
//! #     cache: map,
//! # };
//! assert_struct!(data, Data {
//!     content.len(): 11,                    // String length
//!     items.len(): >= 5,                    // Vector size check
//!     metadata.is_some(): true,             // Option state
//!     cache.contains_key("key1"): true,     // HashMap lookup
//!     ..
//! });
//! ```
//!
//! Method calls work with arguments too:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Text { content: String, other: String }
//! # let text = Text { content: "hello world".to_string(), other: "test".to_string() };
//! assert_struct!(text, Text {
//!     content.starts_with("hello"): true,
//!     ..
//! });
//!
//! assert_struct!(text, Text {
//!     content.contains("world"): true,
//!     ..
//! });
//! ```
//!
//! # Data Types
//!
//! ## Collections (Vec/Slice)
//!
//! Element-wise pattern matching for vectors:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Data { values: Vec<i32>, names: Vec<String> }
//! # let data = Data {
//! #     values: vec![5, 15, 25],
//! #     names: vec!["alice".to_string(), "bob".to_string()],
//! # };
//! // Exact matching
//! assert_struct!(data, Data {
//!     values: [5, 15, 25],
//!     names: ["alice", "bob"],  // String literals work in slices too!
//! });
//!
//! // Pattern matching for each element
//! assert_struct!(data, Data {
//!     values: [> 0, < 20, >= 25],    // Different pattern per element
//!     names: ["alice", "bob"],
//! });
//! ```
//!
//! Partial slice matching:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Data { items: Vec<i32> }
//! # let data = Data { items: vec![1, 2, 3, 4, 5] };
//! assert_struct!(data, Data {
//!     items: [1, 2, ..],      // First two elements, ignore rest
//! });
//!
//! assert_struct!(data, Data {
//!     items: [.., 4, 5],      // Last two elements
//! });
//!
//! assert_struct!(data, Data {
//!     items: [1, .., 5],      // First and last elements
//! });
//! ```
//!
//! ## Set Patterns
//!
//! Use `#(...)` to assert that a collection contains elements matching the given patterns,
//! **in any order**. Each pattern must match a distinct element; unlike slice patterns `[...]`,
//! position does not matter.
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Data { items: Vec<i32>, tags: Vec<String> }
//! # let data = Data {
//! #     items: vec![3, 1, 2],
//! #     tags: vec!["rust".to_string(), "async".to_string()],
//! # };
//! // Exact match - every element must be matched, in any order
//! assert_struct!(data, Data {
//!     items: #(1, 2, 3),
//!     tags: #("rust", "async"),  // String literals work too
//! });
//!
//! // Partial match - use .. to allow extra unmatched elements
//! assert_struct!(data, Data {
//!     items: #(> 0, ..),         // At least one element matching > 0
//!     tags: #("rust", ..),       // Contains "rust", possibly more
//! });
//! ```
//!
//! Struct patterns work inside `#(...)` too, which is useful when asserting that certain
//! items are present in a collection regardless of their order:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Event { kind: String, value: i32 }
//! # let events = vec![
//! #     Event { kind: "click".to_string(), value: 10 },
//! #     Event { kind: "hover".to_string(), value: 20 },
//! #     Event { kind: "scroll".to_string(), value: 30 },
//! # ];
//! // Assert that click and hover events are present, ignoring order and other events
//! assert_struct!(events, #(
//!     _ { kind: "click", value: > 0 },
//!     _ { kind: "hover" },
//!     ..
//! ));
//! ```
//!
//! Other pattern types also work inside `#(...)`:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Report { scores: Vec<i32>, results: Vec<Option<i32>> }
//! # let report = Report {
//! #     scores: vec![95, 42, 77],
//! #     results: vec![Some(5), None, Some(10)],
//! # };
//! assert_struct!(report, Report {
//!     scores: #(> 90, < 50, 18..=100),    // Comparisons and ranges
//!     results: #(None, Some(> 0), ..),     // Enum patterns
//! });
//! ```
//!
//! Empty and wildcard set patterns:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Data { empty: Vec<i32>, any: Vec<i32> }
//! # let data = Data { empty: vec![], any: vec![1, 2, 3] };
//! assert_struct!(data, Data {
//!     empty: #(),     // Exactly empty collection
//!     any: #(..),     // Any collection (wildcard - any contents or length)
//! });
//! ```
//!
//!
//! ## Maps (HashMap/BTreeMap)
//!
//! Pattern matching for map-like structures using duck typing (works with any type that has `len()` and `get()` methods):
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # use std::collections::HashMap;
//! # #[derive(Debug)]
//! # struct Config {
//! #     settings: HashMap<String, String>,
//! #     flags: HashMap<String, bool>,
//! # }
//! # let mut settings = HashMap::new();
//! # settings.insert("theme".to_string(), "dark".to_string());
//! # settings.insert("language".to_string(), "en".to_string());
//! # let mut flags = HashMap::new();
//! # flags.insert("debug".to_string(), true);
//! # flags.insert("verbose".to_string(), false);
//! # let config = Config { settings, flags };
//! // Exact matching (checks map length)
//! assert_struct!(config, Config {
//!     settings: #{ "theme": "dark", "language": "en" },
//!     flags: #{ "debug": true, "verbose": false },
//! });
//!
//! // Partial matching (ignores map length)
//! assert_struct!(config, Config {
//!     settings: #{ "theme": "dark", .. },     // Only check theme
//!     flags: #{ "debug": true, .. },          // Only check debug flag
//! });
//! ```
//!
//! Advanced map patterns with comparisons and nested patterns:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # use std::collections::{HashMap, BTreeMap};
//! # #[derive(Debug)]
//! # struct Analytics {
//! #     metrics: HashMap<String, i32>,
//! #     metadata: BTreeMap<String, String>,
//! # }
//! # let mut metrics = HashMap::new();
//! # metrics.insert("views".to_string(), 1000);
//! # metrics.insert("clicks".to_string(), 50);
//! # metrics.insert("conversions".to_string(), 5);
//! # let mut metadata = BTreeMap::new();
//! # metadata.insert("version".to_string(), "v1.2.3".to_string());
//! # metadata.insert("environment".to_string(), "production".to_string());
//! # let analytics = Analytics { metrics, metadata };
//! // Pattern matching with comparison operators
//! assert_struct!(analytics, Analytics {
//!     metrics: #{
//!         "views": > 500,           // More than 500 views
//!         "clicks": >= 10,          // At least 10 clicks
//!         "conversions": > 0,       // Some conversions
//!         ..
//!     },
//!     metadata: #{
//!         "version": =~ r"^v\d+\.\d+\.\d+$",  // Semantic version pattern
//!         "environment": != "development",     // Not in development
//!         ..
//!     },
//! });
//! ```
//!
//! Empty and wildcard map matching:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # use std::collections::HashMap;
//! # #[derive(Debug)]
//! # struct Data {
//! #     cache: HashMap<String, i32>,
//! #     config: HashMap<String, String>,
//! # }
//! # let mut config = HashMap::new();
//! # config.insert("key".to_string(), "value".to_string());
//! # let data = Data { cache: HashMap::new(), config };
//! assert_struct!(data, Data {
//!     cache: #{},             // Exactly empty map (len() == 0)
//!     config: #{ .. },        // Any map content (wildcard)
//! });
//! ```
//!
//! ## Tuples
//!
//! Full support for multi-field tuples:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Data { point: (i32, i32), metadata: (String, u32, bool) }
//! # let data = Data {
//! #     point: (15, 25),
//! #     metadata: ("info".to_string(), 100, true),
//! # };
//! // Basic tuple matching
//! assert_struct!(data, Data {
//!     point: (15, 25),
//!     metadata: ("info", 100, true),  // String literals work in tuples!
//! });
//!
//! // Advanced patterns
//! assert_struct!(data, Data {
//!     point: (> 10, < 30),           // Comparison operators
//!     metadata: ("info", >= 50, true),
//! });
//! ```
//!
//! Tuple method calls:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Data { coords: (String, Vec<i32>) }
//! # let data = Data {
//! #     coords: ("location".to_string(), vec![1, 2, 3]),
//! # };
//! assert_struct!(data, Data {
//!     coords: (0.len(): 8, 1.len(): 3),  // Method calls on tuple elements
//! });
//! ```
//!
//! ## Enums (Option/Result/Custom)
//!
//! ### Option Types
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct User { name: Option<String>, age: Option<u32> }
//! # let user = User { name: Some("Alice".to_string()), age: Some(30) };
//! assert_struct!(user, User {
//!     name: Some("Alice"),
//!     age: Some(30),
//! });
//!
//! // Advanced patterns inside Option
//! assert_struct!(user, User {
//!     name: Some("Alice"),
//!     age: Some(>= 18),      // Adult check inside Some
//! });
//! ```
//!
//! ### Result Types
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Response { result: Result<String, String> }
//! # let response = Response { result: Ok("success".to_string()) };
//! assert_struct!(response, Response {
//!     result: Ok("success"),
//! });
//!
//! // Pattern matching inside Result
//! # let response = Response { result: Ok("user123".to_string()) };
//! assert_struct!(response, Response {
//!     result: Ok(=~ r"^user\d+$"),  // Regex inside Ok
//! });
//! ```
//!
//! ### Custom Enums
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug, PartialEq)]
//! # enum Status { Active, Pending { since: String } }
//! # #[derive(Debug)]
//! # struct Account { status: Status }
//! # let account = Account { status: Status::Pending { since: "2024-01-01".to_string() } };
//! // Unit variants
//! let active_account = Account { status: Status::Active };
//! assert_struct!(active_account, Account {
//!     status: Status::Active,
//! });
//!
//! // Struct variants with partial matching
//! assert_struct!(account, Account {
//!     status: Status::Pending { since: "2024-01-01" },
//! });
//! ```
//!
//! ## Smart Pointers
//!
//! Dereference smart pointers directly in patterns:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # use std::rc::Rc;
//! # use std::sync::Arc;
//! # #[derive(Debug)]
//! # struct Cache {
//! #     data: Arc<String>,
//! #     count: Box<i32>,
//! #     shared: Rc<bool>,
//! # }
//! # let cache = Cache {
//! #     data: Arc::new("cached".to_string()),
//! #     count: Box::new(42),
//! #     shared: Rc::new(true),
//! # };
//! assert_struct!(cache, Cache {
//!     *data: "cached",       // Dereference Arc<String>
//!     *count: > 40,          // Dereference Box<i32> with comparison
//!     *shared: true,         // Dereference Rc<bool>
//! });
//! ```
//!
//! Multiple dereferencing for nested pointers:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Nested { value: Box<Box<i32>> }
//! # let nested = Nested { value: Box::new(Box::new(42)) };
//! assert_struct!(nested, Nested {
//!     **value: 42,           // Double dereference
//! });
//! ```
//!
//! ## Wildcard Patterns
//!
//! Use wildcard patterns (`_`) to avoid importing types while still asserting on their structure:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # mod api {
//! #     #[derive(Debug)]
//! #     pub struct Response {
//! #         pub user: User,
//! #         pub metadata: Metadata,
//! #     }
//! #     #[derive(Debug)]
//! #     pub struct User {
//! #         pub id: u32,
//! #         pub name: String,
//! #     }
//! #     #[derive(Debug)]
//! #     pub struct Metadata {
//! #         pub timestamp: u64,
//! #         pub version: String,
//! #     }
//! # }
//! # let response = api::Response {
//! #     user: api::User { id: 123, name: "Alice".to_string() },
//! #     metadata: api::Metadata { timestamp: 1234567890, version: "1.0".to_string() }
//! # };
//! // No need to import User or Metadata types!
//! // Wildcard patterns always do partial matching, so .. is never required.
//! assert_struct!(response, _ {
//!     user: _ {
//!         id: 123,
//!         name: "Alice",
//!     },
//!     metadata: _ {
//!         version: "1.0",
//!     },
//! });
//! ```
//!
//! This is particularly useful when testing API responses where you don't want to import all the nested types:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct JsonResponse { data: Data }
//! # #[derive(Debug)]
//! # struct Data { items: Vec<Item>, total: u32 }
//! # #[derive(Debug)]
//! # struct Item { id: u32, value: String }
//! # let json_response = JsonResponse {
//! #     data: Data {
//! #         items: vec![Item { id: 1, value: "test".to_string() }],
//! #         total: 1
//! #     }
//! # };
//! // Test deeply nested structures without imports
//! assert_struct!(json_response, _ {
//!     data: _ {
//!         items: [_ { id: 1, value: "test" }],
//!         total: 1,
//!     },
//! });
//! ```
//!
//! # Error Messages
//!
//! When assertions fail, `assert-struct` provides detailed, actionable error messages:
//!
//! ## Basic Mismatch
//!
//! ```rust,should_panic
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct User { name: String, age: u32 }
//! # let user = User { name: "Alice".to_string(), age: 25 };
//! assert_struct!(user, User {
//!     name: "Bob",  // This will fail
//!     age: 25,
//! });
//! // Error output:
//! // assert_struct! failed:
//! //
//! // value mismatch:
//! //   --> `user.name` (src/lib.rs:456)
//! //   actual: "Alice"
//! //   expected: "Bob"
//! ```
//!
//! ## Comparison Failure
//!
//! ```rust,should_panic
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Stats { score: u32 }
//! # let stats = Stats { score: 50 };
//! assert_struct!(stats, Stats {
//!     score: > 100,  // This will fail
//! });
//! // Error output:
//! // assert_struct! failed:
//! //
//! // comparison mismatch:
//! //   --> `stats.score` (src/lib.rs:469)
//! //   actual: 50
//! //   expected: > 100
//! ```
//!
//! ## Nested Field Errors
//!
//! Error messages show the exact path to the failing field, even in deeply nested structures.
//! Method calls are also shown in the field path for clear debugging.
//!
//! # Advanced Usage
//!
//! ## Mixing Structural and Operator Patterns
//!
//! Structural patterns and operator patterns are complementary — within a single
//! `assert_struct!` call, use whichever is most concise for each field. The goal is
//! the shortest assertion that expresses what you actually care about.
//!
//! Structural patterns (`SomeType { field: value, .. }`) are great for navigating
//! nested types. But for a specific field, writing out the full structural equivalent
//! can be far more verbose than a simple `==` or `=~` check — especially when the
//! field's type implements `PartialEq` or `PartialOrd` with a simpler type.
//!
//! For example, consider a `Value` enum (similar to `serde_json::Value`) that can
//! hold different primitive types and implements `PartialEq` with them:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug, PartialEq)]
//! # enum Value { Bool(bool), Int(i64), Text(String) }
//! # impl PartialEq<bool> for Value {
//! #     fn eq(&self, other: &bool) -> bool {
//! #         match self { Value::Bool(b) => b == other, _ => false }
//! #     }
//! # }
//! # impl PartialEq<i64> for Value {
//! #     fn eq(&self, other: &i64) -> bool {
//! #         match self { Value::Int(n) => n == other, _ => false }
//! #     }
//! # }
//! # impl PartialEq<&str> for Value {
//! #     fn eq(&self, other: &&str) -> bool {
//! #         match self { Value::Text(s) => s == *other, _ => false }
//! #     }
//! # }
//! # impl PartialOrd<i64> for Value {
//! #     fn partial_cmp(&self, other: &i64) -> Option<std::cmp::Ordering> {
//! #         match self { Value::Int(n) => n.partial_cmp(other), _ => None }
//! #     }
//! # }
//! # #[derive(Debug)]
//! # struct Filter { column: usize, value: Value }
//! # #[derive(Debug)]
//! # struct Query { table: String, filter: Option<Filter> }
//! # let query = Query {
//! #     table: "users".to_string(),
//! #     filter: Some(Filter { column: 2, value: Value::Text("alice".to_string()) }),
//! # };
//! // Structural matching navigates the outer types; operator pattern handles Value
//! assert_struct!(query, Query {
//!     table: "users",
//!     filter: Some(_ {
//!         column: 2,
//!         value: == "alice",  // much shorter than Value::Text("alice".to_string())
//!     }),
//! });
//! ```
//!
//! The `== "alice"` works because `Value: PartialEq<&str>`. The same applies to
//! comparison operators — if `Value: PartialOrd<i64>`, you can write `value: > 0i64`
//! instead of matching the variant.
//!
//! The general rule: if writing the structural pattern for a field requires naming
//! internal types or constructing wrapper values, check whether an operator pattern
//! expresses the same intent more directly.
//!
//! ## Pattern Composition
//!
//! Combine multiple patterns for comprehensive assertions:
//!
//! ```rust
//! # use assert_struct::assert_struct;
//! # #[derive(Debug)]
//! # struct Complex {
//! #     data: Option<Vec<i32>>,
//! #     metadata: (String, u32),
//! # }
//! # let complex = Complex {
//! #     data: Some(vec![1, 2, 3]),
//! #     metadata: ("info".to_string(), 42),
//! # };
//! assert_struct!(complex, Complex {
//!     data: Some([> 0, > 1, > 2]),              // Option + Vec + comparisons
//!     metadata: ("info", > 40),                 // Tuple + string + comparison
//!     ..
//! });
//!
//! // Verify data length separately
//! assert_eq!(complex.data.as_ref().unwrap().len(), 3);
//! ```
//!
//! ## Real-World Testing Patterns
//!
//! See the [examples directory](../../examples/) for comprehensive real-world examples including:
//! - API response validation
//! - Database record testing
//! - Configuration validation
//! - Event system testing
//!
//! For complete specification details, see the [`assert_struct!`] macro documentation.

// Re-export the procedural macro
pub use assert_struct_macros::assert_struct;

// Error handling module
#[doc(hidden)]
pub mod error;

// Hidden module for macro support functions
#[doc(hidden)]
pub mod __macro_support {
    pub use crate::error::{ComparisonOp, ErrorReport, NodeKind, PatternNode, PlainOutputGuard};

    // Re-export regex types for macro expansion when regex feature is enabled
    #[cfg(feature = "regex")]
    pub use regex::Regex;

    /// Helper function to enable type inference for closure parameters in assert_struct patterns
    #[inline]
    pub fn check_closure_condition<T, F>(value: T, predicate: F) -> bool
    where
        F: FnOnce(T) -> bool,
    {
        predicate(value)
    }

    /// Runtime helper for the set pattern `#(...)`.
    ///
    /// Checks that `n_elements` satisfies the length constraint, then uses backtracking
    /// to find a 1-to-1 assignment of patterns to elements. Each predicate returns `true`
    /// if the element at the given index matches its pattern.
    ///
    /// On failure, pushes exactly one error to `report`.
    pub fn set_match(
        n_elements: usize,
        rest: bool,
        predicates: &[&dyn Fn(usize) -> bool],
        report: &mut ErrorReport,
        node: &'static PatternNode,
    ) {
        let n_patterns = predicates.len();

        // Length check
        let length_ok = if rest {
            n_elements >= n_patterns
        } else {
            n_elements == n_patterns
        };

        if !length_ok {
            let expected_str = if rest {
                format!("at least {} element(s)", n_patterns)
            } else {
                format!("{} element(s)", n_patterns)
            };
            report.push(
                node,
                format!("{} element(s)", n_elements),
                Some(expected_str),
            );
            return;
        }

        // Backtracking assignment
        let mut matched = vec![false; n_elements];
        if !set_backtrack(predicates, &mut matched, 0) {
            report.push(node, format!("{} element(s)", n_elements), None);
        }
    }

    fn set_backtrack(
        predicates: &[&dyn Fn(usize) -> bool],
        matched: &mut [bool],
        pattern_idx: usize,
    ) -> bool {
        if pattern_idx == predicates.len() {
            return true;
        }
        for i in 0..matched.len() {
            if !matched[i] && predicates[pattern_idx](i) {
                matched[i] = true;
                if set_backtrack(predicates, matched, pattern_idx + 1) {
                    return true;
                }
                matched[i] = false;
            }
        }
        false
    }
}

/// A trait for pattern matching, similar to `PartialEq` but for flexible matching.
///
/// The `Like` trait enables custom pattern matching logic beyond simple equality.
/// It's primarily used with the `=~` operator in `assert_struct!` macro to support
/// regex patterns, custom matching logic, and other pattern-based comparisons.
///
/// # Examples
///
/// ## Basic String Pattern Matching
///
/// ```
/// # #[cfg(feature = "regex")]
/// # {
/// use assert_struct::Like;
///
/// // Using Like trait directly
/// let text = "hello@example.com";
/// assert!(text.like(&r".*@example\.com"));
/// # }
/// ```
///
/// ## Custom Implementation
///
/// ```
/// use assert_struct::Like;
///
/// struct EmailAddress(String);
///
/// struct DomainPattern {
///     domain: String,
/// }
///
/// impl Like<DomainPattern> for EmailAddress {
///     fn like(&self, pattern: &DomainPattern) -> bool {
///         self.0.ends_with(&format!("@{}", pattern.domain))
///     }
/// }
///
/// let email = EmailAddress("user@example.com".to_string());
/// let pattern = DomainPattern { domain: "example.com".to_string() };
/// assert!(email.like(&pattern));
/// ```
pub trait Like<Rhs = Self> {
    /// Returns `true` if `self` matches the pattern `other`.
    ///
    /// # Examples
    ///
    /// ```
    /// # #[cfg(feature = "regex")]
    /// # {
    /// use assert_struct::Like;
    ///
    /// let s = "test123";
    /// assert!(s.like(&r"\w+\d+"));
    /// # }
    /// ```
    fn like(&self, other: &Rhs) -> bool;
}

// String/&str implementations for regex pattern matching
#[cfg(feature = "regex")]
mod like_impls {
    use super::Like;

    /// Implementation of Like for String with &str patterns (interpreted as regex)
    impl Like<&str> for String {
        fn like(&self, pattern: &&str) -> bool {
            regex::Regex::new(pattern)
                .map(|re| re.is_match(self))
                .unwrap_or(false)
        }
    }

    /// Implementation of Like for String with String patterns (interpreted as regex)
    impl Like<String> for String {
        fn like(&self, pattern: &String) -> bool {
            self.like(&pattern.as_str())
        }
    }

    /// Implementation of Like for &str with &str patterns (interpreted as regex)
    impl Like<&str> for &str {
        fn like(&self, pattern: &&str) -> bool {
            regex::Regex::new(pattern)
                .map(|re| re.is_match(self))
                .unwrap_or(false)
        }
    }

    /// Implementation of Like for &str with String patterns (interpreted as regex)
    impl Like<String> for &str {
        fn like(&self, pattern: &String) -> bool {
            self.like(&pattern.as_str())
        }
    }

    /// Implementation of Like for String with pre-compiled Regex
    impl Like<regex::Regex> for String {
        fn like(&self, pattern: &regex::Regex) -> bool {
            pattern.is_match(self)
        }
    }

    /// Implementation of Like for &str with pre-compiled Regex
    impl Like<regex::Regex> for &str {
        fn like(&self, pattern: &regex::Regex) -> bool {
            pattern.is_match(self)
        }
    }
}