cascading_classes 0.3.0 → 0.6.0

data/Rakefile

@@ -1,7 +1,14 @@
 require 'rake'
 require 'rake/testtask'
 
-Rake::TestTask.new do |t|
-  t.pattern = "spec/*_spec.rb"
+desc "Default Task"
+task :default => :test_all
+
+desc "Run all tests"
+task :test_all => [:test_units]
+
+Rake::TestTask.new("test_units") do |t|
+  t.pattern = "spec/**/*_spec.rb"
+  ## t.test_files = FileList['spec/*
 end
 

data/lib/cascading_classes.rb

@@ -1,97 +1,305 @@
 require 'cascading_classes/cascading_classes'
+require 'cascading_classes/parse_options'
 
 CC = CascadingClasses unless defined? CC
 
-# trivialities:
-#   module not meant to be both included and extended
-
+# todo: add :unset_property functionality
+# todo: allow types to cascade down singleton_class
+#       ie: each subclass could potentially have a different type
+# todo: make parents_for() redundant by keeping track of each child's parents
+# todo: Proc properties: (proc_spec.rb)  B redefines mood/color procs, C.color(:inherit => false)
+#       is this supposed to call C.mood(:inherit => false) too?
 
-# class Foo
-#   include CC
-#   cascade :one, :two, :three, ...
-# end
-# Foo.one = 12
-# Foo.new.one  # => 12
-# Bar = Class.new(Foo).one  # => 12
-# Bar.new.one  # => 12
+# blurb:
+#   module not meant to be both included and extended
 
 module CascadingClasses
 
   # note, VERSION will be undetected unless called directly
   def self.const_missing(name)
     case name
-    when :VERSION then "0.2.0"
+    when :VERSION then "0.4.0"
     else super
     end
   end
 
-  def respond_to?(const)
+  def self.respond_to?(const)
     (const.to_s == 'VERSION') ? true : super
   end
-  module_function :respond_to?
 
-  # todo: fill in rest
+  def self.class_methods
+    [:to_hash, :nearest_parent_for, :top_level_parent_for?]
+  end
+
+  # only applies to desired getter and setter names, not the property itself
   # todo: allow one of [:cascade, :all!] to be overwritten
+  # todo: add :unset_property
   def self.illegal_names
     [:cascade, :all!, :set_property, :instance_eval, :instance_exec,
-     :class_eval]
+     :class_eval].concat(class_methods)
+  end
+
+  # global default: whether proc values are evaluated or instance_exec'd
+  # global default defaults to false
+  def self.proc_inst_exec?
+    @proc_inst_exec.nil? ? @proc_inst_exec = false : @proc_inst_exec
   end
 
+  def self.proc_inst_exec=(val)
+    @proc_inst_exec = !!val
+  end
+
+  # global default: whether blocks are yielded to or instance_exec'd
+  # global default defaults to true
+  def self.block_inst_exec?
+    @block_inst_exec.nil? ? @block_inst_exec = true : @block_inst_exec
+  end
+
+  def self.block_inst_exec=(val)
+    @block_inst_exec = !!val
+  end
+
+  # klass is the class that included/excluded CascadingClasses
   def self.apply(klass, instances_too)
+
+    # cascade method 
     klass.singleton_class.instance_eval do
 
       define_method :cascade do |*props, &block|
         illegal_names = CascadingClasses.illegal_names
 
