configtoolkit 1.0.4 → 1.0.5

data/History.txt

@@ -1,3 +1,6 @@
+=== 1.0.5 / 2008-05-13
+Improve the code comments.
+
 === 1.0.4 / 2008-05-12
 Improve the code comments.
 

data/Rakefile

@@ -7,7 +7,7 @@ require 'hoe'
 
 $stderr = STDERR
 
-Hoe.new('configtoolkit', "1.0.4") do |p|
+Hoe.new('configtoolkit', "1.0.5") do |p|
   p.developer('DesigningPatterns', 'technical.inquiries@designingpatterns.com')
 end
 

data/lib/configtoolkit/baseconfig.rb

@@ -4,21 +4,69 @@ require 'pathname'
 require 'set'
 require 'uri'
 
-#
-# Tomorrow:
-# 7.) Ruby gems
-# 11.) Write lots of readers + writers
-# 13.) Clean up cast?
-# 14.) Production comments
-#
 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.
+#
+# 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
+# (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.
+# 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.
+#
+# 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.
+#
 class BaseConfig
+  
+  #
+  # This class represents the specification for a parameter.  Right now,
+  # a parameter specification consists of:
+  # 1.) The parameter name (Symbol)
+  # 2.) The parameter value class (Class)
+  # 3.) Whether or not the parameter is required
+  # 4.) If the parameter is not required, a default value
+  #
   class ParamSpec
     attr_reader :name
     attr_reader :value_class
     attr_reader :default_value # Only meaningful if is_required?
 
+    # 
+    # ====Description:
+    # 
+    # 
+    # ====Parameters:
+    # [name]
+    #      ?
+    # [value_class]
+    #      ?
+    # [is_required]
+    #      ?
+    # [default_value]
+    #      ?
+    # 
+    # ====Returns:
+    # 
+    # 
     def initialize(name, value_class, is_required, default_value)
       @name = name
       @value_class = value_class
@@ -29,6 +77,13 @@ class BaseConfig
       end
     end
 
+    # 
+    # ====Description:
+    # 
+    # 
+    # ====Returns:
+    # 
+    # 
     def is_required?
       return @is_required
     end
@@ -59,6 +114,17 @@ class BaseConfig
     attr_reader :required_params
   end
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [child_class]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def self.inherited(child_class)
     #
     # Initialize the class instance variables.
@@ -71,6 +137,25 @@ class BaseConfig
     end
   end
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [name]
+  #      ?
+  # [value_class]
+  #      ?
+  # [is_required]
+  #      ?
+  # [default_value]
+  #      ?
+  # [validate_value_block]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def self.add_param(name,
                      value_class,
                      is_required,
@@ -132,6 +217,21 @@ class BaseConfig
   end
   private_class_method :add_param
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [name]
+  #      ?
+  # [value_class]
+  #      ?
+  # [validate_value_block]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def self.add_required_param(name,
                               value_class,
                               &validate_value_block)
@@ -139,6 +239,23 @@ class BaseConfig
   end
   private_class_method :add_required_param
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [name]
+  #      ?
+  # [value_class]
+  #      ?
+  # [default_value]
+  #      ?
+  # [validate_value_block]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def self.add_optional_param(name,
                               value_class,
                               default_value,
@@ -148,6 +265,14 @@ class BaseConfig
   private_class_method :add_optional_param
 
   attr_reader :containing_object_name
+
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Returns:
+  # 
+  # 
   def initialize
     @containing_object_name = ""
     @params_with_values = Set.new()
@@ -157,6 +282,17 @@ class BaseConfig
     end
   end
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [operation_name]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def enforce_specs(operation_name)
     #
     # Iterate through the parameters without values.  If any are
@@ -207,9 +343,17 @@ class BaseConfig
   private :enforce_specs
 
   #
+  # ====Description:
   # Because the to_s in Ruby 1.8 for the Array and Hash classes
   # are horrible...
-  #
+  # 
+  # ====Parameters:
+  # [value]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def construct_value_str(value)
     if(value.is_a?(Array))
       str = "["
@@ -243,6 +387,21 @@ class BaseConfig
   end
   private :construct_value_str
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [param_name]
+  #      ?
+  # [value]
+  #      ?
+  # [message]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def construct_error_message(param_name, value, message)
     if(@containing_object_name.empty?)
       full_param_name = ""
@@ -256,10 +415,32 @@ class BaseConfig
   end
   private :construct_error_message
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [message]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def raise_error(message)
     raise Error, message, caller()
   end
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [rhs]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def ==(rhs)
     if(rhs == nil)
       return false
@@ -274,6 +455,19 @@ class BaseConfig
     return true
   end
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [value_class]
+  #      ?
+  # [value]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def dump_value_impl(value_class, value)
     if(value_class < BaseConfig)
       return value.dump_impl({})
@@ -289,6 +483,17 @@ class BaseConfig
   end
   private :dump_value_impl
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [containing_object_hash]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def dump_impl(containing_object_hash)
     #
     # Configuration never will be dumped without the
@@ -304,6 +509,17 @@ class BaseConfig
   end
   protected :dump_impl
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [writer]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def dump(writer)
     dump_hash = {}
     containing_object_hash = dump_hash
