squeel 0.5.5 → 0.6.0

data/lib/squeel/nodes/join.rb

@@ -1,40 +1,72 @@
 module Squeel
   module Nodes
+    # A node representing a joined association
     class Join
-      attr_reader :name, :type, :klass
+      undef_method :id if method_defined?(:id)
 
+      # @return [Symbol] The join's association name
+      attr_reader :_name
+
+      # @return [Arel::InnerJoin, Arel::OuterJoin] The ARel join type
+      attr_reader :_type
+
+      # @return [Class] The polymorphic belongs_to join class
+      # @return [NilClass] If the join is not a polymorphic belongs_to join
+      attr_reader :_klass
+
+      # Create a new Join node
+      # @param [Symbol] name The association name
+      # @param [Arel::InnerJoin, Arel::OuterJoin] type The ARel join class
+      # @param [Class, String, Symbol] klass The polymorphic belongs_to class or class name
       def initialize(name, type = Arel::InnerJoin, klass = nil)
-        @name, @type = name, type
-        @klass = convert_to_class(klass) if klass
+        @_name, @_type = name, type
+        @_klass = convert_to_class(klass) if klass
       end
 
+      # Set the join type to an inner join
+      # @return [Join] The join, with an updated join type.
       def inner
-        @type = Arel::InnerJoin
+        @_type = Arel::InnerJoin
         self
       end
 
+      # Set the join type to an outer join
+      # @return [Join] The join, with an updated join type.
       def outer
-        @type = Arel::OuterJoin
+        @_type = Arel::OuterJoin
         self
       end
 
-      def klass=(class_or_class_name)
-        @klass = convert_to_class(class_or_class_name)
+      # Set the polymorphic belongs_to class
+      # @param [Class, String, Symbol] class_or_class_name The polymorphic belongs_to class or class name
+      # @return [Class] The class that's just been set
+      def _klass=(class_or_class_name)
+        @_klass = convert_to_class(class_or_class_name)
       end
 
+      # Returns a true value (the class itself) if a polymorphic belongs_to class has been set
+      # @return [NilClass, Class] The class, if present.
       def polymorphic?
-        @klass
+        @_klass
       end
 
+      # Compare with other objects
       def eql?(other)
         self.class == other.class &&
-        self.name  == other.name &&
-        self.type == other.type &&
-        self.klass == other.klass
+        self._name  == other._name &&
+        self._type == other._type &&
+        self._klass == other._klass
       end
-
       alias :== :eql?
 
+      # Ensures that a Join can be used as the base of a new KeyPath
+      # @overload node_name
+      #   Creates a new KeyPath with this Join as the base and the method_name as the endpoint
+      #   @return [KeyPath] The new keypath
+      # @overload node_name(klass)
+      #   Creates a new KeyPath with this Join as the base and a polymorphic belongs_to join as the endpoint
+      #   @param [Class] klass The polymorphic class for the join
+      #   @return [KeyPath] The new keypath
       def method_missing(method_id, *args)
         super if method_id == :to_ary
         if (args.size == 1) && (Class === args[0])
@@ -44,15 +76,27 @@ module Squeel
         end
       end
 
+      # Return a KeyPath containing only this Join, but flagged as absolute.
+      # This helps Joins behave more like a KeyPath, as anyone using the Squeel
+      # DSL is likely to think of them as such.
+      # @return [KeyPath] An absolute KeyPath, containing only this Join
+      def ~
+        KeyPath.new [], self, true
+      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
 
       private
 
+      # Convert the given value into a class.
+      # @param [Class, String, Symbol] value The value to be converted
+      # @return [Class] The class after conversion
       def convert_to_class(value)
         case value
         when String, Symbol

data/lib/squeel/nodes/key_path.rb

@@ -3,12 +3,25 @@ require 'squeel/nodes/predicate_operators'
 
 module Squeel
   module Nodes
+    # A node that stores a path of keys (of Symbol, Stub, or Join values) and
+    # an endpoint. Used similarly to a nested hash.
     class KeyPath
       include PredicateOperators
       include Operators
 
-      attr_reader :path, :endpoint
+      undef_method :id if method_defined?(:id)
 
+      # @return [Array<Symbol, Stub, Join>] The path
+      attr_reader :path
+
+      # @return The endpoint, either another key as in the path, or a predicate, function, etc.
+      attr_reader :endpoint
+
+      # Create a new KeyPath.
+      # @param [Array, Object] path The intial path. Will be converted to an array if it isn't already.
+      # @param endpoint the endpoint of the KeyPath
+      # @param [Boolean] absolute If the KeyPath should start from the base
+      #   or remain relative to whatever location it's found.
       def initialize(path, endpoint, absolute = false)
         @path, @endpoint = path, endpoint
         @path = [@path] unless Array === @path
@@ -16,10 +29,14 @@ module Squeel
         @absolute = absolute
       end
 
