gorillib 0.4.1pre → 0.4.2pre

data/examples/hash/slicing_methods.rb

@@ -0,0 +1,101 @@
+#!/usr/bin/env ruby
+
+require 'formatador'
+require 'active_support/core_ext/hash/slice.rb'
+load File.expand_path('../../lib/gorillib/hashlike/slice.rb', File.dirname(__FILE__))
+load File.expand_path('../../lib/gorillib/hash/mash.rb',      File.dirname(__FILE__))
+
+# +-----------+-------+---------+-------------+---------------------------+--------------------+
+# | method    | kind  | altered | returns     | result                    | receiver           |
+# +-----------+-------+---------+-------------+---------------------------+--------------------+
+# | select    | block | -       | copy        | {:a=>"A", :c=>"A"}        | (unchanged)        |
+# | only      | list  | -       | copy        | {:a=>"A", :c=>"A"}        | (unchanged)        |
+# | slice     | list  | -       | copy        | {:a=>"A", :c=>"A"}        | (unchanged)        |
+# | reject    | block | -       | copy        | {:b=>"not A"}             | (unchanged)        |
+# | except    | list  | -       | copy        | {:b=>"not A"}             | (unchanged)        |
+# | select!   | block | yes     | self or nil | {:a=>"A", :c=>"A"} or nil | {:a=>"A", :c=>"A"} |
+# | keep_if   | block | yes     | self        | {:a=>"A", :c=>"A"}        | {:a=>"A", :c=>"A"} |
+# | only!     | list  | yes     | self        | {:a=>"A", :c=>"A"}        | {:a=>"A", :c=>"A"} |
+# | slice!    | list  | yes     | copy        | {:b=>"not A"}             | {:a=>"A", :c=>"A"} |
+# | reject!   | block | yes     | self or nil | {:b=>"not A"} or nil      | {:b=>"not A"}      |
+# | delete_if | block | yes     | self        | {:b=>"not A"}             | {:b=>"not A"}      |
+# | except!   | list  | yes     | self        | {:b=>"not A"}             | {:b=>"not A"}      |
+# | extract!  | list  | yes     | copy        | {:a=>"A", :c=>"A"}        | {:b=>"not A"}      |
+# +-----------+-------+---------+-------------+---------------------------+--------------------+
+
+SLICING_METHODS = [
+  :select,              :only,    :slice,
+  :reject,              :except,
+  :select!, :keep_if,   :only!,   :slice!,
+  :reject!, :delete_if, :except!, :extract!, ]
+
+
+class Hashish < Hash
+  include Gorillib::Hashlike::Slice
+  include Gorillib::Hashlike::ExceptOnly
+end
+class Mashish < Mash
+  include Gorillib::Hashlike::ExceptOnly
+end
+
+EXAMPLE_HASH      = { a: 'A', b: 'not A', c: 'A' }.freeze
+EXAMPLE_MASH      = Mash   .new.merge!(EXAMPLE_HASH).freeze
+EXAMPLE_HASHISH   = Hashish.new.merge!(EXAMPLE_HASH).freeze
+EXAMPLE_MASHISH   = Mashish.new.merge!(EXAMPLE_HASH).freeze
+
+# The given set of keys, 'A' -- either as list or block
+GIVEN_KEYS   = [:c, :a]
+GIVEN_BLK    = ->(key,val){ val == 'A' }
+
+KLASS_COLORS = {Hashish => 'green', Mash => 'blue', Hash => 'red'}
+
+def colorize(item, choices)
+  color = choices[item] or return item
+  "[#{color}]#{item}[/]"
+end
+
+def slicing_method_report(obj, meth)
+  return :split if meth == :split
+  return({ method: meth, result: '(unimplemented)' }) unless obj.respond_to?(meth)
+  hsh        = obj.dup
+  kind       = (hsh.method(meth).arity == 0) ? :block : :list
+  result     = (kind == :block) ? hsh.send(meth, &GIVEN_BLK) : hsh.send(meth, *GIVEN_KEYS)
+  #
+  altered    = (hsh == obj)
+  result_str = result.to_s
+  returns    = result.equal?(hsh) ? 'self' : 'copy'
+  if [:select!, :reject!].include?(meth)
+    result_str << " or nil"; returns << " or nil"
+  end
+  ret_class  = colorize(result.class, KLASS_COLORS)
+  obj_class  = colorize(obj.class,    KLASS_COLORS)
+  src_loc, _ = hsh.method(meth).source_location
+  provider   = case src_loc when /gorillib\/hashlike\/slice/ then 'gorillib' when /activesupp/ then 'activesupp' when nil then 'internal' else 'other' ; end
+
+  { method: meth,     kind: kind,         altered: (altered ? '-' : 'yes'),
+    returns: returns, result: result_str, receiver: (altered ? '(unchanged)' : hsh),
+    provider: provider, obj_class: obj_class, ret_class: ret_class }
+end
+
+def display_results_table
+  info = SLICING_METHODS.flat_map do |meth|
+    [EXAMPLE_HASH, EXAMPLE_MASH, EXAMPLE_HASHISH, EXAMPLE_MASHISH].flat_map do |obj|
+      slicing_method_report(obj, meth)
+    end + [:split]
+  end
+  Formatador.display_compact_table(info,
+    [:method, :kind, :altered, :returns, :result, :receiver, :provider, :obj_class, :ret_class] )
+end
+
+puts
+puts "Results for hash #{EXAMPLE_HASH.inspect}, of hash.meth(:a, :c) or"
+puts "  hash.meth{|key, val| val == 'A'} as appropriate."
+puts "  Note: select! and reject! act resp. like keep_if and delete_if"
+puts "  but return nil if the contents are unchanged."
+puts
+
+display_results_table
+
+# display_results_table(EXAMPLE_HASHISH)
+#
+# display_results_table(EXAMPLE_MASH)

