cascading_classes 0.1.0

data/README.md

@@ -0,0 +1,190 @@
+# CascadingClasses
+
+This library allows you to easily create properties that cascade down a class tree. For example:
+
+    require 'cascading_classes'
+
+    class Parent
+      extend CC
+    end
+
+    class Child < Parent; end
+
+    class GrandChild < Child; end
+
+now create two properties that will cascade down all descendents
+
+    Parent.cascade :eye_color, :hair_color
+
+set the properties on ```Parent```
+
+    Parent.eye_color = "brown"
+    Parent.hair_color = "black"
+
+all child classes are affected
+
+    p Child.eye_color        # => "brown"
+    p GrandChild.eye_color   # => "brown"
+
+    p Child.hair_color       # => "black"
+    p GrandChild.hair_color  # => "black"
+
+now change the ```eye_color``` and ```hair_color``` properties on ```Child```
+
+    Child.eye_color = "blue"     
+    Child.hair_color = "blond"
+
+only descendents of ```Child``` are affected
+
+    p Parent.eye_color       # => "brown"
+    p Child.eye_color        # => "blue"
+    p GrandChild.eye_color   # => "blue"
+
+
+Getting Started
+---------------
+
+Assume the class structure from above:
+
+    class Parent
+      extend CC
+    end
+
+    class Child < Parent; end
+
+    class GrandChild < Child; end
+
+## Setting default values
+
+Setting default values for cascaded properties are easy. The first method is to bracket them in Array pairs. For example:
+
+    Parent.cascade [:eye_color, "hazel"], [:hair_color, "brown"], :has_education
+
+sets the ```eye_color``` and ```hair_color``` properties on ```Parent``` to "hazel" and "brown" and initializes, but does not set, the ```has_education``` property. 
+
+
+### Alternative syntax: all!
+
+You also create cascaded properties via ```Parent.all!```
+
+For example, the following are equivalent:
+
+    Parent.cascade :arms, :legs, :head
+    Parent.all! :arms, :legs, :head
+
+this initiates, but does not set, two cascading properties: ```arms```, ```legs```
+
+    p Parent.arms      # => nil
+    p Child.arms       # => nil
+    p GrandChild.arms  # => nil
+
+since no default was given, all are nil 
+
+Again, to set a default use brackets:
+
+    Parent.all! :arms, [:legs, 2], [:head, :none]
+
+
+### Alternative syntax: block arguments
+
+You can also create cascading properties with a block. The major difference is that you must not prefix your property with a colon. 
+
+For example
+
+    Parent.cascade [:eye_color, "blue"], [:hair_color, "blond"]
+
+is equivalent to
+
+    Parent.cascade do
+      eye_color  :default => "blue"
+      hair_color :default => "blond"
+    end
+    
+or
+
+    Parent.all! do
+      eye_color  :initial => "blue"
+      hair_color :initial => "blond"
+    end
+ 
+#### More block examples
+
+The folowing are all equivalent
+==============================
+
+    Parent.cascade :address, :phone, [:email, "jon@example.com"]
+
+    Parent.cascade :address, :phone do
+      email :initial => "jon@example.com"
+    end
+
+    Parent.all! do
+      address
+      phone
+      email :start => "jon@example.com"
+    end
+
+    Parent.all!{ address; phone; email :default => "jon@example.com" }
+
+You can also set a property in a block using ```set_property```
+
+    Parent.cascade do
+      set_property :address
+      set_property :phone
+      set_property :email, :default => "jon@example.com"
+    end
+
+
+## Quick Summary
+
+* require the gem: ```require cascading_classes```
+* extend or include the module
+    class Foo
+      extend CascadingClasses
+    end
+* CC is equivalent to CascadingClasses
+* create some cascading properties by listing them 
+    A.cascade :desk, :chair, :lamp
+* or by using a block
+    A.cascade{ desk; chair; lamp }
+* get and set the property on any descendent
+    class B < A; end
+    B.desk = "a large, wooden structure in need of a fix"         
+    class C < A; end
+    C.lamp = "old and rusty"
+
+### What's the difference between ```extend CC``` and ```include CC```?
+
+First, in either case you are dealing with class instance variables and class methods. ```A.cascade :eye_color; A.eye_color``` sets ```@eye_color``` on the singleton class of A.
+
+But if you also want the properties to cascade down to instance variables you have three options. The first way is to ```include CC```, which will create cascading instance properties by default.
+
+For example:
+
+    class Parent
+      include CC
+    end
+
+    Parent.cascade [:eye_color, "blue"]
+    p = Parent.new
+    p p.eye_color   # => "blue"
+
+    class Child < Parent; end
+
+    c = Child.new
+    p c.eye_color   # => "blue"
+
+The other two ways to make properties cascade down to instances is via:
+
+    Parent.cascade [:hair_color, "blue", true]
+
+or 
+ 
+    Parent.cascade do
+      hair_color :default => "blue", :instances => true
+    end
+
+In either case, even if you ```extend CC```, all instance variables of all descendents will have the ```hair_color``` property. 
+
+      
+      

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rake'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.pattern = "spec/*_spec.rb"
+end
+

