configurate 0.1.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b1c77311fcc9be9b8545a349cb8a9352fac266ba
-  data.tar.gz: 23cc86a4bc3e0edad45c756eb77a27a97628cb3c
+SHA256:
+  metadata.gz: 5917dff879c04bd7e35104f02ed093e0ade7628503b70eaa9ba9f988250ce89d
+  data.tar.gz: 0ac06ee31c43264bac9001e7dad1c4fa18e9116dd02adfd325f21281d65ac2a1
 SHA512:
-  metadata.gz: 0f9b04ce701034847ce8d337093a692bae175e75c8b68b30de0260bfe20520350f6d0112a0423df972d564321b23b4a91a35160d1186899fef1c3d2f61f64388
-  data.tar.gz: f48dbe835f2cb4b2102d8090a1b030612b19f52a7b2b23d517eb6cbc7bc748304a6cac4a1a6826eb90367ad77e73e783735b7bb9be02901766c8a5ea1680bf43
+  metadata.gz: eaf82b6d8a397b3473bf4abc11722a7fb43f98981ee25142786a37c7ba46c1d847324a43f6950ad8997b7fd6db1186d3cd0e7d9a554b28e4f3a5d07b742075bb
+  data.tar.gz: 28022b6871d3282a5c8283b701bc9a45b1e2519470cb4762e9cb0d4a1875c86c5d16648c8eead096bc0da0da4cc09d477b2c27ef398b9b8c55c0638a4c245b6c

data/Changelog.md

@@ -1,3 +1,33 @@
+# 0.5.0
+
+* Support and prefer `toml-rb` over `tomlrb` in the shipped TOML provider.
+* Drop explicit support for Ruby < 2.4
+
+# 0.4.0
+
+* `Configurate::Proxy` returns its own singleton class if the target does not support creating one.
+* Extract `Configurate::Provider::StringHash` as a new base class for hash based providers.
+* Add `Configurate::Provider::TOML`.
+
+# 0.3.1
+
+* Configurate::Provider::Dynamic returns true when passed the special
+ `reset_dynamic!` call.
+
+# 0.3.0
+
+* Add new exception: Configurate::MissingSetting to be raised and bubble up to the user
+  if a setting wasn't found and the user requested to be informed.
+* Configurate::Provider::YAML got the new option raise_on_missing to raise
+  Configurate::MissingSetting if the requested key is not in the YAML document.
+
+# 0.2.0
+
+* Dynamic provider listens to reset_dynamic! message and forgets all settings on it.
+* Calls ending in ! call the providers directly.
+* Added SettingPath#action?, remove is_ prefix from SettingPath methods.
+* Add implicit converters to Proxy that call the explicit converters.
+
 # 0.1.0
 
 * Dynamic provider resolves nested assignments

data/README.md

@@ -1,9 +1,8 @@
 # Configurate - A flexible configuration system
