app_config_loader 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1f6fcbc8cf8afaf0cf827cdfbd109435935adb52
-  data.tar.gz: 1cfe704eb579fb86e97e7c99ac44555a28ddf490
+  metadata.gz: 1e592723d0d4dc4f9f4640900c9898bb83fd4c35
+  data.tar.gz: c2b0ffc59d4e620846cab0c9f38a245e34460ec7
 SHA512:
-  metadata.gz: d840c314529c38da7df35390e6dcfd666b5c748ff9a390c289caf6702080bd8f147da30199071ff69fe621400f48a5cbbc2baa7d6d8474abaf22ae1b7a714c31
-  data.tar.gz: 1191bd4b2b0c7e4668349260c5d571090b2d8cacdac03d38ce2257f8ceba83f7370f7863d0477ad1245bb7400420da0aefeaa36cd056d206b8dd44d3a25ec8b2
+  metadata.gz: 8478ba6318c4ff97a6c47f8e04358d26086f07f88db2e2a5fc00b69f96aada7fadf6d391d97a6aa84ea1dfe6eefb2eb2dcc9561bedd9caed34f3f2070fff2db9
+  data.tar.gz: 528e97b31426dd3aa76a782a0d19945763c826c5d861e1015bd053bc25460b019e7f26ac6c21cfede5a839fa188d865c3eba223758c7f111ac3a74f25ef548f8

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # CHANGELOG
 