data/gorillib.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "gorillib"
-  s.version = "0.4.1pre"
+  s.version = "0.4.2pre"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Infochimps"]
-  s.date = "2012-06-27"
+  s.date = "2012-08-18"
   s.description = "Gorillib: infochimps lightweight subset of ruby convenience methods"
   s.email = "coders@infochimps.org"
   s.extra_rdoc_files = [
@@ -28,32 +28,32 @@ Gem::Specification.new do |s|
     "Rakefile",
     "TODO.md",
     "VERSION",
+    "examples/benchmark/factories_benchmark.rb",
     "examples/builder/ironfan.rb",
+    "examples/hash/slicing_methods.rb",
     "examples/model/simple.rb",
     "gorillib.gemspec",
-    "lib/alt/kernel/call_stack.rb",
     "lib/gorillib.rb",
-    "lib/gorillib/array/average.rb",
     "lib/gorillib/array/compact_blank.rb",
     "lib/gorillib/array/deep_compact.rb",
     "lib/gorillib/array/extract_options.rb",
-    "lib/gorillib/array/random.rb",
-    "lib/gorillib/array/sorted_median.rb",
-    "lib/gorillib/array/sorted_percentile.rb",
-    "lib/gorillib/array/sorted_sample.rb",
+    "lib/gorillib/array/simple_statistics.rb",
     "lib/gorillib/array/wrap.rb",
     "lib/gorillib/base.rb",
     "lib/gorillib/builder.rb",
-    "lib/gorillib/builder/field.rb",
     "lib/gorillib/collection.rb",
-    "lib/gorillib/collection/has_collection.rb",
-    "lib/gorillib/collection/list_collection.rb",
     "lib/gorillib/collection/model_collection.rb",
     "lib/gorillib/datetime/parse.rb",
     "lib/gorillib/datetime/to_flat.rb",
+    "lib/gorillib/deprecated/array/average.rb",
+    "lib/gorillib/deprecated/array/random.rb",
+    "lib/gorillib/deprecated/array/sorted_median.rb",
+    "lib/gorillib/deprecated/array/sorted_percentile.rb",
+    "lib/gorillib/deprecated/array/sorted_sample.rb",
+    "lib/gorillib/deprecated/metaprogramming/aliasing.rb",
     "lib/gorillib/enumerable/sum.rb",
-    "lib/gorillib/exception/confidence.rb",
     "lib/gorillib/exception/raisers.rb",
+    "lib/gorillib/factories.rb",
     "lib/gorillib/hash/compact.rb",
     "lib/gorillib/hash/deep_compact.rb",
     "lib/gorillib/hash/deep_dup.rb",
@@ -73,9 +73,7 @@ Gem::Specification.new do |s|
     "lib/gorillib/hashlike/keys.rb",
     "lib/gorillib/hashlike/reverse_merge.rb",
     "lib/gorillib/hashlike/slice.rb",
-    "lib/gorillib/io/system_helpers.rb",
     "lib/gorillib/logger/log.rb",
-    "lib/gorillib/metaprogramming/aliasing.rb",
     "lib/gorillib/metaprogramming/class_attribute.rb",
     "lib/gorillib/metaprogramming/concern.rb",
     "lib/gorillib/metaprogramming/delegation.rb",
@@ -91,11 +89,14 @@ Gem::Specification.new do |s|
     "lib/gorillib/model/errors.rb",
     "lib/gorillib/model/factories.rb",
     "lib/gorillib/model/field.rb",
+    "lib/gorillib/model/fixup.rb",
     "lib/gorillib/model/lint.rb",
     "lib/gorillib/model/named_schema.rb",
     "lib/gorillib/model/overlay.rb",
-    "lib/gorillib/model/record_schema.rb",
+    "lib/gorillib/model/positional_fields.rb",
+    "lib/gorillib/model/schema_magic.rb",
     "lib/gorillib/model/serialization.rb",
+    "lib/gorillib/model/serialization/csv.rb",
     "lib/gorillib/model/validate.rb",
     "lib/gorillib/numeric/clamp.rb",
     "lib/gorillib/object/blank.rb",
@@ -110,12 +111,13 @@ Gem::Specification.new do |s|
     "lib/gorillib/string/inflector.rb",
     "lib/gorillib/string/simple_inflector.rb",
     "lib/gorillib/string/truncate.rb",
+    "lib/gorillib/type/boolean.rb",
     "lib/gorillib/type/extended.rb",
     "lib/gorillib/type/url.rb",
     "lib/gorillib/utils/capture_output.rb",
     "lib/gorillib/utils/console.rb",
+    "lib/gorillib/utils/edge_cases.rb",
     "lib/gorillib/utils/nuke_constants.rb",
-    "lib/gorillib/utils/stub_module.rb",
     "notes/HOWTO.md",
     "notes/bucket.md",
     "notes/builder.md",
@@ -124,15 +126,12 @@ Gem::Specification.new do |s|
     "notes/model-overlay.md",
     "notes/model.md",
     "notes/structured-data-classes.md",
-    "spec/array/average_spec.rb",
-    "spec/array/sorted_median_spec.rb",
-    "spec/array/sorted_percentile_spec.rb",
-    "spec/array/sorted_sample_spec.rb",
     "spec/examples/builder/ironfan_spec.rb",
     "spec/extlib/hash_spec.rb",
     "spec/extlib/mash_spec.rb",
     "spec/gorillib/array/compact_blank_spec.rb",
     "spec/gorillib/array/extract_options_spec.rb",
+    "spec/gorillib/array/simple_statistics_spec.rb",
     "spec/gorillib/builder_spec.rb",
     "spec/gorillib/collection_spec.rb",
     "spec/gorillib/datetime/parse_spec.rb",
@@ -152,14 +151,13 @@ Gem::Specification.new do |s|
     "spec/gorillib/hashlike/hashlike_via_accessors_spec.rb",
     "spec/gorillib/hashlike_spec.rb",
     "spec/gorillib/logger/log_spec.rb",
-    "spec/gorillib/metaprogramming/aliasing_spec.rb",
     "spec/gorillib/metaprogramming/class_attribute_spec.rb",
     "spec/gorillib/metaprogramming/delegation_spec.rb",
     "spec/gorillib/metaprogramming/singleton_class_spec.rb",
+    "spec/gorillib/model/defaults_spec.rb",
+    "spec/gorillib/model/factories_spec.rb",
     "spec/gorillib/model/lint_spec.rb",
-    "spec/gorillib/model/record/defaults_spec.rb",
-    "spec/gorillib/model/record/factories_spec.rb",
-    "spec/gorillib/model/record/overlay_spec.rb",
+    "spec/gorillib/model/overlay_spec.rb",
     "spec/gorillib/model/serialization_spec.rb",
     "spec/gorillib/model_spec.rb",
     "spec/gorillib/numeric/clamp_spec.rb",
@@ -175,24 +173,24 @@ Gem::Specification.new do |s|
     "spec/gorillib/type/extended_spec.rb",
     "spec/gorillib/utils/capture_output_spec.rb",
     "spec/spec_helper.rb",
+    "spec/support/factory_test_helpers.rb",
     "spec/support/gorillib_test_helpers.rb",
     "spec/support/hashlike_fuzzing_helper.rb",
     "spec/support/hashlike_helper.rb",
     "spec/support/hashlike_struct_helper.rb",
     "spec/support/hashlike_via_delegation.rb",
-    "spec/support/kcode_test_helper.rb",
     "spec/support/matchers/be_array_eql.rb",
     "spec/support/matchers/be_hash_eql.rb",
     "spec/support/matchers/enumerate_method.rb",
     "spec/support/matchers/evaluate_to_true.rb",
     "spec/support/model_test_helpers.rb"
   ]
-  s.homepage = "http://infochimps.com/labs"
-  s.licenses = ["MIT"]
+  s.homepage = "https://github.com/infochimps-labs/gorillib"
+  s.licenses = ["Apache 2.0"]
   s.require_paths = ["lib"]
-  s.rubygems_version = "1.8.11"
+  s.rubygems_version = "1.8.24"
   s.summary = "include only what you need. No dependencies, no creep"
-  s.test_files = ["spec/array/average_spec.rb", "spec/array/sorted_median_spec.rb", "spec/array/sorted_percentile_spec.rb", "spec/array/sorted_sample_spec.rb", "spec/examples/builder/ironfan_spec.rb", "spec/extlib/hash_spec.rb", "spec/extlib/mash_spec.rb", "spec/gorillib/array/compact_blank_spec.rb", "spec/gorillib/array/extract_options_spec.rb", "spec/gorillib/builder_spec.rb", "spec/gorillib/collection_spec.rb", "spec/gorillib/datetime/parse_spec.rb", "spec/gorillib/datetime/to_flat_spec.rb", "spec/gorillib/enumerable/sum_spec.rb", "spec/gorillib/exception/raisers_spec.rb", "spec/gorillib/hash/compact_spec.rb", "spec/gorillib/hash/deep_compact_spec.rb", "spec/gorillib/hash/deep_merge_spec.rb", "spec/gorillib/hash/keys_spec.rb", "spec/gorillib/hash/reverse_merge_spec.rb", "spec/gorillib/hash/slice_spec.rb", "spec/gorillib/hash/zip_spec.rb", "spec/gorillib/hashlike/behave_same_as_hash_spec.rb", "spec/gorillib/hashlike/deep_hash_spec.rb", "spec/gorillib/hashlike/hashlike_behavior_spec.rb", "spec/gorillib/hashlike/hashlike_via_accessors_spec.rb", "spec/gorillib/hashlike_spec.rb", "spec/gorillib/logger/log_spec.rb", "spec/gorillib/metaprogramming/aliasing_spec.rb", "spec/gorillib/metaprogramming/class_attribute_spec.rb", "spec/gorillib/metaprogramming/delegation_spec.rb", "spec/gorillib/metaprogramming/singleton_class_spec.rb", "spec/gorillib/model/lint_spec.rb", "spec/gorillib/model/record/defaults_spec.rb", "spec/gorillib/model/record/factories_spec.rb", "spec/gorillib/model/record/overlay_spec.rb", "spec/gorillib/model/serialization_spec.rb", "spec/gorillib/model_spec.rb", "spec/gorillib/numeric/clamp_spec.rb", "spec/gorillib/object/blank_spec.rb", "spec/gorillib/object/try_dup_spec.rb", "spec/gorillib/object/try_spec.rb", "spec/gorillib/pathname_spec.rb", "spec/gorillib/string/constantize_spec.rb", "spec/gorillib/string/human_spec.rb", "spec/gorillib/string/inflections_spec.rb", "spec/gorillib/string/inflector_test_cases.rb", "spec/gorillib/string/truncate_spec.rb", "spec/gorillib/type/extended_spec.rb", "spec/gorillib/utils/capture_output_spec.rb", "spec/spec_helper.rb", "spec/support/gorillib_test_helpers.rb", "spec/support/hashlike_fuzzing_helper.rb", "spec/support/hashlike_helper.rb", "spec/support/hashlike_struct_helper.rb", "spec/support/hashlike_via_delegation.rb", "spec/support/kcode_test_helper.rb", "spec/support/matchers/be_array_eql.rb", "spec/support/matchers/be_hash_eql.rb", "spec/support/matchers/enumerate_method.rb", "spec/support/matchers/evaluate_to_true.rb", "spec/support/model_test_helpers.rb"]
+  s.test_files = ["spec/examples/builder/ironfan_spec.rb", "spec/extlib/hash_spec.rb", "spec/extlib/mash_spec.rb", "spec/gorillib/array/compact_blank_spec.rb", "spec/gorillib/array/extract_options_spec.rb", "spec/gorillib/array/simple_statistics_spec.rb", "spec/gorillib/builder_spec.rb", "spec/gorillib/collection_spec.rb", "spec/gorillib/datetime/parse_spec.rb", "spec/gorillib/datetime/to_flat_spec.rb", "spec/gorillib/enumerable/sum_spec.rb", "spec/gorillib/exception/raisers_spec.rb", "spec/gorillib/hash/compact_spec.rb", "spec/gorillib/hash/deep_compact_spec.rb", "spec/gorillib/hash/deep_merge_spec.rb", "spec/gorillib/hash/keys_spec.rb", "spec/gorillib/hash/reverse_merge_spec.rb", "spec/gorillib/hash/slice_spec.rb", "spec/gorillib/hash/zip_spec.rb", "spec/gorillib/hashlike/behave_same_as_hash_spec.rb", "spec/gorillib/hashlike/deep_hash_spec.rb", "spec/gorillib/hashlike/hashlike_behavior_spec.rb", "spec/gorillib/hashlike/hashlike_via_accessors_spec.rb", "spec/gorillib/hashlike_spec.rb", "spec/gorillib/logger/log_spec.rb", "spec/gorillib/metaprogramming/class_attribute_spec.rb", "spec/gorillib/metaprogramming/delegation_spec.rb", "spec/gorillib/metaprogramming/singleton_class_spec.rb", "spec/gorillib/model/defaults_spec.rb", "spec/gorillib/model/factories_spec.rb", "spec/gorillib/model/lint_spec.rb", "spec/gorillib/model/overlay_spec.rb", "spec/gorillib/model/serialization_spec.rb", "spec/gorillib/model_spec.rb", "spec/gorillib/numeric/clamp_spec.rb", "spec/gorillib/object/blank_spec.rb", "spec/gorillib/object/try_dup_spec.rb", "spec/gorillib/object/try_spec.rb", "spec/gorillib/pathname_spec.rb", "spec/gorillib/string/constantize_spec.rb", "spec/gorillib/string/human_spec.rb", "spec/gorillib/string/inflections_spec.rb", "spec/gorillib/string/inflector_test_cases.rb", "spec/gorillib/string/truncate_spec.rb", "spec/gorillib/type/extended_spec.rb", "spec/gorillib/utils/capture_output_spec.rb", "spec/spec_helper.rb", "spec/support/factory_test_helpers.rb", "spec/support/gorillib_test_helpers.rb", "spec/support/hashlike_fuzzing_helper.rb", "spec/support/hashlike_helper.rb", "spec/support/hashlike_struct_helper.rb", "spec/support/hashlike_via_delegation.rb", "spec/support/matchers/be_array_eql.rb", "spec/support/matchers/be_hash_eql.rb", "spec/support/matchers/enumerate_method.rb", "spec/support/matchers/evaluate_to_true.rb", "spec/support/model_test_helpers.rb"]
 
   if s.respond_to? :specification_version then
     s.specification_version = 3
