cascading_classes 0.3.0 → 0.6.0

data/README.md

@@ -1,256 +1,1075 @@
-# CascadingClasses
+todo: blank values: what are the defaults for each class type
+todo: what kind of tree is this?  not binary!
+todo: find a city that has a pro baseball team but not a pro basketball team (or other way around)
 
-This library allows you to easily create properties that cascade down a class tree. For example:
+Cascading Classes
 
-    require 'cascading_classes'
+This is a small ruby library to help manipulate and manage hierachal data.  Whether modeling a simple hierarchy or a deeply nested tree, whether you have only a handful of properties to manage or hundreds, this library aims to help you can stay in control of your data.
 
-    class Parent
+Before you go running off playing with this library, you have to answer a few questions about your data.  Think about which of the following types of hierachal data best describes your situation:
+
+* few children spanning a small number of generations (skinny and short)
+* few children spanning many generations (skinny and tall)
+* many children spanning few generations (wide and short)
+* many children spanning many generations (wide and tall)
+
+Next, you'll need to come up with the essential set of properties that define your data.  An essential property is __not__ one that can be derived from another.  Think of all the "traits", "behaviors", and "functionality" you would like to model.  An essential property is one that is necessary, one that cannot be replaced by some combination of the others, one that, without which, the purpose, the point, of your data cannot be fulfilled.  
+
+Group these essential ingredients together and then describe them one at a time.  For each, what kind of object is it?  What is its type?  Is it a string, a number, a list, a hash?  What kind of object is it?  What kinds of values does it take?  Next, think about what its default should be.  Next, decide what value  is for every new child?  That is, what should the value of the property be when a new node is added to the hierarchy?  Next, what 
+"blank" means for your property.  What value or values will cause the property to be effectively null or without meaning?  This is important since a property that is blank can inherit its value from a parent.
+
+Now list those properties that not as vital or that can be derived from some combination of essential ones.  For each of these, answer the same questions:  What is a suitable __default__?  What should its value be for every__new__ child?  What value or values make the property __blank__?
+
+Only after doing all this are ready to use this library.
+
+# Quick Tour
+
+Assume the following simple class hierarchy:
+
+    class A
       extend CC
     end
 
-    class Child < Parent; end
+    class B < A
+    end
 
-    class GrandChild < Child; end
+    class C < B
+    end
 
-now create properties that will cascade down all descendents
+A is the top-level parent, B is one of A's (possibly many) children.  C is one of B's (possibly many) children.
 
-    Parent.cascade :eye_color, :hair_color
+Create ```name, city and state``` properties:
 
-set a property on a parent class
+    A.cascade do
+      name :default => "Franklin"
+      city :default => "New York"
+      state :default => "NY"
+    end
+	
+specifying a default sets the properties on top-level class to the same value:
 
-    Parent.eye_color = "brown"
+    p A.name   # => "Franklin"
+    p A.city   # => "New York"
+    p A.state  # => "NY"
 
-all child classes are affected
+furthermore, blank descendents inherit the same property values:
 
-    p Child.eye_color        # => "brown"
-    p GrandChild.eye_color   # => "brown"
+    p B.name    # => "Franklin"
+    p C.name    # => "Franklin"
 
-now change the property on a descendent class
+    p B.city    # => "New York"
+    p C.city    # => "New York"
 
-    Child.eye_color = "blue"     
+    ...
 
-only descendents of ```Child``` are affected
+Update the properties on A's desendents:
+ 
+    B.name = "Charles"
+    C.name = "Sam"
 
-    p Parent.eye_color       # => "brown"
-    p Child.eye_color        # => "blue"
-    p GrandChild.eye_color   # => "blue"
+    C.city = "Rochester"
 
+Collect property names and values:
 
-Getting Started
----------------
+    p A.to_hash   # => {:name => "Franklin", :city => "New York", :state => "NY"}
+    p B.to_hash   # => {:name => "Charles", :city => "New York", :state => "NY"}
+    p C.to_hash   # => {:name => "Sam", :city => "Rochester", :state => "NY"}
 
-Assume the class structure from above:
+pass 'false' for only those properties that were specifically set:
 
-    class Parent
-      extend CC
-    end
+    p A.to_hash(false)  # => {:name => "Franklin", :city => "New York", :state => "NY"}
+    p B.to_hash(false)  # => {:name => "Charles"}
+    p C.to_hash(false)  # => {:name => "Sam", :city => "Rochester"}
+ 
+This is a pretty basic example with just three nodes spanning three generations (short and skinny).  Also, there are only three properties.  Let's ramp up the complexity  
 
-    class Child < Parent; end
+### ...more...
 
-    class GrandChild < Child; end
+Add a second child to A based out of Boston:
 
-## Setting default values
+    B2 = Class.new(A)  # same as: class B2 < A; end
+    
+    B2.name = 'Thomas'
+    B2.city = 'Boston'
+    B2.state = 'MA'
 
-Setting default values for cascaded properties is easy. The first method is to bracket them in Array pairs. For example:
+Descendents of B2 will inherit these new values unless set. 
 
-    Parent.cascade [:eye_color, "hazel"], [:hair_color, "brown"], :has_education
+    class C2 < B2; end
 
-sets the ```eye_color``` and ```hair_color``` properties on ```Parent``` to "hazel" and "brown" and initializes, but does not set, the ```has_education``` property. 
+    p C2.city   # => Boston
+    p C2.state  # => MA
 
+Now we have three properties on five nodes spanning three generations. 
 
-### Alternative syntax: all!
+Let's add two more properties; these will depend on one's location:
 
-You also create cascaded properties via ```Parent.all!```
+    A.cascade do
+      baseball_team :default => proc{|me| me.state == 'NY' ? "Yankees" : "Red Sox"}
+      basketball_team :default => proc{|me| me.state == 'NY' ? "Knicks" : "Celtics"}
+    end
 
