rudy4 0.2.0

data/test/rudy4_test.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+# Gem-level tests for the `rudy4` command: the scaffolder, the doctor, and the
+# vendor refresh. Plain Ruby — no test framework, run it with:
+#
+#   ruby -Ilib test/rudy4_test.rb            # scaffolding + CLI (fast)
+#   RUDY4_FULL=1 ruby -Ilib test/rudy4_test.rb   # + real GDC build (slow)
+#
+# The full build test is what CI runs: it scaffolds a project from the gem and
+# drives `rake test` inside it, which is exactly the path a new user takes.
+
+require "fileutils"
+require "open3"
+require "rbconfig"
+require "stringio"
+require "tmpdir"
+
+require "rudy4"
+
+$checks = 0
+$failures = []
+
+def assert(cond, msg)
+  $checks += 1
+  return if cond
+
+  $failures << msg
+  puts "  FAIL: #{msg}"
+end
+
+def assert_equal(expected, actual, msg)
+  assert(expected == actual, "#{msg} (expected #{expected.inspect}, got #{actual.inspect})")
+end
+
+def section(name)
+  puts "\n== #{name}"
+end
+
+def run_cli(*argv)
+  out = StringIO.new
+  err = StringIO.new
+  status = Rudy4::CLI.new(argv, out: out, err: err).run
+  [status, out.string, err.string]
+end
+
+RUBY = RbConfig.ruby
+
+# ---------------------------------------------------------------------------
+section "CLI: version and help"
+
+status, out, = run_cli("--version")
+assert_equal 0, status, "--version exit status"
+assert_equal Rudy4::VERSION, out.strip, "--version prints the version"
+
+status, out, = run_cli("help")
+assert_equal 0, status, "help exit status"
+assert(out.include?("rudy4 init NAME"), "help documents init")
+assert(out.include?("rudy4 doctor"), "help documents doctor")
+assert(out.include?("rake compile"), "help shows the getting-started loop")
+
+status, out, = run_cli(nil)
+assert_equal 0, status, "bare invocation prints usage and exits 0"
+assert(out.include?("Usage:"), "bare invocation prints usage")
+
+status, _out, err = run_cli("frobnicate")
+assert_equal Rudy4::CLI::EXIT_USAGE, status, "unknown command is a usage error"
+assert(err.include?("unknown command"), "unknown command is reported")
+
+status, _out, err = run_cli("init", "whatever", "--quick")
+assert_equal Rudy4::CLI::EXIT_USAGE, status, "--quick is rejected for init"
+assert(err.include?("not valid"), "invalid option is reported")
+
+# ---------------------------------------------------------------------------
+section "init: scaffold contents"
+
+Dir.mktmpdir("rudy4-gem-test-") do |tmp|
+  status, out, err = run_cli("init", "fast_math", "-h")
+  assert_equal 0, status, "init -h prints usage"
+
+  status, out, err = run_cli("init", "fast_math")
+  assert_equal 0, status, "init exits 0 (err: #{err})"
+
+  root = File.join(tmp, "fast_math")
+
+  # The generator ran in Dir.pwd, so move it into the tmpdir to keep $PWD clean.
+  # (CLI uses Dir.pwd by design, so we exercise it there and clean up after.)
+  expected = [
+    "fast_math.gemspec",
+    "Rakefile",
+    "README.md",
+    ".gitignore",
+    "lib/fast_math.rb",
+    "lib/fast_math/version.rb",
+    "ext/fast_math/fast_math.d",
+    "ext/fast_math/extconf.rb",
+    "ext/fast_math/rudy/defs.d",
+    "ext/fast_math/rudy/bind/value.d",
+    "ext/fast_math/rudy/convert.d",
+    "ext/fast_math/rudy/args.d",
+    "ext/fast_math/rudy/objproto.d",
+    "ext/fast_math/rudy/typeddata.d",
+    "test/fast_math_test.rb",
+  ]
+  expected.each do |rel|
+    assert(File.file?(File.join("fast_math", rel)), "generated #{rel}")
+  end
+
+  assert(out.include?("Created fast_math/"), "init reports what it created")
+  assert(out.include?("rake compile"), "init prints the next steps")
+
+  # No leftover template placeholders anywhere.
+  Dir.glob("fast_math/**/*").select { |f| File.file?(f) }.each do |file|
+    body = File.read(file)
+    %w[PROJECT_NAME PROJECT_CONST RUBY_REQ AUTHOR EMAIL].each do |token|
+      assert(!body.include?(token), "#{file} has no unresolved #{token} placeholder")
+    end
+  end
+
+  # The extension name must be spliced consistently: Init_<name>_ext, module,
+  # gem name, and the artifact name are all the same project.
+  d_source = File.read("fast_math/ext/fast_math/fast_math.d")
+  assert(d_source.include?('pragma(mangle, "Init_fast_math_ext")'), "Init_ entry point named after the project")
+  assert(d_source.include?('module fast_math;'), "D module named after the project")
+  assert(d_source.include?('rb_define_module("FastMath")'), "Ruby module is the camelized name")
+  assert(d_source.include?('def!("FastMath", add)'), "def! targets the Ruby module")
+
+  extconf = File.read("fast_math/ext/fast_math/extconf.rb")
+  assert(extconf.include?("TARGET = fast_math_ext."), "artifact is <name>_ext, not <name>")
+  assert(extconf.include?('RUDY_SRC = File.join(HERE, "rudy")'),
+         "extconf uses the vendored rudy sources, not a checkout path")
+  assert(!extconf.include?("RUDY4_ROOT"), "extconf does not need RUDY4_ROOT")
+
+  gemspec = File.read("fast_math/fast_math.gemspec")
+  assert(gemspec.include?('spec.extensions = ["ext/fast_math/extconf.rb"]'),
+         "gemspec declares the D extension")
+
+  lib_rb = File.read("fast_math/lib/fast_math.rb")
+  assert(lib_rb.include?('require "fast_math_ext"'), "lib requires the _ext artifact")
+
+  FileUtils.rm_rf("fast_math")
+
+  # -------------------------------------------------------------------------
+  section "init: argument validation"
+
+  status, _out, err = run_cli("init")
+  assert_equal Rudy4::CLI::EXIT_USAGE, status, "init without a name is a usage error"
+  assert(err.include?("usage: rudy4 init NAME"), "missing name shows usage")
+
+  status, _out, err = run_cli("init", "fast-math")
+  assert_equal Rudy4::CLI::EXIT_ERROR, status, "hyphenated name is rejected"
+  assert(err.include?("snake_case"), "hyphenated name explains the rule")
+
+  status, _out, err = run_cli("init", "FastMath")
+  assert_equal Rudy4::CLI::EXIT_ERROR, status, "capitalized name is rejected"
+
+  status, _out, err = run_cli("init", "ruby")
+  assert_equal Rudy4::CLI::EXIT_ERROR, status, "reserved name is rejected"
+  assert(err.include?("reserved"), "reserved name explains why")
+
+  status, _out, err = run_cli("init", "fast_math", "extra")
+  assert_equal Rudy4::CLI::EXIT_USAGE, status, "extra arguments are rejected"
+
+  # -------------------------------------------------------------------------
+  section "init: existing directory handling"
+
+  Dir.mktmpdir("rudy4-existing-") do |dir|
+    FileUtils.mkdir_p(File.join(dir, "taken"))
+    File.write(File.join(dir, "taken", "precious.txt"), "do not clobber")
+
+    generator = Rudy4::Generator.new("taken", parent_dir: dir, out: StringIO.new)
+    begin
+      generator.call
+      assert(false, "refuses to overwrite a non-empty directory")
+    rescue Rudy4::Error => e
+      assert(e.message.include?("already exists"), "existing directory is reported")
+      assert(e.message.include?("--force"), "the error suggests --force")
+    end
+
+    assert_equal "do not clobber", File.read(File.join(dir, "taken", "precious.txt")),
+                 "existing files are untouched"
+
+    forced = Rudy4::Generator.new("taken", parent_dir: dir, force: true, out: StringIO.new)
+    forced.call
+    assert(File.file?(File.join(dir, "taken", "taken.gemspec")), "--force writes into the directory")
+    assert(File.file?(File.join(dir, "taken", "precious.txt")), "--force does not delete existing files")
+  end
+
+  # -------------------------------------------------------------------------
+  section "vendor: refresh an existing project"
+
+  status, _out, err = run_cli("init", "vendored_app")
+  assert_equal 0, status, "scaffold a project for the vendor test (err: #{err})"
+
+  ext_dir = File.join("vendored_app", "ext", "vendored_app")
+  sentinel = File.join(ext_dir, "rudy", "defs.d")
+  File.write(sentinel, "// stale, hand-mangled copy")
+  File.write(File.join(ext_dir, "vendored_app.d"), "// user code — must not be touched")
+
+  Dir.chdir(ext_dir) do
+    status, out, err = run_cli("vendor")
+    assert_equal 0, status, "vendor exits 0 (err: #{err})"
+    assert(out.include?("Refreshed"), "vendor reports what it refreshed")
+  end
+
+  assert(!File.read(sentinel).include?("stale"), "vendor overwrites the stale vendored source")
+  assert_equal Rudy4::Vendor.d_sources.length,
+               Dir.glob(File.join(ext_dir, "rudy", "**", "*.d")).length,
+               "vendor restores every vendored source"
+  assert_equal "// user code — must not be touched",
+               File.read(File.join(ext_dir, "vendored_app.d")),
+               "vendor leaves user code alone"
+
+  FileUtils.rm_rf("vendored_app")
+
+  # -------------------------------------------------------------------------
+  section "doctor: quick checks"
+
+  Dir.mktmpdir("rudy4-doctor-") do |dir|
+    Dir.chdir(dir) do
+      out = StringIO.new
+      status = Rudy4::Doctor.new(quick: true, out: out).call
+      text = out.string
+
+      assert(text.include?("rudy4 doctor"), "doctor prints a header")
+      assert(text.include?("ruby headers"), "doctor checks ruby headers")
+      assert(text.include?("shared libruby"), "doctor checks the shared library")
+      assert(text.include?("gdc (D compiler)"), "doctor checks GDC")
+      assert(text.include?("vendored rudy4 sources"), "doctor checks the vendored sources")
+      assert(!text.include?("build smoke test"), "--quick skips the build probe")
+
+      gdc_ok = !text.include?("[fail] gdc")
+      headers_ok = !text.include?("[fail] ruby headers")
+      if gdc_ok && headers_ok
+        assert_equal 0, status, "doctor exits 0 on a healthy toolchain"
+      else
+        assert_equal 1, status, "doctor exits 1 when the toolchain is missing"
+      end
+    end
+  end
+end
+
+# ---------------------------------------------------------------------------
+if ENV["RUDY4_FULL"] == "1"
+  section "end-to-end: scaffold, GDC build, generated test suite (slow)"
+
+  Dir.mktmpdir("rudy4-e2e-") do |dir|
+    Dir.chdir(dir) do
+      status, _out, err = run_cli("init", "fast_math")
+      assert_equal 0, status, "init for the e2e build (err: #{err})"
+
+      # The exact path a new user runs.
+      out, build_status = Open3.capture2e({ "GDC" => ENV["GDC"] || "gdc-14" },
+                                          "rake", "test",
+                                          chdir: File.join(dir, "fast_math"))
+      puts out
+      assert(build_status.success?, "rake test succeeds in the generated project")
+
+      lib = File.join(dir, "fast_math", "lib", "fast_math_ext.#{RbConfig::CONFIG['DLEXT']}")
+      assert(File.file?(lib), "rake compile installs the artifact into lib/")
+
+      probe, probe_status = Open3.capture2e(
+        RUBY, "-I#{File.dirname(lib)}", "-e",
+        'require "fast_math"; print FastMath.squares(3).inspect',
+      )
+      assert_equal "[0.0, 1.0, 4.0]", probe.strip, "the built extension is loadable and correct"\
+        if probe_status.success?
+      assert(probe_status.success?, "loading the built extension succeeds")
+
+      # `rake` + no build residue tracked by the gem's own .gitignore.
+      gitignore = File.read(File.join(dir, "fast_math", ".gitignore"))
+      assert(gitignore.include?("/lib/*.so"), ".gitignore covers built artifacts")
+
+      # And the doctor, end to end, inside the generated project.
+      out = StringIO.new
+      status = Rudy4::Doctor.new(out: out).call
+      puts out.string
+      assert_equal 0, status, "doctor reports a healthy setup inside a generated project"
+    end
+  end
+end
+
+# ---------------------------------------------------------------------------
+puts
+if $failures.empty?
+  puts "rudy4 gem tests: #{$checks} assertions OK"
+  exit 0
+else
+  puts "rudy4 gem tests: #{$checks} assertions, #{$failures.length} FAILED"
+  $failures.each { |f| puts "  - #{f}" }
+  exit 1
+end