@@ -201,20 +199,23 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<multi_json>, [">= 1.1"])
       s.add_development_dependency(%q<bundler>, ["~> 1.1"])
       s.add_development_dependency(%q<rake>, [">= 0"])
-      s.add_development_dependency(%q<oj>, [">= 1.2"])
-      s.add_development_dependency(%q<json>, [">= 0"])
+      s.add_development_dependency(%q<yard>, [">= 0.7"])
+      s.add_development_dependency(%q<rspec>, [">= 2.8"])
+      s.add_development_dependency(%q<jeweler>, [">= 1.6"])
     else
       s.add_dependency(%q<multi_json>, [">= 1.1"])
       s.add_dependency(%q<bundler>, ["~> 1.1"])
       s.add_dependency(%q<rake>, [">= 0"])
-      s.add_dependency(%q<oj>, [">= 1.2"])
-      s.add_dependency(%q<json>, [">= 0"])
+      s.add_dependency(%q<yard>, [">= 0.7"])
+      s.add_dependency(%q<rspec>, [">= 2.8"])
+      s.add_dependency(%q<jeweler>, [">= 1.6"])
     end
   else
     s.add_dependency(%q<multi_json>, [">= 1.1"])
     s.add_dependency(%q<bundler>, ["~> 1.1"])
     s.add_dependency(%q<rake>, [">= 0"])
-    s.add_dependency(%q<oj>, [">= 1.2"])
-    s.add_dependency(%q<json>, [">= 0"])
+    s.add_dependency(%q<yard>, [">= 0.7"])
+    s.add_dependency(%q<rspec>, [">= 2.8"])
+    s.add_dependency(%q<jeweler>, [">= 1.6"])
   end
 end

data/lib/gorillib/array/deep_compact.rb

@@ -1,9 +1,10 @@
+require 'set'
 require 'gorillib/object/blank'
 
-#
-# deep_compact! removes all 'blank?' elements in the array in place, recursively
-#
 class Array
+  #
+  # deep_compact! removes all 'blank?' elements in the array in place, recursively
+  #
   def deep_compact!
     self.map! do |val|
       val.deep_compact! if val.respond_to?(:deep_compact!)

data/lib/gorillib/array/simple_statistics.rb

@@ -0,0 +1,76 @@
+class Array
+
+  #
+  # The average of my elements.
+  # precondition: Each element must be convertible to a float.
+  #
+  # @return [Float] average of all elements
+  def average
+    return nil if empty?
+    inject(:+) / size.to_f
+  end
+
+  #
+  # @return the element that fraction of the way along the indexes
+  #
+  # @example halfway point:
+  #   [1,4,9,16,25].at_fraction(0.5)      #  9
+  #
+  # @example note that indexes are rounded down:
+  #   [1,4,9,16,25].at_fraction(0.74999)  #  9
+  #   [1,4,9,16,25].at_fraction(0.75)     # 16
+  #
+  # @example blank array:
+  #   [].at_fraction(0.1)       # nil
+  #
+  def at_fraction(fraction)
+    raise ArgumentError, "fraction should be between 0.0 and 1.0: got #{fraction.inspect}" unless (0.0 .. 1.0).include?(fraction)
+    return nil if empty?
+    self[ ((size - 1) * Float(fraction)).round ]
+  end
+
+  #
+  # @return the 1/nth, 2/nth, ... n/nth (last) elements in the array.
+  #
+  # @example
+  #   [1,4,9,16,25,36,49].take_nths(3)  # [4, 16, 36]
+  #   [ 4,9,  16,  36,49].take_nths(3)  # [4, 16, 36]
+  #   [1,4,9,16,25,36,49].take_nths(5)  # [1, 4, 16, 25, 36]
+  #
+  # @example edge cases
+  #   [1,4,9,16,25,36,49].take_nths(99) # [1,4,9,16,25,36,49]
+  #   [1,4,9,16,25,36,49].take_nths(1)  # [16]
+  #   [1,4,9,16,25,36,49].take_nths(0)  # []
+  #   [].take_nths(3)                   # []
+  #
+  # The array must be sorted for this to be useful.
+  #
+  def take_nths(num)
+    return [] if empty?
+    (0 .. num-1).map{|step| at_fraction( (step + 0.5)/(num)) }.uniq
+  end
+
+  #
+  # Returns the middle element of odd-sized arrays. For even arrays,
+  # it will return one of the two middle elements. Precisely which is
+  # undefined, except that it will consistently return one or the
+  # other.
+  #
+  # The array must be sorted for this to be useful.
+  #
+  def sorted_median
+    at_fraction(0.5)
+  end
+
+  #
+  # Returns the element at the position closest to the given
+  # percentile. For example, sorted_percentile 0.0 will return the
+  # first element and sorted_percentile 100.0 will return the last
+  # element.
+  #
+  # The array must be sorted for this to be useful.
+  #
+  def sorted_percentile(percentile)
+    at_fraction(percentile / 100.0)
+  end
+end

