binder 0.0.3 → 0.0.4

data/README.rdoc

@@ -11,121 +11,158 @@ binder allows you to change the closure in which a proc is executed. This is hel
 
 The #bind_to method on a proc instance allows you to change the closure in which the proc is run:
   
-  # irb
-  >> require 'binder'
-    ==> true
+  require 'binder'
+  # ==> true
+  
+  def speak
+    "why should i?"
+  end
     
-  >> def speak
-  >>   "why should i?"
-  >> end
-    ==> nil
-
-  >> class Dog
-  >>   def speak
-  >>       "ruff!"
-  >>     end
-  >> end
-    ==> nil
-
-  >> command = proc { speak }
-    ==> #<Proc:0x012c6a04@(irb):28>
-
-  >> command.call
-    ==> "why should i?"  
-
-  >> command.bind_to(Dog.new).call
-    ==> "ruff!"
+  class Dog
+    def speak
+        "ruff!"
+      end
+  end
+  
+  command = proc { speak }  
+  
+  command.call
+  # ==> "why should i?"  
+  
+  command.bind_to(Dog.new).call
+  # ==> "ruff!"
   
+== Object#tell (or #ask, #beg, or #teach)
+
+The "tell"/"ask"/"beg"/"teach" 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: 
+
+  class Dog
+    def speak
+      puts "ruff!"
+    end
+  end
+
+  fido = Dog.new
+
+  fido.instance_eval do
+    speak
+  end
+
+  # ==> would print "ruff!"
+
+  tell fido do
+    speak
+  end
+
+  # or 
+
+  tell(fido) { speak }
+
+  # or
+
+  tell(fido, :to) { speak }
+
+  # ==> would all print "ruff!" - and these are all equivalent to the instance eval above
+
+  commands = proc { speak }
+
+  fido.instance_eval(&commands) 
+  # ==> would print "ruff"
+
+  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
-  >>   bind :do_trick, :self # binds to the instance of Dog
-  >>     
-  >>   def speak
-  >>     "ruff!"
-  >>   end
-  >> end
-    ==> nil
-  
-  >> Dog.new.do_trick { speak }
-    ==> "ruff!"
+  class Dog
+    # binds a "do_trick" instance method to the instance of Dog
+    bind :do_trick, :self 
+      
+    def speak
+      "ruff!"
+    end
+  end
     
-  >> class Cat
-  >>   bind :do_trick, :class # binds to Cat, not an instance of Cat
-  >>   
-  >>   class << self
-  >>     def speak
-  >>       "screw you"
-  >>     end
-  >>   end
-  >>   
-  >>   def speak
-  >>     "bugger off"
-  >>   end
-  >> end
-    ==> nil
+  Dog.new.do_trick { speak }
+  # ==> "ruff!"
     
-  >> 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 
-    ==> nil
+  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"
   
-  >> Kitten.new(Cat).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.new).do_trick { speak }
-    ==> "bugger off"
+  Kitten.new(Cat).do_trick { speak }
+  # ==> "screw you"
   
-  >> Kitten.new(Dog.new).do_trick { speak }
-    ==> "ruff!"
+  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
-  >>   bind :do_trick, :class # binds to Cat class, not an instance of Cat
-  >> 
-  >>   class << self
-  >>     def speak
-  >>       "screw you"
-  >>     end
-  >>   end
-  >>   
-  >>   def speak
-  >>     "bugger off"
-  >>   end
-  >> end
-    ==> nil
+  class Cat
+    # binds to Cat class, not an instance of Cat
+    bind :do_trick, :class 
   
-  >> class Lion
-  >>   bind_class_method :tame, :self # binds to Lion, since "self" will be evaluated in the context
-  >>                                  # of a class method
-  >>   bind_class_method :do_trick, :child # binds to value returned by method "child"
-  >>   class << self
-  >>     def down_kitty
-  >>       "meow"
-  >>     end
-  >>     
-  >>     def child
-  >>       @child ||= Cat
-  >>     end
-  >>   end
-  >> end
-    ==> nil
+    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.tame { down_kitty }
+  # ==> "meow"
     
-  >> Lion.do_trick { speak }
-    ==> "screw you"
+  Lion.do_trick { speak }
+  # ==> "screw you"

data/lib/binder/object.rb

@@ -1,5 +1,19 @@
 class Object
-  class << self
+  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
+  
+  alias ask tell
+  alias teach tell
+  alias beg tell
+    
+  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

data/spec/binder/object_spec.rb

@@ -1,7 +1,30 @@
 require 'spec_helper'
 
 describe Object do
-  describe "#bind" 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: binder
 version: !ruby/object:Gem::Version 
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors: 
 - Matt Parker