configtoolkit 1.2.0 → 2.0.0

data/lib/configtoolkit/types.rb

@@ -1,23 +1,37 @@
 #!/usr/bin/env ruby
+
+require 'singleton'
+
 module ConfigToolkit
 
+#
+# All errors raised by ConfigToolkit code descend from
+# this one; while right now it is the only error raised
+# from the ConfigToolkit, at some point an error class hierarchy
+# rooted in this class might be developed.
+#
+class Error < RuntimeError; end
+
 #
 # Since Ruby does not have a boolean type (TrueClass and FalseClass classes
 # for boolean values exist, but they descend from Object),
-# define an empty marker class that can be passed into the BaseConfig methods
-# to add new parameters in order to indicate that the parameter is a boolean
-# (the value of the parameter will be FalseClass or TrueClass, however).
+# this is an empty marker class that can be passed into the BaseConfig methods
+# to add new parameters (BaseConfig.add_required_param and
+# BaseConfig.add_optional_param) in order to indicate that the
+# parameter is a boolean (the value of the parameter will be +true+ or
+# +false+, however).  Boolean values can be written as "true"/"false" or as
+# "yes"/"no" in configuration files.
 #
 class Boolean; end
 
 #
-# The ConstrainedArray models an Array with a specified size
-# and with all elements being a specified class (basically, it models
-# the arrays generally offerred by statically typed languages).
+# ConstrainedArray classes model Arrays with specified sizes
+# and with all elements being instances of specified classes (basically,
+# they model the arrays generally offerred by statically typed languages).
 # A ConstrainedArray has:
-# 1.) A minimum number of elements (could be zero)
-# 2.) A maximum number of elements (could be infinity)
-# 3.) An element class
+# * A minimum number of elements (could be zero)
+# * A maximum number of elements (could be infinity)
+# * An element class (could be Object, which allows any class)
 #
 # A future enhancement might be to allow users to specify a different
 # class for each element.  Note that the ConstrainedArray also allows
@@ -25,13 +39,14 @@ class Boolean; end
 # just instances of its element class.  Thus, a ConstrainedArray containing
 # class Object essentially would have no class constraints.
 #
-# class ConstrainedArray actually is a class generator, similar to Struct.
-# Its new() method does *not* return a ConstrainedArray instance, but
-# instead returns a new class with the specified constraints that
-# descends from ConstrainedArray.  The class returned by new() is meant
-# to be used in the BaseConfig methods to add new parameters.  The
+# ConstrainedArray actually is a class generator, similar to Struct.
+# Its new method does *not* return a ConstrainedArray instance
+# but instead returns a new class with the specified constraints that
+# descends from ConstrainedArray.  The class returned by new is meant
+# to be used in the BaseConfig methods to add new parameters
+# (BaseConfig.add_required_param and BaseConfig.add_optional_param).  The
 # value of one of these parameters actually will be a native Ruby
-# Array, but one that satisifes the constraints contained in
+# Array, but one that is guaranteed to satisify the constraints contained in
 # the ConstrainedArray class.
 #
 class ConstrainedArray
@@ -46,13 +61,13 @@ class ConstrainedArray
     attr_reader :element_class
 
     #
-    # The minimum number of elements, or nil if there is no
+    # The minimum number of elements, or +nil+ if there is no
     # minimum.
     #
     attr_reader :min_num_elements
 
     #
-    # The maximum number of elements, or nil if there is no
+    # The maximum number of elements, or +nil+ if there is no
     # maximum.
     #
     attr_reader :max_num_elements
@@ -62,23 +77,24 @@ class ConstrainedArray
   # ====Description:
   # This method does *not* return a ConstrainedArray instance.  Instead,
   # it returns a new ConstrainedArray child class that represents
-  # an array with the constraints specified in the method arguments.
+  # an Array with the constraints specified in the method arguments.
   # This class can be passed as a parameter class into the BaseConfig methods
-  # to add parameters.
+  # to add parameters (BaseConfig.add_required_param and
+  # BaseConfig.add_optional_param).
   # 
   # ====Parameters:
   # [element_class]
   #      This constrains all elements of the generated ConstrainedArray
-  #      class to be of this class or one of its child classes.
-  #      If this argument is object, then this constraint effectively
+  #      class to be of this class or of one of its child classes.
+  #      If this argument is Object, then this constraint effectively
   #      disappears.
-  # [min_num_elements = nil]
+  # [min_num_elements]
   #      This constrains the generated ConstrainedArray class to have
