tcfg 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 39595952f6c08c280797fd9c93ee54dd72824b48
-  data.tar.gz: 7920588447e198f58433ff1b46587bdd4c724a8d
+  metadata.gz: baf00e0fc9572c1a3004fd09a7deb75c41385e12
+  data.tar.gz: e58ce1b90b952e089f8b3284ce016772c9dbf668
 SHA512:
-  metadata.gz: f924cc3a03d1213429ab451eead6e61bf0556ab2cdc616f9fb67a19b436deb20e31d9fbd5852e236316a6eb7476cc12f6ade545fee347054a413bb484c1995fa
-  data.tar.gz: 08f13614791d8ce60f4da75adf2eac7c7bd10e7b81fd33bba0b90e7b46ecbb792bad508e18484499501e207346a1a6f7c5f672fba80adb81ef6f1f658362ae30
+  metadata.gz: 8c791b4b7f2b322fbcd754e576d3790ee1b744721947a9ffd40460bd04b8efdffcfa8804b73c04ee8b63287c907715938cf78eff7058b6ecb259d4718ecab4d9
+  data.tar.gz: a39546cb361ce1712c37851c58bce65e11a260ad1b13bd2d4fff61e412cf77e9cf3c21d54454b60fb5a74bed1fd0023d270dbb15172e06ff9fce5f5eb97f42c0

data/Gemfile

@@ -6,4 +6,5 @@ gem 'activesupport', '~> 3.2'
 group :development do
   gem "rspec", '~> 2.14'
   gem "jeweler", '~> 2'
+  gem "yard", "~> 0.8"
 end

data/Gemfile.lock

@@ -58,6 +58,7 @@ GEM
     rspec-expectations (2.14.5)
       diff-lcs (>= 1.1.3, < 2.0)
     rspec-mocks (2.14.6)
+    yard (0.8.7.3)
 
 PLATFORMS
   ruby
@@ -66,3 +67,4 @@ DEPENDENCIES
   activesupport (~> 3.2)
   jeweler (~> 2)
   rspec (~> 2.14)
+  yard (~> 0.8)

data/README.md

@@ -35,7 +35,7 @@ In the project root, make a yaml file called tcfg.yml that contains all configur
     LOG_LEVEL: INFO
 
     #This is a special section with overrides by 'environment'
-    tcfg_environments:
+    t_environments:
       QA:
         BASE_URL: http://qa.mysite.com
 
@@ -69,7 +69,7 @@ Now you can access configuration in any before, after, or it block, like:
 
 If you need to access configuration outside of a before, after, or it block you can use the TCFG module directly:
 
-    Log.level = TCFG.tcfg['LOG_LEVEL']
+    Log.level = TCFG['BASE_URL']
 
 To control your test suite, you can use environment variables.  To change the browser used:
 
@@ -77,10 +77,10 @@ To control your test suite, you can use environment variables.  To change the br
     $ rspec
 
     #To change the browser used
-    $ TCFG_BROWSER=chrome rspec
+    $ T_BROWSER=chrome rspec
 
     #To change which environment the tests execute against:
-    $ TCFG_ENVIRONMENT=QA rspec
+    $ T_ENVIRONMENT=QA rspec
 
 
 ### Other uses

data/Rakefile

@@ -2,6 +2,7 @@
 
 require 'rubygems'
 require 'bundler'
+
 begin
   Bundler.setup(:default, :development)
 rescue Bundler::BundlerError => e
@@ -43,3 +44,9 @@ end
 
 task :default => :spec
 
+#documentation
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']   # optional
+  #t.options = ['--any', '--extra', '--opts'] # optional
+end

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.1.0

data/lib/tcfg/tcfg_base.rb

@@ -1,10 +1,31 @@
 require_relative 'tcfg_helper'
 
+
 module TCFG
+  # The TCFG::Base object can used an instance of configuration
+  #
+  # All of the methods from TCFG::Helper are available as instance methods
+  #
+  #     cfg = TCFG::Base.new
+  #     cfg.tcfg_set 'my_key', 'my_value'
+  #
+  #     cfg['my_key']
+  #     => 'my_value'
+  #
+  #     cfg.tcfg
+  #     => { 'my_key' => 'my_value', ... }
+  #
   class Base
     include TCFG::Helper
