ryansch-andand 1.3.2

data/History.txt

@@ -0,0 +1,25 @@
+== 1.3.2
+
+* 1 minor enhancement
+  * better docs
+* 2 major enhancement:
+  * Fix 1.9 warning (patch by George MacKerron)
+* 3 major enhancement:
+  * Remove deprecated gemspec information (patch by Anthony Panozzo)
+
+== 1.3.1 2008-07-12
+
+* 1 major enhancement:
+  * Initial release
+* 2 tiny enhancement:
+  * fixed specifications
+* 3 minor enhancement
+  * tap is now a synonym for me
+* 4 minor enhancement
+  * Object#dont
+* 5 bug fix
+  * Plays well with other patch-artists
+* 6 minor enhancement
+  * uses existing BlankSlate class if already defined
+* 7 tiny enhancement
+  * use BasicObject as well

data/License.txt

@@ -0,0 +1,26 @@
+Copyright (c) 2008 Reginald Braithwaite
+http://weblog.raganwald.com/2008/01/objectandand-objectme-in-ruby.html
+
+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.
+
+Some code adapted from Jim Weirich's post:
+http://onestepback.org/index.cgi/Tech/Ruby/BlankSlate.rdoc

data/README.textile

@@ -0,0 +1,162 @@
+h1. Object#andand
+
+h2. Breaking News
+
+@Object#andand@'s functionality is also available as part of the "RewriteRails":http://github.com/raganwald/rewrite_rails plug-in. If you are using Ruby on Rails, please consider using RewriteRails instead of the andand gem.
+
+h2. What
+
+@Object#andand@ lets us write:
+
+<pre syntax="ruby">
+@phone = Location.find(:first, ...elided... ).andand.phone
+</pre>And get a _guarded method invocation_ or _safe navigation method_. This snippet performs a @.find@ on the Location class, then sends @.phone@ to the result _if the result is not nil_. If the result is nil, then the expression returns nil without throwing a NoMethodError.
+
+As Dejan Simic "put it":http://rors.org/2008/3/18/andand:
+
+Why would you want to write this:
+
+<pre syntax="ruby">
+entry.at('description') && entry.at('description').inner_text
+</pre>when you can write this:
+
+<pre syntax="ruby">
+entry.at('description').andand.inner_text
+</pre>Why indeed! As a bonus, install andand and you will also receive an enhanced Object#tap method, _at no extra charge_!
+
+h2. Installing
+
+Update to RubyGems 1.2.0 before proceeding!!
+
+<pre syntax="ruby">sudo gem sources -a http://gems.github.com (you only have to do this once)
+sudo gem install raganwald-andand</pre>
+
+Or:
+
+<pre syntax="ruby">git clone git://github.com/raganwald/andand.git
+cd andand
+rake gem
+rake install_gem</pre>
+
+h2. The basics
+
+h3. Object#andand
+
+Ruby programmers are familiar with the two _guarded assignment_ operators @&&=@ and @||=@. The typical use for them is when you have a variable that might be nil. For example:
+
+<pre syntax="ruby">
+first_name &&= @first_name.trim
+@phone ||= '612-777-9311'
+</pre>You are trimming the first name provided it isn’t nil, and you are assigning ‘612-777-9311’ to the phone if it _is_ nil (or false, but that isn’t important right now). The other day we were discussing the guards and we agreed that we wished there was a _guarded method invocation_ operator. Here’s an example of when you would use it:
+
+<pre syntax="ruby">
+@phone = Location.find(:first, ...elided... )&&.phone
+</pre>Meaning, search the location table for the first record matching some criteria, and if you find a location, get its phone. If you don’t, get nil. (Groovy provides this exact functionality, although Groovy uses @?.@ instead of @&&.@) However, @&&.@ won’t work because @&&.@ is not a real Ruby operator.
+
+Object#andand let&rsquo;s us write:
+
+<pre syntax="ruby">
+@phone = Location.find(:first, ...elided... ).andand.phone
+</pre>And get the same effect as:
+
+<pre syntax="ruby">
+@phone = ->(loc){ loc && loc.phone }.call(Location.find(:first, ...elided... ))
+</pre>Note that because you accept any method using Ruby’s method invocation syntax, you can accept methods with parameters and/or blocks:
+
+<pre syntax="ruby">
+list_of_lists.detect { ...elided... }.andand.inject(42) { ...elided ... }
+</pre>Object#andand emphasizes syntactic regularity: the goal was to make an @&&.@ operation that worked like @&&=@. @&&=@ looks just like normal assignment, you can use any expression on the RHS, only the semantics are different. The andand method also works just like a normal method invocation, only the semantics are modified.
+
+h3. Block-Structured andand
+
+You can use @andand@ with a block instead of a method:
+
+<pre syntax="ruby">
+@phone =  Location.find(:first, ...elided... ).andand { |location|
+  YellowPages.reverse_lookup(location).phone
+}
+</pre>If the receiver is nil, the block is not executed and @andand@ returns @nil@. If the receiver is not nil, it is passed as a parameter to the block and @andand@ returns the value of the block. This makes it possible to perform conditional evaluation and also to make the scope of the variable really obvious.
+
+h3. Scope
+
+@Object#andand@ only works for one method call. For example, @fu.andand.bar.blitz@ is going to call @nil.blitz@ if @fu@ is @nil@. That's because @fu.andand.bar@ is going to evaluate to @nil@, and then we will call the method @blitz@ on it. In most cases, you want to use @fu.andand.bar.andand.blitz@. If that seems awkward, you might want to reconsider violating the Law of Demeter in an environment where you can't be sure if your receiver is @nil@ or not.
+
+Another example of this (pointed out by Jan Zimmek):
+
+<pre syntax="ruby">
+x = nil
+x.andand.length > 3
+</pre>This results in a @NoMethodError@. Again, @x@ is @nil@, therefore @x.andand.length@ is @nil@, therefore we end up with @nil > 3@ which results in a @NoMethodError@. This can be fixed with @x.andand.length.andand > 3@ as above, or perhaps:
+
+<pre syntax="ruby">
+x = nil
+x.andand { |value| value.length > 3 }
+</pre>
+
+h3. Enhanced Object#tap
+
+Ruby 1.9 introduces "Object#tap":http://moonbase.rydia.net/mental/blog/programming/eavesdropping-on-expressions. This library implements Object#tap for Ruby 1.8 *and* enhances it. As in Ruby 1.9, you can call @.tap@ with a block:
+
+<pre syntax="ruby">
+	blah.sort.grep( /foo/ ).tap { |xs| p xs }.map { |x| x.blah }
+</pre> But like its sibling @.andand@, you can now call @.tap@ with a method as well:
+
+<pre syntax="ruby">
+	[1, 2, 3, 4, 5].tap.pop.map { |n| n * 2 }
+    	=> [2, 4, 6, 8]
+</pre>
+
+h3. Doctor, it hurts when I do that
+
+_So don't do that!_
+
+The popular use case for Object#tap is poor man's debugging:
+
+<pre syntax="ruby">
+	blah.sort.grep( /foo/ ).tap { |xs| p xs }.map { |x| x.blah }
+</pre>Perhaps you want to remove the tap, you can delete it:
+
+<pre syntax="ruby">
+	blah.sort.grep( /foo/ ).map { |x| x.blah }
+</pre>Or, you can change it to @.dont@:
+
+<pre syntax="ruby">
+	blah.sort.grep( /foo/ ).dont { |xs| p xs }.map { |x| x.blah }
+</pre>Like @.andand@ and @.tap@, @.dont@ works with arbitrary methods, not just blocks:
+
+<pre syntax="ruby">
+	(1..10).to_a.reverse!
+	    => [10, 9, 8, 7, 6, 5, 4, 3, 2, 1]
+	(1..10).to_a.dont.reverse!
+	    => [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+</pre>
+
+h2. A little more background
+
+"Object#andand & Object#me in Ruby":http://weblog.raganwald.com/2008/01/objectandand-objectme-in-ruby.html explains the original motivations, as well as providing links to similar implementations you may want to consider. A few people have pointed out that Object#andand is similar to Haskell's Maybe monad. "The Maybe Monad in Ruby":http://blog.pretheory.com/arch/2008/02/the_maybe_monad_in_ruby.php is a good introduction for Ruby programmers.
+
+h2. That's cool, but&hellip;
+
+No problem, I get that andand isn't exactly what you need. Have a look at the "Invocation Construction Kit":http://ick.rubyforge.org or "Ick." The Ick gem _generalizes_ #andand and #tap: Ick provides four useful ways to block-structure your code, the methods #let, #returning, #inside, and #my. Ick also includes four quasi-monadic invocations, #maybe, #please, #tee, and #fork.
+
+"Ick":http://ick.rubyforge.org provides abstractions for building your own invocations, so you can branch out and build some of your own abstractions with Ick's building blocks.
+
+h2. How to submit patches
+
+Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/.
+
+The public clone url is @git://github.com/raganwald/andand.git@. Fork you very much.
+
+h2. License
+
+This code is free to use under the terms of the "MIT license":http://en.wikipedia.org/wiki/MIT_License. 
+
+h2. Shout Out
+
+"Mobile Commons":http://mcommons.com/. Huge.
+
+Also interesting: "Wicked":http://github.com/wideopenspaces/wicked
+
+h2. Contact
+
+Comments are welcome. Send an email to "Reginald Braithwaite":mailto:raganwald@gmail.com.

data/lib/andand.rb

@@ -0,0 +1,148 @@
+$:.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?
+          yield(self)
+        elsif p
+          p.to_proc.call(self)
+        else
+          self
+        end
+      else
+        if block_given? or p
+          self
+        else
+          MockReturningMe.new(self)
+        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)
+        self
+      elsif p
+        p.to_proc.call(self)
+        self
+      else
+        ProxyReturningMe.new(self)
+      end
+    end
+    
+    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
+      elsif p
+        self
+      else
+        MockReturningMe.new(self)
+      end
+    end
+    
+  end
+  
+end
+
+class Object
+  include AndAnd::ObjectGoodies
+end
+  
+unless Module.constants.map { |c| c.to_s }.include?('BlankSlate')
+ if Module.constants.map { |c| c.to_s }.include?('BasicObject')
+    module AndAnd
+      class BlankSlate < BasicObject
+      end
+    end
+  else
+    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
+end
+
+module AndAnd
+  
+  # A proxy that returns its target without invoking the method you
+  # invoke. Useful for nil.andand and #dont
+  class MockReturningMe < BlankSlate
+    def initialize(me)
+      super()
+      @me = me
+    end
+    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
+    end
+  end
+  
+end

