squeel 0.5.5 → 0.6.0

data/lib/squeel/nodes/predicate.rb

@@ -3,35 +3,56 @@ require 'squeel/nodes/predicate_operators'
 
 module Squeel
   module Nodes
+    # This node is essentially a container that will result in ARel predicate nodes
+    # once visited. It stores the expression (normally an attribute name, function, or
+    # operation), the ARel predicate method name, and a value. these are then interpreted
+    # when visited by the PredicateVisitor to generate a condition against the appropriate
+    # columns.
     class Predicate
 
-      include PredicateMethods
       include PredicateOperators
 
+      # @return The right-hand value being considered in this predicate.
       attr_accessor :value
-      attr_reader :expr, :method_name
 
+      # @return The expression on the left side of this predicate.
+      attr_reader :expr
+
+      # @return [Symbol] The ARel "predication" method name, such as eq, matches, etc.
+      attr_reader :method_name
+
+      # Create a new Predicate node with the given expression, method name, and value
+      # @param expr The expression for the left hand side of the predicate.
+      # @param [Symbol] method_name The ARel predication method
+      # @param value An optional value. If not given, one will need to be supplied
+      #   before the node can be visited properly.
       def initialize(expr, method_name = :eq, value = :__undefined__)
         @expr, @method_name, @value = expr, method_name, value
       end
 
+      # Object comparison
       def eql?(other)
         self.class.eql?(other.class) &&
         self.expr.eql?(other.expr) &&
         self.method_name.eql?(other.method_name) &&
         self.value.eql?(other.value)
       end
-
       alias :== :eql?
 
+      # Implemented for equality testing
       def hash
         [self.class, expr, method_name, value].hash
       end
 
+      # Whether the value has been assigned yet.
+      # @return [Boolean] Has the value been set?
       def value?
         @value != :__undefined__
       end
 
+      # Set the value for this predicate
+      # @param val The value to be set
+      # @return [Predicate] This predicate, with its new value set
       def %(val)
         @value = val
         self
@@ -40,6 +61,7 @@ module Squeel
       # 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

data/lib/squeel/nodes/predicate_operators.rb

@@ -1,17 +1,29 @@
 module Squeel
   module Nodes
+    # Operators that act as factories for Or, And, and Not nodes for inclusion
+    # in classes which can be contained inside these nodes.
     module PredicateOperators
+
+      # Create a new Or node, with this node as its left-hand node.
+      # @param other The right-hand node for the Or
+      # @return [Or] The new Or node
       def |(other)
         Or.new(self, other)
       end
 
+      # Create a new And node, with this node as its left-hand node.
+      # @param other The right-hand node for the And
+      # @return [And] The new And node
       def &(other)
         And.new([self, other])
       end
 
+      # Create a new Not node, with this node as its expression
+      # @return [Not] The new Not node
       def -@
         Not.new(self)
       end
+
     end
   end
 end

data/lib/squeel/nodes/stub.rb

@@ -3,111 +3,118 @@ require 'squeel/nodes/operators'
 
 module Squeel
   module Nodes
+    # Stub nodes are basically a container for a Symbol that can have handy predicate
+    # methods and operators defined on it since doing so on Symbol will incur the
+    # nerdrage of many.
     class Stub
 
       include PredicateMethods
       include Operators
 
+      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
+
+      undef_method :id if method_defined?(:id)
+
+      # @return [Symbol] The symbol contained by this stub
       attr_reader :symbol
 
+      # Create a new Stub.
+      # @param [Symbol] symbol The symbol that this Stub contains
       def initialize(symbol)
         @symbol = symbol
       end
 
+      # Object comparison
       def eql?(other)
         self.class == other.class &&
         self.symbol == other.symbol
       end
 
+      # To support object equality tests
       def hash
         symbol.hash
       end
 
+      # @return [Symbol] The symbol this Stub contains.
       def to_sym
         symbol
       end
 
+      # @return [String] The Stub's String equivalent.
       def to_s
         symbol.to_s
       end
 
+      # Create a KeyPath when any undefined method is called on a Stub.
+      # @overload node_name
+      #   Creates a new KeyPath with this Stub 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 Stub 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])
+        if args.empty?
+          KeyPath.new(self, method_id)
+        elsif (args.size == 1) && (Class === args[0])
           KeyPath.new(self, Join.new(method_id, Arel::InnerJoin, args[0]))
         else
-          KeyPath.new(self, method_id)
+          KeyPath.new(self, Nodes::Function.new(method_id, args))
         end
       end
 
