axiom 0.1.0

data/lib/axiom/relation/operation/offset.rb

@@ -0,0 +1,174 @@
+# encoding: utf-8
+
+module Axiom
+  class Relation
+    module Operation
+
+      # A class representing an offset relation
+      class Offset < Relation
+        include Unary
+        include Equalizer.new(:operand, :offset)
+
+        # Return the offset
+        #
+        # @example
+        #   offset = offset_relation.offset
+        #
+        # @return [Integer]
+        #
+        # @api public
+        attr_reader :offset
+
+        # The relation sort order
+        #
+        # @return [Operation::Order::DirectionSet]
+        #
+        # @api private
+        attr_reader :directions
+
+        # Instantiate a new Offset
+        #
+        # @example
+        #   offset_relation = Offset.new(operand, offset)
+        #
+        # @param [Relation] operand
+        #   the relation to offset
+        # @param [Integer] offset
+        #   the offset of the operand to drop
+        #
+        # @return [Offset]
+        #
+        # @api public
+        def self.new(operand, offset)
+          assert_ordered_operand(operand)
+          assert_valid_offset(offset)
+          super
+        end
+
+        # Assert the operand is ordered
+        #
+        # @param [Relation] operand
+        #
+        # @return [undefined]
+        #
+        # @raise [OrderedRelationRequiredError]
+        #   raised if the operand is unordered
+        #
+        # @api private
+        def self.assert_ordered_operand(operand)
+          if operand.header.to_ary.size != operand.directions.to_ary.size
+            raise OrderedRelationRequiredError, 'can only offset an ordered operand'
+          end
+        end
+
+        # Assert the offset is valid
+        #
+        # @param [Integer] offset
+        #
+        # @return [undefined]
+        #
+        # @raise [InvalidOffsetError]
+        #   raised if the offset is less than 0
+        #
+        # @api private
+        def self.assert_valid_offset(offset)
+          if offset.nil? || offset < 0
+            raise InvalidOffsetError, "offset must be greater than or equal to 0, but was #{offset.inspect}"
+          end
+        end
+
+        private_class_method :assert_ordered_operand, :assert_valid_offset
+
+        # Initialize an Offset
+        #
+        # @param [Relation] operand
+        #   the relation to offset
+        # @param [Integer] offset
+        #   the offset of the operand to drop
+        #
+        # @return [undefined]
+        #
+        # @api private
+        def initialize(operand, offset)
+          super(operand)
+          @offset     = offset
+          @directions = operand.directions
+        end
+
+        # Iterate over each tuple in the set
+        #
+        # @example
+        #   offset_relation = Offset.new(operand, offset)
+        #   offset_relation.each { |tuple| ... }
+        #
+        # @yield [tuple]
+        #
+        # @yieldparam [Tuple] tuple
+        #   each tuple in the set
+        #
+        # @return [self]
+        #
+        # @api public
+        def each
+          return to_enum unless block_given?
+          operand.each_with_index do |tuple, index|
+            yield tuple if index >= @offset
+          end
+          self
+        end
+
+        # Raise an exception when inserting into the Offset
+        #
+        # @example
+        #   offset.insert(other)  # => ImmutableRelationError raised
+        #
+        # @return [undefined]
+        #
+        # @raise [ImmutableRelationError]
+        #   raised when inserting into the offset
+        #
+        # @api public
+        def insert(*)
+          raise ImmutableRelationError, 'inserting into an offset is impossible'
+        end
+
+        # Raise an exception when deleting from the Offset
+        #
+        # @example
+        #   offset.delete(other)  # => ImmutableRelationError raised
+        #
+        # @return [undefined]
+        #
+        # @raise [ImmutableRelationError]
+        #   raised when deleting from the offset
+        #
+        # @api public
+        def delete(*)
+          raise ImmutableRelationError, 'deleting from an offset is impossible'
+        end
+
+        module Methods
+
+          # Return a relation with n tuples
+          #
+          # @example
+          #   offset_relation = relation.drop(5)
+          #
+          # @param [Integer] offset
+          #   the offset of the relation to drop
+          #
+          # @return [Offset]
+          #
+          # @api public
+          def drop(offset)
+            Offset.new(self, offset)
+          end
+
+        end # module Methods
+
+        Relation.class_eval { include Methods }
+
+      end # class Offset
+    end # module Operation
+  end # class Relation
+end # module Axiom

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

@@ -0,0 +1,204 @@
+# encoding: utf-8
+
+module Axiom
+  class Relation
+    module Operation
+
+      # A class representing a sorted relation
+      class Order < Relation
+        include Unary
+        include Equalizer.new(:operand, :directions)
+
+        # The relation sort order
+        #
+        # @return [Operation::Order::DirectionSet]
+        #
+        # @api private
+        attr_reader :directions
+
+        # 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 != directions.attributes
+            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
+          return to_enum unless block_given?
+          directions.sort_tuples(operand).each { |tuple| yield tuple }
+          self
+        end
+
+        # Insert a relation into the Order
+        #
+        # @example
+        #   new_relation = order.insert(other)
+        #
+        # @param [Relation] other
+        #
+        # @return [Order]
+        #
+        # @api public
+        def insert(other)
+          assert_matching_directions(other, INSERTED)
+          operand.insert(other.operand).sort_by(directions)
+        end
+
+        # Delete a relation from the Order
+        #
+        # @example
+        #   new_relation = order.delete(other)
+        #
+        # @param [Relation] other
+        #
+        # @return [Order]
+        #
+        # @api public
+        def delete(other)
+          assert_matching_directions(other, DELETED)
+          operand.delete(other.operand).sort_by(directions)
+        end
+
+      private
+
+        # Assert that the other relation has matching directions
+        #
+        # @param [Relation] other
+        #
+        # @param [String] event
+        #
+        # @return [undefined]
+        #
+        # @raise [OrderMismatchError]
+        #   raised when inserting a relation does not have matching directions
+        #
+        # @api private
+        def assert_matching_directions(other, event)
+          unless other.kind_of?(self.class) && directions.eql?(other.directions)
+            raise OrderMismatchError, "other relation must have matching directions to be #{event}"
+          end
+        end
+
+        module Methods
+
+          # Return an ordered relation
+          #
+          # @example with a block
+          #   order = relation.sort_by { |r| [ r.a.desc, r.b ] }
+          #
+          # @example with directions
+          #   order = relation.sort_by(directions)
+          #
+          # @param [Array] args
+          #   optional arguments
+          #
+          # @yield [relation]
+          #   optional block to evaluate for directions
+          #
+          # @yieldparam [Relation] relation
+          #
+          # @yieldreturn [DirectionSet, Array<Direction>, Header]
+          #
+          # @return [Order]
+          #
+          # @api public
+          def sort_by(*args, &block)
+            Order.new(self, coerce_to_directions(*args, &block))
+          end
+
+        private
+
+          # Coerce the arguments and block into directions
+          #
+          # @param [DirectionSet, Array<Direction>, Header] directions
+          #   optional directions
+          #
+          # @yield [relation]
+          #   optional block to evaluate for directions
+          #
+          # @yieldparam [Relation] relation
+          #
+          # @yieldreturn [DirectionSet, Array<Direction>, Header]
+          #
+          # @return [DirectionSet, Array<Direction>, Header]
+          #
+          # @api private
+          def coerce_to_directions(directions = Undefined)
+            if directions.equal?(Undefined)
+              Evaluator::Context.new(header) { |context| yield context }.yield
+            else
+              directions
+            end
+          end
+
+        end # module Methods
+
+        Relation.class_eval { include Methods }
+
+      end # class Order
+    end # module Operation
+  end # class Relation
+end # module Axiom

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

@@ -0,0 +1,182 @@
+# encoding: utf-8
+
+module Axiom
+  class Relation
+    module Operation
+      class Order
+
+        # Abstract base class for attribute sorting
+        class Direction
+          extend Aliasable
+          include AbstractType
+          include Equalizer.new(:attribute)
+
+          inheritable_alias(:== => :eql?)
+
+          # 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
+
+          # Return the attribute name
+          #
+          # @example
+          #   direction.name  # => :id
+          #
+          # @return [Symbol]
+          #
+          # @api public
+          def name
+            attribute.name
+          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)
+            self.class.call(attribute.call(left), attribute.call(right))
+          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)
+            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
+
+          # 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(Attribute.coerce(object))
+          end
+
+        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 Axiom