mongory 0.6.2 → 0.7.0

data/ext/mongory_ext/mongory-core/src/matchers/array_record_matcher.c

@@ -0,0 +1,309 @@
+/**
+ * @file array_record_matcher.c
+ * @brief Implements a versatile matcher for arrays, handling various condition
+ * types. This is an internal implementation file for the matcher module.
+ *
+ * This matcher can interpret conditions as:
+ * - A table: Parsed for operators like $elemMatch or implicit field conditions
+ *   on array elements.
+ * - A regex: Creates an $elemMatch to match array elements against the regex.
+ * - A literal: Creates an $elemMatch to check for equality with elements.
+ * - Another array: Checks for whole-array equality.
+ * It often constructs a composite OR matcher to combine these possibilities.
+ */
+#include "array_record_matcher.h"
+#include "../foundations/config_private.h" // For mongory_try_parse_int
+#include "base_matcher.h"                  // For mongory_matcher_base_new, mongory_try_parse_int
+#include "compare_matcher.h"               // For mongory_matcher_equal_new
+#include "composite_matcher.h"             // For mongory_matcher_composite_new, $elemMatch, table_cond_new, or_match
+#include "literal_matcher.h"               // Potentially used by table_cond_new
+#include "mongory-core/foundations/table.h"
+#include "mongory-core/foundations/value.h"
+#include <mongory-core.h> // General include
+#include <stdio.h>        // For NULL
+#include <string.h>       // For strcmp
+
+/**
+ * @struct mongory_matcher_array_record_parse_table_context
+ * @brief Context used when parsing a table condition for array record matching.
+ *
+ * Helps separate parts of the condition table:
+ * - `parsed_table`: For explicit operators (e.g., $size, $all if implemented)
+ *   or indexed conditions.
+ * - `elem_match_table`: For conditions that should apply to individual elements
+ *   via an implicit or explicit $elemMatch.
+ */
+typedef struct mongory_matcher_array_record_parse_table_context {
+  mongory_table *parsed_table;     /**< Stores operator or indexed conditions. */
+  mongory_table *elem_match_table; /**< Stores conditions for element matching. */
+} mongory_matcher_array_record_parse_table_context;
+
+/**
+ * @brief Callback to populate the `elem_match_table` during parsing.
+ * Used when an explicit $elemMatch object is found within the condition.
+ * @param key Key from the $elemMatch object.
+ * @param value Value from the $elemMatch object.
+ * @param acc Pointer to `mongory_matcher_array_record_parse_table_context`.
+ * @return Always true to continue iteration.
+ */
+static inline bool mongory_matcher_array_record_set_table_elem(char *key, mongory_value *value, void *acc) {
+  mongory_matcher_array_record_parse_table_context *context = (mongory_matcher_array_record_parse_table_context *)acc;
+  mongory_table *elem_match_table_to_populate = context->elem_match_table;
+  elem_match_table_to_populate->set(elem_match_table_to_populate, key, value);
+  return true;
+}
+
+/**
+ * @brief Callback to parse a condition table for array matching.
+ *
+ * Iterates through the main condition table:
+ * - If `key` is "$elemMatch" and `value` is a table, its contents are added to
+ *   `context->elem_match_table`.
+ * - If `key` starts with '$' (another operator) or is numeric (array index),
+ *   it's added to `context->parsed_table`.
+ * - Otherwise (plain field name), it's considered part of an implicit element
+ *   match and added to `context->elem_match_table`.
+ *
+ * @param key Current key in the condition table.
+ * @param value Current value for the key.
+ * @param acc Pointer to `mongory_matcher_array_record_parse_table_context`.
+ * @return Always true to continue.
+ */
+static inline bool mongory_matcher_array_record_parse_table_foreach(char *key, mongory_value *value, void *acc) {
+  mongory_matcher_array_record_parse_table_context *context = (mongory_matcher_array_record_parse_table_context *)acc;
+  mongory_table *parsed_table_for_operators = context->parsed_table;
+  mongory_table *table_for_elem_match_conditions = context->elem_match_table;
+
+  if (strcmp(key, "$elemMatch") == 0 && value->type == MONGORY_TYPE_TABLE && value->data.t != NULL) {
+    // Explicit $elemMatch: iterate its sub-table and add to elem_match_table
+    mongory_table *elem_match_condition_object = value->data.t;
+    elem_match_condition_object->each(elem_match_condition_object, context,
+                                      mongory_matcher_array_record_set_table_elem);
+  } else if (*key == '$' || mongory_try_parse_int(key, NULL)) {
+    // Operator (like $size) or numeric index: goes to parsed_table
+    parsed_table_for_operators->set(parsed_table_for_operators, key, value);
+  } else {
+    // Regular field name: implies a condition on elements, goes to
+    // elem_match_table
+    table_for_elem_match_conditions->set(table_for_elem_match_conditions, key, value);
+  }
+  return true;
+}
+
+/**
+ * @brief Parses a table `condition` intended for array matching.
+ *
+ * Separates the condition into parts for direct array operations (like $size)
+ * and parts for matching individual elements (implicit or explicit $elemMatch).
+ * If any element-matching conditions are found, they are grouped under an
+ * "$elemMatch" key in the returned `parsed_table`.
+ *
+ * @param condition The `mongory_value` (must be a table) to parse.
+ * @return A new `mongory_value` (table) containing the parsed and restructured
+ * condition. Returns NULL if input is not a table or on allocation failure.
+ */
+static inline mongory_value *mongory_matcher_array_record_parse_table(mongory_value *condition) {
+  if (!condition || condition->type != MONGORY_TYPE_TABLE || !condition->data.t || !condition->pool) {
+    return NULL; // Invalid input
+  }
+  mongory_memory_pool *pool = condition->pool;
+  mongory_table *parsed_table = mongory_table_new(pool);
+  mongory_table *elem_match_sub_table = mongory_table_new(pool);
+
+  if (!parsed_table || !elem_match_sub_table) {
+    // Cleanup if one allocation succeeded but other failed? Pool should handle.
+    return NULL;
+  }
+
+  mongory_matcher_array_record_parse_table_context parse_ctx = {parsed_table, elem_match_sub_table};
+  mongory_table *original_condition_table = condition->data.t;
+
+  original_condition_table->each(original_condition_table, &parse_ctx,
+                                 mongory_matcher_array_record_parse_table_foreach);
+
+  if (elem_match_sub_table->count > 0) {
+    // If there were conditions for element matching, add them as an $elemMatch
+    // clause to the main parsed_table.
+    parsed_table->set(parsed_table, "$elemMatch", mongory_value_wrap_t(pool, elem_match_sub_table));
+  }
+  // If elem_match_sub_table is empty, it's not added. The original parsed_table
+  // (which might contain $size etc.) is returned.
+  return mongory_value_wrap_t(pool, parsed_table);
+}
+
+/**
+ * @brief Wraps a table in a value.
+ * @param pool Memory pool.
+ * @param key Key to set in the table.
+ * @param value Value to set in the table.
+ * @return A new `mongory_value` (table) containing the wrapped table.
+ */
+static inline mongory_value *mongory_matcher_array_record_parse_table_wrap(mongory_memory_pool *pool, char *key, mongory_value *value) {
+  if (!pool || !key || !value)
+    return NULL;
+  mongory_table *table = mongory_table_new(pool);
+  if (!table)
+    return NULL;
+  table->set(table, key, value);
+  return mongory_value_wrap_t(pool, table);
+}
+
+/**
+ * @brief Helper to create an $elemMatch matcher with an inner $regex condition.
+ * E.g., for matching an array where elements match a regex.
+ * @param pool Memory pool.
+ * @param regex_condition The `mongory_value` (string or regex type) for the
+ * regex.
+ * @return A new $elemMatch matcher with a nested $regex, or NULL on failure.
+ */
+static inline mongory_matcher *mongory_matcher_array_record_elem_match_regex_new(mongory_memory_pool *pool,
+                                                                                 mongory_value *regex_condition, void *extern_ctx) {
+  mongory_value *wrapped_table = mongory_matcher_array_record_parse_table_wrap(pool, "$regex", regex_condition);
+  if (!wrapped_table)
+    return NULL;
+  return mongory_matcher_elem_match_new(pool, wrapped_table, extern_ctx);
+}
+
+/**
+ * @brief Helper to create an $elemMatch matcher with an inner $eq condition.
+ * E.g., for matching an array containing a specific literal value.
+ * @param pool Memory pool.
+ * @param literal_condition The `mongory_value` literal to find in array
+ * elements.
+ * @return A new $elemMatch matcher with a nested $eq, or NULL on failure.
+ */
+static inline mongory_matcher *mongory_matcher_array_record_elem_match_equal_new(mongory_memory_pool *pool,
+                                                                                 mongory_value *literal_condition, void *extern_ctx) {
+  mongory_value *wrapped_table = mongory_matcher_array_record_parse_table_wrap(pool, "$eq", literal_condition);
+  if (!wrapped_table)
+    return NULL;
+  return mongory_matcher_elem_match_new(pool, wrapped_table, extern_ctx);
+}
+
+/**
+ * @brief Delegates creation of the "left" part of an array_record_matcher.
+ *
+ * This part typically handles conditions related to array elements (e.g.,
+ * $elemMatch logic).
+ * - If `condition` is a table, it's parsed by
+ * `mongory_matcher_array_record_parse_table` and then a
+ * `mongory_matcher_table_cond_new` is created.
+ * - If `condition` is regex, creates an $elemMatch with inner $regex.
+ * - Otherwise (literal), creates an $elemMatch with inner $eq.
+ *
+ * @param pool Memory pool.
+ * @param condition The original condition for the array_record_matcher.
+ * @return The "left" child matcher, or NULL on failure.
+ */
+static inline mongory_matcher *mongory_matcher_array_record_generic_delegate(mongory_memory_pool *pool,
+                                                                          mongory_value *condition, void *extern_ctx) {
+  if (!condition)
+    return NULL;
+  switch (condition->type) {
+  case MONGORY_TYPE_TABLE: {
+    mongory_value *parsed_table_condition = mongory_matcher_array_record_parse_table(condition);
+    if (!parsed_table_condition)
+      return NULL;
+    return mongory_matcher_table_cond_new(pool, parsed_table_condition, extern_ctx);
+  }
+  case MONGORY_TYPE_REGEX:
+    return mongory_matcher_array_record_elem_match_regex_new(pool, condition, extern_ctx);
+  default: // Literals (string, int, bool, etc.)
+    return mongory_matcher_array_record_elem_match_equal_new(pool, condition, extern_ctx);
+  }
+}
+
+/**
+ * @brief Delegates creation of the "right" part of an array_record_matcher.
+ *
+ * This part handles conditions where the array_record_matcher's `condition`
+ * is itself an array, implying a whole-array equality check.
+ *
+ * @param pool Memory pool.
+ * @param condition The original condition for the array_record_matcher.
+ * @return An equality matcher if `condition` is an array, otherwise NULL.
+ */
+static inline mongory_matcher *mongory_matcher_array_record_array_cond_delegate(mongory_memory_pool *pool,
+                                                                           mongory_value *condition, void *extern_ctx) {
+  if (!condition)
+    return NULL;
+  switch (condition->type) {
+  case MONGORY_TYPE_ARRAY:
+    // If original condition is an array, right delegate is for direct equality.
+    return mongory_matcher_equal_new(pool, condition, extern_ctx);
+  default:
+    return NULL; // No whole-array equality check needed for other types.
+  }
+}
+
+/**
+ * @brief Match function for the array_record_matcher.
+ *
+ * It expects the `matcher` to be a composite OR matcher.
+ * It checks if the input `value` is an array, then applies the OR logic.
+ * This OR logic typically combines:
+ * 1. Matching based on element conditions (via `composite->left` from
+ * `left_delegate`).
+ * 2. Matching based on whole-array equality (via `composite->right` from
+ * `right_delegate`, if applicable).
+ *
+ * @param matcher The array_record_matcher instance (cast as base `mongory_matcher`).
+ * @param value The `mongory_value` to check, expected to be an array.
+ * @return True if the array matches according to the ORed conditions, false
+ * otherwise.
+ */
+static inline bool mongory_matcher_array_record_match(mongory_matcher *matcher, mongory_value *value) {
+  if (value == NULL || value->type != MONGORY_TYPE_ARRAY) {
+    return false; // Only applies to arrays.
+  }
+  // This matcher is constructed as a composite OR internally.
+  return mongory_matcher_or_match(matcher, value);
+}
+
+/**
+ * @brief Main constructor for `mongory_matcher_array_record_new`.
+ *
+ * Constructs a two-part matcher (often combined with OR):
+ * - `left`: Handles element-wise conditions (like $elemMatch from various
+ *   condition types).
+ * - `right`: Handles whole-array equality if the original `condition` was an
+ *   array.
+ *
+ * If `right` is NULL (i.e., original `condition` was not an array), only the
+ * `left` matcher is returned. Otherwise, a composite OR matcher is created
+ * with `left` and `right` as children.
+ *
+ * @param pool Memory pool.
+ * @param condition The condition to apply to arrays.
+ * @return The constructed array_record_matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_array_record_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!pool || !condition)
+    return NULL;
+
+  mongory_matcher *generic_child = mongory_matcher_array_record_generic_delegate(pool, condition, extern_ctx);
+  mongory_matcher *array_cond_child = mongory_matcher_array_record_array_cond_delegate(pool, condition, extern_ctx);
+
+  if (!(generic_child && array_cond_child)) {
+    return generic_child ? generic_child : array_cond_child;
+  }
+
+  // Both left (element-wise) and right (whole-array equality) are possible.
+  // Combine them with an OR.
+  mongory_composite_matcher *final_or_composite = mongory_matcher_composite_new(pool, condition, extern_ctx);
+  if (!final_or_composite) {
+    return NULL;
+  }
+
+  final_or_composite->children = mongory_array_new(pool);
+  if (!final_or_composite->children) {
+    return NULL;
+  }
+  final_or_composite->children->push(final_or_composite->children, (mongory_value *)generic_child);
+  final_or_composite->children->push(final_or_composite->children, (mongory_value *)array_cond_child);
+  final_or_composite->base.match = mongory_matcher_array_record_match; // Uses or_match
+  final_or_composite->base.original_match = mongory_matcher_array_record_match;
+
+  final_or_composite->base.name = mongory_string_cpy(pool, "ArrayRecord");
+  return (mongory_matcher *)final_or_composite;
+}

data/ext/mongory_ext/mongory-core/src/matchers/array_record_matcher.h

@@ -0,0 +1,47 @@
+#ifndef MONGORY_MATCHER_ARRAY_RECORD_H
+#define MONGORY_MATCHER_ARRAY_RECORD_H
+
+/**
+ * @file array_record_matcher.h
+ * @brief Defines the constructor for a matcher that handles complex conditions
+ * against arrays. This is an internal header for the matcher module.
+ *
+ * This matcher is more specialized than simple `$elemMatch` or `$every`. It can
+ * interpret a condition that might be a direct value to find, a regex to match
+ * elements, or a table defining multiple criteria for array elements (similar
+ * to an implicit `$elemMatch` with that table). It can also handle checking if
+ * an input array is equal to a condition array.
+ */
+
+#include "base_matcher.h"
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include "mongory-core/matchers/matcher.h" // For mongory_matcher structure
+
+/**
+ * @brief Creates an "array record" matcher.
+ *
+ * This matcher is designed to apply various types of conditions to an input
+ * array or its elements. The behavior depends on the `condition`'s type:
+ * - If `condition` is a table: It's parsed. Keys like `$elemMatch` are handled
+ *   specifically. Other field-value pairs in the table are typically wrapped
+ *   into an implicit `$elemMatch` condition that applies to elements of the
+ *   target array.
+ * - If `condition` is a regex: It effectively creates an `$elemMatch` where
+ *   each element of the target array is matched against this regex.
+ * - If `condition` is a simple literal (string, number, bool): It creates an
+ *   `$elemMatch` where elements are checked for equality against this literal.
+ * - If `condition` itself is an array: It creates a matcher that checks if the
+ *   target array is equal to this condition array.
+ *
+ * The resulting matcher might be a composite of several internal matchers (e.g.,
+ * an OR between element matching and whole-array equality).
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition A `mongory_value` representing the condition to apply to an
+ * array or its elements.
+ * @return A new array record matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_array_record_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+#endif /* MONGORY_MATCHER_ARRAY_RECORD_H */

