gorillib 0.4.0pre → 0.4.1pre

data/lib/gorillib/collection/list_collection.rb

@@ -0,0 +1,58 @@
+require 'gorillib/collection'
+
+module Gorillib
+  class ListCollection < Gorillib::GenericCollection
+
+    def initialize
+      @clxn = Array.new
+    end
+    
+    # common to all collections, delegable to array
+    delegate :to_a, :each,         :to => :clxn
+
+    # Add the new items in-place; given items clobber existing items
+    # @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.concat( convert_collection(other) ).uniq!
+      self
+    end
+
+    # @return [Array] an array holding the items
+    def values ; to_a ; end
+
+    # iterate over each value in the collection
+    def each_value(&block); each(&block) ; end
+
+    # # removed on purpose, pending us understanding what the
+    # # even-yet-simpler-still collection should be.
+    #
+    # delegate :[], :[]=, :fetch,    :to => :clxn
+    #
+    # # Deletes the entry whose index is `idx`, returning the corresponding
+    # # value. If the index is out of bounds, returns nil. If the optional code
+    # # block is given and the index is out of bounds, pass it the index and
+    # # return the result of block.
+    # #
+    # # @return the now-delete value, if found; otherwise, the result of the
+    # #   block, if given; otherwise nil.
+    # def delete(idx, &block)
+    #   if idx < length
+    #     clxn.delete_at(idx)
+    #   elsif block_given?
+    #     yield(idx)
+    #   else
+    #     nil
+    #   end
+    # end
+
+  protected
+
+    # - 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 uses a hash generated from the id/value pairs of each object in the given collection.
+    def convert_collection(cc)
+      cc.respond_to?(:values) ? cc.values : cc.to_a
+    end
+  end
+
+end

data/lib/gorillib/collection/model_collection.rb

@@ -0,0 +1,63 @@
+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
+
+    # [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
+
+    # Adds an item in-place
+    # @return [Gorillib::Collection] the collection
+    def <<(val)
+      receive! [val]
+      self
+    end
+
+    def create(*args, &block)
+      item = factory.receive(*args)
+      self << item
+      item
+    end
+
+    def update_or_create(key, *args, &block)
+      if include?(key)
+        obj = fetch(key)
+        obj.receive!(*args, &block)
+        obj
+      else
+        attrs = args.extract_options!.merge(key_method => key)
+        create(*args, attrs, &block)
+      end
+    end
+
+  protected
+
+    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
+      end
+    end
+
+  end
+end

data/lib/gorillib/collection.rb

@@ -2,51 +2,36 @@ require 'gorillib/metaprogramming/delegation'
 require 'gorillib/metaprogramming/class_attribute'
 
 module Gorillib
-  class 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
-
-    # [Class, #receive] Factory for generating a new collection item.
-    class_attribute :factory, :instance_writer => false
-    singleton_class.class_eval{ protected :factory= }
 
+  #
+  # A generic collection stores objects uniquely, in the order added. It 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.
+  #
+  # 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
+  #     `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
     attr_reader :clxn
     protected   :clxn
 
-    delegate :[], :[]=, :delete, :fetch,                  :to => :clxn
-    delegate :keys, :values, :each_pair, :each_value,     :to => :clxn
-    delegate :has_key?, :include?, :length, :size, :empty?, :blank?, :to => :clxn
-
-    def initialize(factory=nil, key_method=DEFAULT_KEY_METHOD)
-      @key_method  = key_method
-      @factory     = factory unless factory.nil?
-      @clxn        = {}
-    end
-
-    # @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
-
-    # Merge the new items in-place; given items clobber existing items
-    # @param  other [{Symbol => Object}, Array<Object>] a hash of key=>item pairs or a list of items
-    # @return [Gorillib::Collection] the collection
-    def merge!(other)
-      clxn.merge!( convert_collection(other) )
-      self
-    end
-    alias_method :concat,   :merge!
-    alias_method :receive!, :merge!
-
     def self.receive(items, *args)
       coll = new(*args)
       coll.receive!(items)
       coll
     end
 
