gorillib 0.4.2 → 0.5.0

data/notes/structured-data-classes.md

@@ -0,0 +1,127 @@
+# gorillib's structured data classes -- Record, Model, Builder and Bucket
+
+## Overview
+
+Gorillib provides these general flavors of model:
+
+* `Gorillib::Record`: **lightweight structured records**. Easily assemble a dynamic data structure that enables both rich behavior and generic manipulation, serialization and transformation. Especially useful when you just need to pull something from JSON, attach some functionality, and get it back on the wire.
+
+      ```ruby
+      class Place
+        include Gorillib::Record
+        # fields can be simple...
+        field :name, String
+        field :country_id, String, :doc => 'Country code (2-letter alpha) containing the place'
+        # ... or complext
+        field :geo, GeoCoordinates, :doc => 'geographic location of the place'
+      end
+      
+      class GeoCoordinates
+        include Gorillib::Record
+        field :latitude,  Float, :doc => 'latitude in decimal degrees; negative numbers are south of the equator'
+        field :longitude, Float, :doc => 'longitude in decimal degrees; negative numbers are west of Greenwich'
+      end
+
+      # It's simple to instantiate complex nested data structures
+      lunch_spot = Place.receive({ :name => "Torchy's Tacos", :country_id => "us",
+        :geo => { :latitude => "30.295", :longitude => "-97.745" }})
+      ```
+
+* `Gorillib::Model`: **rich structured models** offering predictable magic with a disciplined footprint. Comparable to ActiveRecord or Datamapper, but for a world dominated by JSON+HTTP, not relational databases
+
+      ```ruby
+      class GeoCoordinates
+        include Gorillib::Model
+        field :latitude,  Float, :doc => 'latitude in decimal degrees; negative numbers are south of the equator', :validates => { :numericality => { :>= =>  -90, :<= =>  90  } }
+        field :longitude, Float, :doc => 'longitude in decimal degrees; negative numbers are west of Greenwich', :validates => { :numericality => { :>= => -180, :<= => 180  } }
+      end
+      position = GeoCoordinates.from_tuple(30.295, -97.745)
+      # A Gorillib::Model obeys the ActiveModel contract
+      GeoCoordinates.model_name.human # => 'Geo coordinates'
+      ```
+
+* `Gorillib::Builder`: **foundation models for elegant ruby DSLs** (Domain-Specific Languages). Relaxes ruby syntax to enable highly-readable specification of complex behavior.
+
+      ```ruby
+      workflow(:bake_pie) do
+        step   :make_crust
+        step   :add_filling
+        step   :bake
+        step   :cool
+      end
+      ```
+
+* `Gorillib::Bucket` (?name?): **record-style access to freeform hashes**. Provide a disciplined interface on top of arbitrarily-structured data. Used by [[Configliere]] and others.
+
+       ```ruby
+       # pre-defining a field gives you special powers...
+       Settings.define :port,   Integer, :doc => 'API server port number', :default => 80
+       # but you can still store or read anything you'd like...
+       Settings[:shout] = "SAN DIMAS HIGH SCHOOL FOOTBALL RULES"
+       # and treat the object as a hash when you'd like to
+       conn = Connections.open(Settings.merge(user_overrides))
+       ```
+
+## Decisions
+
+* **initializer** - *does not* inject an initializer; if you want one, do `alias_method :initialize, :receive!`
+* **frills** --
+  - *does inject*: `inspect` on the class, `inspect`, `to_s` on the instance
+  - *does inject*: accessors (`foo`, `foo=`) for each field.
+  - *does inject*: `==` on the instance
+  - *does not define*: `schema`, `initialize`
+* **field defaults** - evaluated on first read, at which point its value is fixed on the record.
+
+* **define_metamodel_record** -- visibility=false does not remove an existing method from the metamodel
+
+* ?? **hash vs mash** -- does `attributes` return a mash or hash?
+* are these basic functionality:
+  - **extra_attributes** -- ??
+  - **default**          -- ??
+
+* Record:
+  - class methods -- `field`, `fields`, `field_names`, `has_field?`, `metamodel`, `receive`, `inspect`
+  - instance methods  -- `read_attribute`, `write_attribute`, `unset_attribute`, `attribute_set?`, `attributes`, `receive!`, `update`, `inspect`, `to_s`, `==`
+  - with each attribute  -- `receive_foo`, `foo=`, `foo`
+
+* Builder:
+  - defining classes before they're used
+
+
+## Features
+
+### `Record`
+
+* `Record::Ordered`       -- sort order on fields (and thus record)
+* `Record::FieldAliasing` -- aliases for fields and receivers
+* `Record::Defaults`      -- default values
+* `Record::Schema`        -- icss schema
+* `Record::HashAccessors` -- adds `[]`, `[]=`, `delete`, `keys`, `#has_key?`, `to_hash`, and `update`. This allows it to be `hashlike`, but you must include that explicitly.
+* `Record::Hashlike`      -- mixes in `Record::HashAccessors` and `Gorillib::Hashlike`, making it behave in almost every respect like a hash. Use this when you want something that will *behave* like a hash but *be* a record. If you want something to *be* a hash but *behave* like a record, use the `Gorillib::MashRecord`
+
+### `Builder`
+
+* `Builder::GetsetField`  --
+
+### `HashRecord`
+
+### `Model`
+
+* `Model::Naming`
+* `Model::Conversion`     --
+
+### active_model / active_model_lite
+
+From `active_model` or `active_model_lite`:
+
+* `Model::Callbacks`      --
+* `Model::Dirty`          --
+* `Model::Serialization`  --
+* `Model::Validations`    -- implies `Model::Errors`, `Model::Callbacks`
+
+
+## Why, in a world with ActiveRecord, Datamapper, Hashie, Struct, ..., do we need yet another damn model framework?
+
+ActiveRecord and Datamapper excel in a world where data (and truth) live in the database. ActiveRecord sets the standard for elegant magic, but is fairly heavyweight (I don't want to include a full XML serialization suite just so I can validate records). This often means it's overkill for the myriad flyweight scripts, Goliath apps, and such that we deploy. Datamapper does a remarkable job of delivering power while still being light on its toes, but ultimately is too tightly bound to an ORM view of the world. Hashie, Structs and OStructs behave as both hashes and records. In my experience, this interface is too generous -- their use leads to mealymouthed code.
+
+More importantly, our data spends most of its time on the wire or being handled as an opaque blob of data; a good amount of time being handled as a generic bundle of properties; and (though most important) a relatively small amount of time as an active, assertive object. So type conversion and validation are fundamental actions, but shouldn't crud up my critical path or be required. Models should offer predictable and disciplined features, but be accessable as generic bags of facts.

data/spec/gorillib/array/hashify_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+require 'gorillib/array/hashify'
+
+describe Array, :simple_spec, :only do
+
+  describe '#hashify' do
+    it 'returns a hash pairing elements with value from block' do
+      [1,2,3].hashify{|x| x * x }.should == { 1 => 1, 2 => 4, 3 => 9 }
+      [1,2,3].hashify{|x| x > 2 ? nil : x }.should == { 1 => 1, 2 => 2, 3 => nil }
+    end
+    it "returns an empty hash on an empty array" do
+      [].hashify{}.should == {}
+    end
+    it "fails if no block given" do
+      expect{ [1,2,3].hashify }.to raise_error(ArgumentError)
+    end
+
+  end
+
+end

data/spec/gorillib/builder_spec.rb

@@ -17,8 +17,8 @@ describe Gorillib::Builder, :model_spec => true, :builder_spec => true do
   context 'examples:' do
     let(:subject_class  ){ car_class }
     it 'type-converts values' do
-      obj = subject_class.receive(     :name => 'wildcat', :make_model => 'Buick Wildcat', :year => "1968", :doors => "2" )
-      obj.attributes.should == { :name => :wildcat,  :make_model => 'Buick Wildcat', :year =>  1968,  :doors =>  2, :engine => nil }
+      obj = subject_class.receive( :name => 'wildcat', :make_model => 'Buick Wildcat', :year => "1968", :doors => "2" )
+      obj.attributes.should == {   :name => :wildcat,  :make_model => 'Buick Wildcat', :year =>  1968,  :doors =>  2, :engine => nil }
     end
     it 'handles nested structures' do
       obj = subject_class.receive(

data/spec/gorillib/{model/factories_spec.rb → factories_spec.rb}

@@ -1,5 +1,5 @@
 require 'spec_helper'
-# require 'support/factory_test_helpers'
+require 'support/factory_test_helpers'
 
 require 'gorillib/object/blank'
 require 'gorillib/object/try_dup'
@@ -8,11 +8,9 @@ require 'gorillib/metaprogramming/class_attribute'
 require 'gorillib/string/inflector'
 
 require 'gorillib/collection'
-require 'gorillib/model/factories'
+require 'gorillib/factories'
 
-require 'factory_test_helpers'
-
-describe '', :model_spec, :factory_spec, :only do
+describe '', :model_spec, :factory_spec do
 
   describe Gorillib::Factory do
     describe 'Factory()' do

data/spec/gorillib/model/serialization/tsv_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+require 'support/model_test_helpers'
+
+require 'multi_json'
+#
+require 'gorillib/model'
+require 'gorillib/builder'
+require 'gorillib/model/serialization/tsv'
+
+describe Gorillib::Model, :model_spec, :builder_spec do
+
+  context ".load_tsv" do
+    # it "respects blank characters at end of line, so '1\\t2\\t\\t\\t becomes [\"1\",\"2\",\"\",\"\",\"\"]" do
+    #   # make sure
+    # end
+  end
+end

data/spec/gorillib/type/ip_address_spec.rb

@@ -0,0 +1,143 @@
+require 'spec_helper'
+require 'support/factory_test_helpers'
+require 'gorillib/object/blank'
+#
+require 'gorillib/type/ip_address'
+
+shared_examples_for(:ip_addresslike) do
+
+  its(:dotted){ should == '1.2.3.4' }
+  its(:quads){  should == [1, 2, 3, 4] }
+  its(:packed){ should == packed_1234 }
+
+  context '.from_packed' do
+    subject{ described_class.from_packed(packed_1234) }
+    it{ should be_a(described_class) }
+    its(:dotted){ should == '1.2.3.4' }
+  end
+
+  context '#bitness_min' do
+    it('is unchanged for /32'){ subject.bitness_min(32).should == subject.packed }
+    {  0 => 0,          # '0.0.0.0'
+       6 => 0,          # '0.0.0.0'
+       8 => 0x01000000, # '1.0.0.0',
+      30 => 0x01020304, # '1.2.3.4',
+    }.each do |bitness, result|
+      it("returns #{result} for #{bitness}"){ subject.bitness_min(bitness).should == result }
+    end
+    it 'raises an error if bitness is out of range' do
+      expect{ subject.bitness_min(33)    }.to raise_error(ArgumentError, /only 32 bits.*33/)
+      expect{ subject.bitness_min(-1)    }.to raise_error(ArgumentError, /only 32 bits.*-1/)
+      expect{ subject.bitness_min('bob') }.to raise_error(ArgumentError, /only 32 bits.*bob/)
+    end
+  end
+
+  context '#bitness_max' do
+    it 'returns an integer' do
+      subject.bitness_max(24).should equal(16909311)
+    end
+    it('is unchanged for /32'   ){ subject.bitness_max(32).should == subject.packed }
+    {  0 => 0xFFFFFFFF, # '255.255.255.255'
+       6 => 0x03FFFFFF, # '3.255.255.255'
+       8 => 0x01FFFFFF, # '1.255.255.255'
+      31 => 0x01020305, # '1.2.3.5'
+    }.each do |bitness, result|
+      it("returns #{result} for #{bitness}"){ subject.bitness_max(bitness).should == result }
+    end
+    it 'raises an error if bitness is out of range' do
+      expect{ subject.bitness_max(33)    }.to raise_error(ArgumentError, /only 32 bits.*33/)
+      expect{ subject.bitness_max(-1)    }.to raise_error(ArgumentError, /only 32 bits.*-1/)
+      expect{ subject.bitness_max('bob') }.to raise_error(ArgumentError, /only 32 bits.*bob/)
+    end
+  end
+end
+
+describe ::IpAddress do
+  let(:packed_1234){ 16909060 }
+  let(:dotted_1234){ '1.2.3.4' }
+  subject{ described_class.new('1.2.3.4') }
+
+  it_should_behave_like(:ip_addresslike)
+
+  its(:to_i){ should equal(packed_1234) }
+  it{ expect{ subject.to_int }.to raise_error(NoMethodError, /undefined method.*\`to_int\'/) }
+end
+
+describe ::IpNumeric do
+  let(:packed_1234){ 16909060 }
+  let(:dotted_1234){ '1.2.3.4' }
+  subject{ described_class.new(packed_1234) }
+
+  it_should_behave_like(:ip_addresslike)
+
+  context '.from_dotted' do
+    subject{ described_class.from_dotted(dotted_1234) }
+    it('memoizes #dotted') do
+      val = subject.instance_variable_get('@dotted')
+      val.should == '1.2.3.4'
+      val.should be_frozen
+    end
+    it('memoizes #quads') do
+      val = subject.instance_variable_get('@quads')
+      val.should == [1,2,3,4]
+      val.should be_frozen
+    end
+  end
+
+end
+
+
+describe ::IpRange do
+  let(:beg_1234){ 16909060 }
+  let(:end_1234){ 16909384 }
+  subject{ described_class.new(beg_1234 .. end_1234) }
+
+  its(:min){ should == beg_1234 }
+  its(:max){ should == end_1234 }
+  its(:min){ should be_a(IpNumeric) }
+  its(:max){ should be_a(IpNumeric) }
+
+  context 'bitness_blocks' do
+    it 'emits nothing if empty' do
+      described_class.new(50, 49).bitness_blocks(24).should == []
+    end
+    it 'emits only one block if min and max are in same bitness block' do
+      described_class.new(40, 80).bitness_blocks(24).should == [ [40, 80] ]
+    end
+    it 'emits only one block if min and max are the same' do
+      described_class.new(40, 40).bitness_blocks(24).should == [ [40, 40] ]
+    end
+    it 'emits two short blocks if min and max are in neighboring blocks' do
+      described_class.new(40, 260).bitness_blocks(24).should == [ [40, 255], [256, 260] ]
+    end
+    it 'emits intermediate blocks if min and max are far apart' do
+      described_class.new(40, 520).bitness_blocks(24).should == [ [40, 255], [256, 511], [512, 520] ]
+    end
+
+    {
+      [ '255.255.255.255', '255.255.255.255',  0 ] => [ [0xFFFFFFFF, 0xFFFFFFFF] ],
+      [ '255.255.255.255', '255.255.255.255', 24 ] => [ [0xFFFFFFFF, 0xFFFFFFFF] ],
+      [ '255.255.255.255', '255.255.255.255', 32 ] => [ [0xFFFFFFFF, 0xFFFFFFFF] ],
+      [ '255.255.254.1',   '255.255.255.255',  0 ] => [ [0xFFFFFe01, 0xFFFFFFFF] ],
+      [ '255.255.254.1',   '255.255.255.255', 24 ] => [ [0xFFFFFe01, 0xFFFFFeFF], [0xFFFFFF00, 0xFFFFFFFF] ],
+      [ '255.255.253.1',   '255.255.255.7',   24 ] => [ [0xFFFFFd01, 0xFFFFFdFF], [0xFFFFFe00, 0xFFFFFeFF], [0xFFFFFF00, 0xFFFFFF07] ],
+      [ '0.0.0.0',         '0.0.0.0',         24 ] => [ [0x0,        0x0], ],
+      [ '0.0.0.255',       '0.0.1.0',         24 ] => [ [0xFF, 0xFF], [0x100, 0x100] ],
+      [ '0.0.0.7',         '0.0.0.10',        31 ] => [ [0x7, 0x7], [0x8, 0x9], [0xa, 0xa], ],
+      [ '0.0.0.7',         '0.0.0.11',        31 ] => [ [0x7, 0x7], [0x8, 0x9], [0xa, 0xb], ],
+      [ '0.0.0.0',         '0.0.0.0',         24 ] => [ [0x0,        0x0], ],
+      [ '0.0.1.7',         '0.0.1.255',       24 ] => [ [0x107,      0x1FF], ],
+      [ '0.0.1.7',         '0.0.2.7',         24 ] => [ [0x107,      0x1FF], [0x200, 0x207] ],
+      [ '0.0.1.7',         '0.0.3.7',         24 ] => [ [0x107,      0x1FF], [0x200, 0x2FF], [0x300, 0x307] ],
+    }.each do |(beg_ip, end_ip, bitness), blocks|
+      it "/#{bitness}-bit blocks of #{beg_ip}..#{end_ip} are #{blocks}" do
+        beg_ip = IpNumeric.from_dotted(beg_ip)
+        end_ip = IpNumeric.from_dotted(end_ip)
+        subject = IpRange.new(beg_ip .. end_ip)
+        subject.bitness_blocks(bitness).should == blocks
+      end
+    end
+
+  end
+
+end

metadata

@@ -2,7 +2,7 @@
 name: gorillib
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors: 
 - Infochimps
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-09-06 00:00:00 Z
+date: 2012-10-22 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: multi_json
@@ -118,8 +118,18 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
+- CHANGELOG.md
 - LICENSE.md
 - README.md
+- TODO.md
+- notes/HOWTO.md
+- notes/bucket.md
+- notes/builder.md
+- notes/collection.md
+- notes/factories.md
+- notes/model-overlay.md
+- notes/model.md
+- notes/structured-data-classes.md
 files: 
 - .gitignore
 - .rspec
@@ -141,6 +151,7 @@ files:
 - lib/gorillib/array/compact_blank.rb
 - lib/gorillib/array/deep_compact.rb
 - lib/gorillib/array/extract_options.rb
+- lib/gorillib/array/hashify.rb
 - lib/gorillib/array/simple_statistics.rb
 - lib/gorillib/array/wrap.rb
 - lib/gorillib/base.rb
@@ -203,12 +214,16 @@ files:
 - lib/gorillib/model/schema_magic.rb
 - lib/gorillib/model/serialization.rb
 - lib/gorillib/model/serialization/csv.rb
+- lib/gorillib/model/serialization/json.rb
+- lib/gorillib/model/serialization/lines.rb
+- lib/gorillib/model/serialization/tsv.rb
 - lib/gorillib/model/validate.rb
 - lib/gorillib/numeric/clamp.rb
 - lib/gorillib/object/blank.rb
 - lib/gorillib/object/try.rb
 - lib/gorillib/object/try_dup.rb
 - lib/gorillib/pathname.rb
+- lib/gorillib/pathname/utils.rb
 - lib/gorillib/serialization/to_wire.rb
 - lib/gorillib/some.rb
 - lib/gorillib/string/constantize.rb
@@ -219,16 +234,26 @@ files:
 - lib/gorillib/string/truncate.rb
 - lib/gorillib/type/boolean.rb
 - lib/gorillib/type/extended.rb
+- lib/gorillib/type/ip_address.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
+- notes/HOWTO.md
+- notes/bucket.md
+- notes/builder.md
+- notes/collection.md
+- notes/factories.md
+- notes/model-overlay.md
+- notes/model.md
+- notes/structured-data-classes.md
 - 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/hashify_spec.rb
 - spec/gorillib/array/simple_statistics_spec.rb
 - spec/gorillib/builder_spec.rb
 - spec/gorillib/collection_spec.rb
@@ -237,6 +262,7 @@ files:
 - spec/gorillib/datetime/to_flat_spec.rb
 - spec/gorillib/enumerable/sum_spec.rb
 - spec/gorillib/exception/raisers_spec.rb
+- spec/gorillib/factories_spec.rb
 - spec/gorillib/hash/compact_spec.rb
 - spec/gorillib/hash/deep_compact_spec.rb
 - spec/gorillib/hash/deep_merge_spec.rb
@@ -254,9 +280,9 @@ files:
 - 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/tsv_spec.rb
 - spec/gorillib/model/serialization_spec.rb
 - spec/gorillib/model_spec.rb
 - spec/gorillib/numeric/clamp_spec.rb
@@ -270,6 +296,7 @@ files:
 - spec/gorillib/string/inflector_test_cases.rb
 - spec/gorillib/string/truncate_spec.rb
 - spec/gorillib/type/extended_spec.rb
+- spec/gorillib/type/ip_address_spec.rb
 - spec/gorillib/utils/capture_output_spec.rb
 - spec/spec_helper.rb
 - spec/support/factory_test_helpers.rb
@@ -297,7 +324,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: -2648422057706542462
+      hash: 4018535107500327818
       segments: 
       - 0
       version: "0"
@@ -345,6 +372,7 @@ test_files:
 - spec/gorillib/utils/capture_output_spec.rb
 - spec/gorillib/collection_spec.rb
 - spec/gorillib/type/extended_spec.rb
+- spec/gorillib/type/ip_address_spec.rb
 - spec/gorillib/hash/zip_spec.rb
 - spec/gorillib/hash/reverse_merge_spec.rb
 - spec/gorillib/hash/slice_spec.rb
@@ -359,11 +387,12 @@ test_files:
 - spec/gorillib/hashlike/hashlike_via_accessors_spec.rb
 - spec/gorillib/hashlike/behave_same_as_hash_spec.rb
 - spec/gorillib/configurable_spec.rb
+- spec/gorillib/factories_spec.rb
+- spec/gorillib/model/serialization/tsv_spec.rb
 - spec/gorillib/model/lint_spec.rb
 - spec/gorillib/model/defaults_spec.rb
 - spec/gorillib/model/serialization_spec.rb
 - spec/gorillib/model/overlay_spec.rb
-- spec/gorillib/model/factories_spec.rb
 - spec/gorillib/pathname_spec.rb
 - spec/gorillib/enumerable/sum_spec.rb
 - spec/gorillib/object/try_spec.rb
@@ -372,6 +401,7 @@ test_files:
 - spec/gorillib/array/compact_blank_spec.rb
 - spec/gorillib/array/simple_statistics_spec.rb
 - spec/gorillib/array/extract_options_spec.rb
+- spec/gorillib/array/hashify_spec.rb
 - spec/gorillib/logger/log_spec.rb
 - spec/spec_helper.rb
 - spec/examples/builder/ironfan_spec.rb