configtoolkit 2.1.0 → 2.2.0

data/FAQ.txt

@@ -170,3 +170,25 @@ I realize that this is an unsatisfactory solution and have it on the
 +configtoolkit+ TODO list (see README.txt) to craft a better one (one that
 does not require patching rdoc).  If this is particularly important to you,
 please let me know so that I can prioritize this work.
+
+=== How can I override the contents of one configuration file with the contents of another?
+One common pattern in UNIX applications is to have a system-wide configuration
+file in /etc and to allow users to override the system-wide settings with
+a configuration file in their home directories.  The
+ConfigToolkit::OverrideReader supports this by allowing the contents of
+one configuration file to override those of another (the files even can be 
+different formats).  See Override.txt for more details.
+
+=== Configuration files are great, but how can I populate a configuration from the command-line?
+The ConfigToolkit currently does not support sourcing configuration from the
+command-line directly.  This is an enhancement that we are
+investigating, however, so if you think it desirable, please let us know so
+that we can prioritize it appropriately.
+
+In the meantime, configuration classes still can be populated with command-line
+arguments.  The easiest way to do this is to populate a Hash with the arguments
+and, after reading all the command-line options, to use the
+ConfigToolkit::HashReader to load the Hash into a configuration instance.
+If the application also sources configuration from a file, the 
+ConfigToolkit::OverrideReader allows configuration to be sourced from more
+than one source.

data/Hash.txt

@@ -125,4 +125,4 @@ When run, the program produces:
  }
  
  The Hash dumped from the second config:
