rconfig 0.3.3 → 0.4.0

data/lib/rconfig.rb

@@ -1,39 +1,105 @@
-#--
+##
+#
 # Copyright (c) 2009 Rahmal Conda <rahmal@gmail.com>
+# -------------------------------------------------------------------
+# The complete solution for Ruby Configuration Management. RConfig is a Ruby library that
+# manages configuration within Ruby applications. It bridges the gap between yaml, xml, and
+# key/value based properties files, by providing a centralized solution to handle application
+# configuration from one location. It provides the simplicity of hash-based access, that
+# Rubyists have come to know and love, supporting your configuration style of choice, while
+# providing many new features, and an elegant API.
+#
+# -------------------------------------------------------------------
+# * Simple, easy to install and use.
+# * Supports yaml, xml, and properties files.
+# * Yaml and xml files supprt infinite level of configuration grouping.
+# * Intuitive dot-notation 'key chaining' argument access.
+# * Simple well-known hash/array based argument access.
+# * Implements multilevel caching to reduce disk access.
+# * Short-hand access to 'global' application configuration, and shell environment.
+# * Overlays multiple configuration files to support environment, host, and
+#   even locale-specific configuration.
+#
+# -------------------------------------------------------------------
+#  The overlay order of the config files is defined by SUFFIXES:
+#  * nil
+#  * _local
+#  * _config
+#  * _local_config
+#  * _{environment} (.i.e _development)
+#  * _{environment}_local (.i.e _development_local)
+#  * _{hostname} (.i.e _whiskey)
+#  * _{hostname}_config_local (.i.e _whiskey_config_local)
+#
+# -------------------------------------------------------------------
+#
+# Example:
+#
+#  shell/console =>
+#    export LANG=en
+#
+#  demo.yml =>
+#   server:
+#     address: host.domain.com
+#     port: 81
+#  ...
 #
-# 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.
-#++
+#  application.properties =>
+#    debug_level = verbose
+#  ...
+#
+# demo.rb =>
+#  require 'rconfig'
+#  RConfig.load_paths = ['$HOME/config', '#{APP_ROOT}/config', '/demo/conf']
+#  RConfig.demo[:server][:port] => 81
+#  RConfig.demo.server.address  => 'host.domain.com'
+#
+#  RConfig[:debug_level] => 'verbose'
+#  RConfig[:lang] => 'en'
+#  ...
+#
+require 'active_support'
+require 'rconfig/core_ext/array'
+require 'rconfig/core_ext/hash'
+require 'rconfig/core_ext/nil'
 
-$:.unshift File.dirname(__FILE__)
+module RConfig
+  VERSION = '0.4.0'
 
-require 'rubygems'
-require 'active_support'
-require 'active_support/core_ext'
-require 'active_support/core_ext/hash/conversions'
-require 'active_support/core_ext/hash/indifferent_access'
+  autoload :Socket,                    'socket'
+  autoload :YAML,                      'yaml'
+  autoload :ERB,                       'erb'
+  autoload :Logger,                    'logger'
+  autoload :Singleton,                 'singleton'
+
+  autoload :Concern,                   'active_support/concern'
+  autoload :Hash,                      'active_support/core_ext/hash/conversions'
+  autoload :HashWithIndifferentAccess, 'active_support/core_ext/hash/indifferent_access'
 
-require 'rconfig/core_ext'
-require 'rconfig/config_hash'
-require 'rconfig/properties_file_parser'
-require 'rconfig/rconfig'
+  autoload :Config,                    'rconfig/config'
+  autoload :Logger,                    'rconfig/logger'
+  autoload :Exceptions,                'rconfig/exceptions'
+  autoload :Utils,                     'rconfig/utils'
+  autoload :Constants,                 'rconfig/constants'
+  autoload :Settings,                  'rconfig/settings'
+  autoload :ConfigError,               'rconfig/exceptions'
+  autoload :LoadPaths,                 'rconfig/load_paths'
+  autoload :Cascade,                   'rconfig/cascade'
+  autoload :Callbacks,                 'rconfig/callbacks'
+  autoload :Reload,                    'rconfig/reload'
+  autoload :CoreMethods,               'rconfig/core_methods'
+  autoload :PropertiesFile,            'rconfig/properties_file'
+  autoload :InstallGenerator,          'generators/rconfig/install_generator'
 
-# Create global reference to RConfig instance
-$config = RConfig.instance
+  extend ActiveSupport::Concern
 
+  extend Utils
+  extend Constants
+  extend Settings
+  extend Exceptions
+  extend LoadPaths
+  extend Cascade
+  extend Callbacks
+  extend Reload
+  extend CoreMethods
+end

