cascading_classes 0.6.1 → 0.6.2

data/README.md

@@ -2,16 +2,30 @@ Cascading Classes
 
 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. 
 
-__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:
+__Warning:__ This library commits the blasphemous crime of utilizing classes as objects. Stuff like this:
 
-    Parent.last_name = 'brownstein'
-    Parent.first_name = "charlie"
-    Parent.name = Proc.new{|c| c.first_name + ' ' + c.last_name}
-
-    Child.first_name = "sam"
+    Parent.lname = 'brownstein'
+    Parent.fname = "charlie"
+    Parent.name = Proc.new{|c| c.fname + ' ' + c.lname}
 
+    Child.fname = "sam"
     p Child.name     #  =>  "sam brownstein"
 
+Whereas normally you might write something like this:
+  
+    class Parent
+      attr_accessor :fname, :lname
+
+      def name
+        fname + ' ' + lname
+      end
+    end
+
+    obj = Parent.new
+    obj.fname = 'sam'
+    obj.lname = 'brownstein'
+    p obj.name     #  =>  'sam brownstien'
+
 You have been warned!
 
 # Take it for a quick spin
@@ -40,39 +54,41 @@ is equivalent to
       extend CascadingClasses
     end
 
-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:
+Note also the difference between the *extend* and the *include* versions. Class instances will not "inherit" cascaded properties with *extend* but will with *include*. 
 
     class Person
       extend CC
+   
+      cascade do
+        language default: "english"
+      end
     end
 
-    Person.cascade do
-      language default: "english"
-    end
-
-    person = Person.new
+    Brit = Class.new(Person)     #  same as: class Brit < Person; end
+    john = Person.new
 
-    p Person.language     #  =>  "english"
-    p person.language     #  =>  NoMethodError: undefined method 'language' for #<Person:0x0000...>
+    p Brit.language       #  =>  "english"
+    p john.language     #  =>  NoMethodError: undefined method 'language' for #<Person:0x0000...>
 
-compare this to:
+compare that to the following:
 
     class Person
       include CC
-    end
 
-    Person.cascade do
-      language default: "english"
+      cascade do
+        language default: "english"
+      end
     end
 
-    person = Person.new
+    Brit = Class.new(Person)
+    john = Person.new
 
-    p Person.language     #  =>  "english"
-    p person.language     #  =>  "english"
+    p Brit.language       #  =>  "english"
+    p john.language     #  =>  "english"
 
-The `person` object doesn't have the ```language``` property in one and does in another.
+The `john` instance doesn't have the ```language``` property in one and does in another.
 
-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*
+There are two versions to emphasize the point that calling *cascade* is about endowing your descendents with traits. And instances aren't inheritable. They don't have children. Consider a class hierarchy a hundred levels deep. Calling *cascade* on any one class will effect it and all its descendents. If you want instances of all those classes to be effected as well use *include*. Otherwise use *extend*.  
 
 ## Continuing the tour
 
@@ -97,34 +113,21 @@ create ```name``` and ```city``` properties:
       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```.
+Here we provide A and all its descendents with the *name* and *city* properties. 
 
     p A.name     #  =>  "Tom"
     p B.name     #  =>  "Tom"
     p C.name     #  =>  "Tom"
 
-Each descendent *inherits* its parent's value if unset.
-
-    p A.name_is_unset?     #  =>  false
-    p B.name_is_unset?     #  =>  true
-    p C.name_is_unset?     #  =>  true
-
-    p A.name     #  =>  "Tom"     
-    p B.name     #  =>  "Tom"
-    p C.name     #  =>  "Tom"
-
-Notice the dynamic class method ```name_is_unset?``` created from the ```name``` property. 
-
-Naturally properties can be read and written to. Let's update the ```name``` on B:
+Descendents inherit their values unless set themeselves.
 
     B.name = "John"
     p B.name     #  =>  "John"
-
-It's crucuial to see how this effects the descendents of ```B```. Notice how this value cascades down to ```C```
-
     p C.name     #  =>  "John"
 
-At any point in time we can add nodes anywhere along the tree: up or down:
+It's crucuial to see that C changes too
+
+At any point in time we can add nodes anywhere on the tree:
 
     class B2 < A
     end
@@ -135,7 +138,7 @@ At any point in time we can add nodes anywhere along the tree: up or down:
     class D < C
     end
 
-Our tree now looks like the following:
+Our simple example now looks like the following:
 
 
                                                _______  D
@@ -156,9 +159,9 @@ Our tree now looks like the following:
                            \ ________   C2  -------- ..
 
 
-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```.  
+Now we 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 to apply a set of properties on a tree in a predictible way. We can continue adding (subclassing) nodes and watch each descendent come to life endowed with a sensible values for *name* and *city*.  
 
