configtoolkit 1.2.0 → 2.0.0

data/examples/yaml_example.dump.yaml

@@ -0,0 +1,12 @@
+--- 
+production: 
+  www: 
+    contains_sensitive_data: true
+    addresses: 
+    - http://www.designingpatterns.com
+    - http://tokyo.designingpatterns.com
+    os: 
+      name: Solaris
+      version: 10.0
+    num_cpus: 64
+    behind_firewall: true

data/examples/yaml_example.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/yamlwriter'
+
+CONFIGURATION_FILE = File.expand_path_relative_to_caller("yaml_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.  Note that the second configuration
+# reprents the URI elements of the addresses parameter array
+# as Ruby URI classes, leveraging Ruby's ability to unserialize
+# objects from YAML.
+#
+reader = ConfigToolkit::YAMLReader.new(CONFIGURATION_FILE)
+second_config = MachineConfig.load(reader, "production.www")
+print("The second config:\n#{second_config}\n")
+
+#
+# Write second_config to a string stream, which then is written to
+# stdout.  Pass true as the second argument to new in order to specify that
+# the writer only should write native YAML types (Strings, integers, floats,
+# booleans, etc.).
+#
+string_stream = StringIO.new()
+writer = ConfigToolkit::YAMLWriter.new(string_stream, true)
+second_config.dump(writer)
+print("The second configuration written in YAML with native YAML types:\n")
+print("#{string_stream.string}")

data/examples/yaml_example.yaml

@@ -0,0 +1,59 @@
+#
+# 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:
+############################################################
+# Second configuration (nested in the production.www
+# containing object).  Note that the elements of the
+# addresses parameter array are expressed
+# not as strings, as in the first configuration, but rather
+# as serialized Ruby URI instances.  The YAMLReader class
+# can read both, and the YAMLWriter class can
+# output values of either only YAML native types or of serialized Ruby
+# classes.
+  www:
+    contains_sensitive_data: true
+    addresses: 
+    - !ruby/object:URI::HTTP 
+      fragment: 
+      host: www.designingpatterns.com
+      opaque: 
+      password: 
+      path: ""
+      port: 80
+      query: 
+      registry: 
+      scheme: http
+      user: 
+    - !ruby/object:URI::HTTP 
+      fragment: 
+      host: tokyo.designingpatterns.com
+      opaque: 
+      password: 
+      path: ""
+      port: 80
+      query: 
+      registry: 
+      scheme: http
+      user: 
+    os: 
+      name: Solaris
+      version: 10.0
+    num_cpus: 64
+    behind_firewall: true
+############################################################

data/lib/configtoolkit.rb

@@ -1,2 +1,2 @@
 #!/usr/bin/env ruby
-require 'configtoolkit/toolkit'
+require 'configtoolkit/baseconfig'

data/lib/configtoolkit/baseconfig.rb

@@ -1,42 +1,63 @@
 #!/usr/bin/env ruby
 
+require 'configtoolkit/types'
+require 'configtoolkit/prettyprintwriter.rb'
+
 require 'pathname'
 require 'set'
+require 'stringio'
 require 'uri'
 
 module ConfigToolkit
 
 #
-# This class represents a configuration.  It provides configuration
-# specification, loading, and dumping functionality.  A BaseConfig
-# configuration can contain "scalars" (anything except an array or
-# nested configuration class), ConstrainedArrays (arrays), and other
-# BaseConfig child classes (which can be thought of as hashes).
-# Note that ConstrainedArrays and other BaseConfig
-# classes recursively can contain anything the parent BaseConfig can contain,
-# so nesting to any depth is supported.
+# This class can be subclassed to create a class representing a configuration.
+# It provides configuration specification, loading, and dumping functionality.
+# A BaseConfig configuration can contain "scalar" parameters (anything except
+# an array or nested configuration class), ConstrainedArray
+# parameters (arrays), and other BaseConfig child classes parameters (which can
+# be thought of as hashes).  Note that nested ConstrainedArray
+# and BaseConfig config parameters recursively can contain anything the parent
+# BaseConfig can contain, so nesting arrays and configuration classes to any
+# depth is supported.
+#
+# A BaseConfig child instance has getter, setter, and predicate methods for each
+# parameter.  The predicate method for a parameter returns whether or not the
+# parameter has a value and is named +param_name?+.  An optional parameter
+# also has a method to clear its value from the configuration (after this the
+# predicate method will return +false+); the clear method is named
+# +clear_param_name+.
 #
-# BaseConfig neither parses nor writes to files directly, but instead does so
-# through reader and writer classes (respectively) specified by the
-# programmer.  This allows BaseConfig to support virtually any underlying
-# configuration file format (including YAML, UNIX key/value pairs, etc).
-# BaseConfig expects reader classes to contain a read method that sources
-# configuration information and returns a hash that maps strings
+# BaseConfig neither parses from nor writes to configuration files directly
+# but instead does so through reader (Reader) and
+# writer (Writer) classes specified by the programmer.
+# This allows BaseConfig to support virtually any underlying
+# configuration file format (including YAML, key/value pairs, etc).
+# BaseConfig expects reader classes to contain a +read+ method that sources
+# configuration information and returns a Hash that maps Symbols or Strings
 # (parameter names) to values, which can themselves
-# be hashes or arrays.  It expects writer classes to in turn support a write
-# method that accepts such a hash and writes it to some underlying stream.
+# be Hashes or Arrays.  It expects writer classes to support a +write+ method
+# that in turn accepts such a Hash and writes it to some underlying stream.
 # The reader and writer implementations used have no effect on BaseConfig's
-# validation functionality; data from whatever source (even specified
-# programatically via setters) always fully is validated.
+# validation functionality; data from any source (even specified
+# programatically via setters) always is validated fully.
 #
 # Programmers wishing to create their own configuration classes
 # should extend BaseConfig and, in the body of their class' definition,
 # call add_required_param and add_optional_param for each parameter
 # they wish to specify.  If they wish to enforce a relationship between
-# parameters, then they also can define validate_all_values.
+# parameters, they also can override validate_all_values.
 #
 class BaseConfig
-  
+  #
+  # This constant can be passed to add_optional_param in order to
+  # indicate that the parameter has no default value.  The actual value of
+  # the constant does not matter in the least, so long as it
+  # never could be a real default value (a gemsym() function would be
+  # handy here to generate a unique symbol).
+  #
+  NO_DEFAULT_VALUE = :baseconfig_no_default_value
+
   #
   # This class represents the specification for a parameter.  Right now,
   # a parameter specification consists of:
@@ -46,14 +67,15 @@ class BaseConfig
   # * Whether or not the parameter is required
   # * If the parameter is not required, a default value
   #
-  class ParamSpec
+  class ParamSpec #:nodoc:
     attr_reader :name
     attr_reader :value_class
-    attr_reader :default_value # Only meaningful if is_required?
+    attr_reader :default_value # Optionally present; default_value? is the
+                               # predicate
 
     # 
     # ====Description:
-    # This constructs a Paramspec for parameter name and value
+    # This constructs a ParamSpec for parameter name and value
     # of class value_class.  If is_required, then the parameter is
     # required; otherwise, the parameter is optional with a default
     # value of default_value.
@@ -68,15 +90,22 @@ class BaseConfig
     # [default_value]
     #      If the parameter need not be set in a configuration file
     #      (!is_required), the value it defaults to if it's not specified.
+    #      A default_value of BaseConfig::NO_DEFAULT_VALUE means that
+    #      there is no default_value attribute.
     # 
     def initialize(name, value_class, is_required, default_value)
       @name = name
       @value_class = value_class
       @is_required = is_required
+      @default_value = default_value
+    end
 
-      if(!is_required)
-        @default_value = default_value
-      end
+    # 
+    # ====Returns:
+    # true if and only if the parameter has a default value
+    # 
+    def default_value?
+      return !@default_value.equal?(BaseConfig::NO_DEFAULT_VALUE)
     end
 
     # 
@@ -84,16 +113,10 @@ class BaseConfig
     # true if and only if the parameter must be set in a configuration
     # file; false otherwise.
     # 
-    def is_required?
+    def required?
       return @is_required
     end
   end
-  
-  #
-  # The indentation used to indicate nesting when printing out
-  # a BaseConfig.
-  #
-  NESTING_INDENT = " " * 4
 
   #
   # Create accessors for some class instance variables;
@@ -113,20 +136,13 @@ class BaseConfig
     # specifications (ParamSpecs) in the order in which they were specified
     # in the BaseConfig child class.
     #
-    attr_reader :param_spec_list
+    attr_reader :param_spec_list #:nodoc:
 
     #
     # This is a Hash (class instance variable) mapping
     # paramater names (Symbols) to parameter specifications (ParamSpecs)
     #
-    attr_reader :param_spec_lookup_table
-
-    #
-    # This is an Integer (class instance variable) containing the length
-    # of the longest parameter name.  This is used to line up the output
-    # when printing out an instance.
-    #
-    attr_reader :longest_param_name_length
+    attr_reader :param_spec_lookup_table #:nodoc:
   end
 
   # 
@@ -140,29 +156,126 @@ class BaseConfig
   # [child_class]
   #      The new child class
   # 
-  def self.inherited(child_class)
+  def self.inherited(child_class) # :nodoc:
     #
     # Initialize the class instance variables.
     #
     child_class.class_eval do
       @param_spec_list = []
       @param_spec_lookup_table = {}
-      @longest_param_name_length = 0
     end
   end
 
   #
   # ====Description:
-  # This class method adds a new parameter to a BaseConfig child
-  # class (it should be called within the body of the child class'
-  # definition).  The new parameter has name name and has values
-  # of class value_class (or one of value_class' child classes).
+  # Because the to_s in Ruby 1.8 for the Array and Hash classes
+  # are horrible...  This method returns a readable String representation
+  # of value, recursively expanding the contents of Array and Hash
+  # value arguments (the String representation of the expansion is
+  # written on a single line, however) and otherwise returning value.to_s.
+  # This is called by construct_error_message in order to construct a nicely
+  # formatted error message.
+  # 
+  # ====Parameters:
+  # [value]
+  #      The object for which to return a String representation
+  # 
+  # ====Returns:
+  # A nicely formatted String representation of value
+  # 
+  def self.construct_value_str(value)
+    if(value == nil)
+      return "nil"
+    elsif(value.is_a?(Array))
+      #
+      # Recursively call construct_value_str for each Array element,
+      # surrounding the element strings in brackets.
+      #
+      str = "["
+
+      value.each_with_index do |element, index|
+        str << construct_value_str(element)
+
+        if(index < (value.size - 1))
+          str << ", "
+        end
+      end
+
+      str << "]"
+      return str
+    elsif(value.is_a?(Hash))
+      #
+      # Recursively call construct_value_str for each Hash element,
+      # surrounding the element strings in braces.
+      #
+      str = "{"
+
+      value.each_with_index do |key_and_value, index|
+        str << "#{construct_value_str(key_and_value[0])}=>#{construct_value_str(key_and_value[1])}"
+
+        if(index < (value.size - 1))
+          str << ", "
+        end
+      end
+
+      str << "}"
+      return str
+    else
+      return value.to_s
+    end
+  end
+  private_class_method :construct_value_str
+
+  # 
+  # ====Description:
+  # This method returns an error message for an error (described by
+  # reason) that occurred while setting parameter param_name with
+  # value value.
+  # 
+  # ====Parameters:
+  # [containing_object_name]
+  #      The containing object name
+  # [param_name]
+  #      The parameter being set when the error occurred (String)
+  #      This need not be a "real" parameter value; it also can be
+  #      an element in an Array value (i.e., the 3rd element of Array
+  #      parameter servers will be passed as "servers[2]").
+  # [value]
+  #      The parameter value that caused the error
+  # [reason]
+  #      The reason for the error (String)
+  # 
+  # ====Returns:
+  # An error message that includes the parameter name, the problem
+  # parameter value, and the error description.
+  # 
+  def self.construct_error_message(containing_object_name,
+                                   param_name,
+                                   value,
+                                   reason)
+    if(containing_object_name.empty?)
+      full_param_name = param_name
+    else
+      full_param_name = "#{containing_object_name}.#{param_name}"
+    end
+
+    return "error setting #{full_param_name} with value #{construct_value_str(value)}: #{reason}."
+  end
+  private_class_method :construct_error_message
+
+  #
+  # ====Description:
+  # This class method adds a parameter to the BaseConfig child class
+  # (it should be called from within the body of the child class'
+  # definition).  The new parameter is called +name+ and has values
+  # of class +value_class+ (or one of +value_class+' child classes).
   # The parameter must be set in a configuration file if
-  # is_required is true; if !is_required, then default_value is the
-  # value of the parameter if it's not set in a configuration file.
+  # +is_required+; if not +is_required+, then +default_value+ is the
+  # value of the parameter if the parameter is not set in a configuration file
+  # and if +default_value+ is not +NO_DEFAULT_VALUE+.
   #
-  # This method optionally accepts a block (validate_value_block), which,
-  # if present, is called with the new value for the parameter before setting
+  # This method optionally accepts a block (+validate_value_block+), which,
+  # if present, is called with a new value for the parameter before setting
   # the parameter with the new value, allowing custom validation
   # code to be executed (if this validation fails, then raise_error should
   # be called inside of the block).
@@ -172,16 +285,18 @@ class BaseConfig
   # 
   # ====Parameters:
   # [name]
-  #      The name of the parameter
+  #      The name of the parameter (Symbol)
   # [value_class]
-  #      The parent class of the parameter's values
+  #      The class (or parent class) of the parameter's values
   # [is_required]
   #      Whether or not the parameter must be specified in a
-  #      configuration file.
+  #      configuration file
   # [default_value]
-  #      If !is_required, then the default value of the parameter if it's
-  #      not specified in a configuration file.
-  # [validate_value_block]
+  #      The default value of the parameter if it's not specified in
+  #      a configuration file (which only makes sense if not +is_required+)
+  #      If this argument is +NO_DEFAULT_VALUE+, then it is treated
+  #      treated as absent (the parameter will have no default value)
+  # [&validate_value_block]
   #      An optional block that, if present, is called to validate a new
   #      value for the parameter before setting the parameter to the new
   #      value.
@@ -191,10 +306,6 @@ class BaseConfig
                      is_required,
                      default_value,
                      &validate_value_block) #:doc:
