mongory 0.7.6 → 0.7.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e866b7fdded31e87ff8a44eb76c6bf7f2f592b18b4eb8a0e2fb7dd9e81549b6
-  data.tar.gz: e3113b959720dc718885ade589ef05ec1acb7f05186373b5a667552532a33399
+  metadata.gz: 69f848ea0c1b1b71ad0ab165fb63ae29fcea07538f1ad04321df692fce003720
+  data.tar.gz: f92879ac8385d752b4b07881219bb45c73d4aad7b52c91bf52d75c94f085a400
 SHA512:
-  metadata.gz: 44bcad683fd980c72e3feda8617f5c281e86b94fd519671d9dc5be67b1e9d05cc1abe5635bcd229061dfe35aa963d3ef716cf751437edeeea93ef87990258988
-  data.tar.gz: 7957b3825577c1dcee98c1de067bcc3340a0e3525a20209a4dd3bdb5128b090c354ba6c78c18eaeb7d204e2b4bc6c70d1d41a9c44b09e0b95ebc843db34bf6c9
+  metadata.gz: 40dcf855a25c8ddd056eaed5a29f643dfb7636136171f2823b474379b305054568cf86608a02d020a88cc943a226ae3125e342d784546056490a7455eda8d381
+  data.tar.gz: 9c4539742f5b088704b88c7420ce792b9cd5c6068e444b6669f6cd36b574fc0f082caf344d8039a875521061223f09c62d0661580279681478ca913e0b04c122

data/Rakefile

@@ -14,8 +14,6 @@ end
 
 # Add support for rake-compiler if available
 begin
-  ENV['RUBY_CC_VERSION'] ||= '2.6.0:2.7.0:3.0.0:3.1.0:3.2.0:3.3.0'
-
   spec = Gem::Specification.load('mongory.gemspec')
 
   Rake::ExtensionTask.new('mongory_ext', spec) do |ext|
@@ -24,18 +22,6 @@ begin
     ext.ext_dir = 'ext/mongory_ext'
     ext.source_pattern = '*.c'
     ext.gem_spec = spec
-    ext.cross_compile = true
-    ext.cross_platform = [
-      'x86_64-linux',
-      'aarch64-linux',
-      'x86_64-darwin',
-      'arm64-darwin',
-      # 'arm64-mingw-ucrt', # TODO: add this when we have a mingw-ucrt rake-compiler-dock image
-      'x64-mingw32',
-      'x64-mingw-ucrt',
-      'x86_64-linux-musl',
-      'aarch64-linux-musl'
-    ]
   end
 
   # Add tasks for building with submodule

data/ext/mongory_ext/extconf.rb

@@ -55,6 +55,13 @@ $CFLAGS << ' -Wno-declaration-after-statement -Wno-discarded-qualifiers'
 $CFLAGS << ' -O2' unless ENV['DEBUG']
 $CFLAGS << ' -g -O0 -DDEBUG' if ENV['DEBUG']
 
+# --- macOS (darwin) linking: avoid hard-linking libruby, let symbols resolve at load time
+if RbConfig::CONFIG['host_os'] =~ /darwin/
+  # Use dynamic_lookup so Ruby symbols (rb_*) are resolved by the host interpreter at dlopen time
+  $LDFLAGS  << ' -Wl,-undefined,dynamic_lookup'
+  $DLDFLAGS << ' -Wl,-undefined,dynamic_lookup'
+end
+
 # Let mkmf generate rules by listing all sources and corresponding objects
 $INCFLAGS << ' -I.'
 $INCFLAGS << " -I#{File.join(core_src_dir, 'foundations')}"
@@ -74,6 +81,18 @@ puts "Use 'make' to build the extension"
 # Append Makefile rules: explicit compilation rules for submodule sources to avoid copying/linking files
 mk = File.read('Makefile')
 
+if RbConfig::CONFIG['host_os'] =~ /darwin/
+  # --- sanitize Makefile to ensure no hard link against Ruby framework/libruby ---
+  mk << <<~'MAKE'
+  # --- darwin: force unlink from libruby (final override) ---
+  LIBRUBYARG =
+  LIBRUBYARG_SHARED =
+  LIBRUBYARG_STATIC =
+  LIBRUBY =
+  LIBS =
+  MAKE
+end
+
 # rubocop:disable Layout/HeredocIndentation
 rules = +"\n# --- custom rules for mongory-core submodule sources ---\n"
 (foundations_src + matchers_src).each do |src|

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

@@ -0,0 +1,122 @@
+#ifndef MONGORY_ARRAY
+#define MONGORY_ARRAY
+
+/**
+ * @file array.h
+ * @brief Defines the mongory_array structure and its associated operations.
+ *
+ * mongory_array is a dynamic array implementation that stores mongory_value
+ * pointers. It handles its own memory management for the array storage using a
+ * provided mongory_memory_pool. The array can grow automatically as new
+ * elements are added.
+ */
+
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include <stdbool.h>
+
+/**
+ * @brief Forward declaration for the mongory_array structure.
+ */
+typedef struct mongory_array mongory_array;
+
+/**
+ * @brief Callback function type used by mongory_array_each_func.
+ *
+ * This function is called for each item in the array during an iteration.
+ *
+ * @param item A pointer to the current mongory_value item in the array.
+ * @param acc An accumulator or context pointer passed through the iteration.
+ * @return bool Return true to continue iteration, false to stop.
+ */
+typedef bool (*mongory_array_callback_func)(mongory_value *item, void *acc);
+
+/**
+ * @brief Function pointer type for iterating over the array.
+ * @param self A pointer to the mongory_array instance.
+ * @param acc An accumulator or context pointer to be passed to the callback.
+ * @param func The callback function to be executed for each item.
+ * @return bool Returns true if the iteration completed fully, false if it was
+ * stopped by a callback.
+ */
+typedef bool (*mongory_array_each_func)(mongory_array *self, void *acc, mongory_array_callback_func func);
+
+/**
+ * @brief Function pointer type for adding an element to the end of the array.
+ * @param self A pointer to the mongory_array instance.
+ * @param value A pointer to the mongory_value to add.
+ * @return bool Returns true if the value was successfully added, false
+ * otherwise (e.g., memory allocation failure).
+ */
+typedef bool (*mongory_array_push_func)(mongory_array *self, mongory_value *value);
+
+/**
+ * @brief Function pointer type for retrieving an element at a specific index.
+ * @param self A pointer to the mongory_array instance.
+ * @param index The index of the element to retrieve.
+ * @return mongory_value* A pointer to the mongory_value at the given index, or
+ * NULL if the index is out of bounds.
+ */
+typedef mongory_value *(*mongory_array_get_func)(mongory_array *self, size_t index);
+
+/**
+ * @brief Function pointer type for setting or replacing an element at a
+ * specific index.
+ *
+ * If the index is beyond the current count, the array will be grown, and
+ * intermediate elements will be initialized to NULL.
+ *
+ * @param self A pointer to the mongory_array instance.
+ * @param index The index at which to set the value.
+ * @param value A pointer to the mongory_value to set.
+ * @return bool Returns true if the value was successfully set, false otherwise
+ * (e.g., memory allocation failure).
+ */
+typedef bool (*mongory_array_set_func)(mongory_array *self, size_t index, mongory_value *value);
+
+/**
+ * @brief Creates a new mongory_array instance.
+ *
+ * The array is initialized with a default capacity and will use the provided
+ * memory pool for all its internal allocations related to storing elements.
+ *
+ * @param pool A pointer to the mongory_memory_pool to be used for allocations.
+ * @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_new(mongory_memory_pool *pool);
+
+/**
+ * @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, ...);
+#define MG_ARRAY_WRAP(pool, n, ...) mongory_value_wrap_a(pool, mongory_array_nested_wrap(pool, n, __VA_ARGS__))
+
+/**
+ * @struct mongory_array
+ * @brief Represents a dynamic array of mongory_value pointers.
+ *
+ * This structure provides function pointers for common array operations,
+ * allowing for a somewhat object-oriented interface in C.
+ */
+struct mongory_array {
+  size_t count;                 /**< The current number of elements in the array. */
+  mongory_memory_pool *pool;    /**< The memory pool used for allocations. */
+  mongory_array_each_func each; /**< Function to iterate over elements in the array. */
+  mongory_array_push_func push; /**< Function to add an element to the end of the array. */
+  mongory_array_get_func get;   /**< Function to retrieve an element by index. */
+  mongory_array_set_func set;   /**< Function to set or replace an element at an index. */
+};
+
+#endif /* MONGORY_ARRAY */

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

@@ -0,0 +1,161 @@
+#ifndef MONGORY_FOUNDATIONS_CONFIG_H
+#define MONGORY_FOUNDATIONS_CONFIG_H
+
+/**
+ * @file config.h
+ * @brief Defines global configuration functions and types for the Mongory
+ * library.
+ *
+ * This includes initialization and cleanup routines, as well as functions
+ * for setting up custom behaviors like regex matching and value conversion.
+ * It also provides a string copying utility that uses the library's memory
+ * pool.
+ */
+
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include <stdbool.h>
+
+/**
+ * @brief Function pointer type for custom regex matching.
+ *
+ * This function is called when a regex match is required.
+ *
+ * @param pool The memory pool to use for any allocations during the match.
+ * @param pattern The regex pattern (as a mongory_value, typically a string or
+ * regex type).
+ * @param value The value to match against (as a mongory_value, typically a
+ * string).
+ * @return bool True if the value matches the pattern, false otherwise.
+ */
+typedef bool (*mongory_regex_func)(mongory_memory_pool *pool, mongory_value *pattern, mongory_value *value);
+
+/**
+ * @brief Function pointer type for stringifying a regex pattern.
+ *
+ * This function is called when a regex pattern needs to be stringified.
+ *
+ * @param pool The memory pool to use for any allocations during the
+ * stringification.
+ * @param pattern The regex pattern (as a mongory_value, typically a string or
+ * regex type).
+ * @return char* A stringified representation of the regex pattern, or NULL on failure.
+ */
+typedef char* (*mongory_regex_stringify_func)(mongory_memory_pool *pool, mongory_value *pattern);
+
+/**
+ * @brief Function pointer type for deep conversion of an external value to a
+ * mongory_value.
+ *
+ * "Deep" implies that if the external value is a complex type (e.g., a struct
+ * representing a document or array), its contents should also be converted.
+ *
+ * @param pool The memory pool to use for allocating the new mongory_value and
+ * its data.
+ * @param value A pointer to the external value to convert.
+ * @return mongory_value* A new mongory_value representing the converted data,
+ * or NULL on failure.
+ */
+typedef mongory_value *(*mongory_deep_convert_func)(mongory_memory_pool *pool, void *value);
+
+/**
+ * @brief Function pointer type for shallow conversion of an external value to a
+ * mongory_value.
+ *
+ * "Shallow" implies that if the external value is complex, only a wrapper or
+ * pointer might be stored in the mongory_value, without deeply converting its
+ * contents.
+ *
+ * @param pool The memory pool to use for allocating the new mongory_value.
+ * @param value A pointer to the external value to convert.
+ * @return mongory_value* A new mongory_value, or NULL on failure.
+ */
+typedef mongory_value *(*mongory_shallow_convert_func)(mongory_memory_pool *pool, void *value);
+
+/**
+ * @brief Function pointer type for recovering an external value from a
+ * mongory_value.
+ *
+ * This is the reverse of a conversion, intended to get back the original
+ * external data representation if it was stored or wrapped.
+ *
+ * @param pool The memory pool (can be used if recovery involves allocation,
+ * though often it might just retrieve a stored pointer).
+ * @param value The mongory_value from which to recover the external data.
+ * @return void* A pointer to the recovered external value, or NULL if not
+ * possible.
+ */
+typedef void *(*mongory_recover_func)(mongory_memory_pool *pool, mongory_value *value);
+
+/**
+ * @brief Initializes the Mongory library.
+ *
+ * Sets up internal structures, including the global memory pool,
+ * regex adapter, matcher mapping, and value converter. This function
+ * should be called before any other Mongory library functions are used.
+ * It also registers the default set of matchers (e.g., $in, $eq).
+ */
+void mongory_init();
+
+/**
+ * @brief Cleans up resources used by the Mongory library.
+ *
+ * Frees the internal memory pool and resets global pointers. This should
+ * be called when the library is no longer needed to prevent memory leaks.
+ */
+void mongory_cleanup();
+
+/**
+ * @brief Sets the custom regex matching function.
+ *
+ * If not called, a default function that always returns false is used.
+ *
+ * @param func The custom regex function to use.
+ */
+void mongory_regex_func_set(mongory_regex_func func);
+
+/**
+ * @brief Sets the custom regex stringify function.
+ *
+ * If not called, a default function that always returns NULL is used.
+ *
+ * @param func The custom regex stringify function to use.
+ */
+void mongory_regex_stringify_func_set(mongory_regex_stringify_func func);
+
+/**
+ * @brief Sets the custom deep value conversion function.
+ * @param deep_convert The function to use for deep conversions.
+ */
+void mongory_value_converter_deep_convert_set(mongory_deep_convert_func deep_convert);
+
+/**
+ * @brief Sets the custom shallow value conversion function.
+ * @param shallow_convert The function to use for shallow conversions.
+ */
+void mongory_value_converter_shallow_convert_set(mongory_shallow_convert_func shallow_convert);
+
+/**
+ * @brief Sets the custom value recovery function.
+ * @param recover The function to use for recovering external values.
+ */
+void mongory_value_converter_recover_set(mongory_recover_func recover);
+
+/**
+ * @brief Function pointer type for matching a value 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_context {
+  char *name; // Name of the custom matcher.
+  void *external_matcher; // External reference to the custom matcher.
+} mongory_matcher_custom_context;
+
+void mongory_custom_matcher_match_func_set(bool (*match)(void *external_matcher, mongory_value *value));
+void mongory_custom_matcher_build_func_set(mongory_matcher_custom_context *(*build)(char *key, mongory_value *condition, void *extern_ctx));
+void mongory_custom_matcher_lookup_func_set(bool (*lookup)(char *key));
+
+void mongory_matcher_trace_result_colorful_set(bool colorful);
+
+#endif /* MONGORY_FOUNDATIONS_CONFIG_H */

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

@@ -0,0 +1,79 @@
+#ifndef MONGORY_ERROR
+#define MONGORY_ERROR
+
+/**
+ * @file error.h
+ * @brief Defines error types and structures for the Mongory library.
+ *
+ * This file provides an enumeration of possible error codes and a structure
+ * for representing error information, typically consisting of an error type
+ * and an associated message.
+ */
+
+#include <stdbool.h>
+
+/**
+ * @def MONGORY_ERROR_TYPE_MAGIC
+ * @brief A magic number used in generating enum values for error types.
+ * Helps in creating somewhat unique integer values for the enums.
+ */
+#define MONGORY_ERROR_TYPE_MAGIC 107
+
+/**
+ * @def MONGORY_ERROR_TYPE_MACRO
+ * @brief X-Macro for defining error types.
+ * This macro allows defining the error enum, string conversion, etc.,
+ * from a single list, promoting consistency.
+ * Each entry takes the enum name, a numeric suffix, and a string description.
+ */
+#define MONGORY_ERROR_TYPE_MACRO(_)                                                                                    \
+  _(MONGORY_ERROR_NONE, 10, "No Error")                                                                                \
+  _(MONGORY_ERROR_MEMORY, 11, "Memory Allocation Error")                                                               \
+  _(MONGORY_ERROR_INVALID_TYPE, 12, "Invalid Type Error")                                                              \
+  _(MONGORY_ERROR_OUT_OF_BOUNDS, 13, "Out of Bounds Error")                                                            \
+  _(MONGORY_ERROR_UNSUPPORTED_OPERATION, 14, "Unsupported Operation Error")                                            \
+  _(MONGORY_ERROR_INVALID_ARGUMENT, 15, "Invalid Argument Error")                                                      \
+  _(MONGORY_ERROR_IO, 16, "I/O Error")                                                                                 \
+  _(MONGORY_ERROR_PARSE, 17, "Parse Error")                                                                            \
+  _(MONGORY_ERROR_UNKNOWN, 99, "Unknown Error")
+
+/**
+ * @enum mongory_error_type
+ * @brief Enumerates the types of errors that can occur within the Mongory
+ * library. Values are generated using MONGORY_ERROR_TYPE_MACRO and
+ * MONGORY_ERROR_TYPE_MAGIC.
+ */
+typedef enum mongory_error_type {
+#define DEFINE_ERROR_ENUM(name, num, str) name = num * MONGORY_ERROR_TYPE_MAGIC,
+  MONGORY_ERROR_TYPE_MACRO(DEFINE_ERROR_ENUM)
+#undef DEFINE_ERROR_ENUM
+} mongory_error_type;
+
+/**
+ * @brief Converts a mongory_error_type enum to its string representation.
+ *
+ * @param type The error type enum value.
+ * @return const char* A string describing the error type. Returns "Unknown
+ * Error Type" if the type is not recognized.
+ */
+const char *mongory_error_type_to_string(enum mongory_error_type type);
+
+/**
+ * @struct mongory_error
+ * @brief Structure to hold error information.
+ *
+ * Contains the type of error and an optional descriptive message.
+ * The message string is expected to be a literal or have a lifetime
+ * managed elsewhere (e.g., allocated from a memory pool).
+ */
+typedef struct mongory_error {
+  mongory_error_type type; /**< The type of the error. */
+  const char *message;     /**< A descriptive message for the error. This message
+                                might be a string literal or allocated from a
+                                memory pool. Its lifetime should be considered
+                                carefully. */
+} mongory_error;
+
+extern mongory_error MONGORY_ALLOC_ERROR;
+
+#endif /* MONGORY_ERROR */

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

@@ -0,0 +1,95 @@
+#ifndef MONGORY_MEMORY_POOL
+#define MONGORY_MEMORY_POOL
+
+/**
+ * @file memory_pool.h
+ * @brief Defines the mongory_memory_pool structure and its associated
+ * operations.
+ *
+ * A memory pool is used for efficient memory management within the Mongory
+ * library. It allows for allocating blocks of memory that can be freed
+ * all at once when the pool itself is destroyed. This can reduce the overhead
+ * of individual allocations and deallocations and help prevent memory leaks.
+ */
+
+#include "mongory-core/foundations/error.h"
+#include <stdbool.h>
+#include <stdlib.h> // For size_t
+
+// Forward declaration of the memory pool structure.
+typedef struct mongory_memory_pool mongory_memory_pool;
+
+#define MG_ALLOC(p, n) (p->alloc(p, n))
+#define MG_ALLOC_PTR(p, t) ((t*)MG_ALLOC(p, sizeof(t)))
+#define MG_ALLOC_OBJ(p, t) ((t)MG_ALLOC(p, sizeof(t)))
+#define MG_ALLOC_ARY(p, t, n) ((t*)MG_ALLOC(p, sizeof(t) * (n)))
+/**
+ * @struct mongory_memory_pool
+ * @brief Represents a memory pool for managing memory allocations.
+ *
+ * The pool uses a context (`ctx`) to store its internal state, which typically
+ * includes a list of allocated memory chunks.
+ * It provides function pointers for allocation, tracing (optional), and freeing
+ * the entire pool. An error field can store information about the last error
+ * encountered during pool operations.
+ */
+struct mongory_memory_pool {
+  /**
+   * @brief Allocates a block of memory from the pool.
+   * @param ctx A pointer to the pool's internal context.
+   * @param size The number of bytes to allocate.
+   * @return void* A pointer to the allocated memory block, or NULL on failure.
+   * Memory allocated this way is typically aligned.
+   */
+  void *(*alloc)(mongory_memory_pool *pool, size_t size);
+
+  /**
+   * @brief Traces an externally allocated memory block, associating it with the
+   * pool.
+   *
+   * This is useful if memory is allocated outside the pool's `alloc` function
+   * (e.g., by an external library) but its lifecycle should be tied to the
+   * pool. When the pool is freed, traced memory blocks might also be freed
+   * depending on the pool's implementation.
+   *
+   * @param ctx A pointer to the pool's internal context.
+   * @param ptr A pointer to the memory block to trace.
+   * @param size The size of the memory block.
+   */
+  void (*trace)(mongory_memory_pool *pool, void *ptr, size_t size);
+
+  /**
+   * @brief Resets the memory pool to its initial state.
+   * @param ctx A pointer to the pool's internal context.
+   */
+  void (*reset)(mongory_memory_pool *pool);
+
+  /**
+   * @brief Frees the entire memory pool, including all memory blocks allocated
+   * from it and any traced memory blocks (depending on implementation).
+   * @param self A pointer to the mongory_memory_pool instance to be freed.
+   */
+  void (*free)(mongory_memory_pool *self);
+
+  void *ctx;            /**< Pointer to the internal context/state of the memory
+                           pool. This is managed by the pool implementation. */
+  mongory_error *error; /**< Pointer to a mongory_error structure. If an
+                           operation fails (e.g., allocation), this may be set
+                           to describe the error. The memory for this error
+                           struct itself is typically allocated from the pool or
+                           is a static error object. */
+};
+
+/**
+ * @brief Creates a new mongory_memory_pool instance.
+ *
+ * Initializes the pool structure and its internal context, preparing it for
+ * allocations.
+ *
+ * @return mongory_memory_pool* A pointer to the newly created memory pool, or
+ * NULL if creation fails (e.g., initial memory allocation for the pool's
+ * context failed).
+ */
+mongory_memory_pool *mongory_memory_pool_new();
+
+#endif /* MONGORY_MEMORY_POOL */

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

