RubyGems - cascading_classes - Versions diffs - 0.6.0 → 0.6.1 - Mend

cascading_classes 0.6.0 → 0.6.1

Files changed (5) hide show

data/README.md CHANGED Viewed

@@ -1,28 +1,20 @@
-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)
 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.
-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:
+This is a small library that helps simplify and manage deeply hierarchal data. It can be used for brainstorming. It can be used to model a tree of data of any depth and breadth. You can use it for brainstorming or to carry active content.
-* 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)
+__Forewarning:__ This library commits the heinous (blasphemous?) crime of focusing on classes as useful objects in their own right rather than the objects spawned form them. Stuff like this:
-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.
+    Parent.last_name = 'brownstein'
+    Parent.first_name = "charlie"
+    Parent.name = Proc.new{|c| c.first_name + ' ' + c.last_name}
-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.
+    Child.first_name = "sam"
-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__?
+    p Child.name     #  =>  "sam brownstein"
-Only after doing all this are ready to use this library.
+You have been warned!
-# Quick Tour
+# Take it for a quick spin
 Assume the following simple class hierarchy:
@@ -36,1040 +28,195 @@ Assume the following simple class hierarchy:
     class C < B
     end
-A is the top-level parent, B is one of A's (possibly many) children.  C is one of B's (possibly many) children.
-Create ```name, city and state``` properties:
-    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:
-    p A.name   # => "Franklin"
-    p A.city   # => "New York"
-    p A.state  # => "NY"
-furthermore, blank descendents inherit the same property values:
-    p B.name    # => "Franklin"
-    p C.name    # => "Franklin"
-    p B.city    # => "New York"
-    p C.city    # => "New York"
-    ...
-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
+Notice that ```CC``` is an alias for ```CascadingClasses```
-# In Depth:
-Assume a simple three node, three generation setup:
     class A
-      include CC
-    end
-    class B < A
-    end
-    class C < B
+      extend CC
     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.
+is equivalent to
-### 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
+    class A
+      extend CascadingClasses
     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
+Note also the difference between the *extend* and the *include* versions. Objects of a class are able to inherit class properties created with `cascade` when *include* is used. When *extend* is used objects do not inherit *cascaded* properties. Note that subclasses *always* inherit the cascaded properties.  A quick example will explain it better than words:
-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"
+    class Person
+      extend CC
     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
+    Person.cascade do
+      language default: "english"
     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.
+    person = Person.new
-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.
+    p Person.language     #  =>  "english"
+    p person.language     #  =>  NoMethodError: undefined method 'language' for #<Person:0x0000...>
-### set the type manually
+compare this to:
-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
+    class Person
+      include CC
     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 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
-      urls :default => ["www.google.com", "www.nytimes.com"]
-      name :default => {:first => 'jon', :last => 'smith'}
+    Person.cascade do
+      language default: "english"
     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"]
+    person = Person.new
-    p A.name    # => {:first => 'jon', :last => 'smith'}
-    p B.name    # => {}
-    p C.name    # => {}
+    p Person.language     #  =>  "english"
+    p person.language     #  =>  "english"
-    B.name[:first] = "adam"
-    B.name[:last] = "johnson"
-    C.name = {:first => 'terry', :last => 'williamson'}
+The `person` object doesn't have the ```language``` property in one and does in another.
-    p A.name       # => {:first => 'jon', :last => 'smith'}
-    p B.name       # => {:first => 'adam', :last => 'johnson'}
-    p C.name       # => {:first => 'terry', :last => 'williamson'}
+There are two versions to emphasize the point that objects aren't themselves inheritable. Consider a class hierarchy a hundred levels deep. A class can give birth to whole host of classes (through subclassing) made in its own image. Objects are unable to offer its own traits to the next generation of classes. They can inherit from above, but no object (or class) inherits from it. Hence the difference between *extend* and *include*
-### container lack inheritance override
+## Continuing the tour
-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):
+Let's create a new example
-    A.cascade do
-      cities :default=> ["boston", "new york"], :inherit => true
+    Class A
+      extend CC
     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"
+    Class B < A; end
-    p A.cities             # => ["boston", "new york"]
-    p B.cities             # => ["london"]
+    Class C < B; end
-you can also ommit the the ':inherit' bit
+A is the top-level parent. B is its child. C is the child of B.
-    B.cities = []
-    p B.cities         # ["boston", "new york"]  (inherits from A)
-    p B.cities false   # []  (own value)
+    A  <  B  <  C
-    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:
+create ```name``` and ```city``` properties:
     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 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"]
+      name default: "Tom"
+      city default: "New York"
     end
