mixit 0.4.0 → 0.5.0

data/README.md

@@ -37,9 +37,11 @@ __WHY?__
 
 __EXAMPLES__
 
-Temporarily mix 'SomeModule' onto the 'self' referenced by _block_:
+__1.__
 
-    Mixit.temporarily SomeModule, :scope => self do 
+Temporarily mix 'SomeModule' onto 'self' (non-thread safe).
+
+    Mixit.temporarily :modules => [SomeModule], :scope => self do 
       p self.class  # => Object
       p respond_to?(:some_mixed_method) # => true  
     end
@@ -47,6 +49,23 @@ Temporarily mix 'SomeModule' onto the 'self' referenced by _block_:
     p self.class # => Object
     p respond_to?(:some_mixed_method) # => false
 
+__2.__
+
+Temporarily mix 'SomeModule' onto 'self' (thread-safe - **per thread**)  
+
+A clone of the extended scope is passed as a argument to the receiving block.   
+Any state created by your mixed-in module(s) is lost to the original scope.  
+Any existing state  mutated by your mixed-in module(s) will propagate back 
+to the original scope.
+
+You should be careful, as always.
+
+    Mixit.temporarily :modules => [SomeModule], :scope => self do |extended| 
+      p extended.class # => Object
+      p extended.respond_to?(:some_mixed_method) # => true
+    end
+
+
 __INSTALL__
 
   gem install mixit

data/lib/mixit/version.rb

@@ -1,3 +1,3 @@
 class Mixit 
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

data/lib/mixit.rb

@@ -1,77 +1,68 @@
-require "mixit/core_ext/object"
 require "mixit/version"
 
 class Mixit
 
-  class << self
+  class << self 
     # 
-    # @overload mix(*modules, options, &block) 
-    #   Temporarily extends a scope with methods from __modules__.
+    # Temporarily extends a scope with instance methods from modules.
     #
-    #   @param [Module] modules
-    #     A variable number of modules to extend the scope with.
-    #
-    #   @param [Hash] options 
+    # @param opts     
+    #   (see Mixit#initialize)
     #   
-    #   @option options [Binding, Proc, Object] :scope 
-    #     The scope to extend.
-    #
-    #   @param block 
-    #     (see Mixit#mix!)
+    # @option opts 
+    #   (see Mixit#initialize)
     #   
-    #   @yieldparam object 
-    #     (see Mixit#mix!)
-    #
-    #   @raise [ArgumentError] 
-    #     If the :scope option is missing.
+    # @param block 
+    #   (see Mixit#temporarily)
+    #   
+    # @yieldparam object   
+    #   (see Mixit#temporarily) 
     #
-    #   @return [void]
+    # @return 
+    #   (see Mixit#temporarily)
     #     
-    def mix(*args, &block)
-      options = args.pop
-      modules = args
-
-      if options.has_key?(:scope)
-        scope = options[:scope]
-      else
-        raise ArgumentError, 'missing :scope option.'
-      end
-
-      new(scope, modules).mix!(&block)
+    def temporarily opts, &block
+      mixit = new(opts)
+      mixit.temporarily(&block)
     end
-    alias_method :temporarily, :mix
   end
 
   #
   # @return [Array<Module>] 
-  #   An Array of Module objects.
-  #
+  #   An Array of modules to extend a scope with.
+  #   
   attr_reader :modules
  
   #
   # @return [Object]
-  #   The scope.
+  #   The scope to extend.
   #
   attr_reader :scope
 
   #
-  # @param [Binding, Proc, Object] scope
-  #   A scope to extend.
+  # @param [Hash] opts
+  #   A Hash of options.
+  #   
+  # @option opts [Object] :scope
+  #   The scope to extend.
+  #
+  # @option opts [Module] :modules
+  #   An Array of modules to extend a scope with.
   #
-  # @param [Array<Module>] modules
-  #   An Array of Module objects.
+  # @raise [ArgumentError] 
+  #   If the :scope option is missing.
   #
-  def initialize scope, modules
-    @modules = modules
+  def initialize opts
     @clones  = []
+    @modules = opts[:modules]
 
-    case scope
+    case opts[:scope]
     when Binding
-      @scope = scope.eval "self"
+      @scope = opts[:scope].eval "self"
     when Proc
-      @scope = scope.binding.eval "self"
+      @scope = opts[:scope].binding.eval "self"
     else
-      @scope = scope
+      @scope = opts[:scope]
     end
   end
 
@@ -84,47 +75,32 @@ class Mixit
   # @yieldparam [Object] object
   #   Yields a clone of the extended object (Optional).  
   #
-  # @return [void]
+  # @return [Object]
+  #   Returns the return value of 'block'.
   #
-  def mix! &block
+  def temporarily &block
     if block.arity == 1
-      block.call extend!(true)
+      value = block.call extend_scope!(:clone => true) 
     else
       begin
