collapsium-config 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6f59285701d071aae2421be7c500cf4b814c346d
-  data.tar.gz: efe7bc99ba90a5b7a0508047a7e61ff5618eede9
+  metadata.gz: 0a2e09619cf514355f44f452ca59fd28a7843346
+  data.tar.gz: efbe2423aa303a6fc3ec19d94ebe95a7064a3186
 SHA512:
-  metadata.gz: 051281284616335b1776dc9001f07d5da473f3ce6873c3d477eb2b8c74c62396d6b57f30943c288123fbe76e149a5f50b63b83957bc30946b700ed1f584fce67
-  data.tar.gz: 26a6b17ffcb4af8aed8368adaf8f9686800f61dded3e3d1566b121ccf3b7e3618af8fbc94ecedcfb5fff22d2e05f6e0bd2730975cbf246913dcfc261c8820649
+  metadata.gz: 609a05eefe1d7a6db2a11787bdee3ae865b642b30295e00b4e3192452789fad9c664895c20c0945faa59ae1c1be8d7a8f3ebd02b7c97bda09547f5a8c142c7d7
+  data.tar.gz: adc2a47d375e899e828028ebc1fedf021aa78782f70d9d1c43f682102bdda1720297eab3b315be51aee9199e4fa68c7f88cb49f178f5f921f5af75e899841c7f

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    collapsium-config (0.3.0)
-      collapsium (~> 0.5)
+    collapsium-config (0.4.0)
+      collapsium (~> 0.6)
 
 GEM
   remote: https://rubygems.org/
@@ -10,7 +10,7 @@ GEM
     ast (2.3.0)
     codeclimate-test-reporter (0.6.0)
       simplecov (>= 0.7.1, < 1.0.0)
-    collapsium (0.5.0)
+    collapsium (0.6.1)
     diff-lcs (1.2.5)
     docile (1.1.5)
     json (2.0.2)
@@ -32,7 +32,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.5.0)
     rspec-support (3.5.0)
-    rubocop (0.44.1)
+    rubocop (0.45.0)
       parser (>= 2.3.1.1, < 3.0)
       powerpack (~> 0.1)
       rainbow (>= 1.99.1, < 3.0)
@@ -56,9 +56,9 @@ DEPENDENCIES
   collapsium-config!
   rake (~> 11.3)
   rspec (~> 3.5)
-  rubocop (~> 0.44)
+  rubocop (~> 0.45)
   simplecov (~> 0.12)
   yard (~> 0.9)
 
 BUNDLED WITH
-   1.12.5
+   1.13.6

data/README.md

@@ -17,12 +17,14 @@ various configuration sources into one configuration object.
 - Given a main configuration file `foo.yml` to load, also loads `foo-local.yml`
   if that exists, and merges it's contents recursively into the main
   configuration.
