its-it 1.0.1 → 1.1.0

data/README.rdoc

@@ -2,7 +2,14 @@
 
 == Overview
 
-This gem defines kernel methods <code>its</code> and <code>it</code> that extend the Symbol#to_proc idiom to support chaining multiple methods.
+This gem defines kernel methods <code>its</code> and <code>it</code> that
+queue and defer method calls. This is handy for list enumeration and case
+statements.
+
+== List Enumeration
+
+<code>its</code> and <code>it</code> extend the Symbol#to_proc idiom to
+support chaining multiple methods.
 
 The pure Ruby way to chain methods when enumerating a list would be:
 
@@ -16,11 +23,66 @@ And using <code>its</code>, this becomes becomes simpler still:
 
         users.collect(&its.contact.last_name.capitalize)
 
+Note that <code>its</code> captures arguments and blocks, allowing constructs like this,
+which will select users whose names include any non-hyphenated word that's more than 10
+letters long:
+        users.select(&its.name.split(/ /).reject{|word| word =~ /-/}.collect(&:length).max > 10)
+
 <code>it</code> is an alias for <code>its</code>, to use with methods that
 describe actions rather than posessives. For example:
 
         items.collect(&it.to_s.capitalize)
 
+== Case statements
+
+<code>its</code> and <code>it</code> likewise extend Ruby's
+<code>code</code> statement to support testing arbitrary methods,
+minimizing the need to create temporary variables and use
+<code>if-elsif</code> constructs.
+
+In pure Ruby, doing comparisons on computed values would be done something
+like this:
+
+        maxlen = arrays.collect(&size).max
+        if maxlen > 10000
+            "too big"
+        elsif maxlen < 10
+            "too small"
+        else
+            "okay"
+        end
+
+But using <code>it</code> this becomes:
+
+        case arrays.collect(&size).max
+        when it > 1000
+            "too big"
+        when it < 10
+            "too small"
+        else
+            "okay"
+        end
+
+Of course method chanining can be used here too:
+
+        case users.first
+        when its.name == "Gimme Cookie" then ...
+        when its.name.length > 10 then ...
+        else ...
+        end
+
+== Under the hood
+
+The <code>ItsIt::It</code> class starts from <code>BlankSlate</code>, and
+uses <code>method_missing</code> to capture and queue up all methods and
+their arguments, with the exception of <code>:to_proc</code> and <code>:===</code>
+(and also excepting <code>:respond_to? :to_proc</code> and
+<code>:respond_to? :===</code>).
+
+<code>:to_proc</code> returns a proc that will evaluate the method queue on
+a given argument.  <code>:===</code> takes an argument and evaluates that
+proc, returning the result.
+
 == Installation
 
 Install from http://rubygems.org via
@@ -37,8 +99,9 @@ Tested with <b>ruby 1.8.7</b> and <b>ruby 1.9.2</b>
 
 == History
 