+      # Whether or not the KeyPath should be interpreted relative to its current location
+      #   (if nested in a Hash, for instance) or as though it's at the base.
+      # @return [Boolean] The flag's value
       def absolute?
         @absolute
       end
 
+      # Object comparison
       def eql?(other)
         self.class == other.class &&
         self.path == other.path &&
@@ -27,38 +44,72 @@ module Squeel
         self.absolute? == other.absolute?
       end
 
+      # Allow KeyPath to function like its endpoint, in the case where its endpoint
+      # responds to |
+      # @param other The right hand side of the operation
+      # @return [Or] An Or node with the KeyPath on the left side and the other object on the right.
       def |(other)
         endpoint.respond_to?(:|) ? super : no_method_error(:|)
       end
 
+      # Allow KeyPath to function like its endpoint, in the case where its endpoint
+      # responds to &
+      # @param other The right hand side of the operation
+      # @return [And] An And node with the KeyPath on the left side and the other object on the right.
       def &(other)
         endpoint.respond_to?(:&) ? super : no_method_error(:&)
       end
 
+      # Allow KeyPath to function like its endpoint, in the case where its endpoint
+      # responds to -@
+      # @return [Not] A not node with the KeyPath as its expression
       def -@
         endpoint.respond_to?(:-@) ? super : no_method_error(:-@)
       end
 
+      # Allow KeyPath to function like its endpoint, in the case where its endpoint
+      # responds to +
+      # @param other The right hand side of the operation
+      # @return [Operation] An operation (with operator +) with the KeyPath on its left and the other object on the right.
       def +(other)
         endpoint.respond_to?(:+) ? super : no_method_error(:+)
       end
 
+      # Allow KeyPath to function like its endpoint, in the case where its endpoint
+      # responds to -
+      # @param other The right hand side of the operation
+      # @return [Operation] An operation (with operator -) with the KeyPath on its left and the other object on the right.
       def -(other)
         endpoint.respond_to?(:-) ? super : no_method_error(:-)
       end
 
+      # Allow KeyPath to function like its endpoint, in the case where its endpoint
+      # responds to *
+      # @param other The right hand side of the operation
+      # @return [Operation] An operation (with operator *) with the KeyPath on its left and the other object on the right.
       def *(other)
         endpoint.respond_to?(:*) ? super : no_method_error(:*)
       end
 
+      # Allow KeyPath to function like its endpoint, in the case where its endpoint
+      # responds to /
+      # @param other The right hand side of the operation
+      # @return [Operation] An operation (with operator /) with the KeyPath on its left and the other object on the right.
       def /(other)
         endpoint.respond_to?(:/) ? super : no_method_error(:/)
       end
 
+      # Allow KeyPath to function like its endpoint, in the case where its endpoint
+      # responds to #op
+      # @param [String, Symbol] operator The custom operator
+      # @param other The right hand side of the operation
+      # @return [Operation] An operation with the given custom operator, the KeyPath on its left and the other object on the right.
       def op(operator, other)
         endpoint.respond_to?(:op) ? super : no_method_error(:/)
       end
 
+      # Set the absolute flag on this KeyPath
+      # @return [KeyPath] This keypath, with its absolute flag set to true
       def ~
         @absolute = true
         self
@@ -69,18 +120,26 @@ module Squeel
         undef_method operator
       end
 
+      # For use with equality tests
       def hash
         [self.class, endpoint, *path].hash
       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
 
+      # Delegate % to the KeyPath's endpoint, with a bit of special logic for stubs or functions.
+      # @param val The value to be supplied to the created/existing predicate
+      # @return [KeyPath] This KeyPath, with a predicate endpoint containing the given value
       def %(val)
         case endpoint
         when Stub, Function
-          eq(val)
+          Array === val ? self.in(val) : self.eq(val)
           self
         else
           endpoint % val
@@ -88,14 +147,19 @@ module Squeel
         end
       end
 
+      # @return [Array] The KeyPath's path, including its endpoint, as a single array.
       def path_with_endpoint
         path + [endpoint]
       end
 
+      # Impleneted (and aliased to :to_str) to play nicely with ActiveRecord grouped calculations
       def to_s
         path.map(&:to_s).join('.') << ".#{endpoint}"
       end
+      alias :to_str :to_s
 
+      # Appends to the KeyPath or delegates to the endpoint, as appropriate
+      # @return [KeyPath] The updated KeyPath
       def method_missing(method_id, *args)
         super if method_id == :to_ary
         if endpoint.respond_to? method_id
@@ -118,6 +182,8 @@ module Squeel
 
       private
 
+      # Raises a NoMethodError manually, bypassing #method_missing.
+      # Used by special-case operator overrides.
       def no_method_error(method_id)
         raise NoMethodError, "undefined method `#{method_id}' for #{self}:#{self.class}"
       end

data/lib/squeel/nodes/nary.rb

@@ -1,33 +1,43 @@
 module Squeel
   module Nodes
+    # A node containing multiple children. Just the And node for now.
     class Nary
       include PredicateOperators
 
+      # @return [Array] This node's children
       attr_reader :children
 