+## [v1.0.3](https://github.com/lscspirit/app_config_loader/tree/v1.0.3) (2017-04-23)
+[Full list of commits](https://github.com/lscspirit/app_config_loader/compare/v1.0.2...v1.0.3)
+
+- Auto-initialization through Railtie in Rails
+- Make ConfigEntry comparable
+- Make ConfigMap and ConfigWithIndifferentAccess enumerable.
+
 ## [v1.0.2](https://github.com/lscspirit/app_config_loader/tree/v1.0.2) (2017-04-23)
 [Full list of commits](https://github.com/lscspirit/app_config_loader/compare/v1.0.1...v1.0.2)
 

data/README.md

@@ -1,6 +1,6 @@
 # AppConfigLoader
 
-A easy way to define application configurations using YAML in your Rails environment.
+A customizable YAML configuration library for Rails and Ruby, featuring wildcards, nesting, namespacing and local override. 
 
 ## Getting Started
 
@@ -24,15 +24,6 @@ Create a YAML file in the default directory `config/app_configs` to put your app
   'host': prod.someservice.com
 ```
 
-Create an initializer `config/initializers/00_app_config.rb` to configure and initialize AppConfigLoader. Typically, you would want AppConfigLoader to be the first thing to be initialized so that you can access your app config values in the remaining Rails initialization process. This is why the initializer filename has the '00_' prefix.
-
-
-```ruby
-# config/initializers/00_app_config.rb
-
-APP_CONFIG = AppConfigLoader.load
-```
-
 From this point onward, you can access your app config values through `APP_CONFIG`.
 
 ```ruby
@@ -43,25 +34,36 @@ APP_CONFIG['some_service.host']  # => 'dev.someservice.com'
 APP_CONFIG['some_service.host']  # => 'prod.someservice.com'
 ```
 
+### Non-Rails Environment
+
+When using `AppConfigLoader` outside of Rails, getting started is a little different:
+
+* the default app config file directory is `<pwd>/app_configs`
+* you need to manually initialize `AppConfigLoader` by including the following early on in your code:
+  ```ruby
+  AppConfigLoader.init
+  ```
+
 ## Configuration
 
 You can configure where and how AppConfigLoader load your app config file(s).
 
 ```ruby
-APP_CONFIG = AppConfigLoader.load do |config|
+AppConfigLoader.configure do |config|
   config.use_domain = true
   config.domain = 'us'
   config.config_paths << '/path/to/additional_config.yml'
 end
 ```
 
-Below is a list of all the settings available:
+Below is a list of all options available:
 
-* `config.env` - (String) app config environment. This determines which set of app config values to load. **Default:** `Rails.env`.
-* `config.use_domain` - (Boolean) whether the app config key uses a domain. **Default:** `false`.
+* `config.const_name` - (String) the name of the constant to which the config object is assigned. **Default:** `APP_CONFIG`
+* `config.env` - (String) app config environment. This determines which set of app config values to load. **Default:** Rails - `Rails.env`, non-Rails - `ENV['RACK_ENV'] || ENV['RUBY_ENV']`
+* `config.use_domain` - (Boolean) whether the app config key uses a domain. **Default:** `false`
 * `config.domain` - (String) app config domain. This determines which set of app config values to load. It is only applicable if `use_domain` is set to true. **Default:** `nil`
-* `config.config_paths` - (Array&lt;String&gt;) a list of paths from where app config YAML files should be loaded. Path can either be a file or a directory. With a directory path, all YAML files within that directory will be loaded. **Default:** `['<rails root>/config/app_configs']`.
-* `config.local_overrides` - (String) path to a local overrides app config file. Entries in this file take precedence over all values from other files. **Default:** `<rails root>/config/app_configs/local_overrides.yml`.
+* `config.config_paths` - (Array&lt;String&gt;) a list of paths from where app config YAML files should be loaded. Path can either be a file or a directory. With a directory path, all YAML files within that directory will be loaded. **Default:** Rails - `['<rails root>/config/app_configs']`, non-Rails - `['<pwd>/app_configs']`
+* `config.local_overrides` - (String) path to a local overrides app config file. Entries in this file take precedence over all values from other files. **Default:** Rails - `<rails root>/config/app_configs/local_overrides.yml`, non-Rails - `<pwd>/app_configs/local_overrides.yml`
 
 ## Defining your App Configs
 
@@ -72,7 +74,7 @@ All app configs are defined as key-value entries in YAML format. A app config va
 
 #### Basic Example
 
-```ruby
+```YAML
 # app config in YAML file
 'test.timeout': 3000
 'test.some_service.host': 'dev.someservice.com'
@@ -80,20 +82,27 @@ All app configs are defined as key-value entries in YAML format. A app config va
 'production.timeout': 500
 'production.some_service.host': 'prod.someservice.com'
 'production.some_service.port': 8000
+```
 
-# In Rails
-APP_CONFIG = AppConfigLoader.load do |config|
+```ruby
+# Rails initialization
+AppConfigLoader.configure do |config|
   config.env = 'test'
 end
 
+# after AppConfigLoader is initialized
 APP_CONFIG['timeout']             # => 3000
 APP_CONFIG['some_service.host']   # => dev.someservice.com
 APP_CONFIG['some_service.port']   # => nil
+```
 
-APP_CONFIG = AppConfigLoader.load do |config|
+```ruby
+# Rails initialization
+AppConfigLoader.configure do |config|
   config.env = 'production'
 end
 
+# after AppConfigLoader is initialized
 APP_CONFIG['timeout']             # => 500
 APP_CONFIG['some_service.host']   # => prod.someservice.com
 APP_CONFIG['some_service.port']   # => 8000
@@ -101,38 +110,45 @@ APP_CONFIG['some_service.port']   # => 8000
 
 #### Nested Definition
 
-```ruby
+```YAML
 'production.some_service':
   'host': 'prod.someservice.com'
   'port': 8000
-
-# In Rails
+```
+```ruby
 APP_CONFIG['some_service.host']   # => prod.someservice.com
 APP_CONFIG['some_service.port']   # => 8000
 ```
 
-#### Using Domain in Key
+#### Namespacing with Domain
 
-```ruby
+You may use `domain` to group your configuration. For example, you can provide different configuration when running in different regions.
+
+```YAML
 # app config in YAML file
 'production.us.some_service.host': 'prod.someservice.com'
 'production.hk.some_service.host': 'prod.someservice.com.hk'
-
-# In Rails
-APP_CONFIG = AppConfigLoader.load do |config|
+```
+```ruby
+# Rails initialization
+AppConfigLoader.configure do |config|
   config.env = 'production'
   config.use_domain = true
   config.domain     = 'us'
 end
 
+# after AppConfigLoader is initialized
 APP_CONFIG['some_service.host']   # => prod.someservice.com
-
-APP_CONFIG = AppConfigLoader.load do |config|
+```
+```ruby
+# Rails initialization
+AppConfigLoader.configure do |config|
   config.env = 'production'
   config.use_domain = true
   config.domain     = 'hk'
 end
 
+# after AppConfigLoader is initialized
 APP_CONFIG['some_service.host']   # => prod.someservice.com.hk
 ```
 
@@ -140,22 +156,27 @@ APP_CONFIG['some_service.host']   # => prod.someservice.com.hk
 
 You may use the wildcard `*` in place of the env and the domain. This allows you to specify app config entry that is applicable in any env or domain. An app config entry with a specific env or domain always takes precedence over ones with wildcard of the same key.
 
-```ruby
+```YAML
 # app config in YAML file
 '*.some_service.host': 'dev.someservice.com'
 'production.some_service.host': 'prod.someservice.com'
-
-# In Rails
-APP_CONFIG = AppConfigLoader.load do |config|
+```
+```ruby
+# Rails initialization
+AppConfigLoader.configure do |config|
   config.env = 'test'
 end
 
+# after AppConfigLoader is initialized
 APP_CONFIG['some_service.host']   # => dev.someservice.com
-
-APP_CONFIG = AppConfigLoader.load do |config|
+```
+```ruby
+# Rails initialization
+AppConfigLoader.configure do |config|
   config.env = 'production'
 end
 
+# after AppConfigLoader is initialized
 APP_CONFIG['some_service.host']   # => prod.someservice.com
 ```
 
@@ -170,6 +191,31 @@ When there a multiple app config entries for the same key, the final value is re
 '*.*.some_service.host': 'prod.someservice.com'               # lowest specificity
 ```
 
+### Key Conflict
+
+In most cases, entries belonging to or falling under the same key can be resolved by specificity. However, there are cases when the entries' values
+conflict with each other and a `ConfigKeyConflict` error will be raises. 
+
+* Assigning value to key with children
+
+  ```YAML
+  *.key_with_children.child_1: 'child1'
+  *.key_with_children.child_2: 'child2'
+  production.key_with_children: 'some value'
+
+  ```
+  The config above will raise `ConfigKeyConflict` error, regardless of the different in specificity. 
+  
+* Assigning children to key with value
+
+  ```YAML
+  production.key_with_value: 'some value'
+  *.key_with_value.child_1: 'child1'
+
+  ```
+  The config above will raise `ConfigKeyConflict` error, regardless of the different in specificity. 
+  
+
 ## Local Overrides File
 
 The local overrides file provides a quick way to override any entries defined in regular app config files. Entries within this file are resolved according to the specificity rule. Once resolved, the resolved entries will override any existing entries regardless of specificity. This is meant for development or testing purposes. Typically, you would not want to check this file into your source repository.

data/app_config_loader.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Derrick Yeung"]
   spec.email         = ["lscspirit@hotmail.com"]
 
-  spec.summary       = %q{Application configuration using YAML}
-  spec.description   = %q{A easy way to define application configurations using YAML in your Rails environment.}
+  spec.summary       = %q{Customizable YAML app config library}
+  spec.description   = %q{A customizable YAML configuration library for Rails and Ruby, featuring wildcards, nesting, namespacing and local override.}
   spec.homepage      = 'https://github.com/lscspirit/app_config_loader'
   spec.license       = "MIT"
 

data/lib/app_config_loader.rb

@@ -6,24 +6,50 @@ require 'app_config_loader/config_entry'
 require 'app_config_loader/config_map'
 require 'app_config_loader/config_with_indifferent_access'
 
+require 'app_config_loader/railtie' if defined?(Rails)
+
 module AppConfigLoader
-  def self.load(config = nil)
-    raise ArgumentError, 'config must be a AppConfigLoader::Config instance' unless config.nil? || config.is_a?(AppConfigLoader::Config)
+  #
+  # Config
+  #
 
-    active_cfg = config || default_config
+  def self.configure
+    yield self.config if block_given?
+  end
 
-    yield active_cfg if block_given?
+  def self.init
+    cfg = self.config
 
-    Loader.new(active_cfg).load
+    raise NameError, "cannot assign app config because '#{cfg.const_name}' is already defined" if Object.const_defined?(cfg.const_name)
+    Object.const_set cfg.const_name, self.load(cfg)
+  end
+
+  def self.load(config = nil)
+    raise ArgumentError, 'config must be a AppConfigLoader::Config instance' unless config.nil? || config.is_a?(AppConfigLoader::Config)
+    Loader.new(config || self.config).load
   end
 
   private
 
+  def self.config
+    @config ||= self.default_config
+  end
+
   def self.default_config
     cfg = AppConfigLoader::Config.new
-    cfg.env = defined?(Rails) ? Rails.env : 'development'
-    cfg.config_paths << (defined?(Rails) ? Rails.root.join('config', 'app_configs') : File.join(__dir__, 'app_configs'))
-    cfg.local_overrides = defined? (Rails) ? Rails.root.join('config', 'app_configs', 'local_overrides.yml') : File.join(__dir__, 'config', 'local_overrides.yml')
+
+    cfg.const_name = 'APP_CONFIG'
+
+    if defined?(Rails)
+      cfg.env = Rails.env || ENV['RACK_ENV'] || ENV['RUBY_ENV'] || 'development'
+      cfg.config_paths << Rails.root.join('config', 'app_configs')
+      cfg.local_overrides = Rails.root.join('config', 'app_configs', 'local_overrides.yml')
+    else
+      cfg.env = ENV['RACK_ENV'] || ENV['RUBY_ENV'] || 'development'
+      cfg.config_paths << File.join(Dir.pwd, 'app_configs')
+      cfg.local_overrides = File.join(Dir.pwd, 'config', 'local_overrides.yml')
+    end
+
     cfg
   end
 end

data/lib/app_config_loader/config.rb

@@ -1,6 +1,6 @@
 module AppConfigLoader
   class Config
-    attr_accessor :env, :domain, :local_overrides
+    attr_accessor :const_name, :env, :domain, :local_overrides
 
     def config_paths
       @config_paths ||= []

data/lib/app_config_loader/config_entry.rb

@@ -1,12 +1,15 @@
 module AppConfigLoader
   class ConfigEntry
+    include Comparable
+
     attr_reader :env, :domain, :key_components, :value
 
     #
     # Constructor
     #
     def initialize(full_key, value, use_domain = false)
-      @env, @domain, @key_components = parse_full_key full_key, use_domain
+      @use_domain = use_domain
+      @env, @domain, @key_components = parse_full_key full_key
       @value = value
     end
 
@@ -14,10 +17,23 @@ module AppConfigLoader
     # Accessor
     #
 
+    # Config key without env and domain
+    #
+    # @return [String] config key without the env and domain
     def key
       @key_components.join('.')
     end
 
+    # Config key including env and domain
+    # The domain portion is included if +config.use_domain+ is +true+
+    #
+    # @return [String] config key including the env and domain
+    def full_key
+      prefix = @env == :any ? '*.' : "#{@env}."
+      prefix += @domain == :any ? '*.' : "#{@domain}." if @use_domain
+      "#{prefix}#{self.key}"
+    end
+
     def specificity
       score = 0
       score += 1  if @env != :any       # add one point if env is specified
@@ -35,27 +51,59 @@ module AppConfigLoader
       true
     end
 
-    def ==(o)
-      o.class == self.class &&
-        o.env == self.env &&
-        o.domain == self.domain &&
-        o.key_components == self.key_components &&
-        o.value == self.value
+    def to_s
+      "#{self.full_key}: #{self.value}"
+    end
+
+    #
+    # Comparison
+    #
+
+    def ==(other)
+      other.class == self.class &&
+        other.env == self.env &&
+        other.domain == self.domain &&
+        other.key_components == self.key_components &&
+        other.value == self.value
     end
     alias_method :eql?, :==
 
+    def <=>(other)
+      # first compare key size
+      comp = self.key_components.count <=> other.key_components.count
+      return comp if comp != 0
+
+      # lexically compare the actual key components
+      other_keys = other.key_components
+      self.key_components.each_with_index do |key, index|
+        comp = key <=> other_keys[index]
+        return comp if comp != 0
+      end
+
+      # compare specificity
+      comp = self.specificity <=> other.specificity
+      return comp if comp != 0
+
+      # compare env
+      comp = wildcard_compare self.env, other.env
+      return comp if comp != 0
+
+      # compare domain
+      wildcard_compare self.domain, other.domain
+    end
+
     private
 
-    def parse_full_key(full_key, use_domain)
+    def parse_full_key(full_key)
       key_ary = full_key.split('.')
 
       raise InvalidConfigKey, "invalid config key '#{full_key}': must have a env component" unless key_ary.length > 1
-      raise InvalidConfigKey, "invalid config key '#{full_key}': must have a domain component when 'use_domain' is enabled" unless !use_domain || key_ary.length > 2
+      raise InvalidConfigKey, "invalid config key '#{full_key}': must have a domain component when 'use_domain' is enabled" unless !@use_domain || key_ary.length > 2
 
       begin
         env    = normalize_key_component key_ary[0], true
-        domain = use_domain ? normalize_key_component(key_ary[1], true) : :any
-        components = (use_domain ? key_ary[2..-1] : key_ary[1..-1]).map{ |k| normalize_key_component k }
+        domain = @use_domain ? normalize_key_component(key_ary[1], true) : :any
+        components = (@use_domain ? key_ary[2..-1] : key_ary[1..-1]).map{ |k| normalize_key_component k }
       rescue => ex
         raise InvalidConfigKey, "invalid config key component in '#{full_key}': #{ex.message}"
       end
@@ -71,5 +119,15 @@ module AppConfigLoader
         comp.to_s
       end
     end
+
+    def wildcard_compare(target, other)
+      if (diff = target <=> other) # comparing a symbol with string returns nil
+        diff
+      elsif target == :any
+        -1
+      else
+        1
+      end
+    end
   end
 end

data/lib/app_config_loader/config_map.rb

@@ -1,5 +1,7 @@
 module AppConfigLoader
   class ConfigMap
+    include Enumerable
+
     def initialize
       @key_map = {}
     end
@@ -38,6 +40,10 @@ module AppConfigLoader
       config_map.to_a.each { |override| self.add override, true }
     end
 
+    def each(&block)
+      self.to_a.each(&block)
+    end
+
     private
 
     def deep_add(parent, keys, &block)

data/lib/app_config_loader/config_with_indifferent_access.rb

@@ -1,5 +1,7 @@
 module AppConfigLoader
   class ConfigWithIndifferentAccess
+    include Enumerable
+
     def initialize(map, prefix = nil)
       @config_map = map
       @prefix     = prefix
@@ -21,5 +23,13 @@ module AppConfigLoader
       end
     end
     alias_method :[], :get
+
+    def to_a
+      @config_map.to_a
+    end
+
+    def each(&block)
+      @config_map.each(&block)
+    end
   end
 end

data/lib/app_config_loader/railtie.rb

@@ -0,0 +1,8 @@
+module AppConfigLoader
+  class Railtie < Rails::Railtie
+    config.before_initialize do
+      # initialize the app config before Rails initialization
+      AppConfigLoader.init
+    end
+  end
+end

data/lib/app_config_loader/version.rb

@@ -1,3 +1,3 @@
 module AppConfigLoader
-  VERSION = '1.0.2'
+  VERSION = '1.0.3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: app_config_loader
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Derrick Yeung
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-22 00:00:00.000000000 Z
+date: 2017-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,8 +66,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: A easy way to define application configurations using YAML in your Rails
-  environment.
+description: A customizable YAML configuration library for Rails and Ruby, featuring
+  wildcards, nesting, namespacing and local override.
 email:
 - lscspirit@hotmail.com
 executables: []
@@ -90,6 +90,7 @@ files:
 - lib/app_config_loader/errors.rb
 - lib/app_config_loader/loader.rb
 - lib/app_config_loader/parser.rb
+- lib/app_config_loader/railtie.rb
 - lib/app_config_loader/version.rb
 homepage: https://github.com/lscspirit/app_config_loader
 licenses:
@@ -114,5 +115,5 @@ rubyforge_project:
 rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
-summary: Application configuration using YAML
+summary: Customizable YAML app config library
 test_files: []