mixit 0.2.0 → 0.3.0

data/.yardopts

@@ -0,0 +1,8 @@
+-m markdown
+--no-private
+--hide-void-return
+--no-cache
+- 
+LICENSE.txt
+
+

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (C) 2011 by Robert Gleeson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/README.md

@@ -1,22 +1,24 @@
 | Project         | Mixit   
 |:----------------|:--------------------------------------------------
 | Homepage        | https://github.com/robgleeson/Mixit
-| Documentation   | http://rubydoc.info/gems/Mixit/frames 
-| Author          | Rob Gleeson             
+| Documentation   | http://rubydoc.info/gems/mixit/frames 
+| Author          | Rob Gleeson, Renato Riccieri Santos Zannon          
 
 
 __DESCRIPTION__
 
-  Mixit can be used to temporarily extend the calling scope of a block or object with instance methods from a module.   
-  It is written to help Domain Specific Language(DSL) writers provide a DSL with their own methods 
-  without losing the calling scope of the caller.
+  Mixit can be used to temporarily extend the calling scope of a block or 
+  object with instance methods from a module.   
+  It is written to help Domain Specific Language(DSL) writers provide a DSL 
+  with their own methods without losing the calling scope of the caller.
 
 __WHY?__
 
   Some Ruby DSL approaches already exist(maybe one suits you):
 
   * `instance_eval`  
-    The calling scope is lost, and internal state is exposed to the user of the DSL.
+    The calling scope is lost, and internal state is exposed to the user of 
+    the DSL.
 
   * `instance_eval` via "EmptyContext"  
     The calling scope is lost, but the object is void of any state.
@@ -24,32 +26,31 @@ __WHY?__
   * Pass `self` onto the calling block.  
     The cleanest approach but some of the beauty of the DSL can be lost.
 
-  All these approaches(but the last) lose the calling scope, and that's why I created 'Mixit'.  
-  I wanted the user of the DSL to have access to the calling scope, but have access to my DSL as
-  implicit receivers of 'self' as well.
+  All these approaches(but the last) lose the calling scope, and that's why I 
+  created 'Mixit'.  
+  I wanted the user of the DSL to have access to the calling scope, but have 
+  access to my DSL as implicit receivers of 'self' as well.
 
   This approach is by no means 'perfect', or even 'good'.   
   If you use it wisely, though, it can be a cool way to build nice DSLs.
 
 
-
 __EXAMPLES__
 
-Mix 'Foo' onto the 'self' referenced by _block_:
+Temporarily mix 'Foo' onto the 'self' referenced by _block_:
 
-    module Foo 
-      def bar
-      end 
+    module Foo
+      def bar() end
     end
 
-    def DSL(&block)
-      Mixit.mix(Foo, block)
-    end
+    block = proc { }
 
-    DSL do 
-      p respond_to?(:bar) # => true
+    Mixit.temporarily(Foo, block) do 
+      p self.class        # => Object
+      p respond_to?(:bar) # => true  
     end
 
+    p self.class        # => Object
     p respond_to?(:bar) # => false
 
 __INSTALL__

data/lib/mixit.rb

@@ -4,7 +4,24 @@ require "mixit/version"
 class Mixit
 
   class << self
-
+    # 
+    # @overload mix(*modules, receiver, &block) 
+    #   Temporarily extends the __receiver__ with methods from __modules__.
+    #
+    #   @param [Module] modules
+    #     A variable number of modules to extend the receiver with.
+    #
+    #   @param receiver 
+    #     (see Mixit#mix_onto) 
+    #   
+    #   @param block 
+    #     (see Mixit#mix_onto)
+    #   
+    #   @yieldparam object 
+    #     (see Mixit#mix_onto)
+    #
+    #   @return [void]
+    #     
     def mix(*args, &block)
       case args.last
       when Proc
@@ -18,12 +35,39 @@ class Mixit
                 
       new(modules).mix_onto(receiver, &block)
     end
+    alias_method :temporarily, :mix
   end
 
+
+  #
+  # @return [Array<Module>] 
+  #   An Array of Module objects.
+  #
+  attr_reader :modules
+  
+  #
+  # @param [Array<Module>] modules
+  #   An Array of Module objects.
+  #
   def initialize(modules)