data/lib/cascading_classes/cascading_classes.rb

@@ -0,0 +1,163 @@
+module CascadingClasses
+
+  # based off 
+  # http://blog.oleganza.com/post/115377756/correct-blankslate-in-ruby
+  class BlankSlate 
+    class << self; alias __undef_method undef_method; end
+    keep = [:instance_eval, :object_id]
+    ancestors.inject([]){|res, a| res + (a.instance_methods - keep)}.uniq.
+      each{|m| (__undef_method(m) rescue nil) unless m =~ /^__/ }
+  end
+
+  class Helper < CascadingClasses::BlankSlate 
+
+    def method_missing(meth, *args, &block)
+      case meth
+      when /inspect/
+        super
+      when /set_property/
+        __property__(args[0], *args[1..-1], &block)
+      else
+        __property__(meth, *args, &block)
+      end
+    end
+
+    def __property__(name, args={}, &block)
+      @names << name unless @names.include? name
+
+      @defaults[name] = if args.include? :default
+        args[:default]
+      elsif args.include? :initial
+        args[:initial]
+      elsif args.include? :start
+        args[:start]
+      elsif args.include? :begin
+        args[:begin]
+      else
+        nil
+      end
+
+      @instances_too[name] = if args.include? :classes_only
+        !args[:classes_only]
+      elsif args.include? :only_classes
+        !args[:only_classes]
+      elsif args.include? :classes_only
+        !args[:classes_only] 
+      elsif args.include? :exclude_instances
+        !args[:exclude_instances]
+      elsif args.include? :skip_instances
+        !args[:skip_instances]
+      elsif args.include? :not_instances
+        !args[:not_instances]
+      elsif args.include? :apply_to_instances
+        args[:apply_to_instances]
+      elsif args.include? :both
+        args[:both]
+      elsif args.include? :instances_too
+        args[:instances_too]
+      elsif args.include? :instances
+        args[:instances]
+      elsif args.include? :instance
+        args[:instance]
+      else
+        @apply_to_instances                    
+      end
+    end
+
+    def initialize(apply_to_instances, &block)
+      @apply_to_instances = apply_to_instances
+      @names = []
+      @defaults = {} 
+      @instances_too = {}  # values are true/false
+
+      return unless block_given?
+      if block.arity == 0
+        instance_eval &block
+      else
+        raise "ArgumentError: wrong number of args for block: #{block.arity} for 1"
+      end
+    end
+
+  end  # class Helper
+
+  # returns an array 
+  # apply_to_instances: whether properties should be set on instances of the classes too
+  def self.cascading_props(apply_to_instances, *properties, &block)
+    props = {}  # values are defaults
+    instances_too = {}  # values are true/false
+    properties.each do |prop|
+      if Array === prop and prop.size == 3
+        props[prop[0].to_sym] = prop[1]
+        instances_too[prop[0].to_sym] = !!prop[2]
+      elsif Array === prop and prop.size == 2
+        props[prop[0].to_sym] = prop[1]
+      else
+        props[prop.to_sym] = nil
+      end
+    end
+    
+    props.each{|prop, default| instances_too[prop] =
+      apply_to_instances unless instances_too.include? prop}
+
+    if block_given?
+      a = Helper.new(apply_to_instances, &block)
+      names, defaults, inst =
+        a.instance_eval{ [@names, @defaults, @instances_too] }
+      names.each do |prop|
+        props[prop] = defaults[prop]
+        instances_too[prop] = inst[prop]
+      end
+    end
+
+    props.map do |prop, default|
+      mod = Module.new do
+
+        define_method :extended do |klass|
+          klass.class_eval{ instance_variable_set "@#{prop}", default }
+        end
+        module_function :extended
+
+        define_method :included do |klass|
+          klass.class_eval{ instance_variable_set "@#{prop}", default }
+        end
+        module_function :included
+
+        # getter has dual role as setter:
+        #   m.prop val <=> m.prop = val
+        define_method prop do |*args|
+          if args.empty?  # getter
+            val = instance_variable_get "@#{prop}"
+            if val.nil? 
+              # reach up into the class first, then into superclass
+              if self.class == Class
+                try_super = superclass.instance_eval{ respond_to? "#{prop}" }
+                return superclass.send("#{prop}") if try_super
+              else
+                try_klass_methd = self.class.send :respond_to?, prop
+                return self.class.send(prop) if try_klass_methd
+              end
+            end
+            val
+          else  # setter
+            if args.size == 1 and Array === args[0]
+              send("#{prop}=", args[0])
+            else
+              send("#{prop}=", *args)
+            end
+          end
+        end
+
+        # todo: setter validations ??
+        define_method "#{prop}=" do |*vals|
+          if vals.size == 1 and Array === vals[0]
+            vals = vals[0]
+          end
+          instance_variable_set "@#{prop}", vals[0]
+        end
+
+      end  # new module
+      [prop, props[prop], instances_too[prop], mod]
+    end
+  end
+
+end  # module CascadingClasses