-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```
+We can also, at any point, introduce new properties onto the tree, or any subtree of the tree for that matter. And you can expect each descendent to inherit from its parent in real time. For example, let's add the *state* property to all descendents of *B*.
 
     B.cascade do
       state default: "MA"
@@ -170,16 +173,16 @@ We can also, at any point, introduce new properties onto the tree, or any subtre
 
 # Another simple example
 
-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```. 
+Let's try another example. This time we'll let properties cascade to instances (requires use of ```include``` keyword). We'll begin with three properties: ```color```, ```width```, and ```height```. 
 
     class Parent
       include CC
-    end
-
-    Parent.cascade do
-      color default: "red"
-      width default: 100
-      height default: 50
+    
+      cascade do
+        color default: "red"
+        width default: 100
+        height default: 50
+      end
     end
 
     class Div1 < Parent; end
@@ -188,35 +191,133 @@ Let's try another example. This time we'll allow objects themselves to take afte
     div1 = Div1.new
     div2 = Div2.new
 
-Every object and class in this hierarchy has a color, height, and width. 
+Every instance and class in this hierarchy has a color, height, and width. 
 
     p Div1.color     #  =>  "red"
     p div1.color     #  =>  "red"
 
-    Div1.color = "blue"
-
-    p Div1.color     #  =>  "blue"
-    p div1.color     #  =>  "blue"
+Set the *color* property 
 
+    Div1.color = "blue"
     div1.color = "black"
 
-    p Div1.color     #  =>  "blue"
-    p div1.color     #  =>  "black"
-
-We can collect the property values by calling ```to_hash```
+We can collect *cascaded* properties values by calling ```to_hash``` 
 
     p Div1.to_hash     #  =>  {:color=>"blue", :width=>100, :height=>50}
 
-If you only want to see the hash of properties that have been set, pass ```false```
+To obtain the hash that includes only properties that have been set (not inherited) pass *false*
 
     p Div1.to_hash            #  =>  {:color=>"blue", :width=>100, :height=>50}
     p Div1.to_hash(false)     #  =>  {:color=>"blue"}
 
-Notice that we have only set the ```color``` property on ```Div1```. Let's give a height different from its parent.
+only the *color* has been set on Div1. The others inherit from *Parent*
 
     Div1.height = 75
-
     p Div1.to_hash(false)     #  =>  {:color=>"blue", :height=>75}
 
-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](#)
+## what is *default* 
+
+Consider this simple example:
+
+    Class A
+      extend CC
+
+      cascade do
+        color default: "red"
+      end
+    end
+
+    B = Class.new(A)
+    C = Class.new(B)
+
+The default value is always available to any descendent, even if the property has since been set.
+
+    C.color = "black"
+    p C.color(:default)     #  =>  "red"
+
+## Arrays and Hashes follow different inheritance rules
+
+Container types actually behave differently. Descendents don't inherit from their ancestors. They start out with empty containers.
+
+Try it with an array:
+
+    A.cascade do
+      list default: []
+    end
+
+    A.list << 4 << 1
+    B.list << 5 << 1
+
+    p A.list     #  =>  [4, 1]
+    p B.list     #  =>  [5, 3]
+
+And a hash:
+
+    A.cascade do
+      dict default: {}
+    end
+
+    A.dict[:width] = 400
+    B.dict[:height] = 20
+
+    p A.dict     #  =>  {:width=>400}
+    p B.dict     #  =>  {:height=>20}
+
+## Proc properties
+
+A property can also be a *Proc*. The object passed to it is a copy of the current class. This allows you to create properties that are derived, dynamic
+
+    A.cascade do
+      score default: 89
+      passed default: Proc.new{|me| me.score > 75}
+    end
+
+Here we've created two new properties. The *passed* property gets its value from the *score* property. Note that calling *passed* evaluates the Proc in the context of the receiver. It doesn't return the Proc itself.
+
+    A.passed     #  =>  true
+
+Now we can change the value on *score* on any descendent and *passed* will change too
+
+    B.score = 72
+    p B.passed     #  => false
+
+## Blocks
+
+You can pass blocks to any property. The parameters passed to the block are the property value and an array of ancestors. Here is an example:
+
+    A.cascade do
+      color default: "red"
+    end
+
+    B = Class.new(A)
+    C = Class.new(B)
+    
+    B.color = "blue"
+    C.color = "white"
+
+    p C.color{|color| color}                #  =>  "red"
+    p C.color{|color, parents| parents}     #  => [B, A]
+
+For example you could print out a list of C and its ancestors' colors
+
+    C.color{|c, parents| [c] + 
+      parents.map{|x| x.color}
+    }                                 #  =>  ["white", "blue", "red"]
+
+Or you can set the color on every ancestor:
+
+    C.color{|c, parents| parents.each{|p| p.color = c}}
+
+    p A.color     #  =>  "white"
+    p B.color     #  =>  "white"
+    p C.color     #  =>  "white"
+
+## Ancestor chain
+
+To obtain an array of parents call *ancestor_chain*
+
+    A.ancestor_chain     #  => []
+    B.ancestor_chain     #  => [A]
+    C.ancestor_chain     #  => [B, A]
 
+}    

