binder 0.0.6 → 0.1.0

data/README.rdoc

@@ -1,18 +1,137 @@
+= Motivation
+
+If you're tired of creating APIs like this:
+
+  MyApp.configure do |c|
+    c.description "My app's Description"
+  end
+
+and you long to create APIs like this: 
+
+  MyApp.configure do
+    description "My app's Description"
+  end
+
+Then look no further than this gem. 
+
 = Installation 
 
   # gem install binder
 
 = Use
 
-binder allows you to change the closure in which a proc is executed. This is helpful for anyone developing their own domain specific language in ruby. For more information about proc binding, check out this post I wrote which in turn inspired me to write this gem: http://moonmaster9000.tumblr.com/post/398991873/creating-cleaner-apis
+In truth, there's no magic to this. If you want to change the context in which a block
+gets evaluated, you can use a combination of instance_eval and the fact that you can pass a proc
+to a method as if it were a block by prefixing it with an "&":
+
+  class Dog
+    def do_tricks(&block)
+      instance_eval(&block)
+    end
+
+    def speak
+      puts "ruff!"
+    end
+
+    def fetch
+      puts "fetching...."
+    end
+  end
+
+  Dog.new.do_tricks do
+    speak
+    fetch
+  end
+
+If you're creating a large API like the Rails 3 router, 
+you may find yourself writing a whole lot of mehods that run the block passed to it
+in some other context. 
+
+To dry up the process of creating these methods, you can use the binder gem:
+
+  require 'binder'
+
+  class Dog
+    extend Binder
+    bind :do_tricks, :self
+
+    def speak
+      puts "ruff!"
+    end
+
+    def fetch
+      puts "fetching...."
+    end
+  end
+
+  Dog.new.do_tricks do
+    speak
+    fetch
+  end
+
+First, we passed to bind the name of the method that we wanted to pass our block to; the second
+argument represents the context in which we want our block evaluated. :self, in this case,
+represents the instance of the Dog that we're calling "do_tricks" on. We could have alternatively
+passed a symbol representing an instance method or an instance variable. 
+
+If you wanted to bind class method instead of instance methods, you simply have to extend
+the singleton class: 
+
+  require 'binder'
+
+  class Dog
+    class << self
+      extend Binder
+      bind :do_tricks, :self
+
+      def speak
+        puts "ruff!"
+      end
+
+      def fetch
+        puts "fetching...."
+      end
+    end
+  end
+
+  Dog.do_tricks do
+    speak
+    fetch
+  end
+
+
+
+If you'd rather not have to extend all of your classes with "Binder" everytime you intend
+to use the "bind" class method, you can require 'binder/pervasive' instead. Note, however, that 
+this will pollute your namespace, so if you've happened to define a "bind" method in any of your 
+existing classes, you may run into issues.
+
+  require 'binder/pervasive'
+
+  class Dog
+    bind :do_tricks, :self
+
+    def speak
+      puts "ruff!"
+    end
+
+    def fetch
+      puts "fetching...."
+    end
+  end
+
+  Dog.new.do_tricks do
+    speak
+    fetch
+  end
 
 
 == Proc#bind_to
 
-The #bind_to method on a proc instance allows you to change the closure in which the proc is run:
+In addition to the "bind" method, binder also adds a "bind_to" instance method to the Proc class. 
+It allows you to change the context in which the proc is run:
   
   require 'binder'
-  # ==> true
   
   def speak
     "why should i?"
@@ -32,9 +151,13 @@ The #bind_to method on a proc instance allows you to change the closure in which
   command.bind_to(Dog.new).call
   # ==> "ruff!"
   
-== Object#tell
 
-The "tell" method is essentially short hand for an instance_eval on an object - it simply presents you with a more human readable way of using this language feature: 
+== "Tell" 
+
+The "Tell" method is essentially short hand for an instance_eval on an object - 
+it simply presents you with a more human readable way of using this language feature: 
+
+  require 'binder/tell'
 
   class Dog
     def speak
