mongory 0.6.3 → 0.7.0

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

@@ -0,0 +1,334 @@
+/**
+ * @file literal_matcher.c
+ * @brief Implements literal matchers, field matchers, $not, and $size.
+ * This is an internal implementation file for the matcher module.
+ *
+ * - "Literal" matching often involves comparing a value directly or using a
+ *   simple condition (like equality).
+ * - Field matchers extract a value from a table/array by field name/index and
+ *   apply a condition to it.
+ * - $not inverts the result of a condition.
+ * - $size checks the number of elements in an array against a condition.
+ */
+#include "literal_matcher.h"
+#include "../foundations/config_private.h"  // For mongory_internal_value_converter, mongory_string_cpy
+#include "../foundations/string_buffer.h"   // For mongory_string_buffer_appendf
+#include "array_record_matcher.h"           // For handling array-specific matching logic
+#include "base_matcher.h"                   // For mongory_try_parse_int, mongory_matcher_base_new
+#include "compare_matcher.h"                // For mongory_matcher_equal_new
+#include "composite_matcher.h"              // For mongory_matcher_composite_new, mongory_matcher_table_cond_new
+#include "existance_matcher.h"              // For mongory_matcher_exists_new (used by null_new)
+#include "matcher_explainable.h"
+#include "matcher_traversable.h"
+#include "mongory-core/foundations/array.h" // For mongory_array access
+#include "mongory-core/foundations/table.h" // For mongory_table access
+#include "mongory-core/foundations/value.h" // For mongory_value types and wrappers
+#include "external_matcher.h"               // For mongory_matcher_regex_new
+#include <mongory-core.h>                   // General include
+#include <stdio.h>                          // For printf
+
+/**
+ * @brief Core matching logic for literal-based conditions.
+ *
+ * This function is used by field matchers, $not, and $size.
+ * It checks the type of the input `value`.
+ * - If `value` is an array, it may delegate to an `array_record_matcher`
+ *   (via `composite->right`, if initialized). This path seems intended for
+ *   more complex array matching scenarios where the condition itself might
+ *   describe how array elements should be matched.
+ * - Otherwise (if `value` is not an array, or if array-specific handling is
+ *   not triggered), it uses the `composite->left` matcher. `composite->left`
+ *   is typically set up by `mongory_matcher_literal_delegate` to handle the
+ *   specific type of the literal condition (e.g., equality for simple values,
+ *   regex matcher for regex conditions, table condition matcher for table
+ *   conditions).
+ *
+ * @param matcher The `mongory_matcher` (expected to be a
+ * `mongory_composite_matcher` where `left` and possibly `right` are set up).
+ * @param value The `mongory_value` to evaluate against the matcher's condition.
+ * @return True if the value matches, false otherwise.
+ */
+static inline bool mongory_matcher_literal_match(mongory_matcher *matcher, mongory_value *value) {
+  mongory_literal_matcher *literal = (mongory_literal_matcher *)matcher;
+  if (!literal || !literal->base.pool)
+    return false; // Basic safety check
+
+  if (value != NULL && value->type == MONGORY_TYPE_ARRAY) {
+    // If the value being matched is an array, there's special handling.
+    // The `right` child of the composite matcher is used for array record matching.
+    // It's created on-demand if not already present.
+    if (literal->array_record_matcher == NULL) {
+      // Lazily create the array_record_matcher if needed.
+      // The condition for array_record_new is the original condition of the literal matcher.
+      literal->array_record_matcher = mongory_matcher_array_record_new(literal->base.pool, literal->base.condition, literal->base.extern_ctx);
+    }
+    // If right child exists (or was successfully created), use it.
+    return literal->array_record_matcher ? literal->array_record_matcher->match(literal->array_record_matcher, value) : false;
+  } else {
+    // For non-array values, or if array-specific path wasn't taken.
+    // The `left` child handles the general literal condition.
+    return literal->delegate_matcher ? literal->delegate_matcher->match(literal->delegate_matcher, value) : false;
+  }
+}
+
+/**
+ * @brief Internal helper to create a specialized matcher for a `MONGORY_TYPE_NULL`
+ * condition.
+ *
+ * This creates an OR condition:
+ * (`value` IS MONGORY_TYPE_NULL) OR (`value` DOES NOT EXIST (evaluates to
+ * false for $exists:true)). This means it matches actual BSON nulls or missing
+ * fields.
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition The `mongory_value` which is of `MONGORY_TYPE_NULL`.
+ * @return A composite matcher for the NULL condition, or NULL on failure.
+ */
+static inline mongory_matcher *mongory_matcher_null_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  mongory_composite_matcher *composite = mongory_matcher_composite_new(pool, condition, extern_ctx);
+  if (!composite)
+    return NULL;
+
+  mongory_array *sub_matchers = mongory_array_new(pool);
+  if (!sub_matchers)
+    return NULL;
+
+  // Left branch: checks for actual MONGORY_TYPE_NULL
+  mongory_value *null_val = mongory_value_wrap_n(pool, NULL);
+  if (!null_val)
+    return NULL; // Failed to wrap null value
+  sub_matchers->push(sub_matchers, (mongory_value *)mongory_matcher_equal_new(pool, null_val, extern_ctx));
+
+  // Right branch: checks if the field does not exist (value is NULL from get)
+  // $exists: false
+  mongory_value *exists_false_cond = mongory_value_wrap_b(pool, false);
+  if (!exists_false_cond)
+    return NULL; // Failed to wrap bool
+  sub_matchers->push(sub_matchers, (mongory_value *)mongory_matcher_exists_new(pool, exists_false_cond, extern_ctx));
+
+  composite->children = sub_matchers;
+  composite->base.match = mongory_matcher_or_match; // OR logic
+  composite->base.original_match = mongory_matcher_or_match;
+  composite->base.sub_count = 1;
+  composite->base.name = mongory_string_cpy(pool, "Or");
+  // composite->base.condition is already set by mongory_matcher_composite_new
+  return (mongory_matcher *)composite;
+}
+
+/**
+ * @brief Delegates creation of a simple literal matcher based on the
+ * `condition`'s type.
+ *
+ * - Table condition: creates a `mongory_matcher_table_cond_new`.
+ * - Regex condition: creates a `mongory_matcher_regex_new`.
+ * - Null condition: creates a specialized `mongory_matcher_null_new`.
+ * - Other types: creates an equality matcher (`mongory_matcher_equal_new`).
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition The literal value or condition table.
+ * @return The appropriate simple matcher for the condition, or NULL on failure.
+ */
+static inline mongory_matcher *mongory_matcher_literal_delegate(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  if (!condition)
+    return mongory_matcher_equal_new(pool, NULL, extern_ctx); // Or specific null matcher
+
+  switch (condition->type) {
+  case MONGORY_TYPE_TABLE:
+    return mongory_matcher_table_cond_new(pool, condition, extern_ctx);
+  case MONGORY_TYPE_REGEX:
+    return mongory_matcher_regex_new(pool, condition, extern_ctx);
+  case MONGORY_TYPE_NULL:
+    // When the condition is explicitly `null`, e.g. `{ field: null }`
+    return mongory_matcher_null_new(pool, condition, extern_ctx);
+  default:
+    // For boolean, int, double, string, array (equality), pointer, unsupported.
+    return mongory_matcher_equal_new(pool, condition, extern_ctx);
+  }
+}
+
+/**
+ * @brief Match function for a field matcher.
+ *
+ * Extracts the value of `field_matcher->field` from the input `value`
+ * (table or array). Then, applies the literal matching logic
+ * (`mongory_matcher_literal_match`) using the sub-matcher stored in
+ * `composite.left` (which was set up by `literal_delegate` based on the
+ * original condition for this field).
+ *
+ * @param matcher Pointer to the `mongory_matcher` (a `mongory_field_matcher`).
+ * @param value The input table or array to extract the field from.
+ * @return True if the field's value matches the condition, false otherwise.
+ */
+static inline bool mongory_matcher_field_match(mongory_matcher *matcher, mongory_value *value) {
+  if (value == NULL) { // Cannot extract field from NULL.
+    return false;
+  }
+  mongory_field_matcher *field_matcher = (mongory_field_matcher *)matcher;
+  if (!field_matcher->field)
+    return false; // No field specified.
+
+  mongory_value *field_value = NULL;
+  char *field_key = field_matcher->field;
+
+  if (value->type == MONGORY_TYPE_TABLE) {
+    if (value->data.t) {
+      field_value = value->data.t->get(value->data.t, field_key);
+    }
+  } else if (value->type == MONGORY_TYPE_ARRAY) {
+    if (value->data.a) {
+      int index;
+      if (!mongory_try_parse_int(field_key, &index))
+        return false; // Field key is not a valid integer index for an array.
+      if (index < 0) { // Handle negative indexing (from end of array)
+        if ((size_t)(-index) > value->data.a->count)
+          return false; // Out of bounds
+        index = value->data.a->count + index;
+      }
+      if ((size_t)index >= value->data.a->count)
+        return false; // Out of bounds
+      field_value = value->data.a->get(value->data.a, (size_t)index);
+    }
+  } else {
+    return false; // Can only extract fields from tables or arrays.
+  }
+
+  // If the extracted field value is a pointer type that needs conversion
+  // (e.g., from a language binding), convert it.
+  if (field_value && field_value->type == MONGORY_TYPE_POINTER && mongory_internal_value_converter &&
+      mongory_internal_value_converter->shallow_convert) {
+    // The pool for the converted value should ideally be the field_value's pool
+    // or the matcher's pool.
+    mongory_memory_pool *conversion_pool = field_value->pool ? field_value->pool : matcher->pool;
+    field_value = mongory_internal_value_converter->shallow_convert(conversion_pool, field_value->data.ptr);
+  }
+  // Now, use the literal_match logic (which uses composite.left primarily)
+  // to match the extracted field_value.
+  return mongory_matcher_literal_match(matcher, field_value);
+}
+
+mongory_matcher *mongory_matcher_field_new(mongory_memory_pool *pool, char *field_name,
+                                           mongory_value *condition_for_field, void *extern_ctx) {
+  mongory_field_matcher *field_m = MG_ALLOC_PTR(pool, mongory_field_matcher);
+  if (field_m == NULL) {
+    pool->error = &MONGORY_ALLOC_ERROR;
+    return NULL;
+  }
+  field_m->field = mongory_string_cpy(pool, field_name);
+  if (field_m->field == NULL) {
+    // pool->free(field_m) is not standard; pool manages its own memory.
+    // This indicates an error in string copy, likely pool allocation.
+    return NULL;
+  }
+
+  // Initialize the base composite matcher part
+  field_m->literal.base.pool = pool;
+  field_m->literal.base.name = NULL; // Can be set if needed, e.g. to field_name
+  field_m->literal.base.match = mongory_matcher_field_match;
+  field_m->literal.base.original_match = mongory_matcher_field_match;
+  field_m->literal.base.sub_count = 1;
+  field_m->literal.base.condition = condition_for_field; // Original condition for the field
+  field_m->literal.base.name = mongory_string_cpy(pool, "Field");
+  field_m->literal.base.explain = mongory_matcher_field_explain;
+  field_m->literal.base.traverse = mongory_matcher_literal_traverse;
+  // The 'left' child of the composite is the actual matcher for the field's value,
+  // determined by the type of 'condition_for_field'.
+  field_m->literal.delegate_matcher = mongory_matcher_literal_delegate(pool, condition_for_field, extern_ctx);
+  field_m->literal.array_record_matcher = NULL; // Not typically used by field_match directly,
+                                                // but literal_match might use it for arrays.
+
+  if (field_m->literal.delegate_matcher == NULL) {
+    // Failed to create the delegate matcher for the condition.
+    return NULL;
+  }
+
+  return (mongory_matcher *)field_m;
+}
+
+/**
+ * @brief Match function for a NOT matcher.
+ * Negates the result of `mongory_matcher_literal_match`.
+ * @param matcher The $not matcher.
+ * @param value The value to evaluate.
+ * @return True if the literal match is false, false if it's true.
+ */
+static inline bool mongory_matcher_not_match(mongory_matcher *matcher, mongory_value *value) {
+  // literal_match uses composite.left (and sometimes .right for arrays)
+  return !mongory_matcher_literal_match(matcher, value);
+}
+
+mongory_matcher *mongory_matcher_not_new(mongory_memory_pool *pool, mongory_value *condition_to_negate, void *extern_ctx) {
+  mongory_literal_matcher *literal = MG_ALLOC_PTR(pool, mongory_literal_matcher);
+  if (!literal)
+    return NULL;
+
+  // The 'left' child is the matcher for the condition being negated.
+  literal->delegate_matcher = mongory_matcher_literal_delegate(pool, condition_to_negate, extern_ctx);
+  if (!literal->delegate_matcher) {
+    return NULL; // Failed to create delegate for the condition.
+  }
+  literal->array_record_matcher = NULL;
+  // composite->right remains NULL for $not, as literal_match's array path
+  // via composite->right will use condition_to_negate if right is NULL.
+
+  literal->base.pool = pool;
+  literal->base.condition = condition_to_negate;
+  literal->base.match = mongory_matcher_not_match;
+  literal->base.original_match = mongory_matcher_not_match;
+  literal->base.name = mongory_string_cpy(pool, "Not");
+  literal->base.explain = mongory_matcher_literal_explain;
+  literal->base.traverse = mongory_matcher_literal_traverse;
+  literal->base.sub_count = 1;
+  literal->base.extern_ctx = extern_ctx;
+  return (mongory_matcher *)literal;
+}
+
+/**
+ * @brief Match function for a $size matcher.
+ * Checks if the input `value` (must be an array) has a size that matches
+ * the condition associated with the $size matcher.
+ * @param matcher The $size matcher.
+ * @param value The value to evaluate (must be an array).
+ * @return True if array size matches condition, false otherwise.
+ */
+static inline bool mongory_matcher_size_match(mongory_matcher *matcher, mongory_value *value) {
+  if (!value || value->type != MONGORY_TYPE_ARRAY || !value->data.a) {
+    return false; // $size only applies to valid arrays.
+  }
+  mongory_array *array = value->data.a;
+  // Wrap the array's count as a mongory_value (integer) to be matched.
+  // The pool for this temporary size value should be from the input value or matcher.
+
+  // Use literal_match with the matcher's original condition against the size_value.
+  // The $size matcher's `composite.left` was set up by literal_delegate
+  // based on the condition provided to $size (e.g., if {$size: 5}, left is an
+  // equality matcher for 5).
+  return mongory_matcher_literal_match(matcher, mongory_value_wrap_i(value->pool, (int)array->count));
+}
+
+mongory_matcher *mongory_matcher_size_new(mongory_memory_pool *pool, mongory_value *size_condition, void *extern_ctx) {
+  mongory_literal_matcher *literal = MG_ALLOC_PTR(pool, mongory_literal_matcher);
+  if (!literal)
+    return NULL;
+
+  // The 'left' child is the matcher for the size_condition itself.
+  // E.g., if {$size: {$gt: 5}}, size_condition is {$gt: 5}, and
+  // composite.left becomes a "greater than 5" matcher.
+  literal->delegate_matcher = mongory_matcher_literal_delegate(pool, size_condition, extern_ctx);
+  if (!literal->delegate_matcher) {
+    return NULL;
+  }
+  literal->array_record_matcher = NULL;
+  // composite->right typically NULL for $size, array path of literal_match not primary.
+
+  literal->base.pool = pool;
+  literal->base.condition = size_condition;
+  literal->base.match = mongory_matcher_size_match;
+  literal->base.original_match = mongory_matcher_size_match;
+  literal->base.name = mongory_string_cpy(pool, "Size");
+  literal->base.explain = mongory_matcher_literal_explain;
+  literal->base.traverse = mongory_matcher_literal_traverse;
+  literal->base.sub_count = 1;
+  literal->base.extern_ctx = extern_ctx;
+  return (mongory_matcher *)literal;
+}
+

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

