mongory 0.7.2-arm64-darwin-23

data/ext/mongory_ext/mongory-core/src/foundations/array.c

@@ -0,0 +1,287 @@
+/**
+ * @file array.c
+ * @brief Implements the mongory_array dynamic array.
+ *
+ * This file contains the internal implementation details for the mongory_array,
+ * including memory management, resizing, and the core array operations.
+ * It uses a private structure `mongory_array_private` which extends
+ * `mongory_array` with capacity information and the actual item storage.
+ */
+
+#include <string.h>
+#include "array_private.h"
+#include <mongory-core/foundations/array.h>
+#include <mongory-core/foundations/memory_pool.h>
+#include <stdarg.h>
+#include <mongory-core/foundations/value.h>
+
+/**
+ * @def MONGORY_ARRAY_INIT_SIZE
+ * @brief Initial capacity of a newly created mongory_array.
+ */
+#define MONGORY_ARRAY_INIT_SIZE 4
+
+/**
+ * @brief Resizes the internal storage of the array.
+ *
+ * Allocates a new block of memory for items and copies existing items to it.
+ * The old item storage is not explicitly freed here as it's managed by the
+ * memory pool; this function assumes the new allocation replaces the old one
+ * in terms of where `internal->items` points.
+ *
+ * @param self Pointer to the mongory_array instance.
+ * @param size The new capacity (number of elements) for the array.
+ * @return true if resizing was successful, false otherwise (e.g., memory
+ * allocation failure).
+ */
+bool mongory_array_resize(mongory_array *self, size_t size) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+
+  // Allocate a new, larger block of memory for the items.
+  mongory_value **new_items = MG_ALLOC_ARY(self->pool, mongory_value*, size);
+  if (!new_items) {
+    self->pool->error = &MONGORY_ALLOC_ERROR;
+    return false;
+  }
+
+  // Copy existing item pointers to the new memory block.
+  memcpy(new_items, internal->items, sizeof(mongory_value *) * self->count);
+
+  internal->items = new_items;
+  internal->capacity = size;
+  return true;
+}
+
+/**
+ * @brief Ensures the array has enough capacity for a given size, growing it if
+ * necessary.
+ *
+ * If the required size is smaller than the current capacity, this function does
+ * nothing. Otherwise, it calculates a new capacity (typically double the
+ * current, or more if needed to fit `size`) and calls mongory_array_resize.
+ *
+ * @param self Pointer to the mongory_array instance.
+ * @param size The minimum number of elements the array needs to accommodate.
+ * @return true if the array has sufficient capacity (or was successfully
+ * grown), false otherwise.
+ */
+// ============================================================================
+// Static Helper Functions
+// ============================================================================
+static inline bool mongory_array_grow_if_needed(mongory_array *self, size_t size) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+  if (size < internal->capacity) {
+    return true;
+  }
+
+  // Calculate new capacity, typically doubling, until it's sufficient.
+  size_t new_capacity = internal->capacity * 2;
+  while (new_capacity <= size) {
+    new_capacity *= 2;
+  }
+
+  return mongory_array_resize(self, new_capacity);
+}
+
+/**
+ * @brief Internal implementation for iterating over array elements.
+ * @param self Pointer to the mongory_array instance.
+ * @param acc Accumulator/context passed to the callback.
+ * @param func Callback function executed for each item.
+ * @return true if iteration completed, false if callback stopped it.
+ */
+static inline bool mongory_array_each(mongory_array *self, void *acc, mongory_array_callback_func func) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+  for (size_t i = 0; i < self->count; i++) {
+    mongory_value *item = internal->items[i];
+    if (!func(item, acc)) {
+      return false; // Callback requested to stop iteration.
+    }
+  }
+  return true;
+}
+
+/**
+ * @brief Internal implementation for adding an element to the end of the array.
+ * Grows the array if necessary.
+ * @param self Pointer to the mongory_array instance.
+ * @param value The mongory_value to add.
+ * @return true if successful, false on failure (e.g., memory allocation).
+ */
+static inline bool mongory_array_push(mongory_array *self, mongory_value *value) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+  // Ensure there's space for one more element (current count).
+  if (!mongory_array_grow_if_needed(self, self->count)) {
+    return false;
+  }
+
+  internal->items[self->count++] = value;
+  return true;
+}
+
+/**
+ * @brief Internal implementation for retrieving an element by index.
+ * @param self Pointer to the mongory_array instance.
+ * @param index The index of the element.
+ * @return Pointer to the mongory_value, or NULL if index is out of bounds.
+ */
+static inline mongory_value *mongory_array_get(mongory_array *self, size_t index) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+  if (index >= self->count) {
+    return NULL; // Index out of bounds.
+  }
+  return internal->items[index];
+}
+
+/**
+ * @brief Internal implementation for setting an element at a specific index.
+ *
+ * Grows the array if necessary. If the index is beyond the current count,
+ * intermediate elements are set to NULL, and the array's count is updated.
+ *
+ * @param self Pointer to the mongory_array instance.
+ * @param index The index at which to set the value.
+ * @param value The mongory_value to set.
+ * @return true if successful, false on failure (e.g., memory allocation).
+ */
+static inline bool mongory_array_set(mongory_array *self, size_t index, mongory_value *value) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+  // Ensure capacity for the given index (index + 1 elements).
+  if (!mongory_array_grow_if_needed(self, index + 1)) {
+    return false;
+  }
+
+  // If setting beyond the current count, fill intermediate spots with NULL.
+  if (index >= self->count) {
+    for (size_t i = self->count; i < index; i++) {
+      internal->items[i] = NULL;
+    }
+    self->count = index + 1; // Update count to include the new element.
+  }
+
+  internal->items[index] = value;
+  return true;
+}
+
+/**
+ * @brief Creates and initializes a new mongory_array.
+ *
+ * Allocates memory for the array structure itself and its initial item storage
+ * using the provided memory pool. Assigns function pointers for array
+ * operations.
+ *
+ * @param pool The memory pool to use for allocations.
+ * @return Pointer to the new mongory_array, or NULL on allocation failure.
+ */
+mongory_array *mongory_array_new(mongory_memory_pool *pool) {
+  // First, allocate the private structure that holds all array metadata.
+  mongory_array_private *internal = MG_ALLOC_PTR(pool, mongory_array_private);
+  if (!internal) {
+    pool->error = &MONGORY_ALLOC_ERROR;
+    return NULL;
+  }
+
+  // Then, allocate the initial block of memory for the array items.
+  mongory_value **items = MG_ALLOC_ARY(pool, mongory_value*, MONGORY_ARRAY_INIT_SIZE);
+  if (!items) {
+    // If this fails, the 'internal' struct allocated above will be cleaned up
+    // by the pool, assuming it's a tracing pool.
+    pool->error = &MONGORY_ALLOC_ERROR;
+    return NULL;
+  }
+
+  // Initialize the public part of the array structure.
+  internal->base.pool = pool;
+  internal->base.count = 0;
+  internal->base.each = mongory_array_each;
+  internal->base.get = mongory_array_get;
+  internal->base.push = mongory_array_push;
+  internal->base.set = mongory_array_set;
+
+  // Initialize the private part of the array structure.
+  internal->items = items;
+  internal->capacity = MONGORY_ARRAY_INIT_SIZE;
+
+  return &internal->base; // Return pointer to the public structure.
+}
+
+/**
+ * @brief Creates a new mongory_array instance with a nested array.
+ *
+ * This function is used to create a new mongory_array instance with a nested
+ * array. The nested array is created with the given memory pool and the given
+ * values. The nested array is returned as a pointer to the mongory_array structure.
+ *
+ * @param pool A pointer to the mongory_memory_pool to be used for allocations.
+ * @param argc The number of values to be set.
+ * @param ... The values to be set.
+ * @return mongory_array* A pointer to the newly created mongory_array, or NULL
+ * if creation fails (e.g., memory allocation failure).
+ */
+mongory_array *mongory_array_nested_wrap(mongory_memory_pool *pool, int argc, ...) {
+  mongory_array *array = mongory_array_new(pool);
+  if (!array) {
+    return NULL;
+  }
+  va_list args;
+  va_start(args, argc);
+  for (int i = 0; i < argc; i++) {
+    mongory_value *value = va_arg(args, mongory_value *);
+    array->push(array, value);
+  }
+  va_end(args);
+  return array;
+}
+
+typedef size_t(*mongory_array_sort_cb)(mongory_value *value, void *ctx);
+
+static mongory_value** mongory_array_merge_sort_finalize(mongory_memory_pool *pool, mongory_value **left, mongory_value **right, size_t count, void *ctx, mongory_array_sort_cb callback) {
+  mongory_value **result = MG_ALLOC_ARY(pool, mongory_value*, count);
+  size_t i = 0, j = 0, k = 0;
+  while (i < count / 2 && j < count - count / 2) {
+    if (callback(left[i], ctx) < callback(right[j], ctx)) {
+      result[k++] = left[i++];
+    } else {
+      result[k++] = right[j++];
+    }
+  }
+  while (i < count / 2) {
+    result[k++] = left[i++];
+  }
+  while (j < count - count / 2) {
+    result[k++] = right[j++];
+  }
+  return result;
+}
+
+static mongory_value** mongory_array_merge_sort(mongory_memory_pool *pool, mongory_value **origin_items, size_t count, void *ctx, mongory_array_sort_cb callback) {
+  if (count <= 1) {
+    return origin_items;
+  }
+  size_t mid = count / 2;
+  mongory_value **left = mongory_array_merge_sort(pool, origin_items, mid, ctx, callback);
+  mongory_value **right = mongory_array_merge_sort(pool, origin_items + mid, count - mid, ctx, callback);
+  return mongory_array_merge_sort_finalize(pool, left, right, count, ctx, callback);
+}
+
+mongory_array *mongory_array_sort_by(mongory_array *self, mongory_memory_pool *temp_pool, void *ctx, mongory_array_sort_cb callback) {
+  mongory_array_private *internal = (mongory_array_private *)self;
+
+  mongory_value **new_items = mongory_array_merge_sort(temp_pool, internal->items, self->count, ctx, callback);
+  mongory_array_private *new_array = (mongory_array_private *)mongory_array_new(self->pool);
+  new_array->capacity = internal->capacity;
+  new_array->base.count = self->count;
+  new_array->items = MG_ALLOC_ARY(self->pool, mongory_value*, new_array->capacity);
+  memcpy(new_array->items, new_items, sizeof(mongory_value *) * self->count);
+  return &new_array->base;
+}
+
+bool mongory_array_includes(mongory_array *self, mongory_value *value) {
+  for (size_t i = 0; i < self->count; i++) {
+    mongory_value *item = self->get(self, i);
+    if (item->comp(item, value) == 0) {
+      return true;
+    }
+  }
+  return false;
+}

