configtoolkit 1.0.6 → 1.0.7

data/lib/configtoolkit/types.rb

@@ -40,8 +40,21 @@ class ConstrainedArray
   # store the constraints.
   #
   class << self
+    #
+    # The class of all of the elements.
+    #
     attr_reader :element_class
+
+    #
+    # 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
+    # maximum.
+    #
     attr_reader :max_num_elements
   end
 

data/lib/configtoolkit/yamlreader.rb

@@ -3,7 +3,24 @@ require 'yaml'
 
 module ConfigToolkit
 
+#
+# This class implements the reader interface for
+# YAML configuration files.  It basically is a wrapper
+# over Ruby's YAML library.
+#
 class YAMLReader
+  #
+  # ====Description:
+  # 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
+  #      will open the associated file.
+  # 
   def initialize(stream)
     if(stream.class == String)
       @stream = File.open(stream, "r")
@@ -12,6 +29,11 @@ class YAMLReader
     end
   end
 
+  # 
+  # ====Returns:
+  # the contents of the next YAML document read from the underlying
+  # stream.
+  # 
   def read
     return YAML::load(@stream)
   end

data/lib/configtoolkit/yamlwriter.rb

@@ -3,57 +3,136 @@ require 'yaml'
 
 module ConfigToolkit
 
+#
+# 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
+# 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
+# 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.
+#
 class YAMLWriter
-  def initialize(stream, only_output_standard_yaml_types)
+  #
+  # ====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
+  # 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
+  # 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
+  #      will open the associated file.
+  #
+  # [only_output_standard_yaml_classes]
+  #      Whether or not the writer should output only standard
+  #      YAML classes.
+  # 
+  def initialize(stream, only_output_standard_yaml_classes)
     if(stream.class == String)
       @stream = File.open(stream, "w")
     else
       @stream = stream
     end
 
-    @only_output_standard_yaml_types = only_output_standard_yaml_types
+    @only_output_standard_yaml_classes = only_output_standard_yaml_classes
   end
   
-  def convert_value_to_standard_yaml_type(param_value)
-    if(param_value.class == Hash)
-      return convert_hash_values_to_standard_yaml_types(param_value)
-    elsif(param_value.class == Array)
-      new_param_value = []
-
-      param_value.each do |element|
-        new_param_value.push(convert_value_to_standard_yaml_type(element))
+  # 
+  # ====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))
       end
 
-      return new_param_value
-    elsif((param_value.class <= Integer) ||
-          (param_value.class <= Float) ||
-          (param_value.class == TrueClass) ||
-          (param_value.class == FalseClass) ||
-          (param_value.class == String))
-      return param_value
+      return new_value
+    elsif((value.class <= Integer) ||
+          (value.class <= Float) ||
+          (value.class == TrueClass) ||
+          (value.class == FalseClass) ||
+          (value.class == String))
+      return value
     else
-      return param_value.to_s
+      return value.to_s
     end
   end
+  private :convert_value_to_standard_yaml_class
 
-  def convert_hash_values_to_standard_yaml_types(config_hash)
-    standard_yaml_typed_config_hash = {}
+  # 
+  # ====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.
+  # 
+  def convert_hash_values_to_standard_yaml_classes(hash_value)
+    standard_yaml_class_hash_value = {}
     