-[![Gem Version](https://badge.fury.io/rb/configurate.png)](https://rubygems.org/gems/configurate)
-[![Build Status](https://secure.travis-ci.org/jhass/configurate.png?branch=master)](https://travis-ci.org/jhass/configurate)
-[![Gemnasium](https://gemnasium.com/MrZYX/configurate.png)](https://gemnasium.com/MrZYX/configurate)
-[![Code Climate](https://codeclimate.com/github/jhass/configurate.png)](https://codeclimate.com/github/MrZYX/configurate)
-[![Coverage Status](https://coveralls.io/repos/jhass/configurate/badge.png?branch=master)](https://coveralls.io/r/MrZYX/configurate)
+[![Gem Version](https://badge.fury.io/rb/configurate.svg)](https://badge.fury.io/rb/configurate)
+[![Build Status](https://travis-ci.org/jhass/configurate.svg?branch=master)](https://travis-ci.org/jhass/configurate)
+[![Code Climate](https://codeclimate.com/github/jhass/configurate.svg)](https://codeclimate.com/github/jhass/configurate)
+[![Coverage Status](https://coveralls.io/repos/jhass/configurate/badge.svg?branch=master)](https://coveralls.io/r/jhass/configurate?branch=master)
 
 Configurate allows you to specify a chain of configuration providers which are
 queried in order until one returns a value. This allows scenarios like overriding
@@ -11,7 +10,7 @@ your default settings with a user configuration file and let those be overridden
 by environment variables. The query interface allows to group and nest your configuration options
 to a practically unlimited level.
 
-Configurate works with Ruby 1.9.2 or later.
+Configurate supports Ruby 2.0 or later.
 
 ## Installation
 
@@ -80,7 +79,7 @@ Ruby does not allow to metaprogram `false`, thus something like
 puts "yep" if Config.enable_stuff
 ```
 
-always outputs `yep`. The workaround is to append `.get` or `?` to get the
+always outputs `yep`. The workaround is to append `.get`, or `?` to get the
 real value:
 
 ```ruby
@@ -107,14 +106,6 @@ will always output `unknown`. Again use `.get`
 
 ## Shipped providers
 
-### Configurate::Provider::Base
-
-A convenience base class changing the interface for implementers. It provides a basic `#lookup` method
-which just passes all parameters through to `#lookup_path`.
-The result of `#lookup_path` is returned, unless it's `nil`
-then `Configurate::SettingNotFoundError` is raised. Subclasses are expected to implement `#lookup_path`.
-Do not use this class directly as a provider!
-
 ### Configurate::Provider::Env
 
 This class transforms a query string into a name for a environment variable and looks up this variable then.
@@ -124,6 +115,40 @@ into arrays.
 
 This provider does not take any additional initialization parameters.
 
+### Configurate::Provider::TOML
+
+This provider reads settings from a given [TOML](https://github.com/toml-lang/toml) file. It converts the sections of
+query string to a nested value. For a given TOML file
+
+```toml
+[stuff]
+enable = true
+param = "foo"
+
+[stuff.nested]
+param = "bar"
+```
+
+the following queries would be valid:
+
+```ruby
+Config.stuff.enable?      # => true
+Config.stuff.param        # => "foo"
+Config.stuff.nested.param # => "bar"
+```
+
+This provider depends on the [toml-rb](https://github.com/emancu/toml-rb) or the [tomlrb](https://github.com/fbernier/tomlrb) gem.
+This is why it is not loaded by default and needs an explicit `require 'configurate/provider/toml'` to be available. If both are available, toml-rb is preferred.
+
+The initializer takes a path to the configuration file a the mandatory first argument and
+the following optional parameters:
+
+* *namespace:* Specify a alternative root. This is useful if you for example add the same file multiple
+  times through multiple providers, with different namespaces, letting you override settings depending on
+  the rails environment, without duplicating common settings. Defaults to none.
+* *required:* Whether to raise an error if the the file isn't found or, if one is given, the namespace
+  doesn't exist in the file.
+
 ### Configurate::Provider::YAML
 
 This provider reads settings from a given [YAML](http://www.yaml.org) file. It converts the sections of
@@ -145,8 +170,8 @@ Config.stuff.param        # => "foo"
 Config.stuff.nested.param # => "bar"
 ```
 
-The initializer takes a path to the configuration file as mandatory first argument and
-the following optional parameters, as a hash:
+The initializer takes a path to the configuration file a the mandatory first argument and
+the following optional parameters:
 
 * *namespace:* Specify a alternative root. This is useful if you for example add the same file multiple
   times through multiple providers, with different namespaces, letting you override settings depending on
@@ -154,18 +179,67 @@ the following optional parameters, as a hash:
 * *required:* Whether to raise an error if the the file isn't found or, if one is given, the namespace
   doesn't exist in the file.
 
+
+### Configurate::Provider::StringHash
+
+A provider taking a (nested) `Hash` where all keys are strings. The query string is then looked up in this hash.
+
+So for a given `Hash`
+
+```ruby
+{
+  "stuff" => {
+    "enable" => true,
+    "param" => "foo",
+    "nested" => {
+      "param" => "bar"
+    }
+  }
+}
+```
+
+the following queries would be valid:
+
+```ruby
+Config.stuff.enable?      # => true
+Config.stuff.param        # => "foo"
+Config.stuff.nested.param # => "bar"
+```
+
+The initializer takes the hash as the mandatory first argument and
+the following optional parameters:
+
+* *namespace:* Specify a alternative root. This is useful if you for example add the same file multiple
+  times through multiple providers, with different namespaces, letting you override settings depending on
+  the rails environment, without duplicating common settings. Defaults to none.
+* *required:* Whether to raise an error if the namespace
+  doesn't exist in the hash.
+* *source:* A hint text about the origin of the configuration data to be used in error messages.
+
+As you may have noticed by now, `Configurate::Provider::YAML` and `Configurate::Provider::TOML` are merely convenience
+subclasses of this provider, loading the file for you.
+
 ### Configurate::Provider::Dynamic
 
-A provider which stores the first additonal parameter if the query string ends with an equal sign and can
-return it later. This is mainly useful for testing but can be useful to temporarily overide stuff
-too. To clarify a small example:
+A provider which stores the first additional parameter if the query string ends with an equal sign and can
+return it later. This is mainly useful for testing but can be useful to temporarily override stuff too. To clarify a small example:
 
 ```ruby
 Config.foo.bar         # => nil
 Config.foo.bar = "baz"
 Config.foo.bar         # => "baz"
+Config.reset_dynamic!
+Config.foo.bar         # => nil
 ```
 
+### Configurate::Provider::Base
+
+A convenience base class changing the interface for implementers. It provides a basic `#lookup` method
+which just passes all parameters through to `#lookup_path`.
+The result of `#lookup_path` is returned, unless it's `nil`
+then `Configurate::SettingNotFoundError` is raised. Subclasses are expected to implement `#lookup_path`.
+Do not use this class directly as a provider!
+
 ## Writing a provider
 
 ...should be pretty easy. For example here is the `Configurate::Provider::Env` provider:
@@ -183,6 +257,8 @@ class Configurate::Provider::Env < Configurate::Provider::Base
 end
 ```
 
+`Configurate::Provider::StringHash` should also serve as a useful baseclass for most providers.
+
 
 ## Documentation
 

data/lib/configurate.rb

@@ -1,10 +1,11 @@
-require 'forwardable'
+# frozen_string_literal: true
 
-require 'configurate/setting_path'
-require 'configurate/lookup_chain'
-require 'configurate/provider'
-require 'configurate/proxy'
+require "forwardable"
 
+require "configurate/setting_path"
+require "configurate/lookup_chain"
+require "configurate/provider"
+require "configurate/proxy"
 
 # A flexible and extendable configuration system.
 # The calling logic is isolated from the lookup logic
@@ -20,15 +21,15 @@ require 'configurate/proxy'
 module Configurate
   # This is your main entry point. Instead of lengthy explanations
   # let an example demonstrate its usage:
-  # 
+  #
   #     require 'configuration_methods'
-  #     
+  #
   #     AppSettings = Configurate::Settings.create do
   #       add_provider Configurate::Provider::Env
   #       add_provider Configurate::Provider::YAML, '/etc/app_settings.yml',
   #                    namespace: Rails.env, required: false
   #       add_provider Configurate::Provider::YAML, 'config/default_settings.yml'
-  #       
+  #
   #       extend YourConfigurationMethods
   #     end
   #
@@ -36,18 +37,17 @@ module Configurate
   #
   # Please also read the note at {Proxy}!
   class Settings
-  
     attr_reader :lookup_chain
-    
+
     undef_method :method # Remove possible conflicts with common setting names
 
     extend Forwardable
 
     def initialize
       @lookup_chain = LookupChain.new
-      $stderr.puts "Warning you called Configurate::Settings.new with a block, you really meant to call #create" if block_given?
+      warn "Warning you called Configurate::Settings.new with a block, you really meant to call #create" if block_given?
     end
-    
+
     # @!method lookup(setting)
     # (see {LookupChain#lookup})
 
@@ -59,19 +59,30 @@ module Configurate
 
     def_delegators :@lookup_chain, :lookup, :add_provider, :[]
 
+    # rubocop:disable Style/MethodMissingSuper we handle all calls
+    # rubocop:disable Style/MissingRespondToMissing we override respond_to? instead
+
     # See description and {#lookup}, {#[]} and {#add_provider}
     def method_missing(method, *args, &block)
       Proxy.new(@lookup_chain).public_send(method, *args, &block)
     end
-    
+    # rubocop:enable all
+
     # Create a new configuration object
     # @yield the given block will be evaluated in the context of the new object
     def self.create(&block)
-      config = self.new
+      config = new
       config.instance_eval(&block) if block_given?
       config
     end
   end
-  
+
+  # This is supposed to be raised by providers if the requested setting
+  # does not exist, (remember, nil is a valid value and thus rarely a sufficient check)
+  # and this should be communicated to the end user.
+  class MissingSetting < RuntimeError; end
+
+  # This is supposed to be raised by providers if the requested setting
+  # cannot be found and the next provider in the chain should be tried.
   class SettingNotFoundError < RuntimeError; end
 end

data/lib/configurate/lookup_chain.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Configurate
   # This object builds a chain of configuration providers to try to find
   # the value of a setting.
@@ -5,7 +7,7 @@ module Configurate
     def initialize
       @provider = []
     end
-    
+
     # Adds a provider to the chain. Providers are tried in the order
     # they are added, so the order is important.
     #
@@ -17,11 +19,10 @@ module Configurate
       unless provider.respond_to?(:instance_methods) && provider.instance_methods.include?(:lookup)
         raise ArgumentError, "the given provider does not respond to lookup"
       end
-      
+
       @provider << provider.new(*args)
     end
-    
-    
+
     # Tries all providers in the order they were added to provide a response
     # for setting.
     #
@@ -37,27 +38,28 @@ module Configurate
           return special_value_or_string(provider.lookup(setting.clone, *args))
         rescue SettingNotFoundError; end
       end
-      
+
       nil
     end
     alias_method :[], :lookup
-    
-    private 
-    
+
+    private
+
     def special_value_or_string(value)
-      if [TrueClass, FalseClass, NilClass, Array, Hash].include?(value.class)
-        return value
-      elsif value.is_a?(String)
-        return case value.strip
+      case value
+      when TrueClass, FalseClass, NilClass, Array, Hash
+        value
+      else
+        if value.respond_to?(:to_s)
+          case value.to_s.strip
           when "true" then true
           when "false" then false
           when "", "nil" then nil
-          else value
+          else value.to_s
+          end
+        else
+          value
         end
-      elsif value.respond_to?(:to_s)
-        return value.to_s
-      else
-        return value
       end
     end
   end

data/lib/configurate/provider.rb

@@ -1,32 +1,39 @@
-module Configurate; module Provider
-  # This provides a basic {#lookup} method for other providers to build
-  # upon. Childs are expected to define +lookup_path(path, *args)+.
-  # The method should return nil if the setting
-  # wasn't found and {#lookup} will raise an {SettingNotFoundError} in that
-  # case.
-  class Base
-    def lookup(*args)
-      result = lookup_path(*args)
-      return result unless result.nil?
-      raise Configurate::SettingNotFoundError, "The setting #{args.first} was not found"
+# frozen_string_literal: true
+
+module Configurate
+  module Provider
+    # This provides a basic {#lookup} method for other providers to build
+    # upon. Childs are expected to define +lookup_path(path, *args)+.
+    # The method should return nil if the setting
+    # wasn't found and {#lookup} will raise an {SettingNotFoundError} in that
+    # case.
+    class Base
+      def lookup(*args)
+        result = lookup_path(*args)
+        return result unless result.nil?
+
+        raise Configurate::SettingNotFoundError, "The setting #{args.first} was not found"
+      end
     end
-  end
 
-  # Utility function to lookup a settings path in a hash
-  # @param setting_path [SettingPath]
-  # @param hash [Hash]
-  # @yield fallback value if not found
-  # @return [Object]
-  def self.lookup_in_hash setting_path, hash, &fallback
-    fallback ||= proc { nil }
-    while hash.is_a?(Hash) && hash.has_key?(setting_path.first) && !setting_path.empty?
-      hash = hash[setting_path.shift]
+    # Utility function to lookup a settings path in a hash
+    # @param setting_path [SettingPath]
+    # @param hash [Hash]
+    # @yield fallback value if not found
+    # @return [Object]
+    def self.lookup_in_hash setting_path, hash, &fallback
+      fallback ||= proc { nil }
+      while hash.is_a?(Hash) && hash.has_key?(setting_path.first) && !setting_path.empty?
+        hash = hash[setting_path.shift]
+      end
+      return fallback.call unless setting_path.empty?
+
+      hash
     end
-    return fallback.call unless setting_path.empty?
-    hash
   end
-end; end
+end
 
-require 'configurate/provider/yaml'
-require 'configurate/provider/env'
-require 'configurate/provider/dynamic'
+require "configurate/provider/string_hash"
+require "configurate/provider/yaml"
+require "configurate/provider/env"
+require "configurate/provider/dynamic"