-For example, the following are equivalent:
+The beauty here is that when the ```baseball_team``` property is called, the proc is evaluated in the context of the calling class.  This means each property automatically gains the 'correct' baseball_team value through just one line of code.  Though the current hierarchy is tiny, imagine a tree with hundreds of nodes spanning many generations.  
 
-    Parent.cascade :arms, :legs
-    Parent.all! :arms, :legs
+Watch how this works for our five node, three generation setup.  Notice how each proc (read: behavior) cascades down the class hierarchy:
 
-this initiates, but does not set, two cascading properties: ```arms```, ```legs```
+    p A.baseball_team    # => "Yankees"
+    p B.baseball_team    # => "Yankees"
+    p C.baseball_team    # => "Yankees"
 
-    p Parent.arms      # => nil
-    p Child.arms       # => nil
-    p GrandChild.arms  # => nil
+    p B2.baseball_team   # => "Red Sox"
+    p C2.baseball_team   # => "Red Sox"
 
-since no default was given, all are nil 
+If we change C2's location, its teams should follow suit:
 
-Again, to set a default use brackets:
+    C2.city = "New York"
+    C2.state = "NY"
 
-    Parent.all! :arms, [:legs, 2]
+    p C2.baseball_team     # => "Yankees"
+    p C2.basketball_team   # => "Knicks"
 
+Any new node added to the mix should be "born" with the same behavior:
 
-### Alternative syntax: block arguments
+    class D < C; end
 
-You can also create cascading properties with a block. The major difference is that you must not prefix your property with a colon. 
+    p D.state           # => "NY"
+    p D.baseball_team   # => "Yankees"
 
-For example
+    D.state = "MA"
+    p D.baseball_team   # => "Red Sox"
 
-    Parent.cascade [:eye_color, "blue"], [:hair_color, "blond"]
+Whether this is the "correct" response is not the point.  Moving from city to city most likely wouldn't change one's favorite baseball team.  The point is that if you decide to define the baseball team property (read: behavior) this way, you can affect the whole tree at once.   
 
-is equivalent to
+Finally, let's add a child to C2, located in Los Angeles, and rewrite the sports properties to fit our bulging world:
 
-    Parent.cascade do
-      eye_color  :default => "blue"
-      hair_color :default => "blond"
+    class D2 < C2
+    end
+
+    D2.city = "Los Angeles"
+    D2.state = "CA"
+
+    A.baseball_team = Proc.new do |me|
+      case me.state
+      when "NY" then "Yankees"
+      when "MA" then "Red Sox"
+      when "CA" then "Dodgers"
+      else ''
+      end
+    end
+
+    A.basketball_team = Proc.new do |me|
+      case me.state
+      when "NY" then "Knicks"
+      when "MA" then "Celtics"
+      when "CA" then "Lakers"
+      else ""
+      end
     end
     
-or 
+We now in charge of seven nodes spanning four generations.  
+
+To further showcase proc properties, let's create a ```teams``` property that is a composite of one's favorite teams:
 
-    Parent.all! do
-      eye_color  :initial => "blue"
-      hair_color :initial => "blond"
+    A.cascade do
+      teams :default => Proc.new{|me|
+        [me.baseball_team, me.basketball_team]
+      }
     end
+
+test it out
  
-### More block examples
+    p A.teams     # => ["Yankees", "Knicks"]
+    p B.teams     # => ["Yankees", "Knicks"]
+    p C.teams     # => ["Yankees", "Knicks"]
+    p D.teams     # => ["Yankees", "Knics"]
+    p B2.teams    # => ["Red Sox", "Celtics"]
+    p C2.teams    # => ["Red Sox", "Celticks"]
+    p D2.teams    # => ["Dodgers", "Lakers"]
+
+now we can move people around and expect their teams to follow suit:
+
+    D.state = "CA"
+    D.city = "Los Angeles"
+
+    p D.teams    # => ["Dodgers", "Lakers"]
 
-The folowing are all equivalent
+### top it off with a block
 
-    Parent.cascade :address, :phone, [:email, "jon@example.com"]
+For the final act of this brief tour, we will print the ```teams``` property for D2 and its ancestors.  The simplest way to do this is by passing a block during the ```teams``` property call:
 
-    Parent.cascade :address, :phone do
-      email :initial => "jon@example.com"
+    p D2.teams do |val, parents|
+      puts "D2: #{val.inspect}"
+      parents.each{|parent| puts "#{parent}: #{parent.teams.inspect}"}
     end
 
