serializable_proc 0.1.0

data/lib/serializable_proc.rb

@@ -0,0 +1,169 @@
+require 'rubygems'
+require 'forwardable'
+require 'ruby2ruby'
+require 'serializable_proc/marshalable'
+require 'serializable_proc/parsers'
+require 'serializable_proc/binding'
+require 'serializable_proc/sandboxer'
+
+begin
+  require 'parse_tree'
+  require 'parse_tree_extensions'
+rescue LoadError
+  require 'ruby_parser'
+end
+
+##
+# SerializableProc differs from the vanilla Proc in 2 ways:
+#
+# #1. Isolated variables
+#
+# Upon initializing, all variables (local, instance, class & global) within its context
+# are extracted from the proc's binding, and are isolated from changes outside the
+# proc's scope, thus, achieving a snapshot effect.
+#
+#   require 'rubygems'
+#   require 'serializable_proc'
+#
+#   x, @x, @@x, $x = 'lx', 'ix', 'cx', 'gx'
+#
+#   s_proc = SerializableProc.new { [x, @x, @@x, $x].join(', ') }
+#   v_proc = Proc.new { [x, @x, @@x, $x].join(', ') }
+#
+#   x, @x, @@x, $x = 'ly', 'iy', 'cy', 'gy'
+#
+#   s_proc.call # >> "lx, ix, cx, gx"
+#   v_proc.call # >> "ly, iy, cy, gy"
+#
+# #2. Marshallable
+#
+# No throwing of TypeError when marshalling a SerializableProc:
+#
+#   Marshal.load(Marshal.dump(s_proc)).call # >> "lx, ix, cx, gx"
+#   Marshal.load(Marshal.dump(v_proc)).call # >> TypeError (cannot dump Proc)
+#
+class SerializableProc
+
+  include Marshalable
+  marshal_attrs :file, :line, :code, :arity, :binding
+
+  ##
+  # Creates a new instance of SerializableProc by passing in a code block, in the process,
+  # all referenced variables (local, instance, class & global) within the block are
+  # extracted and isolated from the current context.
+  #
+  #   SerializableProc.new {|...| block }
+  #   x = lambda { ... }; SerializableProc.new(&x)
+  #   y = proc { ... }; SerializableProc.new(&y)
+  #   z = Proc.new { ... }; SerializableProc.new(&z)
+  #
+  # The following will only work if u have ParseTree (not available for 1.9.* & JRuby)
+  # installed:
+  #
+  #   def action(&block) ; SerializableProc.new(&block) ; end
+  #   action { ... }
+  #
+  def initialize(&block)
+    file, line = /^#<Proc:0x[0-9A-Fa-f]+@(.+):(\d+).*?>$/.match(block.inspect)[1..2]
+    @file, @line, @arity = File.expand_path(file), line.to_i, block.arity
+    @code, sexp = Parsers::PT.process(block) || Parsers::RP.process(self.class, @file, @line)
+    @binding = Binding.new(block.binding, sexp)
+  end
+
+  ##
+  # Returns true if +other+ is exactly the same instance, or if +other+ has the same string
+  # content.
+  #
+  #   x = SerializableProc.new { puts 'awesome' }
+  #   y = SerializableProc.new { puts 'wonderful' }
+  #   z = SerializableProc.new { puts 'awesome' }
+  #
+  #   x == x # >> true
+  #   x == y # >> false
+  #   x == z # >> true
+  #
+  def ==(other)
+    other.object_id == object_id or
+      other.is_a?(self.class) && other.to_s == to_s
+  end
+
+  ##
+  # Returns a plain vanilla proc that works just like other instances of Proc, the
+  # only difference is that the binding of variables is the same as the serializable
+  # proc, which is isolated.
+  #
+  #   x, @x, @@x, $x = 'lx', 'ix', 'cx', 'gx'
+  #   s_proc = SerializableProc.new { [x, @x, @@x, $x].join(', ') }
+  #   x, @x, @@x, $x = 'ly', 'iy', 'cy', 'gy'
+  #   s_proc.to_proc.call # >> 'lx, ix, cx, gx'
+  #
+  # Just like any object that responds to #to_proc, you can do the following as well:
+  #
+  #   def action(&block) ; yield ; end
+  #   action(&s_proc) # >> 'lx, ix, cx, gx'
+  #
+  def to_proc
+    @proc ||= eval(@code[:runnable], @binding.eval!, @file, @line)
+  end
+
+  ##
+  # Returns a string representation of itself, which is in fact the code enclosed within
+  # the initializing block.
+  #
+  #   SerializableProc.new { [x, @x, @@x, $x].join(', ') }.to_s
+  #   # >> lambda { [x, @x, @@x, $x].join(', ') }
+  #
+  # By specifying +debug+ as true, the true runnable code is returned, the only difference
+  # from the above is that the variables within has been renamed (in order to provide for
+  # variables isolation):
+  #
+  #   SerializableProc.new { [x, @x, @@x, $x].join(', ') }.to_s(true)
+  #   # >> lambda { [lvar_x, ivar_x, cvar_x, gvar_x].join(', ') }
+  #
+  # The following renaming rules apply:
+  # * local variable -> prefixed with 'lvar_',
+  # * instance variable -> replaced '@' with 'ivar_'
+  # * class variable -> replaced '@@' with 'cvar_'
+  # * global variable -> replaced '$ with 'gvar_'
+  #
+  def to_s(debug = false)
+    @code[debug ? :runnable : :extracted]
+  end
+
+  ##
+  # Returns the number of arguments accepted when running #call. This is extracted directly
+  # from the initializing code block, & is only as accurate as Proc#arity.
+  #
+  # Note that at the time of this writing, running on 1.8.* yields different result from
+  # that of 1.9.*:
+  #
+  #   lambda { }.arity         # 1.8.* (-1) / 1.9.* (0)  (?!)
+  #   lambda {|x| }.arity      # 1.8.* (1)  / 1.9.* (1)
+  #   lambda {|x,y| }.arity    # 1.8.* (2)  / 1.9.* (2)
+  #   lambda {|*x| }.arity     # 1.8.* (-1) / 1.9.* (-1)
+  #   lambda {|x, *y| }.arity  # 1.8.* (-2) / 1.9.* (-2)
+  #   lambda {|(x,y)| }.arity  # 1.8.* (1)  / 1.9.* (1)
+  #
+  def arity
+    @arity
+  end
+
+  ##
+  # Just like the vanilla proc, invokes it, setting params as specified. Since the code
+  # representation of a SerializableProc is a lambda, expect lambda-like behaviour when
+  # wrong number of params are passed in.
+  #
+  #   SerializableProc.new{|i| (['hello'] * i).join(' ') }.call(2)
+  #   # >> 'hello hello'
+  #
+  def call(*params)
+    to_proc.call(*params)
+  end
+
+  alias_method :[], :call
+
+  def binding #:nodoc:
+    raise NotImplementedError
+  end
+
+end

