id 0.0.12 → 0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4a4830e44c543e20bfbd0a69894f31e33f255d60
-  data.tar.gz: 910da24aa9829a4dbea10c6c77e64773fdf188bd
+  metadata.gz: 4626765bc042e4c08215636a3c50e751729ae2c7
+  data.tar.gz: 6a549d6d328b1b91583f9ec7f2819b6f9ecea0a9
 SHA512:
-  metadata.gz: 69f2da5ba66e623889de506206115604a152536f97dbfbcb75dbf00967d16fbf843d9aaae12c3d8f970d5ce4726aae2ee1691362330fc0b0d5faf6541c32915a
-  data.tar.gz: 3ea228e5c3c75256a77029b523236ae9e6be7cc264ae9db92b3b53d86b33456c4dfe2ad188f86e7fe4fa5e2c69687c53172a2a3d796c12a4b91fdb24b25fc5c5
+  metadata.gz: 6698ecb274e81d09550a410d6bf547b48d4ed124f173d0f9ef0d0270d0ca76eef757887c40c73c4c16b87167c1a6e86b0a63d21975d328b9c45464d1b7f3899d
+  data.tar.gz: 38ac9a455e27e9751e0fc3b66ce5d730c70cfb5ce83b38cfc4f66945f3147aecd199792994a675e85b8c069753d66e954d1f1aacc26c56d101af1e16cd3a17cd

data/Gemfile

@@ -1,5 +1,2 @@
 source 'https://rubygems.org'
 gemspec
-gem 'test-unit'
-gem 'json', '~> 1.7.7'
-gem 'money', '3.7.1'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    id (0.0.11)
+    id (0.1)
       activemodel
       activesupport
       money
@@ -19,16 +19,27 @@ GEM
       multi_json (~> 1.3)
       thread_safe (~> 0.1)
       tzinfo (~> 0.3.37)
-    atomic (1.1.12)
+    atomic (1.1.14)
     builder (3.1.4)
+    coveralls (0.7.0)
+      multi_json (~> 1.3)
+      rest-client
+      simplecov (>= 0.7)
+      term-ansicolor
+      thor
     diff-lcs (1.2.1)
-    i18n (0.6.4)
-    json (1.7.7)
+    i18n (0.6.5)
+    metaclass (0.0.1)
+    mime-types (1.25)
     minitest (4.7.5)
-    money (3.7.1)
-      i18n (~> 0.4)
+    mocha (0.14.0)
+      metaclass (~> 0.0.1)
+    money (5.1.1)
+      i18n (~> 0.6.0)
     multi_json (1.7.3)
     optional (0.0.7)
+    rest-client (1.6.7)
+      mime-types (>= 1.16)
     rspec (2.13.0)
       rspec-core (~> 2.13.0)
       rspec-expectations (~> 2.13.0)
@@ -41,18 +52,22 @@ GEM
       multi_json (~> 1.0)
       simplecov-html (~> 0.7.1)
     simplecov-html (0.7.1)
+    term-ansicolor (1.2.2)
+      tins (~> 0.8)
     test-unit (2.5.5)
-    thread_safe (0.1.2)
+    thor (0.18.1)
+    thread_safe (0.1.3)
       atomic
-    tzinfo (0.3.37)
+    tins (0.12.0)
+    tzinfo (0.3.38)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  coveralls
   id!
-  json (~> 1.7.7)
-  money (= 3.7.1)
+  mocha
   rspec
   simplecov
   test-unit

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2012 On The Beach Ltd
+Copyright (c) 2012 Russell Dunphy
 
 MIT License
 

data/README.md

@@ -3,63 +3,201 @@
 
 JSON is a great way to transfer data between systems, and it's easy to parse into a Ruby hash. But sometimes it's nice to have actual methods to call when you want to get attributes from your data, rather than coupling your entire codebase to the hash representation by littering it with calls to `fetch` or `[]`. The same goes for BSON documents stored in Mongo.
 