@@ -50,17 +173,17 @@ The "tell" method is essentially short hand for an instance_eval on an object -
 
   # ==> would print "ruff!"
 
-  tell fido do
+  Tell fido do
     speak
   end
 
   # or 
 
-  tell(fido) { speak }
+  Tell(fido) { speak }
 
   # or
 
-  tell(fido, :to) { speak }
+  Tell(fido, :to) { speak }
 
   # ==> would all print "ruff!" - and these are all equivalent to the instance eval above
 
@@ -69,100 +192,6 @@ The "tell" method is essentially short hand for an instance_eval on an object -
   fido.instance_eval(&commands) 
   # ==> would print "ruff"
 
-  tell fido, commands 
+  Tell fido, commands 
   # ==> would also print "ruff!"
 
-== Object##bind
-
-binder also provides the "#bind" object class method to DRY up your DSL instance methods: 
-
-  class Dog
-    # binds a "do_trick" instance method to the instance of Dog
-    bind :do_trick, :self 
-      
-    def speak
-      "ruff!"
-    end
-  end
-    
-  Dog.new.do_trick { speak }
-  # ==> "ruff!"
-    
-  class Cat
-    # binds a block passed to a "do_trick" instance method to the Cat class
-    bind :do_trick, :class
-    
-    class << self
-      def speak
-        "screw you"
-      end
-    end
-    
-    def speak
-      "bugger off"
-    end
-  end
-    
-  Cat.new.do_trick { speak }
-  # ==> "screw you"
-  
-  class Kitten
-    bind :do_trick, :mother # binds to @mother instance variable
-    
-    def initialize(mom)
-      @mother = mom
-    end
-  end 
-  
-  Kitten.new(Cat).do_trick { speak }
-  # ==> "screw you"
-  
-  Kitten.new(Cat.new).do_trick { speak }
-  # ==> "bugger off"
-  
-  Kitten.new(Dog.new).do_trick { speak }
-  # ==> "ruff!"
-
-== Object##bind_class_method
-  
-Whereas the Object##bind method created instance methods, Object##bind_class_method creates class methods:
-
-  class Cat
-    # binds to Cat class, not an instance of Cat
-    bind :do_trick, :class 
-  
-    class << self
-      def speak
-        "screw you"
-      end
-    end
-    
-    def speak
-      "bugger off"
-    end
-  end
-  
-  class Lion
-    # binds to Lion, since "self" will be evaluated in the context
-    # of a class method
-    bind_class_method :tame, :self 
-    
-    # binds to value returned by method "child"
-    bind_class_method :do_trick, :child 
-    
-    class << self
-      def down_kitty
-        "meow"
-      end
-      
-      def child
-        @child ||= Cat
-      end
-    end
-  end
-     
-  Lion.tame { down_kitty }
-  # ==> "meow"
-    
-  Lion.do_trick { speak }
-  # ==> "screw you"

data/lib/binder.rb

@@ -1,2 +1,2 @@
 require 'binder/proc'
-require 'binder/object'
+require 'binder/binder'

data/lib/binder/binder.rb