@@ -318,6 +534,21 @@ class BaseConfig
     writer.write(dump_hash)
   end
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [param_name]
+  #      ?
+  # [value_class]
+  #      ?
+  # [value]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def load_value_impl(param_name, value_class, value)
     if(value.class <= value_class)
       #
@@ -409,6 +640,19 @@ class BaseConfig
   end
   private :load_value_impl
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [containing_object_hash]
+  #      ?
+  # [containing_object_name]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def load_impl(containing_object_hash, containing_object_name)
     @containing_object_name = containing_object_name
     @params_with_values.clear()
@@ -438,6 +682,19 @@ class BaseConfig
   end
   protected :load_impl
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [reader]
+  #      ?
+  # [containing_object_name = ""]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def load(reader, containing_object_name = "")
     param_hash = reader.read
 
@@ -478,12 +735,42 @@ class BaseConfig
     load_impl(containing_object_hash, containing_object_name)
   end
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [reader]
+  #      ?
+  # [containing_object_name = ""]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def self.load(reader, containing_object_name = "")
     instance = new()
     instance.load(reader, containing_object_name)
     return instance
   end
   
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [str]
+  #      ?
+  # [indent]
+  #      ?
+  # [value_class]
+  #      ?
+  # [value]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def write_value_impl(str, indent, value_class, value)
     nesting_indent = indent + NESTING_INDENT
     if(value != nil)
@@ -522,6 +809,19 @@ class BaseConfig
   end
   private :write_value_impl
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Parameters:
+  # [str]
+  #      ?
+  # [indent]
+  #      ?
+  # 
+  # ====Returns:
+  # 
+  # 
   def write_impl(str, indent)
     self.class.param_spec_list.each do |param_spec|
       name_field_length = self.class.longest_param_name_length
@@ -533,6 +833,13 @@ class BaseConfig
   end
   protected :write_impl
 
+  # 
+  # ====Description:
+  # 
+  # 
+  # ====Returns:
+  # 
+  # 
   def to_s
     #
     # Print out config file name and the containing object_name and then

data/lib/configtoolkit/toolkit.rb

@@ -2,13 +2,19 @@
 module ConfigToolkit
 
 #
-# All exceptions thrown from the Toolkit descend from
-# this one; at some point, an exception class hierarchy
+# All exceptions thrown from the ConfigToolkit descend from
+# this one; while right now it is the only exception thrown
+# from the ConfigToolkit, at some point, an exception class hierarchy
 # rooted in this class might be developed.
 #
 class Error < RuntimeError; end
 
 end
 
+#
+# Load up the files necessary to specify a config.
+# Users will need to load explicitly whichever readers
+# and writers they wish to use.
+#
 require 'configtoolkit/types'
 require 'configtoolkit/baseconfig'

data/lib/configtoolkit/types.rb

@@ -3,27 +3,27 @@ module ConfigToolkit
 
 #
 # Since Ruby does not have a boolean type (TrueClass and FalseClass classes
-# 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).
+# 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).
 #
 class Boolean; end
 
 #
 # The ConstrainedArray models an Array with a specified size
-# and with all elements being a specified type (basically, it models
-# the arrays generally offerred by static typing languages).
+# and with all elements being a specified class (basically, it models
+# the arrays generally offerred by statically typed languages).
 # A ConstrainedArray has:
-# 1.) A minimum number of elements
-# 2.) A maximum number of elements
-# 3.) An element type
+# 1.) A minimum number of elements (could be zero)
+# 2.) A maximum number of elements (could be infinity)
+# 3.) An element class
 #
 # A future enhancement might be to allow users to specify a different
-# type for each element.  Note that the Constrained Array also allows
-# elements to be instances of a child class of its element type, not
-# just instances of its element type.  Thus, a ConstrainedArray containing
-# type Object essentially would have no type constraints.
+# class for each element.  Note that the ConstrainedArray also allows
+# elements to be instances of a child class of its element class, not
+# 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
@@ -31,7 +31,7 @@ class Boolean; end
 # descends from ConstrainedArray.  The class returned by new() is meant
 # to be used in the BaseConfig methods to add new parameters.  The
 # value of one of these parameters actually will be a native Ruby
-# Array, just one that satisifes the constraints contained in
+# Array, but one that satisifes the constraints contained in
 # the ConstrainedArray class.
 #
 class ConstrainedArray
@@ -45,6 +45,32 @@ class ConstrainedArray
     attr_reader :max_num_elements
   end
 
+  # 
+  # ====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.
+  # This class can be passed as a parameter class into the BaseConfig methods
+  # to add parameters.
+  # 
+  # ====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
+  #      disappears.
+  # [min_num_elements = nil]
+  #      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]
+  #      This constrains the generated ConstrainedArray class to have
+  #      at most max_num_elements elements; if this argument is nil,
+  #      the constraint effectively disappears.
+  # 
+  # ====Returns:
+  # A ConstrainedArray child class with the specified constraints.
+  # 
   def self.new(element_class, min_num_elements = nil, max_num_elements = nil)
     return Class.new(ConstrainedArray) do
       @element_class = element_class

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: configtoolkit
 version: !ruby/object:Gem::Version 
-  version: 1.0.4
+  version: 1.0.5
 platform: ruby
 authors: 
 - DesigningPatterns
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-05-13 00:00:00 -04:00
+date: 2008-05-14 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency