configtoolkit 1.0.0

data/History.txt

@@ -0,0 +1,3 @@
+=== 1.0.0 / 2008-05-12
+Initial release of the ConfigToolkit.  This release includes readers and
+writers for YAML config files.  The package is unit tested fully.

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Designing Patterns
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.txt

@@ -0,0 +1,67 @@
+= configtoolkit
+
+* http://configtoolkit.rubyforge.org/
+
+== DESCRIPTION:
+
+This package makes sourcing information from configuration files robust
+and easy!  It:
+* Allows programmers to specify the type of data that should be returned
+  from a configuration file.  The toolkit automatically will validate
+  the file's data against this specification when loading the file, ensuring
+  that the specifications always are met and saving the programmer the tedious
+  chore of writing validation code.
+* Allows programmers to easily programatically create and dump new
+  configuration files.
+* Provides classes that can load from and dump to different kinds of
+  configuration files, including YAML configuration files.
+
+== FEATURES/PROBLEMS:
+
+None (known).
+
+== SYNOPSIS:
+
+  class MachineConfig < ConfigToolkit::BaseConfig
+    add_required_param(:name, String)
+
+    add_required_param(:architecture, String)
+
+    add_required_param(:os, String)
+
+    add_required_param(:num_cpus, Integer) do |value|
+      if(value <= 0)
+        raise_error("num_cpus must be greater than zero")
+      end
+    end
+
+    add_optional_param(:behind_firewall, ConfigToolkit::Boolean, true)
+
+    add_required_param(:contains_sensitive_data, ConfigToolkit::Boolean)
+
+    add_required_param(:addresses, ConfigToolkit::ConstrainedArray.new(URI, 2, 3))
+
+    def validate_all_values
+      if(contains_sensitive_data && !behind_firewall)
+        raise_error("a machine cannot contain sensitive data and not be behind the firewall")
+      end
+    end
+  end
+
+  This code creates a configuration class for a company's servers.  The
+  programmer specifies each of the parameters (the parameter's type, whether
+  the parameter is required, and a default value if the parameter is optional).
+
+  The programmer also specifies a method (validate_all_valus) that enforces
+  an invariant between multiple parameters.
+== REQUIREMENTS:
+
+Hoe is required, but only for running the tests.
+
+== INSTALL:
+
+sudo gem install configtoolkit
+
+== LICENSE:
+
+See LICENSE, at the root of the distribution.

data/Rakefile

@@ -0,0 +1,16 @@
+# -*- ruby -*-
+
+$LOAD_PATH.unshift("lib")
+
+require 'rubygems'
+require 'hoe'
+require 'configtoolkit.rb'
+
+$stderr = STDERR
+
+Hoe.new('configtoolkit', ConfigToolkit::VERSION) do |p|
+  ENV[VERSION] = ConfigToolkit::VERSION
+  p.developer('DesigningPatterns', 'technical.inquiries@designingpatterns.com')
+end
+
+# vim: syntax=Ruby

data/lib/configtoolkit.rb

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

data/lib/configtoolkit/baseconfig.rb