@@ -0,0 +1,39 @@
+module Binder
+  def bind(method_name, closure)
+    raise ArgumentError, "You may only pass symbols to #bind" unless closure.kind_of?(Symbol)
+    
+    if closure == :self
+      self.class_eval do
+        eval(
+          "
+          def #{method_name}(&block)
+            if block
+              block.bind_to(self).call
+            end
+          end
+          "
+        )
+      end
+    else
+      self.class_eval do
+        eval(
+          "
+          def #{method_name}(&block)
+            if block
+              # if we're suposed to bind an object returned by a method
+              if self.respond_to?(:#{closure})
+                block.bind_to(self.#{closure}).call
+              # if self has an instance variable 
+              elsif @#{closure}
+                block.bind_to(@#{closure}).call
+              else
+                raise StandardError, \"Trying to bind to an unknown method or variable: #{closure}\"
+              end
+            end
+          end
+          "
+        )
+      end
+    end      
+  end
+end

data/lib/binder/object.rb

@@ -1,54 +1,3 @@
 class Object
-  def tell(closure, relayed_message=nil, &message)
-    if relayed_message && relayed_message.kind_of?(Proc)
-      closure.instance_eval(&relayed_message)
-    elsif message 
-      closure.instance_eval(&message)
-    else
-      raise StandardError, "What is your command?"
-    end
-  end
-    
-  class << self    
-    def bind_in_context(method_name, closure, eval_context=:class_eval)
-      raise ArgumentError, "You may only pass symbols to #bind and #bind_class_method" unless closure.kind_of?(Symbol)
-      if closure == :self
-        self.send(eval_context) do
-          eval(
-            "
-            def #{method_name}(&block)
-              if block
-                block.bind_to(self).call
-              end
-            end
-            "
-          )
-        end
-      else
-        self.send(eval_context) do
-          eval(
-            "
-            def #{method_name}(&block)
-              if block
-                if self.respond_to?(:#{closure})
-                  block.bind_to(self.#{closure}).call
-                elsif @#{closure}
-                  block.bind_to(@#{closure}).call
-                else
-                  block.bind_to(self.#{closure}).call
-                end
-              end
-            end
-            "
-          )
-        end
-      end      
-    end
-    
-    alias_method :bind, :bind_in_context
-    
-    def bind_class_method(method_name, closure)
-      bind_in_context method_name, closure, :instance_eval
-    end
-  end
+  extend Binder
 end

data/lib/binder/pervasive.rb

@@ -0,0 +1,4 @@
+require 'binder/proc'
+require 'binder/binder'
+require 'binder/object'
+require 'binder/tell'

data/lib/binder/tell.rb

@@ -0,0 +1,3 @@
+def Tell(obj, &block)
+  obj.instance_eval(&block) if block
+end

data/spec/binder/binder_spec.rb

@@ -0,0 +1,95 @@
+require 'spec_helper'
+require 'binder'
+
+describe Binder do
+  describe "##bind" do
+    it "should create a new instance method that evaluates the block passed it within the requested closure" do
+      proc do
+        class Platypus
+          extend Binder
+          bind :do_trick, "invalid argument"
+        end
+      end.should raise_error(ArgumentError, "You may only pass symbols to #bind")
+      
+      class Dog
+        extend Binder
+        bind :do_trick, :self
+      
+        def speak
+          "ruff!"
+        end
+      end
+    
+      Dog.new.do_trick { speak }.should == "ruff!"
+    
+      class Cat
+        extend Binder
+        bind :do_trick, :class
+      
+        class << self
+          def speak
+            "screw you"
+          end
+        end
+      
+        def speak
+          "bugger off"
+        end
+      end
+    
+      Cat.new.do_trick { speak }.should == "screw you"
+    
+      class Kitten
+        extend Binder
+        bind :do_trick, :mother
+      
+        def initialize(mom)
+          @mother = mom
+        end
+      end 
+    
+      Kitten.new(Cat).do_trick { speak }.should == "screw you"
+      Kitten.new(Cat.new).do_trick { speak }.should == "bugger off"
+      Kitten.new(Dog.new).do_trick { speak }.should == "ruff!"
+    
+    end
+  
+    describe "#bind in the singleton class" do
+      it "should create a class method responder that binds to either a new class or the return value of a class method" do
+        class Cat
+          extend Binder
+          bind :do_trick, :class
+
+          class << self
+            def speak
+              "screw you"
+            end
+          end
+
+          def speak
+            "bugger off"
+          end
+        end
+        
+        class Lion
+          class << self
+            extend Binder
+            bind :tame, :self
+            bind :do_trick, :child
+          
+            def down_kitty
+              "meow"
+            end
+
+            def child
+              @child ||= Cat
+            end
+          end
+        end
+
+        Lion.tame {down_kitty}.should == "meow"
+        Lion.do_trick { speak }.should == "screw you"
+      end
+    end
+  end
+end

data/spec/binder/object_spec.rb

@@ -1,36 +1,14 @@
 require 'spec_helper'
+require 'binder/pervasive'
 
 describe Object do
-  describe "#tell" do
-    it "should run the given block or proc inside the requested object closure" do
-      class Baby
-        def say_dada
-          "waaaa"
-        end
-      end
-            
-      Object.new.tell(Baby.new) { say_dada }.should == "waaaa"
-      Object.tell(Baby.new) { say_dada }.should == "waaaa"
-      tell(Baby.new) { say_dada }.should == "waaaa"
-      
-      tell Baby.new, :to do
-        say_dada
-      end
-
-      to_say_dada = proc { say_dada }      
-      Object.new.tell(Baby.new, to_say_dada).should == "waaaa"
-      Object.tell(Baby.new, to_say_dada).should == "waaaa"
-      tell(Baby.new, to_say_dada).should == "waaaa"
-    end
-  end
-
   describe "##bind" do
     it "should create a new instance method that evaluates the block passed it within the requested closure" do
       proc do
         class Platypus
           bind :do_trick, "invalid argument"
         end
-      end.should raise_error(ArgumentError, "You may only pass symbols to #bind and #bind_class_method")
+      end.should raise_error(ArgumentError, "You may only pass symbols to #bind")
       
       class Dog
         bind :do_trick, :self
@@ -72,7 +50,7 @@ describe Object do
     
     end
   
-    describe "#bind_class_method" do
+    describe "#bind in the singleton class" do
       it "should create a class method responder that binds to either a new class or the return value of a class method" do
         class Cat
           bind :do_trick, :class
@@ -89,9 +67,10 @@ describe Object do
         end
         
         class Lion
-          bind_class_method :tame, :self
-          bind_class_method :do_trick, :child
           class << self
+            bind :tame, :self
+            bind :do_trick, :child
+          
             def down_kitty
               "meow"
             end

data/spec/binder/proc_spec.rb

@@ -1,4 +1,5 @@
 require 'spec_helper'
+require 'binder/proc'
 
 describe Proc do
   describe "#bind_to" do

data/spec/binder/tell_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+require 'binder/tell'
+
+describe "Tell" do 
+  it "should raise an error if an object isn't passed to it" do
+    proc {Tell()}.should raise_error(ArgumentError)
+  end
+
+  it "should not raise an error if an object, but not a block, is passed to it" do
+    proc {Tell "hello"}.should_not raise_error
+    Tell("hello").should == nil
+  end
+
+  it "should run an instance_eval on the object" do
+    str = "hello"
+    str.should_receive(:instance_eval).and_return :hello
+    Tell(str) { to_sym }
+  end
+
+  it "should run the block within the context of the object" do
+    Tell("hi") { to_sym }.should == :hi
+  end
+end

data/spec/spec_helper.rb

@@ -1,2 +1 @@
 $LOAD_PATH.unshift './lib'
-require 'binder'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: binder
 version: !ruby/object:Gem::Version 
-  version: 0.0.6
+  version: 0.1.0
 platform: ruby
 authors: 
 - Matt Parker
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-23 00:00:00 -05:00
+date: 2010-03-07 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -24,8 +24,11 @@ extra_rdoc_files:
 files: 
 - README.rdoc
 - lib/binder.rb
+- lib/binder/binder.rb
 - lib/binder/object.rb
+- lib/binder/pervasive.rb
 - lib/binder/proc.rb
+- lib/binder/tell.rb
 has_rdoc: true
 homepage: http://github.com/moonmaster9000/binder
 licenses: []
@@ -55,6 +58,8 @@ signing_key:
 specification_version: 3
 summary: A tool for rebinding your ruby procs, with a helper for DSL creaters.
 test_files: 
+- spec/binder/binder_spec.rb
 - spec/binder/object_spec.rb
 - spec/binder/proc_spec.rb
+- spec/binder/tell_spec.rb
 - spec/spec_helper.rb