data/ext/mongory_ext/mongory-core/src/matchers/base_matcher.c

@@ -0,0 +1,161 @@
+/**
+ * @file base_matcher.c
+ * @brief Implements the base matcher constructor and related utility functions.
+ * This is an internal implementation file for the matcher module.
+ */
+#include "base_matcher.h"
+#include "../foundations/string_buffer.h"
+#include <errno.h>        // For errno, ERANGE
+#include <limits.h>       // For INT_MIN, INT_MAX
+#include <mongory-core.h> // General include, for mongory_matcher types
+#include <stdbool.h>
+#include <stdio.h>  // For printf
+#include <stdlib.h> // For strtol
+#include "matcher_explainable.h"
+#include "matcher_traversable.h"
+
+/**
+ * @brief Allocates and initializes common fields of a `mongory_matcher`.
+ *
+ * This function serves as a common initializer for all specific matcher types.
+ * It allocates memory for the `mongory_matcher` structure itself from the
+ * provided `pool`, sets the `pool` and `condition` members.
+ * The `matcher->match` function pointer specific to the matcher type must be
+ * set by the caller. `original_match` and `trace` in the context are set to
+ * NULL.
+ *
+ * @param pool The memory pool to use for allocation. Must be non-NULL and
+ * valid.
+ * @param condition The condition value for this matcher.
+ * @return mongory_matcher* Pointer to the newly allocated and partially
+ * initialized matcher, or NULL if allocation fails.
+ */
+mongory_matcher *mongory_matcher_base_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!pool || !pool->alloc) {
+    return NULL; // Invalid memory pool.
+  }
+  mongory_matcher *matcher = MG_ALLOC_PTR(pool, mongory_matcher);
+  if (matcher == NULL) {
+    // Allocation failed, pool->alloc might set pool->error.
+    pool->error = &MONGORY_ALLOC_ERROR;
+    return NULL;
+  }
+
+  // Initialize common fields
+  matcher->original_match = NULL;
+  matcher->sub_count = 0;
+  matcher->pool = pool;
+  matcher->condition = condition;
+  matcher->name = NULL;                            // Name is not set by base_new.
+  matcher->match = NULL;                           // Specific match function must be set by derived type.
+  matcher->explain = mongory_matcher_base_explain; // Specific explain function must be set by derived type.
+  matcher->traverse = mongory_matcher_leaf_traverse;
+  matcher->extern_ctx = extern_ctx;                // Set the external context.
+  return matcher;
+}
+
+/**
+ * @brief The match function for a matcher that always returns true.
+ * @param matcher Unused.
+ * @param value Unused.
+ * @return Always true.
+ */
+static inline bool mongory_matcher_always_true_match(mongory_matcher *matcher, mongory_value *value) {
+  (void)matcher; // Mark as unused to prevent compiler warnings.
+  (void)value;   // Mark as unused.
+  return true;   // This matcher always indicates a match.
+}
+
+/**
+ * @brief Creates a matcher instance that will always evaluate to true.
+ * Useful as a placeholder or for default cases.
+ * @param pool Memory pool for allocation.
+ * @param condition Condition (typically ignored by this matcher).
+ * @return A new `mongory_matcher` or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_always_true_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->match = mongory_matcher_always_true_match;
+  matcher->original_match = mongory_matcher_always_true_match;
+  matcher->name = mongory_string_cpy(pool, "Always True");
+  matcher->explain = mongory_matcher_base_explain;
+  // Optionally set original_match as well if it's a strict policy
+  // matcher->context.original_match = mongory_matcher_always_true_match;
+  return matcher;
+}
+
+/**
+ * @brief The match function for a matcher that always returns false.
+ * @param matcher Unused.
+ * @param value Unused.
+ * @return Always false.
+ */
+static inline bool mongory_matcher_always_false_match(mongory_matcher *matcher, mongory_value *value) {
+  (void)matcher; // Mark as unused.
+  (void)value;   // Mark as unused.
+  return false;  // This matcher never indicates a match.
+}
+
+/**
+ * @brief Creates a matcher instance that will always evaluate to false.
+ * Useful for conditions that should never match.
+ * @param pool Memory pool for allocation.
+ * @param condition Condition (typically ignored by this matcher).
+ * @return A new `mongory_matcher` or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_always_false_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->match = mongory_matcher_always_false_match;
+  matcher->original_match = mongory_matcher_always_false_match;
+  matcher->name = mongory_string_cpy(pool, "Always False");
+  matcher->explain = mongory_matcher_base_explain;
+  // matcher->context.original_match = mongory_matcher_always_false_match;
+  return matcher;
+}
+
+/**
+ * @brief Attempts to parse a string `key` into an integer `out`.
+ *
+ * Uses `strtol` for conversion and checks for common parsing errors:
+ * - Input string is NULL or empty.
+ * - The string contains non-numeric characters after the number.
+ * - The parsed number is out of the range of `int` (`INT_MIN`, `INT_MAX`).
+ *
+ * @param key The null-terminated string to parse.
+ * @param out Pointer to an integer where the result is stored.
+ * @return `true` if parsing is successful and the value fits in an `int`.
+ *         `false` otherwise. `errno` may be set by `strtol`.
+ */
+bool mongory_try_parse_int(const char *key, int *out) {
+  if (key == NULL || *key == '\0') {
+    return false; // Invalid input string.
+  }
+  if (out == NULL) {
+    return false; // Output pointer must be valid.
+  }
+
+  char *endptr = NULL;
+  errno = 0;                           // Clear errno before calling strtol.
+  long val = strtol(key, &endptr, 10); // Base 10 conversion.
+
+  // Check for parsing errors reported by strtol.
+  if (endptr == key) {
+    return false; // No digits were found.
+  }
+  if (*endptr != '\0') {
+    return false; // Additional characters after the number.
+  }
+  if (errno == ERANGE || val < INT_MIN || val > INT_MAX) {
+    // Value out of range for int. ERANGE is set by strtol for overflow/underflow.
+    return false;
+  }
+
+  *out = (int)val; // Successfully parsed and within int range.
+  return true;
+}

