ohm-contrib 1.0.1 → 1.1.0

data/README.markdown

@@ -1,200 +1,216 @@
-ohm-contrib
-===========
-
-A collection of drop-in modules for Ohm. Read the full documentation at
-[http://cyx.github.com/ohm-contrib](http://cyx.github.com/ohm-contrib).
-
-List of modules
----------------
-1. [`Ohm::Boundaries`](http://cyx.github.com/ohm-contrib/doc/Ohm/Boundaries.html)
-2. [`Ohm::Callbacks`](http://cyx.github.com/ohm-contrib/doc/Ohm/Callbacks.html)
-3. [`Ohm::Timestamping`](http://cyx.github.com/ohm-contrib/doc/Ohm/Timestamping.html)
-5. [`Ohm::WebValidations`](http://cyx.github.com/ohm-contrib/doc/Ohm/WebValidations.html)
-6. [`Ohm::NumberValidations`](http://cyx.github.com/ohm-contrib/doc/Ohm/NumberValidations.html)
-7. [`Ohm::ExtraValidations`](http://cyx.github.com/ohm-contrib/doc/Ohm/ExtraValidations.html)
-8. [`Ohm::Typecast`](http://cyx.github.com/ohm-contrib/doc/Ohm/Typecast.html)
-9. [`Ohm::Locking`](http://cyx.github.com/ohm-contrib/doc/Ohm/Locking.html)
-
-Example usage
--------------
-
-    require 'ohm'
-    require 'ohm/contrib'
-
-    class Post < Ohm::Model
-      include Ohm::Timestamping
-      include Ohm::Boundaries
-      include Ohm::WebValidations
-      include Ohm::NumberValidations
-
-      attribute :amount
-      attribute :url
-      attribute :poster_email
-      attribute :slug
-
-      def validate
-        # from NumberValidations
-        assert_decimal :amount
-
-        # or if you want it to be optional
-        assert_decimal :amount unless amount.to_s.empty?
-
-        # from WebValidations
-        assert_slug  :slug
-        assert_url   :url
-        assert_email :poster_email
-      end
-    end
-
-    Post.first
-    Post.last
-    Post.new.to_hash
-    Post.create.to_hash
-    Post.create.created_at
-    Post.create.updated_at
-
-    # Casting example
-    class Product
-      include Ohm::Typecast
-
-      attribute :price, Decimal
-      attribute :start_of_sale, Time
-      attribute :end_of_sale, Time
-      attribute :priority, Integer
-      attribute :rating, Float
-    end
-
-Typecasting explained
----------------------
-
-I studied various typecasting behaviors implemented by a few ORMs in Ruby.
-
-### ActiveRecord
-
-    class Post < ActiveRecord::Base
-      # say we have an integer column in the DB named votes
-    end
-    Post.new(:votes => "FooBar").votes == 0
-    # => true
-
-### DataMapper
-    class Post
-      include DataMapper::Resource
-
-      property :id, Serial
-      property :votes, Integer
-    end
-
-    post = Post.new(:votes => "FooBar")
-    post.votes == "FooBar"
-    # => true
-
-    post.save
-    post.reload
-
-    # Get ready!!!!
-    post.votes == 0
-    # => true
-
-### Ohm::Typecast approach.
-
-#### Mindset:
-
-1. Explosion everytime is too cumbersome.
-2. Mutation of data is less than ideal (Also similar to MySQL silently allowing you
-   to store more than 255 chars in a VARCHAR and then truncating that data. Yes I know
-   you can configure it to be noisy but the defaults kill).
-3. We just want to operate on it like it should!
-
-#### Short Demo:
-    class Post < Ohm::Model
-      include Ohm::Typecast
-      attribute :votes
-    end
-
-    post = Post.new(:votes => "FooBar")
-    post.votes == "FooBar"
-    # => true
-
-    post.save
-    post = Post[post.id]
-    post.votes == "FooBar"
-    # => true
-
-    # Here comes the cool part...
-    post.votes * 1
-    # => ArgumentError: invalid value for Integer: "FooBar"
-
-    post.votes = 50
-    post.votes * 2 == 100
-    # => true
-
-    post.votes.class == Ohm::Types::Integer
-    # => true
-    post.votes.inspect == "50"
-    # => true
-
-#### More examples just to show the normal case.
-
-    require 'ohm'
-    require 'ohm/contrib'
-
-    class Post < Ohm::Model
-      include Ohm::Typecast
-
-      attribute :price, Decimal
-      attribute :available_at, Time
-      attribute :stock, Integer
-      attribute :address, Hash
-      attribute :tags, Array
-    end
-
-    post = Post.create(:price => "10.20", :stock => "100",
-                       :address => { "city" => "Boston", "country" => "US" },
-                       :tags => ["redis", "ohm", "typecast"])
+# ohm-contrib
 
-    post.price.to_s == "10.20"
-    # => true
+A collection of drop-in modules for Ohm.
 
-    post.price * 2 == 20.40
-    # => true
-
-    post.stock / 10 == 10
-    # => true
+If you're upgrading from 0.1.x, see [the changes below](#upgrade)
 
-    post.address["city"] == "Boston"
-    post.tags.map { |tag| tag.upcase }
+## Quick Overview
 
-    # of course mutation works for both cases
-    post.price += 5
-    post.stock -= 1
-    post.tags << "contrib"
-    post.address["state"] = "MA"
-    post.save
-    post = Post[post.id]
-
-    post.address["state"] == "MA"
-    # => true
-    post.tags.include?("contrib")
-    # => true
-
-
-Credits
--------
-Thanks to github user gnrfan for the web validations.
-
-Note on Patches/Pull Requests
------------------------------
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a
-  commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-Copyright
----------
-Copyright (c) 2010 Cyril David. See LICENSE for details.
+```ruby
+require 'ohm'
+require 'ohm/contrib'
 
+class Post < Ohm::Model
+  include Ohm::Timestamps
+  include Ohm::DataTypes
+
+  attribute :amount, Type::Decimal
+  attribute :url
+  attribute :poster_email
+  attribute :slug
+end
+
+post = Post.create
+
+post.created_at.kind_of?(Time)
+# => true
+
+post.update_at.kind_of?(Time)
+# => true
+```
+
+It's important to note that `created_at` and `update_at` both store
+times as a unix timestamp for efficiency.
+
+## Ohm::Callbacks
+
+**Note:** Macro-style callbacks have been removed since version 1.0.x.
+Please use instance style callbacks.
+
+### On the topic of callbacks
+
+Since I initially released ohm-contrib, a lot has changed. Initially, I
+had a bad habit of putting a lot of stuff in callbacks. Nowadays, I
+prefer having a workflow object or a service layer which coordinates
+code not really related to the model, a perfect example of which is
+photo manipulation.
+
+It's best to keep your models pure, and have domain specific code
+in a separate object.
+
+```ruby
+class Order < Ohm::Model
+  attribute :status
+
+  def before_create
+    self.status = "pending"
+  end
+
+  def after_save
+    # do something here
+  end
+end
+```
+
+## Ohm::DataTypes
+
+If you don't already know, Ohm 1.0 already supports typecasting out of
+the box by taking a `lambda` parameter. An example best explains:
+
+```ruby
+class Product < Ohm::Model
+  attribute :price, lambda { |x| x.to_f }
+end
+```
+
+What `Ohm::DataTypes` does is define all of these lambdas for you,
+so we don't have to manually define how to cast an Integer, Float,
+Decimal, Time, Date, etc.
+
+### DataTypes: Basic example
+
+```ruby
+class Product < Ohm::Model
+  include Ohm::DataTypes
+
+  attribute :price, Type::Decimal
+  attribute :start_of_sale, Type::Time
+  attribute :end_of_sale, Type::Time
+  attribute :priority, Type::Integer
+  attribute :rating, Type::Float
+end
+
+product = Product.create(price: "127.99")
+product.price.kind_of?(BigDecimal)
+# => true
+
+product = Product.create(start_of_sale: Time.now.rfc2822)
+product.start_of_sale.kind_of?(Time)
+# => true
+
+product = Product.create(end_of_sale: Time.now.rfc2822)
+product.end_of_sale.kind_of?(Time)
+# => true
+
+product = Product.create(priority: "100")
+product.priority.kind_of?(Integer)
+# => true
+
+product = Product.create(rating: "5.5")
+product.rating.kind_of?(Float)
+# => true
+```
+
+### DataTypes: Advanced example
+
+**IMPORTANT NOTE**: Mutating a Hash and/or Array doesn't work, so you have
+to re-assign them accordingly.
+
+```ruby
+class Product < Ohm::Model
+  include Ohm::DataTypes
+
+  attribute :meta, Type::Hash
+  attribute :sizes, Type::Array
+end
+
+product = Product.create(meta: { resolution: '1280x768', battery: '8 hours' },
+                         sizes: ['XS S M L XL'])
+
+product.meta.kind_of?(Hash)
+# => true
+
+product.meta == { resolution: '1280x768', battery: '8 hours' }
+# => true
+
+product.meta.kind_of?(Array)
+# => true
+
+product.sizes == ['XS S M L XL']
+# => true
+```
+
+## Ohm::Slug
+
+```ruby
+class Post < Ohm::Model
+  include Ohm::Slug
+
+  attribute :title
+
+  def to_s
+    title
+  end
+end
+
+post = Post.create(title: "Using Ohm contrib 1.0")
+post.to_param == "1-using-ohm-contrib-1.0"
+# => true
+```
+
+By default, `Ohm::Slug` tries to load iconv in order to transliterate
+non-ascii characters.
+
+```ruby
+post = Post.create(:title => "Décor")
+post.to_param == "2-decor"
+```
+
+## Ohm::Versioned
+
+For cases where you expect people to be editing long pieces of
+content concurrently (the most obvious example would be a CMS with multiple
+moderators), then you need to put some kind of versioning in place.
+
+```ruby
+class Article < Ohm::Model
+  include Ohm::Versioned
+
+  attribute :title
+  attribute :content
+end
+
+a1 = Article.create(:title => "Foo Bar", :content => "Lorem ipsum")
+a2 = Article[a1.id]
+
+# At this point, a2 will be stale.
+a1.update(title: "Foo Bar Baz")
+
+begin
+  a2.update(:title => "Bar Baz")
+rescue Ohm::VersionConflict => ex
+  ex.attributes == { :title => "Bar Baz", :_version => "1", :content => "Lorem ipsum" }
+  # => true
+end
+```
+
+<a name="upgrade" id="upgrade"></a>
+
+## Important Upgrade notes from 0.1.x
+
+The following lists the major changes:
+
+1. `Ohm::Typecast` has been removed in favor of `Ohm::DataTypes`.
+2. `Ohm::Timestamping` has been renamed to `Ohm::Timestamps`.
+3. `Ohm::Timestamps` now store times as a UNIX Timestamp.
+4. `All Ohm validation related plugins have been removed.
+    See [scrivener][scrivener] instead.
+5. `Ohm::Boundaries` has been removed.
+6. Ohm::Contrib no longer uses `autoload`. You can either
+   `require 'ohm/contrib', which requires everything, or you
+   can `require ohm/datatypes` for example if you want to cherry
+   pick your requires.
+7. `Ohm::Callbacks` no longer provides macro style callbacks, i.e.
+   `after :create, :do_something`. Use instance callbacks instead.
+
+[scrivener]: http://github.com/soveran/scrivener

data/ohm-contrib.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "ohm-contrib"
-  s.version = "1.0.1"
+  s.version = "1.1.0"
   s.summary = %{A collection of decoupled drop-in modules for Ohm.}
   s.description = %{Includes a couple of core functions such as callbacks, timestamping, typecasting and lots of generic validation routines.}
   s.author = "Cyril David"
@@ -21,8 +21,7 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
   s.rubyforge_project = "ohm-contrib"
 
-  s.has_rdoc = false
-  s.add_dependency "ohm", "~> 1.0"
+  s.add_dependency "ohm", "~> 1.1"
 
   s.add_development_dependency "cutest"
   s.add_development_dependency "redis"

data/test/plugin.rb

@@ -58,8 +58,8 @@ scope do
   end
 
   test "slugging" do
-    post = Post.create(:title => "Foo Bar Baz")
-    assert_equal "1-foo-bar-baz", post.to_param
+    post = Post.create(:title => "Foo Bar Baz 1.0")
+    assert_equal "1-foo-bar-baz-1-0", post.to_param
 
     post = Post.create(:title => "Décor")
     assert_equal "2-decor", post.to_param

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ohm-contrib
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-14 00:00:00.000000000 Z
+date: 2012-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ohm
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.1'
 - !ruby/object:Gem::Dependency
   name: cutest
   requirement: !ruby/object:Gem::Requirement