-    param_spec = ParamSpec.new(name, value_class, is_required, default_value)
-    @param_spec_list.push(param_spec)
-    @param_spec_lookup_table[name] = param_spec
-
     #
     # Convert Array value classes into ConstrainedArrays with
     # no constraints.  This makes supporting Arrays much easier, since
@@ -204,10 +315,26 @@ class BaseConfig
       value_class = ConstrainedArray.new(Object, nil, nil)
     end
 
+    if(!default_value.equal?(NO_DEFAULT_VALUE))
+      #
+      # Try loading the default value, given the specified value class,
+      # in order to verify that the default value is a valid value
+      # for the parameter.
+      #
+      value = load_value_impl("",
+                              "default value for #{name}",
+                              value_class,
+                              default_value)
+    end
+
+    param_spec = ParamSpec.new(name, value_class, is_required, default_value)
+    @param_spec_list.push(param_spec)
+    @param_spec_lookup_table[name] = param_spec
+
     #
     # Define the getter and setter methods with a string passed to
     # class_eval rather than a block, so as to avoid the need to access
-    # the reflectoin APIs when the setter actually is called.
+    # the reflectionn APIs when the setter actually is called.
     #
     # Note that the setter will call load_value_impl() on any value
     # that it is passed; this ensures that data specified programatically
@@ -222,37 +349,51 @@ class BaseConfig
     # variable storing this class from the param_spec_lookup_table.
     #
     methods = String.new()
-    methods << "attr_reader :#{name}\n"
+    methods << "def #{name}\n"
+    methods << "  if(@__#{name}_supplied_p__)\n"
+    methods << "    return @#{name}\n"
+    methods << "  else\n"
+    methods << "    return nil\n"
+    methods << "  end\n"
+    methods << "end\n"
     methods << "\n"
     methods << "def #{name}=(value)\n"
     methods << "  value_class = self.class.param_spec_lookup_table[:#{name}].value_class\n"
-    methods << "  loaded_value = load_value_impl(\"#{name}\", value_class, value)\n"
+    methods << "  loaded_value = self.class.send(:load_value_impl, @containing_object_name, \"#{name}\", value_class, value)\n"
     if(validate_value_block != nil)
       validate_value_method = "validate_#{name}_value".to_sym()
       define_method(validate_value_method, &validate_value_block)
       methods << "  begin\n"
-      methods << "    #{validate_value_method}(value)\n"
+      methods << "    #{validate_value_method}(loaded_value)\n"
       methods << "  rescue Error => e\n"
-      methods << "    raise Error, construct_error_message(\"#{name}\", value, e.message), e.backtrace()\n"
+      methods << "    raise Error, self.class.send(:construct_error_message, @containing_object_name, \"#{name}\", value, e.message), e.backtrace()\n"
       methods << "  end\n"
     end
 
     methods << "  @#{name} = loaded_value\n"
-    methods << "  @params_with_values.add(:#{name})\n"
+    methods << "  @__#{name}_supplied_p__ = true\n"
+    methods << "end\n"
+    methods << "\n"
+    methods << "def #{name}?\n"
+    methods << "  return @__#{name}_supplied_p__\n"
     methods << "end\n"