@@ -0,0 +1,97 @@
+#ifndef MONGORY_MATCHER_LITERAL_H
+#define MONGORY_MATCHER_LITERAL_H
+
+/**
+ * @file literal_matcher.h
+ * @brief Defines constructors for literal-based matchers, field matchers,
+ * $not, and $size. This is an internal header for the matcher module.
+ *
+ * "Literal" here often refers to matching a field's value against a specific
+ * condition, which might itself be a simple value or a more complex condition
+ * table.
+ */
+
+#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 "matcher_explainable.h"
+#include "composite_matcher.h"
+
+typedef struct mongory_literal_matcher {
+  mongory_matcher base;
+  mongory_matcher *delegate_matcher;
+  mongory_matcher *array_record_matcher;
+} mongory_literal_matcher;
+
+/**
+ * @struct mongory_field_matcher
+ * @brief Specialized composite matcher for matching a specific field.
+ * Stores the field name/index.
+ */
+typedef struct mongory_field_matcher {
+  mongory_literal_matcher literal; /**< Base composite matcher structure. */
+  char *field;                         /**< Name/index of the field to match. Copied string. */
+} mongory_field_matcher;
+/**
+ * @brief Creates a "field" matcher.
+ *
+ * This matcher extracts a value from a specified `field` (or array index) of
+ * an input `mongory_value` (which is expected to be a table or array). It then
+ * applies a sub-matcher (derived from `condition`) to this extracted field
+ * value.
+ *
+ * @param pool Memory pool for allocation.
+ * @param field The name of the field (if input is a table) or string
+ * representation of an index (if input is an array). A copy of this string is
+ * made.
+ * @param condition The `mongory_value` condition to apply to the field's value.
+ * This condition is processed by `mongory_matcher_literal_delegate` to determine
+ * the actual sub-matcher (e.g., equality, regex, nested table condition).
+ * @return A new field matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_field_new(mongory_memory_pool *pool, char *field, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "NOT" ($not) matcher.
+ *
+ * This matcher negates the result of a sub-matcher derived from `condition`.
+ * The sub-matcher is typically determined by
+ * `mongory_matcher_literal_delegate`.
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition The `mongory_value` condition whose result will be negated.
+ * @return A new $not matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_not_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "size" ($size) matcher.
+ *
+ * This matcher checks if the size (count of elements) of an input array
+ * matches the given `condition`. The `condition` itself is processed by
+ * `mongory_matcher_literal_delegate` (e.g., it could be a number for exact
+ * size, or a condition table like {$gt: 5}).
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition The `mongory_value` condition to apply to the array's size.
+ * @return A new $size matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_size_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Creates a "literal" matcher (deprecated or internal use).
+ *
+ * This function seems to be a more generic entry point that delegates to
+ * `mongory_matcher_literal_delegate` and potentially `array_record_matcher`.
+ * Its direct public use might be limited compared to `field_new` or specific
+ * operator matchers. It appears to be part of the internal logic for how field
+ * values are matched.
+ *
+ * @param pool Memory pool for allocation.
+ * @param condition The literal `mongory_value` or condition table.
+ * @return A new literal matcher, or NULL on failure.
+ */
+mongory_matcher *mongory_matcher_literal_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+#endif /* MONGORY_MATCHER_LITERAL_H */

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

