rbxx 0.1.0

data/include/rbxx/object.hpp

@@ -0,0 +1,68 @@
+#pragma once
+
+#include <rbxx/value.hpp>
+
+#include <memory>
+#include <utility>
+
+namespace rbxx {
+namespace detail {
+
+class object_cell {
+public:
+  explicit object_cell(VALUE initial) noexcept : stored_(initial) {
+    rb_gc_register_address(&stored_);
+  }
+
+  object_cell(const object_cell&) = delete;
+  object_cell& operator=(const object_cell&) = delete;
+
+  ~object_cell() noexcept { rb_gc_unregister_address(&stored_); }
+
+  [[nodiscard]] VALUE raw() const noexcept { return stored_; }
+
+private:
+  VALUE stored_;
+};
+
+} // namespace detail
+
+/// @brief A copyable, movable RAII handle that pins a Ruby object across GC and compaction.
+/// @code rbxx::object pinned{rbxx::value{ruby_value}}; @endcode
+class object {
+public:
+  /// @brief Constructs an empty handle representing nil.
+  object() noexcept = default;
+
+  /// @brief Pins the supplied Ruby value.
+  /// @code rbxx::object pinned{rbxx::value{Qtrue}}; @endcode
+  explicit object(value initial) : cell_(std::make_shared<detail::object_cell>(initial.raw())) {}
+
+  /// @brief Pins the supplied raw Ruby VALUE.
+  explicit object(VALUE initial) : object(value{initial}) {}
+
+  object(const object&) noexcept = default;
+  object(object&&) noexcept = default;
+  object& operator=(const object&) noexcept = default;
+  object& operator=(object&&) noexcept = default;
+  ~object() = default;
+
+  /// @brief Returns the pinned object as a non-owning value view.
+  /// @code rbxx::value current = pinned.get(); @endcode
+  [[nodiscard]] value get() const noexcept { return value{raw()}; }
+
+  /// @brief Returns the current raw VALUE, updated after compaction.
+  [[nodiscard]] VALUE raw() const noexcept { return cell_ ? cell_->raw() : Qnil; }
+
+  /// @brief Returns whether the handle is empty or pins nil.
+  [[nodiscard]] bool is_nil() const noexcept { return NIL_P(raw()); }
+
+  /// @brief Releases this handle's ownership of the pin.
+  /// @code pinned.reset(); @endcode
+  void reset() noexcept { cell_.reset(); }
+
+private:
+  std::shared_ptr<detail::object_cell> cell_;
+};
+
+} // namespace rbxx

data/include/rbxx/operators.hpp

@@ -0,0 +1,31 @@
+#pragma once
+
+namespace rbxx::op {
+
+/// @brief Metadata for mapping a C++ callable to a Ruby operator method.
+struct name {
+  const char* ruby_name;
+  bool include_comparable = false;
+};
+
+/// @name Ruby operator names
+/// @{
+inline constexpr name add{"+"};
+inline constexpr name subtract{"-"};
+inline constexpr name multiply{"*"};
+inline constexpr name divide{"/"};
+inline constexpr name modulo{"%"};
+inline constexpr name equal{"=="};
+inline constexpr name compare{"<=>", true};
+inline constexpr name less{"<"};
+inline constexpr name greater{">"};
+inline constexpr name index{"[]"};
+inline constexpr name index_set{"[]="};
+inline constexpr name left_shift{"<<"};
+inline constexpr name to_s{"to_s"};
+inline constexpr name inspect{"inspect"};
+inline constexpr name hash{"hash"};
+inline constexpr name call{"call"};
+/// @}
+
+} // namespace rbxx::op

data/include/rbxx/policies.hpp