+    
+    if(!is_required)
+      methods << "\n"
+      methods << "def clear_#{name}\n"
+      methods << "  @__#{name}_supplied_p__ = false\n"
+      methods << "end\n"
+    end
 
     class_eval(methods)
-
-    name_str = name.to_s
-    if(name_str.length > @longest_param_name_length)
-      @longest_param_name_length = name_str.length
-    end
   end
   private_class_method :add_param
 
   # 
   # ====Description:
-  # This is a wrapper around add_param that passes is_required = true.
+  # This is a wrapper around add_param that passes +true+ for the
+  # +is_required+ argument.  Values must be specified for required
+  # parameters in configuration files.
   # 
   # ====Parameters:
   # See add_param's parameter list.
@@ -260,71 +401,124 @@ class BaseConfig
   def self.add_required_param(name,
                               value_class,
                               &validate_value_block) #:doc:
-    add_param(name, value_class, true, nil, &validate_value_block)
+    add_param(name, value_class, true, NO_DEFAULT_VALUE, &validate_value_block)
   end
   private_class_method :add_required_param
 
   # 
   # ====Description:
-  # This is a wrapper around add_param that passes is_required = false and
-  # default_value = default_value.
+  # This is a wrapper around add_param that passes +false+ for the
+  # +is_required+ argument.  Values need not be specified for optional
+  # parameters in configuration files (optional parameters can be
+  # set to default values when a value is not specified in a configuration
+  # file, if desired).
   # 
   # ====Parameters:
   # See add_param's parameter list.
   # 
   def self.add_optional_param(name,
                               value_class,
-                              default_value,
+                              default_value = NO_DEFAULT_VALUE,
                               &validate_value_block) #:doc:
     add_param(name, value_class, false, default_value, &validate_value_block)
   end
   private_class_method :add_optional_param
 
   #
-  # This is a String (instance variable) containing the name of the object that
+  # This is a String containing the name of the object that
   # contains this instance's configuration.  For example, if
-  # all of this instance's configuration is under production and
-  # webserver, then the containing_object_name would be
-  # 'production.webserver'.
+  # all of this instance's configuration is under +production+ and
+  # +webserver+ in the configuration file, then the +containing_object_name+
+  # would be +production.webserver+.
   #
   attr_reader :containing_object_name
 
   # 
   # ====Description:
-  # This constructs a BaseConfig with no parameters set (all parameters
-  # initially have a nil value).
+  # This constructs a BaseConfig with no parameters set (each parameter
+  # initially has a +nil+ value).
   # 
-  def initialize
+  # If a block is specified, then it will be passed the new instance and
+  # should set the BaseConfig's parameters fully (as if load had been called);
+  # the BaseConfig's specifications will be verified by this method after
+  # it executes the block (with a call to enforce_specs).
+  #
+  # ====Example:
+  #  class Config < ConfigToolkit::BaseConfig
+  #    add_required_param(:age, Fixnum)
+  #  end
+  #
+  #  empty_config = Config.new()
+  #
+  #  initialized_config = Config.new() do |config|
+  #    config.age = 5
+  #  end
+  #
+  #  # This will raise an exception, because the age parameter is
+  #  # required but is not being set by the block passed to new.
+  #  initalized_config = Config.new() do |config|
+  #  end
+  #
+  # ====Parameters:
+  # [&initialization_block]
+  #      A block that fully initializes the parameters of the new
+  #      instance
+  # 
+  def initialize(&initialization_block)
     @containing_object_name = ""
-    @params_with_values = Set.new()
 
+    clear_all_values()
+
+    if(block_given?())
+      yield self
+      enforce_specs()
+    end
+  end
+
+  # 
+  # ====Description:
+  # This method clears all parameter values.
+  # 
+  def clear_all_values
     self.class.param_spec_list.each do |param_spec|
-      instance_variable_set("@#{param_spec.name}", nil)
+      instance_variable_set("@__#{param_spec.name}_supplied_p__", false)
     end
   end
+  private :clear_all_values
+
+  # 
+  # ====Description:
+  # This method returns true if and only if a value for parameter
+  # param_name is present in the configuration.
+  # 
+  # ====Parameters:
+  # [param_name]
+  #      The parameter for which to check for the presence of a value
+  # 
+  # ====Returns:
+  # true if and only if a value for parameter param_name is present in
+  # the configuration
+  # 
+  def has_value(param_name)
+    return send("#{param_name}?".to_sym())
+  end
+  private :has_value
 
   # 
   # ====Description:
   # This method enforces the BaseConfig's specifications.  In particular,
   # it:
-  # * Checks hat all required parameters have been set.  If a required
+  # * Checks that all required parameters have been set.  If a required
   #   parameter is missing, then this method raises an Error.
-  # * Sets all optional parameters without values to their
-  #   default values.
-  # * Calls validate_all_values, if this exists.
+  # * Sets all optional parameters without values and with default values to
+  #   their default values.
+  # * Calls validate_all_values.
   #
   # This method is called at the end of a load operation (verifying that
   # a valid configuration was loaded from a reader) and before a dump operation
-  # (verifying that a valid configuration will be dumped).  The operation_name
-  # parameter is a String containing the name of the operation calling
-  # this method; this String is used in Error messages.
-  # 
-  # ====Parameters:
-  # [operation_name]
-  #      A String containing the name of the operation calling this
-  #      method ("load" or "dump", for example)
+  # (verifying that a valid configuration will be dumped).
   # 
-  def enforce_specs(operation_name)
+  def enforce_specs
     #
     # Iterate through the parameters without values.  If any are
     # required parameters, then raise (after completing the
@@ -335,10 +529,10 @@ class BaseConfig
     missing_params = []
 
     self.class.param_spec_list.each do |param_spec|
-      if(!@params_with_values.include?(param_spec.name))
-        if(param_spec.is_required?)
+      if(!has_value(param_spec.name))
+        if(param_spec.required?)
           missing_params.push(param_spec.name)