@@ -0,0 +1,127 @@
+#ifndef MONGORY_TABLE_H
+#define MONGORY_TABLE_H
+
+/**
+ * @file table.h
+ * @brief Defines the mongory_table structure (a hash table) and its
+ * associated operations.
+ *
+ * mongory_table implements a hash table mapping string keys to mongory_value
+ * pointers. It uses a mongory_memory_pool for its allocations and handles
+ * operations like get, set, delete, and iteration over key-value pairs.
+ * The table automatically resizes (rehashes) when its load factor is exceeded.
+ */
+
+#include "mongory-core/foundations/array.h" // Used internally by the table
+#include "mongory-core/foundations/memory_pool.h"
+#include "mongory-core/foundations/value.h"
+#include <stdbool.h>
+#include <stddef.h> // For size_t
+
+// Forward declaration of the mongory_table structure.
+struct mongory_table;
+/**
+ * @brief Alias for `struct mongory_table`.
+ */
+typedef struct mongory_table mongory_table;
+
+/**
+ * @brief Callback function type for iterating over key-value pairs in a table.
+ * @param key The current key (null-terminated string).
+ * @param value A pointer to the current mongory_value.
+ * @param acc An accumulator or context pointer passed through the iteration.
+ * @return bool Return true to continue iteration, false to stop.
+ */
+typedef bool (*mongory_table_each_pair_callback_func)(char *key, mongory_value *value, void *acc);
+
+/**
+ * @brief Function pointer type for retrieving a value by its key.
+ * @param self A pointer to the mongory_table instance.
+ * @param key The null-terminated string key.
+ * @return mongory_value* A pointer to the mongory_value associated with the
+ * key, or NULL if the key is not found.
+ */
+typedef mongory_value *(*mongory_table_get_func)(mongory_table *self, char *key);
+
+/**
+ * @brief Function pointer type for setting (adding or updating) a key-value
+ * pair.
+ * @param self A pointer to the mongory_table instance.
+ * @param key The null-terminated string key. The table will make its own copy
+ * of this key.
+ * @param value A pointer to the mongory_value to associate with the key.
+ * @return bool True if the operation was successful, false otherwise (e.g.,
+ * memory allocation failure).
+ */
+typedef bool (*mongory_table_set_func)(mongory_table *self, char *key, mongory_value *value);
+
+/**
+ * @brief Function pointer type for iterating over all key-value pairs in the
+ * table.
+ * @param self A pointer to the mongory_table instance.
+ * @param acc An accumulator or context pointer to be passed to the callback.
+ * @param callback The function to be executed for each key-value pair.
+ * @return bool True if the iteration completed fully, false if it was stopped
+ * by a callback.
+ */
+typedef bool (*mongory_table_each_func)(mongory_table *self, void *acc, mongory_table_each_pair_callback_func callback);
+
+/**
+ * @brief Function pointer type for deleting a key-value pair from the table.
+ * @param self A pointer to the mongory_table instance.
+ * @param key The null-terminated string key of the pair to delete.
+ * @return bool True if the key was found and deleted, false otherwise.
+ */
+typedef bool (*mongory_table_del_func)(mongory_table *self, char *key);
+
+/**
+ * @brief Creates a new mongory_table instance.
+ *
+ * Initializes the hash table with a default capacity and associates it with the
+ * provided memory pool for all internal allocations.
+ *
+ * @param pool A pointer to the mongory_memory_pool to be used for allocations.
+ * @return mongory_table* A pointer to the newly created mongory_table, or NULL
+ * if creation fails (e.g., memory allocation failure).
+ */
+mongory_table *mongory_table_new(mongory_memory_pool *pool);
+
+/**
+ * @brief Creates a new mongory_table instance with a nested table.
+ *
+ * This function is used to create a new mongory_table instance with a nested
+ * table. The nested table is created with the given memory pool and the given
+ * key-value pairs. The nested table is returned as a pointer to the
+ * mongory_table structure.
+ *
+ * @param pool A pointer to the mongory_memory_pool to be used for allocations.
+ * @param argc The number of key-value pairs to be set.
+ * @param ... The key-value pairs to be set.
+ * @return mongory_table* A pointer to the newly created mongory_table, or NULL
+ * if creation fails (e.g., memory allocation failure).
+ */
+mongory_table *mongory_table_nested_wrap(mongory_memory_pool *pool, int argc, ...);
+#define MG_TABLE_WRAP(pool, n, ...) mongory_value_wrap_t(pool, mongory_table_nested_wrap(pool, n, __VA_ARGS__))
+
+/**
+ * @struct mongory_table
+ * @brief Represents a hash table mapping string keys to mongory_value pointers.
+ *
+ * Provides function pointers for common table operations, similar to an
+ * object-oriented interface. The `count` field indicates the number of
+ * key-value pairs currently in the table and should be treated as read-only by
+ * users of the table.
+ */
+struct mongory_table {
+  mongory_memory_pool *pool;    /**< The memory pool used for allocations. */
+  size_t count;                 /**< Read-only. The current number of key-value pairs in the
+                                   table. */
+  mongory_table_get_func get;   /**< Function to get a value by key. */
+  mongory_table_each_func each; /**< Function to iterate over key-value pairs. */
+  mongory_table_set_func set;   /**< Function to set a key-value pair. */
+  mongory_table_del_func del;   /**< Function to delete a key-value pair. */
+};
+
+mongory_table *mongory_table_merge(mongory_table *table, mongory_table *other);
+
+#endif /* MONGORY_TABLE_H */