-    Parent.all! do
-      address
-      phone
-      email :start => "jon@example.com"
+         # => D2: ["Dodgers", "Lakers"]
+	      C2: ["Red Sox", "Celtics"]
+	      B2: ["Red Sox", "Celtics"]
+	      A: ["Yankees", "Knicks"]
+
+### quickly summarized
+
+Even simple hierarchies can turn into complex beasts in need of taming.  To use this library in your projects: 
+
+* require the library: ```require 'cascading_classes'```
+* extend or include your class with CascadingClasses or its synonym: CC 
+* call ```cascade``` on a parent class
+* wrap your properties and their defaults in block
+* get and set properties on any node in the hierachy
+* add extra functionality with derived properties using procs
+* pass a block to easily iterate over a property's parents
+
+# In Depth:
+
+Assume a simple three node, three generation setup:
+  
+    class A
+      include CC
+    end
+
+    class B < A
+    end
+
+    class C < B
+    end
+
+It's important to understand that this library distinguishes among three kinds of properties:  non-container types like Floats, Fixnums, Strings, Symbols, and booleans; containers types like arrays, hashes, and sets; and procs.  
+
+The reason for this is allow non-containers to inherit their value when blank, while ensuring containers don't.  Also, proc properties are very different from the others.  They can be used to add layers of seemingly complex functionality from a very simple, core set of properties.  Proc properties (read: behaviors) can also be used to add dynamism and time-varying effects.
+
+### basic types: strings, symbols, numbers, booleans, ...
+
+Using basic types is as it should be, dead simple:
+
+    A.cascade do
+      score :default => 45.2
+      rank :default => 4
+      color :default => "red"
+      direction :default => :south
+      available :default => true
+    end
+
+we've added five properties accessible by A and its descendents.  Each is of a different type and each has been given a default.  It's important to understand that specifying a default has a side effect: it sets the value on the class invoking ```cascade```.  That is, the default score for any property will be 45.2 and it won't change.
+
+### defaults
+
+To access the default, pass ':default' to any descendent in the property call
+
+    p A.score :default    # => 45.2
+    p B.score :default    # => 45.2
+    p C.score :default    # => 45.2
+
+notice how the property can change, but the default stays the same:
+
+    A.score = 19.2
+    B.score = 22.1
+    C.score = 39.7
+
+    p A.score             # => 19.2
+    p B.score             # => 22.1
+    p C.score             # => 39.7
+
+    p A.score :default    # => 45.2
+    p B.score :default    # => 45.2
+    p C.score :default    # => 45.2
+
+### one essential rule
+
+The basic rule is that non-container properties inherit their value (when blank) by default.  The definition of blank can be redefined, but defaults to reasonable values: empty string for ':String', nil for ':Float' and ':Fixnum' and symbols.  Also, unset properties are usually blank.  
+
+    p A.score    # => 19.2
+    p B.score    # => 22.1
+    p C.score    # => 39.7
+    
+    B.score = nil
+    C.score = nil
+
+    p B.score    # => 19.2
+    p C.score    # => 19.2
+
+notice how even though the ```score``` property is set to nil, it prints out the value of A's ```score```.  This is inheritance at work.  Next, notice how the same thing happens for the ```rank``` property except that it wasn't explicitly set to a blank value, rather they defaulted to one:
+
+    p A.rank    # => 4
+    p B.rank    # => 4
+    p C.rank    # => 4
+
+The way this works is that when you ask B for its ```rank```, it asks itself whether the value is blank.  If it is, it proxies to its nearest parent, otherwise it returns its value.  Hence, when C is asked for its ```rank```, it proxies to B, which in turn proxies to A.  Notice how C returns B's rank when the proeprty on B is set:
+
+    B.rank = 12
+
+    p A.rank   # => 4
+    p B.rank   # => 2
+    p C.rank   # => 2
+
+Of course, this cascading behavior may not be what you want.  You can explicitly control whether a property is to inherit:
+
+    p A.score        # => 19.2
+    p B.score false  # => nil
+    p C.score true   # => 19.2
+
+Here, we tell B just to give us its own value without proxying to A.  Passing ```true``` to C tells C that it __can__ ask B for its value if its own is blank.  
+
+It's important to realize that any property that is not blank will never inherit no matter what arguments you pass (unless its ':default').
+
+    C.score = 17.4
+
+    p A.score(true)   # => 19.2
+    p B.score         # => 19.2
+    p C.score(true)   # => 17.4
+
+Here, A and C have set the ```score``` property, hence any call to the property regardless of the inherit argument, returns that same value.
+
+### single example inheritance summary
+
+For a brief summarry of inheritance for noncontainers consider this example:
+
+    A.color = "white"
+    p A.color    # => "white"
+    p B.color    # => "white"
+    p C.color    # => "white"
+
+    A.color = "blue"
+    p A.color    # => "blue"
+    p B.color    # => "blue"
+    p C.color    # => "blue"
+
+    B.color = "orange"
+
+    p A.color    # => "blue"
+    p B.color    # => "orange"
+    p C.color    # => "orange"
+      
+see how initially the ```color``` property for B and C inherits from A.  When B's ```color``` is set to a nonblank value, C no longer returns the value of it two generations higher.  It returns B's instead.
+
+### '<propname>_is_blank?' 
+
+For each cascaded property, an extra method is added to every node in the hierarchy that returns whether the property is blank:
+
+    p A.score_is_blank?   # => false
+    p B.score_is_blank?   # => false
+    p C.score_is_blank?   # => true
+
+    p C.score = 18.2
+    p C.score_is_blank?   # => false
+
+    p A.color_is_blank?   # => false
+    p B.color_is_blank?   # => false
+    p C.color_is_blank?   # => true
+
+For good measure, notice inheritance at work for the other properties.
+
+    B.available = false
+    C.color = "purple"
+
+    p C.score        # => 18.2      (inherits from B)
+    p C.color        # => "purple"  (own value)
+    p C.rank         # => 12        (inherits from B)
+    p C.direction    # => :south    (inherits from A)
+    p C.available    # => false     (inherits from B)
+
+### more on defaults 
+
+Each property can have a default value which is set in the ```cascade``` call.  Default values are like global values.  They are set once and can be referenced at any time by any node in the tree. 
+
+Again, recall that the side effect of giving a default is that the parent property is set too.  Let's create a ```city``` property that defaults to "seatle"
+
+    A.cascade do
+      city :default => "seatle"
     end
 
-    Parent.all!{ address; phone; email :default => "jon@example.com" }
+    p A.city_is_blank?     # => false
+
+    p A.city               # => "seatle"
+    p B.city               # => "seatle" (inherits from A)
+
+    A.city = "austin"
+    B.city = "los angeles"
+
+    p A.city :default      # => "seatle"
+    p B.city :default      # => "seatle"
+    p C.city :default      # => "seatle"
+
+Notice how adding the ':default' argument returns the property-wide default regardless of the node making the call.  
+
+### types 
 
-You can also set a property in a block using ```set_property```
+Defaults are not required, but if not given, the type of the property won't be known until it is first assigned.
 
-    Parent.cascade do
-      set_property :address
-      set_property :phone
-      set_property :email, :default => "jon@example.com"
+    props = A.cascade do
+      space_free
+      color
     end
 
+    p props[:space_free][:type]    # => :undefined_type
+    A.space_free = 328.12
+    p props[:space_free][:type]    # => :Float
 