-    config_hash.each do |param_name, param_value|
-      standard_yaml_typed_config_hash[param_name] = convert_value_to_standard_yaml_type(param_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_typed_config_hash
+    return standard_yaml_class_hash_value
   end
+  private :convert_hash_values_to_standard_yaml_classes
 
+  # 
+  # ====Description:
+  # This method writes config_hash to the underlying stream.
+  # 
+  # ====Parameters:
+  # [config_hash]
+  #      The configuration hash to write
+  # 
   def write(config_hash)
-    if(@only_output_standard_yaml_types)
-      output_config_hash = convert_hash_values_to_standard_yaml_types(config_hash)
+    if(@only_output_standard_yaml_classes)
+      output_hash = convert_hash_values_to_standard_yaml_classes(config_hash)
     else
-      output_config_hash = config_hash
+      output_hash = config_hash
     end
 
-    YAML::dump(output_config_hash, @stream)
+    YAML::dump(output_hash, @stream)
     @stream.flush()
   end
 end

data/test/test_yaml.rb

@@ -13,17 +13,17 @@ class YAMLTest < Test::Unit::TestCase
     run_reader_test(ConfigToolkit::YAMLReader,
                     "",
                     REFERENCE_SAMPLE_CONFIG,
-                    get_test_config_file_name("sample.standard_yaml_types.yaml"))
+                    get_test_config_file_name("sample.standard_yaml_classes.yaml"))
     
     run_reader_test(ConfigToolkit::YAMLReader,
                     "",
                     REFERENCE_SAMPLE_CONFIG,
-                    get_test_config_file_name("sample.ruby_yaml_types.yaml"))
+                    get_test_config_file_name("sample.ruby_yaml_classes.yaml"))
     
     run_reader_test(ConfigToolkit::YAMLReader,
                     "",
                     REFERENCE_SAMPLE_CONFIG,
-                    File.new(get_test_config_file_name("sample.ruby_yaml_types.yaml"), "r"))
+                    File.new(get_test_config_file_name("sample.ruby_yaml_classes.yaml"), "r"))
     
     run_reader_test(ConfigToolkit::YAMLReader,
                     "contained_sample",
@@ -34,23 +34,23 @@ class YAMLTest < Test::Unit::TestCase
   def test_writers
     run_writer_test(ConfigToolkit::YAMLWriter,
                     REFERENCE_SAMPLE_CONFIG,
-                    get_test_config_file_name("sample.standard_yaml_types.yaml"),
-                    get_test_config_file_name("sample.standard_yaml_types.dumped.yaml"),
-                    get_test_config_file_name("sample.standard_yaml_types.dumped.yaml"),
+                    get_test_config_file_name("sample.standard_yaml_classes.yaml"),
+                    get_test_config_file_name("sample.standard_yaml_classes.dumped.yaml"),
+                    get_test_config_file_name("sample.standard_yaml_classes.dumped.yaml"),
                     true)
     
     run_writer_test(ConfigToolkit::YAMLWriter,
                     REFERENCE_SAMPLE_CONFIG,
-                    get_test_config_file_name("sample.ruby_yaml_types.yaml"),
-                    get_test_config_file_name("sample.ruby_yaml_types.dumped.yaml"),
-                    get_test_config_file_name("sample.ruby_yaml_types.dumped.yaml"),
+                    get_test_config_file_name("sample.ruby_yaml_classes.yaml"),
+                    get_test_config_file_name("sample.ruby_yaml_classes.dumped.yaml"),
+                    get_test_config_file_name("sample.ruby_yaml_classes.dumped.yaml"),
                     false)
     
     run_writer_test(ConfigToolkit::YAMLWriter,
                     REFERENCE_SAMPLE_CONFIG,
-                    get_test_config_file_name("sample.standard_yaml_types.yaml"),
-                    get_test_config_file_name("sample.standard_yaml_types.dumped.yaml"),
-                    File.new(get_test_config_file_name("sample.standard_yaml_types.dumped.yaml"), "w"),
+                    get_test_config_file_name("sample.standard_yaml_classes.yaml"),
+                    get_test_config_file_name("sample.standard_yaml_classes.dumped.yaml"),
+                    File.new(get_test_config_file_name("sample.standard_yaml_classes.dumped.yaml"), "w"),
                     true)
     
     run_writer_test(ConfigToolkit::YAMLWriter,
@@ -65,8 +65,8 @@ class YAMLTest < Test::Unit::TestCase
     run_reader_writer_test(ConfigToolkit::YAMLReader,
                            ConfigToolkit::YAMLWriter,
                            REFERENCE_SAMPLE_CONFIG,
-                           [get_test_config_file_name("sample.standard_yaml_types.dumped.yaml")],
-                           [get_test_config_file_name("sample.standard_yaml_types.dumped.yaml"), false])
+                           [get_test_config_file_name("sample.standard_yaml_classes.dumped.yaml")],
+                           [get_test_config_file_name("sample.standard_yaml_classes.dumped.yaml"), false])
     run_reader_writer_test(ConfigToolkit::YAMLReader,
                            ConfigToolkit::YAMLWriter,
                            REFERENCE_CONTAINED_SAMPLE_CONFIG,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: configtoolkit
 version: !ruby/object:Gem::Version 
-  version: 1.0.6
+  version: 1.0.7
 platform: ruby
 authors: 
 - DesigningPatterns
@@ -52,8 +52,8 @@ files:
 - test/contained_sample.yaml
 - test/firewall.yaml
 - test/machines.yaml
-- test/sample.ruby_yaml_types.yaml
-- test/sample.standard_yaml_types.yaml
+- test/sample.ruby_yaml_classes.yaml
+- test/sample.standard_yaml_classes.yaml
 - test/webserver.yaml
 has_rdoc: true
 homepage: http://configtoolkit.rubyforge.org/