data/spec/extracting_bound_variables_spec.rb

@@ -0,0 +1,99 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe 'Extracting bound variables' do
+
+  class << self
+    def m1    ; 'm1' ; end
+    def m2(x) ; 'm2(%s)' % x ; end
+  end
+
+  describe '>> extracting local variables' do
+
+    extend SerializableProc::Spec::Helpers
+
+    should "handle outer-scoped ones" do
+      x, y = 'awe', 'some'
+      should_have_expected_binding \
+        SerializableProc.new{ x + y }, {:lvar_x => x, :lvar_y => y}
+    end
+
+    should "handle inner-scoped ones" do
+      x, y = 'awe', 'some'
+      should_have_expected_binding \
+        SerializableProc.new{|x| z = 'wonder' ; %w{a b}.each{|y| puts z, x, y } },
+        {:lvar_x => x, :lvar_y => y, :lvar_z => nil}
+    end
+
+    # NOTE: Errors checking are found under ./initializing_errors_spec.rb
+
+  end
+
+  describe '>> extracting instance variables' do
+
+    extend SerializableProc::Spec::Helpers
+
+    should 'handle outer-scoped ones' do
+      @x, @y = 'awe', 'some'
+      should_have_expected_binding \
+        SerializableProc.new{ @x + @y }, {:ivar_x => @x, :ivar_y => @y}
+    end
+
+    should "handle inner-scoped ones" do
+      @x, @y = 'awe', 'some'
+      should_have_expected_binding \
+        SerializableProc.new{ @z = 'wonder' ; %w{a b}.each{ puts @z, @x, @y } },
+        {:ivar_x => @x, :ivar_y => @y, :ivar_z => nil}
+    end
+
+    # NOTE: Errors checking are found under ./initializing_errors_spec.rb
+
+  end
+
+  describe '>> extracting class variables' do
+
+    extend SerializableProc::Spec::Helpers
+
+    should 'handle outer-scoped ones' do
+      @@x, @@y = 'awe', 'some'
+      should_have_expected_binding \
+        SerializableProc.new{ @@x + @@y }, {:cvar_x => @@x, :cvar_y => @@y}
+    end
+
+    should "handle inner-scoped ones" do
+      @@x, @@y = 'awe', 'some'
+      should_have_expected_binding \
+        SerializableProc.new{ @@z = 'wonder' ; %w{a b}.each{ puts @@z, @@x, @@y } },
+        {:cvar_x => @@x, :cvar_y => @@y, :cvar_z => nil}
+    end
+
+    # NOTE: Errors checking are found under ./initializing_errors_spec.rb
+
+  end
+
+  describe '>> extracting global variables' do
+
+    extend SerializableProc::Spec::Helpers
+
+    should 'handle outer-scoped ones' do
+      $x, $y = 'awe', 'some'
+      should_have_expected_binding SerializableProc.new{ $x + $y }, {:gvar_x => $x, :gvar_y => $y}
+    end
+
+    should "handle inner-scoped ones" do
+      $x, $y = 'awe', 'some'
+      should_have_expected_binding \
+        SerializableProc.new{ $z = 'wonder' ; %w{a b}.each{ puts $z, $x, $y } },
+        {:gvar_x => $x, :gvar_y => $y, :gvar_z => nil}
+    end
+
+    # NOTE: Errors checking are found under ./initializing_errors_spec.rb
+
+  end
+
+  describe '>> extracting method returns' do
+    should "not handle" do
+      SerializableProc.new { m1 + m2(3) }.binding_dump.should.be.empty
+    end
+  end
+
+end