-## Quick Summary
+    p props[:color][:type]         # => :undefined_type
+    A.color = "red"
+    p props[:color][:type]         # => :String
 
-NOTE: CC is equivalent to CascadingClasses
+Here we capture the result of the ```cascade``` call into the ```props``` variable.  This let's us peek into the property metadata being tracked behind the scenes.  Notice that every property has a type and that it defaults to ":unknown_type" unless known.
 
-require the gem
+The type of a property is defined as the class (in symbol form) of the first assigned value.  This is inferred automatically when a default is given.
 
-    require cascading_classes
+### set the type manually
 
-extend or include the module
+You can manually mark the type of a property during the ```cascade``` call.  This is useful if you you know a property's type but not yet its initial (top-most) value or default.  There's no reason to let such information go to waste:
 
-    class Foo
-      extend CascadingClasses
+    props = A.cascade do
+      name :Hash => true
+      address :hash => true
+      city :String => true
+      area :fixnum => true
+      zip :Fixnum => true
     end
 
-create some cascading properties by listing them 
+    p props[:name][:type]           # => :Hash
+    p props[:color][:type]          # => :Symbol
+    p props[:address][:type]        # => :Hash
+    p props[:city][:type]           # => :String
+    p props[:area][:type]           # => :Fixnum
+    p props[:zip][:type]            # => :Fixnum
 
-    A.cascade :desk, :chair, :lamp
+## container types: arrays, hashes, sets, ...
 
-or by using a block
+Container properties are those that implement ```each``` or include ```Enumerable```.  The definition of "blank" for arrays, hashes and sets has been pre-defined to be those that are empty.    
+
+### containers and inheritance: fundamental rule
+
+It doesn't usually make sense for a hash or array to inherit its parent's value.  By default, containers don't inherit.  Other than this, they behave exactly as you'd expect:
 
     A.cascade do
-      desk
-      chair
-      lamp
+      urls :default => ["www.google.com", "www.nytimes.com"]
+      name :default => {:first => 'jon', :last => 'smith'}
     end
 
-or
+    p A.urls    # => ["www.google.com", "www.nytimes.com"]
+    p B.urls    # => []
+    p C.urls    # => []
+
+    B.urls << "www.techcrunch.com" << "www.twitter.com"
+    C.urls = ["www.bgr.com"]
+
+    p A.urls       # => ["www.google.com", "www.nytimes.com"]
+    p B.urls       # => ["www.techcrunch.com", "www.twitter.com"]
+    p C.urls       # => ["www.bgr.com"]
 
-    A.cascade{ desk; chair; lamp }
+    p A.name    # => {:first => 'jon', :last => 'smith'}
+    p B.name    # => {}
+    p C.name    # => {}
 
-get and set the property on any descendent
+    B.name[:first] = "adam"
+    B.name[:last] = "johnson"
+    C.name = {:first => 'terry', :last => 'williamson'}
 
-    class B < A; end
+    p A.name       # => {:first => 'jon', :last => 'smith'}
+    p B.name       # => {:first => 'adam', :last => 'johnson'}
+    p C.name       # => {:first => 'terry', :last => 'williamson'}
 
-    B.desk = "a large, wooden structure in need of a fix"         
+### container lack inheritance override 
 
-    class C < A; end
+You can this lack of inheritance default at the property-wide level or during each individual call.  To allow container properties to inherit by default, add an ":inherit => true" argument in the ```cascade``` call.  Let's add a ```cities``` container property, allowing it to inherit (if blank):
 
-    C.lamp = "old and rusty"
+    A.cascade do
+      cities :default=> ["boston", "new york"], :inherit => true
+    end
 
-## What's the difference between ```extend CC``` and ```include CC```?
+    p A.cities     # => ["boston", "new york"]
+    p B.cities     # => ["boston", "new york"]  (inherited from A)
+    p C.cities     # => ["boston", "new york"]  (inherited from A)
 
-First, in either case you are dealing with class instance variables.
+    p A.cities_is_blank?   # => false
+    p B.cities_is_blank?   # => true
+    p C.cities_is_blank?   # => true
 
-    A.cascade :eye_color
-    A.eye_color = "blue"
+if you think this is useful, just take care not to trip over yourself
 
-sets ```@eye_color``` on ```A```.
+    B.cities << "london"
 
-But if you also want the properties to cascade to instance variables, you have three options. The first is to ```include CC```, which, by default, creates the properties on instances too
+    p B.cities_is_blank?   # => true
+    p A.cities             # => ["boston", "new york", "london"]
+    p B.cities             # => ["boston", "new york", "london"]
 
-    class Parent
-      include CC
+That's likely __not__ the behavior you were expecting.  What happened is that the ```cities``` property on B returned the value on A.  Hence "london" was appended to A's array, not B's empty one.
+
+#### overriding the override 
+
+If you do find it useful to override the lack of inheritance for containers at the property-wide level, you will probably want to know how to explicitly override this behavior.  Simply pass in ':inherit => false' in the property call.  Let's correct the previous example:
+
+    B.cities(:inherit => false) << "london"
+
+    p A.cities             # => ["boston", "new york"]
+    p B.cities             # => ["london"]
+
+you can also ommit the the ':inherit' bit
+
+    B.cities = []
+    
+    p B.cities         # ["boston", "new york"]  (inherits from A)
+    p B.cities false   # []  (own value)
+
+    B.cities(false) << "london"
+
+    p B.cities         # ["london"]
+
+### manual inheritance 
+
+This works in the opposite way too.  Container properties don't inherit by default, but you can force the behavior on an indivudual basis:
+
+    A.cascade do
+      cuisine :default => [:italian, :french]
     end
 
-    Parent.cascade [:one, 1]
-    p = Parent.new
-    p p.one   # => 1
+    p A.cuisine            # => [:italian, :french]
+    p B.cuisine            # => []
+    p C.cuisine            # => []
 