-      def ==(value)
-        Predicate.new self.symbol, :eq, value
-      end
-
-      # Won't work on Ruby 1.8.x so need to do this conditionally
-      define_method('!=') do |value|
-        Predicate.new(self.symbol, :not_eq, value)
-      end if respond_to?('!=')
-
-      def ^(value)
-        Predicate.new self.symbol, :not_eq, value
-      end
-
-      def >>(value)
-        Predicate.new self.symbol, :in, value
-      end
-
-      def <<(value)
-        Predicate.new self.symbol, :not_in, value
-      end
-
-      def =~(value)
-        Predicate.new self.symbol, :matches, value
-      end
-
-      # Won't work on Ruby 1.8.x so need to do this conditionally
-      define_method('!~') do |value|
-        Predicate.new(self.symbol, :does_not_match, value)
-      end if respond_to?('!~')
-
-      def >(value)
-        Predicate.new self.symbol, :gt, value
-      end
-
-      def >=(value)
-        Predicate.new self.symbol, :gteq, value
-      end
-
-      def <(value)
-        Predicate.new self.symbol, :lt, value
-      end
-
-      def <=(value)
-        Predicate.new self.symbol, :lteq, value
+      # Return a KeyPath containing only this Stub, but flagged as absolute.
+      # This helps Stubs 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 Stub
+      def ~
+        KeyPath.new [], self, true
       end
 
+      # Create an ascending Order node with this Stub's symbol as its expression
+      # @return [Order] The new Order node
       def asc
         Order.new self.symbol, 1
       end
 
+      # Create a descending Order node with this Stub's symbol as its expression
+      # @return [Order] The new Order node
       def desc
         Order.new self.symbol, -1
       end
 
+      # Create a Function node for a function named the same as this Stub and with the given arguments
+      # @return [Function] The new Function node
       def func(*args)
         Function.new(self.symbol, args)
       end
 
-      alias :[] :func
-
+      # Create an inner Join node for the association named by this Stub
+      # @return [Join] The new inner Join node
       def inner
         Join.new(self.symbol, Arel::InnerJoin)
       end
 
+      # Create an outer Join node for the association named by this Stub
+      # @return [Join] The new outer Join node
       def outer
         Join.new(self.symbol, Arel::OuterJoin)
       end
 
+      # Create a polymorphic Join node for the association named by this Stub,
+      # @param [Class] klass The polymorphic belongs_to class for this Join
+      # @return [Join] The new polymorphic Join node
       def of_class(klass)
         Join.new(self.symbol, Arel::InnerJoin, klass)
       end

data/lib/squeel/nodes/unary.rb

@@ -2,21 +2,27 @@ require 'squeel/nodes/predicate_operators'
 
 module Squeel
   module Nodes
+    # A node that contains a single expression.
     class Unary
+
       include PredicateOperators
 
+      # @return The expression contained in the node
       attr_reader :expr
 
+      # Create a new Unary node.
+      # @param expr The expression to contain inside the node.
       def initialize(expr)
         @expr = expr
       end
 
+      # Object comparison
       def eql?(other)
         self.class == other.class &&
         self.expr  == other.expr
       end
-
       alias :== :eql?
+
     end
   end
 end

data/lib/squeel/predicate_methods.rb

@@ -1,19 +1,11 @@
-require 'squeel/predicate_methods/symbol'
-require 'squeel/predicate_methods/stub'
-require 'squeel/predicate_methods/predicate'
-require 'squeel/predicate_methods/function'
-
 module Squeel
+  # Defines Nodes::Predicate factories named for each of the ARel predication methods
   module PredicateMethods
 
-    def self.included(base)
-      base.send :include, const_get(base.name.split(/::/)[-1].to_sym)
-    end
-
     Constants::PREDICATES.each do |method_name|
       class_eval <<-RUBY
         def #{method_name}(value = :__undefined__)
-          predicate :#{method_name}, value
+          Nodes::Predicate.new self, :#{method_name}, value
         end
       RUBY
     end

data/lib/squeel/version.rb

@@ -1,3 +1,3 @@
 module Squeel
-  VERSION = "0.5.5"
+  VERSION = "0.6.0"
 end

data/lib/squeel/visitors/attribute_visitor.rb

@@ -2,8 +2,18 @@ require 'squeel/visitors/base'
 
 module Squeel
   module Visitors
+    # A visitor that tries to convert visited nodes into Arel::Attributes
+    # or other nodes that can be used for grouping, ordering, and the like.
     class AttributeVisitor < Base
 
+      private
+
+      # Visit a Hash. This entails iterating through each key and value and
+      # visiting each value in turn.
+      #
+      # @param [Hash] o The Hash to visit
+      # @param parent The current parent object in the context
+      # @return [Array] An array of values for use in an ordering, grouping, etc.
       def visit_Hash(o, parent)
         o.map do |k, v|
           if implies_context_change?(v)
@@ -14,11 +24,19 @@ module Squeel
         end.flatten
       end
 
+      # @return [Boolean] Whether the given value implies a context change
+      # @param v The value to consider
       def implies_context_change?(v)