data/spec/initializing_errors_spec.rb

@@ -0,0 +1,95 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe 'Initializing errors' do
+
+  unless $parse_tree_installed
+    describe '>> SerializableProc::CannotAnalyseCodeError' do
+
+      extend SerializableProc::Spec::Helpers
+
+      should "raise if line has more than 1 'SerializableProc.new'" do
+        lambda {
+          SerializableProc.new {} ; SerializableProc.new { |arg| %w{a b}.map{|x| puts x } }
+        }.should.be raising_cannot_analyse_error("'SerializableProc.new'")
+      end
+
+      should "raise if line has more than 1 'Proc.new'" do
+        lambda {
+          p1 = Proc.new {} ; p2 = Proc.new { |arg| %w{a b}.map{|x| puts x } }
+          SerializableProc.new(&p2)
+        }.should.be raising_cannot_analyse_error("'lambda'/'proc'/'Proc.new'")
+      end
+
+      should "raise if line has more than 1 'lambda'" do
+        lambda {
+          p1 = lambda {} ; p2 = lambda { |arg| %w{a b}.map{|x| puts x } }
+          SerializableProc.new(&p2)
+        }.should.be raising_cannot_analyse_error("'lambda'/'proc'/'Proc.new'")
+      end
+
+      should "raise if line has more than 1 'proc'" do
+        lambda {
+          p1 = proc {} ; p2 = proc { |arg| %w{a b}.map{|x| puts x } }
+          SerializableProc.new(&p2)
+        }.should.be raising_cannot_analyse_error("'lambda'/'proc'/'Proc.new'")
+      end
+
+      should "raise if line mixes 'lambda' & 'proc'" do
+        lambda {
+          p1 = lambda {} ; p2 = proc { |arg| %w{a b}.map{|x| puts x } }
+          SerializableProc.new(&p2)
+        }.should.be raising_cannot_analyse_error("'lambda'/'proc'/'Proc.new'")
+      end
+
+      should "raise if line mixes 'Proc.new' & 'proc'" do
+        lambda {
+          p1 = Proc.new {} ; p2 = proc { |arg| %w{a b}.map{|x| puts x } }
+          SerializableProc.new(&p2)
+        }.should.be raising_cannot_analyse_error("'lambda'/'proc'/'Proc.new'")
+      end
+
+      should "raise if line mixes 'Proc.new' & 'lambda'" do
+        lambda {
+          p1 = Proc.new {} ; p2 = lambda { |arg| %w{a b}.map{|x| puts x } }
+          SerializableProc.new(&p2)
+        }.should.be raising_cannot_analyse_error("'lambda'/'proc'/'Proc.new'")
+      end
+
+      should "raise if line does not have lambda, proc, Proc.new or SerializableProc.new" do
+        lambda {
+          def create_serializable_proc(&block) ; SerializableProc.new(&block) ; end
+          create_serializable_proc { %w{a b}.map{|x| puts x } }
+        }.should.raise(SerializableProc::CannotAnalyseCodeError).
+          message.should.equal('Cannot find specified initializer !!')
+      end
+
+    end
+  end
+
+  describe '>> SerializableProc::CannotSerializeVariableError' do
+
+    extend SerializableProc::Spec::Helpers
+
+    should "raise if local variable cannot be marshalled" do
+      f = Tempfile.new('fake')
+      lambda { SerializableProc.new{ f } }.should.be raising_cannot_serialize_variable_error('f')
+    end
+
+    should "raise if class variable cannot be marshalled" do
+      @@f = Tempfile.new('fake')
+      lambda { SerializableProc.new{ @@f } }.should.be raising_cannot_serialize_variable_error('@@f')
+    end
+
+    should "raise if instance variable cannot be marshalled" do
+      @f = Tempfile.new('fake')
+      lambda { SerializableProc.new{ @f } }.should.be raising_cannot_serialize_variable_error('@f')
+    end
+
+    should "raise if global variable cannot be marshalled" do
+      $f = Tempfile.new('fake')
+      lambda { SerializableProc.new{ $f } }.should.be raising_cannot_serialize_variable_error('$f')
+    end
+
+  end
+
+end