-    class Child < Parent; end
+    p B.cuisine :inherit   # => [:italian, :french]
+    p C.cuisine :inherit   # => [:italian, :french]
 
-    c = Child.new
-    p c.one   # => 1
+The inherit argument can be one of ```false, true, nil``` or a number.  When a number, it specifies the maximum inheritance age.  A negative value means "infinite inheritance".  As does ```true```.  For example: 
 
-The other two ways to ensure instances have cascading properties uses an additional argument:
+    p C.cuisine :inherit => false   # => [] (own value)
+    p C.cuisine :inherit => nil     # => [] (own value)
+    p C.cuisine :inherit => 0       # => [] (own value)
+    p C.cuisine :inherit => 1       # => [] (own value)
+    p C.cuisine :inherit => 2       # => [:italian, :french] (inherits from A)
+    p C.cuisine :inherit => 83      # => [:italian, :french] (inherits from A)
+    p C.cuisine :inherit => -1      # => [:italian, :french] (inherits from A)
+    p C.cuisine :inherit => true    # => [:italian, :french] (inherits from A)
 
-either
+you can ommit the ':inherit' syntax entirely:
 
-    Parent.cascade [:hair_color, "blue", true]
+    p C.cuisine 
+    p C.cuisine false    # => []
+    p C.cuisine nil      # => []
+    p C.cuisine 0        # => []
+    p C.cuisine 1        # => []
+    p C.cuisine 2        # => [:italian, :french]
+    p C.cuisine 83       # => [:italian, :french]
+    p C.cuisine -1       # => [:italian, :french]
+    p C.cuisine true     # => [:italian, :french]
+    p C.cuisine 20       # => [:italian, :french]
 
-or 
- 
-    Parent.cascade do
-      hair_color :default => "blue", :instances => true
+Notice why an inheritance age of '1' is not enough to reach the value on A.  This is because there are two generations between C and A and a max inheritance of '1' only gets you to B, which is blank.
+
+### metadata again
+
+One way to obtain the background metadata hash is by capturing the result of the ```cascade``` call:
+
+    props = A.cascade do
+      states :default => [:good, :bad, :disaster], :inherit => true
+      colors :default => ["blue", "orange", "red"]
+    end
+
+    p props.keys             # => [:states, :colors]
+    p props[:states].keys    # => [:default, :instances_too, :getters, :setters, ...]
+
+The hash is located as an instance variable (read: property) on the singleton class of the top-most class.  Hence, another way at it is:
+
+    props = A.singleton_class.properties
+
+### metadata - check 'inheritance' status
+
+The rule is very simple: containers don't inherit, all others do.  But seeing as you can override this rule, one reason you might go looking for the metadata hash is to remind yourself of a property's inheritance status.  This is especially true when your collection of properties is large. 
+
+    p props[:states][:inherit]     # => true
+    p props[:colors][:inherit]     # => false
+
+### more on inheritance and max inherit age
+
+If you override the container inheritance default and add ```:inherit => true``` as part of the ```cascade``` call, each property call will assume the inheritance age to be -1.  That is, it will assume you want to inherit upwards until the first parent node whose property value is not blank is reached.  This is also true for noncontainer types, as they inherit by default (unless inheritance is turned off at the property-wide level using: ```:inherit => false```).
+
+    p A.states    # => [:good, :bad, :disaster]  (inherits from A)
+    p B.states    # => [:good, :bad, :disaster]  (inherits from A) 
+    p C.states    # => [:good, :bad, :disaster]  (inherits from A)
+
+    p A.colors    # => ["blue", "orange", "red"] (own value)
+    p B.colors    # => [] (own value)
+    p C.colors    # => [] (own value)
+  
+### container behavior summary
+  
+To understand all you need to know about containers and inheritance, whether induced at the property-wide level or the individual level, study the following example:
+
+    A.cascade do
+      servers :inherit => true
+      users 
     end
 
-will do the trick.
+    A.servers = ["rails", "sinatra"]
+    A.users = [:bigfoot, :charlie]
 
-In either case, even if you ```extend CC```, all instance variables of all descendents will have the ```hair_color``` property. 
+    p A.servers          # => ["rails", "sinatra"]
+    p B.servers          # => ["rails", "sinatra"]         
+    p B.servers false    # => []
+    p B.servers true     # => ["rails", "sinatra"]
+    p C.servers          # => ["rails", "sinatra"]
+    p C.serverse false   # => []
+    p C.servers true     # => ["rails", "sinatra"]
 
-## Custom getters and setters
+    p A.users            # => [:bigfoot, :charlie]
+    p B.users            # => []
+    p B.users false      # => []
+    p B.users true       # => [:bigfoot, :charlie]
+    p C.users            # => []
+    p C.users false      # => []
+    p C.users true       # => [:bigfoot, :charlie]
 
-The easiest way to apply custom names for getting and setting a property is with the :getter/:setter options.
+##  Proc Properites
 
-    Parent.cascade do
-      eye_color :start => "brown", :getter => :eyes, :setter => :eyes=
+Properties set to a proc are invoked on each property call. This makes it simple to create complex property dependencies.  Note that the concept of property dependencies is indepenent from the concept of class hierarchies (and property inheritance).  A tree can be a single node (no inheritance) and yet contain a complex web of dependencies.  You can create a pyramid of property dependencies all on one class.  
+
+### two types of proc properties
+
+This library distinguishes between two kinds of proc properties: First, the properties of type ```:Proc```, whose initial value has class: ```Proc```.
+
+Then there are properties defined with some other type, but with a descendent that 'sets' the property to one.  This makes properties very flexible.  You can set the top-level ancestor to some basic value and have a descendent 'redefine' that property for itself and its descendents in a more complicated, state-dependent way. 
+
+### Proc Syntax
+
+Procs take (up to) two parameters: the first is the object calling the property, the second is an array of ancestors.
+
+### properties of type: ```:Proc``` 
+
+Consider the following example:
+
+    A.cascade do
+      weather :default => :sunny
+      mood :default => Proc.new{|me| me.weather == :sunny ? "happy" : "miserable"}
+      color :default => Proc.new{|me| me.mood == "happy" ? "rosy" : "blue"}
     end
