andand 1.2.1 → 1.3.0

data/History.txt

@@ -1,4 +1,4 @@
-== 1.1.0 2008-02-03
+== 1.3.0 2008-07-12
 
 * 1 major enhancement:
   * Initial release
@@ -10,3 +10,5 @@
   * Object#dont
 * 5 bug fix
   * Plays well with other patch-artists
+* 6 minor enhancement
+  * uses existing BlankSlate class if already defined

data/lib/andand.rb

@@ -2,8 +2,24 @@ $:.unshift File.dirname(__FILE__)
 
 module AndAnd
   
+  # This module is included in Object, so each of these methods are added
+  # to Object when you require 'andand'. Each method is an *adverb*: they are
+  # intended to be enchained with another method, such as receiver.adverb.method
+  #
+  # The purpose of an adverb is to modify what the primary method returns.
+  #
+  # Adverbs also take blocks or procs, passing the receiver as an argument to the
+  # block or proc. They retain the same semantics with a block or proc as they
+  # do with a method. This behaviour weakly resembles a monad.
   module ObjectGoodies
     
+    # Returns nil if its receiver is nil, regardless of whether nil actually handles the
+    # actual method ot what it might return. 
+    #
+    #    'foo'.andand.size => 3
+    #    nil.andand.size => nil
+    #    'foo'.andand { |s| s << 'bar' } => 'foobar'
+    #    nil.andand { |s| s << 'bar' } => nil
     def andand (p = nil)
       if self
         if block_given?
@@ -21,7 +37,24 @@ module AndAnd
         end
       end 
     end
-    
+
+    # Invokes the method and returns the receiver if nothing is raised. Therefore,
+    # the purpose of calling the method is strictly for side effects. In the block
+    # form, it resembles #tap from Ruby 1.9, and is useful for debugging. It also
+    # resembles #returning from Rails, with slightly different syntax.
+    #
+    #    Object.new.me do |o|
+    #      def o.foo
+    #        'foo'
+    #      end
+    #    end
+    #      => your new object
+    #
+    # In the method form, it is handy for chaining methods that don't ordinarily
+    # return the receiver:
+    #
+    #    [1, 2, 3, 4, 5].me.pop.reverse
+    #      => [4, 3, 2, 1]
     def me (p = nil)
       if block_given?
         yield(self)
@@ -34,8 +67,19 @@ module AndAnd
       end
     end
     
-    alias :tap :me
+    unless Object.instance_methods.include?('tap')
+      alias :tap :me
+    end
     
+    # Does not invoke the method or block and returns the receiver.
+    # Useful for comemnting stuff out, especially if you are using #me for
+    # debugging purposes: change the .me to .dont and the semantics of your
+    # program are unchanged.
+    #
+    #    [1, 2, 3, 4, 5].me { |x| p x }
+    #      => prints and returns the array
+    #    [1, 2, 3, 4, 5].dont { |x| p x }
+    #      => returns the array without printing it
     def dont (p = nil)
       if block_given?
         self
@@ -53,26 +97,41 @@ end
 class Object
   include AndAnd::ObjectGoodies
 end
+  
+unless Module.constants.include?('BlankSlate')
+  module AndAnd
+    class BlankSlate
+      def self.wipe
+        instance_methods.reject { |m| m =~ /^__/ }.each { |m| undef_method m }
+      end
+      def initialize
+        BlankSlate.wipe
+      end
+    end
+  end
+end
 
 module AndAnd
   
-  class BlankSlate
-    def self.wipe
-      instance_methods.reject { |m| m =~ /^__/ }.each { |m| undef_method m }
-    end
+  # A proxy that returns its target without invoking the method you
+  # invoke. Useful for nil.andand and #dont
+  class MockReturningMe < BlankSlate
     def initialize(me)
-      BlankSlate.wipe
+      super()
       @me = me
     end
-  end
-  
-  class MockReturningMe < BlankSlate
     def method_missing(*args)
       @me
     end
   end
-  
+
+  # A proxy that returns its target after invoking the method you
+  # invoke. Useful for #me
   class ProxyReturningMe < BlankSlate
+    def initialize(me)
+      super()
+      @me = me
+    end
     def method_missing(sym, *args, &block)
       @me.__send__(sym, *args, &block)
       @me

data/lib/andand/version.rb

@@ -1,8 +1,8 @@
 module Andand #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 1
-    MINOR = 2
-    TINY  = 1
+    MINOR = 3
+    TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/website/index.html

@@ -33,7 +33,7 @@
     <h1>Object#andand</h1>
     <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/andand"; return false'>
       <p>Get Version</p>
-      <a href="http://rubyforge.org/projects/andand" class="numbers">1.2.1</a>
+      <a href="http://rubyforge.org/projects/andand" class="numbers">1.3.0</a>
     </div>
     <h1>&#x2192; &#8216;andand&#8217;</h1>
 
@@ -217,7 +217,7 @@
 
 	<p>Comments are welcome. Send an email to <a href="mailto:raganwald+rubyforge@gmail.com">Reginald Braithwaite</a>.</p>
     <p class="coda">
-      <a href="http://weblog.raganwald.com">Reginald Braithwaite</a>, 6th April 2008<br>
+      <a href="http://weblog.raganwald.com">Reginald Braithwaite</a>, 12th July 2008<br>
       Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
     </p>
 </div>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: andand
 version: !ruby/object:Gem::Version 
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors: 
 - Reginald Braithwaite
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-07-10 00:00:00 -04:00
+date: 2008-07-13 00:00:00 -04:00
 default_executable: 
 dependencies: []