squeel 0.5.0 → 0.5.5

data/README.rdoc

@@ -1,41 +1,117 @@
 =Squeel
 
-This is a complete rewrite of the library formerly called MetaWhere. It's Rails 3.1-only
-for now.
-
-It's not really suitable for actual use yet, but you're welcome to test it and send
-me feedback.
-
-==What's new?
-
-A lot.
-
-* Symbol and hash methods aren't loaded by default. To enable them, do this in
-  your Squeel.configure block: <tt>config.load_core_extensions :hash, :symbol</tt>
-* Speaking of, you can call Squeel.configure do |config| ... end and do
-  another bit of configuration, setting up your own aliases.
-  <tt>config.alias_predicate :new_name, :old_name</tt>
-* The preferred way to use the various enhancements is now by passing a block to
-  the relation method you're calling. For example:
-
-    Person.select{max(id).as(max_id)} # Call SQL functions
-    Person.where{(name == 'bob') & (salary == 100000)} # Compounds & and | work
-
-* Operators have changed. As before, operators starting with ! are only available
-  on Ruby 1.9. Upgrade, for the love of all that is good and holy.
-
-  * == - Equality
-  * != - Inequality
-  * ^ - Inequality, for those poor souls on 1.8.x
-  * >> - In, (mnemonic: value >> [1,2,3], the value is running INTO the array)
-  * << - Not in, (mnemonic: value << [1,2,3], the value is running OUT of the array)
-  * =~ - Matches (SQL LIKE)
-  * !~ - Not matches (SQL NOT LIKE) Again, only in Ruby 1.9
-  * > - Greater than
-  * >= - Greater than or equal to
-  * < - Less than
-  * <= - Less than or equal to
-  * [] - Alternative function syntax. Just use parentheses, not sure I'm gonna keep [].
-
-There's more -- have a read through the specs for a better idea of what you can do,
-or clone the repo, run <tt>bundle install</tt> and play around in <tt>rake console</tt>.
+Squeel is a (Rails 3.1-only for now) rewrite of MetaWhere. It's rapidly approaching
+a point where I could recommend it for daily use. Once it hits feature completion, I'll
+work on backporting to Rails 3.0.x. In the meantime, please feel free to clone this repo
+and give it a test drive using <tt>rake console</tt> and the models in the
+<tt>spec/support/schema.rb</tt> file.
+
+== 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 intitializer:
+
+  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
+
+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.
+
+=== Joins
+
+As you saw above, keypaths can be used as shorthand for joins. Additionally, you can
+specify join types (or join classes, in the case of polymorphic belongs_to joins):
+
+  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"
+
+=== 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
+
+=== Operators
+
+You can use the standard mathematical operators (+, -, *, /)inside the Squeel DSL to
+specify operators in the resulting SQL, or the <tt>op</tt> method to specify another
+custom operator, such as the standard SQL concatenation operator, ||:
+
+...more docs to come...

data/lib/squeel/adapters/active_record.rb

@@ -1,6 +1,23 @@
-require 'squeel/adapters/active_record/relation'
-require 'squeel/adapters/active_record/join_dependency'
-require 'squeel/adapters/active_record/join_association'
+case ActiveRecord::VERSION::STRING
+when /^3\.0\./
+  require 'squeel/adapters/active_record/3.0/compat'
+  require 'squeel/adapters/active_record/3.0/relation'
+  require 'squeel/adapters/active_record/3.0/join_dependency'
+  require 'squeel/adapters/active_record/3.0/join_association'
+  require 'squeel/adapters/active_record/3.0/association_preload'
+  require 'squeel/adapters/active_record/3.0/context'
 
-ActiveRecord::Relation.send :include, Squeel::Adapters::ActiveRecord::Relation
-ActiveRecord::Associations::JoinDependency.send :include, Squeel::Adapters::ActiveRecord::JoinDependency
+  ActiveRecord::Relation.send :include, Squeel::Adapters::ActiveRecord::Relation
+  ActiveRecord::Associations::ClassMethods::JoinDependency.send :include, Squeel::Adapters::ActiveRecord::JoinDependency
+  ActiveRecord::Base.extend Squeel::Adapters::ActiveRecord::AssociationPreload
+else
+  require 'squeel/adapters/active_record/relation'
+  require 'squeel/adapters/active_record/join_dependency'
+  require 'squeel/adapters/active_record/join_association'
+  require 'squeel/adapters/active_record/preloader'
+  require 'squeel/adapters/active_record/context'
+
+  ActiveRecord::Relation.send :include, Squeel::Adapters::ActiveRecord::Relation
+  ActiveRecord::Associations::JoinDependency.send :include, Squeel::Adapters::ActiveRecord::JoinDependency
+  ActiveRecord::Associations::Preloader.send :include, Squeel::Adapters::ActiveRecord::Preloader
+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,143 @@
+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
+
+      # This isn't really very cachey at all. Good enough for now.
+      def column_cache
+        @column_cache ||= Hash.new do |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

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

