squeel_rbg 0.8.2

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/.yardopts

@@ -0,0 +1,3 @@
+--main README.md
+--private
+--exclude compat

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+gemspec
+
+if ENV['RAILS_VERSION'] == 'release'
+  gem 'activesupport'
+  gem 'activerecord'
+else
+  gem 'arel',  :git => 'git://github.com/rails/arel.git'
+  git 'git://github.com/rails/rails.git' do
+    gem 'activesupport'
+    gem 'activerecord'
+  end
+end

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010-2011 Ernie Miller
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,398 @@
+# Squeel
+
+Squeel lets you write your ActiveRecord queries with with fewer strings, and more Ruby,
+by making the ARel awesomeness that lies beneath ActiveRecord more accessible.
+
+Squeel lets you rewrite...
+
+    Article.where ['created_at >= ?', 2.weeks.ago]
+
+...as...
+
+    Article.where{created_at >= 2.weeks.ago}
+
+This is a _good thing_. If you don't agree, Squeel might not be for you. The above is
+just a simple example -- Squeel's capable of a whole lot more. Keep reading.
+
+## Getting started
+
+In your Gemfile:
+
+    gem "squeel"  # Last officially released gem
+    # gem "squeel", :git => "git://github.com/ernie/squeel.git" # Track git repo
+
+In an initializer:
+
+    Squeel.configure do |config|
+      # To load hash extensions (to allow for AND (&), OR (|), and NOT (-) against
+      # hashes of conditions)
+      config.load_core_extensions :hash
+
+      # To load symbol extensions (for a subset of the old MetaWhere functionality,
+      # via ARel predicate methods on Symbols: :name.matches, etc)
+      # config.load_core_extensions :symbol
+
+      # To load both hash and symbol extensions
+      # config.load_core_extensions :hash, :symbol
+    end
+
+## The Squeel Query DSL
+
+Squeel enhances the normal ActiveRecord query methods by enabling them to accept
+blocks. Inside a block, the Squeel query DSL can be used. Note the use of curly braces
+in these examples instead of parentheses. `{}` denotes a Squeel DSL query.
+
+Stubs and keypaths are the two primary building blocks used in a Squeel DSL query, so we'll
+start by taking a look at them. Most of the other examples that follow will be based on
+this "symbol-less" block syntax.
+
+**An important gotcha, before we begin:** The Squeel DSL works its magic using `instance_eval`.
+If you've been working with Ruby for a while, you'll know immediately that this means that
+_inside_ a Squeel DSL block, `self` isn't the same thing that it is _outside_ the block.
+
+This carries with it an important implication: <strong>Instance variables and instance methods
+inside the block won't refer to your object's variables/methods.</strong>
+
+Don't worry, Squeel's got you covered. Use one of the following methods to get access
+to your object's methods and variables:
+
+  1. Assign the variable locally before the DSL block, and access it as you would
+     normally.
+  2. Supply an arity to the DSL block, as in `Person.where{|q| q.name == @my_name}`
+     Downside: You'll need to prefix stubs, keypaths, and functions (explained below)
+     with the DSL object.
+  3. Wrap the method or instance variable inside the block with `my{}`.
+     `Person.where{name == my{some_method_to_return_a_name}}`
+
+### Stubs
+
+Stubs are, for most intents and purposes, just like Symbols in a normal call to
+`Relation#where` (note the need for doubling up on the curly braces here, the first ones
+start the block, the second are the hash braces):
+
+    Person.where{{name => 'Ernie'}}
+    => SELECT "people".* FROM "people"  WHERE "people"."name" = 'Ernie'
+
+You normally wouldn't bother using the DSL in this case, as a simple hash would
+suffice. However, stubs serve as a building block for keypaths, and keypaths are
+very handy.
+
+### KeyPaths
+
+A Squeel keypath is essentially a more concise and readable alternative to a
+deeply nested hash. For instance, in standard ActiveRecord, you might join several
+associations like this to perform a query:
+
+    Person.joins(:articles => {:comments => :person})
+    => SELECT "people".* FROM "people"
+         INNER JOIN "articles" ON "articles"."person_id" = "people"."id"
+         INNER JOIN "comments" ON "comments"."article_id" = "articles"."id"
+         INNER JOIN "people" "people_comments" ON "people_comments"."id" = "comments"."person_id"
+
+With a keypath, this would look like:
+
+    Person.joins{articles.comments.person}
+
+A keypath can exist in the context of a hash, and is normally interpreted relative to
+the current level of nesting. It can be forced into an "absolute" path by anchoring it with
+a ~, like:
+
+    ~articles.comments.person
+
+This isn't quite so useful in the typical hash context, but can be very useful when it comes
+to interpreting functions and the like. We'll cover those later.
+
+### Predicates
+
+All of the ARel "predication" methods can be accessed inside the Squeel DSL, via
+their method name, an alias, or an an operator, to create ARel predicates, which are
+used in `WHERE` or `HAVING` clauses.
+
+<table>
+  <tr>
+    <th>SQL</th>
+    <th>Predication</th>
+    <th>Operator</th>
+    <th>Alias</th>
+  </tr>
+  <tr>
+    <td>=</td>
+    <td>eq</td>
+    <td>==</td>
+    <td></td>
+  </tr>
+  <tr>
+    <td>!=</td>
+    <td>not_eq</td>
+    <td>!= (1.9 only), ^ (1.8)</td>
+    <td></td>
+  </tr>
+  <tr>
+    <td>LIKE</td>
+    <td>matches</td>
+    <td>=~</td>
+    <td>like</td>
+  </tr>
+  <tr>
+    <td>NOT LIKE</td>
+    <td>does_not_match</td>
+    <td>!~ (1.9 only)</td>
+    <td>not_like</td>
+  </tr>
+  <tr>
+    <td>&lt;</td>
+    <td>lt</td>
+    <td>&lt;</td>
+    <td></td>
+  </tr>
+  <tr>
+    <td>&lt;=</td>
+    <td>lteq</td>
+    <td>&lt;=</td>
+    <td>lte</td>
+  </tr>
+  <tr>
+    <td>></td>
+    <td>gt</td>
+    <td>></td>
+    <td></td>
+  </tr>
+  <tr>
+    <td>>=</td>
+    <td>gteq</td>
+    <td>>=</td>
+    <td>gte</td>
+  </tr>
+  <tr>
+    <td>IN</td>
+    <td>in</td>
+    <td>>></td>
+    <td></td>
+  </tr>
+  <tr>
+    <td>NOT IN</td>
+    <td>not_in</td>
+    <td>&lt;&lt;</td>
+    <td></td>
+  </tr>
+</table>
+
+Let's say we want to generate this simple query:
+
+    SELECT "people".* FROM people WHERE "people"."name" = 'Joe Blow'
+
+All of the following will generate the above SQL:
+
+    Person.where(:name => 'Joe Blow')
+    Person.where{{name => 'Joe Blow'}}
+    Person.where{{name.eq => 'Joe Blow'}}
+    Person.where{name.eq 'Joe Blow'}
+    Person.where{name == 'Joe Blow'}
+    
+Not a very exciting example since equality is handled just fine via the
+first example in standard ActiveRecord. But consider the following query:
+
+    SELECT "people".* FROM people
+    WHERE ("people"."name" LIKE 'Ernie%' AND "people"."salary" < 50000)
+      OR  ("people"."name" LIKE 'Joe%' AND "people"."salary" > 100000)
+      
+To do this with standard ActiveRecord, we'd do something like:
+
+    Person.where(
+      '(name LIKE ? AND salary < ?) OR (name LIKE ? AND salary > ?)',
+      'Ernie%', 50000, 'Joe%', 100000
+    )
+    
+With Squeel:
+
+    Person.where{(name =~ 'Ernie%') & (salary < 50000) | (name =~ 'Joe%') & (salary > 100000)}
+    
+Here, we're using `&` and `|` to generate `AND` and `OR`, respectively.
+
+There are two obvious but important differences between these two code samples, and
+both of them have to do with *context*.
+
+1. To read code with SQL interpolation, the structure of the SQL query must
+   first be considered, then we must cross-reference the values to be substituted
+   with their placeholders. This carries with it a small but perceptible (and
+   annoying!) context shift during which we stop thinking about the comparison being
+   performed, and instead play "count the arguments", or, in the case of 
+   named/hash interpolations, "find the word". The Squeel syntax places
+   both sides of each comparison in proximity to one another, allowing us to
+   focus on what our code is doing.
+
+2. In the first example, we're starting off with Ruby, switching context to SQL,
+   and then back to Ruby, and while we spend time in SQL-land, we're stuck with
+   SQL syntax, whether or not it's the best way to express what we're trying to do.
+   With Squeel, we're writing Ruby from start to finish. And with Ruby syntax comes
+   flexibility to express the query in the way we see fit.
+
+### Predicate aliases
+
+That last bit is important. We can mix and match predicate methods with operators
+and take advantage of Ruby's operator precedence or parenthetical grouping to make
+our intentions more clear, on the first read-through. And if we don't like the
+way that the existing predications read, we can create our own aliases in a Squeel
+configure block:
+
+    Squeel.configure do |config|
+      config.alias_predicate :is_less_than, :lt
+    end
+    
+    Person.where{salary.is_less_than 50000}.to_sql
+    # => SELECT "people".* FROM "people"  WHERE "people"."salary" < 50000
+
+And while we're on the topic of helping you make your code more expressive...
+
+### Compound conditions
+
+Let's say you want to check if a Person has a name like one of several possibilities.
+
+    names = ['Ernie%', 'Joe%', 'Mary%']
+    Person.where('name LIKE ? OR name LIKE ? OR name LIKE ?', *names)
+
+But you're smart, and you know that you might want to check more or less than
+3 names, so you make your query flexible:
+
+    Person.where((['name LIKE ?'] * names.size).join(' OR '), *names)
+
+Yeah... that's readable, all right. How about:
+
+    Person.where{name.like_any names}
+    # => SELECT "people".* FROM "people"  
+         WHERE (("people"."name" LIKE 'Ernie%' OR "people"."name" LIKE 'Joe%' OR "people"."name" LIKE 'Mary%'))
+    
+I'm not sure about you, but I much prefer the latter. In short, you can add `_any` or
+`_all` to any predicate method, and it would do what you expect, when given an array of
+possibilities to compare against.
+
+### Subqueries
+
+You can supply an `ActiveRecord::Relation` as a value for a predicate in order to use
+a subquery. So, for example:
+
+    awesome_people = Person.where{awesome == true}
+    Article.where{author_id.in(awesome_people.select{id})}
+    # => SELECT "articles".* FROM "articles"  
+         WHERE "articles"."author_id" IN (SELECT "people"."id" FROM "people"  WHERE "people"."awesome" = 't')
+
+### Joins
+
+Squeel adds a couple of enhancements to joins. First, keypaths can be used as shorthand for
+nested association joins. Second, you can specify join types (inner and outer), and a class
+in the case of a polymorphic belongs_to relationship.
+
+    Person.joins{articles.outer}
+    => SELECT "people".* FROM "people"
+       LEFT OUTER JOIN "articles" ON "articles"."person_id" = "people"."id"
+    Note.joins{notable(Person).outer}
+    => SELECT "notes".* FROM "notes"
+       LEFT OUTER JOIN "people"
+         ON "people"."id" = "notes"."notable_id"
+         AND "notes"."notable_type" = 'Person'
+
+These can also be used inside keypaths:
+
+    Note.joins{notable(Person).articles}
+    => SELECT "notes".* FROM "notes"
+       INNER JOIN "people" ON "people"."id" = "notes"."notable_id"
+         AND "notes"."notable_type" = 'Person'
+       INNER JOIN "articles" ON "articles"."person_id" = "people"."id"
+       
+You can refer to these associations when constructing other parts of your query, and
+they'll be automatically mapped to the proper table or table alias This is most noticeable
+when using self-referential associations:
+
+    Person.joins{children.parent.children}.
+           where{
+             (children.name.like 'Ernie%') |
+             (children.parent.name.like 'Ernie%') |
+             (children.parent.children.name.like 'Ernie%')
+           }
+    => SELECT "people".* FROM "people" 
+       INNER JOIN "people" "children_people" ON "children_people"."parent_id" = "people"."id" 
+       INNER JOIN "people" "parents_people" ON "parents_people"."id" = "children_people"."parent_id" 
+       INNER JOIN "people" "children_people_2" ON "children_people_2"."parent_id" = "parents_people"."id" 
+       WHERE ((("children_people"."name" LIKE 'Ernie%' 
+             OR "parents_people"."name" LIKE 'Ernie%') 
+             OR "children_people_2"."name" LIKE 'Ernie%'))
+
+Keypaths were used here for clarity, but nested hashes would work just as well.
+
+### Functions
+
+You can call SQL functions just like you would call a method in Ruby...
+
+    Person.select{coalesce(name, '<no name given>')}
+    => SELECT coalesce("people"."name", '<no name given>') FROM "people"
+
+...and you can easily give it an alias:
+
+    person = Person.select{
+      coalesce(name, '<no name given>').as(name_with_default)
+    }.first
+    person.name_with_default # name or <no name given>, depending on data
+
+When you use a stub, symbol, or keypath inside a function call, it'll be interpreted relative to
+its place inside any nested associations:
+
+    Person.joins{articles}.group{articles.title}.having{{articles => {max(id) => id}}}
+    => SELECT "people".* FROM "people" 
+       INNER JOIN "articles" ON "articles"."person_id" = "people"."id" 
+       GROUP BY "articles"."title" 
+       HAVING max("articles"."id") = "articles"."id"
+       
+If you want to use an attribute from a different branch of the hierarchy, use an absolute
+keypath (~) as done here:
+
+    Person.joins{articles}.group{articles.title}.having{{articles => {max(~id) => id}}}
+    => SELECT "people".* FROM "people" 
+       INNER JOIN "articles" ON "articles"."person_id" = "people"."id" 
+       GROUP BY "articles"."title" 
+       HAVING max("people"."id") = "articles"."id"
+
+### SQL Operators
+
+You can use the standard mathematical operators (`+`, `-`, `*`, `/`) inside the Squeel DSL to
+specify operators in the resulting SQL, or the `op` method to specify another
+custom operator, such as the standard SQL concatenation operator, `||`:
+
+    p = Person.select{name.op('||', '-diddly').as(flanderized_name)}.first
+    p.flanderized_name
+    => "Aric Smith-diddly" 
+
+As you can see, just like functions, these operations can be given aliases.
+
+## Legacy compatibility
+
+While the Squeel DSL is the preferred way to access advanced query functionality, you can
+still enable methods on symbols to access ARel predications in a similar manner to MetaWhere:
+
+    Squeel.configure do |config|
+      config.load_core_extensions :symbol
+    end
+    
+    Person.joins(:articles => :comments).
+           where(:articles => {:comments => {:body.matches => 'Hello!'}})
+    SELECT "people".* FROM "people" 
+    INNER JOIN "articles" ON "articles"."person_id" = "people"."id" 
+    INNER JOIN "comments" ON "comments"."article_id" = "articles"."id" 
+    WHERE "comments"."body" LIKE 'Hello!'
+
+This should help to smooth over the transition to the new DSL.
+
+## Contributions
+
+If you'd like to support the continued development of Squeel, please consider
+[making a donation](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=N7QP5N3UB76ME).
+
+To support the project in other ways:
+
+* Use Squeel in your apps, and let me know if you encounter anything that's broken or missing.
+  A failing spec is awesome. A pull request is even better!
+* Spread the word on Twitter, Facebook, and elsewhere if Squeel's been useful to you. The more
+  people who are using the project, the quicker we can find and fix bugs!
+
+## Copyright
+
+Copyright &copy; 2011 [Ernie Miller](http://twitter.com/erniemiller)

data/Rakefile

@@ -0,0 +1,19 @@
+require 'bundler'
+require 'rspec/core/rake_task'
+
+Bundler::GemHelper.install_tasks
+
+RSpec::Core::RakeTask.new(:spec) do |rspec|
+  rspec.rspec_opts = ['--backtrace']
+end
+
+task :default => :spec
+
+desc "Open an irb session with Squeel and the sample data used in specs"
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require 'console'
+  ARGV.clear
+  IRB.start
+end

data/lib/core_ext/hash.rb

@@ -0,0 +1,13 @@
+require 'squeel/nodes/predicate_operators'
+
+# Hashes are "acceptable" by PredicateVisitor, so they
+# can be treated like nodes for the purposes of and/or/not
+# if you load these extensions.
+#
+# @example Load Hash extensions
+#   Squeel.configure do |config|
+#     config.load_core_extensions :hash
+#   end
+class Hash
+  include Squeel::Nodes::PredicateOperators
+end

data/lib/core_ext/symbol.rb

@@ -0,0 +1,39 @@
+require 'squeel/predicate_methods'
+require 'squeel/nodes/aliasing'
+
+# These extensions to Symbol are loaded optionally, mostly to provide
+# a small amount of backwards compatibility with MetaWhere.
+#
+# @example Load Symbol extensions
+#   Squeel.configure do |config|
+#     config.load_core_extensions :symbol
+#   end
+class Symbol
+  include Squeel::PredicateMethods
+  include Squeel::Nodes::Aliasing
+
+  def asc
+    Squeel::Nodes::Order.new self, 1
+  end
+
+  def desc
+    Squeel::Nodes::Order.new self, -1
+  end
+
+  def func(*args)
+    Squeel::Nodes::Function.new(self, args)
+  end
+
+  def inner
+    Squeel::Nodes::Join.new(self, Arel::InnerJoin)
+  end
+
+  def outer
+    Squeel::Nodes::Join.new(self, Arel::OuterJoin)
+  end
+
+  def of_class(klass)
+    Squeel::Nodes::Join.new(self, Arel::InnerJoin, klass)
+  end
+
+end

data/lib/squeel/adapters/active_record/3.0/association_preload.rb

@@ -0,0 +1,15 @@
+module Squeel
+  module Adapters
+    module ActiveRecord
+      module AssociationPreload
+
+        def preload_associations(records, associations, preload_options={})
+          records = Array.wrap(records).compact.uniq
+          return if records.empty?
+          super(records, Visitors::SymbolVisitor.new.accept(associations), preload_options)
+        end
+
+      end
+    end
+  end
+end

data/lib/squeel/adapters/active_record/3.0/compat.rb

@@ -0,0 +1,142 @@
+module Arel
+
+  class Table
+    alias :table_name :name
+
+    def [] name
+      ::Arel::Attribute.new self, name.to_sym
+    end
+  end
+
+  module Nodes
+    class Node
+      def not
+        Nodes::Not.new self
+      end
+    end
+
+    remove_const :And
+    class And < Arel::Nodes::Node
+      attr_reader :children
+
+      def initialize children, right = nil
+        unless Array === children
+          children = [children, right]
+        end
+        @children = children
+      end
+
+      def left
+        children.first
+      end
+
+      def right
+        children[1]
+      end
+    end
+
+    class NamedFunction < Arel::Nodes::Function
+      attr_accessor :name, :distinct
+
+      include Arel::Predications
+
+      def initialize name, expr, aliaz = nil
+        super(expr, aliaz)
+        @name = name
+        @distinct = false
+      end
+    end
+
+    class InfixOperation < Binary
+      include Arel::Expressions
+      include Arel::Predications
+
+      attr_reader :operator
+
+      def initialize operator, left, right
+        super(left, right)
+        @operator = operator
+      end
+    end
+
+    class Multiplication < InfixOperation
+      def initialize left, right
+        super(:*, left, right)
+      end
+    end
+
+    class Division < InfixOperation
+      def initialize left, right
+        super(:/, left, right)
+      end
+    end
+
+    class Addition < InfixOperation
+      def initialize left, right
+        super(:+, left, right)
+      end
+    end
+
+    class Subtraction < InfixOperation
+      def initialize left, right
+        super(:-, left, right)
+      end
+    end
+  end
+
+  module Visitors
+    class ToSql
+      def column_for attr
+        name    = attr.name.to_s
+        table   = attr.relation.table_name
+
+        column_cache[table][name]
+      end
+
+      def column_cache
+        @column_cache ||= Hash.new do |hash, key|
+          hash[key] = Hash[
+            @engine.connection.columns(key, "#{key} Columns").map do |c|
+              [c.name, c]
+            end
+          ]
+        end
+      end
+
+      def visit_Arel_Nodes_InfixOperation o
+        "#{visit o.left} #{o.operator} #{visit o.right}"
+      end
+
+      def visit_Arel_Nodes_NamedFunction o
+        "#{o.name}(#{o.distinct ? 'DISTINCT ' : ''}#{o.expressions.map { |x|
+          visit x
+        }.join(', ')})#{o.alias ? " AS #{visit o.alias}" : ''}"
+      end
+
+      def visit_Arel_Nodes_And o
+        o.children.map { |x| visit x }.join ' AND '
+      end
+
+      def visit_Arel_Nodes_Not o
+        "NOT (#{visit o.expr})"
+      end
+
+      def visit_Arel_Nodes_Values o
+        "VALUES (#{o.expressions.zip(o.columns).map { |value, attr|
+          if Nodes::SqlLiteral === value
+            visit_Arel_Nodes_SqlLiteral value
+          else
+            quote(value, attr && column_for(attr))
+          end
+        }.join ', '})"
+      end
+    end
+  end
+
+  module Predications
+    def as other
+      Nodes::As.new self, Nodes::SqlLiteral.new(other)
+    end
+  end
+
+end