-    Child.eyes = "blue"
+
+In this case, the color depends on the mood and the mood depends on the weather.
+
+    p A.weather    # => :sunny
+    p A.mood       # => "happy"
+    p A.color      # => "rosy"
+
+Changing the weather to ```rainy``` will be reflected automatically in calls to ```mood``` and ```color```:
+
+    A.weather = :rainy
     
-now you cannot use ```:eye_color``` or ```:eye_color=``` methods to get or set the property.
+    p A.mood       # => "miserable"
+    p A.color      # => "blue"
+
+Properties of type ```:Proc``` inherit their proc value from the nearest parent when blank.  The proc itself, not its evaluation, is borrowed from some parent class and then evaluated in the descendent's own context.  
+
+In this case, this just means that changing the weather on B, changes its mood and color.
+
+    A.weather = :sunny
+    B.weather = :rainy
+    
+    p A.mood     # => "happy"
+    p B.mood     # => "miserable"
+
+    p A.color    # => "rosy"
+    p B.color    # => "blue"
+
+In this case, B graps the mood proc from A and evaluates it in its own context.  The same goes for the color proc.  Again, just remember that only blank properties are inherited (unless such behavior is otherwise overriden).
 
-    p Parent.eyes         # => "brown"
-    p Parent.eye_color    # => NoMethodError
+Let's give B its own mood proc. 
 
-    p Child.eyes          # => "blue"
-    p GrandChild.eyes     # => "blue"
+    B.mood = Proc.new{|me, parents|
+      parents.first.mood == "miserable" ? "happy" : "miserable"
+    }
 
-You can also have more than one getter or setter function
+B's mood now depends on the mood of its nearest parent.  It is irrelevant what the weather is, only its parent's mood matters.  When A is happy, B is misearble and when A is miserable, B is happy.  
 
-    Parent.all! do
-      has_hair :begin => false, :getters => [:has_hair?, :hair?]
+    A.weather = :sunny
+    B.weather = :sunny
+
+    p A.mood   # => "content"
+    p B.mood   # => "miserable"
+
+    A.weather = :rainy
+
+    p A.mood   # => "miserable"
+    p B.mood   # => "happy" 
+
+Now since procs are inherited and C has not set its mood property, note what it means for C to 'inherit' B's mood proc:
+
+    p A.mood   # => "miserable"
+    p B.mood   # => "happy"
+    p C.mood   # => "miserable"
+
+    A.weather = :sunny
+
+    p A.mood   # => "happy"
+    p B.mood   # => "miserable"
+    p C.mood   # => "happy"
+
+C uses B's mood property.  The proc decides the mood based on the first parent's mood.  Hence, since B is C's parent, C's mood is always the opposite of B's.
+
+Take a step back and consider what has been accomplished.  For some classes, the mood property depends one's own value for the weather.  For others, it depends only on the mood of a parent.  
+  
+### don't forget about ':default => true'
+
+Proc inheritance is a powerful concept but it may not always be what you want.  To manually override it, don't forget that you can always revert to the global default proc (the one defined in the ```cascade``` call):
+
+    B.weather = :sunny
+
+    A.mood           # => "happy"
+    B.mood :default  # => "happy"
+    C.mood :default  # => "happy"
+
+### blank proc properties: manual override
+
+Overriding inheritance in favor of the global default is so useful for procs that whenever you'd expect a blank property to return its blank value, it will instead invoke the default.  What would you expect a proc property that is blank to return when forced to return its own value anyways?  It doesn't make sense to return ```nil``` when some proc was expected to be called.
+
+Consider the following example:
+
+    A.weather = :sunny
+    B.weather = nil
+    C.weather = nil
+  
+    A.mood = Proc.new{ "angry" }
+    B.mood = nil
+    C.mood = nil
+
+We've forced the ```weather``` and ```mood``` properties on B and C to be blank:
+
+    B.weather_is_blank?  # => true
+    B.mood_is_blank?     # => true
+
+typical calls to B's mood evalutes A's new proc:
+
+    B.mood  # => "angry"
+
+notice how many ways we can instead force it to evaluate the default proc:
+
+    B.mood :default            # => "happy"
+    B.mood :inherit => false   # => "happy"
+    B.mood :inherit => 0       # => "happy"
+    B.mood false               # => "happy"
+    B.mood nil                 # => "happy"
+    B.mood 0                   # => "happy"
+
+when proc inheritance is overriden, it reverts to the default
+
+### blank proc properties: property-wide override
+
+You can get the same effect at the property-wide level simply by ensuring proc's don't inherit at all:
+
+    A.cascade do
+      mood :default => Proc.new{|me| me.weather == :sunny ? "content" : "depressed"}, :inherit => false
+    end
+
+    A.weather = :sunny  
+    B.weather = C.weather = nil   # set the others to blank
+
+    A.mood  # => "content"
+    B.mood  # => "content"
+    C.mood  # => "content"
+
+Now, any descendent that redefines the mood cannot affect further downstream descendents:
+
+    B.mood = Proc.new{ "angry" }
+
+    A.mood   # => "content"
+    B.mood   # => "angry"
+    C.mood   # => "content"
+
+### overridding the override
+
+Of course you can force a descendent to inherit the proc:
+
+    C.mood        # => "content"
+    C.mood true   # => "angry"
+
+### summary of procs
+
+All you need to remember is that proc properties inherit their proc by default but that blank properties use the default proc (if given).
+
+### procs not of type ':Proc'
+
+You can also set a property to a proc even if it has a different type. This is useful if the property is to be static for the parent, but dynamic for some descendent(s).  Consider the following:
+
+    A.cascade do
+      ingredients :default => Set.new([:sugar, :butter, :flour, :eggs]), :inherit => true
+    end
+
+    B.cascade do
+      diabetic :default => false
+    end
+
+    B.ingredients = Proc.new do |me, parents|
+      me.diabetic ? parents.first.ingredients.dup.delete(:sugar) << :splenda :
+        parents.first.ingredients.dup.delete(:splenda) << :sugar
+    end
+
+In this case, the ingredients property is of type ```:Set```.  It is still a set even when B redefines it using a proc.  Property types don't change once defined.  But by 'setting' it to a proc, B and its descendents (since ```:inherit => true```) get a list of ingredients that changes based on the diabetic property.
+
+    class D < C; end
+
+    C.diabetic = true
+    D.diabetic = false
+
+    p B.diabetic           # => false
+    p C.diabetic           # => true
+    p D.diabetic           # => false
+
+    p B.ingredients.to_a   # => [:sugar, :butter, :flour, :eggs]
+    p C.ingredients.to_a   # => [:splenda, :butter, :flour, :eggs]
+    p D.ingredients.to_a   # => [:sugar, :butter, :flour, :eggs]
+
+To illustrate this further, let's add another property to A.  Let's give A and its descendents a sweet_tooth property, which takes either true or false.  ```A``` sets its value to false, but his immediate descendent, B, decides that having a sweet tooth should depend upon whether one uses sugar:
+
+    A.cascade do
+      sweet_tooth :default => false
+    end
+
+    B.sweet_tooth = Proc.new{|me| me.ingredients.include? :sugar }
+
+    B.diabetic = false
+    C.diabetic = true
+    D.diabetic = false
+
+    p A.ingredients.to_a    # => [:sugar, :butter, :flour, :eggs]
+    p B.ingredients.to_a    # => [:sugar, :butter, :flour, :eggs]
+    p C.ingredients.to_a    # => [:splenda, :butter, :flour, :eggs]
+    p D.ingredients.to_a    # => [:sugar, :butter, :flour, :eggs]
+
+    p A.sweet_tooth         # => false
+    p B.sweet_tooth         # => true
+    p C.sweet_tooth         # => false
+    p D.sweet_tooth         # => true
+
+Obviously the sweet_tooth property depends on the diabetic property, but it does so through the ingredients property for every class except A.  This is an indirect dependency.  That's the point.  You can construct a class hierachy (read: template) having a core collection of properties with simple dependencies and then layer on more complicated properties (read: extra functionality) as needed. 
+
+Notice that the previous example requires ```:inherit => true``` on the initial ingredients definition:
+
+    A.cascade do
+      ingredients :default => Set.new([:sugar, :butter, :flour, :eggs]), :inherit => true
+    end
+
+Again, this is because container types don't inherit by default.  And that's also why the sweet_tooth property didn't need the same treatment: it's not a type of container.
+
+## blocks
+
+You can pass a block to any property call.  The block takes two parameters: the property value and an array of parents.  Notice the subtle difference between block parameters and proc parameters: whereas procs are given the __object__ itself as the first parameter, blocks are given the __value__ of the property for that object.
+
+This makes it easy to obtain a property's ancestors relative to any node:
+
+    A.cascade do
+      color :default => "red"
+    end
+    B.color = "blue"
+    C.color = "white"
+
+    parents = C.color{|my_color, parents| parents}
+
+    p parents   # => [B, A]
+
+For another example, consider the following:
+
+    A.cascade do
+      location :default => :urban
+      trendy :default => Proc.new{|me| me.location == :urban}
     end