data/lib/rconfig/callbacks.rb

@@ -0,0 +1,46 @@
+module RConfig
+  module Callbacks
+
+    ##
+    # Register a callback when a config has been reloaded. If no config name
+    # is specified, the callback will be registered under the name :ANY. The
+    # name :ANY will register a callback for any config file change.
+    #
+    # Example:
+    #
+    #   class MyClass
+    #     self.my_config = { }
+    #     RConfig.on_load(:cache) do
+    #       self.my_config = { }
+    #     end
+    #     def my_config
+    #       self.my_config ||= something_expensive_thing_on_config(RConfig.cache.memory_limit)
+    #     end
+    #   end
+    #
+    def on_load(*args, &blk)
+      args << :ANY if args.empty?
+      proc = blk.to_proc
+
+      # Call proc on registration.
+      proc.call()
+
+      # Register callback proc.
+      args.each do |name|
+        (self.callbacks[name.to_s] ||= []) << proc
+      end
+    end
+
+    ##
+    # Executes all of the reload callbacks registered to the specified config name,
+    # and all of the callbacks registered to run on any config, as specified by the
+    # :ANY symbol.
+    def fire_on_load(name)
+      procs = (self.callbacks['ANY'] || RConfig::EMPTY_ARRAY) + (self.callbacks[name] || RConfig::EMPTY_ARRAY)
+      procs.uniq!
+      logger.debug "fire_on_load(#{name.inspect}): callbacks[#{procs.inspect}]" unless procs.empty?
+      procs.each { |proc| proc.call() }
+    end
+
+  end
+end

data/lib/rconfig/cascade.rb

@@ -0,0 +1,56 @@
+module RConfig
+  module Cascade
+    include Constants
+
+    ##
+    # Sets a custome overlay for
+    def overlay=(value)
+      reload(false) if self.overlay != value
+      self.overlay = value && value.dup.freeze
+    end
+
+    ##
+    # Returns a list of suffixes to try for a given config name.
+    #
+    # A config name with an explicit overlay (e.g.: 'name_GB')
+    # overrides any current _overlay.
+    #
+    # This allows code to specifically ask for config overlays
+    # for a particular locale.
+    #
+    def suffixes_for(name)
+      name = name.to_s
+      self.suffixes[name] ||= begin
+        ol = overlay
+        name_x = name.dup
+        if name_x.sub!(/_([A-Z]+)$/, '')
+          ol = $1
+        end
+        name_x.freeze
+        result = if ol
+          ol_ = ol.upcase
+          ol = ol.downcase
+          x = []
+          SUFFIXES.each do |suffix|
+            # Standard, no overlay:
+            # e.g.: database_<suffix>.yml
+            x << suffix
+
+            # Overlay:
+            # e.g.: database_(US|GB)_<suffix>.yml
+            x << [ol_, suffix]
+          end
+          [name_x, x.freeze]
+        else
+          [name.dup.freeze, SUFFIXES.freeze]
+        end
+        result.freeze
+
+        logger.debug "suffixes(#{name}) => #{result.inspect}"
+
+        result
+      end
+    end
+
+  end
+end

data/lib/rconfig/config.rb

@@ -0,0 +1,78 @@
+##
+# Copyright (c) 2009 Rahmal Conda <rahmal@gmail.com>
+#
+# Config is a special class, derived from HashWithIndifferentAccess.
+# It was specifically created for handling config data or creating mock 
+# objects from yaml files. It provides a dotted notation for accessing 
+# embedded hash values, similar to the way one might traverse a object tree.
+#
+module RConfig
+  class Config < ::HashWithIndifferentAccess
+
+    ##
+    # HashWithIndifferentAccess#default is broken in early versions of Rails.
+    # This is defined to use the hash version in Config#default
+    define_method(:hash_default, Hash.instance_method(:default))
+
+    ##
+    # Dotted notation can be used with arguments (useful for creating mock objects)
+    # in the YAML file the method name is a key, argument(s) form a nested key,
+    # so that the correct value is retrieved and returned.
+    #
+    # For example loading to variable foo a yaml file that looks like:
+    # customer:
+    #   id: 12345678
+    #   verified:
+    #     phone: verified
+    #     :address: info_not_available
+    #     ? [name, employer]
+    #     : not_verified
+    #
+    # Allows the following calls:
+    # foo.customer.id                 => 12345678
+    # foo.customer.verified.phone     => verified
+    # foo.customer.verified("phone")  => verified
+    # foo.customer.verified(:address) => info_not_available
+    # foo.customer.verified("name", "employer") => not_verified
+    #
+    # Note that :address is specified as a symbol, where phone is just a string.
+    # Depending on what kind of parameter the method being mocked out is going
+    # to be called with, define in the YAML file either a string or a symbol.
+    # This also works inside the composite array keys.
+    def method_missing(method, *args)
+      method = method.to_s
+      return if method == 'default_key'
+      value = self[method]
+      case args.size
+      when 0  # e.g.: RConfig.application.method
+        value
+      when 1  # e.g.: RConfig.application.method(one_arg)
+        value.send(args[0])
+      else    # e.g.: RConfig.application.method(arg_one, args_two, ...)
+        value[args]
+      end
+    end
+
+    ##
+    # Allow hash.default => hash['default']
+    # without breaking Hash's usage of default(key)
+    def default(key = self.default_key)
+      key = key.to_s if key.is_a?(Symbol)
+      if key == self.default_key 
+        self['default'] if key?('default')
+      else
+        hash_default(key)
+      end
+    end
+
+    protected
+
+    ##
+    # Override HashWithIndifferentAccess#convert_value
+    # return instance of Config for Hash values.
+    def convert_value(value)
+      value.is_a?(Hash) ? self.class.new(value).freeze : super
+    end
+
+  end # class Config
+end

data/lib/rconfig/constants.rb

@@ -0,0 +1,58 @@
+module RConfig
+  module Constants
+
+    # Sets CONFIG_ROOT to RAILS_ROOT/config unless it has already
+    # been defined (i.e. in rails env, or calling ruby app).
+    CONFIG_ROOT = File.join(::Rails.root || '', 'config').gsub(/^\//, '').gsub(/\/$/,'') if defined?(::Rails) && !defined?(CONFIG_ROOT)
+
+    # ENV TIER i.e. (development, integration, staging, or production)
+    # Defaults to RAILS_ENV if running in Rails, otherwise, it checks
+    # if ENV['TIER'] is present. If not, it assumes production.
+    ENV_TIER = (defined?(RAILS_ENV) ? RAILS_ENV : (ENV['TIER'] || 'production')) unless defined? ENV_TIER
+
+    # yml, yaml => yaml files, parsable by YAML library
+    YML_FILE_TYPES = [:yml, :yaml].freeze unless defined? YML_FILE_TYPES
+
+    # xml => self-explanatory
+    XML_FILE_TYPES = [:xml].freeze unless defined? XML_FILE_TYPES
+
+    # conf, properties => <key=value> based config files  
+    CNF_FILE_TYPES = [:cnf, :conf, :config, :properties].freeze unless defined? CNF_FILE_TYPES
+
+    # The type of file used for config. Valid choices
+    # include (yml, yaml, xml, conf, config, properties)  
+    CONFIG_FILE_TYPES = (YML_FILE_TYPES + XML_FILE_TYPES + CNF_FILE_TYPES).freeze unless defined? CONFIG_FILE_TYPES
+
+    # Use CONFIG_HOSTNAME environment variable to
+    # test host-based configurations.
+    HOSTNAME = ENV['CONFIG_HOSTNAME'] || Socket.gethostname unless defined? HOSTNAME
+
+    # Short Hostname: removes all chars from HOSTNAME, after first "."
+    # Used to specify machine-specific config files.
+    HOSTNAME_SHORT = HOSTNAME.sub(/\..*$/, '').freeze unless defined? HOSTNAME_SHORT
+
+    # This is an array of filename suffixes facilitates cascading
+    # configuration overrides (i.e. 'services_local', 'services_development').
+    # These files get loaded in the order of the array. Meaning the last file
+    # loaded overrides everything before it. So config files suffixed with
+    # hostname has the highest precedence, and therefore overrides everything.
+    # Example: 
+    #          database_local.yml overrides database.yml
+    #          database_staging.yml overrides database_local.yml
+    #          database_appsvr01.yml overrides database_integration.yml
+    SUFFIXES = [
+      nil,                                                # Empty suffix, used for default config file (i.e. database.yml).
+      :local,                                             # Allows user to create 'local' overrides (i.e. database_local.yml), primarily used for development.
+      :config, :local_config,
+      ENV_TIER, [ENV_TIER, :local],                       # Environment configs (i.e. development, test, production).
+      HOSTNAME_SHORT, [HOSTNAME_SHORT, :config_local],    # Short hostname (i.e. appsvr01), for server-specific configs.
+      HOSTNAME, [HOSTNAME, :config_local]                 # Hostname (i.e. appsvr01.acme.com), for server/domain-specific configs.
+    ] unless defined? SUFFIXES
+
+    # Used in place of undefined but expected arrays,
+    # to prevent creating a bunch of unecesary arrays
+    # in memory. See ConfigCore.fire_on_load
+    EMPTY_ARRAY = [].freeze unless defined? EMPTY_ARRAY
+    
+  end
+end

data/lib/rconfig/core_ext/array.rb

@@ -0,0 +1,3 @@
+class Array
+  alias_method :blank?, :empty?
+end

data/lib/rconfig/core_ext/hash.rb

@@ -1,5 +1,4 @@
-
-#++
+##
 # source: http://rubyforge.org/projects/facets/
 # version: 1.7.46
 # license: Ruby License
@@ -7,12 +6,12 @@
 # BUG: weave is destructive to values in the source hash that are arrays!
 #      (this is acceptable for RConfig's use as the basis for weave!)
 #
-#--
+#
 class Hash
 
   ##
   # Weaves the contents of two hashes producing a new hash.
-  def weave(other_hash, dont_clobber = true)
+  def weave(other_hash, clobber=false)
     return self unless other_hash
     unless other_hash.kind_of?(Hash)
       raise ArgumentError, "RConfig: (Hash#weave) expected <Hash>, but was <#{other_hash.class}>"
@@ -24,68 +23,68 @@ class Hash
 
       self_dup[key] =
 
-      if self_node = self_dup[key]
+          if self_node = self_dup[key]
 
-        case self_node
-        when Hash
+            case self_node
+              when Hash
 
-          # hash1, hash2 => hash3 (recursive +)
-          if other_node.is_a?(Hash)
+                # hash1, hash2 => hash3 (recursive +)
+                if other_node.is_a?(Hash)
 
-            self_node.weave(other_node, dont_clobber)
+                  self_node.weave(other_node, clobber)
 
-          # hash, array => error (Can't weave'em, must clobber.)
-          elsif other_node.is_a?(Array) && dont_clobber
+                  # hash, array => error (Can't weave'em, must clobber.)
+                elsif other_node.is_a?(Array) && !clobber
 
-            raise(ArgumentError, "RConfig: (Hash#weave) Can't weave Hash and Array")
+                  raise(ArgumentError, "RConfig: (Hash#weave) Can't weave Hash and Array")
 
-          # hash, array => hash[key] = array
-          # hash, value => hash[key] = value
-          else
-            other_node
-          end
+                  # hash, array => hash[key] = array
+                  # hash, value => hash[key] = value
+                else
+                  other_node
+                end
 
-        when Array
-
-          # array, hash => array << hash
-          # array1, array2 => array1 + array2
-          # array, value => array << value
-          if dont_clobber
-            case other_node
-            when Hash
-              self_node << other_node
-            when Array
-              self_node + other_node
-            else
-              self_node << other_node
-            end
-
-          # array, hash => hash
-          # array1, array2 => array2
-          # array, value => value
-          else
-            other_node
-          end
+              when Array
+
+                # array, hash => array << hash
+                # array1, array2 => array1 + array2
+                # array, value => array << value
+                unless clobber
+                  case other_node
+                    when Hash
+                      self_node << other_node
+                    when Array
+                      self_node + other_node
+                    else
+                      self_node << other_node
+                  end
+
+                  # array, hash => hash
+                  # array1, array2 => array2
+                  # array, value => value
+                else
+                  other_node
+                end
+
+              else
 
-      else
+                # value, array => array.unshift(value)
+                if other_node.is_a?(Array) && !clobber
+                  other_node.unshift(self_node)
 
-        # value, array => array.unshift(value)
-        if other_node.is_a?(Array) && dont_clobber
-          other_node.unshift(self_node)
+                  # value1, value2 => value2
+                else
+                  other_node
+                end
 
-        # value1, value2 => value2
-        else
-          other_node
-        end
-              
-      end # case self_node
+            end # case self_node
 
-      # Target hash didn't have a node matching the key, 
-      # so just add it from the source hash.
-      # !self_dup.has_key?(key) => self_dup.add(key, other_node)
-      else
-        other_node
-      end
+            # Target hash didn't have a node matching the key,
+            # so just add it from the source hash.
+            # !self_dup.has_key?(key) => self_dup.add(key, other_node)
+          else
+            other_node
+          end
 
     } # other_hash.each
 
@@ -95,8 +94,8 @@ class Hash
   ##
   # Same as self.weave(other_hash, dont_clobber) except that it weaves other hash 
   # to itself, rather than create a new hash.
-  def weave!(other_hash, dont_clobber = true)
-    weaved_hash = self.weave(other_hash, dont_clobber)
+  def weave!(other_hash, clobber=false)
+    weaved_hash = self.weave(other_hash, clobber)
     self.merge!(weaved_hash)
   end