+    delegate :length, :size, :empty?, :blank?, :to => :clxn
+
     # 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
@@ -56,74 +41,61 @@ module Gorillib
       clxn == other.send(:clxn)
     end
 
-    # Merge the new items into a new collection; given items clobber existing items
-    # @param  other [{Symbol => Object}, Array<Object>] a hash of key=>item pairs or a list of items
-    # @return [Gorillib::Collection] a new merged collection
-    def merge(other)
-      dup.merge!(other)
-    end
-
-    def create(*args)
-      item = factory.receive(*args)
-      self << item
-      item
-    end
-
-    def find_or_create(key)
-      fetch(key){ create(key_method => key) }
-    end
-
-    # Adds an item in-place
-    # @return [Gorillib::Collection] the collection
-    def <<(val)
-      merge! [val]
-      self
-    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)
-      str = "c{ "
-      if detailed
-        str << clxn.map do |key, val|
-          "%-15s %s" % ["#{key}:", val.inspect]
-        end.join(",\n   ")
-      else
-        str << keys.join(", ")
-      end
-      str << " }"
+      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)
+    def to_wire(options={})
       to_a.map{|el| el.respond_to?(:to_wire) ? el.to_wire(options) : el }
     end
-    alias_method(:as_json, :to_wire)
+    # 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)
-      p [self, options]
-      to_wire(*args).to_json(*args)
+    def to_json(*args) to_wire(*args).to_json(*args) ; end
+
+  end
+
+  class Collection < Gorillib::GenericCollection
+    def initialize
+      @clxn   = Hash.new
     end
 
-  protected
+    delegate :[], :[]=, :fetch, :delete,       :to => :clxn
+    delegate :values,                          :to => :clxn
+    delegate :keys, :each_pair, :each_value,   :to => :clxn
+    delegate :include?,                        :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
 
-    def convert_value(val)
-      return val unless factory
-      return nil if val.nil?
-      factory.receive(val)
+    # Add the new items in-place; given items clobber existing items
+    # @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) )
+      self
     end
 
-    # - if the given collection responds_to `to_hash`, it is merged into the internal collection; each hash key *must* match the id of its value or results are undefined.
-    # - otherwise, it merges a hash generates from the id/value pairs of each object in the given collection.
+  protected
+
+    # - 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).to_sym
-        acc[key] = val
-        acc
-      end
+      raise "a #{self.class} can only receive a hash with explicitly-labelled contents."
     end
-  end
 
+  end
 end

data/lib/gorillib/logger/log.rb

@@ -1,29 +1,12 @@
-require 'logger'
-
 #
 # A convenient logger.
 #
-# define Log yourself to prevent its creation
+# to override its creation, simply define the top-level constant `::Log`
 #
-::Log = Logger.new($stderr) unless defined?(::Log)
-
-# unless defined?(Log)
-#   require 'log4r'
-#   Log = Log4r::Logger.new('wukong')
-#   Log.outputters = Log4r::Outputter.stderr
-#   # require 'logger'
-#   # Log = Logger.new(STDERR)
-# end
-
-# require 'log_buddy'; LogBuddy.init :log_to_stdout => false, :logger => Log
-# LogBuddy::Utils.module_eval do
-#   def arg_and_blk_debug(arg, blk)
-#     result = eval(arg, blk.binding)
-#     result_str = obj_to_string(result, :quote_strings => true)
-#     LogBuddy.debug(%[#{arg} = #{result_str}])
-#   end
-# end
-
+unless defined?(::Log)
+  require 'logger'
+  ::Log = Logger.new($stderr)
+end
 
 def Log.dump *args
   self.debug([
@@ -31,3 +14,24 @@ def Log.dump *args
       caller.first
     ].join("\t"))
 end unless Log.respond_to?(:dump)