-  #      at least min_num_elements elements; if this argument is nil or zero,
-  #      the constraint effectively disappears.
-  # [max_num_elements = nil]
+  #      at least +min_num_elements+ elements; if this argument is +nil+ or
+  #      zero, the constraint effectively disappears.
+  # [max_num_elements]
   #      This constrains the generated ConstrainedArray class to have
-  #      at most max_num_elements elements; if this argument is nil,
+  #      at most +max_num_elements+ elements; if this argument is +nil+,
   #      the constraint effectively disappears.
   # 
   # ====Returns:

data/lib/configtoolkit/writer.rb

@@ -0,0 +1,116 @@
+#!/usr/bin/env ruby
+
+module ConfigToolkit
+
+#
+# This is an "abstract class" that documents the Writer interface.
+# I put "abstract class" in quotes because Ruby of course neither supports
+# nor requires abstract classes (that is, one can create a new writer class
+# without extending Writer).  It solely serves to document the interface.
+#
+# Writers write configuration (represented by Hashes of parameter names to
+# parameter values with the parameter names being Strings or Symbols and
+# the parameter values being scalars, Hashes, or Arrays) to some underlying
+# data sink (the write method).
+#
+# Writers must implement require_symbol_parameter_names? in order to
+# advertise whether they want parameter names as Strings or Symbols in the
+# Hash passed to the write method.
+#
+class Writer
+  # 
+  # ====Description:
+  # This is a concrete method that may be useful to Writers.  It
+  # returns a Hash containing (possibly nested) entries for
+  # +containing_object_name+ and, in the last object name's Hash,
+  # +config_hash+.  Basically, it returns a Hash that reflects
+  # +config_hash+ *and* +containing_object_name+.
+  # 
+  # Some Writers may want to display containing objects in a special way,
+  # in which case the arguments to the +write+ method (the configuration Hash
+  # and the containing object name) allow them to do so.  For Writers
+  # that do not want any special handling for containing objects,
+  # however, this method can convert that information into a
+  # single Hash representation in which the configuration parameters
+  # are nested within Hashes for the containing objects (this matches
+  # the format returned by readers, as they do not know about
+  # containing objects).
+  # 
+  # This should *not* be re-implemented by writers.
+  #
+  # ====Parameters:
+  # [config_hash]
+  #      A configuration represented as a Hash
+  # [containing_object_name]
+  #      The configuration's containing object name
+  # 
+  # ====Returns:
+  # A Hash in which +config_hash+ is nested within Hashes for the
+  # containing objects in +containing_object_name+
+  # 
+  def create_containing_object_hash(config_hash, containing_object_name)
+    if(containing_object_name.empty?())
+      return config_hash
+    else
+      use_symbol_parameter_names = require_symbol_parameter_names?()
+
+      containing_object_hash = {}
+      object_hash = containing_object_hash
+      
+      object_names = containing_object_name.split(".")
+      object_names.each_with_index do |object_name, index|
+        #
+        # The hash for the last object in containing_object_name must
+        # be config_hash, so it gets treated specially.
+        #
+        if(index < (object_names.size() - 1))
+          contained_hash = {}
+        else
+          contained_hash = config_hash
+        end
+
+        if(use_symbol_parameter_names)
+          object_hash[object_names[index].to_sym()] = contained_hash
+        else
+          object_hash[object_names[index]] = contained_hash
+        end
+        
+        object_hash = contained_hash
+      end
+
+      return containing_object_hash
+    end
+  end
+
+  public
+  # 
+  # This *must* be implemented by Writers.
+  # 
+  # ====Returns:
+  # Returns +true+ if and only if the Writer requires Symbol parameter
+  # names (rather than String parameter names) in the Hash passed to write.
+  # 
+  def require_symbol_parameter_names?
+    raise NotImplementedError, "abstract method called"
+  end
+
+  # 
+  # ====Description:
+  # This method writes the configuration in +config_hash+, with
+  # containing object name +containing_object_name+, to the
+  # underlying data sink.
+  #
+  # This *must* be implemented by Writers.
+  # 
+  # ====Parameters:
+  # [config_hash]
+  #      A configuration represented as a Hash
+  # [containing_object_name]
+  #      The configuration's containing object name
+  # 
+  def write(config_hash, containing_object_name)
+    raise NotImplementedError, "abstract method called"
+  end
+end
+
+end

data/lib/configtoolkit/yamlreader.rb

@@ -1,24 +1,28 @@
 #!/usr/bin/env ruby
+require 'configtoolkit/reader'
+
 require 'yaml'
 
 module ConfigToolkit
 
 #
-# This class implements the reader interface for
+# This class implements the Reader interface for
 # YAML configuration files.  It basically is a wrapper
 # over Ruby's YAML library.
 #
-class YAMLReader
+# See YAML.txt for more details.
+#
+class YAMLReader < Reader
   #
   # ====Description:
-  # This constructs a YAMLReader instance for stream,
-  # where stream either is a file name (a String)
+  # This constructs a YAMLReader instance for +stream+,
+  # where +stream+ either is a file name (a String)
   # or an IO object.
   # 
   # ====Parameters:
   # [stream]
   #      A file name (String) or an IO object.  If
-  #      stream is a file name, then the YAMLReader
+  #      +stream+ is a file name, then the YAMLReader
   #      will open the associated file.
   # 
   def initialize(stream)
@@ -31,7 +35,7 @@ class YAMLReader
 
   # 
   # ====Returns:
-  # the contents of the next YAML document read from the underlying
+  # The contents of the next YAML document read from the underlying
   # stream.
   # 
   def read

data/lib/configtoolkit/yamlwriter.rb

@@ -1,45 +1,50 @@
 #!/usr/bin/env ruby
+
+require 'configtoolkit/hasharrayvisitor'
+require 'configtoolkit/writer'
+
 require 'yaml'
 
 module ConfigToolkit
 
 #
-# This class implements the writer interface for
+# This class implements the Writer interface for
 # YAML configuration files.  It basically is a wrapper
 # over Ruby's YAML library.
 #
 # YAML natively supports Integers, Floats, Strings, and Booleans.
 # Instances of other classes are written by Ruby to YAML configuration
 # files by recursively writing each of the instance's variables and
-# noting in the YAML file the associated Ruby classes.  This may not
+# noting the associated Ruby class in the YAML file.  This may not
 # be desired behavior for a configuration file, especially if the file
 # is going to be shared with a non-Ruby program.  On the other hand,
 # if only Ruby is using the configuration the file, this behavior may
 # well be very desirable (since arbitrarily complex objects can be
-# supported properly by the YAML format).  Thus, the YAMLWriter
+# supported directly by the YAML format).  Thus, the YAMLWriter
 # offers two options:
 # * Only standard YAML classes will be written.  Values of classes
-#   not supported natively by YAML will be converted to Strings.
-# * Non-standard YAML classes will be written.
+#   not supported natively by YAML will be converted to Strings (with +to_s+).
+# * Non-standard YAML classes will be written (Ruby object->YAML serialization).
+#
+# See YAML.txt for more details.
 #
-class YAMLWriter
+class YAMLWriter < Writer
   #
   # ====Description:
-  # This constructs a YAMLWriter instance for stream,
-  # where stream either is a file name (a String)
-  # or an IO object.  If only_output_standard_yaml_classes, then
+  # This constructs a YAMLWriter instance for +stream+,
+  # where +stream+ either is a file name (a String)
+  # or an IO object.  If +only_output_standard_yaml_classes+, then
   # the writer only will output standard YAML classes; all classes not
-  # native to YAML will be converted into Strings before being
-  # written.  If !only_output_standard_yaml_classes, however, then
+  # native to YAML will be converted into Strings with +to_s+ before being
+  # written.  If not +only_output_standard_yaml_classes+, however, then
   # Ruby serialized classes will be written to the configuration
   # file.
   #
   # ====Parameters:
   # [stream]
   #      A file name (String) or an IO object.  If
-  #      stream is a file name, then the YAMLReader
+  #      +stream+ is a file name, then the YAMLWriter
   #      will open the associated file.
-  #
   # [only_output_standard_yaml_classes]
   #      Whether or not the writer should output only standard
   #      YAML classes.
@@ -53,86 +58,123 @@ class YAMLWriter
 
     @only_output_standard_yaml_classes = only_output_standard_yaml_classes
   end
-  
-  # 
-  # ====Description:
-  # This method converts value to an equivalent representation
-  # in a standard YAML class.  In particular,
-  # * Hash eleemnts are converted with a
-  #   convert_hash_value_to_standard_yaml_classes call
-  # * Arrays elements are converted with recursive
-  #   convert_value_to_standard_yaml_class calls
-  # * Non-standard YAML classes are converted to Strings (via to_s)
-  # 
-  # ====Parameters:
-  # [value]
-  #      The value to convert
-  # 
-  # ====Returns:
-  # An equivalent representation of value in a standard YAML class
-  # 
-  def convert_value_to_standard_yaml_class(value)
-    if(value.class == Hash)
-      return convert_hash_values_to_standard_yaml_classes(value)
-    elsif(value.class == Array)
-      new_value = []
-
-      value.each do |element|
-        new_value.push(convert_value_to_standard_yaml_class(element))
+
+  #
+  # This class is used for converting the elements of the structure
+  # passed to write to standard YAML types.  See the comments for
+  # HashArrayVisitor for details on how this visitor works.
+  #
+  # As this visitor visits the nodes of a structure, it builds up a parallel
+  # structure that is the same as the original except that all elements are
+  # of standard YAML types.
+  #
+  class Visitor < HashArrayVisitor # :nodoc:
+    #
+    # The structure currently being built.
+    #
+    attr_reader :config_hash
+
+    #
+    # A StackFrame contains the container currently being
+    # built.
+    #
+    StackFrame = Struct.new(:container)
+
+    def initialize
+      @config_hash = {}
+      @next_container = @config_hash
+
+      super()
+    end
+
+    # 
+    # ====Description:
+    # This method returns a representation of value using
+    # standard YAML types.
+    # 
+    # ====Parameters:
+    # [value]
+    #      The value to convert
+    # 
+    # ====Returns:
+    # A standard YAML representation of value
+    # 
+    def convert_value(value)
+      if(value.is_a?(Hash))
+        return {}
+      elsif(value.is_a?(Array))
+        return []
+      elsif((value.class <= Integer) ||
+            (value.class <= Float) ||
+            (value.class == TrueClass) ||
+            (value.class == FalseClass) ||
+            (value.class == String))
+        return value
+      else
+        return value.to_s
       end
+    end
+    private :convert_value
 
-      return new_value
-    elsif((value.class <= Integer) ||
-          (value.class <= Float) ||
-          (value.class == TrueClass) ||
-          (value.class == FalseClass) ||
-          (value.class == String))
-      return value
-    else
-      return value.to_s
+    def enter_hash(hash)
+      return StackFrame.new(@next_container)
+    end
+
+    def visit_hash_element(key, value, index, is_container)
+      converted_value = convert_value(value)
+
+      if(is_container)
+        @next_container = converted_value
+      end
+
+      stack_top().container[key] = converted_value
+    end
+    
+    def enter_array(array)
+      return StackFrame.new(@next_container)
+    end
+    
+    def visit_array_element(value, index, is_container)
+      converted_value = convert_value(value)
+
+      if(is_container)
+        @next_container = converted_value
+      end
+
+      stack_top().container.push(converted_value)
     end
   end
-  private :convert_value_to_standard_yaml_class
 
-  # 
-  # ====Description:
-  # This method converts all elements of hash_value to standard
-  # YAML classes via convert_value_to_standard_yaml_class calls.
-  # 
-  # ====Parameters:
-  # [hash_value]
-  #      The Hash to convert
   # 
   # ====Returns:
-  # An equivalent Hash, the values of which are of standard YAML classes.
+  # Returns +false+, since the YAMLWriter requires String parameter names
+  # in the Hash passed to write.
   # 
-  def convert_hash_values_to_standard_yaml_classes(hash_value)
-    standard_yaml_class_hash_value = {}
-    
-    hash_value.each do |param_name, value|
-      standard_yaml_class_hash_value[param_name] = convert_value_to_standard_yaml_class(value)
-    end
-
-    return standard_yaml_class_hash_value
+  def require_symbol_parameter_names?
+    return false
   end
-  private :convert_hash_values_to_standard_yaml_classes
 
   # 
   # ====Description:
-  # This method writes config_hash to the underlying stream.
+  # This method writes +config_hash+ to the underlying stream.
   # 
   # ====Parameters:
   # [config_hash]
   #      The configuration hash to write
+  # [containing_object_name]
+  #      The configuration's containing object name
   # 
-  def write(config_hash)
+  def write(config_hash, containing_object_name)
     if(@only_output_standard_yaml_classes)
-      output_hash = convert_hash_values_to_standard_yaml_classes(config_hash)
+      visitor = Visitor.new()
+      visitor.visit(config_hash)
+      output_hash = visitor.config_hash
     else
       output_hash = config_hash
     end
 
-    YAML::dump(output_hash, @stream)
+    containing_object_hash = create_containing_object_hash(output_hash, containing_object_name)
+    YAML::dump(containing_object_hash, @stream)
     @stream.flush()
   end
 end