-        props = CascadingClasses.parse_options(klass, instances_too, *props, &block)
+        props = CascadingClasses.parse_options(instances_too, *props, &block)
         props.each{|prop, v| 
-          default, inst_too, getters, setters = v
-          getters.each{|getter|
+          v[:getters].each{|getter|
             raise NameError, "Illegal property getter: #{getter} for #{prop}" if
               illegal_names.include? getter }
         }
 
-        props.each do |prop, v|
-          default, inst_too, getters, setters = v
+        props.each do |prop, settings|
+          raise "Hell" unless Symbol === prop  # sanity
+          getters, setters = settings[:getters], settings[:setters]
+          getter, setter = getters.first, setters.first
 
-          klass.singleton_class.instance_eval do
-            undef_method prop.to_sym rescue nil
-            undef_method "#{prop}=".to_sym rescue nil
+          # set default value on top level parent
+          me = settings[:ensure_type].call(settings[:default])
+          instance_variable_set("@#{prop}", me)
+
+          slf = self
+          # property metadata saved in singleton class
+          singleton_class.instance_eval do
+            @properties ||= {}
+            @properties.delete prop  # in case it's already there
+            @properties[prop] = settings
+            @properties[prop][:class] = slf
           end
 
-          klass.instance_eval{ instance_variable_set "@#{prop}", default }
+          ## mod = CascadingClasses.cascade_intern(self, prop, settings)
+          mod = CascadingClasses.cascade_intern(prop, settings)
 
-          mod = CascadingClasses.cascade_intern(klass, prop, getters[0], setters[0])
-          klass.extend mod
-          klass.singleton_class.instance_eval do
-            getters[1..-1].each{|getter| alias_method getter, getters[0]} unless
-              getters[0].nil?
-            setters[1..-1].each{|setter| alias_method setter, setters[0]} unless
-              setters[0].nil?
+          self.extend mod
+          singleton_class.instance_eval do
+            getters[1..-1].each{|g| alias_method g, getter} unless getter.nil?
+            setters[1..-1].each{|s| alias_method s, setter} unless setter.nil?
           end
 
-          if inst_too
-            klass.instance_eval do
-              undef_method prop.to_sym rescue nil
-              undef_method "#{prop}=".to_sym rescue nil
-            end
-            klass.send(:include, mod)
-            klass.instance_eval do
-              getters[1..-1].each{|getter| alias_method getter, getters[0]} unless
-                getters[0].nil?
-              setters[1..-1].each{|setter| alias_method setter, setters[0]} unless
-                setters[0].nil?
+          if settings[:instances_too]
+            send(:include, mod)
+            instance_eval do
+              getters[1..-1].each{|g| alias_method g, getter} unless getter.nil?
+              setters[1..-1].each{|s| alias_method s, setter} unless setter.nil?
             end
           end
         end
+      end  
+
+      alias_method(:all!, :cascade) unless instance_methods.include?(:all!)
+    end
+
+    klass_methods = Module.new do
+
+      # whether property was originally defined on self
+      # uses the fact that 'properties' hash can be defined multiple times
+      #   for the same property on the class tree
+      # name: property name
+      # instance: (boolean) whether callee is an instance
+      define_method :top_level_parent_for? do |name, instance=false|
+        return false if instance
+        name = name.to_sym
+        props = singleton_class.properties
+        raise "neither #{self} nor its ancestors have #{name}" unless
+          props and props[name]
+        props2 = superclass.singleton_class.properties rescue nil
+        (props2 and props2[name]) ? false : true
+      end
+
+      # returns array of parents starting (excludes self)
+      #   for property:'name'
+      ### will include self if self is a class
+      # never includes self, even if a class
+      # name: property name
+      # instance: (boolean) whether 'callee' is an instance
+      # always called by a class, not an instance
+      define_method :parents_for do |name, instance=false|
+        return [] if top_level_parent_for?(name, instance) 
+        s = instance ? self : self.superclass
+        res = [s]
+
+        until s.top_level_parent_for?(name)
+          raise "Hell" if s.nil?
+          s = s.superclass
+          res << s
+        end
+        res
+      end
+
+      # differs from 'parents_for' in that it is not
+      # property specific. a property defined on  a
+      # descendent of the top-most class will only
+      # go as high as that descendent in the 'parents_for'.
+      # hence any call to 'parents_for' will be a sub array
+      # of a call to 'ancestor_chain'
+      #
+      # never includes self
+      define_method :ancestor_chain do |instance=false|
+        top_parent = oldest_cascading_class
+        return [] unless top_parent  # todo: raise "Hell" instead
+        ## return [self] if self == top_parent
+        return [] if self == top_parent
+        res = []
+        up = self
+        while up != top_parent
+          res << up unless up == self and instance == false
+          up = up.superclass
+        end
+        res << top_parent
+        res
+      end
+
+      # slightly hackish
+      # todo: propose adding marker variable to top-level class
+      define_method :oldest_cascading_class do 
+        res = singleton_class.instance_variable_get("@properties").nil? ? nil : self
+        tmp = self
+        while tmp = tmp.superclass
+          if s = tmp.singleton_class.instance_variable_get("@properties")
+            res = tmp if Hash === s
+          end
+        end
+        res
+      end
+
+      # calculates number of generations to ancestor
+      #  *eval*  todo: resolve
+      # note: a class is considered one generations away from its instances
+      # todo: explain why not using self.ancestors 
+      # ancestor: class name to take generations from
+      # instance: (boolean) whether 'callee' is an instance
+      # always called by a class, not an instance
+      define_method :generations_from do |ancestor, instance=false|
+        ancestor = eval(ancestor.to_s) if Symbol === ancestor  # *eval*
+        s = self
+        num = instance ? 1 : 0
+
+        while s != ancestor 
+          s = s.superclass
+          raise "NoAncestor" if s.nil?
+          num += 1
+        end
+        num
+      end
+
+      # todo: instances
+      # collects properties and their values
+      # blanks: whether to include values that are blank
+      define_method :to_hash do |blanks=true|
+        s = self.class == Class ? self : self.class
+        ## props = s.singleton_class.properties rescue {}
+        ## return props if props.empty?
+        props = s.singleton_class.properties
+        getters = Hash[ props.map{|name, v| [name, v[:getters].first]} ]
+            
+        res = if blanks
+          props.map{|name, v| [name, s.send(getters[name])] }
+        else
+          prop_names = props.keys.delete_if{|name| send("#{name}_is_blank?") }  
+          prop_names.map{|name| [name, s.send(getters[name])] }
+        end
+        Hash[res]
+      end
+
+      # closest ancestor with a non-blank property
+      # returns nil if there aren't any
+      # name: property name
+      # instance: (boolean) whether 'callee' is an instance
+      # always called by a class, not an instance
+      define_method :youngest_valid_ancestor_for do |name, instance=false|
+        parents = parents_for(name, instance)
+        return nil if parents.empty?
+        parents.each{|ancestor| return ancestor unless
+          ancestor.send("#{name}_is_blank?") }
+        nil
+      end
+
+=begin
+      define_method :youngest_valid_ancestor_for_OLD do |name, instance=false|
+        parents = parents_for(name, instance)
+        return self if parents.empty?
+        parents.each{|ancestor|
+          return ancestor unless ancestor.send("#{name}_is_blank?") }
+        self
+      end
+=end
+
+      # name: property name
+      # instance: (boolean) whether 'callee' is an instance
+      # always called by a class, not an instance
+      define_method :oldest_valid_ancestor_for do |name, instance=false|
+        ## s = self.class == Class ? self : self.class
+        ## props = s.singleton_class.properties
+        props = singleton_class.properties
+        raise "No ancestor of #{self} has #{name}" unless
+          props and props[name.to_sym]
+
+        s = self
+        begin
+          tmp = s.superclass
+          while props2 = tmp.singleton_class.properties and
+                props2[name.to_sym]
+            s = tmp
+            tmp = s.superclass                
+          end
+        rescue NoMethodError          
+        end
+        s
       end
 
-      unless instance_methods.include? :all!
-        alias_method :all!, :cascade
+    end
+    klass.extend klass_methods
+    ## klass.send(:include, klass_and_inst_methods) if instances_too
+
+    klass.singleton_class.instance_eval do
+      @properties ||= {}
+
+      singleton_class.instance_eval do
+        define_method :properties do
+          res = instance_variable_get("@properties") || {}
+          return res if self.superclass == Object.singleton_class
+          up = superclass.send(:properties) rescue {}
+          up.merge(res)
+        end
+
+        define_method :children do
+          @children ||= []
+        end
       end
 
+      define_method :inherited do |subklass|
+        c = self.singleton_class.send(:children)
+        c.delete subklass # if present
+        c << subklass
+      end
     end
-  end
+  end  # self.apply
 
   def self.included(klass)
     apply(klass, true)

data/lib/cascading_classes/cascading_classes.rb

@@ -1,60 +1,214 @@
 require 'cascading_classes/dsl'
+require 'cascading_classes/types'
+require 'set'
+
+# todo: support regexp's natively??
 
 module CascadingClasses
 
-  def self.cascade_intern(klass, property, getter, setter)
-    Module.new do
+  def self.cascade_parse_options(arg1, arg2, opts, settings)
+    r = {}
 
-      if getter
-        define_method getter do
-          val = instance_variable_get "@#{property}"
-          return val unless (val.nil? and self != klass)
-          (self.class == Class) ? superclass.send(getter) :
-            self.class.send(getter)
-        end
+    # ':default' given? -> whether to ignore own value and
+    # return top-level 'default' set in 'cascade' call
+    r[:default] = 
+      if arg1 == :default and (arg2 or arg2 == :undef)
+        true
+      elsif Hash === arg1 and arg1.include?(:default)
+        !!arg1[:default]
+      else
+        false
       end
+    return r if r[:default]
 
-      if setter
-        define_method setter do |v|
-          instance_variable_set "@#{property}", v
-        end
+    r[:proc_inst_exec] = opts.include?(:proc_inst_exec) ?
+      !!opts[:proc_inst_exec] : settings[:proc_inst_exec]
+    r[:block_inst_exec] = opts.include?(:block_inst_exec) ?
+      !!opts[:block_inst_exec] : settings[:block_inst_exec]
+
+    is_container = CascadingClasses.is_container?(settings[:type])
+
+    # inherit_age unless it's given manually
+    r[:inherit_age] = 
+      if settings[:inherit] == :undef 
+        raise "Hell" unless CascadingClasses.undefined_type?(settings[:type])  # sanity
+        -1
+      else
+        settings[:inherit]
       end
 
+=begin      
+    r[:inherit_age] = settings[:inherit]
+    if r[:inherit_age] == :undef and
+        not CascadingClasses.undefined_type?(settings[:type])
+      # only happens in corner case of unknown type 
+      r[:inherit_age] = is_container ? 0 : -1
     end
+=end    
+
+    r[:inherit_age] = 
+      if Hash === arg1 and arg1.include?(:inherit)
+        arg1[:inherit]
+      elsif arg1 == :inherit
+        arg2 == :undef ? -1 : arg2
+      elsif opts.include?(:inherit)
+        opts[:inherit]
+      else
+        (arg1 == :undef) ? r[:inherit_age] : arg1
+      end
+ 
+    r[:inherit_age] = 
+      case r[:inherit_age]
+      when Fixnum then r[:inherit_age]
+      when true then -1
+      when false, nil then 0
+      else
+        raise "inherit_age: #{r[:inherit_age]} must be one of true, false, nil, <fixnum>"
+      end
+
+    r
   end
 
-  # returns hash: {..., attr => [default, inst_too], .. }
-  def self.parse_options(klass, apply_to_instances, *properties, &block)
-    res = {}  
-    properties.each do |prop|
-      name, default, inst_too = prop, nil, apply_to_instances
-      getters, setters = [], []
-      if Array === prop 
-        case prop.size
-        when 0 then next
-        when 1 then name = prop[0]
-        when 2 then name, default = prop[0..1]
+  ## def self.cascade_intern(klass, property, settings)
+  def self.cascade_intern(property, settings)
+    property = property.to_sym
+    Module.new do
+
+      getter, setter = settings[:getters].first, settings[:setters].first
+      raise "Hell" unless getter
+
+      # opts:
+      #   proc_context:      class to evaluate any proc in
+      #   block_inst_exec:   whether to call block (false) or
+      #                      to send block to instance_exec (true)
+      #   proc_inst_exec:    whether to call proc (false) or
+      #                      to convert to a block and send to instance_exec (true)
+      #   inherit:           whether property (if blank) should inherit its value from above
+      #   --->top_most_parent_overall vs top_most_parent_property
+      define_method getter do |arg1=:undef, arg2=:undef, opts={}, &block|
+        is_instance = (self.class == Class) ? false : true
+        klass = is_instance ? self.class : self
+
+        # todo: allow an option to decide which chain to use
+        chain = klass.parents_for(property, is_instance)
+        ## chain = klass.ancestor_chain  # incorrect value for A.new.prop{|val, parents| parents}
+
+        if send("#{property}_is_unset?") and
+             not CascadingClasses.undefined_type?(settings[:type])
+          instance_variable_set "@#{property}", settings[:new].call
+        end
+
+        # parse options
+        r = CascadingClasses.cascade_parse_options(arg1, arg2, opts, settings)
+        proc_inst_exec, block_inst_exec = r[:proc_inst_exec], r[:block_inst_exec]
+        inherit_age = r[:inherit_age] || -1 
+
+        if r[:default]
+          val, is_blank = settings[:default], false
         else
-          name, default, inst_too = prop[0..2]
-          getters = [*prop[3]] if prop.size >= 4
-          setters = [*prop[4]] if prop.size >= 5            
+          val = instance_variable_get "@#{property}"
+          is_blank = send("#{property}_is_blank?")
+        end
+        raise "Hell" if val and CascadingClasses.undefined_type?(settings[:type]) # sanity
+        return nil if CascadingClasses.undefined_type?(settings[:type]) # corner case
+
+        ## cb = settings[:ensure_type]  # callback
+        cb = (settings[:type] == :Proc) ? Proc.new{|v| v} : settings[:ensure_type]
+        if settings[:after_get]
+          cb = Proc.new{|v| cb.call(settings[:after_get].call(v))}
         end
+
+        first_valid_ancestor = is_blank ?
+          klass.youngest_valid_ancestor_for(property, is_instance) : self
+
+        # todo: double-check
+        unless first_valid_ancestor 
+          # there are no valid ancestors (from self) for property
+          raise "Hell" unless
+            klass.top_level_parent_for?(property, is_instance) or is_blank
+
+          me = cb.call(val)
+          return block ? (block_inst_exec ? instance_exec(self, chain, &block) :
+                          block.call(me, chain)) : me
+        end
+
+        ancestor_age = (self == first_valid_ancestor) ? 0 :
+          klass.generations_from(first_valid_ancestor, is_instance)
+        inherit_age = (inherit_age < 0) ? ancestor_age : inherit_age
+
+        if is_blank
+          if ancestor_age > 0 and inherit_age >= ancestor_age
+            if settings[:type] == :Proc and not opts.include?(:proc_context)
+              opts.merge!({:proc_context => self})
+            end
+
+            # fix: hackish
+            up_val = first_valid_ancestor.instance_variable_get "@#{property}"
+            val = (settings[:type] == :Proc or Proc === up_val) ? 
+              up_val : first_valid_ancestor.send(getter, :undef, :undef, opts)
+          end          
+        end
+
+        if is_blank and inherit_age.zero? and settings[:type] == :Proc
+          val = settings[:default]
+        end
+     
+        if Proc === val 
+          val = if opts[:proc_context]
+            opts[:proc_context].instance_exec(self, chain, &val)
+          else
+            opts[:proc_inst_exec] ? instance_exec(self, chain, &val) : 
+              val.call(self, chain)
+          end
+        end
+
+        me = cb.call(val)
+        block ? (block_inst_exec ? instance_exec(me, chain, &block) :
+                 block.call(me, chain)) : me
       end
-      getters = [name.to_sym] if getters.empty?
-      setters = ["#{name}=".to_sym] if setters.empty?
-      inst_too = !!inst_too
-      res[name.to_sym] = [default, inst_too, getters, setters]
-    end
 
-    if block_given?
-      a = CascadingClasses::DSL.new(apply_to_instances, &block)
-      names, defaults, inst, getters, setters =
-        a.instance_eval{ [@names, @defaults, @instances_too, @getters, @setters] }
-      names.each{|name|
-        res[name] = [defaults[name], inst[name], getters[name], setters[name]] }
-    end
+      if setter
+        define_method setter do |v|
+          raise "Hell" if settings[:type] == :NilClass  # sanity
+          if CascadingClasses.undefined_type?(settings[:type])   # or
+            ## settings[:type] == :NilClass
+            if v and v.class.to_s.to_sym != settings[:type]
+              type = settings[:type] = v.class.to_s.to_sym           
+              unless settings[:options_given].include?(:blank)
+                settings[:blank] = CascadingClasses.default_blank(type)
+              end
+              unless settings[:options_given].include?(:new)
+                settings[:new] = CascadingClasses.default_new(type)
+              end
+              unless settings[:options_given].include?(:ensure_type)
+                settings[:ensure_type] =
+                  CascadingClasses.default_ensure_type type,
+                                                       settings[:blank],
+                                                       settings[:new]
+              end
+              unless settings[:options_given].include?(:inherit)
+                settings[:inherit] = CascadingClasses.is_container?(type) ? false : true
+              end
+            end
+          end
+
+          v = settings[:ensure_type].call(v) unless Proc === v
+          instance_variable_set("@#{property}", v)
+        end
 
-    res
+      end
+
+      define_method "#{property}_is_unset?" do
+        not instance_variables.include? "@#{property}".to_sym
+      end
+ 
+      define_method "#{property}_is_blank?" do
+        return true if self.send "#{property}_is_unset?"
+        val = instance_variable_get "@#{property}"
+        Proc === val ? false : settings[:blank].call(val)
+      end
+      
+    end
   end
 
 end  # module CascadingClasses