-    @modules = modules.map(&:clone)
+    @modules = modules
+    @clones  = []
   end
 
+  #
+  # Temporarily extends __receiver__ with methods from {#modules modules}. 
+  #
+  # @param [Object] receiver 
+  #   An object to temporarily extend.
+  #
+  # @param [Proc] block
+  #   A block executed while the object is extended. 
+  #
+  # @yieldparam [Object] object
+  #   Yields a clone of the extended object (Optional).  
+  #
+  # @return [void]
+  #
   def mix_onto(receiver, &block)
     if block.arity == 1
       block.call extend!(receiver, true)
@@ -32,15 +76,11 @@ class Mixit
         ivars = receiver.instance_variables
         extend!(receiver, false).instance_eval(&block)
       ensure
-        # Remove instance variables added by @modules, or &block from 'receiver'.
-        # We want to restore the calling scope to its previous state.
         (receiver.instance_variables - ivars).each do |ivar|
           receiver.send(:remove_instance_variable, ivar)
         end
 
-        # Remove methods added by @modules from 'receiver'.
-        # We want to restore the calling scope to its previous state.
-        @modules.each do |mod|
+        @clones.each do |mod|
           mod.instance_methods(false).each do |meth|
             mod.send(:remove_method, meth)
           end
@@ -49,12 +89,25 @@ class Mixit
     end
   end
 
+  #
+  # Extends __receiver__ with the methods from {#modules modules}.
+  #
+  # @param receiver 
+  #   (see Mixit#mix_onto)
+  #
+  # @param [Boolean] to_be_cloned
+  #   If true, a clone of the receiver is extended.
+  #
+  # @return [Object]
+  #   Returns the extended object.
+  #
   def extend!(receiver, to_be_cloned=false)
     if to_be_cloned
       receiver = receiver.clone
     end
 
-    @modules.inject(receiver) { |obj, mod| obj.extend(mod) }
+    @clones = @modules.map(&:clone)
+    @clones.inject(receiver) { |obj, mod| obj.extend(mod) }
   end
   private :extend!
 

data/lib/mixit/version.rb

@@ -1,3 +1,3 @@
 class Mixit 
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/test/test_mixit.rb

@@ -1,109 +1,105 @@
 context Mixit do
   
   context 'mix' do
-    context 'When receiving a block.' do 
-      before do
-        @module = Module.new do
-          def callme
-            :ok
-          end
-
-          def i
-            @i = 'asdf'
-          end
+    before do
+      @module = Module.new do
+        def callme
+          :ok
+        end
+
+        def set_ivar
+          @set_ivar = 'asdf'
+        end
+      end
+    end
+
+    context 'When receiving a block with no param.' do 
+      it 'must provide access to mixed-in methods' do        
+        block = proc { }
+
+        Mixit.mix(@module, block) do 
+          callme.must_equal(:ok)
         end
       end
 
-      context 'When extending the calling scope of a Proc.' do
-        context 'Without cloning the receiver.' do
-          it 'must provide access to mixed in module methoss' do        
-            block = proc { }
-
-            Mixit.mix(@module, block) do 
-              callme.must_equal(:ok)
-            end
-          end
-
-          it 'must provide access to surrounding locals.' do
-            block = proc { }
-            local = :ok
-          
-            Mixit.mix(@module, block) do 
-              local.must_equal(:ok)
-            end
-          end
-
-          it 'must provide access to surrounding methods.' do
-            def callme_() :ok end
-            block = proc { }
-
-            Mixit.mix(@module, block) do
-              callme_.must_equal(:ok)
-            end
-          end
-
-          it 'must remove instance variables added by the passed block.' do
-            block = proc { }
-
-            Mixit.mix(@module, block) do 
-              @ok = :no
-            end
-
-            instance_variable_defined?(:@ok).must_equal(false)
-          end
-
-          it 'must remove instance variables added by the mixed in modules.' do 
-            block = proc { }
-
-            Mixit.mix(@module, block) do
-              i
-              instance_variable_defined?(:@i).must_equal(true)
-            end
-
-            instance_variable_defined?(:@i).must_equal(false)
-          end
-
-          it 'must not remove instance variables set before the scope is extended.' do
-            block = proc {}
-            @ok   = :ok
-
-            Mixit.mix(@module, block) do
-              nil
-            end
-            
-            instance_variable_defined?(:@ok).must_equal(true)
-          end
-
-          it 'must remove methods added by mixed in modules.' do
-            block = proc {}
-            
-            Mixit.mix(@module, block) do
-              nil
-            end
-
-            respond_to?(:callme).must_equal(false)
-          end
+      it 'must provide access to surrounding locals.' do
+        block = proc { }
+        local = :ok
+      
+        Mixit.mix(@module, block) do 
+          local.must_equal(:ok)
+        end
+      end
+
+      it 'must provide access to surrounding methods.' do
+        def callme_() :ok end
+        block = proc { }
+
+        Mixit.mix(@module, block) do
+          callme_.must_equal(:ok)
+        end
+      end
+
+      it 'must remove instance variables added by the calling block.' do
+        block = proc { }
+
+        Mixit.mix(@module, block) do 
+          @ok = :no
         end
