dm-core 0.9.11 → 0.10.0

data/lib/dm-core/property_set.rb

@@ -1,169 +1,212 @@
 module DataMapper
-  class PropertySet
-    include Assertions
-    include Enumerable
-
+  # Set of Property objects, used to associate
+  # queries with set of fields it performed over,
+  # to represent composite keys (esp. for associations)
+  # and so on.
+  class PropertySet < Array
+    extend Deprecate
+
+    deprecate :has_property?, :named?
+    deprecate :slice,         :values_at
+    deprecate :add,           :<<
+
+    # TODO: document
+    # @api semipublic
     def [](name)
-      property_for(name) || raise(ArgumentError, "Unknown property '#{name}'", caller)
+      @properties[name]
     end
 
+    alias super_slice []=
+
+    # TODO: document
+    # @api semipublic
     def []=(name, property)
-      @key, @defaults = nil
-      if existing_property = detect { |p| p.name == name }
-        property.hash
-        @entries[@entries.index(existing_property)] = property
+      if named?(name)
+        add_property(property)
+        super_slice(index(property), property)
       else
-        add(property)
+        self << property
       end
-      property
-    end
-
-    def has_property?(name)
-      !!property_for(name)
-    end
-
-    def slice(*names)
-      @key, @defaults = nil
-      names.map do |name|
-        property_for(name)
-      end
-    end
-
-    def clear
-      @key, @defaults = nil
-      @entries.clear
     end
 
-    def add(*properties)
-      @key, @defaults = nil
-      @entries.push(*properties)
-      properties.each { |property| property.hash }
-      self
+    # TODO: document
+    # @api semipublic
+    def named?(name)
+      @properties.key?(name)
     end
 
-    alias << add
-
-    def length
-      @entries.length
+    # TODO: document
+    # @api semipublic
+    def values_at(*names)
+      @properties.values_at(*names)
     end
 
-    def empty?
-      @entries.empty?
+    # TODO: document
+    # @api semipublic
+    def <<(property)
+      if named?(property.name)
+        add_property(property)
+        super_slice(index(property), property)
+      else
+        add_property(property)
+        super
+      end
     end
 
-    def each
-      @entries.each { |property| yield property }
-      self
+    # TODO: document
+    # @api semipublic
+    def include?(property)
+      named?(property.name)
     end
 
+    # TODO: make PropertySet#reject return a PropertySet instance
+    # TODO: document
+    # @api semipublic
     def defaults
-      @defaults ||= reject { |property| property.lazy? }
+      @defaults ||= self.class.new(key | [ discriminator ].compact | reject { |property| property.lazy? }).freeze
     end
 
+    # TODO: document
+    # @api semipublic
     def key
-      @key ||= select { |property| property.key? }
+      @key ||= self.class.new(select { |property| property.key? }).freeze
+    end
+
+    # TODO: document
+    # @api semipublic
+    def discriminator
+      @discriminator ||= detect { |property| property.type == Types::Discriminator }
     end
 
+    # TODO: document
+    # @api semipublic
     def indexes
       index_hash = {}
-      repository_name = repository.name
-      each { |property| parse_index(property.index, property.field(repository_name), index_hash) }
+      each { |property| parse_index(property.index, property.field, index_hash) }
       index_hash
     end
 
+    # TODO: document
+    # @api semipublic
     def unique_indexes
       index_hash = {}
-      repository_name = repository.name
-      each { |property| parse_index(property.unique_index, property.field(repository_name), index_hash) }
+      each { |property| parse_index(property.unique_index, property.field, index_hash) }
       index_hash
     end
 
+    # TODO: document
+    # @api semipublic
     def get(resource)
       map { |property| property.get(resource) }
     end
 
+    # TODO: document
+    # @api semipublic
+    def get!(resource)
+      map { |property| property.get!(resource) }
+    end
+
+    # TODO: document
+    # @api semipublic
     def set(resource, values)
-      if values.kind_of?(Array) && values.length != length
-        raise ArgumentError, "+values+ must have a length of #{length}, but has #{values.length}", caller
-      end
+      zip(values) { |property, value| property.set(resource, value) }
+    end
 
-      each_with_index { |property,i| property.set(resource, values.nil? ? nil : values[i]) }
+    # TODO: document
+    # @api semipublic
+    def set!(resource, values)
+      zip(values) { |property, value| property.set!(resource, value) }
     end
 
-    def property_contexts(name)
-      contexts = []
-      lazy_contexts.each do |context,property_names|
-        contexts << context if property_names.include?(name)
-      end
-      contexts
+    # TODO: document
+    # @api semipublic
+    def loaded?(resource)
+      all? { |property| property.loaded?(resource) }
     end
 
-    def lazy_context(name)
-      lazy_contexts[name] ||= []
+    # TODO: document
+    # @api semipublic
+    def typecast(values)
+      zip(values.nil? ? [] : values).map { |property, value| property.typecast(value) }
     end
 
-    def lazy_load_context(names)
-      if names.kind_of?(Array) && names.empty?
-        raise ArgumentError, '+names+ cannot be empty', caller
+    # TODO: document
+    # @api private
+    def property_contexts(property_name)
+      contexts = []
+      lazy_contexts.each do |context, property_names|
+        contexts << context if property_names.include?(property_name)
       end
+      contexts
+    end
 
-      result = []
+    # TODO: document
+    # @api private
+    def lazy_context(context)
+      lazy_contexts[context] ||= []
+    end
 
-      Array(names).each do |name|
-        contexts = property_contexts(name)
-        if contexts.empty?
-          result << name  # not lazy
+    # TODO: document
+    # @api private
+    def in_context(property_names)
+      property_names_in_context = property_names.map do |property_name|
+        if (contexts = property_contexts(property_name)).any?
+          lazy_contexts.values_at(*contexts)
         else
-          result |= lazy_contexts.values_at(*contexts).flatten.uniq
+          property_name  # not lazy
         end
       end
-      result
-    end
 
-    def to_query(bind_values)
-      Hash[ *zip(bind_values).flatten ]
-    end
-
-    def inspect
-      '#<PropertySet:{' + map { |property| property.inspect }.join(',') + '}>'
+      values_at(*property_names_in_context.flatten.uniq)
     end
 
     private
 
-    def initialize(properties = [])
-      assert_kind_of 'properties', properties, Enumerable
+    # TODO: document
+    # @api semipublic
+    def initialize(*)
+      super
+      @properties = map { |property| [ property.name, property ] }.to_mash
+    end
+
+    # TODO: document
+    # @api private
+    def initialize_copy(*)
+      super
+      @properties = @properties.dup
+    end
 
-      @entries = properties
-      @property_for = {}
+    # TODO: document
+    # @api private
+    def add_property(property)
+      clear_cache
+      @properties[property.name] = property
     end
 
-    def initialize_copy(orig)
-      @key, @defaults = nil
-      @entries = orig.entries.dup
-      @property_for = {}
+    # TODO: document
+    # @api private
+    def clear_cache
+      @defaults, @key, @discriminator = nil
     end
 
+    # TODO: document
+    # @api private
     def lazy_contexts
       @lazy_contexts ||= {}
     end
 
+    # TODO: document
+    # @api private
     def parse_index(index, property, index_hash)
       case index
-      when true then index_hash[property] = [property]
-      when Symbol
-        index_hash[index.to_s] ||= []
-        index_hash[index.to_s] << property
-      when Enumerable then index.each { |idx| parse_index(idx, property, index_hash) }
+        when true
+          index_hash[property] = [ property ]
+        when Symbol
+          index_hash[index] ||= []
+          index_hash[index] << property
+        when Array
+          index.each { |idx| parse_index(idx, property, index_hash) }
       end
     end
