ick 0.2.0 → 0.2.1

data/History.txt

@@ -8,4 +8,7 @@
 * 3 minor enhancement:
   * refactored Wrapped into Wrap with runtime options
   * added ArrayWrapper and Tee classes
+* 4 minor enhancement
+  * fixed manifest.txt
+  * TODO: build the manifest algorithmically!
   

data/Manifest.txt

@@ -6,7 +6,13 @@ Rakefile
 config/hoe.rb
 config/requirements.rb
 lib/ick.rb
+lib/ick/advisor.rb
+lib/ick/base.rb
+lib/ick/guard.rb
+lib/ick/sugar.rb
+lib/ick/tee.rb
 lib/ick/version.rb
+lib/ick/wrap.rb
 log/debug.log
 script/destroy
 script/generate

data/lib/ick.rb

@@ -2,6 +2,7 @@ $:.unshift File.dirname(__FILE__)
 
 require 'ick/base'
 require 'ick/wrap'
+require 'ick/advisor'
 require 'ick/guard'
 require 'ick/tee'
 require 'ick/sugar'

data/lib/ick/advisor.rb

@@ -0,0 +1,43 @@
+module Ick
+  class Advisor < Wrapper
+    @@arounds = lambda { |callback, receiver, sym, *args|
+      callback.call()
+    }
+    def self.around target = nil, args = {}, &proc # { |callback, receiver, sym, *args| ... }
+      old_arounds = @@arounds
+      if target.kind_of?(Symbol)
+        proc = lambda { |callback, receiver, sym, *args|
+          self.send(target, sym, *args, &proc)
+        }
+      elsif target.kind_of?(Class)
+        proc = lambda { |callback, receiver, sym, *args|
+          target.filter(receiver, sym, *args, &proc)
+        }
+      end
+      @@arounds = if args[:only]
+          lambda { |callback, receiver, sym, *args|
+            new_callback = lambda { old_arounds.call(callback, receiver, sym, *args) }
+            Array(args[:only]).include(sym) ? proc.call(callback, receiver, sym, *args) : callback.call()
+          }
+        elsif args[:except]
+          lambda { |callback, receiver, sym, *args|
+            new_callback = lambda { old_arounds.call(callback, receiver, sym, *args) }
+            Array(args[:only]).include(sym) ? new_callback.call() : proc.call(new_callback, receiver, sym, *args)
+          }
+        else
+          lambda { |callback, receiver, sym, *args|
+            new_callback = lambda { old_arounds.call(callback, receiver, sym, *args) }
+            proc.call(new_callback, receiver, sym, *args)
+          }
+        end
+    end
+    def __invoke__(sym, *args, &block)
+      @@arounds.call(
+        lambda { @value.__send__(sym, *args, &block) },
+        @value,
+        sym,
+        *args
+      )
+    end
+  end
+end

data/lib/ick/base.rb

@@ -0,0 +1,108 @@
+$:.unshift File.dirname(__FILE__)
+
+require 'singleton'
+
+module Ick
+  
+  class Base
+    include Singleton
+    
+    def returns(value, result)
+      raise 'implemented by subclass or by calling meta-method'
+    end
+    
+    def evaluate(value, proc)
+      raise 'implemented by subclass or by calling meta-method'
+    end
+    
+    def invoke(value = nil, &proc)
+      result = evaluate(value, proc)
+      returns(value, result)
+    end
+    
+    def self.evaluates_in_calling_environment
+      define_method :evaluate do |value, proc|
+        proc.call(value)
+      end
+      true
+    end
+    
+    def self.evaluates_in_value_environment
+      define_method :evaluate do |value, proc|
+        value.instance_eval(&proc)
+      end
+      true
+    end
+    
+    def self.returns_value
+      define_method :returns do |value, result|
+        value
+      end
+      true
+    end
+    
+    def self.returns_result
+      define_method :returns do |value, result|
+        result
+      end
+      true
+    end
+  
+    #snarfed from Ruby On Rails
+    def self.underscore(camel_cased_word)
+      camel_cased_word.to_s.gsub(/::/, '/').
+        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+        tr("-", "_").
+        downcase
+    end
+    
+    def self.belongs_to clazz
+      method_name = self.underscore(self.name.split('::')[-1])
+      unless clazz.method_defined?(method_name)
+        clazz.class_eval " 
+          def #{method_name}(value=self,&proc)
+            if block_given?
+              #{self.name}.instance.invoke(value, &proc)
+            else
+              Invoker.new(value, #{self.name})
+            end
+          end"
+      end
+    end
+    
+  end
+  
+  class Invoker
+    
+    instance_methods.reject { |m| m =~ /^__/ }.each { |m| undef_method m }
+  
+    def initialize(value, clazz)
+      @value = value
+      @clazz = clazz
+    end
+    
+    def method_missing(sym, *args, &block)
+      @clazz.instance.invoke(@value) { |value|
+        value.__send__(sym, *args, &block)
+      }
+    end
+  
+  end
+    
+  class Let < Base
+    evaluates_in_calling_environment and returns_result
+  end
+
+  class Returning < Base
+    evaluates_in_calling_environment and returns_value
+  end
+
+  class My < Base
+    evaluates_in_value_environment and returns_result
+  end
+
+  class Inside < Base
+    evaluates_in_value_environment and returns_value
+  end
+  
+end

data/lib/ick/guard.rb

@@ -0,0 +1,53 @@
+$:.unshift File.dirname(__FILE__)
+
+require 'singleton'
+
+module Ick
+  
+  class GuardWrapper < IdentityWrapper
+    def initialize(value, default, proc)
+      @proc = proc
+      @default = default
+      super(value)
+    end
+    def __rewrap__(new_value)
+      self.__class.new(new_value, @default, @proc) #contagious
+    end
+    def __invoke__(sym, *args, &block)
+      @proc.call(@value, sym) ? super : @default
+    end
+  end
+  
+  class Guard < Wrap
+    include Singleton
+    
+    def self.guard_with(&proc)
+      @guard_proc = proc
+    end
+    
+    def self.guard
+      @guard_proc
+    end
+    
+    def invoke(value, &proc)
+      invoke_wrapped(value, GuardWrapper, nil, self.class.guard, &proc)
+    end
+    
+  end
+  
+  class Maybe < Guard
+    guard_with { |value, sym| value.nil? == false }
+    evaluates_in_calling_environment and returns_result
+  end
+  
+  class Try < Guard
+    guard_with { |value, sym| value.respond_to?(sym) == true }
+    evaluates_in_calling_environment and returns_result
+  end
+  
+  class Please < Ick::Guard
+    guard_with { |value, sym| value.respond_to?(sym) == true } # defines your guard condition
+    evaluates_in_value_environment and returns_result          # defines its behaviour
+  end
+
+end

data/lib/ick/sugar.rb

@@ -0,0 +1,7 @@
+module Ick
+  def self.sugarize
+    [Let, Returning, My, Inside, Maybe, Try, Please, Tee].each do |clazz|
+      clazz.belongs_to Object
+    end
+  end
+end

data/lib/ick/tee.rb

@@ -0,0 +1,35 @@
+module Ick
+
+=begin
+  WARNING: UNTESTED
+=end
+  class Tee < Wrap
+    
+    def invoke(*values, &proc)
+      invoke_wrapped(values, ArrayWrapper, nil, &proc)
+    end
+    
+    def unwrap(wrapped, wrapper_class)
+      wrapped.respond_to?(:__value__) ? wrapped.__value__.first : wrapped
+    end
+    
+    evaluates_in_calling_environment and returns_result
+    
+    def self.belongs_to clazz
+      method_name = self.underscore(self.name.split('::')[-1])
+      unless clazz.method_defined?(method_name)
+        clazz.class_eval " 
+          def #{method_name}(*values,&proc)
+            values = [self] if values.empty?
+            if block_given?
+              #{self.name}.instance.invoke(*values, &proc)
+            else
+              Invoker.new(values, #{self.name})
+            end
+          end"
+      end
+    end
+    
+  end
+  
+end

data/lib/ick/version.rb

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

data/lib/ick/wrap.rb

@@ -0,0 +1,92 @@
+module Ick
+  
+  class Wrapper
+    
+    alias  :__respond_to? :respond_to?
+    alias :__instance_eval :instance_eval 
+    alias :__class :class 
+    alias :__inspect :inspect 
+    instance_methods.reject { |m| m =~ /^__/ }.each { |m| undef_method m }
+    alias :instance_eval :__instance_eval 
+    
+    def initialize(value, *additional_attributes)
+      @value = value
+    end
+    
+    def __value__
+      @value
+    end
+    def __invocation__
+      @invocation
+    end
+    def __rewrap__(value)
+      raise 'implemented by subclass'
+    end
+    def __invoke__(sym, *args, &block)
+      raise 'implemented by subclass'
+    end
+    def method_missing(sym, *args, &block)
+      __rewrap__(__invoke__(sym, *args, &block))
+    end
+    def respond_to?(sym)
+      @value.respond_to?(sym) || self.__respond_to?(sym)
+    end
+    
+    def self.is_contagious
+      define_method(:__rewrap__) { |value|
+        self.__class.new(value) 
+      }
+    end
+    
+    def self.is_not_contagious
+      define_method(:__rewrap__) { |value| value }
+    end
+    
+  end
+  
+  class IdentityWrapper < Wrapper
+    
+    def __invoke__(sym, *args, &block)
+      @value.__send__(sym, *args, &block)
+    end
+    
+  end
+  
+  class ArrayWrapper < Wrapper
+    
+    def initialize(values, *additional_attributes)
+      super(values)
+    end
+    
+    def __invoke__(sym, *args, &block)
+      p "#{sym} -> #{@value.inspect}"
+      @value.map { |_| _.__send__(sym, *args, &block) }
+    end
+    
+    is_contagious
+    
+  end
+  
+  class Wrap < Base
+    
+    def wrap(value, wrapper_class, *additional_arguments)
+      wrapper_class.new(value, *additional_arguments)
+    end
+    
+    def unwrap(wrapped, wrapper_class)
+      wrapped.respond_to?(:__value__) ? wrapped.__value__ : wrapped
+    end
+    
+    def invoke_wrapped(value, wrapper_class, *additional_arguments, &proc)
+      wrapped_value = wrap(value, wrapper_class, *additional_arguments)
+      wrapped_result = evaluate(wrapped_value, proc)
+      returns(unwrap(wrapped_value, wrapper_class), unwrap(wrapped_result, wrapper_class))
+    end
+    
+    def invoke
+      raise 'subclass should override and invoke invoke_wrapped'
+    end
+    
+  end
+  
+end

data/test/test_ick.rb

@@ -125,15 +125,28 @@ class TestIck < Test::Unit::TestCase
     )
   end
   
-  def test_tee
-    
-    box1 = Box.new(1)
-    box2 = Box.new(2)
-    
-    tee(box1,box2) { |box| box.value = 7 }
-    assert_equal(7, box1.value)
-    assert_equal(7, box2.value)
-    
-  end
+  # def test_tee_basic
+  #   box1 = Box.new(1)
+  #   box2 = Box.new(2)
+  #   tee(box1,box2) { |box| box.value = 7 }
+  #   assert_equal(7, box1.value)
+  #   assert_equal(7, box2.value)
+  # end
+  
+  # def test_tee_semantics
+  #   first_log = []
+  #   second_log = []
+  #   [first_log, second_log].map do |value|
+  #     log << "first line of output"
+  #     log << "second line of output"
+  #   end
+  #   assert_equal(, log)
+  #   out = []
+  #   tee(1, 2, 3) do |value|
+  #     out << "a#{value}"
+  #     out << "b#{value}"
+  #   end
+  #   assert_equal(%w(a1 b1 c1 a2 b2 c2), out)
+  # end
   
 end

data/website/index.html

@@ -33,7 +33,7 @@
     <h1>Invocation Construction Kit</h1>
     <div id="version" class="clickable" onclick='document.location = "http://rubyforge.org/projects/ick"; return false'>
       <p>Get Version</p>
-      <a href="http://rubyforge.org/projects/ick" class="numbers">0.2.0</a>
+      <a href="http://rubyforge.org/projects/ick" class="numbers">0.2.1</a>
     </div>
     <h1>&#x2192; &#8216;ick&#8217;</h1>
 
@@ -66,7 +66,7 @@
 	<p>Although Ruby borrows many of its features from Lisp and its syntax from Algol, it does not have block-local variables. In other words, if you declare a variable anywhere inside of a method, that variable is visible everywhere in that method. This is a problem, because it encourages writing methods where the instance variables create lot of dependencies between different expressions. Those methods can be hard to understand and refactor.</p>
 
 
-	<p>Ick solves this problem by providing four block structure methods: #let, #returning, #my, and #inside. These methods take an expression and bind it to a variable inside of a block. For example, if you want someone&#8217;s phone number only if they are a friend:</p>
+	<p>Ick solves this problem by providing a block structure method: #let. #let takes an expression and binds it to a variable inside of a block. For example, if you want someone&#8217;s phone number only if they are a friend:</p>
 
 
 	<p><pre class='syntax'>
@@ -74,10 +74,7 @@
 </pre></p>
 
 
-	<p>This code makes it clear that you only need the <code>person</code> variable inside the block. If you want to refactor this code, you know that the entire expression can move without breaking another piece of code. We&#8217;ll elaborate on the differences between #let, #returning, #my, and #inside below.</p>
-
-
-	<p>(The four methods were inspired by <a href="http://blog.rubyenrails.nl/articles/2008/02/18/our-daily-method-10-object-r-rs-ds-s">Michiel de Mare&#8217;s post on the same subject</a>, although Ick&#8217;s nomenclature is not compatible with Michiel&#8217;s. Michiel&#8217;s #rsss, #rrss, #rsds, and #rrds are called #returning, #let, #inside, and #my in Ick.)</p>
+	<p>This code makes it clear that you only need the <code>person</code> variable inside the block. If you want to refactor this code, you know that the entire expression can move without breaking another piece of code. Ick provides three other block structure methods (#returning, #my, and #inside) that are detailed on the <a href="inside.html">Inside Ick</a> page.</p>
 
 
 	<h2>Guarded Evaluation</h2>
@@ -184,112 +181,34 @@
 	<p>The point is, <code>try(program) { responsibly }</code>. You choose which classes to open and which methods to add. <a href="http://avdi.org/devblog/2008/02/25/full-disclosure/">All I’m saying is this: before re-opening a class, did you go through the rest of your toolbox first?</a></p>
 
 
-	<h2>More about the four block structures</h2>
-
-
-	<p>There are two binary decisions to be made about every block: First, do you want to evaluate the block in the calling environment (which is how almost every block is evaluated in Ruby), or do you want to evaluate the block in the value&#8217;s context. In other words, does <em>self</em> stay the same, or does it become the value in the block?</p>
-
-
-	<p>The methods #try and #maybe are both implemented as <em>evaluates_in_calling_environment</em>, because that is least surprising. But when you&#8217;re rolling your own, you might want to change that to make things more sugary. For example, here is a different version of #try:</p>
-
-
-	<p><pre class='syntax'>
-<span class="keyword">class </span><span class="class">Please</span> <span class="punct">&lt;</span> <span class="constant">Ick</span><span class="punct">::</span><span class="constant">Guard</span>
-  <span class="ident">guard_with</span> <span class="punct">{</span> <span class="punct">|</span><span class="ident">value</span><span class="punct">,</span> <span class="ident">sym</span><span class="punct">|</span> <span class="ident">value</span><span class="punct">.</span><span class="ident">respond_to?</span><span class="punct">(</span><span class="ident">sym</span><span class="punct">)</span> <span class="punct">==</span> <span class="constant">true</span> <span class="punct">}</span>
-  <span class="ident">evaluates_in_value_environment</span> <span class="keyword">and</span> <span class="ident">returns_result</span>
-  <span class="ident">belongs_to</span> <span class="constant">Object</span>
-<span class="keyword">end</span>
-
-<span class="ident">please</span><span class="punct">(...)</span> <span class="punct">{</span> <span class="ident">may</span><span class="punct">.</span><span class="ident">i</span><span class="punct">.</span><span class="ident">have</span><span class="punct">.</span><span class="ident">some</span><span class="punct">.</span><span class="ident">more</span> <span class="punct">}</span>
-</pre></p>
-
-
-	<p>The method #please executes in the value&#8217;s environment, and thus it can call methods directly.</p>
-
-
-	<p>You already saw #let, it takes your expression and binds it to a parameter, then it evaluates a block in the calling environment, just as #try evaluates and guards its block in the calling environment. If you want something that behaves like #let but evaluates in the value&#8217;s environment just like #please, you can use #my:</p>
-
-
-	<p><pre class='syntax'>
-<span class="ident">my</span><span class="punct">(</span><span class="constant">Person</span><span class="punct">.</span><span class="ident">find</span><span class="punct">(</span><span class="symbol">:first</span><span class="punct">,</span> <span class="punct">...))</span> <span class="keyword">do</span>
-	<span class="ident">first_name</span> <span class="punct">=</span> <span class="punct">'</span><span class="string">Charles</span><span class="punct">'</span>
-	<span class="ident">last_name</span> <span class="punct">=</span> <span class="punct">'</span><span class="string">Babbage</span><span class="punct">'</span>
-	<span class="ident">friends</span> <span class="punct">&lt;&lt;</span> <span class="punct">'</span><span class="string">Ada Lovelace</span><span class="punct">'</span>
-<span class="keyword">end</span>
-</pre></p>
-
-
-	<p>This will return Charles Babbage&#8217;s friends. On the surface, <em>evaluates_in_value_environment</em> is about the syntactic sugar of dropping an instance variable. But with a little thought, you can come up with some really cool way to (mis)use this capability.</p>
-
-
-	<p>So #let and #my both pass an expression to a block and return the result. Given that they both &#8216;declare&#8217; <em>returns_result</em>, this is not surprising. But there is another choice: <em>returns_value</em> instead of <em>returns_result</em>. Ruby on Rails includes the popular #returning method, and it works the same in Ick:</p>
+	<h2>Is Ick for me?</h2>
 
 
-	<p><pre class='syntax'>
-<span class="ident">returning</span><span class="punct">(</span><span class="constant">Person</span><span class="punct">.</span><span class="ident">find</span><span class="punct">(</span><span class="symbol">:first</span><span class="punct">,</span> <span class="punct">...))</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">p</span><span class="punct">|</span>
-	<span class="ident">p</span><span class="punct">.</span><span class="ident">first_name</span> <span class="punct">=</span> <span class="punct">'</span><span class="string">Charles</span><span class="punct">'</span>
-	<span class="ident">p</span><span class="punct">.</span><span class="ident">last_name</span> <span class="punct">=</span> <span class="punct">'</span><span class="string">Babbage</span><span class="punct">'</span>
-	<span class="ident">p</span><span class="punct">.</span><span class="ident">friends</span> <span class="punct">&lt;&lt;</span> <span class="punct">'</span><span class="string">Ada Lovelace</span><span class="punct">'</span>
-<span class="keyword">end</span>
-</pre></p>
-
-
-	<p>This returns the person record, not the list of friends. The block is evaluated strictly for side effects. And what happens if we want to return the value and also evaluate in the value&#8217;s environment?</p>
-
-
-	<p><pre class='syntax'>
-<span class="ident">inside</span><span class="punct">(</span><span class="constant">Person</span><span class="punct">.</span><span class="ident">find</span><span class="punct">(</span><span class="symbol">:first</span><span class="punct">,</span> <span class="punct">...))</span> <span class="keyword">do</span>
-	<span class="ident">first_name</span> <span class="punct">=</span> <span class="punct">'</span><span class="string">Charles</span><span class="punct">'</span>
-	<span class="ident">last_name</span> <span class="punct">=</span> <span class="punct">'</span><span class="string">Babbage</span><span class="punct">'</span>
-	<span class="ident">friends</span> <span class="punct">&lt;&lt;</span> <span class="punct">'</span><span class="string">Ada Lovelace</span><span class="punct">'</span>
-<span class="keyword">end</span>
-</pre></p>
-
-
-	<p>The method #inside returns the value and evaluates the block in the value&#8217;s environment.</p>
-
-
-	<h2>Under the Hood</h2>
+	<p>Ick does provide a number of very convenient methods for abstracting evaluation. If you adopt them for your project, your code will be more readable, more succinct, and easier to refactor. That being said, it will not make your teeth whiter or help you sleep if you have a newborn.</p>
 
 
-	<p>Ick is actually a construction kit. By all means install the gem and go wild with #let, #returning, #my, #inside, #try, and #maybe. But have a look under the hood. It&#8217;s easy to build your own methods.</p>
+	<p><em>Every programming problem can be solved with another layer of abstraction, except the problem of too many layers of abstraction</em></p>
 
 
-	<h3>Every programming problem can be solved with another layer of abstraction, except the problem of too many layers of abstraction</h3>
+	<p>The important caveat about Ick is that its implementation adds abstraction. If all you want are two or three specific methods, writing them as simply and as directly as possible makes for a very simple implementation. Ick uses classes and templates instead of simple methods so that when you are ready to start writing your own abstractions, you can easily use the pieces that Ick has built-in. If Ick was written as a collection of cool methods, you would not be able to extend it without copying and pasting.</p>
 
 
-	<p>Ick uses classes and template methods to replicate what can be done in a few lines of explicit code. For example, Object#returning is implemented in Rails as:</p>
-
-
-	<p><pre class='syntax'>
-<span class="keyword">class </span><span class="class">Object</span>
-  <span class="keyword">def </span><span class="method">returning</span><span class="punct">(</span><span class="ident">value</span><span class="punct">)</span>
-    <span class="keyword">yield</span><span class="punct">(</span><span class="ident">value</span><span class="punct">)</span>
-    <span class="ident">value</span>
-  <span class="keyword">end</span>
-<span class="keyword">end</span>
-</pre></p>
-
-
-	<p>So why bother with Ick? Well, Ick is a construction kit. if you want to make a method just like Object#returning, only <em>X</em> (for some value of X), you can&#8217;t do that without copying, pasting, and modifying. Ick&#8217;s classes are included specifically so you can subclass things and make your own new kinds of methods that are variations of the existing methods.</p>
-
-
-	<p>Thus, the extra abstraction is appropriate if you want to use the built-in methods as a starting point for your own exploratory programming. And if you don&#8217;t care, you just want the methods, by all means install the gem and just use them. Don&#8217;t worry about the implementation unless you identify it as a performance problem.</p>
+	<p>Ick raises how you handle things to the level of first-class objects in Ruby, so you can mix and match and separate concerns as you see fit. Logging, permissions, error handling&#8230; These are some of the places you can take Ick. Have fun.</p>
 
 
-	<h3>Where do you want to go today?</h3>
+	<h2>Where can I read about what&#8217;s going on inside Ick?</h2>
 
 
-	<p>The point behind abstracting invocation and evaluation is that you can <em>separate concerns</em>. For example, which methods to chain is one concern. How to handle nil or an object that does not respond to a method is a separate concern. Should you raise and handle and exception? Return nil? log an error? Why should error handling and logging be intermingled with your code?</p>
+	<p><a href="inside.html">Inside Ick</a></p>
 
 
-	<p>With Ick, you can separate the two issues. You can even make the handling pluggable. For example, if instead of calling #let you call your own method, you could sometimes invoke <code>Ick::Let</code> with a block and other times invoke your own handler, perhaps one that logs every method called.</p>
+	<h2>Administrivia</h2>
 
 
-	<p>Ick raises how you handle things to the level of first-class objects in Ruby, so you can mix and match and separate concerns as you see fit. Logging, permissions, error handling&#8230; These are some of the places you can take Ick. Have fun.</p>
+	<h3>Home Sweet Home</h3>
 
 
-	<h2>Administrivia</h2>
+	<p><a href="http://ick.rubyforge.org">ick.rubyforge.org</a></p>
 
 
 	<h3>How to submit patches</h3>

data/website/index.txt

@@ -22,15 +22,13 @@ h2. Block Structured Ruby
 
 Although Ruby borrows many of its features from Lisp and its syntax from Algol, it does not have block-local variables. In other words, if you declare a variable anywhere inside of a method, that variable is visible everywhere in that method. This is a problem, because it encourages writing methods where the instance variables create lot of dependencies between different expressions. Those methods can be hard to understand and refactor.
 
-Ick solves this problem by providing four block structure methods: #let, #returning, #my, and #inside. These methods take an expression and bind it to a variable inside of a block. For example, if you want someone's phone number only if they are a friend:
+Ick solves this problem by providing a block structure method: #let. #let takes an expression and binds it to a variable inside of a block. For example, if you want someone's phone number only if they are a friend:
 
 <pre syntax="ruby">
 let(Person.find(:first, ...)) { |person| person.phone_number if person.friend? }
 </pre>
 
-This code makes it clear that you only need the @person@ variable inside the block. If you want to refactor this code, you know that the entire expression can move without breaking another piece of code. We'll elaborate on the differences between #let, #returning, #my, and #inside below.
-
-(The four methods were inspired by "Michiel de Mare's post on the same subject":http://blog.rubyenrails.nl/articles/2008/02/18/our-daily-method-10-object-r-rs-ds-s, although Ick's nomenclature is not compatible with Michiel's. Michiel's #rsss, #rrss, #rsds, and #rrds are called #returning, #let, #inside, and #my in Ick.)
+This code makes it clear that you only need the @person@ variable inside the block. If you want to refactor this code, you know that the entire expression can move without breaking another piece of code. Ick provides three other block structure methods (#returning, #my, and #inside) that are detailed on the "Inside Ick":inside.html page.
 
 h2. Guarded Evaluation
 
@@ -112,88 +110,25 @@ If you simply want everything you see here working exactly as it's shown, simply
 
 The point is, @try(program) { responsibly }@. You choose which classes to open and which methods to add. "All I’m saying is this: before re-opening a class, did you go through the rest of your toolbox first?":http://avdi.org/devblog/2008/02/25/full-disclosure/
 
-h2. More about the four block structures
- 
-There are two binary decisions to be made about every block: First, do you want to evaluate the block in the calling environment (which is how almost every block is evaluated in Ruby), or do you want to evaluate the block in the value's context. In other words, does _self_ stay the same, or does it become the value in the block?
-
-The methods #try and #maybe are both implemented as _evaluates_in_calling_environment_, because that is least surprising. But when you're rolling your own, you might want to change that to make things more sugary. For example, here is a different version of #try:
-
-<pre syntax="ruby">
-class Please < Ick::Guard
-  guard_with { |value, sym| value.respond_to?(sym) == true }
-  evaluates_in_value_environment and returns_result
-  belongs_to Object
-end
-
-please(...) { may.i.have.some.more }
-</pre>
-
-The method #please executes in the value's environment, and thus it can call methods directly.
+h2. Is Ick for me?
 
-You already saw #let, it takes your expression and binds it to a parameter, then it evaluates a block in the calling environment, just as #try evaluates and guards its block in the calling environment. If you want something that behaves like #let but evaluates in the value's environment just like #please, you can use #my:
+Ick does provide a number of very convenient methods for abstracting evaluation. If you adopt them for your project, your code will be more readable, more succinct, and easier to refactor. That being said, it will not make your teeth whiter or help you sleep if you have a newborn.
 
-<pre syntax="ruby">
-my(Person.find(:first, ...)) do
-	first_name = 'Charles'
-	last_name = 'Babbage'
-	friends << 'Ada Lovelace'
-end
-</pre>
-
-This will return Charles Babbage's friends. On the surface, _evaluates_in_value_environment_ is about the syntactic sugar of dropping an instance variable. But with a little thought, you can come up with some really cool way to (mis)use this capability.
-
-So #let and #my both pass an expression to a block and return the result. Given that they both 'declare' _returns_result_, this is not surprising. But there is another choice: _returns_value_ instead of _returns_result_. Ruby on Rails includes the popular #returning method, and it works the same in Ick:
-
-<pre syntax="ruby">
-returning(Person.find(:first, ...)) do |p|
-	p.first_name = 'Charles'
-	p.last_name = 'Babbage'
-	p.friends << 'Ada Lovelace'
-end
-</pre>
+_Every programming problem can be solved with another layer of abstraction, except the problem of too many layers of abstraction_
 
-This returns the person record, not the list of friends. The block is evaluated strictly for side effects. And what happens if we want to return the value and also evaluate in the value's environment?
+The important caveat about Ick is that its implementation adds abstraction. If all you want are two or three specific methods, writing them as simply and as directly as possible makes for a very simple implementation. Ick uses classes and templates instead of simple methods so that when you are ready to start writing your own abstractions, you can easily use the pieces that Ick has built-in. If Ick was written as a collection of cool methods, you would not be able to extend it without copying and pasting.
 
-<pre syntax="ruby">
-inside(Person.find(:first, ...)) do
-	first_name = 'Charles'
-	last_name = 'Babbage'
-	friends << 'Ada Lovelace'
-end
-</pre>
-
-The method #inside returns the value and evaluates the block in the value's environment.
-
-h2. Under the Hood
-
-Ick is actually a construction kit. By all means install the gem and go wild with #let, #returning, #my, #inside, #try, and #maybe. But have a look under the hood. It's easy to build your own methods.
-
-h3. Every programming problem can be solved with another layer of abstraction, except the problem of too many layers of abstraction
-
-Ick uses classes and template methods to replicate what can be done in a few lines of explicit code. For example, Object#returning is implemented in Rails as:
-
-<pre syntax="ruby">
-class Object
-  def returning(value)
-    yield(value)
-    value
-  end
-end
-</pre>
-
-So why bother with Ick? Well, Ick is a construction kit. if you want to make a method just like Object#returning, only _X_ (for some value of X), you can't do that without copying, pasting, and modifying. Ick's classes are included specifically so you can subclass things and make your own new kinds of methods that are variations of the existing methods.
-
-Thus, the extra abstraction is appropriate if you want to use the built-in methods as a starting point for your own exploratory programming. And if you don't care, you just want the methods, by all means install the gem and just use them. Don't worry about the implementation unless you identify it as a performance problem.
+Ick raises how you handle things to the level of first-class objects in Ruby, so you can mix and match and separate concerns as you see fit. Logging, permissions, error handling... These are some of the places you can take Ick. Have fun.
 
-h3. Where do you want to go today?
+h2. Where can I read about what's going on inside Ick?
 
-The point behind abstracting invocation and evaluation is that you can _separate concerns_. For example, which methods to chain is one concern. How to handle nil or an object that does not respond to a method is a separate concern. Should you raise and handle and exception? Return nil? log an error? Why should error handling and logging be intermingled with your code?
+"Inside Ick":inside.html
 
-With Ick, you can separate the two issues. You can even make the handling pluggable. For example, if instead of calling #let you call your own method, you could sometimes invoke @Ick::Let@ with a block and other times invoke your own handler, perhaps one that logs every method called.
+h2. Administrivia
 
-Ick raises how you handle things to the level of first-class objects in Ruby, so you can mix and match and separate concerns as you see fit. Logging, permissions, error handling... These are some of the places you can take Ick. Have fun.
+h3. Home Sweet Home
 
-h2. Administrivia
+"ick.rubyforge.org":http://ick.rubyforge.org
 
 h3. How to submit patches
 

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: ick
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
-date: 2008-03-08 00:00:00 -05:00
+  version: 0.2.1
+date: 2008-03-09 00:00:00 -05:00
 summary: Invocation Construction Kit
 require_paths: 
 - lib
@@ -38,7 +38,13 @@ files:
 - config/hoe.rb
 - config/requirements.rb
 - lib/ick.rb
+- lib/ick/advisor.rb
+- lib/ick/base.rb
+- lib/ick/guard.rb
+- lib/ick/sugar.rb
+- lib/ick/tee.rb
 - lib/ick/version.rb
+- lib/ick/wrap.rb
 - log/debug.log
 - script/destroy
 - script/generate