configmanager 0.0.1 → 0.0.2

data/lib/configmanager/combined_configuration.rb

@@ -0,0 +1,65 @@
+#
+# 20 Jul 2012
+#
+
+require "configmanager/configuration"
+require "configmanager/exceptions"
+
+module ConfigManager
+
+  # A configuration class that can merge multiple configuration trees into a single configuration tree.
+  # Each addition, overwrites any properties that already existed.
+  class CombinedConfiguration < ConfigManager::Configuration
+
+    # Creates a new empty combined configuration.
+    #
+    # @param [Hash] options configuration options. Supported keys are:
+    #   :interpolator - an object that can respond to the 'interpolate' method. Default is the DefaultInterpolator.
+    #   :use_interpolator - global flag to specify if the interpolator should be used for this configuration. Default is true.
+    def initialize(options = {})
+      super
+
+      @configurations = {}
+    end
+
+    # Adds a configuration to be merged into this configuration. All existing properties are overwritten.
+    #
+    # @param [String] name a unique name for this configuration, it can be retrieved later with this name.
+    # @param [ConfigManager::Configuration] configuration the configuration to be merged.
+    #
+    # @return [NilClass]
+    def add_configuration(name, configuration)
+      raise ConfigManager::KeyError.new("Cannot add - Configuration '#{name}' already exists!") if @configurations.has_key?(name)
+      @configurations[name] = configuration
+      merge_configuration(configuration)
+
+      nil
+    end
+
+    # Get the configuration identified by the specified name. Raises an exception if the configuration does not exist.
+    # Modifying the returned configuration does not update this combined configuration.
+    #
+    # @param [String] name the configuration to get.
+    #
+    # @return [ConfigManager::Configuration] the configuration.
+    def get_configuration(name)
+      raise ConfigManager::PropertyNotFoundError("Cannot get - Configuration '#{name}' does not exist!") unless @configurations.has_key?(name)
+      @configurations[name]
+    end
+
+    private
+
+    # Merges the specified configuration with this configuration. Existing nodes are overwritten!
+    #
+    # @param [ConfigManager::Configuration] configuration the configuration to merge.
+    #
+    # @return [NilClass]
+    def merge_configuration(configuration)
+      values = configuration.get_property("")
+      at = ""
+      add_properties(values, at, :overwrite => true)
+    end
+
+  end
+
+end

data/lib/configmanager/configuration.rb

@@ -0,0 +1,165 @@
+#
+# 20 Jul 2012
+#
+
+require "configmanager/exceptions"
+require "configmanager/interpolators"
+
+module ConfigManager
+
+# Represents a collection of properties stored as a hash.
+  class Configuration
+
+    # Creates a new empty configuration.
+    #
+    # @param [Hash] options configuration options. Supported keys are:
+    #   :interpolator - an object that can respond to the 'interpolate' method. Default is the DefaultInterpolator.
+    #   :use_interpolator - global flag to specify if the interpolator should be used for this configuration. Default is true.
+    def initialize(options = {})
+      @root = {}
+      @use_interpolator = get_option(options, :use_interpolator, false, true)
+      @interpolator = get_option(options, :interpolator, false, ConfigManager::DefaultInterpolator)
+    end
+
+    # Adds a hash of properties to this configuration.
+    #
+    # @param [Hash] values the values to add to this configuration.
+    # @param [String] at the node under which to add these properties. Default is the root node.
+    # @param [Hash] options configuration options. Supported key are
+    #   :overwrite - true to overwrite existing properties, false to raise an exception if a property exists. Default is false.
+    #
+    # @return [NilClass]
+    def add_properties(values, at = "", options = {})
+      # Add each item in the hash - Nested hashes call this method recursively.
+      at_array = at.split(".")
+      values.each_pair do |key, value|
+        full_key = (at_array + [key]).join(".")
+        value.kind_of?(Hash) ? add_properties(value, full_key, options) : add_property(full_key, value, options)
+      end
+
+      nil
+    end
+
+    # Adds a property to this configuration. The key is a '.' separated string that fully qualifies this property.
+    # So the property a.b identifies the property 'b' inside the group 'a'. Similarly a.b.c identifies the property
+    # 'c' inside the group 'b' which is inside the group 'a'.
+    #
+    # @param [String] key the unique key to identify this property.
+    # @param [Object] value the value of this property.
+    # @param [Hash] options configuration options. Supported keys are:
+    #   :overwrite - true to overwrite existing properties, false to raise an exception if a property exists. Default is false.
+    #   :at - an optional node's name under which to add this property. Default is the root node.
+    #
+    # @return [NilClass]
+    def add_property(key, value, options = {})
+      # Default options.
+      at = get_option(options, :at, false, "")
+      overwrite = get_option(options, :overwrite, false, false)
+      # Create and add the property.
+      key_array = key.split(".")
+      at_array = at.split(".")
+      leaf = key_array[-1]
+      at_array = at_array + key_array[0..-2]
+      at_node = get_node(at_array, create = true)
+      # Got the node, now add the property, unless it already exists.
+      raise ConfigManager::KeyError.new("Cannot add - '#{at_array.join(".")}.#{leaf}' already exists!") if at_node.has_key?(leaf) and not overwrite
+      at_node[leaf] = value
+
+      nil
+    end
+
+    # Get the value of the specified property. The key is a '.' separated string that fully qualifies this property.
+    # So the property a.b identifies the property 'b' inside the group 'a'. Similarly a.b.c identifies the property
+    # 'c' inside the group 'b' which is inside the group 'a'.
+    #
+    # If enabled, the property's value is interpolated.
+    # Finally the list of post-processors are invoked and the value is returned.
+    #
+    # @param [String] key the property to get.
+    # @param [Hash] options configuration options. Supported keys are:
+    #   :use_interpolator - flag to indicate if the interpolator should be used. Uses the value specified when creating this configuration by default.
+    #   :interpolator - the interpolator to use. Uses the value specified when creating this configuration by default.
+    #   :post_processors - an array of callable procs. Each one is invoked with the output of the previous one. The first one is invoked with the fully interpolated value.
+    #   :replacements - a hash containing replacement values for references. References are looked up in this before being looked up in this configuration.
+    #   :tolerate_missing_references: a flag to indicate if missing references should raise an exception.
+    #
+    # Note : Interpolator implementations may support additional options too.
+    #
+    # @return [Object] the property's value.
+    def get_property(key, options = {})
+      use_interpolator = get_option(options, :use_interpolator, false, @use_interpolator)
+      interpolator = get_option(options, :interpolator, false, @interpolator)
+      post_processors = pop_option(options, :post_processors, false, [])
+      # Get the required property's raw value.
+      key_array = key.split(".")
+      create = false
+      raw_value = get_node(key_array, create)
+      # Interpolate.
+      raw_value = interpolator.interpolate(key, raw_value, self, options) if use_interpolator
+      # Post-process.
+      final_value = raw_value
+      post_processors.each { |processor| final_value = processor.call(final_value) }
+      # All done.
+      final_value
+    end
+
+    # Check to see if the specified property is defined for this configuration. This method will throw an exception if
+    # the key is invalid.
+    #
+    # @param [String] key the property to check.
+    #
+    # @return [TrueClass, FalseClass] true if the property exists, false otherwise.
+    def has_property?(key)
+      key_array = key.split(".")
+      create = false
+      get_node(key_array, create)
+      return true
+    rescue ConfigManager::PropertyNotFoundError
+      return false
+    end
+
+    private
+
+    # Gets the node identified by the specified key. If the 'create' flag is true, missing nodes will be created.
+    #
+    # @param [Array] key_array the array representing the full key.
+    # @param [TrueClass, FalseClass] create true to create missing nodes, false otherwise.
+    #
+    # @return [Hash] the node identified by this key.
+    def get_node(key_array, create = false)
+      return @root if key_array.empty?
+
+      key_str = key_array.join(".")
+      processed_parts = []
+      current_node = @root
+      # Walk the property tree. What's left at the end, is the required node.
+      key_array.each do |part|
+        # If the current node is not a hash, it means the key is invalid.
+        unless current_node.kind_of?(Hash)
+          raise ConfigManager::KeyError.new("Invalid key '#{key_str}' - Reached leaf at '#{processed_parts.join(".")}'!")
+        end
+
+        # If the current node is a hash, then check if the next part of the key is present.
+        # If it present, make that the current node.
+        # If it isn't present and the create flag is true, create an empty node and make it the current node.
+        # If the create flag is false, raise an exception.
+        processed_parts << part
+        if current_node.has_key?(part)
+          current_node = current_node[part]
+        elsif create
+          current_node = current_node[part] = {}
+        else
+          raise ConfigManager::PropertyNotFoundError.new("Key '#{processed_parts.join(".")}' does not exist!")
+        end
+      end
+      # The required node.
+      current_node
+    end
+
+    alias_method :[], :get_property
+    alias_method :[]=, :add_property
+    alias_method :set_property, :add_property
+
+  end
+
+end

data/lib/configmanager/exceptions.rb

@@ -0,0 +1,19 @@
+#
+# 20 Jul 2012
+#
+
+module ConfigManager
+
+# Raised when a property references itself - either directly or indirectly.
+  class CircularReferenceError < Exception
+  end
+
+# Raised when a requested property's key is invalid.
+  class KeyError < Exception
+  end
+
+# Raised when a requested property does not exist.
+  class PropertyNotFoundError < Exception
+  end
+
+end

data/lib/configmanager/interpolators.rb

@@ -0,0 +1,65 @@
+#
+# 20 Jul 2012
+#
+
+require "configmanager/configuration"
+require "configmanager/exceptions"
+
+module ConfigManager
+
+  # The default interpolator that will look for ${} property references.
+  # The interpolator will only inspect Strings and Strings in Arrays. All other types are returned as is.
+  class DefaultInterpolator
+
+    REFERENCE_REGEX = /\$\{[\w\.]+\}/
+
+    # Replaces all ${} references with an actual value. Will evaluate any nested references too.
+    # If circular references are detected, an exception is raised.
+    #
+    # @param [String] key the full (. separated) key against which this value was stored.
+    # @param [String, Array] raw_value the raw value to interpolate.
+    # @param [ConfigManager::Configuration] context the context under which the value should be evaluated.
+    # @param [Hash] options extra configuration options. Supported keys are:
+    #   :replacements - a hash containing replacement values for references. References are replaced with these value on priority.
+    #   :tolerate_missing_properties - a flag to indicate if an exception should be raised if referenced properties are missing.
+    #
+    # @return [String] the fully interpolated value.
+    def self.interpolate(key, raw_value, context, options = {})
+      # Default options.
+      replacements = get_option(options, :replacements, false, {})
+      tolerate_missing_references = get_option(options, :tolerate_missing_references, false, false)
+      interpolating = set_option(options, :interpolating, {}, false)
+      # Mark this key
+      interpolating[key] = true
+      # Check for type.
+      # Array - Recursively call this method.
+      # Not a String - Return as is.
+      # Otherwise, interpolate!
+      return raw_value.map { |item| interpolate(key, item, context, options) } if raw_value.kind_of?(Array)
+      return raw_value unless raw_value.kind_of?(String)
+      raw_value.gsub(REFERENCE_REGEX) do |reference|
+        # If the referenced key is still being interpolated, its a circular reference!
+        # Otherwise, substitute it with its replacement value (either from the supplied hash, or the provided context)
+        key = reference[2..-2]
+        if interpolating[key]
+          trace = (interpolating.keys + [key]).join(" -> ")
+          raise ConfigManager::CircularReferenceError.new("Cannot interpolate - Circular reference detected. Trace: #{trace}")
+        elsif replacements.has_key?(key)
+          replacements[key]
+        elsif context.has_property?(key)
+          context.get_property(key, options)
+        elsif tolerate_missing_references
+          reference
+        else
+          trace = (interpolating.keys + [key]).join(" -> ")
+          raise ConfigManager::PropertyNotFoundError.new("Cannot interpolate - Referenced key '#{key}' does not exist. Trace: #{trace}")
+        end
+      end
+    ensure
+      # Done, so mark as done.
+      interpolating.delete(key)
+    end
+
+  end
+
+end

data/lib/configmanager/loaders.rb

@@ -0,0 +1,182 @@
+#
+# 20 Jul 2012
+#
+
+module ConfigManager
+
+  # Loads properties from a YAML file.
+  class YAMLPropertiesLoader
+
+    # Loads properties from the specified YAML file. This is the default loader.
+    #
+    # @param [String] file_path the file to load.
+    # @param [Configuration] configuration the configuration to add the loaded properties to.
+    #
+    # @return [Hash] the properties read from the file.
+    def self.load_properties(file_path, configuration)
+      require "yaml"
+      file_path = File.expand_path(file_path)
+      properties = YAML.load_file(file_path)
+      files_to_import = properties.delete("import") { [] }
+      files_to_import = [files_to_import] unless files_to_import.kind_of?(Array)
+      configuration.add_properties(properties)
+      # Load any referenced files too.
+      file_dir = File.dirname(file_path)
+      files_to_import.each { |file_to_import| load_properties(File.expand_path(file_to_import, file_dir), configuration) }
+    end
+
+  end
+
+  # Loads properties from a Java style property file. The syntax is slightly different from regular property files.
+  # Important differences are :
+  # 1. Escape characters are not allowed.
+  # 2. Properties can be assigned a type (int, float, regex, string, bool).
+  # 3. Properties can be collected as arrays.
+  #
+  # A property would look like :
+  # <key><:optional_type> = <value>
+  # For arrays, add a [] to the property :
+  # <key><:optional_type>[] = <value separated by ','>
+  class JavaPropertiesLoader
+
+    # Raised if a property file is not valid.
+    class SyntaxError < Exception
+    end
+
+    LINE_REGEX = /^([\w\.]+)(:(\w+))?(\[\])?\s*([\s=])\s*(.*)$/
+    COMMAND_REGEX = /^@(\w+)\s+(.*)$/
+
+    TRUE_VALUES = %w(true yes on)
+    FALSE_VALUES = %w(false no off)
+    TYPE_CONVERTERS = {"bool" => :type_bool, "int" => :type_int, "float" => :type_float, "regex" => :type_regex,
+                       "string" => :type_string, nil => :type_string}
+    COMMANDS = {"import" => :command_import}
+
+    # Executes the import command.
+    #
+    # @param [String] file_to_import the file that needs to be imported.
+    # @param [String] file_path the file that contained the command.
+    # @param [Integer] line_number the line number where the command existed.
+    # @param [ConfigManager::Configuration] configuration the configuration to load the properties into.
+    #
+    # @return [NilClass]
+    def self.command_import(file_to_import, file_path, line_number, configuration)
+      file_to_import = file_to_import[1..-2]
+      file_dir = File.dirname(file_path)
+      file_to_import = File.expand_path(file_to_import, file_dir)
+      load_properties(file_to_import, configuration)
+      nil
+    end
+
+    # Loads properties from the specified Java style property file.
+    #
+    # @param [String] file_path the file to load properties from.
+    # @param [ConfigManager::Configuration] configuration the configuration to load the properties into.
+    #
+    # @return [NilClass]
+    def self.load_properties(file_path, configuration)
+      file_path = File.expand_path(file_path)
+      lines = File.readlines(file_path)
+      lines.each_with_index do |line, line_number|
+        line = line.chomp.strip
+        # Empty lines, ignore.
+        # Comment lines, ignore.
+        # Command - Call the command's method.
+        next if line.empty?
+        next if line.start_with?("#")
+        match = line.match(COMMAND_REGEX)
+        if match
+          command_name = match[1]
+          command_arg = match[2]
+          raise SyntaxError.new("Unrecognized command '#{command_name}' #(#{file_path}:#{line_number})") unless COMMANDS.has_key?(command_name)
+          send(COMMANDS[command_name], command_arg, file_path, line_number, configuration)
+          next
+        end
+        # Other lines, parse as a property.
+        # Raises an exception if the line was not valid.
+        match = line.match(LINE_REGEX)
+        raise SyntaxError.new("Syntax error '#{line}' (#{file_path}:#{line_number})") if match.nil?
+        key, type, array, value = match[1], match[3], match[4], match[6]
+        # Invalid types raise an exception.
+        raise SyntaxError.new("Unrecognized type '#{type}' (#{file_path}:#{line_number})") unless TYPE_CONVERTERS.has_key?(type)
+        type_converter = TYPE_CONVERTERS[type]
+
+        # Split into array if required and apply the type converter.
+        if array
+          value = value.split(",").map { |item| send(type_converter, item.strip, file_path, line_number) }
+        else
+          value = send(type_converter, value, file_path, line_number)
+        end
+
+        # Finally, add to configuration.
+        configuration.add_property(key, value)
+      end
+      nil
+    end
+
+    # Converts the specified string value into a boolean (TrueClass, FalseClass).
+    #
+    # @param [String] value the string value to convert.
+    # @param [String] file_path the file that contains the property.
+    # @param [Integer] line_number the line that contained this property.
+    #
+    # @return [TrueClass, FalseClass]
+    def self.type_bool(value, file_path, line_number)
+      return true if TRUE_VALUES.include?(value)
+      return false if FALSE_VALUES.include?(value)
+      raise SyntaxError.new("Invalid boolean '#{value}' (#{file_path}:#{line_number})")
+    end
+
+    # Converts the specified string value into float.
+    # Invalid values will raise an exception.
+    #
+    # @param [String] value the string value to convert.
+    # @param [String] file_path the file that contains the property.
+    # @param [Integer] line_number the line that contained this property.
+    #
+    # @return [Float]
+    def self.type_float(value, file_path, line_number)
+      Float(value)
+    rescue
+      raise SyntaxError.new("Invalid float value '#{value}' (#{file_path}:#{line_number})")
+    end
+
+    # Converts the specified string value into a integer.
+    # Invalid values will raise an exception
+    #
+    # @param [String] value the string value to convert.
+    # @param [String] file_path the file that contains the property.
+    # @param [Integer] line_number the line that contained this property.
+    #
+    # @return [Integer]
+    def self.type_int(value, file_path, line_number)
+      Integer(value)
+    rescue
+      raise SyntaxError.new("Invalid integer value '#{value}' (#{file_path}:#{line_number})")
+    end
+
+    # Converts the specified string value into a regexp.
+    #
+    # @param [String] value the string value to convert.
+    # @param [String] file_path the file that contains the property.
+    # @param [Integer] line_number the line that contained this property.
+    #
+    # @return [Regexp]
+    def self.type_regex(value, file_path, line_number)
+      Regexp.new(value)
+    end
+
+    # Returns the value as is.
+    #
+    # @param [String] value the string value to convert.
+    # @param [String] file_path the file that contains the property.
+    # @param [Integer] line_number the line that contained this property.
+    #
+    # @return [String]
+    def self.type_string(value, file_path, line_number)
+      value
+    end
+
+  end
+
+end

data/lib/configmanager/version.rb

@@ -0,0 +1,9 @@
+#
+# 20 Jul 2012
+#
+
+module ConfigManager
+
+  VERSION = "0.0.2"
+
+end

data/lib/samples/test 1.properties

@@ -0,0 +1,17 @@
+# Comments are ignored. So are empty lines.
+
+# Commands start with '@' character.
+# The import command will import another file into this file. The path is resolved relative to this file.
+@import "test 2.properties"
+
+# A property has the following format
+# <key><:optional_type> = <value>
+test.sample_string = Test String
+test.sample_int:int = 1
+test.sample_float:float = 1.0
+
+# Arrays can be created by appending [] to a property. Arrays are split using the ',' character.
+test.sample_array[] = first, second, third
+
+# Arrays can also be provided with a type - each value is converted to that type.
+test.sample_int_array:int[] = 1, 2, 3

data/lib/samples/test 1.yaml

@@ -0,0 +1,14 @@
+# Comments are ignored. So are empty lines.
+
+# The import key has special meaning. It will import another file into this file.
+# The path is resolved relative to this file.
+import: 'test 2.yaml'
+
+# The format is same as any YAML file.
+test_yaml:
+  sample_string: Test String
+  sample_int: 1
+  sample_float: 1.0
+
+  sample_array: [first, second, third]
+  sample_int_array: [1, 2, 3]

data/lib/samples/test 2.properties

@@ -0,0 +1,9 @@
+# This file imported by test 1.properties
+
+# Properties can reference other properties too. References are evaluated only when the
+# property's value is evaluated. The referenced property's type is not used - so this property will
+# evaluate as a String.
+test.sample_reference = ${test.sample_int}
+
+# References can be part of an array too.
+test.sample_reference_array[] = ${test.sample_string}, ${test.sample_int}, ${test.sample_float}

data/lib/samples/test 2.yaml

@@ -0,0 +1,8 @@
+# This file imported by test 1.yaml
+
+# Properties can reference other properties too. References are evaluated only when the
+# property's value is evaluated. The referenced property's type is not used - so this property will
+# evaluate as a String.
+test_yaml:
+  sample_reference: ${test_yaml.sample_int}
+  sample_reference_array: [${test_yaml.sample_string}, ${test_yaml.sample_int}, ${test_yaml.sample_float}]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: configmanager
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -20,8 +20,18 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/configmanager/combined_configuration.rb
+- lib/configmanager/configuration.rb
+- lib/configmanager/exceptions.rb
+- lib/configmanager/interpolators.rb
+- lib/configmanager/loaders.rb
+- lib/configmanager/version.rb
 - lib/configmanager.rb
 - lib/options_arg.rb
+- lib/samples/test 1.properties
+- lib/samples/test 1.yaml
+- lib/samples/test 2.properties
+- lib/samples/test 2.yaml
 - lib/test_configmanager.rb
 homepage: 
 licenses: []