axiom 0.1.0

data/lib/axiom/relation/base.rb

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+module Axiom
+  class Relation
+
+    # A class that represents a base relation
+    class Base < Relation
+      include Equalizer.new(:header, :to_set, :name)
+
+      # The base relation name
+      #
+      # @example
+      #   name = base.name
+      #
+      # @return [#to_s]
+      #
+      # @api public
+      attr_reader :name
+
+      # Initialize a base relation
+      #
+      # @param [#to_s] name
+      #   the relation name
+      # @param [Header, #to_ary] header
+      #   the relation header
+      # @param [Enumerable] tuples
+      #   the relation tuples
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def initialize(name, header, tuples = Empty::ZERO_TUPLE)
+        super(header, tuples)
+        @name = freeze_object(name.to_s)
+      end
+
+    end # class Base
+  end # class Relation
+end # module Axiom

data/lib/axiom/relation/empty.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+module Axiom
+  class Relation
+
+    # An empty relation
+    class Empty < Materialized
+      ZERO_TUPLE = EMPTY_ARRAY
+
+      # Initialize an empty Relation
+      #
+      # @param [Header] _header
+      #   the header for the empty relation
+      # @param [#each] _tuples
+      #   optional original tuples
+      #
+      # @return [undefined]
+      #
+      # @api public
+      def initialize(_header, _tuples = ZERO_TUPLE)
+        super
+      end
+
+      # Noop #each method
+      #
+      # @example
+      #   empty = Empty.new(header)
+      #   empty.each { ... }
+      #
+      # @return [self]
+      #
+      # @api public
+      def each
+        return to_enum unless block_given?
+        self
+      end
+
+      # Return the number of tuples
+      #
+      # @example
+      #   empty.size  # => 0
+      #
+      # @return [0]
+      #
+      # @api public
+      def size
+        0
+      end
+
+    end # class Empty
+  end # class Relation
+end # module Axiom

data/lib/axiom/relation/header.rb

@@ -0,0 +1,349 @@
+# encoding: utf-8
+
+module Axiom
+  class Relation
+
+    # A set of attributes that correspond to values in each tuple
+    class Header
+      extend Aliasable
+      include Enumerable
+      include Equalizer.new(:to_set, :keys)
+
+      inheritable_alias(
+        :[] => :call,
+        :&  => :intersect,
+        :|  => :union,
+        :-  => :difference
+      )
+
+      # The header keys
+      #
+      # @return [Keys]
+      #
+      # @api private
+      attr_reader :keys
+
+      # Coerce an Array-like object into a Header
+      #
+      # @param [Header, #to_ary] object
+      #   the header or attributes
+      # @param [Hash] options
+      #
+      # @yield [attribute]
+      #
+      # @yieldparam [Attribute, Array] attribute
+      #
+      # @return [Header]
+      #
+      # @api private
+      def self.coerce(object, options = EMPTY_HASH)
+        if object.kind_of?(self)
+          object
+        else
+          # Find the attribute with the block if possible, then fallback
+          # to the default coercion method.
+          block = lambda do |attribute|
+            block_given? and yield(attribute) or coerce_attribute(attribute)
+          end
+          new(Array(object).map(&block), options)
+        end
+      end
+
+      # Instantiate a Header
+      #
+      # @example
+      #   header = Header.new(attributes)
+      #
+      # @param [Array<Attribute>] attributes
+      #   optional attributes
+      # @param [Hash] _options
+      #
+      # @return [Header]
+      #
+      # @api public
+      def self.new(attributes = EMPTY_ARRAY, _options = EMPTY_HASH)
+        assert_unique_names(attributes.map(&:name))
+        super
+      end
+
+      # Coerce the attribute into an Attribute
+      #
+      # @param [Object] attribute
+      #
+      # @return [Attribute]
+      #
+      # @api private
+      def self.coerce_attribute(attribute)
+        Attribute.coerce(attribute)
+      end
+
+      # Assert the names are unique
+      #
+      # @param [Array<Symbol>] names
+      #
+      # @return [undefined]
+      #
+      # @raise [DuplicateNameError]
+      #   raised if the names are not unique
+      #
+      # @api private
+      def self.assert_unique_names(names)
+        duplicates = duplicate_names(names)
+        if duplicates
+          raise DuplicateNameError, "duplicate names: #{duplicates.inspect}"
+        end
+      end
+
+      # Returns the duplicate names, if any
+      #
+      # @param [Array<Symbol>] names
+      #
+      # @return [Array<Symbol>]
+      #   returns an array of duplicate names
+      #
+      # @return [nil]
+      #   returns nil if there are no duplicate names
+      #
+      # @api private
+      def self.duplicate_names(names)
+        names.select { |name| names.count(name) > 1 }.uniq!
+      end
+
+      private_class_method :coerce_attribute, :assert_unique_names, :duplicate_names
+
+      # Initialize a Header
+      #
+      # @example
+      #   header = Header.new(attributes, :keys => [ [ :id ] ])
+      #
+      # @param [Array] attributes
+      #
+      # @param [Hash] options
+      #
+      # @return [undefined]
+      #
+      # @api public
+      def initialize(attributes, options)
+        @attributes    = freeze_object(attributes)
+        @options       = freeze_object(options)
+        @attribute_for = Hash[@attributes.map(&:name).zip(@attributes)]
+        @keys          = coerce_keys
+      end
+
+      # Iterate over each attribute in the header
+      #
+      # @example
+      #   header = Header.new(attributes)
+      #   header.each { |attribute| ... }
+      #
+      # @yield [attribute]
+      #
+      # @yieldparam [Attribute] attribute
+      #   each attribute in the header
+      #
+      # @return [self]
+      #
+      # @api public
+      def each
+        return to_enum unless block_given?
+        to_ary.each { |attribute| yield attribute }
+        self
+      end
+
+      # Lookup an attribute in the header given a name
+      #
+      # @example
+      #   attribute = header.call(:id)
+      #
+      # @param [Attribute, #to_ary, #to_sym] name
+      #
+      # @return [Attribute]
+      #   the attribute when the name is known
+      #
+      # @api public
+      def call(name)
+        @attribute_for.fetch(Attribute.name_from(name)) do |attribute_name|
+          raise UnknownAttributeError,
+            "the attribute #{attribute_name} is unknown"
+        end
+      end
+
+      # Return a header with only the attributes specified
+      #
+      # The unique keys intersected with the attributes become the new keys
+      # because a projection strengthens key constraints.
+      #
+      # @example
+      #   projected = header.project(attributes)
+      #
+      # @param [#map] attributes
+      #   the attributes to keep in the header
+      #
+      # @return [Header]
+      #
+      # @api public
+      def project(attributes)
+        coerce(attributes, :keys => keys.project(attributes))
+      end
+
+      # Return a header with the new attributes added
+      #
+      # The original keys from the header are reused because
+      # an extension does not affect key constraints.
+      #
+      # @example
+      #   extended = header.extend(attributes)
+      #
+      # @param [#to_ary] attributes
+      #   the attributes to add to the header
+      #
+      # @return [Header]
+      #
+      # @api public
+      def extend(attributes)
+        new(to_ary + coerce(attributes), :keys => keys)
+      end
+
+      # Return a header with the attributes renamed
+      #
+      # The attributes in the original keys are renamed, but
+      # a rename does not otherwise affect the key constraints.
+      #
+      # @example
+      #   renamed = header.rename(aliases)
+      #
+      # @param [Aliases] aliases
+      #   the old and new attribute names
+      #
+      # @return [Header]
+      #
+      # @api public
+      def rename(aliases)
+        new(
+          map { |attribute| aliases[attribute] },
+          :keys => keys.rename(aliases)
+        )
+      end
+
+      # Return the intersection of the header with another header
+      #
+      # The unique keys from the headers become the new keys because
+      # an intersection strengthens key constraints.
+      #
+      # @example
+      #   intersection = header.intersect(other)
+      #
+      # @param [Header] other
+      #
+      # @return [Header]
+      #
+      # @api public
+      def intersect(other)
+        other      = coerce(other)
+        attributes = to_ary & other
+        new(attributes, :keys => (keys | other.keys).project(attributes))
+      end
+
+      # Return the union of the header with another header
+      #
+      # The common keys from the headers become the new keys because
+      # a union weakens key constraints.
+      #
+      # @example
+      #   union = header.union(other)
+      #
+      # @param [Header] other
+      #
+      # @return [Header]
+      #
+      # @api public
+      def union(other)
+        other = coerce(other)
+        new(to_ary | other, :keys => keys & other.keys)
+      end
+
+      # Return the difference of the header with another header
+      #
+      # The original keys from the header are reused because
+      # a difference does not affect key constraints.
+      #
+      # @example
+      #   difference = header.difference(other)
+      #
+      # @param [Header] other
+      #
+      # @return [Header]
+      #
+      # @api public
+      def difference(other)
+        other = coerce(other)
+        new(to_ary - other, :keys => keys - other.keys)
+      end
+
+      # Convert the Header into an Array
+      #
+      # @example
+      #   array = header.to_ary
+      #
+      # @return [Array]
+      #
+      # @api public
+      def to_ary
+        @attributes
+      end
+
+      # Test if there are no attributes
+      #
+      # @example
+      #   header.empty?  # => true or false
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def empty?
+        to_ary.empty?
+      end
+
+    private
+
+      # Utility method to instantiate a Header
+      #
+      # @param [Array] args
+      #
+      # @return [Header]
+      #
+      # @api private
+      def new(*args)
+        self.class.new(*args)
+      end
+
+      # Coerce the keys into an Array of Headers
+      #
+      # @return [Array<Header>]
+      #
+      # @api private
+      def coerce_keys
+        Keys.coerce(@options.fetch(:keys, EMPTY_ARRAY)) do |attributes|
+          coerce(attributes)
+        end
+      end
+
+      # Coerce the object into a Header
+      #
+      # @param [Array] args
+      #
+      # @return [Header]
+      #
+      # @api private
+      def coerce(*args)
+        self.class.coerce(*args) do |attribute|
+          @attribute_for[attribute]
+        end
+      end
+
+      # Represent an empty set of attributes
+      EMPTY = new
+
+    end # class Header
+  end # class Relation
+end # module Axiom

data/lib/axiom/relation/keys.rb

@@ -0,0 +1,282 @@
+# encoding: utf-8
+
+module Axiom
+  class Relation
+
+    # A set of keys in a Header
+    class Keys
+      extend Aliasable
+      include Enumerable
+      include Equalizer.new(:to_set)
+
+      inheritable_alias(
+        :& => :intersect,
+        :| => :union,
+        :- => :difference
+      )
+
+      # Coerce an Array-like object into Keys
+      #
+      # @param [Keys, #to_ary] object
+      #
+      # @yield [attributes]
+      #
+      # @yieldparam [Header, Array] attributes
+      #   the attributes in each key
+      #
+      # @return [Keys]
+      #
+      # @api private
+      def self.coerce(object, &block)
+        if object.kind_of?(self)
+          object
+        else
+          block ||= lambda { |attributes| coerce_attributes(attributes) }
+          new(object.map(&block))
+        end
+      end
+
+      # Instantiate Keys
+      #
+      # @example
+      #   keys = Keys.new(keys)
+      #
+      # @param [Array<Header>] keys
+      #
+      # @return [Keys]
+      #
+      # @api public
+      def self.new(keys = EMPTY_ARRAY)
+        assert_irreducible_keys(keys.map(&:to_set))
+        super
+      end
+
+      # Coerce the attributes into a Header
+      #
+      # @param [Object] attributes
+      #
+      # @return [Header]
+      #
+      # @api private
+      def self.coerce_attributes(attributes)
+        Header.coerce(attributes)
+      end
+
+      # Assert the keys are irreducible
+      #
+      # In a relation a candidate key must be irreducible, which means that
+      # there can't exist another key that is a proper subset of it. If this
+      # occurs, we should raise an exception because it means there is a
+      # specification error in the system.
+      #
+      # @param [Array<Set>] keys
+      #
+      # @return [undefined]
+      #
+      # @raise [ReducibleKeyError]
+      #   raised if a key can be reduced
+      #
+      # @api private
+      def self.assert_irreducible_keys(keys)
+        reducible_keys = reducible_keys(keys)
+        if reducible_keys
+          raise ReducibleKeyError, "reducible keys: #{reducible_keys.inspect}"
+        end
+      end
+
+      # The keys that can be reduced
+      #
+      # @param [Array<Header>] keys
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      def self.reducible_keys(keys)
+        keys.permutation(2).select { |key, other| key.proper_superset?(other) }.
+          transpose.first
+      end
+
+      private_class_method :coerce_attributes, :assert_irreducible_keys, :reducible_keys
+
+      # Initialize Keys
+      #
+      # @example
+      #   keys = Keys.new([ [ :id ] ])
+      #
+      # @param [Array<Header>] keys
+      #
+      # @return [undefined]
+      #
+      # @api public
+      def initialize(keys)
+        @keys = freeze_object(keys)
+      end
+
+      # Iterate over each key in the Keys
+      #
+      # @example
+      #   keys = Keys.new(keys)
+      #   keys.each { |key| ... }
+      #
+      # @yield [key]
+      #
+      # @yieldparam [Header] key
+      #
+      # @return [self]
+      #
+      # @api public
+      def each
+        return to_enum unless block_given?
+        to_ary.each { |key| yield key }
+        self
+      end
+
+      # Return keys with only the attributes specified
+      #
+      # When the attributes do not match any attributes in an existing
+      # key, then the key should be removed because it means the attributes
+      # it applied against no longer exist in the new header.
+      #
+      # @example
+      #   projected = keys.project(attributes)
+      #
+      # @param [#map] attributes
+      #   the attributes to keep in the keys
+      #
+      # @return [Keys]
+      #
+      # @api public
+      def project(attributes)
+        new(map { |key| key & attributes }.delete_if(&:empty?))
+      end
+
+      # Return keys with the new attributes added
+      #
+      # @example
+      #   extended = keys.extend(attributes)
+      #
+      # @param [#to_ary] attributes
+      #   the attributes to add to the keys
+      #
+      # @return [Keys]
+      #
+      # @api public
+      def extend(attributes)
+        if empty?
+          coerce(attributes)
+        else
+          new(map { |key| key | attributes })
+        end
+      end
+
+      # Return keys with the attributes renamed
+      #
+      # @example
+      #   renamed = keys.rename(aliases)
+      #
+      # @param [Aliases] aliases
+      #   the old and new attribute names
+      #
+      # @return [Keys]
+      #
+      # @api public
+      def rename(aliases)
+        new(map { |key| key.rename(aliases) })
+      end
+
+      # Return the intersection of the keys with other keys
+      #
+      # @example
+      #   intersection = keys.intersect(other)
+      #
+      # @param [Keys] other
+      #
+      # @return [Keys]
+      #
+      # @api public
+      def intersect(other)
+        new(to_ary & other)
+      end
+
+      # Return the union of the keys with other keys
+      #
+      # @example
+      #   union = keys.union(other)
+      #
+      # @param [Keys] other
+      #
+      # @return [Keys]
+      #
+      # @api public
+      def union(other)
+        new(to_ary | other)
+      end
+
+      # Return the difference of the keys with other keys
+      #
+      # @example
+      #   difference = keys.difference(other)
+      #
+      # @param [Keys] other
+      #
+      # @return [Keys]
+      #
+      # @api public
+      def difference(other)
+        new(to_ary - other)
+      end
+
+      # Convert the Keys into an Array
+      #
+      # @example
+      #   array = keys.to_ary
+      #
+      # @return [Array]
+      #
+      # @api public
+      def to_ary
+        @keys
+      end
+
+      # Test if there are no keys
+      #
+      # @example
+      #   keys.empty?  # => true or false
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def empty?
+        to_ary.empty?
+      end
+
+    private
+
+      # Utility method to instantiate Keys
+      #
+      # @param [Array] keys
+      #
+      # @return [Keys]
+      #
+      # @api private
+      def new(keys)
+        to_ary == keys ? self : self.class.new(keys)
+      end
+
+      # Coerce the object into Keys
+      #
+      # @param [Keys, #to_ary] object
+      #
+      # @return [Keys]
+      #
+      # @api private
+      def coerce(object)
+        self.class.coerce(object)
+      end
+
+      # Represent an empty set of keys
+      EMPTY = new
+
+    end # class Keys
+  end # class Relation
+end # module Axiom