-    def initialize
 
+    #the simplest way to acces configuration
+    #
+    #    cfg['my_key']
+    #    => 'some_value'
+    #
+    # @see TCFG::Helper#tcfg_get
+    def [] key
+      tcfg_get key
     end
   end
 end

data/lib/tcfg/tcfg_helper.rb

@@ -1,68 +1,160 @@
 require 'yaml'
 require 'active_support/core_ext/hash/indifferent_access'
 require 'active_support/core_ext/hash/deep_merge'
-
-require_relative 'tcfg_base'
+require 'active_support/core_ext/hash/deep_dup'
+require 'active_support/core_ext/hash/slice'
 
 module TCFG
-  module Helper
-    DEFAULT_CONFIG_FILE = 'tcfg.yml'
-
-    def tcfg
-      unless @resolved_config
-        resolved_config = ActiveSupport::HashWithIndifferentAccess.new
 
-        #tier 1 code defaults
-        resolved_config.merge! tier_code_defaults
-
-        #tier 2, the main config file
-        resolved_config.merge! tier_config_file
+  # TCFG::Helper does all the "heavy lifting".  Essentially all the logic within TCFG is defined by this module.
+  # The intended ways to use this module are:
+  #
+  # - use the TCFG module methods whenever a single instance of configuration will do
+  #
+  #     TCFG['some_key']
+  #     => 'some_value'
+  #
+  #     TCFG.tcfg
+  #     => { 'some_key' => 'some_value', ... }
+  #
+  # - mix it into any class that needs configuration
+  #
+  #     Class MyClass
+  #       include TCFG::Helper
+  #     end
+  #
+  #     Myclass.new.tcfg
+  #     => { 'some_key' => 'some_value', ... }
+  #
+  # - create a configuration instance object with this module pre-mixed in
+  #
+  #     cfg = TCFG::Base.new
+  #     cfg['some_key']
+  #     => 'some_value'
+  #
+  #     cfg.tcfg
+  #     => { 'some_key' => 'some_value', ... }
+  #
+  #
+  module Helper
 
-        #tier 3, the main config file
-        resolved_config.merge! tier_secret_config_file
+    # the public config file that is looked for unless tcfg_config_file is called
+    DEFAULT_CONFIG_FILE = 'tcfg.yml'
 
-        #tier 4, environment overrides
-        resolved_config.merge! tier_environment_overrides
+    #the default prefix that goes before environment variables and the environments section in config files
+    DEFAULT_ENV_VAR_PREFIX = 'T_'
 
-        #tier 5, environment variable overrides
-        resolved_config.each_pair do |k, v|
-          env_var_name = "TCFG_#{k}"
-          resolved_config[k] = ENV.fetch(env_var_name, v)
-        end
-        @resolved_config = resolved_config
-      end
-      return @resolved_config
+    # return a copy of the resolved configuration
+    #
+    # This is the preferred way to access a complete copy of the fully resolved configuration.
+    #
+    # @return [ActiveSupport::HashWithIndifferentAccess] a copy of the resolved configuration
+    def tcfg
+      @tcfg_resolved_config ||= resolve_config
+      #return a deep copy of the configuration object to prevent mutations
+      @tcfg_resolved_config.deep_dup
     end
 
+    # change the name of the public configuration file
+    #
+    # Changing the name of the public configuration file also
+    # changes the default secret configuration file.
+    # For example calling #tcfg_config_file('my_cfg.ym') will
+    # cause TCFG to look for 'my_cfg.secret.yml' for the secret
+    # file unless #tcfg_secret_config_file is also called.
+    #
+    # @see #tcfg_secret_config_file
+    #
+    # @param filename [String] the path to a yaml file
+    # @return [nil]
+    #
     def tcfg_config_file filename
       confirm_config_file_existence  filename
       tcfg_reset
       @tcfg_config_filename = filename
+      nil
     end
 
