configtoolkit 1.2.0 → 2.0.0

data/Manifest.txt

@@ -1,18 +1,51 @@
 Manifest.txt
 LICENSE
-README.txt
 History.txt
-Rakefile
 FAQ.txt
+Hash.txt
+KeyValue.txt
+README.txt
+Ruby.txt
+YAML.txt
+Rakefile
+examples/hash_example.rb
+examples/key_value_example.rb
+examples/load_example.rb
+examples/load_group_example.rb
+examples/machineconfig.rb
+examples/ruby_example.rb
+examples/usage_example.rb
+examples/yaml_example.rb
+examples/load_example.yaml
+examples/load_group_example.yaml
+examples/yaml_example.dump.yaml
+examples/yaml_example.yaml
+examples/key_value_example.dump.cfg
+examples/key_value_example.normal1.cfg
+examples/key_value_example.normal2.cfg
+examples/key_value_example.wacky.cfg
+examples/ruby_example.rcfg
 lib/configtoolkit.rb
 lib/configtoolkit/baseconfig.rb
-lib/configtoolkit/toolkit.rb
+lib/configtoolkit/hasharrayvisitor.rb
+lib/configtoolkit/hashreader.rb
+lib/configtoolkit/hashwriter.rb
+lib/configtoolkit/keyvalueconfig.rb
+lib/configtoolkit/keyvaluereader.rb
+lib/configtoolkit/keyvaluewriter.rb
+lib/configtoolkit/prettyprintwriter.rb
+lib/configtoolkit/reader.rb
+lib/configtoolkit/rubyreader.rb
 lib/configtoolkit/types.rb
+lib/configtoolkit/writer.rb
 lib/configtoolkit/yamlreader.rb
 lib/configtoolkit/yamlwriter.rb
-test/common.rb
 test/readerwritertest.rb
 test/test_baseconfig.rb
+test/test_hash.rb
+test/test_keyvalue.rb
+test/test_prettyprint.rb
+test/test_ruby.rb
 test/test_yaml.rb
 test/bad_config.yaml
 test/contained_sample.yaml
@@ -21,3 +54,32 @@ test/machines.yaml
 test/sample.ruby_yaml_classes.yaml
 test/sample.standard_yaml_classes.yaml
 test/webserver.yaml
+test/bad_directive.cfg
+test/bad_include1.cfg
+test/bad_include2.cfg
+test/contained_sample.cfg
+test/containers.cfg
+test/exta_string_after_container.cfg
+test/extra_container_closing.cfg
+test/extra_string_after_container.cfg
+test/extra_string_after_nested_container.cfg
+test/missing_array_closing.cfg
+test/missing_array_element.cfg
+test/missing_directive.cfg
+test/missing_hash_closing.cfg
+test/missing_hash_element.cfg
+test/missing_hash_value.cfg
+test/missing_include_argument.cfg
+test/missing_key_value_delimiter.cfg
+test/sample.cfg
+test/wacky_sample1.cfg
+test/wacky_sample2.cfg
+test/wacky_sample3.cfg
+test/wacky_sample4.cfg
+test/contained_sample.pretty_print
+test/sample.pretty_print
+test/bad_array_index.rcfg
+test/bad_containing_object_assignment.rcfg
+test/bad_parameter_reference.rcfg
+test/contained_sample.rcfg
+test/sample.rcfg

data/README.txt

@@ -1,9 +1,8 @@
 = configtoolkit
-
-Project Page: http://rubyforge.org/projects/configtoolkit/
+* Project Page: http://rubyforge.org/projects/configtoolkit/
+* Documentation: http://configtoolkit.rubyforge.org/
 
 == DESCRIPTION:
-
 This package makes sourcing information from configuration files robust
 and easy!  It:
 * Allows programmers to specify the type of data that should be loaded
@@ -11,268 +10,733 @@ and easy!  It:
   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, an equality operator,