data/spec/marshalling_spec.rb

@@ -0,0 +1,51 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe 'Marshalling' do
+
+  describe '>> basic (wo contextual references)' do
+
+    before do
+      @proc = SerializableProc.new{ %w{a b}.map{|x| x } }
+    end
+
+    should 'be able to marshal' do
+      Marshal.load(Marshal.dump(@proc))
+      true.should.be.true # the above should execute wo error
+    end
+
+    should 'be able to resume proc behaviours' do
+      Marshal.load(Marshal.dump(@proc)).call.should.equal(%w{a b})
+    end
+
+  end
+
+  describe '>> with contextual references' do
+
+    should 'handle local variables' do
+      x, y, expected = 'awe', 'some', 'awesome'
+      s_proc = SerializableProc.new{ x + y }
+      Marshal.load(Marshal.dump(s_proc)).call.should.equal(expected)
+    end
+
+    should 'handle instance variables' do
+      @x, @y, expected = 'awe', 'some', 'awesome'
+      s_proc = SerializableProc.new{ @x + @y }
+      Marshal.load(Marshal.dump(s_proc)).call.should.equal(expected)
+    end
+
+    should 'handle class variables' do
+      @@x, @@y, expected = 'awe', 'some', 'awesome'
+      s_proc = SerializableProc.new{ @@x + @@y }
+      Marshal.load(Marshal.dump(s_proc)).call.should.equal(expected)
+    end
+
+    should 'handle global variables' do
+      $x, $y, expected = 'awe', 'some', 'awesome'
+      s_proc = SerializableProc.new{ $x + $y }
+      Marshal.load(Marshal.dump(s_proc)).call.should.equal(expected)
+    end
+
+  end
+
+end
+

data/spec/multiple_arities_serializable_proc_spec.rb

@@ -0,0 +1,159 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+describe 'Multiple arities serializable proc' do
+
+  extend SerializableProc::Spec::Helpers
+
+  expected_file = File.expand_path(__FILE__)
+  expected_code = "lambda { |lvar_arg1, lvar_arg2| [\"a\", \"b\"].map { |lvar_x| puts(lvar_x) } }"
+
+  should_handle_proc_variable expected_file, expected_code, {
+    # ////////////////////////////////////////////////////////////////////////
+    # >> Always newlinling
+    # ////////////////////////////////////////////////////////////////////////
+      __LINE__ =>
+        lambda do |arg1, arg2|
+          %w{a b}.map do |x|
+            puts x
+          end
+        end,
+      __LINE__ =>
+        lambda { |arg1, arg2|
+          %w{a b}.map{|x|
+            puts x
+          }
+        },
+      __LINE__ =>
+        proc do |arg1, arg2|
+          %w{a b}.map do |x|
+            puts x
+          end
+        end,
+      __LINE__ =>
+        lambda { |arg1, arg2|
+          %w{a b}.map{|x|
+            puts x
+          }
+        },
+      __LINE__ =>
+        Proc.new do |arg1, arg2|
+          %w{a b}.map do |x|
+            puts x
+          end
+        end,
+      __LINE__ =>
+        Proc.new { |arg1, arg2|
+          %w{a b}.map{|x|
+            puts x
+          }
+        },
+    # ////////////////////////////////////////////////////////////////////////
+    # >> Partial newlining
+    # ////////////////////////////////////////////////////////////////////////
+      __LINE__ =>
+        lambda do |arg1, arg2|
+          %w{a b}.map do |x| puts x end
+        end,
+      __LINE__ =>
+        lambda { |arg1, arg2|
+          %w{a b}.map{|x| puts x }
+        },
+      __LINE__ =>
+        proc do |arg1, arg2|
+          %w{a b}.map do |x| puts x end
+        end,
+      __LINE__ =>
+        lambda { |arg1, arg2|
+          %w{a b}.map{|x| puts x }
+        },
+      __LINE__ =>
+        Proc.new do |arg1, arg2|
+          %w{a b}.map do |x| puts x end
+        end,
+      __LINE__ =>
+        Proc.new { |arg1, arg2|
+          %w{a b}.map{|x| puts x }
+        },
+    # ////////////////////////////////////////////////////////////////////////
+    # >> No newlining
+    # ////////////////////////////////////////////////////////////////////////
+      __LINE__ =>
+        lambda do |arg1, arg2| %w{a b}.map do |x| puts x end end,
+      __LINE__ =>
+        lambda { |arg1, arg2| %w{a b}.map{|x| puts x } },
+      __LINE__ =>
+        proc do |arg1, arg2| %w{a b}.map do |x| puts x end end,
+      __LINE__ =>
+        lambda { |arg1, arg2| %w{a b}.map{|x| puts x } },
+      __LINE__ =>
+        Proc.new do |arg1, arg2| %w{a b}.map do |x| puts x end end,
+      __LINE__ =>
+        Proc.new { |arg1, arg2| %w{a b}.map{|x| puts x } },
+    }
+
+  should "handle block using do ... end [##{__LINE__}]" do
+    (
+      SerializableProc.new do |arg1, arg2|
+        %w{a b}.map{|x| puts x }
+      end
+    ).should.be having_expected_proc_attrs(expected_file, __LINE__ - 3, expected_code)
+  end
+
+  should "handle block using do ... end [##{__LINE__}]" do
+    (SerializableProc.new do |arg1, arg2| %w{a b}.map{|x| puts x } end).
+      should.be having_expected_proc_attrs(expected_file, __LINE__.pred, expected_code)
+  end
+
+  should "handle block using { ... } [##{__LINE__}]" do
+    (
+      SerializableProc.new { |arg1, arg2|
+        %w{a b}.map{|x| puts x }
+      }
+    ).should.be having_expected_proc_attrs(expected_file, __LINE__ - 3, expected_code)
+  end
+
+  should "handle block using { ... } [##{__LINE__}]" do
+    (SerializableProc.new { |arg1, arg2| %w{a b}.map{|x| puts x } }).
+      should.be having_expected_proc_attrs(expected_file, __LINE__.pred, expected_code)
+  end
+
+  should "handle fanciful initializing with lambda { ... } [##{__LINE__}]" do
+    (SerializableProc.new(&(lambda { |arg1, arg2| %w{a b}.map{|x| puts x } }))).
+      should.be having_expected_proc_attrs(expected_file, __LINE__.pred, expected_code)
+  end
+
+  should "handle fanciful initializing with lambda do ... end [##{__LINE__}]" do
+    (
+      SerializableProc.new(&(lambda do |arg1, arg2|
+        %w{a b}.map{|x| puts x }
+      end))
+    ).should.be having_expected_proc_attrs(expected_file, __LINE__ - 3, expected_code)
+  end
+
+  should "handle fanciful initializing with proc { ... } [##{__LINE__}]" do
+    (SerializableProc.new(&(proc { |arg1, arg2| %w{a b}.map{|x| puts x } }))).
+      should.be having_expected_proc_attrs(expected_file, __LINE__.pred, expected_code)
+  end
+
+  should "handle fanciful initializing with proc do ... end [##{__LINE__}]" do
+    (
+      SerializableProc.new(&(proc do |arg1, arg2|
+        %w{a b}.map{|x| puts x }
+      end))
+    ).should.be having_expected_proc_attrs(expected_file, __LINE__ - 3, expected_code)
+  end
+
+  should "handle fanciful initializing with Proc.new { ... } [##{__LINE__}]" do
+    (SerializableProc.new(&(Proc.new { |arg1, arg2| %w{a b}.map{|x| puts x } }))).
+      should.be having_expected_proc_attrs(expected_file, __LINE__.pred, expected_code)
+  end
+
+  should "handle fanciful initializing with Proc.new do ... end [##{__LINE__}]" do
+    (
+      SerializableProc.new(&(Proc.new do |arg1, arg2|
+        %w{a b}.map{|x| puts x }
+      end))
+    ).should.be having_expected_proc_attrs(expected_file, __LINE__ - 3, expected_code)
+  end
+
+end