ick 0.2.3 → 0.2.4

data/website/180seconds.txt

@@ -0,0 +1,159 @@
+h1. Ick in 180 seconds or less
+
+h2. Transforming your code
+
+Object#let turns:
+
+<pre syntax="ruby">
+</pre>
+
+Into:
+
+<pre syntax="ruby">
+</pre>
+
+Object#returning turns:
+
+<pre syntax="ruby">
+</pre>
+
+Into:
+
+<pre syntax="ruby">
+</pre>
+
+Object#my turns:
+
+<pre syntax="ruby">
+</pre>
+
+Into:
+
+<pre syntax="ruby">
+</pre>
+
+Object#inside turns:
+
+<pre syntax="ruby">
+</pre>
+
+Into:
+
+<pre syntax="ruby">
+</pre>
+
+h2. Test Cases
+
+The four canonical block structuring methods (#let, #returning, #my, and #inside):
+
+<pre syntax="ruby">
+Ick.sugarize
+arr = []
+
+# let returns the value of the block and executes in the current environment
+assert_equal(
+  "3628800 ends with zero",
+  let((1..10).inject(&:*)) { |num|
+    arr << self.class
+    num % 10 == 0 ? "#{num} ends with zero" : "#{num} does not end with zero"
+  })
+assert_equal([ self.class ], arr)
+
+# returning returns the value of the expression and executes in the current environment
+assert_equal(
+  3628800,
+  returning((1..10).inject(&:*)) { |num|
+    arr << self.class
+    num % 10 == 0 ? "#{num} ends with zero" : "#{num} does not end with zero"
+  })
+assert_equal([ self.class, self.class ], arr)
+
+# my returns the value of the block and executes in the expression's environment
+assert_equal(
+  "3628800 ends with zero",
+  my((1..10).inject(&:*)) { |num|
+    arr << self.class
+    num % 10 == 0 ? "#{num} ends with zero" : "#{num} does not end with zero"
+  })
+assert_equal([ self.class, self.class, Fixnum ], arr)
+
+# inside returns the value of the expression and executes in the expression's environment
+assert_equal(
+  3628800,
+  inside((1..10).inject(&:*)) { |num|
+    arr << self.class
+    num % 10 == 0 ? "#{num} ends with zero" : "#{num} does not end with zero"
+  })
+assert_equal([ self.class, self.class, Fixnum, Fixnum ], arr)
+</pre>
+
+The two most common guarded evauators (#maybe and #try):
+
+<pre syntax="ruby">
+# an object with two methods. #do returns itself, #do_not returns nil
+yoda = returning(Object.new) do |obj|
+  def obj.do
+    self
+  end
+  def obj.do_not
+    nil
+  end
+end
+
+# maybe handles nils, even for methods nil has, but not missing methods
+assert_equal(
+  yoda, 
+  maybe(yoda) { |obj| obj.do }
+)
+assert_nil(
+  maybe(nil) { |obj| obj.do }
+)
+assert_nil(
+  maybe(yoda) { |obj| obj.do_not.do }
+)
+assert_nil(
+  maybe(nil) { |obj| obj.nil? }
+)
+assert_raise(NoMethodError) do
+  maybe(yoda) { |obj| obj.fubar }
+end
+
+#try handles NoMethodErrors, without caring whether nil is involved
+assert_equal(
+  yoda, 
+  try(yoda) { |obj| obj.do }
+)
+assert_nil(
+  try(nil) { |obj| obj.do_not }
+)
+assert_not_nil(
+  try(nil) { |obj| obj.nil? }
+)
+assert_nil(
+  try(yoda) { |obj| obj.fubar }
+)
+</pre>
+
+h2. Administrivia
+
+h3. Home Sweet Home
+
+"ick.rubyforge.org":http://ick.rubyforge.org
+
+h3. 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 trunk repository is @svn://rubyforge.org/var/svn/ick/trunk@ for anonymous access.
+
+h3. License
+
+This code is free to use under the terms of the "MIT license":http://en.wikipedia.org/wiki/MIT_License. 
+
+h3. Shout Out
+
+"Mobile Commons":http://mcommons.com/. Still Huge After All These Years.
+
+h3. Contact
+
+Comments are welcome. Send an email to "Reginald Braithwaite":mailto:raganwald+rubyforge@gmail.com. And you can always visit "weblog.raganwald.com":http://weblog.raganwald.com/ to see what's cooking.

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.3</a>
+      <a href="http://rubyforge.org/projects/ick" class="numbers">0.2.4</a>
     </div>
     <h1>&#x2192; &#8216;ick&#8217;</h1>
 
@@ -55,11 +55,14 @@
 </pre></p>
 
 
-	<h2>Installing</h2>
+	<h2>Getting Started</h2>
 
 
 <pre>sudo gem install ick</pre>
 
+	<p>You can also see <a href="180seconds.html">Ick in 180 seconds or less</a></p>
+
+
 	<h2>Block Structured Ruby</h2>
 
 
@@ -202,6 +205,12 @@
 	<p><a href="inside.html">Inside Ick</a></p>
 
 
+	<h2>That&#8217;s cool, but&hellip;</h2>
+
+
+	<p>No problem, I get that Ick isn&#8217;t exactly what you need. Why not have a look at <a href="http://andand.rubyforge.org">andand</a>? The andand gem gives you a very specialized version of Object#maybe and an enhanced Object#tap: it does a lot less but tries to do it very, very well. Have a look and let me know what you think.</p>
+
+
 	<h2>Administrivia</h2>
 
 
@@ -237,12 +246,14 @@
 
 	<p>Comments are welcome. Send an email to <a href="mailto:raganwald+rubyforge@gmail.com">Reginald Braithwaite</a>. And you can always visit <a href="http://weblog.raganwald.com/">weblog.raganwald.com</a> to see what&#8217;s cooking.</p>
     <p class="coda">
-      <a href="http://weblog.raganwald.com/">Reginald Braithwaite</a>, 8th March 2008<br>
+      <a href="http://weblog.raganwald.com/">Reginald Braithwaite</a>, 26th March 2008<br>
       Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
     </p>
 </div>
 
 <!-- insert site tracking codes here, like Google Urchin -->
 
+<script type="text/javascript" src="http://pub44.bravenet.com/counter/code.php?id=404724&usernum=3754613835&cpv=2"></script>
+
 </body>
 </html>

data/website/index.txt

@@ -14,10 +14,12 @@ Thus, the *Invocation Construction Kit*, or "Ick!" Ick provides the tools needed
 please(sir) { may.i.have.some.more }
 </pre>
 
-h2. Installing
+h2. Getting Started
 
 <pre>sudo gem install ick</pre>
 
+You can also see "Ick in 180 seconds or less":180seconds.html
+
 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.
@@ -124,6 +126,10 @@ h2. Where can I read about what's going on inside Ick?
 
 "Inside Ick":inside.html
 
+h2. That's cool, but&hellip;
+
+No problem, I get that Ick isn't exactly what you need. Why not have a look at "andand":http://andand.rubyforge.org? The andand gem gives you a very specialized version of Object#maybe and an enhanced Object#tap: it does a lot less but tries to do it very, very well. Have a look and let me know what you think.
+
 h2. Administrivia
 
 h3. Home Sweet Home

data/website/inside.html

@@ -0,0 +1,325 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+  <link rel="stylesheet" href="stylesheets/screen.css" type="text/css" media="screen" />
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>
+      Inside the Invocation Construction Kit
+  </title>
+  <script src="javascripts/rounded_corners_lite.inc.js" type="text/javascript"></script>
+<style>
+
+</style>
+  <script type="text/javascript">
+    window.onload = function() {
+      settings = {
+          tl: { radius: 10 },
+          tr: { radius: 10 },
+          bl: { radius: 10 },
+          br: { radius: 10 },
+          antiAlias: true,
+          autoPad: true,
+          validTags: ["div"]
+      }
+      var versionBox = new curvyCorners(settings, document.getElementById("version"));
+      versionBox.applyCornersToAll();
+    }
+  </script>
+</head>
+<body>
+<div id="main">
+
+    <h1>Inside the 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.4</a>
+    </div>
+    <h2>More about the four block structures</h2>
+
+
+	<p><a href="index.html">Ick</a> provides #let, a method for block-structuring Ruby code. As already shown, if you want someone&#8217;s phone number only if they are a friend: <code>let(Person.find(:first, ...)) { |person| person.phone_number if person.friend? }</code></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.</p>
+
+
+	<h3>#let, #returning, #my, and #inside</h3>
+
+
+	<p>As shown above, #let does the obvious thing: it passes a value to a block, it evaluates the block in the caller&#8217;s environment, and it returns the result of the block. Hmmm&#8230;</p>
+
+
+	<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>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>
+
+
+	<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>
+
+
+	<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</a> post on the same subject, 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.)</p>
+
+
+	<h3>What about #try and #maybe?</h3>
+
+
+	<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. Here is the key point about Ick as compared to rolling your own methods directly: you can combine and recombine the parts to make new kinds of methods. As you just saw, we can make #try and #please out of the same building blocks. This is why Ick is a &#8220;contruction kit,&#8221; not just a collection of handy syntactic short cuts.</p>
+
+
+	<h2>Wrap Music</h2>
+
+
+	<p>The four methods #let, #returning, #my, and #inside are fairly simple. There&#8217;s some finagling with what they return and their evaluation environment, but evaluation within the environment is 100% standard Ruby. But things get really interesting when we want to actually change Ruby&#8217;s evaluation behaviour. Specifically, when we want to change what it means to call a method on the value we provide.</p>
+
+
+	<p>That&#8217;s what #maybe, #please, and #try all do: when a method is called on the value, they intercept it and decide whether to call the method or prematurely return <em>nil</em>. Ick can&#8217;t actually change the behaviour of the Ruby interpreter, so what it does is as close to evil metaprogramming as possible. Ick doesn&#8217;t do any method redefinition or method chain manipulation, instead it performs its juju by wrapping the value in a delegator. Ick&#8217;s delegators are called <em>Wrappers</em>.</p>
+
+
+	<p>Ick&#8217;s built-in methods that use wrappers inherit from <code>Ick::Wrap</code>. When the result is returned from the block, it is unwrapped if it is wrapped.</p>
+
+
+	<h3>Hand Rolling</h3>
+
+
+	<p>You can use Ick::Wrap along with your own wrappers by calling #invoke_wrapped:</p>
+
+
+	<p><pre class='syntax'>
+class MyWrapper &lt; Ick::Wrapper
+  def initialize(value)
+    # ...
+  end
+  # ...
+end
+
+Ick::Wrap.instance.invoke_wrapped(Person.find(:first, ...), MyWrapper)
+</pre></p>
+
+
+	<p>If you need additional parameters for your wrapper, you can declare them in the initializer and pass them to #invoke_wrapped:</p>
+
+
+	<p><pre class='syntax'>
+class MyWrapper &lt; Ick::Wrapper
+  def initialize(value, extra1, extra2)
+    # ...
+  end
+  # ...
+end
+
+Ick::Wrap.instance.invoke_wrapped(Person.find(:first, ...), MyWrapper, :foo, :bar)
+</pre></p>
+
+
+	<p>The methods #maybe, #please, and #try are all implemented as subclasses of Ick:Guard. Have a look at guard.rb to see how to hide the extra wrapping syntax that #invoke_wrapped requires.</p>
+
+
+	<h3>ArrayWrapper</h3>
+
+
+	<p>Ick::ArrayWrapper wraps a collection of receivers. Any message sent to the wrapper is dispatched to each of the receivers in the collection. Here&#8217;s a simplified implementation:</p>
+
+
+	<p><pre class='syntax'>
+<span class="keyword">class </span><span class="class">ArrayWrapper</span> <span class="punct">&lt;</span> <span class="constant">Wrapper</span>
+  
+  <span class="keyword">def </span><span class="method">__invoke__</span><span class="punct">(</span><span class="ident">sym</span><span class="punct">,</span> <span class="punct">*</span><span class="ident">args</span><span class="punct">,</span> <span class="punct">&amp;</span><span class="ident">block</span><span class="punct">)</span>
+    <span class="attribute">@value</span><span class="punct">.</span><span class="ident">map</span> <span class="punct">{</span> <span class="punct">|</span><span class="ident">_</span><span class="punct">|</span> <span class="ident">_</span><span class="punct">.</span><span class="ident">__send__</span><span class="punct">(</span><span class="ident">sym</span><span class="punct">,</span> <span class="punct">*</span><span class="ident">args</span><span class="punct">,</span> <span class="punct">&amp;</span><span class="ident">block</span><span class="punct">)</span> <span class="punct">}</span>
+  <span class="keyword">end</span>
+  
+  <span class="ident">is_contagious</span>
+  
+<span class="keyword">end</span>
+</pre></p>
+
+
+	<p>What on Earth is it for? Specifically, what&#8217;s wrong with just using Enumerable#map if we want to send the same message(s) to each receiver in a collection?</p>
+
+
+	<p>The answer is that when we use Enumerable#map, it executes the entire block once for each receiver. So if there are side effects in the block, they are executed once for each receiver as well. Whereas ArrayWrapper dispatches the messages to each receiver without executing side effects more than once.</p>
+
+
+	<p>Ick::Tee provides a method for using an ArrayWrapper with <em>return_value</em> semantics. When you use #tee, it evaluates the block once, but dispatches methods to each of the values you pass in. It returns the first value you pass in. This can be handy for things like sending logging information to more than one log.</p>
+
+
+	<p>Here&#8217;s one of the test cases you can find in the gem:</p>
+
+
+	<p><pre class='syntax'>
+<span class="keyword">def </span><span class="method">test_tee_semantics</span>
+  <span class="ident">array_logger_one</span> <span class="punct">=</span> <span class="punct">[]</span>
+  <span class="ident">array_logger_two</span> <span class="punct">=</span> <span class="punct">[]</span>
+  <span class="ident">line_number</span> <span class="punct">=</span> <span class="number">0</span>
+  <span class="punct">[</span><span class="ident">array_logger_one</span><span class="punct">,</span> <span class="ident">array_logger_two</span><span class="punct">].</span><span class="ident">map</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">log</span><span class="punct">|</span>
+    <span class="ident">line_number</span> <span class="punct">+=</span> <span class="number">1</span> 
+    <span class="ident">log</span> <span class="punct">&lt;&lt;</span> <span class="punct">&quot;</span><span class="string">A<span class="expr">#{line_number}</span></span><span class="punct">&quot;</span>
+    <span class="ident">line_number</span> <span class="punct">+=</span> <span class="number">1</span> 
+    <span class="ident">log</span> <span class="punct">&lt;&lt;</span> <span class="punct">&quot;</span><span class="string">B<span class="expr">#{line_number}</span></span><span class="punct">&quot;</span>
+  <span class="keyword">end</span>
+  <span class="ident">assert_equal</span><span class="punct">(%w(</span><span class="string">A1 B2</span><span class="punct">),</span> <span class="ident">array_logger_one</span><span class="punct">)</span>
+  <span class="ident">assert_equal</span><span class="punct">(%w(</span><span class="string">A3 B4</span><span class="punct">),</span> <span class="ident">array_logger_two</span><span class="punct">)</span>
+  <span class="ident">array_logger_one</span> <span class="punct">=</span> <span class="punct">[]</span>
+  <span class="ident">array_logger_two</span> <span class="punct">=</span> <span class="punct">[]</span>
+  <span class="ident">line_number</span> <span class="punct">=</span> <span class="number">0</span>
+  <span class="ident">tee</span><span class="punct">(</span><span class="ident">array_logger_one</span><span class="punct">,</span> <span class="ident">array_logger_two</span><span class="punct">)</span> <span class="keyword">do</span> <span class="punct">|</span><span class="ident">log</span><span class="punct">|</span>
+    <span class="ident">line_number</span> <span class="punct">+=</span> <span class="number">1</span> 
+    <span class="ident">log</span> <span class="punct">&lt;&lt;</span> <span class="punct">&quot;</span><span class="string">A<span class="expr">#{line_number}</span></span><span class="punct">&quot;</span>
+    <span class="ident">line_number</span> <span class="punct">+=</span> <span class="number">1</span> 
+    <span class="ident">log</span> <span class="punct">&lt;&lt;</span> <span class="punct">&quot;</span><span class="string">B<span class="expr">#{line_number}</span></span><span class="punct">&quot;</span>
+  <span class="keyword">end</span>
+  <span class="ident">assert_equal</span><span class="punct">(%w(</span><span class="string">A1 B2</span><span class="punct">),</span> <span class="ident">array_logger_one</span><span class="punct">)</span>
+  <span class="ident">assert_equal</span><span class="punct">(%w(</span><span class="string">A1 B2</span><span class="punct">),</span> <span class="ident">array_logger_two</span><span class="punct">)</span>
+<span class="keyword">end</span>
+</pre></p>
+
+
+	<p>When we used Enumerable#map, the side effect <code>line_number += 1</code> is evaluated four times, twice for each receiver. However when we use #tee, the side effect <code>line_number += 1</code> is only evaluated twice, even though we have two receivers. Now that you know about the four execution possibilities encapsulated by #let, #returning, #my, and #inside, you can probably guess what #fork does when I tell you that its implementation <em>returns_result</em>.</p>
+
+
+	<h3>Beware!</h3>
+
+
+	<p>Because Ick::Wrap is passing a wrapper into the block instead of the original value, you can get unexpected results under certain circumstances. For example, if you assign the value something else within the block such as an instance variable, when the block exits the value will still have whatever behaviour the wrapper creates.</p>
+
+
+	<p>Therefore, wrappers are <em>unidirectional</em>: they only work when you are calling methods on your value, not when you are passing the wrapped value as a parameter to any other method. This is hideous: why should there be any difference between <code>{ |value| value + 1 }</code> and <code>{ |value| 1 + value }</code>?</p>
+
+
+	<p>Also, wrappers are <em>external</em>, they only affect messages sent to the wrapped value in your block. For example, if you are using #try to avoid NoMethodErrors, any messages you send to the wrapped value will handled by the wrapper. But what happens if the wrapped value sends itself a message that it doesn&#8217;t handle? Aha, that will raise a NoMethodError!</p>
+
+
+	<p>Wrappers are a very leaky abstraction, which is why I try to name things a little closer to what they actually do than what they purport to do but don&#8217;t really do. For example, we write <code>try { something.or.other }</code> to emphasize that we are only trying the things you see in front of you.</p>
+
+
+	<h2>Why Ick?</h2>
+
+
+	<p>As just mentioned, Ick is 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. 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, 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>
+
+
+	<h3>Where do you want to go today?</h3>
+
+
+	<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>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>
+
+
+	<p>Have fun!</p>
+
+
+	<h2>Administrivia</h2>
+
+
+	<h3>Home Sweet Home</h3>
+
+
+	<p><a href="http://ick.rubyforge.org">ick.rubyforge.org</a></p>
+
+
+	<h3>How to submit patches</h3>
+
+
+	<p>Read the <a href="http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/">8 steps for fixing other people&#8217;s code</a>.</p>
+
+
+	<p>The trunk repository is <code>svn://rubyforge.org/var/svn/ick/trunk</code> for anonymous access.</p>
+
+
+	<h3>License</h3>
+
+
+	<p>This code is free to use under the terms of the <a href="http://en.wikipedia.org/wiki/MIT_License"><span class="caps">MIT</span> license</a>.</p>
+
+
+	<h3>Shout Out</h3>
+
+
+	<p><a href="http://mcommons.com/">Mobile Commons</a>. Still Huge After All These Years.</p>
+
+
+	<h3>Contact</h3>
+
+
+	<p>Comments are welcome. Send an email to <a href="mailto:raganwald+rubyforge@gmail.com">Reginald Braithwaite</a>. And you can always visit <a href="http://weblog.raganwald.com/">weblog.raganwald.com</a> to see what&#8217;s cooking.</p>
+    <p class="coda">
+      <a href="http://weblog.raganwald.com/">Reginald Braithwaite</a>, 9th March 2008<br>
+      Theme extended from <a href="http://rb2js.rubyforge.org/">Paul Battley</a>
+    </p>
+</div>
+
+<!-- insert site tracking codes here, like Google Urchin -->
+
+<script type="text/javascript" src="http://pub44.bravenet.com/counter/code.php?id=404724&usernum=3754613835&cpv=2"></script>
+
+</body>
+</html>