squeel_rbg 0.8.2

data/lib/squeel/nodes/order.rb

@@ -0,0 +1,53 @@
+module Squeel
+  module Nodes
+    # A node that represents SQL orderings, such as "people.id DESC"
+    class Order
+      # @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
+      end
+    end
+  end
+end

data/lib/squeel/nodes/predicate.rb

@@ -0,0 +1,71 @@
+require 'squeel/predicate_methods'
+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 PredicateOperators
+
+      # @return The right-hand value being considered in this predicate.
+      attr_accessor :value
+
+      # @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
+      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
+
+    end
+  end
+end

data/lib/squeel/nodes/predicate_operators.rb

@@ -0,0 +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

@@ -0,0 +1,125 @@
+require 'squeel/predicate_methods'
+require 'squeel/nodes/operators'
+require 'squeel/nodes/aliasing'
+
+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
+      include Aliasing
+
+      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.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, Nodes::Function.new(method_id, args))
+        end
+      end
+
+      # 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
+
+      # 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
+
+    end
+  end
+end

data/lib/squeel/nodes/unary.rb

@@ -0,0 +1,28 @@
+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/nodes.rb

@@ -0,0 +1,17 @@
+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'
+require 'squeel/nodes/function'
+require 'squeel/nodes/operation'
+require 'squeel/nodes/order'
+require 'squeel/nodes/and'
+require 'squeel/nodes/or'
+require 'squeel/nodes/as'
+require 'squeel/nodes/not'
+require 'squeel/nodes/join'

data/lib/squeel/predicate_methods.rb

@@ -0,0 +1,14 @@
+module Squeel
+  # Defines Nodes::Predicate factories named for each of the ARel predication methods
+  module PredicateMethods
+
+    Constants::PREDICATES.each do |method_name|
+      class_eval <<-RUBY
+        def #{method_name}(value = :__undefined__)
+          Nodes::Predicate.new self, :#{method_name}, value
+        end
+      RUBY
+    end
+
+  end
+end

data/lib/squeel/version.rb

@@ -0,0 +1,3 @@
+module Squeel
+  VERSION = "0.8.2"
+end

data/lib/squeel/visitors/attribute_visitor.rb

@@ -0,0 +1,191 @@
+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)
+            visit_with_context_change(k, v, parent)
+          else
+            visit_without_context_change(k, v, parent)
+          end
+        end.flatten
+      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
+          when Nodes::Function, Nodes::KeyPath
+            accept(arg, parent)
+          when Symbol, Nodes::Stub
+            Arel.sql(arel_visitor.accept contextualize(parent)[arg.to_sym])
+          else
+            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
+          when Nodes::Function
+            accept(arg, parent)
+          when Symbol, Nodes::Stub
+            Arel.sql(arel_visitor.accept contextualize(parent)[arg.to_sym])
+          else
+            quote arg
+          end
+        end
+
+        op = case o.operator
+        when :+
+          Arel::Nodes::Addition.new(args[0], args[1])
+        when :-
+          Arel::Nodes::Subtraction.new(args[0], args[1])
+        when :*
+          Arel::Nodes::Multiplication.new(args[0], args[1])
+        when :/
+          Arel::Nodes::Division.new(args[0], args[1])
+        else
+          Arel.sql("#{arel_visitor.accept(args[0])} #{o.operator} #{arel_visitor.accept(args[1])}")
+        end
+        o.alias ? op.as(o.alias) : op
+      end
+
+      # Visit a Squeel As node, resulting in am ARel As node.
+      #
+      # @param [Nodes::As] The As node to visit
+      # @param parent The parent object in the context
+      # @return [Arel::Nodes::As] The resulting as node.
+      def visit_Squeel_Nodes_As(o, parent)
+        accept(o.left, parent).as(o.right)
+      end
+
+      # @return [Boolean] Whether the given value implies a context change
+      # @param v The value to consider
+      def implies_context_change?(v)
+        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
+            traverse(k, parent, true)
+          else
+            find(k, parent)
+          end
+
+        if Array === v
+          v.map {|val| accept(val, parent || k)}
+        else
+          can_accept?(v) ? accept(v, parent || k) : v
+        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
+
+    end
+  end
+end

