galaaz 0.4.10 → 2.0.0

data/lib/R_interface/robject.rb

@@ -1,351 +1,409 @@
-# -*- coding: utf-8 -*-
-
-##########################################################################################
-# @author Rodrigo Botafogo
+# robject.rb
 #
-# Copyright © 2018 Rodrigo Botafogo. All Rights Reserved. Permission to use, copy, modify, 
-# and distribute this software and its documentation, without fee and without a signed 
-# licensing agreement, is hereby granted, provided that the above copyright notice, this 
-# paragraph and the following two paragraphs appear in all copies, modifications, and 
-# distributions.
+# R::Object is the Ruby proxy for an R value. It inherits from BasicObject so that most
+# method calls (e.g. .dim, .names, .length) are forwarded to R via method_missing.
 #
-# IN NO EVENT SHALL RODRIGO BOTAFOGO BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, 
-# INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF 
-# THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF RODRIGO BOTAFOGO HAS BEEN ADVISED OF THE 
-# POSSIBILITY OF SUCH DAMAGE.
+# Each instance holds @r_interop (the R-side handle, e.g. "g2_v42") and optionally
+# @expression (source expression for Language objects). Object.build(...) turns a handle
+# into the appropriate subclass: DataFrame, Matrix, Vector, List, Closure, RSymbol,
+# RExpression, or a plain Object for other R types. Handles "rb_obj_*" are unwrapped
+# to the stored Ruby object; R NULL becomes Ruby nil.
 #
-# RODRIGO BOTAFOGO SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
-# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE 
-# SOFTWARE AND ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED HEREUNDER IS PROVIDED "AS IS". 
-# RODRIGO BOTAFOGO HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, 
-# OR MODIFICATIONS.
-##########################################################################################
-
 require_relative 'r_methods'
 
 module R
-  
-  #--------------------------------------------------------------------------------------
-  # 
-  #--------------------------------------------------------------------------------------
+  class Object < BasicObject
+    include IndexedObject
+    include BinaryOperators
+    include ExecBinOp
+    include UnaryOperators
+    include ExecUniOp
+
+    # Methods we explicitly define (Phase A / BasicObject). respond_to?(sym) is true for these and for any symbol we forward to R.
+    EXPLICIT_RUBY_SURFACE = [
+      :r_interop, :expression, :expression=,
+      :[], :[]=, :>>, :unboxed_get, :to_ruby, :to_i, :to_ary, :length, :size,
+      :class, :to_s, :rclass, :typeof, :inspect, :object_id, :__id__,
+      :==, :equal?, :call, :nil?, :pretty_print, :send,
+      :instance_variable_set, :instance_variable_get,
+      :is_a?, :kind_of?, :instance_of?, :respond_to?,
+      :method_missing
+    ].freeze
 
-  class Object
-    
     attr_reader :r_interop
-    attr_accessor :statement
-    
-    #--------------------------------------------------------------------------------------
-    #
-    #--------------------------------------------------------------------------------------
+    attr_accessor :expression
 
-    def initialize(r_interop)
-      @r_interop = r_interop
+    # Delegate to Kernel#instance_variable_set so that instance vars work despite BasicObject.
+    def instance_variable_set(name, value)
+      ::Object.instance_method(:instance_variable_set).bind(self).call(name, value)
     end
 
-    #--------------------------------------------------------------------------------------
-    # Checks for equality between two R::Objects.  This method is used by rspec's
-    # expectation. It returns a Ruby true or false and not an R::Vector with [TRUE] or
-    # [FALSE]
-    #--------------------------------------------------------------------------------------
-
-    def ==(other_object)
-      res =
-        R::Support.exec_function_name('identical', @r_interop,
-                                      R::Support.parse_arg(other_object))
-      return nil if (res.length >> 0) == 0
-      res >> 0
+    # Delegate to Kernel#instance_variable_get so that instance vars work despite BasicObject.
+    def instance_variable_get(name)
+      ::Object.instance_method(:instance_variable_get).bind(self).call(name)
     end
 
