ardm-core 1.2.1

data/lib/dm-core/support/ordered_set.rb

@@ -0,0 +1,380 @@
+module DataMapper
+
+  # An ordered set of things
+  #
+  # {OrderedSet} implements set behavior and keeps
+  # track of the order in which entries were added.
+  #
+  # {OrderedSet} allows to inject a class that implements
+  # {OrderedSet::Cache::API} at construction time, and will
+  # use that cache implementation to enforce set semantics
+  # and perform internal caching of insertion order.
+  #
+  # @see OrderedSet::Cache::API
+  # @see OrderedSet::Cache
+  # @see SubjectSet::NameCache
+  #
+  # @api private
+  class OrderedSet
+
+    # The default cache used by {OrderedSet}
+    #
+    # Uses a {Hash} as internal storage and enforces set semantics
+    # by calling #eql? and #hash on the set's entries.
+    #
+    # @api private
+    class Cache
+
+      # The default implementation of the {API} that {OrderedSet} expects from
+      # the cache object that it uses to
+      #
+      #     1. keep track of insertion order
+      #     2. enforce set semantics.
+      #
+      # Classes including {API} must customize the behavior of the cache in 2 ways:
+      #
+      # They must determine the value to use as cache key and thus set discriminator,
+      # by implementing the {#key_for} method. The {#key_for} method accepts an arbitrary
+      # object as param and the method is free to return whatever value from that method.
+      # Obviously this will most likely be some attribute or value otherwise derived from
+      # the object that got passed in.
+      #
+      # They must determine which objects are valid set entries by overwriting the
+      # {#valid?} method. The {#valid?} method accepts an arbitrary object as param and
+      # the overwriting method must return either true or false.
+      #
+      # The motivation behind this is that set semantics cannot always be enforced
+      # by calling {#eql?} and {#hash} on the set's entries. For example, two entries
+      # might be considered unique wrt the set if their names are the same, but other
+      # internal state differs. This is exactly the case for {DataMapper::Property} and
+      # {DataMapper::Associations::Relationship} objects.
+      #
+      # @see DataMapper::SubjectSet::NameCache
+      #
+      # @api private
+      module API
+
+        # Initialize a new Cache
+        #
+        # @api private
+        def initialize
+          @cache = {}
+        end
+
+        # Tests if the given entry qualifies to be added to the cache
+        #
+        # @param [Object] entry
+        #   the entry to be checked
+        #
+        # @return [Boolean]
+        #   true if the entry qualifies to be added to the cache
+        #
+        # @api private
+        def valid?(entry)
+          raise NotImplementedError, "#{self}#valid? must be implemented"
+        end
+
+        # Given an entry, return the key to be used in the cache
+        #
+        # @param [Object] entry
+        #   the entry to get the key for
+        #
+        # @return [Object, nil]
+        #   a value derived from the entry that is used as key in the cache
+        #
+        # @api private
+        def key_for(entry)
+          raise NotImplementedError, "#{self}#key_for must be implemented"
+        end
+
+        # Check if the entry exists in the cache
+        #
+        # @param [Object] entry
+        #   the entry to test for
+        #
+        # @return [Boolean]
+        #   true if entry is included in the cache
+        #
+        # @api private
+        def include?(entry)
+          @cache.has_key?(key_for(entry))
+        end
+
+        # Return the index for the entry in the cache
+        #
+        # @param [Object] entry
+        #   the entry to get the index for
+        #
+        # @return [Integer, nil]
+        #   the index for the entry, or nil if it does not exist
+        #
+        # @api private
+        def [](entry)
+          @cache[key_for(entry)]
+        end
+
+        # Set the index for the entry in the cache
+        #
+        # @param [Object] entry
+        #   the entry to set the index for
+        # @param [Integer] index
+        #   the index to assign to the given entry
+        #
+        # @return [Integer]
+        #   the given index for the entry
+        #
+        # @api private
+        def []=(entry, index)
+          if valid?(entry)
+            @cache[key_for(entry)] = index
+          end
+        end
+
+        # Delete an entry from the cache
+        #
+        # @param [Object] entry
+        #   the entry to delete from the cache
+        #
+        # @return [API] self
+        #
+        # @api private
+        def delete(entry)
+          deleted_index = @cache.delete(key_for(entry))
+          if deleted_index
+            @cache.each do |key, index|
+              @cache[key] -= 1 if index > deleted_index
+            end
+          end
+          deleted_index
+        end
+
+        # Removes all entries and returns self
+        #
+        # @return [API] self
+        #
+        # @api private
+        def clear
+          @cache.clear
+          self
+        end
+
+      end # module API
+
+      include API
+
+      # Tests if the given entry qualifies to be added to the cache
+      #
+      # @param [Object] entry
+      #   the entry to be checked
+      #
+      # @return [true] true
+      #
+      # @api private
+      def valid?(entry)
+        true
+      end
+
+      # Given an entry, return the key to be used in the cache
+      #
+      # @param [Object] entry
+      #   the entry to get the key for
+      #
+      # @return [Object]
+      #   the passed in entry
+      #
+      # @api private
+      def key_for(entry)
+        entry
+      end
+
+    end # class Cache
+
+    include Enumerable
+    extend  Equalizer
+
+    # This set's entries
+    #
+    # The order in this Array is not guaranteed
+    # to be the order in which the entries were
+    # inserted. Use #each to access the entries
+    # in insertion order.
+    #
+    # @return [Array]
+    #  this set's entries
+    #
+    # @api private
+    attr_reader :entries
+
+    equalize :entries
+
+    # Initialize an OrderedSet
+    #
+    # @param [#each] entries
+    #   the entries to initialize this set with
+    # @param [Class<Cache::API>] cache
+    #   the cache implementation to use
+    #
+    # @api private
+    def initialize(entries = [], cache = Cache)
+      @cache   = cache.new
+      @entries = []
+      merge(entries.to_ary)
+    end
+
+    # Initialize a copy of OrderedSet
+    #
+    # @api private
+    def initialize_copy(*)
+      @cache   = @cache.dup
+      @entries = @entries.dup
+    end
+
+    # Get the entry at the given index
+    #
+    # @param [Integer] index
+    #   the index of the desired entry
+    #
+    # @return [Object, nil]
+    #   the entry at the given index, or nil if no entry is present
+    #
+    # @api private
+    def [](index)
+      entries[index]
+    end
+
+    # Add or update an entry in the set
+    #
+    # If the entry to add isn't part of the set already,
+    # it will be added. If an entry with the same cache
+    # key as the entry to add is part of the set already,
+    # it will be replaced with the given entry.
+    #
+    # @param [Object] entry
+    #   the entry to be added
+    #
+    # @return [OrderedSet] self
+    #
+    # @api private
+    def <<(entry)
+      if index = @cache[entry]
+        entries[index] = entry
+      else
+        @cache[entry] = size
+        entries << entry
+      end
+      self
+    end
+
+    # Merge with another Enumerable object
+    #
+    # @param [#each] other
+    #   the Enumerable to merge with this OrderedSet
+    #
+    # @return [OrderedSet] self
+    #
+    # @api private
+    def merge(other)
+      other.each { |entry| self << entry }
+      self
+    end
+
+    # Delete an entry from this OrderedSet
+    #
+    # @param [Object] entry
+    #   the entry to delete
+    #
+    # @return [Object, nil]
+    #   the deleted entry or nil
+    #
+    # @api private
+    def delete(entry)
+      if index = @cache.delete(entry)
+        entries.delete_at(index)
+      end
+    end
+
+    # Removes all entries and returns self
+    #
+    # @return [OrderedSet] self
+    #
+    # @api private
+    def clear
+      @cache.clear
+      entries.clear
+      self
+    end
+
+    # Iterate over each entry in the set
+    #
+    # @yield [entry]
+    #   all entries in the set
+    #
+    # @yieldparam [Object] entry
+    #   an entry in the set
+    #
+    # @return [OrderedSet] self
+    #
+    # @api private
+    def each
+      entries.each { |entry| yield(entry) }
+      self
+    end
+
+    # The number of entries
+    #
+    # @return [Integer]
+    #   the number of entries
+    #
+    # @api private
+    def size
+      entries.size
+    end
+
+    # Check if there are any entries
+    #
+    # @return [Boolean]
+    #   true if the set is empty
+    #
+    # @api private
+    def empty?
+      entries.empty?
+    end
+
+    # Check if the entry exists in the set
+    #
+    # @param [Object] entry
+    #   the entry to test for
+    #
+    # @return [Boolean]
+    #   true if entry is included in the set
+    #
+    # @api private
+    def include?(entry)
+      entries.include?(entry)
+    end
+
+    # Return the index for the entry in the set
+    #
+    # @param [Object] entry
+    #   the entry to check the set for
+    #
+    # @return [Integer, nil]
+    #   the index for the entry, or nil if it does not exist
+    #
+    # @api private
+    def index(entry)
+      @cache[entry]
+    end
+
+    # Convert the OrderedSet into an Array
+    #
+    # @return [Array]
+    #   an array containing all the OrderedSet's entries
+    #
+    # @api private
+    def to_ary
+      entries
+    end
+
+  end # class OrderedSet
+end # module DataMapper