-  and a to_s method from the configuration's specification.
+* 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 classes that can load from and dump to different kinds of
+* Provides a class that can load Ruby configuration files (allowing the
+  full power of Ruby to be used within configuration files).
+* Provides classes that can load from 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.
 
 == FEATURES:
-
 * The ConfigToolkit allows programmers to define a new configuration class by
   specifying the parameters that are included in the configuration.  A
   parameter specification consists of the class of the parameter's values,
   whether or not the paramater is required, and a default value if the
   parameter is not required.
-* Getter and setter methods automatically are added to a new configuration
-  class for each specified parameter.
+* Getter, setter, and predicate methods automatically are generated for a new
+  configuration class for each specified parameter to get the parameter's
+  value, set the parameter's value, and test whether the parameter has a value.
+* A method to clear a parameter's value automatically is generated for
+  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).
+* +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
   determines equality based on whether all parameter values are equal.
-* A to_s method that produces very pretty output exists for each
-  configuration class.
+* A +to_s+ method that produces very pretty output exists for each
+  configuration class (ConfigToolkit::BaseConfig#to_s, leveraging the
+  ConfigToolkit::PrettyPrintWriter)
 * Programmers can specify custom validation blocks for each parameter, in
   order to enforce specifications not directly supported by the engine.
 * Programmers can define a method in a configuration class that will be
   called in order to enforce relationships between the values of different