-        Hash === v || can_accept?(v) ||
-        (Array === v && !v.empty? && v.all? {|val| can_accept?(val)})
+        can_accept?(v)
       end
 
+      # Change context (by setting the new parent to the result of a #find or
+      # #traverse on the key), then accept the given value.
+      #
+      # @param k The hash key
+      # @param v The hash value
+      # @param parent The current parent object in the context
+      # @return The visited value
       def visit_with_context_change(k, v, parent)
         parent = case k
           when Nodes::KeyPath
@@ -34,32 +52,84 @@ module Squeel
         end
       end
 
+      # If there is no context change, we'll just return the value unchanged,
+      # currently. Is this really the right behavior? I don't think so, but
+      # it works in this case.
+      #
+      # @param k The hash key
+      # @param v The hash value
+      # @param parent The current parent object in the context
+      # @return The same value we just received. Yeah, this method's pretty pointless,
+      #   for now, and only here for consistency's sake.
       def visit_without_context_change(k, v, parent)
         v
       end
 
+      # Visit elements of an array that it's possible to visit -- leave other
+      # elements untouched.
+      #
+      # @param [Array] o The array to visit
+      # @param parent The array's parent within the context
+      # @return [Array] The flattened array with elements visited
       def visit_Array(o, parent)
         o.map { |v| can_accept?(v) ? accept(v, parent) : v }.flatten
       end
 
+      # Visit a symbol. This will return an attribute named after the symbol against
+      # the current parent's contextualized table.
+      #
+      # @param [Symbol] o The symbol to visit
+      # @param parent The symbol's parent within the context
+      # @return [Arel::Attribute] An attribute on the contextualized parent table
       def visit_Symbol(o, parent)
         contextualize(parent)[o]
       end
 
+      # Visit a stub. This will return an attribute named after the stub against
+      # the current parent's contextualized table.
+      #
+      # @param [Nodes::Stub] o The stub to visit
+      # @param parent The stub's parent within the context
+      # @return [Arel::Attribute] An attribute on the contextualized parent table
       def visit_Squeel_Nodes_Stub(o, parent)
         contextualize(parent)[o.symbol]
       end
 
+      # Visit a keypath. This will traverse the keypath's "path", setting a new
+      # parent as though the keypath's endpoint was in a deeply-nested hash,
+      # then visit the endpoint with the new parent.
+      #
+      # @param [Nodes::KeyPath] o The keypath to visit
+      # @param parent The keypath's parent within the context
+      # @return The visited endpoint, with the parent from the KeyPath's path.
       def visit_Squeel_Nodes_KeyPath(o, parent)
         parent = traverse(o, parent)
 
         accept(o.endpoint, parent)
       end
 
+      # Visit an Order node.
+      #
+      # @param [Nodes::Order] o The order node to visit
+      # @param parent The node's parent within the context
+      # @return [Arel::Nodes::Ordering] An ascending or desending ordering
       def visit_Squeel_Nodes_Order(o, parent)
         accept(o.expr, parent).send(o.descending? ? :desc : :asc)
       end
 
+      # Visit a Function node. Each function argument will be accepted or
+      # contextualized if appropriate. Keep in mind that this occurs with
+      # the current parent within the context.
+      #
+      # @example A function as the endpoint of a keypath
+      #   Person.joins{children}.order{children.coalesce(name, '<no name>')}
+      #   # => SELECT "people".* FROM "people"
+      #          INNER JOIN "people" "children_people"
+      #            ON "children_people"."parent_id" = "people"."id"
+      #          ORDER BY coalesce("children_people"."name", '<no name>')
+      #
+      # @param [Nodes::Function] o The function node to visit
+      # @param parent The node's parent within the context
       def visit_Squeel_Nodes_Function(o, parent)
         args = o.args.map do |arg|
           case arg
@@ -68,12 +138,18 @@ module Squeel
           when Symbol, Nodes::Stub
             Arel.sql(arel_visitor.accept contextualize(parent)[arg.to_sym])
           else
-            quoted?(arg) ? Arel.sql(arel_visitor.accept arg) : arg
+            quote arg
           end
         end
         Arel::Nodes::NamedFunction.new(o.name, args, o.alias)
       end
 
+      # Visit an Operation node. Each operand will be accepted or
+      # contextualized if appropriate. Keep in mind that this occurs with
+      # the current parent within the context.
+      #
+      # @param [Nodes::Operation] o The operation node to visit
+      # @param parent The node's parent within the context
       def visit_Squeel_Nodes_Operation(o, parent)
         args = o.args.map do |arg|
           case arg
@@ -82,7 +158,7 @@ module Squeel
           when Symbol, Nodes::Stub
             Arel.sql(arel_visitor.accept contextualize(parent)[arg.to_sym])
           else
-            quoted?(arg) ? Arel.sql(arel_visitor.accept arg) : arg
+            quote arg
           end
         end