yaml_settings 1.0.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 248f78a2595723d1f64b57406b7bed078831232b
+  data.tar.gz: 302fa7f374b773c56fa3dbc93655711f3e6b3dab
+SHA512:
+  metadata.gz: a3d3f8bcb4964b607d765369f31ba74781e39d851396a69bbb91d3a4718510156f713cc6824b0d709e173f062ba3eaec21b134d1561fd1156792d5c8b910a36e
+  data.tar.gz: ef37138b7b107afaed5f377382bd0a314cddba81d7e8770987afdd5278bc34f7e0c273ad99c5fd65af9c84b910ba221652c234e770f2456cd9ab635ce90d5e26

data/.rdoc_options

@@ -0,0 +1,11 @@
+--- !ruby/object:RDoc::Options
+charset: UTF-8
+encoding: UTF-8
+static_path: []
+rdoc_include:
+- "."
+exclude: 
+line_numbers: false
+main_page: README.rdoc
+markup: rdoc
+title: YAMLSettings Ruby Gem - Load and merge app settings from YAML files

data/README.rdoc

@@ -0,0 +1,154 @@
+= YAML Settings
+
+Load and merge application settings from YAML files.
+
+At load time, settings are merged in two stages. First, all YAML data are
+recursively merged in reverse file order. Settings in succeeding files override
+all duplicate settings in preceding files. Second, the user selected
+settings—specified by key (e.g., environment key)—are recursively merged with
+the default settings.
+
+This class can load multiple settings files, which provides a few benefits:
+
+1. Confidential settings can be stored separately and securely from
+   non-confidential settings; for example, in a public repository.
+
+2. Settings for each application component or service (e.g., database, payment
+   gateway, logger, CDN) can be stored in their respective files.
+
+3. Shared or system-wide settings can be merged with application settings.
+
+
+== Settings File Examples
+
+The following are settings files, defined using YAML[http://yaml.org], which
+typically use the +.yml+ or +.yaml+ file extension. For information on how to
+craft YAML, see the spec[http://yaml.org/spec/].
+
+=== Absolute minimal settings
+
+  default:
+
+Above is the *mandatory* +default+ stanza, which must be present in at least one
+of the YAML settings files, even if it is empty. This isn't very useful, so lets
+add a couple of default settings.
+
+  default:
+    setting_1: on
+    setting_2: off
+
+
+=== Database settings
+
+Here we have settings that specify the database name, user, host, and password
+file. There are three additional top-level stanzas: +development+, +production+,
+and +test+. These stanzas can be defined for any reason and have any name, but
+typically represent the runtime environment or mode of the application. Zero or
+more non-default top-level stanzas can be defined.
+
+  # database.yaml
+  default:
+    db:
+      host: db.example.com
+      user: dbusr
+      pass: config/db-access
+
+  development:
+    db:
+      name: myapp_dev
+
+  production:
+    db:
+      name: myapp
+      pass: /var/www/sites/myapp/db-access
+
+  test:
+    db:
+      name: myapp_test
+
+With these settings, the +default+ will always provide the database +host+ and
++user+ because it is not overridden in any other stanza. However, the database
++name+ is not specified in +default+ because it is set in each environment. In
++production+, the database password file is unique—and secure of course—thus
+overrides +default+.
+
+
+== Usage Examples
+
+<em>First things first!</em>
+
+  require 'yaml_settings'
+
+=== Load database settings
+
+Load +production+ using the database settings above. The +production+ settings
+are merged into +default+.
+
+  settings = YAMLSettings.new('database.yaml', :production)
+  settings.db.host    # => "db.example.com"
+  settings.db.user    # => "dbusr"
+  settings.db.name    # => "myapp"
+  settings.db.pass    # => "/var/www/sites/myapp/db-access"
+
+The settings are accessed using methods. The +db+ setting is actually a Hash and
+can also be accessed as such.
+
+  settings.db['host']   # => "db.example.com"
+
+The difference is that method access raises an error if a setting is nonexistent.
+
+  settings.db.mia       # KeyError: key not found: "mia"
+  settings.db['mia']    # => nil
+
+Method access is only available for string and symbol keys of Hash settings.
+
+=== Load multiple settings files
+
+It may be helpful to store settings for each application component separately.
+Or perhaps, settings are in a shared location. Here's how to initialize for such
+a situation:
+
+  settings = YAMLSettings.new '/etc/app-defaults.yml',         # system wide
+                              '/etc/payment-gateway.yml',      # system wide
+                              '/var/www/share/config/cdn.yml', # common for sites
+                              'config/app.yml',                # app specific
+                              'config/database.yml',           # app specific
+                              ENV['APP_MODE']
+
+The +settings+ variable above is a compilation of four merges. First,
+_config/database.yml_ will merge with and override _config/app.yml_; the result
+will merge with and override _cdn.yml_; and so on. Therefore, specify files with
+more generic settings first.
+
+
+== Links
+
+Homepage      :: https://ecentryx.com/gems/yaml_settings
+Ruby Gem      :: https://rubygems.org/gems/yaml_settings
+Source Code   :: https://bitbucket.org/pachl/yaml_settings/src
+Bug Tracker   :: https://bitbucket.org/pachl/yaml_settings/issues
+
+
+== History
+
+1. 2017-06-30, v1.0.6
+   * First public release
+
+
+== License
+
+({ISC License}[https://opensource.org/licenses/ISC])
+
+Copyright (c) 2013-2017, Clint Pachl <pachl@ecentryx.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

data/Rakefile

@@ -0,0 +1,22 @@
+GEM_NAME = File.basename(Dir['*.gemspec'][0], '.*')
+
+desc 'Build gem'
+task :gem do
+  system "gem build #{GEM_NAME}.gemspec"
+end
+
+desc 'Publish docs'
+task :pub do
+  dir  = ENV.fetch('public_gem_dir') + GEM_NAME
+  host = ENV.fetch('public_gem_host')
+
+  if system 'rdoc lib README.rdoc'
+    `cd ./doc && pax -w . | ssh #{host} 'cd #{dir} && rm -rf * && pax -r'`
+    `rm -r ./doc;`
+  end
+end
+
+desc 'Run tests'
+task :test do
+  system 'bacon -a'
+end

data/lib/yaml_settings.rb

@@ -0,0 +1,59 @@
+require 'delegate'
+require 'yaml'
+
+class YAMLSettings < DelegateClass(Hash)
+
+  VERSION = '1.0.6'
+
+  module AttrReader # :nodoc:
+    def method_missing(setting)
+      has_key?(setting) ? fetch(setting) : fetch(setting.to_s) # raises KeyError
+    end
+    private :method_missing
+  end
+
+  #
+  # Settings are merged in two stages. First, all +filenames+ are recursively
+  # merged in reverse order. Settings in succeeding +filenames+ overwrite all
+  # duplicate settings in preceding +filenames+. Second, settings specified by
+  # +key+ are then recursively merged with the _default_ settings.
+  #
+  # +filenames+:: one or more YAML data files
+  # +key+::       selects the top-level stanza from +filenames+ to be merged
+  #               with the _default_ stanza
+  #
+  def initialize(*filenames, key)
+    all_settings = filenames.collect {|f| YAML.load_file(f) }
+    settings = all_settings.reduce {|i, j| deep_merge(i, j) }
+    @settings = deep_merge(settings.fetch('default'),
+                           settings.fetch(key.to_s))
+    @settings.extend(AttrReader)
+    propagate_attr_reader(@settings)
+    super(@settings)
+  end
+
+  def inspect() @settings.inspect end
+  alias :to_s :inspect
+
+  private
+
+  def method_missing(setting, *args, &blk)
+    super rescue @settings.send(setting)
+  end
+
+  def deep_merge(h1, h2)
+    h1.merge!(h2) do |key, v1, v2|
+      v1.is_a?(Hash) && v2.is_a?(Hash) ? deep_merge(v1, v2) : v2
+    end
+  end
+
+  def propagate_attr_reader(settings)
+    settings.each_value do |setting_value|
+      if setting_value.is_a? Hash
+        setting_value.extend(AttrReader)
+        propagate_attr_reader(setting_value)
+      end
+    end
+  end
+
+end

data/spec/fixtures/default.yml

@@ -0,0 +1,79 @@
+# NOTE: Settings with a value of 'default overriden' should never be accessible.
+default:
+  a: 'default overriden'
+  c:
+    a:
+      a: 'default overriden'
+      b: 'default c.a.b'
+    b: 'default c.b'
+    c: 'default overriden'
+  d:
+    a: 'default d.a'
+  e:
+    a:
+      a: 'default overriden'
+      b: 'default overriden'
+    b:
+      a: 'default e.b.a'
+      b: 'default overriden'
+  f:
+    - 'default 0'
+    - 'default 1'
+  g:
+    - 'default overriden'
+    - 'default overriden'
+    - 'default overriden'
+  :h: 'default h'
+  i:
+    a: 'default i.a'
+  j:
+    a:
+      a: 'default j.a.a'
+  k:
+    a: 'default overriden'
+    b: 'default overriden'
+    c: 'default overriden'
+    d: 'default k.d'
+  l:
+    a: 'default overriden'
+    b: 'default overriden'
+  m: 'default m'
+ 
+test:
+  a: 'test a'
+  b:
+    a: 'test b.a'
+    b: 'test b.b'
+  c:
+    a:
+      a: 'test c.a.a'
+    c: 'test c.c'
+  d:
+    b: 'test d.b'
+  e:
+    a:
+      a: 'test e.a.a'
+      b: 'test e.a.b'
+    b:
+      b: 'test e.b.b'
+  g:
+    - 'test 0'
+    - 'test 1'
+  k:
+    a: 'test k.a'
+    b: 'test k.b'
+    c: 'test k.c'
+    e: 'test k.e'
+  l: 'test l'
+  m:
+    a: 'test m.a'
+ 
+development:
+  a: 'development a'
+
+production:
+  a: 'production a'
+  k:
+    a: 'production k.a'
+    b: 'production overriden'
+

data/spec/fixtures/default_missing.yml

@@ -0,0 +1,3 @@
+# Missing "default" stanza; no bueno!
+development:
+  setting_1: 'setting 1'

data/spec/fixtures/default_only.yml

@@ -0,0 +1,3 @@
+# For simple configurations, allow just the "default" stanza.
+default:
+  setting_1: 'setting 1'

data/spec/fixtures/example_database.yml

@@ -0,0 +1,18 @@
+default:
+  db:
+    host: db.example.com
+    user: dbusr
+    pass: config/db-access
+
+development:
+  db:
+    name: myapp_dev
+
+production:
+  db:
+    name: myapp
+    pass: /var/www/sites/myapp/db-access
+
+test:
+  db:
+    name: myapp_test

data/spec/fixtures/private.yml

@@ -0,0 +1,6 @@
+# Confidential settings to be securely stored.
+production:
+  a: 'production a [private]'
+  k:
+    b: 'production k.b [private]'
+    c: 'production k.c [private]'

data/spec/fixtures/symbol_keys.yml

@@ -0,0 +1,6 @@
+# Symbols as environment keys are not allowed.
+:default:
+  setting_1: 'setting 1'
+
+:development:
+  setting_2: 'setting 2'

data/spec/spec_readme_examples.rb

@@ -0,0 +1,13 @@
+describe 'README Examples' do
+
+  should 'load database settings' do
+    yaml = File.join(File.dirname(__FILE__), "fixtures", "example_database.yml")
+
+    settings = YAMLSettings.new(yaml, :production)
+    settings.db.host.should == "db.example.com"
+    settings.db.user.should == "dbusr"
+    settings.db.name.should == "myapp"
+    settings.db.pass.should == "/var/www/sites/myapp/db-access"
+  end
+
+end

data/spec/spec_yaml_settings.rb

@@ -0,0 +1,167 @@
+require 'yaml_settings'
+
+describe YAMLSettings do
+
+  def fixture name
+    File.join(File.dirname(__FILE__), "fixtures", "#{name}.yml")
+  end
+
+  ys = YAMLSettings.new(fixture(:default), :test)
+
+  should 'load and merge multiple YAML files' do
+    p = YAMLSettings.new(
+      fixture(:default),
+      fixture(:private),
+      :production
+    )
+    p.a.  should == 'production a [private]'
+    p.k.a.should == 'production k.a'
+    p.k.b.should == 'production k.b [private]'
+    p.k.c.should == 'production k.c [private]'
+    p.k.d.should == 'default k.d'
+  end
+
+  should 'allow either a string or symbol for environment parameter' do
+    str = YAMLSettings.new(fixture(:default), 'development')
+    sym = YAMLSettings.new(fixture(:default), :development)
+    str.a.should == 'development a'
+    sym.a.should == 'development a'
+  end
+
+  should 'allow only string environment keys in YAML files' do
+    should.raise(KeyError) {
+      YAMLSettings.new(fixture(:symbol_keys), :development)
+    }.message.should.equal 'key not found: "default"'
+  end
+
+  should 'allow just a "default" stanza in YAML file' do
+    default = YAMLSettings.new(fixture(:default_only), :default)
+    default.setting_1.should.equal 'setting 1'
+  end
+
+  should 'raise if "default" stanza does not exist' do
+    should.raise(KeyError) {
+      YAMLSettings.new(fixture(:default_missing), :development)
+    }.message.should.equal 'key not found: "default"'
+  end
+
+  should 'raise if specified environment does not exist' do
+    should.raise(KeyError) {  # single file
+      YAMLSettings.new(fixture(:default), "nonexistent")
+    }.message.should.equal 'key not found: "nonexistent"'
+
+    should.raise(KeyError) {  # multiple files
+      YAMLSettings.new(fixture(:default_only),
+                       fixture(:default),
+                       fixture(:private),
+                       "nonexistent")
+    }.message.should.equal 'key not found: "nonexistent"'
+  end
+
+  should 'delegate to a Hash object' do
+    [:hash, :key, :keys, :each_value, :merge, :rehash].each do |hash_method|
+      ys.public_methods.should.include? hash_method
+    end
+    ys.__getobj__.class.should.equal Hash
+  end
+
+  should 'act like a Hash' do
+    ys.keys.should == # "b" not in default
+      ["a", "c", "d", "e", "f", "g", :h, "i", "j", "k", "l", "m", "b"]
+    ys.values.count.should == 13
+    ys['a'].should == 'test a'
+  end
+
+  should 'allow method call for symbol keys' do
+    ys.h.should == ys[:h]
+  end
+
+  should 'raise when accessing nonexistent settings via method call' do
+    [ -> { ys.    mia_setting },  # TOP level
+      -> { ys.b.  mia_setting },  # 2nd level
+      -> { ys.c.a.mia_setting },  # 3rd level
+      -> { ys.i.  mia_setting },  # 2nd level from default
+      -> { ys.j.a.mia_setting }   # 3nd level from default
+    ].each do |setting|
+      should.raise(KeyError) { setting.call }.
+        message.should.equal 'key not found: "mia_setting"'
+    end
+  end
+
+  should 'not raise when accessing nonexistent settings via hash bracket' do
+    [ -> { ys['mia_setting'] },
+      -> { ys.d['mia_setting'] }
+    ].each do |setting|
+      should.not.raise { setting.call }
+      setting.call.should.equal nil
+    end
+  end
+  
+  should 'return non-default setting from each environment' do
+    %w(development production test).each do |env|
+      YAMLSettings.new(fixture(:default), env).a.should == env+' a'
+    end
+  end
+
+  should 'return settings using hash bracket or method call at any level' do
+    i = 'test e.a.b'
+    ys['e']['a']['b'].should == i  # 000
+    ys['e']['a'] .b  .should == i  # 001
+    ys['e'] .a[  'b'].should == i  # 010
+    ys['e'] .a   .b  .should == i  # 011
+    ys .e[  'a']['b'].should == i  # 100
+    ys .e[  'a'] .b  .should == i  # 101
+    ys .e   .a[  'b'].should == i  # 110
+    ys .e   .a   .b  .should == i  # 111
+  end
+
+  should 'return default string settings at multiple levels' do
+    ys.c.a.b.should == 'default c.a.b'
+    ys.c.b.  should == 'default c.b'
+    ys.d.a.  should == 'default d.a'
+    ys.e.b.a.should == 'default e.b.a'
+  end
+
+  should 'return non-defualt string settings at multiple levels' do
+    ys.a.    should == 'test a'
+    ys.b.a.  should == 'test b.a'
+    ys.b.b.  should == 'test b.b'
+    ys.c.a.a.should == 'test c.a.a'
+    ys.c.c.  should == 'test c.c'
+    ys.d.b.  should == 'test d.b'
+    ys.e.a.a.should == 'test e.a.a'
+    ys.e.a.b.should == 'test e.a.b'
+    ys.e.b.b.should == 'test e.b.b'
+  end
+
+  should 'only override hash values for duplicate keys' do
+    ys.k.a.should == 'test k.a'
+    ys.k.b.should == 'test k.b'
+    ys.k.c.should == 'test k.c'
+    ys.k.d.should == 'default k.d'
+    ys.k.e.should == 'test k.e'
+  end
+
+  should 'override default hash with string value' do
+    ys.l.should == 'test l'
+    should.raise(NoMethodError) { ys.l.a }  # no access to default hash
+  end 
+
+  should 'override default string value with hash' do
+    ys.m.class.should.equal Hash
+    ys.m.keys.count.should == 1
+  end 
+
+  should 'return default array setting' do
+    ys.f[0].should == 'default 0'
+    ys.f[1].should == 'default 1'
+  end
+
+  should 'return non-default array setting' do
+    ys.g[0].should == 'test 0'
+    ys.g[1].should == 'test 1'
+    ys.g[2].should.be.nil     # unlike hash, duplicate indexes not preserved
+    ys.g.size.should == 2
+  end
+
+end

data/yaml_settings.gemspec

@@ -0,0 +1,29 @@
+Gem::Specification.new do |s|
+  s.name        = 'yaml_settings'
+  s.version     = File.read('lib/yaml_settings.rb')[/VERSION = '(.*)'/, 1]
+  s.author      = 'Clint Pachl'
+  s.email       = 'pachl@ecentryx.com'
+  s.homepage    = 'https://ecentryx.com/gems/yaml_settings'
+  s.license     = 'ISC'
+  s.summary     = 'Load and merge application settings from YAML files'
+  s.description = <<-EOS
+YAMLSettings loads and recursively merges settings from one or more YAML data
+files. A settings group—specified by key (e.g., environment variable)—is merged
+with any default settings to create a coherent hash of settings.
+  EOS
+  s.files = Dir[
+    'Rakefile',
+    'README*',
+    '*.gemspec',
+    'lib/*.rb',
+    'spec/**/*',
+    '.rdoc_options'
+  ]
+  s.extra_rdoc_files = ['README.rdoc']
+  s.rdoc_options = [
+    '--title', "YAMLSettings Ruby Gem: #{s.summary}",
+    '--main', 'README.rdoc'
+  ]
+  s.required_ruby_version = '>= 2.2'
+  s.add_development_dependency 'bacon', '~> 1.2'
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: yaml_settings
+version: !ruby/object:Gem::Version
+  version: 1.0.6
+platform: ruby
+authors:
+- Clint Pachl
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-06-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bacon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: |
+  YAMLSettings loads and recursively merges settings from one or more YAML data
+  files. A settings group—specified by key (e.g., environment variable)—is merged
+  with any default settings to create a coherent hash of settings.
+email: pachl@ecentryx.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.rdoc
+files:
+- ".rdoc_options"
+- README.rdoc
+- Rakefile
+- lib/yaml_settings.rb
+- spec/fixtures/default.yml
+- spec/fixtures/default_missing.yml
+- spec/fixtures/default_only.yml
+- spec/fixtures/example_database.yml
+- spec/fixtures/private.yml
+- spec/fixtures/symbol_keys.yml
+- spec/spec_readme_examples.rb
+- spec/spec_yaml_settings.rb
+- yaml_settings.gemspec
+homepage: https://ecentryx.com/gems/yaml_settings
+licenses:
+- ISC
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--title"
+- 'YAMLSettings Ruby Gem: Load and merge application settings from YAML files'
+- "--main"
+- README.rdoc
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.12
+signing_key: 
+specification_version: 4
+summary: Load and merge application settings from YAML files
+test_files: []