@@ -0,0 +1,36 @@
+#pragma once
+
+#include <cstddef>
+
+namespace rbxx {
+
+namespace policy {
+
+/// @brief Internal value carried by a public return-value policy constant.
+enum class kind { automatic, copy, take, reference, shared };
+
+/// @brief Selects ownership behavior when converting a C++ return value to Ruby.
+struct return_value_policy {
+  kind value;
+};
+
+/// @name Return-value policies
+/// @{
+inline constexpr return_value_policy automatic{kind::automatic};
+inline constexpr return_value_policy copy{kind::copy};
+inline constexpr return_value_policy take{kind::take};
+inline constexpr return_value_policy reference{kind::reference};
+inline constexpr return_value_policy shared{kind::shared};
+/// @}
+
+} // namespace policy
+
+/// @brief Keeps one Ruby object alive for as long as another remains reachable.
+/// @details Index 0 is the return value, 1 is self, and 2 onward are arguments.
+/// @code .def("child", &Owner::child, policy::reference, keep_alive<0, 1>()) @endcode
+template <std::size_t Nurse, std::size_t Patient> struct keep_alive {
+  static constexpr std::size_t nurse = Nurse;
+  static constexpr std::size_t patient = Patient;
+};
+
+} // namespace rbxx

data/include/rbxx/protect.hpp

@@ -0,0 +1,72 @@
+#pragma once
+
+#include <rbxx/exception.hpp>
+
+#include <exception>
+#include <functional>
+#include <optional>
+#include <tuple>
+#include <type_traits>
+#include <utility>
+
+namespace rbxx {
+namespace detail {
+
+template <typename Function, typename... Args> struct protect_payload {
+  using function_type = std::decay_t<Function>;
+  using result_type = std::invoke_result_t<function_type&, std::decay_t<Args>&...>;
+  using stored_result = std::conditional_t<std::is_void_v<result_type>, bool, result_type>;
+
+  function_type function;
+  std::tuple<std::decay_t<Args>...> args;
+  std::optional<stored_result> result;
+  std::exception_ptr cpp_exception;
+};
+
+template <typename Payload> VALUE protect_trampoline(VALUE opaque) noexcept {
+  auto* payload = reinterpret_cast<Payload*>(opaque);
+  try {
+    if constexpr (std::is_void_v<typename Payload::result_type>) {
+      std::apply(payload->function, payload->args);
+      payload->result.emplace(true);
+    } else {
+      payload->result.emplace(std::apply(payload->function, payload->args));
+    }
+  } catch (...) {
+    payload->cpp_exception = std::current_exception();
+  }
+  return Qnil;
+}
+
+} // namespace detail
+
+/// @brief Invokes a Ruby C API operation through rb_protect and converts longjmp to ruby_error.
+/// @code VALUE string = rbxx::protect(rb_utf8_str_new_cstr, "safe"); @endcode
+template <typename Function, typename... Args> auto protect(Function&& function, Args&&... args) {
+  using payload_type = detail::protect_payload<Function, Args...>;
+  static_assert(!std::is_reference_v<typename payload_type::result_type>,
+                "rbxx::protect does not support reference return types");
+
+  payload_type payload{std::forward<Function>(function),
+                       std::tuple<std::decay_t<Args>...>{std::forward<Args>(args)...}, std::nullopt,
+                       nullptr};
+  int state = 0;
+  rb_protect(detail::protect_trampoline<payload_type>, reinterpret_cast<VALUE>(&payload), &state);
+
+  if (state != 0) {
+    VALUE exception = rb_errinfo();
+    rb_set_errinfo(Qnil);
+    throw ruby_error(exception);
+  }
+  if (payload.cpp_exception) {
+    std::rethrow_exception(payload.cpp_exception);
+  }
+
+  if constexpr (std::is_void_v<typename payload_type::result_type>) {
+    return;
+  } else {
+    return std::move(*payload.result);
+  }
+}
+
+} // namespace rbxx

data/include/rbxx/rbxx.hpp

@@ -0,0 +1,20 @@
+#pragma once
+
+#include <rbxx/arg.hpp>
+#include <rbxx/callback.hpp>
+#include <rbxx/class.hpp>
+#include <rbxx/data_object.hpp>
+#include <rbxx/detail/ruby_include.hpp>
+#include <rbxx/extension.hpp>
+#include <rbxx/function.hpp>
+#include <rbxx/module.hpp>
+#include <rbxx/nogvl.hpp>
+#include <rbxx/object.hpp>
+#include <rbxx/operators.hpp>
+#include <rbxx/policies.hpp>
+#include <rbxx/protect.hpp>
+#include <rbxx/registry.hpp>
+#include <rbxx/stl.hpp>
+#include <rbxx/type_caster.hpp>
+#include <rbxx/value.hpp>
+#include <rbxx/version.hpp>

data/include/rbxx/registry.hpp

@@ -0,0 +1,145 @@
+#pragma once
+
+#include <rbxx/type_caster.hpp>
+
+#include <functional>
+#include <memory>
+#include <mutex>
+#include <source_location>
+#include <string>
+#include <typeindex>
+#include <unordered_map>
+
+namespace rbxx::detail {
+
+struct class_info {
+  std::type_index cpp_type{typeid(void)};
+  VALUE ruby_class = Qnil;
+  const rb_data_type_t* data_type = nullptr;
+  std::function<void*(void*)> native_pointer;
+  std::unordered_map<std::type_index, std::function<void*(void*)>> conversions;
+  std::source_location registered_at = std::source_location::current();
+};
+
+class type_registry {
+public:
+  static type_registry& instance() {
+    static auto* registry = new type_registry();
+    return *registry;
+  }
+
+  template <typename T, typename Base = void>
+  void add(VALUE ruby_class, const rb_data_type_t* data_type,
+           std::source_location location = std::source_location::current()) {
+    auto information = std::make_unique<class_info>();
+    information->cpp_type = std::type_index(typeid(T));
+    information->ruby_class = ruby_class;
+    information->data_type = data_type;
+    information->conversions.emplace(std::type_index(typeid(T)),
+                                     [](void* pointer) { return pointer; });
+    information->registered_at = location;
+
+    if constexpr (!std::is_void_v<Base>) {
+      class_info* base = find(std::type_index(typeid(Base)));
+      if (base == nullptr) {
+        std::string message = "rbxx: base C++ type ";
+        message += type_name<Base>();
+        message += " is not registered; call def_class<Base>() first";
+        throw ruby_error(make_exception(rb_eTypeError, message.c_str()));
+      }
+      for (const auto& [target, conversion] : base->conversions) {
+        information->conversions.emplace(target, [conversion](void* pointer) {
+          auto* derived = static_cast<T*>(pointer);
+          return conversion(static_cast<Base*>(derived));
+        });
+      }
+    }
+
+    std::lock_guard lock(write_mutex_);
+    class_info* stored = information.get();
+    by_data_type_.insert_or_assign(data_type, stored);
+    by_type_.insert_or_assign(std::type_index(typeid(T)), std::move(information));
+  }
+
+  template <typename T> void set_native_pointer(std::function<void*(void*)> extractor) {
+    class_info* information = find(std::type_index(typeid(T)));
+    if (information != nullptr) {
+      information->native_pointer = std::move(extractor);
+    }
+  }
+
+  [[nodiscard]] class_info* find(std::type_index type) const noexcept {
+    auto found = by_type_.find(type);
+    return found == by_type_.end() ? nullptr : found->second.get();
+  }
+
+  [[nodiscard]] class_info* find(const rb_data_type_t* type) const noexcept {
+    auto found = by_data_type_.find(type);
+    return found == by_data_type_.end() ? nullptr : found->second;
+  }
+
+private:
+  std::mutex write_mutex_;
+  std::unordered_map<std::type_index, std::unique_ptr<class_info>> by_type_;
+  std::unordered_map<const rb_data_type_t*, class_info*> by_data_type_;
+};
+
+template <typename T> [[noreturn]] void throw_unregistered_type() {
+  std::string message = "rbxx: C++ type ";
+  message += type_name<T>();
+  message += " is not registered; call def_class<T>() or specialize rbxx::type_caster<T>";
+  throw ruby_error(make_exception(rb_eTypeError, message.c_str()));
+}
+
+template <typename T> class_info& registered_class() {
+  class_info* information = type_registry::instance().find(std::type_index(typeid(T)));
+  if (information == nullptr) {
+    throw_unregistered_type<T>();
+  }
+  return *information;
+}
+
+template <typename T> T& load_registered(value input) {
+  VALUE raw = input.raw();
+  if (!RB_TYPE_P(raw, T_DATA) || !RTYPEDDATA_P(raw)) {
+    std::string message = "rbxx: expected registered C++ type ";
+    message += type_name<T>();
+    message += ", got ";
+    message += rb_obj_classname(raw);
+    message += "; call def_class<T>() for the expected type";
+    throw ruby_error(make_exception(rb_eTypeError, message.c_str()));
+  }
+
+  class_info* actual = type_registry::instance().find(RTYPEDDATA_TYPE(raw));
+  if (actual == nullptr || !actual->native_pointer) {
+    throw_unregistered_type<T>();
+  }
+  auto conversion = actual->conversions.find(std::type_index(typeid(T)));
+  if (conversion == actual->conversions.end()) {
+    std::string message = "rbxx: wrapped C++ type cannot be converted to ";
+    message += type_name<T>();
+    message += "; register the inheritance with def_class<Derived, Base>()";
+    message += "; actual type was registered at ";
+    message += actual->registered_at.file_name();
+    message += ":";
+    message += std::to_string(actual->registered_at.line());
+    throw ruby_error(make_exception(rb_eTypeError, message.c_str()));
+  }
+
+  void* native = actual->native_pointer(RTYPEDDATA_DATA(raw));
+  if (native == nullptr) {
+    throw ruby_error(make_exception(rb_eRuntimeError, "rbxx: C++ object is not initialized"));
+  }
+  return *static_cast<T*>(conversion->second(native));
+}
+
+template <typename T> bool registered_matches(value input) noexcept {
+  if (!RB_TYPE_P(input.raw(), T_DATA) || !RTYPEDDATA_P(input.raw())) {
+    return false;
+  }
+  class_info* actual = type_registry::instance().find(RTYPEDDATA_TYPE(input.raw()));
+  return actual != nullptr &&
+         actual->conversions.contains(std::type_index(typeid(std::remove_cv_t<T>)));
+}
+
+} // namespace rbxx::detail