data/lib/gorillib/base.rb

@@ -1,5 +1,4 @@
 require 'gorillib/object/blank'
-require 'gorillib/object/try'
 require 'gorillib/array/extract_options'
 require 'gorillib/array/compact_blank'
 require 'gorillib/hash/reverse_merge'

data/lib/gorillib/builder.rb

@@ -7,12 +7,12 @@ module Gorillib
     extend  Gorillib::Concern
     include Gorillib::Model
 
+    # @return [Object, nil] the return value of the block, or nil if no block given
     def receive!(*args, &block)
       super(*args)
       if block_given?
         (block.arity == 1) ? block.call(self) : self.instance_eval(&block)
       end
-      self
     end
 
     def getset(field, *args, &block)
@@ -35,8 +35,8 @@ module Gorillib
         val = read_attribute(field.name)
         if val.present?
           # existing item: update it with args and block
-          val.receive!(*args, &block) if args.present?
-        elsif attrs.blank?
+          val.receive!(*args, &block) if args.present? or block_given?
+        elsif attrs.blank? and not block_given?
           # missing item (read): return nil
           return nil
         else
@@ -72,7 +72,9 @@ module Gorillib
     end
 
     def set_collection_item(plural_name, item_key, item)
-      collection_of(plural_name)[item_key] = item
+      collection = collection_of(plural_name)
+      collection[item_key] = item
+      collection[item_key]
     end
 
     def has_collection_item?(plural_name, item_key)