data/ext/mongory_ext/mongory-core/src/foundations/array_private.h

@@ -0,0 +1,19 @@
+#ifndef MONGORY_ARRAY_PRIVATE_H
+#define MONGORY_ARRAY_PRIVATE_H
+#include "mongory-core/foundations/array.h"
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include <stdbool.h>
+
+bool mongory_array_resize(mongory_array *self, size_t size); // resize array
+
+typedef struct mongory_array_private {
+  mongory_array base;    // public array
+  mongory_value **items; // items pointer
+  size_t capacity;       // capacity
+} mongory_array_private;
+
+mongory_array *mongory_array_sort_by(mongory_array *self, mongory_memory_pool *temp_pool, void *ctx, size_t(*callback)(mongory_value *value, void *ctx));
+bool mongory_array_includes(mongory_array *self, mongory_value *value);
+
+#endif // MONGORY_ARRAY_PRIVATE_H

data/ext/mongory_ext/mongory-core/src/foundations/config.c

@@ -0,0 +1,270 @@
+/**
+ * @file config.c
+ * @brief Implements global configuration and initialization for the Mongory
+ * library.
+ *
+ * This file manages the lifecycle of global resources such as the internal
+ * memory pool, regex adapter, matcher registration table, and value converters.
+ * It provides the `mongory_init` and `mongory_cleanup` functions, as well as
+ * setters for customizable components and a string copy utility.
+ */
+#include "mongory-core/foundations/config.h"
+#include "../matchers/base_matcher.h"      // For mongory_matcher_build_func
+#include "../matchers/compare_matcher.h"   // For specific matcher constructors
+#include "../matchers/composite_matcher.h" // For specific matcher constructors
+#include "../matchers/existance_matcher.h" // For specific matcher constructors
+#include "../matchers/inclusion_matcher.h" // For specific matcher constructors
+#include "../matchers/literal_matcher.h"   // For specific matcher constructors
+#include "../matchers/external_matcher.h"     // For specific matcher constructors
+#include "config_private.h"                // For mongory_regex_adapter, mongory_value_converter, etc.
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/table.h"
+#include "mongory-core/foundations/value.h"
+
+static bool mongory_regex_default_func(mongory_memory_pool *pool, mongory_value *pattern, mongory_value *value);
+static char *mongory_regex_default_stringify_func(mongory_memory_pool *pool, mongory_value *pattern);
+
+// Global internal memory pool for the library.
+mongory_memory_pool *mongory_internal_pool = NULL;
+// Global adapter for regex operations.
+mongory_regex_adapter mongory_internal_regex_adapter = {
+  .match_func = mongory_regex_default_func,
+  .stringify_func = mongory_regex_default_stringify_func,
+};
+// Global table mapping matcher names (e.g., "$eq") to their build functions.
+mongory_table *mongory_matcher_mapping = NULL;
+// Global converter for handling external data types.
+mongory_value_converter mongory_internal_value_converter = {
+  .deep_convert = NULL,
+  .shallow_convert = NULL,
+  .recover = NULL,
+};
+// Global adapter for custom matchers.
+mongory_matcher_custom_adapter mongory_custom_matcher_adapter = {
+  .build = NULL,
+  .lookup = NULL,
+  .match = NULL,
+};
+
+bool mongory_matcher_trace_result_colorful = true;
+
+/**
+ * @brief Initializes the internal memory pool if it hasn't been already.
+ * This pool is used for allocations by various library components.
+ */
+static inline void mongory_internal_pool_init() {
+  if (mongory_internal_pool != NULL) {
+    return; // Already initialized.
+  }
+  mongory_internal_pool = mongory_memory_pool_new();
+  // TODO: Add error handling if mongory_memory_pool_new returns NULL.
+}
+
+/**
+ * @brief Default regex function that always returns false.
+ * Used if no custom regex function is set via mongory_regex_func_set.
+ * @param pool Unused.
+ * @param pattern Unused.
+ * @param value Unused.
+ * @return Always false.
+ */
+static bool mongory_regex_default_func(mongory_memory_pool *pool, mongory_value *pattern, mongory_value *value) {
+  (void)pool;    // Mark as unused to prevent compiler warnings.
+  (void)pattern; // Mark as unused.
+  (void)value;   // Mark as unused.
+  return false;  // Default behavior is no match.
+}
+
+static char *mongory_regex_default_stringify_func(mongory_memory_pool *pool, mongory_value *pattern) {
+  (void)pool;    // Mark as unused to prevent compiler warnings.
+  (void)pattern; // Mark as unused.
+  return "//";   // Default behavior is no stringification.
+}
+
+/**
+ * @brief Sets the global regex matching function.
+ * Initializes the regex adapter if it's not already.
+ * @param func The custom regex function to use.
+ */
+void mongory_regex_func_set(mongory_regex_func func) {
+  mongory_internal_regex_adapter.match_func = func;
+}
+
+/**
+ * @brief Sets the global regex stringify function.
+ * Initializes the regex adapter if it's not already.
+ * @param func The custom regex stringify function to use.
+ */
+void mongory_regex_stringify_func_set(mongory_regex_stringify_func func) {
+  mongory_internal_regex_adapter.stringify_func = func;
+}
+/**
+ * @brief Initializes the matcher mapping table if it hasn't been already.
+ * This table stores registrations of matcher names to their constructor
+ * functions.
+ */
+static inline void mongory_matcher_mapping_init() {
+  if (mongory_matcher_mapping != NULL) {
+    return; // Already initialized.
+  }
+
+  // Ensure the internal pool is initialized first.
+  mongory_internal_pool_init();
+  if (mongory_internal_pool == NULL) {
+    return; // Cannot proceed if pool initialization failed.
+  }
+
+  mongory_matcher_mapping = mongory_table_new(mongory_internal_pool);
+  if (mongory_matcher_mapping == NULL) {
+    // TODO: Set error state.
+    return;
+  }
+}
+
+/**
+ * @brief Registers a matcher build function with a given name.
+ * The build function is stored in the global matcher mapping table.
+ * @param name The name of the matcher (e.g., "$eq", "$in").
+ * @param build_func A function pointer to the matcher's constructor.
+ */
+void mongory_matcher_register(char *name, mongory_matcher_build_func build_func) {
+  // Ensure mapping is initialized.
+  if (mongory_matcher_mapping == NULL) {
+    mongory_matcher_mapping_init();
+    if (mongory_matcher_mapping == NULL) {
+      // TODO: Set error: Cannot register if mapping init failed.
+      return;
+    }
+  }
+
+  // Wrap the function pointer in a mongory_value to store in the table.
+  mongory_value *value = mongory_value_wrap_ptr(mongory_internal_pool, build_func);
+  if (value == NULL) {
+    // TODO: Set error: Failed to wrap pointer.
+    return;
+  }
+
+  mongory_matcher_mapping->set(mongory_matcher_mapping, name, value);
+  // TODO: Check return value of set?
+}
+
+/**
+ * @brief Retrieves a matcher build function by its name from the global
+ * mapping.
+ * @param name The name of the matcher to retrieve.
+ * @return mongory_matcher_build_func A function pointer to the matcher's
+ * constructor, or NULL if not found.
+ */
+mongory_matcher_build_func mongory_matcher_build_func_get(char *name) {
+  if (mongory_matcher_mapping == NULL) {
+    return NULL; // Mapping not initialized or init failed.
+  }
+
+  mongory_value *value = mongory_matcher_mapping->get(mongory_matcher_mapping, name);
+  if (value == NULL || value->type != MONGORY_TYPE_POINTER) {
+    return NULL; // Not found or not a pointer type as expected.
+  }
+
+  return (mongory_matcher_build_func)value->data.ptr;
+}
+
+/**
+ * @brief Sets the function for deep conversion of external values.
+ * Initializes the value converter if necessary.
+ * @param deep_convert The deep conversion function.
+ */
+void mongory_value_converter_deep_convert_set(mongory_deep_convert_func deep_convert) {
+  mongory_internal_value_converter.deep_convert = deep_convert;
+}
+
+/**
+ * @brief Sets the function for shallow conversion of external values.
+ * Initializes the value converter if necessary.
+ * @param shallow_convert The shallow conversion function.
+ */
+void mongory_value_converter_shallow_convert_set(mongory_shallow_convert_func shallow_convert) {
+  mongory_internal_value_converter.shallow_convert = shallow_convert;
+}
+
+/**
+ * @brief Sets the function for recovering external values from mongory_value.
+ * Initializes the value converter if necessary.
+ * @param recover The recovery function.
+ */
+void mongory_value_converter_recover_set(mongory_recover_func recover) {
+  mongory_internal_value_converter.recover = recover;
+}
+
+
+void mongory_custom_matcher_match_func_set(bool (*match)(void *external_matcher, mongory_value *value)) {
+  mongory_custom_matcher_adapter.match = match;
+}
+
+void mongory_custom_matcher_build_func_set(mongory_matcher_custom_context *(*build)(char *key, mongory_value *condition, void *extern_ctx)) {
+  mongory_custom_matcher_adapter.build = build;
+}
+
+void mongory_custom_matcher_lookup_func_set(bool (*lookup)(char *key)) {
+  mongory_custom_matcher_adapter.lookup = lookup;
+}
+
+void mongory_matcher_trace_result_colorful_set(bool colorful) {
+  mongory_matcher_trace_result_colorful = colorful;
+}
+
+/**
+ * @brief Initializes all core Mongory library components.
+ * This includes the internal memory pool, regex adapter, matcher mapping table,
+ * and value converter. It then registers all standard matcher types.
+ * This function MUST be called before using most other library features.
+ */
+void mongory_init() {
+  // Initialize all global components. Order can be important if one init
+  // depends on another (e.g., most depend on the pool).
+  mongory_internal_pool_init();
+  mongory_matcher_mapping_init();
+
+  // Register all standard matchers.
+  // Note: These registrations rely on mongory_internal_pool and
+  // mongory_matcher_mapping being successfully initialized.
+  // TODO: Add checks to ensure initializations were successful before
+  // proceeding.
+  mongory_matcher_register("$in", mongory_matcher_in_new);
+  mongory_matcher_register("$nin", mongory_matcher_not_in_new);
+  mongory_matcher_register("$eq", mongory_matcher_equal_new);
+  mongory_matcher_register("$ne", mongory_matcher_not_equal_new);
+  mongory_matcher_register("$gt", mongory_matcher_greater_than_new);
+  mongory_matcher_register("$gte", mongory_matcher_greater_than_or_equal_new);
+  mongory_matcher_register("$lt", mongory_matcher_less_than_new);
+  mongory_matcher_register("$lte", mongory_matcher_less_than_or_equal_new);
+  mongory_matcher_register("$exists", mongory_matcher_exists_new);
+  mongory_matcher_register("$present", mongory_matcher_present_new);
+  mongory_matcher_register("$regex", mongory_matcher_regex_new);
+  mongory_matcher_register("$and", mongory_matcher_and_new);
+  mongory_matcher_register("$or", mongory_matcher_or_new);
+  mongory_matcher_register("$elemMatch", mongory_matcher_elem_match_new);
+  mongory_matcher_register("$every", mongory_matcher_every_new);
+  mongory_matcher_register("$not", mongory_matcher_not_new);
+  mongory_matcher_register("$size", mongory_matcher_size_new);
+}
+
+/**
+ * @brief Cleans up all resources allocated by the Mongory library.
+ * This primarily involves freeing the internal memory pool, which should, in
+ * turn, release all memory allocated from it. It also resets global pointers
+ * to NULL. This should be called when the library is no longer needed to
+ * prevent memory leaks.
+ */
+void mongory_cleanup() {
+  if (mongory_internal_pool != NULL) {
+    // Freeing the pool should handle all allocations made from it,
+    // including the regex_adapter, matcher_mapping table (and its contents if
+    // they were allocated from this pool), and value_converter.
+    mongory_internal_pool->free(mongory_internal_pool);
+    mongory_internal_pool = NULL;
+  }
+
+  // Set other global pointers to NULL to indicate they are no longer valid.
+  // The memory they pointed to should have been managed by the internal pool.
+  mongory_matcher_mapping = NULL; // The table itself and its nodes.
+}

