gorillib-model 0.0.1

data/lib/gorillib/model/base.rb

@@ -0,0 +1,273 @@
+module Gorillib
+
+  # Provides a set of class methods for defining a field schema and instance
+  # methods for reading and writing attributes.
+  #
+  # @example Usage
+  #   class Person
+  #     include Gorillib::Model
+  #
+  #     field :name,   String,  :doc => 'Full name of person'
+  #     field :height, Float,   :doc => 'Height in meters'
+  #   end
+  #
+  #   person      = Person.new
+  #   person.name = "Bob Dobbs, Jr"
+  #   puts person  #=> #<Person name="Bob Dobbs, Jr">
+  #
+  module Model
+    extend ActiveSupport::Concern
+
+    def initialize(*args, &block)
+      attrs = self.class.attrs_hash_from_args(args)
+      receive!(attrs, &block)
+    end
+
+    # Returns a Hash of all attributes
+    #
+    # @example Get attributes
+    #   person.attributes # => { :name => "Emmet Brown", :title => "Dr" }
+    #
+    # @return [{Symbol => Object}] The Hash of all attributes
+    def attributes
+      self.class.field_names.inject(Hash.new) do |hsh, fn|
+        # hsh[fn] = attribute_set?(fn) ? read_attribute(fn) : nil
+        hsh[fn] = read_attribute(fn)
+        hsh
+      end
+    end
+
+    # @return [Array[Object]] all the attributes, in field order, with `nil` where unset
+    def attribute_values
+      self.class.field_names.map{|fn| read_attribute(fn) }
+    end
+
+    # Returns a Hash of all attributes *that have been set*
+    #
+    # @example Get attributes (smurfette is unarmed)
+    #   smurfette.attributes         # => { :name => "Smurfette", :weapon => nil }
+    #   smurfette.compact_attributes # => { :name => "Smurfette" }
+    #
+    # @return [{Symbol => Object}] The Hash of all *set* attributes
+    def compact_attributes
+      self.class.field_names.inject(Hash.new) do |hsh, fn|
+        hsh[fn] = read_attribute(fn) if attribute_set?(fn)
+        hsh
+      end
+    end
+
+    #
+    # Accept the given attributes, converting each value to the appropriate
+    # type, constructing included models and collections, and other triggers as
+    # defined.
+    #
+    # Use `#receive!` to accept 'dirty' data -- from JSON, from a nested hash,
+    # or some such. Use `#update_attributes` if your data is already type safe.
+    #
+    # @param [{Symbol => Object}] hsh The values to receive
+    # @return [nil] nothing
+    def receive!(hsh={})
+      if hsh.respond_to?(:attributes)
+        hsh = hsh.compact_attributes
+      else
+        Gorillib::Model::Validate.hashlike!(hsh){ "attributes for #{self.inspect}" }
+        hsh = hsh.dup
+      end
+      self.class.field_names.each do |field_name|
+        if    hsh.has_key?(field_name)      then val = hsh.delete(field_name)
+        elsif hsh.has_key?(field_name.to_s) then val = hsh.delete(field_name.to_s)
+        else next ; end
+        self.send("receive_#{field_name}", val)
+      end
+      handle_extra_attributes(hsh)
+      nil
+    end
+
+    def handle_extra_attributes(attrs)
+      @_extra_attributes ||= Hash.new
+      @_extra_attributes.merge!(attrs)
+    end
+
+    #
+    # Accept the given attributes, adopting each value directly.
+    #
+    # Use `#receive!` to accept 'dirty' data -- from JSON, from a nested hash,
+    # or some such. Use `#update_attributes` if your data is already type safe.
+    #
+    # @param [{Symbol => Object}] hsh The values to update with
+    # @return [Gorillib::Model] the object itself
+    def update_attributes(hsh)
+      if hsh.respond_to?(:attributes) then hsh = hsh.attributes ; end
+      Gorillib::Model::Validate.hashlike!(hsh){ "attributes for #{self.inspect}" }
+      self.class.field_names.each do |field_name|
+        if    hsh.has_key?(field_name)      then val = hsh[field_name]
+        elsif hsh.has_key?(field_name.to_s) then val = hsh[field_name.to_s]
+        else next ; end
+        write_attribute(field_name, val)
+      end
+      self
+    end
+
+    # Read a value from the model's attributes.
+    #
+    # @example Reading an attribute
+    #   person.read_attribute(:name)
+    #
+    # @param [String, Symbol, #to_s] field_name Name of the attribute to get.
+    #
+    # @raise [UnknownAttributeError] if the attribute is unknown
+    # @return [Object] The value of the attribute, or nil if it is unset
+    def read_attribute(field_name)
+      attr_name = "@#{field_name}"
+      if instance_variable_defined?(attr_name)
+        instance_variable_get(attr_name)
+      else
+        read_unset_attribute(field_name)
+      end
+    end
+
+    # Write the value of a single attribute.
+    #
+    # @example Writing an attribute
+    #   person.write_attribute(:name, "Benjamin")
+    #
+    # @param [String, Symbol, #to_s] field_name Name of the attribute to update.
+    # @param [Object] val The value to set for the attribute.
+    #
+    # @raise [UnknownAttributeError] if the attribute is unknown
+    # @return [Object] the attribute's value
+    def write_attribute(field_name, val)
+      instance_variable_set("@#{field_name}", val)
+    end
+
+    # Unset an attribute. Subsequent reads of the attribute will return `nil`,
+    # and `attribute_set?` for that field will return false.
+    #
+    # @example Unsetting an attribute
+    #   obj.write_attribute(:foo, nil)
+    #   [ obj.read_attribute(:foo), obj.attribute_set?(:foo) ] # => [ nil, true ]
+    #   person.unset_attribute(:height)
+    #   [ obj.read_attribute(:foo), obj.attribute_set?(:foo) ] # => [ nil, false ]
+    #
+    # @param [String, Symbol, #to_s] field_name Name of the attribute to unset.
+    #
+    # @raise [UnknownAttributeError] if the attribute is unknown
+    # @return [Object] the former value if it was set, nil if it was unset
+    def unset_attribute(field_name)
+      if instance_variable_defined?("@#{field_name}")
+        val = instance_variable_get("@#{field_name}")
+        remove_instance_variable("@#{field_name}")
+        return val
+      else
+        return nil
+      end
+    end
+
+    # True if the attribute is set.
+    #
+    # Note that an attribute can have the value nil but be set.
+    #
+    # @param [String, Symbol, #to_s] field_name Name of the attribute to check.
+    #
+    # @raise [UnknownAttributeError] if the attribute is unknown
+    # @return [true, false]
+    def attribute_set?(field_name)
+      instance_variable_defined?("@#{field_name}")
+    end
+
+    # Two models are equal if they have the same class and their attributes
+    # are equal.
+    #
+    # @example Compare for equality.
+    #   model == other
+    #
+    # @param [Gorillib::Model, Object] other The other model 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)
+      attributes == other.attributes
+    end
+
+    # override to_inspectable (not this) in your descendant class
+    # @return [String] Human-readable presentation of the attributes
+    def inspect
+      str = '#<' << self.class.name.to_s
+      attrs = to_inspectable
+      if attrs.present?
+        str << '(' << attrs.map{|attr, val| "#{attr}=#{val.respond_to?(:inspect_compact) ? val.inspect_compact : val.inspect}" }.join(", ") << ')'
+      end
+      str << '>'
+    end
+
+    def to_s
+      inspect
+    end
+
+    def inspect_compact
+      str = "#<#{self.class.name.to_s}>"
+    end
+
+    # assembles just the given attributes into the inspect string.
+    # @return [String] Human-readable presentation of the attributes
+    def to_inspectable
+      compact_attributes
+    end
+
+  protected
+
+    module ClassMethods
+
+      #
+      # A readable handle for this field
+      #
+      def typename
+        @typename ||= ActiveSupport::Inflector.underscore(self.name||'anon').gsub(%r{/}, '.')
+      end
+
+      #
+      # Receive external data, type-converting and creating contained models as necessary
+      #
+      # @return [Gorillib::Model] the new object
+      def receive(attrs={}, &block)
+        return nil if attrs.nil?
+        return attrs if native?(attrs)
+        #
+        Gorillib::Model::Validate.hashlike!(attrs){ "attributes for #{self.inspect}" }
+        klass = attrs.has_key?(:_type) ? Gorillib::Factory(attrs[:_type]) : self
+        warn "factory #{klass} is not a type of #{self} as specified in #{attrs}" unless klass <= self
+        #
+        klass.new(attrs, &block)
+      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 native?(obj)
+        obj.is_a?(self)
+      end
+
+      # @return Class name and its attributes
+      #
+      # @example Inspect the model's definition.
+      #   Person.inspect #=> Person[first_name, last_name]
+      def inspect
+        "#{self.name || 'anon'}[#{ field_names.join(",") }]"
+      end
+      def inspect_compact() self.name || inspect ; end
+
+    end
+
+    self.included do |base|
+      base.instance_eval do
+        extend Gorillib::Model::NamedSchema
+        extend Gorillib::Model::ClassMethods
+        self.meta_module
+        @_own_fields ||= {}
+      end
+    end
+
+  end
+end