- {:production=>{:www=>{:addresses=>[#<URI::HTTP:0xb7e8b018 URL:http://www.designingpatterns.com>, #<URI::HTTP:0xb7e8aed8 URL:http://tokyo.designingpatterns.com>], :num_cpus=>64, :os=>{:version=>10.0, :name=>"Solaris"}, :behind_firewall=>true, :contains_sensitive_data=>true}}}
+ {:production=>{:www=>{:addresses=>[#<URI::HTTP:0xb7e6046c URL:http://www.designingpatterns.com>, #<URI::HTTP:0xb7e60408 URL:http://tokyo.designingpatterns.com>], :num_cpus=>64, :os=>{:version=>10.0, :name=>"Solaris"}, :behind_firewall=>true, :contains_sensitive_data=>true}}}

data/History.txt

@@ -1,3 +1,9 @@
+=== 2.2.0 / 2008-07-29 
+* Add support for overriding configurations through the
+  ConfigToolkit::OverrideReader, allowing the contents of one configuration file
+  to override the contents of another configuration file.  See Override.txt
+  for more details.
+
 === 2.1.0 / 2008-07-25
 * Small documentation enhancements
 * Add a patch for properly documenting configuration parameters for rdoc

data/Manifest.txt

@@ -4,6 +4,7 @@ History.txt
 FAQ.txt
 Hash.txt
 KeyValue.txt
+Override.txt
 README.txt
 Ruby.txt
 YAML.txt
@@ -13,11 +14,15 @@ examples/key_value_example.rb
 examples/load_example.rb
 examples/load_group_example.rb
 examples/machineconfig.rb
+examples/override_example_1.rb
+examples/override_example_2.rb
 examples/ruby_example.rb
 examples/usage_example.rb
 examples/yaml_example.rb
 examples/load_example.yaml
 examples/load_group_example.yaml
+examples/override_example_override.yaml
+examples/override_example.yaml
 examples/yaml_example.dump.yaml
 examples/yaml_example.yaml
 examples/key_value_example.dump.cfg
@@ -33,6 +38,7 @@ lib/configtoolkit/hashwriter.rb
 lib/configtoolkit/keyvalueconfig.rb
 lib/configtoolkit/keyvaluereader.rb
 lib/configtoolkit/keyvaluewriter.rb
+lib/configtoolkit/overridereader.rb
 lib/configtoolkit/prettyprintwriter.rb
 lib/configtoolkit/reader.rb
 lib/configtoolkit/rubyreader.rb
@@ -46,6 +52,7 @@ test/readerwritertest.rb
 test/test_baseconfig.rb
 test/test_hash.rb
 test/test_keyvalue.rb
+test/test_override.rb
 test/test_prettyprint.rb
 test/test_ruby.rb
 test/test_yaml.rb
@@ -53,6 +60,8 @@ test/bad_config.yaml
 test/contained_sample.yaml
 test/firewall.yaml
 test/machines.yaml
+test/override_sample_1.yaml
+test/override_sample_2.yaml
 test/sample.ruby_yaml_classes.yaml
 test/sample.standard_yaml_classes.yaml
 test/webserver.yaml

data/Override.txt

@@ -0,0 +1,249 @@
+== OVERRIDE CONFIGURATION FILES: 
+Do you find yourself needing to override specific configuration
+parameters in your configuration?  For example, does your application
+require a configuration file and also allow the user to override
+configuration parameters via the command line or a per-user
+configuration file?  Do you want to postpone validating this
+configuration until after the override has been performed?  The
+ConfigToolkit::OverrideReader allows you to override a Reader instance
+with other Reader instance(s).  Validation is performed by your custom
+config class (derived from ConfigToolkit::BaseConfig) after the
+override has been performed.
+
+For more specific details see the ConfigToolkit::OverrideReader class.
+
+== EXAMPLE: 
+
+Following are two YAML configurations that will be passed to the
+override reader.  Configuration in the second file will override that
+of the first.
+======+examples/override_example.yaml+:
+ #
+ # This file contains MachineConfig configurations
+ # (see examples/machineconfig.rb for the configuration's specification).
+ #
+ 
+ num_cpus: 32
+ os:
+   name: AIX
+   version: 5.3
+ behind_firewall: no
+ contains_sensitive_data: no
+ addresses:
+   - http://default.designingpatterns.com
+   - http://apple.designingpatterns.com
+
+======+examples/override_example_override.yaml+:
+ #
+ # This file contains a subset of a MachineConfig configuration and
+ # is meant to be an override of the MachineConfig specified in 
+ # examples/override_example.yaml.
+ #
+ 
+ num_cpus: 64
+ os:
+   version: 5.4
+
+This is the program that reads the two above configurations and performs the override.
+======+examples/override_example_1.rb+:
+ #!/usr/bin/env ruby
+ 
+ #
+ # These example programs use the 'relative' gem in order to
+ # express paths relative to __FILE__ cleanly, allowing them to be run from
+ # any directory.  In particular, they use the require_relative
+ # method to load examples/machineconfig.rb and
+ # File.expand_path_relative_to_caller in order to refer to
+ # configuration files within the examples directory.
+ #
+ 
+ require 'rubygems'
+ require 'relative'
+ require_relative 'machineconfig'
+ 
+ require 'configtoolkit/yamlreader'
+ require 'configtoolkit/overridereader'
+ 
+ CONFIGURATION_FILE = File.expand_path_relative_to_caller("override_example.yaml")
+ OVERRIDE_FILE = File.expand_path_relative_to_caller("override_example_override.yaml")
+ 
+ reader = ConfigToolkit::OverrideReader.new(ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE),
+                                            ConfigToolkit::YAMLReader.new(OVERRIDE_FILE))
+ 
+ # Let's load the overriden configuration.
+ config = MachineConfig.load(reader)
+ print("The config:\n#{config}\n")
+
+When run, it produces the following output:
+======The output of <code>examples/override_example_1.rb</code>:
+ The config:
+ {
+     os                     : {
+         version: 5.4
+         name   : AIX
+     }
+     behind_firewall        : false
+     num_cpus               : 64
+     addresses              : [
+         http://default.designingpatterns.com,
+         http://apple.designingpatterns.com
+     ]
+     contains_sensitive_data: false
+ }
+ 
+
+
+In the following example, a machine configuration will be added to a
+list of machine configurations via the ConfigToolkit::OverrideReader.
+
+The following YAML configuration specifies a list of machine
+configurations (+db1+, +db2+, ..).
+======+examples/load_group_example.yaml+:
+ #
+ # This file contains MachineConfig configurations
+ # (see examples/machineconfig.rb for the configuration's specification).
+ #
+ 
+ db_cluster:
+   db1:
+     num_cpus: 16
+     os:
+       name: Solaris
+       version: 10.0
+     contains_sensitive_data: yes
+     behind_firewall: yes
+     addresses:
+       - http://db1.designingpatterns.com
+   db2:
+     num_cpus: 12
+     os:
+       name: AIX
+       version: 5.3
+     contains_sensitive_data: yes
+     behind_firewall: yes
+     addresses:
+       - http://db2.designingpatterns.com
+   db3:
+     num_cpus: 24
+     os:
+       name: Solaris
+       version: 10.0
+     contains_sensitive_data: yes
+     behind_firewall: yes
+     addresses:
+       - http://db3.designingpatterns.com
+
+
+This program specifies a MachineConfig via HashReader and adds it to
+the list of MachineConfig configurations specified in the YAML file
+above.
+
+======+examples/override_example_2.rb+:
+ #!/usr/bin/env ruby
+ 
+ #
+ # These example programs use the 'relative' gem in order to
+ # express paths relative to __FILE__ cleanly, allowing them to be run from
+ # any directory.  In particular, they use the require_relative
+ # method to load examples/machineconfig.rb and
+ # File.expand_path_relative_to_caller in order to refer to
+ # configuration files within the examples directory.
+ #
+ require 'rubygems'
+ require 'relative'
+ require_relative 'machineconfig'
+ 
+ require 'configtoolkit/yamlreader'
+ require 'configtoolkit/hashreader'
+ require 'configtoolkit/overridereader'
+ 
+ CONFIGURATION_FILE = 
+   File.expand_path_relative_to_caller("load_group_example.yaml")
+ 
+ hash_configuration = {
+   "db_cluster" => { 
+     "db4" => {
+       "num_cpus" =>  48,
+       "os" => {
+         "name" => "Solaris",
+         "version" => 10.0
+       },
+       "contains_sensitive_data" => "yes",
+       "behind_firewall" => "yes",
+       "addresses" => [ "http://db4.designingpatterns.com" ]
+     }
+   }
+ }
+     
+ #
+ # The group of configurations is under the db_cluster containing
+ # object name.
+ #
+ reader = ConfigToolkit::OverrideReader.new(ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE),
+                                            ConfigToolkit::HashReader.new(hash_configuration))
+ 
+ configs = MachineConfig.load_group(reader, "db_cluster")
+ configs.each do |name, config|
+   print "The #{name} configuration:\n#{config}\n"
+ end
+ 
+
+When run, it produces the following output:
+======The output of <code>examples/override_example_2.rb</code>:
+ The db3 configuration:
+ db_cluster.db3: {
+     num_cpus               : 24
+     addresses              : [
+         http://db3.designingpatterns.com
+     ]
+     contains_sensitive_data: true
+     os                     : {
+         version: 10.0
+         name   : Solaris
+     }
+     behind_firewall        : true
+ }
+ 
+ The db4 configuration:
+ db_cluster.db4: {
+     num_cpus               : 48
+     addresses              : [
+         http://db4.designingpatterns.com
+     ]
+     contains_sensitive_data: true
+     os                     : {
+         version: 10.0
+         name   : Solaris
+     }
+     behind_firewall        : true
+ }
+ 
+ The db1 configuration:
+ db_cluster.db1: {
+     num_cpus               : 16
+     addresses              : [
+         http://db1.designingpatterns.com
+     ]
+     contains_sensitive_data: true
+     os                     : {
+         version: 10.0
+         name   : Solaris
+     }
+     behind_firewall        : true
+ }
+ 
+ The db2 configuration:
+ db_cluster.db2: {
+     num_cpus               : 12
+     addresses              : [
+         http://db2.designingpatterns.com
+     ]
+     contains_sensitive_data: true
+     os                     : {
+         version: 5.3
+         name   : AIX
+     }
+     behind_firewall        : true
+ }
+ 
+

data/README.txt

@@ -20,6 +20,9 @@ robust and easy!  It:
 * Provides classes that can load from (parse) and dump to YAML and key-value
   configuration files.
 * Provides classes that can load from and dump to Hashes.
+* Provides a class that allows the contents of one configuration source to
+  override the contents of another (this works with configuration files of any
+  format or Hashes).
 * Is very extensible, allowing the engine to be used with custom format
   configuration files and with custom data validation rules.
 
@@ -81,6 +84,9 @@ robust and easy!  It:
 * The ConfigToolkit::KeyValueReader and ConfigToolkit::KeyValueWriter classes
   can be configured to work with many different formats of key-value
   configuration files (via ConfigToolkit::KeyValueConfig).
+* A reader class to source one configuration from multiple configuration files,
+  allowing one configuration file to override another
+  (ConfigToolkit::OverrideReader)
 * The ConfigToolkit includes a full unit testing suite.
 * The ConfigToolkit code has detailed comments.
 * The ConfigToolkit code has many example programs (in the +examples+
@@ -605,7 +611,11 @@ When run, it produces:
 * YAML.txt describes working with YAML configuration files.
 * KeyValue.txt describes working with key-value configuration files.
 * Ruby.txt describes working with Ruby configuration files.
-* Hash.txt describes loading configurations from Hashes and dumping configurations to Hashes.
+* Hash.txt describes loading configurations from Hashes and dumping
+  configurations to Hashes.
+* Override.txt describes loading configurations from multiple sources (files),
+  allowing the configuration from one source to override that from another
+  source.
 
 === NEW FORMATS:
 The ConfigToolkit easily can be extended to support new file formats.  A new
@@ -673,8 +683,6 @@ Here are some *possible* ideas:
   any format) containing embedded Ruby (+EmbeddedRubyReader+ class, which
   would process the embedded Ruby and then hand the resulting file off
   to another reader class)
-* Provide support for sourcing configuration from multiple sources (i.e., first
-  source from a file and then from the command-line).
 * Allow more powerful parameter specifications to be specified.  For instance,
   it would be nice if users could specify that the parameter is a Pathname
   to a readable file.  Possibly the ConfigToolkit should provide a Rules

data/Rakefile

@@ -3,7 +3,7 @@
 require 'rubygems'
 require 'hoe'
 
-Hoe.new('configtoolkit', "2.1.0") do |p|
+Hoe.new('configtoolkit', "2.2.0") do |p|
   p.extra_deps << ['relative', '>= 1.0.0']
   p.extra_deps << ['assertions', '>= 1.0.0']
   p.remote_rdoc_dir = ''

data/examples/override_example.yaml

@@ -0,0 +1,14 @@
+#
+# This file contains MachineConfig configurations
+# (see examples/machineconfig.rb for the configuration's specification).
+#
+
+num_cpus: 32
+os:
+  name: AIX
+  version: 5.3
+behind_firewall: no
+contains_sensitive_data: no
+addresses:
+  - http://default.designingpatterns.com
+  - http://apple.designingpatterns.com

data/examples/override_example_1.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+#
+# These example programs use the 'relative' gem in order to
+# express paths relative to __FILE__ cleanly, allowing them to be run from
+# any directory.  In particular, they use the require_relative
+# method to load examples/machineconfig.rb and
+# File.expand_path_relative_to_caller in order to refer to
+# configuration files within the examples directory.
+#
+
+require 'rubygems'
+require 'relative'
+require_relative 'machineconfig'
+
+require 'configtoolkit/yamlreader'
+require 'configtoolkit/overridereader'
+
+CONFIGURATION_FILE = File.expand_path_relative_to_caller("override_example.yaml")
+OVERRIDE_FILE = File.expand_path_relative_to_caller("override_example_override.yaml")
+
+reader = ConfigToolkit::OverrideReader.new(ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE),
+                                           ConfigToolkit::YAMLReader.new(OVERRIDE_FILE))
+
+# Let's load the overriden configuration.
+config = MachineConfig.load(reader)
+print("The config:\n#{config}\n")

data/examples/override_example_2.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+
+#
+# These example programs use the 'relative' gem in order to
+# express paths relative to __FILE__ cleanly, allowing them to be run from
+# any directory.  In particular, they use the require_relative
+# method to load examples/machineconfig.rb and
+# File.expand_path_relative_to_caller in order to refer to
+# configuration files within the examples directory.
+#
+require 'rubygems'
+require 'relative'
+require_relative 'machineconfig'
+
+require 'configtoolkit/yamlreader'
+require 'configtoolkit/hashreader'
+require 'configtoolkit/overridereader'
+
+CONFIGURATION_FILE = 
+  File.expand_path_relative_to_caller("load_group_example.yaml")
+
+hash_configuration = {
+  "db_cluster" => { 
+    "db4" => {
+      "num_cpus" =>  48,
+      "os" => {
+        "name" => "Solaris",
+        "version" => 10.0
+      },
+      "contains_sensitive_data" => "yes",
+      "behind_firewall" => "yes",
+      "addresses" => [ "http://db4.designingpatterns.com" ]
+    }
+  }
+}
+    
+#
+# The group of configurations is under the db_cluster containing
+# object name.
+#
+reader = ConfigToolkit::OverrideReader.new(ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE),
+                                           ConfigToolkit::HashReader.new(hash_configuration))
+
+configs = MachineConfig.load_group(reader, "db_cluster")
+configs.each do |name, config|
+  print "The #{name} configuration:\n#{config}\n"
+end
+

data/examples/override_example_override.yaml

@@ -0,0 +1,9 @@
+#
+# This file contains a subset of a MachineConfig configuration and
+# is meant to be an override of the MachineConfig specified in 
+# examples/override_example.yaml.
+#
+
+num_cpus: 64
+os:
+  version: 5.4

data/lib/configtoolkit/overridereader.rb

@@ -0,0 +1,190 @@
+#!/usr/bin/env ruby
+
+require 'configtoolkit/reader'
+
+module ConfigToolkit
+
+#
+# This class allows the caller to override configuration paramaters in
+# a given Reader instance with configuration parameters in a second
+# Reader instance.
+#
+# The override process is similar to a union without duplicate keys.
+# When processing two readers, if a given configuration parameter's
+# key is present in both readers, the second reader's parameter
+# replaces the first.  The union performed is a "deep" union.  Hashes
+# nested in the configuration are unioned as well.  Handling arrays is
+# a tad more complicated.  If an array specified in the first reader
+# contains no containers (arrays or hashes), and is present in the
+# second reader as well, the second array will completely replace the
+# first.  If the array specified in the first reader contains a
+# container, the array will be unioned, and nested containers will be
+# unioned (except for arrays with no containers which are always
+# replaced not unioned.)
+#
+# See Override.txt for more details.
+#
+# === Additional Note on the Handling of Arrays 
+# The Array handling behavior was chosen from a usage standpoint.
+# Arrays with no container elements are most often considered as
+# one configuration parameter (not a list of configuration parameters).
+# As such, arrays should remain intact during the union (be replaced as
+# opposed to unioned).  However, if configurations are nested inside an array,
+# the array is no longer (from a usage standpoint) one configuration parameter,
+# but a container of configuration parameters.  Thus, when arrays contain
+# non-container elements, they are unioned instead of simply replaced.  If different
+# behavior is required, please feel free to contact us in order to request it.
+#
+
+class OverrideReader < Reader
+  #
+  # ====Description: 
+  # This constructs a OverrideReader instance for the list of readers passed in.
+  # 
+  # ====Parameters: 
+  # [readers] 
+  #      A list of objects whose class(es) implements the Reader interface.
+  # 
+  def initialize(*readers)
+    if (readers.length == 0)
+      raise ArgumentError, "At least one reader must be specified"
+    end
+
+    @readers = *readers
+  end
+
+  # The Visitor allows the caller to override a configuration
+  # (specified by a hash) with a second configuration (specified by a
+  # hash).  The first hash is passed in through the new method, the
+  # second via the visit method.  The hash passed in through the new
+  # method is directly edited, and after the visit method finishes,
+  # contains the resulting overriden hash.
+  #
+  # The Visitor algorithm works as follows.  The visit method visits
+  # all elements in the second "overriding" hash.  While doing so, the
+  # Visitor keeps track of the matching containing element in the
+  # first hash (if such containing element exists), by storing this
+  # information on the stack.  When an element (in the second hash) is
+  # visited, it is added to the containing element specified on the
+  # stack (replaces the element in the first hash if the parameter's
+  # key already exists in the first hash).
+  class Visitor < HashArrayVisitor # :nodoc:
+    #
+    # The structure currently being built.
+    #
+    attr_reader :config_hash
+
+    #
+    # A StackFrame contains the container currently being
+    # built.
+    #
+    StackFrame = Struct.new(:container)
+
+    def initialize(config_hash)
+      @config_hash = config_hash
+      @next_container = @config_hash
+
+      super()
+    end
+
+    # 
+    # ====Description:
+    # This method clears the container if a container is
+    # passed in.
+    #
+    def convert_value(value)
+      if(value.is_a?(Hash))
+        return {}
+      elsif(value.is_a?(Array))
+        return []
+      else
+        return value
+      end
+    end
+    private :convert_value
+    
+    def enter_hash(hash)
+      return StackFrame.new(@next_container)
+    end
+    
+    def visit_hash_element(key, value, index, is_container)
+      converted_value = convert_value(value)
+      
+      if(is_container)
+        existing_value = stack_top().container[key]
+        
+        if ((existing_value.class == value.class) &&
+            (existing_value.class == Hash ||
+             (existing_value.class == Array && 
+              array_contains_container(existing_value))))
+          @next_container = existing_value
+          return
+        end
+        
+        @next_container = converted_value
+      end
+      
+      stack_top().container[key] = converted_value
+    end
+    
+    # 
+    # ====Description:
+    # This method returns whether the container passed in contains a container.
+    #
+    def array_contains_container(container)
+      container.index() {|value| value.class == Hash || value.class == Array }
+    end
+    private :array_contains_container
+    
+    def enter_array(array)
+      return StackFrame.new(@next_container)
+    end
+    
+    def visit_array_element(value, index, is_container)
+      converted_value = convert_value(value)
+      
+
+      if(is_container)
+        existing_value = stack_top().container[index]
+        if ((existing_value.class == value.class) &&
+            (existing_value.class == Hash ||
+             (existing_value.class == Array && 
+              array_contains_container(existing_value))))
+          @next_container = existing_value
+          return
+        end
+
+        @next_container = converted_value
+      end
+      
+      if (index < stack_top().container.length())
+        stack_top().container[index] = converted_value
+      else
+        stack_top().container.push(converted_value)
+      end
+    end
+  end
+  
+  def self.override(left, right)
+    visitor = Visitor.new(left)
+    visitor.visit(right)
+    return visitor.config_hash
+  end
+  private_class_method :override
+
+  # 
+  # ====Returns:
+  # A hash representing the configuration after all overrides are performed.
+  # 
+  def read
+    aggregate_hash = {}
+    
+    @readers.each do |reader|
+      aggregate_hash = self.class.send(:override, aggregate_hash, reader.read())
+    end
+    
+    aggregate_hash
+  end
+
+end
+end

data/test/override_sample_1.yaml

@@ -0,0 +1,21 @@
+--- 
+# missing req_integer
+opt_integer: 56
+req_uri: http://blogs.designingpatterns.com
+req_float: 1.23
+req_pathname: /usr/designingpatterns/bin
+req_string: sample string2
+req_boolean: true
+req_symbol: sample_symbol5
+req_big_integer: 90000000000
+nested_config:
+  req_nested_array: 
+  - req_second_nested_array: 
+    - 6
+    - 20
+  - req_second_nested_pathname: /usr
+    req_second_nested_array: 
+    - 305
+    - 306
+    - 307
+  req_nested_integer: 23

data/test/override_sample_2.yaml

@@ -0,0 +1,20 @@
+--- 
+# missing req_big_integer
+opt_integer: 56
+req_uri: http://blogs.designingpatterns.com
+req_float: 3.14                                                                   # override
+req_pathname: /usr/designingpatterns/bin
+req_integer: 6
+req_string: sample string2
+req_boolean: true
+req_symbol: sample_symbol2
+nested_config:
+  req_nested_array:
+  - req_second_nested_pathname: /usr/designingpatterns/Applications/pattmake      # override
+    req_second_nested_array: 
+    - 6
+    - 20
+  - req_second_nested_array:                                                      # override
+    - 205
+    - 206
+  req_nested_integer: 34                                                          # override

data/test/test_override.rb

@@ -0,0 +1,115 @@
+require 'readerwritertest'
+
+require 'configtoolkit/overridereader'
+require 'configtoolkit/yamlreader'
+require 'configtoolkit/hashreader'
+
+require 'rubygems'
+require 'assertions'
+require 'relative'
+
+class OverrideTest < Test::Unit::TestCase
+  include ReaderWriterTest
+
+  # Test basic override operations.
+  def basic_reader_operations()
+    # non-container -> non-container
+    run_override({ "first" => 5 }, 
+                 { "first" => 6})
+    # non-container -> array
+    run_override({ "first" => 5 }, 
+                 { "first" => [ 1, 2, 3 ] })
+    # array -> non-container
+    run_override({ "first" => [ 1, 2, 3 ] }, 
+                 { "first" => 5 })
+    # non-container -> hash
+    run_override({ "first" => 5 }, 
+                 { "first" => { "second" => 3 }})
+    # hash -> non-container
+    run_override({ "first" => { "second" => 3 }}, 
+                 { "first" => 5 } )
+    # hash -> array
+    run_override({ "first" => { "second" => 3 }}, 
+                 { "first" => [1, 2, 3] })
+    # array -> hash
+    run_override({ "first" => [1, 2, 3] }, 
+                 { "first" => { "second" => 3 }})
+    # simple union of 2 hash values
+    run_override({ "first" => 1 }, 
+                 {"second" => 2 }, 
+                 { "first" => 1, "second" => 2 })
+    # union of nested hash values
+    run_override({ "config" => { "first" => 1 }}, 
+                 { "config" => { "second" => 2 }},
+                 { "config" => { "first" => 1, "second" => 2 }})
+    # array -> array - replace entire array
+    run_override({ "first" => [1, 2, 3] }, 
+                 { "first" => [4, 5]})
+    # array -> array - union hash inside array
+    run_override({ "first" => [1, { "second" => 2 }] }, 
+                 { "first" => [3, { "fourth" => 5 }] },
+                 { "first" => [3, { "second" => 2, "fourth" => 5 }] })    
+  end
+
+  def run_override(hash_1, hash_2, expected = nil)
+    reader_1 = ConfigToolkit::HashReader.new(hash_1)
+    reader_2 = ConfigToolkit::HashReader.new(hash_2)
+    
+    if (!expected) then expected = hash_2 end
+
+    assert_equal(expected,
+                 ConfigToolkit::OverrideReader.new(reader_1, reader_2).read())
+  end
+
+  def test_reader
+    basic_reader_operations()
+    
+    # Override a reader with an identical reader.
+    file = File.expand_path_relative_to_caller("sample.standard_yaml_classes.yaml")
+    run_reader_test(ConfigToolkit::OverrideReader,
+                    "",
+                    REFERENCE_SAMPLE_CONFIG,
+                    ConfigToolkit::YAMLReader.new(file),
+                    ConfigToolkit::YAMLReader.new(file))
+    
+    # Override an almost empty reader with the standard sample reader.
+    file = File.expand_path_relative_to_caller("sample.standard_yaml_classes.yaml")
+    hash_reader = ConfigToolkit::HashReader.new({ "opt_integer" => 10 })
+    yaml_reader = ConfigToolkit::YAMLReader.new(file)
+
+    run_reader_test(ConfigToolkit::OverrideReader,
+                    "",
+                    REFERENCE_SAMPLE_CONFIG,
+                    hash_reader, 
+                    yaml_reader)
+    
+    # Perform an override on two different configs together to produce the sample config.
+    # - replace a hash value
+    # - replace a hash value nested in an array
+    # - replace an array containing only non-containers
+    file_1 = File.expand_path_relative_to_caller("override_sample_1.yaml")
+    file_2 = File.expand_path_relative_to_caller("override_sample_2.yaml")
+    run_reader_test(ConfigToolkit::OverrideReader,
+                    "",
+                    REFERENCE_SAMPLE_CONFIG,
+                    ConfigToolkit::YAMLReader.new(file_1),
+                    ConfigToolkit::YAMLReader.new(file_2))
+
+    # The contained sample, pass more than 2 readers.
+    file = File.expand_path_relative_to_caller("contained_sample.yaml")
+    yaml_reader = ConfigToolkit::YAMLReader.new(file)
+    
+    hash_1 = { "first" => [ 1, 2, 3 ] }
+    hash_2 = { "first" => { "second" => 3 }}
+    hash_reader_1 = ConfigToolkit::HashReader.new(hash_1)
+    hash_reader_2 = ConfigToolkit::HashReader.new(hash_2)
+    
+    run_reader_test(ConfigToolkit::OverrideReader,
+                    "first.second",
+                    REFERENCE_CONTAINED_SAMPLE_CONFIG,
+                    hash_reader_1, 
+                    hash_reader_2,
+                    yaml_reader)    
+  end
+  
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: configtoolkit
 version: !ruby/object:Gem::Version 
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors: 
 - DesigningPatterns
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-07-25 00:00:00 -04:00
+date: 2008-07-29 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -42,7 +42,7 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: 1.7.0
     version: 
-description: "This package makes sourcing information from (parsing) configuration files robust and easy!  It: * Allows programmers to specify the type of data that should be loaded from a configuration file.  The toolkit automatically will validate the file's data against this specification when loading the file, ensuring that the specification always is obeyed and saving the programmer the tedious chore of writing validation code. * Automagically generates parameter accessor methods (getters, setters, and predicates to test for presence), an equality operator, and a +to_s+ method from the configuration's specification. * Allows programmers to create configuration files, easily and programatically. * Provides a class that can load (parse) Ruby configuration files (allowing the full power of Ruby to be used within configuration files). * Provides classes that can load from (parse) and dump to YAML and key-value configuration files. * Provides classes that can load from and dump to Hashes. * Is very extensible, allowing the engine to be used with custom format configuration files and with custom data validation rules."
+description: "This package makes sourcing information from (parsing) configuration files robust and easy!  It: * Allows programmers to specify the type of data that should be loaded from a configuration file.  The toolkit automatically will validate the file's data against this specification when loading the file, ensuring that the specification always is obeyed and saving the programmer the tedious chore of writing validation code. * Automagically generates parameter accessor methods (getters, setters, and predicates to test for presence), an equality operator, and a +to_s+ method from the configuration's specification. * Allows programmers to create configuration files, easily and programatically. * Provides a class that can load (parse) Ruby configuration files (allowing the full power of Ruby to be used within configuration files). * Provides classes that can load from (parse) and dump to YAML and key-value configuration files. * Provides classes that can load from and dump to Hashes. * Provides a class that allows the contents of one configuration source to override the contents of another (this works with configuration files of any format or Hashes). * Is very extensible, allowing the engine to be used with custom format configuration files and with custom data validation rules."
 email: 
 - technical.inquiries@designingpatterns.com
 executables: []
@@ -55,6 +55,7 @@ extra_rdoc_files:
 - FAQ.txt
 - Hash.txt
 - KeyValue.txt
+- Override.txt
 - README.txt
 - Ruby.txt
 - YAML.txt
@@ -65,6 +66,7 @@ files:
 - FAQ.txt
 - Hash.txt
 - KeyValue.txt
+- Override.txt
 - README.txt
 - Ruby.txt
 - YAML.txt
@@ -74,11 +76,15 @@ files:
 - examples/load_example.rb
 - examples/load_group_example.rb
 - examples/machineconfig.rb
+- examples/override_example_1.rb
+- examples/override_example_2.rb
 - examples/ruby_example.rb
 - examples/usage_example.rb
 - examples/yaml_example.rb
 - examples/load_example.yaml
 - examples/load_group_example.yaml
+- examples/override_example_override.yaml
+- examples/override_example.yaml
 - examples/yaml_example.dump.yaml
 - examples/yaml_example.yaml
 - examples/key_value_example.dump.cfg
@@ -94,6 +100,7 @@ files:
 - lib/configtoolkit/keyvalueconfig.rb
 - lib/configtoolkit/keyvaluereader.rb
 - lib/configtoolkit/keyvaluewriter.rb
+- lib/configtoolkit/overridereader.rb
 - lib/configtoolkit/prettyprintwriter.rb
 - lib/configtoolkit/reader.rb
 - lib/configtoolkit/rubyreader.rb
@@ -107,6 +114,7 @@ files:
 - test/test_baseconfig.rb
 - test/test_hash.rb
 - test/test_keyvalue.rb
+- test/test_override.rb
 - test/test_prettyprint.rb
 - test/test_ruby.rb
 - test/test_yaml.rb
@@ -114,6 +122,8 @@ files:
 - test/contained_sample.yaml
 - test/firewall.yaml
 - test/machines.yaml
+- test/override_sample_1.yaml
+- test/override_sample_2.yaml
 - test/sample.ruby_yaml_classes.yaml
 - test/sample.standard_yaml_classes.yaml
 - test/webserver.yaml
@@ -175,6 +185,7 @@ specification_version: 2
 summary: "This package makes sourcing information from (parsing) configuration files robust and easy!  It: * Allows programmers to specify the type of data that should be loaded from a configuration file"
 test_files: 
 - test/test_baseconfig.rb
+- test/test_override.rb
 - test/test_ruby.rb
 - test/test_yaml.rb
 - test/test_keyvalue.rb