config_hound 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bf68a0009e160c2de3a2f7a14e189f526327a275
-  data.tar.gz: e6845c1983d410b7b89653b0b1a9e00e76d83102
+  metadata.gz: 876182cbec6fa89633e1fd3b2fdbed37b88a714a
+  data.tar.gz: 9c342ccc39c549785c660c4b13b9ab52d17a6024
 SHA512:
-  metadata.gz: 23399f2c12c0360b4f972e5bec88b8839ebdafcfc2f00f39047a0a5d3b90609e4a6a373d9541300755024b1b715686cbe5644943bcb62a15fc38336fbf63dd1c
-  data.tar.gz: 0569f52b04d4e1304e7b52d0fa95f98efb3e902ac85014faf48e050fca5224aa713da6c3a463c06ad80048af5a88719bee19d5ae768143444d11798b383a6482
+  metadata.gz: c05735b52a238ba1fd28189880ee341b95f61cbebc96ac733e6411531ec197e433ba931acdf660d98958c297db0c3396c3aae4141b5b4388f1ded3f162d290ee
+  data.tar.gz: b9a148f6097f6c42849845a8881367716629d7a97709efab0393ba95c89e01b177abbdcd1654783aeaeabe33c77eed3201c687c9a1d8de42fa23908573eb9b25

data/README.md

@@ -1,48 +1,104 @@
 # ConfigHound
 
-ConfigHound makes it easy to load configuration data that is
-spread between multiple files.
+ConfigHound makes it easy to load configuration data.
 
 ## Usage
 
-    # load YAML
-    config = ConfigHound.load("config.yml")
+`ConfigHound.load` supports config in JSON, YAML or TOML formats, and returns raw Ruby data.
 
-    # load JSON
-    config = ConfigHound.load("config.json")
+```ruby
+config = ConfigHound.load("config.yml")   # or "config.{json,toml}"
+```
 
-    # load TOML
-    config = ConfigHound.load("config.toml")
+## Remote config
+
+As well as local files, you can load from any URI supported by `OpenURI`, e.g.
+
+```ruby
+# load over HTTP
+ConfigHound.load("http://config-source/app-config.yml")
+
+# load from S3
+require "open-uri-s3"
+config = ConfigHound.load("s3://config-bucket/app-config.json")
+```
+
+## Multiple sources of config
+
+If you specify a list of config sources, ConfigHound will load them all, and deep-merge the data. Files specified earlier in the list take precedence.
+
+```ruby
+ConfigHound.load(["config.yml", "defaults.yml"])
+```
+
+You can include raw data (Hashes) in the list, too, which is handy if you have defaults or overrides already in Ruby format.
+
+```ruby
+overrides = { ... }
+ConfigHound.load([overrides, "config.yml"])
+```
 
 ## Inclusion
 
-ConfigHound let's you include defaults from other files.
-Just list the file paths (or URLs) under the key "_include",
+You can also "include" other file (or URIs) from _within_ a config file.
+Just list the paths under the key `_include`.
 
 For example, in `config.yml`:
 
-    _include:
-      - defaults.yml
-    pool:
-      size: 10
-    log:
-      file: "app.log"
+```yaml
+pool:
+  size: 10
+log:
+  file: "app.log"
+_include:
+  - defaults.yml
+```
 
 then in `defaults.yml`
 
-    log:
-      level: INFO
-    pool:
-      size: 1
+  ```yaml
+log:
+  level: INFO
+pool:
+  size: 1
+```
 
-Values in the original config file override those from included files.
+Values in the original config file take precedence over those from included files.
 Multiple levels of inclusion are possible.
 
 If the placeholder "`_include`" doesn't suit, you can specify
 another, e.g.
 
-    config = ConfigHound.load("config.yml", :include_key => "defaults")
+```ruby
+config = ConfigHound.load("config.yml", :include_key => "defaults")
+```
+
+## Reference expansion
+
+ConfigHound can expand references of the form `<(X.Y.Z)>` in config values, which can help DRY up configuration, e.g.
+
+```yaml
+name: myapp
+aws:
+  region: us-west-1
+log:
+  stream: <(name)>-logs-<(aws.region)>
+```
+
+Enable reference expansion with the `:expand_refs` option.
+
+```ruby
+ConfigHound.load(config_files, :expand_refs => true)
+```
+
+Reference expansion is performed _after_ all config is loaded and merged, so you can reference config specified in other files.
 
 ## Contributing
 
 It's on GitHub; you know the drill.
+
+## See also
+
+ConfigHound works well with:
+
+* [ConfigMapper](https://github.com/mdub/config_mapper)

data/lib/config_hound/error.rb

@@ -0,0 +1,5 @@
+module ConfigHound
+
+  Error = Class.new(StandardError)
+
+end

data/lib/config_hound/interpolation.rb

@@ -0,0 +1,73 @@
+require "config_hound/error"
+
+module ConfigHound
+
+  # Expand variables
+  #
+  module Interpolation
+
+    extend self
+
+    def expand(input, root = input, seen = Set.new)
+      Context.new(root).expand(input)
+    end
+
+    # Interpolation context
+    #
+    class Context
+
+      def initialize(root, seen = Set.new)
+        @root = root
+        @seen = seen.freeze
+      end
+
+      attr_reader :root
+      attr_reader :seen
+
+      def expand(input)
+        case input
+        when Hash
+          expand_hash(input)
+        when Array
+          input.map { |v| expand(v) }
+        when /\A<\(([\w.]+)\)>\Z/
+          evaluate_expression($1)
+        when /<\([\w.]+\)>/
+          input.gsub(/<\(([\w.]+)\)>/) do
+            evaluate_expression($1)
+          end
+        else
+          input
+        end
+      end
+
+      private
+
+      def expand_hash(input)
+        input.each_with_object({}) do |(k,v), a|
+          a[k] = expand(v)
+        end
+      end
+
+      def evaluate_expression(expr)
+        if seen.include?(expr)
+          details = seen.map { |e| "<(#{e})>" }.join(", ")
+          raise CircularReferenceError, "circular reference: #{details}"
+        end
+        words = expr.split(".")
+        expansion = root.dig(*words)
+        if expansion.nil?
+          raise ReferenceError, "cannot resolve reference: <(#{expr})>"
+        end
+        subcontext = Context.new(root, seen + [expr])
+        subcontext.expand(expansion)
+      end
+
+    end
+
+    ReferenceError = Class.new(ConfigHound::Error)
+    CircularReferenceError = Class.new(ReferenceError)
+
+  end
+
+end

data/lib/config_hound/loader.rb

@@ -1,4 +1,5 @@
 require "config_hound/deep_merge"
+require "config_hound/interpolation"
 require "config_hound/resource"
 
 module ConfigHound
@@ -7,21 +8,28 @@ module ConfigHound
 
     DEFAULT_INCLUDE_KEY = "_include"
 
+    attr_accessor :include_key
+    attr_accessor :expand_refs
+
     def initialize(options = {})
-      @include_key = options.fetch(:include_key, DEFAULT_INCLUDE_KEY)
+      @include_key = DEFAULT_INCLUDE_KEY
+      options.each do |k, v|
+        public_send("#{k}=", v)
+      end
     end
 
-    def load(paths)
-      Array(paths).reverse.map do |path|
-        load_resource(Resource[path])
-      end.reduce({}, &ConfigHound.method(:deep_merge_into))
+    def load(sources)
+      raw_hashes = Array(sources).map(&method(:load_source))
+      result = raw_hashes.reverse.reduce({}, &ConfigHound.method(:deep_merge_into))
+      result = Interpolation.expand(result) if expand_refs
+      result
     end
 
     private
 
-    attr_reader :include_key
-
-    def load_resource(resource)
+    def load_source(source)
+      return source if source.is_a?(Hash)
+      resource = Resource[source]
       raw_data = resource.load
       includes = Array(raw_data.delete(include_key))
       included_resources = includes.map do |relative_path|

data/lib/config_hound/resource.rb

@@ -1,10 +1,11 @@
+require "config_hound/error"
 require "config_hound/parser"
 require "open-uri"
 require "uri"
 
 module ConfigHound
 
-  LoadError = Class.new(StandardError)
+  LoadError = Class.new(ConfigHound::Error)
 
   # Represents a source of configuration data.
   #

data/lib/config_hound/version.rb

@@ -1,3 +1,3 @@
 module ConfigHound
-  VERSION = "1.2.1"
+  VERSION = "1.3.0"
 end

data/lib/config_hound.rb

@@ -8,5 +8,3 @@ module ConfigHound
   end
 
 end
-
-

data/spec/config_hound/interpolation_spec.rb

@@ -0,0 +1,151 @@
+require "spec_helper"
+
+require "config_hound/interpolation"
+
+describe ConfigHound::Interpolation do
+
+  describe ".expand" do
+
+    let(:output) { described_class.expand(input) }
+
+    context "with a simple config Hash" do
+
+      let(:input) do
+        {
+          "author" => {
+            "name" => "Mike"
+          }
+        }
+      end
+
+      it "returns the input" do
+        expect(output).to eql(input)
+      end
+
+    end
+
+    context "with reference" do
+
+      let(:input) do
+        {
+          "x" => 42,
+          "y" => "<(x)>"
+        }
+      end
+
+      it "expands the reference" do
+        expect(output["y"]).to eql(42)
+      end
+
+    end
+
+    context "with complex reference" do
+
+      let(:input) do
+        {
+          "vars" => {
+            "author" => {
+              "name" => "Mike"
+            }
+          },
+          "foo" => "<(vars.author.name)>"
+        }
+      end
+
+      it "expands the reference" do
+        expect(output["foo"]).to eql("Mike")
+      end
+
+    end
+
+    context "with reference in nested object" do
+
+      let(:input) do
+        {
+          "vars" => {
+            "author" => {
+              "name" => "Mike"
+            }
+          },
+          "foo" => {
+            "bar" => "<(vars.author.name)>"
+          }
+        }
+      end
+
+      it "expands the reference" do
+        expect(output["foo"]["bar"]).to eql("Mike")
+      end
+
+    end
+
+    context "with reference embedded in a String" do
+
+      let(:input) do
+        {
+          "size" => 42,
+          "desc" => "Size <(size)>"
+        }
+      end
+
+      it "expands the reference" do
+        expect(output["desc"]).to eql("Size 42")
+      end
+
+    end
+
+    context "when multiple references" do
+
+      let(:input) do
+        {
+          "everything" => "<(parts.first)> and <(parts.last)>",
+          "parts" => {
+            "first" => "<(article)> one",
+            "last" => "<(article)> two"
+          },
+          "article" => "Part"
+        }
+      end
+
+      it "expands the reference" do
+        expect(output["everything"]).to eql("Part one and Part two")
+      end
+
+    end
+
+  end
+
+  context "with circular reference" do
+
+    let(:input) do
+      {
+        "ping" => "refers to <(pong)>",
+        "pong" => "refers to <(ping)>"
+      }
+    end
+
+    it "raises a ReferenceError" do
+      expect {
+        described_class.expand(input)
+      }.to raise_error(ConfigHound::Interpolation::ReferenceError)
+    end
+
+  end
+
+  context "with unresolved reference" do
+
+    let(:input) do
+      {
+        "foo" => "refers to <(bar)>"
+      }
+    end
+
+    it "raises a ReferenceError" do
+      expect {
+        described_class.expand(input)
+      }.to raise_error(ConfigHound::Interpolation::ReferenceError)
+    end
+
+  end
+
+end

data/spec/features/expansion_spec.rb

@@ -0,0 +1,19 @@
+require "spec_helper"
+
+require "config_hound"
+
+describe ConfigHound, "expansion" do
+
+  let(:config) { ConfigHound.load("config.yml", :expand_refs => true) }
+
+  given_resource "config.yml", %{
+    var:
+      port: 5678
+    address: host:<(var.port)>
+  }
+
+  it "expands references" do
+    expect(config["address"]).to eq("host:5678")
+  end
+
+end

data/spec/features/{basics_spec.rb → formats_spec.rb}

@@ -2,7 +2,7 @@ require "spec_helper"
 
 require "config_hound"
 
-describe ConfigHound do
+describe ConfigHound, "formats" do
 
   def load(path)
     ConfigHound.load(path)

data/spec/features/{include_spec.rb → inclusion_spec.rb}

@@ -1,5 +1,8 @@
+require "spec_helper"
 
-describe ConfigHound do
+require "config_hound"
+
+describe ConfigHound, "inclusion" do
 
   let(:options) { {} }
 
@@ -193,5 +196,3 @@ describe ConfigHound do
 
   end
 end
-
-

data/spec/features/sources_spec.rb

@@ -0,0 +1,59 @@
+require "spec_helper"
+
+require "config_hound"
+
+describe ConfigHound, "sources" do
+
+  let(:defaults) do
+    {
+      "meta" => {
+        "winner" => "defaults"
+      },
+      "data" => {
+        "from-defaults" => "D"
+      }
+    }
+  end
+
+  given_resource "fileA.yml", %{
+    meta:
+      winner: fileA
+    data:
+      from-fileA: A
+  }
+
+  given_resource "fileB.yml", %{
+    meta:
+      winner: fileB
+    data:
+      from-fileB: B
+  }
+
+  let(:overrides) do
+    {
+      "meta" => {
+        "winner" => "overrides"
+      },
+      "data" => {
+        "from-overrides" => "O"
+      }
+    }
+  end
+
+  let(:config) do
+    ConfigHound.load([overrides, "fileA.yml", "fileB.yml", defaults])
+  end
+
+  it "merges file contents with hashes" do
+    data = config.fetch("data")
+    expect(data["from-overrides"]).to eql("O")
+    expect(data["from-fileA"]).to eql("A")
+    expect(data["from-fileB"]).to eql("B")
+    expect(data["from-defaults"]).to eql("D")
+  end
+
+  it "favours the earliest source" do
+    expect(config["meta"]["winner"]).to eq("overrides")
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: config_hound
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Mike Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-04 00:00:00.000000000 Z
+date: 2017-07-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -54,15 +54,19 @@ files:
 - config_hound.gemspec
 - lib/config_hound.rb
 - lib/config_hound/deep_merge.rb
+- lib/config_hound/error.rb
+- lib/config_hound/interpolation.rb
 - lib/config_hound/loader.rb
 - lib/config_hound/parser.rb
 - lib/config_hound/resource.rb
 - lib/config_hound/version.rb
 - spec/config_hound/deep_merge_spec.rb
+- spec/config_hound/interpolation_spec.rb
 - spec/config_hound/resource_spec.rb
-- spec/features/basics_spec.rb
-- spec/features/include_spec.rb
-- spec/features/multi_file_spec.rb
+- spec/features/expansion_spec.rb
+- spec/features/formats_spec.rb
+- spec/features/inclusion_spec.rb
+- spec/features/sources_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/mdub/config_hound
 licenses:
@@ -84,14 +88,16 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.6.12
 signing_key: 
 specification_version: 4
 summary: Sniffs out config, wherever it may be.
 test_files:
 - spec/config_hound/deep_merge_spec.rb
+- spec/config_hound/interpolation_spec.rb
 - spec/config_hound/resource_spec.rb
-- spec/features/basics_spec.rb
-- spec/features/include_spec.rb
-- spec/features/multi_file_spec.rb
+- spec/features/expansion_spec.rb
+- spec/features/formats_spec.rb
+- spec/features/inclusion_spec.rb
+- spec/features/sources_spec.rb
 - spec/spec_helper.rb

data/spec/features/multi_file_spec.rb

@@ -1,28 +0,0 @@
-require "spec_helper"
-
-require "config_hound"
-
-describe ConfigHound do
-
-  let(:config) { ConfigHound.load(["fileA.yml", "fileB.yml"]) }
-
-  given_resource "fileA.yml", %{
-    source: A
-    fromA: true
-  }
-
-  given_resource "fileB.yml", %{
-    source: B
-    fromB: true
-  }
-
-  it "loads both files" do
-    expect(config).to have_key("fromA")
-    expect(config).to have_key("fromB")
-  end
-
-  it "favours earliest included file" do
-    expect(config["source"]).to eq("A")
-  end
-
-end