-  parameters.
+  parameters (ConfigToolkit::BaseConfig#validate_all_values)
 * Programmers can create custom reader and writer classes in order to
   load from and dump to (respectively) configuration file formats not
   directly supported by the ConfigToolkit.
 * Configuration classes can be nested to any depth within each other.
 * Configuration classes have first class support for Array configuration
   parameters.  Constraints can be specified for a given Array parameter that
-  will ensure that all elements of a value are of a
-  specified class and that there are a specified number of elements in
-  a value.
+  will ensure that all elements are of a specified class and that there
+  are a specified number of elements present (see
+  ConfigToolkit::ConstrainedArray)
 * The ConfigToolkit supports multiple configurations stored
   in a single file; it is able to distinguish that different configurations
   within a file belong to different configuration objects.  For example,
   "production" and "test" configuration information can live within the
   same configuration file and can be loaded into separate configuration
-  instances.
-* A reader class to read YAML configuration files is included in the
-  Configtoolkit.
-* A writer class to dump YAML configuration files is included in the
-  Configtoolkit.
+  instances (by specifying a different "containing object name" for each
+  ConfigToolkit::BaseConfig#load call)
+* A reader class to read Ruby configuration files
+  (ConfigToolkit::RubyReader)
+* A reader class to read YAML configuration files
+  (ConfigToolkit::YAMLReader)
+* A writer class to dump YAML configuration files
+  (ConfigToolkit::YAMLWriter)
+* A reader class to load configuration directly from a Hash
+  (ConfigToolkit::HashReader)
+* A writer class do dump configuration directly to a Hash
+  (ConfigToolkit::HashWriter)
+* A reader class to read key-value configuration files
+  (ConfigToolkit::KeyValueReader)
+* A writer class to dump key-value configuration files
+  (ConfigToolkit::KeyValueWriter)
+* The ConfigToolkit::KeyValueReader and ConfigToolkit::KeyValueWriter classes
+  can be configured to work with many different formats of key-value
+  configuration files (via ConfigToolkit::KeyValueConfig).
 * The ConfigToolkit includes a full unit testing suite.
 * The ConfigToolkit code has detailed comments.
+* The ConfigToolkit code has many example programs (in the +examples+
+  subdirectory).
+* The ConfigToolkit package includesx extensive documentation, including
+  FAQ.txt and documentation for the support file formats.
 
 == PROBLEMS:
-
 None (known).
 
 == SYNOPSIS:
-
-This is a sample configuration class:
-  require 'rubygems'
-  require 'configtoolkit'
-
-  class MachineConfig < ConfigToolkit::BaseConfig
-    add_required_param(:name, String)
-
-    add_required_param(:architecture, String)
-
-    add_required_param(:os, String)
-
-    add_required_param(:num_cpus, Integer) do |value|
-      if(value <= 0)
-        raise_error("num_cpus must be greater than zero")
-      end
-    end
-
-    add_optional_param(:behind_firewall, ConfigToolkit::Boolean, true)
-
-    add_required_param(:contains_sensitive_data, ConfigToolkit::Boolean)
-
-    add_required_param(:addresses, ConfigToolkit::ConstrainedArray.new(URI, 2, 3))
-
-    def validate_all_values
-      if(contains_sensitive_data && !behind_firewall)
-        raise_error("a machine cannot contain sensitive data and not be behind the firewall")
-      end
-    end
-  end
-
-This code creates a configuration class for a company's servers.  The
-programmer specifies each of the parameters (the parameter's class, whether
-the parameter is required, and a default value if the parameter is optional).
-
-The programmer also specifies a method (<code>validate_all_values</code>)
-that enforces an invariant between multiple parameters.  This will be called
-by the ConfigToolkit at the end of a load or at the start of a dump operation.
-
-A custom validation block is specified for the <code>num_cpus</code> parameter;
+Here is a sample configuration class:
+======+examples/machineconfig.rb+:
+ require 'rubygems'
+ require 'configtoolkit'
+ 
+ require 'uri'
+ 
+ #
+ # This configuration class is nested within MachineConfig (below).
+ # All configuration classes must descend from ConfigToolkit::BaseConfig.
+ #
+ class OSConfig < ConfigToolkit::BaseConfig
+   add_required_param(:name, String)
+   add_required_param(:version, Float)
+ end
+ 
+ #
+ # This configuration class is used in all of the example programs.
+ # Since it is a configuration class, it descends from
+ # ConfigToolkit::BaseConfig.
+ #
+ class MachineConfig < ConfigToolkit::BaseConfig
+   #
+   # This is a required parameter with extra user-specified validation
+   # (that :num_cpus > 0 must be true)
+   #
+   add_required_param(:num_cpus, Integer) do |value|
+     if(value <= 0)
+       raise_error("num_cpus must be greater than zero")
+     end
+   end
+ 
+   #
+   # This required parameter is itself a BaseConfig instance; BaseConfig
+   # instances can be nested within each other.
+   #
+   add_required_param(:os, OSConfig)
+   
+   #
+   # This is a required boolean parameter.  Note that Ruby does not
+   # have a boolean type (it has a TrueClass and a FalseClass), so use
+   # a marker class (ConfigToolkit::Boolean) to indicate that
+   # the parameter will have boolean values (true and false).
+   # Boolean values can be written as "true"/"false" or as
+   # "yes"/"no" in configuration files.
+   #
+   add_required_param(:contains_sensitive_data, ConfigToolkit::Boolean)
+ 
+   #
+   # The behind_firewall parameter is optional and has a default value of
+   # true, which means that it will be set to the true if not explicitly set
+   # by a configuration file.
+   #
+   add_optional_param(:behind_firewall, ConfigToolkit::Boolean, true)
+ 
+   #
+   # The primary_contact parameter is optional and has no default value, which
+   # means that it will be absent if not explicitly set by a configuration file.
+   #
+   add_optional_param(:primary_contact, String)
+   
+   #
+   # This parameter's values are guaranteed to be Arrays with URI elements.
+   #
+   add_required_param(:addresses, ConfigToolkit::ConstrainedArray.new(URI))
+ 
+   #
+   # This method is called by load() after loading values for
+   # all parameters from a specified configuration and can enforce
+   # constraints between different parameters.  In this case, this method
+   # ensures that all machines containing sensitive data are behind
+   # the firewall.
+   #
+   def validate_all_values
+     if(contains_sensitive_data && !behind_firewall)
+       raise_error("only machines behind firewalls can contain sensitive data")
+     end
+   end
+ end
+
+
+This code creates a configuration class for a company's servers by subclassing
+ConfigToolkit::BaseConfig.  Each of the parameters is specified (the
+parameter's class, whether the parameter is required, and a default value
+if the parameter is optional) with private class methods of 
+ConfigToolkit::BaseConfig (ConfigToolkit::BaseConfig.add_required_param and
+ConfigToolkit::BaseConfig.add_optional_param).
+
+A +validate_all_values+ method also is defined in the +MachineConfig+
+class that enforces an invariant between multiple parameters.  This will be
+called at the end of ConfigToolkit::BaseConfig#load or at the start of
+ConfigToolkit::BaseConfig#dump (see
+ConfigToolkit::BaseConfig#validate_all_values for more details).
+
+A custom validation block is specified for the +num_cpus+ parameter;
 the ConfigToolkit engine does not have direct support for
 checking specifications like "the value must be greater than zero", but these
 conditions easily can be added by the programmer.  Such blocks are
 called by the engine before the configuration parameter is set to the new
 value and are executed in the context of the configuration class instance.
 If there is a problem with the new value, the block should call
-<code>ConfigToolkit::BaseConfig#raise_error</code>.
+ConfigToolkit::BaseConfig#raise_error.
 
 A ConfigToolkit::Boolean class is specified for the
-<code>behind_firewall</code> and <code>contains_sensitive_data</code>
++behind_firewall+ and +contains_sensitive_data+
 parameters.  Ruby does not have a standard boolean
 class (although it does have TrueClass and FalseClass, for boolean values), and
 so the ConfigToolkit provides a marker class for boolean values.  The value
-of a parameter specified with ConfigToolkit::Boolean either is true or false.
+of a parameter specified with ConfigToolkit::Boolean either is +true+ or
++false+.
 
-A <code>ConfigToolkit::ConstrainedArray.new(URI, 2, 3)</code> class is
-specified for the <code>addresses</code> parameter.  A
+A ConfigToolkit::ConstrainedArray.new(URI) class is
+specified for the +addresses+ parameter.  A
 ConfigToolkit::ConstrainedArray class simply specifies that the
 parameter value will be an Array that obeys the
 constraints contained in the ConfigToolkit::ConstrainedArray.  In this
 case, the constraints ensure that all Array elements are of class URI,
-that the Array has at least two elements, and that the Array has at most
-three elements.
-
-The following machines.yaml file contains two MachineConfig configurations:
-  name: apple
-  architecture: powerpc
-  os: AIX
-  num_cpus: 32
-  behind_firewall: no
-  contains_sensitive_data: no
-  addresses:
-    - http://default.designingpatterns.com
-    - http://apple.designingpatterns.com
-
-  production:
-    tokyo:
-      name: orange
-      architecture: ultrasparc
-      os: Solaris
-      num_cpus: 64
-      contains_sensitive_data: yes
-      addresses:
-        - http://production.designingpatterns.com
-        - http://orange.designingpatterns.com
-
-The first configuration in the file:
-  name: apple
-  architecture: powerpc
-  os: AIX
-  num_cpus: 32
-  behind_firewall: no
-  contains_sensitive_data: no
-  addresses:
-    - http://default.designingpatterns.com
-    - http://apple.designingpatterns.com
-can be loaded into a MachineConfig instance like this:
-  require 'rubygems'
-  require 'configtoolkit'
-  require 'configtoolkit/yamlreader'
-
-  config = MachineConfig.load(ConfigToolkit::YAMLReader.new("machines.yaml"))
-
-The second configuration:
-  production:
-    tokyo:
-      name: orange
-      architecture: ultrasparc
-      os: Solaris
-      num_cpus: 64
-      contains_sensitive_data: yes
-      addresses:
-        - http://production.designingpatterns.com
-        - http://orange.designingpatterns.com
-can be loaded by specifying a "containing object" in the load call.
-A containing object simply is an object in a configuration file within
-which a config object is stored.  In this case, the containing
-object is "production.tokyo".  So:
-  require 'rubygems'
-  require 'configtoolkit'
-  require 'configtoolkit/yamlreader'
-
-  config = MachineConfig.load(ConfigToolkit::YAMLReader.new("machines.yaml"), "production.tokyo")
-will load the second configuration in machines.yaml.
-
-A MachineConfig instance can be dumped like this:
-  require 'rubygems'
-  require 'configtoolkit'
-  require 'configtoolkit/yamlreader'
-  require 'configtoolkit/yamlwriter'
-
-  config = MachineConfig.load(ConfigToolkit::YAMLReader.new("machines.yaml"))  
-  config.dump(ConfigToolkit::YAMLWriter.new("apple.yaml", true))
-
-This will produce the following apple.yaml:
-  --- 
-  name: apple
-  contains_sensitive_data: false
-  addresses: 
-  - http://default.designingpatterns.com
-  - http://apple.designingpatterns.com
-  os: AIX
-  architecture: powerpc
-  num_cpus: 32
-  behind_firewall: false
-
-To load a group of named configurations at once from this machines.yaml file:
-  db_cluster:
-    db1:
-      name: cherry
-      architecture: powerpc
-      os: Linux
-      num_cpus: 24
-      contains_sensitive_data: yes
-      addresses:
-        - http://cherrydb.designingpatterns.com
-        - http://db1.designingpatterns.com
-    db2:
-      name: strawberry
-      architecture: powerpc
-      os: Linux
-      num_cpus: 24
-      contains_sensitive_data: yes
-      addresses:
-        - http://strawberrydb.designingpatterns.com
-        - http://db2.designingpatterns.com
-    db3:
-      name: blueberry
-      architecture: powerpc
-      os: Linux
-      num_cpus: 24
-      contains_sensitive_data: yes
-      addresses:
-        - http://blueberrydb.designingpatterns.com
-        - http://db3.designingpatterns.com
-
-do:
-  require 'rubygems'
-  require 'configtoolkit'
-  require 'configtoolkit/yamlreader'
-
-  configs = MachineConfig.load_group(ConfigToolkit::YAMLReader.new("machines.yaml"), "db_cluster")
-  configs.each do |name, config|
-    print "The #{name} configuration:\n#{config}\n"
-  end
+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+:
+ #!/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'
+ 
+ #
+ # If new() is passed a block, the block *must* initialize all
+ # required parameters (otherwise a ConfigToolkit::Error will
+ # be thrown).  Optional parameters to not need to be
+ # explicitly initialized, however.  If a default value was
+ # specified for an uninitialized optional parameter, the 
+ # optional parameter will be set to the default value after
+ # the block (the behind_firewall parameter is an example of this below);
+ # otherwise, the default value will have no value
+ # (the primary_contact parameter is an example of this below).
+ #
+ config = MachineConfig.new() do |config|
+   config.num_cpus = 8
+   config.os = OSConfig.new() do |os_config|
+     os_config.name = "Solaris"
+     os_config.version = 10.0
+   end
+   config.contains_sensitive_data = true
+   config.addresses = [URI("http://www.designingpatterns.com"),
+                       URI("http://jackfruit.designingpatterns.com")]
+ end
+ 
+ #
+ # Note in the output that the behind_firewall parameter is true, its
+ # default value, because it was not initialized in the block above.
+ # Also note that the primary_contact parameter is not present.
+ #
+ print "Config after initialization:\n#{config}\n"
+ 
+ #
+ # Each parameter has a predicate method (automatically generated by
+ # add_required_param or add_optional_param) that returns whether or not
+ # the parameter has a value.
+ #
+ if(!config.primary_contact?)
+   #
+   # This will be printed...
+   #
+   print "Optional primary_contact parameter is NOT set!\n"
+ end
+ 
+ #
+ # Each parameter has getter and setter accessor methods (automatically
+ # generated by add_required_param or add_optional_param), just like
+ # "normal" attributes.
+ #
+ config.primary_contact = "Tony"
+ print("primary_contact parameter set to: #{config.primary_contact}\n")
+ 
+ if(config.primary_contact?)
+   #
+   # This will be printed...
+   #
+   print "Optional primary_contact parameter is now IS set!\n\n"
+ end
+ 
+ #
+ # Note in the output that the primary_contact parameter *now* is present.
+ #
+ print "Config after setting optional primary_contact parameter:\n#{config}\n"
+ 
+ #
+ # Each optional parameter has a clear method (automatically generated by
+ # add_optional_param) that deletes the parameter's value.
+ #
+ config.clear_primary_contact()
+ 
+ if(!config.primary_contact?)
+   #
+   # This will be printed...
+   #
+   print "Optional primary_contact parameter has been deleted!\n\n"
+ end
+ 
+ #
+ # Note in the output that the primary_contact parameter once again
+ # is absent.
+ #
+ print "Config after deleting the primary_contact parameter:\n#{config}\n"
+
+This example uses the accessor methods (a getter, a setter, and a predicate)
+that are generated automatically for each configuration parameter.  These
+allow configuration instances to be manipulated in the same way that
+instances of a hand-written configuration class could be manipulated.  Note,
+however, that the same strict validation is performed for values specified
+programatically through setters as is done for values sourced from
+configuration files.  Also note that setters copy the *values* of their
+arguments (with the +dup+ method) not *references* to their arguments, unlike
+the setters created by the +attr_accessor+ method.
+When run, it produces:
+======The output of <code>examples/usage_example.rb</code>:
+ Config after initialization:
+ {
+     contains_sensitive_data: true
+     num_cpus               : 8
+     addresses              : [
+         http://www.designingpatterns.com,
+         http://jackfruit.designingpatterns.com
+     ]
+     behind_firewall        : true
+     os                     : {
+         version: 10.0
+         name   : Solaris
+     }
+ }
+ 
+ Optional primary_contact parameter is NOT set!
+ primary_contact parameter set to: Tony
+ Optional primary_contact parameter is now IS set!
+ 
+ Config after setting optional primary_contact parameter:
+ {
+     contains_sensitive_data: true
+     num_cpus               : 8
+     addresses              : [
+         http://www.designingpatterns.com,
+         http://jackfruit.designingpatterns.com
+     ]
+     behind_firewall        : true
+     os                     : {
+         version: 10.0
+         name   : Solaris
+     }
+     primary_contact        : Tony
+ }
+ 
+ Optional primary_contact parameter has been deleted!
+ 
+ Config after deleting the primary_contact parameter:
+ {
+     contains_sensitive_data: true
+     num_cpus               : 8
+     addresses              : [
+         http://www.designingpatterns.com,
+         http://jackfruit.designingpatterns.com
+     ]
+     behind_firewall        : true
+     os                     : {
+         version: 10.0
+         name   : Solaris
+     }
+ }
+ 
+
+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+:
+ #
+ # This file contains MachineConfig configurations
+ # (see examples/machineconfig.rb for the configuration's specification).
+ #
+ 
+ ############################################################
+ # First configuration
+ 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
+ ############################################################
+ 
+ # production is a containing object
+ production:
+ # production.www is a containing object
+   www:
+ ############################################################
+ # Second configuration (nested in the production.www
+ # containing object)
+     num_cpus: 64
+     os:
+       name: Solaris
+       version: 10.0
+     contains_sensitive_data: yes
+     addresses:
+       - http://www.designingpatterns.com
+       - http://tokyo.designingpatterns.com
+ ############################################################
+
+The following program loads and prints the two configurations from
++examples/load_example.yaml+.
+======+examples/load_example.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'
+ 
+ CONFIGURATION_FILE = File.expand_path_relative_to_caller("load_example.yaml")
+ 
+ #
+ # The first configuration has no containing object name.
+ #
+ reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+ first_config = MachineConfig.load(reader)
+ print("The first config:\n#{first_config}\n")
+ 
+ #
+ # The second configuration has "production.www" as a containing
+ # object name.
+ #
+ reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+ second_config = MachineConfig.load(reader, "production.www")
+ print("The second config:\n#{second_config}\n")
+
+Note how the program changes the containing object name passed to the +load+
+method (first an empty string, next +production.www+, and finally
++production.mail+) in order to refer to different configurations within
+the YAML file.  The ConfigToolkit's support of containing objects allows it
+to accomodate multiple configurations living in the same file, with each
+configuration being accessible separately.  When run, it produces:
+======The output of <code>examples/load_example.rb</code>:
+ The first config:
+ {
+     os                     : {
+         name   : AIX
+         version: 5.3
+     }
+     behind_firewall        : false
+     num_cpus               : 32
+     addresses              : [
+         http://default.designingpatterns.com,
+         http://apple.designingpatterns.com
+     ]
+     contains_sensitive_data: false
+ }
+ 
+ The second config:
+ production.www: {
+     os                     : {
+         name   : Solaris
+         version: 10.0
+     }
+     behind_firewall        : true
+     num_cpus               : 64
+     addresses              : [
+         http://www.designingpatterns.com,
+         http://tokyo.designingpatterns.com
+     ]
+     contains_sensitive_data: true
+ }
+ 
+
+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+:
+ #
+ # 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
+
+the following code will load the file's three configurations into a +Hash+ 
+mapping containing object names to configurations:
+======+examples/load_group_example.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'
+ 
+ CONFIGURATION_FILE =
+  File.expand_path_relative_to_caller("load_group_example.yaml")
+ 
+ #
+ # The group of configurations is under the db_cluster containing
+ # object name.
+ #
+ reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+ 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 output of <code>examples/load_group_example.rb</code>:
+ The db1 configuration:
+ db_cluster.db1: {
+     os                     : {
+         version: 10.0
+         name   : Solaris
+     }
+     behind_firewall        : true
+     num_cpus               : 16
+     addresses              : [
+         http://db1.designingpatterns.com
+     ]
+     contains_sensitive_data: true
+ }
+ 
+ The db2 configuration:
+ db_cluster.db2: {
+     os                     : {
+         version: 5.3
+         name   : AIX
+     }
+     behind_firewall        : true
+     num_cpus               : 12
+     addresses              : [
+         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
+ }
+ 
+
+
+== CONFIGURATION FILE FORMATS:
+=== EXISTING FORMATS:
+* 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.
+
+=== NEW FORMATS:
+The ConfigToolkit easily can be extended to support new file formats.  A new
+reader class can be created to load from a new format, and a new writer class
+can be created to write out a new format.
+
+The reader interface is documented by the ConfigToolkit::Reader class.
+Basically, a reader needs to have a read method that reads data from some
+underlying stream and returns a Hash that represents the configuration (see
+ConfigToolkit::Reader#read for the specifications;
+ConfigToolkit::YAMLReader#read is a simple example of an implementation).
+ConfigToolkit::HashReader is a no-op reader, so the Hash that its constructor
+accepts is the same that a new reader class should return from its
++read+ method.
+
+The writer interface is documented by the ConfigToolkit::Writer class.
+Basically, a writer needs to have a write method that accepts a Hash
+representing a configuration and writes it to some underlying stream (see
+ConfigToolkit::Writer#write for the specifications;
+ConfigToolkit::YAMLWriter#write is a relatively simple example of an
+implementation).  ConfigToolkit::HashWriter is a no-op writer, so the Hash
+stored in its +config_hash+ attribute after a ConfigToolkit::BaseConfig#dump
+call is the same Hash passed to a writer's +write+ method.
+
+While writing a new reader or writer class, it may be necessary to iterate
+over a Hash that contains arbitrarily deeply nested Hashes and Arrays.  The
+ConfigToolkit::HashArrayVisitor can help with this task by allowing hook
+functions to be written that will be called when a particular type of node
+is visited.  ConfigToolkit::YAMLWriter#write,
+ConfigToolkit::KeyValueWriter#write and ConfigToolkit::PrettyPrintWriter#write
+all use such visitors.
+
+Feel free also to request that we add support for a new file format to the
+distribution, and we will try our best to accomodate!  See below for some
+ideas that we have had for new readers and writers.
+
+== CONFIGURATION CLASS DOCUMENTATION:
+Configuration classes *can* be documented properly by +rdoc+, although not by
+default.  See FAQ.txt for full details.
 
 == REQUIREMENTS:
-
-Hoe is required, but only for running the tests.
+Hoe, assertions, and relative are required, but only for running the tests.
+Relative also is required for running the examples.
 
 == INSTALL:
-
-sudo gem install configtoolkit
+ sudo gem install configtoolkit
+
+== POSSIBLE FUTURE TECHNICAL DIRECTIONS:
+Here are some *possible* ideas:
+* Modify the ConfigToolkit and/or +rdoc+ so that +rdoc+ produces good
+  documentation for configuration classes (perhaps showing parameter value
+  classes and any default values).  This enhancement should eliminate
+  any need to patch +rdoc+ (see FAQ.txt for the current procedure).
+* Provide support for sourcing configuration from XML files
+  (+XMLReader+ and +XMLWriter+ classes)
+* Provide support for sourcing configuration from INI files
+  (+INIReader+ and +INIWriter+ classes)
+* Provide support for sourcing configuration from command-line parameters
+  (+CommandLineReader+ and +CommandLineWriter+ classes)
+* Provide support for sourcing configuration from environment variables
+  (+EnvVarReader+ and +EnvVarWriter+ classes)
+* Provide support for sourcing configuration from a database
+  (+DatabaseReader+ and +DatabaseWriter+ classes)
+* Provide support for sourcing configuration from a configuration file (of
+  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
+  interface to create new parameter rules.
+* Allow user-specified conversions from Strings to arbitrary types for
+  configuration file formats that only have a limited type palette (key-value
+  files, for instance).
+* Allow other languages to use the ConfigToolkit (possible targets could
+  be C++, Python, or Java)
+* Provide a ConfigToolkit::BaseConfig class method "constructor" that would
+  allocate any nested config instances and Arrays (recursively, so that
+  and multiply-nested config instances and Arrays also would be initialized).
+  This would make programatically setting the configuration parameters
+  very easy, since no explicit +new+ calls would be necessary for the
+  nested config object and Array parameters.
+
+We would love to receive input from users about which new features are most
+desirable!
 
 == AUTHORS:
-
-Designing Patterns: http://www.designingpatterns.com
-
-Share and Enjoy!
+=== Designing Patterns
+* Homepage: http://www.designingpatterns.com
+* Blogs: http://blogs.designingpatterns.com
 
 == 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.
-Please discuss any enhancements with the authors (Designing Patterns)
-before doing any work.
+
+== 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
+who want it.  Designing Patterns provides contracting and consulting services,
+so if there is an enhancement that *must* get done (and in a specified time
+frame), please inquire about retaining our services!
 
 == LICENSE:
+The license text can be found in the +LICENSE+ file at the root of the
+distribution.
+
+This  package is licensed with an MIT license:
+
+Copyright (c) 2008 Designing Patterns
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-See LICENSE, at the root of the distribution.
+== SHARE AND ENJOY!