data/lib/cascading_classes.rb

@@ -0,0 +1,75 @@
+require 'cascading_classes/cascading_classes'
+
+CC = CascadingClasses unless defined? CC
+
+# trivialities:
+#   module not meant to be both included and extended
+
+
+# class Foo
+#   include CC
+#   cascade :one, :two, :three, ...
+# end
+# Foo.one = 12
+# Foo.new.one
+# Bar = Class.new(Foo).one
+
+module CascadingClasses
+
+  # VERSION: "1.0.0"
+  # note, VERSION will be undetected unless called directly
+  def self.const_missing(name)
+    case name
+    when :VERSION then "1.0.0"
+    else raise NameError
+    end
+  end
+
+  def respond_to?(const)
+    (const.to_s == 'VERSION') ? true : super
+  end
+  module_function :respond_to?
+
+  def self.included(klass)
+    has_all = klass.instance_methods.include? :all!
+    klass.instance_eval do
+      def cascade(*props, &block)
+        res = CascadingClasses.cascading_props(true, *props, &block)
+        res.map! do |prop, default, apply_to_instances, mod|
+          send(:extend, mod)
+          send(:include, mod) if apply_to_instances
+          [prop, [default, apply_to_instances]]
+        end
+        {self.name => Hash[res]}
+      end
+
+      class << klass
+        unless instance_methods.include? :all!        
+          alias_method :all!, :cascade
+        end
+      end
+    end
+  end
+
+  def self.extended(klass)
+    has_all = klass.instance_methods.include? :all
+    klass.instance_eval do
+      def cascade(*props, &block)
+        res = CascadingClasses.cascading_props(false, *props, &block)
+        res.map! do |prop, default, apply_to_instances, mod|
+          send(:extend, mod)
+          send(:include, mod) if apply_to_instances
+          [prop, [default, apply_to_instances]]
+        end
+        {self.name => Hash[res]}
+      end
+
+      class << klass
+        unless instance_methods.include? :all!        
+          alias_method :all!, :cascade
+        end
+      end
+    end
+  end
+
+end  # module CascadingClases

data/spec/alternative_syntax_spec.rb