data/lib/andand/version.rb

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

data/test/andand_spec.rb

@@ -0,0 +1,133 @@
+=begin
+
+Copyright (c) 2008 Reginald Braithwaite
+http://weblog.raganwald.com/2008/01/objectandand-objectme-in-ruby.html
+
+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.
+
+=end
+
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+require 'andand'
+
+class Symbol
+  def to_proc
+    Proc.new { |*args| args.shift.__send__(self, *args) }
+  end
+end
+
+describe AndAnd, "Basic Behaviour" do
+  it "should conditionally yield to a block" do
+    5.andand { |n| n*n }.should == 25
+    5.andand(&:succ).should == 6
+    nil.andand { |n| n*n }.should == nil
+    false.andand { |n| n*n }.should == false
+  end
+  it "should conditionally call a proc-able parameter" do
+    5.andand(:succ).should == 6
+    nil.andand(:succ).should == nil
+    false.andand(:succ).should == false
+  end
+  it "should conditionally proxy methods" do
+    5.andand.succ.should == 6
+    nil.andand.succ.should == nil
+    false.andand.succ.should == false
+    (1..10).andand.inject(&:+).should == 55
+    nil.andand.inject(&:+).should == nil
+    false.andand.inject(&:+).should == false
+    'HelloWeblogReaders'.andand[7,4].should == 'blog'
+    nil.andand[7,4].should == nil
+    false.andand[7,4].should == false
+    'HelloWeblogReaders'.andand.tr('Wb','Bd').should == 'HelloBedlogReaders'
+    nil.andand.tr('Wb','Bd').should == nil
+    false.andand.tr('Wb','Bd').should == false
+  end
+  it "should handle infix operators" do
+    (5.andand * 2).should == 10
+    (nil.andand * 2).should == nil
+    (false.andand * 2).should == false
+  end
+end
+
+describe AndAnd, "Me" do
+  it "should unconditionally yield to a block" do
+    5.me { |n| n*n }.should == 5
+    5.me(&:succ).should == 5
+    nil.me { |n| n || true }.should be_nil
+    false.me { |n| n || true }.should == false
+  end
+  it "should unconditionally call a proc-able parameter" do
+    5.me(:to_s).should == 5
+    nil.me(:to_s).should == nil
+    false.me(:to_s).should == false
+  end
+  it "should proxy methods" do
+    5.me.to_s.should == 5
+    nil.me.to_s.should == nil
+    false.me.to_s.should == false
+    (1..10).me.inject(&:+).should == (1..10)
+    'HelloWeblogReaders'.me[7,4].should == 'HelloWeblogReaders'
+    'HelloWeblogReaders'.me.tr('Wb','Bd').should == 'HelloWeblogReaders'
+  end
+  it "should handle infix operators" do
+    (5.me * 2).should == 5
+  end
+end
+
+describe AndAnd, "Mixing Me with AndAnd" do
+  it "should compose me.andand" do
+    frobbish = :blitz
+    :foo.me.andand do
+      frobbish = :bar
+    end.should == :foo
+    frobbish.should == :bar
+    nil.me.andand do
+      frobbish = :barbarella
+    end.should be_nil
+    frobbish.should == :bar
+    false.me.andand do
+      frobbish = :hope
+    end.should == false
+    frobbish.should == :bar
+  end
+end
+
+class Foo
+  def frobbish
+    'fnord'
+  end
+end
+
+describe AndAnd, "exception handling" do
+  it "should not swallow NoMethodErrors" do
+    foo = Foo.new
+    lambda do
+      foo.andand.frobbish
+      nil.andand.frobbish
+      nil.andand.hsibborf
+    end.should_not raise_error
+    lambda do
+      foo.andand.hsibborf
+    end.should raise_error
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,2 @@
+require 'test/unit'
+require File.dirname(__FILE__) + '/../lib/andand'

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: ryansch-andand
+version: !ruby/object:Gem::Version 
+  hash: 31
+  prerelease: 
+  segments: 
+  - 1
+  - 3
+  - 2
+  version: 1.3.2
+platform: ruby
+authors: 
+- Reg Braithwaite
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-11-07 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: " Maybe Monad in idiomatic Ruby."
+email: reg@braythwayt.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- README.textile
+files: 
+- History.txt
+- License.txt
+- README.textile
+- lib/andand.rb
+- lib/andand/version.rb
+- test/andand_spec.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/ryansch/andand
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.textile
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: The Maybe Monad in idiomatic Ruby
+test_files: 
+- test/andand_spec.rb
+- test/test_helper.rb