cascading_classes 0.6.1 → 0.6.2

data/spec/usage/proc_spec.rb

@@ -20,17 +20,17 @@ describe "options" do
   describe "proc values are called alone or evaluated with instance exec" do
     it "has a global default" do
       CC.proc_inst_exec = true
-      CC.proc_inst_exec?.must_equal true
+      CC.proc_inst_exec?.should == true
 
       CC.proc_inst_exec = false
-      CC.proc_inst_exec?.must_equal false
+      CC.proc_inst_exec?.should == false
     end
 
     it "defaults to global setting" do
       props = A.cascade do
         color
       end
-      props[:color][:proc_inst_exec].must_equal(CC.proc_inst_exec?)
+      props[:color][:proc_inst_exec].should ==(CC.proc_inst_exec?)
     end
 
     it "can be set in the 'cascade' block, overruling the global default" do
@@ -38,7 +38,7 @@ describe "options" do
       props = A.cascade do
         color :proc_inst_exec => false
       end
-      props[:color][:proc_inst_exec].must_equal false
+      props[:color][:proc_inst_exec].should == false
     end
 
     it "can be set in 'opts' hash of property method, overruling others" do
@@ -50,11 +50,11 @@ describe "options" do
 
       B.color = Proc.new{|me, parents| who_is_self = self; :orange}
 
-      B.color.must_equal :orange
-      who_is_self.must_equal(outside_context)
+      B.color.should == :orange
+      who_is_self.should ==(outside_context)
 
-      B.color(:undef, :undef, {:proc_inst_exec => true}).must_equal :orange
-      who_is_self.must_equal(B)
+      B.color(:undef, :undef, {:proc_inst_exec => true}).should == :orange
+      who_is_self.should ==(B)
     end
   end
 end

data/todo

@@ -1,3 +1,24 @@
+tests
+  spec/basics/inherit_spec.rb
+
+feature??
+  new method: first_parent OR direct_parent ??
+    will return ancestor_chain.first
+
+Bug ??
+  Proc property descendent on non Proc ancestor doesn't inherit behavior ??
+    example:
+      class A; extend CC; end
+      B = Class.new A
+      C = Class.new B
+      A.cascade{ width default: 100 }
+      B.width = Proc.new{|me, parents| parents.last.width + 10}
+      p B.width     #  =>  110  (good)
+      p C.width     #  =>  110  (is this correct?)
+≈
+Bug
+  ancestor_chain doesn't work on instances
+
 Bug
   to_hash not working for objects
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cascading_classes
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.6.2
   prerelease: 
 platform: ruby
 authors:
@@ -18,7 +18,6 @@ extensions: []
 extra_rdoc_files: []
 files:
 - README.md
-- README-part-ii.md
 - Rakefile
 - todo
 - lib/cascading_classes.rb

data/README-part-ii.md