data/test/run.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# Acceptance suite for rudy-d's dextest extension (dexter revival, 2010 -> 2026).
+
+require_relative "dextest_loader"
+
+$failures = 0
+$count = 0
+
+def assert(cond, msg)
+  $count += 1
+  if cond
+    puts "ok #{$count} - #{msg}"
+  else
+    $failures += 1
+    puts "FAIL #{$count} - #{msg}"
+  end
+end
+
+def assert_equal(expected, actual, msg = nil)
+  assert(expected == actual, "#{msg || 'equal'}: expected #{expected.inspect}, got #{actual.inspect}")
+end
+
+def assert_raises(exp)
+  yield
+  assert(false, "expected #{exp} to be raised")
+rescue exp
+  assert(true, "raised #{exp}")
+rescue => e
+  assert(false, "expected #{exp}, got #{e.class}")
+end
+
+# ---------------------------------------------------------------- raw C API class
+d = DexterClass.new
+assert_equal(Class, DexterClass.class, "DexterClass is a class")
+assert_equal(Object, DexterClass.superclass, "DexterClass < Object")
+assert_equal(10, d.return_ten, "return_ten")
+assert_equal([], d.arr, "arr starts empty")
+d.add(1); d.add(2)
+assert_equal([1, 2], d.arr, "add pushes raw VALUEs")
+d.native_add(22)
+assert_equal([1, 2, 23], d.arr, "native_add converts via num2long/ll2inum")
+d.add_strings_first_letter("showtime!")
+assert_equal([1, 2, 23, "s"], d.arr, "add_strings_first_letter")
+
+# ---------------------------------------------------------------- def! globals
+assert_equal(15, the_new_fifteen, "def! global function")
+assert_equal(33, convert_integer_two_ways(33), "def! integer round trip")
+assert_equal(45.67, convert_float_two_ways(45.67), "def! float round trip")
+assert_equal("somestring", convert_string_two_ways("somestring"), "def! string round trip")
+assert_equal(true, convert_bool_two_ways(true), "def! bool true round trip")
+assert_equal(false, convert_bool_two_ways(false), "def! bool false round trip")
+assert_equal(17, add_five(12), "def! computed int")
+assert_equal("hi tomash 42", DexterModule.greet("tomash", 42), "def! module function, 2 args, mixed types")
+
+# ---------------------------------------------------------------- issue #1 regression: ulong params decode, Raw!VALUE passes bits
+assert_equal(10, identity_ulong(10), "def! ulong param decodes (not tagged)")
+assert_equal(0, identity_ulong(0), "def! ulong zero decodes")
+assert_equal(20, double_it_ulong(10), "def! ulong param arithmetic")
+assert_equal(10, raw_value_id(10), "def! Raw!VALUE passthrough identity")
+assert_equal("abc", raw_value_id("abc"), "def! Raw!VALUE passthrough string object")
+
+# ---------------------------------------------------------------- arity / errors
+assert_raises(ArgumentError) { convert_integer_two_ways }        # wrong arity
+assert_raises(TypeError) { convert_integer_two_ways("nope") }    # bad conversion
+
+# ---------------------------------------------------------------- results
+puts
+if $failures.zero?
+  puts "PASS: all #{$count} assertions green"
+  exit 0
+else
+  puts "FAIL: #{$failures}/#{$count} assertions failed"
+  exit 1
+end

