squeel 0.5.5 → 0.6.0

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

@@ -93,10 +93,9 @@ module Arel
         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[
+          hash[key] = Hash[
             @engine.connection.columns(key, "#{key} Columns").map do |c|
               [c.name, c]
             end

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

@@ -8,8 +8,11 @@ module Squeel
         JoinBase = ::ActiveRecord::Associations::ClassMethods::JoinDependency::JoinBase
 
         def initialize(object)
-          @base = object.join_base
           super
+          @base = object.join_base
+          @engine = @base.arel_engine
+          @arel_visitor = Arel::Visitors.visitor_for @engine
+          @default_table = Arel::Table.new(@base.table_name, :as => @base.aliased_table_name, :engine => @engine)
         end
 
         def find(object, parent = @base)
@@ -23,7 +26,7 @@ module Squeel
             when Nodes::Join
               @object.join_associations.detect { |j|
                 j.reflection.name == object.name && j.parent == parent &&
-                (object.polymorphic? ? j.reflection.klass == object.klass : true)
+                (object.polymorphic? ? j.reflection.klass == object._klass : true)
               }
             else
               @object.join_associations.detect { |j|
@@ -43,17 +46,13 @@ module Squeel
           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)
+            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

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

@@ -37,13 +37,13 @@ module Squeel
           case associations
           when Nodes::Join
             parent ||= @joins.last
-            reflection = parent.reflections[associations.name] or
-              raise ::ActiveRecord::ConfigurationError, "Association named '#{ associations.name }' was not found; perhaps you misspelled it?"
+            reflection = parent.reflections[associations._name] or
+              raise ::ActiveRecord::ConfigurationError, "Association named '#{ associations._name }' was not found; perhaps you misspelled it?"
 
-            unless join_association = find_join_association_respecting_polymorphism(reflection, parent, associations.klass)
+            unless join_association = find_join_association_respecting_polymorphism(reflection, parent, associations._klass)
               @reflections << reflection
-              join_association = build_join_association_respecting_polymorphism(reflection, parent, associations.klass)
-              join_association.join_type = associations.type
+              join_association = build_join_association_respecting_polymorphism(reflection, parent, associations._klass)
+              join_association.join_type = associations._type
               @joins << join_association
               cache_joined_association(join_association)
             end

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

@@ -8,8 +8,11 @@ module Squeel
         JoinPart = ::ActiveRecord::Associations::JoinDependency::JoinPart
 
         def initialize(object)
-          @base = object.join_base
           super
+          @base = object.join_base
+          @engine = @base.arel_engine
+          @arel_visitor = Arel::Visitors.visitor_for @engine
+          @default_table = Arel::Table.new(@base.table_name, :as => @base.aliased_table_name, :engine => @engine)
         end
 
         def find(object, parent = @base)
@@ -23,7 +26,7 @@ module Squeel
             when Nodes::Join
               @object.join_associations.detect { |j|
                 j.reflection.name == object.name && j.parent == parent &&
-                (object.polymorphic? ? j.reflection.klass == object.klass : true)
+                (object.polymorphic? ? j.reflection.klass == object._klass : true)
               }
             else
               @object.join_associations.detect { |j|
@@ -43,17 +46,13 @@ module Squeel
           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)
+            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

data/lib/squeel/adapters/active_record/join_dependency.rb

@@ -36,13 +36,13 @@ module Squeel
           case associations
           when Nodes::Join
             parent ||= join_parts.last
-            reflection = parent.reflections[associations.name] or
-              raise ::ActiveRecord::ConfigurationError, "Association named '#{ associations.name }' was not found; perhaps you misspelled it?"
+            reflection = parent.reflections[associations._name] or
+              raise ::ActiveRecord::ConfigurationError, "Association named '#{ associations._name }' was not found; perhaps you misspelled it?"
 
-            unless join_association = find_join_association_respecting_polymorphism(reflection, parent, associations.klass)
+            unless join_association = find_join_association_respecting_polymorphism(reflection, parent, associations._klass)
               @reflections << reflection
-              join_association = build_join_association_respecting_polymorphism(reflection, parent, associations.klass)
-              join_association.join_type = associations.type
+              join_association = build_join_association_respecting_polymorphism(reflection, parent, associations._klass)
+              join_association.join_type = associations._type
               @join_parts << join_association
               cache_joined_association(join_association)
             end

data/lib/squeel/configuration.rb

@@ -2,18 +2,47 @@ require 'squeel/constants'
 require 'squeel/predicate_methods'
 
 module Squeel
+  # The Squeel configuration module. The Squeel module extends this to provide its
+  # configuration capability.
   module Configuration
 
+    # Start a Squeel configuration block in an initializer.
+    #
+    # @yield [config] A configuration block
+    #
+    # @example Load hash and symbol extensions
+    #   Squeel.configure do |config|
+    #     config.load_core_extensions :hash, :symbol
+    #   end
+    #
+    # @example Alias a predicate
+    #   Squeel.configure do |config|
+    #     config.alias_ptedicate :is_less_than, :lt
+    #   end
     def configure
       yield self
     end
 
+    # Load core extensions for Hash, Symbol, or both
+    #
+    # @overload load_core_extensions(sym)
+    #   Load a single extension
+    #   @param [Symbol] sym :hash or :symbol
+    # @overload load_core_extensions(sym1, sym2)
+    #   Load both extensions
+    #   @param [Symbol] sym1 :hash or :symbol
+    #   @param [Symbol] sym2 :hash or :symbol
     def load_core_extensions(*exts)
       exts.each do |ext|
         require "core_ext/#{ext}"
       end
     end
 
+    # Create an alias to an existing predication method. The _any/_all variations will
+    # be created automatically.
+    # @param [Symbol] new_name The alias name
+    # @param [Symbol] existing_name The existing predicate name
+    # @raise [ArgumentError] The existing name is an _any/_all variation, and not the original predicate name
     def alias_predicate(new_name, existing_name)
       raise ArgumentError, 'the existing name should be the base name, not an _any/_all variation' if existing_name.to_s =~ /(_any|_all)$/
       ['', '_any', '_all'].each do |suffix|

data/lib/squeel/constants.rb

@@ -1,4 +1,5 @@
 module Squeel
+  # Defines the default list of ARel predicates and predicate aliases
   module Constants
     PREDICATES = [
        :eq, :eq_any, :eq_all,

data/lib/squeel/context.rb

@@ -1,35 +1,64 @@
 require 'arel'
 
 module Squeel
+  # @abstract Subclass and implement {#traverse}, #{find} and {#get_table}
+  #   to create a Context that supports a given ORM.
   class Context
     attr_reader :base, :engine, :arel_visitor
 
+    # The Squeel context expects some kind of context object that is
+    # representative of the current joins in a query in order to return
+    # appropriate tables. Again, in the case of an ActiveRecord context,
+    # this will be a JoinDependency. Subclasses are expected to set the
+    # <tt>@base</tt>, <tt>@engine</tt>, and <tt>@arel_visitor</tt>
+    # instance variables to appropriate values for use in their implementations
+    # of other required methods.
+    #
+    # @param object The object the context will use for contextualization
     def initialize(object)
       @object = object
-      @engine = @base.arel_engine
-      @arel_visitor = Arel::Visitors.visitor_for @engine
-      @default_table = Arel::Table.new(@base.table_name, :as => @base.aliased_table_name, :engine => @engine)
       @tables = Hash.new {|hash, key| hash[key] = get_table(key)}
     end
 
+    # This method should find a given object inside the context.
+    #
+    # @param object The object to find
+    # @param parent The parent object, if applicable
+    # @return a valid "parent" or contextualizable object
     def find(object, parent = @base)
       raise NotImplementedError, "Subclasses must implement public method find"
     end
 
+    # This method should traverse a keypath and return an object for use
+    # in future calls to #traverse, #find, or #contextualize.
+    #
+    # @param [Nodes::KeyPath] keypath The keypath to traverse
+    # @param parent The parent object from which traversal should start.
+    # @param [Boolean] include_endpoint Whether or not the KeyPath's
+    #   endpoint should be treated as a traversable key
+    # @return a valid "parent" or contextualizable object
     def traverse(keypath, parent = @base, include_endpoint = false)
       raise NotImplementedError, "Subclasses must implement public method traverse"
     end
 
+    # This method, as implemented, just makes use of the table cache, which will
+    # call get_table, where the real work of getting the ARel Table occurs.
+    #
+    # @param object A contextualizable object (this will depend on the subclass's implementation)
+    # @return [Arel::Table] A table corresponding to the object param
     def contextualize(object)
       @tables[object]
     end
 
-    def sanitize_sql(conditions, parent)
-      raise NotImplementedError, "Subclasses must implement public method sanitize_sql"
-    end
-
     private
 
+    # Returns an Arel::Table that's appropriate for the object it's been sent.
+    # What's "appropriate"? Well, that's up to the implementation to decide, but
+    # it should probably generate a table that is least likely to result in invalid
+    # SQL.
+    #
+    # @param object A contextualizable object (this will depend on the subclass's implementation)
+    # @return [Arel::Table] A table corresponding to the object param.
     def get_table(object)
       raise NotImplementedError, "Subclasses must implement private method get_table"
     end

data/lib/squeel/dsl.rb

@@ -1,6 +1,9 @@
 module Squeel
+  # Interprets DSL blocks, generating various Squeel nodes as appropriate.
   class DSL
 
+    # We're creating a BlankSlate-type class here, since we want most
+    # method calls to fall through to method_missing.
     Squeel.evil_things do
       (instance_methods + private_instance_methods).each do |method|
         unless method.to_s =~ /^(__|instance_eval)/
@@ -9,15 +12,67 @@ module Squeel
       end
     end
 
+    # Called from an adapter, not directly.
+    # Evaluates a block of Squeel DSL code.
+    #
+    # @example A DSL block that uses instance_eval
+    #   Post.where{title == 'Hello world!'}
+    #
+    # @example A DSL block with access to methods from the closure
+    #   Post.where{|dsl| dsl.title == local_method(local_var)}
+    #
+    # @yield [dsl] A block of Squeel DSL code, with an optional argument if
+    #   access to closure methods is desired.
+    # @return The results of the interpreted DSL code.
     def self.eval(&block)
       if block.arity > 0
-        yield self.new
+        yield self.new(block.binding)
       else
-        self.new.instance_eval(&block)
+        self.new(block.binding).instance_eval(&block)
       end
     end
 
+    private
+
+    # This isn't normally called directly, but via DSL.eval, which will
+    # pass the block's binding to the new instance, for use with #my.
+    #
+    # @param [Binding] The block's binding.
+    def initialize(caller_binding)
+      @caller = caller_binding.eval 'self'
+    end
+
+    # If you really need to get at an instance variable or method inside
+    # a DSL block, this method will let you do it. It passes a block back
+    # to the DSL's caller for instance_eval.
+    #
+    # It's also pretty evil, so I hope you enjoy using it while I'm burning in
+    # programmer hell.
+    #
+    # @param &block A block to instance_eval against the DSL's caller.
+    # @return
+    def my(&block)
+      @caller.instance_eval &block
+    end
+
+    # Node generation inside DSL blocks.
+    #
+    # @overload node_name
+    #   Creates a Stub. Method calls chained from this Stub will determine
+    #   what type of node we eventually end up with.
+    #   @return [Nodes::Stub] A stub with the name of the method
+    # @overload node_name(klass)
+    #   Creates a Join with a polymorphic class matching the given parameter
+    #   @param [Class] klass The polymorphic class of the join node
+    #   @return [Nodes::Join] A join node with the name of the method and the given class
+    # @overload node_name(first_arg, *other_args)
+    #   Creates a Function with the given arguments becoming the function's arguments
+    #   @param first_arg The first argument
+    #   @param *other_args Optional additional arguments
+    #   @return [Nodes::Function] A function node for the given method name with the given arguments
     def method_missing(method_id, *args)
+      super if method_id == :to_ary
+
       if args.empty?
         Nodes::Stub.new method_id
       elsif (args.size == 1) && (Class === args[0])

data/lib/squeel/nodes.rb

@@ -1,3 +1,9 @@
+module Squeel
+  # Namespace for the nodes created by Squeel::DSL, and
+  # evaluated by Squeel::Visitors classes
+  module Nodes
+  end
+end
 require 'squeel/nodes/stub'
 require 'squeel/nodes/key_path'
 require 'squeel/nodes/predicate'

data/lib/squeel/nodes/and.rb

@@ -2,6 +2,7 @@ require 'squeel/nodes/nary'
 
 module Squeel
   module Nodes
+    # A grouping of nodes that will be converted to an Arel::Nodes::And upon visitation.
     class And < Nary
     end
   end

data/lib/squeel/nodes/binary.rb

@@ -2,22 +2,31 @@ require 'squeel/nodes/predicate_operators'
 
 module Squeel
   module Nodes
+    # A node that represents an operation with two operands.
     class Binary
+
       include PredicateOperators
 
-      attr_reader :left, :right
+      # The left operand
+      attr_reader :left
+
+      # The right operand
+      attr_reader :right
 
+      # @param left The left operand
+      # @param right The right operand
       def initialize(left, right)
         @left, @right = left, right
       end
 
+      # Comparison with other nodes
       def eql?(other)
         self.class == other.class &&
         self.left  == other.left &&
         self.right == other.right
       end
-
       alias :== :eql?
+
     end
   end
 end

data/lib/squeel/nodes/function.rb

@@ -2,26 +2,49 @@ require 'squeel/predicate_methods'
 
 module Squeel
   module Nodes
+    # A node that represents an SQL function call
     class Function
 
       include PredicateMethods
       include Operators
 
-      attr_reader :name, :args, :alias
-
+      alias :== :eq
+      alias :'^' :not_eq
+      alias :'!=' :not_eq if respond_to?(:'!=')
+      alias :>> :in
+      alias :<< :not_in
+      alias :=~ :matches
+      alias :'!~' :does_not_match if respond_to?(:'!~')
+      alias :> :gt
+      alias :>= :gteq
+      alias :< :lt
+      alias :<= :lteq
+
+      # @return [Symbol] The name of the SQL function to be called
+      attr_reader :name
+
+      # @return [Array] The arguments to be passed to the SQL function
+      attr_reader :args
+
+      # @return [String] The SQL function's alias
+      # @return [NilClass] If no alias
+      attr_reader :alias
+
+      # Create a node representing an SQL Function with the given name and arguments
+      # @param [Symbol] name The function name
+      # @param [Array] args The array of arguments to pass to the function.
       def initialize(name, args)
         @name, @args = name, args
       end
 
+      # Set an alias for the function
+      # @param [String, Symbol] The alias name
+      # @return [Function] This function with the new alias value.
       def as(alias_name)
         @alias = alias_name.to_s
         self
       end
 
-      def ==(value)
-        Predicate.new self, :eq, value
-      end
-
       def asc
         Order.new self, 1
       end
@@ -30,51 +53,10 @@ module Squeel
         Order.new self, -1
       end
 
-      # Won't work on Ruby 1.8.x so need to do this conditionally
-      define_method('!=') do |value|
-        Predicate.new(self, :not_eq, value)
-      end if respond_to?('!=')
-
-      def ^(value)
-        Predicate.new self, :not_eq, value
-      end
-
-      def >>(value)
-        Predicate.new self, :in, value
-      end
-
-      def <<(value)
-        Predicate.new self, :not_in, value
-      end
-
-      def =~(value)
-        Predicate.new self, :matches, value
-      end
-
-      # Won't work on Ruby 1.8.x so need to do this conditionally
-      define_method('!~') do |value|
-        Predicate.new(self, :does_not_match, value)
-      end if respond_to?('!~')
-
-      def >(value)
-        Predicate.new self, :gt, value
-      end
-
-      def >=(value)
-        Predicate.new self, :gteq, value
-      end
-
-      def <(value)
-        Predicate.new self, :lt, value
-      end
-
-      def <=(value)
-        Predicate.new self, :lteq, value
-      end
-
       # expand_hash_conditions_for_aggregates assumes our hash keys can be
       # converted to symbols, so this has to be implemented, but it doesn't
       # really have to do anything useful.
+      # @return [NilClass] Just to avoid bombing out on expand_hash_conditions_for_aggregates
       def to_sym
         nil
       end