updated readme to document the Lash

1 files changed, 39 insertions, 12 deletions

diff --git a/README.rdoc b/README.rdoc
index 4e26518..76e237d 100644
--- a/README.rdoc
+++ b/README.rdoc
@@ -4,7 +4,7 @@ Hashie is a growing collection of tools that extend Hashes and make
 them more useful.
 
 == Installation
-    
+
 Hashie is available as a RubyGem:
 
     gem install hashie
@@ -13,11 +13,11 @@ Hashie is available as a RubyGem:
 
 Mash is an extended Hash that gives simple pseudo-object functionality
 that can be built from hashes and easily extended. It is designed to
-be used in RESTful API libraries to provide easy object-like access 
+be used in RESTful API libraries to provide easy object-like access
 to JSON and XML parsed hashes.
 
 === Example:
-  
+
     mash = Hashie::Mash.new
     mash.name? # => false
     mash.name # => nil
@@ -25,16 +25,16 @@ to JSON and XML parsed hashes.
     mash.name # => "My Mash"
     mash.name? # => true
     mash.inspect # => <Hashie::Mash name="My Mash">
-  
+
     mash = Mash.new
     # use bang methods for multi-level assignment
     mash.author!.name = "Michael Bleigh"
     mash.author # => <Hashie::Mash name="Michael Bleigh">
 
-<b>Note:</b> The <tt>?</tt> method will return false if a key has been set 
+<b>Note:</b> The <tt>?</tt> method will return false if a key has been set
 to false or nil. In order to check if a key has been set at all, use the
 <tt>mash.key?('some_key')</tt> method instead.
-  
+
 == Dash
 
 Dash is an extended Hash that has a discrete set of defined properties
@@ -56,11 +56,11 @@ can set defaults for each property.
     p.email        # => 'abc@def.com'
     p[:awesome]    # => NoMethodError
     p[:occupation] # => 'Rubyist'
-    
+
     p = Person.new(:name => "Bob")
     p.name       # => 'Bob'
     p.occupation # => 'Rubyist'
-    
+
 == Trash
 
 A Trash is a Dash that allows you to translate keys on initialization.
@@ -69,12 +69,12 @@ It is used like so:
     class Person < Hashie::Trash
       property :first_name, :from => :firstName
     end
-    
+
 This will automatically translate the <tt>firstName</tt> key to <tt>first_name</tt>
 when it is initialized using a hash such as through:
-  
+
     Person.new(:firstName => 'Bob')
-    
+
 == Clash
 
 Clash is a Chainable Lazy Hash that allows you to easily construct
@@ -102,8 +102,35 @@ provide.
     c.where(:abc => 'def').where(:hgi => 123)
     c # => {:where => {:abc => 'def', :hgi => 123}}
 
+== Lash
+
+Lash is an extended Dash that allows properties to be set
+as required. These required properties will cause new Lash
+instances to "lash out" by raising an error when passed a
+nil value.
+
+=== Example:
+
+    class Person < Hashie::Dash
+      property :name, :required => true
+      property :email
+      property :occupation, :default => 'Rubyist'
+    end
+
+    p = Person.new # => ArgumentError: The property 'name' is required for this Lash.
+
+    p = Person.new(:name => 'Bob')
+    p.name # => 'Bob'
+    p.email = 'abc@def.com'
+    p.occupation   # => 'Rubyist'
+    p.email        # => 'abc@def.com'
+    p[:awesome]    # => NoMethodError
+    p[:occupation] # => 'Rubyist'
+
+    p.name = nil # => ArgumentError: The property 'name' is required for this Lash.
+
 == 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.