-    #--------------------------------------------------------------------------------------
-    # Use eql to check for equality between two objects and receive in return an R::Vector
-    #--------------------------------------------------------------------------------------
-
-    def eql(other_object)
-      # exec_bin_oper("`==`", other_object)
-      R::Support.exec_function_name("`==`", @r_interop,
-                                    R::Support.parse_arg(other_object))
+    # BasicObject lacks Kernel#send; provide Ruby dispatch explicitly so calls like
+    # obj.send(:mpg) do not get forwarded to R as send(obj, mpg).
+    def send(method_name, *args, &block)
+      ::Object.instance_method(:send).bind(self).call(method_name, *args, &block)
     end
-    
-    #--------------------------------------------------------------------------------------
-    # @param r_interop [Interop] pointer to an R object
-    # @return the R object wrapped in a Ruby class
-    #--------------------------------------------------------------------------------------
-
-    def self.build(r_interop)
-
-      # if the value is actually not an r_interop, then just return it: native Ruby
-      # object
-      if (!Truffle::Interop.foreign?(r_interop))
-        # puts "I'm native"
-        return r_interop
-      # a matrix is also a vector... test should come before
-      elsif (R::Support.eval("is.matrix").call(r_interop) == true)
-        # puts "1"
-        R::Matrix.new(r_interop)
-      elsif (R::Support.eval("is.atomic").call(r_interop) == true)
-        # puts "2"
-        Vector.new(r_interop)
-      elsif (R::Support.eval("is.function").call(r_interop) == true)
-        # puts "3"
-        Closure.new(r_interop)
-      elsif (R::Support.eval("is.data.frame").call(r_interop) == true)
-        # puts "4"
-        DataFrame.new(r_interop)
-      elsif (R::Support.eval("is.list").call(r_interop) == true)
-        # puts "5"
-        List.new(r_interop)
-      elsif (R::Support.eval("typeof").call(r_interop) == "language")
-        # @TODO: tests are passing both when we use Language.new
-        # and RExpression.new.  Check what should be and write
-        # discriminating tests.
-        # print "robject buid: language\n"
-        # R::Support.print_foreign(r_interop)
-        # puts "6"
-        Language.new(r_interop)
-        # RExpression.new(r_interop)
-      elsif (R::Support.eval("typeof").call(r_interop) == "expression")
-        # puts "7"
-        RExpression.new(r_interop)
-      elsif (R::Support.eval("typeof").call(r_interop) == "name")
-        # puts "8"
-        p "i'm of type name"
-        Name.new(r_interop)
-      elsif (R::Support.eval("typeof").call(r_interop) == "symbol")
-        # puts "9"
-        RSymbol.new(r_interop)
-      elsif (R::Support.eval("typeof").call(r_interop) == "environment")
-        # puts "10"
-        Environment.new(r_interop)
-      else # Generic type
-        # puts "11"
-        p "Generic type: #{R::Support.eval("typeof").call(r_interop).to_s}"
-        r_interop
-      end
 
+    # R objects are never nil; R NULL is converted to Ruby nil in Object.build.
+    def nil?
+      false
     end
 
-    #--------------------------------------------------------------------------------------
-    #
-    #--------------------------------------------------------------------------------------
-
-    def method_missing(symbol, *args, &block)
-      name = R::Support.convert_symbol2r(symbol)
-
-      # Need to raise a NoMethodError when method_missing is called by an implicit
-      # call to "to_ary".  The explanation for that is:
-      # Okay, I've found the source of the behaviour. IOOperations.puts will attempt to
-      # coerce an argument to an array and print its contents, and R::Vector responds to
-      # to_ary but returns the empty array which results in no output.
-      #
-      # Previously IOOperations.puts only checked the type of the argument, and did not
-      # attempt coercion, but that meant we didn't match MRI's behaviour and had some test
-      # failures in other gems. I'd suggest either removing the to_ary methods on
-      # R::Object and R::Vector or implementing them more fully. I see from the comments on
-      # those methods that you needed them for RSpec, it might worth seeing if those problems
-      # still occur and we can look a better way to resolve those.      
-      raise NoMethodError if name == "to_ary"
-
-      case
-      when block_given?
-        R::Support.new_scope(symbol, self, *args, &block)
-      when name =~ /(.*)=$/
-        method_missing_assign($1, args[0])
-      when name == "eval"
-        # R function 'eval' needs to be called in a special way, since it expects
-        # the second argument to be an environment.  If the arguments are packed
-        # into a list, then there is no second argument and the function fails to
-        # use the second argument as environment
-        R::Support.r_evaluate(@r_interop, *args)
-      when args.length == 0
-        # no arguments: 2 options: either a named item of the object or apply the function
-        # to the object
-        # if name is a named item of the object, then return the named item
-        named = R::Support.eval("`%in%`").
-                  call(name, R::Support.eval("names").call(@r_interop))
-        (false === named || !(true === named || named[0])) ?
-          R::Support.exec_function_name(name, @r_interop) :
-          R::Support.exec_function_name("`[[`", @r_interop, name)
-      else
-        args.unshift(@r_interop)
-        R::Support.exec_function_name(name, *args)
-      end
-        
+    # Used by pp/inspect-style pretty printing.
+    def pretty_print(pp)
+      pp.text(inspect)
     end