-        else
+        elsif(param_spec.default_value?)
           #
           # Even the default values are set through the setter.
           #
@@ -354,128 +548,37 @@ class BaseConfig
         param_prefix = "#{@containing_object_name}."
       end
 
-      missing_param_spec_list = missing_params.map do |param_name|
+      missing_params_str = missing_params.map do |param_name|
         "#{param_prefix}#{param_name}"
-      end
-
-      raise Error, "missing parameter(s): #{missing_param_spec_list.join(", ")}"
-    end
-
-    if(respond_to?(:validate_all_values))
-      begin
-        validate_all_values()
-      rescue Error => e
-        #
-        # Rescue the error, add some information to the error message, and
-        # throw a repackaged error.
-        #
-        message = "#{self.class}#validate_all_values #{operation_name} error"
-
-        if(!@containing_object_name.empty?)
-          message << " for #{@containing_object_name}"
-        end
+      end.join(", ")
 
-        message << ": #{e.message}"
-        raise Error, message, e.backtrace()
-      end
+      raise Error, "missing parameter(s): #{missing_params_str}"
     end
-  end
-  private :enforce_specs
-
-  #
-  # ====Description:
-  # Because the to_s in Ruby 1.8 for the Array and Hash classes
-  # are horrible...  This method returns a readable String representation
-  # of value, recursively expanding the contents of Array and Hash
-  # value arguments and otherwise returning value.to_s.  This is
-  # called by construct_error_message in order to construct a nicely formatted
-  # error message.
-  # 
-  # ====Parameters:
-  # [value]
-  #      The object for which to return a String representation
-  # 
-  # ====Returns:
-  # A nicely formatted String representation of value
-  # 
-  def construct_value_str(value)
-    if(value.is_a?(Array))
-      #
-      # Recursively call construct_value_str for each Array element,
-      # surrounding the element strings in brackets.
-      #
-      str = "["
-
-      value.each_with_index do |element, index|
-        str << construct_value_str(element)
-
-        if(index < (value.size - 1))
-          str << ", "
-        end
-      end
 
-      str << "]"
-      return str
-    elsif(value.is_a?(Hash))
+    begin
+      validate_all_values()
+    rescue Error => e
       #
-      # Recursively call construct_value_str for each Hash element,
-      # surrounding the element strings in braces.
+      # Rescue the error, add some information to the error message, and
+      # throw a repackaged error.
       #
-      str = "{"
-
-      value.each_with_index do |key_value, index|
-        str << "#{construct_value_str(key_value[0])}=>#{construct_value_str(key_value[1])}"
-
-        if(index < (value.size - 1))
-          str << ", "
-        end
+      message = "#{self.class}#validate_all_values error"
+      
+      if(!@containing_object_name.empty?)
+        message << " for #{@containing_object_name}"
       end
-
-      str << "}"
-      return str
-    else
-      return value.to_s
-    end
-  end
-  private :construct_value_str
-
-  # 
-  # ====Description:
-  # This method returns an error message for an error (described by
-  # reason) that occurred while setting parameter param_name with
-  # value value.
-  # 
-  # ====Parameters:
-  # [param_name]
-  #      The parameter being set when the error occurred (String)
-  #      This need not be a "real" parameter value; it also can be
-  #      an element in an Array value (i.e., the 3rd element of Array
-  #      parameter servers will be passed as "servers[2]").
-  # [value]
-  #      The parameter value that caused the error
-  # [reason]
-  #      The reason for the error (String)
-  # 
-  # ====Returns:
-  # An error message that includes the parameter name, the problem
-  # parameter value, and the error description.
-  # 
-  def construct_error_message(param_name, value, reason)
-    if(@containing_object_name.empty?)
-      full_param_name = "#{param_name}"
-    else
-      full_param_name = "#{@containing_object_name}.#{param_name}"
+      
+      message << ": #{e.message}"
+      raise Error, message, e.backtrace()
     end
-
-    return "error setting parameter #{full_param_name} with value #{construct_value_str(value)}: #{reason}."
   end
-  private :construct_error_message
 
   # 
   # ====Description:
-  # This method raises an Error with message reason.  It is meant to
-  # be called from user-defined parameter validation blocks.  This is
-  # a Hotel California type of call; it does not return.
+  # This method raises an Error with message +reason+.  It is meant to
+  # be called from user-defined parameter validation blocks (see the
+  # arguments to add_param).  This is a Hotel California type of call;
+  # it does not return.
   # 
   # ====Parameters:
   # [reason]
@@ -487,16 +590,16 @@ class BaseConfig
 
   # 
   # ====Description:
-  # Equality operator for BaseConfig; this iterates through the
-  # specified parameters and compares the parameter values of
-  # self and rhs using the equality operator of the parameter values.
+  # Equality operator for BaseConfig; this method iterates through the
+  # configuration's parameters and, for each parameter, compares the value
+  # of +self+ and +rhs+ using the value's equality operator.
   # 
   # ====Parameters:
   # [rhs]
-  #      The instance to compare with self
+  #      The instance to compare with +self+
   # 
   # ====Returns:
-  # True if and only if the values of self and rhs are equal
+  # True if and only if the parameter values of self and rhs are equal
   # 
   def ==(rhs)
     if(rhs == nil)
@@ -521,17 +624,23 @@ class BaseConfig
   # ====Parameters:
   # [value]
   #      The parameter value to dump
+  # [use_symbol_parameter_names]
+  #      Whether dump_value_impl should use Symbols or Strings for parameter
+  #      names (needed in order to recursively call dump_impl)
   # 
   # ====Returns:
   # A dump of value
   # 
-  def dump_value_impl(value)
+  def dump_value_impl(value, use_symbol_parameter_names)
     if(value.class < BaseConfig)
-      return value.dump_impl({})
+      #
+      # Use send to call the private dump_impl method.
+      #
+      return value.send(:dump_impl, {}, use_symbol_parameter_names)
     elsif(value.class == Array)
       dumped_array = []
       value.each do |element|