data/ext/mongory_ext/mongory-core/src/foundations/config_private.h

@@ -0,0 +1,48 @@
+#ifndef MONGORY_FOUNDATIONS_CONFIG_PRIVATE_H
+#define MONGORY_FOUNDATIONS_CONFIG_PRIVATE_H
+#include "../matchers/base_matcher.h"
+#include "mongory-core/foundations/config.h"
+#include "mongory-core/foundations/table.h"
+#include "mongory-core/matchers/matcher.h"
+
+typedef struct mongory_regex_adapter {
+  mongory_regex_func match_func;
+  mongory_regex_stringify_func stringify_func;
+} mongory_regex_adapter;
+
+typedef struct mongory_value_converter {
+  mongory_deep_convert_func deep_convert;
+  mongory_shallow_convert_func shallow_convert;
+  mongory_recover_func recover;
+} mongory_value_converter;
+
+/**
+ * @brief Function pointer type for matching a value against an external matcher.
+ *
+ * This function is called when a value needs to be matched against an external
+ * matcher.
+ *
+ * @param external_matcher The external reference to the matcher.
+ * @param value The value to match against.
+ * @return bool True if the value matches the matcher, false otherwise.
+ */
+typedef struct mongory_matcher_custom_adapter {
+  bool (*match)(void *external_matcher, mongory_value *value); // Match a value against an external matcher.
+  mongory_matcher_custom_context *(*build)(char *key, mongory_value *condition, void *extern_ctx); // Build an external matcher reference.
+  bool (*lookup)(char *key); // Lookup a matcher reference by key.
+} mongory_matcher_custom_adapter;
+
+extern mongory_memory_pool *mongory_internal_pool;
+extern mongory_regex_adapter mongory_internal_regex_adapter;
+extern mongory_table *mongory_matcher_mapping;
+extern mongory_value_converter mongory_internal_value_converter;
+extern mongory_matcher_custom_adapter mongory_custom_matcher_adapter;
+extern bool mongory_matcher_trace_result_colorful;
+
+typedef mongory_matcher *(*mongory_matcher_build_func)(mongory_memory_pool *pool,
+                                                       mongory_value *condition,
+                                                       void *extern_ctx); // build function
+void mongory_matcher_register(char *name, mongory_matcher_build_func build_func);
+mongory_matcher_build_func mongory_matcher_build_func_get(char *name);
+
+#endif