-
-    def property_for(name)
-      unless @property_for[name]
-        property = detect { |property| property.name == name.to_sym }
-        @property_for[name.to_s] = @property_for[name.to_sym] = property if property
-      end
-      @property_for[name]
-    end
-
   end # class PropertySet
 end # module DataMapper

data/lib/dm-core/query.rb

@@ -1,139 +1,563 @@
+# TODO: break this up into classes for each primary option, eg:
+#
+#   - DataMapper::Query::Fields
+#   - DataMapper::Query::Links
+#   - DataMapper::Query::Conditions
+#   - DataMapper::Query::Offset
+#   - DataMapper::Query::Limit
+#   - DataMapper::Query::Order
+#
+# TODO: move assertions, validations, transformations, and equality
+#   checking into each class and clean up Query
+#
+# TODO: add a way to "register" these classes with the Query object
+#   so that new reserved options can be added in the future.  Each
+#   class will need to implement a "slug" method or something similar
+#   so that their option namespace can be reserved.
+
+# TODO: move condition transformations into a Query::Conditions
+#   helper class that knows how to transform the primitives, and
+#   calls #comparison_for(repository, model) on objects (or some
+#   other convention that we establish)
+
 module DataMapper
+
+  # Query class represents a query which will be run against the data-store.
+  # Generally Query objects can be found inside Collection objects.
+  #
   class Query
-    include Assertions
+    include Extlib::Assertions
+
+    OPTIONS = [ :fields, :links, :conditions, :offset, :limit, :order, :unique, :add_reversed, :reload ].to_set.freeze
+
+    # Extract conditions to match a Resource or Collection
+    #
+    # @param [Array, Collection, Resource] source
+    #   the source to extract the values from
+    # @param [ProperySet] source_key
+    #   the key to extract the value from the resource
+    # @param [ProperySet] target_key
+    #   the key to match the resource with
+    #
+    # @return [AbstractComparison, AbstractOperation]
+    #   the conditions to match the resources with
+    #
+    # @api private
+    def self.target_conditions(source, source_key, target_key)
+      source_values = []
+
+      if source.nil?
+        source_values << [ nil ] * target_key.size
+      else
+        Array(source).each do |resource|
+          next unless source_key.loaded?(resource)
+          source_values << source_key.get!(resource)
+        end
+      end
+
+      source_values.uniq!
+
+      if target_key.size == 1
+        target_key = target_key.first
+        source_values.flatten!
+
+        if source_values.size == 1
+          Conditions::EqualToComparison.new(target_key, source_values.first)
+        else
+          Conditions::InclusionComparison.new(target_key, source_values)
+        end
+      else
+        or_operation = Conditions::OrOperation.new
+
+        source_values.each do |source_value|
+          and_operation = Conditions::AndOperation.new
+
+          target_key.zip(source_value) do |property, value|
+            and_operation << Conditions::EqualToComparison.new(property, value)
+          end
+
+          or_operation << and_operation
+        end
+
+        or_operation
+      end
+    end
+
+    # Returns the repository query should be
+    # executed in
+    #
+    # Set in cases like the following:
+    #
+    # @example
+    #
+    #   Document.all(:repository => :medline)
+    #
+    #
+    # @return [Repository]
+    #   the Repository to retrieve results from
+    #
+    # @api semipublic
+    attr_reader :repository
+
+    # Returns model (class) that is used
+    # to instantiate objects from query result
+    # returned by adapter
+    #
+    # @return [Model]
+    #   the Model to retrieve results from
+    #
+    # @api semipublic
+    attr_reader :model
+
+    # Returns the fields
+    #
+    # Set in cases like the following:
+    #
+    # @example
+    #
+    #   Document.all(:fields => [:title, :vernacular_title, :abstract])
+    #
+    # @return [PropertySet]
+    #   the properties in the Model that will be retrieved
+    #
+    # @api semipublic
+    attr_reader :fields
+
+    # Returns the links (associations) query fetches
+    #
+    # @return [Array<DataMapper::Associations::Relationship>]
+    #   the relationships that will be used to scope the results
+    #
+    # @api private
+    attr_reader :links
+
+    # Returns the conditions of the query
+    #
+    # In the following example:
+    #
+    # @example
+    #
+    #   Team.all(:wins.gt => 30, :conference => 'East')
+    #
+    # Conditions are "greater than" operator for "wins"
+    # field and exact match operator for "conference".
+    #
+    # @return [Array]
+    #   the conditions that will be used to scope the results
+    #
+    # @api semipublic
+    attr_reader :conditions
+
+    # Returns the offset query uses
+    #
+    # Set in cases like the following:
+    #
+    # @example
+    #
+    #   Document.all(:offset => page.offset)
+    #
+    # @return [Integer]
+    #   the offset of the results
+    #
+    # @api semipublic
+    attr_reader :offset
+
+    # Returns the limit query uses
+    #
+    # Set in cases like the following:
+    #
+    # @example
+    #
+    #   Document.all(:limit => 10)
+    #
+    # @return [Integer, NilClass]
+    #   the maximum number of results
+    #
+    # @api semipublic
+    attr_reader :limit
 
-    OPTIONS = [
-      :reload, :offset, :limit, :order, :add_reversed, :fields, :links, :includes, :conditions, :unique
-    ]
+    # Returns the order
+    #
+    # Set in cases like the following:
+    #
+    # @example
+    #
+    #   Document.all(:order => [:created_at.desc, :length.desc])
+    #
+    # query order is a set of two ordering rules, descending on
+    # "created_at" field and descending again on "length" field
+    #
+    # @return [Array]
+    #   the order of results
+    #
+    # @api semipublic
+    attr_reader :order
 
-    attr_reader :repository, :model, *OPTIONS - [ :reload, :unique ]
-    attr_writer :add_reversed
-    alias add_reversed? add_reversed
+    # Returns the original options
+    #
+    # @return [Hash]
+    #   the original options
+    #
+    # @api private
+    attr_reader :options
+
+    # Indicates if each result should be returned in reverse order
+    #
+    # Set in cases like the following:
+    #
+    # @example
+    #
+    #   Document.all(:limit => 5).reverse
+    #
+    # Note that :add_reversed option may be used in conditions directly,
+    # but this is rarely the case
+    #
+    # @return [Boolean]
+    #   true if the results should be reversed, false if not
+    #
+    # @api private
+    def add_reversed?
+      @add_reversed
+    end
 
+    # Indicates if the Query results should replace the results in the Identity Map
+    #
+    #   TODO: needs example
+    #
+    # @return [Boolean]
+    #   true if the results should be reloaded, false if not
+    #
+    # @api semipublic
     def reload?
       @reload
     end
 
+    # Indicates if the Query results should be unique
+    #
+    #   TODO: needs example
+    #
+    # @return [Boolean]
+    #   true if the results should be unique, false if not
+    #
+    # @api semipublic
     def unique?
       @unique
     end
 
+    # Indicates if the Query has raw conditions
+    #
+    # @return [Boolean]
+    #   true if the query has raw conditions, false if not
+    #
+    # @api semipublic
+    def raw?
+      @raw
+    end
+
+    # Indicates if the Query is valid
+    #
+    # @return [Boolean]
+    #   true if the query is valid
+    #
+    # @api semipublic
+    def valid?
+      conditions.valid?
+    end
+
+    # Returns a new Query with a reversed order
+    #
+    # @example
+    #
+    #   Document.all(:limit => 5).reverse
+    #
+    # Will execute a single query with correct order
+    #
+    # @return [Query]
+    #   new Query with reversed order
+    #
+    # @api semipublic
     def reverse
       dup.reverse!
     end
 
+    # Reverses the sort order of the Query
+    #
+    # @example
+    #
+    #   Document.all(:limit => 5).reverse
+    #
+    # Will execute a single query with original order
+    # and then reverse collection in the Ruby space
+    #
+    # @return [Query]
+    #   self
+    #
+    # @api semipublic
     def reverse!
       # reverse the sort order
-      update(:order => self.order.map { |o| o.reverse })
+      @order.map! { |direction| direction.reverse! }
+
+      # copy the order to the options
+      @options = @options.merge(:order => @order.map { |direction| direction.dup }).freeze
 
       self
     end
 
+    # Updates the Query with another Query or conditions
+    #
+    # Pretty unrealistic example:
+    #
+    # @example
+    #
+    #   Journal.all(:limit => 2).query.limit                     # => 2
+    #   Journal.all(:limit => 2).query.update(:limit => 3).limit # => 3
+    #
+    # @param [Query, Hash] other
+    #   other Query or conditions
+    #
+    # @return [Query]
+    #   self
+    #
+    # @api semipublic
     def update(other)
       assert_kind_of 'other', other, self.class, Hash
 
-      assert_valid_other(other)
+      other_options = if other.kind_of? self.class
+        if self.eql?(other)
+          return self
+        end
+        assert_valid_other(other)
+        other.options
+      else
+        other
+      end
 
-      if other.kind_of?(Hash)
-        return self if other.empty?
-        other = self.class.new(@repository, model, other)
+      unless other_options.empty?
+        options = @options.merge(other_options)
+        if @options[:conditions] and other_options[:conditions]
+          options[:conditions] = @options[:conditions].dup << other_options[:conditions]
+        end
+        initialize(repository, model, options)
       end
 
-      return self if self == other
+      self
+    end
+
+    # Similar to Query#update, but acts on a duplicate.
+    #
+    # @param [Query, Hash] other
+    #   other query to merge with
+    #
+    # @return [Query]
+    #   updated duplicate of original query
+    #
+    # @api semipublic
+    def merge(other)
+      dup.update(other)
+    end
+
+    # Builds and returns new query that merges
+    # original with one given, and slices the result
+    # with respect to :limit and :offset options
+    #
+    # This method is used by Collection to
+    # concatenate options from multiple chained
+    # calls in cases like the following:
+    #
+    # @example
+    #
+    #   author.books.all(:year => 2009).all(:published => false)
+    #
+    # @api semipublic
+    def relative(options)
+      assert_kind_of 'options', options, Hash
+
+      options = options.dup
 
-      # TODO: update this so if "other" had a value explicitly set
-      #       overwrite the attributes in self
+      repository = options.delete(:repository) || self.repository
 
-      # only overwrite the attributes with non-default values
-      @reload       = other.reload?       unless other.reload?       == false
-      @unique       = other.unique?       unless other.unique?       == false
-      @offset       = other.offset        if other.reload? || other.offset != 0
-      @limit        = other.limit         unless other.limit         == nil
-      @order        = other.order         unless other.order         == model.default_order
-      @add_reversed = other.add_reversed? unless other.add_reversed? == false
-      @fields       = other.fields        unless other.fields        == @properties.defaults
-      @links        = other.links         unless other.links         == []
-      @includes     = other.includes      unless other.includes      == []
+      if repository.kind_of?(Symbol)
+        repository = DataMapper.repository(repository)
+      end
 
-      update_conditions(other)
+      if options.key?(:offset) && (options.key?(:limit) || self.limit)
+        offset = options.delete(:offset)
+        limit  = options.delete(:limit) || self.limit - offset
 
-      self
+        self.class.new(repository, model, @options.merge(options)).slice!(offset, limit)
+      else
+        self.class.new(repository, model, @options.merge(options))
+      end
     end
 
-    def merge(other)
-      dup.update(other)
+    # Takes an Enumerable of records, and destructively filters it.
+    # First finds all matching conditions, then sorts it,
+    # then does offset & limit
+    #
+    # @param [Enumerable] records
+    #   The set of records to be filtered
+    #
+    # @return [Enumerable]
+    #   Whats left of the given array after the filtering
+    #
+    # @api semipublic
+    def filter_records(records)
+      records = records.uniq if unique?
+      records = match_records(records)
+      records = sort_records(records)
+      records = limit_records(records)
+      records
     end
 
-    def ==(other)
-      return true if super
-      return false unless other.kind_of?(self.class)
-
-      # TODO: add a #hash method, and then use it in the comparison, eg:
-      #   return hash == other.hash
-      @model        == other.model         &&
-      @reload       == other.reload?       &&
-      @unique       == other.unique?       &&
-      @offset       == other.offset        &&
-      @limit        == other.limit         &&
-      @order        == other.order         &&  # order is significant, so do not sort this
-      @add_reversed == other.add_reversed? &&
-      @fields       == other.fields        &&  # TODO: sort this so even if the order is different, it is equal
-      @links        == other.links         &&  # TODO: sort this so even if the order is different, it is equal
-      @includes     == other.includes      &&  # TODO: sort this so even if the order is different, it is equal
-      @conditions.sort_by { |c| c.at(0).hash + c.at(1).hash + c.at(2).hash } == other.conditions.sort_by { |c| c.at(0).hash + c.at(1).hash + c.at(2).hash }
-    end
-
-    alias eql? ==
-
-    def bind_values
-      bind_values = []
-      conditions.each do |tuple|
-        next if tuple.size == 2
-        operator, property, bind_value = *tuple
-        if :raw == operator
-          bind_values.push(*bind_value)
-        else
-          bind_values << bind_value
+    # Filter a set of records by the conditions
+    #
+    # @param [Enumerable] records
+    #   The set of records to be filtered
+    #
+    # @return [Enumerable]
+    #   Whats left of the given array after the matching
+    #
+    # @api semipublic
+    def match_records(records)
+      records.select do |record|
+        conditions.matches?(record)
+      end
+    end
+
+    # Sorts a list of Records by the order
+    #
+    # @param [Enumerable] records
+    #   A list of Resources to sort
+    #
+    # @return [Enumerable]
+    #   The sorted records
+    #
+    # @api semipublic
+    def sort_records(records)
+      sort_order = order.map { |direction| [ direction.target, direction.operator == :asc ] }
+
+      records.sort_by do |record|
+        sort_order.map do |(property, ascending)|
+          Sort.new(record_value(record, property), ascending)
         end
       end
-      bind_values
     end
 
-    def inheritance_property
-      fields.detect { |property| property.type == DataMapper::Types::Discriminator }
+    # Limits a set of records by the offset and/or limit
+    #
+    # @param [Enumerable] records
+    #   A list of Recrods to sort
+    #
+    # @return [Enumerable]
+    #   The offset & limited records
+    #
+    # @api semipublic
+    def limit_records(records)
+      size = records.size
+
+      if offset > size - 1
+        []
+      elsif (limit && limit != size) || offset > 0
+        records[offset, limit || size] || []
+      else
+        records.dup
+      end
     end
 
-    def inheritance_property_index
-      fields.index(inheritance_property)
+    # Compares another Query for equivalency
+    #
+    # @param [Query] other
+    #   the other Query to compare with
+    #
+    # @return [Boolean]
+    #   true if they are equivalent, false if not
+    #
+    # @api semipublic
+    def ==(other)
+      if equal?(other)
+        return true
+      end
+
+      unless [ :repository, :model, :fields, :links, :conditions, :order, :offset, :limit, :reload?, :unique?, :add_reversed? ].all? { |method| other.respond_to?(method) }
+        return false
+      end
+
+      cmp?(other, :==)
     end
 
-    # TODO: spec this
-    def key_property_indexes(repository)
-      if (key_property_indexes = model.key(repository.name).map { |property| fields.index(property) }).all?
-        key_property_indexes
+    # Compares another Query for equality
+    #
+    # @param [Query] other
+    #   the other Query to compare with
+    #
+    # @return [Boolean]
+    #   true if they are equal, false if not
+    #
+    # @api semipublic
+    def eql?(other)
+      if equal?(other)
+        return true
+      end
+
+      unless instance_of?(other.class)
+        return false
       end
+
+      cmp?(other, :eql?)
     end
 
-    # find the point in self.conditions where the sub select tuple is
-    # located. Delete the tuple and add value.conditions. value must be a
-    # <DM::Query>
+    # Slices collection by adding limit and offset to the
+    # query, so a single query is executed
+    #
+    # @example
+    #
+    #   Journal.all(:limit => 10).slice(3, 5)
     #
-    def merge_subquery(operator, property, value)
-      assert_kind_of 'value', value, self.class
+    # will execute query with the following limit and offset
+    # (when repository uses DataObjects adapter, and thus
+    # queries use SQL):
+    #
+    #   LIMIT 5 OFFSET 3
+    #
+    # @api semipublic
+    def slice(*args)
+      dup.slice!(*args)
+    end
 
-      new_conditions = []
-      conditions.each do |tuple|
-        if tuple.at(0).to_s == operator.to_s && tuple.at(1) == property && tuple.at(2) == value
-          value.conditions.each do |subquery_tuple|
-            new_conditions << subquery_tuple
-          end
-        else
-          new_conditions << tuple
-        end
+    alias [] slice
+
+    # Slices collection by adding limit and offset to the
+    # query, so a single query is executed
+    #
+    # @example
+    #
+    #   Journal.all(:limit => 10).slice!(3, 5)
+    #
+    # will execute query with the following limit
+    # (when repository uses DataObjects adapter, and thus
+    # queries use SQL):
+    #
+    #   LIMIT 10
+    #
+    # and then takes a slice of collection in the Ruby space
+    #
+    # @api semipublic
+    def slice!(*args)
+      offset, limit = extract_slice_arguments(*args)
+
+      if self.limit || self.offset > 0
+        offset, limit = get_relative_position(offset, limit)
       end
-      @conditions = new_conditions
+
+      update(:offset => offset, :limit => limit)
     end
 
+    # Returns detailed human readable
+    # string representation of the query
+    #
+    # @return [String]  detailed string representation of the query
+    #
+    # @api semipublic
     def inspect
       attrs = [
         [ :repository, repository.name ],
@@ -148,529 +572,659 @@ module DataMapper
         [ :unique,     unique?         ],
       ]
 
-      "#<#{self.class.name} #{attrs.map { |(k,v)| "@#{k}=#{v.inspect}" } * ' '}>"
-    end
-
-    # TODO: add docs
-    # @api public
-    def to_hash
-      hash = {
-        :reload       => reload?,
-        :unique       => unique?,
-        :offset       => offset,
-        :order        => order,
-        :add_reversed => add_reversed?,
-        :fields       => fields,
-      }
-
-      hash[:limit]    = limit    unless limit    == nil
-      hash[:links]    = links    unless links    == []
-      hash[:includes] = includes unless includes == []
-
-      conditions  = {}
-      raw_queries = []
-      bind_values = []
-
-      conditions.each do |condition|
-        if condition[0] == :raw
-          raw_queries << condition[1]
-          bind_values << condition[2]
-        else
-          operator, property, bind_value = condition
-          conditions[ Query::Operator.new(property, operator) ] = bind_value
-        end
-      end
-
-      if raw_queries.any?
-        hash[:conditions] = [ raw_queries.join(' ') ].concat(bind_values)
-      end
-
-      hash.update(conditions)
+      "#<#{self.class.name} #{attrs.map { |key, value| "@#{key}=#{value.inspect}" }.join(' ')}>"
     end
 
-    # TODO: add docs
+    # Get the properties used in the conditions
+    #
+    # @return [Set<Property>]
+    #  Set of properties used in the conditions
+    #
     # @api private
-    def _dump(*)
-      Marshal.dump([ repository, model, to_hash ])
-    end
+    def condition_properties
+      properties = Set.new
 
-    # TODO: add docs
-    # @api private
-    def self._load(marshalled)
-      new(*Marshal.load(marshalled))
+      each_comparison do |comparison|
+        properties << comparison.subject if comparison.subject.kind_of?(Property)
+      end
+
+      properties
     end
 
     private
 
+    # Initializes a Query instance
+    #
+    # @example
+    #
+    #  JournalIssue.all(:repository => :medline, :created_on.gte => Date.today - 7)
+    #
+    # initialized a query with repository defined with name :medline,
+    # model JournalIssue and options { :created_on.gte => Date.today - 7 }
+    #
+    # @param [Repository] repository
+    #   the Repository to retrieve results from
+    # @param [Model] model
+    #   the Model to retrieve results from
+    # @param [Hash] options
+    #   the conditions and scope
+    #
+    # @api semipublic
     def initialize(repository, model, options = {})
       assert_kind_of 'repository', repository, Repository
       assert_kind_of 'model',      model,      Model
-      assert_kind_of 'options',    options,    Hash
 
-      options.each_pair { |k,v| options[k] = v.call if v.is_a? Proc } if options.is_a? Hash
+      @repository = repository
+      @model      = model
+      @options    = options.dup.freeze
 
-      assert_valid_options(options)
+      repository_name = repository.name
 
-      @repository = repository
-      @properties = model.properties(@repository.name)
-
-      @model        = model                               # must be Class that includes DM::Resource
-      @reload       = options.fetch :reload,       false  # must be true or false
-      @unique       = options.fetch :unique,       false  # must be true or false
-      @offset       = options.fetch :offset,       0      # must be an Integer greater than or equal to 0
-      @limit        = options.fetch :limit,        nil    # must be an Integer greater than or equal to 1
-      @order        = options.fetch :order,        model.default_order(@repository.name)   # must be an Array of Symbol, DM::Query::Direction or DM::Property
-      @add_reversed = options.fetch :add_reversed, false  # must be true or false
-      @fields       = options.fetch :fields,       @properties.defaults  # must be an Array of Symbol, String or DM::Property
-      @links        = options.fetch :links,        []     # must be an Array of Tuples - Tuple [DM::Query,DM::Assoc::Relationship]
-      @includes     = options.fetch :includes,     []     # must be an Array of DM::Query::Path
-      @conditions   = []                                  # must be an Array of triplets (or pairs when passing in raw String queries)
-
-      # normalize order and fields
-      @order  = normalize_order(@order)
-      @fields = normalize_fields(@fields)
-
-      # XXX: should I validate that each property in @order corresponds
-      # to something in @fields?  Many DB engines require they match,
-      # and I can think of no valid queries where a field would be so
-      # important that you sort on it, but not important enough to
-      # return.
-
-      # normalize links and includes.
-      # NOTE: this must be done after order and fields
-      @links    = normalize_links(@links)
-      @includes = normalize_includes(@includes)
+      @properties    = @model.properties(repository_name)
+      @relationships = @model.relationships(repository_name)
+
+      assert_valid_options(@options)
+
+      @fields       = @options.fetch :fields,       @properties.defaults
+      @links        = @options.fetch :links,        []
+      @conditions   = Conditions::Operation.new(:and)  # AND all the conditions together
+      @offset       = @options.fetch :offset,       0
+      @limit        = @options.fetch :limit,        nil
+      @order        = @options.fetch :order,        @model.default_order(repository_name)
+      @unique       = @options.fetch :unique,       false
+      @add_reversed = @options.fetch :add_reversed, false
+      @reload       = @options.fetch :reload,       false
+      @raw          = false
+
+      @links = @links.dup
 
       # treat all non-options as conditions
-      (options.keys - OPTIONS).each do |k|
-        append_condition(k, options[k])
-      end
+      @options.except(*OPTIONS).each { |kv| append_condition(*kv) }
 
-      # parse raw options[:conditions] differently
-      if conditions = options[:conditions]
-        if conditions.kind_of?(Hash)
-          conditions.each do |k,v|
-            append_condition(k, v)
-          end
-        elsif conditions.kind_of?(Array)
-          raw_query, *bind_values = conditions
-          @conditions << if bind_values.empty?
-            [ :raw, raw_query ]
-          else
-            [ :raw, raw_query, bind_values ]
-          end
-        end
+      # parse @options[:conditions] differently
+      case conditions = @options[:conditions]
+        when Conditions::AbstractOperation, Conditions::AbstractComparison
+          @conditions << conditions
+
+        when Hash
+          conditions.each { |kv| append_condition(*kv) }
+
+        when Array
+          statement, *bind_values = *conditions
+          @conditions << [ statement, bind_values ]
+          @raw = true
       end
+
+      normalize_order
+      normalize_fields
+      normalize_links
     end
 
+    # Copying contructor, called for Query#dup
+    #
+    # @api semipublic
     def initialize_copy(original)
-      # deep-copy the condition tuples when copying the object
-      @conditions = original.conditions.map { |tuple| tuple.dup }
+      initialize(original.repository, original.model, original.options)
     end
 
-    # validate the options
+    # Validate the options
+    #
+    # @param [#each] options
+    #   the options to validate
+    #
+    # @raise [ArgumentError]
+    #   if any pairs in +options+ are invalid options
+    #
+    # @api private
     def assert_valid_options(options)
-      # [DB] This might look more ugly now, but it's 2x as fast as the old code
-      # [DB] This is one of the heavy spots for Query.new I found during profiling.
-      options.each_pair do |attribute, value|
-
-        # validate the reload option and unique option
-        if [:reload, :unique].include? attribute
-          if value != true && value != false
-            raise ArgumentError, "+options[:#{attribute}]+ must be true or false, but was #{value.inspect}", caller(2)
-          end
+      assert_kind_of 'options', options, Hash
+
+      options.each do |attribute, value|
+        case attribute
+          when :fields                         then assert_valid_fields(value, options[:unique])
+          when :links                          then assert_valid_links(value)
+          when :conditions                     then assert_valid_conditions(value)
+          when :offset                         then assert_valid_offset(value, options[:limit])
+          when :limit                          then assert_valid_limit(value)
+          when :order                          then assert_valid_order(value, options[:fields])
+          when :unique, :add_reversed, :reload then assert_valid_boolean("options[:#{attribute}]", value)
+          else
+            assert_valid_conditions(attribute => value)
+        end
+      end
+    end
 
-        # validate the offset and limit options
-        elsif [:offset, :limit].include? attribute
-          assert_kind_of "options[:#{attribute}]", value, Integer
-          if attribute == :offset && value < 0
-            raise ArgumentError, "+options[:offset]+ must be greater than or equal to 0, but was #{value.inspect}", caller(2)
-          elsif attribute == :limit && value < 1
-            raise ArgumentError, "+options[:limit]+ must be greater than or equal to 1, but was #{options[:limit].inspect}", caller(2)
-          end
+    # Verifies that value of :fields option
+    # refers to existing properties
+    #
+    # @api private
+    def assert_valid_fields(fields, unique)
+      assert_kind_of 'options[:fields]', fields, Array
+
+      if fields.empty? && unique == false
+        raise ArgumentError, '+options[:fields]+ should not be empty if +options[:unique]+ is false'
+      end
 
-        # validate the :order, :fields, :links and :includes options
-        elsif [ :order, :fields, :links, :includes ].include? attribute
-          assert_kind_of "options[:#{attribute}]", value, Array
-
-          if value.empty?
-            if attribute == :fields
-              if options[:unique] == false
-                raise ArgumentError, '+options[:fields]+ cannot be empty if +options[:unique] is false', caller(2)
-              end
-            elsif attribute == :order
-              if options[:fields] && options[:fields].any? { |p| !p.kind_of?(Operator) }
-                raise ArgumentError, '+options[:order]+ cannot be empty if +options[:fields] contains a non-operator', caller(2)
-              end
-            else
-              raise ArgumentError, "+options[:#{attribute}]+ cannot be empty", caller(2)
+      fields.each do |field|
+        case field
+          when Symbol, String
+            unless @properties.named?(field)
+              raise ArgumentError, "+options[:fields]+ entry #{field.inspect} does not map to a property in #{model}"
             end
-          end
 
-        # validates the :conditions option
-        elsif :conditions == attribute
-          assert_kind_of 'options[:conditions]', value, Hash, Array
+          when Property
+            unless @properties.include?(field)
+              raise ArgumentError, "+options[:field]+ entry #{field.name.inspect} does not map to a property in #{model}"
+            end
 
-          if value.empty?
-            raise ArgumentError, '+options[:conditions]+ cannot be empty', caller(2)
-          end
+          else
+            raise ArgumentError, "+options[:fields]+ entry #{field.inspect} of an unsupported object #{field.class}"
         end
       end
     end
 
-    # validate other DM::Query or Hash object
-    def assert_valid_other(other)
-      return unless  other.kind_of?(self.class)
+    # Verifies that value of :links option
+    # refers to existing associations
+    #
+    # @api private
+    def assert_valid_links(links)
+      assert_kind_of 'options[:links]', links, Array
 
-      unless other.repository == repository
-        raise ArgumentError, "+other+ #{self.class} must be for the #{repository.name} repository, not #{other.repository.name}", caller(2)
+      if links.empty?
+        raise ArgumentError, '+options[:links]+ should not be empty'
       end
 
-      unless other.model == model
-        raise ArgumentError, "+other+ #{self.class} must be for the #{model.name} model, not #{other.model.name}", caller(2)
+      links.each do |link|
+        case link
+          when Symbol, String
+            unless @relationships.key?(link.to_sym)
+              raise ArgumentError, "+options[:links]+ entry #{link.inspect} does not map to a relationship in #{model}"
+            end
+
+          when Associations::Relationship
+            # TODO: figure out how to validate links from other models
+            #unless @relationships.value?(link)
+            #  raise ArgumentError, "+options[:links]+ entry #{link.name.inspect} does not map to a relationship in #{model}"
+            #end
+
+          else
+            raise ArgumentError, "+options[:links]+ entry #{link.inspect} of an unsupported object #{link.class}"
+        end
       end
     end
 
-    # normalize order elements to DM::Query::Direction
-    def normalize_order(order)
-      order.map do |order_by|
-        case order_by
-          when Direction
-            # NOTE: The property is available via order_by.property
-            # TODO: if the Property's model doesn't match
-            # self.model, append the property's model to @links
-            # eg:
-            #if property.model != self.model
-            #  @links << discover_path_for_property(property)
-            #end
+    # Verifies that value of :conditions option
+    # refers to existing properties
+    #
+    # @api private
+    def assert_valid_conditions(conditions)
+      assert_kind_of 'options[:conditions]', conditions, Conditions::AbstractOperation, Conditions::AbstractComparison, Hash, Array
+
+      case conditions
+        when Hash
+          conditions.each do |subject, bind_value|
+            case subject
+              when Symbol, String
+                unless subject.to_s.include?('.') || @properties.named?(subject) || @relationships.key?(subject)
+                  raise ArgumentError, "condition #{subject.inspect} does not map to a property or relationship in #{model}"
+                end
 
-            order_by
-          when Property
-            # TODO: if the Property's model doesn't match
-            # self.model, append the property's model to @links
-            # eg:
-            #if property.model != self.model
-            #  @links << discover_path_for_property(property)
-            #end
+              when Operator
+                unless (Conditions::Comparison.slugs | [ :not ]).include?(subject.operator)
+                  raise ArgumentError, "condition #{subject.inspect} used an invalid operator #{subject.operator}"
+                end
 
-            Direction.new(order_by)
-          when Operator
-            property = @properties[order_by.target]
-            Direction.new(property, order_by.operator)
-          when Symbol, String
-            property = @properties[order_by]
+                assert_valid_conditions(subject.target => bind_value)
+
+                if subject.operator == :not && bind_value.kind_of?(Array) && bind_value.empty?
+                  raise ArgumentError, "Cannot use 'not' operator with a bind value that is an empty Array for #{subject.inspect}"
+                end
 
-            if property.nil?
-              raise ArgumentError, "+options[:order]+ entry #{order_by} does not map to a DataMapper::Property", caller(2)
+              when Path
+                assert_valid_links(subject.relationships)
+
+              when Associations::Relationship, Property
+                # TODO: validate that it belongs to the current model, or to any
+                # model in the links
+                #unless @properties.include?(subject)
+                #  raise ArgumentError, "condition #{subject.name.inspect} does not map to a property in #{model}"
+                #end
+
+              else
+                raise ArgumentError, "condition #{subject.inspect} of an unsupported object #{subject.class}"
             end
+          end
 
-            Direction.new(property)
-          else
-            raise ArgumentError, "+options[:order]+ entry #{order_by.inspect} not supported", caller(2)
-        end
+        when Array
+          if conditions.empty?
+            raise ArgumentError, '+options[:conditions]+ should not be empty'
+          end
+
+          unless conditions.first.kind_of?(String) && !conditions.first.blank?
+            raise ArgumentError, '+options[:conditions]+ should have a statement for the first entry'
+          end
       end
     end
 
-    # normalize fields to DM::Property
-    def normalize_fields(fields)
-      # TODO: return a PropertySet
-      # TODO: raise an exception if the property is not available in the repository
-      fields.map do |field|
-        case field
-          when Property, Operator
-            # TODO: if the Property's model doesn't match
-            # self.model, append the property's model to @links
-            # eg:
-            #if property.model != self.model
-            #  @links << discover_path_for_property(property)
-            #end
-            field
-          when Symbol, String
-            property = @properties[field]
+    # Verifies that query offset is non-negative and only used together with limit
+    # @api private
+    def assert_valid_offset(offset, limit)
+      assert_kind_of 'options[:offset]', offset, Integer
 
-            if property.nil?
-              raise ArgumentError, "+options[:fields]+ entry #{field} does not map to a DataMapper::Property", caller(2)
-            end
+      unless offset >= 0
+        raise ArgumentError, "+options[:offset]+ must be greater than or equal to 0, but was #{offset.inspect}"
+      end
 
-            property
-          else
-            raise ArgumentError, "+options[:fields]+ entry #{field.inspect} not supported", caller(2)
-        end
+      if offset > 0 && limit.nil?
+        raise ArgumentError, '+options[:offset]+ cannot be greater than 0 if limit is not specified'
       end
     end
 
-    # normalize links to DM::Query::Path
-    def normalize_links(links)
-      # XXX: this should normalize to DM::Query::Path, not DM::Association::Relationship
-      # because a link may be more than one-hop-away from the source.  A DM::Query::Path
-      # should include an Array of Relationship objects that trace the "path" between
-      # the source and the target.
-      links.map do |link|
-        case link
-          when Associations::Relationship
-            link
+    # Verifies the limit is equal to or greater than 0
+    #
+    # @raise [ArgumentError]
+    #   raised if the limit is not an Integer or less than 0
+    #
+    # @api private
+    def assert_valid_limit(limit)
+      assert_kind_of 'options[:limit]', limit, Integer
+
+      unless limit >= 0
+        raise ArgumentError, "+options[:limit]+ must be greater than or equal to 0, but was #{limit.inspect}"
+      end
+    end
+
+    # Verifies that :order option uses proper operator and refers
+    # to existing property
+    #
+    # @api private
+    def assert_valid_order(order, fields)
+      return if order.nil?
+
+      assert_kind_of 'options[:order]', order, Array
+
+      if order.empty? && fields && fields.any? { |property| !property.kind_of?(Operator) }
+        raise ArgumentError, '+options[:order]+ should not be empty if +options[:fields] contains a non-operator'
+      end
+
+      order.each do |order_entry|
+        case order_entry
           when Symbol, String
-            link = link.to_sym if link.kind_of?(String)
+            unless @properties.named?(order_entry)
+              raise ArgumentError, "+options[:order]+ entry #{order_entry.inspect} does not map to a property in #{model}"
+            end
 
-            unless model.relationships(@repository.name).has_key?(link)
-              raise ArgumentError, "+options[:links]+ entry #{link} does not map to a DataMapper::Associations::Relationship", caller(2)
+          when Property
+            unless @properties.include?(order_entry)
+              raise ArgumentError, "+options[:order]+ entry #{order_entry.name.inspect} does not map to a property in #{model}"
             end
 
-            model.relationships(@repository.name)[link]
+          when Operator, Direction
+            unless order_entry.operator == :asc || order_entry.operator == :desc
+              raise ArgumentError, "+options[:order]+ entry #{order_entry.inspect} used an invalid operator #{order_entry.operator}"
+            end
+
+            assert_valid_order([ order_entry.target ], fields)
+
           else
-            raise ArgumentError, "+options[:links]+ entry #{link.inspect} not supported", caller(2)
+            raise ArgumentError, "+options[:order]+ entry #{order_entry.inspect} of an unsupported object #{order_entry.class}"
         end
       end
     end
 
-    # normalize includes to DM::Query::Path
-    def normalize_includes(includes)
-      # TODO: normalize Array of Symbol, String, DM::Property 1-jump-away or DM::Query::Path
-      # NOTE: :includes can only be and array of DM::Query::Path objects now. This method
-      #       can go away after review of what has been done.
-      includes
+    # Used to verify value of boolean properties in conditions
+    # @api private
+    def assert_valid_boolean(name, value)
+      if value != true && value != false
+        raise ArgumentError, "+#{name}+ should be true or false, but was #{value.inspect}"
+      end
     end
 
-    # validate that all the links or includes are present for the given DM::Query::Path
+    # Verifies that associations given in conditions belong
+    # to the same repository as query's model
     #
-    def validate_query_path_links(path)
-      path.relationships.map do |relationship|
-        @links << relationship unless (@links.include?(relationship) || @includes.include?(relationship))
+    # @api private
+    def assert_valid_other(other)
+      unless other.repository == repository
+        raise ArgumentError, "+other+ #{other.class} must be for the #{repository.name} repository, not #{other.repository.name}"
+      end
+
+      unless other.model >= model
+        raise ArgumentError, "+other+ #{other.class} must be for the #{model.name} model, not #{other.model.name}"
       end
     end
 
-    def append_condition(clause, bind_value)
-      operator = :eql
-      bind_value = bind_value.call if bind_value.is_a?(Proc)
+    # Normalize order elements to Query::Direction instances
+    #
+    #   TODO: needs example
+    #
+    # @api private
+    def normalize_order
+      return if @order.nil?
 
-      property = case clause
-        when Property
-          clause
-        when Query::Path
-          validate_query_path_links(clause)
-          clause
-        when Operator
-          operator = clause.operator
-          return if operator == :not && bind_value == []
-          if clause.target.is_a?(Symbol)
-            @properties[clause.target]
-          elsif clause.target.is_a?(Query::Path)
-            validate_query_path_links(clause.target)
-            clause.target
-          end
-        when Symbol
-          @properties[clause]
-        when String
-          if clause =~ /\w\.\w/
-            query_path = @model
-            clause.split(".").each { |piece| query_path = query_path.send(piece) }
-            append_condition(query_path, bind_value)
-            return
-          else
-            @properties[clause]
-          end
-        else
-          raise ArgumentError, "Condition type #{clause.inspect} not supported", caller(2)
-      end
+      # TODO: should Query::Path objects be permitted?  If so, then it
+      # should probably be normalized to a Direction object
+      @order = @order.map do |order|
+        case order
+          when Operator
+            target   = order.target
+            property = target.kind_of?(Property) ? target : @properties[target]
+
+            Direction.new(property, order.operator)
 
-      if property.nil?
-        raise ArgumentError, "Clause #{clause.inspect} does not map to a DataMapper::Property", caller(2)
+          when Symbol, String
+            Direction.new(@properties[order])
+
+          when Property
+            Direction.new(order)
+
+          when Direction
+            order.dup
+        end
       end
+    end
 
-      bind_value = dump_custom_value(property, bind_value)
+    # Normalize fields to Property instances
+    #
+    #   TODO: needs example
+    #
+    # @api private
+    def normalize_fields
+      @fields = @fields.map do |field|
+        case field
+          when Symbol, String
+            @properties[field]
 
-      @conditions << [ operator, property, bind_value ]
+          when Property, Operator
+            field
+        end
+      end
     end
 
-    def dump_custom_value(property_or_path, bind_value)
-      case property_or_path
-      when DataMapper::Query::Path
-        dump_custom_value(property_or_path.property, bind_value)
-      when Property
-        if property_or_path.custom?
-          property_or_path.type.dump(bind_value, property_or_path)
-        else
-          bind_value
+    # Normalize links to Query::Path
+    #
+    # Normalization means links given as symbols are replaced with
+    # relationships they refer to, intermediate links are "followed"
+    # and duplicates are removed
+    #
+    # @api private
+    def normalize_links
+      links = @links.dup
+
+      @links.clear
+
+      while link = links.shift
+        relationship = case link
+          when Symbol, String             then @relationships[link]
+          when Associations::Relationship then link
         end
-      else
-        bind_value
-      end
-    end
-
-    # TODO: check for other mutually exclusive operator + property
-    # combinations.  For example if self's conditions were
-    # [ :gt, :amount, 5 ] and the other's condition is [ :lt, :amount, 2 ]
-    # there is a conflict.  When in conflict the other's conditions
-    # overwrites self's conditions.
-
-    # TODO: Another condition is when the other condition operator is
-    # eql, this should over-write all the like,range and list operators
-    # for the same property, since we are now looking for an exact match.
-    # Vice versa, passing in eql should overwrite all of those operators.
-
-    def update_conditions(other)
-      @conditions = @conditions.dup
-
-      # build an index of conditions by the property and operator to
-      # avoid nested looping
-      conditions_index = {}
-      @conditions.each do |condition|
-        operator, property = *condition
-        next if :raw == operator
-        conditions_index[property] ||= {}
-        conditions_index[property][operator] = condition
-      end
-
-      # loop over each of the other's conditions, and overwrite the
-      # conditions when in conflict
-      other.conditions.each do |other_condition|
-        other_operator, other_property, other_bind_value = *other_condition
-
-        unless :raw == other_operator
-          conditions_index[other_property] ||= {}
-          if condition = conditions_index[other_property][other_operator]
-            operator, property, bind_value = *condition
-
-            next if bind_value == other_bind_value
-
-            # overwrite the bind value in the existing condition
-            condition[2] = case operator
-              when :eql, :like then other_bind_value
-              when :gt,  :gte  then [ bind_value, other_bind_value ].min
-              when :lt,  :lte  then [ bind_value, other_bind_value ].max
-              when :not, :in
-                if bind_value.kind_of?(Array)
-                  bind_value |= other_bind_value
-                elsif other_bind_value.kind_of?(Array)
-                  other_bind_value |= bind_value
-                else
-                  other_bind_value
-                end
+
+        next if @links.include?(relationship)
+
+        if relationship.respond_to?(:links)
+          links.concat(relationship.links)
+        else
+          repository_name = relationship.relative_target_repository_name
+          model           = relationship.target_model
+
+          # TODO: see if this can handle extracting the :order option and sort the
+          # resulting collection using the order specified by through relationships
+
+          model.current_scope.merge(relationship.query).each do |subject, value|
+            # TODO: figure out how to merge Query options from links
+            if OPTIONS.include?(subject)
+              next  # skip for now
             end
 
-            next  # process the next other condition
+            # set @repository when appending conditions
+            original, @repository = @repository, DataMapper.repository(repository_name)
+
+            begin
+              append_condition(subject, value, model)
+            ensure
+              @repository = original
+            end
           end
-        end
 
-        # otherwise append the other condition
-        @conditions << other_condition.dup
+          @links << relationship
+        end
       end
+    end
 
-      @conditions
+    # Append conditions to this Query
+    #
+    #   TODO: needs example
+    #
+    # @param [Property, Symbol, String, Operator, Associations::Relationship, Path] subject
+    #   the subject to match
+    # @param [Object] bind_value
+    #   the value to match on
+    # @param [Symbol] operator
+    #   the operator to match with
+    #
+    # @return [Query::Conditions::AbstractOperation]
+    #   the Query conditions
+    #
+    # @api private
+    def append_condition(subject, bind_value, model = self.model, operator = :eql)
+      case subject
+        when Property, Associations::Relationship then append_property_condition(subject, bind_value, operator)
+        when Symbol                               then append_symbol_condition(subject, bind_value, model, operator)
+        when String                               then append_string_condition(subject, bind_value, model, operator)
+        when Operator                             then append_operator_conditions(subject, bind_value, model)
+        when Path                                 then append_path(subject, bind_value, model, operator)
+        else
+          raise ArgumentError, "#{subject} is an invalid instance: #{subject.class}"
+      end
     end
 
-    class Direction
-      include Assertions
+    # TODO: document
+    # @api private
+    def append_property_condition(property, bind_value, operator)
+      bind_value = normalize_bind_value(property, bind_value)
+      negated    = operator == :not
+
+      if operator == :eql || negated
+        operator = case bind_value
+          when Array, Range, Set, Collection then :in
+          when Regexp                        then :regexp
+          else                                    :eql
+        end
+      end
 
-      attr_reader :property, :direction
+      condition = Conditions::Comparison.new(operator, property, bind_value)
 
-      def ==(other)
-        return true if super
-        hash == other.hash
+      if negated
+        condition = Conditions::Operation.new(:not, condition)
       end
 