data/lib/gorillib/model/collection/model_collection.rb

@@ -0,0 +1,157 @@
+module Gorillib
+
+  #
+  # 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 :item_type, :instance_writer => false
+    singleton_class.send(:protected, :item_type=)
+
+    def initialize(options={})
+      @item_type  = Gorillib::Factory(options[:item_type]) if options[:item_type]
+      super
+    end
+
+    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_add(label, attrs, &block)
+      if label && include?(label)
+        item = fetch(label)
+        item.receive!(attrs, &block)
+        item
+      else
+        attrs = attrs.attributes if attrs.is_a? Gorillib::Model
+        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 ActiveSupport::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
+
+      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
+
+    end
+
+    #
+    # @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 ActiveSupport::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
+end

data/lib/gorillib/model/collection.rb

@@ -0,0 +1,200 @@
+module Gorillib
+
+  #
+  # 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?
+  #   - [], []=, 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:
+  #   - `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 Collection
+    # [{Symbol => Object}] The actual store of items -- not for you to mess with
+    attr_reader :clxn
+    protected   :clxn
+
+    # Object that owns this collection, if any
+    attr_reader :belongs_to
+
+    # [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=)
+
+    # 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
+
+    # 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
+
+    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
+
+    #
+    # 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
+    # @return [{Symbol => Object}] a hash of key=>item pairs
+    def to_hash ; clxn.dup  ; end
+
+    # iterate over each value in the collection
+    def each(&block); each_value(&block) ; end
+
+    # 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)
+      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
+
+    # 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
+
+    def inspect_compact
+      ['c{ ', keys.join(", "), ' }'].join
+    end
+
+  end
+end