feat(parser): implement bitwise xor not and any value x operators

[unclesp1d3r]

This pull request adds support for three new operators—bitwise XOR (^), bitwise NOT (~), and any-value (x)—to the magic rule evaluation system. The changes include parsing, evaluation, documentation, and comprehensive tests for these operators, ensuring they are handled consistently throughout the codebase.

Operator support and parsing:

• Added Operator::BitwiseXor, Operator::BitwiseNot, and Operator::AnyValue variants to the Operator enum, with documentation and serialization support (src/parser/ast.rs, src/parser/codegen.rs). [1] [2]
• Updated the grammar parser to recognize ^, ~, and x as valid operators, including documentation and examples (src/parser/grammar.rs). [1] [2] [3]

Evaluation logic and integration:

• Implemented apply_bitwise_xor, apply_bitwise_not, and apply_any_value functions, and integrated them into the main operator dispatch logic (src/evaluator/operators/bitwise.rs, src/evaluator/operators/mod.rs). [1] [2] [3] [4] [5]
• Updated the rule strength calculation to account for the new operators, assigning appropriate specificity scores (src/evaluator/strength.rs).

Testing and documentation:

• Added comprehensive unit tests for the new operators, covering parsing, evaluation, and serialization, and updated operator tests to include the new variants (src/evaluator/operators/mod.rs, src/evaluator/operators/bitwise.rs, src/parser/ast.rs). [1] [2] [3] [4] [5] [6] [7]
• Updated documentation to describe the new operators and their usage in magic rules, including examples in MAGIC_FORMAT.md (docs/MAGIC_FORMAT.md).

End-to-end validation:

• Added end-to-end tests for parsing and evaluating rules using the any-value (x) operator, ensuring it matches unconditionally (src/evaluator/mod.rs).

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Summary by CodeRabbit

• New Features

  • Added three pattern-matching operators: bitwise XOR (^), bitwise NOT (~), and an any-value match (x).

• Documentation

  • Updated API, architecture, CLI, and format docs to include the new operators, expanded examples, and standardized code-block formatting for clarity.

• Tests

  • Greatly expanded unit and integration test coverage for parsing, evaluation, operators, and many edge cases.

Walkthrough

Added three operators (BitwiseXor, BitwiseNot, AnyValue); implemented their evaluator functions and dispatcher entries; moved/rewrote parser grammar into src/parser/grammar/mod.rs with extensive tests; relocated and expanded evaluator tests; updated strength scoring; and applied broad documentation and formatting changes.

Changes

Cohort / File(s)	Summary
AST & Codegen src/parser/ast.rs, src/parser/codegen.rs	Added BitwiseXor, BitwiseNot, AnyValue operator variants and serialization support; added TypeKind::bit_width() helper.
Parser Grammar (moved/rewritten) src/parser/grammar/mod.rs, src/parser/grammar/tests.rs, (removed) src/parser/grammar.rs	Replaced/relocated grammar into grammar/mod.rs with comprehensive parsers and tests; removed the old single-file grammar.rs.
Evaluator — Operators src/evaluator/operators/bitwise.rs, src/evaluator/operators/mod.rs	Implemented apply_bitwise_xor, apply_bitwise_not, apply_bitwise_not_with_width, and apply_any_value; extended dispatcher and re-exports; added unit tests.
Evaluator — Integration & Logic src/evaluator/mod.rs, src/evaluator/strength.rs	Dispatch now uses width-aware apply_bitwise_not_with_width for BitwiseNot; strength calculation extended for new operators; division-by-zero handling simplified in modifier application.
Tests — Relocation & Expansion src/evaluator/tests.rs, src/tests.rs, tests/property_tests.rs, src/parser/grammar/tests.rs	Moved inline tests to standalone modules and added extensive unit/integration/property tests covering new operators, parsing, evaluation contexts, recursion, offsets, and edge cases.
Docs & Examples docs/*, docs/src/*, docs/MAGIC_FORMAT.md, docs/API_REFERENCE.md	Documented new operators and examples; standardized many markdown fences to ```text and adjusted headings/formatting across docs.
Misc. Config & Guides .claude/**, .markdownlint-cli2.jsonc, justfile, CODE_OF_CONDUCT.md, CONTRIBUTING.md	Minor documentation, formatting, lint-ignore, and CI/example tweaks.

Sequence Diagram(s)

sequenceDiagram
    participant Parser as Parser
    participant AST as AST (Operator)
    participant Evaluator as Evaluator Dispatcher
    participant OpImpl as Operator Impl
    participant Strength as Strength Calculator

    rect rgba(0,200,100,0.5)
    Note over Parser,Strength: BitwiseXor Flow
    Parser->>AST: parse "^" token + value
    AST->>Evaluator: emit BitwiseXor node
    Evaluator->>OpImpl: apply_bitwise_xor(left, right)
    OpImpl-->>Evaluator: bool
    Evaluator->>Strength: compute strength (contrib: 4)
    end

    rect rgba(100,150,255,0.5)
    Note over Parser,Strength: BitwiseNot Flow
    Parser->>AST: parse "~" token + value
    AST->>Evaluator: emit BitwiseNot node
    Evaluator->>OpImpl: apply_bitwise_not_with_width(left, right, bit_width)
    OpImpl-->>Evaluator: bool
    Evaluator->>Strength: compute strength (contrib: 4)
    end

    rect rgba(200,100,150,0.5)
    Note over Parser,Strength: AnyValue Flow
    Parser->>AST: parse "x" token
    AST->>Evaluator: emit AnyValue node
    Evaluator->>OpImpl: apply_any_value(left, right)
    OpImpl-->>Evaluator: true
    Evaluator->>Strength: compute strength (contrib: 1)
    end

Loading

Estimated code review effort

🎯 5 (Critical) | ⏱️ ~120 minutes

Possibly related PRs

• feat: built-in rules build time compilation fallback #28 — Touches src/evaluator/mod.rs and evaluate_single_rule; likely intersects with BitwiseNot dispatch and evaluator error/handling changes.
• docs: comprehensive documentation, security, and CI hardening #58 — Modifies src/parser/ast.rs operator variants; closely related to the new Operator variants and AST changes.
• feat: Add evaluation engine with offset resolution and CI/CD automation #5 — Overlaps parser/evaluator surfaces and operator handling; likely relevant to grammar/evaluator coordination.

Poem

🐰 I hopped through grammar, AST, and tests,
XOR and NOT now join the nests.
AnyValue smiles and matches all,
Strengths assigned, the dispatcher calls,
A rabbit cheers these tiny quests. ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main feature addition: implementing three new operators (bitwise XOR, bitwise NOT, and any-value). It accurately reflects the primary objective of the changeset.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, detailing operator support, evaluation logic, testing, and documentation changes across all modified files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch 35-parser-implement-bitwise-xor-not-and-any-value-x-operators

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 CI must pass

Wonderful, this rule succeeded.

All CI checks must pass. Release-plz PRs are exempt because they only bump versions and changelogs (code was already tested on main), and GITHUB_TOKEN-triggered force-pushes suppress CI.

• check-success = coverage
• check-success = quality
• check-success = test
• check-success = test-cross-platform (macos-latest, macOS)
• check-success = test-cross-platform (ubuntu-22.04, Linux)
• check-success = test-cross-platform (ubuntu-latest, Linux)
• check-success = test-cross-platform (windows-latest, Windows)

🟢 Do not merge outdated PRs

Wonderful, this rule succeeded.

Make sure PRs are within 10 commits of the base branch before merging

• #commits-behind <= 3

[dosubot]

Related Documentation

7 document(s) may need updating based on files changed in this PR:

libMagic-rs

api-reference /libmagic-rs/blob/main/docs/src/api-reference.md

View Suggested Changes

@@ -231,22 +231,52 @@
 
 ### Operator
 
-Comparison operators.
+Comparison and bitwise operators for magic rule matching.
 
 ```rust
 use libmagic_rs::Operator;
 ```
 
-| Variant               | Description                                               |
-| --------------------- | --------------------------------------------------------- |
-| `Equal`               | Equality comparison (`=`)                                 |
-| `NotEqual`            | Inequality comparison (`!=`)                              |
-| `LessThan`            | Less than comparison (`<`) (added in v0.2.0)              |
-| `GreaterThan`         | Greater than comparison (`>`) (added in v0.2.0)           |
-| `LessEqual`           | Less than or equal comparison (`<=`) (added in v0.2.0)    |
-| `GreaterEqual`        | Greater than or equal comparison (`>=`) (added in v0.2.0) |
-| `BitwiseAnd`          | Bitwise AND                                               |
-| `BitwiseAndMask(u64)` | Bitwise AND with mask                                     |
+| Variant               | Description                                                               |
+| --------------------- | ------------------------------------------------------------------------- |
+| `Equal`               | Equality comparison (`=`)                                                 |
+| `NotEqual`            | Inequality comparison (`!=`)                                              |
+| `LessThan`            | Less than comparison (`<`) (added in v0.2.0)                              |
+| `GreaterThan`         | Greater than comparison (`>`) (added in v0.2.0)                           |
+| `LessEqual`           | Less than or equal comparison (`<=`) (added in v0.2.0)                    |
+| `GreaterEqual`        | Greater than or equal comparison (`>=`) (added in v0.2.0)                 |
+| `BitwiseAnd`          | Bitwise AND (`&`) - matches if any bits overlap                           |
+| `BitwiseAndMask(u64)` | Bitwise AND with mask - masked comparison of file data                    |
+| `BitwiseXor`          | Bitwise XOR (`^`) - matches if XOR result is non-zero                     |
+| `BitwiseNot`          | Bitwise NOT (`~`) - compares complement of file value with expected value |
+| `AnyValue`            | Match any value (`x`) - unconditional match                               |
+
+#### Examples
+
+```rust
+use libmagic_rs::{MagicDatabase, Operator};
+use libmagic_rs::parser::grammar::parse_magic_rule;
+
+// Equal operator (default)
+let (_, rule) = parse_magic_rule("0 byte =0x7f").unwrap();
+assert_eq!(rule.op, Operator::Equal);
+
+// Bitwise AND - check if bit is set
+let (_, rule) = parse_magic_rule("0 byte &0x80").unwrap();
+assert_eq!(rule.op, Operator::BitwiseAnd);
+
+// Bitwise XOR - check for difference
+let (_, rule) = parse_magic_rule("0 byte ^0xFF").unwrap();
+assert_eq!(rule.op, Operator::BitwiseXor);
+
+// Bitwise NOT - check complement
+let (_, rule) = parse_magic_rule("0 byte ~0xFF").unwrap();
+assert_eq!(rule.op, Operator::BitwiseNot);
+
+// Any value - always matches
+let (_, rule) = parse_magic_rule("0 byte x").unwrap();
+assert_eq!(rule.op, Operator::AnyValue);
+```
 
 ### Value
 

✅ Accepted

API_REFERENCE /libmagic-rs/blob/main/docs/API_REFERENCE.md

View Suggested Changes

@@ -337,6 +337,9 @@
 | `GreaterEqual`        | Greater than or equal comparison (`>=`) (added in v0.2.0) |
 | `BitwiseAnd`          | Bitwise AND (`&`)                                         |
 | `BitwiseAndMask(u64)` | Bitwise AND with mask value                               |
+| `BitwiseXor`          | Bitwise XOR (`^`)                                         |
+| `BitwiseNot`          | Bitwise NOT/complement (`~`)                              |
+| `AnyValue`            | Match any value unconditionally (`x`)                     |
 
 **Version Note:** The comparison operators `LessThan`, `GreaterThan`, `LessEqual`, and `GreaterEqual` were added in v0.2.0.
 

✅ Accepted

architecture /libmagic-rs/blob/main/docs/src/architecture.md

View Suggested Changes

@@ -63,7 +63,7 @@
 
 - ✅ **Number parsing**: Decimal and hexadecimal with overflow protection
 - ✅ **Offset parsing**: Absolute offsets with comprehensive validation
-- ✅ **Operator parsing**: Equality (`=`, `==`), inequality (`!=`, `<>`), comparison (`<`, `>`, `<=`, `>=`), and bitwise AND (`&`) operators
+- ✅ **Operator parsing**: Equality (`=`, `==`), inequality (`!=`, `<>`), comparison (`<`, `>`, `<=`, `>=`), bitwise (`&`, `^`, `~`), and any-value (`x`) operators
 - ✅ **Value parsing**: Strings, numbers, and hex byte sequences with escape sequences
 - ✅ **Error handling**: Comprehensive nom error handling with meaningful messages
 - ✅ **Rule parsing**: Complete rule parsing via `parse_magic_rule()`
@@ -106,6 +106,9 @@
     GreaterEqual,                 // >=
     BitwiseAnd,                   // &
     BitwiseAndMask(u64),          // & with mask
+    BitwiseXor,                   // ^
+    BitwiseNot,                   // ~
+    AnyValue,                     // x (always matches)
 }
 ```
 
@@ -134,7 +137,7 @@
   - `mod.rs`: Dispatcher (`apply_operator`) and re-exports
   - `equality.rs`: `apply_equal`, `apply_not_equal`
   - `comparison.rs`: `compare_values`, `apply_less_than`/`greater_than`/`less_equal`/`greater_equal`
-  - `bitwise.rs`: `apply_bitwise_and`, `apply_bitwise_and_mask`
+  - `bitwise.rs`: `apply_bitwise_and`, `apply_bitwise_and_mask`, `apply_bitwise_xor`, `apply_bitwise_not`
 
 **Implemented Features:**
 
@@ -261,7 +264,7 @@
 
 **Operator Support:**
 
-The evaluator supports all comparison and bitwise operators:
+The evaluator supports all comparison, bitwise, and special matching operators:
 
 - **Equality**: `=` or `==` (exact match)
 - **Inequality**: `!=` or `<>` (not equal)
@@ -270,6 +273,9 @@
 - **Less-equal**: `<=` (numeric or lexicographic)
 - **Greater-equal**: `>=` (numeric or lexicographic)
 - **Bitwise AND**: `&` (bit pattern matching)
+- **Bitwise XOR**: `^` (exclusive OR pattern matching)
+- **Bitwise NOT**: `~` (bitwise complement comparison)
+- **Any-value**: `x` (unconditional match, always succeeds)
 
 Comparison operators support both numeric comparisons (with automatic type coercion between signed and unsigned integers via `i128`) and lexicographic comparisons for strings and byte sequences.
 

✅ Accepted

Magic File Compatibility Status

View Suggested Changes

@@ -22,7 +22,7 @@
 - **[String](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/types.rs#L275-L308)**: Null-terminated or length-limited strings with UTF-8 conversion using [SIMD-accelerated null scanning](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/types.rs#L291-L298)
 
 #### Operators
-Twelve operators are [fully implemented in evaluation](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/operators.rs):
+Fifteen operators are [fully implemented in evaluation](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/operators.rs):
 
 - **[Equal (=, ==)](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/operators.rs#L48-L69)**: Equality comparison with cross-type integer coercion
 - **[NotEqual (!=, <>)](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/operators.rs#L108-L110)**: Inequality comparison
@@ -32,8 +32,11 @@
 - **[GreaterEqual (>=)](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/operators.rs#L273-L280)**: Greater-than-or-equal comparison with cross-type integer coercion
 - **[BitwiseAnd (&)](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/operators.rs#L148-L166)**: Bitwise AND pattern matching (returns true if result is non-zero)
 - **[BitwiseAndMask (&0xMASK)](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/operators.rs#L224-L237)**: Applies mask to value before equality comparison
-
-[12 of 17 operators are implemented (71%)](https://github.com/EvilBit-Labs/libmagic-rs/issues/53), with comparison operators providing version checks and range matching capabilities.
+- **BitwiseXor (^)**: Bitwise XOR pattern matching (returns true if result is non-zero)
+- **BitwiseNot (~)**: Applies bitwise complement to value before equality comparison
+- **AnyValue (x)**: Unconditional match that always returns true
+
+[15 of 17 operators are implemented (88%)](https://github.com/EvilBit-Labs/libmagic-rs/issues/53), with comparison operators providing version checks and range matching capabilities.
 
 #### Offsets
 Two offset types are [fully operational](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/offset.rs):
@@ -95,13 +98,11 @@
 Development is organized into five epics that systematically address compatibility gaps. Each epic targets specific version milestones and has defined success criteria.
 
 ### Epic #53: Operator Completeness (v0.2.0)
-[Status: Comparison operators implemented; bitwise operators pending](https://github.com/EvilBit-Labs/libmagic-rs/issues/53). Currently 12 of 17 required operators are implemented (71%).
+[Status: Nearly complete](https://github.com/EvilBit-Labs/libmagic-rs/issues/53). Currently 15 of 17 required operators are implemented (88%).
 
 **Implemented operators:**
 - [Comparison operators (<, >, <=, >=) implemented in PR #104](https://github.com/EvilBit-Labs/libmagic-rs/pull/104) - These operators enable version checks and range matching, unlocking compatibility with magic rules that test numeric ranges. Released in v0.2.0.
-
-**Missing operators:**
-- [Bitwise XOR (^), NOT (~), and any-value (x) operators tracked in Issue #35](https://github.com/EvilBit-Labs/libmagic-rs/issues/35) - Required for advanced binary pattern matching.
+- [Bitwise XOR (^), NOT (~), and any-value (x) operators implemented in PR #145](https://github.com/EvilBit-Labs/libmagic-rs/pull/145) - Resolves Issue #35. Required for advanced binary pattern matching and unconditional match patterns.
 
 ### Epic #54: Type System Expansion (v0.2.0 + v0.3.0)
 [Status: 5 of 33+ types implemented](https://github.com/EvilBit-Labs/libmagic-rs/issues/54). The type system expansion is split across two releases to manage code complexity.
@@ -178,6 +179,7 @@
 **Implemented features:**
 - [Comparison operators (<, >, <=, >=) via PR #104](https://github.com/EvilBit-Labs/libmagic-rs/pull/104) - Enables version checks and range matching for numeric values, unlocking magic rules that test numeric ranges
 - [Quad (64-bit integer) type via PR #133](https://github.com/EvilBit-Labs/libmagic-rs/pull/133) - Provides signed and unsigned 64-bit integer support with endianness variants for modern binary formats
+- [Bitwise XOR (^), NOT (~), and any-value (x) operators via PR #145](https://github.com/EvilBit-Labs/libmagic-rs/pull/145) - Enables advanced binary pattern matching and unconditional match patterns
 
 ### v0.3.0 - Planned
 [Focus: Offset resolution and type system expansion](https://github.com/EvilBit-Labs/libmagic-rs/issues/52). This release adds support for indirect/relative offsets, text file detection, and advanced numeric types.
@@ -189,7 +191,6 @@
 - Float and double numeric types with endianness variants
 - Date and timestamp types for temporal matching
 - Pascal string type (pstring)
-- Additional bitwise operators: XOR, NOT, any-value
 - ZIP content inspection enhancements
 
 **Mandatory prerequisite refactoring:**
@@ -263,7 +264,7 @@
 | [src/evaluator/mod.rs](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/mod.rs) | Core rule evaluation engine | 474 lines; implements hierarchical rule evaluation with graceful error handling and timeout checking |
 | [src/evaluator/offset.rs](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/offset.rs) | Offset resolution logic | Implements absolute and FromEnd offsets; contains explicit stubs with TODOs for indirect/relative |
 | [src/evaluator/types.rs](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/types.rs) | Type reading and coercion | Implements byte, short, long, quad, string with SIMD optimizations; target for directory module conversion |
-| [src/evaluator/operators.rs](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/operators.rs) | Operator evaluation | Implements =, !=, <, >, <=, >=, &, &mask with cross-type integer coercion using i128 intermediate type |
+| [src/evaluator/operators.rs](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/operators.rs) | Operator evaluation | Implements =, !=, <, >, <=, >=, &, &mask, ^, ~, x with cross-type integer coercion using i128 intermediate type |
 | [docs/src/compatibility.md](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/docs/src/compatibility.md) | Compatibility tracking document | Comprehensive comparison of libmagic versus libmagic-rs features with implementation status |
 
 ## Architectural Differences from Original libmagic

✅ Accepted

parser /libmagic-rs/blob/main/docs/src/parser.md

View Suggested Changes

@@ -78,6 +78,11 @@
 
 // Bitwise operators
 parse_operator("&")    // Ok(("", Operator::BitwiseAnd))
+parse_operator("^")    // Ok(("", Operator::BitwiseXor))
+parse_operator("~")    // Ok(("", Operator::BitwiseNot))
+
+// Any-value operator (always matches)
+parse_operator("x")    // Ok(("", Operator::AnyValue))
 ```
 
 **Features:**
@@ -86,7 +91,7 @@
 - ✅ Precedence handling (longer operators matched first)
 - ✅ Whitespace tolerance
 - ✅ Invalid operator rejection with clear errors
-- ✅ Eight comparison and bitwise operators supported
+- ✅ Eleven comparison and bitwise operators supported
 
 **Note:** Comparison operators (`<`, `>`, `<=`, `>=`) were implemented in v0.2.0 via [#104](https://github.com/EvilBit-Labs/libmagic-rs/pull/104).
 

✅ Accepted

Parser-Evaluator Architecture

View Suggested Changes

@@ -86,7 +86,7 @@
 **Supporting Enums**:
 - **`OffsetSpec`**: Absolute, Indirect (pointer dereferencing), Relative, FromEnd
 - **`TypeKind`**: Byte, Short, Long, Quad, String (each numeric type with endianness and signedness)
-- **`Operator`**: Equal, NotEqual, LessThan, GreaterThan, LessEqual, GreaterEqual, BitwiseAnd, BitwiseAndMask
+- **`Operator`**: Equal, NotEqual, LessThan, GreaterThan, LessEqual, GreaterEqual, BitwiseAnd, BitwiseAndMask, BitwiseXor, BitwiseNot, AnyValue
 - **`Value`**: Uint, Int, Bytes, String
 - **`Endianness`**: Little, Big, Native
 - **`StrengthModifier`**: Add, Subtract, Multiply, Divide, Set
@@ -297,6 +297,45 @@
 ```
 
 This operator applies a mask to the file data before comparison, useful for checking specific bit patterns (e.g., `byte&0xF0` to check upper nibble).
+
+**Bitwise XOR Operations** (from `bitwise.rs`):
+```rust
+pub fn apply_bitwise_xor(left: &Value, right: &Value) -> bool {
+    match (left, right) {
+        (Value::Uint(a), Value::Uint(b)) => (a ^ b) != 0,
+        (Value::Int(a), Value::Int(b)) => ((*a as u64) ^ (*b as u64)) != 0,
+        (Value::Uint(a), Value::Int(b)) => (a ^ (*b as u64)) != 0,
+        (Value::Int(a), Value::Uint(b)) => ((*a as u64) ^ b) != 0,
+        _ => false,
+    }
+}
+```
+
+Returns `true` if the XOR result is non-zero, enabling pattern matching for differing bits.
+
+**Bitwise NOT Operations** (from `bitwise.rs`):
+```rust
+pub fn apply_bitwise_not(left: &Value, right: &Value) -> bool {
+    let complemented = match left {
+        Value::Uint(val) => Value::Uint(!val),
+        Value::Int(val) => Value::Int(!*val),
+        _ => return false,
+    };
+    apply_equal(&complemented, right)
+}
+```
+
+Computes the bitwise complement of the left (file) value, then checks equality with the right value.
+
+**AnyValue Operator** (from `operators/mod.rs`):
+```rust
+pub fn apply_any_value(_left: &Value, _right: &Value) -> bool {
+    true
+}
+```
+
+The `AnyValue` operator (`x`) always returns `true`, providing unconditional matching. Useful for displaying information about file data without performing comparisons.
+
 
 ## Data Flow and Module Interactions
 
@@ -440,6 +479,12 @@
 // Stage 3: Apply operator
 let expected = Value::Uint(0x464C457F); // "\x7fELF" as little-endian u32
 let matches = operators::apply_operator(&Operator::Equal, &read_value, &expected);
+
+// Example with BitwiseXor
+let matches_xor = operators::apply_operator(&Operator::BitwiseXor, &Value::Uint(0xFF), &Value::Uint(0x0F));
+
+// Example with AnyValue (always matches)
+let always_matches = operators::apply_operator(&Operator::AnyValue, &read_value, &Value::Uint(0));
 ```
 
 Example with Quad (64-bit) type:

✅ Accepted

Type System And Operator Coverage

View Suggested Changes

@@ -66,7 +66,7 @@
 
 ### Operator Architecture
 
-The operator system consists of [eight distinct operators](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/parser/ast.rs#L106-L117) defined in the AST, with runtime evaluation provided by [dedicated functions](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/operators.rs#L219-L239) in `src/evaluator/operators.rs`.
+The operator system consists of eleven distinct operators defined in the AST, with runtime evaluation provided by dedicated functions in `src/evaluator/operators.rs`.
 
 ### Implemented Operators
 
@@ -125,16 +125,41 @@
 - **Implementation**: [Masks left value, then calls apply_equal](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/src/evaluator/operators.rs#L224-L238)
 - **Strength Score**: +7 points (moderately specific)
 
+#### BitwiseXor Operator (^)
+- **Semantics**: Performs bitwise XOR between two integer values; returns true if result is non-zero
+- **Use Case**: Detecting bit pattern differences and validation checksums
+- **Integer Support**: Works with `Uint`, `Int`, and mixed integer types
+- **Signed Handling**: Signed integers cast to `u64` for bitwise operations
+- **Implementation**: apply_bitwise_xor function in `src/evaluator/operators/bitwise.rs`
+- **Strength Score**: +4 points
+- **Version**: v0.2.x
+
+#### BitwiseNot Operator (~)
+- **Semantics**: Computes bitwise complement of left operand, then checks equality with right value
+- **Use Case**: Detecting inverted bit patterns
+- **Integer Support**: Works with `Uint` and `Int` types only
+- **Implementation**: apply_bitwise_not function in `src/evaluator/operators/bitwise.rs`
+- **Strength Score**: +4 points
+- **Version**: v0.2.x
+
+#### AnyValue Operator (x)
+- **Semantics**: Unconditional match; always returns true regardless of operand values
+- **Use Case**: Extracting information without filtering, always-match continuation rules
+- **Type Compatibility**: Accepts any value types
+- **Implementation**: apply_any_value function in `src/evaluator/operators/mod.rs`
+- **Strength Score**: +1 point (least specific)
+- **Version**: v0.2.x
+
 ### Operator Type Compatibility Matrix
 
-| Left Type | Right Type | Equal/NotEqual | Comparison (<,>,<=,>=) | BitwiseAnd | BitwiseAndMask |
-|-----------|------------|----------------|------------------------|------------|----------------|
-| Uint      | Uint       | ✅ Direct      | ✅ Direct              | ✅         | ✅             |
-| Int       | Int        | ✅ Direct      | ✅ Direct              | ✅         | ✅             |
-| Uint      | Int        | ✅ i128 coerce | ✅ i128 coerce         | ✅         | ✅             |
-| Bytes     | Bytes      | ✅ Direct      | ✅ Lexicographic       | ❌         | ❌             |
-| String    | String     | ✅ Direct      | ✅ Lexicographic       | ❌         | ❌             |
-| Mixed     | Mixed      | ❌             | ❌                     | ❌         | ❌             |
+| Left Type | Right Type | Equal/NotEqual | Comparison (<,>,<=,>=) | BitwiseAnd | BitwiseAndMask | BitwiseXor | BitwiseNot | AnyValue |
+|-----------|------------|----------------|------------------------|------------|----------------|------------|------------|----------|
+| Uint      | Uint       | ✅ Direct      | ✅ Direct              | ✅         | ✅             | ✅         | ✅         | ✅       |
+| Int       | Int        | ✅ Direct      | ✅ Direct              | ✅         | ✅             | ✅         | ✅         | ✅       |
+| Uint      | Int        | ✅ i128 coerce | ✅ i128 coerce         | ✅         | ✅             | ✅         | ✅         | ✅       |
+| Bytes     | Bytes      | ✅ Direct      | ✅ Lexicographic       | ❌         | ❌             | ❌         | ❌         | ✅       |
+| String    | String     | ✅ Direct      | ✅ Lexicographic       | ❌         | ❌             | ❌         | ❌         | ✅       |
+| Mixed     | Mixed      | ❌             | ❌                     | ❌         | ❌             | ❌         | ❌         | ✅       |
 
 ## Offset Type System
 
@@ -220,23 +245,23 @@
 - ✅ GreaterThan (>)
 - ✅ LessEqual (<=)
 - ✅ GreaterEqual (>=)
-
-**Operator Coverage**: 8 of ~13 operators (62%)
+- ✅ BitwiseXor (^) - [PR #145](https://github.com/EvilBit-Labs/libmagic-rs/pull/145)
+- ✅ BitwiseNot (~) - [PR #145](https://github.com/EvilBit-Labs/libmagic-rs/pull/145)
+- ✅ AnyValue (x) - [PR #145](https://github.com/EvilBit-Labs/libmagic-rs/pull/145)
+
+**Operator Coverage**: 11 of ~13 operators (85%)
 
 ### v0.3.0 (Core Primitives - Planned)
 
-**Focus**: [Advanced bitwise operators and offset resolution](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/ROADMAP.md#L18-L28)
-
-**New Operators**:
-- Bitwise: `^` (XOR), `~` (NOT), any-value operators ([Issue #35](https://github.com/EvilBit-Labs/libmagic-rs/issues/35))
+**Focus**: [Offset resolution enhancements](https://github.com/EvilBit-Labs/libmagic-rs/blob/e925ef6b3f2208fc8805a728ba3de55956f4447a/ROADMAP.md#L18-L28)
 
 **Offset Enhancements**:
-- ✅ [Indirect offset evaluation](https://github.com/EvilBit-Labs/libmagic-rs/issues/37) (pointer dereferencing)
-- ✅ [Relative offset evaluation](https://github.com/EvilBit-Labs/libmagic-rs/issues/38) (position tracking)
+- [Indirect offset evaluation](https://github.com/EvilBit-Labs/libmagic-rs/issues/37) (pointer dereferencing)
+- [Relative offset evaluation](https://github.com/EvilBit-Labs/libmagic-rs/issues/38) (position tracking)
 
 **Expected Coverage**:
 - Types: 5 of ~33 (15%)
-- Operators: ~11 of ~13 (85%)
+- Operators: 11 of ~13 (85%)
 - Offsets: 5 of 5 (100%)
 
 ### v0.4.0 (Advanced Features - Planned)
@@ -252,7 +277,7 @@
 
 **Expected Coverage**:
 - Types: ~25 of ~33 (76%)
-- Operators: ~11 of ~13 (85%)
+- Operators: 11 of ~13 (85%)
 
 ### v0.5.0 (API and UX Polish - Planned)
 
@@ -276,7 +301,7 @@
 
 **Expected Coverage**:
 - Types: ~31 of ~33 (94%)
-- Operators: ~13 of ~13 (100%)
+- Operators: 13 of 13 (100%)
 - Offsets: 5 of 5 (100%)
 
 ## Compatibility Coverage Tracking
@@ -309,8 +334,8 @@
 | Version | Compatibility Target | Key Enablers |
 |---------|---------------------|--------------|
 | v0.1.x | 0% (baseline) | Built-in rules only, 4 basic operators |
-| v0.2.0 | 0% (baseline) | Added comparison operators, quad type |
-| v0.3.0 | ~30% | Indirect/relative offsets, advanced bitwise operators |
+| v0.2.0 | 0% (baseline) | Added comparison operators, bitwise XOR/NOT/any-value, quad type |
+| v0.3.0 | ~30% | Indirect/relative offsets |
 | v0.4.0 | ~60% | Regex, floating-point, date/time types |
 | v0.5.0 | ~80% | Meta-types, remaining edge cases |
 | v1.0.0 | 95%+ | Full feature parity |
@@ -380,14 +405,14 @@
 | | `<=` | Less or equal | ✅ Implemented | v0.2.0 |
 | **Bitwise** | `&` | Bitwise AND (test) | ✅ Implemented | v0.1.x |
 | | `&mask=value` | Bitwise AND with mask | ✅ Implemented | v0.1.x |
-| | `^` | Bitwise XOR | 📋 Planned | v0.3.0 |
-| | `~` | Bitwise NOT | 📋 Planned | v0.3.0 |
-| **Special** | `x` | Any value (always match) | 📋 Planned | v0.3.0 |
+| | `^` | Bitwise XOR | ✅ Implemented | v0.2.x |
+| | `~` | Bitwise NOT | ✅ Implemented | v0.2.x |
+| **Special** | `x` | Any value (always match) | ✅ Implemented | v0.2.x |
 | | `!` | Negation prefix | 📋 Planned | v0.3.0 |
 
-**Current Coverage**: 8 of 13 operators (62%)
-**v0.3.0 Target**: ~11 of 13 operators (85%)
-**v1.0.0 Target**: ~13 of 13 operators (100%)
+**Current Coverage**: 11 of 13 operators (85%)
+**v0.3.0 Target**: 12 of 13 operators (92%)
+**v1.0.0 Target**: 13 of 13 operators (100%)
 
 ## Security and Safety Features
 

✅ Accepted

Note: You must be authenticated to accept/decline updates.

^{How did I do? Any feedback?}  

[Copilot]

Pull request overview

Copilot reviewed 41 out of 41 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 41 out of 41 changed files in this pull request and generated 1 comment.