@@ -1,1020 +0,0 @@
-## WORK IN PROGESS ...
-
-
-
-Update the properties on A's desendents:
- 
-    B.name = "Charles"
-    C.name = "Sam"
-
-    C.city = "Rochester"
-
-Collect property names and values:
-
-    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"}
-
-pass 'false' for only those properties that were specifically set:
-
-    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  
-
-### ...more...
-
-Add a second child to A based out of Boston:
-
-    B2 = Class.new(A)  # same as: class B2 < A; end
-    
-    B2.name = 'Thomas'
-    B2.city = 'Boston'
-    B2.state = 'MA'
-
-Descendents of B2 will inherit these new values unless set. 
-
-    class C2 < B2; end
-
-    p C2.city   # => Boston
-    p C2.state  # => MA
-
-Now we have three properties on five nodes spanning three generations. 
-
-Let's add two more properties; these will depend on one's location:
-
-    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
-
-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.  
-
-Watch how this works for our five node, three generation setup.  Notice how each proc (read: behavior) cascades down the class hierarchy:
-
-    p A.baseball_team    # => "Yankees"
-    p B.baseball_team    # => "Yankees"
-    p C.baseball_team    # => "Yankees"
-
-    p B2.baseball_team   # => "Red Sox"
-    p C2.baseball_team   # => "Red Sox"
-
-If we change C2's location, its teams should follow suit:
-
-    C2.city = "New York"
-    C2.state = "NY"
-
-    p C2.baseball_team     # => "Yankees"
-    p C2.basketball_team   # => "Knicks"
-
-Any new node added to the mix should be "born" with the same behavior:
-
-    class D < C; end
-
-    p D.state           # => "NY"
-    p D.baseball_team   # => "Yankees"
-
-    D.state = "MA"
-    p D.baseball_team   # => "Red Sox"
-
-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.   
-
-Finally, let's add a child to C2, located in Los Angeles, and rewrite the sports properties to fit our bulging world:
-
-    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
-    
-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:
-
-    A.cascade do
-      teams :default => Proc.new{|me|
-        [me.baseball_team, me.basketball_team]
-      }
-    end
-
-test it out
- 
-    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"]
-
-### top it off with a block
-
-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:
-
-    p D2.teams do |val, parents|
-      puts "D2: #{val.inspect}"
-      parents.each{|parent| puts "#{parent}: #{parent.teams.inspect}"}
-    end
-
-         # => 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, it sets the score property on A to 45.2, the rank property on A to 4, the color property on A to "red"... This is in addition to setting global, fixed defaults for those properties.
-
-### 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 is preset with 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 the same thing for the ```rank``` property for nodes B and C except that it wasn't explicitly set to a blank value, but rather, being unset, 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 its blank.  If it is, it proxies to its nearest parent, otherwise it returns the 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   # => 12
-    p C.rank   # => 12
-
-Of course, this cascading behavior may not be what you want.  You can explicitly control whether a property can inherit by passing an argument in the property call:
-
-    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, which it duly does as it is.  
-
-It's important to realize that any property that is not blank will never inherit no matter what arguments you pass (except if the argument is ':default').
-
-    C.score = 17.4
-
-    p A.score(true)   # => 19.2
-    p A.score(false)  # => 19.2
-    p C.score(true)   # => 17.4
-    p C.score(false)  # => 17.4
-
-Here, the ```score``` property on A and C is not blank so any call to the property, regardless of the argument passed, returns its 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 has to reach two generations higher to find a nonblank value.  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:
-
-    A.score = 87.4
-    B.score = C.score = nil
-    
-    p A.score_is_blank?   # => false
-    p B.score_is_blank?   # => true
-    p C.score_is_blank?   # => true
-
-    C.score = 18.2
-    p A.score_is_blank?   # => false
-    p B.score_is_blank?   # => true
-    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.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 static values and can be referenced at any time by any node in the tree.
-
-Recall that the side effect of including a default value is that the parent property gets set to that value.  Let's create a ```city``` property that defaults to "seatle"
-
-    A.cascade do
-      city :default => "seatle"
-    end
-
-    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 
-
-Defaults are not required, but if not given, the type of the property won't be known until it is first assigned.
-
-    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
-
-    p props[:color][:type]         # => :undefined_type
-    A.color = "red"
-    p props[:color][:type]         # => :String
-
-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.
-
-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.
-
-### set the type manually
-
-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:
-
-    props = A.cascade do
-      name :Hash => true
-      address :hash => true
-      city :String => true
-      area :fixnum => true
-      zip :Fixnum => true
-    end
-
-    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
-
-## container types: arrays, hashes, sets, ...
-
-Container properties are those that implement ```each``` or include ```Enumerable```.  The definition of "blank" for arrays, hashes and sets is 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
-      urls :default => ["www.google.com", "www.nytimes.com"]
-      name :default => {:first => 'jon', :last => 'smith'}
-    end
-
-    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"]
-
-    p A.name    # => {:first => 'jon', :last => 'smith'}
-    p B.name    # => {}
-    p C.name    # => {}
-
-    B.name[:first] = "adam"
-    B.name[:last] = "johnson"
-    C.name = {:first => 'terry', :last => 'williamson'}
-
-    p A.name       # => {:first => 'jon', :last => 'smith'}
-    p B.name       # => {:first => 'adam', :last => 'johnson'}
-    p C.name       # => {:first => 'terry', :last => 'williamson'}
-
-### container non inheritance override 
-
-You can override the default lack of inheritance for containers 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):
-
-    A.cascade do
-      cities :default=> ["boston", "new york"], :inherit => true
-    end
-
-    p A.cities     # => ["boston", "new york"]
-    p B.cities     # => ["boston", "new york"]  (inherited from A)
-    p C.cities     # => ["boston", "new york"]  (inherited from A)
-
-    p A.cities_is_blank?   # => false
-    p B.cities_is_blank?   # => true
-    p C.cities_is_blank?   # => true
-
-if you think this is useful, just take care not to trip over yourself
-
-    B.cities << "london"
-
-    p B.cities_is_blank?   # => true
-    p A.cities             # => ["boston", "new york", "london"]
-    p B.cities             # => ["boston", "new york", "london"]
-
-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
-
-    p A.cuisine            # => [:italian, :french]
-    p B.cuisine            # => []
-    p C.cuisine            # => []
-
-    p B.cuisine :inherit   # => [:italian, :french]
-    p C.cuisine :inherit   # => [:italian, :french]
-
-The inherit argument, if given, 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: 
-
-    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)
-
-you can ommit the ':inherit' syntax entirely:
-
-    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]
-
-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 time the property is called, the inheritance age will be set to -1.  That is, it will assume you want to inherit upwards until the first parent node with a nonblank value is.  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
-
-    A.servers = ["rails", "sinatra"]
-    A.users = [:bigfoot, :charlie]
-
-    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"]
-
-    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]
-
-##  Proc Properites
-
-Properties set to a proc are invoked on each property call. This makes it easy to create complex property dependencies.  Note that the concept of property depending on other properties is indepenent of the concept of class hierarchies (and property inheritance).  You can have a tree with a single node (no inheritance) and yet contain a complex web of dependencies.  There may be a pyramid of property dependencies stacked on the 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 with another type, but with a descendent that 'sets' the property to a proc.  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
-
-In this case, the color depends on the mood and the mood depends on the weather.  (Take class A by itself and you have an example of property dependencies without class hierarchies)
-
-    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
-    
-    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).
-
-Let's give B its own mood proc. 
-
-    B.mood = Proc.new{|me, parents|
-      parents.first.mood == "miserable" ? "happy" : "miserable"
-    }
-
-B's mood now depends not on its own weather property but on the mood of its first parent.  When A is happy, B is misearble and when A is miserable, B is happy.  
-
-    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 grabs B's mood proc and evaluates it in its own context.  Since the mood based on the first parent's mood and B is C's first parent, C's mood is always the opposite of B's, which in turn is always the opposite of A's mood.
-
-Take a step back and consider what has been accomplished.  You have created a behavior that, for some nodes, depends on the weather property and for others instead depends on the node's parent.  You can bring incredibly large inheritance trees to life with just a few properly-written behaviors.  
-  
-### 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
-
-    B.location = :rural
-    C.location  = :urban
-
-    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"
-    
-    a.colors << :blue << :white
-
-    B.colors << :pink << :black
-    b.colors << :black
-
-    p A.colors   # => [:green, :yellow, :purple]
-    p a.colors   # => [:blue, :white]
-    p B.colors   # => [:pink, :black]
-    p b.colors   # => [:black]
-
-## Custom Classes
-
-Properties can be any kind of object.  To work with other class types you will need to define "blank" values and "new" values.  
-
-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"}