squeel_rbg 0.8.2

data/lib/squeel/dsl.rb

@@ -0,0 +1,86 @@
+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)/
+          undef_method method
+        end
+      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(block.binding)
+      else
+        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])
+        Nodes::Join.new(method_id, Arel::InnerJoin, args[0])
+      else
+        Nodes::Function.new method_id, args
+      end
+    end
+
+  end
+end

data/lib/squeel/nodes/aliasing.rb

@@ -0,0 +1,13 @@
+require 'squeel/nodes/as'
+
+module Squeel
+  module Nodes
+    module Aliasing
+
+      def as(name)
+        As.new(self, name.to_s)
+      end
+
+    end
+  end
+end

data/lib/squeel/nodes/and.rb

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

data/lib/squeel/nodes/as.rb

@@ -0,0 +1,14 @@
+require 'squeel/nodes/binary'
+
+module Squeel
+  module Nodes
+    # A node representing an SQL alias, which will result in same when visited.
+    class As < Binary
+      # @param left The node to be aliased
+      # @param right The alias name
+      def initialize(left, right)
+        @left, @right = left, right
+      end
+    end
+  end
+end

data/lib/squeel/nodes/binary.rb

@@ -0,0 +1,32 @@
+require 'squeel/nodes/predicate_operators'
+
+module Squeel
+  module Nodes
+    # A node that represents an operation with two operands.
+    class Binary
+
+      include PredicateOperators
+
+      # 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

@@ -0,0 +1,66 @@
+require 'squeel/predicate_methods'
+
+module Squeel
+  module Nodes
+    # A node that represents an SQL function call
+    class Function
+
+      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
+
+      # @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 asc
+        Order.new self, 1
+      end
+
+      def desc
+        Order.new self, -1
+      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/join.rb

@@ -0,0 +1,113 @@
+module Squeel
+  module Nodes
+    # A node representing a joined association
+    class Join
+      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
+      end
+
+      # Set the join type to an inner join
+      # @return [Join] The join, with an updated join type.
+      def inner
+        @_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
+        self
+      end
+
+      # 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
+      end
+
+      # Compare with other objects
+      def eql?(other)
+        self.class == other.class &&
+        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])
+          KeyPath.new(self, Join.new(method_id, Arel::InnerJoin, args[0]))
+        else
+          KeyPath.new(self, method_id)
+        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
+          Kernel.const_get(value)
+        when Class
+          value
+        else
+          raise ArgumentError, "#{value} cannot be converted to a Class"
+        end
+      end
+
+    end
+  end
+end

data/lib/squeel/nodes/key_path.rb

@@ -0,0 +1,192 @@
+require 'squeel/nodes/operators'
+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
+
+      # We need some methods to fall through to the endpoint or create a new
+      # stub of the given name
+      %w(id == != =~ !~).each do |method_name|
+        undef_method method_name if method_defined?(method_name)
+      end
+
+      # @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
+        @endpoint = Stub.new(@endpoint) if Symbol === @endpoint
+        @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 &&
+        self.endpoint.eql?(other.endpoint) &&
+        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
+      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
+          Array === val ? self.in(val) : self.eq(val)
+          self
+        else
+          endpoint % val
+          self
+        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
+          @endpoint = @endpoint.send(method_id, *args)
+          self
+        elsif Stub === endpoint || Join === endpoint
+          @path << endpoint
+          if args.empty?
+            @endpoint = Stub.new(method_id)
+          elsif (args.size == 1) && (Class === args[0])
+            @endpoint = Join.new(method_id, Arel::InnerJoin, args[0])
+          else
+            @endpoint = Nodes::Function.new method_id, args
+          end
+          self
+        else
+          super
+        end
+      end
+
+      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
+
+    end
+  end
+end

data/lib/squeel/nodes/nary.rb

@@ -0,0 +1,45 @@
+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
+        # 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
+  end
+end

data/lib/squeel/nodes/not.rb

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

data/lib/squeel/nodes/operation.rb

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

data/lib/squeel/nodes/operators.rb

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

data/lib/squeel/nodes/or.rb

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