+
+
+
+# TODO: allow swappable loggers more cleanly
+
+  # unless defined?(Log)
+  #   require 'log4r'
+  #   Log = Log4r::Logger.new('wukong')
+  #   Log.outputters = Log4r::Outputter.stderr
+  #   # require 'logger'
+  #   # Log = Logger.new(STDERR)
+  # end
+
+  # require 'log_buddy'; LogBuddy.init :log_to_stdout => false, :logger => Log
+  # LogBuddy::Utils.module_eval do
+  #   def arg_and_blk_debug(arg, blk)
+  #     result = eval(arg, blk.binding)
+  #     result_str = obj_to_string(result, :quote_strings => true)
+  #     LogBuddy.debug(%[#{arg} = #{result_str}])
+  #   end
+  # end

data/lib/gorillib/model/base.rb

@@ -1,4 +1,3 @@
-
 module Gorillib
 
   # Provides a set of class methods for defining a field schema and instance
@@ -19,6 +18,16 @@ module Gorillib
   module Model
     extend Gorillib::Concern
 
+    def initialize(*args, &block)
+      attrs = args.extract_options!
+      if args.present?
+        fns = self.class.field_names
+        ArgumentError.check_arity!(args, 0..fns.length)
+        attrs = attrs.merge(Hash[ fns[0..(args.length-1)].zip(args) ])
+      end
+      receive!(attrs, &block)
+    end
+
     # Returns a Hash of all attributes
     #
     # @example Get attributes
@@ -32,6 +41,11 @@ module Gorillib
       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)
@@ -57,14 +71,19 @@ module Gorillib
     # @param [{Symbol => Object}] hsh The values to receive
     # @return [Gorillib::Model] the object itself
     def receive!(hsh={})
-      if hsh.respond_to?(:attributes) then hsh = hsh.attributes ; end
-      Gorillib::Model::Validate.hashlike!("attributes hash for #{self.inspect}", hsh)
-      hsh = hsh.symbolize_keys
-      self.class.fields.each do |field_name, field|
-        next unless hsh.has_key?(field_name)
-        self.public_send(:"receive_#{field_name}", hsh[field_name])
+      if hsh.respond_to?(:attributes)
+        hsh = hsh.attributes
+      else
+        Gorillib::Model::Validate.hashlike!(hsh){ "attributes hash for #{self.inspect}" }
+        hsh = hsh.dup
       end
-      handle_extra_attributes( hsh.reject{|field_name,val| self.class.has_field?(field_name) } )
+      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)
       self
     end
 
@@ -83,12 +102,12 @@ module Gorillib
     # @return [Gorillib::Model] the object itself
     def update_attributes(hsh)
       if hsh.respond_to?(:attributes) then hsh = hsh.attributes ; end
