veritas 0.0.1

data/lib/veritas/relation/operation/order/direction.rb

@@ -0,0 +1,209 @@
+module Veritas
+  class Relation
+    module Operation
+      class Order
+
+        # Abstract base class for attribute sorting
+        class Direction
+          include AbstractClass, Immutable
+
+          # The attribute to sort on
+          #
+          # @return [Attribute]
+          #
+          # @api private
+          attr_reader :attribute
+
+          # Initialize a Direction
+          #
+          # @param [Attribute] attribute
+          #   the attribute to sort on
+          #
+          # @return [undefined]
+          #
+          # @api private
+          def initialize(attribute)
+            @attribute = attribute
+          end
+
+          # Compare the left and right Tuple attribute values
+          #
+          # @example
+          #   comparison = direction.call(left, right)
+          #
+          # @param [Tuple] left
+          # @param [Tuple] right
+          #
+          # @return [-1]
+          #   returned if the left should be sorted before the right
+          #
+          # @return [0]
+          #   returned if the left and right are equal
+          #
+          # @return [1]
+          #   returned if the left should be sorted after the right
+          #
+          # @api public
+          def call(left, right)
+            attribute = self.attribute
+            self.class.call(left[attribute], right[attribute])
+          end
+
+          # Rename the contained attribute with the provided aliases
+          #
+          # @example
+          #   renamed = direction.rename(aliases)
+          #
+          # @param [Algebra::Rename::Aliases] aliases
+          #   the old and new attributes
+          #
+          # @return [self]
+          #   if the attribute is not renamed
+          # @return [Direction]
+          #   if the attribute is renamed
+          #
+          # @api public
+          def rename(aliases)
+            attribute = self.attribute
+            renamed   = aliases[attribute]
+            renamed.equal?(attribute) ? self : self.class.new(renamed)
+          end
+
+          # Return the reverse Direction
+          #
+          # @example
+          #   reversed = direction.reverse
+          #
+          # @return [Direction]
+          #
+          # @api public
+          def reverse
+            self.class.reverse.new(attribute)
+          end
+
+          # Compare the direction with other direction for equivalency
+          #
+          # @example
+          #   direction == other  # => true or false
+          #
+          # @param [Direction] other
+          #
+          # @return [Boolean]
+          #
+          # @api public
+          def ==(other)
+            eql?(other)
+          end
+
+          # Compare the direction with other direction for equality
+          #
+          # @example
+          #   direction.eql?(other)  # => true or false
+          #
+          # @param [Direction] other
+          #
+          # @return [Boolean]
+          #
+          # @api public
+          def eql?(other)
+            instance_of?(other.class) &&
+            attribute.eql?(other.attribute)
+          end
+
+          # Return the hash of the direction
+          #
+          # @example
+          #   numeric_hash = direction.hash
+          #
+          # @return [Integer]
+          #
+          # @api public
+          def hash
+            attribute.hash
+          end
+
+          # Coerce an object into a Direction
+          #
+          # @param [Attribute, Direction] object
+          #   the object to coerce
+          #
+          # @return [Direction]
+          #
+          # @api private
+          def self.coerce(object)
+            object.kind_of?(Direction) ? object : new(object)
+          end
+
+          memoize :hash
+
+        end # class Direction
+
+        # Represent an attribute sorted ascending
+        class Ascending < Direction
+
+          # Return the reversed direction class
+          #
+          # @return [Class<Descending>]
+          #
+          # @api private
+          def self.reverse
+            Descending
+          end
+
+          # Compare the left and right value
+          #
+          # @param [Comparable] left
+          # @param [Comparable] right
+          #
+          # @return [-1]
+          #   returned if the left should be sorted before the right
+          #
+          # @return [0]
+          #   returned if the left and right are equal
+          #
+          # @return [1]
+          #   returned if the left should be sorted after the right
+          #
+          # @api private
+          def self.call(left, right)
+            left <=> right
+          end
+
+        end # class Ascending
+
+        # Represent an attribute sorted descending
+        class Descending < Direction
+
+          # Return the reversed direction class
+          #
+          # @return [Class<Ascending>]
+          #
+          # @api private
+          def self.reverse
+            Ascending
+          end
+
+          # Compare the left and right value
+          #
+          # @param [Comparable] left
+          # @param [Comparable] right
+          #
+          # @return [-1]
+          #   returned if the left should be sorted after the right
+          #
+          # @return [0]
+          #   returned if the right and left are equal
+          #
+          # @return [1]
+          #   returned if the left should be sorted before the right
+          #
+          # @api private
+          def self.call(left, right)
+            right <=> left
+          end
+
+        end # class Descending
+      end # class Order
+    end # module Operation
+  end # class Relation
+end # module Veritas