data/lib/dm-core/support/subject.rb

@@ -0,0 +1,33 @@
+module DataMapper
+  module Subject
+    # Returns a default value of the subject for given resource
+    #
+    # When default value is a callable object, it is called with resource
+    # and subject passed as arguments.
+    #
+    # @param [Resource] resource
+    #   the model instance for which the default is to be set
+    #
+    # @return [Object]
+    #   the default value of this subject for +resource+
+    #
+    # @api semipublic
+    def default_for(resource)
+      if @default.respond_to?(:call)
+        @default.call(resource, self)
+      else
+        DataMapper::Ext.try_dup(@default)
+      end
+    end
+
+    # Returns true if the subject has a default value
+    #
+    # @return [Boolean]
+    #   true if the subject has a default value
+    #
+    # @api semipublic
+    def default?
+      @options.key?(:default)
+    end
+  end
+end

data/lib/dm-core/support/subject_set.rb

@@ -0,0 +1,250 @@
+module DataMapper
+
+  # An insertion ordered set of named objects
+  #
+  # {SubjectSet} uses {DataMapper::OrderedSet}
+  # under the hood to keep track of a set of
+  # entries. In DataMapper code, a subject
+  # can be either a {DataMapper::Property}, or
+  # a {DataMapper::Associations::Relationship}.
+  #
+  # All entries added to instances of this
+  # class must respond to the {#name} method
+  #
+  # The motivation behind this is that we
+  # use this class as a base to keep track
+  # properties and relationships.
+  # The following constraints apply for these
+  # types of objects: {Property} names must be
+  # unique within any model.
+  # {Associations::Relationship} names must be
+  # unique within any model
+  #
+  # When adding an entry with a name that
+  # already exists, the already existing
+  # entry will be replaced with the new
+  # entry with the same name. This is because
+  # we want to be able to update properties,
+  # and relationship during the course of
+  # initializing our application.
+  #
+  # This also happens to be consistent with
+  # the way ruby handles redefining methods,
+  # where the last definitions "wins".
+  #
+  # Furthermore, the builtin ruby {Set#<<} method
+  # also updates the old object if a new object
+  # gets added.
+  #
+  # @api private
+  class SubjectSet
+
+    # An {OrderedSet::Cache::API} implementation that establishes
+    # set semantics based on the name of its entries. The cache
+    # uses the entries' names as cache key and refuses to add
+    # entries that don't respond_to?(:name).
+    #
+    # @see OrderedSet::Cache::API
+    #
+    # @api private
+    class NameCache
+
+      include OrderedSet::Cache::API
+
+      # Tests if the given entry qualifies to be added to the cache
+      #
+      # @param [#name] entry
+      #   the entry to be checked
+      #
+      # @return [Boolean]
+      #   true if the entry respond_to?(:name)
+      #
+      # @api private
+      def valid?(entry)
+        entry.respond_to?(:name)
+      end
+
+      # Given an entry, return the key to be used in the cache
+      #
+      # @param [#name] entry
+      #   the entry to get the key for
+      #
+      # @return [#to_s, nil]
+      #   the entry's name or nil if the entry isn't #valid?
+      #
+      # @api private
+      def key_for(entry)
+        valid?(entry) ? entry.name : nil
+      end
+
+    end # class NameCache
+
+    include Enumerable
+
+    # The elements in the SubjectSet
+    #
+    # @return [OrderedSet]
+    #
+    # @api private
+    attr_reader :entries
+
+    # Initialize a SubjectSet
+    #
+    # @param [Enumerable<#name>] entries
+    #   the entries to initialize this set with
+    #
+    # @api private
+    def initialize(entries = [])
+      @entries = OrderedSet.new(entries, NameCache)
+    end
+
+    # Initialize a copy of a SubjectSet
+    #
+    # @api private
+    def initialize_copy(*)
+      @entries = @entries.dup
+    end
+
+    # Make sure that entry is part of this SubjectSet
+    #
+    # If an entry with the same name already exists, it
+    # will be updated. If no such named entry exists, it
+    # will be added.
+    #
+    # @param [#name] entry
+    #   the entry to be added
+    #
+    # @return [SubjectSet] self
+    #
+    # @api private
+    def <<(entry)
+      entries << entry
+      self
+    end
+
+    # Delete an entry from this SubjectSet
+    #
+    # @param [#name] entry
+    #   the entry to delete
+    #
+    # @return [#name, nil]
+    #   the deleted entry or nil
+    #
+    # @api private
+    def delete(entry)
+      entries.delete(entry)
+    end
+
+    # Removes all entries and returns self
+    #
+    # @return [SubjectSet] self
+    #
+    # @api private
+    def clear
+      entries.clear
+      self
+    end
+
+    # Test if the given entry is included in this SubjectSet
+    #
+    # @param [#name] entry
+    #   the entry to test for
+    #
+    # @return [Boolean]
+    #   true if the entry is included in this SubjectSet
+    #
+    # @api private
+    def include?(entry)
+      entries.include?(entry)
+    end
+
+    # Tests wether the SubjectSet contains a entry named name
+    #
+    # @param [#to_s] name
+    #   the entry name to test for
+    #
+    # @return [Boolean]
+    #   true if the SubjectSet contains a entry named name
+    #
+    # @api private
+    def named?(name)
+      !self[name].nil?
+    end
+
+    # Check if there are any entries
+    #
+    # @return [Boolean]
+    #   true if the set contains at least one entry
+    #
+    # @api private
+    def empty?
+      entries.empty?
+    end
+
+    # Lookup an entry in the SubjectSet based on a given name
+    #
+    # @param [#to_s] name
+    #   the name of the entry
+    #
+    # @return [Object, nil]
+    #   the entry having the given name, or nil if not found
+    #
+    # @api private
+    def [](name)
+      name = name.to_s
+      entries.detect { |entry| entry.name.to_s == name }
+    end
+
+    # Iterate over each entry in the set
+    #
+    # @yield [entry]
+    #   each entry in the set
+    #
+    # @yieldparam [#name] entry
+    #   an entry in the set
+    #
+    # @return [SubjectSet] self
+    #
+    # @api private
+    def each
+      entries.each { |entry| yield(entry) }
+      self
+    end
+
+    # All entries (or nil values) that have any of the given names
+    #
+    # @param [Enumerable<#to_s>] names
+    #   the names of the desired entries
+    #
+    # @return [Array<#name, nil>]
+    #   an array containing entries whose names match any of the given
+    #   names, or nil values for those names with no matching entries
+    #   in the set
+    #
+    # @api private
+    def values_at(*names)
+      names.map { |name| self[name] }
+    end
+
+    # Get the number of elements inside this SubjectSet
+    #
+    # @return [Integer]
+    #   the number of elements
+    #
+    # @api private
+    def size
+      entries.size
+    end
+
+    # Convert the SubjectSet into an Array
+    #
+    # @return [Array]
+    #   an array containing all the SubjectSet's entries
+    #
+    # @api private
+    def to_ary
+      to_a
+    end
+
+  end # class SubjectSet
+end # module DataMapper