smart_tuple 0.1.1 → 0.1.2

data/README.html

@@ -7,43 +7,61 @@
 
 <h2 id="introduction">Introduction</h2>
 
-<p>Sometimes we need to build SQL WHERE statements which are compound or conditional by nature. SmartTuple simplifies this task by letting us build statements of virtually unlimited complexity out of smaller ones.</p>
+<p>Sometimes we need to build SQL <code>WHERE</code> statements which are compound or conditional by nature. <strong>SmartTuple</strong> simplifies this task by letting us build statements of virtually unlimited complexity out of smaller ones.</p>
 
 <p>SmartTuple is suitable for use with Ruby on Rails (ActiveRecord) and other Ruby frameworks and ORMs.</p>
 
-<h2 id="setup">Setup</h2>
+<h2 id="setup-rails-3">Setup (Rails 3)</h2>
 
-<pre><code>$ gem sources --add http://rubygems.org
-$ gem install smart_tuple
+<p>In your app’s <code>Gemfile</code>, add:</p>
+
+<pre><code>gem "smart_tuple"
+</code></pre>
+
+<p>To install the gem with RDoc/ri documentation, do a:</p>
+
+<pre><code>$ gem install smart_tuple
 </code></pre>
 
-<p>In your app's <code>config/environment.rb</code> do a:</p>
+<p>Otherwise, do a <code>bundle install</code>.</p>
+
+<h2 id="setup-rails-2">Setup (Rails 2)</h2>
+
+<p>In your app’s <code>config/environment.rb</code> do a:</p>
 
-<pre><code>config.gem &quot;smart_tuple&quot;
+<pre><code>config.gem "smart_tuple"
 </code></pre>
 
+<p>To install the gem, do a:</p>
+
+<pre><code>$ gem sources --add http://rubygems.org
+$ gem install smart_tuple
+</code></pre>
+
+<p>, or use <code>rake gems:install</code>.</p>
+
 <h2 id="kickstart-demo">Kickstart Demo</h2>
 
-<pre><code>tup = SmartTuple.new(&quot; AND &quot;)
+<pre><code>tup = SmartTuple.new(" AND ")
 tup &lt;&lt; {:brand =&gt; params[:brand]} if params[:brand].present?
-tup &lt;&lt; [&quot;min_price &gt;= ?&quot;, params[:min_price]] if params[:min_price].present?
-tup &lt;&lt; [&quot;max_price &lt;= ?&quot;, params[:max_price]] if params[:max_price].present?
+tup &lt;&lt; ["min_price &gt;= ?", params[:min_price]] if params[:min_price].present?
+tup &lt;&lt; ["max_price &lt;= ?", params[:max_price]] if params[:max_price].present?
 
 @phones = Phone.find(:all, :conditions =&gt; tup.compile)
 </code></pre>
 
-<p>There's a number of ways you can use SmartTuple depending on the situation. They are covered in the tutorial below.</p>
+<p>There’s a number of ways you can use SmartTuple. Some of them is covered in the tutorial below.</p>
 
 <h2 id="tutorial">Tutorial</h2>
 
-<p>Suppose we've got a mobile phone catalog with a search form. We are starting with a price filter of two values: <code>min_price</code> and <code>max_price</code>, both optional.</p>
+<p>Suppose we’ve got a mobile phone catalog with a search form. We are starting with a price filter of two values: <code>min_price</code> and <code>max_price</code>, both optional.</p>
 
 <p>Filter logic:</p>
 
 <ul>
-  <li>If the user hasn't input anything, the filter has no conditions (allows any record).</li>
-  <li>If the user has input <code>min_price</code>, it's used in filter condition.</li>
-  <li>If the user has input <code>max_price</code>, it's used in filter condition.</li>
+  <li>If the user hasn’t input anything, the filter has no conditions (allows any record).</li>
+  <li>If the user has input <code>min_price</code>, it’s used in filter condition.</li>
+  <li>If the user has input <code>max_price</code>, it’s used in filter condition.</li>
   <li>If the user has input <code>min_price</code> and <code>max_price</code>, they both are used in filter condition.</li>
 </ul>
 
@@ -53,155 +71,162 @@ tup &lt;&lt; [&quot;max_price &lt;= ?&quot;, params[:max_price]] if params[:max_
 params[:max_price] = 300    # Can be blank.
 </code></pre>
 
-<p>Now let's write condition-building code:</p>
+<p>Now let’s write condition-building code:</p>
 
-<pre><code># Start by creating a tuple whose statements are glued with &quot; AND &quot;.
-tup = SmartTuple.new(&quot; AND &quot;)
+<pre><code># Start by creating a tuple whose statements are glued with " AND ".
+tup = SmartTuple.new(" AND ")
 
 # If min_price is not blank, append its statement.
 if params[:min_price].present?
-  tup &lt;&lt; [&quot;min_price &gt;= ?&quot;, params[:min_price]]
+  tup &lt;&lt; ["min_price &gt;= ?", params[:min_price]]
 end
 
 # Same for max_price.
 if params[:max_price].present?
-  tup &lt;&lt; [&quot;max_price &lt;= ?&quot;, params[:max_price]]
+  tup &lt;&lt; ["max_price &lt;= ?", params[:max_price]]
 end
 
 # Finally, fire up the query.
 @phones = Phone.find(:all, {:conditions =&gt; tup.compile})
 </code></pre>
 
-<p>That's basically it. Now let's see how different <code>params</code> values affect the resulting <code>:conditions</code> value. Labelled <strong>p</strong> and <strong>c</strong> in this and following listings:</p>
+<p>That’s basically it. Now let’s see how different <code>params</code> values affect the resulting <code>:conditions</code> value. Labelled <strong>p</strong> and <strong>c</strong> in this and following listings:</p>
 
 <pre><code>p: {}
 c: []
 
 p: {:max_price=&gt;300}
-c: [&quot;max_price &lt;= ?&quot;, 300]
+c: ["max_price &lt;= ?", 300]
 
 p: {:min_price=&gt;100, :max_price=&gt;300}
-c: [&quot;min_price &gt;= ? AND max_price &lt;= ?&quot;, 100, 300]
+c: ["min_price &gt;= ? AND max_price &lt;= ?", 100, 300]
 </code></pre>
 
 <h3 id="plus-another-condition">Plus Another Condition</h3>
 
-<p>Let's make things a bit more user-friendly. Let user filter phones by brand. We do it by adding another field, let's call it <code>brand</code>, bearing a straight string value (that's just a simple tutorial, remember?).</p>
+<p>Let’s make things a bit more user-friendly. Let user filter phones by brand. We do it by adding another field, let’s call it <code>brand</code>, bearing a straight string value (that’s just a simple tutorial, remember?).</p>
 
 <p>Our <code>params</code> now becomes something like:</p>
 
-<pre><code>params[:brand] = &quot;Nokia&quot;    # Can be blank.
+<pre><code>params[:brand] = "Nokia"    # Can be blank.
 params[:min_price] = 100    # Can be blank.
 params[:max_price] = 300    # Can be blank.
 </code></pre>
 
-<p>Let's build a tuple:</p>
+<p>Let’s build a tuple:</p>
 
-<pre><code>tup = SmartTuple.new(&quot; AND &quot;) +
+<pre><code>tup = SmartTuple.new(" AND ") +
   ({:brand =&gt; params[:brand]} if params[:brand].present?) +
-  ([&quot;min_price &gt;= ?&quot;, params[:min_price]] if params[:min_price].present?) +
-  ([&quot;max_price &lt;= ?&quot;, params[:max_price]] if params[:max_price].present?)
+  (["min_price &gt;= ?", params[:min_price]] if params[:min_price].present?) +
+  (["max_price &lt;= ?", params[:max_price]] if params[:max_price].present?)
 </code></pre>
 
 <p>The above code shows that we can construct ready-made tuples with a single expression, using <code>+</code> operator. Also, if a condition is an equality test, we can use Hash notation: <code>{:brand =&gt; params[:brand]}</code>.</p>
 
 <p>A quick look at <code>params</code> and <code>:conditions</code>, again:</p>
 
-<pre><code>p: {:brand=&gt;&quot;Nokia&quot;}
-c: [&quot;brand = ?&quot;, &quot;Nokia&quot;]
+<pre><code>p: {:brand=&gt;"Nokia"}
+c: ["brand = ?", "Nokia"]
 
-p: {:brand=&gt;&quot;Nokia&quot;, :max_price=&gt;300}
-c: [&quot;brand = ? AND max_price &lt;= ?&quot;, &quot;Nokia&quot;, 300]
+p: {:brand=&gt;"Nokia", :max_price=&gt;300}
+c: ["brand = ? AND max_price &lt;= ?", "Nokia", 300]
 
-p: {:brand=&gt;&quot;Nokia&quot;, :min_price=&gt;100, :max_price=&gt;300}
-c: [&quot;brand = ? AND min_price &gt;= ? AND max_price &lt;= ?&quot;, &quot;Nokia&quot;, 100, 300]
+p: {:brand=&gt;"Nokia", :min_price=&gt;100, :max_price=&gt;300}
+c: ["brand = ? AND min_price &gt;= ? AND max_price &lt;= ?", "Nokia", 100, 300]
 </code></pre>
 
 <h3 id="we-want-more">We Want More!</h3>
 
-<p>Since we now see how easy it's to build compound conditions, we decide to further extend our search form. Now we want to:</p>
+<p>Since we now see how easy it’s to build compound conditions, we decide to further extend our search form. Now we want to:</p>
 
 <ul>
   <li>Let user specify more than 1 brand.</li>
   <li>Let user specify a selection of colors.</li>
 </ul>
 
-<p>From <code>params</code> perspective that's something like:</p>
+<p>From <code>params</code> perspective that’s something like:</p>
 
-<pre><code>params[:brands] = [&quot;Nokia&quot;, &quot;Motorola&quot;]         # Can be blank.
+<pre><code>params[:brands] = ["Nokia", "Motorola"]         # Can be blank.
 params[:min_price] = 100                        # Can be blank.
 params[:max_price] = 300                        # Can be blank.
-params[:colors] = [&quot;Black&quot;, &quot;Silver&quot;, &quot;Pink&quot;]   # Can be blank.
+params[:colors] = ["Black", "Silver", "Pink"]   # Can be blank.
 </code></pre>
 
-<p>Quite obvious is that supplied values for brands and colors should be OR'ed. We're now facing the task of creating a &quot;sub-tuple&quot;, e.g. to match brand, and then merging this sub-tuple into main tuple. Doing it straight is something like:</p>
+<p>Quite obvious is that supplied values for brands and colors should be OR’ed. We’re now facing the task of creating a “sub-tuple”, e.g. to match brand, and then merging this sub-tuple into main tuple. Doing it straight is something like:</p>
 
-<pre><code>tup = SmartTuple.new(&quot; AND &quot;)
+<pre><code>tup = SmartTuple.new(" AND ")
 
 if params[:brands].present?
-  subtup = SmartTuple.new(&quot; OR &quot;)
-  params[:brands].each {|brand| subtup &lt;&lt; [&quot;brand = ?&quot;, brand]}
+  subtup = SmartTuple.new(" OR ")
+  params[:brands].each {|brand| subtup &lt;&lt; ["brand = ?", brand]}
   tup &lt;&lt; subtup
 end
 </code></pre>
 
 <p>Or, in a smarter way by utilizing <code>#add_each</code> method:</p>
 
-<pre><code>tup = SmartTuple.new(&quot; AND &quot;)
-tup &lt;&lt; SmartTuple.new(&quot; OR &quot;).add_each(params[:brands]) {|v| [&quot;brand = ?&quot;, v]} if params[:brands].present?
+<pre><code>tup = SmartTuple.new(" AND ")
+tup &lt;&lt; SmartTuple.new(" OR ").add_each(params[:brands]) {|v| ["brand = ?", v]} if params[:brands].present?
 </code></pre>
 
 <p>The final query:</p>
 
-<pre><code>Phone.find(:all, {:conditions =&gt; [SmartTuple.new(&quot; AND &quot;),
-  (SmartTuple.new(&quot; OR &quot;).add_each(params[:brands]) {|v| [&quot;brand = ?&quot;, v]} if params[:brands].present?),
-  ([&quot;min_price &gt;= ?&quot;, params[:min_price]] if params[:min_price].present?),
-  ([&quot;max_price &lt;= ?&quot;, params[:max_price]] if params[:max_price].present?),
-  (SmartTuple.new(&quot; OR &quot;).add_each(params[:colors]) {|v| [&quot;color = ?&quot;, v]} if params[:colors].present?),
+<pre><code>Phone.find(:all, {:conditions =&gt; [SmartTuple.new(" AND "),
+  (SmartTuple.new(" OR ").add_each(params[:brands]) {|v| ["brand = ?", v]} if params[:brands].present?),
+  (["min_price &gt;= ?", params[:min_price]] if params[:min_price].present?),
+  (["max_price &lt;= ?", params[:max_price]] if params[:max_price].present?),
+  (SmartTuple.new(" OR ").add_each(params[:colors]) {|v| ["color = ?", v]} if params[:colors].present?),
 ].sum.compile})
 </code></pre>
 
 <blockquote>
-  <p>NOTE: In the above sample I've used <code>Array#sum</code> (available in ActiveSupport) instead of <code>+</code> to add statements to the tuple. I prefer to write it like this since it allows to comment and swap lines without breaking the syntax.</p>
+  <p>NOTE: In the above sample I’ve used <code>Array#sum</code> (available in ActiveSupport) instead of <code>+</code> to add statements to the tuple. I prefer to write it like this since it allows to comment and swap lines without breaking the syntax.</p>
+</blockquote>
+
+<blockquote>
+  <p>NOTE: Recommended Rails 3 usage is:</p>
+
+  <pre><code>Phone.where(...)      # Pass a compiled SmartTuple object in place of `...`.
+</code></pre>
 </blockquote>
 
 <p>Checking out <code>params</code> and <code>:conditions</code>:</p>
 
-<pre><code>p: {:brands=&gt;[&quot;Nokia&quot;], :max_price=&gt;300}
-c: [&quot;brand = ? AND max_price &lt;= ?&quot;, &quot;Nokia&quot;, 300]
+<pre><code>p: {:brands=&gt;["Nokia"], :max_price=&gt;300}
+c: ["brand = ? AND max_price &lt;= ?", "Nokia", 300]
 
-p: {:brands=&gt;[&quot;Nokia&quot;, &quot;Motorola&quot;], :max_price=&gt;300}
-c: [&quot;(brand = ? OR brand = ?) AND max_price &lt;= ?&quot;, &quot;Nokia&quot;, &quot;Motorola&quot;, 300]
+p: {:brands=&gt;["Nokia", "Motorola"], :max_price=&gt;300}
+c: ["(brand = ? OR brand = ?) AND max_price &lt;= ?", "Nokia", "Motorola", 300]
      ^--                    ^-- note the auto brackets
 
-p: {:brands=&gt;[&quot;Nokia&quot;, &quot;Motorola&quot;], :max_price=&gt;300, :colors=&gt;[&quot;Black&quot;]}
-c: [&quot;(brand = ? OR brand = ?) AND max_price &lt;= ? AND color = ?&quot;, &quot;Nokia&quot;, &quot;Motorola&quot;, 300, &quot;Black&quot;]
+p: {:brands=&gt;["Nokia", "Motorola"], :max_price=&gt;300, :colors=&gt;["Black"]}
+c: ["(brand = ? OR brand = ?) AND max_price &lt;= ? AND color = ?", "Nokia", "Motorola", 300, "Black"]
 
-p: {:brands=&gt;[&quot;Nokia&quot;, &quot;Motorola&quot;], :colors=&gt;[&quot;Black&quot;, &quot;Silver&quot;, &quot;Pink&quot;]}
-c: [&quot;(brand = ? OR brand = ?) AND (color = ? OR color = ? OR color = ?)&quot;, &quot;Nokia&quot;, &quot;Motorola&quot;, &quot;Black&quot;, &quot;Silver&quot;, &quot;Pink&quot;]
+p: {:brands=&gt;["Nokia", "Motorola"], :colors=&gt;["Black", "Silver", "Pink"]}
+c: ["(brand = ? OR brand = ?) AND (color = ? OR color = ? OR color = ?)", "Nokia", "Motorola", "Black", "Silver", "Pink"]
 </code></pre>
 
-<p>That's the end of our tutorial. Hope now you've got an idea of what SmartTuple is.</p>
+<p>That’s the end of our tutorial. Hope now you’ve got an idea of what SmartTuple is.</p>
 
 <h2 id="api-summary">API Summary</h2>
 
-<p>Here's a brief cheatsheet, which outlines main SmartTuple features.</p>
+<p>Here’s a brief cheatsheet, which outlines the main SmartTuple features.</p>
 
 <h3 id="appending-statements">Appending Statements</h3>
 
 <pre><code># Array.
-tup &lt;&lt; [&quot;brand = ?&quot;, &quot;Nokia&quot;]
-tup &lt;&lt; [&quot;brand = ? AND color = ?&quot;, &quot;Nokia&quot;, &quot;Black&quot;]
+tup &lt;&lt; ["brand = ?", "Nokia"]
+tup &lt;&lt; ["brand = ? AND color = ?", "Nokia", "Black"]
 
 # Hash.
-tup &lt;&lt; {:brand =&gt; &quot;Nokia&quot;}
-tup &lt;&lt; {:brand =&gt; &quot;Nokia&quot;, :color =&gt; &quot;Black&quot;}
+tup &lt;&lt; {:brand =&gt; "Nokia"}
+tup &lt;&lt; {:brand =&gt; "Nokia", :color =&gt; "Black"}
 
 # Another SmartTuple.
 tup &lt;&lt; other_tuple
 
-# String.
-tup &lt;&lt; &quot;brand IS NULL&quot;
+# String. Generally NOT recommended.
+tup &lt;&lt; "min_price &gt;= 75"
 </code></pre>
 
 <p>Appending empty or blank (where appropriate) statements has no effect on the receiver:</p>
@@ -210,24 +235,24 @@ tup &lt;&lt; &quot;brand IS NULL&quot;
 tup &lt;&lt; []
 tup &lt;&lt; {}
 tup &lt;&lt; an_empty_tuple
-tup &lt;&lt; &quot;&quot;
-tup &lt;&lt; &quot;  &quot;     # Will be treated as blank if ActiveSupport is on.
+tup &lt;&lt; ""
+tup &lt;&lt; "  "     # Will be treated as blank if ActiveSupport is on.
 </code></pre>
 
 <p>Another way to append something is to use <code>+</code>.</p>
 
-<pre><code>tup = SmartTuple.new(&quot; AND &quot;) + {:brand =&gt; &quot;Nokia&quot;} + [&quot;max_price &lt;= ?&quot;, 300]
+<pre><code>tup = SmartTuple.new(" AND ") + {:brand =&gt; "Nokia"} + ["max_price &lt;= ?", 300]
 </code></pre>
 
 <p>Appending one statement per each collection item is easy through <code>#add_each</code>:</p>
 
-<pre><code>tup.add_each([&quot;Nokia&quot;, &quot;Motorola&quot;]) {|v| [&quot;brand = ?&quot;, v]}
+<pre><code>tup.add_each(["Nokia", "Motorola"]) {|v| ["brand = ?", v]}
 </code></pre>
 
 <p>The latter can be made conditional. Remember, appending <code>nil</code> has no effect on the receiving tuple, which gives us freedom to use conditions whenever we want to:</p>
 
-<pre><code>tup.add_each([&quot;Nokia&quot;, &quot;Motorola&quot;]) do |v|
-  [&quot;brand = ?&quot;, v] if v =~ /^Moto/
+<pre><code>tup.add_each(["Nokia", "Motorola"]) do |v|
+  ["brand = ?", v] if v =~ /^Moto/
 end
 </code></pre>
 
@@ -235,7 +260,7 @@ end
 
 <p><em>This chapter still has to be written.</em></p>
 
-<pre><code>tup = SmartTuple.new(&quot; AND &quot;)
+<pre><code>tup = SmartTuple.new(" AND ")
 tup.brackets
 =&gt; :auto
 
@@ -255,43 +280,44 @@ tup.brackets = :auto
 
 <p>Compiling is converting the tuple into something suitable for use as <code>:conditions</code> of an ActiveRecord call.</p>
 
-<p>It's as straight as:</p>
+<p>It’s as straight as:</p>
 
 <pre><code>tup.compile
 tup.to_a        # An alias, does the same.
 
 # Go fetch!
-Phone.find(:all, :conditions =&gt; tup.compile)
+Phone.find(:all, :conditions =&gt; tup.compile)    # Rails 2
+Phone.where(tup.compile)                        # Rails 3
 </code></pre>
 
 <h3 id="contents-and-size">Contents and Size</h3>
 
-<p>You can examine tuple's state with methods often found in other Ruby classes: <code>#empty?</code>, <code>#size</code>, and attribute accessors <code>#statements</code> and <code>#args</code>.</p>
+<p>You can examine tuple’s state with methods often found in other Ruby classes: <code>#empty?</code>, <code>#size</code>, and attribute accessors <code>#statements</code> and <code>#args</code>.</p>
 
-<pre><code>tup = SmartTuple.new(&quot; AND &quot;)
+<pre><code>tup = SmartTuple.new(" AND ")
 tup.empty?
 =&gt; true
 tup.size
 =&gt; 0
 
-tup &lt;&lt; [&quot;brand = ?&quot;, &quot;Nokia&quot;]
+tup &lt;&lt; ["brand = ?", "Nokia"]
 tup.empty?
 =&gt; false
 tup.size
 =&gt; 1
 
-tup &lt;&lt; [&quot;max_price &gt;= ?&quot;, 300]
+tup &lt;&lt; ["max_price &gt;= ?", 300]
 tup.size
 =&gt; 2
 
 tup.statements
-=&gt; [&quot;brand = ?&quot;, &quot;max_price &gt;= ?&quot;]
+=&gt; ["brand = ?", "max_price &gt;= ?"]
 tup.args
-=&gt; [&quot;Nokia&quot;, 300]
+=&gt; ["Nokia", 300]
 </code></pre>
 
 <h2 id="feedback">Feedback</h2>
 
-<p>Send bug reports, suggestions and criticisms through <a href="http://github.com/dadooda/smart_tuple">project's page on GitHub</a>.</p>
+<p>Send bug reports, suggestions and criticisms through <a href="http://github.com/dadooda/smart_tuple">project’s page on GitHub</a>.</p>
 
 <p>Licensed under the MIT License.</p>

data/README.md

@@ -6,21 +6,39 @@ SmartTuple: A Simple Yet Smart SQL Conditions Builder
 Introduction
 ------------
 
-Sometimes we need to build SQL WHERE statements which are compound or conditional by nature. SmartTuple simplifies this task by letting us build statements of virtually unlimited complexity out of smaller ones.
+Sometimes we need to build SQL `WHERE` statements which are compound or conditional by nature. **SmartTuple** simplifies this task by letting us build statements of virtually unlimited complexity out of smaller ones.
 
 SmartTuple is suitable for use with Ruby on Rails (ActiveRecord) and other Ruby frameworks and ORMs.
 
 
-Setup
------
+Setup (Rails 3)
+---------------
+
+In your app's `Gemfile`, add:
+
+    gem "smart_tuple"
+
+To install the gem with RDoc/ri documentation, do a:
 
-    $ gem sources --add http://rubygems.org
     $ gem install smart_tuple
 
+Otherwise, do a `bundle install`.
+
+
+Setup (Rails 2)
+---------------
+
 In your app's `config/environment.rb` do a:
 
     config.gem "smart_tuple"
 
+To install the gem, do a:
+
+    $ gem sources --add http://rubygems.org
+    $ gem install smart_tuple
+
+, or use `rake gems:install`.
+
 
 Kickstart Demo
 --------------
@@ -32,7 +50,7 @@ Kickstart Demo
 
     @phones = Phone.find(:all, :conditions => tup.compile)
 
-There's a number of ways you can use SmartTuple depending on the situation. They are covered in the tutorial below.
+There's a number of ways you can use SmartTuple. Some of them is covered in the tutorial below.
 
 
 Tutorial
@@ -151,6 +169,10 @@ The final query:
 
 > NOTE: In the above sample I've used `Array#sum` (available in ActiveSupport) instead of `+` to add statements to the tuple. I prefer to write it like this since it allows to comment and swap lines without breaking the syntax.
 
+> NOTE: Recommended Rails 3 usage is:
+>
+>     Phone.where(...)      # Pass a compiled SmartTuple object in place of `...`.
+
 Checking out `params` and `:conditions`:
 
     p: {:brands=>["Nokia"], :max_price=>300}
@@ -172,7 +194,7 @@ That's the end of our tutorial. Hope now you've got an idea of what SmartTuple i
 API Summary
 -----------
 
-Here's a brief cheatsheet, which outlines main SmartTuple features.
+Here's a brief cheatsheet, which outlines the main SmartTuple features.
 
 ### Appending Statements ###
 
@@ -187,8 +209,8 @@ Here's a brief cheatsheet, which outlines main SmartTuple features.
     # Another SmartTuple.
     tup << other_tuple
 
-    # String.
-    tup << "brand IS NULL"
+    # String. Generally NOT recommended.
+    tup << "min_price >= 75"
 
 Appending empty or blank (where appropriate) statements has no effect on the receiver:
 
@@ -244,7 +266,8 @@ It's as straight as:
     tup.to_a        # An alias, does the same.
 
     # Go fetch!
-    Phone.find(:all, :conditions => tup.compile)
+    Phone.find(:all, :conditions => tup.compile)    # Rails 2
+    Phone.where(tup.compile)                        # Rails 3
 
 
 ### Contents and Size ###

data/Rakefile

@@ -1,4 +1,5 @@
 require "rake/rdoctask"
+require "yaml"
 
 GEM_NAME = "smart_tuple"
 
@@ -14,9 +15,9 @@ begin
     gem.files = FileList[
       "[A-Z]*",
       "*.gemspec",
-      "generators/**/*",
-      "lib/**/*.rb",
       "init.rb",
+      "lib/**/*.rb",
+      "spec/**/*.rb",
     ]
   end
 rescue LoadError
@@ -26,13 +27,22 @@ end
 desc "Rebuild gemspec and package"
 task :rebuild => [:gemspec, :build]
 
-desc "Push (publish) gem to RubyGems (aka Gemcutter)"
-task :push => :rebuild do
-  # Yet found no way to ask Jeweler forge a complete version string for us.
+desc "Push (publish) gem to RubyGems.org"
+task :push do
+  # NOTE: Yet found no way to ask Jeweler forge a complete version string for us.
   vh = YAML.load(File.read("VERSION.yml"))
-  version = [vh[:major], vh[:minor], vh[:patch]].join(".")
-  pkgfile = File.join("pkg", [GEM_NAME, "-", version, ".gem"].to_s)
-  system("gem", "push", pkgfile)
+  version = [vh[:major], vh[:minor], vh[:patch], vh[:build]].compact.join(".")
+  pkgfile = File.join("pkg", "#{GEM_NAME}-#{version}.gem")
+  Kernel.system("gem", "push", pkgfile)
+end
+
+desc "Generate RDoc documentation"
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "doc"
+  rdoc.title    = "SmartTuple"
+  #rdoc.options << "--line-numbers"
+  #rdoc.options << "--inline-source"
+  rdoc.rdoc_files.include("lib/**/*.rb")
 end
 
 desc "Compile README preview"

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
 :minor: 1
-:patch: 1
+:patch: 2

data/init.rb

@@ -1,3 +1,4 @@
+# Rails plugin init.
 Dir[File.join(File.dirname(__FILE__), "lib/**/*.rb")].each do |fn|
   require fn
 end

data/lib/smart_tuple.rb

@@ -1,34 +1,50 @@
+# SQL condition builder.
+#
+#   tup = SmartTuple.new(" AND ")
+#   tup << {:brand => "Nokia"}
+#   tup << ["min_price >= ?", 75]
+#   tup.compile   # => ["brand = ? AND min_price >= ?", "Nokia", 75]
 class SmartTuple
+  # Array of SQL argument parts.
   attr_reader :args
+
+  # Put brackets around statements. <tt>true</tt>, <tt>false</tt> or <tt>:auto</tt>. Default:
+  #
+  #   :auto
   attr_reader :brackets
+
+  # String to glue statements together.
   attr_accessor :glue
+
+  # Array of SQL statement parts.
   attr_reader :statements
 
+  # Initializer.
+  #
   #   new(" AND ")
-  #   new(" OR ")
-  #   new(", ")       # E.g. for a SET or UPDATE statement.
+  #   new(" OR ", :brackets => true)
   def initialize(glue, attrs = {})
     @glue = glue
     clear
     attrs.each {|k, v| send("#{k}=", v)}
   end
 
-  # We need it to control #dup behaviour.
-  def initialize_copy(src)
+  # Service initializer for <tt>dup</tt>.
+  def initialize_copy(src)    #:nodoc:
     @statements = src.statements.dup
     @args = src.args.dup
   end
 
-  # NOTE: Alphabetical order below.
-
-  # Add a sub-statement, return new object. See <tt>#&lt;&lt;</tt>.
+  # Add a statement, return new object. See #<<.
+  #
   #   SmartTuple.new(" AND ") + {:brand => "Nokia"} + ["max_price <= ?", 300]
-  def +(sub)
+  def +(arg)
     # Since #<< supports chaining, it boils down to this.
-    dup << sub
+    dup << arg
   end
 
-  # Append a sub-statement.
+  # Add a statement, return self.
+  #
   #   # Array.
   #   tup << ["brand = ?", "Nokia"]
   #   tup << ["brand = ? AND color = ?", "Nokia", "Black"]
@@ -41,70 +57,71 @@ class SmartTuple
   #   tup << other_tuple
   #
   #   # String. Generally NOT recommended.
-  #   tup << "brand IS NULL"
+  #   tup << "min_price >= 75"
+  #
+  # Adding anything empty or blank (where appropriate) has no effect on the receiver:
   #
-  # Appending empty or blank (where appropriate) statements has no effect on the receiver:
   #   tup << nil
   #   tup << []
   #   tup << {}
   #   tup << another_empty_tuple
   #   tup << ""
   #   tup << "  "     # Will be treated as blank if ActiveSupport is on.
-  def <<(sub)
-    ##p "self.class", self.class
-
-    # NOTE: Autobracketing help is placing [value] instead of (value) into @statements. #compile will take it into account.
+  def <<(arg)
+    # NOTE: Autobracketing is placing `[value]` instead of `value` into `@statements`. #compile understands it.
 
     # Chop off everything empty first time.
-    if sub.nil? or (sub.empty? rescue false) or (sub.blank? rescue false)
-      ##puts "-- empty"
-    elsif sub.is_a? String or (sub.acts_like? :string rescue false)
-      ##puts "-- is a string"
-      @statements << sub.to_s
-    elsif sub.is_a? Array
-      # NOTE: If sub == [], the execution won't get here.
+    if arg.nil? or (arg.empty? rescue false) or (arg.blank? rescue false)
+    elsif arg.is_a? String or (arg.acts_like? :string rescue false)
+      @statements << arg.to_s
+    elsif arg.is_a? Array
+      # NOTE: If arg == [], the execution won't get here.
       #       So, we've got at least one element. Therefore stmt will be scalar, and args -- DEFINITELY an array.
-      stmt, args = sub[0], sub[1..-1]
-      ##p "stmt", stmt
-      ##p "args", args
+      stmt, args = arg[0], arg[1..-1]
       if not (stmt.nil? or (stmt.empty? rescue false) or (stmt.blank? rescue false))
-        ##puts "-- stmt nempty"
         # Help do autobracketing later. Here we can ONLY judge by number of passed arguments.
         @statements << (args.size > 1 ? [stmt] : stmt)
         @args += args
       end
-    elsif sub.is_a? Hash
-      sub.each do |k, v|
-        @statements << "#{k} = ?"
-        @args << v
+    elsif arg.is_a? Hash
+      arg.each do |k, v|
+        if v.nil?
+          # NOTE: AR supports it for Hashes only. ["kk = ?", nil] will not be converted.
+          @statements << "#{k} IS NULL"
+        else
+          @statements << "#{k} = ?"
+          @args << v
+        end
       end
-    elsif sub.is_a? self.class
-      # NOTE: If sub is empty, the execution won't get here.
+    elsif arg.is_a? self.class
+      # NOTE: If arg is empty, the execution won't get here.
 
       # Autobrackets here are smarter, than in Array processing case.
-      stmt = sub.compile[0]
-      @statements << ((sub.size > 1 or sub.args.size > 1) ? [stmt] : stmt)
-      @args += sub.args
+      stmt = arg.compile[0]
+      @statements << ((arg.size > 1 or arg.args.size > 1) ? [stmt] : stmt)
+      @args += arg.args
     else
-      raise ArgumentError, "Invalid sub-statement #{sub.inspect}"
+      raise ArgumentError, "Invalid statement #{arg.inspect}"
     end
 
     # Return self, it's IMPORTANT to make chaining possible.
     self
   end
 
-  # Iterate over collection and add block's result per each record.
+  # Iterate over collection and add block's result to self once per each record.
+  #
   #   add_each(brands) do |v|
   #     ["brand = ?", v]
   #   end
   #
   # Can be conditional:
+  #
   #   tup.add_each(["Nokia", "Motorola"]) do |v|
   #     ["brand = ?", v] if v =~ /^Moto/
   #   end
   def add_each(collection, &block)
     raise ArgumentError, "Code block expected" if not block
-    ##p "collection", collection
+
     collection.each do |v|
       self << yield(v)
     end
@@ -114,6 +131,7 @@ class SmartTuple
   end
 
   # Set bracketing mode.
+  #
   #   brackets = true         # Put brackets around each sub-statement.
   #   brackets = false        # Don't put brackets.
   #   brackets = :auto        # Automatically put brackets around compound sub-statements.
@@ -122,23 +140,23 @@ class SmartTuple
     @brackets = value
   end
 
-  # Set self into default state.
+  # Clear self.
   def clear
     @statements = []
     @args = []
     @brackets = :auto
 
-    # Array does it like this. We do either.
+    # `Array` does it like this. We do either.
     self
   end
 
-  # Compile self into an array.
+  # Compile self into an array. Empty self yields empty array.
+  #
+  #   compile   # => []
+  #   compile   # => ["brand = ? AND min_price >= ?", "Nokia", 75]
   def compile
     return [] if empty?
 
-    ##p "@statements", @statements
-    ##p "@args", @args
-
     # Build "bracketed" statements.
     bsta = @statements.map do |s|
       auto_brackets, scalar_s = s.is_a?(Array) ? [true, s[0]] : [false, s]
@@ -173,6 +191,10 @@ class SmartTuple
   end
   alias_method :to_a, :compile
 
+  # Return <tt>true</tt> if self is empty.
+  #
+  #   tup = SmartTuple.new(" AND ")
+  #   tup.empty?    # => true
   def empty?
     @statements.empty?
   end

data/smart_tuple.gemspec

@@ -1,43 +1,39 @@
 # Generated by jeweler
-# DO NOT EDIT THIS FILE
-# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
 # -*- encoding: utf-8 -*-
 
 Gem::Specification.new do |s|
   s.name = %q{smart_tuple}
-  s.version = "0.1.1"
+  s.version = "0.1.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Alex Fortuna"]
-  s.date = %q{2010-11-16}
+  s.date = %q{2011-07-14}
   s.description = %q{A Simple Yet Smart SQL Conditions Builder}
   s.email = %q{alex.r@askit.org}
   s.extra_rdoc_files = [
     "README.html",
-     "README.md"
+    "README.md"
   ]
   s.files = [
     "MIT-LICENSE",
-     "README.html",
-     "README.md",
-     "Rakefile",
-     "VERSION.yml",
-     "init.rb",
-     "lib/smart_tuple.rb",
-     "smart_tuple.gemspec"
+    "README.html",
+    "README.md",
+    "Rakefile",
+    "VERSION.yml",
+    "init.rb",
+    "lib/smart_tuple.rb",
+    "smart_tuple.gemspec",
+    "spec/smart_tuple_spec.rb",
+    "spec/spec_helper.rb"
   ]
   s.homepage = %q{http://github.com/dadooda/smart_tuple}
-  s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.7}
+  s.rubygems_version = %q{1.6.2}
   s.summary = %q{A Simple Yet Smart SQL Conditions Builder}
-  s.test_files = [
-    "spec/spec_helper.rb",
-     "spec/smart_tuple_spec.rb"
-  ]
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
@@ -46,3 +42,4 @@ Gem::Specification.new do |s|
   else
   end
 end
+

data/spec/smart_tuple_spec.rb

@@ -188,6 +188,7 @@ describe (klass = SmartTuple) do
     end
   end # #+
 
+  # Most tests are here, since arg conversion is performed right in `<<`.
   describe "#<<" do
     it "ignores nil/empty/blank objects" do
       objs = []
@@ -210,6 +211,14 @@ describe (klass = SmartTuple) do
       (r << ["is_male = ?", true]).should eql r
     end
 
+    it "supports IS NULL for Hash" do
+      r << {:kk => nil}
+      r.compile.should == ["kk IS NULL"]
+
+      r << {:mkk => 10}
+      r.compile.should == ["kk IS NULL AND mkk = ?", 10]
+    end
+
     it "supports chaining" do
       r << ["age >= ?", 18] << "created_at IS NULL"
       r.compile.should == ["age >= ? AND created_at IS NULL", 18]

metadata

@@ -1,13 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: smart_tuple
 version: !ruby/object:Gem::Version 
-  hash: 25
-  prerelease: false
-  segments: 
-  - 0
-  - 1
-  - 1
-  version: 0.1.1
+  prerelease: 
+  version: 0.1.2
 platform: ruby
 authors: 
 - Alex Fortuna
@@ -15,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-16 00:00:00 +03:00
+date: 2011-07-14 00:00:00 +04:00
 default_executable: 
 dependencies: []
 
@@ -37,15 +32,15 @@ files:
 - init.rb
 - lib/smart_tuple.rb
 - smart_tuple.gemspec
-- spec/spec_helper.rb
 - spec/smart_tuple_spec.rb
+- spec/spec_helper.rb
 has_rdoc: true
 homepage: http://github.com/dadooda/smart_tuple
 licenses: []
 
 post_install_message: 
-rdoc_options: 
-- --charset=UTF-8
+rdoc_options: []
+
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -53,26 +48,19 @@ required_ruby_version: !ruby/object:Gem::Requirement
   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.3.7
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: A Simple Yet Smart SQL Conditions Builder
-test_files: 
-- spec/spec_helper.rb
-- spec/smart_tuple_spec.rb
+test_files: []
+