data/ext/mongory_ext/mongory-core/src/matchers/base_matcher.h

@@ -0,0 +1,115 @@
+#ifndef MONGORY_MATCHER_BASE_H
+#define MONGORY_MATCHER_BASE_H
+
+/**
+ * @file base_matcher.h
+ * @brief Defines the base matcher constructor and utility functions for
+ * matchers. This is an internal header for the matcher module.
+ *
+ * This includes a constructor for the fundamental `mongory_matcher` structure,
+ * constructors for trivial matchers (always true/false), and a utility
+ * for parsing integers from strings.
+ */
+
+#include "mongory-core/foundations/array.h" // For mongory_array (context trace)
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include "mongory-core/matchers/matcher.h" // For mongory_matcher structure
+#include "matcher_explainable.h"
+#include "matcher_traversable.h"
+#include <stdbool.h>
+
+/**
+ * @brief Function pointer type for a matcher's core matching logic.
+ *
+ * @param matcher A pointer to the `mongory_matcher` instance itself.
+ * @param value A pointer to the `mongory_value` to be evaluated against the
+ * matcher's condition.
+ * @return bool True if the `value` matches the condition, false otherwise.
+ */
+typedef bool (*mongory_matcher_match_func)(mongory_matcher *matcher, mongory_value *value);
+
+/**
+ * @struct mongory_matcher
+ * @brief Represents a generic matcher in the Mongory system.
+ *
+ * Each matcher has a name (optional, for identification), a condition value
+ * that defines its criteria, a function pointer to its matching logic,
+ * a memory pool for its allocations, and a context.
+ */
+struct mongory_matcher {
+  char *name;                           /**< Optional name for the matcher (e.g., "$eq").
+                                           String is typically allocated from the pool. */
+  mongory_value *condition;             /**< The condition (a `mongory_value`) that this
+                                           matcher evaluates against. */
+  mongory_matcher_match_func match;     /**< Function pointer to the specific matching
+                                           logic for this matcher type. */
+  mongory_memory_pool *pool;            /**< The memory pool used for allocations related
+                                           to this matcher instance. */
+  mongory_matcher_explain_func explain; /**< Function pointer to the explanation
+                                          logic for this matcher type. */
+  mongory_matcher_match_func original_match; /**< Stores the original match function, potentially for
+                                                restoration or delegation. */
+  size_t sub_count;                          /**< The number of sub-matchers. */
+  mongory_matcher_traverse_func traverse;    /**< Function pointer to the traversal logic for this matcher type. */
+  mongory_array *trace_stack;                /**< The trace stack for this matcher. */
+  int trace_level;                           /**< The trace level for this matcher. */
+  void *extern_ctx;                          /**< External context for the matcher. */
+};
+
+/**
+ * @brief Creates a new base `mongory_matcher` instance and initializes its
+ * common fields.
+ *
+ * This function allocates a `mongory_matcher` structure from the provided pool
+ * and sets its `pool` and `condition` fields. The `match` function and other
+ * specific fields must be set by the caller or derived matcher constructors.
+ * The context's original_match and trace are initialized to NULL.
+ *
+ * @param pool The memory pool to use for allocating the matcher.
+ * @param condition The `mongory_value` representing the condition for this
+ * matcher.
+ * @return mongory_matcher* A pointer to the newly allocated base matcher, or
+ * NULL on allocation failure.
+ */
+mongory_matcher *mongory_matcher_base_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a new matcher that always evaluates to true.
+ *
+ * @param pool The memory pool for allocation.
+ * @param condition The condition value (often unused by this matcher but stored
+ * for consistency).
+ * @return mongory_matcher* A pointer to the "always true" matcher, or NULL on
+ * failure.
+ */
+mongory_matcher *mongory_matcher_always_true_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a new matcher that always evaluates to false.
+ *
+ * @param pool The memory pool for allocation.
+ * @param condition The condition value (often unused by this matcher but stored
+ * for consistency).
+ * @return mongory_matcher* A pointer to the "always false" matcher, or NULL on
+ * failure.
+ */
+mongory_matcher *mongory_matcher_always_false_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Attempts to parse an integer from a string.
+ *
+ * This utility function is useful for matchers that might operate on array
+ * indices or numeric string fields. It checks for valid integer formats and
+ * range (`INT_MIN`, `INT_MAX`).
+ *
+ * @param key The null-terminated string to parse. Must not be NULL or empty.
+ * @param out A pointer to an integer where the parsed value will be stored if
+ * successful. Must not be NULL.
+ * @return bool True if the string was successfully parsed as an integer and is
+ * within `int` range, false otherwise. `errno` might be set by `strtol` on
+ * failure (e.g. `ERANGE`).
+ */
+bool mongory_try_parse_int(const char *key, int *out);
+
+#endif /* MONGORY_MATCHER_BASE_H */