README.textile in dirty_hashy-0.1.0 vs README.textile in dirty_hashy-0.1.1
- old
+ new
@@ -1,8 +1,8 @@
h1. DirtyHashy
-Dirty tracking within hashes with indifferent access
+Dirty tracking within hashes with indifferent access or objects as it is expected to be!
h2. Introduction
"Dirty tracking / objects":http://ryandaigle.com/articles/2008/3/31/what-s-new-in-edge-rails-dirty-objects is a common programming concept. In short, it is the mechanism to track whether or not the attributes of an object have been changed and if so, which ones.
@@ -36,10 +36,11 @@
h = DirtyHashy.new
h.dirty? #=> false
h[:name] = "Paul"
h.dirty? #=> true
+ h.changed? :name #=> true
h.was :name #=> nil
h.change :name #=> [nil, "Paul"]
h.clean_up!
h.dirty? #=> false
h[:name] #=> "Paul"
@@ -61,16 +62,139 @@
h.dirty? #=> true
h.was :company #=> "Internetbureau Holder B.V."
h.change :company #=> ["Internetbureau Holder B.V.", nil]
</pre>
+h3. Method mapping DirtyHashy
+
+You can map methods within a DirtyHashy in order to provide convenience methods like @name@, @name=@, @name_changed?@, @name_was@ and @name_change@. Just pass @true@ for the @map_methods@ argument when initializing a DirtyHashy:
+
+<pre>
+ require "rubygems"
+ require "dirty_hashy"
+
+ h = DirtyHashy.new({}, true)
+ h.dirty? #=> false
+ h.name #=> NoMethodError: undefined method `name' for {}:DirtyHashy
+ h.name = "Paul"
+ h.dirty? #=> true
+ h.name_changed? #=> true
+ h.name_was #=> nil
+ h.name_change #=> [nil, "Paul"]
+ h.clean_up!
+ h.dirty? #=> false
+ h.name #=> "Paul"
+ h.name = "Paul"
+ h.dirty? #=> false
+ h.name = "Engel"
+ h.name_was #=> "Paul"
+ h.name_change #=> ["Paul", "Engel"]
+ h.foo = "Bar"
+ h.changes #=> {"name"=>["Paul", "Engel"], "foo"=>[nil, "Bar"]}
+</pre>
+
+h3. Dirty tracking objects (models)
+
+Like "ActiveModel::Dirty":http://api.rubyonrails.org/classes/ActiveModel/Dirty.html, you can use "DirtyAttributes":https://github.com/archan937/dirty_hashy/blob/master/lib/dirty_attributes.rb to dirty track your own objects (models). But there are two differences:
+
+# Setting up @DirtyAttributes@ is easier to setup than @ActiveModel::Dirty@
+# The implementation of "DirtyAttributes":https://github.com/archan937/dirty_hashy/tree/master/lib is more minimalistic and thus looks a bit cleaner than "ActiveModel::Dirty":https://github.com/rails/rails/blob/master/activemodel/lib/active_model/dirty.rb with "ActiveModel::AttributeMethods":https://github.com/rails/rails/blob/master/activemodel/lib/active_model/attribute_methods.rb
+
+The following illustrates the differences between @DirtyAttributes@ and @ActiveModel::Dirty@ when implementing a simple @Person@ model:
+
+h4. When using ActiveModel::Dirty
+
+<pre>
+ class Person
+ include ActiveModel::Dirty
+ define_attribute_methods = [:name]
+
+ def name
+ @name
+ end
+
+ def name=(val)
+ name_will_change! unless val == @name
+ @name = val
+ end
+
+ def save
+ @previously_changed = changes
+ @changed_attributes.clear
+ end
+ end
+</pre>
+
+h4. When using DirtyAttributes
+
+<pre>
+ class Person
+ include DirtyAttributes
+ attrs :name
+
+ def save
+ clean_up!
+ end
+ end
+</pre>
+
+You can use @Person@ objects as you would expect:
+
+<pre>
+ require "rubygems"
+ require "dirty_hashy"
+
+ class Person
+ include DirtyAttributes
+ attrs :name
+ end
+
+ p = Person.new
+ p.dirty? #=> false
+ p.name #=> nil
+ p.name = "Paul"
+ p.dirty? #=> true
+ p.name_changed? #=> true
+ p.name_was #=> nil
+ p.name_change #=> [nil, "Paul"]
+ p.clean_up!
+ p.dirty? #=> false
+ p.name #=> "Paul"
+</pre>
+
+And last but not least: don't care about specifying the attributes available? Well don't! ;)
+
+<pre>
+ require "rubygems"
+ require "dirty_hashy"
+
+ class Person
+ include DirtyAttributes
+ end
+
+ p = Person.new
+ p.dirty? #=> false
+ p.name #=> NoMethodError: undefined method `name' for #<Person:0x00000100d5cd88>
+ p.name = "Paul"
+ p.dirty? #=> true
+ p.name #=> "Paul"
+ p.name_changed? #=> true
+ p.name_was #=> nil
+ p.name_change #=> [nil, "Paul"]
+ p.clean_up!
+ p.dirty? #=> false
+ p.name #=> "Paul"
+ p.foo = "bar"
+ p.foo #=> "bar"
+</pre>
+
h2. Last remarks
-Please check out "test/unit/test_dirty_hashy.rb":https://github.com/archan937/dirty_hashy/blob/master/test/unit/test_dirty_hashy.rb the tests available. You can run the unit tests with @rake@ within the terminal.
+Please check out "test/unit/test_dirty_hashy.rb":https://github.com/archan937/dirty_hashy/blob/master/test/unit/test_dirty_hashy.rb and "test/unit/test_dirty_attributes.rb":https://github.com/archan937/dirty_hashy/blob/master/test/unit/test_dirty_attributes.rb the tests available. You can run the unit tests with @rake@ within the terminal.
Also, the DirtyHashy repo is provided with @script/console@ which you can use for testing purposes.
-Note: *DirtyHashy is successfully tested using Ruby 1.8.7 and Ruby 1.9.2*
+Note: *DirtyHashy is successfully tested using Ruby 1.8.7, Ruby 1.9.2 and Ruby 1.9.3*
h2. Contact me
For support, remarks and requests please mail me at "paul.engel@holder.nl":mailto:paul.engel@holder.nl.
\ No newline at end of file