dm-core 0.10.1 → 0.10.2

data/lib/dm-core/query/conditions/operation.rb

@@ -1,65 +1,122 @@
 module DataMapper
   class Query
     module Conditions
-      class InvalidOperation < ArgumentError; end
-
       class Operation
-        # TODO: document
+        # Factory method to initialize an operation
+        #
+        # @example
+        #   operation = Operation.new(:and, comparison)
+        #
+        # @param [Symbol] slug
+        #   the identifier for the operation class
+        # @param [Array] *operands
+        #   the operands to initialize the operation with
+        #
+        # @return [AbstractOperation]
+        #   the operation matching the slug
+        #
         # @api semipublic
         def self.new(slug, *operands)
           if klass = operation_class(slug)
             klass.new(*operands)
           else
-            raise "No Operation class for `#{slug.inspect}' has been defined"
+            raise ArgumentError, "No Operation class for #{slug.inspect} has been defined"
           end
         end
 
-        # TODO: document
-        # @api semipublic
-        def self.operation_class(slug)
-          operation_classes[slug] ||= AbstractOperation.descendants.detect { |operation_class| operation_class.slug == slug }
-        end
-
-        # TODO: document
+        # Return an Array of all the slugs for the operation classes
+        #
+        # @return [Array]
+        #   the slugs of all the operation classes
+        #
         # @api private
         def self.slugs
-          @slugs ||= AbstractOperation.descendants.map { |operation_class| operation_class.slug }
+          AbstractOperation.descendants.map { |operation_class| operation_class.slug }
         end
 
         class << self
           private
 
-          # TODO: document
+          # Returns a Hash mapping the slugs to each class
+          #
+          # @return [Hash]
+          #   Hash mapping the slug to the class
+          #
           # @api private
           def operation_classes
             @operation_classes ||= {}
           end
+
+          # Lookup the operation class based on the slug
+          #
+          # @example
+          #   operation_class = Operation.operation_class(:and)
+          #
+          # @param [Symbol] slug
+          #   the identifier for the operation class
+          #
+          # @return [Class]
+          #   the operation class
+          #
+          # @api private
+          def operation_class(slug)
+            operation_classes[slug] ||= AbstractOperation.descendants.detect { |operation_class| operation_class.slug == slug }
+          end
         end
       end # class Operation
 
       class AbstractOperation
+        include Extlib::Assertions
         include Enumerable
         extend Equalizer
 
         equalize :slug, :sorted_operands
 
-        # TODO: document
+        # Returns the parent operation
+        #
+        # @return [AbstractOperation]
+        #   the parent operation
+        #
+        # @api semipublic
+        attr_accessor :parent
+
+        # Returns the child operations and comparisons
+        #
+        # @return [Set<AbstractOperation, AbstractComparison, Array>]
+        #   the set of operations and comparisons
+        #
         # @api semipublic
         attr_reader :operands
 
-        # TODO: document
+        alias children operands
+
+        # Returns the classes that inherit from AbstractComparison
+        #
+        # @return [Set]
+        #   the descendant classes
+        #
         # @api private
         def self.descendants
           @descendants ||= Set.new
         end
 
-        # TODO: document
+        # Hook executed when inheriting from AbstractComparison
+        #
+        # @return [undefined]
+        #
         # @api private
         def self.inherited(operation_class)
           descendants << operation_class
         end
 
-        # TODO: document
+        # Get and set the slug for the operation class
+        #
+        # @param [Symbol] slug
+        #   optionally set the slug for the operation class
+        #
+        # @return [Symbol]
+        #   the slug for the operation class
+        #
         # @api semipublic
         def self.slug(slug = nil)
           slug ? @slug = slug : @slug
@@ -75,69 +132,274 @@ module DataMapper
           self.class.slug
         end
 
-        # TODO: document
+        # Iterate through each operand in the operation
+        #
+        # @yield [operand]
+        #   yields to each operand
+        #
+        # @yieldparam [AbstractOperation, AbstractComparison, Array] operand
+        #   each operand
+        #
+        # @return [self]
+        #   returns the operation
+        #
         # @api semipublic
         def each
-          @operands.each { |*block_args| yield(*block_args) }
+          @operands.each { |op| yield op }
+          self
         end
 
-        # TODO: document
+        # Test if the operation is valid
+        #
+        # @return [Boolean]
+        #   true if the operation is valid, false if not
+        #
         # @api semipublic
         def valid?
