icss-activesupport-4 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 831c3bf554456a2075e061ea3fb803cb04b5d3f4
+  data.tar.gz: cfefd952f5d5294346cdbf099a3d44befa275d45
+SHA512:
+  metadata.gz: 0aa9b080a7d61b3a25df32ee8b899e4696c798f60e1fed56c1d602ccc2295efdf70469174b40dbde7f1c153104f8225192fca346729f04404be6da889315ff6d
+  data.tar.gz: 7e96375397b3edde133d70e6986f6e7aaa3ebef1cf646e2fd88b3a11c24fb96a64ec07dbc6ff30d2c6513ba1ceb9ae9f7a6c5c861bedaeb17ad72631cf4eb3f4

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--drb

data/.watchr

@@ -0,0 +1,52 @@
+# -*- ruby -*-
+
+# def run_spec(pattern, subdir = '')
+#   subdir << '/' unless subdir == '' || subdir =~ %r{./$}
+#   if !(files = Dir["spec/#{subdir}**/*#{pattern}*_spec.rb"]).empty?
+#     rspec(files)
+#   end
+# end
+
+def run_with_ruby(file)
+  unless File.exist?(file) then puts "#{file} does not exist" ; return ; end
+  puts   "Running #{file}"
+  system "ruby", file
+  puts
+end
+
+def run_spec(file)
+  unless File.exist?(file)
+    puts "#{file} does not exist"
+    return
+  end
+
+  puts   "Running #{file}"
+  # system "bundle exec rspec #{file}"
+  system "rspec #{file}"
+  puts
+end
+
+watch("spec/.*/.*_spec\.rb") do |match|
+  run_spec match[0]
+end
+
+watch("spec/.*_spec\.rb") do |match|
+  run_spec match[0]
+end
+
+watch("lib/icss.rb") do |match|
+  run_spec      %{spec/icss_spec.rb}
+end
+
+watch("lib/icss/(.*)\.rb") do |match|
+  if match.string =~ /zaml/
+    run_with_ruby %{spec/#{match[1]}_test.rb}
+    run_spec      %{spec/#{match[1]}_spec.rb}
+  else
+    run_spec      %{spec/#{match[1]}_spec.rb}
+  end
+end
+
+watch("spec/.*_test\.rb") do |match|
+  run_with_ruby match[0]
+end

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+
+## v0.2.0 mid-Aug 2011
+
+Major rethunk.
+
+* Type behavior is provided by 
+* 
+
+TODO:
+
+* move Targets into troop (?)
+
+
+#### CatalogTarget becomes small
+
+Become protocol attributes:
+* `name`        -- protocol `name` (ie. the `protocol` field)
+* `license`     -- protocol `license`
+* `title`       -- alias for protocol's name
+* `description` -- protocol `doc`
+* `tags`        -- protocol `keywords` 
+
+These stay:
+* `owner`, `price`, `messages`, `packages`
+
+These move from protocol to CatalogTarget:
+* update_frequency
+* namespace
+
+## v0.1.0 June 7 2011
+
+* New receiver from gorillib
+
+## v0.0.3 May 22 2011
+
+* used gorillib, got rid of active_support, extlib HOORAY
+* moved Receiver to gorillib.
+* *breaking change*. Gorillib changed the signature of receive() to be @receive(*constructor_args, hsh)@ (formerly, the hsh was first).

data/Gemfile

@@ -0,0 +1,22 @@
+source 'http://rubygems.org'
+
+gem     'json'
+gem     'activemodel',     "~> 4.0"
+gem     'addressable',     "~> 2.2"
+
+gem     'configliere',     "~> 0.4.8"
+gem     'gorillib',        "~> 0.1.7"
+
+group                    :development do
+  gem   'bundler',         "~> 1"
+  gem   'jeweler',         "~> 1.6.4"
+  gem   'yard',            "~> 0.6.0"
+  gem   'rspec',           "~> 2.5.0"
+  gem   'simplecov',       ">= 0"
+  gem   'awesome_print',   "~> 0.4.0"
+end
+
+group                    :test do
+  gem   'spork',           "~> 0.9.0.rc9"
+  gem   'watchr'
+end

data/LICENSE.textile

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Philip (flip) Kromer for Infochimps
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,298 @@
+# The Infochimps Stupid Schema (ICSS)
+
+An ICSS file is a *complete*, *expressive* description of a collection of related data and all associated assets. It is based on the [Avro Protocol](http://avro.apache.org/docs/current/index.html) specification, with some necessary extensions
+
+
+___________________________________________________________________________
+<a name="model" >
+
+## Icss::ReceiverModel -- a pragmatic, flexible framework for active structured data
+
+### (or: How to Be Object-Oriented in a JSON World)
+
+Hooray:
+
+```ruby
+    class Thing
+      include Icss::ReceiverModel
+      field :name, String
+      field :description, String
+    end
+    
+    class GeoCoordinates
+      include Icss::ReceiverModel
+      field :longitude, Float, :validates => { :numericality => { :>= => -180, :<= => 180  } }
+      field :latitude,  Float, :validates => { :numericality => { :>= =>  -90, :<= =>  90  } }
+      def coordinates
+        [ longitude, latitude ]
+      end
+    end
+    
+    class Place < Thing
+      field :geo, GeoCoordinates
+    end
+    
+    class MenuItem < Thing
+      field :price, Float, :required => true
+    end
+    
+    class TacoTrailer < Place
+      field :menu,          Array, :items => MenuItem
+      field :founding_date, Time
+    end
+    
+    torchys = Restaurant.receive({
+      :name => "Torchy's Taco's",
+      :menu => [ 
+        { :name => "Dirty Sanchez", :price => "6.95" }, 
+        { :name => "Fried Avocado", :price => "7.35" }
+      ],
+      :founding_date => '2006-08-01T00:00:00Z',
+      :geo  => { :longitude => 30.295, :latitude => -97.745 },
+    })
+    # #<TacoTrailer:0x00000101d539f8 @name="Torchy's Taco's", 
+    #   @geo=#<GeoCoordinates:0x00000101d53318 @latitude=-97.745, @longitude=30.295>,
+    #   @menu=[ #<MenuItem:0x00000101d51180 @name="Dirty Sanchez", @price=6.95>, 
+    #           #<MenuItem:0x00000101d4d468 @name="Fried Avocado", @price=7.35>  ]
+    #   @founding_date=2006-08-01 00:00:00 UTC >
+
+    torchys.geo.coordinates
+    # [ 30.295, -97.745 ]
+
+    torchys.to_hash
+    # { :name => "Torchy's Taco's",
+    #   :geo  => { :longitude => 30.295, :latitude => -97.745 },
+    #   :menu => [
+    #     { :name => "Dirty Sanchez", :price => 3.50 },
+    #     { :name => "Fried Avocado", :price => 2.95 } ],
+    #   :founding_date => '2006-08-01T00:00:00Z',
+    # }
+
+
+```
+
+### declaring fields
+
+Declaring a field constructs the following. Taking 
+
+```ruby
+    field :foo, Array, :items => :int
+```
+
+* accessors       -- `#foo` and `foo=` getter/setters. These are completely regular accessors: no type checking/conversion/magic happens when the object is in regular use. 
+* receiver        -- a `receive_foo` method that provides lightweight type coercion
+* field schema    -- a `RecordField` object describing the field, available through the `.fields` class method. You can send this schema over the wire (in JSON or whatever) and use it to recapitulate the type elsewhere.
+* hashlike access -- retrieve a value with `object[:foo]`, or set it with `object[:foo] = 7`. 
+
+Optionally, you can decorate with
+
+* rcvr_remaining -- a catchall field for anything `receive!`d that wasn't predicted by the schema.
+* validations  -- the full set of ActiveModel validations
+* after_receive hooks -- including default value
+
+### Predictable magic
+
+Magic *only* happens in the neighborhood of `receive` methods. 
+* The initializer, getter/setter, and so forth are non-magical. 
+* Validation is only done on request, and type conversion when `receive_foo` is invoked.
+* Hashlike access is only for defined fields
+
+### receive methods
+
+You can make a new ojbect using `Smurf.receive({...})`, which is exactly equivalent to calling each of `obj = Smurf.new ; obj.receive!({...}) ; obj` in turn.
+
+### Hashlike
+
+* `.keys` returns a list of the *fields with set values*, in the same order as the class `.field_names`
+
+### validations
+
+Add ActiveModel validations with the `:validates` option to `.field`, or directly using `.validates`:
+
+```ruby
+    class Icss::Handy
+      include Icss::ReceiverModel
+      field :rangey,     Integer, :validates => { :inclusion => { :in => 0..9 }}
+      field :patternish, String
+      field :mandatory,  Integer, :required => true
+      validates :patternish, :format => { :with => /eat$/ }
+    end
+    good_smurf = Icss::Handy.receive(:rangey => 5, :patternish => 'smurfberry crunch is fun to eat', :mandatory => 1)
+    bad_smurf  = Icss::Handy.receive(:rangey => 3, :patternish => 'smurfnuggets!')
+    good_smurf.valid? # true
+    bad_smurf.valid?  # false
+    bad_smurf.errors  # { :mandatory  => ["can't be blank"], :patternish => ["is invalid"] }
+```
+
+As shown, you can also say `:required => true` as a shorthand for `:validates => { :presence => true }`. A summary of the other `:validates` directives:
+
+```ruby
+    :presence     => true
+    :uniqueness   => true
+    :numericality => true           # also :==, :>, :>=, :<, :<=, :odd?, :even?, :equal_to, :less_than, etc
+    :length       => { :<  => 7 }   # also :==, :>=, :<=, :is, :minimum, :maximum
+    :format       => { :with => /.*/ }
+    :inclusion    => { :in => [1,2,3] }
+    :exclusion    => { :in => [1,2,3] }
+```
+
+### rcvr_remaining
+
+`rcvr_remaining` creates a Hash field to catch all attributes send to `receive!` that don't match any receiver fields. This is surprisingly useful.
+
+Note that you can feed `rcvr_remaining` a `:values` option if you want type coercion on the extra params.
+
+### rcvr_alias
+
+`rcvr_alias` will redirect an attribute to a different receiver:
+
+```ruby
+    class Wheel
+      include Icss::ReceiverModel
+      field      :name,          String
+      field      :center_height, Float
+      rcvr_alias :centre_height, :center_height
+    end
+    foo = Wheel.receive(:name => 'tyre', :centre_height => 18.2)
+    foo.center_height               # 18.2
+    foo.respond_to?(:centre_height) # false
+```   
+
+Notes:
+
+* It does not make any other methods, only a `receive_(fake)` that calls the `receive_(target)` method.
+* It makes no special provisions for both attributes being received.
+
+### after_receive
+
+`after_receive(:hook_name){ ... }` creates a named hook, executed at the end of `receive!` (and similar actions). Some examples:
+
+```ruby
+    after_receive(:warnings) do |hsh|
+      warn "Validation failed for field #{self}: #{errors.inspect}" if respond_to?(:errors) && (not valid?)
+    end
+    after_receive(:generate_id) do |hsh|
+      if !attr_set?(:md5id) then self.md5id = Digest::MD5.hex_digest(name) ; end
+    end    
+```
+
+Notes:
+* Make sure your `after_receive` blocks are _idempotent_ -- that is, that re-running the block has no effect. Lots of things are allowed to trigger `run_after_receivers`.
+
+### field :default => val
+
+You can use the `:default` option to `field` (or call `.set_field_default` directly) to specify a default value when the field is empty after a `receive!`.
+
+```ruby
+    class Icss::Smurf
+      field :tool,    Symbol, :default => :smurfwrench
+      field :weapon,  Symbol, :default => :smurfthrower
+    end
+    
+    # default set for missing attributes
+    handy_smurf = Icss::Smurf.receive( :tool => :pipesmurf )
+    handy_smurf.weapon # :smurfthrower
+    
+    # if an attribute is set-but-nil no default is applied
+    handy_smurf = Icss::Smurf.receive( :tool => :smurfwrench, :weapon => nil )
+    handy_smurf.weapon # nil
+    
+    # you can also use a block; it is `instance_eval`ed for the value to set.
+    Icss::Smurf.field(:food, Symbol, :default => 
+      lambda{ (weapon.to_s =~ /^smurf/) ? :smurfed_cheese : :grilled_smurf }
+    brainy_smurf = Icss::Smurf.receive( :weapon => :smurfapult    )
+    hefty_smurf  = Icss::Smurf.receive( :weapon => :gatling_smurf )
+    brainy_smurf.food # :smurfed_cheese
+    hefty_smurf.food  # :grilled_smurf
+```
+
+Note:
+* If a value is explicitly `nil`, the default is not applied.
+* You may specify a block (as shown); the attribute is set to the result of `instance_eval`ing the block.
+* Defaults do *not* applied at initialization -- only when `run_after_receivers` is triggered. (so, the `receive` operation is complete).
+* The run order will be dependable on ruby >= 1.9 but not on 1.8.x.
+
+
+
+___________________________________________________________________________
+<a name="avro" >
+## Avro Protocol, Message, RecordType and Field
+
+
+    avro        kind        ruby           json      example                schema example
+    ---------   ---------   ------------   -------   ---------              --------------
+    null        base        NilClass       null      nil                    'null'
+    boolean     base        Boolean        boolean   true                   'boolean'
+    int         base        Integer        integer   1                      'int'
+    long        base        Long           integer   1                      'long'
+    float       base        Float          number    1.1                    'float'
+    double      base        Double         number    1.1                    'double'
+    bytes       base        Binary         string    "\u00FF"               'bytes'
+    string      base        String         string    "foo"                  'string'
+    time        base        Time           string    "2011-01-02T03:04:05Z" 'time'
+    symbol      base        Symbol         string    :belongs_to            'symbol'
+
+    array       structured  (ArrayOfXXX)   array     [1,2]                  { 'type': 'array',  'items':  'int' }
+    map         structured  (HashOfXXX)    object    { "a": 1 }             { 'type': 'map',    'values': 'int' }
+
+    enum        named       (EnumType)     string    "heads"                { 'type': 'enum',   'name': 'result', 'symbols': ['heads','tails'] }
+    fixed       named       (FixedType)    string    "\xBD\xF3)Q"           { 'type': 'fixed',  'name': 'crc32',  'length': 4 }
+    record      named       (RecordType)   object    {"a": 1}               { 'type': 'record', 'name': 'bob',    'fields':[...] }
+    error       named       (ErrorType)    object    {"err":halp! fire!"}   { 'type': 'record', 'name': 'db_on_fire, 'fields':[...] }
+
+    union       union       <UnionType>    object                           [ 'long', { 'type': 'array', 'items': 'int' } ]
+
+    st.regexp   simple      St::Regexp     string    "^hel*o newman"        'regexp'
+    st.url      simple      St::Url        string    "http://..."           'url'
+    mu.epoch_time simple    Mu::EpochTime  string    1312507492             'epoch_time'
+
+
+
+#### Base (int, float, string, ...)
+
+A `:base` type in an Icss file 
+
+Class `.receive` method is just `new` (where appropriate) with the appropriate conversion. Receiving `nil` returns `nil` without error.
+
+Note that some of the base types are *not* present in the Avro spec.
+
+__________________________________________________________________________
+__________________________________________________________________________
+__________________________________________________________________________
+
+___________________________________________________________________________
+<a name="protocol" >
+## Icss::Protocol specifics
+
+### Assets
+
+Assets may include
+* data assets (including their location and schema)
+* code for api calls (messages) based on the the described records (including their call signature and schema)
+* other referenced schema
+
+See [icss_specification.textile](icss/blob/master/icss_specification.textile) for more.
+
+___________________________________________________________________________
+<a name="colophon" >
+## Colophon
+
+### Credits
+
+Huge thanks to Doug Cutting and the rest of the Avro maintainers.
+
+### Contributing to icss
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+### Copyright
+
+Copyright (c) 2011 Philip (flip) Kromer for Infochimps. See LICENSE.txt for
+further details.
+