configtoolkit 2.2.0 → 2.3.0

data/FAQ.txt

@@ -1,3 +1,5 @@
+
+
 === Why can't I use a normal Ruby Array rather than a ConstrainedArray in my configuration's specification?
 You can, but you probably don't want to.  Actually, underneath, the
 ConfigToolkit converts Array parameters into ConfigToolkit::ConstrainedArray
@@ -86,7 +88,7 @@ all cases, except:
   made available.  In this case, a key-value format is best, but the format
   cannot use key-value extensions like Hashes, Arrays, or include directives
   (since writing support for these in a key-value implementation in another
-   language is non-trivial)
+  language is non-trivial)
 
 === How can configuration parameters be documented with rdoc?
 Unfortunately, +rdoc+ cannot document configuration parameters by default.  One
@@ -101,7 +103,7 @@ versions 2.0.0 and 2.1.0, which can be obtained with +gem+ or at
 http://rubyforge.org/projects/rdoc/) that fixes this for
 ConfigToolkit::BaseConfig.add_required_param and
 ConfigToolkit::BaseConfig.add_optional_param:
-======+rdoc_support/rdoc-2.0.0.patch+:
+======<tt>rdoc_support/rdoc-2.0.0.patch</tt>:
  --- parse_rb.rb	2008-07-14 12:25:06.000000000 -0400
  +++ /usr/lib/ruby/gems/1.8/gems/rdoc-2.0.0/lib/rdoc/parsers/parse_rb.rb	2008-07-14 12:32:02.000000000 -0400
  @@ -2505,6 +2505,21 @@
@@ -129,7 +131,7 @@ ConfigToolkit::BaseConfig.add_optional_param:
 
 This patch only should be applied to the +rdoc+ version 2.0.0 gem with the
 +patch+ utility:
-======+rdoc_support/rdoc-2.1.0.patch+:
+======<tt>rdoc_support/rdoc-2.1.0.patch</tt>:
  --- rdoc-2.1.0/lib/rdoc/parser/ruby.rb	2008-07-25 13:09:44.000000000 -0400
  +++ /usr/lib/ruby/gems/1.8/gems/rdoc-2.1.0/lib/rdoc/parser/ruby.rb	2008-07-25 13:08:37.000000000 -0400
  @@ -1807,6 +1807,21 @@

data/Hash.txt

@@ -1,3 +1,5 @@
+
+
 == LOADING AND DUMPING CONFIGURATIONS FROM AND TO HASHES:
 Reader classes extending the ConfigToolkit::Reader interface implement
 a +read+ method (see ConfigToolkit::Reader#read) that reads configuration
@@ -12,7 +14,7 @@ useful in that it allows ConfigToolkit::BaseConfig#load to be run on data
 specified programatically in a Hash.
 
 == EXAMPLE:
-======+examples/hash_example.rb+:
+======<tt>examples/hash_example.rb</tt>:
  #!/usr/bin/env ruby
  
  #
@@ -125,4 +127,4 @@ When run, the program produces:
  }
  
  The Hash dumped from the second config:
- {: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}}}
+ {:production=>{:www=>{:addresses=>[#<URI::HTTP:0xb7cc042c URL:http://www.designingpatterns.com>, #<URI::HTTP:0xb7cc03dc 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,21 @@
+=== 2.3.0 / 2009-06-09 
+* The ConfigToolkit will print out a warning when it encounters an
+  unknown parameter when loading a configuration file
+  (ConfigToolkit::BaseConfig#load and ConfigToolkit::BaseConfig#load_group).
+  This will make it easier to catch errors in configuration files.  Previously,
+  such unknown parameters were ignored silently (thanks for the idea, Inaki).
+* The ConfigToolkit now *itself* can be configured.
+  ConfigToolkit::ConfigToolkitConfig configurations can be specified for a
+  ConfigToolkit::BaseConfig child class or for an instance of a
+  ConfigToolkit::BaseConfig child class.  The
+  ConfigToolkit::ConfigToolkitConfig allows customization of the loading
+  and dumping processes.  Right now, it supports modifying the ConfigToolkit's
+  behavior upon encountering an unknown configuration parameter: the
+  ConfigToolkit can ignore the parameter (the behavior in prior versions),
+  warn about the parameter (the new default behavior), or raise a
+  ConfigToolkit::Error about the parameter.  See README.txt for
+  more details.
+
 === 2.2.0 / 2008-07-29 
 * Add support for overriding configurations through the
   ConfigToolkit::OverrideReader, allowing the contents of one configuration file

data/KeyValue.txt

@@ -1,3 +1,5 @@
+
+
 == KEY-VALUE CONFIGURATION FILES:
 Key-value configuration files are quite common, although they come in a
 myriad of different formats.  +/etc/sysctl.conf+ on my system (CentOS 5.1), for
@@ -41,7 +43,7 @@ a new file).
 == EXAMPLE:
 The following configuration file contains one configuration in a common
 key-value format (the ConfigToolkit's default key-value format, in fact):
-======+examples/key_value_example.normal1.cfg+:
+======<tt>examples/key_value_example.normal1.cfg</tt>:
  #
  # This file contains MachineConfig configurations
  # (see examples/machineconfig.rb for the configuration's specification).
@@ -65,7 +67,7 @@ key-value format (the ConfigToolkit's default key-value format, in fact):
 
 It includes a second key-value configuration file containing another
 configuration (in the same key-value format):
-======+examples/key_value_example.normal2.cfg+:
+======<tt>examples/key_value_example.normal2.cfg</tt>:
  #
  # This file contains MachineConfig configurations
  # (see examples/machineconfig.rb for the configuration's specification).
@@ -88,7 +90,7 @@ configuration also is represented with a different key-value
 format (the format uses ":" instead of "=" to separate keys and
 values, "<<-->>" instead of "=>" to separate hash keys and values, and
 ";" instead of "#" to prefix comments) in this file:
-======+examples/key_value_example.wacky.cfg+:
+======<tt>examples/key_value_example.wacky.cfg</tt>:
  ;
  ; This file contains MachineConfig configurations
  ; (see examples/machineconfig.rb for the configuration's specification).
@@ -105,7 +107,7 @@ values, "<<-->>" instead of "=>" to separate hash keys and values, and
 
 The following program loads these configurations and writes the second
 configuration in a new key-value format:
-======+examples/key_value_example.rb+:
+======<tt>examples/key_value_example.rb</tt>:
  #!/usr/bin/env ruby
  
  #

data/Manifest.txt

@@ -9,6 +9,7 @@ README.txt
 Ruby.txt
 YAML.txt
 Rakefile
+examples/config_toolkit_config_example.rb
 examples/hash_example.rb
 examples/key_value_example.rb
 examples/load_example.rb
@@ -19,6 +20,7 @@ examples/override_example_2.rb
 examples/ruby_example.rb
 examples/usage_example.rb
 examples/yaml_example.rb
+examples/config_toolkit_config_example.yaml
 examples/load_example.yaml
 examples/load_group_example.yaml
 examples/override_example_override.yaml
@@ -32,6 +34,7 @@ examples/key_value_example.wacky.cfg
 examples/ruby_example.rcfg
 lib/configtoolkit.rb
 lib/configtoolkit/baseconfig.rb
+lib/configtoolkit/configtoolkitconfig.rb
 lib/configtoolkit/hasharrayvisitor.rb
 lib/configtoolkit/hashreader.rb
 lib/configtoolkit/hashwriter.rb
@@ -50,6 +53,7 @@ rdoc_support/rdoc-2.0.0.patch
 rdoc_support/rdoc-2.1.0.patch
 test/readerwritertest.rb
 test/test_baseconfig.rb
+test/test_configtoolkitconfig.rb
 test/test_hash.rb
 test/test_keyvalue.rb
 test/test_override.rb

data/Override.txt

@@ -1,3 +1,5 @@
+
+
 == OVERRIDE CONFIGURATION FILES: 
 Do you find yourself needing to override specific configuration
 parameters in your configuration?  For example, does your application
@@ -17,7 +19,7 @@ For more specific details see the ConfigToolkit::OverrideReader class.
 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+:
+======<tt>examples/override_example.yaml</tt>:
  #
  # This file contains MachineConfig configurations
  # (see examples/machineconfig.rb for the configuration's specification).
@@ -33,7 +35,7 @@ of the first.
    - http://default.designingpatterns.com
    - http://apple.designingpatterns.com
 
-======+examples/override_example_override.yaml+:
+======<tt>examples/override_example_override.yaml</tt>:
  #
  # This file contains a subset of a MachineConfig configuration and
  # is meant to be an override of the MachineConfig specified in 
@@ -45,7 +47,7 @@ of the first.
    version: 5.4
 
 This is the program that reads the two above configurations and performs the override.
-======+examples/override_example_1.rb+:
+======<tt>examples/override_example_1.rb</tt>:
  #!/usr/bin/env ruby
  
  #
@@ -64,11 +66,16 @@ This is the program that reads the two above configurations and performs the ove
  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")
+ 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))
+ config_file_reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+ override_file_reader = ConfigToolkit::YAMLReader.new(OVERRIDE_FILE)
+ 
+ reader = ConfigToolkit::OverrideReader.new(config_file_reader,
+                                            override_file_reader)
  
  # Let's load the overriden configuration.
  config = MachineConfig.load(reader)
@@ -78,17 +85,17 @@ When run, it produces the following output:
 ======The output of <code>examples/override_example_1.rb</code>:
  The config:
  {
+     addresses              : [
+         http://default.designingpatterns.com,
+         http://apple.designingpatterns.com
+     ]
+     contains_sensitive_data: false
      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
  }
  
 
@@ -98,7 +105,7 @@ 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+:
+======<tt>examples/load_group_example.yaml</tt>:
  #
  # This file contains MachineConfig configurations
  # (see examples/machineconfig.rb for the configuration's specification).
@@ -138,7 +145,7 @@ 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+:
+======<tt>examples/override_example_2.rb</tt>:
  #!/usr/bin/env ruby
  
  #
@@ -179,71 +186,71 @@ above.
  # 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))
+ config_file_reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+ hash_reader = ConfigToolkit::HashReader.new(hash_configuration)
+ reader = ConfigToolkit::OverrideReader.new(config_file_reader, hash_reader)
  
  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
+ The db2 configuration:
+ db_cluster.db2: {
+     os                     : {
+         version: 5.3
+         name   : AIX
+     }
+     behind_firewall        : true
+     num_cpus               : 12
      addresses              : [
-         http://db3.designingpatterns.com
+         http://db2.designingpatterns.com
      ]
      contains_sensitive_data: true
+ }
+ 
+ The db3 configuration:
+ db_cluster.db3: {
      os                     : {
          version: 10.0
          name   : Solaris
      }
      behind_firewall        : true
+     num_cpus               : 24
+     addresses              : [
+         http://db3.designingpatterns.com
+     ]
+     contains_sensitive_data: 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
+     num_cpus               : 48
+     addresses              : [
+         http://db4.designingpatterns.com
+     ]
+     contains_sensitive_data: 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
+     num_cpus               : 16
      addresses              : [
-         http://db2.designingpatterns.com
+         http://db1.designingpatterns.com
      ]
      contains_sensitive_data: true
-     os                     : {
-         version: 5.3
-         name   : AIX
-     }
-     behind_firewall        : true
  }
  
 

data/README.txt

@@ -1,6 +1,4 @@
-= configtoolkit
-* Project Page: http://rubyforge.org/projects/configtoolkit/
-* Documentation: http://configtoolkit.rubyforge.org/
+Object
 
 == DESCRIPTION:
 This package makes sourcing information from (parsing) configuration files
@@ -39,6 +37,16 @@ robust and easy!  It:
   optional parameters.
 * A block can be passed to the +new+ method of a configuration class in order
   to initialize the instance (see ConfigToolkit::BaseConfig.new).
+* The ConfigToolkit (by default) will print warnings when it encounters
+  unknown configuration parameters, allowing errors in configuration files to
+  be discovered quickly.
+* The behavior of the ConfigToolkit for a particular ConfigToolkit::BaseConfig
+  child class or for an instance of a ConfigToolkit::BaseConfig child class
+  can be configured through specifying a ConfigToolkit::ConfigToolkitConfig.
+  Right now, the ConfigToolkit's behavior when it encounters an unknown
+  parameter can be configured (to ignore the unknown parameter, to warn
+  about the unknown parameter, or to raise an error about the unknown
+  parameter).
 * +rdoc+ can detect and generate documentation for each parameter in a
   configuration class (see FAQ.txt for how to enable this).
 * An equality operator exists for each configuration class that
@@ -99,7 +107,7 @@ None (known).
 
 == SYNOPSIS:
 Here is a sample configuration class:
-======+examples/machineconfig.rb+:
+======<tt>examples/machineconfig.rb</tt>:
  require 'rubygems'
  require 'configtoolkit'
  
@@ -219,7 +227,7 @@ that the Array has at least two elements.  Additional constraints on the
 number of elements in the Array are possible
 
 The following program manipulates a MachineConfig instance.
-======+examples/usage_example.rb+:
+======<tt>examples/usage_example.rb</tt>:
  #!/usr/bin/env ruby
  
  #
@@ -380,7 +388,7 @@ When run, it produces:
 
 Of course, the most common use case will be setting configuration parameters
 with the contents of configuration files, not programatically.  The following   YAML configuration file contains two MachineConfig configurations:
-======+examples/load_example.yaml+:
+======<tt>examples/load_example.yaml</tt>:
  #
  # This file contains MachineConfig configurations
  # (see examples/machineconfig.rb for the configuration's specification).
@@ -418,7 +426,7 @@ with the contents of configuration files, not programatically.  The following
 
 The following program loads and prints the two configurations from
 +examples/load_example.yaml+.
-======+examples/load_example.rb+:
+======<tt>examples/load_example.rb</tt>:
  #!/usr/bin/env ruby
  
  #
@@ -493,7 +501,7 @@ configuration being accessible separately.  When run, it produces:
 A group of configurations also can be loaded with the
 ConfigToolkit::BaseConfig.load_group method.  For instance, given
 +examples/load_group_example.yaml+:
-======+examples/load_group_example.yaml+:
+======<tt>examples/load_group_example.yaml</tt>:
  #
  # This file contains MachineConfig configurations
  # (see examples/machineconfig.rb for the configuration's specification).
@@ -530,7 +538,7 @@ ConfigToolkit::BaseConfig.load_group method.  For instance, given
 
 the following code will load the file's three configurations into a +Hash+ 
 mapping containing object names to configurations:
-======+examples/load_group_example.rb+:
+======<tt>examples/load_group_example.rb</tt>:
  #!/usr/bin/env ruby
  
  #
@@ -606,6 +614,109 @@ When run, it produces:
  
 
 
+== CONFIGURING THE CONFIGTOOLKIT
+As of version 2.3.0, the ConfigToolkit *itself* can be configured.
+
+Consider the following simple YAML configuration file:
+======<tt>examples/config_toolkit_config_example.yaml</tt>:
+ name: Tony
+ 
+ #
+ # 'country' has been misspelled
+ #
+ county: USA
+
+
+The following code configures the +SimpleConfig+ class and specific instances
+of the +SimpleConfig+ class to behave differently than the ConfigToolkit
+default when unknown parameters are encountered when loading a configuration
+file.
+======<tt>examples/config_toolkit_config_example.rb</tt>:
+ #!/usr/bin/env ruby
+ 
+ require 'rubygems'
+ require 'configtoolkit'
+ require 'configtoolkit/yamlreader'
+ 
+ require 'relative'
+ 
+ class SimpleConfig < ConfigToolkit::BaseConfig
+ 
+   #
+   # Set SimpleConfig's default ConfigToolkit::ConfigToolkitConfig via
+   # the default_config_toolkit_config accessor method.
+   #
+   default_config_toolkit_config = ConfigToolkit::ConfigToolkitConfig.new() do |instance|
+     #
+     # This will suppress warnings when an unknown config param
+     # is encountered when loading a configuration file.
+     #
+     instance.unknown_config_param_behavior =
+       ConfigToolkit::ConfigToolkitConfig::UnknownConfigParamBehavior::IGNORE
+   end
+ 
+   add_required_param(:name, String)
+ 
+   add_optional_param(:country, String, NO_DEFAULT_VALUE)
+ 
+ end
+ 
+ CONFIGURATION_FILE = File.expand_path_relative_to_caller("config_toolkit_config_example.yaml")
+ 
+ #
+ # Even though there is a bogus parameter in the configuration file,
+ # SimpleConfig.load silently will ignore it due to SimpleConfig's
+ # default ConfigToolkit::ConfigToolkitConfig.
+ #
+ reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+ config = SimpleConfig.load(reader)
+ puts "Unknown parameters silently were ignored when loading this: #{config}\n"
+ 
+ #
+ # Note that a ConfigToolkit::ConfigToolkitConfig is passed
+ # into SimpleConfig.load below.  This will override SimpleConfig's default
+ # ConfigToolkit::ConfigToolkitConfig and cause an error to be raised when
+ # the unknown parameter is encountered.
+ #
+ config_toolkit_config = ConfigToolkit::ConfigToolkitConfig.new() do |instance|
+   #
+   # This will cause an error to be raised when an unknown config param
+   # is encountered when loading a configuration file.
+   #
+   instance.unknown_config_param_behavior = 
+     ConfigToolkit::ConfigToolkitConfig::UnknownConfigParamBehavior::ERROR
+ end
+ reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+ 
+ begin
+   config = SimpleConfig.load(reader, "", config_toolkit_config)
+ rescue ConfigToolkit::Error => e
+   puts e
+ end
+
+
+When run, it produces:
+======The output of <code>examples/config_toolkit_config_example.rb</code>:
+ Unknown parameters silently were ignored when loading this: {
+     name: Tony
+ }
+ 
+ error setting county with value USA: no parameter county exists for configuration class SimpleConfig.
+
+
+
+=== CONFIGTOOLKIT CONFIGURATION PARAMETERS
++unknown_config_param_behavior+: the behavior when encountering an unknown parameter.  Its possible values:
++ignore+:: The unknown parameter will be ignored (+ignore+).  This can be
+           useful in order to maintain compatibility with older versions of
+           software when adding new fields to a configuration file.
++warn+:: The unknown parameter will cause a warning to be issued (+warn+). 
+         This is the default and can allow errors in configuration files to
+         be detected more easily.  It does *NOT* prevent the configuration
+         file from being loaded, however.
++error+:: The unknown parameter will cause an error to be raised, preventing
+          the configuration file from being loaded.
+
 == CONFIGURATION FILE FORMATS:
 === EXISTING FORMATS:
 * YAML.txt describes working with YAML configuration files.
@@ -707,12 +818,12 @@ desirable!
 * Homepage: http://www.designingpatterns.com
 * Blogs: http://blogs.designingpatterns.com
 
-== SUPPORT
+== SUPPORT:
 Please post questions, concerns, or requests for enhancement to the forums on
 the project page.  Alternatively, direct contact information for
 Designing Patterns can be found on the project page for this gem.
 
-== ENHANCEMENTS
+== ENHANCEMENTS:
 Please feel free to contact us with any ideas; we will try our best to
 enhance the software and respond to user requests.  Of course, we are more
 likely to work on a particular enhancement if we know that there are users

data/Rakefile

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

data/Ruby.txt

@@ -1,3 +1,5 @@
+
+
 == RUBY CONFIGURATION FILES:
 What could be better than configuring Ruby programs with Ruby
 configuration files, harnessing the full power of Ruby for
@@ -28,7 +30,7 @@ static expressions.
 
 == EXAMPLE:
 This is a Ruby configuration file:
-======+examples/ruby_example.rcfg+:
+======<tt>examples/ruby_example.rcfg</tt>:
  #
  # This file contains MachineConfig configurations
  # (see examples/machineconfig.rb for the configuration's specification).
@@ -83,7 +85,7 @@ This is a Ruby configuration file:
                                    ]
 
 This program loads the two configurations in the file:
-======+examples/ruby_example.rb+:
+======<tt>examples/ruby_example.rb</tt>:
  #!/usr/bin/env ruby
  
  #

data/YAML.txt

@@ -1,3 +1,5 @@
+
+
 == YAML CONFIGURATION FILES:
 YAML is a clean, flexible data representation language that easily can
 represent complicated configurations.  It natively supports simple
@@ -15,7 +17,7 @@ The parameter values in YAML configuration files can be native YAML
 types (strings, integers, floats, booleans, etc.) and also can be
 serialized Ruby classes.  The following configuration file
 demonstrates this:
-======+examples/yaml_example.yaml+:
+======<tt>examples/yaml_example.yaml</tt>:
  #
  # This file contains MachineConfig configurations
  # (see examples/machineconfig.rb for the configuration's specification).
@@ -84,7 +86,7 @@ the file; FAQ.txt discusses how the ConfigToolkit converts YAML
 strings to some Ruby types (Pathnames, URIs, Symbols, etc.).  The following
 program shows how this example YAML configuration file can be loaded,
 and how a configuration can be written as a YAML file:
-======+examples/yaml_example.rb+:
+======<tt>examples/yaml_example.rb</tt>:
  #!/usr/bin/env ruby
  
  #

data/examples/config_toolkit_config_example.rb

@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'configtoolkit'
+require 'configtoolkit/yamlreader'
+
+require 'relative'
+
+class SimpleConfig < ConfigToolkit::BaseConfig
+
+  #
+  # Set SimpleConfig's default ConfigToolkit::ConfigToolkitConfig via
+  # the default_config_toolkit_config accessor method.
+  #
+  default_config_toolkit_config = ConfigToolkit::ConfigToolkitConfig.new() do |instance|
+    #
+    # This will suppress warnings when an unknown config param
+    # is encountered when loading a configuration file.
+    #
+    instance.unknown_config_param_behavior =
+      ConfigToolkit::ConfigToolkitConfig::UnknownConfigParamBehavior::IGNORE
+  end
+
+  add_required_param(:name, String)
+
+  add_optional_param(:country, String, NO_DEFAULT_VALUE)
+
+end
+
+CONFIGURATION_FILE = File.expand_path_relative_to_caller("config_toolkit_config_example.yaml")
+
+#
+# Even though there is a bogus parameter in the configuration file,
+# SimpleConfig.load silently will ignore it due to SimpleConfig's
+# default ConfigToolkit::ConfigToolkitConfig.
+#
+reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+config = SimpleConfig.load(reader)
+puts "Unknown parameters silently were ignored when loading this: #{config}\n"
+
+#
+# Note that a ConfigToolkit::ConfigToolkitConfig is passed
+# into SimpleConfig.load below.  This will override SimpleConfig's default
+# ConfigToolkit::ConfigToolkitConfig and cause an error to be raised when
+# the unknown parameter is encountered.
+#
+config_toolkit_config = ConfigToolkit::ConfigToolkitConfig.new() do |instance|
+  #
+  # This will cause an error to be raised when an unknown config param
+  # is encountered when loading a configuration file.
+  #
+  instance.unknown_config_param_behavior = 
+    ConfigToolkit::ConfigToolkitConfig::UnknownConfigParamBehavior::ERROR
+end
+reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+
+begin
+  config = SimpleConfig.load(reader, "", config_toolkit_config)
+rescue ConfigToolkit::Error => e
+  puts e
+end

data/examples/config_toolkit_config_example.yaml

@@ -0,0 +1,6 @@
+name: Tony
+
+#
+# 'country' has been misspelled
+#
+county: USA

data/examples/override_example_1.rb

@@ -16,11 +16,16 @@ 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")
+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))
+config_file_reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+override_file_reader = ConfigToolkit::YAMLReader.new(OVERRIDE_FILE)
+
+reader = ConfigToolkit::OverrideReader.new(config_file_reader,
+                                           override_file_reader)
 
 # Let's load the overriden configuration.
 config = MachineConfig.load(reader)

data/examples/override_example_2.rb

@@ -38,11 +38,11 @@ hash_configuration = {
 # 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))
+config_file_reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+hash_reader = ConfigToolkit::HashReader.new(hash_configuration)
+reader = ConfigToolkit::OverrideReader.new(config_file_reader, hash_reader)
 
 configs = MachineConfig.load_group(reader, "db_cluster")
 configs.each do |name, config|
   print "The #{name} configuration:\n#{config}\n"
 end
-

data/lib/configtoolkit/baseconfig.rb

@@ -163,6 +163,7 @@ class BaseConfig
     child_class.class_eval do
       @param_spec_list = []
       @param_spec_lookup_table = {}
+      @default_config_toolkit_config = nil
     end
   end
 
@@ -424,6 +425,52 @@ class BaseConfig
   end
   private_class_method :add_optional_param
 
+  # 
+  # ====Description:
+  # This method returns the default ConfigToolkitConfig instance for
+  # this BaseConfig child class (each BaseConfig child class can have a
+  # different default ConfigToolkitConfig instance).  The loading/dumping
+  # processes of all instances of the BaseConfig child class will be
+  # configured by this ConfigToolkitConfig instance unless a different
+  # instance is passed into BaseConfig.load or BaseConfig#initialize.
+  # 
+  # ====Returns:
+  # The default ConfigToolkitConfig instance for this BaseConfig child class.
+  #   
+  def self.default_config_toolkit_config
+    if(@default_config_toolkit_config) then
+      return @default_config_toolkit_config
+    else
+      #
+      # We need to check whether ConfigToolkitConfig::DEFAULT_CONFIG is
+      # defined because it won't be when the ConfigToolkit is bootstrapping
+      # itself (since the ConfigToolkitConfig is a BaseConfig child class).
+      #
+      if(ConfigToolkit.const_defined?(:ConfigToolkitConfig) && ConfigToolkitConfig.const_defined?(:DEFAULT_CONFIG)) then
+        return ConfigToolkitConfig::DEFAULT_CONFIG
+      else
+        return nil
+      end
+    end
+  end
+  private_class_method :default_config_toolkit_config
+
+  # 
+  # ====Description:
+  # This method sets the default ConfigToolkitConfig instance for this
+  # BaseConfig child class to config_toolkit_config (each BaseConfig child
+  # class can have a different default config_toolkit_config).
+  # 
+  # ====Parameters:
+  # [config_toolkit_config]
+  #      The new default ConfigToolkitConfig instance for this BaseConfig
+  #      child class.
+  #
+  def self.default_config_toolkit_config=(config_toolkit_config)
+    @default_config_toolkit_config = config_toolkit_config
+  end
+  private_class_method :default_config_toolkit_config=
+
   #
   # This is a String containing the name of the object that
   # contains this instance's configuration.  For example, if
@@ -460,12 +507,20 @@ class BaseConfig
   #  end
   #
   # ====Parameters:
+  # [config_toolkit_config]
+  #      An optional ConfigToolkitConfig instance to configure the new
+  #      configuration instance (this allows the loading/dumping process to
+  #      be customized).  If this parameter is not specified by the caller,
+  #      then the value of BaseConfig.default_config_toolkit_config will be 
+  #      used.
   # [&initialization_block]
   #      A block that fully initializes the parameters of the new
   #      instance
   # 
-  def initialize(&initialization_block)
+  def initialize(config_toolkit_config = nil,
+                 &initialization_block)
     @containing_object_name = ""
+    @config_toolkit_config = config_toolkit_config
 
     clear_all_values()
 
@@ -475,6 +530,26 @@ class BaseConfig
     end
   end
 
+  # 
+  # ====Description:
+  # This method returns the config_toolkit_config for this instance (used to
+  # configure the loading/dumping process).
+  # 
+  # ====Returns:
+  # the config_toolkit_config for this instance
+  # 
+  def config_toolkit_config
+    if(@config_toolkit_config) then
+      return @config_toolkit_config
+    else
+      #
+      # Use send to call the private default_config_toolkit_config method.
+      #
+      return self.class.send(:default_config_toolkit_config)
+    end
+  end
+  private :config_toolkit_config
+
   # 
   # ====Description:
   # This method clears all parameter values.
@@ -963,13 +1038,17 @@ class BaseConfig
     #
     clear_all_values()
 
+    config_toolkit_config_value = config_toolkit_config
+    unknown_config_param_behavior = config_toolkit_config_value.unknown_config_param_behavior
+
     if(containing_object_hash != nil)
       containing_object_hash.each do |name, value|
         #
         # Lookup the parameter specification by name.  If the parameter is
-        # not found, the config file must have extra parameters in it,
-        # which is not an error (should it be?); we just skip the unsupported
-        # parameter.
+        # not found, the config file must have extra parameters in it; 
+        # handling of such unknown parameters is configured by the
+        # instance's ConfigToolkitConfig (the default is to warn about the
+        # extra parameters).
         #
         # The parameter name in the containing object hash either could be a
         # Symbol or a String; in either case to_sym() will normalize 
@@ -979,6 +1058,20 @@ class BaseConfig
         param_spec = self.class.param_spec_lookup_table[name.to_sym()]
 
         if(param_spec == nil)
+          if(unknown_config_param_behavior != ConfigToolkitConfig::UnknownConfigParamBehavior::IGNORE) then
+            error_message = self.class.send(:construct_error_message,
+                                            containing_object_name,
+                                            name,
+                                            value,
+                                            "no parameter #{name} exists for configuration class #{self.class}")
+
+            if(unknown_config_param_behavior == ConfigToolkitConfig::UnknownConfigParamBehavior::WARN) then
+              $stderr.puts("WARNING: #{error_message}  Ignoring unknown parameter #{name}!")
+            else
+              raise Error, error_message
+            end
+          end
+
           next
         end
 
@@ -1026,12 +1119,18 @@ class BaseConfig
   # 
   # ====Parameters:
   # See the parameter list for load.
+  # [config_toolkit_config]
+  #      An optional ConfigToolkitConfig instance to configure the new
+  #      configuration instance (this allows the loading/dumping process to
+  #      be customized).  If this parameter is not specified by the caller,
+  #      then the value of BaseConfig.default_config_toolkit_config will be
+  #      used.
   # 
   # ====Returns:
   # The new instance, preloaded!
   # 
-  def self.load(reader, containing_object_name = "")
-    instance = new()
+  def self.load(reader, containing_object_name = "", config_toolkit_config = nil)
+    instance = new(config_toolkit_config)
     instance.load(reader, containing_object_name)
     return instance
   end
@@ -1046,11 +1145,17 @@ class BaseConfig
   # 
   # ====Parameters:
   # See the parameter list for load.
+  # [config_toolkit_config]
+  #      An optional ConfigToolkitConfig instance to configure the new
+  #      configuration instance (this allows the loading/dumping process to
+  #      be customized).  If this parameter is not specified by the caller,
+  #      then the value of BaseConfig.default_config_toolkit_config will be
+  #      used.
   # 
   # ====Returns:
   # A Hash of names (Symbols) mapping to loaded configuration instances
   # 
-  def self.load_group(reader, containing_object_name = "")
+  def self.load_group(reader, containing_object_name = "", config_toolkit_config = nil)
     containing_object_hash = load_containing_object_hash(reader, containing_object_name)
 
     config_group = {}
@@ -1066,7 +1171,7 @@ class BaseConfig
           raise Error, message
         end
 
-        instance = new()
+        instance = new(config_toolkit_config)
 
         #
         # Have to use send in order to call private method.
@@ -1109,3 +1214,9 @@ class BaseConfig
 end
 
 end
+
+#
+# This must be loaded after BaseConfig has been defined because it
+# defines a child of BaseConfig.
+#
+require 'configtoolkit/configtoolkitconfig'

data/lib/configtoolkit/configtoolkitconfig.rb

@@ -0,0 +1,77 @@
+#!/usr/bin/env ruby
+
+require 'configtoolkit/baseconfig'
+
+module ConfigToolkit
+
+#
+# This class configures the ConfigToolkit itself (or, more precisely,
+# configures instances of BaseConfig child classes).  Right now, it
+# allows customization of the behavior of a configuration instance when
+# it encounters an unknown configuration parameter during
+# configuration loading.
+#
+class ConfigToolkitConfig < BaseConfig
+
+  #
+  # This module is a (hacky) enumeration of
+  # the possible values for the ConfigToolkitConfig's
+  # +unknown_config_param_behavior+ parameter.
+  #
+  module UnknownConfigParamBehavior
+    #
+    # The ConfigToolkit will ignore unknown configuration parameters
+    # when loading a configuration.
+    #
+    IGNORE = :ignore
+
+    #
+    # The ConfigToolkit will warn about unknown configuration parameters
+    # when loading a configuration.  This is the default.
+    #
+    WARN = :warn
+
+    #
+    # The ConfigToolkit will raise an error when it encounters an unknown
+    # configuration paramater when loading a configuration.
+    #
+    ERROR = :error
+
+    # 
+    # ====Description:
+    # This class method returns +true+ if and only if
+    # +value+ is a valid UnknownConfigParamBehavior
+    # constant.
+    # 
+    # ====Parameters:
+    # [value]
+    #      The value to verify
+    # 
+    # ====Returns:
+    # +True+ if and only if +value+ is a valid UnknownConfigParamBehavior
+    # constant.
+    # 
+    def self.valid?(value)
+      return (value == UnknownConfigParamBehavior::IGNORE ||
+              value == UnknownConfigParamBehavior::WARN ||
+              value == UnknownConfigParamBehavior::ERROR)
+    end
+  end
+
+  #
+  # How the ConfigToolkit should behave when it encounters
+  # an unknown configuration parameter.
+  #
+  add_optional_param(:unknown_config_param_behavior,
+                     Symbol,
+                     UnknownConfigParamBehavior::WARN) do |new_value|
+    if(!UnknownConfigParamBehavior.valid?(new_value)) then
+      raise_error("#{new_value} is not a valid unknown_config_param_behavior value")
+    end
+  end
+
+  DEFAULT_CONFIG = self.new(){}
+
+end
+
+end

data/test/firewall.yaml

@@ -9,3 +9,4 @@ firewall:
   addresses:
     - http://firewall.designingpatterns.com
     - http://durian.designingpatterns.com
+  bogus_param: boo

data/test/test_baseconfig.rb

@@ -52,6 +52,16 @@ class BaseConfigTest < Test::Unit::TestCase
   # 3.) A ConstrainedArray parameter
   #
   class MachineConfig < ConfigToolkit::BaseConfig
+    
+    #
+    # This will quiet lots of warnings, as the configuration files
+    # for the tests have lots of bogus parameters.
+    #
+    CONFIG_TOOLKIT_CONFIG = ConfigToolkit::ConfigToolkitConfig.new() do |instance|
+      instance.unknown_config_param_behavior = ConfigToolkit::ConfigToolkitConfig::UnknownConfigParamBehavior::IGNORE
+    end
+    default_config_toolkit_config = CONFIG_TOOLKIT_CONFIG
+
     add_required_param(:name, String)
 
     add_required_param(:architecture, String)
@@ -434,4 +444,91 @@ class BaseConfigTest < Test::Unit::TestCase
       visitor.visit(3)
     end
   end
+
+  def test_config_toolkit_config
+
+    begin
+      #
+      # This config_toolkit_config will:
+      # * Warn when unknown config params are encountered.
+      #
+      config_toolkit_config1 = ConfigToolkit::ConfigToolkitConfig.new() do |instance|
+        instance.unknown_config_param_behavior = ConfigToolkit::ConfigToolkitConfig::UnknownConfigParamBehavior::WARN
+      end
+      
+      config_file_name = File.expand_path_relative_to_caller("firewall.yaml")
+
+      #
+      # Specify the config_toolkit_config for an instance;
+      # loading the configuration file should result in a warning (which
+      # we unfortunately have no easy way to verify, except visually).
+      #
+      reader = ConfigToolkit::YAMLReader.new(config_file_name)
+      MachineConfig.load(reader, "firewall", config_toolkit_config1)
+      
+      #
+      # Specify the config_toolkit_config for the MachineConfig class.
+      #
+      MachineConfig.send(:default_config_toolkit_config=, config_toolkit_config1)
+      
+      #
+      # Now we should see warnings when even not specifying the
+      # config_toolkit_config when constructing the instance, since we've
+      # specified it at the class level.
+      #
+      reader = ConfigToolkit::YAMLReader.new(config_file_name)
+      MachineConfig.load(reader, "firewall")
+
+      #
+      # This config_toolkit_config will:
+      # * Raise errors when unknown config params are encountered.
+      #
+      config_toolkit_config2 = ConfigToolkit::ConfigToolkitConfig.new() do |instance|
+        instance.unknown_config_param_behavior = ConfigToolkit::ConfigToolkitConfig::UnknownConfigParamBehavior::ERROR
+      end
+
+      #
+      # Specify the config_toolkit_config for an instance.
+      # This should result in an Error being raised when
+      # the configuration file is loaded (since it has an
+      # unknown parameter).
+      #
+      reader = ConfigToolkit::YAMLReader.new(config_file_name)
+      assert_raise_message("error setting firewall.bogus_param with value boo: no parameter bogus_param exists for configuration class BaseConfigTest::MachineConfig.",
+                           ConfigToolkit::Error) do
+        MachineConfig.load(reader, "firewall", config_toolkit_config2)
+      end
+
+      #
+      # We still only should get warnings when not specifying a
+      # config_toolkit_config for an instance since we have not changed
+      # the class-level config_toolkit_config instance yet.
+      #
+      reader = ConfigToolkit::YAMLReader.new(config_file_name)
+      MachineConfig.load(reader, "firewall")
+
+      #
+      # Now specify the new config_toolkit_config for the class.
+      #
+      MachineConfig.send(:default_config_toolkit_config=, config_toolkit_config2)
+      
+      #
+      # Now we should get an Error when not loading up a configuration file
+      # with an unknown parameter.
+      #
+      reader = ConfigToolkit::YAMLReader.new(config_file_name)
+      assert_raise_message("error setting firewall.bogus_param with value boo: no parameter bogus_param exists for configuration class BaseConfigTest::MachineConfig.",
+                           ConfigToolkit::Error) do
+        MachineConfig.load(reader, "firewall")
+      end
+
+    ensure
+      #
+      # Make sure to restore the default config_tookit_config after
+      # this test.
+      #
+      MachineConfig.send(:default_config_toolkit_config=, MachineConfig::CONFIG_TOOLKIT_CONFIG)
+    end
+      
+  end
 end

data/test/test_configtoolkitconfig.rb

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+require 'configtoolkit'
+
+require 'rubygems'
+require 'assertions'
+
+require 'test/unit'
+
+class ConfigToolkitConfigTest < Test::Unit::TestCase
+
+  def test_new
+    config1 = ConfigToolkit::ConfigToolkitConfig.new() # empty configuration
+
+    config2 = ConfigToolkit::ConfigToolkitConfig.new() {} # default
+
+    config3 = ConfigToolkit::ConfigToolkitConfig.new() do |config|
+      config.unknown_config_param_behavior = ConfigToolkit::ConfigToolkitConfig::UnknownConfigParamBehavior::WARN
+    end
+    assert_equal(ConfigToolkit::ConfigToolkitConfig::UnknownConfigParamBehavior::WARN, config3.unknown_config_param_behavior)
+
+    assert_raise_message("error setting unknown_config_param_behavior with value boo: boo is not a valid unknown_config_param_behavior value.", ConfigToolkit::Error) do
+      config3.unknown_config_param_behavior = :boo
+    end
+  end
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: configtoolkit
 version: !ruby/object:Gem::Version 
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors: 
 - DesigningPatterns
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-07-29 00:00:00 -04:00
+date: 2009-06-09 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -40,7 +40,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.7.0
+        version: 1.8.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. * 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: 
@@ -71,6 +71,7 @@ files:
 - Ruby.txt
 - YAML.txt
 - Rakefile
+- examples/config_toolkit_config_example.rb
 - examples/hash_example.rb
 - examples/key_value_example.rb
 - examples/load_example.rb
@@ -81,6 +82,7 @@ files:
 - examples/ruby_example.rb
 - examples/usage_example.rb
 - examples/yaml_example.rb
+- examples/config_toolkit_config_example.yaml
 - examples/load_example.yaml
 - examples/load_group_example.yaml
 - examples/override_example_override.yaml
@@ -94,6 +96,7 @@ files:
 - examples/ruby_example.rcfg
 - lib/configtoolkit.rb
 - lib/configtoolkit/baseconfig.rb
+- lib/configtoolkit/configtoolkitconfig.rb
 - lib/configtoolkit/hasharrayvisitor.rb
 - lib/configtoolkit/hashreader.rb
 - lib/configtoolkit/hashwriter.rb
@@ -112,6 +115,7 @@ files:
 - rdoc_support/rdoc-2.1.0.patch
 - test/readerwritertest.rb
 - test/test_baseconfig.rb
+- test/test_configtoolkitconfig.rb
 - test/test_hash.rb
 - test/test_keyvalue.rb
 - test/test_override.rb
@@ -157,7 +161,7 @@ files:
 - test/contained_sample.rcfg
 - test/sample.rcfg
 has_rdoc: true
-homepage: "Project Page: http://rubyforge.org/projects/configtoolkit/"
+homepage: This package makes sourcing information from (parsing) configuration files
 post_install_message: 
 rdoc_options: 
 - --main
@@ -188,6 +192,7 @@ test_files:
 - test/test_override.rb
 - test/test_ruby.rb
 - test/test_yaml.rb
+- test/test_configtoolkitconfig.rb
 - test/test_keyvalue.rb
 - test/test_prettyprint.rb
 - test/test_hash.rb