data/include/rbxx/stl/array.hpp

@@ -0,0 +1,40 @@
+#pragma once
+
+#include <rbxx/stl/detail.hpp>
+
+#include <array>
+#include <sstream>
+
+namespace rbxx {
+namespace detail {
+template <typename T, std::size_t Size>
+struct is_non_bindable_class<std::array<T, Size>> : std::true_type {};
+} // namespace detail
+
+template <typename T, std::size_t Size> struct type_caster<std::array<T, Size>> {
+  static constexpr std::string_view name = "Array";
+
+  static std::array<T, Size> load(value input) {
+    VALUE array = detail::coerce_array(input);
+    if (RARRAY_LEN(array) != static_cast<long>(Size)) {
+      std::ostringstream message;
+      message << "rbxx: expected Array of length " << Size << ", got " << RARRAY_LEN(array);
+      throw ruby_error(detail::make_exception(rb_eArgError, message.str().c_str()));
+    }
+    return load_elements(array, std::make_index_sequence<Size>{});
+  }
+
+  static value dump(const std::array<T, Size>& input) { return detail::dump_array_range(input); }
+
+  static bool matches(value input) noexcept {
+    return input.is_array() && RARRAY_LEN(input.raw()) == static_cast<long>(Size);
+  }
+
+private:
+  template <std::size_t... Index>
+  static std::array<T, Size> load_elements(VALUE array, std::index_sequence<Index...>) {
+    return {from_ruby<T>(value{RARRAY_AREF(array, static_cast<long>(Index))})...};
+  }
+};
+
+} // namespace rbxx

data/include/rbxx/stl/chrono.hpp

@@ -0,0 +1,26 @@
+#pragma once
+
+#include <rbxx/stl/detail.hpp>
+
+#include <chrono>
+
+namespace rbxx {
+namespace detail {
+template <typename Rep, typename Period>
+struct is_non_bindable_class<std::chrono::duration<Rep, Period>> : std::true_type {};
+} // namespace detail
+
+template <typename Rep, typename Period> struct type_caster<std::chrono::duration<Rep, Period>> {
+  using duration_type = std::chrono::duration<Rep, Period>;
+  static constexpr std::string_view name = "seconds";
+  static duration_type load(value input) {
+    const auto seconds = std::chrono::duration<double>{from_ruby<double>(input)};
+    return std::chrono::duration_cast<duration_type>(seconds);
+  }
+  static value dump(const duration_type& input) {
+    return to_ruby(std::chrono::duration<double>(input).count());
+  }
+  static bool matches(value input) noexcept { return type_caster<double>::matches(input); }
+};
+
+} // namespace rbxx

data/include/rbxx/stl/detail.hpp

@@ -0,0 +1,60 @@
+#pragma once
+
+#include <rbxx/data_object.hpp>
+
+#include <limits>
+#include <string>
+#include <type_traits>
+
+namespace rbxx::detail {
+
+inline VALUE coerce_array(value input) {
+  VALUE converted = protect(rb_check_array_type, input.raw());
+  if (NIL_P(converted)) {
+    throw_type_error("Array or object responding to #to_ary", input);
+  }
+  return converted;
+}
+
+inline VALUE coerce_hash(value input) {
+  VALUE converted = protect(rb_check_hash_type, input.raw());
+  if (NIL_P(converted)) {
+    throw_type_error("Hash or object responding to #to_hash", input);
+  }
+  return converted;
+}
+
+template <typename Range> value dump_array_range(const Range& input) {
+  const auto size = input.size();
+  if (size > static_cast<std::size_t>(std::numeric_limits<long>::max())) {
+    throw std::length_error("rbxx: container is too large for a Ruby Array");
+  }
+  return value{protect([&input, size] {
+    VALUE result = rb_ary_new_capa(static_cast<long>(size));
+    for (const auto& element : input) {
+      using element_type = std::remove_cvref_t<decltype(element)>;
+      if constexpr (std::is_floating_point_v<element_type>) {
+        rb_ary_push(result, rb_float_new(static_cast<double>(element)));
+      } else {
+        rb_ary_push(result, to_ruby(element).raw());
+      }
+    }
+    return result;
+  })};
+}
+
+template <typename Map> value dump_hash_range(const Map& input) {
+  return value{protect([&input] {
+    VALUE result = rb_hash_new();
+    for (const auto& [key, mapped] : input) {
+      rb_hash_aset(result, to_ruby(key).raw(), to_ruby(mapped).raw());
+    }
+    return result;
+  })};
+}
+
+inline VALUE hash_pairs(VALUE hash) {
+  return protect([hash] { return rb_funcall(hash, rb_intern("to_a"), 0); });
+}
+
+} // namespace rbxx::detail

data/include/rbxx/stl/filesystem.hpp

@@ -0,0 +1,21 @@
+#pragma once
+
+#include <rbxx/stl/detail.hpp>
+
+#include <filesystem>
+
+namespace rbxx {
+namespace detail {
+template <> struct is_non_bindable_class<std::filesystem::path> : std::true_type {};
+} // namespace detail
+
+template <> struct type_caster<std::filesystem::path> {
+  static constexpr std::string_view name = "String path";
+  static std::filesystem::path load(value input) {
+    return std::filesystem::path{from_ruby<std::string>(input)};
+  }
+  static value dump(const std::filesystem::path& input) { return to_ruby(input.string()); }
+  static bool matches(value input) noexcept { return type_caster<std::string>::matches(input); }
+};
+
+} // namespace rbxx

data/include/rbxx/stl/map.hpp