-        extend!(false).instance_eval(&block)
+        value = extend_scope!(:clone => false).instance_eval(&block)
       ensure
         remove_methods!
         trigger_callback!
       end
     end
+
+    value
   end
 
-  #
-  # Extends {#scope} with the methods from {#modules modules}.
-  #
-  # @param [Boolean] to_be_cloned
-  #   If true, a clone of the scope is extended.
-  #
-  # @return [Object]
-  #   Returns the extended object.
-  #
-  def extend! clone_scope 
-    if clone_scope
-      scope = @scope.clone
-    else
-      scope = @scope
-    end
+  private 
 
+  def extend_scope! options 
+    options[:clone] ? (scope = @scope.clone) : (scope = @scope)
     @clones = @modules.map(&:clone)
     @clones.inject(scope) { |obj, mod| obj.extend(mod) }
   end
-  private :extend!
 
-  #
-  # Remove methods used to extend {#scope} from module(s).  
-  #
-  # @return [void]
-  #
   def remove_methods!
     @clones.each do |clone|
       clone.instance_methods(false).each do |meth|
@@ -132,13 +108,7 @@ class Mixit
       end
     end
   end
-  private :remove_methods!
 
-  #
-  # Calls cleanup! on module(s) used to extend a scope.
-  #
-  # @return [void]
-  #
   def trigger_callback!
     @clones.each do |clone|
       if clone.respond_to?(:cleanup!)
@@ -146,7 +116,6 @@ class Mixit
       end
     end
   end
-  private :trigger_callback!
 
 end
 

data/test/test_mixit.rb

@@ -13,7 +13,7 @@ context Mixit do
       it 'must provide access to mixed-in methods' do        
         block = proc { }
 
-        Mixit.mix(@module, :scope => block) do 
+        Mixit.temporarily :modules => [@module], :scope => block do 
           callme.must_equal(:ok)
         end
       end
@@ -22,7 +22,7 @@ context Mixit do
         block = proc { }
         local = :ok
       
-        Mixit.mix(@module, :scope => block) do 
+        Mixit.temporarily :modules => [@module], :scope => block do 
           local.must_equal(:ok)
         end
       end
@@ -31,7 +31,7 @@ context Mixit do
         def callme_() :ok end
         block = proc { }
 
-        Mixit.mix(@module, :scope => block) do
+        Mixit.temporarily :modules => [@module], :scope => block do
           callme_.must_equal(:ok)
         end
       end
@@ -45,7 +45,7 @@ context Mixit do
           end
         end
 
-        Mixit.mix(@module, :scope => block) do 
+        Mixit.temporarily :modules => [@module], :scope => block do 
           @ok = :no
         end
 
@@ -55,7 +55,7 @@ context Mixit do
      it 'must remove methods added by mixed-in modules.' do
         block = proc {}
         
-        Mixit.mix(@module, :scope => block) do
+        Mixit.temporarily :modules => [@module], :scope => block do
           nil
         end
 
@@ -67,7 +67,7 @@ context Mixit do
       it 'must provide access to mixed-in methods.' do
         block = proc {}
 
-        Mixit.mix(@module, :scope => block) do |receiver|
+        Mixit.temporarily :modules => [@module], :scope => block do |receiver|
           receiver.callme.must_equal(:ok)
         end
       end
@@ -75,7 +75,7 @@ context Mixit do
       it 'must not extend the original receiver with mixed-in methods.' do
         block = proc {}
 
-        Mixit.mix(@module, :scope => block) do |receiver|
+        Mixit.temporarily :modules => [@module], :scope => block do |receiver|
           respond_to?(:callme).must_equal(false) 
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mixit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-11-26 00:00:00.000000000 Z
+date: 2011-12-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70097654179640 !ruby/object:Gem::Requirement
+  requirement: &70177892499080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 0.9.2
   type: :development
   prerelease: false
-  version_requirements: *70097654179640
+  version_requirements: *70177892499080
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &70097654179140 !ruby/object:Gem::Requirement
+  requirement: &70177892498580 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,7 +32,7 @@ dependencies:
         version: '2.5'
   type: :development
   prerelease: false
-  version_requirements: *70097654179140
+  version_requirements: *70177892498580
 description: Temporarily extend the calling scope of a block with instance methods
   from a module.
 email:
@@ -49,7 +49,6 @@ files:
 - README.md
 - Rakefile
 - lib/mixit.rb
-- lib/mixit/core_ext/object.rb
 - lib/mixit/version.rb
 - mixit.gemspec
 - test/setup.rb
@@ -68,7 +67,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1392924086282936836
+      hash: -3096325220678410006
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -77,7 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -1392924086282936836
+      hash: -3096325220678410006
 requirements: []
 rubyforge_project: mixit
 rubygems_version: 1.8.11

data/lib/mixit/core_ext/object.rb

@@ -1,3 +0,0 @@
-def Mix *args, &block
-  Mixit.mix(*args, &block)
-end