collapsium-config 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 831b6eb064c405db8797886058469fb8f613c0fc
-  data.tar.gz: c38ef78dd89d8a009e01719aa6860c4b6d953697
+  metadata.gz: 6f59285701d071aae2421be7c500cf4b814c346d
+  data.tar.gz: efe7bc99ba90a5b7a0508047a7e61ff5618eede9
 SHA512:
-  metadata.gz: f97ddbf8c8973f5d2590d45da0ab07778295dccc7078836002d899bc41920e75b8e423440af56ec516567fabbf71f3c35b9310634f2e640d6e75f50ec87e36d2
-  data.tar.gz: f0181fba285ca14f6153713316683a0b218bb7709814d01d89039b07c8d74f3f308f1bc71cf5d30c456b6033b1074eba3943cacbf41f8f8416035eb556e8ad3a
+  metadata.gz: 051281284616335b1776dc9001f07d5da473f3ce6873c3d477eb2b8c74c62396d6b57f30943c288123fbe76e149a5f50b63b83957bc30946b700ed1f584fce67
+  data.tar.gz: 26a6b17ffcb4af8aed8368adaf8f9686800f61dded3e3d1566b121ccf3b7e3618af8fbc94ecedcfb5fff22d2e05f6e0bd2730975cbf246913dcfc261c8820649

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    collapsium-config (0.2.1)
-      collapsium (~> 0.4)
+    collapsium-config (0.3.0)
+      collapsium (~> 0.5)
 
 GEM
   remote: https://rubygems.org/
@@ -10,20 +10,20 @@ GEM
     ast (2.3.0)
     codeclimate-test-reporter (0.6.0)
       simplecov (>= 0.7.1, < 1.0.0)
-    collapsium (0.4.1)
+    collapsium (0.5.0)
     diff-lcs (1.2.5)
     docile (1.1.5)
     json (2.0.2)
-    parser (2.3.1.2)
+    parser (2.3.1.4)
       ast (~> 2.2)
     powerpack (0.1.1)
     rainbow (2.1.0)
-    rake (11.2.2)
+    rake (11.3.0)
     rspec (3.5.0)
       rspec-core (~> 3.5.0)
       rspec-expectations (~> 3.5.0)
       rspec-mocks (~> 3.5.0)
-    rspec-core (3.5.2)
+    rspec-core (3.5.4)
       rspec-support (~> 3.5.0)
     rspec-expectations (3.5.0)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -32,7 +32,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.5.0)
     rspec-support (3.5.0)
-    rubocop (0.42.0)
+    rubocop (0.44.1)
       parser (>= 2.3.1.1, < 3.0)
       powerpack (~> 0.1)
       rainbow (>= 1.99.1, < 3.0)
@@ -44,7 +44,7 @@ GEM
       json (>= 1.8, < 3)
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.0)
-    unicode-display_width (1.1.0)
+    unicode-display_width (1.1.1)
     yard (0.9.5)
 
 PLATFORMS
@@ -54,9 +54,9 @@ DEPENDENCIES
   bundler (~> 1.12)
   codeclimate-test-reporter
   collapsium-config!
-  rake (~> 11.2)
+  rake (~> 11.3)
   rspec (~> 3.5)
-  rubocop (~> 0.42)
+  rubocop (~> 0.44)
   simplecov (~> 0.12)
   yard (~> 0.9)
 

data/README.md

@@ -18,11 +18,13 @@ various configuration sources into one configuration object.
   if that exists, and merges it's contents recursively into the main
   configuration.
 - Using the special `extends` configuration key, allows a configuration Hash
-  to include all values from another 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.
 
-# Usage
+# Basic Usage
 
 While you can use the `Configuration` class yourself, the simplest usage is to
 access a global configuration object:
@@ -33,3 +35,72 @@ include Collapsium::Config
 
 puts config["foo"] # loaded automatically from config.yml
 ```
+
+# Advanced Usage
+
+## 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
+to `config.yml`, but you can set it to something different, too:
+
+```ruby
+config_file = 'foo.yaml'
+puts config["foo"] # loaded automatically from foo.yaml
+```
+
+## 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,
+too:
+
+```ruby
+my_config = Collapsium::Config::Configuration.load_config('filename.yaml')
+```
+
+## Extension
+
+Given the following configuration file:
+
+```yaml
+base:
+  foo: 42
+
+derived:
+  bar: value
+  extends: .base
+```
+
+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.
+
+- 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.
+
+## Templating
+
+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
+which your loading code already knows. If you're using `#load_config`, you
+can do that with the `data` keyword parameter:
+
+```ruby
+my_data_hash = {}
+my_config = Configuration.load_config('foo.yaml', data: my_data_hash)
+```
+
+Note that the template has access to the entire hash under the `data` name,
+not to its individual keys:
+
+```erb
+<%= data[:some_key] %> # correct usage
+<%= some_key %>        # incorrect usage
+```

data/collapsium-config.gemspec

@@ -13,6 +13,7 @@ require 'collapsium-config/version'
 
 # rubocop:disable Style/UnneededPercentQ, Style/ExtraSpacing
 # rubocop:disable Style/SpaceAroundOperators
+# rubocop:disable Metrics/BlockLength
 Gem::Specification.new do |spec|
   spec.name          = "collapsium-config"
   spec.version       = Collapsium::Config::VERSION
@@ -37,13 +38,14 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.0'
 
   spec.add_development_dependency "bundler", "~> 1.12"
-  spec.add_development_dependency "rubocop", "~> 0.42"
-  spec.add_development_dependency "rake", "~> 11.2"
+  spec.add_development_dependency "rubocop", "~> 0.44"
+  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.4'
+  spec.add_dependency 'collapsium', '~> 0.5'
 end
+# rubocop:enable Metrics/BlockLength
 # rubocop:enable Style/SpaceAroundOperators
 # rubocop:enable Style/UnneededPercentQ, Style/ExtraSpacing

data/lib/collapsium-config/configuration.rb

@@ -65,6 +65,10 @@ module Collapsium
       end
       private_constant :JSONParser
 
+      def initialize(*args)
+        super(*args)
+      end
+
       class << self
         # @api private
         # Mapping of file name extensions to parser types.
@@ -267,80 +271,90 @@ module Collapsium
       # keywords that cannot be used in configuration files other than for this
       # purpose!
       def resolve_extensions!
-        recursive_merge("", "")
+        # The root object is always a Hash, so has keys, which can be processed
+        # recursively.
+        recursive_resolve(self)
       end
 
-      private
-
-      def recursive_merge(parent, key)
-        loop do
-          full_key = "#{parent}#{separator}#{key}"
+      def recursive_resolve(root, prefix = "")
+        # The self object is a Hash or an Array. Let's iterate over its children
+        # one by one. Defaulting to a Hash here is just convenience, it could
+        # equally be an Array.
+        children = root.fetch(prefix, {})
 
-          # Recurse down to the remaining root of the hierarchy
-          base = full_key
-          derived = nil
-          loop do
-            new_base, new_derived = resolve_extension(parent, base)
+        merge_base(root, prefix, children)
 
-            if new_derived.nil?
-              break
-            end
-
-            base = new_base
-            derived = new_derived
+        if children.is_a? Hash
+          children.each do |key, _|
+            full_key = normalize_path("#{prefix}#{separator}#{key}")
+            recursive_resolve(root, full_key)
           end
-
-          # If recursion found nothing to merge, we're done!
-          if derived.nil?
-            break
+        elsif children.is_a? Array
+          children.each_with_index do |_, idx|
+            key = idx.to_s
+            full_key = normalize_path("#{prefix}#{separator}#{key}")
+            recursive_resolve(root, full_key)
           end
-
-          # Otherwise, merge what needs merging and continue
-          merge_extension(base, derived)
         end
       end
 
-      def resolve_extension(grandparent, parent)
-        fetch(parent, {}).each do |key, value|
-          # Recurse into hash values
-          if value.is_a? Hash
-            recursive_merge(parent, key)
-          end
+      def merge_base(root, path, value)
+        # If the value is not a Hash, we can't do anything here.
+        if not value.is_a? Hash
+          return
+        end
 
-          # No hash, ignore any keys other than the special "extends" key
-          if key != "extends"
-            next
-          end
+        # If the value contains an "extends" keyword, we can find the value's
+        # base. Otherwise there's nothing to do.
+        if not value.include? "extends"
+          return
+        end
 
-          # If the key is "extends", return a normalized version of its value.
-          full_value = value.dup
-          if not full_value.start_with?(separator)
-            full_value = "#{grandparent}#{separator}#{value}"
+        # Now to resolve the path to the base and remove the "extends" keyword.
+        base_paths = value["extends"]
+        base_paths = base_paths.split(/,/).map(&:strip)
+        bases = {}
+        base_paths.each do |base_path|
+          if not base_path.start_with?(separator)
+            parent = parent_path(path)
+            base_path = "#{parent}#{separator}#{base_path}"
           end
+          base_path = normalize_path(base_path)
 
-          if full_value == parent
+          # Fetch the base value from the root. This makes full use of
+          # PathedAccess.
+          # We default to nil. Only Hash base values can be processed.
+          base_value = root.fetch(base_path, nil)
+          if not base_value.is_a? Hash
             next
           end
-          return full_value, parent
+
+          bases[base_path] = base_value
         end
 
-        return nil, nil
-      end
+        # Only delete the "extends" keyword if we found all base.
+        if bases.length == base_paths.length
+          value.delete("extends")
+        end
 
-      def merge_extension(base, derived)
-        # Remove old 'extends' key, but remember the value
-        extends = self[derived]["extends"]
-        self[derived].delete("extends")
+        # We need to recursively resolve the base values before merging them into
+        # value. To preserve the override order, we need to overwrite values when
+        # merging bases...
+        merged_base = Configuration.new
+        bases.each do |base_path, base_value|
+          base_value.recursive_resolve(root, base_path)
+          merged_base.recursive_merge!(base_value, true)
+        end
 
-        # Recursively merge base into derived without overwriting
-        self[derived].extend(::Collapsium::RecursiveMerge)
-        self[derived].recursive_merge!(self[base], false)
+        # ... but value needs to stay authoritative.
+        value.recursive_merge!(merged_base, false)
 
-        # Then set the "base" keyword, but only if it's not yet set.
-        if not self[derived]["base"].nil?
-          return
+        # Set the base if all is well.
+        if value["base"].nil? and not bases.keys.empty?
+          value["base"] = bases.keys
         end
-        self[derived]["base"] = extends
+
+        root[path] = value
       end
     end # class Configuration
   end # module Config

data/lib/collapsium-config/version.rb

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

data/spec/configuration_spec.rb

@@ -117,9 +117,25 @@ describe Collapsium::Config::Configuration do
       expect(cfg["drivers.leaf.branch2option"]).to eql "bar"
 
       # Also test that all levels go back to base == mock
-      expect(cfg["drivers.branch1.base"]).to eql 'mock'
-      expect(cfg["drivers.branch2.base"]).to eql 'mock'
-      expect(cfg["drivers.leaf.base"]).to eql 'mock'
+      expect(cfg["drivers.branch1.base"]).to eql %w(.drivers.mock)
+      expect(cfg["drivers.branch2.base"]).to eql %w(.drivers.mock)
+      expect(cfg["drivers.leaf.base"]).to eql %w(.drivers.mock)
+
+      # We expect that 'derived' is extended with '.other.base', too
+      expect(cfg["derived.test.foo"]).to eql 'bar'
+      expect(cfg["derived.test.some"]).to eql 'option'
+
+      # Expect this to also work with list items
+      expect(cfg["derived.test2.0.foo"]).to eql 'bar'
+      expect(cfg["derived.test2.0.some"]).to eql 'option'
+
+      expect(cfg["derived.test3.foo"]).to eql 'bar'
+      expect(cfg["derived.test3.some2"]).to eql 'option2'
+
+      # Expect this to work with multiple inheritance
+      expect(cfg["derived.test4.foo"]).to eql 'bar'
+      expect(cfg["derived.test4.some"]).to eql 'option_override'
+      expect(cfg["derived.test4.some2"]).to eql 'option2'
     end
 
     it "extends configuration hashes when the base does not exist" do
@@ -129,8 +145,11 @@ describe Collapsium::Config::Configuration do
       # Ensure the hash contains its own value
       expect(cfg["drivers.base_does_not_exist.some"]).to eql "value"
 
-      # Also ensure the "base" is set properly
-      expect(cfg["drivers.base_does_not_exist.base"]).to eql "nonexistent_base"
+      # Also ensure the "base" is _not_ set properly
+      expect(cfg["drivers.base_does_not_exist.base"]).to be_nil
+
+      # On the other hand, "extends" should stay.
+      expect(cfg["drivers.base_does_not_exist.extends"]).to eql "nonexistent_base"
     end
 
     it "does nothing when a hash extends itself" do

data/spec/data/driverconfig.yml

@@ -24,3 +24,24 @@ drivers:
     extends: nonexistent_base
     some: value
 driver: leaf
+
+other:
+  testbase:
+    some: option
+  testbase2:
+    - some2: option2
+      some: option_override
+
+derived:
+  test:
+    foo: bar
+    extends: .other.testbase
+  test2:
+    - foo: bar
+      extends: .other.testbase
+  test3:
+    foo: bar
+    extends: .other.testbase2.0
+  test4:
+    foo: bar
+    extends: .other.testbase, .other.testbase2.0

data/spec/data/extend.yml

@@ -4,3 +4,5 @@ foo_base:
 bar:
   extends: bar_base
   foo: something
+merged:
+  second: 2

data/spec/data/include-extend.yml

@@ -5,3 +5,5 @@ foo:
   bar: quux
 bar_base:
   baz: 42
+merged:
+  first: 1

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: collapsium-config
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Jens Finkhaeuser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-18 00:00:00.000000000 Z
+date: 2016-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -30,28 +30,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.42'
+        version: '0.44'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.42'
+        version: '0.44'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '11.2'
+        version: '11.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '11.2'
+        version: '11.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -100,14 +100,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.5'
 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  "