configurable 0.3.0 → 0.4.0

data/History

@@ -1,3 +1,10 @@
+== 0.4.0 / 2009-03-05
+
+Reworked nesting.  Changes are not backward compatible.
+
+* Nesting syntax reworked
+* Delegates no longer accept nil reader/writers
+
 == 0.3.0 / 2009-02-17
 
 Significant rework of the 0.1.0 release:

data/lib/configurable.rb

@@ -111,18 +111,14 @@ require 'configurable/class_methods'
 #   alt.set_sym('two')
 #   alt.config[:sym]          # => :two
 #
-# Idiosyncratically, true, false, and nil may also be provided as reader/writer
-# options. 
+# Idiosyncratically, true and false may also be provided as reader/writer
+# values.
 #
-#   true     Same as using the defaults, accessors are defined.
-#
-#   false    Sets the default reader/writer but does not define
+# true::     Same as using the defaults, accessors are defined.
+# false::    Sets the default reader/writer but does not define
 #            the accessors (think 'define reader/writer' => false).
 #
-#   nil      Does not define a reader/writer, and does not define
-#            the accessors. In effect this will define a config
-#            that does not map to the instance, but will be
-#            present in instance.config
+# Nil is not allowed as a value.
 #
 # ==== Non-reader/writer attributes
 #

data/lib/configurable/class_methods.rb

@@ -133,223 +133,224 @@ module Configurable
     #     end
     #   end
     #
+    # === Attributes
+    #
+    # Several attributes may be specified to modify how a config is constructed.
+    # Attribute keys should be specified as symbols.
+    #
+    # Attribute::             Description            
+    # reader::                The method used to read the configuration.
+    #                         (default: key)
+    # writer::                The method used to write the configuration
+    #                         (default: "#{key}=")
+    #
+    # Neither attribute may be set to nil, but they may be set to non-default
+    # values.  In that case, config_attr will register the method names as
+    # provided, but it will not define the methods themselves. Specifying true
+    # uses and defines the default methods.  Specifying false uses the default
+    # method name, but does not define the method itself.
+    #
+    # Any additional attributes are registered with the configuration.
     def config_attr(key, value=nil, attributes={}, &block)
       attributes = merge_attributes(block, attributes)
       
-      # define the default public reader method
-      reader = attributes.delete(:reader)
-
-      case reader
-      when true
-        reader = key
-        attr_reader(key) 
-        public(key)
-      when false
-        reader = key
+      # define the reader
+      reader = define_attribute_method(:reader, attributes, key) do |attribute|
+        attr_reader(attribute) 
+        public(attribute)
       end
-
-      # define the default public writer method
-      writer = attributes.delete(:writer)
-
-      if block_given? && writer != true
+      
+      # define the writer
+      if block_given? && attributes[:writer] != true
         raise ArgumentError, "a block may not be specified without writer == true"
       end
-
-      case writer
-      when true
-        writer = "#{key}="
-        block_given? ? define_method(writer, &block) : attr_writer(key)
-        public writer
-      when false
-        writer = "#{key}="
+      
+      writer = define_attribute_method(:writer, attributes, "#{key}=") do |attribute|
+        block_given? ? define_method(attribute, &block) : attr_writer(key)
+        public(attribute)
       end
-  
+      
       configurations[key] = Delegate.new(reader, writer, value, attributes)
     end
-
-    # Adds a configuration to self accessing the configurations for the
-    # configurable class.  Unlike config_attr and config, nest does not
-    # create accessors; the configurations must be accessed through
-    # the instance config method.
+    
+    # Adds nested configurations to self.  Nest creates a new configurable
+    # class using the block, and provides accessors to an instance of the
+    # new class.  Everything is set up so you can access configs through
+    # the instance or through config.
     #
     #   class A
     #     include Configurable
-    #     config :key, 'value'
     #
-    #     def initialize(overrides={})
-    #       initialize_config(overrides)
+    #     config :key, 'one'
+    #     nest :nest do
+    #       config :key, 'two'
     #     end
     #   end
     #