@@ -0,0 +1,146 @@
+begin
+  require_relative 'helper_spec'
+rescue NameError
+  require File.expand_path('helper_spec', __FILE__)
+end
+
+describe "when a class extends CascadingClasses and an alternative syntax is used" do
+
+  # this is the same as:
+  #   class Parent
+  #     extend CascadingClasses
+  #   end
+  #
+  #   class Child < Parent; end
+  #
+  #   class GrandChild < Child; end
+  before do
+    Parent = Class.new{extend CC}
+    Child = Class.new(Parent)
+    GrandChild = Class.new(Child)
+  end
+
+  describe "when an alternative syntax is given (0)" do
+    before do
+      Parent.cascade [:hair_color, "black"], :eye_color, [:piercings, false]
+
+      Child.hair_color = "blond"
+      Child.eye_color = "brown"
+    end
+
+    it "should give the same result" do
+      Parent.hair_color.must_equal "black"
+      Child.hair_color.must_equal "blond"
+      GrandChild.hair_color.must_equal "blond" 
+
+      Parent.eye_color.must_equal nil
+      Child.eye_color.must_equal "brown"
+      GrandChild.eye_color.must_equal "brown"
+
+      Parent.piercings.must_equal false
+      Child.piercings.must_equal false
+      GrandChild.piercings.must_equal false
+    end
+  end
+
+  describe "when an alternate syntax is given (1)" do
+    before do
+      Parent.all! [:hair_color, "black"], :eye_color, [:piercings, false]
+
+      Child.hair_color = "blond"
+      Child.eye_color = "brown"
+    end
+
+    it "should give the same result" do
+      Parent.hair_color.must_equal "black"
+      Child.hair_color.must_equal "blond"
+      GrandChild.hair_color.must_equal "blond"    
+
+      Parent.eye_color.must_equal nil
+      Child.eye_color.must_equal "brown"
+      GrandChild.eye_color.must_equal "brown"
+
+      Parent.piercings.must_equal false
+      Child.piercings.must_equal false
+      GrandChild.piercings.must_equal false
+    end
+  end
+
+  describe "when an alternative syntax is given (2)" do
+    before do
+      Parent.cascade :eye_color do
+        hair_color :begin => "black"
+        piercings :initial => false
+      end
+
+      Child.hair_color = "blond"
+      Child.eye_color = "brown"
+    end
+
+    it "should give the same result" do
+      Parent.hair_color.must_equal "black"
+      Child.hair_color.must_equal "blond"
+      GrandChild.hair_color.must_equal "blond"  
+
+      Parent.eye_color.must_equal nil
+      Child.eye_color.must_equal "brown"
+      GrandChild.eye_color.must_equal "brown"
+
+      Parent.piercings.must_equal false
+      Child.piercings.must_equal false
+      GrandChild.piercings.must_equal false
+    end
+  end
+
+  describe "when an alternative syntax is given (3)" do
+    before do
+      Parent.all! :eye_color do
+        hair_color :start => "black"
+        piercings :default => false
+      end
+
+      Child.hair_color = "blond"
+      Child.eye_color = "brown"
+    end
+
+    it "should give the same result" do
+      Parent.hair_color.must_equal "black"
+      Child.hair_color.must_equal "blond"
+      GrandChild.hair_color.must_equal "blond"  
+
+      Parent.eye_color.must_equal nil
+      Child.eye_color.must_equal "brown"
+      GrandChild.eye_color.must_equal "brown"
+
+      Parent.piercings.must_equal false
+      Child.piercings.must_equal false
+      GrandChild.piercings.must_equal false
+    end
+  end
+
+  describe "when an alternative syntax is given (3)" do
+    before do
+      Parent.all! :eye_color do
+        set_property :hair_color, :start => "black"
+        set_property :piercings, :initial => false
+      end      
+
+      Child.hair_color = "blond"
+      Child.eye_color = "brown"
+    end
+
+    it "should give the same result" do
+      Parent.hair_color.must_equal "black"
+      Child.hair_color.must_equal "blond"
+      GrandChild.hair_color.must_equal "blond"  
+
+      Parent.eye_color.must_equal nil
+      Child.eye_color.must_equal "brown"
+      GrandChild.eye_color.must_equal "brown"
+
+      Parent.piercings.must_equal false
+      Child.piercings.must_equal false
+      GrandChild.piercings.must_equal false
+    end
+  end
+end

data/spec/extended_spec.rb

@@ -0,0 +1,133 @@
+begin
+  require_relative 'helper_spec'
+rescue NameError
+  require File.expand_path('helper_spec', __FILE__)
+end
+
+# require 'minitest/autorun'
+# require 'cascading_classes'
+
+# class << MiniTest::Spec
+  # alias_method :all, :it
+# end
+
+describe "when a class extends CascadingClasses" do
+
+  # this is the same as:
+  #   class Parent
+  #     extend CascadingClasses
+  #   end
+  #
+  #   class Child < Parent; end
+  #
+  #   class GrandChild < Child; end
+  before do
+    Parent = Class.new{extend CC}
+    Child = Class.new(Parent)
+    GrandChild = Class.new(Child)
+  end
+
+  describe "when a property is set from above" do
+    before do
+      Parent.cascade(:hair_color)
+
+      Parent.hair_color = :blond
+    end
+
+    it "should cascade down to its descendents" do
+      Parent.hair_color.must_equal :blond
+      Child.hair_color.must_equal :blond
+      GrandChild.hair_color.must_equal :blond
+    end    
+  end
+
+  describe "when a property is set from below" do
+    before do
+      Parent.cascade do
+        arms :default => 2
+        legs :default => 2
+      end
+
+      Child.arms = 3
+      GrandChild.legs = 1
+    end
+
+    all "descendents are influenced and no acestors are affected" do
+      Parent.arms.must_equal 2
+      Child.arms.must_equal 3
+      GrandChild.arms.must_equal 3
+
+      Parent.legs.must_equal 2
+      Child.legs.must_equal 2
+      GrandChild.legs.must_equal 1
+    end
+  end
+
+  describe "when a property has a default and has not been set by any descendent" do
+    before do
+      Parent.cascade [:eye_color, "red"]
+    end
+
+    all "descendents should reflect that default" do
+      Parent.eye_color.must_equal "red"
+      Child.eye_color.must_equal "red"
+      GrandChild.eye_color.must_equal "red"
+    end
+  end
+
+  describe "when a property has no default and has not been set by any ancestor" do
+    before do
+      Parent.cascade :has_house
+    end
+
+    all "descendents should reflect the same" do
+      Parent.has_house.must_equal nil
+      Child.has_house.must_equal nil
+      GrandChild.has_house.must_equal nil
+    end
+  end
+
+  describe "when a child sets a property when its parent has set it too" do
+    before do
+      Parent.all! :trigger
+
+      Parent.trigger = "silent"
+      Child.trigger = "loud"
+    end
+
+    all "cascading is scoped off the youngest child with a set property" do
+      Parent.trigger.must_equal "silent"
+      Child.trigger.must_equal "loud"
+      GrandChild.trigger.must_equal "loud"
+    end
+  end
+
+  describe "when a parent has a property with a default set" do
+    before do
+      ## Parent.cascade{ :time, :default =>  32}
+      Parent.cascade [:time, 32]
+    end
+
+    it "won't matter if the property is first accessed by the child" do
+      Child.time
+
+      Child.time.must_equal 32
+      Parent.time.must_equal 32
+    end    
+  end
+
+  describe "when a parent has a property with a default set" do
+    before do
+      Parent.cascade [:time, 32]
+    end
+
+    it "won't matter if the property is first accessed by the parent" do
+      Parent.time
+  
+      Child.time.must_equal 32
+      Parent.time.must_equal 32
+    end 
+  end
+  
+  
+end