@@ -0,0 +1,555 @@
+#!/usr/bin/env ruby
+
+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
+
+class BaseConfig
+  class ParamSpec
+    attr_reader :name
+    attr_reader :value_class
+    attr_reader :default_value # Only meaningful if is_required?
+
+    def initialize(name, value_class, is_required, default_value)
+      @name = name
+      @value_class = value_class
+      @is_required = is_required
+
+      if(!is_required)
+        @default_value = default_value
+      end
+    end
+
+    def is_required?
+      return @is_required
+    end
+  end
+  
+  #
+  # The indentation used to indicate nesting when printing out
+  # a BaseConfig.
+  #
+  NESTING_INDENT = "  " * 2
+
+  #
+  # Create accessors for some class instance variables;
+  # these variables will contain the structure of each
+  # BaseConfig child class (which parameters are supported,
+  # which are required, etc.).
+  #
+  # The config parameters are stored in a list (@param_list) for ordered
+  # access (we want to print them out in the order in which they
+  # were added to the config) and in a hash (@param_hash), for fast lookups
+  # (as we want to check whether a parameter that we read from a file
+  # is supported by the class).
+  #
+  class << self
+    attr_reader :param_spec_list
+    attr_reader :param_spec_lookup_table
+    attr_reader :longest_param_name_length
+    attr_reader :required_params
+  end
+
+  def self.inherited(child_class)
+    #
+    # Initialize the class instance variables.
+    #
+    child_class.class_eval do
+      @param_spec_list = []
+      @param_spec_lookup_table = {}
+      @longest_param_name_length = 0
+      @required_params = Set.new()
+    end
+  end
+
+  def self.add_param(name,
+                     value_class,
+                     is_required,
+                     default_value,
+                     &validate_value_block)
+    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 setter method 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.
+    #
+    # Note that the setter will call load_value_impl() on any value
+    # that it is passed; this ensures that data specified programatically
+    # gets processed the same way as that sourced from files.
+    #
+    # There is a bit of hackiness to get the specified value class; the
+    # value class is retrieved from a lookup table rather
+    # than being sourced from value_class.  The reason for this is that the
+    # value_class argument could be an anonymous class without a valid name
+    # and so cannot safely be expanded in a string.  Instead, we'll access a
+    # variable storing this class from the param_spec_lookup_table.
+    #
+    methods = String.new()
+    methods << "attr_reader :#{name}\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"
+    if(validate_value_block != nil)
+      validate_value_method = "validate_#{name}_value".to_sym()
+      methods << "  begin\n"
+      methods << "    #{validate_value_method}(value)\n"
+      methods << "  rescue Error => e\n"
+      methods << "    raise Error, construct_error_message(\"#{name}\", value, e.message), e.backtrace()\n"
+      methods << "  end\n"
+    end
+
+    methods << "  @#{name} = loaded_value\n"
+    methods << "  @params_with_values.add(:#{name})\n"
+    methods << "end\n"
+
+    class_eval(methods)
+
+    if(validate_value_block != nil)
+      define_method(validate_value_method, &validate_value_block)
+    end
+
+    name_str = name.to_s
+    if(name_str.length > @longest_param_name_length)
+      @longest_param_name_length = name_str.length
+    end
+
+    if(is_required)
+      @required_params.add(name)
+    end
+  end
+  private_class_method :add_param
+
+  def self.add_required_param(name,
+                              value_class,
+                              &validate_value_block)
+    add_param(name, value_class, true, nil, &validate_value_block)
+  end
+  private_class_method :add_required_param
+
+  def self.add_optional_param(name,
+                              value_class,
+                              default_value,
+                              &validate_value_block)
+    add_param(name, value_class, false, default_value, &validate_value_block)
+  end
+  private_class_method :add_optional_param
+
+  attr_reader :containing_object_name
+  def initialize
+    @containing_object_name = ""
+    @params_with_values = Set.new()
+
+    self.class.param_spec_list.each do |param_spec|
+      instance_variable_set("@#{param_spec.name}", nil)
+    end
+  end
+
+  def enforce_specs(operation_name)
+    #
+    # Iterate through the parameters without values.  If any are
+    # required parameters, then throw (after completing the
+    # iteration in order to get the full list of missing
+    # parameters).  Otherwise, set all optional, missing
+    # parameters to their default values.
+    #
+    missing_params = []
+
+    self.class.param_spec_list.each do |param_spec|
+      if(!@params_with_values.include?(param_spec.name))
+        if(param_spec.is_required?)
+          missing_params.push(param_spec.name)
+        else
+          send("#{param_spec.name}=", param_spec.default_value)
+        end
+      end
+    end
+
+    if(!missing_params.empty?)
+      missing_param_spec_list = missing_params.map do |param_name|
+        if(@containing_object_name.empty?)
+          next "#{param_name}"
+        else
+          next "#{@containing_object_name}.#{param_name}"
+        end
+      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
+        message = "#{self.class}#validate_all_values #{operation_name} error"
+
+        if(!@containing_object_name.empty?)
+          message << " for #{@containing_object_name}"
+        end
+
+        message << ": #{e.message}"
+        raise Error, message, e.backtrace()
+      end
+    end
+  end
+  private :enforce_specs
+
+  #
+  # Because the to_s in Ruby 1.8 for the Array and Hash classes
+  # are horrible...
+  #
+  def construct_value_str(value)
+    if(value.is_a?(Array))
+      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))
+      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
+      end
+
+      str << "}"
+      return str
+    else
+      return value.to_s
+    end
+  end
+  private :construct_value_str
+
+  def construct_error_message(param_name, value, message)
+    if(@containing_object_name.empty?)
+      full_param_name = ""
+    else
+      full_param_name = "#{@containing_object_name}."
+    end
+
+    full_param_name += param_name
+
+    return "error setting parameter #{full_param_name} with value #{construct_value_str(value)}: #{message}."
+  end
+  private :construct_error_message
+
+  def raise_error(message)
+    raise Error, message, caller()
+  end
+
+  def ==(rhs)
+    if(rhs == nil)
+      return false
+    end
+    
+    self.class.param_spec_list.each do |param_spec|
+      if(send(param_spec.name) != rhs.send(param_spec.name))
+        return false
+      end
+    end
+
+    return true
+  end
+
+  def dump_value_impl(value_class, value)
+    if(value_class < BaseConfig)
+      return value.dump_impl({})
+    elsif(value_class < ConstrainedArray)
+      dumped_array = []
+      value.each do |element|
+        dumped_array.push(dump_value_impl(value_class.element_class, element))
+      end
+      return dumped_array
+    else
+      return value
+    end
+  end
+  private :dump_value_impl
+
+  def dump_impl(containing_object_hash)
+    #
+    # Configuration never will be dumped without the
+    # specifications first having been enforced.
+    #
+    enforce_specs("dump")
+
+    self.class.param_spec_list.each do |param_spec|
+      containing_object_hash[param_spec.name.to_s] = dump_value_impl(param_spec.value_class, send(param_spec.name))
+    end
+
+    return containing_object_hash
+  end
+  protected :dump_impl
+
+  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
+
+    dump_impl(containing_object_hash)
+    writer.write(dump_hash)
+  end
+
+  def load_value_impl(param_name, value_class, value)
+    if(value.class <= value_class)
+      #
+      # If the ConfigReader 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.
+      #
+      return value
+    elsif((value_class < BaseConfig) && (value.class == Hash))
+      #
+      # If we're looking for a BaseConfig child and have a hash, then
+      # construct the child with the hash.
+      #
+      child_config = value_class.new()
+
+      if(@containing_object_name.empty?)
+        nested_containing_object_name = param_name
+      else
+        nested_containing_object_name = "#{@containing_object_name}.#{param_name}"
+      end
+
+      child_config.load_impl(value, nested_containing_object_name)
+      return child_config
+    elsif((value_class < ConstrainedArray) && (value.class == Array))
+      #
+      # If we're looking for a ConstrainedArray and have a Ruby Array, then
+      # iterate over each element of the Ruby Array and recursively
+      # load it.
+      #
+      value.each_with_index do |element, index|
+        value[index] = load_value_impl("#{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, 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, value, message)
+      end
+
+      return value
+    elsif((value_class == Boolean) &&
+          ((value.class == TrueClass) || (value.class == FalseClass)))
+      #
+      # If we're looking for a Boolean, then we just can return
+      # the ConfigReader's value if it's true or false.
+      #
+      return value
+    elsif(value.class == String)
+      #
+      # Some ConfigReaders only may return strings and leave it up to
+      # the caller to figure out the proper types for the parameters.
+      # In our case, we'll levarage Ruby's built-in conversion functions
+      # to support the most common parameter types.  Should this be
+      # made extensible?
+      #
+      case
+      when (value_class <= Integer)
+        return Integer(value)
+      when (value_class <= Float)
+        return Float(value)
+      when (value_class <= Pathname)
+        return Pathname(value)
+      when (value_class <= Symbol)
+        return value.to_sym()
+      when (value_class <= URI)
+        return URI(value)
+      when (value_class == Boolean)
+        #
+        # Support both yes/no and true/false boolean values.
+        #
+        if((value.casecmp("yes") == 0) || (value.casecmp("true") == 0))
+          return true
+        elsif((value.casecmp("no") == 0)|| (value.casecmp("false") == 0))
+          return false
+        end
+      end
+    end
+
+    message = "cannot convert from value class #{value.class.name} to specified class #{value_class.name}"
+    raise Error, construct_error_message(param_name, value, message)
+  end
+  private :load_value_impl
+
+  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")
+  end
+  protected :load_impl
+
+  def load(reader, containing_object_name = "")
+    param_hash = reader.read
+
+    if(param_hash.class != Hash)
+      message =  "#{reader.class}#read returned #{param_hash.class} "
+      message << "rather than Hash"
+      raise Error, message
+    end
+
+    #
+    # Work through the param_hash until 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 search
+    # for tokyo.  Not being able to find one of the objects is not
+    # (necessarily) an error; that just means that none of the parameters will
+    # be set from param_hash, which is allowable if all of the parameters
+    # are optional (this might happen, for instance, if the config file
+    # is empty).  On the other hand, if an object is found but it is not
+    # really an object (a Hash), then raise an exception.
+    #
+    containing_object_hash = param_hash
+    containing_object_name.split(".").each do |object_name|
+      containing_object_hash = containing_object_hash.fetch(object_name, nil)
+
+      if(containing_object_hash == nil)
+        break
+      elsif(containing_object_hash.class != Hash)
+        message =  "error: #{self.class}#load found "
+        message << "#{containing_object_hash.class} "
+        message << "rather than Hash when reading the "
+        message << "#{containing_object_name} containing object"
+        raise Error, message
+      end
+    end
+
+    load_impl(containing_object_hash, containing_object_name)
+  end
+
+  def self.load(reader, containing_object_name = "")
+    instance = new()
+    instance.load(reader, containing_object_name)
+    return instance
+  end
+  
+  def write_value_impl(str, indent, value_class, 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_class < ConstrainedArray)
+        #
+        # Writing an array requires going through each element and
+        # calling write_value_impl, just at one further indentation
+        # level.
+        #
+        str << "[\n"
+
+        value.each_with_index do |element, index|
+          str << nesting_indent
+          write_value_impl(str, nesting_indent, value_class.element_class, element)
+
+          if(index != (value.length - 1))
+            str << ","
+          end
+
+          str << "\n"
+        end
+
+        str << indent << "]"
+      else
+        str << "#{value}"
+      end
+    end
+  end
+  private :write_value_impl
+
+  def write_impl(str, indent)
+    self.class.param_spec_list.each do |param_spec|
+      name_field_length = self.class.longest_param_name_length
+      str << indent << param_spec.name.to_s.ljust(name_field_length) << ": "
+      value = send(param_spec.name)
+      write_value_impl(str, indent, param_spec.value_class, value)
+      str << "\n"
+    end
+  end
+  protected :write_impl
+
+  def to_s
+    #
+    # Print out config file name and the containing object_name and then
+    # call write.
+    #
+    str = String.new()
+
+    if(!@containing_object_name.empty?)
+      str << "#{@containing_object_name}: "
+    end
+
+    str << "{\n"
+    write_impl(str, NESTING_INDENT)
+    str << "}\n"
+
+    return str
+  end
+end
+
+end