-    Child.has_hair = true
 
-    p Parent.has_hair?   # => false
-    p Parent.hair?       # => false
+    B.location = :rural
+    C.location  = :urban
 
-    p Child.has_hair?   # => true
-    p Child.hair?       # => true
+    blk = Proc.new do |is_trendy, parents|
+      puts "my ancestors are: #{parents} and I am #{is_trendy ? '' : 'not'} trendy"
+    end
+
+    p A.trendy &blk    # => "my ancestors are: [] and I am trendy"
+    p B.trendy &blk    # => "my ancestors are: [A] and I am not trendy"
+    p C.trendy &blk    # => "my ancestors are: [B, A] and I am trendy"
+
+By making the ancestor chain available as a parameter, a block become a powerful tool.  One particular case they come in handy is when merging a property's values across ancestors.  For example, let's create a ```foods``` property and a block that concatenates a node's foods with its ancestors:
+
+    A.cascade do
+      foods :default => [:pasta, :tomatoes]
+    end
+
+    B.foods << :apples << :walnuts
+
+    C.foods << :chips
+
+    all = Proc.new do |my_foods, parents|
+      my_foods + parents.inject([]){|r, parent| r += parent.foods}
+    end
+
+    p A.foods        # => [:pasta, :tomatoes]
+    p B.foods        # => [:apples, :walnuts]
+    p C.foods        # => [:chips]
+
+    p A.foods &all   # => [:pasta, :tomatoes]
+    p B.foods &all   # => [:apples, :walnuts, :pasta, :tomatoes]
+    p C.foods &all   # => [:chips, :apples, :walnuts, :pasta, :tomatoes]
+
+For a second example, let's create an options property and a block to merge all options giving precedence to the child:
+
+    A.cascade do
+      options :hash => true
+    end
+
+    A.options = {:color => "black", :music => ["Rolling Stones"]}
+    B.options[:music] = ["Arcade Fire"]
+    C.options = {:color => "blond"}
+
+    merged = Proc.new do |my_opts, parents|
+      parents.reverse.inject({}){|r, child|
+        r.merge(child.options)
+      }.merge(my_opts)
+    end
+
+    p A.options    # => {:color => "black", :music => ["Rolling  Stones"]}
+    p B.options    # => {:music => ["Arcade Fire"]}
+    p C.options    # => {:color => "blond"}
+
+    p A.options &merged   # => {:color => "black", :music => ["Rolling Stones"]}
+    p B.options &merged   # => {:color => "black", :music => ["Arcade Fire"]}
+    p C.options &merged   # => {:color => "blond", :music => ["Arcade Fire"]}
+
+If you find yourself operating on a node's parents often, you can also create a new proc property to do it for you:
+
+    A.cascade do
+      opts :default => {:color => "black", :music => ["Rolling Stones"]}
+      merged_opts :proc => true
+    end
+
+    A.merged_opts = Proc.new do |me, parents|
+      parents.reverse.inject({}){|r, child|
+        r.merge(child.opts)
+      }.merge(me.opts)
+    end
+
+    B.options[:music] = ["Arcade Fire"]
+    C.options[:color] = "blond"
+
+    p A.merged_opts   # => {:color => "black", :music => ["Rolling Stones"]}
+    p B.merged_opts   # => {:color => "black", :music => ["Arcade Fire"]}
+    p C.merged_opts   # => {:color => "blond", :music => ["Arcade Fire"]}
+
+## instances
+
+Everything applies equally to class instances except for a few caveats. To actually operate on instances you must either ```include``` the library (instead of ```extend```) or specify ```:instances => true``` for each property inside the ```cascade``` call.
+
+    class A
+      include CC
+    end
+
+    A.cascade do
+      colors :default => [:red, :blue, :green]
+    end
+
+or
+
+    class A
+      extend CC
+    end
+
+    A.cascade do
+      colors :default => [:red, :blue, :green], :instances => true
+    end
+
+Instances are treated as child nodes.  For instance
+
+    A.cascade do
+      color :default => "red"
+    end
+
+    a = A.new
+    b = B.new
+
+    p B.color{|color, parents| parents}   # => [A]
+    p a.color{|color, parents| parents}   # => [A]
+
+    p C.color{|color, parents| parents}   # => [B, A]
+    p b.color{|color, parents| parents}   # => [B, A]
+    
+It is important to note that instances aren't as flexible as classes since they cannot be the parent of another node.  For instance, B is a child of A, but it is also the parent of C.  Every instance of B is a child and only a child of B.  Keep this in mind when implementing your hierarchy. 
+
+Other than that, you can operate on instances just as you would any other child class:
+
+    A.cascade do
+      name :default => "George"
+      colors :default => [:green, :yellow, :purple]
+    end
+
+    a = A.new
+    b = B.new
+
+    p A.name  # => "George"
+    p a.name  # => "George"  (inherits from A)
+    p B.name  # => "George"  (inherits from A)
+    p b.name  # => "George"  (inherits from A)
+
+    A.name = "Jefferson"
+    B.name = "Sam"
+    
+    p B.name  # => "Sam"
+    p b.name  # => "Sam"   (inherits from B)
+
+    b.name = "Timothy"
+    p b.name  # => "Timothy"  (own)
+
+    p A.name :default  # => "George"
+    p a.name :default  # => "George"
+    p B.name :default  # => "George"
+    p b.name :default  # => "George"
     