@@ -84,13 +86,11 @@ module Gorillib
     end
 
     def to_key
-      self.read_attribute(key_method)
+      self.send(key_method)
     end
 
-    def inspect_helper(detailed, attrs)
-      attrs.delete(:owner)
-      # detailed ? str : ([str[0..-2], " #{to_key}>"].join)
-      str = super(detailed, attrs)
+    def to_inspectable
+      super.tap{|attrs| attrs.delete(:owner) }
     end
 
     def collection_of(plural_name)
@@ -106,10 +106,11 @@ module Gorillib
       def member(field_name, type, options={})
         field(field_name, type, {:field_type => ::Gorillib::Builder::MemberField}.merge(options))
       end
+
+      # FIXME: this interface is borked -- it should not take the item_type in the second slot.
       def collection(field_name, item_type, options={})
-        field(field_name, Gorillib::ModelCollection, {
-            :item_type => item_type,
-            :field_type => ::Gorillib::Builder::CollectionField}.merge(options))
+        super(field_name, Gorillib::ModelCollection, {
+            :item_type => item_type, :field_type => ::Gorillib::Builder::GetsetCollectionField }.merge(options))
       end
 
     protected
@@ -141,20 +142,6 @@ module Gorillib
         end
       end
 
-      def define_collection_receiver(field)
-        plural_name = field.name; item_type = field.item_type; field_type = field.type
-        define_meta_module_method("receive_#{plural_name}", true) do |coll, &block|
-          begin
-            if coll.is_a?(field_type)
-              write_attribute(plural_name, coll)
-            else
-              read_attribute(plural_name).receive!(coll, &block)
-            end
-            self
-          rescue StandardError => err ; err.polish("#{self.class} #{plural_name} c[#{item_type}] on #{args}'") rescue nil ; raise ; end
-        end
-      end
-
       def define_collection_tester(field)
         plural_name = field.plural_name
         define_meta_module_method("has_#{field.singular_name}?", field.visibility(:collection_tester)) do |item_key|
@@ -223,9 +210,8 @@ module Gorillib
       end
     end
 
-    class CollectionField < Gorillib::Model::Field
+    class GetsetCollectionField < ::Gorillib::Model::SimpleCollectionField
       field :singular_name, Symbol, :default => ->{ Gorillib::Inflector.singularize(name.to_s).to_sym }
-      field :item_type, Class, :default => Whatever
 
       self.visibilities = visibilities.merge(:writer => false, :tester => false,
         :collection_getset => :public, :collection_tester => true)
@@ -236,8 +222,6 @@ module Gorillib
       end
 
       def inscribe_methods(model)
-        item_type      = self.item_type
-        self.default   = ->{ Gorillib::ModelCollection.new(nil, item_type) }
         raise "Plural and singular names must differ: #{self.plural_name}" if (singular_name == plural_name)
         #
         @visibilities[:writer] = false
@@ -249,6 +233,7 @@ module Gorillib
         model.__send__(:define_collection_tester,   self)
       end
     end
+    CollectionField = GetsetCollectionField
 
   end
 end