-      alias eql? ==
+      @conditions << condition
+    end
+
+    # TODO: document
+    # @api private
+    def append_symbol_condition(symbol, bind_value, model, operator)
+      append_condition(symbol.to_s, bind_value, model, operator)
+    end
+
+    # TODO: document
+    # @api private
+    def append_string_condition(string, bind_value, model, operator)
+      if string.include?('.')
+        query_path = model
+        string.split('.').each { |method| query_path = query_path.send(method) }
+
+        append_condition(query_path, bind_value, model, operator)
+      else
+        repository_name = repository.name
+        subject         = model.properties(repository_name)[string] ||
+                          model.relationships(repository_name)[string]
 
-      def hash
-        @property.hash + @direction.hash
+        append_condition(subject, bind_value, model, operator)
       end
+    end
+
+    # TODO: document
+    # @api private
+    def append_operator_conditions(operator, bind_value, model)
+      append_condition(operator.target, bind_value, model, operator.operator)
+    end
+
+    # TODO: document
+    # @api private
+    def append_path(path, bind_value, model, operator)
+      @links.unshift(*path.relationships.reverse.map { |relationship| relationship.inverse })
+      append_condition(path.property, bind_value, path.model, operator)
+    end
 
-      def reverse
-        self.class.new(@property, @direction == :asc ? :desc : :asc)
+    # TODO: make this typecast all bind values that do not match the
+    # property primitive
+
+    # TODO: document
+    # @api private
+    def normalize_bind_value(property_or_path, bind_value)
+      # TODO: defer this inside the comparison
+      if bind_value.respond_to?(:call)
+        bind_value = bind_value.call
       end
 
-      def inspect
-        "#<#{self.class.name} #{@property.inspect} #{@direction}>"
+      # TODO: bypass this for Collection, once subqueries can be handled by adapters
+      if bind_value.respond_to?(:to_ary)
+        bind_value = bind_value.to_ary
+        bind_value.uniq!
       end
 
-      private
+      # FIXME: causes m:m specs to fail with in-memory adapter
+      # if bind_value.instance_of?(Array) && bind_value.size == 1
+      #   bind_value = bind_value.first
+      # end
 
-      def initialize(property, direction = :asc)
-        assert_kind_of 'property',  property,  Property
-        assert_kind_of 'direction', direction, Symbol
+      bind_value
+    end
 
-        @property  = property
-        @direction = direction
+    # Extract arguments for #slice and #slice! then return offset and limit
+    #
+    # @param [Integer, Array(Integer), Range] *args the offset,
+    #   offset and limit, or range indicating first and last position
+    #
+    # @return [Integer] the offset
+    # @return [Integer, NilClass] the limit, if any
+    #
+    # @api private
+    def extract_slice_arguments(*args)
+      first_arg, second_arg = args
+
+      if args.size == 2 && first_arg.kind_of?(Integer) && second_arg.kind_of?(Integer)
+        return first_arg, second_arg
+      elsif args.size == 1
+        if first_arg.kind_of?(Integer)
+          return first_arg, 1
+        elsif first_arg.kind_of?(Range)
+          offset = first_arg.first
+          limit  = first_arg.last - offset
+          limit += 1 unless first_arg.exclude_end?
+          return offset, limit
+        end
       end
-    end # class Direction
 
-    class Operator
-      include Assertions
+      raise ArgumentError, "arguments may be 1 or 2 Integers, or 1 Range object, was: #{args.inspect}"
+    end
 
-      attr_reader :target, :operator
+    # TODO: document
+    # @api private
+    def get_relative_position(offset, limit)
+      new_offset = self.offset + offset
 
-      def to_sym
-        @property_name
+      if limit <= 0 || (self.limit && new_offset + limit > self.offset + self.limit)
+        raise RangeError, "offset #{offset} and limit #{limit} are outside allowed range"
       end
 
-      def ==(other)
-        return true if super
-        return false unless other.kind_of?(self.class)
-        @operator == other.operator && @target == other.target
+      return new_offset, limit
+    end
+
+    # Return true if +other+'s is equivalent or equal to +self+'s
+    #
+    # @param [Query] other
+    #   The Resource whose attributes are to be compared with +self+'s
+    # @param [Symbol] operator
+    #   The comparison operator to use to compare the attributes
+    #
+    # @return [Boolean]
+    #   The result of the comparison of +other+'s attributes with +self+'s
+    #
+    # @api private
+    def cmp?(other, operator)
+      # check the attributes that are most likely to differ first
+      unless repository.send(operator, other.repository)
+        return false
       end
 
-      private
+      unless model.send(operator, other.model)
+        return false
+      end
 
-      def initialize(target, operator)
-        assert_kind_of 'operator', operator, Symbol
+      unless conditions.send(operator, other.conditions)
+        return false
+      end
 
-        @target   = target
-        @operator = operator
+      unless offset.send(operator, other.offset)
+        return false
       end
-    end # class Operator
 
-    class Path
-      include Assertions
+      unless limit.send(operator, other.limit)
+        return false
+      end
 
-      instance_methods.each { |m| undef_method m if %w[ id type ].include?(m.to_s) }
+      unless order.send(operator, other.order)
+        return false
+      end
 
-      attr_reader :relationships, :model, :property, :operator
+      unless fields.sort_by { |property| property.hash }.send(operator, other.fields.sort_by { |property| property.hash })
+        return false
+      end
 
-      [ :gt, :gte, :lt, :lte, :not, :eql, :like, :in ].each do |sym|
-        class_eval <<-EOS, __FILE__, __LINE__
-          def #{sym}
-            Operator.new(self, :#{sym})
-          end
-        EOS
+      unless links.send(operator, other.links)
+        return false
       end
 
-      # duck type the DM::Query::Path to act like a DM::Property
-      def field(*args)
-        @property ? @property.field(*args) : nil
+      unless reload?.send(operator, other.reload?)
+        return false
       end
 
-      # more duck typing
-      def to_sym
-        @property ? @property.name.to_sym : @model.storage_name(@repository).to_sym
+      unless unique?.send(operator, other.unique?)
+        return false
       end
 
-      private
+      unless add_reversed?.send(operator, other.add_reversed?)
+        return false
+      end
 
-      def initialize(repository, relationships, model, property_name = nil)
-        assert_kind_of 'repository',    repository,    Repository
-        assert_kind_of 'relationships', relationships, Array
-        assert_kind_of 'model',         model,         Model
-        assert_kind_of 'property_name', property_name, Symbol unless property_name.nil?
+      true
+    end
 
-        @repository    = repository
-        @relationships = relationships
-        @model         = model
-        @property      = @model.properties(@repository.name)[property_name] if property_name
+    # TODO: DRY this up with conditions
+    # @api private
+    def record_value(record, property)
+      case record
+        when Hash
+          record.fetch(property, record[property.field])
+        when Resource
+          property.get!(record)
       end
+    end
 
-      def method_missing(method, *args)
-        if relationship = @model.relationships(@repository.name)[method]
-          klass = klass = model == relationship.child_model ? relationship.parent_model : relationship.child_model
-          return Query::Path.new(@repository, @relationships + [ relationship ], klass)
-        end
+    # TODO: document
+    # @api private
+    def each_comparison
+      operands = conditions.operands.dup
 
-        if @model.properties(@repository.name)[method]
-          @property = @model.properties(@repository.name)[method] unless @property
-          return self
+      while operand = operands.shift
+        if operand.respond_to?(:operands)
+          operands.concat(operand.operands)
+        else
+          yield operand
         end
-
-        raise NoMethodError, "undefined property or association `#{method}' on #{@model}"
       end
-    end # class Path
+    end
   end # class Query
 end # module DataMapper