@@ -0,0 +1,196 @@
+/**
+ * @file matcher.c
+ * @brief Implements the generic mongory_matcher constructor.
+ *
+ * This file provides the implementation for the top-level matcher creation
+ * function.
+ */
+#include <stdio.h>
+#include <string.h>
+#include "mongory-core/matchers/matcher.h" // Public API
+
+// Required internal headers for delegation
+#include "../foundations/config_private.h" // Potentially for global settings
+#include "base_matcher.h"                  // For mongory_matcher_base_new if used directly
+#include "composite_matcher.h"             // For mongory_matcher_table_cond_new
+#include "literal_matcher.h"               // Potentially for other default constructions
+#include "mongory-core/foundations/array.h"
+#include "../foundations/string_buffer.h"
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include <mongory-core.h> // General include, might not be strictly necessary here
+
+
+/**
+ * @brief Creates a new matcher based on the provided condition.
+ *
+ * This is the primary public entry point for creating a matcher. The library
+ * uses a factory pattern where this function determines the appropriate
+ * specific matcher to create based on the structure of the `condition` value.
+ *
+ * Currently, it always delegates to `mongory_matcher_table_cond_new`,
+ * which handles query documents (tables). This is the most common use case,
+ * where the condition is a table like `{ "field": { "$op": "value" } }`.
+ *
+ * @param pool The memory pool to be used for allocating the matcher.
+ * @param condition A `mongory_value` defining the matching criteria. This is
+ *                  typically a `mongory_table`.
+ * @return mongory_matcher* A pointer to the newly constructed matcher, or NULL
+ * if allocation fails or the condition is invalid.
+ */
+mongory_matcher *mongory_matcher_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx) {
+  // The core logic is delegated to a more specific constructor.
+  // This design allows for easy extension; for example, a different constructor
+  // could be chosen here based on the `condition->type`.
+  mongory_matcher *matcher = mongory_matcher_table_cond_new(pool, condition, extern_ctx);
+  if (matcher == NULL) {
+    return NULL;
+  }
+
+  return matcher;
+}
+
+/**
+ * @brief Executes the matching logic for the given matcher.
+ *
+ * This function is a polymorphic wrapper. It invokes the `match` function
+ * pointer on the specific `mongory_matcher` instance, which will be one of
+ * the internal matching functions (e.g., from a compare_matcher or
+ * composite_matcher).
+ *
+ * @param matcher The matcher to use.
+ * @param value The value to check against the matcher's condition.
+ * @return True if the value satisfies the matcher's condition, false otherwise.
+ */
+bool mongory_matcher_match(mongory_matcher *matcher, mongory_value *value) { return matcher->match(matcher, value); }
+
+/**
+ * @brief Generates a human-readable explanation of the matcher's criteria.
+ *
+ * This function is a polymorphic wrapper around the `explain` function pointer,
+ * allowing different matcher types to provide their own specific explanations.
+ *
+ * @param matcher The matcher to explain.
+ * @param temp_pool A temporary memory pool for allocating the explanation string(s).
+ */
+void mongory_matcher_explain(mongory_matcher *matcher, mongory_memory_pool *temp_pool) {
+  mongory_matcher_explain_context ctx = {
+      .pool = temp_pool,
+      .count = 0,
+      .total = 0,
+      .prefix = "",
+  };
+  matcher->explain(matcher, &ctx);
+}
+
+typedef struct mongory_matcher_traced_match_context {
+  char *message;
+  int level;
+} mongory_matcher_traced_match_context;
+
+static bool mongory_matcher_traced_match(mongory_matcher *matcher, mongory_value *value) {
+  bool matched = matcher->original_match(matcher, value);
+  mongory_memory_pool *pool = matcher->trace_stack->pool;
+
+  char *res = matched ? "\e[30;42mMatched\e[0m" : "\e[30;41mDismatch\e[0m";
+  char *cdtn = matcher->condition->to_str(matcher->condition, pool);
+  char *rcd = value == NULL ? "Nothing" : value->to_str(value, pool);
+  char *name = matcher->name;
+  char *message;
+
+  if (strcmp(name, "Field") == 0) {
+    mongory_field_matcher *field_matcher = (mongory_field_matcher *)matcher;
+    char *fd = field_matcher->field;
+    message = mongory_string_cpyf(pool, "%s: %s, field: \"%s\", condition: %s, record: %s\n", name, res, fd, cdtn, rcd);
+  } else {
+    message = mongory_string_cpyf(pool, "%s: %s, condition: %s, record: %s\n", name, res, cdtn, rcd);
+  }
+
+  mongory_matcher_traced_match_context *trace_result = MG_ALLOC_PTR(pool, mongory_matcher_traced_match_context);
+  trace_result->message = message;
+  trace_result->level = matcher->trace_level;
+  matcher->trace_stack->push(matcher->trace_stack, mongory_value_wrap_ptr(pool, (void *)trace_result));
+
+  return matched;
+}
+
+static bool mongory_matcher_enable_trace_cb(mongory_matcher *matcher, mongory_matcher_traverse_context *ctx) {
+  matcher->trace_stack = (mongory_array *)ctx->acc;
+  matcher->trace_level = ctx->level;
+  matcher->match = mongory_matcher_traced_match;
+  return true;
+}
+
+static bool mongory_matcher_disable_trace_cb(mongory_matcher *matcher, mongory_matcher_traverse_context *ctx) {
+  (void)ctx;
+  matcher->match = matcher->original_match;
+  matcher->trace_stack = NULL;
+  return true;
+}
+
+static mongory_array *mongory_matcher_traces_sort(mongory_array *self, int level) {
+  mongory_array *sorted_array = mongory_array_new(self->pool);
+  mongory_array *group = mongory_array_new(self->pool);
+  int total = (int)self->count;
+  for (int i = 0; i < total; i++) {
+    mongory_value *item = self->get(self, i);
+    mongory_matcher_traced_match_context *trace = (mongory_matcher_traced_match_context *)item->data.ptr;
+    if (trace->level == level) {
+      sorted_array->push(sorted_array, item);
+      mongory_array *sorted_group = mongory_matcher_traces_sort(group, level + 1);
+      int sorted_group_total = (int)sorted_group->count;
+      for (int j = 0; j < sorted_group_total; j++) {
+        sorted_array->push(sorted_array, sorted_group->get(sorted_group, j));
+      }
+      group = mongory_array_new(self->pool);
+    } else {
+      group->push(group, item);
+    }
+  }
+  return sorted_array;
+}
+
+void mongory_matcher_enable_trace(mongory_matcher *matcher, mongory_memory_pool *temp_pool) {
+  mongory_array *trace_stack = mongory_array_new(temp_pool);
+  mongory_matcher_traverse_context ctx = {
+      .pool = temp_pool,
+      .level = 0,
+      .count = 0,
+      .total = 0,
+      .acc = (void *)trace_stack,
+      .callback = mongory_matcher_enable_trace_cb,
+  };
+  matcher->traverse(matcher, &ctx);
+}
+
+void mongory_matcher_disable_trace(mongory_matcher *matcher) {
+  mongory_matcher_traverse_context ctx = {
+      .level = 0,
+      .count = 0,
+      .total = 0,
+      .callback = mongory_matcher_disable_trace_cb,
+  };
+  matcher->traverse(matcher, &ctx);
+}
+
+void mongory_matcher_print_trace(mongory_matcher *matcher) {
+  mongory_array *sorted_trace_stack = mongory_matcher_traces_sort(matcher->trace_stack, 0);
+  int total = (int)sorted_trace_stack->count;
+  for (int i = 0; i < total; i++) {
+    mongory_value *item = sorted_trace_stack->get(sorted_trace_stack, i);
+    mongory_matcher_traced_match_context *trace = (mongory_matcher_traced_match_context *)item->data.ptr;
+    int indent_size = trace->level * 2;
+    char *indent = MG_ALLOC(sorted_trace_stack->pool, indent_size + 1);
+    memset(indent, ' ', indent_size);
+    indent[indent_size] = '\0';
+    printf("%s%s", indent, trace->message);
+  }
+}
+
+bool mongory_matcher_trace(mongory_matcher *matcher, mongory_value *value) {
+  mongory_matcher_enable_trace(matcher, value->pool);
+  bool matched = matcher->match(matcher, value);
+  mongory_matcher_print_trace(matcher);
+  mongory_matcher_disable_trace(matcher);
+  return matched;
+}