+Notice that properties are creating by calling ```cascade``` on a class. The act of creating another generation is done through subclassing. In this case, every subclass of ```A``` will have the class properties ```name``` and ```city```. These properties will be propagated to every descendent below ```A```.
-    p props.keys             # => [:states, :colors]
-    p props[:states].keys    # => [:default, :instances_too, :getters, :setters, ...]
+    p A.name     #  =>  "Tom"
+    p B.name     #  =>  "Tom"
+    p C.name     #  =>  "Tom"
-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:
+Each descendent *inherits* its parent's value if unset.
-    props = A.singleton_class.properties
+    p A.name_is_unset?     #  =>  false
+    p B.name_is_unset?     #  =>  true
+    p C.name_is_unset?     #  =>  true
-### metadata - check 'inheritance' status
+    p A.name     #  =>  "Tom"
+    p B.name     #  =>  "Tom"
+    p C.name     #  =>  "Tom"
-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.
+Notice the dynamic class method ```name_is_unset?``` created from the ```name``` property.
-    p props[:states][:inherit]     # => true
-    p props[:colors][:inherit]     # => false
+Naturally properties can be read and written to. Let's update the ```name``` on B:
-### more on inheritance and max inherit age
+    B.name = "John"
+    p B.name     #  =>  "John"
-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```).
+It's crucuial to see how this effects the descendents of ```B```. Notice how this value cascades down to ```C```
-    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 C.name     #  =>  "John"
-    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:
+At any point in time we can add nodes anywhere along the tree: up or down:
-    A.cascade do
-      servers :inherit => true
-      users
+    class B2 < A
     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 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"}
+    class C2 < B2
     end
-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
-    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 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.
-    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
+    class D < C
     end
-    A.weather = :sunny
-    B.weather = C.weather = nil   # set the others to blank
-    A.mood  # => "content"
-    B.mood  # => "content"
-    C.mood  # => "content"
+Our tree now looks like the following:
-Now, any descendent that redefines the mood cannot affect further downstream descendents:
-    B.mood = Proc.new{ "angry" }
+                                               _______  D
+                                             /
+                                            /
+                             ________   C   --------  ..
+                           /
+                          /
+            ________  B   --------  ..
+          /               \
+         /                 \ ________  ..
+        /
+    A   --------  ..         ________  ..
+        \                  /
+         \                /                   ________  ..
+          \ ________  B2  --------  ..       /
+                          \                 /
+                           \ ________   C2  -------- ..
-    A.mood   # => "content"
-    B.mood   # => "angry"
-    C.mood   # => "content"
-### overridding the override
+We now have six nodes that span four generations (depth=4). Things have gotten considerably more complex. That's the point. It's easy for the complexity to get out of hand. But you need a way of applying properties across the whole of it in a way that is predictible and sensible. We can continue forever adding (subclassing) nodes and watch each descendent come to life endowed with a sensible```name``` and ```city```.
-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
+We can also, at any point, introduce new properties onto the tree, or any subtree of the tree. And you can expect each descendent to inherit from its parent in real time. For example, we let's add the ```state``` property to all descendents of ```B```
     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
+      state default: "MA"
     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 B.state     #  =>  "MA"
+    p C.state     #  =>  "MA"
+    p D.state     #  =>  "MA"
-    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]
+# Another simple example
-    p A.sweet_tooth         # => false
-    p B.sweet_tooth         # => true
-    p C.sweet_tooth         # => false
-    p D.sweet_tooth         # => true
+Let's try another example. This time we'll allow objects themselves to take after their class parent (requires use of ```include``` keyword). Objects inherit from their class, but are not inheritable themselves. We'll begin with three properties: ```color```, ```width```, and ```height```.
-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
+    class Parent
       include CC
     end
-    A.cascade do
-      colors :default => [:red, :blue, :green]
+    Parent.cascade do
+      color default: "red"
+      width default: 100
+      height default: 50
     end
-or
+    class Div1 < Parent; end
+    class Div2 < Parent; end
-    class A
-      extend CC
-    end
+    div1 = Div1.new
+    div2 = Div2.new
-    A.cascade do
-      colors :default => [:red, :blue, :green], :instances => true
-    end
+Every object and class in this hierarchy has a color, height, and width.
-Instances are treated as child nodes.  For instance
+    p Div1.color     #  =>  "red"
+    p div1.color     #  =>  "red"
-    A.cascade do
-      color :default => "red"
-    end
+    Div1.color = "blue"
-    a = A.new
-    b = B.new
+    p Div1.color     #  =>  "blue"
+    p div1.color     #  =>  "blue"
-    p B.color{|color, parents| parents}   # => [A]
-    p a.color{|color, parents| parents}   # => [A]
+    div1.color = "black"
-    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.
+    p Div1.color     #  =>  "blue"
+    p div1.color     #  =>  "black"
-Other than that, you can operate on instances just as you would any other child class:
+We can collect the property values by calling ```to_hash```
-    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
+    p Div1.to_hash     #  =>  {:color=>"blue", :width=>100, :height=>50}
-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
+If you only want to see the hash of properties that have been set, pass ```false```
-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.
+    p Div1.to_hash            #  =>  {:color=>"blue", :width=>100, :height=>50}
+    p Div1.to_hash(false)     #  =>  {:color=>"blue"}
-It helps to verify that your ```blank``` and ```new``` proc work as expected and that the default value is correct using the metadata hash:
+Notice that we have only set the ```color``` property on ```Div1```. Let's give a height different from its parent.
-    props = A.singleton_class.properties
+    Div1.height = 75
-    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
+    p Div1.to_hash(false)     #  =>  {:color=>"blue", :height=>75}
-Now you can use the property anywhere in the class tree:
+This concludes the introduction to this library. To learn about what happens when properties are arrays or hashes or to learn about dynamic properties and what that means in the context of *cascade* see [todo](#)
-    B.custom             # => {}
-    B.custom(:default)   # => {:name => "Gabe", :profession => "student"}