-    #   class B
-    #     include Configurable
-    #     nest :a, A
+    #   a = A.new
+    #   a.key                     # => 'one'
+    #   a.config[:key]            # => 'one'
     #
-    #     def initialize(overrides={})
-    #       initialize_config(overrides)
-    #     end
-    #   end
+    #   a.nest.key                # => 'two'
+    #   a.config[:nest][:key]     # => 'two'
+    # 
+    #   a.nest.key = 'TWO'
+    #   a.config[:nest][:key]     # => 'TWO'
     #
-    #   b = B.new
-    #   b.config[:a]                   # => {:key => 'value'}
+    #   a.config[:nest][:key] = 2
+    #   a.nest.key                # => 2
     #
-    # Nest may be provided a block which initializes an instance of
-    # configurable_class.  In this case accessors for the instance
-    # are created and access becomes quite natural.
+    #   a.config.to_hash          # => {:key => 'one', :nest => {:key => 2}}
+    #   a.nest.config.to_hash     # => {:key => 2}
+    #   a.nest.class              # => A::Nest
     #
-    #   class C
+    # An existing configurable class may be provided instead of using the block
+    # to define a new configurable class.  Recursive nesting is supported.
+    #
+    #   class B
     #     include Configurable
-    #     nest(:a, A) {|overrides| A.new(overrides) }
     #
-    #     def initialize(overrides={})
-    #       initialize_config(overrides)
+    #     config :key, 1, &c.integer
+    #     nest :nest do 
+    #       config :key, 2, &c.integer
+    #       nest :nest do
+    #         config :key, 3, &c.integer
+    #       end
     #     end
     #   end
     #
-    #   c = C.new
-    #   c.a.key                        # => "value"
-    #
-    #   c.a.key = "one"
-    #   c.config[:a].to_hash           # => {:key => 'one'}
-    #
-    #   c.config[:a][:key] = 'two'
-    #   c.a.key                        # => "two"
-    #
-    #   c.config[:a] = {:key => 'three'}
-    #   c.a.key                        # => "three"
-    #
-    # The initialize block executes in class context, much like config.
-    #
-    #   # An equivalent class to illustrate class-context
-    #   class EquivalentClass
-    #     attr_reader :a, A
-    #
-    #     INITIALIZE_BLOCK = lambda {|overrides| A.new(overrides) }
-    #
-    #     def initialize(overrides={})
-    #       @a = INITIALIZE_BLOCK.call(overrides[:a] || {})
-    #     end
+    #   class C
+    #     include Configurable
+    #     nest :a, A
+    #     nest :b, B
     #   end
     #