+- Pathed access to configuration variables.
 - Using the special `extends` configuration key, allows a configuration Hash
   to include all values from other configuration Hash(es).
 - Using the special, top-level `include` configuration key, allows a
   configuration file to be split into multiple included files.
 - As of `v0.2`, configuration files are [ERB templates](http://ruby-doc.org/stdlib-2.3.1/libdoc/erb/rdoc/ERB.html).
   Do your templating stuff as you'd usually do it.
+- Allows overriding of configuration values from the environment.
 
 # Basic Usage
 
@@ -38,7 +40,9 @@ puts config["foo"] # loaded automatically from config.yml
 
 # Advanced Usage
 
-## Configuration File Location
+## Configuration File Management
+
+### Configuration File Location
 
 The friendly neighbour to the `#config` function introduced in the basic
 usage section above is the `#config_file` accessor. Its value will default
@@ -49,7 +53,7 @@ config_file = 'foo.yaml'
 puts config["foo"] # loaded automatically from foo.yaml
 ```
 
-## Loading Configuration Files
+### Loading Configuration Files
 
 All that `#config` and `#config_file` do is wrap `#load_config` such that
 configuration is loaded only once. You can load configuration files manually,
@@ -59,33 +63,66 @@ too:
 my_config = Collapsium::Config::Configuration.load_config('filename.yaml')
 ```
 
-## Extension
+### Array Files
+
+Configuration files can also contain Arrays at the top level. While that may
+make some sense at times, it does not make for good naming schemes and creates
+problems elsewhere.
 
-Given the following configuration file:
+Therefore, if your file contains an Array at the top level, the class wraps it
+into a Hash with a `config` key containing the Array:
 
 ```yaml
-base:
-  foo: 42
+- foo
+- bar
+```
 
-derived:
-  bar: value
-  extends: .base
+```ruby
+config["config"][0] # => "foo"
+config["config"][1] # => "bar"
 ```
 
-Then the special `extends` keyword is interpreted to merge all values from
-the value at path `.base` into the value at path `.derived`. Additionally,
-`.derived` will gain a new key `base` which is an Array containing all the
-bases merged into the value.
+### File Formats
 
-- Absolute paths are preferred for values of `extends`.
-- Relative paths for values of `extends` are looked up in the parent of the
-  value that contains the `extends` keyword, i.e. the root in the example
-  above. So in this minimal example, specifying `.base` and `base` is
-  equivalent.
-- You can specify a comma-separated list of bases in the `extends` keyword.
-  Latter paths overwrite values in earlier paths.
+The gem supports loading [YAML](http://yaml.org/) and [JSON](http://www.json.org/)
+configuration files. Both formats can be mixed in the various mechanisms described
+below.
+
+### Local Configuration Overrides
+
+For the example file of `config/config.yml`, if a file with the same path and
+name, and the name postfix `-local` exists (i.e. `config/config-local.yml`), that
+file will also be loaded. It's keys will be recursively added to the keys from the
+main configuration file, overwriting only leaves, not entire hashes.
+
+Example:
+
+```yaml
+# config/config.yml
+---
+foo:
+  bar: 42
+  baz: quux
+
+# config/config-local.yml
+---
+something: else
+foo:
+  baz: override
+
+# result
+---
+something: else
+foo:
+  bar: 42
+  baz: override
+```
+
+### Templating
 
-## Templating
+Configuration files aren't quite static entities even taking merging of local
+overrides into account. They can further be generated at load time by
+templating, extension and including.
 
 ERB templating in configuration files works out-of-the-box, but one of the
 more powerful features is of course to substitute some values in the template
@@ -104,3 +141,179 @@ not to its individual keys:
 <%= data[:some_key] %> # correct usage
 <%= some_key %>        # incorrect usage
 ```
+
+But even without explicit passing of a data hash, you can use templating to
+e.g. include environment variables:
+
+```erb
+foo: <%= ENV['MYVAR'] %>
+```
+
+Note, though, that this might interact unexpectedly with the environment
+override feature described later.
+
+
+### Extension
+
+An additional feature is that you can extend individual hashes with values from
+other hashes.
+
+```yaml
+---
+root:
+  foo: bar
+derived:
+  baz: quux
+  extends: root
+```
+
+This results in:
+
+```yaml
+---
+root:
+  foo: bar
+derived:
+  baz: quux
+  foo: bar
+  base: root
+```
+
+The special `extends` keyword is interpreted to merge all values from
+the value at path `.root` into the value at path `.derived`. Additionally,
+`.derived` will gain a new key `base` which is an Array containing all the
+bases merged into the value.
+
+**Notes:**
+
+- Absolute paths are preferred for values of `extends`.
+- Relative paths for values of `extends` are looked up in the parent of the
+  value that contains the `extends` keyword, i.e. the root in the example
+  above. So in this minimal example, specifying `.base` and `base` is
+  equivalent.
+- You can specify a comma-separated list of bases in the `extends` keyword.
+  Latter paths overwrite values in earlier paths.
+- You can also specify an Array of paths, with the same effect.
+- This feature means that `extends` and `base` are reserved configuration keys!
+- Multiple levels of extension are supported.
+
+### Includes
+
+Includes work just as you might expect: if you specify a key `include` anywhere,
+the value will be interpreted as a file system path to another configuration file.
+That other file will be loaded, and the parent of the `include` statement will
+gain all the values from the other configuration file.
+
+Example:
+
+```yaml
+# config/main.yml
+include: config/first.yml
+foo:
+  bar: 42
+  include: config/second.yml
+```
+
+```yaml
+# config/first.yml
+baz: quux
+```
+
+```yaml
+# config/second.yml
+- 123
+- 456
+```
+
+Will result in:
+
+```yaml
+# final YAML
+baz: quux
+foo:
+  bar: 42
+  data:
+    - 123
+    - 456
+```
+
+**Notes:**
+
+- If your loaded configuration file contains an Array at the top level, then
+  a new key `config` will be added (see Array Files above)
+- You can specify a comma-separated list of paths in the `include` keyword.
+  Latter paths overwrite values in earlier paths.
+- You can also specify an Array of paths, with the same effect.
+- This means that `include` is a reserved configuration key.
+
+## Configuration Access
+
+### Pathed Access
+
+Thanks to [collapsium](https://github.com/jfinkhaeuser/collapsium)'s `UberHash`,
+configuration values can be accessed more easily than in a regular nested
+structure. Take the following configuration as an example:
+
+```yaml
+---
+foo:
+  bar:
+    baz: 42
+    quux:
+      - 123
+      - "asdf"
+```
+
+Then, the following are equivalent:
+
+```ruby
+config["foo"]["bar"]["baz"]
+config["foo.bar.baz"]
+config[".foo.bar.baz"]
+config["foo.bar"]["baz"]
+config["foo"]["bar.baz"]
+```
+
+The major benefit is that if *any* of the path components does not exist, nil is
+returned (and the behaviour is equivalent to other access methods such as
+`:fetch`, etc.)
+
+Similarly you can use this type of access for writing: `config['baz.quux'] = 42`
+will create both the `baz` hash, and it's child the `quux` key.
+
+## Environment Override
+
+Given a configuration path, any environment variable with the same name (change
+path to upper case letters and replace `.` with `_`, e.g. `foo.bar` becomes
+`FOO_BAR`) overrides the values in the configuration file.
+
+```ruby
+# Called with FOO_BAR=42
+config["foo.bar"] # => 42
+```
+
+If the environment variable is parseable as JSON, then that parsed JSON will
+**replace** the original configuration path (i.e. it will not be merged).
+
+```ruby
+# Called with FOO_BAR='{ "baz": 42 }'
+config["foo.bar.baz"] # => 42
+```
+
+
+## A Note on Priorities
+
+A lot of the features above interact with each other. For example, environment
+override still respects pathed access. In other cases, things are not quite
+so clear, so let's give you a rough idea on priorities in the code:
+
+1. Templating happens when files are loaded, and generates the most basic data
+   the gem works with.
+1. Configuration file merging happens next, i.e. `config.yml` and `config-local.yml`
+   are merged into one data structure.
+1. Next up is handling of `include` directives.
+1. After that, `extends` is resolved - that is, `extends` works on paths that
+   only exists after any of the above steps created them. This step finishes the
+   configuration loading process.
+1. Finally, environment override works whenever a value is *accessed*, meaning
+   if the environment changes, so does the configuration value.

data/collapsium-config.gemspec

@@ -38,13 +38,13 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.0'
 
   spec.add_development_dependency "bundler", "~> 1.12"
-  spec.add_development_dependency "rubocop", "~> 0.44"
+  spec.add_development_dependency "rubocop", "~> 0.45"
   spec.add_development_dependency "rake", "~> 11.3"
   spec.add_development_dependency "rspec", "~> 3.5"
   spec.add_development_dependency "simplecov", "~> 0.12"
   spec.add_development_dependency "yard", "~> 0.9"
 
-  spec.add_dependency 'collapsium', '~> 0.5'
+  spec.add_dependency 'collapsium', '~> 0.6'
 end
 # rubocop:enable Metrics/BlockLength
 # rubocop:enable Style/SpaceAroundOperators

data/lib/collapsium-config/configuration.rb

@@ -9,6 +9,8 @@
 
 require 'collapsium'
 
+require 'collapsium-config/support/values'
+
 module Collapsium
   module Config
     ##
@@ -40,6 +42,7 @@ module Collapsium
     # result may be unexpected.
     class Configuration < ::Collapsium::UberHash
       include ::Collapsium::EnvironmentOverride
+      include ::Collapsium::Config::Support::Values
 
       # @api private
       # Very simple YAML parser
@@ -70,6 +73,8 @@ module Collapsium
       end
 
       class << self
+        include ::Collapsium::Config::Support::Values
+
         # @api private
         # Mapping of file name extensions to parser types.
         FILE_TO_PARSER = {
@@ -109,7 +114,7 @@ module Collapsium
           config.recursive_merge!(local_config)
 
           # Resolve includes
-          config = resolve_includes(base, config, options[:data])
+          config = resolve_includes(base, config, options)
 
           # Create config from the result
           cfg = Configuration.new(config)
@@ -183,63 +188,37 @@ module Collapsium
           return data
         end
 
-        def resolve_includes(base, config, template_data)
-          processed = []
-          includes = []
-
-          loop do
-            # Figure out includes
-            outer_inc = extract_includes(config)
-            if not outer_inc.empty?
-              includes = outer_inc
-            end
-
-            to_process = includes - processed
-
-            # Stop resolving when all includes have been processed
-            if to_process.empty?
-              break
-            end
-
-            # Load and merge the include files
-            to_process.each do |filename|
-              incfile = Pathname.new(base.dirname)
-              incfile = incfile.join(filename)
-
-              # Just try to open it, if that errors out that's ok.
-              file = incfile.open
-              contents = file.read
-
-              parsed = parse(incfile.extname, contents, template_data)
-
-              # Extract and merge includes
-              inner_inc = extract_includes(parsed)
-              includes += inner_inc
-
-              # Merge the rest
-              config.recursive_merge!(hashify(parsed))
+        def resolve_includes(base, config, options)
+          # Only process Hashes
+          if not config.is_a? Hash
+            return config
+          end
 
-              processed << filename
+          # Figure out includes. We have to recursively fetch the string and
+          # the symbol keys, and process includes where we find them.
+          ["include", :include].each do |key|
+            config.recursive_fetch_all(key) do |parent, value, _|
+              # The value contains the includes
+              includes = array_value(value)
+              parent.delete(key)
+
+              # Now merge all includes into the parent
+              includes.each do |filename|
+                # Load included file
+                incfile = Pathname.new(base.dirname)
+                incfile = incfile.join(filename)
+
+                # Due to the way recursive_fetch works, we may get bad
+                included = Configuration.load_config(incfile, options)
+
+                # Merge included
+                parent.recursive_merge!(hashify(included), true)
+              end
             end
           end
 
           return config
         end
-
-        def extract_includes(config)
-          # Figure out includes
-          includes = config.fetch("include", [])
-          config.delete("include")
-          includes = config.fetch(:include, includes)
-          config.delete(:include)
-
-          # We might have a simple/string include
-          if not includes.is_a? Array
-            includes = [includes]
-          end
-
-          return includes
-        end
       end # class << self
 
       ##
@@ -311,8 +290,7 @@ module Collapsium
         end
 
         # Now to resolve the path to the base and remove the "extends" keyword.
-        base_paths = value["extends"]
-        base_paths = base_paths.split(/,/).map(&:strip)
+        base_paths = array_value(value["extends"])
         bases = {}
         base_paths.each do |base_path|
           if not base_path.start_with?(separator)

data/lib/collapsium-config/support/values.rb

@@ -0,0 +1,50 @@
+# coding: utf-8
+#
+# collapsium-config
+# https://github.com/jfinkhaeuser/collapsium-config
+#
+# Copyright (c) 2016 Jens Finkhaeuser and other collapsium-config contributors.
+# All rights reserved.
+#
+
+require 'collapsium'
+
+module Collapsium
+  module Config
+    ##
+    # Contains support code
+    module Support
+      ##
+      # Contains helper functions for parsing configuration values.
+      module Values
+
+        ##
+        # Given the value, turn it into an Array:
+        # - comma-separated strings are split
+        # - other single values are wrapped into an Array
+        def array_value(value)
+          # Split comma-separated strings.
+          if value.respond_to? :split
+            value = value.split(/,/)
+          end
+
+          # If the value is an Array, we strip its string elements.
+          if value.is_a? Array
+            value = value.map do |v|
+              if v.respond_to? :strip
+                next v.strip
+              end
+              next v
+            end
+          else
+            # Otherwise turn the value into an Array if it's a single
+            # value.
+            value = [value]
+          end
+
+          return value
+        end
+      end # module Values
+    end # module Support
+  end # module Config
+end # module Collapsium

data/lib/collapsium-config/version.rb

@@ -9,6 +9,6 @@
 module Collapsium
   module Config
     # The current release version
-    VERSION = "0.3.0".freeze
+    VERSION = "0.4.0".freeze
   end # module Config
 end # module Collapsium

data/spec/configuration_spec.rb

@@ -180,6 +180,15 @@ describe Collapsium::Config::Configuration do
       expect(cfg["baz"]).to eql 'test'
     end
 
+    it "can include multiple files from a comma-separated list" do
+      config = File.join(@data_path, 'include-multiple2.yml')
+      cfg = Collapsium::Config::Configuration.load_config(config)
+
+      expect(cfg["foo"]).to eql 42
+      expect(cfg["bar"]).to eql 'quux'
+      expect(cfg["baz"]).to eql 'test'
+    end
+
     it "can resolve includes recursively" do
       config = File.join(@data_path, 'include-recursive.yml')
       cfg = Collapsium::Config::Configuration.load_config(config)
@@ -198,6 +207,23 @@ describe Collapsium::Config::Configuration do
       expect(cfg["bar.foo"]).to eql 'something'
       expect(cfg["bar.baz"]).to eql 42
     end
+
+    it "can include array configuration files" do
+      config = File.join(@data_path, 'include-array.yml')
+      cfg = Collapsium::Config::Configuration.load_config(config)
+
+      expect(cfg["quux"]).to eql "baz"
+      expect(cfg["config"]).to eql %w(foo bar)
+    end
+
+    it "works in nested structures" do
+      config = File.join(@data_path, 'include-nested.yml')
+      cfg = Collapsium::Config::Configuration.load_config(config)
+
+      expect(cfg["foo"]).to eql "bar"
+      expect(cfg["baz.quux"]).to eql "baz" # Overridden from include!
+      expect(cfg["baz.config"]).to eql %w(foo bar)
+    end
   end
 
   describe "behaves like a UberHash" do

data/spec/data/include-array.yml

@@ -0,0 +1,3 @@
+---
+quux: baz
+include: array.yaml

data/spec/data/include-multiple2.yml

@@ -0,0 +1,3 @@
+---
+foo: 42
+include: include1.yml, include2.json

data/spec/data/include-nested.yml

@@ -0,0 +1,5 @@
+---
+foo: bar
+baz:
+  quux: asdf
+  include: include-array.yml

data/spec/support_values_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+require_relative '../lib/collapsium-config/support/values'
+
+describe Collapsium::Config::Support::Values do
+  let(:tester) { Class.new { extend Collapsium::Config::Support::Values } }
+
+  context "#array_value" do
+    it "splits a comma separated string" do
+      expect(tester.array_value("foo,bar")).to eql %w(foo bar)
+    end
+
+    it "strips spaces from comma separated strings" do
+      expect(tester.array_value(" foo ,  bar ")).to eql %w(foo bar)
+    end
+
+    it "turns single strings into an array" do
+      expect(tester.array_value("foo")).to eql %w(foo)
+    end
+
+    it "strips spaces from single strings" do
+      expect(tester.array_value(" foo ")).to eql %w(foo)
+    end
+
+    it "strips array elements" do
+      expect(tester.array_value(['foo ', ' bar'])).to eql %w(foo bar)
+    end
+
+    it "wraps other values into arrays" do
+      expect(tester.array_value({})).to eql [{}]
+      expect(tester.array_value(42)).to eql [42]
+    end
+
+    it "handles mixed arrays well" do
+      expect(tester.array_value([42, 'foo'])).to eql [42, 'foo']
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: collapsium-config
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jens Finkhaeuser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-10-27 00:00:00.000000000 Z
+date: 2016-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.44'
+        version: '0.45'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.44'
+        version: '0.45'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -100,14 +100,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
+        version: '0.6'
 description: "\n    Using collapsium's UberHash class for easy access to configuration
   values,\n    this gem reads and merges various configuration sources into one\n
   \   configuration object.\n  "
@@ -130,6 +130,7 @@ files:
 - collapsium-config.gemspec
 - lib/collapsium-config.rb
 - lib/collapsium-config/configuration.rb
+- lib/collapsium-config/support/values.rb
 - lib/collapsium-config/version.rb
 - spec/configuration_spec.rb
 - spec/data/array.yaml
@@ -138,8 +139,11 @@ files:
 - spec/data/extend.yml
 - spec/data/global.yml
 - spec/data/hash.yml
+- spec/data/include-array.yml
 - spec/data/include-extend.yml
 - spec/data/include-multiple.yml
+- spec/data/include-multiple2.yml
+- spec/data/include-nested.yml
 - spec/data/include-recursive.yml
 - spec/data/include-simple.yml
 - spec/data/include1.yml
@@ -156,6 +160,7 @@ files:
 - spec/data/test.json
 - spec/module_spec.rb
 - spec/spec_helper.rb
+- spec/support_values_spec.rb
 homepage: https://github.com/jfinkhaeuser/collapsium-config
 licenses:
 - MITNFA
@@ -188,8 +193,11 @@ test_files:
 - spec/data/extend.yml
 - spec/data/global.yml
 - spec/data/hash.yml
+- spec/data/include-array.yml
 - spec/data/include-extend.yml
 - spec/data/include-multiple.yml
+- spec/data/include-multiple2.yml
+- spec/data/include-nested.yml
 - spec/data/include-recursive.yml
 - spec/data/include-simple.yml
 - spec/data/include1.yml
@@ -206,3 +214,4 @@ test_files:
 - spec/data/test.json
 - spec/module_spec.rb
 - spec/spec_helper.rb
+- spec/support_values_spec.rb