-    
-    #----------------------------------------------------------------------------------------
-    # We use the following notation to access binary R functions such as %in%:
-    # R.vec_ "in", list.
-    # @param args [Array] The first element of the array is an R infix function, the other
-    # arguments are the list of arguments for the function.
-    #----------------------------------------------------------------------------------------
-
-    def _(*args)
-      name = "`%#{args.shift.to_s}%`"
-      args.unshift(@r_interop)
-      R::Support.exec_function_name(name, *args)
+
+    def initialize(r_interop, expression = nil)
+      @r_interop = r_interop
+      @expression = expression
     end
 
-    #--------------------------------------------------------------------------------------
-    # Sets the current object self interop pointer to the returned value of the execution
-    # of the given method with arguments. This method should be called when R will copy
-    # the parameter, but in Ruby we want to hide the copying.
-    # @param [Interop] Interop pointer to R function
-    # @param [Array] Array of arguments 
-    #--------------------------------------------------------------------------------------
-
-    def setR(method, *args)
-      @r_interop = R::Support.exec_function_i(method, @r_interop, *args)
-      self
+    # Number of R `class()` probes issued from Object.build (missing r_class and no usable wrapper_tag).
+    # Reset with reset_build_counters! before measuring. See docs/performance_plan.md Phase 2.
+    def self.build_class_probe_count
+      @build_class_probe_count ||= 0
     end
 
-    #--------------------------------------------------------------------------------------
-    # 
-    #--------------------------------------------------------------------------------------
+    def self.reset_build_counters!
+      @build_class_probe_count = 0
+    end
 
-    def setR_name(method_name, *args)
-      method = R::Support.eval(method_name)
-      setR(method, *args)
-      self
+    def self.increment_build_class_probe_count!
+      @build_class_probe_count = build_class_probe_count + 1
     end
 
-    #--------------------------------------------------------------------------------------
-    # Sets the names attribute of the object
-    # @param [R::Object] names_vector is an RVector with the list of names.
-    #--------------------------------------------------------------------------------------
+    # Factory: build the right Ruby wrapper for an R value. Returns a subclass (DataFrame, Vector, etc.),
+    # or the unwrapped Ruby value for rb_obj_* handles and for R NULL. Pass r_class to avoid an R class() call.
+    # Pass wrapper_tag from the new-bridge envelope to classify without string-matching r_class and to allow
+    # probe-free builds when r_class is absent but tag is present (non-+other+).
+    def self.build(r_interop, expression = nil, r_class: nil, wrapper_tag: nil)
+      # Ruby object handles stored in R: unwrap to the original Ruby object.
+      if r_interop.is_a?(::String) && r_interop.start_with?("rb_obj_")
+        return ::R::Support.get_ruby_object(r_interop)
+      end
 
-    def names=(names_vector)
-      setR_name("`names<-`", names_vector)
+      # If we got a basic Ruby type, it's already unboxed
+      return r_interop if r_interop.is_a?(::Numeric) || r_interop.is_a?(::TrueClass) ||
+                         r_interop.is_a?(::FalseClass) || r_interop.nil? || r_interop.is_a?(::Symbol)
+
+      if r_interop.is_a?(::String) && r_interop.start_with?("g2_v")
+        return new(r_interop, expression) unless ::R.bridge.ready?
+
+        begin
+          rc_in = r_class
+          rc = r_class.to_s.strip
+          rc = nil if rc.nil? || rc.empty?
+          tag = wrapper_tag.to_s.strip
+          tag = nil if tag.nil? || tag.empty?
+
+          # Probe only when we have no class string and no definitive wrapper tag.
+          if rc.nil? && (!tag || tag == "other")
+            rc = class_probe_fetch_r_class(r_interop)
+          elsif rc.nil? && tag && tag != "other"
+            # Envelope-style path: tag is enough; avoid class() round-trip.
+          end
+
+          return nil if rc && rc.strip == "NULL"
+
+          if ::ENV['GALAAZ_DEBUG']
+            ::Kernel.puts "DEBUG: Object.build r_interop=#{r_interop.inspect} r_class_arg=#{rc_in.inspect} r_class=#{rc.inspect} wrapper_tag=#{tag.inspect}"
+          end
+
+          if tag && tag != "other"
+            obj = build_from_wrapper_tag(r_interop, expression, tag, r_class_hint: rc)
+            if obj
+              ::Kernel.puts "DEBUG: Object.build returning #{obj.class}" if ::ENV['GALAAZ_DEBUG']
+              return obj
+            end
+          end
+
+          if rc.nil?
+            rc = class_probe_fetch_r_class(r_interop)
+            return nil if rc.strip == "NULL"
+          end
+
+          obj = build_from_r_class_string(r_interop, expression, rc)
+          ::Kernel.puts "DEBUG: Object.build returning #{obj.class}" if ::ENV['GALAAZ_DEBUG']
+          obj
+        rescue => e
+          ::Kernel.puts "DEBUG: Object.build rescue: #{e.message}" if ::ENV['GALAAZ_DEBUG']
+          new(r_interop, expression)
+        end
+      else
+        # Fallback for already unboxed or unexpected strings
+        r_interop
+      end
     end
 
