README.markdown in blendris-0.5 vs README.markdown in blendris-0.6

@@ -4,11 +4,12 @@
 
 
 
 # DESCRIPTION #
 
-Blendris is a Ruby interface to a Redis database.
+Blendris is a Ruby interface to a Redis database.  It performs no caching,
+causing all reads and writes to interact directly with Redis.
 
 
 
 # FEATURES/PROBLEMS #
 
@@ -56,37 +57,78 @@
       set :family_members
 
       ref :employer, :class => "Employer", :reverse => :employees
     end
 
+And now some examples of using them:
+
+    >> captain = Employee.create("Captain Amazing")
+    => #<Employee:0x45d18084 @key="employee:Captain_Amazing">
+
+    >> captain.address = "123 Fake Street"
+    => "123 Fake Street"
+
+    >> guild = Employer.create("The Really Fantastic Guild of Heroes")
+    => #<Employer:0x476e46f5 @key="employer:The_Really_Fantastic_Guild_of_Heroes">
+
+    >> guild.employees << captain
+    => #<Blendris::RedisReferenceSet:0x500150a0 @key="employer:The_Really_Fantastic_Guild_of_Heroes:employees", ...>
+
+    >> guild.employees.first.address
+    => "123 Fake Street"
+
+    >> guild.employees.count
+    => 1
+
+    >> guild.employees.first.employer.employees.first.name
+    => "Captain Amazing"
+
 ### key ###
 
-Key sets the base key for this object.  In the case of the employer
-"37 Signals" it would create a key "employer:37_Signals" and set its value
-to "Employer".  In the key, strings are interpreted as literals and
-symbols are interpreted as pointers to that data field.
+Key sets the base key for this object.
 
-* Note that spaces are converted to underscores, as spaces are not
-  allowed in Redis keys.  This could cause problems in some data sets.
-* Also note that the value assigned to the base key is the class name of
-  the model being used.
+* Any strings in the key will be used as literal strings.
+* Any symbols in the key will be set to the value of that field in this object.
+* In the case of the employer "37 Signals" it would create a key
+  "employer:37_Signals" and set its value to "Employer".
+* Note that spaces are converted to underscores, as spaces are not allowed in
+  Redis keys.  This could cause problems in some data sets.
+* Also note that the value assigned to the base key is the class name of the
+  model being used.
 * Only strings and integers should be used as key values.
 
+Examples of keys in use:
+
+    >> employer = Employer.create("37 Signals")
+    => #<Employer:0x169da74 @key="employer:37_Signals">
+
+    >> employer.key
+    => "employer:37_Signals"
+
+    >> employer.name
+    => "37 Signals"
+
+    >> employer[:name]
+    => #<Blendris::RedisString:0x20dbd794 @key="employer:37_Signals:name", ...>
+
+    >> employer[:name].key
+    => "employer:37_Signals:name"
+
 ### string ###
 
 String creates a string key named for the first parameter given to it.
 This means that it would generate a key "employer:37_Signals:name" with
 a value of "37 Signals".
 
-### refs ###
+### ref and refs ###
 
-Refs maintains a set of references to other objects.
+Refs maintain references to other objects.
 
 * *:class* will limit objects in this reference set to the given class.
   If a string is specified as a class, it will be constantized before
   comparing.
-* *reverse* will cause the given field to be updated on the object when
+* *:reverse* will cause the given field to be updated on the object when
   it is added to or removed from this set.
 
 ### new vs create ###
 
 Calling the *create* method will build a new object, generating a new base
@@ -94,10 +136,80 @@
 the list of symbols in your *key* field.
 
 Calling the *new* method will instantiate an existing object using the
 given *key* as the base key.
 
+Calling *create* on an object key that already exists is perfectly acceptable
+and only results in new Ruby objects being instantiated.  They will all read
+and write to the same Redis data.  Calling *new* however must be done on a
+Redis key that already exists and is set to the name of the requested model.
 
+    >> Employer.create("Giant Faceless Corporation")
+    => #<Employer:0x45a84b38 @key="employer:Giant_Faceless_Corporation">
+
+    >> Employer.create("Giant Faceless Corporation")
+    => #<Employer:0x12b8501d @key="employer:Giant_Faceless_Corporation">
+
+    >> Employer.create("Giant Faceless Corporation")
+    => #<Employer:0x742136c6 @key="employer:Giant_Faceless_Corporation">
+
+    >> Employer.new("Anything")
+    TypeError: Anything does not exist, not a Employer - you may want create instead of new
+            from .../blendris/lib/blendris/model.rb:25:in `initialize'
+            from (irb):32:in `new'
+            from (irb):32
+
+    >> Employer.new("employer:Giant_Faceless_Corporation")
+    => #<Employer:0x73cb4cae @key="employer:Giant_Faceless_Corporation">
+
+    >> Employee.create("Invisible Woman")
+    => #<Employee:0x5f27a49c @key="employee:Invisible_Woman">
+
+    >> Employer.new("employee:Invisible_Woman")
+    TypeError: employee:Invisible_Woman is a Employee, not a Employer
+            from /Users/amchale/Dropbox/Projects/blendris/lib/blendris/model.rb:26:in `initialize'
+            from (irb):36:in `new'
+            from (irb):36
+
+### on_change ###
+
+This keyword allows you to execute a block when one or more fields on the
+object change.  The block is executed within the context of the object.
+
+    class Dog < Blendris::Model
+      key "dog", :name
+
+      string  :name
+      string  :color
+      integer :attention
+      integer :food
+
+      on_change do
+        puts "Bark, bark!"
+      end
+
+      on_change :attention, :food do
+        puts "Woof, woof!"
+      end
+    end
+
+    >> d = Dog.create("Spot")
+    Bark, bark!
+    => #<Dog:0x000001011739e8 @key="dog:Spot">
+
+    >> d.attention = 0
+    Bark, bark!
+    Woof, woof!
+    => 0
+
+    >> d.color = "brown"
+    Bark, bark!
+    => "brown"
+
+    >> d[:attention].increment
+    Bark, bark!
+    Woof, woof!
+    => 1
 
 # LICENSE #
 
 (The MIT License)