gorillib 0.4.1pre → 0.4.2pre

data/lib/gorillib/collection.rb

@@ -4,73 +4,116 @@ require 'gorillib/metaprogramming/class_attribute'
 module Gorillib
 
   #
-  # A generic collection stores objects uniquely, in the order added. It responds to:
+  # The Collection class encapsulates the minimum functionality to let you:
+  #
+  # * store items uniquely, in order added
+  # * retrieve items by label
+  # * iterate over its values
+  #
+  # A collection is best used for representing 'plural' properties of models; it
+  # is *not* intended to be some radical reimagining of a generic array or
+  # hash. We've found its locked-down capabilities to particularly useful for
+  # constructing DSLs (Domain-Specific Languages). Collections are *not*
+  # intended to be performant: its abstraction layer comes at the price of
+  # additional method calls.
+  #
+  # ### Gated admission
+  #
+  # Collection provides a well-defended perimeter. Every item added to the
+  # collection (whether sent to the initializer, the  passes through `add` method
+  #
+  # ### Familiarity with its contents
+  #
+  # Typically your model will have a familiar (but not intimate) relationship
+  # with its plural property:
+  #
+  # * items may have some intrinsic, uniquely-identifying feature: a `name`,
+  #   `id`, or normalized representation. You'd like to be able to add an
+  #   retrieve them by that intrinsic feature without having to manually juggle
+  #   the correspondence of labels to intrinsic features.
+  #
+  # In the case of a ModelCollection,
+  #
+  # * all its items may share a common type: "a post has many `Comment`s".
+  #
+  # * a model may want items to hold a reference back to the containing model,
+  #   or otherwise to share some common attributes. As an example, a `Graph` may
+  #   have many `Stage` objects; the collection can inform newly-added stages
+  #   which graph they belong to.
+  #
+  # ### Barebones enumerable methods
+  #
+  # The set of methods is purposefully sparse. If you want to use `select`,
+  # `invert`, etc, just invoke `to_hash` or `to_a` and work with the copy it
+  # gives you.
+  #
+  # Collection responds to:
   #   - receive!, values, to_a, each and each_value;
   #   - length, size, empty?, blank?
-  #
-  # A Collection additionally lets you store and retrieve things by label:
   #   - [], []=, include?, fetch, delete, each_pair, to_hash.
+  #   - `key_method`: called on items to get their key; `to_key` by default.
+  #   - `<<`: adds item under its `key_method` key
+  #   - `receive!`s an array by auto-keying the elements, or a hash by trusting what you give it
   #
   # A ModelCollection adds:
-  #   - `key_method`: called on objects to get their key; `to_key` by default.
-  #   - `factory`: generates new objects, converts received objects
-  #   - `<<`: adds object under its `key_method` key
-  #   - `receive!`s an array by auto-keying the elements, or a hash by trusting what you give it
-  #   - `update_or_create: if absent, creates object with given attributes and
+  #   - `factory`: generates new items, converts received items
+  #   - `update_or_create: if absent, creates item with given attributes and
   #     `key_method => key`; if present, updates with given attributes.
   #
-  class GenericCollection
-    # [{Symbol => Object}] The actual store of items, but not for you to mess with
+  #
+  class Collection
+    # [{Symbol => Object}] The actual store of items -- not for you to mess with
     attr_reader :clxn
     protected   :clxn
 
-    def self.receive(items, *args)
-      coll = new(*args)
-      coll.receive!(items)
-      coll
-    end
+    # Object that owns this collection, if any
+    attr_reader :belongs_to
 
-    delegate :length, :size, :empty?, :blank?, :to => :clxn
+    # [String, Symbol] Method invoked on a new item to generate its collection key; :to_key by default
+    class_attribute :key_method, :instance_writer => false
+    singleton_class.send(:protected, :key_method=)
 
-    # Two collections are equal if they have the same class and their contents are equal
-    #
-    # @param [Gorillib::Collection, Object] other The other collection to compare
-    # @return [true, false] True if attributes are equal and other is instance of the same Class
-    def ==(other)
-      return false unless other.instance_of?(self.class)
-      clxn == other.send(:clxn)
+    # include Gorillib::Model
+    def initialize(options={})
+      @clxn       = Hash.new
+      @key_method = options[:key_method] if options[:key_method]
+      @belongs_to = options[:belongs_to] if options[:belongs_to]
     end
 
-  public
-
-    # @return [String] string describing the collection's array representation
-    def to_s           ; to_a.to_s           ; end
-    # @return [String] string describing the collection's array representation
-    def inspect(detailed=true)
-      if detailed then  guts = clxn.map{|key, val| "%-15s %s" % ["#{key}:", val.inspect] }.join(",\n   ")
-      else              guts =  keys.join(", ") ; end
-      ["c{ ", guts, " }"].join
-    end
-    # @return [Array] serializable array representation of the collection
-    def to_wire(options={})
-      to_a.map{|el| el.respond_to?(:to_wire) ? el.to_wire(options) : el }
+    # Adds an item in-place. Items added to the collection (via `add`, `[]=`,
+    # `initialize`, etc) all pass through the `add` method: you should override
+    # this in subclasses to add any gatekeeper behavior.
+    #
+    # If no label is supplied, we use the result of invoking `key_method` on the
+    # item (or raise an error if no label *and* no key_method).
+    #
+    # It's up to you to ensure that labels make sense; this method doesn't
+    # demand the item's key_method match its label.
+    #
+    # @return [Object] the item
+    def add(item, label=nil)
+      label ||= label_for(item)
+      @clxn[label] = item
     end
-    # same as #to_wire
-    def as_json(*args) to_wire(*args) ; end
-    # @return [String] JSON serialization of the collection's array representation
-    def to_json(*args) to_wire(*args).to_json(*args) ; end
 
-  end
-
-  class Collection < Gorillib::GenericCollection
-    def initialize
-      @clxn   = Hash.new
+    def label_for(item)
+      if key_method.nil? then
+        raise ArgumentError, "Can't add things to a #{self.class} without some sort of label: use foo[label] = obj, or set the collection's key_method" ;
+      end
+      item.public_send(key_method)
     end
 
-    delegate :[], :[]=, :fetch, :delete,       :to => :clxn
-    delegate :values,                          :to => :clxn
-    delegate :keys, :each_pair, :each_value,   :to => :clxn
-    delegate :include?,                        :to => :clxn
+    #
+    # Barebones enumerable methods
+    #
+    # This set of methods is purposefully sparse. If you want to use `select`,
+    # `invert`, etc, just invoke `to_hash` or `to_a` and work with the copy it
+    # gives you.
+    #
+
+    delegate :[], :fetch, :delete, :include?,         :to => :clxn
+    delegate :keys, :values, :each_pair, :each_value, :to => :clxn
+    delegate :length, :size, :empty?, :blank?,        :to => :clxn
 
     # @return [Array] an array holding the items
     def to_a    ; values    ; end
@@ -80,21 +123,80 @@ module Gorillib
     # iterate over each value in the collection
     def each(&block); each_value(&block) ; end
 
-    # Add the new items in-place; given items clobber existing items
+    # Adds item, returning the collection itself.
+    # @return [Gorillib::Collection] the collection
+    def <<(item)
+      add(item)
+      self
+    end
+
+    # add item with given label
+    def []=(label, item)
+      add(item, label)
+    end
+
+    # Receive items in-place, replacing any existing item with that label.
+    #
+    # Individual items are added using #receive_item -- if you'd like to perform
+    # any conversion or modification to items, do it there
+    #
     # @param  other [{Symbol => Object}, Array<Object>] a hash of key=>item pairs or a list of items
     # @return [Gorillib::Collection] the collection
     def receive!(other)
-      clxn.merge!( convert_collection(other) )
+      if other.respond_to?(:each_pair)
+        other.each_pair{|label, item| receive_item(label, item) }
+      elsif other.respond_to?(:each)
+        other.each{|item|             receive_item(nil,   item) }
+      else
+        raise "A collection can only receive something that is enumerable: got #{other.inspect}"
+      end
       self
     end
 
