configtoolkit 1.2.0 → 2.0.0

data/lib/configtoolkit/hasharrayvisitor.rb

@@ -0,0 +1,242 @@
+#!/usr/bin/env ruby
+
+module ConfigToolkit
+
+#
+# This class allows each node of an Array or Hash containing
+# arbitrarily deeply nested Arrays or Hashes to be visited.  Users extend
+# this class for a particular task and override some or all of the
+# +visit_*+, +enter_*+, and +leave_*+ methods to accomplish the task.  They
+# then call the +visit+ method in order to visit the nodes of a structure.
+#
+# This class was written in order to factor out (fairly complicated) iteration
+# logic from methods that need to process each element of one of these
+# structures.  Such methods almost invariably require a stack to store
+# information for all levels above the level currently being processed.
+# Previously, when these methods recursively iterated over these structures,
+# they used the call stack for this purpose.  The HashArrayVisitor, however,
+# provides its own stack.  All of the +enter_*+ methods are expected to
+# return a new stack frame for the container being entered, which will be
+# accessible via the stack_top method while processing elements of the
+# container.  When the +leave_*+ method is called for the container, the
+# associated stack frame will be popped from the top of the stack and
+# passed to the +leave_*+ method.  An initial stack frame can be specified
+# in new, which often is handy as it ensures that there always will
+# be at least one element in the stack.  The HashArrayVisitor base class
+# has no knowledge of the contents of a stack frame, and so the stack frames
+# can be of any type (even +nil+ if no stack is required).
+#
+# PrettyPrintWriter, YAMLWriter, and KeyValueWriter all use this class.
+#
+class HashArrayVisitor
+  # 
+  # ====Description:
+  # This constructs the visitor with initial stack frame
+  # +initial_stack_frame+.
+  # 
+  # ====Parameters:
+  # [initial_stack_frame]
+  #      The initial stack frame; if not specified, then the stack
+  #      initially will be empty.  Specifying an initial stack frame
+  #      ensures that the stack never will be empty while visiting
+  #      a structure (this frame never will be popped).
+  # 
+  def initialize(initial_stack_frame = nil)
+    @stack = []
+
+    if(initial_stack_frame != nil)
+      @stack.push(initial_stack_frame)
+    end
+  end
+
+  # 
+  # ====Returns:
+  # +true+ if and only if value is a container
+  # 
+  def container_value?(value)
+    return (value.is_a?(Hash) || value.is_a?(Array))
+  end
+  private :container_value?
+
+  # 
+  # ====Description:
+  # This method visits the nodes of +structure+, calling the appropriate
+  # method for each node.
+  # 
+  # ====Parameters:
+  # [structure]
+  #      The Hash or Array whose nodes are to be visited (if +structure+'s
+  #      nodes themselves are Arrays or Hashes, the nodes of these
+  #      nested structures also will be visited).
+  # 
+  def visit(structure)
+    if(structure.is_a?(Hash))
+      @stack.push(enter_hash(structure))
+
+      structure.each_with_index do |key_value, index|
+        key = key_value[0]
+        value = key_value[1]
+
+        is_container_value = container_value?(value)
+        visit_hash_element(key, value, index, is_container_value)
+
+        if(is_container_value)
+          visit(value)
+        end
+      end
+
+      leave_hash(@stack.pop())
+    elsif(structure.is_a?(Array))
+      @stack.push(enter_array(structure))
+      
+      structure.each_with_index do |element, index|
+        is_container_value = container_value?(element)
+        visit_array_element(element, index, is_container_value)
+
+        if(is_container_value)
+          visit(element)
+        end
+      end
+
+      leave_array(@stack.pop())
+    else
+      message  = "The argument to HashArrayVisitor::visit must be a "
+      message << "Hash or Array; instead, a #{structure.class} "
+      message << "(#{structure}) was passed!"
+      raise ArgumentError, message
+    end
+  end
+
+  # 
+  # ====Returns:
+  # The top stack frame
+  # 
+  def stack_top
+    return @stack[-1]
+  end
+
+  # 
+  # ====Returns:
+  # True if and only if the stack is empty
+  # 
+  def stack_empty?
+    return @stack.empty?()
+  end
+
+  # 
+  # ====Description:
+  # This method is called when a Hash is visited for the first time.  It
+  # must return the new stack frame for the Hash.
+  # 
+  # This can be overridden; the default implementation is a no-op
+  # and returns +nil+.
+  #
+  # ====Parameters:
+  # [hash]
+  #      The Hash being visited
+  # 
+  # ====Returns:
+  # The new stack frame for the Hash
+  # 
+  def enter_hash(hash)
+    return nil
+  end
+
+  # 
+  # ====Description:
+  # This method is called when finished visiting all elements of a Hash.
+  # The stack will be popped before the call (so stack_top will
+  # return the frame for the Hash's parent), but the popped stack
+  # frame is passed as +popped_stack_frame+.
+  # 
+  # This can be overridden; the default implementation is a no-op.
+  # 
+  # ====Parameters:
+  # [popped_stack_frame]
+  #      The stack frame associated with the Hash, which has been
+  #      popped from the stack.
+  # 
+  def leave_hash(popped_stack_frame)
+  end
+
+  # 
+  # ====Description:
+  # This method is called when visiting a Hash element
+  # mapping +key+ to +value+.
+  #
+  # This can be overridden; the default implementation is a no-op.
+  # 
+  # ====Parameters:
+  # [key]
+  #      The key in the Hash element
+  # [value]
+  #      The value in the Hash element
+  # [index]
+  #      The index of key=>value in the Hash (the index that is returned by
+  #      +each_with_index+)
+  # [is_container_value]
+  #      Whether or not +value+ is a container (in
+  #      which case, it will be visited next with a call to
+  #      +enter_array+ or +enter_hash+)
+  # 
+  def visit_hash_element(key, value, index, is_container_value)
+  end
+
+  # 
+  # ====Description:
+  # This method is called when an Array is visited for the first time.  It
+  # must return the new stack frame for the Array.
+  # 
+  # This can be overridden; the default implementation is a no-op
+  # and returns +nil+.
+  #
+  # ====Parameters:
+  # [array]
+  #      The Array being visited
+  # 
+  # ====Returns:
+  # The new stack frame for the Array
+  # 
+  def enter_array(array)
+    return nil
+  end
+
+  # 
+  # ====Description:
+  # This method is called when finished visiting all elements of an Array.
+  # The stack will be popped before the call (so stack_top will
+  # return the frame for the Array's parent), but the popped stack
+  # frame is passed as +popped_stack_frame+.
+  # 
+  # This can be overridden; the default implementation is a no-op.
+  # 
+  # ====Parameters:
+  # [popped_stack_frame]
+  #      The stack frame associated with the Array, which has been
+  #      popped from the stack.
+  # 
+  def leave_array(popped_stack_frame)
+  end
+
+  # 
+  # ====Description:
+  # This method is called when visiting an Array element +value+ at
+  # +index+ in the Array.
+  #
+  # This can be overridden; the default implementation is a no-op.
+  # 
+  # ====Parameters:
+  # [value]
+  #      The Array element
+  # [index]
+  #      The index of +value+ in the Array
+  # [is_container_value]
+  #      Whether or not +value+ is a container (in
+  #      which case, it will be visited next with a call to
+  #      +enter_array+ or +enter_hash+)
+  # 
+  def visit_array_element(value, index, is_container_value)
+  end
+end
+
+end