+      # Creates a new Nary node with the given array of children
+      # @param [Array] children The node's children
       def initialize(children)
         raise ArgumentError, '#{self.class} requires an array' unless Array === children
         # We don't dup here, as incoming arrays should be created by the
-        # Operators#& method on other nodes. If you're creating And nodes
+        # PredicateOperators#& method on other nodes. If you're creating And nodes
         # manually, by sure that they're new arays.
         @children = children
       end
 
+      # Add a new child to the node's children
+      # @param other A new child node
+      # @return [Nary] This node, with its updated children.
       def &(other)
         @children << other
         self
       end
 
+      # Append a new Not node to this node's children
+      # @param other A new child node
+      # @return [Nary] This node, with its new, negated child
       def -(other)
         @children << Not.new(other)
         self
       end
 
+      # Object comparison
       def eql?(other)
         self.class     == other.class &&
         self.children  == other.children
       end
-
       alias :== :eql?
 
     end

data/lib/squeel/nodes/not.rb

@@ -2,6 +2,7 @@ require 'squeel/nodes/unary'
 
 module Squeel
   module Nodes
+    # A node that represents SQL NOT, and will result in same when visited
     class Not < Unary
     end
   end

data/lib/squeel/nodes/operation.rb

@@ -2,18 +2,27 @@ require 'squeel/nodes/function'
 
 module Squeel
   module Nodes
+    # An Operation is basically a function with its operands limited, and rearranged,
+    # so Squeel implements it as such.
     class Operation < Function
 
+      # Create a new Operation with the given operator and left and right operands
+      # @param left The left operand
+      # @param [String, Symbol] operator The operator
+      # @param right The right operand
       def initialize(left, operator, right)
         super(operator, [left, right])
       end
 
+      # An operation should probably call its "function" name an "operator", shouldn't it?
       alias :operator :name
 
+      # @return The left operand
       def left
         args[0]
       end
 
+      # @return The right operand
       def right
         args[1]
       end

data/lib/squeel/nodes/operators.rb

@@ -1,23 +1,39 @@
 module Squeel
   module Nodes
+    # Module containing Operation factory methods for inclusion in Squeel nodes
     module Operators
 
+      # Factory for a new addition operation with this node as its left operand.
+      # @param value The right operand
+      # @return [Operation] The new addition operation
       def +(value)
         Operation.new(self, :+, value)
       end
 
+      # Factory for a new subtraction operation with this node as its left operand.
+      # @param value The right operand
+      # @return [Operation] The new subtraction operation
       def -(value)
         Operation.new(self, :-, value)
       end
 
+      # Factory for a new multiplication operation with this node as its left operand.
+      # @param value The right operand
+      # @return [Operation] The new multiplication operation
       def *(value)
         Operation.new(self, :*, value)
       end
 
+      # Factory for a new division operation with this node as its left operand.
+      # @param value The right operand
+      # @return [Operation] The new division operation
       def /(value)
         Operation.new(self, :/, value)
       end
 
+      # Factory for a new custom operation with this node as its left operand.
+      # @param value The right operand
+      # @return [Operation] The new operation
       def op(operator, value)
         Operation.new(self, operator, value)
       end

data/lib/squeel/nodes/or.rb

@@ -2,6 +2,7 @@ require 'squeel/nodes/binary'
 
 module Squeel
   module Nodes
+    # A node representing an SQL OR, which will result in same when visited.
     class Or < Binary
     end
   end

data/lib/squeel/nodes/order.rb

@@ -1,31 +1,49 @@
 module Squeel
   module Nodes
+    # A node that represents SQL orderings, such as "people.id DESC"
     class Order
-      attr_reader :expr, :direction
+      # @return The expression being ordered on. Might be an attribute, function, or operation
+      attr_reader :expr
 
+      # @return [Fixnum] 1 or -1, depending on ascending or descending direction, respectively
+      attr_reader :direction
+
+      # Create a new Order node with the given expression and direction
+      # @param expr The expression to order on
+      # @param [Fixnum] direction 1 or -1, depending on the desired sort direction
       def initialize(expr, direction = 1)
         raise ArgumentError, "Direction #{direction} is not valid. Must be -1 or 1." unless [-1,1].include? direction
         @expr, @direction = expr, direction
       end
 
+      # Set this node's direction to ascending
+      # @return [Order] This order node with an ascending direction
       def asc
         @direction = 1
         self
       end
 
+      # Set this node's direction to descending
+      # @return [Order] This order node with a descending direction
       def desc
         @direction = -1
         self
       end
 
+      # Whether or not this node represents an ascending order
+      # @return [Boolean] True if the order is ascending
       def ascending?
         @direction == 1
       end
 
+      # Whether or not this node represents a descending order
+      # @return [Boolean] True if the order is descending
       def descending?
         @direction == -1
       end
 
+      # Reverse the node's direction
+      # @return [Order] This node with a reversed direction
       def reverse!
         @direction = - @direction
         self