data/ext/mongory_ext/mongory-core/src/foundations/error.c

@@ -0,0 +1,38 @@
+#ifndef MONGORY_ERROR_C
+#define MONGORY_ERROR_C
+/**
+ * @file error.c
+ * @brief Implements error type to string conversion for the Mongory library.
+ */
+#include <mongory-core/foundations/error.h>
+
+/**
+ * @brief Converts a mongory_error_type enum to its human-readable string
+ * representation.
+ *
+ * This function uses the MONGORY_ERROR_TYPE_MACRO to generate a switch
+ * statement that maps each error enum to its corresponding string.
+ *
+ * @param type The mongory_error_type enum value to convert.
+ * @return const char* A string literal representing the error type. If the
+ * type is not recognized, it returns "Unknown Error Type".
+ */
+const char *mongory_error_type_to_string(enum mongory_error_type type) {
+  switch (type) {
+// Use the X-Macro to generate case statements for each error type.
+#define DEFINE_ERROR_STRING(name, num, str)                                                                            \
+  case name:                                                                                                           \
+    return str;
+    MONGORY_ERROR_TYPE_MACRO(DEFINE_ERROR_STRING)
+#undef DEFINE_ERROR_STRING // Undefine the macro after use.
+  default:
+    // Fallback for any undefined or unknown error types.
+    return "Unknown Error Type";
+  }
+}
+
+mongory_error MONGORY_ALLOC_ERROR = {
+  .type = MONGORY_ERROR_MEMORY,
+  .message = "Memory Allocation Failed",
+};
+#endif