rbxx 0.1.0

data/include/rbxx/stl/tuple.hpp

@@ -0,0 +1,74 @@
+#pragma once
+
+#include <rbxx/stl/detail.hpp>
+
+#include <tuple>
+#include <utility>
+
+namespace rbxx {
+namespace detail {
+template <typename First, typename Second>
+struct is_non_bindable_class<std::pair<First, Second>> : std::true_type {};
+template <typename... Items> struct is_non_bindable_class<std::tuple<Items...>> : std::true_type {};
+
+inline void require_tuple_length(VALUE array, long expected) {
+  if (RARRAY_LEN(array) == expected) {
+    return;
+  }
+  std::string message = "rbxx: expected Array tuple of length ";
+  message += std::to_string(expected);
+  message += ", got ";
+  message += std::to_string(RARRAY_LEN(array));
+  throw ruby_error(make_exception(rb_eArgError, message.c_str()));
+}
+
+template <typename Tuple, std::size_t... Index>
+Tuple load_tuple(VALUE array, std::index_sequence<Index...>) {
+  return Tuple{from_ruby<std::tuple_element_t<Index, Tuple>>(
+      value{RARRAY_AREF(array, static_cast<long>(Index))})...};
+}
+
+template <typename Tuple, std::size_t... Index>
+value dump_tuple(const Tuple& input, std::index_sequence<Index...>) {
+  return value{protect([&input] {
+    VALUE result = rb_ary_new_capa(static_cast<long>(sizeof...(Index)));
+    (rb_ary_push(result, to_ruby(std::get<Index>(input)).raw()), ...);
+    return result;
+  })};
+}
+} // namespace detail
+
+template <typename First, typename Second> struct type_caster<std::pair<First, Second>> {
+  using pair_type = std::pair<First, Second>;
+  static constexpr std::string_view name = "Array(2)";
+  static pair_type load(value input) {
+    VALUE array = detail::coerce_array(input);
+    detail::require_tuple_length(array, 2);
+    return {from_ruby<First>(value{RARRAY_AREF(array, 0)}),
+            from_ruby<Second>(value{RARRAY_AREF(array, 1)})};
+  }
+  static value dump(const pair_type& input) {
+    return detail::dump_tuple(input, std::index_sequence<0, 1>{});
+  }
+  static bool matches(value input) noexcept {
+    return input.is_array() && RARRAY_LEN(input.raw()) == 2;
+  }
+};
+
+template <typename... Items> struct type_caster<std::tuple<Items...>> {
+  using tuple_type = std::tuple<Items...>;
+  static constexpr std::string_view name = "Array tuple";
+  static tuple_type load(value input) {
+    VALUE array = detail::coerce_array(input);
+    detail::require_tuple_length(array, static_cast<long>(sizeof...(Items)));
+    return detail::load_tuple<tuple_type>(array, std::index_sequence_for<Items...>{});
+  }
+  static value dump(const tuple_type& input) {
+    return detail::dump_tuple(input, std::index_sequence_for<Items...>{});
+  }
+  static bool matches(value input) noexcept {
+    return input.is_array() && RARRAY_LEN(input.raw()) == static_cast<long>(sizeof...(Items));
+  }
+};
+
+} // namespace rbxx

data/include/rbxx/stl/variant.hpp

@@ -0,0 +1,35 @@
+#pragma once
+
+#include <rbxx/stl/detail.hpp>
+
+#include <variant>
+
+namespace rbxx {
+namespace detail {
+template <typename... Items>
+struct is_non_bindable_class<std::variant<Items...>> : std::true_type {};
+
+template <typename Variant, std::size_t Index = 0> Variant load_variant(value input) {
+  if constexpr (Index == std::variant_size_v<Variant>) {
+    throw_type_error("one of the std::variant alternatives", input);
+  } else {
+    using alternative = std::variant_alternative_t<Index, Variant>;
+    if (type_caster<alternative>::matches(input)) {
+      return Variant{std::in_place_index<Index>, from_ruby<alternative>(input)};
+    }
+    return load_variant<Variant, Index + 1U>(input);
+  }
+}
+} // namespace detail
+
+template <typename... Items> struct type_caster<std::variant<Items...>> {
+  using variant_type = std::variant<Items...>;
+  static constexpr std::string_view name = "variant";
+  static variant_type load(value input) { return detail::load_variant<variant_type>(input); }
+  static value dump(const variant_type& input) {
+    return std::visit([](const auto& selected) { return to_ruby(selected); }, input);
+  }
+  static bool matches(value input) noexcept { return (type_caster<Items>::matches(input) || ...); }
+};
+
+} // namespace rbxx

data/include/rbxx/stl/vector.hpp

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

data/include/rbxx/stl.hpp

@@ -0,0 +1,11 @@
+#pragma once
+
+#include <rbxx/stl/array.hpp>
+#include <rbxx/stl/chrono.hpp>
+#include <rbxx/stl/filesystem.hpp>
+#include <rbxx/stl/map.hpp>
+#include <rbxx/stl/optional.hpp>
+#include <rbxx/stl/set.hpp>
+#include <rbxx/stl/tuple.hpp>
+#include <rbxx/stl/variant.hpp>
+#include <rbxx/stl/vector.hpp>

data/include/rbxx/type_caster.hpp

@@ -0,0 +1,247 @@
+#pragma once
+
+#include <rbxx/protect.hpp>
+
+#include <concepts>
+#include <cstddef>
+#include <limits>
+#include <string>
+#include <string_view>
+#include <type_traits>
+#include <utility>
+
+namespace rbxx {
+
+/// @brief Customization point for conversion between Ruby and C++ values.
+/// @code template <> struct rbxx::type_caster<MyType> { /* load/dump/matches */ }; @endcode
+template <typename T, typename Enable = void> struct type_caster;
+
+/// @brief True when T can be converted to a Ruby value.
+template <typename T>
+concept to_ruby_convertible = requires(T&& input) {
+  {
+    type_caster<std::remove_cvref_t<T>>::dump(std::forward<T>(input))
+  } -> std::convertible_to<value>;
+};
+
+/// @brief True when a Ruby value can be converted to T.
+template <typename T>
+concept from_ruby_convertible =
+    requires(value input) { type_caster<std::remove_cvref_t<T>>::load(input); };
+
+namespace detail {
+
+template <typename T> constexpr std::string_view type_name() noexcept {
+#if defined(_MSC_VER)
+  constexpr std::string_view signature = __FUNCSIG__;
+  constexpr std::string_view prefix = "type_name<";
+  const auto start = signature.find(prefix) + prefix.size();
+  return signature.substr(start, signature.find(">(void)", start) - start);
+#else
+  constexpr std::string_view signature = __PRETTY_FUNCTION__;
+  constexpr std::string_view prefix = "T = ";
+  const auto start = signature.find(prefix) + prefix.size();
+  const auto end = signature.find_first_of("];", start);
+  return signature.substr(start, end - start);
+#endif
+}
+
+[[noreturn]] inline void throw_type_error(const char* expected, value actual) {
+  const char* actual_name = rb_obj_classname(actual.raw());
+  std::string message = "rbxx: expected ";
+  message += expected;
+  message += ", got ";
+  message += actual_name;
+  throw ruby_error(make_exception(rb_eTypeError, message.c_str()));
+}
+
+template <typename Integer> Integer load_integer(value input) {
+  if constexpr (std::is_signed_v<Integer>) {
+    const auto converted = protect(rb_num2ll, input.raw());
+    constexpr auto minimum = static_cast<LONG_LONG>(std::numeric_limits<Integer>::min());
+    constexpr auto maximum = static_cast<LONG_LONG>(std::numeric_limits<Integer>::max());
+    if (converted < minimum || converted > maximum) {
+      throw std::range_error("rbxx: Integer is outside the target C++ signed integer range");
+    }
+    return static_cast<Integer>(converted);
+  } else {
+    const auto converted = protect(rb_num2ull, input.raw());
+    constexpr auto maximum = static_cast<unsigned LONG_LONG>(std::numeric_limits<Integer>::max());
+    if (converted > maximum) {
+      throw std::range_error("rbxx: Integer is outside the target C++ unsigned integer range");
+    }
+    return static_cast<Integer>(converted);
+  }
+}
+
+template <typename Integer> value dump_integer(Integer input) {
+  if constexpr (std::is_signed_v<Integer>) {
+    if (RB_FIXABLE(static_cast<LONG_LONG>(input))) {
+      return value{LONG2FIX(static_cast<long>(input))};
+    }
+    return value{protect(rb_ll2inum, static_cast<LONG_LONG>(input))};
+  } else {
+    if (RB_POSFIXABLE(static_cast<unsigned LONG_LONG>(input))) {
+      return value{LONG2FIX(static_cast<long>(input))};
+    }
+    return value{protect(rb_ull2inum, static_cast<unsigned LONG_LONG>(input))};
+  }
+}
+
+inline const char* checked_string_pointer(value input) {
+  if (!input.is_string()) {
+    throw_type_error("String", input);
+  }
+  VALUE raw = input.raw();
+  return protect([raw]() mutable {
+    VALUE string = raw;
+    return StringValueCStr(string);
+  });
+}
+
+inline VALUE checked_string_value(value input) {
+  if (input.is_string()) {
+    return input.raw();
+  }
+  VALUE converted = protect(rb_check_string_type, input.raw());
+  if (NIL_P(converted)) {
+    throw_type_error("String or object responding to #to_str", input);
+  }
+  return converted;
+}
+
+inline value dump_utf8(const char* bytes, std::size_t size) {
+  if (size > static_cast<std::size_t>(std::numeric_limits<long>::max())) {
+    throw std::length_error("rbxx: String is too large for CRuby");
+  }
+  return value{protect(rb_utf8_str_new, bytes, static_cast<long>(size))};
+}
+
+} // namespace detail
+
+template <typename T>
+struct type_caster<T, std::enable_if_t<std::is_integral_v<T> && !std::is_same_v<T, bool>>> {
+  static constexpr std::string_view name = "Integer";
+
+  /// @brief Loads a range-checked C++ integer.
+  static T load(value input) { return detail::load_integer<T>(input); }
+
+  /// @brief Dumps a C++ integer as a Ruby Integer.
+  static value dump(T input) { return detail::dump_integer(input); }
+
+  /// @brief Returns whether the Ruby value is an Integer.
+  static bool matches(value input) noexcept { return input.is_integer(); }
+};
+
+template <> struct type_caster<bool> {
+  static constexpr std::string_view name = "Boolean";
+
+  static bool load(value input) {
+    if (!input.is_bool()) {
+      detail::throw_type_error("true or false", input);
+    }
+    return input.raw() == Qtrue;
+  }
+
+  static value dump(bool input) noexcept { return value{input ? Qtrue : Qfalse}; }
+  static bool matches(value input) noexcept { return input.is_bool(); }
+};
+
+template <> struct type_caster<float> {
+  static constexpr std::string_view name = "Float";
+  static float load(value input) {
+    if (input.is_float()) {
+      return static_cast<float>(RFLOAT_VALUE(input.raw()));
+    }
+    return static_cast<float>(protect(rb_num2dbl, input.raw()));
+  }
+  static value dump(float input) {
+    return value{protect(rb_float_new, static_cast<double>(input))};
+  }
+  static bool matches(value input) noexcept { return input.is_float() || input.is_integer(); }
+};
+
+template <> struct type_caster<double> {
+  static constexpr std::string_view name = "Float";
+  static double load(value input) {
+    return input.is_float() ? RFLOAT_VALUE(input.raw()) : protect(rb_num2dbl, input.raw());
+  }
+  static value dump(double input) { return value{protect(rb_float_new, input)}; }
+  static bool matches(value input) noexcept { return input.is_float() || input.is_integer(); }
+};
+
+template <> struct type_caster<const char*> {
+  static constexpr std::string_view name = "String";
+  static const char* load(value input) { return detail::checked_string_pointer(input); }
+  static value dump(const char* input) {
+    if (input == nullptr) {
+      detail::throw_type_error("non-null C string", value{Qnil});
+    }
+    return value{protect(rb_utf8_str_new_cstr, input)};
+  }
+  static bool matches(value input) noexcept { return input.is_string(); }
+};
+
+template <> struct type_caster<std::string> {
+  static constexpr std::string_view name = "String";
+  static std::string load(value input) {
+    VALUE converted = detail::checked_string_value(input);
+    const char* bytes = protect([converted]() mutable {
+      VALUE string = converted;
+      return StringValueCStr(string);
+    });
+    return std::string(bytes, static_cast<std::size_t>(RSTRING_LEN(converted)));
+  }
+  static value dump(const std::string& input) {
+    return detail::dump_utf8(input.data(), input.size());
+  }
+  static bool matches(value input) noexcept { return input.is_string(); }
+};
+
+template <> struct type_caster<std::string_view> {
+  static constexpr std::string_view name = "String";
+  static std::string_view load(value input) {
+    const char* bytes = detail::checked_string_pointer(input);
+    return std::string_view(bytes, static_cast<std::size_t>(RSTRING_LEN(input.raw())));
+  }
+  static value dump(std::string_view input) {
+    return detail::dump_utf8(input.data(), input.size());
+  }
+  static bool matches(value input) noexcept { return input.is_string(); }
+};
+
+template <> struct type_caster<value> {
+  static constexpr std::string_view name = "Object";
+  static value load(value input) noexcept { return input; }
+  static value dump(value input) noexcept { return input; }
+  static bool matches(value) noexcept { return true; }
+};
+
+template <> struct type_caster<object> {
+  static constexpr std::string_view name = "Object";
+  static object load(value input) { return object{input}; }
+  static value dump(const object& input) noexcept { return input.get(); }
+  static bool matches(value) noexcept { return true; }
+};
+
+/// @brief Converts a C++ value to Ruby with an actionable missing-caster diagnostic.
+/// @code rbxx::value result = rbxx::to_ruby(42); @endcode
+template <typename T> [[nodiscard]] value to_ruby(T&& input) {
+  using converted_type = std::remove_cvref_t<T>;
+  static_assert(to_ruby_convertible<converted_type>,
+                "rbxx: type has no type_caster; bind it with def_class<T>() or specialize "
+                "rbxx::type_caster<T>");
+  return type_caster<converted_type>::dump(std::forward<T>(input));
+}
+
+/// @brief Converts a Ruby value to C++ with an actionable missing-caster diagnostic.
+/// @code int result = rbxx::from_ruby<int>(ruby_value); @endcode
+template <typename T> [[nodiscard]] decltype(auto) from_ruby(value input) {
+  using converted_type = std::remove_cvref_t<T>;
+  static_assert(from_ruby_convertible<converted_type>,
+                "rbxx: type has no type_caster; bind it with def_class<T>() or specialize "
+                "rbxx::type_caster<T>");
+  return type_caster<converted_type>::load(input);
+}
+
+} // namespace rbxx

data/include/rbxx/value.hpp

@@ -0,0 +1,63 @@
+#pragma once
+
+#include <rbxx/detail/ruby_include.hpp>
+
+#include <type_traits>
+
+namespace rbxx {
+
+/// @brief A zero-overhead, non-owning view of a Ruby VALUE.
+/// @code rbxx::value nil{Qnil}; @endcode
+class value {
+public:
+  /// @brief Constructs a nil value.
+  constexpr value() noexcept = default;
+
+  /// @brief Wraps a raw Ruby VALUE without pinning it.
+  /// @code auto wrapped = rbxx::value{Qtrue}; @endcode
+  explicit constexpr value(VALUE raw) noexcept : raw_(raw) {}
+
+  /// @brief Returns the wrapped Ruby VALUE.
+  /// @code VALUE raw = wrapped.raw(); @endcode
+  [[nodiscard]] constexpr VALUE raw() const noexcept { return raw_; }
+
+  /// @brief Returns whether this value is nil.
+  /// @code if (wrapped.is_nil()) { return; } @endcode
+  [[nodiscard]] constexpr bool is_nil() const noexcept { return NIL_P(raw_); }
+
+  /// @brief Returns whether this value is a Ruby boolean.
+  [[nodiscard]] constexpr bool is_bool() const noexcept { return raw_ == Qtrue || raw_ == Qfalse; }
+
+  /// @brief Returns whether this value is a Ruby Integer.
+  [[nodiscard]] bool is_integer() const noexcept { return RB_INTEGER_TYPE_P(raw_); }
+
+  /// @brief Returns whether this value is a Ruby Float.
+  [[nodiscard]] bool is_float() const noexcept { return RB_TYPE_P(raw_, T_FLOAT); }
+
+  /// @brief Returns whether this value is a Ruby String.
+  [[nodiscard]] bool is_string() const noexcept { return RB_TYPE_P(raw_, T_STRING); }
+
+  /// @brief Returns whether this value is a Ruby Symbol.
+  [[nodiscard]] bool is_symbol() const noexcept { return SYMBOL_P(raw_); }
+
+  /// @brief Returns whether this value is a Ruby Array.
+  [[nodiscard]] bool is_array() const noexcept { return RB_TYPE_P(raw_, T_ARRAY); }
+
+  /// @brief Returns whether this value is a Ruby Hash.
+  [[nodiscard]] bool is_hash() const noexcept { return RB_TYPE_P(raw_, T_HASH); }
+
+private:
+  VALUE raw_ = Qnil;
+};
+
+static_assert(std::is_trivially_copyable_v<value>);
+static_assert(sizeof(value) == sizeof(VALUE));
+
+/// @brief Keeps a temporary Ruby value visible to the conservative GC.
+/// @code rbxx::gc_guard(value); @endcode
+inline void gc_guard(value guarded) noexcept {
+  VALUE raw = guarded.raw();
+  RB_GC_GUARD(raw);
+}
+
+} // namespace rbxx

data/include/rbxx/version.hpp

@@ -0,0 +1,14 @@
+#pragma once
+
+#define RBXX_VERSION_MAJOR 0
+#define RBXX_VERSION_MINOR 1
+#define RBXX_VERSION_PATCH 0
+#define RBXX_VERSION "0.1.0"
+
+namespace rbxx {
+
+/// @brief The rbxx semantic version string.
+/// @code auto version = rbxx::version; @endcode
+inline constexpr const char* version = RBXX_VERSION;
+
+} // namespace rbxx

data/lib/rbxx/cli.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "erb"
+require "fileutils"
+require "optparse"
+
+module Rbxx
+  # Command-line project generator for source and CMake-based native gems.
+  class CLI
+    TEMPLATE_ROOT = File.expand_path("../../templates", __dir__)
+
+    def self.start(arguments, out: $stdout, err: $stderr)
+      new(arguments.dup, out:, err:).run
+    rescue OptionParser::ParseError, ArgumentError => e
+      err.puts(e.message)
+      1
+    end
+
+    def initialize(arguments, out:, err:)
+      @arguments = arguments
+      @out = out
+      @err = err
+    end
+
+    def run
+      command = @arguments.shift
+      return create_project if command == "new"
+
+      raise ArgumentError, "usage: rbxx new NAME [--cmake]"
+    end
+
+    private
+
+    def create_project
+      options = parse_options
+      name = @arguments.shift
+      validate_name(name)
+      raise ArgumentError, "unexpected arguments: #{@arguments.join(' ')}" unless @arguments.empty?
+
+      project = Project.new(name:, cmake: options[:cmake], rbxx_path: options[:rbxx_path])
+      project.generate
+      @out.puts("Created #{project.destination}")
+      0
+    end
+
+    def parse_options
+      options = { cmake: false, rbxx_path: nil }
+      OptionParser.new do |parser|
+        parser.on("--cmake") { options[:cmake] = true }
+        parser.on("--rbxx-path PATH") { |path| options[:rbxx_path] = File.expand_path(path) }
+      end.parse!(@arguments)
+      options
+    end
+
+    def validate_name(name)
+      return if name&.match?(/\A[a-z][a-z0-9_]*\z/)
+
+      raise ArgumentError, "NAME must use lowercase letters, digits, and underscores"
+    end
+
+    # Rendering context for one generated gem project.
+    class Project
+      attr_reader :destination
+
+      def initialize(name:, cmake:, rbxx_path:)
+        @name = name
+        @cmake = cmake
+        @rbxx_path = rbxx_path
+        @destination = File.expand_path(name)
+      end
+
+      def generate
+        raise ArgumentError, "destination already exists: #{destination}" if File.exist?(destination)
+
+        templates.each do |source, relative_destination|
+          render(source, File.join(destination, relative_destination))
+        end
+      end
+
+      def class_name
+        @name.split("_").map(&:capitalize).join
+      end
+
+      def rbxx_gem_line
+        return %(gem "rbxx", path: #{@rbxx_path.inspect}) if @rbxx_path
+
+        %(gem "rbxx", "~> 0.1")
+      end
+
+      private
+
+      attr_reader :name
+
+      def templates
+        common_templates.merge(build_templates)
+      end
+
+      def common_templates
+        {
+          "Gemfile.erb" => "Gemfile",
+          "gemspec.erb" => "#{name}.gemspec",
+          "Rakefile.erb" => "Rakefile",
+          "README.md.erb" => "README.md",
+          "extension.cpp.erb" => "ext/#{name}/#{name}.cpp",
+          "lib.rb.erb" => "lib/#{name}.rb",
+          "version.rb.erb" => "lib/#{name}/version.rb",
+          "test.rb.erb" => "test/test_#{name}.rb",
+          "ci.yml.erb" => ".github/workflows/ci.yml",
+          "release.yml.erb" => ".github/workflows/release.yml"
+        }
+      end
+
+      def build_templates
+        extconf = @cmake ? "extconf_cmake.rb.erb" : "extconf.rb.erb"
+        result = { extconf => "ext/#{name}/extconf.rb" }
+        result["CMakeLists.txt.erb"] = "ext/#{name}/CMakeLists.txt" if @cmake
+        result
+      end
+
+      def render(source, target)
+        FileUtils.mkdir_p(File.dirname(target))
+        template = File.read(File.join(TEMPLATE_ROOT, source))
+        File.write(target, ERB.new(template, trim_mode: "-").result(binding))
+      end
+    end
+  end
+end