data/spec/included_spec.rb

@@ -0,0 +1,85 @@
+begin
+  require_relative 'helper_spec'
+rescue NameError
+  require File.expand_path('helper_spec', __FILE__)
+end
+
+describe "when CascadingClasses is included by a class" do
+
+
+  # this is the same as:
+  #   class A
+  #     include CascadingClasses
+  #   end
+  #
+  #   class B < A; end
+  #
+  #   class C < B; end
+  #
+  #   a = A.new
+  #   b = B.new
+  #   c = C.new
+  before do
+    A = Class.new{include CC}
+    B = Class.new(A)
+    C = Class.new(B)
+    @a, @b, @c = A.new, B.new, C.new
+  end  
+
+  describe "when CascadingClasses is included in a module" do
+    before do
+    end
+
+    it "must pass all 'extended' test" do
+      # how do you run those tests??
+      file = File.join(File.expand_path(File.dirname(__FILE__)), 'extended_spec.rb')
+      result = `ruby #{file}`
+      result.must_match /(0) failures/
+      result.must_match /(0) errors/
+    end
+  end
+
+  describe "when a property is set on a class" do
+    before do
+      A.all! :once, :twice  # same as A.cascade :once, :twice
+
+      A.once = :thinking
+      B.twice = :speaking
+    end
+
+    all "cascading flows from that class downwards to all child classes and child objects" do
+      # :once
+      A.once.must_equal :thinking
+      @a.once.must_equal :thinking
+      B.once.must_equal :thinking
+      @b.once.must_equal :thinking
+      C.once.must_equal :thinking
+      @c.once.must_equal :thinking
+
+      # :twice
+      A.twice.must_equal nil
+      @a.twice.must_equal nil
+      B.twice.must_equal :speaking
+      @b.twice.must_equal :speaking
+      C.twice.must_equal :speaking
+      @c.twice.must_equal :speaking
+    end
+  end
+
+  describe "when a property is set on an object" do
+    before do
+      A.all! :table
+
+      @a.table = "a large, rectangular object with spotty marks"
+    end
+
+    it "only affects that object" do
+      A.table.must_equal  nil
+      @a.table.must_equal "a large, rectangular object with spotty marks"
+      B.table.must_equal  nil
+      @b.table.must_equal nil
+      C.table.must_equal  nil
+      @c.table.must_equal nil
+    end
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: cascading_classes
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Jeremy Gables
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-08-03 00:00:00.000000000Z
+dependencies: []
+description: 
+email: jeremy.gables@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/cascading_classes.rb
+- lib/cascading_classes/cascading_classes.rb
+- spec/extended_spec.rb
+- spec/included_spec.rb
+- spec/alternative_syntax_spec.rb
+homepage: http://github.com/gables/cascading_classes
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.5
+signing_key: 
+specification_version: 3
+summary: Easily create properties whose values cascade down class trees
+test_files:
+- spec/extended_spec.rb
+- spec/included_spec.rb
+- spec/alternative_syntax_spec.rb