+    # change the name of the secret configuration file
+    #
+    # Calling this method if neccesary only if:
+    # - you dont have a public configuration file, or
+    # - your secret file is not named like <public name>.secret.yml
+    #
+    # @param filename [String] the path to a yaml file
+    # @return [nil]
+    #
     def tcfg_secret_config_file filename
       confirm_config_file_existence  filename
       tcfg_reset
       @tcfg_secret_config_filename = filename
+      nil
     end
 
+    # to correct way to default configuration is to use tcfg_set
+    #
+    # @param key [String] the configuration key name
+    # @param value [String, Integer, FixNum, Array, Hash] the value of the configuration
+    # @return value The same value that was passed in
+    #
     def tcfg_set key, value
       tier_code_defaults[key] = value
       tcfg_reset
       return value
     end
 
+    # return a single piece of configuration by key
+    #
+    # @param key [String] the configuration to return
+    # @return [String, Integer, FixNum, Array, Hash] the value of the configuration from the resolved configuration
+    #
     def tcfg_get key
-      tier_code_defaults[key]
+      t_tcfg = tcfg
+      unless t_tcfg.has_key? key
+        raise NoSuchConfigurationKeyError.new "No configuration defined for '#{key}'"
+      end
+      t_tcfg[key]
     end
 
+    # force tcfg to re-resolve the configuration
+    #
+    # This method can be called to force tcfg to re-resolve the configuration.
+    # This generally should not be needed directly, but situations where it 
+    # could be used include:
+    # - The underlying config file(s) have changed and you want to re-read them
+    # - The underlying ENV environment variables have changed and you want to re-read them
+    #
+    # @return [nil]
+    #
     def tcfg_reset
-      @resolved_config = nil
+      @tcfg_resolved_config = nil
+    end
+
+    # change the prefix used for configuration finding
+    #
+    # By default TCFG looks for 
+    # - environment variables prefixed with T_
+    # - sections in config files called t_environments
+    #
+    # This method lets you change that to any prefic you want.
+    # For example calling it like this:
+    #
+    #     TCFG.tcfg_set_env_var_prefix 'MY_'
+    #
+    # Will cause tcfg to look for:
+    # - environment variables prefixed with MY_
+    # - sections in config files called my_environments
+    #
+    # @param prefix [String] the new prefix. It can be an empty string to specify no prefix should be used.
+    # @return [nil]
+    #
+    def tcfg_set_env_var_prefix prefix
+      @tcfg_env_var_prefix = prefix
+      tcfg_reset
     end
 
     private
 
-    #define how we handle state for each of the tiers
     def tier_code_defaults
       @tcfg_code_defaults ||= ActiveSupport::HashWithIndifferentAccess.new
     end
@@ -87,12 +179,38 @@ module TCFG
     end
 
     def tier_environment_overrides
-      tenv = ENV['TCFG_ENVIRONMENT']
+      tenv = tcfg_fetch_env_var 'ENVIRONMENT', nil
       return {} unless @tcfg_environments_config and tenv
       unless @tcfg_environments_config.has_key? tenv
         raise TCFG::NoSuchEnvironmentError.new "No such environment in configuration '#{tenv}'"
       end
-      @tcfg_environments_config[tenv].merge({'TCFG_ENVIRONMENT' => tenv})
+      @tcfg_environments_config[tenv].merge({tcfg_env_var_name('ENVIRONMENT') => tenv})
+    end
+
+    #environment variable overrides is the most complex tier
+    #The rules:
+    # - You can only override configuration that exists in a lower tier. An exception is raised otherwise
+    # - You can use a - character to override deeply
+    # - All env variables must start with the prefix (T_)
+    # - ignore the special T_ENVIRONMENT variable
+    def tier_environment_variable_overrides lower_config={}
+      tcfg_env_vars = ENV.keys.select{|ev| ev =~ /^#{tcfg_env_var_prefix}/}
+      tcfg_env = ENV.to_hash.slice(*tcfg_env_vars)
+      tcfg_env.each_pair do |full_var_name, value|
+        var_chain = full_var_name.sub(/^#{tcfg_env_var_prefix}/, '').split('-')
+        next if var_chain.first.upcase == 'ENVIRONMENT'
+        parent_of_config_to_modify = lower_config
+        var_chain[0...-1].each do |parent_key|
+          unless parent_of_config_to_modify.respond_to? :has_key? and parent_of_config_to_modify.has_key? parent_key
+            raise BadParentInDeepOverrideError.new("No such parent '#{parent_key}' for deep override '#{full_var_name}'")
+          end
+          parent_of_config_to_modify = parent_of_config_to_modify[parent_key]
+        end
+        unless parent_of_config_to_modify.respond_to? :has_key? and parent_of_config_to_modify.has_key? var_chain.last
+          raise NoSuchConfigurationKeyError.new("No such configuration for '#{var_chain.last}' for override var '#{full_var_name}'")
+        end
+        parent_of_config_to_modify[var_chain.last] = value
+      end
     end
 
     def tcfg_load_optional_config_file filename
@@ -100,7 +218,7 @@ module TCFG
       if File.exist? filename
         file_contents = YAML.load_file filename
         hashed = ActiveSupport::HashWithIndifferentAccess.new file_contents
-        environments = hashed.delete :tcfg_environments
+        environments = hashed.delete tcfg_env_var_name('environments').downcase
         @tcfg_environments_config.deep_merge!(environments) if environments
         hashed
       else
@@ -114,9 +232,51 @@ module TCFG
       end
     end
 
+    def tcfg_env_var_prefix
+      @tcfg_env_var_prefix ||= DEFAULT_ENV_VAR_PREFIX
+      @tcfg_env_var_prefix
+    end
+
+    def tcfg_env_var_name key
+      tcfg_env_var_prefix + key
+    end
+
+    def tcfg_fetch_env_var key, not_defined_value
+      ENV.fetch tcfg_env_var_name(key), not_defined_value
+    end
+
+    def resolve_config
+      resolved_config = ActiveSupport::HashWithIndifferentAccess.new
+
+      #tier 1 code defaults
+      resolved_config.merge! tier_code_defaults
+
+      #tier 2, the main config file
+      resolved_config.merge! tier_config_file
+
+      #tier 3, the main config file
+      resolved_config.merge! tier_secret_config_file
+
+      #tier 4, environment overrides
+      resolved_config.merge! tier_environment_overrides
+
+      #tier 5, environment variable overrides
+      tier_environment_variable_overrides resolved_config
+
+      resolved_config
+    end
+
   end
 
-  #custom exceptions
+  #Raised when the requested environment is not available
   class NoSuchEnvironmentError < StandardError; end
+
+  #raised when a non-existent config file is specified
   class NoSuchConfigFileError < StandardError; end
+
+  #raise when a non-existent piece of configuration is requested
+  class NoSuchConfigurationKeyError < StandardError; end
+
+  #raise when a deep env var override specifies a non-existent parent hash in config
+  class BadParentInDeepOverrideError < StandardError; end
 end

data/lib/tcfg/tcfg_module.rb

@@ -1,7 +1,31 @@
 require_relative 'tcfg_helper'
 
+# The TCFG module can be used as singleton for accessing and specifying configuration
+#
+# All of the public methods from TCFG::Helper are available as class methods
+# right off the TCFG module
+#
+#     TCFG.tcfg_set 'some_key', 'some_value'
+#
+#     TCFG['some_key']
+#     => 'some_value'
+#
+#     TCFG.tcfg
+#     => { 'some_key' => 'some_value', ... }
+#
+#
 module TCFG
   class << self
     include TCFG::Helper
+
+    #the simplest way to acces configuration
+    #
+    #    TCFG['my_key']
+    #    => 'some_value'
+    #
+    # @see TCFG::Helper#tcfg_get
+    def [] key
+      tcfg_get key
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tcfg
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - robert schultheis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-23 00:00:00.000000000 Z
+date: 2014-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 description: A tiered approach to configuration which allows for full control of your
   test suite through environment variables
 email: robert.schultheis@gmail.com