better_settings 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 838170a01ea177f40b02a01a7e7308c6b1cf6528
+  data.tar.gz: 94ddb23c277b6ae2ba9c9eb12cfab77635163d87
+SHA512:
+  metadata.gz: 0241b28bfe8bdc7d143c21dbf7526b88142bae2e958c4a9c85a8369ff14c390383a3db14abff98122fc7e2593384d2b0ca3b52fc6a3471700476f9eba173c161
+  data.tar.gz: 254487a597d7e78ca6569d2df82634c48551dfa2715a49533d29bfcd11ade1472df41eebf5cc5d7661fa3a1ba5dfd6610759e21663dc3b8da2ffa03e3aa68f41

data/README.md

@@ -0,0 +1,137 @@
+BetterSettings [![Gem Version](https://img.shields.io/gem/v/better_settings.svg?colorB=e9573f)](https://rubygems.org/gems/better_settings) [![Build Status](https://travis-ci.org/ElMassimo/better_settings.svg)](https://travis-ci.org/ElMassimo/better_settings) [![Coverage Status](https://coveralls.io/repos/github/ElMassimo/better_settings/badge.svg?branch=master)](https://coveralls.io/github/ElMassimo/better_settings?branch=master) [![Inline docs](http://inch-ci.org/github/ElMassimo/better_settings.svg)](http://inch-ci.org/github/ElMassimo/better_settings) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/ElMassimo/better_settings/blob/master/LICENSE.txt)
+=======================================
+
+A robust settings library that can read YML files and provide an immutable object allowing to access settings through method calls. Can be used in __any Ruby app__, __not just Rails__.
+
+### Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'better_settings'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install better_settings
+
+### Usage
+
+#### 1. Define a class
+
+Instead of defining a Settings constant for you, that task is left to you. Simply create a class in your application
+that looks like:
+
+```ruby
+# app/models/settings.rb
+class Settings < BetterSettings
+  source Rails.root.join('config', 'application.yml'), namespace: Rails.env
+end
+```
+
+#### 2. Create your settings
+
+Notice above we specified an absolute path to our settings file called `application.yml`. This is just a typical YAML file.
+Also notice above that we specified a namespace for our environment. A namespace is just an optional string that corresponds to a key in the YAML file.
+
+Using a namespace allows us to change our configuration depending on our environment:
+
+```yaml
+# config/application.yml
+defaults: &defaults
+  port: 80
+  mailer:
+    root: www.example.com
+  dynamic: <%= "Did you know you can use ERB inside the YML file? Env is #{ Rails.env }." %>
+
+development:
+  <<: *defaults
+  port: 3000
+
+test:
+  <<: *defaults
+
+production:
+  <<: *defaults
+```
+
+#### 3. Access your settings
+
+  >> Rails.env
+  => "development"
+
+  >> Settings.mailer
+  => "#<Settings ... >"
+
+  >> Settings.mailer.root
+  => "www.example.com
+
+  >> Settings.port
+  => 3000
+
+  >> Settings.dynamic
+  => "Did you know you can use ERB inside the YML file? Env is development."
+
+You can use these settings anywhere, for example in a model:
+
+  class Post < ActiveRecord::Base
+    self.per_page = Settings.pagination.posts_per_page
+  end
+
+### Advanced Setup ⚙
+Name it `Settings`, name it `Config`, name it whatever you want. Add as many or as few as you like, read from as many files as necessary (nested keys will be merged).
+
+We usually read a few optional files for the `development` and `test` environment, which allows each developer to override some settings in their own local environment (we git ignore `development.yml` and `test.yml`).
+
+```ruby
+# app/models/settings.rb
+class Settings < BetterSettings
+  source Rails.root.join('config', 'application.yml'), namespace: Rails.env
+  source Rails.root.join('config', 'development.yml'), namespace: Rails.env, optional: true if Rails.env.development?
+  source Rails.root.join('config', 'test.yml'), namespace: Rails.env, optional: true if Rails.env.test?
+end
+```
+Our `application.yml` looks like this:
+```yaml
+# application.yml
+defaults: &defaults
+  auto_logout: false
+  secret_key_base: 'fake_secret_key_base'
+
+server_defaults: &server_defaults
+  <<: *defaults
+  auto_logout: true
+  secret_key: <%= ENV['SECRET_KEY'] %>
+
+development:
+  <<: *defaults
+  host: 'localhost'
+
+test:
+  <<: *defaults
+  host: '127.0.0.1'
+
+staging:
+  <<: *server_defaults
+  host: 'staging.example.com'
+
+production:
+  <<: *server_defaults
+  host: 'example.com'
+```
+A developer might want to override some settings by defining a `development.yml` such as:
+```yaml
+development:
+  auto_logout: true
+````
+The main advantage is that those changes won't be tracked by source control :smiley:
+
+## Opinionated Design
+After using [settingslogic](https://github.com/settingslogic/settingslogic) for a long time, we learned some lessons, which are distilled in the following decisions:
+- __Immutability:__ Once created settings can't be modified.
+- __No Optional Setings:__ Any optional setting can be modeled in a safer way, this library doesn't allow them.
+- __Not Tied to a Source File:__ Useful to create multiple environment-specific files.

data/lib/better_settings.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'erb'
+require 'open-uri'
+require 'forwardable'
+
+# Public: Rewrite of BetterSettings to enforce fail-fast and immutability, and
+# avoid extending a core class like Hash which can be problematic.
+class BetterSettings
+  extend Forwardable
+
+  VALID_SETTING_NAME = /^\w+$/
+  RESERVED_METHODS = %w[
+    settings
+    root_settings
+  ]
+
+  attr_reader :settings
+  def_delegators :settings, :to_h, :to_hash
+
+  # Public: Initializes a new settings object from a Hash or compatible object.
+  def initialize(hash, parent:)
+    @settings = hash.to_h.freeze
+    @parent = parent
+
+    # Create a getter method for each setting.
+    @settings.each { |key, value| create_accessor(key, value) }
+  end
+
+  # Internal: Returns a new Better Settings instance that combines the settings.
+  def merge(other_settings)
+    self.class.new(deep_merge(@settings, other_settings.to_h), parent: @parent)
+  end
+
+  # Internal: Display explicit errors for typos and missing settings.
+  # rubocop:disable Style/MethodMissing
+  def method_missing(name, *)
+    raise MissingSetting, "Missing setting '#{ name }' in #{ @parent }"
+  end
+
+private
+
+  # Internal: Wrap nested hashes as settings to allow accessing keys as methods.
+  def auto_wrap(key, value)
+    case value
+    when Hash then self.class.new(value, parent: "'#{ key }' section in #{ @parent }")
+    when Array then value.map { |item| auto_wrap(key, item) }.freeze
+    else value.freeze
+    end
+  end
+
+  # Internal: Defines a getter for the specified setting.
+  def create_accessor(key, value)
+    raise InvalidSettingKey if !key.is_a?(String) || key !~ VALID_SETTING_NAME || RESERVED_METHODS.include?(key)
+    instance_variable_set("@#{ key }", auto_wrap(key, value))
+    singleton_class.send(:attr_reader, key)
+  end
+
+  # Internal: Recursively merges two hashes (in case ActiveSupport is not available).
+  def deep_merge(this_hash, other_hash)
+    this_hash.merge(other_hash) do |key, this_val, other_val|
+      if this_val.is_a?(Hash) && other_val.is_a?(Hash)
+        deep_merge(this_val, other_val)
+      else
+        other_val
+      end
+    end
+  end
+
+  class MissingSetting < StandardError; end
+  class InvalidSettingKey < StandardError; end
+
+  class << self
+    extend Forwardable
+    def_delegators :root_settings, :to_h, :to_hash, :method_missing
+
+    # Public: Loads a file as settings (merges it with any previously loaded settings).
+    def source(file_name, namespace: false, optional: false)
+      return if !File.exist?(file_name) && optional
+
+      # Load the specified yaml file and instantiate a Settings object.
+      settings = new(yaml_to_hash(file_name), parent: file_name)
+
+      # Take one of the settings keys if one is specified.
+      settings = settings.public_send(namespace) if namespace
+
+      # Merge settings if a source had previously been specified.
+      @root_settings = @root_settings ? @root_settings.merge(settings) : settings
+
+      # Allow to call any settings methods directly on the class.
+      singleton_class.extend(Forwardable)
+      singleton_class.def_delegators :root_settings, *@root_settings.settings.keys
+    end
+
+  private
+
+    # Internal: Methods called at the class level are delegated to this instance.
+    def root_settings
+      raise ArgumentError, '`source` must be specified for the settings' unless defined?(@root_settings)
+      @root_settings
+    end
+
+    # Internal: Parses a yml file that can optionally use ERB templating.
+    def yaml_to_hash(file_name)
+      return {} if (content = open(file_name).read).empty?
+      YAML.load(ERB.new(content).result).to_hash
+    end
+  end
+end

data/lib/better_settings/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class BetterSettings
+  VERSION = '1.0.0'
+end

data/spec/better_settings/better_settings_spec.rb

@@ -0,0 +1,126 @@
+require 'spec_helper'
+require 'support/settings'
+
+describe BetterSettings do
+  def new_settings(value)
+    Settings.new(value, parent: 'new_settings')
+  end
+
+  it 'should access settings' do
+    expect(Settings.setting2).to eq 5
+  end
+
+  it 'should access nested settings' do
+    expect(Settings.setting1.setting1_child).to eq 'saweet'
+  end
+
+  it 'should access settings in nested arrays' do
+    expect(Settings.array.first.name).to eq 'first'
+  end
+
+  it 'should access deep nested settings' do
+    expect(Settings.setting1.deep.another).to eq 'my value'
+  end
+
+  it 'should access extra deep nested settings' do
+    expect(Settings.setting1.deep.child.value).to eq 2
+  end
+
+  it 'should enable erb' do
+    expect(Settings.setting3).to eq 25
+  end
+
+  it 'should namespace settings' do
+    expect(DevSettings.language.haskell.paradigm).to eq 'functional'
+    expect(DevSettings.language.smalltalk.paradigm).to eq 'object-oriented'
+    expect(DevSettings.environment).to eq 'development'
+  end
+
+  it 'should distinguish nested keys' do
+    expect(Settings.language.haskell.paradigm).to eq 'functional'
+    expect(Settings.language.smalltalk.paradigm).to eq 'object oriented'
+  end
+
+  it 'should not override global methods' do
+    expect(Settings.global).to eq 'GLOBAL'
+    expect(Settings.custom).to eq 'CUSTOM'
+  end
+
+  it 'should raise a helpful error message' do
+    expect {
+      Settings.missing
+    }.to raise_error(BetterSettings::MissingSetting, /Missing setting 'missing' in/)
+    expect {
+      Settings.language.missing
+    }.to raise_error(BetterSettings::MissingSetting, /Missing setting 'missing' in 'language' section/)
+  end
+
+  it 'should raise an error on a nil source argument' do
+    expect { NoSource.foo.bar }.to raise_error(ArgumentError, '`source` must be specified for the settings')
+  end
+
+  it 'should support instance usage as well' do
+    expect(new_settings(Settings.setting1).setting1_child).to eq 'saweet'
+  end
+
+  it 'should handle invalid name settings' do
+    expect {
+      new_settings('some-dash-setting#' => 'dashtastic')
+    }.to raise_error(BetterSettings::InvalidSettingKey)
+  end
+
+  it 'should handle settings with nil value' do
+    expect(Settings.nil).to eq nil
+  end
+
+  it 'should handle settings with false value' do
+    expect(Settings.false).to eq false
+  end
+
+  # If .name is called on BetterSettings itself, handle appropriately
+  # by delegating to Hash
+  it 'should have the parent class always respond with Module.name' do
+    expect(BetterSettings.name).to eq 'BetterSettings'
+  end
+
+  # If .name is not a property, delegate to superclass
+  it 'should respond with Module.name' do
+    expect(DevSettings.name).to eq 'DevSettings'
+  end
+
+  # If .name is a property, respond with that instead of delegating to superclass
+  it 'should allow a name setting to be overriden' do
+    expect(Settings.name).to eq 'test'
+  end
+
+  describe 'to_h' do
+    it 'should handle empty file' do
+      expect(NoSettings.to_h).to be_empty
+    end
+
+    it 'should be similar to the internal representation' do
+      expect(settings = Settings.send(:root_settings)).to be_is_a(Settings)
+      expect(hash = settings.send(:settings)).to be_is_a(Hash)
+      expect(Settings.to_h).to eq hash
+    end
+
+    it 'should not mutate the original when getting a copy' do
+      result = Settings.language.to_h.merge('haskell' => 'awesome')
+      expect(result.class).to eq Hash
+      expect(result).to eq(
+        'haskell' => 'awesome',
+        'smalltalk' => { 'paradigm' => 'object oriented' },
+      )
+      expect(Settings.language.haskell.paradigm).to eq('functional')
+      expect(Settings.language).not_to eq Settings.language.merge('paradigm' => 'functional')
+    end
+  end
+
+  describe '#to_hash' do
+    it 'should return a new instance of a Hash object' do
+      expect(Settings.to_hash).to be_kind_of(Hash)
+      expect(Settings.to_hash.class.name).to eq 'Hash'
+      expect(Settings.to_hash.object_id).not_to eq Settings.object_id
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'simplecov'
+require 'coveralls'
+SimpleCov.start { add_filter '/spec/' }
+Coveralls.wear!
+
+require 'better_settings'
+require 'rspec/given'
+require 'pry-byebug'

data/spec/support/settings.rb

@@ -0,0 +1,25 @@
+class Settings < BetterSettings
+  source "#{ File.dirname(__FILE__) }/settings.yml"
+  source "#{File.dirname(__FILE__)}/settings_empty.yml"
+
+  def self.custom
+    'CUSTOM'
+  end
+
+  def self.global
+    'GLOBAL'
+  end
+end
+
+class DevSettings < BetterSettings
+  source "#{ File.dirname(__FILE__) }/settings.yml", namespace: :development
+  source "#{ File.dirname(__FILE__) }/dev.yml", namespace: 'development'
+end
+
+class NoSettings < BetterSettings
+  source "#{File.dirname(__FILE__)}/settings_empty.yml", optional: true
+  source "#{File.dirname(__FILE__)}/settings_none.yml", optional: true
+end
+
+class NoSource < BetterSettings
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: better_settings
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Máximo Mussini
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-12-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-given
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Settings solution for Rails applications that can read YAML files (ERB-enabled)
+  and allows to access using method calls.
+email:
+- maximomussini@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/better_settings.rb
+- lib/better_settings/version.rb
+- spec/better_settings/better_settings_spec.rb
+- spec/spec_helper.rb
+- spec/support/settings.rb
+homepage: https://github.com/ElMassimo/better_settings
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+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.11
+signing_key: 
+specification_version: 4
+summary: 'Settings for Rails applications: simple, immutable, better.'
+test_files:
+- spec/better_settings/better_settings_spec.rb
+- spec/spec_helper.rb
+- spec/support/settings.rb