-        dumped_array.push(dump_value_impl(element))
+        dumped_array.push(dump_value_impl(element, use_symbol_parameter_names))
       end
       return dumped_array
     else
@@ -542,61 +651,79 @@ class BaseConfig
 
   # 
   # ====Description:
-  # This method dumps self into containing_object_hash; that is,
-  # it adds entries to containing_object_hash for each parameter.
-  # An entry's key is the parameter name (as a String), and the value is
-  # the parameter value.  The method returns containing_object_hash
+  # This method dumps +self+ into +containing_object_hash+; that is,
+  # it adds entries to +containing_object_hash+ for each parameter.
+  # An entry's key is the parameter name (as a Symbol or a String,
+  # depending on the value of +use_symbol_parameter_names+), and the value is
+  # the parameter value.  The method returns +containing_object_hash+
   # after the dump.  Before dumping everything, this method calls
-  # enforce_specs in order to ensure that valid data is being
+  # +enforce_specs+ in order to ensure that valid data is being
   # dumped.
   # 
   # ====Parameters:
   # [containing_object_hash]
   #      The hash into which to dump self
+  # [use_symbol_parameter_names]
+  #      Whether dump_impl should use Symbols or Strings for parameter names
   # 
   # ====Returns:
-  # containing_object_hash after the dump
+  # +containing_object_hash+ after the dump
   # 
-  def dump_impl(containing_object_hash)
+  def dump_impl(containing_object_hash, use_symbol_parameter_names)
     #
     # Configuration never will be dumped without the
     # specifications first having been enforced.
     #
-    enforce_specs("dump")
+    enforce_specs()
 
     self.class.param_spec_list.each do |param_spec|
-      containing_object_hash[param_spec.name.to_s] = dump_value_impl(send(param_spec.name))
+      #
+      # Don't dump parameters without values.
+      #
+      if(!has_value(param_spec.name))
+        next
+      end
+
+      value = dump_value_impl(send(param_spec.name), use_symbol_parameter_names)
+
+      if(use_symbol_parameter_names)
+        containing_object_hash[param_spec.name] = value
+      else
+        containing_object_hash[param_spec.name.to_s()] = value
+      end
+        
     end
 
     return containing_object_hash
   end
-  protected :dump_impl
+  private :dump_impl
 
   # 
   # ====Description:
-  # This method dumps self to writer.  That is, it constructs
-  # a Hash containing entries for the containing object (and,
-  # in the the most nested containing object entry, entries for the
-  # paramters) and passes the Hash to the write method of writer.  The
-  # configuration's data is checked against its specifications
-  # before anything is dumped.
+  # This method writes +self+ to a configuration file.  It does this by
+  # passing the contents of +self+ to +writer+.  That is, it constructs
+  # a Hash containing entries for the parameters and passes the Hash to
+  # the +write+ method of +writer+, which should write the information to
+  # some underlying medium (most likely writing a configuration file).  The
+  # method checks the configuration against its specifications (via a
+  # call to enforce_specs) before dumping anything.
   # 
   # ====Parameters:
   # [writer]
-  #      The writer to which to dump
+  #      The writer to which to dump (see Writer)
   # 
   def dump(writer)
-    dump_hash = {}
-    containing_object_hash = dump_hash
-
-    @containing_object_name.split(".").each do |object_name|
-      object_hash = {}
-      containing_object_hash[object_name] = object_hash
-      containing_object_hash = object_hash
-    end
+    #
+    # If the require_symbol_parameter_names? method returns true,
+    # then Symbol parameter names will be passed to the writer;
+    # otherwise, String parameter names will be passed to the writer.
+    #
+    use_symbol_parameter_names = writer.require_symbol_parameter_names?()
+    
+    config_hash = {}
+    dump_impl(config_hash, use_symbol_parameter_names)
 
-    dump_impl(containing_object_hash)
-    writer.write(dump_hash)
+    writer.write(config_hash, @containing_object_name)
   end
 
   # 
@@ -615,6 +742,8 @@ class BaseConfig
   #   types from files and so BaseConfig has to do some lexical casting.
   # 
   # ====Parameters:
+  # [containing_object_name]
+  #      The containing object name
   # [param_name]
   #      The name of the parameter whose value is being loaded (String).
   #      This need not be a "real" parameter value; it also can be
@@ -628,14 +757,24 @@ class BaseConfig
   # ====Returns:
   # A parameter value of class value_class for param_name loaded from raw_value
   # 
-  def load_value_impl(param_name, value_class, raw_value)
+  def self.load_value_impl(containing_object_name,
+                           param_name,
+                           value_class,
+                           raw_value)
     if(raw_value.class <= value_class)
       #
       # If the reader has returned a value of the same class as
       # was specified for that parameter (or a child class of the specified
-      # class), then just return the value.
+      # class), then just return a copy of the value.  Erros need
+      # to be rescued because Fixnums, symbols, and the rest of
+      # the Ruby immediate values do not support dup() (they will
+      # throw).
       #
-      return raw_value
+      begin
+        return raw_value.dup()
+      rescue
+        return raw_value
+      end
     elsif((value_class < BaseConfig) && (raw_value.class == Hash))
       #
       # If we're looking for a BaseConfig child and have a Hash, then
@@ -644,13 +783,16 @@ class BaseConfig
       #
       child_config = value_class.new()
 
-      if(@containing_object_name.empty?)
+      if(containing_object_name.empty?)
         nested_containing_object_name = param_name
       else
-        nested_containing_object_name = "#{@containing_object_name}.#{param_name}"
+        nested_containing_object_name = "#{containing_object_name}.#{param_name}"
       end
 
-      child_config.load_impl(raw_value, nested_containing_object_name)
+      #
+      # Use send to call the private load_impl method.
+      #
+      child_config.send(:load_impl, raw_value, nested_containing_object_name)
       return child_config
     elsif((value_class < ConstrainedArray) && (raw_value.class == Array))
       #