-    def names(*args)
-      return R::Support.exec_function_name("names", @r_interop) if (args.length == 0)
-      setR_name("`names<-`", *args)
-      self
+    def self.class_probe_fetch_r_class(r_interop)
+      increment_build_class_probe_count!
+      ::R.bridge.eval_r("paste(class(#{r_interop}), collapse=' ')").gsub(/^\[1\] /, "").gsub(/"/, "").strip
     end
-        
-    #--------------------------------------------------------------------------------------
-    #
-    #--------------------------------------------------------------------------------------
 
-    def rclass=(class_name)
-      setR_name("`class<-`", class_name)
-    end
-    
-    def rclass
-      R::Support.exec_function_name("class", @r_interop)
-    end
-    
-    #--------------------------------------------------------------------------------------
-    #
-    #--------------------------------------------------------------------------------------
+    def self.build_from_wrapper_tag(r_interop, expression, tag, r_class_hint: nil)
+      # typeof(formula) is language in R, but class is "formula"; keep plain R::Object (legacy semantics).
+      if tag == "language" && r_class_hint && r_class_hint.include?("formula")
+        return nil
+      end
 
-    def comment=(comment_text)
-      setR_name("`comment<-`", comment_text)
-    end
-    
-    def comment
-      R::Support.exec_function_name("comment", @r_interop)
+      case tag
+      when "data_frame"
+        ::R::DataFrame.new(r_interop, expression)
+      when "matrix"
+        ::R::Matrix.new(r_interop, expression)
+      when "vector"
+        v = ::R::Vector.new(r_interop)
+        v.expression = expression if expression
+        v
+      when "list"
+        ::R::List.new(r_interop, expression)
+      when "environment"
+        ::R::Environment.new(r_interop, expression)
+      when "closure"
+        ::R::Closure.new(r_interop, expression)
+      when "language"
+        ::R::Language.new(r_interop, expression)
+      when "symbol"
+        ::R::RSymbol.new(r_interop, expression)
+      else
+        nil
+      end
     end
-    
-    #--------------------------------------------------------------------------------------
-    #
-    #--------------------------------------------------------------------------------------
 
-    def dim=(numeric_vector)
-      setR_name("`dim<-`", numeric_vector)
+    def self.build_from_r_class_string(r_interop, expression, r_class)
+      case
+      when r_class.include?("data.frame") || r_class.include?("tbl_df")
+        ::R::DataFrame.new(r_interop, expression)
+      when r_class.include?("matrix") || r_class.include?("array")
+        ::R::Matrix.new(r_interop, expression)
+      when r_class.include?("numeric") || r_class.include?("integer") ||
+           r_class.include?("logical") || r_class.include?("character")
+        v = ::R::Vector.new(r_interop)
+        v.expression = expression if expression
+        v
+      when r_class.include?("list")
+        ::R::List.new(r_interop, expression)
+      when r_class.include?("environment")
+        ::R::Environment.new(r_interop, expression)
+      when r_class.include?("function")
+        ::R::Closure.new(r_interop, expression)
+      when r_class.include?("language") || r_class == "call"
+        ::R::Language.new(r_interop, expression)
+      when r_class == "name" || r_class == "symbol"
+        ::R::RSymbol.new(r_interop, expression)
+      when r_class == "expression"
+        ::R::RExpression.new(r_interop, expression)
+      else
+        ::Kernel.puts "DEBUG: Object.build fell through to else (r_class=#{r_class.inspect})" if ::ENV['GALAAZ_DEBUG']
+        new(r_interop, expression)
+      end
     end
 
-    def dim
-      R::Support.exec_function_name("dim", @r_interop)
+    # Printed representation of the R object (as R would print it).
+    def to_s
+      return super unless ::R.bridge.ready?
+      ::R.bridge.print_r(@r_interop)
     end
-    
-    #--------------------------------------------------------------------------------------
-    #
-    #--------------------------------------------------------------------------------------
 
-    def dimnames=(names_vector)
-      setR_name("`dimnames<-`", names_vector)
+    # Phase B: BasicObject has no class; we must define it.
+    def class
+      ::R::Object
     end
 
-    def dimnames
-      R::Support.exec_function_name("dimnames", @r_interop)
+    # true for EXPLICIT_RUBY_SURFACE and for any other symbol (forwarded to R via method_missing).
+    def respond_to?(sym, include_private = false)
+      sym = sym.to_sym
+      return true if EXPLICIT_RUBY_SURFACE.include?(sym)
+      true
     end
-    
-    #--------------------------------------------------------------------------------------
-    # @bug Needed to create method R.row__names because dispatch is not working properly
-    #--------------------------------------------------------------------------------------
-
-    # since we need to call a method and the method changes the object, then we need to
-    # change our internal pointer also @r_interop.  Ideally, just setting the row.names
-    # should work.
-    def row__names=(names_vector)
-      setR_name("`row.names<-`", names_vector)
+
+    # Type check against Ruby modules/classes (e.g. obj.is_a?(R::DataFrame)).
+    def is_a?(mod)
+      return false unless mod.is_a?(::Module)
+      !!(self.class <= mod)
     end
+    alias_method :kind_of?, :is_a?
 
-    def row__names
-      R::Support.exec_function_name("row.names", @r_interop)
+    # Exact class check (e.g. obj.instance_of?(R::Object)).
+    def instance_of?(mod)
+      return false unless mod.is_a?(::Module)
+      self.class == mod
     end
-      
-    #--------------------------------------------------------------------------------------
-    #
-    #--------------------------------------------------------------------------------------
 
-    def tsp=(numeric_vector)
-      setR_name("`tsp<-`", numeric_vector)
+    # Debug string: class, object id, and @r_interop handle.
+    def inspect
+      "#<#{self.class}:#{__id__.to_s(16)} @r_interop=#{@r_interop.inspect}>"
     end
 
-    def tsp
-      R::Support.exec_function_name("tsp", @r_interop)
+    alias_method :object_id, :__id__
+
+    # R's class() of this object; unwrapped to a single string when length 1.
+    def rclass
+      res = ::R::Support.exec_function("class", self)
+      val = res.respond_to?(:>>) ? (res >> nil) : res
+      val.is_a?(::Array) ? val[0] : val
     end
-    
-    #--------------------------------------------------------------------------------------
-    #
-    #--------------------------------------------------------------------------------------
-    
-    def attr=(which: w, value: v)
-      value = (R::Support.interop(value) ? value.r_interop : value)
-      # setR(@@set_attr, which, value)
-      setR_name("`attr<-`", which, value)
+
+    # R's typeof() of this object; unwrapped to a single string when length 1.
+    def typeof
+      res = ::R::Support.exec_function("typeof", self)
+      val = res.respond_to?(:>>) ? (res >> nil) : res
+      val.is_a?(::Array) ? val[0] : val
     end
-    
-    #--------------------------------------------------------------------------------------
-    #
-    #--------------------------------------------------------------------------------------
 
-    def pp
-      R.print(@r_interop)
+    # Unbox this R object to a Ruby value. Recurses until only Ruby values (no R::Object).
+    # Plain R::Object: re-evaluates handle; if list (typeof=="list") iterates [[i]] and recurses;
+    # if atomic uses [[index+1]] and result protocol (never uses $ on atomic). Raises UnboxDepthError when depth exceeded.
+    def unboxed_get(index = nil, depth = 0)
+      if depth >= ::R::Support::MAX_UNBOX_DEPTH
+        ::Kernel.raise(::R::UnboxDepthError, "unbox: list too deep (max depth #{::R::Support::MAX_UNBOX_DEPTH} exceeded)")
+      end
+      val = ::R::Support.eval(@r_interop)
+      return val unless val.is_a?(::R::Object)
+      return val.unboxed_get(index, depth + 1) if val.class.instance_method(:unboxed_get).owner != ::R::Object
+
+      handle = @r_interop.to_s
+      safe_handle = handle =~ /\Ag2_v\d+\z/
+
+      # Whole object (index.nil?): plain Object may be a list in R — use typeof/length, never $
+      if index.nil?
+        type_str = self.typeof.to_s.strip
+        len_obj = self.length
+        n = len_obj.respond_to?(:unboxed_get) ? len_obj.unboxed_get(0) : len_obj
+        n = n.to_i if n.respond_to?(:to_i)
+        if type_str == "list" && n.is_a?(::Integer) && n >= 1
+          list_handle = handle
+          unless safe_handle
+            list_handle = ::R::Support.generate_var_name
+            ::R.bridge.eval_r("#{list_handle} <- #{::R::Support.parse_arg(self)}")
+          end
+          arr = []
+          (1..n).each do |i|
+            elt = ::R::Support.eval("#{list_handle}[[#{i}]]")
+            if elt.nil?
+              arr << nil
+            elsif !elt.is_a?(::R::Object)
+              arr << elt
+            else
+              arr << (elt.is__null.unboxed_get(0) ? nil : elt.unboxed_get(nil, depth + 1))
+            end
+          end
+          return arr
+        end
+        # Atomic (or length 0): treat as single element for consistency
+        index = 0
+      end
+
+      idx = index + 1
+      r_code = safe_handle ? "#{handle}[[#{idx}]]" : nil
+      unless r_code
+        var = ::R::Support.generate_var_name
+        ::R.bridge.eval_r("#{var} <- #{::R::Support.parse_arg(self)}")
+        r_code = "#{var}[[#{idx}]]"
+      end
+      val2 = ::R::Support.eval(r_code)
+      return val2 unless val2.is_a?(::R::Object)
+      return val2.unboxed_get(nil, depth + 1) if val2.class.instance_method(:unboxed_get).owner != ::R::Object
+
+      # Plain R::Object single element: use result protocol until scalar or Vector/List
+      r_code = "#{val2.r_interop}[[1]]"
+      max_plain = ::R::Support::MAX_UNBOX_DEPTH - depth
+      loop do
+        var = ::R::Support.generate_var_name
+        assignment = "#{var} <- #{r_code}"
+        envelope = ::R.bridge.eval_r_with_result(assignment)
+        raise "Result protocol: no envelope (buffer missing or invalid)" unless envelope
+        case envelope[:type]
+        when :scalar_double, :scalar_integer, :scalar_logical, :scalar_symbol
+          return envelope[:value]
+        when :scalar_character
+          v = envelope[:value]
+          return (v.is_a?(::String) && v =~ /^rb_obj_\d+$/) ? ::R::Support.get_ruby_object(v) : v
+        when :handle
+          obj = ::R::Object.build(envelope[:handle], nil, r_class: envelope[:r_class], wrapper_tag: envelope[:wrapper_tag])
+          unless obj.instance_of?(::R::Object)
+            return obj.unboxed_get(nil, depth + 1)
+          end
+          r_code = "#{envelope[:handle]}[[1]]"
+          max_plain -= 1
+          if max_plain <= 0
+            ::Kernel.raise(::R::UnboxDepthError, "unbox: list too deep (max depth #{::R::Support::MAX_UNBOX_DEPTH} exceeded)")
+          end
+        else
+          raise "Result protocol: unknown envelope type #{envelope[:type].inspect}"
+        end
+      end
     end
 
-    #--------------------------------------------------------------------------------------
-    #
-    #--------------------------------------------------------------------------------------
+    # Unbox via >>: same as unboxed_get so (self >> nil) and (self >> 0) work.
+    # << is kept as a compatibility alias for older Galaaz docs/examples.
+    alias_method :>>, :unboxed_get
+    alias_method :<<, :unboxed_get
+
+    # Unboxing semantics (>> nil / to_ruby / unboxed_get(nil)): recurse until result contains only Ruby
+    # values (Integer, Float, String, true/false, Array, nil). List → Array (single list → [x]).
+    # Atomic length 1 → scalar; length > 1 → Array. Can be expensive for large/deep structures.
+    # Raises R::UnboxDepthError when recursion exceeds MAX_UNBOX_DEPTH.
 
-    def pretty_print(obj)
-      puts self
+    # Simple way to get a Ruby value: (self >> nil). For length-1 vectors returns the scalar; for longer returns array.
+    def to_ruby
+      self >> nil
     end
-    
-    #--------------------------------------------------------------------------------------
-    #
-    #--------------------------------------------------------------------------------------
 
-    def to_s
+    # Unbox length-1 numeric (or string digits) to Integer without forwarding to R (R has no to_i).
+    # Callback procs often use x.to_i when R passes scalars as R::Object.
+    def to_i
+      v = to_ruby
+      v = v.first if v.is_a?(::Array) && v.size == 1
+      case v
+      when ::Integer then v
+      when ::Float then v.to_i
+      when ::String then Integer(v)
+      else
+        Integer(v)
+      end
+    end
 
-      begin
-        cap = nil
-        cap = R::Support.capture2.call(r_interop)
-        str = String.new
-        (0...(cap.size - 1)).each do |i|
-          str << cap[i] << "\n"
+    # Return nil so RSpec/eq and array conversion don't forward to_ary to R (plain Object is not array-like).
+    def to_ary
+      nil
+    end
+
+    # Equality: R::Object vs R::Object uses all.equal; vs Ruby scalar uses unboxed value(s).
+    def ==(other)
+      return true if self.equal?(other)
+      if other.is_a?(::R::Object)
+        res = ::R.bridge.eval_r("isTRUE(all.equal(#{@r_interop}, #{other.r_interop}))")
+        return res == "[1] TRUE"
+      elsif other.is_a?(::Numeric) || other.is_a?(::String) || other.is_a?(::TrueClass) ||
+            other.is_a?(::FalseClass) || other.nil? || other.is_a?(::Symbol)
+        # DataFrame/Matrix etc. are not equal to a scalar even if they contain that value (e.g. row['mpg'] != 21.0).
+        return false if self.class == ::R::DataFrame || self.class == ::R::Matrix
+        val = (self >> nil)
+        if val.is_a?(::Array)
+          return val[0] == other if val.size == 1
+          return val.include?(other) if other.is_a?(::String)
         end
-        str << cap[cap.size - 1] if cap.size >= 1
-        str
-      rescue StandardError => e
-        puts e
+        return val == other
+      else
+        super
       end
-      
     end
 
-  end
+    # Call this object as an R function with the given args (e.g. obj.call(1, 2)).
+    def call(*args)
+      ::R::Support.exec_function(self, *args)
+    end
 
-    
+    # Forward unknown methods to R: process_missing(symbol, self, *args) builds and runs the R call.
+    def method_missing(symbol, *args)
+      ::R::Support.process_missing(symbol, self, *args)
+    end
+  end
 end