mongory 0.7.6 → 0.7.8

data/ext/mongory_ext/mongory-core/include/mongory-core/foundations/value.h

@@ -0,0 +1,175 @@
+#ifndef MONGORY_VALUE
+#define MONGORY_VALUE
+
+/**
+ * @file value.h
+ * @brief Defines the mongory_value structure, a generic value type for the
+ * Mongory library.
+ *
+ * `mongory_value` is a tagged union that can represent various data types such
+ * as null, boolean, integer, double, string, array, table, regex, pointers,
+ * and an unsupported type. It includes functions for wrapping C types into
+ * `mongory_value` objects, comparing values, and converting them to strings.
+ */
+
+#include "mongory-core/foundations/memory_pool.h"
+#include <stdbool.h>
+#include <stdint.h> // For int64_t
+
+// Forward declarations for complex types that can be stored in mongory_value.
+struct mongory_array;
+struct mongory_table;
+
+// Forward declaration of mongory_value itself and its type enum.
+struct mongory_value;
+/**
+ * @brief Alias for `struct mongory_value`.
+ */
+typedef struct mongory_value mongory_value;
+
+enum mongory_type;
+/**
+ * @brief Alias for `enum mongory_type`.
+ */
+typedef enum mongory_type mongory_type;
+
+/**
+ * @brief Function pointer type for comparing two mongory_value instances.
+ *
+ * @param a The first mongory_value.
+ * @param b The second mongory_value.
+ * @return int Returns:
+ *         - 0 if a is equal to b.
+ *         - A negative value if a is less than b.
+ *         - A positive value if a is greater than b.
+ *         - `mongory_value_compare_fail` (a specific constant) if the types
+ *           are incompatible for comparison or an error occurs.
+ */
+typedef int (*mongory_value_compare_func)(mongory_value *a, mongory_value *b);
+
+/**
+ * @brief Function pointer type for converting a mongory_value to a string representation.
+ * @param value The mongory_value to convert.
+ * @param pool The memory pool to allocate from.
+ * @return char* A string literal representing the value, or NULL if allocation
+ * fails. The string is a literal and should not be freed.
+ */
+typedef char *(*mongory_value_to_str_func)(mongory_value *value, mongory_memory_pool *pool);
+
+/**
+ * @brief Converts the type of a mongory_value to its string representation.
+ * @param value A pointer to the mongory_value.
+ * @return char* A string literal representing the type (e.g., "Int", "String").
+ * Returns "UnknownType" if the type is not recognized. This string is a
+ * literal and should not be freed.
+ */
+char *mongory_type_to_string(mongory_value *value);
+
+/**
+ * @brief Extracts a pointer to the raw data stored within a mongory_value.
+ * The type of the returned pointer depends on the `mongory_value`'s type.
+ * For example, for an MONGORY_TYPE_INT, it returns `int64_t*`.
+ * @param value A pointer to the mongory_value.
+ * @return void* A pointer to the internal data, or NULL if the type is unknown
+ * or has no direct data pointer (e.g. MONGORY_TYPE_NULL).
+ */
+void *mongory_value_extract(mongory_value *value);
+
+/** @name Mongory Value Wrapper Functions
+ *  Functions to create mongory_value instances from basic C types.
+ *  These functions allocate a new mongory_value from the provided pool.
+ *  @{
+ */
+mongory_value *mongory_value_wrap_n(mongory_memory_pool *pool, void *n);
+mongory_value *mongory_value_wrap_b(mongory_memory_pool *pool, bool b);
+mongory_value *mongory_value_wrap_i(mongory_memory_pool *pool, int64_t i);
+mongory_value *mongory_value_wrap_d(mongory_memory_pool *pool, double d);
+mongory_value *mongory_value_wrap_s(mongory_memory_pool *pool, char *s);
+mongory_value *mongory_value_wrap_a(mongory_memory_pool *pool, struct mongory_array *a);
+mongory_value *mongory_value_wrap_t(mongory_memory_pool *pool, struct mongory_table *t);
+mongory_value *mongory_value_wrap_regex(mongory_memory_pool *pool, void *regex);
+mongory_value *mongory_value_wrap_ptr(mongory_memory_pool *pool, void *ptr);
+mongory_value *mongory_value_wrap_u(mongory_memory_pool *pool, void *u);
+/** @} */
+
+/**
+ * @def MONGORY_TYPE_MACRO
+ * @brief X-Macro for defining mongory_type enum members and associated data.
+ * Simplifies the definition of types, their string names, and corresponding
+ * union fields.
+ * _(ENUM_NAME, UNIQUE_NUM_SUFFIX, "STRING_NAME", UNION_FIELD_NAME)
+ * Note: For MONGORY_TYPE_NULL, the 'i' field (int64_t) is arbitrarily used in
+ * the macro as the union needs a field, but it's not meaningful for null.
+ */
+#define MONGORY_TYPE_MACRO(_)                                                                                          \
+  _(MONGORY_TYPE_NULL, 0, "Null", i) /* Field 'i' is arbitrary for NULL */                                             \
+  _(MONGORY_TYPE_BOOL, 10, "Bool", b)                                                                                  \
+  _(MONGORY_TYPE_INT, 11, "Int", i)                                                                                    \
+  _(MONGORY_TYPE_DOUBLE, 12, "Double", d)                                                                              \
+  _(MONGORY_TYPE_STRING, 13, "String", s)                                                                              \
+  _(MONGORY_TYPE_ARRAY, 14, "Array", a)                                                                                \
+  _(MONGORY_TYPE_TABLE, 15, "Table", t)                                                                                \
+  _(MONGORY_TYPE_REGEX, 16, "Regex", regex)          /* Custom regex object pointer */                                 \
+  _(MONGORY_TYPE_POINTER, 17, "Pointer", ptr)        /* Generic void pointer */                                        \
+  _(MONGORY_TYPE_UNSUPPORTED, 999, "Unsupported", u) /* External/unknown type pointer */
+
+/**
+ * @def MONGORY_ENUM_MAGIC
+ * @brief A magic number used in generating enum values for mongory_type.
+ * Helps in creating somewhat unique integer values for the enums.
+ */
+#define MONGORY_ENUM_MAGIC 103
+
+/**
+ * @enum mongory_type
+ * @brief Enumerates the possible data types a mongory_value can hold.
+ * Values are generated using MONGORY_TYPE_MACRO and MONGORY_ENUM_MAGIC.
+ */
+enum mongory_type {
+#define DEFINE_ENUM(name, num, str, field) name = num * MONGORY_ENUM_MAGIC,
+  MONGORY_TYPE_MACRO(DEFINE_ENUM)
+#undef DEFINE_ENUM
+};
+
+/**
+ * @var mongory_value_compare_fail
+ * @brief Special return value from compare functions indicating comparison
+ * failure (e.g. incompatible types).
+ */
+static const int mongory_value_compare_fail = 97;
+
+/**
+ * @struct mongory_value
+ * @brief Represents a generic value in the Mongory system.
+ *
+ * It's a tagged union, where `type` indicates which field in the `data` union
+ * is active. Each value also carries a pointer to the `mongory_memory_pool`
+ * it was allocated from (or is associated with) and a `comp` function for
+ * comparisons. The `origin` field can be used to store a pointer to an
+ * original external data structure if the `mongory_value` is a bridge or
+ * wrapper.
+ */
+struct mongory_value {
+  mongory_memory_pool *pool;        /**< Memory pool associated with this value. */
+  mongory_type type;                /**< The type of data stored in the union. */
+  mongory_value_compare_func comp;  /**< Function to compare this value with
+                                       another. */
+  mongory_value_to_str_func to_str; /**< Function to convert this value to a
+                                      string representation. */
+  union {
+    bool b;                  /**< Boolean data. */
+    int64_t i;               /**< Integer data (64-bit). */
+    double d;                /**< Double-precision floating-point data. */
+    char *s;                 /**< String data (null-terminated). String memory
+                                is typically managed by the pool. */
+    struct mongory_array *a; /**< Pointer to a mongory_array. */
+    struct mongory_table *t; /**< Pointer to a mongory_table. */
+    void *regex;             /**< Pointer to a custom regex object/structure. */
+    void *ptr;               /**< Generic void pointer for other data. */
+    void *u;                 /**< Pointer for unsupported/external types. */
+  } data;                    /**< Union holding the actual data based on type. */
+  void *origin;              /**< Optional pointer to an original external value, useful for
+                                bridging with other data systems. */
+};
+
+#endif /* MONGORY_VALUE */

data/ext/mongory_ext/mongory-core/include/mongory-core/matchers/matcher.h

@@ -0,0 +1,76 @@
+#ifndef MONGORY_MATCHER_H
+#define MONGORY_MATCHER_H
+
+/**
+ * @file matcher.h
+ * @brief Defines the core mongory_matcher structure and related types.
+ *
+ * This file provides the basic structure for all matchers in the Mongory
+ * library. A matcher is responsible for determining if a given `mongory_value`
+ * meets certain criteria defined by a `condition`.
+ */
+
+#include "mongory-core/foundations/array.h" // For mongory_array (used in context)
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+
+// Forward declaration for the main matcher structure.
+typedef struct mongory_matcher mongory_matcher;
+/**
+ * @brief Creates a new generic matcher instance.
+ *
+ * This function typically serves as a high-level entry point for creating
+ * matchers. In the current implementation, it delegates to
+ * `mongory_matcher_table_cond_new`, implying that conditions are often
+ * table-based (similar to query documents).
+ *
+ * @param pool The memory pool to use for the matcher's allocations.
+ * @param condition A `mongory_value` representing the condition for this
+ * matcher.
+ * @return mongory_matcher* A pointer to the newly created matcher, or NULL on
+ * failure.
+ */
+mongory_matcher *mongory_matcher_new(mongory_memory_pool *pool, mongory_value *condition, void *extern_ctx);
+
+/**
+ * @brief Matches a value against a matcher.
+ * @param matcher The matcher to match against.
+ * @param value The value to match.
+ * @return True if the value matches the matcher, false otherwise.
+ */
+bool mongory_matcher_match(mongory_matcher *matcher, mongory_value *value);
+
+/**
+ * @brief Explains a matcher.
+ * @param matcher The matcher to explain.
+ * @param temp_pool The temporary pool to use for the explanation.
+ */
+void mongory_matcher_explain(mongory_matcher *matcher, mongory_memory_pool *temp_pool);
+
+/**
+ * @brief Traces a matcher.
+ * @param matcher The matcher to trace.
+ * @param value The value to trace.
+ */
+bool mongory_matcher_trace(mongory_matcher *matcher, mongory_value *value);
+
+/**
+ * @brief Prints the trace of a matcher.
+ * @param matcher The matcher to print the trace of.
+ */
+void mongory_matcher_print_trace(mongory_matcher *matcher);
+
+/**
+ * @brief Enables the trace of a matcher.
+ * @param matcher The matcher to enable the trace of.
+ * @param temp_pool The temporary pool to use for the trace.
+ */
+void mongory_matcher_enable_trace(mongory_matcher *matcher, mongory_memory_pool *temp_pool);
+
+/**
+ * @brief Disables the trace of a matcher.
+ * @param matcher The matcher to disable the trace of.
+ */
+void mongory_matcher_disable_trace(mongory_matcher *matcher);
+
+#endif /* MONGORY_MATCHER_H */

data/ext/mongory_ext/mongory-core/include/mongory-core.h

@@ -0,0 +1,12 @@
+#ifndef MONGORY_CORE_H
+#define MONGORY_CORE_H
+
+#include "mongory-core/foundations/array.h"
+#include "mongory-core/foundations/config.h"
+#include "mongory-core/foundations/error.h"
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/table.h"
+#include "mongory-core/foundations/value.h"
+#include "mongory-core/matchers/matcher.h"
+
+#endif

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