data/lib/configtoolkit/hashreader.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+
+require 'configtoolkit/reader'
+
+module ConfigToolkit
+
+#
+# This class implements a no-op Reader interface.  A Hash
+# is specified in its constructor and is passed through to
+# requesting BaseConfig instances in its read method.
+#
+# This allows BaseConfig instances to be programatically loaded from
+# Hashes.  For instance,
+#  config = SimpleConfig.load(ConfigToolkit::HashReader.new(:param1 => 1))
+#
+# See Hash.txt for more details.
+#
+class HashReader < Reader
+  #
+  # ====Description:
+  # This constructs a HashReader instance that will
+  # return +config_hash+ in read.
+  # 
+  # ====Parameters:
+  # [config_hash]
+  #      A Hash to be returned by read
+  # 
+  def initialize(config_hash)
+    @config_hash = config_hash
+  end
+
+  # 
+  # ====Returns:
+  # The Hash specified in the constructor
+  # 
+  def read
+    return @config_hash
+  end
+end
+
+end

data/lib/configtoolkit/hashwriter.rb

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+
+require 'configtoolkit/writer'
+
+module ConfigToolkit
+
+#
+# This class implements a no-op Writer interface.  An instance
+# simply stores the last Hash passed to its write method.
+#
+# See Hash.txt for more details.
+#
+class HashWriter < Writer
+  #
+  # This is set by the argument to write.
+  #
+  attr_reader :config_hash
+
+  # 
+  # ====Returns:
+  # Returns +true+, since the HashWriter requires Symbol parameter names in the
+  # Hash passed to write.
+  # 
+  def require_symbol_parameter_names?
+    return true
+  end
+
+  # 
+  # ====Description:
+  # This method sets the +config_hash+ attribute to the +config_hash+ argument,
+  # modified to reflect a +containing_object_name+ containing object.
+  # 
+  # ====Parameters:
+  # [config_hash]
+  #      The new value of the +config_hash+ attribute, modified to reflect
+  #      a +containing_object_name+ containing object
+  # [containing_object_name]
+  #      The configuration's containing object name
+  # 
+  def write(config_hash, containing_object_name)
+    @config_hash = create_containing_object_hash(config_hash, containing_object_name)
+  end
+end
+
+end

