configtoolkit 1.2.0 → 2.0.0

data/lib/configtoolkit/keyvaluewriter.rb

@@ -0,0 +1,157 @@
+#!/usr/bin/env ruby
+
+require 'configtoolkit/keyvalueconfig'
+require 'configtoolkit/writer'
+
+module ConfigToolkit
+
+#
+# This class implements the Writer interface for key-value configuration
+# files.
+#
+# See KeyValue.txt for more details about the key-value configuration format.
+#
+class KeyValueWriter < Writer
+  #
+  # ====Description:
+  # This constructs a KeyValueWriter 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 KeyValueWriter
+  #      will open the associated file.
+  # [config]
+  #      A KeyValueConfig that defines the format of the key-value
+  #      output that this instance can write
+  #
+  def initialize(stream, config = KeyValueConfig::DEFAULT_CONFIG)
+    if(stream.class == String)
+      @stream = File.open(stream, "w")
+    else
+      @stream = stream
+    end
+
+    @config = config
+  end
+
+  # 
+  # ====Returns:
+  # Returns +true+, since the KeyValueWriter requires Symbol parameter names
+  # in the Hash passed to write.
+  # 
+  def require_symbol_parameter_names?
+    return true
+  end
+
+  #
+  # This class is used for printing nested elements of the structure
+  # passed to write.  See the comments for HashArrayVisitor for
+  # details on how this visitor works.
+  #
+  class Visitor < HashArrayVisitor # :nodoc:
+    # 
+    # ====Description:
+    # This constructs a Visitor to write structures in key-value format to
+    # stream stream.
+    # 
+    # ====Parameters:
+    # [stream]
+    #      The stream to which to write
+    # [config]
+    #      The KeyValueConfig that defines the format of the key-value
+    #      output that this instance can write
+    # 
+    def initialize(stream, config)
+      @stream = stream
+      @config = config
+
+      super()
+    end
+
+    def enter_hash(hash)
+      @stream << @config.hash_opening
+
+      return nil
+    end
+    
+    def leave_hash(popped_stack_frame)
+      @stream << @config.hash_closing
+    end
+    
+    def visit_hash_element(key, value, index, is_container)
+      if(index != 0)
+        @stream << "#{@config.container_element_delimiter} "
+      end
+
+      @stream << "#{key} #{@config.hash_key_value_delimiter} "
+
+      if(!is_container)
+        @stream << "#{value}"
+      end
+    end
+    
+    def enter_array(array)
+      @stream << @config.array_opening
+    end
+    
+    def visit_array_element(value, index, is_container)
+      if(index != 0)
+        @stream << "#{@config.container_element_delimiter} "
+      end
+
+      if(!is_container)
+        @stream << "#{value}"
+      end
+    end
+
+    def leave_array(popped_stack_frame)
+      @stream << @config.array_closing
+    end
+  end
+
+  # 
+  # ====Description:
+  # 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, containing_object_name)
+    #
+    # Unfortunately, the Visitor cannot be used to write out the top level
+    # of configuration parameters, because the top-level format is different
+    # than the nested levels (the top-level *is* a hash, but is written
+    # out without braces and with one element on each line; the top-level
+    # also has a containing object name).
+    #
+    if(!containing_object_name.empty?())
+      key_prefix = "#{containing_object_name.gsub(/\./, @config.object_delimiter)}#{@config.object_delimiter}"
+    else
+      key_prefix = ""
+    end
+
+    visitor = Visitor.new(@stream, @config)
+    config_hash.each do |key, value|
+      @stream << "#{key_prefix}#{key} #{@config.key_value_delimiter} "
+
+      if(value.is_a?(Hash) || value.is_a?(Array))
+        visitor.visit(value)
+      else
+        @stream << "#{value}"
+      end
+
+      @stream << "\n"
+    end
+
+    @stream.flush()
+  end
+end
+
+end

data/lib/configtoolkit/prettyprintwriter.rb

@@ -0,0 +1,167 @@
+#!/usr/bin/env ruby
+
+require 'configtoolkit/hasharrayvisitor'
+require 'configtoolkit/writer'
+
+module ConfigToolkit
+
+#
+# This class implements the Writer interface for pretty printing
+# configuration classes to specified streams.  This is used by
+# BaseConfig#to_s.
+#
+class PrettyPrintWriter < Writer
+  #
+  # ====Description:
+  # This constructs a PrettyPrintWriter 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 PrettyPrintWriter
+  #      will open the associated file.
+  # 
+  def initialize(stream)
+    if(stream.class == String)
+      @stream = File.open(stream, "w")
+    else
+      @stream = stream
+    end
+  end
+
+  #
+  # This class is used for printing the elements of the structure
+  # passed to write.  See the comments for HashArrayVisitor for
+  # details on how this visitor works.
+  #
+  class Visitor < HashArrayVisitor # :nodoc:
+    #
+    # The amount by which to indent for each nesting level when
+    # pretty printing.
+    #
+    NESTING_INDENT = " " * 4
+
+    StackFrame = Struct.new(:indent, :longest_param_name_length)
+
+    # 
+    # ====Description:
+    # This constructs a Visitor to pretty pretty structures to
+    # stream stream.
+    # 
+    # ====Parameters:
+    # [stream]
+    #      The stream to which to write
+    # 
+    def initialize(stream)
+      @stream = stream
+
+      super(StackFrame.new("", 0))
+    end
+
+    # 
+    # ====Description:
+    # This method returns a new stack frame with
+    # longest parameter name length longest_param_name_length.
+    # The indentation for the new frame automatically is
+    # constructed from the current indentation.
+    # 
+    # ====Parameters:
+    # [longest_param_name_length]
+    #      The length of the longest parameter name in the
+    #      container associated with the frame
+    # 
+    # ====Returns:
+    # A new stack frame
+    # 
+    def construct_new_stack_frame(longest_param_name_length)
+      indent = stack_top().indent + NESTING_INDENT
+
+      return StackFrame.new(indent, longest_param_name_length)
+    end
+
+    def enter_hash(hash)
+      @stream << "{"
+      
+      longest_param_name_length = 0
+      hash.each_key do |key|
+        key_size = key.to_s().size()
+        if(key_size > longest_param_name_length)
+          longest_param_name_length = key_size
+        end
+      end
+      
+      return construct_new_stack_frame(longest_param_name_length)
+    end
+    
+    def leave_hash(popped_stack_frame)
+      @stream << "\n#{stack_top.indent}" << "}"
+    end
+    
+    def visit_hash_element(key, value, index, is_container)
+      @stream << "\n#{stack_top.indent}"
+      @stream << key.to_s.ljust(stack_top.longest_param_name_length)
+      @stream << ": "
+      
+      if(!is_container)
+        @stream << "#{value}"
+      end
+    end
+    
+    def enter_array(array)
+      @stream << "["
+
+      return construct_new_stack_frame(stack_top().longest_param_name_length)
+    end
+    
+    def visit_array_element(value, index, is_container)
+      if(index != 0)
+        @stream << ","
+      end
+
+      @stream << "\n#{stack_top.indent}"
+
+      if(!is_container)
+        @stream << "#{value}"
+      end
+    end
+
+    def leave_array(popped_stack_frame)
+      @stream << "\n#{stack_top.indent}" << "]"
+    end
+  end
+
+  # 
+  # ====Returns:
+  # Returns +true+, since the PrettyPrintWriter requires Symbol parameter names
+  # in the hash passed to write.
+  # 
+  def require_symbol_parameter_names?
+    return true
+  end
+
+  # 
+  # ====Description:
+  # This method pretty prints +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, containing_object_name)
+    if(!containing_object_name.empty?())
+      @stream << "#{containing_object_name}: "
+    end
+
+    Visitor.new(@stream).visit(config_hash)
+
+    @stream << "\n"
+
+    @stream.flush()
+  end
+end
+
+end

data/lib/configtoolkit/reader.rb

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+
+require 'pathname'
+
+module ConfigToolkit
+
+#
+# This is an "abstract class" that documents the Reader interface.
+# I put "abstract class" in quotes because Ruby of course neither supports
+# nor requires abstract classes (that is, one can create a new reader class
+# without extending Reader).  It solely serves to document the interface.
+#
+# Readers read data (the read method) from some underlying source and 
+# return configuration represented as a Hash of parameter names
+# to parameter values.  The parameter names can be either Strings
+# or Symbols; the parameter values can be scalars, Hashes, or Arrays.
+# Array or Hash parameter values can in turn have Arrays or Hash elements,
+# arbitrarily deeply nested.
+#
+class Reader
+  public
+
+  # 
+  # ====Description:
+  # This class method attempts to find a file system path for +stream+, where
+  # stream is an argument passed to a reader constructor (if a String, then
+  # stream names a file; otherwise, stream should be an IO or IO-like object)
+  # This is used by several of the the reader classes.
+  # 
+  # ====Parameters:
+  # [stream]
+  #      The underlying data source passed to a reader's constructor
+  # 
+  # ====Returns:
+  # The file system path for +stream+, or +nil+ if unable to find this
+  # 
+  def self.stream_path(stream)
+    if(stream.is_a?(String))
+      return Pathname.new(stream) # stream must be a file name
+    elsif(stream.is_a?(File))
+      return Pathname.new(stream.path())
+    else
+      return nil # Who knows?
+    end
+  end
+
+  # 
+  # This reads and returns configuration represented as a Hash, where
+  # the elements are parameter names (Strings or Symbols) mapping to
+  # parameter values.
+  #
+  # This *must* be implemented by Readers.
+  #
+  # ====Returns:
+  # The contents of a configuration as a Hash
+  # 
+  def read
+    raise NotImplementedError, "abstract method called"
+  end
+end
+
+end

data/lib/configtoolkit/rubyreader.rb

@@ -0,0 +1,270 @@
+#!/usr/bin/env ruby
+
+require 'configtoolkit/reader'
+require 'configtoolkit/types'
+
+require 'singleton'
+
+module ConfigToolkit
+
+#
+# This class implements the Reader interface for Ruby configuration files.
+# Ruby configuration files essentially are key-value configuration files
+# parsed by the Ruby interpreter; they allow the full Ruby language to
+# be used while building up a configuration.  Parameters are specified
+# by config.param_name or config.containing_object.param_name.  They can
+# be assigned to and, after assignment, used in other expressions.  If a
+# name first is referred to with a setter (i.e., "age" in
+# "config.first.second.age = 5"), then the name is assumed to be a
+# parameter name.  If a name first is referred to with a
+# getter (i.e., "first" and "second" in "config.first.second.age = 5"),
+# then the name is assumed to be an object name (either a containing or
+# a nested configuration object).  Objects cannot be set
+# (i.e., "config.first.second = 2" is illegal).
+# Parameter values, once set, can be referenced in later
+# expressions.
+#
+# See Ruby.txt for more details.
+#
+class RubyReader < Reader
+  #
+  # ====Description:
+  # This constructs a RubyReader 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 RubyReader
+  #      will open the associated file.
+  # 
+  def initialize(stream)
+    if(stream.class == String)
+      @stream = File.open(stream, "r")
+    else
+      @stream = stream
+    end
+
+    @stream_path = Reader.stream_path(stream)
+  end
+
+  #
+  # This is a helper class (not meant to be used externally).
+  # The Ruby code in Ruby configuration files is executed in the
+  # context of the instances of this class.  It provides a config
+  # instance method that allows references to "config.param_name"
+  # in the configuration file to work.  This method returns a
+  # ObjectProxy, which in turn re-implements method_missing
+  # so as to allow references to arbitrary parameters.
+  # 
+  class Interpreter # :nodoc:
+    #
+    # This serves as a marker that allows the ObjectProxy
+    # to distinguish between "simple" (non-object) parameter values and
+    # objects.  It is a singleton because there is no need for more than
+    # one simple parameter marker object.
+    #
+    class SimpleParam # :nodoc:
+      include Singleton
+    end
+
+    #
+    # ObjectProxy instances use method_missing to build up
+    # configuration Hashes (returned by the Reader's read method)
+    # from arbitrary parameter references in the Ruby configuration file.
+    # An instance maintains two Hashes.  The first is the configuration hash
+    # that maps parameter names to parameter values and containing object names
+    # to Hashes.  The second is the proxy hash that maps containing object
+    # names to ObjectProxy instances (and parameter names to
+    # the SimpleParam singleton marker).
+    #
+    # For instance, if the configuration file has "config.age = 5",
+    # age= will trigger a method_missing call that in turn will
+    # map :age to 5 in its configuration hash table (and also :age to
+    # SimpleParam in its proxy hash table if :age was encountered for the first
+    # time).  A line like "config.first.age = 5", will trigger
+    # a method_missing call to first.  Assuming first does not exist already,
+    # a new ObjectProxy will be created for it (:first => new
+    # ObjectProxy in the proxy hash table and :first => {} in the
+    # configuration hash table) and returned; age then will work with the
+    # new ObjectProxy as described.
+    #
+    # method_missing classifies references according to the following:
+    # 1.) Setter methods must be setting parameters.
+    # 2.) Getter methods must refer to a containing object if
+    #     the name never has been encountered before and, if it has,
+    #     to whatever it originally was resolved.
+    #
+    # Thus, containing objects are referred to via getters and only can be
+    # referred to via getters.  Parameters first must be
+    # referred to via a setter and then can be referred to via a
+    # getter or a setter (you can't get the value of a parameter that hasn't
+    # been set yet, after all).  Getters for containing objects return
+    # ObjectProxy instances, so that they in turn can service member
+    # references (i.e, "config.first.second.age = 2" has config, first, and
+    # second returning ObjectProxy instances).
+    #
+    # The configuration and proxy hashes have parallel structures, with
+    # the configuration hash mapping names to values and the proxy hash
+    # mapping names to containing object proxies.
+    #
+    class ObjectProxy # :nodoc:
+      # 
+      # ====Description:
+      # This contructs a ObjectProxy instance to have
+      # empty configuration and proxy hashes.
+      # 
+      def initialize(name)
+        @name = name
+        @config_hash = {}
+        @proxy_hash = {}
+      end
+
+      # 
+      # ====Description:
+      # This is an accessor for the @config_hash member variable.  It is
+      # surrounded by ___ characters on each side in order to reduce the
+      # chance of any collision occurring with a name referenced in the
+      # configuration file (___config_hash___ cannot be used as a 
+      # parameter or containing object name).
+      # 
+      # ====Returns:
+      # @config_hash
+      # 
+      def ___config_hash___
+        return @config_hash
+      end
+
+      # 
+      # ====Description:
+      # This method simulates methods in order to allow configuration
+      # files to reference arbitrary parameter and containing object names.
+      # When a configuration file contains "config.first.second.age = 2",
+      # the references to first, second, and age are handled by this
+      # method.
+      # 
+      # ====Parameters:
+      # [method_name]
+      #      The missing method
+      # [*args]
+      #      The arguments to the missing method
+      # 
+      # ====Returns:
+      # If a getter, then the ObjectProxy associated with the
+      # containing object or the parameter's value.  If a setter (which
+      # must act on a parameter), then the new value.
+      # 
+      def method_missing(method_name, *args)
+        method_name_str = method_name.to_s()
+        
+        if((method_name_str.size() >= 2) && (method_name_str[0, 2] == "[]"))
+          raise Error, "cannot index with array notation into #{@name}"
+        elsif(method_name_str[-1,1] == "=")
+          new_value = args[0]
+
+          #
+          # The interpreter more or less guarantees that args.size() == 1
+          # for setter methods.
+          #
+
+          #
+          # Get rid of the trailing '='
+          #
+          object_name = method_name_str[0, method_name_str.size() - 1].to_sym()
+          proxy = @proxy_hash.fetch(object_name, nil)
+          if(proxy == nil)
+            #
+            # A parameter value is being set for the first time, so
+            # record the parameter name in the proxy hash
+            #
+            @proxy_hash[object_name] = SimpleParam.instance()
+            return (@config_hash[object_name] = new_value)
+          elsif(proxy.is_a?(SimpleParam))
+            return (@config_hash[object_name] = new_value)
+          else
+            raise Error, "cannot assign to object #{@name}.#{object_name}"
+          end
+        elsif(args.size != 0)
+          super.missing_method(method_name, *args)
+        else
+          object_name = method_name
+          proxy = @proxy_hash.fetch(object_name, nil)
+
+          if(proxy == nil)
+            #
+            # Since this is a getter and there is no record of the
+            # name, the name must refer to a containing object.
+            #
+            proxy = @proxy_hash[object_name] = ObjectProxy.new("#{@name}.#{object_name}")
+            @config_hash[object_name] = proxy.___config_hash___
+            return proxy
+          elsif(proxy.is_a?(ObjectProxy))
+            return proxy
+          else
+            return @config_hash[object_name]
+          end
+        end
+      end
+    end
+
+    # 
+    # ====Description:
+    # This initializes the Interpreter with an empty
+    # configuration hash.
+    # 
+    def initialize
+      @root_proxy = ObjectProxy.new("config")
+    end
+
+    # 
+    # ====Description:
+    # This method returns a reference to the root ObjectProxy.
+    # It exists so that configuration parameters can be set in Ruby
+    # configuration files via lines like "config.age = 5".
+    # 
+    # ====Returns:
+    # The root ObjectProxy
+    # 
+    def config
+      return @root_proxy
+    end
+    private :config
+
+    # 
+    # ====Description:
+    # This method interprets (evals) code (which should have been
+    # sourced from a file with path file_path) and returns a Hash
+    # representing the configuration built by code
+    # 
+    # ====Parameters:
+    # [code]
+    #      The code containing the configuration to be interpreted (String)
+    # [file_path]
+    #      The path of the file containing the code (Pathname or nil)
+    # 
+    # ====Returns:
+    # A Hash representing the configuration built by code
+    # 
+    def interpret(code, file_path)
+      if(file_path == nil)
+        instance_eval(code)
+      else
+        instance_eval(code, file_path.to_s())
+      end
+
+      return @root_proxy.___config_hash___
+    end
+  end
+
+  # 
+  # ====Returns:
+  # The contents of the ruby configuration file
+  # 
+  def read
+    interpreter = Interpreter.new()
+    return interpreter.interpret(@stream.read(), @stream_path)
+  end
+end
+
+end