-          operands.any? && operands.all? do |operand|
-            if operand.respond_to?(:valid?)
-              operand.valid?
-            else
-              true
-            end
-          end
+          any? && all? { |op| valid_operand?(op) }
         end
 
-        # TODO: document
+        # Add an operand to the operation
+        #
+        # @param [AbstractOperation, AbstractComparison, Array] operand
+        #   the operand to add
+        #
+        # @return [self]
+        #   the operation
+        #
         # @api semipublic
         def <<(operand)
-          @operands << operand
+          assert_valid_operand_type(operand)
+          @operands << relate_operand(operand)
           self
         end
 
-        # TODO: document
+        # Add operands to the operation
+        #
+        # @param [#each] operands
+        #   the operands to add
+        #
+        # @return [self]
+        #   the operation
+        #
         # @api semipublic
-        def inspect
-          "#<#{self.class} @operands=#{@operands.inspect}>"
+        def merge(operands)
+          operands.each { |op| self << op }
+          self
+        end
+
+        # Return the union with another operand
+        #
+        # @param [AbstractOperation] other
+        #   the operand to union with
+        #
+        # @return [OrOperation]
+        #   the union of the operation and operand
+        #
+        # @api semipublic
+        def union(other)
+          Operation.new(:or, dup, other.dup).minimize
+        end
+
+        alias | union
+        alias + union
+
+        # Return the intersection of the operation and another operand
+        #
+        # @param [AbstractOperation] other
+        #   the operand to intersect with
+        #
+        # @return [AndOperation]
+        #   the intersection of the operation and operand
+        #
+        # @api semipublic
+        def intersection(other)
+          Operation.new(:and, dup, other.dup).minimize
+        end
+
+        alias & intersection
+
+        # Return the difference of the operation and another operand
+        #
+        # @param [AbstractOperation] other
+        #   the operand to not match
+        #
+        # @return [AndOperation]
+        #   the intersection of the operation and operand
+        #
+        # @api semipublic
+        def difference(other)
+          Operation.new(:and, dup, Operation.new(:not, other.dup)).minimize
+        end
+
+        alias - difference
+
+        # Minimize the operation
+        #
+        # @return [self]
+        #   the minimized operation
+        #
+        # @api semipublic
+        def minimize
+          self
+        end
+
+        # Clear the operands
+        #
+        # @return [self]
+        #   the operation
+        #
+        # @api semipublic
+        def clear
+          @operands.clear
+          self
+        end
+
+        # Return the string representation of the operation
+        #
+        # @return [String]
+        #   the string representation of the operation
+        #
+        # @api semipublic
+        def to_s
+          empty? ? '' : "(#{sort_by { |op| op.to_s }.map { |op| op.to_s }.join(" #{slug.to_s.upcase} ")})"
+        end
+
+        # Test if the operation is negated
+        #
+        # Defaults to return false.
+        #
+        # @return [Boolean]
+        #   true if the operation is negated, false if not
+        #
+        # @api private
+        def negated?
+          parent = self.parent
+          parent ? parent.negated? : false
         end
 
         # Return a list of operands in predictable order
         #
-        # @return [Array<AbstractOperation>]
+        # @return [Array<AbstractOperation, AbstractComparison, Array>]
         #   list of operands sorted in deterministic order
         #
         # @api private
         def sorted_operands
-          @operands.sort_by { |operand| operand.hash }
+          sort_by { |op| op.hash }
         end
 
         private
 
-        # TODO: document
+        # Initialize an operation
+        #
+        # @param [Array<AbstractOperation, AbstractComparison, Array>] *operands
+        #   the operands to include in the operation
+        #
+        # @return [AbstractOperation]
+        #   the operation
+        #
         # @api semipublic
         def initialize(*operands)
-          @operands = operands
+          @operands = Set.new
+          merge(operands)
         end
 
-        # TODO: document
+        # Copy an operation
+        #
+        # @param [AbstractOperation] original
+        #   the original operation
+        #
+        # @return [undefined]
+        #
         # @api semipublic
         def initialize_copy(*)
-          @operands = @operands.map { |operand| operand.dup }
+          @operands = map { |op| op.dup }.to_set
+        end
+
+        # Minimize the operands recursively
+        #
+        # @return [undefined]
+        #
+        # @api private
+        def minimize_operands
+          # FIXME: why does Set#map! not work here?
+          @operands = map do |op|
+            relate_operand(op.respond_to?(:minimize) ? op.minimize : op)
+          end.to_set
+        end
+
+        # Prune empty operands recursively
+        #
+        # @return [undefined]
+        #
+        # @api private
+        def prune_operands
+          @operands.delete_if { |op| op.respond_to?(:empty?) ? op.empty? : false }
+        end
+
+        # Test if the operand is valid
+        #
+        # @param [AbstractOperation, AbstractComparison, Array] operand
+        #   the operand to test
+        #
+        # @return [Boolean]
+        #   true if the operand is valid
+        #
+        # @api private
+        def valid_operand?(operand)
+          if operand.respond_to?(:valid?)
+            operand.valid?
+          else
+            true
+          end
+        end
+
+        # Set self to be the operand's parent
+        #
+        # @return [AbstractOperation, AbstractComparison, Array]
+        #   the operand that was related to self
+        #
+        # @api privTE
+        def relate_operand(operand)
+          operand.parent = self if operand.respond_to?(:parent=)
+          operand
+        end
+
+        # Assert that the operand is a valid type
+        #
+        # @param [AbstractOperation, AbstractComparison, Array] operand
+        #   the operand to test
+        #
+        # @return [undefined]
+        #
+        # @raise [ArgumentError]
+        #   raised if the operand is not a valid type
+        #
+        # @api private
+        def assert_valid_operand_type(operand)
+          assert_kind_of 'operand', operand, AbstractOperation, AbstractComparison, Array
         end
       end # class AbstractOperation
 
       module FlattenOperation
-        # TODO: document
+        # Add an operand to the operation, flattening the same types
+        #
+        # Flattening means that if the operand is the same as the
+        # operation, we should just include the operand's operands
+        # in the operation and prune that part of the tree.  This results
+        # in a shallower tree, is faster to match and usually generates
+        # more efficient queries in the adapters.
+        #
+        # @param [AbstractOperation, AbstractComparison, Array] operand
+        #   the operand to add
+        #
+        # @return [self]
+        #   the operation
+        #
         # @api semipublic
         def <<(operand)
-          if operand.kind_of?(self.class)
-            @operands.concat(operand.operands)
-            self
+          if kind_of?(operand.class)
+            merge(operand.operands)
           else
             super
           end
@@ -149,10 +411,41 @@ module DataMapper
 
         slug :and
 
-        # TODO: document
+        # Match the record
+        #
+        # @example with a Hash
+        #   operation.matches?({ :id => 1 })  # => true
+        #
+        # @example with a Resource
+        #   operation.matches?(Blog::Article.new(:id => 1))  # => true
+        #
+        # @param [Resource, Hash] record
+        #   the resource to match
+        #
+        # @return [true]
+        #   true if the record matches, false if not
+        #
         # @api semipublic
         def matches?(record)
-          @operands.all? { |operand| operand.matches?(record) }
+          all? { |op| op.respond_to?(:matches?) ? op.matches?(record) : true }
+        end
+
+        # Minimize the operation
+        #
+        # @return [self]
+        #   the minimized AndOperation
+        # @return [AbstractOperation, AbstractComparison, Array]
+        #   the minimized operation
+        #
+        # @api semipublic
+        def minimize
+          minimize_operands
+
+          return Operation.new(:null) if any? && all? { |op| op.nil? }
+
+          prune_operands
+
+          one? ? first : self
         end
       end # class AndOperation
 
@@ -161,47 +454,182 @@ module DataMapper
 
         slug :or
 
-        # TODO: document
+        # Match the record
+        #
+        # @param [Resource, Hash] record
+        #   the resource to match
+        #
+        # @return [true]
+        #   true if the record matches, false if not
+        #
         # @api semipublic
         def matches?(record)
-          @operands.any? { |operand| operand.matches?(record) }
+          any? { |op| op.respond_to?(:matches?) ? op.matches?(record) : true }
+        end
+
+        # Test if the operation is valid
+        #
+        # An OrOperation is valid if one of it's operands is valid.
+        #
+        # @return [Boolean]
+        #   true if the operation is valid, false if not
+        #
+        # @api semipublic
+        def valid?
+          any? { |op| valid_operand?(op) }
+        end
+
+        # Minimize the operation
+        #
+        # @return [self]
+        #   the minimized OrOperation
+        # @return [AbstractOperation, AbstractComparison, Array]
+        #   the minimized operation
+        #
+        # @api semipublic
+        def minimize
+          minimize_operands
+
+          return Operation.new(:null) if any? { |op| op.nil? }
+
+          prune_operands
+
+          one? ? first : self
         end
       end # class OrOperation
 
       class NotOperation < AbstractOperation
         slug :not
 