-This gem is a clone of Jay Philips'
-methodphitamine[https://github.com/jicksta/methodphitamine] gem, updated to
-be compatible with ruby 1.9.2 and gemspec, renamed its-it, and installed on
-rubygems.org[http://rubygems.org].  Unlike methodphitamine, this gem includes only
-<code>its</code> and <code>it</code>, not the "maybe" monad.
+This gem is orignally based on Jay Philips'
+methodphitamine[https://github.com/jicksta/methodphitamine] gem. It has
+been updated to be compatible with ruby 1.9.2 and gemspec, renamed its-it,
+and installed on rubygems.org[http://rubygems.org].  Unlike
+methodphitamine, this gem includes only <code>its</code> and
+<code>it</code>, not the "maybe" monad.

data/its-it.gemspec

@@ -5,19 +5,21 @@ Gem::Specification.new do |s|
   s.name = 'its-it'
   s.version = ItsIt::VERSION
   s.platform = Gem::Platform::RUBY
-  s.date = "2011-04-23"
+  s.date = "2011-04-26"
   s.authors = ['Ronen Barzel']
   s.email = 'ronen@barzel.org'
   s.homepage = 'http://github.com/ronen/its-it'
-  s.summary = %q{Defines its() and it() method-chain proc proxies.}
+  s.summary = %q{Defines its() and it() method-chain proxies.}
   s.description = %q{
-This gem defines the Kernel method "it", which extends the Symbol#to_proc
-idiom to support chaining multiple methods.  For example,
-items.collect(&it.to_s.capitalize).  The method is also aliased as "its",
-for methods that describe possessives rather than actions, such as
-items.collect(&its.name.capitalize)
+This gem defines the Kernel method "it" that queue and defer method calls.
+This extends the Symbol#to_proc idiom to support chaining multiple methods.
+For example, items.collect(&it.to_s.capitalize).  This also allows
+conditionals in case statements, such as: case ... when it > 3 then [etc.].
+The method is also aliased as "its", for methods that describe possessives
+rather than actions, such as items.collect(&its.name.capitalize)
 
-[This gem is clone of Jay Philips' "methodphitamine" gem, updated for ruby 1.9 and gemspec compatibility.]
+[This gem is an extension of Jay Philips' "methodphitamine" gem, updated
+for ruby 1.9 and gemspec compatibility and adding the case statement functionality.]
 }
   s.extra_rdoc_files = [
     "LICENSE.txt",

data/lib/its-it/it.rb

@@ -17,7 +17,7 @@ module ItsIt
     end
     
     def method_missing(*args, &block)
-      @methods << [args, block] unless args == [:respond_to?, :to_proc]
+      @methods << [args, block] unless args.first == :respond_to? and [:to_proc, :===].include?(args[1])
       self
     end
   
@@ -29,6 +29,10 @@ module ItsIt
       end
     end
 
+    def ===(obj)
+      to_proc.call(obj)
+    end
+
     # Used for testing.  This method is hidden but can be revealed using
     #   ItsIt::It.reveal(:method_queue)
     def method_queue

data/lib/its-it/version.rb

@@ -1,3 +1,3 @@
 module ItsIt
-  VERSION = "1.0.1"
+  VERSION = "1.1.0"
 end

data/spec/it_spec.rb

@@ -47,10 +47,29 @@ describe "An It instance" do
   it "should respond to to_proc()" do
     @it.should respond_to(:to_proc)
   end
+
+  it "should respond to ===" do
+    @it.should respond_to(:===)
+  end
+
+  it "should work in a case statement" do
+    [0,1,2].each do |i|
+      case i
+      when it < 1 then i.should == 0
+      when it == 1 then i.should == 1
+      else i.should == 2
+      end
+    end
+  end
   
   it "should not queue the method respond_to? when given :to_proc as an arg" do
     @it.respond_to? :to_proc
     @it.method_queue.should be_empty
   end
+
+  it "should not queue the method respond_to? when given :=== as an arg" do
+    @it.respond_to? :to_proc
+    @it.method_queue.should be_empty
+  end
   
 end

metadata

@@ -2,7 +2,7 @@
 name: its-it
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors: 
 - Ronen Barzel
@@ -10,7 +10,8 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-23 00:00:00 Z
+date: 2011-04-26 00:00:00 -07:00
+default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: blankslate
@@ -79,12 +80,14 @@ dependencies:
   prerelease: false
   version_requirements: *id006
 description: "\n\
-  This gem defines the Kernel method \"it\", which extends the Symbol#to_proc\n\
-  idiom to support chaining multiple methods.  For example,\n\
-  items.collect(&it.to_s.capitalize).  The method is also aliased as \"its\",\n\
-  for methods that describe possessives rather than actions, such as\n\
-  items.collect(&its.name.capitalize)\n\n\
-  [This gem is clone of Jay Philips' \"methodphitamine\" gem, updated for ruby 1.9 and gemspec compatibility.]\n"
+  This gem defines the Kernel method \"it\" that queue and defer method calls.\n\
+  This extends the Symbol#to_proc idiom to support chaining multiple methods.\n\
+  For example, items.collect(&it.to_s.capitalize).  This also allows\n\
+  conditionals in case statements, such as: case ... when it > 3 then [etc.].\n\
+  The method is also aliased as \"its\", for methods that describe possessives\n\
+  rather than actions, such as items.collect(&its.name.capitalize)\n\n\
+  [This gem is an extension of Jay Philips' \"methodphitamine\" gem, updated\n\
+  for ruby 1.9 and gemspec compatibility and adding the case statement functionality.]\n"
 email: ronen@barzel.org
 executables: []
 
@@ -109,6 +112,7 @@ files:
 - spec/it_spec.rb
 - spec/rspec_compatibility_spec.rb
 - spec/spec_helper.rb
+has_rdoc: true
 homepage: http://github.com/ronen/its-it
 licenses: []
 
@@ -122,7 +126,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 143375
+      hash: -664830529632804485
       segments: 
       - 0
       version: "0"
@@ -135,10 +139,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.7.2
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
-summary: Defines its() and it() method-chain proc proxies.
+summary: Defines its() and it() method-chain proxies.
 test_files: 
 - spec/it_spec.rb
 - spec/rspec_compatibility_spec.rb