-    # Nest checks for recursive nesting and raises an error if a recursive nest
-    # is detected.
-    #
-    # ==== Attributes
-    #
-    # Nesting with an initialization block creates the public accessor for the
-    # instance, private methods to read and write the instance configurations,
-    # and a private method to initialize the instance. The default names
-    # for these methods are listed with the attributes to override them:
-    #
-    #   :instance_reader         key
-    #   :instance_writer         "#{key}="
-    #   :instance_initializer    "#{key}_initialize"
-    #   :reader                  "#{key}_config_reader"
-    #   :writer                  "#{key}_config_writer"
-    #
-    # These attributes are ignored if no block is given; true/false/nil
-    # values are meaningless and will be treated as the default.
-    #
-    def nest(key, configurable_class, attributes={}, &block)
+    #   c = C.new
+    #   c.b.key = 7
+    #   c.b.nest.key = "8"
+    #   c.config[:b][:nest][:nest][:key] = "9"
+    #
+    #   c.config.to_hash
+    #   # => {
+    #   # :a => {
+    #   #   :key => 'one',
+    #   #   :nest => {:key => 'two'}
+    #   # },
+    #   # :b => {
+    #   #   :key => 7,
+    #   #   :nest => {
+    #   #     :key => 8,
+    #   #     :nest => {:key => 9}
+    #   #   }
+    #   # }}
+    #
+    # === Attributes
+    #
+    # Nest provides a number of attributes that can modify how a nest is
+    # constructed.  Attribute keys should be specified as symbols.
+    #
+    # Attribute::             Description            
+    # const_name::            Determines the constant name of the configurable
+    #                         class within the nesting class.  May be nil.
+    #                         (default: key.to_s.capitalize)
+    # instance_reader::       The method accessing the nested instance. (default: key)
+    # instance_writer::       The method to set the nested instance. (default: "#{key}=")
+    # instance_initializer::  The method that initializes the instance.
+    #                         (default: "initialize_#{key}")
+    # reader::                The method used to read the instance configuration.
+    #                         (default: "#{key}_config_reader")
+    # writer::                The method used to initialize or reconfigure the
+    #                         instance. (default: "#{key}_config_writer")
+    #
+    # Except for const_name, these attributes are used to define methods
+    # required for nesting to work properly.  None of the method attributes may
+    # be set to nil, but they may be set to non-default values.  In that case,
+    # nest will register the method names as provided, but it will not define
+    # the methods themselves.  The user must define methods with the following
+    # functionality:
+    #
+    # Attribute::             Function          
+    # instance_reader::       Returns the instance of the configurable class
+    # instance_writer::       Inputs and sets the instance of the configurable class
+    # instance_initializer::  Receives the initial config and return an instance of
+    #                         configurable class
+    # reader::                Returns instance.config
+    # writer::                Reconfigures instance using the input overrides,
+    #                         or uses instance_initializer and instance_writer to
+    #                         initialize and set the instance.
+    #
+    # Methods can be public or otherwise.  Specifying true uses and defines the
+    # default methods.  Specifying false uses the default method name, but does
+    # not define the method itself.
+    #
+    # Any additional attributes are registered with the configuration.
+    def nest(key, configurable_class=nil, attributes={}, &block)
       attributes = merge_attributes(block, attributes)
+      attributes = {
+        :instance_reader => true,
+        :instance_writer => true,
+        :initializer => true
+      }.merge(attributes)
       
-      if block_given?
-        instance_variable = "@#{key}".to_sym
-        nest_attr(key, configurable_class, attributes) do |input|
-          instance_variable_set(instance_variable, yield(input))
-        end
+      # define the nested configurable
+      if configurable_class
+        raise "a block is not allowed when a configurable class is specified" if block_given?
       else
-        nest_attr(key, configurable_class, attributes)
+        configurable_class = Class.new { include Configurable }
+        configurable_class.class_eval(&block) if block_given?
       end
-    end  
-    
-    # Same as nest, except the initialize block executes in instance-context.
-    #
-    #   class C
-    #     include Configurable
-    #     nest(:a, A) {|overrides| A.new(overrides) }
-    #
-    #     def initialize(overrides={})
-    #       initialize_config(overrides)
-    #     end
-    #   end
-    #
-    #   # An equivalent class to illustrate instance-context
-    #   class EquivalentClass
-    #     attr_reader :a, A
-    #
-    #     def a_initialize(overrides)
-    #       A.new(overrides)
-    #     end
-    #
-    #     def initialize(overrides={})
-    #       @a = send(:a_initialize, overrides[:a] || {})
-    #     end
-    #   end
-    #
-    def nest_attr(key, configurable_class, attributes={}, &block)
-      unless configurable_class.kind_of?(Configurable::ClassMethods)
-        raise ArgumentError, "not a Configurable class: #{configurable_class}" 
+      
+      # set the new constant
+      const_name = if attributes.has_key?(:const_name) 
+        attributes.delete(:const_name) 
+      else
+        key.to_s.capitalize
       end
+      const_set(const_name, configurable_class) if const_name
       
-      attributes = merge_attributes(block, attributes)
+      # define instance reader
+      instance_reader = define_attribute_method(:instance_reader, attributes, key) do |attribute|
+        attr_reader(key)
+        public(key)
+      end
+      
+      # define instance writer
+      instance_writer = define_attribute_method(:instance_writer, attributes, "#{key}=") do |attribute|
+        attr_writer(key)
+        public(attribute)
+      end
       