@@ -661,21 +803,32 @@ class BaseConfig
       value = []
 
       raw_value.each_with_index do |element, index|
-        value.push(load_value_impl("#{param_name}[#{index}]", value_class.element_class, element))
+        value.push(load_value_impl(containing_object_name,
+                                   "#{param_name}[#{index}]",
+                                   value_class.element_class,
+                                   element))
       end
 
       if((value_class.min_num_elements != nil) &&
          (value.length < value_class.min_num_elements))
-        message = "the number of elements (#{value.length}) is less than the specified "
-        message << "minimum number of elements (#{value_class.min_num_elements})"
-        raise Error, construct_error_message(param_name, raw_value, message)
+        message = "the number of elements (#{value.length}) is less than the "
+        message << "specified minimum number of elements "
+        message << "(#{value_class.min_num_elements})"
+        raise Error, construct_error_message(containing_object_name,
+                                             param_name,
+                                             raw_value,
+                                             message)
       end
       
       if((value_class.max_num_elements != nil) &&
          (value.length > value_class.max_num_elements))
-        message = "the number of elements (#{value.length}) is greater than the specified "
-        message << "maximum number of elements (#{value_class.max_num_elements})"
-        raise Error, construct_error_message(param_name, raw_value, message)
+        message = "the number of elements (#{value.length}) is greater than the "
+        message << "specified maximum number of elements "
+        message << "(#{value_class.max_num_elements})"
+        raise Error, construct_error_message(containing_object_name,
+                                             param_name,
+                                             raw_value,
+                                             message)
       end
 
       return value
@@ -717,67 +870,25 @@ class BaseConfig
       end
     end
 
-    message = "cannot convert from value class #{raw_value.class.name} to specified class #{value_class.name}"
-    raise Error, construct_error_message(param_name, raw_value, message)
-  end
-  private :load_value_impl
-
-  # 
-  # ====Description:
-  # This method loads self from containing_object_hash, which
-  # must contain key/value pairs, where the keys are
-  # parameter names (Strings) and the values are parameter
-  # values (to be passed to load_value_impl).  The configuration's
-  # specifications are enforced by this method.
-  # 
-  # ====Parameters:
-  # [containing_object_hash]
-  #      The Hash containing the configuration's parameters
-  # [containing_object_name]
-  #      The containing object name
-  # 
-  def load_impl(containing_object_hash, containing_object_name)
-    @containing_object_name = containing_object_name
-    @params_with_values.clear()
-
-    if(containing_object_hash != nil)
-      containing_object_hash.each do |name, value|
-        #
-        # Lookup the spec 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.
-        #
-        param_spec = self.class.param_spec_lookup_table.fetch(name.to_sym(), nil)
-
-        if(param_spec == nil)
-          next
-        end
-
-        #
-        # Invoke the parameter's setter.
-        #
-        send("#{param_spec.name}=", value)
-      end
-    end
-
-    enforce_specs("load")
+    message = "cannot convert from value class #{raw_value.class.name} to "
+    message << "specified class #{value_class.name}"
+    raise Error, construct_error_message(containing_object_name,
+                                         param_name,
+                                         raw_value,
+                                         message)
   end
-  protected :load_impl
+  private_class_method :load_value_impl
 
   # 
   # ====Description:
-  # This method loads the configuration hash from reader for containing object
-  # containing_object_name.  This method is not really part of BaseConfig's
-  # public API but, unfortunately, cannot be made private (since it is
-  # called from an instance method; there are no "protected" class methods,
-  # unfortunately).
+  # This method loads the configuration hash from +reader+ for containing object
+  # +containing_object_name+.
   # 
   # ====Parameters:
   # See the parameter list for load.
   # 
   # ====Returns:
-  # The configuration hash for containing_object_name (or nil, if none
+  # The configuration hash for +containing_object_name+ (or +nil+, if none
   # is found)
   # 
   def self.load_containing_object_hash(reader, containing_object_name)
@@ -791,8 +902,8 @@ class BaseConfig
 
     #
     # Work through the param_hash until the most nested object in
-    # containing_object_name is found by
-    # splitting up containing_object_name into an object list and
+    # containing_object_name is found by splitting
+    # up containing_object_name into an object list and
     # hashing for each.  For example, production.webserver.tokyo would
     # result in a lookup for production, the results of which them would be
     # searched for webserver, the results of which finally would be searched
@@ -805,7 +916,14 @@ class BaseConfig
     #
     containing_object_hash = param_hash
     containing_object_name.split(".").each do |object_name|
-      containing_object_hash = containing_object_hash.fetch(object_name, nil)
+      #
+      # Do the lookup with a String and with a Symbol (if the String lookup
+      # fails), as a containing object could be specified with either in the
+      # hash.
+      #
+      containing_object_hash =
+        containing_object_hash[object_name] ||
+        containing_object_hash[object_name.to_sym()]
 
       if(containing_object_hash == nil)
         break
@@ -824,16 +942,70 @@ class BaseConfig
 
   # 
   # ====Description:
-  # This method loads self from reader (with containing object
-  # containing_object_name).
+  # This method clears all of the configuration's parameter values and
+  # loads self from +containing_object_hash+, which
+  # must contain key/value pairs, where the keys are
+  # parameter names (Strings or Symbols) and the values are parameter
+  # values (to be passed to load_value_impl).  The configuration's
+  # specifications are enforced by this method.
+  # 
+  # ====Parameters:
+  # [containing_object_hash]
+  #      The Hash containing the configuration's parameters
+  # [containing_object_name]
+  #      The containing object name (String)
+  # 
+  def load_impl(containing_object_hash, containing_object_name)
+    @containing_object_name = containing_object_name
+
+    #
+    # A load operation clears all prior parameter values.
+    #
+    clear_all_values()
+
+    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.
+        #
+        # The parameter name in the containing object hash either could be a
+        # Symbol or a String; in either case to_sym() will normalize 
+        # it as a Symbol (the keys in param_spec_lookup_table all are
+        # Symbols)
+        #
+        param_spec = self.class.param_spec_lookup_table[name.to_sym()]
+
+        if(param_spec == nil)
+          next
+        end
+
+        #
+        # Invoke the parameter's setter.
+        #
+        send("#{param_spec.name}=", value)
+      end
+    end
+
+    enforce_specs()
+  end
+  private :load_impl
+
+  # 
+  # ====Description:
+  # This method loads the contents of a configuration file into
+  # +self+.  It loads +self+ from +reader+ (with containing object
+  # +containing_object_name+), deleting all prior parameter values.
   # 
   # ====Parameters:
   # [reader]
-  #      The reader from which to load the parameter values.  This method
-  #      will call the read method of reader, which will return
-  #      a Hash containing, in the most nested containing object entry,
-  #      the configuration parameter values for self.
-  # [containing_object_name = ""]
+  #      The reader (see Reader) from which to load the parameter
+  #      values.  This method will call the +read+ method of
+  #      +reader+, which will return a Hash containing, in the most nested
+  #      containing object entry, the configuration parameter values for +self+.
+  # [containing_object_name]
   #      The containing object name
   # 
   def load(reader, containing_object_name = "")
@@ -849,7 +1021,7 @@ class BaseConfig
   # 
   # ====Description:
   # This class method creates a new config instance and
-  # calls load on it with the specified parameters.  This
+  # calls load on it with the specified arguments.  This
   # is a second "constructor" for the class.
   # 
   # ====Parameters:
@@ -867,17 +1039,16 @@ class BaseConfig
   # 
   # ====Description:
   # This class method loads arbitrarily many configs from
-  # reader.  This should be used when containing_object_name's
-  # elements all are hashes, each of which is a different instance of
-  # this class' configuration.  This call returns a Hash containing
-  # elements mapping configuration name to configuration
-  # instance.
+  # reader.  This should be used when each of +containing_object_name+'s
+  # elements is a different instance of this class' configuration.
+  # This call returns a Hash containing elements mapping configuration names
+  # (Symbols) to configuration instance.
   # 
   # ====Parameters:
   # See the parameter list for load.
   # 
   # ====Returns:
-  # A Hash of names (Strings) mapping to loaded configuration instances
+  # A Hash of names (Symbols) mapping to loaded configuration instances
   # 
   def self.load_group(reader, containing_object_name = "")
     containing_object_hash = load_containing_object_hash(reader, containing_object_name)
@@ -898,109 +1069,42 @@ class BaseConfig
         instance = new()
 
         #
-        # Have to use send in order to call protected method.
-        # I think that not being able to call protected instance methods
+        # Have to use send in order to call private method.
+        # I think that not being able to call private instance methods
         # from class methods is a bug.
         #
         instance.send(:load_impl, value, value_containing_object_name)
-        config_group[key] = instance
+        config_group[key.to_sym()] = instance
       end
     end
 
     return config_group
   end
-  
-  # 
-  # ====Description:
-  # This method writes parameter value value to str, with
-  # indentation indent.
-  # 
-  # ====Parameters:
-  # [str]
-  #      The String to which to write
-  # [indent]
-  #      The indentation at which to write value
-  # [value]
-  #      The parameter value to write
-  # 
-  def write_value_impl(str, indent, value)
-    nesting_indent = indent + NESTING_INDENT
-    if(value != nil)
-      if(value.class < BaseConfig)
-        #
-        # Writing a nested config requires calling its write(),
-        # just at one further indentation level.
-        #
-        str << "{\n"
-        value.write_impl(str, nesting_indent)
-        str << indent << "}"
-      elsif(value.is_a?(Array))
-        #
-        # Writing an array requires calling write_value_impl for each element,
-        # just at one further indentation level.
-        #
-        str << "[\n"
-
-        value.each_with_index do |element, index|
-          str << nesting_indent
-          write_value_impl(str, nesting_indent, element)
-
-          if(index < (value.length - 1))
-            str << ","
-          end
-
-          str << "\n"
-        end
-
-        str << indent << "]"
-      else
-        str << "#{value}"
-      end
-    end
-  end
-  private :write_value_impl
-
-  # 
-  # ====Description:
-  # This method writes self to str, at indentation indent.
-  # 
-  # ====Parameters:
-  # [str]
-  #      The String to which to write
-  # [indent]
-  #      The indentation at which to write self
-  # 
-  def write_impl(str, indent)
-    name_field_length = self.class.longest_param_name_length
-    self.class.param_spec_list.each do |param_spec|
-      str << indent << param_spec.name.to_s.ljust(name_field_length) << ": "
-      value = send(param_spec.name)
-      write_value_impl(str, indent, value)
-      str << "\n"
-    end
-  end
-  protected :write_impl
 
   # 
   # ====Returns:
-  # String representation of self
+  # String representation of +self+
   # 
   def to_s
-    #
-    # Print out config file name and the containing object_name and then
-    # call write.
-    #
-    str = String.new()
+    string_stream = StringIO.new()
 
-    if(!@containing_object_name.empty?)
-      str << "#{@containing_object_name}: "
-    end
-
-    str << "{\n"
-    write_impl(str, NESTING_INDENT)
-    str << "}\n"
+    writer = PrettyPrintWriter.new(string_stream)
+    dump(writer)
+    
+    return string_stream.string()
+  end
 
-    return str
+  # 
+  # ====Description:
+  # This method enforces constraints between parameters; unless overriden,
+  # it is a no-op.  It is called after all values have been loaded
+  # during a load operation or at the start of a dump operation.  If a child
+  # class wishes to enforce a particular constraint, it should re-implement
+  # this method; if a constraint is violated, the method should call
+  # raise_error in order to raise an Error.
+  # 
+  def validate_all_values
+    # This must be re-implemented in child classes in order to do anything
   end
 end