data/test/typedtest.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# Acceptance suite for the typed-data extension (rudy/typeddata.d).
+# Exercises: wrap/unwrap via TypedData API (rb_data_typed_object_wrap /
+# rb_check_typeddata), alloc func, det, GC stress, TypeError on bad unwrap.
+
+require "pathname"
+EXT = Pathname.new(__dir__).parent + ".build" + "dtypetest.so"
+raise "extension not built: run `make` first" unless EXT.exist?
+require EXT.to_s
+
+$failures = 0
+$count = 0
+
+def assert(cond, msg)
+  $count += 1
+  if cond then puts "ok #{$count} - #{msg}"
+  else $failures += 1; puts "FAIL #{$count} - #{msg}" end
+end
+
+def assert_equal(expected, actual, msg = nil)
+  assert(expected == actual, "#{msg || 'equal'}: expected #{expected.inspect}, got #{actual.inspect}")
+end
+
+def assert_raises(exp)
+  yield
+  assert(false, "expected #{exp} to be raised")
+rescue exp
+  assert(true, "raised #{exp}")
+rescue => e
+  assert(false, "expected #{exp}, got #{e.class}: #{e.message}")
+end
+
+# ---------------------------------------------------------------- basics
+m = DTypeMatrix.new(3, 3)
+assert_equal(9, DTypeMatrix.allocate.unwrap_other(m), "typed wrap/unwrap round trip")
+[[2, 0, 1], [0, 3, 0], [1, 0, 2]].each_with_index do |row, r|
+  row.each_with_index { |v, c| m[r, c] = v }
+end
+assert_equal([[2, 0, 1], [0, 3, 0], [1, 0, 2]], m.to_a, "to_a returns matrix contents")
+assert((m.det - 9.0).abs < 1e-9, "3x3 det == 9.0 (Laplace, recursion)")
+assert_equal(24, DTypeTest::SIZEOF, "sizeof Matrix struct exposed (2*8 + 8 == 24 on LP64)")
+
+# 10x10 identity perturbation — deep det recursion
+big = DTypeMatrix.new(10, 10)
+10.times { |r| 10.times { |c| big[r, c] = (r == c) ? 1.0 : 0.0 } }
+big[3, 3] = 3.5
+big[7, 0] = 2.0
+assert((big.det - 3.5).abs < 1e-9, "10x10 identity det with [3,3]=3.5")
+
+# ---------------------------------------------------------------- TypeError
+assert_raises(TypeError) { DTypeMatrix.allocate.unwrap_other("not a matrix") }
+assert_raises(TypeError) { DTypeMatrix.allocate.unwrap_other(42) }
+assert_raises(TypeError) { DTypeMatrix.allocate.unwrap_other(DTypeMatrix) }
+
+# ---------------------------------------------------------------- GC stress
+before = `ps -o rss= -p #{Process.pid}`.to_i
+m2 = DTypeMatrix.new(4, 4)
+m2.stress(100_000)
+after = `ps -o rss= -p #{Process.pid}`.to_i
+assert(after - before < 50_000, "100k typed wrap/free cycles: RSS delta #{after - before} KB < 50 MB")
+
+puts
+if $failures.zero?
+  puts "PASS: all #{$count} assertions green"
+  exit 0
+else
+  puts "FAIL: #{$failures}/#{$count} assertions failed"
+  exit 1
+end

data/vendor/rudy/args.d

@@ -0,0 +1,253 @@
+/// Parameter wrappers for `def!` (rudy/defs.d) that reach past the
+/// plain positional-argument model. The 2010 RuDy had none of these;
+/// a `def!`'d function could neither receive the caller's block nor
+/// take rest/keyword arguments.
+///
+///     void with_block(RubyBlock blk)   { blk.call(42); }  // receives the
+///                                                         // caller's block
+///     long rest_sum(long first, Rest rest) { ... }        // 1 + *rest
+///     D str_kw(KwArgs kw) { kw.get!string("sep", "-") }   // **kwargs
+///
+/// All wrappers are VALUE-sized (passable as fixed-arity C args); the
+/// interesting VALUE lives inside (block proc, rest array, kwargs
+/// hash). See defs.d for how the trampolines populate them.
+
+module rudy.args;
+
+import rudy.bind.value;
+import rudy.convert;
+import std.string : toStringz;
+
+// lazily-interned method names (rb_intern on every call is a symbol-table
+// hash probe; the VM is alive inside any method call, so lazy init is safe)
+private __gshared ID rudy_id_call;
+private __gshared ID rudy_id_arity;
+private __gshared ID rudy_id_length;
+private __gshared ID rudy_id_to_a;
+private __gshared ID rudy_id_to_s;
+
+private ID id_call()   { if (!rudy_id_call)   rudy_id_call   = rb_intern("call");   return rudy_id_call;   }
+private ID id_arity()  { if (!rudy_id_arity)  rudy_id_arity  = rb_intern("arity");  return rudy_id_arity;  }
+private ID id_length() { if (!rudy_id_length) rudy_id_length = rb_intern("length"); return rudy_id_length; }
+private ID id_to_a()   { if (!rudy_id_to_a)   rudy_id_to_a   = rb_intern("to_a");   return rudy_id_to_a;   }
+private ID id_to_s()   { if (!rudy_id_to_s)   rudy_id_to_s   = rb_intern("to_s");   return rudy_id_to_s;   }
+
+// ---------------------------------------------------------------- RubyBlock
+
+/// A caller's block, materialized as a Proc. `def!` fills it in via
+/// rb_scan_args' "&" slot inside the trampoline (Qnil when no block was
+/// passed), before the D function runs.
+///
+///   blk.call(args...)   — invoke the block
+///   blk.arity           — the Proc's arity
+///   blk.given           — was a block actually passed?
+///
+/// A block-less method raises LocalJumpError from Ruby the moment
+/// call() runs — same failure mode as bare `yield` in Ruby. Check
+/// `given` first when that must not happen.
+struct RubyBlock
+{
+    VALUE proc = Qnil_;
+
+    /// Was a block actually passed to this method?
+    bool given() const @safe pure nothrow @nogc { return proc != Qnil_; }
+
+    /// The wrapped Proc, as raw VALUE (for API-passing scenarios).
+    Raw!VALUE raw() const @safe pure nothrow @nogc { return Raw!VALUE(proc); }
+
+    /// Number of arguments the block expects (Proc#arity).
+    long arity() { return d_type!long(rb_funcallv(proc, id_arity(), 0, null)); }
+
+    /// Call the block with args; returns whatever the block returned.
+    /// LocalJumpError (from Ruby) if called with no block given; any
+    /// exception the block raises propagates straight through the D frame.
+    VALUE call() { return lje_or_call(proc, 0, null); }
+
+    VALUE call(VALUE a1)
+    {
+        VALUE[1] av = [a1];
+        return lje_or_call(proc, 1, av.ptr);
+    }
+
+    VALUE call(VALUE a1, VALUE a2)
+    {
+        VALUE[2] av = [a1, a2];
+        return lje_or_call(proc, 2, av.ptr);
+    }
+
+    VALUE call(VALUE a1, VALUE a2, VALUE a3)
+    {
+        VALUE[3] av = [a1, a2, a3];
+        return lje_or_call(proc, 3, av.ptr);
+    }
+
+    /// Call with a pre-built argv (n args).
+    VALUE callv(int n, const(VALUE)* argv)
+    {
+        return lje_or_call(proc, n, cast(VALUE*) argv);
+    }
+}
+
+/// RubyBlock#call contract helper: a block-less call is the same error
+/// a bare `yield` with no block would give (rb_funcallv on Qnil would
+/// give a misleading NoMethodError instead).
+private VALUE lje_or_call(VALUE proc, int n, VALUE* argv)
+{
+    if (proc == Qnil_)
+        rb_raise(rb_eLocalJumpError, "no block given (yield)");
+    return rb_funcallv(proc, id_call(), n, argv);
+}
+
+// ---------------------------------------------------------------- Self
+
+/// The method's receiver (self), passed through raw. First-parameter
+/// convention; lets def!'d functions inspect the object they were
+/// called on (class, ivars, singleton-ness) without dropping to a
+/// hand-written trampoline.
+///
+///   long klass_name(Self self) { ... rb_obj_class(self.v) ... }
+struct Self
+{
+    VALUE v = Qnil_;
+
+    /// The receiver as raw VALUE.
+    Raw!VALUE raw() const @safe pure nothrow @nogc { return Raw!VALUE(v); }
+
+    /// implicit conversion so `self.v` and passing Self around stays terse
+    VALUE value() const @safe pure nothrow @nogc { return v; }
+}
+
+// ---------------------------------------------------------------- Rest
+
+/// Captured `*rest` arguments, as a Ruby Array. The trampoline owns the
+/// VALUE (GC-rooted for the call's duration); the D function sees this
+/// slice-style wrapper.
+struct Rest
+{
+    VALUE ary = Qnil_;
+
+    /// Number of captured rest arguments (0 for an unused slot).
+    @property size_t length() const
+    {
+        if (ary == Qnil_)
+            return 0;
+        return cast(size_t) d_type!long(rb_funcallv(ary, id_length(), 0, null));
+    }
+
+    /// True when nothing was captured. NB: rb_scan_args' "*" slot fills
+    /// an EMPTY ARRAY (not Qnil) when the caller passes zero rest args —
+    /// this must agree with Ruby-side `rest.empty?`, so it checks the
+    /// length, not just the slot's Qnil-ness.
+    bool empty() { return length == 0; }
+
+    /// i-th captured argument (0-based).
+    VALUE opIndex(size_t i)
+    {
+        return rb_ary_entry(ary, cast(long) i);
+    }
+
+    /// Iterate the captured arguments (foreach over a Rest works).
+    int opApply(scope int delegate(ref VALUE) dg)
+    {
+        long n = cast(long) length;
+        foreach (i; 0 .. n)
+        {
+            VALUE v = rb_ary_entry(ary, i);
+            int r = dg(v);
+            if (r)
+                return r;
+        }
+        return 0;
+    }
+
+    /// The raw Ruby Array, as raw VALUE.
+    Raw!VALUE raw() const @safe pure nothrow @nogc { return Raw!VALUE(ary); }
+
+    /// Convert every captured arg to D type T (allocates a D array).
+    T[] to(T)()
+    {
+        long n = cast(long) length;
+        T[] outv;
+        outv.length = cast(size_t) n;
+        foreach (i; 0 .. n)
+            outv[cast(size_t) i] = d_type!T(rb_ary_entry(ary, i));
+        return outv;
+    }
+}
+
+// ---------------------------------------------------------------- KwArgs
+
+/// Captured keyword arguments, as a Ruby Hash. `def!` fills it via
+/// rb_scan_args' `:` slot (Qnil_ when no keywords were passed — see
+/// `given`).
+///
+///   kw.get!long("sep", 1)     — decoded with a D default when absent
+///   kw["sep"]                 — raw VALUE (Qnil_ when absent)
+///   kw.to!(long, string)()    — whole hash as a D AA
+struct KwArgs
+{
+    VALUE hash = Qnil_;
+
+    /// Were any keywords passed?
+    bool given() const @safe pure nothrow @nogc { return hash != Qnil_; }
+
+    /// Raw value of keyword `key` (Qnil_ when absent). Ruby keyword keys
+    /// are Symbols (`m(sep: x)`), but string keys are legal too
+    /// (`m("sep": x)` / string-keyed **hash) — probe both.
+    VALUE opIndex(string key)
+    {
+        if (!given)
+            return Qnil_;
+        ID id = rb_intern(toStringz(key));
+        VALUE v = rb_hash_lookup2(hash, rb_id2sym(id), Qnil_);
+        if (v != Qnil_)
+            return v;
+        VALUE[1] av = [rb_str_new(key.ptr, cast(C_long) key.length)];
+        return rb_hash_lookup2(hash, av[0], Qnil_);
+    }
+
+    /// Keyword decoded to D type T; `dflt` when the keyword was absent.
+    T get(T)(string key, T dflt)
+    {
+        VALUE v = opIndex(key);
+        if (v == Qnil_ || v == Qundef_)
+            return dflt;
+        return d_type!T(v);
+    }
+
+    /// All keywords as a D associative array (empty when none passed).
+    V[K] to(V, K)()
+    {
+        V[K] outv;
+        if (!given)
+            return outv;
+        // Hash#to_a -> [[k, v], ...]: plain exported-API walking, no
+        // callbacks (rb_block_call's return value can't accumulate).
+        VALUE pairs = rb_funcallv(hash, id_to_a(), 0, null);
+        long n = d_type!long(rb_funcallv(pairs, id_length(), 0, null));
+        foreach (i; 0 .. n)
+        {
+            VALUE pair = rb_ary_entry(pairs, i);
+            VALUE k = rb_ary_entry(pair, 0);
+            static if (is(K == string))
+            {
+                // kwargs keys are normally Symbols; d_type!string of a
+                // Symbol raises TypeError. Normalize through to_s
+                // (Symbol#to_s -> name String, String#to_s -> self) so
+                // string-keyed D AAs see every key. Non-string K keys
+                // go through d_type directly.
+                k = rb_funcallv(k, id_to_s(), 0, null);
+            }
+            static if (is(V == Raw!VALUE))
+            {
+                // raw VALUE escape hatch: bits unchanged, no decode
+                outv[d_type!K(k)] = Raw!VALUE(rb_ary_entry(pair, 1));
+            }
+            else
+            {
+                outv[d_type!K(k)] = d_type!V(rb_ary_entry(pair, 1));
+            }
+        }
+        return outv;
+    }
+}