data/lib/squeel/visitors/base.rb

@@ -0,0 +1,112 @@
+require 'active_support/core_ext/module'
+require 'squeel/nodes'
+
+module Squeel
+  module Visitors
+    # The Base visitor class, containing the default behavior common to subclasses.
+    class Base
+      attr_accessor :context
+      delegate :contextualize, :find, :traverse, :engine, :arel_visitor, :to => :context
+
+      # Create a new Visitor that uses the supplied context object to contextualize
+      # visited nodes.
+      #
+      # @param [Context] context The context to use for node visitation.
+      def initialize(context = nil)
+        @context = context
+      end
+
+      # Accept an object.
+      #
+      # @param object The object to visit
+      # @param parent The parent of this object, to track the object's place in
+      #   any association hierarchy.
+      # @return The results of the node visitation, typically an ARel object of some kind.
+      def accept(object, parent = context.base)
+        visit(object, parent)
+      end
+
+      # @param object The object to check
+      # @return [Boolean] Whether or not the visitor can accept the given object
+      def can_accept?(object)
+        self.class.can_accept? object
+      end
+
+      # @param object The object to check
+      # @return [Boolean] Whether or not visitors of this class can accept the given object
+      def self.can_accept?(object)
+        @can_accept ||= Hash.new do |hash, klass|
+          hash[klass] = klass.ancestors.detect { |ancestor|
+            private_method_defined? DISPATCH[ancestor]
+          } ? true : false
+        end
+        @can_accept[object.class]
+      end
+
+      private
+
+      # A hash that caches the method name to use for a visitor for a given class
+      DISPATCH = Hash.new do |hash, klass|
+        hash[klass] = "visit_#{(klass.name || '').gsub('::', '_')}"
+      end
+
+      # Important to avoid accidentally allowing the default ARel visitor's
+      # last_column quoting behavior (where a value is quoted as though it
+      # is of the type of the last visited column). This can wreak havoc with
+      # Functions and Operations.
+      #
+      # @param object The object to check
+      # @return [Boolean] Whether or not the ARel visitor will try to quote the object if
+      #   not passed as an SqlLiteral.
+      def quoted?(object)
+        case object
+        when Arel::Nodes::SqlLiteral, Bignum, Fixnum, Arel::SelectManager
+          false
+        else
+          true
+        end
+      end
+
+      # Quote a value based on its type, not on the last column used by the
+      # ARel visitor. This is occasionally necessary to avoid having ARel
+      # quote a value according to an integer column, converting 'My String' to 0.
+      #
+      # @param value The value to quote
+      # @return [Arel::Nodes::SqlLiteral] if the value needs to be pre-quoted
+      # @return the unquoted value, if default quoting won't hurt.
+      def quote(value)
+        if quoted? value
+          case value
+          when Array
+            value.map {|v| quote(v)}
+          when Range
+            Range.new(quote(value.begin), quote(value.end), value.exclude_end?)
+          else
+            Arel.sql(arel_visitor.accept value)
+          end
+        else
+          value
+        end
+      end
+
+      # Visit the object. This is not called directly, but instead via the public
+      # #accept method.
+      #
+      # @param object The object to visit
+      # @param parent The object's parent within the context
+      def visit(object, parent)
+        send(DISPATCH[object.class], object, parent)
+      rescue NoMethodError => e
+        raise e if respond_to?(DISPATCH[object.class], true)
+
+        superklass = object.class.ancestors.find { |klass|
+          respond_to?(DISPATCH[klass], true)
+        }
+        raise(TypeError, "Cannot visit #{object.class}") unless superklass
+        DISPATCH[object.class] = DISPATCH[superklass]
+        retry
+      end
+
+    end
+  end
+end