data/lib/veritas/relation/operation/order/direction_set.rb

@@ -0,0 +1,246 @@
+module Veritas
+  class Relation
+    module Operation
+      class Order
+
+        # A class that represents a tuple sort order for a set of attributes
+        class DirectionSet
+          extend Aliasable
+          include Enumerable, Immutable
+
+          inheritable_alias(:| => :union)
+
+          # Initialize a DirectionSet
+          #
+          # @param [Array<Direction, Attribute>] attribute
+          #   the attribute to sort on
+          #
+          # @return [undefined]
+          #
+          # @api private
+          def initialize(directions)
+            @directions = directions.to_ary.map do |direction|
+              Ascending.coerce(direction)
+            end
+          end
+
+          EMPTY = new([])
+
+          # Return a direction set with only the attributes specified
+          #
+          # @example
+          #   projected = directions.project([ attribute ])
+          #
+          # @param [Array<Attribute>] attributes
+          #   the attributes to keep in the direction set
+          #
+          # @return [DirectionSet]
+          #
+          # @api public
+          def project(attributes)
+            new select { |direction|
+              attributes.include?(direction.attribute)
+            }
+          end
+
+          # Rename the contained attributes with the provided aliases
+          #
+          # @example
+          #   renamed = directions.rename(aliases)
+          #
+          # @param [Algebra::Rename::Aliases] aliases
+          #   the old and new attributes
+          #
+          # @return [DirectionSet]
+          #
+          # @api public
+          def rename(aliases)
+            new(map { |direction| direction.rename(aliases) })
+          end
+
+          # Reverse the directions for each attribute
+          #
+          # @example
+          #   reversed = directions.reverse
+          #
+          # @return [DirectionSet]
+          #
+          # @api public
+          def reverse
+            new(map { |direction| direction.reverse })
+          end
+
+          # Iterate over each direction in the set
+          #
+          # @example
+          #   directions = DirectionSet.new(directions)
+          #   directions.each { |direction| ... }
+          #
+          # @yield [direction]
+          #
+          # @yieldparam [Direction] direction
+          #   each direction in the set
+          #
+          # @return [self]
+          #
+          # @api public
+          def each(&block)
+            to_ary.each(&block)
+            self
+          end
+
+          # Return the directions as an Array
+          #
+          # @return [Array]
+          #
+          # @api private
+          def to_ary
+            @directions
+          end
+
+          # Union the directions with another set of directions
+          #
+          # @example
+          #   union = directions.union(other)
+          #
+          # @param [DirectionSet] other
+          #   the directions to union with
+          #
+          # @return [DirectionSet]
+          #
+          # @api public
+          def union(other)
+            new(to_ary | other.to_ary)
+          end
+
+          # Return each attribute in an Array
+          #
+          # @return [Array]
+          #
+          # @api private
+          def attributes
+            map { |direction| direction.attribute }
+          end
+
+          # Sort the supplied tuples in the correct direction
+          #
+          # @param [Array] tuples
+          #   the list of tuples to sort
+          #
+          # @return [Array]
+          #   the sorted tuples
+          #
+          # @api private
+          def sort_tuples(tuples)
+            tuples.sort { |left, right| cmp_tuples(left, right) }
+          end
+
+          # Compare the directions with other directions for equivalency
+          #
+          # @example
+          #   directions == other  # => true or false
+          #
+          # @param [DirectionSet] other
+          #   the other directions to compare with
+          #
+          # @return [Boolean]
+          #
+          # @api public
+          def ==(other)
+            other = self.class.coerce(other)
+            to_ary == other.to_ary
+          end
+
+          # Compare the directions with other directions for equality
+          #
+          # @example
+          #   directions.eql?(other)  # => true or false
+          #
+          # @param [DirectionSet] other
+          #   the other directions to compare with
+          #
+          # @return [Boolean]
+          #
+          # @api public
+          def eql?(other)
+            instance_of?(other.class) &&
+            to_ary.eql?(other.to_ary)
+          end
+
+          # Return the hash of the aliases
+          #
+          # @example
+          #   numeric_hash = directions.hash
+          #
+          # @return [Integer]
+          #
+          # @api public
+          def hash
+            to_ary.hash
+          end
+
+          # Test if there are no directions
+          #
+          # @example
+          #   directions.empty?  # => true or false
+          #
+          # @return [Boolean]
+          #
+          # @api public
+          def empty?
+            @directions.empty?
+          end
+
+        private
+
+          # Utility method for initializing a set of directions
+          #
+          # @param [Array<Direction>] directions
+          #
+          # @return [DirectionSet]
+          #
+          # @api private
+          def new(directions)
+            self.class.new(directions)
+          end
+
+          # Compare the attributes for each Tuple
+          #
+          # @param [Tuple] left
+          # @param [Tuple] right
+          #
+          # @return [-1]
+          #   returned if the left should be sorted before the right
+          #
+          # @return [0]
+          #   returned if the left and right are equal
+          #
+          # @return [1]
+          #   returned if the left should be sorted after the right
+          #
+          # @api private
+          def cmp_tuples(left, right)
+            reduce(0) do |cmp, direction|
+              break cmp if cmp.nonzero?
+              direction.call(left, right)
+            end
+          end
+
+          # Coerce directions into a DirectionSet
+          #
+          # @param [DirectionSet, Array<Direction, Attribute>]
+          #
+          # @return [DirectionSet]
+          #
+          # @api private
+          def self.coerce(object)
+            object.kind_of?(DirectionSet) ? object : new(object)
+          end
+
+          memoize :hash
+
+        end # class DirectionSet
+      end # class Order
+    end # module Operation
+  end # class Relation
+end # module Veritas

data/lib/veritas/relation/operation/order.rb

@@ -0,0 +1,138 @@
+module Veritas
+  class Relation
+    module Operation
+
+      # A class representing a sorted relation
+      class Order < Relation
+        include Unary
+
+        # Instantiate a new Order
+        #
+        # @example
+        #   order = Order.new(operand, directions)
+        #
+        # @param [Relation] operand
+        #   the relation to sort
+        # @param [DirectionSet, Array<Direction, Attribute>] directions
+        #   the directions to sort tuples in
+        #
+        # @return [Order]
+        #
+        # @api public
+        def self.new(operand, directions)
+          directions = DirectionSet.coerce(directions)
+          assert_order_by_full_header(operand, directions)
+          super
+        end
+
+        # Assert the full header is sorted on
+        #
+        # Sorting on the full header ensures deterministic results,
+        # which is necessary for ordering to be useful.
+        #
+        # @param [Relation] operand
+        # @param [#attributes] directions
+        #
+        # @return [undefined]
+        #
+        # @raise [InvalidDirectionsError]
+        #   raised if the full header is not sorted on
+        #
+        # @api private
+        def self.assert_order_by_full_header(operand, directions)
+          if operand.header.to_set != directions.attributes.to_set
+            raise InvalidDirectionsError, 'directions must include every attribute in the header'
+          end
+        end
+
+        private_class_method :assert_order_by_full_header
+
+        # Initialize an Order
+        #
+        # @param [Relation] operand
+        #   the relation to sort
+        # @param [DirectionSet, Array<Direction, Attribute>] directions
+        #   the directions to sort tuples in
+        #
+        # @return [undefined]
+        #
+        # @api private
+        def initialize(operand, directions)
+          super(operand)
+          @directions = directions
+        end
+
+        # Iterate over each tuple in the set
+        #
+        # @example
+        #   order = Order.new(operand, directions)
+        #   order.each { |tuple| ... }
+        #
+        # @yield [tuple]
+        #
+        # @yieldparam [Tuple] tuple
+        #   each tuple in the set
+        #
+        # @return [self]
+        #
+        # @api public
+        def each(&block)
+          directions.sort_tuples(operand).each(&block)
+          self
+        end
+
+        # Compare the Order with other relation for equality
+        #
+        # @example
+        #   order.eql?(other)  # => true or false
+        #
+        # @param [Relation] other
+        #   the other relation to compare with
+        #
+        # @return [Boolean]
+        #
+        # @api public
+        def eql?(other)
+          instance_of?(other.class)         &&
+          directions.eql?(other.directions) &&
+          operand.eql?(other.operand)
+        end
+
+      private
+
+        module Methods
+
+          # Return an ordered relation
+          #
+          # @example with no directions
+          #   order = relation.order  # sort by the header
+          #
+          # @example with directions
+          #   order = relation.order([ relation[:a].desc, relation[:b] ])
+          #
+          # @example with a block
+          #   order = relation.order { |r| [ r[:a].desc, r[:b] ] }
+          #
+          # @yield [relation]
+          #   optional block to evaluate for directions
+          #
+          # @yieldparam [Relation] relation
+          #
+          # @return [Order]
+          #
+          # @api public
+          def order(directions = block_given? ? yield(self) : header)
+            Order.new(self, Array(directions))
+          end
+
+        end # module Methods
+
+        Relation.class_eval { include Methods }
+
+      end # class Order
+    end # module Operation
+  end # class Relation
+end # module Veritas
+
+require 'veritas/relation/operation/order/direction'
+require 'veritas/relation/operation/order/direction_set'