data/spec/basics/basic_spec.rb

@@ -21,15 +21,11 @@ describe "basics" do
     before do
       @props = A.cascade do
         wings
-        features
-        blind
       end
     end
 
-    it "has unknown type of :Object" do
-      @props[:wings][:type].must_equal :undefined_type
-      @props[:features][:type].must_equal :undefined_type
-      @props[:blind][:type].must_equal :undefined_type
+    it "has undefined type" do
+      @props[:wings][:type].should == :undefined_type
     end
   end
   
@@ -48,88 +44,87 @@ describe "basics" do
     end
 
     describe "parent class" do
-      it "has set with the default value" do
-        A.color.must_equal "red"
-        A.score.must_equal 45.9
-        A.rank.must_equal 18
-        A.style.must_equal :spotted
-        A.available.must_equal true
-        A.locations.must_equal [:south, :north]
-        A.name.must_equal({:first => 'jon', :last => 'smith'})
-        A.classified.must_equal true
+      it "is set with the defaults" do
+        A.color.should == "red"
+        A.score.should == 45.9
+        A.rank.should == 18
+        A.style.should == :spotted
+        A.available.should == true
+        A.locations.should == [:south, :north]
+        A.name.should eq({:first => 'jon', :last => 'smith'})
+        A.classified.should == true
       end
     end
 
     describe "descendents" do
-      it "has access to the 'default' value" do
-        A.color(:default).must_equal "red"
+      it "can access the defaults" do
+        A.color(:default).should == "red"
         A.color = "blue"
-        A.color(:default).must_equal "blue"
-        
+        A.color(:default).should == "red"
         B.color = "white"
-        B.color.must_equal "white"
-        B.color(:default).must_equal "red"
-        C.color(:default).must_equal "red"        
+        B.color.should == "white"
+        B.color(:default).should == "red"
+        C.color(:default).should == "red"        
       end
 
       describe "non-container-type properties" do
-        it "inherits non-blank values from first non-blank ancestor" do
-          @props[:color][:inherit].must_equal true
-          @props[:score][:inherit].must_equal true
-          @props[:rank][:inherit].must_equal true
-          @props[:style][:inherit].must_equal true
-          @props[:available][:inherit].must_equal true
-
-          B.color.must_equal "red"
-          B.score.must_equal 45.9
-          B.rank.must_equal 18
-          B.style.must_equal :spotted
-          B.available.must_equal true
-
-          C.color.must_equal "red"
-          C.score.must_equal 45.9
-          C.rank.must_equal 18
-          C.style.must_equal :spotted
-          C.available.must_equal true
+        it "inherit non-blank values from first non-blank ancestor" do
+          @props[:color][:inherit].should  be_true
+          @props[:score][:inherit].should be_true
+          @props[:rank][:inherit].should be_true
+          @props[:style][:inherit].should be_true
+          @props[:available][:inherit].should be_true
+
+          B.color.should == "red"
+          B.score.should == 45.9
+          B.rank.should == 18
+          B.style.should == :spotted
+          B.available.should be_true
+
+          C.color.should == "red"
+          C.score.should == 45.9
+          C.rank.should == 18
+          C.style.should == :spotted
+          C.available.should == true
 
           B.score = 48.2
           B.style = :rugged
           B.available = false
 