-  protected
+    # items arriving from the outside world should pass through receive_item,
+    # not directly to add.
+    def receive_item(label, item)
+      add(item, label)
+    end
+
+    # Create a new collection and add the given items to it
+    # (if given an existing collection, just returns it directly)
+    def self.receive(items, *args)
+      return items if native?(items)
+      coll = new(*args)
+      coll.receive!(items)
+      coll
+    end
+
+    # A `native` object does not need any transformation; it is accepted directly.
+    # By default, an object is native if it `is_a?` this class
+    #
+    # @param  obj [Object] the object that will be received
+    # @return [true, false] true if the item does not need conversion
+    def self.native?(obj)
+      obj.is_a?(self)
+    end
+
+    # Two collections are equal if they have the same class and their contents are equal
+    #
+    # @param [Gorillib::Collection, Object] other The other collection to compare
+    # @return [true, false] True if attributes are equal and other is instance of the same Class
+    def ==(other)
+      return false unless other.instance_of?(self.class)
+      clxn == other.send(:clxn)
+    end
+
+    # @return [String] string describing the collection's array representation
+    def to_s           ; to_a.to_s           ; end
+    # @return [String] string describing the collection's array representation
+    def inspect
+      key_width = [keys.map{|key| key.to_s.length + 1 }.max.to_i, 45].min
+      guts = clxn.map{|key, val| "%-#{key_width}s %s" % ["#{key}:", val.inspect] }.join(",\n   ")
+      ['c{ ', guts, ' }'].join
+    end
 
-    # - if the given collection responds_to `to_hash`, it is received into the internal collection; each hash key *must* match the id of its value or results are undefined.
-    # - otherwise, it receives a hash generates from the id/value pairs of each object in the given collection.
-    def convert_collection(cc)
-      return cc.to_hash if cc.respond_to?(:to_hash)
-      raise "a #{self.class} can only receive a hash with explicitly-labelled contents."
+    def inspect_compact
+      ['c{ ', keys.join(", "), ' }'].join
     end
 
   end

data/lib/gorillib/collection/model_collection.rb

@@ -1,62 +1,155 @@
 module Gorillib
-  class ModelCollection < Gorillib::Collection
-    # [String, Symbol] Method invoked on a new item to generate its collection key; :to_key by default
-    attr_accessor :key_method
-    # The default `key_method` invoked on a new item to generate its collection key
-    DEFAULT_KEY_METHOD = :to_key
 
+  #
+  # A collection of Models
+  #
+  # ### Item Type
+  #
+  # `item_type` is a class attribute -- you can make a "collection of Foo's" by
+  # subclassing ModelCollection and set the item item_type at the class level:
+  #
+  #     class ClusterCollection < ModelCollection
+  #       self.item_type = Cluster
+  #     end
+  #
+  #
+  #
+  # A model collection serializes as an array does, but indexes labelled objects
+  # as a hash does.
+  #
+  #
+  class ModelCollection < Gorillib::Collection
     # [Class, #receive] Factory for generating a new collection item.
-    class_attribute :factory, :instance_writer => false
-    singleton_class.class_eval{ protected :factory= }
-
-    def initialize(key_meth=nil, obj_factory=nil)
-      @factory     = Gorillib::Factory(obj_factory) if obj_factory
-      @clxn        = Hash.new
-      @key_method  = key_meth || DEFAULT_KEY_METHOD
-    end
+    class_attribute :item_type, :instance_writer => false
+    singleton_class.send(:protected, :item_type=)
 
-    # Adds an item in-place
-    # @return [Gorillib::Collection] the collection
-    def <<(val)
-      receive! [val]
-      self
+    def initialize(options={})
+      @item_type  = Gorillib::Factory(options[:item_type]) if options[:item_type]
+      super
     end
 
-    def create(*args, &block)
-      item = factory.receive(*args)
-      self << item
-      item
+    def receive_item(label, *args, &block)
+      item  = item_type.receive(*args, &block)
+      super(label, item)
+    rescue StandardError => err ; err.polish("#{item_type} #{label} as #{args.inspect} to #{self}") rescue nil ; raise
     end
 
-    def update_or_create(key, *args, &block)
-      if include?(key)
-        obj = fetch(key)
-        obj.receive!(*args, &block)
-        obj
+    def update_or_add(label, attrs, &block)
+      if label && include?(label)
+        item = fetch(label)
+        item.receive!(attrs, &block)
+        item
       else
-        attrs = args.extract_options!.merge(key_method => key)
-        create(*args, attrs, &block)
+        attrs = attrs.merge(key_method => label) if key_method && label
+        receive_item(label, attrs, &block)
       end
+    rescue StandardError => err ; err.polish("#{item_type} #{label} as #{attrs} to #{self}") rescue nil ; raise
+    end
+
+    # @return [Array] serializable array representation of the collection
+    def to_wire(options={})
+      to_a.map{|el| el.respond_to?(:to_wire) ? el.to_wire(options) : el }
     end