@@ -0,0 +1,67 @@
+require 'squeel/context'
+
+module Squeel
+  module Adapters
+    module ActiveRecord
+      class Context < ::Squeel::Context
+        # Because the AR::Associations namespace is insane
+        JoinBase = ::ActiveRecord::Associations::ClassMethods::JoinDependency::JoinBase
+
+        def initialize(object)
+          @base = object.join_base
+          super
+        end
+
+        def find(object, parent = @base)
+          if JoinBase === parent
+            object = object.to_sym if String === object
+            case object
+            when Symbol, Nodes::Stub
+              @object.join_associations.detect { |j|
+                j.reflection.name == object.to_sym && j.parent == parent
+              }
+            when Nodes::Join
+              @object.join_associations.detect { |j|
+                j.reflection.name == object.name && j.parent == parent &&
+                (object.polymorphic? ? j.reflection.klass == object.klass : true)
+              }
+            else
+              @object.join_associations.detect { |j|
+                j.reflection == object && j.parent == parent
+              }
+            end
+          end
+        end
+
+        def traverse(keypath, parent = @base, include_endpoint = false)
+          parent = @base if keypath.absolute?
+          keypath.path.each do |key|
+            parent = find(key, parent) || key
+          end
+          parent = find(keypath.endpoint, parent) if include_endpoint
+
+          parent
+        end
+
+        def sanitize_sql(conditions, parent)
+          parent.active_record.send(:sanitize_sql, conditions, parent.aliased_table_name)
+        end
+
+        private
+
+        def get_table(object)
+          if [Symbol, Nodes::Stub].include?(object.class)
+            Arel::Table.new(object.to_sym, :engine => @engine)
+          elsif Nodes::Join === object
+            object.klass ? object.klass.arel_table : Arel::Table.new(object.name, :engine => @engine)
+          elsif object.respond_to?(:aliased_table_name)
+            Arel::Table.new(object.table_name, :as => object.aliased_table_name, :engine => @engine)
+          else
+            raise ArgumentError, "Unable to get table for #{object}"
+          end
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+require 'active_record'
+
+module Squeel
+  module Adapters
+    module ActiveRecord
+      class JoinAssociation < ::ActiveRecord::Associations::ClassMethods::JoinDependency::JoinAssociation
+
+        def initialize(reflection, join_dependency, parent = nil, polymorphic_class = nil)
+          if polymorphic_class && ::ActiveRecord::Base > polymorphic_class
+            swapping_reflection_klass(reflection, polymorphic_class) do |reflection|
+              super(reflection, join_dependency, parent)
+            end
+          else
+            super(reflection, join_dependency, parent)
+          end
+        end
+
+        def swapping_reflection_klass(reflection, klass)
+          reflection = reflection.clone
+          original_polymorphic = reflection.options.delete(:polymorphic)
+          reflection.instance_variable_set(:@klass, klass)
+          yield reflection
+        ensure
+          reflection.options[:polymorphic] = original_polymorphic
+        end
+
+        def ==(other)
+          super && active_record == other.active_record
+        end
+
+        def association_join
+          return @join if @Join
+
+          @join = super
+
+          if reflection.macro == :belongs_to && reflection.options[:polymorphic]
+            aliased_table = Arel::Table.new(table_name, :as      => @aliased_table_name,
+                                                        :engine  => arel_engine,
+                                                        :columns => klass.columns)
+
+            parent_table = Arel::Table.new(parent.table_name, :as      => parent.aliased_table_name,
+                                                              :engine  => arel_engine,
+                                                              :columns => parent.active_record.columns)
+
+            @join << parent_table[reflection.options[:foreign_type]].eq(reflection.klass.name)
+          end
+
+          @join
+        end
+
+      end
+    end
+  end
+end