-While not recommended, you can also apply custom getter/setter name in the array style syntax. 
+    a.colors << :blue << :white
 
-    Parent.cascade [:has_hair, false, true, [:has_hair?, :hair?]]
-   
-this initializes the ```has_hair``` property on ```Parent``` to false and sets the getter functions to ```:has_hair?``` and ```:hair?```. Recall that the third argument in the block explicitly sets whether class instances are inherit the property. 
+    B.colors << :pink << :black
+    b.colors << :black
 
-If you wanted to apply a custom setter, it would be the fifth argument:
+    p A.colors   # => [:green, :yellow, :purple]
+    p a.colors   # => [:blue, :white]
+    p B.colors   # => [:pink, :black]
+    p b.colors   # => [:black]
 
-    Parent.cascade [:has_hair, false, true, :hair?, :hair!]
+## Custom Classes
 
-Compare how much worse that looks compared to the block syntax:
+Properties can be any kind of object.  To work with other class types you will need to define "blank" values and "new" values.  
 
-    Parent.cascade do
-      hair_color :default => false, :instances => true, :getter => :hair?, :setter => :hair!
+Let's implement a custom type that is a sublcass of Hash
+
+    class MyCustom < Hash
+      def initialize(*arr)
+        return super unless arr.size > 0
+	[*arr].flatten.each_slice(2){|k,v| self[k] = v}
+      end
     end
+
+This gives us some flexible ways to initialize a hash:
+
+    c1 = MyCustom.new [[:name, "Gabe"], [:profession, "student"]]
+    c2 = MyCustom.new [:name, "Gabe"], [:profession, "student"]
+    c3 = MyCustom.new :name, "Gabe", :profession, "student"
+
+    p c1  # => {:name => "Gabe", :profession => "student"}
+    p c2  # => {:name => "Gabe", :profession => "student"}
+    p c3  # => {:name => "Gabe", :profession => "student"}
+
+To incorporate MyCustom into a class hierarchy, we'll do the obvious thing:
+
+    A.cascade
+      custom :default => c1,
+             :inherit => false,
+             :blank => lambda{|v| v.size.zero?},
+	     :new => lambda{ MyCustom.new }
+    end
+
+We didn't have to specify the inheritance since MyCustom is an ancestor of Enumerable, making it a container.  It doesn't hurt to overspecify. 
+
+It helps to verify that your ```blank``` and ```new``` proc work as expected and that the default value is correct using the metadata hash:
+
+    props = A.singleton_class.properties
+
+    c = MyCustom.new
+    
+    p props[:custom][:new].call == c   # => true
+    p props[:custom[:blank].call(c)    # => true
+    p props[:custom][:type]            # => :MyCustom
+    p props[:custom][:default] == c1   # => true
+
+Now you can use the property anywhere in the class tree:
+
+    B.custom             # => {}
+    B.custom(:default)   # => {:name => "Gabe", :profession => "student"}