Conex

Conex is a powerful C++ single-header library designed for condition-based binary pattern matching. Unlike traditional methods that rely on hard-coded byte signatures, Conex allows users to define matching conditions using lambdas, facilitating more flexible and semantic pattern searches. With Conex, structures can be detected based on specific conditions rather than using mere byte values.

Key Features

• C++20 Compatibility: Built to leverage the features of C++20, ensuring modern C++ practices.
• No External Dependencies: The library is lightweight, requiring no dependencies beyond the standard library.
• Flexible Pattern Syntax: Patterns are expressed as sequences of groups, providing significant versatility.

Usage Example

Conex offers intuitive APIs for performing pattern searches. Below is an example demonstrating how to search for a binary pattern:

auto result = conex::search_first(blob, "(c0:4)(c1:8)*",
    [](std::span<const uint8_t> s) { /* signature check */ },
    [](std::span<const uint8_t> s) { /* page-aligned address */ }
);

Pattern Syntax Breakdown

A pattern consists of a series of groups formatted as follows:

(cN:W)Q

|| Part | Meaning | |---------|--------------------------------------------------------------------------| | N | Index of the lambda to use (0-based matching your variadic arguments) | | :W | Width in bytes to consume per match (default: 1) | | Q | Quantifier: * zero or more, + one or more, ? zero or one |

Core API Functions

1. conex::search_first: Scans a blob and returns the first match.

   conex::MatchResult conex::search_first(std::span<const uint8_t> blob, std::string_view pattern, Conds&&... conditions);
   

2. conex::search_all: Returns all non-overlapping matches.

   std::vector<conex::MatchResult> conex::search_all(std::span<const uint8_t> blob, std::string_view pattern, Conds&&... conditions);
   

3. conex::match: Attempts to match at the start or at a specific offset in a given span.

   conex::MatchResult conex::match(std::span<const uint8_t> blob, std::string_view pattern, Conds&&... conditions);
   

Match Result Structure

The MatchResult structure provides details about the matches:

struct MatchResult {
    bool matched;                             // Indicates if a match was found
    size_t start;                             // Byte offset where match begins
    size_t end;                               // Byte offset after match ends
    std::vector<std::vector<Capture>> captures; // Captures from the matched groups
};

This library is particularly useful for developers working with binary data who wish to implement advanced searching capabilities with a semantic approach.