-        # TODO: document
+        # Match the record
+        #
+        # @param [Resource, Hash] record
+        #   the resource to match
+        #
+        # @return [true]
+        #   true if the record matches, false if not
+        #
         # @api semipublic
         def matches?(record)
-          not @operands.first.matches?(record)
+          operand = self.operand
+          operand.respond_to?(:matches?) ? !operand.matches?(record) : true
         end
 
-        # TODO: document
+        # Add an operand to the operation
+        #
+        # This will only allow a single operand to be added.
+        #
+        # @param [AbstractOperation, AbstractComparison, Array] operand
+        #   the operand to add
+        #
+        # @return [self]
+        #   the operation
+        #
         # @api semipublic
         def <<(operand)
-          raise ArgumentError, "#{self.class} cannot have more than one operand" if @operands.size > 0
+          assert_one_operand(operand)
+          assert_no_self_reference(operand)
           super
         end
 
-        private
+        # Return the only operand in the operation
+        #
+        # @return [AbstractOperation, AbstractComparison, Array]
+        #   the operand
+        #
+        # @api semipublic
+        def operand
+          first
+        end
 
-        # TODO: document
+        # Minimize the operation
+        #
+        # @return [self]
+        #   the minimized NotOperation
+        # @return [AbstractOperation, AbstractComparison, Array]
+        #   the minimized operation
+        #
         # @api semipublic
-        def initialize(*operands)
-          raise InvalidOperation, "#{self.class} is a unary operator" if operands.size > 1
-          super
+        def minimize
+          minimize_operands
+          prune_operands
+
+          # factor out double negatives if possible
+          operand = self.operand
+          one? && instance_of?(operand.class) ? operand.operand : self
+        end
+
+        # Return the string representation of the operation
+        #
+        # @return [String]
+        #   the string representation of the operation
+        #
+        # @api semipublic
+        def to_s
+          empty? ? '' : "NOT(#{operand.to_s})"
+        end
+
+        # Test if the operation is negated
+        #
+        # Defaults to return false.
+        #
+        # @return [Boolean]
+        #   true if the operation is negated, false if not
+        #
+        # @api private
+        def negated?
+          parent = self.parent
+          parent ? !parent.negated? : true
+        end
+
+        private
+
+        # Assert there is only one operand
+        #
+        # @param [AbstractOperation, AbstractComparison, Array] operand
+        #   the operand to test
+        #
+        # @return [undefined]
+        #
+        # @raise [ArgumentError]
+        #   raised if the operand is not a valid type
+        #
+        # @api private
+        def assert_one_operand(operand)
+          unless empty? || self.operand == operand
+            raise ArgumentError, "#{self.class} cannot have more than one operand"
+          end
+        end
+
+        # Assert the operand is not equal to self
+        #
+        # @param [AbstractOperation, AbstractComparison, Array] operand
+        #   the operand to test
+        #
+        # @return [undefined]
+        #
+        # @raise [ArgumentError]
+        #  raised if object is appended to itself
+        #
+        # @api private
+        def assert_no_self_reference(operand)
+          if equal?(operand)
+            raise ArgumentError, 'cannot append operand to itself'
+          end
         end
       end # class NotOperation
 
       class NullOperation < AbstractOperation
         undef_method :<<
+        undef_method :merge
 
         slug :null
 
         # Match the record
         #
-        # @param [Resource] record
+        # A NullOperation matches every record.
+        #
+        # @param [Resource, Hash] record
         #   the resource to match
         #
         # @return [true]
@@ -209,11 +637,13 @@ module DataMapper
         #
         # @api semipublic
         def matches?(record)
-          true
+          record.kind_of?(Hash) || record.kind_of?(Resource)
         end
 
         # Test validity of the operation
         #
+        # A NullOperation is always valid.
+        #
         # @return [true]
         #   always valid
         #
@@ -241,6 +671,18 @@ module DataMapper
         def inspect
           'nil'
         end
+
+        private
+
+        # Initialize a NullOperation
+        #
+        # @return [NullOperation]
+        #   the operation
+        #
+        # @api semipublic
+        def initialize
+          @operands = Set.new
+        end
       end
     end # module Conditions
   end # class Query