-That's where `id` (as in Freud) comes in. You define your model classes using syntax that should look pretty familiar if you've used any popular Ruby ORMs - but `id` is not an ORM. Model objects defined with `id` have a constructor that accepts a hash, and you define the values of this hash that are made readable as fields - but that hash can come from any source.
+That's where `id` (as in Freud) comes in. You define your model classes using syntax that should look pretty familiar if you've used any popular Ruby ORMs - but `id` is not an ORM. Model objects defined with `id` have a constructor that accepts a hash, and you define the values of this hash that are made readable as fields, but that hash can come from any source.
 
 #### Defining a model
 
-Defining a model looks like this:
+To define a model, include the `Id::Model` module in your class.
 
-    class MyModel
-      include Id::Model
+```ruby
+class Cat
+  include Id::Model
+end
+```
 
-      field :foo
-      field :bar, default: 42
-      field :baz, key: 'barry'
+#### Defining fields
 
-    end
+At its most basic, you can define a field like this:
 
-    my_model = MyModel.new(foo: 7, barry: 'hello')
-    my_model.foo # => 7
-    my_model.bar # => 42
-    my_model.baz # => 'hello'
+```ruby
+class Cat
+  field :name
+end
+```
 
-As you can see, you can specify default values as well as key aliases.
+This gives you the equivalent of an `attr_reader` for that field, as well as a predicate method which checks if it has been set (in the case of boolean fields, this predicate method also checks the value of that field - nil is interpreted as false).
+
+```ruby
+cat = Cat.new(name: "Travis")
+cat.name  # => "Travis"
+cat.name? # => true
+
+cat = Cat.new
+cat.name? # => false
+```
+
+###### What happens if you try to access a field that hasn't been set?
+
+```ruby
+irb(main):007:0> Cat.new.name
+  Id::MissingAttributeError: Cat had a nil value for 'name'.
+```
+Id is allergic to `nil`, and refuses to return it. If you want to access a field you need to be sure it's there, or you'll get an error. This means if you have a bug in your code and a field isn't set, you'll find out as soon as possible, rather that letting a `nil` leak out and cause an `undefined method 'foo' for nil:NilClass` at some unspecified future point, from where it might be hard to track down the source of the problem.
+
+###### What about optional fields?
+
+Sometimes fields really are optional. In this case you can either test for their presence using the predicate methods (which is a bit ugly, but at least forces you to deal with the empty case), or you can mark the field as `optional: true`, which will make them return an `Option` type rather than a raw value.
+
+`Option` types are a pattern found in many functional languages (the `Option` type in Scala, the `Maybe` monad in Haskell) and the Ruby implementation used by id can be found [here](http://github.com/rsslldnphy/optional).
+
+###### Can I set default values?
+
+Yes. Default values are specified like this:
+
+```ruby
+class Cat
+  ...
+  field :paws, default: 4
+end
+
+Cat.new.paws # => 4
+```
+
+You can also specify lambda defaults. These will be run on initialization of an instance of your model.
+
+```ruby
+class Cat
+  ...
+  field :birthday, default: -> { Date.new }
+end
+
+Cat.new.birthday # => #<Date: 2013-10-21 ((2456587j,0s,0n),+0s,2299161j)>
+```
+
+###### I don't like the key names in my data-source :-(
+
+We don't always get what we want. But don't despair! If the hash you're using to create your models has badly named keys - e.g., horror of horrors, keys in camelCase - you can use key aliases to convert them to nice, succinct, Rubyish identifiers:
+
+```ruby
+class Camel
+  include Id::Model
+
+  field :name,  key: 'camelName'
+  field :humps, key: 'camelHumps'
+end
+
+Camel.new('camelName' => 'Terry').name # => "Terry"
+```
+
+#### Type Coercion
+
+Id can coerce your fields into a number of basic types. Just specify the type you want as part of the field definition.
+
+```ruby
+class Cat
+  ...
+  field :paws, type: Integer
+end
+
+Cat.new(paws: "3").paws => 3
+Cat.new(paws: "3").paws.class => Integer
+```
+
+You can typecast array elements like this:
+
+```ruby
+field :counts, type: Array[Integer]
+```
+
+Because Ruby doesn't have a `Boolean` type (weird, right?), if you want to coerce something to either `true` or `false`, you need to use `Id::Boolean`, like this:
+
+```ruby
+field :admin, type: Id::Boolean
+```
+
+And if you need to coerce a type id doesn't yet support, such as a custom type of your own, you can register new coercions by passing the "from" type, "to" type, and a block to perform the conversion to `Id::Coercion.register`.
+
+```ruby
+Id::Coercion.register String, Money do |value|
+  value.to_money
+end
+```
+or more succinctly:
+
+```ruby
+Id::Coercion.register String, Money, &:to_money
+```
 
 #### Associations
 
-You can also specify has_one or has_many "associations" - what would be nested subdocuments in MongoDB for example - like this:
+If you have nested arrays or hashes in your source, you can define id models for them in turn, and treat them much like you would associations in an ORM, by defining them as `has_one` or `has_many` associations on the parent model.
 
-    class Zoo
-      include Id::Model
+```ruby
+class Lion
+  include Id::Model
+  field :name
+end
 
-      has_many :lions
-      has_many :zebras
-      has_one :zookeeper, type: Person
-    end
+class Person
+  include Id::Model
+  field :name
+end
 
-    zoo = Zoo.new(lions: [{name: 'Hetty'}],
-                  zebras: [{name: 'Lisa'}],
-                  zookeeper: {name: 'Russell' d})
+class Zoo
+  include Id::Model
 
-    zoo.lions.first.class # => Lion
-    zoo.lions.first.name  # => "Hetty"
-    zoo.zookeeper.class   # => Person
-    zoo.zookeeper.name    # => "Russell"
+  has_many :lions
+  has_one :zookeeper, type: Person
+end
 
-Types are inferred from the association name unless one is specified.
+zoo = Zoo.new(lions: [{name: 'Hetty'}],
+              zookeeper: {name: 'Russell'})
+
+zoo.lions.first.class # => Lion
+zoo.lions.first.name  # => "Hetty"
+zoo.zookeeper.class   # => Person
+zoo.zookeeper.name    # => "Russell"
+```
+
+Types are inferred from the association name unless specified.
 
 #### Designed for immutability
 
 `id` models provide accessor methods, but no mutator methods, because they are designed for immutability. How do immutable models work? When you need to change some field of a model object, a new copy of the object is created with the field changed as required. This is handled for you by `id`'s `set` method:
 
-    person = Person.new(name: 'Russell', job: 'programmer')
-    person.set(name: 'Radek') # => returns a new Person whose name is Radek and whose job is 'programmer'
+```ruby
+person1 = Person.new(name: 'Russell', job: 'programmer')
+person2 = person1.set(name: 'Radek')
+person1.name # => 'Russell'
+person2.name # => 'Radek'
+person2.job  # => 'programmer'
+```
+
+Obviously, this is Ruby, and if you really want to mutate some of the internal state of an id model you will be able to find a way to do it. Don't do it!
+
+#### Id and Rails
+
+We might not love everything about Rails, but we probably use it at least some of the time. So does id play nicely with it?
+
+With a few modifications, yes. Models that blow up at the sight of `nil` don't play happy with Rails' `nil`-happy forms, but you can make your id models active model compliant in forms, while otherwise retaining the `nil`-allergy in the rest of your code, by doing two things.
+
+Include the `Id::Form` module in your model.
+
+```ruby
+class Cat
+  include Id::Model
+  include Id::Form
+end
+```
+
+Add the following line to `config/application.rb`:
 
-You can even set fields on nested models in this way:
+```ruby
+config.action_view.default_form_builder = Id::FormBuilder
+```
 
-    person.hat.set(color: 'red') # => returns a new person object with a new hat object with its color set to red
+With `Id::Form` included you can use Active Model validations as normal, and override methods like `to_partial_path`, `self.model_name`, and `persisted?` right there in your model.
 
-#### Avoiding nils
+### Timestamps
 
-`id` tries to avoid nils entirely, by using the Option pattern found in many functional programming languages and implemented [here](http://github.com/rsslldnphy/optional).
-Just mark optional fields as `optional: true` and their accessors will return either `Some[value]` or `None`.
+And finally, it's reasonably common to want to know when a particular model was created and/or updated. Id provides you this functionality out of the box through the `Id::Timestamps` module. Just include it to your model to get `created_at` and `updated_at` fields that behave as you would expect.

data/id.gemspec

@@ -1,15 +1,16 @@
 Gem::Specification.new do |s|
   s.name          = 'id'
-  s.version       = '0.0.12'
+  s.version       = '0.1'
   s.date          = '2013-03-28'
   s.summary       = "Simple models based on hashes"
-  s.description   = "Developed at On The Beach Ltd. Contact russell.dunphy@onthebeach.co.uk"
+  s.description   = "Easily convert hashes to Ruby objects. Originally developed at www.onthebeach.co.uk."
   s.authors       = ["Russell Dunphy", "Radek Molenda"]
   s.email         = ['rssll@rsslldnphy.com', 'radek.molenda@gmail.com']
   s.files         = `git ls-files`.split($\)
   s.test_files    = s.files.grep(%r{^(test|spec|features)/})
   s.require_paths = ["lib"]
-  s.homepage      = 'http://github.com/onthebeach/id'
+  s.homepage      = 'http://github.com/rsslldnphy/id'
+  s.license       = 'MIT'
 
   s.add_dependency "optional"
   s.add_dependency "money"
@@ -17,6 +18,10 @@ Gem::Specification.new do |s|
   s.add_dependency "activemodel"
 
   s.add_development_dependency "rspec"
+  s.add_development_dependency "mocha"
   s.add_development_dependency "simplecov"
+  s.add_development_dependency "coveralls"
+  s.add_development_dependency "test-unit"
+
 
 end

data/lib/id.rb

@@ -1,22 +1,28 @@
-require 'active_model'
+module Id
+end
+
 require 'active_support/inflector'
 require 'active_support/core_ext/string/inflections'
 require 'active_support/core_ext/hash/except'
+require 'active_support/core_ext/hash/keys'
+
+require 'active_model'
 require 'optional'
-require 'money'
-require 'id/missing_attribute_error'
+require 'delegate'
+require 'date'
+require 'time'
+
+require 'id/boolean'
+require 'id/coercion'
 require 'id/hashifier'
-require 'id/model/definer'
-require 'id/model/descriptor'
-require 'id/model/type_casts'
-require 'id/model/field'
-require 'id/model/association'
-require 'id/model/has_one'
-require 'id/model/has_many'
+require 'id/field/summary'
+require 'id/field/definition'
+require 'id/field'
+require 'id/association'
+require 'id/eta_expansion'
 require 'id/model'
-require 'id/timestamps'
+require 'id/validations'
+require 'id/active_model'
+require 'id/form_backwards_compatibility'
 require 'id/form'
-require 'id/form/active_model_form'
-require 'id/form/descriptor'
-require 'id/form/field_with_form_support'
-require 'id/form/field_form'
+require 'id/timestamps'

data/lib/id/active_model.rb

@@ -0,0 +1,30 @@
+class Id::ActiveModel
+  include ActiveModel::Conversion
+  include ActiveModel::Validations
+
+  def self.i18n_scope
+    :id
+  end
+
+  def initialize(model, data)
+    @model = model
+    @data = data
+  end
+
+  def to_partial_path
+    model.respond_to?(:to_partial_path) ? model.to_partial_path : super
+  end
+
+  def respond_to?(name, include_private = false)
+    super || model.respond_to?(name, include_private)
+  end
+
+  private
+
+  def method_missing(name, *args, &block)
+    field = model.fields[name]
+    field.nil? ? model.send(name, *args, &block) : data[field.key]
+  end
+
+  attr_reader :model, :data
+end

data/lib/id/association.rb

@@ -0,0 +1,26 @@
+module Id::Association
+
+  def has_one(name, options = {})
+    type    = options[:type] || infer_class(name)
+    options = options.merge(type: type)
+    field name, options
+  end
+
+  def has_many(name, options = {})
+    type    = Array[options[:type] || infer_class(name)]
+    options = options.merge(type: type)
+    field name, options
+  end
+
+  private
+
+  def infer_class(name)
+    name = name.to_s.singularize.classify
+    if const_defined?(name)
+      const_get(name)
+    else
+      parent = self.name.sub(/::[^:]+$/, '')
+      parent.constantize.const_get(name)
+    end
+  end
+end