+
+        instance_variable_defined?(:@ok).must_equal(false)
       end
 
-      context 'With the receiver cloned.' do
-        it 'must provide access to mixed in module methods.' do
-          block = proc {}
+      it 'must remove instance variables added by mixed-in modules.' do 
+        block = proc { }
 
-          Mixit.mix(@module, block) do |receiver|
-            receiver.callme.must_equal(:ok)
-          end
+        Mixit.mix(@module, block) do
+          set_ivar
+          instance_variable_defined?(:@set_ivar).must_equal(true)
         end
 
-        it 'must not extending the original receiver with mixed in module methods.' do
-          block = proc {}
+        instance_variable_defined?(:@set_ivar).must_equal(false)
+      end
+
+      it 'must not remove pre-existing instance variables.' do
+        block = proc {}
+        @ok   = :ok
+
+        Mixit.mix(@module, block) do
+          nil
+        end
+        
+        instance_variable_defined?(:@ok).must_equal(true)
+      end
 
-          Mixit.mix(@module, block) do |receiver|
-            respond_to?(:callme).must_equal(false) 
-          end
+      it 'must remove methods added by mixed-in modules.' do
+        block = proc {}
+        
+        Mixit.mix(@module, block) do
+          nil
         end
+
+        respond_to?(:callme).must_equal(false)
       end
     end
+
+    context 'When receiving a block with a extended object as a param.' do
+      it 'must provide access to mixed-in methods.' do
+        block = proc {}
+
+        Mixit.mix(@module, block) do |receiver|
+          receiver.callme.must_equal(:ok)
+        end
+      end
+
+      it 'must not extend the original receiver with mixed-in methods.' do
+        block = proc {}
+
+        Mixit.mix(@module, block) do |receiver|
+          respond_to?(:callme).must_equal(false) 
+        end
+      end
+   end
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mixit
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-11-19 00:00:00.000000000 Z
+date: 2011-11-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70150457564540 !ruby/object:Gem::Requirement
+  requirement: &70339179578900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 0.9.2
   type: :development
   prerelease: false
-  version_requirements: *70150457564540
+  version_requirements: *70339179578900
 - !ruby/object:Gem::Dependency
   name: minitest
-  requirement: &70150457564040 !ruby/object:Gem::Requirement
+  requirement: &70339179578400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,7 +32,7 @@ dependencies:
         version: '2.5'
   type: :development
   prerelease: false
-  version_requirements: *70150457564040
+  version_requirements: *70339179578400
 description: Temporarily extend the calling scope of a block with instance methods
   from a module.
 email:
@@ -43,7 +43,9 @@ extra_rdoc_files: []
 files:
 - .gitignore
 - .travis.yml
+- .yardopts
 - Gemfile
+- LICENSE.txt
 - README.md
 - Rakefile
 - lib/mixit.rb
@@ -66,7 +68,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -222401743341189092
+      hash: 2621427566551580532
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
@@ -75,7 +77,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -222401743341189092
+      hash: 2621427566551580532
 requirements: []
 rubyforge_project: mixit
 rubygems_version: 1.8.11