@@ -0,0 +1,49 @@
+#pragma once
+
+#include <rbxx/stl/detail.hpp>
+
+#include <map>
+#include <unordered_map>
+
+namespace rbxx {
+namespace detail {
+template <typename Key, typename Mapped, typename Compare, typename Allocator>
+struct is_non_bindable_class<std::map<Key, Mapped, Compare, Allocator>> : std::true_type {};
+template <typename Key, typename Mapped, typename Hash, typename Equal, typename Allocator>
+struct is_non_bindable_class<std::unordered_map<Key, Mapped, Hash, Equal, Allocator>>
+    : std::true_type {};
+
+template <typename Map> Map load_map(value input) {
+  VALUE pairs = hash_pairs(coerce_hash(input));
+  Map result;
+  const long length = RARRAY_LEN(pairs);
+  for (long index = 0; index < length; ++index) {
+    VALUE pair = RARRAY_AREF(pairs, index);
+    using key_type = typename Map::key_type;
+    using mapped_type = typename Map::mapped_type;
+    result.emplace(from_ruby<key_type>(value{RARRAY_AREF(pair, 0)}),
+                   from_ruby<mapped_type>(value{RARRAY_AREF(pair, 1)}));
+  }
+  return result;
+}
+} // namespace detail
+
+template <typename Key, typename Mapped, typename Compare, typename Allocator>
+struct type_caster<std::map<Key, Mapped, Compare, Allocator>> {
+  using map_type = std::map<Key, Mapped, Compare, Allocator>;
+  static constexpr std::string_view name = "Hash";
+  static map_type load(value input) { return detail::load_map<map_type>(input); }
+  static value dump(const map_type& input) { return detail::dump_hash_range(input); }
+  static bool matches(value input) noexcept { return input.is_hash(); }
+};
+
+template <typename Key, typename Mapped, typename Hash, typename Equal, typename Allocator>
+struct type_caster<std::unordered_map<Key, Mapped, Hash, Equal, Allocator>> {
+  using map_type = std::unordered_map<Key, Mapped, Hash, Equal, Allocator>;
+  static constexpr std::string_view name = "Hash";
+  static map_type load(value input) { return detail::load_map<map_type>(input); }
+  static value dump(const map_type& input) { return detail::dump_hash_range(input); }
+  static bool matches(value input) noexcept { return input.is_hash(); }
+};
+
+} // namespace rbxx

data/include/rbxx/stl/optional.hpp

@@ -0,0 +1,23 @@
+#pragma once
+
+#include <rbxx/stl/detail.hpp>
+
+#include <optional>
+
+namespace rbxx {
+namespace detail {
+template <typename T> struct is_non_bindable_class<std::optional<T>> : std::true_type {};
+} // namespace detail
+
+template <typename T> struct type_caster<std::optional<T>> {
+  static constexpr std::string_view name = "Object or nil";
+  static std::optional<T> load(value input) {
+    return input.is_nil() ? std::nullopt : std::optional<T>{from_ruby<T>(input)};
+  }
+  static value dump(const std::optional<T>& input) { return input ? to_ruby(*input) : value{Qnil}; }
+  static bool matches(value input) noexcept {
+    return input.is_nil() || type_caster<T>::matches(input);
+  }
+};
+
+} // namespace rbxx

data/include/rbxx/stl/set.hpp

@@ -0,0 +1,30 @@
+#pragma once
+
+#include <rbxx/stl/detail.hpp>
+
+#include <set>
+
+namespace rbxx {
+namespace detail {
+template <typename T, typename Compare, typename Allocator>
+struct is_non_bindable_class<std::set<T, Compare, Allocator>> : std::true_type {};
+} // namespace detail
+
+template <typename T, typename Compare, typename Allocator>
+struct type_caster<std::set<T, Compare, Allocator>> {
+  using set_type = std::set<T, Compare, Allocator>;
+  static constexpr std::string_view name = "Array";
+  static set_type load(value input) {
+    VALUE array = detail::coerce_array(input);
+    set_type result;
+    const long length = RARRAY_LEN(array);
+    for (long index = 0; index < length; ++index) {
+      result.insert(from_ruby<T>(value{RARRAY_AREF(array, index)}));
+    }
+    return result;
+  }
+  static value dump(const set_type& input) { return detail::dump_array_range(input); }
+  static bool matches(value input) noexcept { return input.is_array(); }
+};
+
+} // namespace rbxx