data/lib/configtoolkit/keyvalueconfig.rb

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+
+require 'configtoolkit/baseconfig'
+
+module ConfigToolkit
+
+#
+# This class configures instances of the KeyValueReader and KeyValueWriter
+# classes.  It essentially describes a key-value file format
+# (what delimiter is used to separate keys and values, what string
+# prefixes comments, etc).
+#
+# See KeyValue.txt for more details.
+#
+class KeyValueConfig < BaseConfig
+  #
+  # The String that separates keys and values (the default value is "=")
+  #
+  add_optional_param(:key_value_delimiter, String, "=")
+
+  #
+  # The String that prefixes comment lines, which the KeyValueReader
+  # ignores (the default value is "#")
+  #
+  add_optional_param(:comment_line_prefix, String, "#")
+
+  #
+  # The String that prefixes directive lines (only include directives
+  # currently are supported; the default value is "*")
+  #
+  add_optional_param(:directive_line_prefix, String, "*")
+
+  #
+  # The String used to separate object names in containing object names,
+  # which prefix keys in the key-value format (the default value is ".")
+  #
+  add_optional_param(:object_delimiter, String, ".")
+
+  #
+  # Whether or not this format supports array and hash values (the default
+  # value is +true+)
+  #
+  add_optional_param(:allow_containers, ConfigToolkit::Boolean, true)
+
+
+  #
+  # The character used to separate elements of a container (hash or array
+  # values; the default value is ",")
+  #
+  add_optional_param(:container_element_delimiter, String, ",") do |new_value|
+    if(new_value.size() > 1)
+      raise_error("container_element_delimiter only can be a single character")
+    end
+  end
+
+
+  #
+  # The character that begins an array (the default value is "[")
+  #
+  add_optional_param(:array_opening, String, "[") do |new_value|
+    if(new_value.size() > 1)
+      raise_error("array_opening only can be a single character")
+    end
+  end
+
+  #
+  # The character that ends an array (the default value is "]")
+  #
+  add_optional_param(:array_closing, String, "]") do |new_value|
+    if(new_value.size() > 1)
+      raise_error("array_closing only can be a single character")
+    end
+  end
+
+  #
+  # The character that begins a hash (the default value is "{")
+  #
+  add_optional_param(:hash_opening, String, "{") do |new_value|
+    if(new_value.size() > 1)
+      raise_error("hash_opening only can be a single character")
+    end
+  end
+
+  #
+  # The character that ends a hash (the default value is "}")
+  #
+  add_optional_param(:hash_closing, String, "}") do |new_value|
+    if(new_value.size() > 1)
+      raise_error("hash_closing only can be a single character")
+    end
+  end
+
+  #
+  # The String that separates keys and values within a hash (the default value
+  # is "=>")
+  #
+  add_optional_param(:hash_key_value_delimiter, String, "=>")
+
+  #
+  # Just use the default values for all of the parameters.
+  #
+  DEFAULT_CONFIG = self.new(){}
+end
+
+end

data/lib/configtoolkit/keyvaluereader.rb