+    # same as #to_wire
+    def as_json(*args) to_wire(*args) ; end
+    # @return [String] JSON serialization of the collection's array representation
+    def to_json(*args) to_wire(*args).to_json(*args) ; end
+  end
+
+  class Collection
+
+    #
+    #
+    #     class ClusterCollection < ModelCollection
+    #       self.item_type = Cluster
+    #     end
+    #     class Organization
+    #       field :clusters, ClusterCollection, default: ->{ ClusterCollection.new(common_attrs: { organization: self }) }
+    #     end
+    #
+    module CommonAttrs
+      extend Gorillib::Concern
+
+      included do
+        # [Class, #receive] Attributes to mix in to each added item
+        class_attribute :common_attrs, :instance_writer => false
+        singleton_class.send(:protected, :common_attrs=)
+        self.common_attrs = Hash.new
+      end
 
-  protected
+      def initialize(options={})
+        super
+        @common_attrs = self.common_attrs.merge(options[:common_attrs]) if options.include?(:common_attrs)
+      end
+
+      #
+      # * a factory-native object: item is updated with common_attrs, then added
+      # * raw materials for the object: item is constructed (from the merged attrs and common_attrs), then added
+      #
+      def receive_item(label, *args, &block)
+        attrs = args.extract_options!.merge(common_attrs)
+        super(label, *args, attrs, &block)
+      end
+
+      def update_or_add(label, *args, &block)
+        attrs = args.extract_options!.merge(common_attrs)
+        super(label, *args, attrs, &block)
+      end
 
-    def convert_value(val)
-      return val unless factory
-      return nil if val.nil?
-      factory.receive(val)
     end
 
-    # - if the given collection responds_to `to_hash`, it is received into the internal collection; each hash key *must* match the id of its value or results are undefined.
-    # - otherwise, it receives a hash generates from the id/value pairs of each object in the given collection.
-    def convert_collection(cc)
-      return cc.to_hash if cc.respond_to?(:to_hash)
-      cc.inject({}) do |acc, val|
-        val      = convert_value(val)
-        key      = val.public_send(key_method)
-        acc[key] = val
-        acc
+    #
+    # @example
+    #   class Smurf
+    #     include Gorillib::Model
+    #   end
+    #
+    #   # Sets the 'village' attribute on each item it receives to the object
+    #   # this collection belongs to.
+    #   class SmurfCollection < ModelCollection
+    #     include Gorillib::Collection::ItemsBelongTo
+    #     self.item_type        = Smurf
+    #     self.parentage_method = :village
+    #   end
+    #
+    #   # SmurfVillage makes sure its SmurfCollection knows that it `belongs_to` the village
+    #   class SmurfVillage
+    #     include Gorillib::Model
+    #     field :name,   Symbol
+    #     field :smurfs, SmurfCollection, default: ->{ SmurfCollection.new(belongs_to: self) }
+    #   end
+    #
+    #   # all the normal stuff works as you'd expect
+    #   smurf_town = SmurfVillage.new('smurf_town')   # #<SmurfVillage name=smurf_town>
+    #   smurf_town.smurfs                             # c{ }
+    #   smurf_town.smurfs.belongs_to                  # #<SmurfVillage name=smurf_town>
+    #
+    #   # when a new smurf moves to town, it knows what village it belongs_to
+    #   smurf_town.smurfs.receive_item(:novel_smurf, smurfiness: 10)
+    #   # => #<Smurf name=:novel_smurf smurfiness=10 village=#<SmurfVillage name=smurf_town>>
+    #
+    module ItemsBelongTo
+      extend Gorillib::Concern
+      include Gorillib::Collection::CommonAttrs
+
+      included do
+        # [Class, #receive] Name of the attribute to set on
+        class_attribute :parentage_method, :instance_writer => false
+        singleton_class.send(:protected, :common_attrs=)
       end
+
+      # add this collection's belongs_to to the common attrs, so that a
+      # newly-created object knows its parentage from birth.
+      def initialize(*args)
+        super
+        @common_attrs = self.common_attrs.merge(parentage_method => self.belongs_to)
+      end
+
+      def add(item, *args)
+        item.send("#{parentage_method}=", belongs_to)
+        super
+      end
+
     end
 
   end