-      Gorillib::Model::Validate.hashlike!("attributes hash", hsh)
-      self.class.fields.each do |attr, field|
-        if    hsh.has_key?(attr)      then val = hsh[attr]
-        elsif hsh.has_key?(attr.to_s) then val = hsh[attr.to_s]
+      Gorillib::Model::Validate.hashlike!(hsh){ "attributes hash 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(attr, val)
+        write_attribute(field_name, val)
       end
       self
     end
@@ -103,9 +122,9 @@ module Gorillib
     # @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)
-      check_field(field_name)
-      if instance_variable_defined?("@#{field_name}")
-        instance_variable_get("@#{field_name}")
+      attr_name = "@#{field_name}"
+      if instance_variable_defined?(attr_name)
+        instance_variable_get(attr_name)
       else
         read_unset_attribute(field_name)
       end
@@ -122,7 +141,6 @@ module Gorillib
     # @raise [UnknownAttributeError] if the attribute is unknown
     # @return [Object] the attribute's value
     def write_attribute(field_name, val)
-      check_field(field_name)
       instance_variable_set("@#{field_name}", val)
     end
 
@@ -140,7 +158,6 @@ module Gorillib
     # @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)
-      check_field(field_name)
       if instance_variable_defined?("@#{field_name}")
         val = instance_variable_get("@#{field_name}")
         remove_instance_variable("@#{field_name}")
@@ -159,7 +176,6 @@ module Gorillib
     # @raise [UnknownAttributeError] if the attribute is unknown
     # @return [true, false]
     def attribute_set?(field_name)
-      check_field(field_name)
       instance_variable_defined?("@#{field_name}")
     end
 
@@ -188,9 +204,8 @@ module Gorillib
     def inspect_helper(detailed, attrs)
       str = "#<" << self.class.name.to_s
       if detailed && attrs.present?
-        str << " "
-        str << attrs.map do |attr, val|
-          "#{attr}=#{val.is_a?(Gorillib::Model) || val.is_a?(Gorillib::Collection) ? val.inspect(false) : val.inspect}"
+        str << " " << attrs.map do |attr, val|
+          "#{attr}=#{val.is_a?(Gorillib::Model) || val.is_a?(Gorillib::GenericCollection) ? val.inspect(false) : val.inspect}"
         end.join(", ")
       end
       str << ">"
@@ -199,17 +214,13 @@ module Gorillib
 
   protected
 
-    # @return [true] if the field exists
-    # @raise [UnknownFieldError] if the field is missing
-    def check_field(field_name)
-      return true if self.class.has_field?(field_name)
-      raise UnknownFieldError, "unknown field: #{field_name} for #{self}"
-    end
-
     module ClassMethods
 
+      #
+      # A readable handle for this field
+      #
       def typename
-        Gorillib::Inflector.underscore(self.name).gsub(%r{/}, '.')
+        @typename ||= Gorillib::Inflector.underscore(self.name||'anon').gsub(%r{/}, '.')
       end
 
       #
@@ -219,12 +230,12 @@ module Gorillib
       def receive(attrs={}, &block)
         return nil if attrs.nil?
         return attrs if attrs.is_a?(self)
-        Gorillib::Model::Validate.hashlike!("attributes for #{self}", attrs)
+        #
+        Gorillib::Model::Validate.hashlike!(attrs){ "attributes for #{self.inspect}" }
         klass = attrs.has_key?(:_type) ? Gorillib::Factory(attrs[:_type]) : self
-        warn "factory #{self} doesn't match type specified in #{attrs}" unless klass <= self
-        obj = klass.new
-        obj.receive!(attrs, &block)
-        obj
+        warn "factory #{klass} is not a type of #{self} as specified in #{attrs}" unless klass <= self
+        #
+        klass.new(attrs, &block)
       end
 
       # Defines a new field
@@ -260,12 +271,12 @@ module Gorillib
 
       # @return [true, false] true if the field is defined on this class
       def has_field?(field_name)
-        fields.has_key?(field_name.to_sym)
+        fields.has_key?(field_name)
       end
 
       # @return [Array<Symbol>] The attribute names
       def field_names
-        fields.keys
+        @_field_names ||= fields.keys
       end
 
       # @return Class name and its attributes
@@ -284,7 +295,8 @@ module Gorillib
       # are added after the child class is defined.
       def _reset_descendant_fields
         ObjectSpace.each_object(::Class) do |klass|
-          klass.__send__(:remove_instance_variable, '@_fields') if klass <= self && klass.instance_variable_defined?('@_fields')
+          klass.__send__(:remove_instance_variable, '@_fields')      if (klass <= self) && klass.instance_variable_defined?('@_fields')
+          klass.__send__(:remove_instance_variable, '@_field_names') if (klass <= self) && klass.instance_variable_defined?('@_field_names')
         end
       end
 
@@ -306,8 +318,9 @@ module Gorillib
 
       # define the present method `#foo?` for a field named `:foo`
       def define_attribute_tester(field_name, field_type, visibility)
+        field = fields[field_name]
         define_meta_module_method("#{field_name}?", visibility) do
-          attribute_set?(field_name)
+          attribute_set?(field_name) || field.has_default?
         end
       end
 

data/lib/gorillib/model/doc_string.rb

@@ -0,0 +1,15 @@
+module Gorillib
+  module Model
+    module DocString
+      extend Gorillib::Concern
+      included do
+        field :doc, String
+
+        def doc(*args)
+          if s
+          end
+        end
+      end
+    end
+  end
+end