-      # add some tracking attributes
-      attributes[:receiver] ||= configurable_class
+      # define initializer
+      initializer = define_attribute_method(:initializer, attributes, "initialize_#{key}") do |attribute|
+        define_method(attribute) {|config| configurable_class.new.reconfigure(config) }
+        private(attribute)
+      end
       
-      # remove method attributes
-      instance_reader = attributes.delete(:instance_reader)
-      instance_writer = attributes.delete(:instance_writer)
-      initializer = attributes.delete(:instance_initializer)
-      reader = attributes.delete(:reader)
-      writer = attributes.delete(:writer)
+      # define the reader
+      reader = define_attribute_method(:reader, attributes, "#{key}_config_reader") do |attribute|
+        define_method(attribute) { send(instance_reader).config }
+        private(attribute)
+      end
       
-      if block_given?
-        # define instance accessor methods
-        instance_reader = boolean_select(instance_reader, key)
-        instance_writer = boolean_select(instance_writer, "#{key}=")
-        instance_var = "@#{instance_reader}".to_sym
-        
-        initializer = boolean_select(reader, "#{key}_initialize")
-        reader = boolean_select(reader, "#{key}_config_reader")
-        writer = boolean_select(writer, "#{key}_config_writer")
-        
-        # the public accessor
-        attr_reader instance_reader
-        
-        define_method(instance_writer) do |value|
-          instance_variable_set(instance_var, value)
-        end
-        public(instance_reader, instance_writer)
-        
-        # the initializer
-        define_method(initializer, &block)
-
-        # the reader returns the config for the instance
-        define_method(reader) do
-          instance_variable_get(instance_var).config
-        end
-  
-        # the writer initializes the instance if necessary,
-        # or reconfigures the instance if it already exists
-        define_method(writer) do |value|
-          if instance_variable_defined?(instance_var) 
-            instance_variable_get(instance_var).reconfigure(value)
+      # define the writer
+      writer = define_attribute_method(:writer, attributes, "#{key}_config_writer") do |attribute|
+        define_method(attribute) do |value|
+          if instance = send(instance_reader)
+            instance.reconfigure(value)
           else
-            instance_variable_set(instance_var, send(initializer, value))
+            send(instance_writer, send(initializer, value))
           end
         end
-        private(reader, writer)
-      else
-        reader = writer = nil
+        private(attribute)
       end
       
-      value = DelegateHash.new(configurable_class.configurations)
-      configurations[key] = Delegate.new(reader, writer, value, attributes)
-  
+      # define the configuration
+      nested_config = DelegateHash.new(configurable_class.configurations)
+      configurations[key] = Delegate.new(reader, writer, nested_config, attributes)
+      
       check_infinite_nest(configurable_class.configurations)
-    end
-
+    end  
+    
     # Alias for Validation
     def c
       Validation
@@ -357,13 +358,30 @@ module Configurable
 
     private
     
-    # a helper to select a value or the default, if the default is true,
-    # false, or nil.  used by nest_attr to handle attributes
-    def boolean_select(value, default) # :nodoc:
-      case value
-      when true, false, nil then default
-      else value
+    # a helper to define methods that may be overridden in attributes.
+    # yields the default to the block if the default is supposed to
+    # be defined.  returns the symbolized method name.
+    def define_attribute_method(name, attributes, default) # :nodoc:
+      attribute = attributes.delete(name)
+      
+      case attribute
+      when true
+        # true means use the default and define the method
+        attribute = default
+        yield(attribute)
+        
+      when false
+        # false means use the default, but let the user define the method
+        attribute = default
+        
+      when nil
+        # nil is not allowed
+        raise "#{name.inspect} attribute cannot be nil"
       end
+      # ... all other values specify what the method should be,
+      # and lets the user define the method.
+
+      attribute.to_sym
     end
     
     # a helper to initialize configurations for the first time,

data/lib/configurable/delegate.rb

@@ -27,8 +27,7 @@ module Configurable
     # line, in a web form, or a desktop app).
     attr_reader :attributes
 
-    # Initializes a new Delegate with the specified key 
-    # and default value.
+    # Initializes a new Delegate with the specified key and default value.
     def initialize(reader, writer="#{reader}=", default=nil, attributes={})
       self.default = default
       self.reader = reader
@@ -61,16 +60,16 @@ module Configurable
       duplicate && @duplicable ? @default.dup : @default
     end
 
-    # Sets the reader for self.  The reader is symbolized,
-    # but may also be set to nil.
+    # Sets the reader for self.
     def reader=(value)
-      @reader = value == nil ? value : value.to_sym
+      raise ArgumentError, "reader may not be nil" if value == nil
+      @reader = value.to_sym
     end
 
-    # Sets the writer for self.  The writer is symbolized,
-    # but may also be set to nil.
+    # Sets the writer for self.
     def writer=(value)
-      @writer = value == nil ? value : value.to_sym
+      raise ArgumentError, "writer may not be nil" if value == nil
+      @writer = value.to_sym
     end
     
     # Returns true if the default value is a kind of DelegateHash.

data/lib/configurable/delegate_hash.rb

@@ -58,8 +58,8 @@ module Configurable
     end
 
     # Binds self to the specified receiver.  Delegate values are removed from
-    # store and sent to their writer method on receiver.  If the store has no
-    # value for a delegate key, the delegate default value will be used.
+    # store and sent to their writer on receiver.  If the store has no value
+    # for a delegate key, the delegate default value will be used.
     def bind(receiver)
       raise ArgumentError, "receiver cannot be nil" if receiver == nil
       
@@ -89,15 +89,15 @@ module Configurable
       self
     end
 
-    # Retrieves the value corresponding to the key.  When bound, delegates with
-    # readers pull values from the receiver; otherwise the value in store will
-    # be returned.  When unbound, if the store has no value for a delegate, the
-    # delgate default value will be returned.
+    # Retrieves the value corresponding to the key.  When bound, delegates pull
+    # values from the receiver using the delegate.reader method; otherwise the
+    # value in store will be returned.  When unbound, if the store has no value
+    # for a delegate, the delgate default value will be returned.
     def [](key)
       return store[key] unless delegate = delegates[key]
       
       case
-      when bound? && delegate.reader
+      when bound?
         receiver.send(delegate.reader)
       when store.has_key?(key)
         store[key]
@@ -106,17 +106,15 @@ module Configurable
       end
     end
 
-    # Stores a value for the key.  When bound, delegates with writers send the
-    # value to the receiver; otherwise values are stored in store.
+    # Stores a value for the key.  When bound, delegates set the value in the
+    # receiver using the delegate.writer method; otherwise values are stored in
+    # store.
     def []=(key, value)
       if bound? && delegate = delegates[key]
-        if delegate.writer
-          receiver.send(delegate.writer, value)
-          return
-        end
+        receiver.send(delegate.writer, value)
+      else
+        store[key] = value
       end
-      
-      store[key] = value
     end
     
     # Returns the union of delegate and store keys.
@@ -181,8 +179,6 @@ module Configurable
     # helper to map delegate values from source to the receiver
     def map(source) # :nodoc:
       delegates.each_pair do |key, delegate|
-        next unless writer = delegate.writer
-        
         # map the value; if no value is set in the source then use the 
         # delegate default.  if map_default is false, then simply skip... 
         # this ensures each config is initialized to a value when bound
@@ -193,15 +189,14 @@ module Configurable
         else next
         end
         
-        receiver.send(writer, value)
+        receiver.send(delegate.writer, value)
       end
     end
     
     # helper to unmap delegates from the receiver to a target hash
     def unmap(target) # :nodoc:
       delegates.each_pair do |key, delegate|
-        next unless reader = delegate.reader
-        target[key] = receiver.send(reader)
+        target[key] = receiver.send(delegate.reader)
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: configurable
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Simon Chiang
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-02-17 00:00:00 -07:00
+date: 2009-03-05 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency