mongory 0.7.6 → 0.7.7

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;
+}

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

@@ -0,0 +1,83 @@
+#ifndef MONGORY_MATCHER_COMPARE_H
+#define MONGORY_MATCHER_COMPARE_H
+
+/**
+ * @file compare_matcher.h
+ * @brief Defines constructors for comparison matchers (e.g., equality, greater
+ * than). This is an internal header for the matcher module.
+ *
+ * These matchers compare an input `mongory_value` against a `condition` value
+ * stored within the matcher, using the `comp` function of the input value.
+ */
+
+#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
+#include <stdbool.h>
+
+/** @name Comparison Matcher Constructors
+ *  Functions to create instances of various comparison matchers.
+ *  Each takes a memory pool and a condition value.
+ * @{
+ */
+
+/**
+ * @brief Creates an "equal" ($eq) matcher.
+ * Matches if the input value is equal to the matcher's condition value.
+ * @param pool Memory pool for allocation.
+ * @param condition The `mongory_value` to compare against.
+ * @return A new `$eq` matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_equal_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "not equal" ($ne) matcher.
+ * Matches if the input value is not equal to the matcher's condition value.
+ * Also matches if the types are incompatible for comparison.
+ * @param pool Memory pool for allocation.
+ * @param condition The `mongory_value` to compare against.
+ * @return A new `$ne` matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_not_equal_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "greater than" ($gt) matcher.
+ * Matches if the input value is greater than the matcher's condition value.
+ * @param pool Memory pool for allocation.
+ * @param condition The `mongory_value` to compare against.
+ * @return A new `$gt` matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_greater_than_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "less than" ($lt) matcher.
+ * Matches if the input value is less than the matcher's condition value.
+ * @param pool Memory pool for allocation.
+ * @param condition The `mongory_value` to compare against.
+ * @return A new `$lt` matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_less_than_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "greater than or equal" ($gte) matcher.
+ * Matches if the input value is greater than or equal to the matcher's
+ * condition value.
+ * @param pool Memory pool for allocation.
+ * @param condition The `mongory_value` to compare against.
+ * @return A new `$gte` matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_greater_than_or_equal_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "less than or equal" ($lte) matcher.
+ * Matches if the input value is less than or equal to the matcher's condition
+ * value.
+ * @param pool Memory pool for allocation.
+ * @param condition The `mongory_value` to compare against.
+ * @return A new `$lte` matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_less_than_or_equal_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+/** @} */
+
+#endif /* MONGORY_MATCHER_COMPARE_H */