-          B.score.must_equal 48.2 
-          C.score.must_equal 48.2
+          B.score.should == 48.2 
+          C.score.should == 48.2
 
-          B.style.must_equal :rugged
-          C.style.must_equal :rugged
+          B.style.should == :rugged
+          C.style.should == :rugged
 
-          B.available.must_equal false
-          C.available.must_equal false
+          B.available.should be_false
+          C.available.should be_false
         end
       end
 
       describe "container-type properties" do
         it "does not inherit ancestor properties" do
-          @props[:locations][:inherit].must_equal false
-          @props[:name][:inherit].must_equal false
+          @props[:locations][:inherit].should be_false
+          @props[:name][:inherit].should be_false
 
-          B.locations.must_equal Array.new
-          C.locations.must_equal Array.new
-          B.name.must_equal Hash.new
-          C.name.must_equal Hash.new
+          B.locations.should == Array.new
+          C.locations.should == Array.new
+          B.name.should == Hash.new
+          C.name.should == Hash.new
 
           B.locations = [:east, :west]
           B.name = {:first => 'adam', :last => 'phillips'}
 
-          B.locations.must_equal [:east, :west]
-          C.locations.must_equal Array.new
-          B.name.must_equal({:first => 'adam', :last => 'phillips'})
-          C.name.must_equal Hash.new
+          B.locations.should == [:east, :west]
+          C.locations.should == Array.new
+          B.name.should == ({:first => 'adam', :last => 'phillips'})
+          C.name.should == Hash.new
         end
       end
 
       describe "proc properties" do
         it "inherits by default" do
-          @props[:classified][:inherit].must_equal true
+          @props[:classified][:inherit].should == true
         end
 
         it "evaluates the proc in context of each descendent" do
@@ -137,9 +132,9 @@ describe "basics" do
           B.score = 30.1
           C.score = 45.2
 
-          A.classified.must_equal true
-          B.classified.must_equal false
-          C.classified.must_equal true
+          A.classified.should be_true
+          B.classified.should be_false
+          C.classified.should be_true
         end
       end
     end
@@ -152,25 +147,25 @@ describe "basics" do
 
       it "expects two parameters: property_name, ancestors" do
         A.color{|color_a, parents|
-          color_a.must_equal "red"
-          parents.must_equal []
+          color_a.should == "red"
+          parents.should == []
         }
 
         B.color{|color_b, parents|
-          color_b.must_equal "blue"
-          parents.must_equal [A]
+          color_b.should == "blue"
+          parents.should == [A]
         }
 
         C.color{|color_c, parents|
-          color_c.must_equal "purple"
-          parents.must_equal [B, A]
+          color_c.should == "purple"
+          parents.should == [B, A]
         }
       end
 
       it "returns last expression of block" do
-        A.color{|my_color| my_color.reverse}.must_equal "der"
-        B.color{|my_color| my_color.capitalize}.must_equal "Blue"
-        C.color{|my_color| my_color * 2}.must_equal "purplepurple"
+        A.color{|my_color| my_color.reverse}.should == "der"
+        B.color{|my_color| my_color.capitalize}.should == "Blue"
+        C.color{|my_color| my_color * 2}.should == "purplepurple"
       end
     end
 
@@ -182,17 +177,17 @@ describe "basics" do
         end
 
         it "descendents whose property is blank, inherit (invoke) the proc" do
-          B.color.must_equal "Red"
+          B.color.should == "Red"
 
           sec = Time.now.sec
-          B.rank.must_equal sec
-          C.rank.must_equal sec
+          B.rank.should == sec
+          C.rank.should == sec
 
           sleep(2)
 
           sec = Time.now.sec
-          B.rank.must_equal sec
-          C.rank.must_equal sec
+          B.rank.should == sec
+          C.rank.should == sec
         end
       end
     end
@@ -218,13 +213,13 @@ describe "to_hash" do
   end
 
   it "returns hash of property name/values" do
-    A.to_hash.must_equal({:color => "red",
+    A.to_hash.should ==({:color => "red",
                            :name => {:first => 'jon',
                                      :last => 'mackey'}
                          })
   end
 
   it "applies default getter logic: non-container-types inherit, container-types don't" do
-    B.to_hash.must_equal({:color => "red", :name => {}})
+    B.to_hash.should ==({:color => "red", :name => {}})
   end
 end