layeredyamlconfig 1.4.3

data/History.txt

@@ -0,0 +1,36 @@
+# LayeredYAMLConfig Change History
+
+## 1.4.3
+
+* first release on rubygems.org
+* bring test suite to 100% coverage
+
+## 1.4.2
+
+* remove soft breakpoints.  I make this mistake so often I wrote a Perl test module to catch them: https://metacpan.org/release/Test-NoBreakpoints.  Time for a Ruby version methinks.
+
+## 1.4.1
+
+* replace dependency on 'erbuis' (ERB's sophisticated European cousin) with 'erubis'
+
+## 1.4.0
+
+* added ::reset and ::reset_all methods to reset per-class options to their default
+* added ERB Template evaluation of leaf nodes
+
+## 1.3.0
+
+* Added #to_hash
+
+## 1.2.0
+
+* added #files read accessor to get a list of files the config was constructed from
+
+## 1.1.0
+
+* Changes to symbolized keys
+* We now return an object of our class and delegate key lookup to the underlying hash
+
+## 1.0.0
+
+* Initial Release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2012, 2013 James FitzGibbon <james@nadt.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,46 @@
+History.txt
+Manifest.txt
+README.txt
+LICENSE.txt
+Rakefile
+layeredyamlconfig.gemspec
+lib/layeredyamlconfig.rb
+lib/layeredyamlconfig/array_traverse.rb
+lib/layeredyamlconfig/core.rb
+lib/layeredyamlconfig/hash_traverse.rb
+lib/layeredyamlconfig/templates.rb
+test/minitest_helper.rb
+test/ex1.yaml
+test/ex2.yaml
+test/ex3.yaml
+test/ex4.yaml
+test/ex5.yaml
+test/ex6.yaml
+test/ex7.yaml
+test/ex8.yaml
+test/ex9.yaml
+test/ex10.yaml
+test/ex11.yaml
+test/ex12.yaml
+test/ex13.yaml
+test/ex14.yaml
+test/ex15.yaml
+test/ex16.yaml
+test/ex17.yaml
+test/ex18.yaml
+test/exbad1.yaml
+test/exbad2.yaml
+test/test_addlayer.rb
+test/test_clear.rb
+test/test_comments.rb
+test/test_constructor.rb
+test/test_deepmerge.rb
+test/test_erb_array.rb
+test/test_erb_hash.rb
+test/test_erb_empty.rb
+test/test_erb_multi.rb
+test/test_erb.rb
+test/test_files.rb
+test/test_invalid.rb
+test/test_multi.rb
+test/test_tohash.rb

data/README.txt

@@ -0,0 +1,247 @@
+# LayeredYAMLConfig
+
+home :: https://github.com/jf647/LayeredYAMLConfig
+
+## SUMMARY:
+
+Ruby configuration library that layers multiple YAML files on top of each
+other with ERB evalution.
+
+## DESCRIPTION:
+
+LayeredYAMLConfig provides a simple config file that supports multiple
+layers.  Values in the right or uppermost layers override values in lower
+layers.  This makes it easy to share configuration without duplication while
+still allowing what needs to be different to vary.
+
+For example:
+
+    program.default.conf
+    program.server_foo.conf
+    program.site_bar.conf
+    program.conf
+
+Optionally, leaf nodes can be evaluated using as ERB templates, feeding the
+configuration into itself.
+
+## Synopsis
+
+```ruby
+class MyConfig < LayeredYAMLConfig
+end
+
+MyConfig.skipbad = true
+cfg = MyConfig.instance( 'ex7.yaml', 'ex8.yaml', 'ex9.yaml', 'ex10.yaml' )
+puts cfg[:foo]['bar']
+puts cfg['foo'][:gzonk]
+```
+
+ex7.yaml:
+```yaml
+---
+foo:
+    bar: baz
+```
+
+ex8.yaml:
+```yaml
+---
+foo:
+    gzonk: quux
+```
+
+ex10.yaml:
+```text
+This is not a YAML file
+```
+
+ex16.yaml:
+```text
+---
+a: d
+b: e
+c: f
+g:
+    - <%= @cfg[:a] %>
+    - <%= @cfg[:b] %>
+    - <%= @cfg[:c] %>
+```
+
+To use LayeredYAMLConfig, create a new class that inherits from it.  The new
+class is a singleton that can only be constructed the first time ::instance
+is called.  Pass one or more YAML filenames which will be read and deep
+merged on top of each other in left-to-right order.
+
+Files that are missing are skipped by default.  Files that are bad (i.e. do
+not parse as valid YAML) cause an exception to be thrown.  This behaviour
+can be overridden by calling ::skipbad = true or ::skipmissing = true before
+constructing the configuration.
+
+The type of the returned object is your subordinate class, but #[] and #[]=
+are delegated to the contained hash, which is an
+ActiveSupport::HashWithIndifferentAccess.  This means you can use strings or
+symbols interchangeably to access elements of the hash.
+
+## Adding Layers after Instance Construction
+
+Using #add, you can add one or more layers that are deep merged into the
+existing config.
+
+## Converting to a Hash
+
+Call #to_hash to return a symbolized hash representation of the
+configuration object
+
+## ERB Templates
+
+To enable template evaluation, call ::templates = true on the class:
+
+```ruby
+class OurConfig < LayeredYAMLConfig
+end
+OurConfig.templates = true
+OurConfig.instance('file_containing_erb.yaml')
+```
+
+Every time #add is called (either directly or implicitly during creation),
+the configuration tree is traversed.  Any String leaf nodes are evaluated
+using Erubis.  The only context variable available is @cfg, which
+representes the configuration at the start of the template pass.
+
+The process of template evaluation is as follows:
+
+1. Walk the tree, keeping track of how successful and failed template evaluations we performed
+2. If there were no failures, the pass is complete
+3. If there were no successes and the previous pass (if any) had at least one success, keep going
+4. If there were no successes and the previous pass also had no successes, raise an exception
+5. Keep going
+
+Requiring two passes with no successful template evaluations allows files in
+upper layers to depend on values defined in lower layers.  For example,
+given these files:
+
+```text
+---
+a:
+    b:
+        c: <%= @cfg[:d][:e][:f] %>
+
+---
+d:
+    e:
+        f: <%= @cfg[:g][:h][:i] %>
+
+---
+g:
+    h:
+        i: j
+```
+
+It would take two passes to fully resolve all templates.  In the first pass,
+cfg[:d][:e][:f] would resolve to 'j', and in the second pass,
+cfg[:a][:b][:c] would also resolve to 'j'.
+
+### Empty Strings
+
+If a template evaluates to the empty string, this is by default considered a
+failure.  To treat empty strings as success, call ::emptyok before
+constructing the configuration:
+
+```ruby
+class OurConfig < LayeredYAMLConfig
+end
+OurConfig.templates = true
+OurConfig.emptyok = true
+OurConfig.instance('file_containing_erb.yaml')
+```
+
+Beware of hidden gotchas though: if an intermediate node is undefined, ERB
+will throw an exception trying to deference nil.  But if only the last node
+is defined, then ERB will generate an empty string:
+
+```text
+---
+a:
+    b:
+        c: d
+        e: <%= @cfg[:a][:b][:f] %>
+        g: <%= @cfg[:a][:h][:i] %>
+```
+
+In the default mode, neither template resolves successfully.  With ::emptyok
+enabled, cfg[:a][:b][:e] becomes the empty string.
+
+### What can be expanded
+
+The result of an Erubis expansion is always a string.  Therefore, you can't
+expand a Hash or Array and then expect it to dereference properly.  This,
+for example, won't work:
+
+```text
+a:
+    one: 1
+    two: 2
+    three: 3
+b: <%= @cfg[:a] %>
+```
+
+```ruby
+puts cfg[:b][:one]
+```
+
+The expansion of cfg[:b] isn't the same as cfg[:a], it's the same as
+cfg[:a].to_s.
+
+You can however dereference through a Hash or Array to a scalar leaf:
+
+```text
+a:
+    one: 1
+    two: 2
+    three: 3
+b: <%= @cfg[:a][:one] %>
+```
+
+```ruby
+puts cfg[:b]
+```
+
+## Resetting Per-Class Options
+
+call ::reset on your class to reset the ::skipbad, ::skipmissing,
+::templates and ::emptyok settings to their defaults.  Call ::reset_all on
+the base class to reset these options to default for all derived classes.
+
+## LICENSE:
+
+The MIT License (MIT)
+
+Copyright (c) 2012, 2013 James FitzGibbon <james@nadt.net>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+
+## Contributing to LayeredYAMLConfig
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the version or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

data/Rakefile

@@ -0,0 +1,18 @@
+require 'rake/testtask'
+require 'hoe'
+
+Hoe.spec 'layeredyamlconfig' do
+    developer("James FitzGibbon", "james@nadt.net")
+    license "MIT"
+end
+
+task :default => [:unit_tests]
+
+desc "Run basic tests"
+Rake::TestTask.new("unit_tests") { |t|
+    t.libs.push 'lib'
+    t.libs.push 'test'
+    t.pattern = 'test/test_*.rb'
+    t.verbose = true
+    t.warning = true
+}

data/layeredyamlconfig.gemspec

@@ -0,0 +1,17 @@
+$:.push File.expand_path("../lib", __FILE__)
+require 'layeredyamlconfig'
+
+Gem::Specification.new do |s|
+    s.name          = 'layeredyamlconfig'
+    s.version       = ThreadedLogger::VERSION
+    s.summary       = 'YAML Configs with multiple layers and ERB evaluation'
+    s.add_dependency( 'psych', '>= 1.3.4' )
+    s.add_dependency( 'activesupport', '>= 3.2.12' )
+    s.add_dependency( 'hash-deep-merge' )
+    s.add_dependency( 'erubis' )
+    s.authors       = ['James FitzGibbon']
+    s.email         = ['james@nadt.net']
+    s.files         = `git ls-files`.split("\n")
+    s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+    s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f)
+end

data/lib/layeredyamlconfig.rb

@@ -0,0 +1,2 @@
+require 'layeredyamlconfig/core'
+require 'layeredyamlconfig/templates'

data/lib/layeredyamlconfig/array_traverse.rb

@@ -0,0 +1,19 @@
+# based on Hash traverse from Ruby Facets (https://github.com/rubyworks/facets)
+class Array
+
+    def traverse(&blk)
+        na = []
+        inject(na) do |a, e|
+            case e
+                when Hash
+                    e = e.traverse(&blk)
+                when Array
+                    e = e.traverse(&blk)
+            end
+            ne = blk.call(e)
+            a.push ne
+            a
+        end
+    end
+
+end

data/lib/layeredyamlconfig/core.rb

@@ -0,0 +1,103 @@
+require 'yaml'
+require 'forwardable'
+require 'hash_deep_merge'
+require 'active_support/core_ext/hash/indifferent_access'
+
+class LayeredYAMLConfig
+
+    VERSION = '1.4.3'
+
+    extend Forwardable
+
+    private_class_method :new
+    attr_reader :files
+    def_delegators :@cfg, :[], :[]=, :to_hash
+    
+    def self.instance(*files)
+        if @@instances[self].nil?
+            if ! files.empty?
+                @@instances[self] = new(files)
+            else
+                raise ArgumentError, "no files in initial construction of #{self}"
+            end
+        else
+            if ! files.empty?
+                raise ArgumentError, "instance for #{self} already constructed"
+            end
+        end
+        return @@instances[self]
+    end
+
+    def self.clear
+        @@instances[self] = nil
+    end
+
+    def self.clear_all
+        @@instances = Hash.new
+    end
+
+    def self.reset
+        %w(skipbad skipmissing templates emptyok).each do |opt|
+            @@opts[opt.to_sym].delete(self)
+        end
+    end
+
+    def self.reset_all
+        @@opts = {
+            :skipbad => Hash.new(false),
+            :skipmissing => Hash.new(true),
+            :templates => Hash.new(false),
+            :emptyok => Hash.new(false),
+        }
+    end
+    
+    # create class-level option accessors
+    %w(skipbad skipmissing templates emptyok).each do |opt|
+        self.define_singleton_method(opt.to_sym) do
+            @@opts[opt.to_sym][self]
+        end
+        self.define_singleton_method("#{opt}=".to_sym) do |newval|
+            @@opts[opt.to_sym][self] = !!newval
+        end
+    end
+
+    # add files to an instance
+    def add(*files)
+        # due to the multi passing of splat args, we can get Array-in-Array situations here
+        files.flatten.each do |fn|
+            @files.push(fn)
+            if ! File.exists?(fn)
+                next if self.class.skipmissing
+                raise ArgumentError, "file #{fn} does not exist"
+            end
+            begin
+                data = YAML.load(File.open(fn))
+                if ! data.instance_of?(Hash)
+                    raise ArgumentError, "file #{fn} does not contain a Hash"
+                end
+                @cfg.deep_merge!(data.deep_symbolize_keys).deep_symbolize_keys
+            rescue
+                if ! self.class.skipbad
+                    raise
+                end
+            end
+        end
+
+        # resolve templates
+        if self.class.templates
+            resolve_templates
+        end
+    end
+
+    # constructor
+    def initialize(*files)
+        @cfg = Hash.new.with_indifferent_access
+        @files = []
+        add(files)
+    end
+    
+    # create catalog of per-subclass instances and options
+    self.clear_all
+    self.reset_all
+
+end