data/lib/veritas/relation/operation/reverse.rb

@@ -0,0 +1,85 @@
+module Veritas
+  class Relation
+    module Operation
+
+      # A class representing a reverse sorted relation
+      class Reverse < Order
+
+        # Instantiate a new Reverse relation
+        #
+        # @example
+        #   reverse = Reverse.new(operand)
+        #
+        # @param [Relation] operand
+        #
+        # @return [Reverse]
+        #
+        # @api public
+        def self.new(operand)
+          assert_ordered_operand(operand)
+          super(operand, operand.directions.reverse)
+        end
+
+        # Assert the operand is ordered
+        #
+        # @param [Relation] operand
+        #
+        # @return [undefined]
+        #
+        # @raise [OrderedRelationRequiredError]
+        #   raise if the operand is unordered
+        #
+        # @api private
+        def self.assert_ordered_operand(operand)
+          if operand.directions.empty?
+            raise OrderedRelationRequiredError, 'can only reverse an ordered operand'
+          end
+        end
+
+        private_class_method :assert_ordered_operand
+
+        # Iterate over each tuple in the set
+        #
+        # @example
+        #   reverse = Reverse.new(operand)
+        #   reverse.each { |tuple| ... }
+        #
+        # @yield [tuple]
+        #
+        # @yieldparam [Tuple] tuple
+        #   each tuple in the set
+        #
+        # @return [self]
+        #
+        # @api public
+        def each(&block)
+          operand.reverse_each(&block)
+          self
+        end
+
+      private
+
+        module Methods
+
+          # Return the reversed relation
+          #
+          # @example
+          #   reverse = relation.reverse
+          #
+          # @param [Relation] other
+          #
+          # @return [Reverse]
+          #
+          # @api public
+          def reverse
+            Reverse.new(self)
+          end
+
+        end # module Methods
+
+        Relation.class_eval { include Methods }
+
+      end # class Limit
+    end # module Operation
+  end # class Relation
+end # module Veritas