mongory 0.7.2-x86_64-linux

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

@@ -0,0 +1,164 @@
+/**
+ * @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"
+#include "../foundations/utils.h"          // For mongory_try_parse_int
+#include "base_matcher.h"                  // For mongory_matcher_base_new
+#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 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_merge(table_for_elem_match_conditions, value->data.t);
+  } 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->data.t || !condition->pool) {
+    mongory_error *error = MG_ALLOC_PTR(condition->pool, mongory_error);
+    if (!error) {
+      condition->pool->error = &MONGORY_ALLOC_ERROR;
+      return NULL;
+    }
+    error->type = MONGORY_ERROR_INVALID_TYPE;
+    error->message = "Expected condition to be a table, got a non-table value";
+    condition->pool->error = error; // TODO: This is a hack, we should use a better error handling mechanism
+    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 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 (!condition)
+    return NULL;
+  switch (condition->type) {
+  case MONGORY_TYPE_TABLE:
+    return mongory_matcher_table_cond_new(pool,
+      mongory_matcher_array_record_parse_table(condition),
+      extern_ctx
+    );
+  case MONGORY_TYPE_ARRAY:
+    return mongory_matcher_or_new(pool, MG_ARRAY_WRAP(pool, 2,
+      MG_TABLE_WRAP(pool, 1, "$eq", condition),
+      MG_TABLE_WRAP(pool, 1, "$elemMatch",
+        MG_TABLE_WRAP(pool, 1, "$eq", condition)
+      )
+    ), extern_ctx);
+  case MONGORY_TYPE_REGEX:
+    return mongory_matcher_elem_match_new(pool, MG_TABLE_WRAP(pool, 1, "$regex", condition), extern_ctx);
+  default: // Literals (string, int, bool, etc.)
+    return mongory_matcher_elem_match_new(pool, MG_TABLE_WRAP(pool, 1, "$eq", condition), extern_ctx);
+  }
+}

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,122 @@
+/**
+ * @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"
+#include "../foundations/utils.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.
+  matcher->priority = 1.0;                         // Set the priority to 1.0.
+  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;
+}

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

@@ -0,0 +1,100 @@
+#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_traverse_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. */
+  double priority;                           /**< The priority 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);
+
+#endif /* MONGORY_MATCHER_BASE_H */

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

@@ -0,0 +1,217 @@
+/**
+ * @file compare_matcher.c
+ * @brief Implements comparison matchers like `$eq`, `$gt`, `$lt`, etc.
+ *
+ * This file follows a factory pattern. A generic private constructor,
+ * `mongory_matcher_compare_new`, is used to create a base matcher.
+ * Each specific comparison operator (e.g., `$eq`, `$gt`) has its own public
+ * constructor (e.g., `mongory_matcher_equal_new`) that provides a specialized
+ * matching function to the generic constructor.
+ */
+#include "compare_matcher.h"
+#include "base_matcher.h" // For mongory_matcher_base_new
+#include <mongory-core.h> // For mongory_value, mongory_matcher types
+#include "../foundations/utils.h"
+
+/**
+ * @brief Generic constructor for comparison matchers.
+ *
+ * Initializes a base matcher and sets its `match` function and
+ * `original_match` context field to the provided `match_func`.
+ *
+ * @param pool The memory pool for allocation.
+ * @param condition The `mongory_value` to be stored as the comparison target.
+ * @param match_func The specific comparison logic function (e.g., for equality,
+ * greater than).
+ * @return mongory_matcher* A pointer to the newly created comparison matcher,
+ * or NULL on failure.
+ */
+static inline mongory_matcher *mongory_matcher_compare_new(mongory_memory_pool *pool, mongory_value *condition,
+                                                           mongory_matcher_match_func match_func, void *extern_ctx) {
+  mongory_matcher *matcher = mongory_matcher_base_new(pool, condition, extern_ctx);
+  if (matcher == NULL) {
+    return NULL; // Base matcher allocation failed.
+  }
+  matcher->match = match_func;
+  matcher->original_match = match_func; // Store original match function
+  return matcher;
+}
+
+// ============================================================================
+// Static Match Functions
+//
+// These functions contain the actual logic for each comparison operator.
+// They all follow the `mongory_matcher_match_func` signature and are passed
+// to the generic constructor.
+// ============================================================================
+
+/**
+ * @brief Match function for equality ($eq).
+ *
+ * Compares the input `value` with the matcher's `condition` using the
+ * polymorphic `comp` function of the value.
+ *
+ * @param matcher The equality matcher instance.
+ * @param value The value to check.
+ * @return True if `value` is equal to `matcher->condition`; false otherwise or
+ * if the types are not comparable.
+ */
+static inline bool mongory_matcher_equal_match(mongory_matcher *matcher, mongory_value *value) {
+  if (!value || !value->comp || !matcher->condition)
+    return false; // Invalid inputs
+  int result = value->comp(value, matcher->condition);
+  if (result == mongory_value_compare_fail) {
+    return false; // Types are not comparable or other comparison error.
+  }
+  return result == 0; // 0 indicates equality.
+}
+
+mongory_matcher *mongory_matcher_equal_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  mongory_matcher *matcher = mongory_matcher_compare_new(pool, condition, mongory_matcher_equal_match, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->name = mongory_string_cpy(pool, "Eq");
+  matcher->priority = 1.0;
+  return matcher;
+}
+
+/**
+ * @brief Match function for inequality ($ne).
+ *
+ * This is the logical inverse of the `equal_match` function.
+ * If the types are not comparable (comparison fails), it is considered "not
+ * equal", so this function returns true in that case.
+ *
+ * @param matcher The inequality matcher instance.
+ * @param value The value to check.
+ * @return True if `value` is not equal to `matcher->condition` or if they
+ * are not comparable.
+ */
+static inline bool mongory_matcher_not_equal_match(mongory_matcher *matcher, mongory_value *value) {
+  if (!value || !value->comp || !matcher->condition)
+    return true; // Invalid inputs, treat as "not equal"
+  int result = value->comp(value, matcher->condition);
+  if (result == mongory_value_compare_fail) {
+    return true; // Incomparable types are considered "not equal".
+  }
+  return result != 0; // Non-zero indicates inequality.
+}
+
+mongory_matcher *mongory_matcher_not_equal_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  mongory_matcher *matcher = mongory_matcher_compare_new(pool, condition, mongory_matcher_not_equal_match, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->name = mongory_string_cpy(pool, "Ne");
+  matcher->priority = 1.0;
+  return matcher;
+}
+
+/**
+ * @brief Match function for "greater than" ($gt).
+ * @param matcher The $gt matcher instance.
+ * @param value The value to check.
+ * @return True if `value` is greater than `matcher->condition`, false
+ * otherwise or on comparison failure.
+ */
+static inline bool mongory_matcher_greater_than_match(mongory_matcher *matcher, mongory_value *value) {
+  if (!value || !value->comp || !matcher->condition)
+    return false;
+  int result = value->comp(value, matcher->condition);
+  if (result == mongory_value_compare_fail) {
+    return false;
+  }
+  return result == 1; // 1 indicates value > condition.
+}
+
+mongory_matcher *mongory_matcher_greater_than_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  mongory_matcher *matcher = mongory_matcher_compare_new(pool, condition, mongory_matcher_greater_than_match, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->name = mongory_string_cpy(pool, "Gt");
+  matcher->priority = 2.0;
+  return matcher;
+}
+
+/**
+ * @brief Match function for "less than" ($lt).
+ * @param matcher The $lt matcher instance.
+ * @param value The value to check.
+ * @return True if `value` is less than `matcher->condition`, false otherwise or
+ * on comparison failure.
+ */
+static inline bool mongory_matcher_less_than_match(mongory_matcher *matcher, mongory_value *value) {
+  if (!value || !value->comp || !matcher->condition)
+    return false;
+  int result = value->comp(value, matcher->condition);
+  if (result == mongory_value_compare_fail) {
+    return false;
+  }
+  return result == -1; // -1 indicates value < condition.
+}
+
+mongory_matcher *mongory_matcher_less_than_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  mongory_matcher *matcher = mongory_matcher_compare_new(pool, condition, mongory_matcher_less_than_match, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->name = mongory_string_cpy(pool, "Lt");
+  matcher->priority = 2.0;
+  return matcher;
+}
+
+/**
+ * @brief Match function for "greater than or equal" ($gte).
+ * @param matcher The $gte matcher instance.
+ * @param value The value to check.
+ * @return True if `value` is >= `matcher->condition`, false otherwise or on
+ * comparison failure.
+ */
+static inline bool mongory_matcher_greater_than_or_equal_match(mongory_matcher *matcher, mongory_value *value) {
+  if (!value || !value->comp || !matcher->condition)
+    return false;
+  int result = value->comp(value, matcher->condition);
+  if (result == mongory_value_compare_fail) {
+    return false;
+  }
+  return result >= 0; // 0 or 1 indicates value >= condition.
+}
+
+mongory_matcher *mongory_matcher_greater_than_or_equal_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  mongory_matcher *matcher = mongory_matcher_compare_new(pool, condition, mongory_matcher_greater_than_or_equal_match, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->name = mongory_string_cpy(pool, "Gte");
+  matcher->priority = 2.0;
+  return matcher;
+}
+
+/**
+ * @brief Match function for "less than or equal" ($lte).
+ * @param matcher The $lte matcher instance.
+ * @param value The value to check.
+ * @return True if `value` is <= `matcher->condition`, false otherwise or on
+ * comparison failure.
+ */
+static inline bool mongory_matcher_less_than_or_equal_match(mongory_matcher *matcher, mongory_value *value) {
+  if (!value || !value->comp || !matcher->condition)
+    return false;
+  int result = value->comp(value, matcher->condition);
+  if (result == mongory_value_compare_fail) {
+    return false;
+  }
+  return result <= 0; // 0 or -1 indicates value <= condition.
+}
+
+mongory_matcher *mongory_matcher_less_than_or_equal_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  mongory_matcher *matcher = mongory_matcher_compare_new(pool, condition, mongory_matcher_less_than_or_equal_match, extern_ctx);
+  if (!matcher) {
+    return NULL;
+  }
+  matcher->name = mongory_string_cpy(pool, "Lte");
+  matcher->priority = 2.0;
+  return matcher;
+}