@@ -0,0 +1,597 @@
+#!/usr/bin/env ruby
+
+require 'configtoolkit/keyvalueconfig'
+require 'configtoolkit/reader'
+require 'configtoolkit/types'
+
+require 'pathname'
+
+module ConfigToolkit
+
+#
+# This class implements the Reader interface for
+# key-value configuration files.
+#
+# See KeyValue.txt for more details about the key-value configuration format.
+#
+class KeyValueReader < Reader  
+  #
+  # An internal error class that never is exposed to users of
+  # the KeyValueReader.  Its main purpose is to be caught and
+  # repackaged with a more informative error message into an
+  # Error.
+  #
+  class ParsingError < RuntimeError # :nodoc:
+  end
+
+  #
+  # ====Description:
+  # This constructs a KeyValueReader instance for a key-value
+  # format described by +config+ for +stream+,
+  # where stream is either 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 KeyValueReader
+  #      will open the associated file.
+  # [config]
+  #      A KeyValueConfig that defines the format of the key-value
+  #      input that this instance can read
+  #
+  def initialize(stream, config = KeyValueConfig::DEFAULT_CONFIG)
+    if(stream.class == String)
+      @stream = File.open(stream, "r")
+    else
+      @stream = stream
+    end
+
+    @stream_path = Reader.stream_path(stream)
+    @config = config
+  end
+
+  # 
+  # ====Description:
+  # This method processes directive with arguments, modifying param_hash
+  # with the result.
+  # 
+  # ====Parameters:
+  # [param_hash]
+  #      The parameter hash that should be modified (Hash)
+  # [directive]
+  #      The directive to process (String)
+  # [arguments]
+  #      The directive's arguments (String)
+  # [stream_path]
+  #      The path of the file currently being processed
+  # 
+  def handle_directive(param_hash, directive, arguments, stream_path)
+    case(directive)
+    when "include"
+      if(arguments.empty?())
+        raise ParsingError, "missing filename for include directive"
+      end
+
+      #
+      # Relative include file paths should be made relative to the
+      # path of the file currently being parsed, *not* relative to
+      # the current working directory.
+      #
+      include_file_path = Pathname.new(arguments)
+      if(include_file_path.relative?())
+        if(stream_path == nil)
+          raise ParsingError, "only can process relative include directives in File streams"
+        end
+
+        include_file_path = stream_path.dirname() + include_file_path
+      end
+
+      included_stream = File.open(include_file_path, "r")
+      read_impl(param_hash, included_stream, include_file_path)
+    else
+      raise ParsingError, "unknown directive '#{directive}'"
+    end
+  end
+  private :handle_directive
+
+  #
+  # This class is *not* meant to be accessed by KeyValueReader
+  # users; it solely is to be used internally.
+  #
+  # This class represents a hash entry while the entry is being parsed.
+  #
+  class HashEntry #:nodoc:
+    attr_reader :key
+    attr_accessor :value
+
+    # 
+    # ====Description:
+    # This initializes an empty instance (empty key and empty value).
+    # key_value_delimiter is the String that the instance will search
+    # for in order to know when to start appending characters to the
+    # value rather than to the key.
+    # 
+    # ====Parameters:
+    # [key_value_delimiter]
+    #      The String that will separate the key from the value
+    # 
+    def initialize(key_value_delimiter)
+      @key = ""
+      @value = ""
+      @key_value_delimiter = key_value_delimiter
+      @curr_delimiter = ""
+      @finished_parsing_key = false
+    end
+
+    # 
+    # ====Description:
+    # This method appends char to the hash entry.  This method will
+    # figure out whether char should be appended to the key or the to value,
+    # depending on whether the key-value delimiter has been appended yet.
+    # 
+    # ====Parameters:
+    # [char]
+    #      The character (String) to append
+    # 
+    def <<(char)
+      #
+      # If still parsing the key, check whether the new character matches
+      # the next unmatched character in the delimiter.  If it does, then
+      # do not append the character to the key (yet), because the character
+      # may be part of the delimiter.  If the all characters in the delimiter
+      # have been matched, then switch to parsing the value; otherwise,
+      # return in order to get the next character.
+      #
+      # If the new character does not match the next character in
+      # the delimiter, then append any prior characters that did match to the 
+      # key since they now have been proven not to be part of the delimiter.
+      #
+      if(!@finished_parsing_key)
+        if(char == @key_value_delimiter[@curr_delimiter.size(), 1])
+          @curr_delimiter << char
+
+          if(@curr_delimiter.size() == @key_value_delimiter.size())
+            @finished_parsing_key = true
+          end
+        else
+          if(!@curr_delimiter.empty?())
+            @key << @curr_delimiter
+            @curr_delimiter = ""
+          end
+
+          @key << char
+        end
+      else
+        @value << char
+      end
+    end
+  end
+
+  #
+  # This class is *not* meant to be accessed by KeyValueReader
+  # users; it solely is to be used internally.
+  #
+  # This class represents a nesting level while parsing a container.
+  # When a container is encountered (perhaps within another container),
+  # one of these frames is pushed onto a stack.  After the container has
+  # been completed, this frame is popped off the stack.
+  #
+  # A lot of logic of the form:
+  # if the contaier is an Array
+  #   do something
+  # else if the container is a Hash
+  #   do something else
+  # ...
+  # lives within this class, and so it is messy.  If more containers
+  # are added, some kind of interface over a container could be developed
+  # to replace the conditionals with polymorphism.
+  #
+  # Right now, the following containers are supported:
+  # * Array (elements can be Strings or other containers)
+  # * Hash (values are Strings or other containers; the curr_element
+  #         attribute is a HashEntry).
+  #
+  class ContainerParsingFrame #:nodoc:
+    #
+    # The container being parsed.
+    #
+    attr_reader :container
+
+    #
+    # The current container element being parsed.  A setter actually
+    # exists for this, but it is implemented by hand in order to
+    # take into account the differences in assigning to Array and Hash
+    # elements.
+    #
+    attr_reader :curr_element
+    
+    # 
+    # ====Description:
+    # This initializes a frame for parsing container, given
+    # key-value config config.
+    # 
+    # ====Parameters:
+    # [container]
+    #      The container to parse
+    # [config]
+    #      The KeyValueConfig for the configuration being parsed
+    # 
+    def initialize(container, config)
+      @container = container
+      @config = config
+      @curr_element = nil
+    end
+
+    # 
+    # ====Description:
+    # This method should be called when done parsing the current
+    # container element; it causes the current element to be added
+    # to the container and readies the frame to parse a new
+    # element.
+    # 
+    def finish_curr_element
+      if(@container.is_a?(Array))
+        if(@curr_element.is_a?(String))
+          @curr_element.strip!()
+        end
+        
+        @container.push(@curr_element)
+      else # @container.is_a?(Hash)
+        @curr_element.key.strip!()
+
+        if(@curr_element.value.is_a?(String))
+          @curr_element.value.strip!()
+
+          #
+          # String values that are empty are not allowed.
+          #
+          if(@curr_element.value.empty?())
+            raise ParsingError, "hash key '#{@curr_element.key}' is missing a value"
+          end
+        end
+
+        @container[@curr_element.key.to_sym()] = @curr_element.value
+      end
+
+      @curr_element = nil
+    end
+
+    # 
+    # ====Description:
+    # This method appends char to the container element currently being parsed.
+    # 
+    # ====Parameters:
+    # [char]
+    #      The character to be appended to the container element currently
+    #      being parsed.
+    # 
+    def append_char_to_curr_element(char)
+      #
+      # Create an element of the appropriate type if a new
+      # element is being parsed.
+      #
+      if(@curr_element == nil)
+        if(@container.is_a?(Array))
+          @curr_element = ""
+        else @container.is_a?(Hash)
+          @curr_element = HashEntry.new(@config.hash_key_value_delimiter)
+        end
+      end
+
+      #
+      # It only makes sense to append characters to String values.
+      #
+      if(@curr_element.is_a?(String) ||
+         (@curr_element.is_a?(HashEntry) && @curr_element.value.is_a?(String)))
+        @curr_element << char
+      else
+        raise ParsingError, "extraneous character '#{char}' after container"
+      end
+    end
+
+    # 
+    # ====Description:
+    # This is a setter for @curr_element.
+    # 
+    # ====Parameters:
+    # [value]
+    #      The new value of @curr_element.
+    # 
+    def curr_element=(value)
+      if(@curr_element.is_a?(HashEntry))
+        @curr_element.value = value
+      else
+        @curr_element = value
+      end
+    end
+
+    # 
+    # ====Returns:
+    # Returns true if and only if the currently parsed element is empty,
+    # which will be the case if no non-whitespace characters have been appended
+    # yet.
+    # 
+    def curr_element_empty?
+      if(@curr_element == nil)
+        return true
+      end
+
+      if(@curr_element.is_a?(String))
+        return @curr_element.match(/^\s*$/)
+      elsif(@curr_element.is_a?(HashEntry))
+        return @curr_element.key.match(/^\s*$/)
+      else
+        return false
+      end
+    end
+  end
+
+  # 
+  # ====Description:
+  # This method parses a container from raw_value.  This *only* should be
+  # called if raw_value is a container.
+  # 
+  # ====Parameters:
+  # [raw_value]
+  #      The String to parse
+  # 
+  # ====Returns:
+  # The container represented by raw_value
+  # 
+  def parse_container_value(raw_value)
+    #
+    # Welcome to the jungle!  This method is pretty messy...
+    # It parses raw_value with the aid of a stack.  Each time a nested
+    # container is encountered, a new frame is pushed onto the stack.
+    # When the method finishes parsing a container, a frame is popped off
+    # the stack.
+    #
+    parsing_stack = []
+    top_frame = nil
+    container_value = nil
+
+    #
+    # raw_value.split("").each <=> raw_value.each_char
+    # in Ruby 1.9.
+    #
+    raw_value.split("").each_with_index do |char, index|
+      #
+      # If there are no frames on the stack, and this is not the
+      # first iteration, then something must have horribly gone wrong.
+      # Either there are too many array or hash closing characters (each
+      # one of which pops the stack) or there is gunk after the container.
+      # Abort!
+      #
+      if(parsing_stack.empty?() && (index != 0))
+        if((char == @config.array_closing) ||
+           (char == @config.hash_closing))
+          raise ParsingError, "unmatched '#{char}'"
+        else
+          raise ParsingError, "extraneous string '#{raw_value[index, raw_value.size() - index + 1]}' after container"
+        end
+      end
+      
+      #
+      # The character can:
+      # 1.) Begin a new container.
+      # 2.) End a container element.
+      # 3.) End a container.
+      # 4.) Be part of a container element.
+      #
+      if((char == @config.array_opening) ||
+         (char == @config.hash_opening))
+        #
+        # A nested container has been encountered.  Push a frame onto the
+        # stack and parse the nested container.
+        #
+        if(char == @config.array_opening)
+          parsing_stack.push(ContainerParsingFrame.new([], @config))
+        else # char == @config.hash_opening
+          parsing_stack.push(ContainerParsingFrame.new({}, @config))
+        end
+
+        top_frame = parsing_stack[-1]
+      elsif(char == @config.container_element_delimiter)
+        #
+        # We're done parsing a container element.  If the current
+        # container element is empty, however, then the user
+        # must have made a syntax error.
+        #
+        if(!top_frame.curr_element_empty?())
+          top_frame.finish_curr_element()
+        else
+          raise ParsingError, "missing container element before '#{@config.container_element_delimiter}'"
+        end
+      elsif((char == @config.array_closing) ||
+            (char == @config.hash_closing))
+        #
+        # We're done parsing a container.  Finalize the element currently
+        # being processed and pop the stack.
+        # If the container is nested within a parent
+        # container, then set the element being processed in the parent
+        # container to the container that we just parsed.  Otherwise, we
+        # must be finished and so set the return value (container_value) to
+        # the container that we just parsed (we could return right here, but
+        # allow the code to flow to the top of the loop in order to ensure
+        # that there are no more characters to be processed, which would be
+        # an error in the configuration file).
+        #
+        if(!top_frame.curr_element_empty?())
+          top_frame.finish_curr_element()
+        end
+
+        prev_top_frame = parsing_stack.pop()
+        
+        if(!parsing_stack.empty?())
+          top_frame = parsing_stack[-1]
+          top_frame.curr_element = prev_top_frame.container
+        else
+          container_value = prev_top_frame.container
+        end
+      else
+        top_frame.append_char_to_curr_element(char)
+      end
+    end
+
+    if(!parsing_stack.empty?())
+      if(top_frame.container.is_a?(Array))
+        raise ParsingError, "missing array closing '#{@config.array_closing}'"
+      else # top_frame.container.is_a?(Hash)
+        raise ParsingError, "missing hash closing '#{@config.hash_closing}'"
+      end
+    end
+
+    return container_value
+  end
+  private :parse_container_value
+
+  # 
+  # ====Description:
+  # This method parses a value from raw_value; the method
+  # can parse scalar and container values.
+  # 
+  # ====Parameters:
+  # [raw_value]
+  #      The String to parse
+  # 
+  # ====Returns:
+  # The value represented by raw_value
+  # 
+  def parse_parameter_value(raw_value)
+    if(@config.allow_containers &&
+       raw_value.size() > 1 &&
+       ((raw_value[0, 1] == @config.array_opening) ||
+        (raw_value[0, 1] == @config.hash_opening)))
+      return parse_container_value(raw_value)
+    else
+      return raw_value
+    end
+  end
+  private :parse_parameter_value
+
+  # 
+  # ====Description:
+  # This method parses the contents of line and adds the contents to
+  # param_hash.
+  # 
+  # ====Parameters:
+  # [param_hash]
+  #      The parameter hash that should be modified (Hash)
+  # [line]
+  #      The line to be parsed (String)
+  # [stream_path]
+  #      The path of the file currently being parsed (Pathname or nil)
+  # 
+  def parse_line(param_hash, line, stream_path)
+    if(line.empty?())
+      return
+    elsif(line[0, @config.comment_line_prefix.length()] == @config.comment_line_prefix)
+      return
+    elsif(line[0, @config.directive_line_prefix.length()] == @config.directive_line_prefix)
+      directive_and_args = line[@config.directive_line_prefix.length(), line.length()].split(" ", 2)
+      
+      if(directive_and_args.empty?())
+        raise ParsingError, "missing directive on line starting with directive prefix '#{@config.directive_line_prefix}'"
+      end
+
+      directive = directive_and_args[0].strip()
+      if(directive_and_args.size() > 1)
+        arguments = directive_and_args[1].strip()
+      else
+        arguments = ""
+      end
+      
+      handle_directive(param_hash, directive, arguments, stream_path)
+    else
+      key_and_value = line.split(@config.key_value_delimiter, 2)
+      
+      if(key_and_value.length() != 2)
+        raise ParsingError, "missing key-value delimiter '#{@config.key_value_delimiter}'"
+      end
+      
+      key = key_and_value[0].strip()
+      value = key_and_value[1].strip()
+
+      #
+      # In order to allow containing objects to be represented compactly (and
+      # not via hashes, which are ugly in key-value format files), they can be
+      # repesented like:
+      # containing_object.param = blah
+      #
+      # So, split the key on the object delimiter and, for each object found,
+      # hash into param_hash.
+      #
+      object_names = key.split(@config.object_delimiter).map do |object_name|
+        object_name.to_sym() # Convert the object names from Strings to Symbols
+      end
+      
+      #
+      # The last object name actually is the parameter name, which must
+      # map to whatever is parsed from the value portion of the line.
+      # So, use upto rather than each here, since each would iterate over
+      # all of the object names.
+      #
+      object_hash = param_hash
+      0.upto(object_names.size() - 2) do |index|
+        object_hash[object_names[index]] ||= {}
+        object_hash = object_hash[object_names[index]]
+      end
+
+      object_hash[object_names[-1]] = parse_parameter_value(value)
+    end
+  end
+  private :parse_line
+  
+  # 
+  # ====Description:
+  # This method reads and parses each line of stream.
+  # Each line is parsed into a key and a value, which then are
+  # added to param_hash.
+  # 
+  # ====Parameters:
+  # [param_hash]
+  #      The parameter hash that should be modified (Hash)
+  # [stream]
+  #      The stream containing the configuration information
+  # [stream_path]
+  #      The path of stream (Pathname or nil)
+  # 
+  def read_impl(param_hash, stream, stream_path)
+    line_num = 1
+
+    stream.each_line do |line|
+      line.strip!()
+
+      begin
+        parse_line(param_hash, line, stream_path)
+      rescue ParsingError => e
+        if(stream_path == nil)
+          stream_name = "<unknown>"
+        else
+          stream_name = stream_path.to_s()
+        end
+
+        message = "Error parsing line ##{line_num} of #{stream_name}: #{e.message}!"
+        raise Error, message, e.backtrace()
+      end
+
+      line_num += 1
+    end
+  end
+  private :read_impl
+
+  # 
+  # ====Returns:
+  # The contents of the key-value configuration file
+  # 
+  def read
+    param_hash = {}
+
+    read_impl(param_hash, @stream, @stream_path)
+
+    return param_hash
+  end
+end
+
+end