settingable 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 322c4138d887529b845f3027badc7b35a6031693
-  data.tar.gz: 9f24b8585d437a0b06be1e81c4e2816930d196af
+  metadata.gz: 903821ee3c31b65a77729e2eb36ed6d295f00a4a
+  data.tar.gz: 2bdb5c3ea7c51f10c2e7b6f847859372b81508d8
 SHA512:
-  metadata.gz: 8cec1a8f17952b59f03a0c552aa36efbf571eb40479575c843b015e2ec3d15f6c001f39b533409f204c3d8c20f441568e8aa703aa09b54c0bf0f1e525e441a4a
-  data.tar.gz: 58be6a3f657922814dcb7f0525f5a78e05beb0c07394eb0ed83e333809bef2fcdf0bd17a5f6cb8af87073d7e056cbcad8180fba756cae97b5325aa8eb2d6e465
+  metadata.gz: 972a99a3465daf5cdca3fbb336815b1351d32b2fa46f257304bbcdac6e185aaff902bfd7f601d2d6d6bed0c63cf40b23b8d3351fb9ee47e8667194863bcc03ce
+  data.tar.gz: fe8b359de31ce9452f6489b0970707a38539f5d5dbd1d039913477d9034f1dc5a51de8c7121fc1af70edd66de94d8b580861d4066d6bf737900a46803150da33

data/README.md

@@ -1,27 +1,78 @@
-# settingable
+# settingable [![Build Status](https://travis-ci.org/medcat/settingable.svg)](https://travis-ci.org/medcat/settingable)
 
 * [Homepage](https://rubygems.org/gems/settingable)
 * [Documentation](http://rubydoc.info/gems/settingable/frames)
-* [Email](mailto:redjazz96@gmail.com)
+* [Email](mailto:me@medcat.me)
+
+## Install
+
+    $ gem install settingable
 
 ## Description
 
-TODO: Description
+A Settings module for your application.  Its job is to make handling
+user-definable settings easy for you, so you can focus on the more
+important parts of your library.  The main component of it is the
+`Settingable::Settings` module.  Just include that in a class, and
+you're good to go.
 
-## Features
+```Ruby
+module MyLibrary
+  class Settings
+    include Settingable::Settings
+end
+```
 
-## Examples
+The `Settings` module provides a few methods.  First, it defines the
+`.instance` class method.  This returns a single instance upon
+repeated invocation, like the `Singleton` module.  Then, it defines
+the `.configure` method.  This is used to (*ahem*) configure the
+settings.  It both yields itself and runs it in its context, so you
+may configure it however you like.  It also forwards the methods
+`.[]`, `.[]=`, and `.fetch` on to the actual instance itself as well.
 
-    require 'settingable'
+The instance forwards the `#[]`, `#[]=`, `#fetch`, and `#key?` method
+on to the `Settingable::Hash` powering the settings (see the
+documentation for more).  The instance can also accept any other
+methods.  If the method ends in an equal sign (i.e. a setter method),
+it is forwarded to `#[]=`; otherwise, it is forwarded to `#[]`.
 
-## Requirements
+Here's a few examples.
 
-## Install
+```Ruby
+MyLibrary::Settings.configure do |config|
+  # These two are the same.
+  config.value = 2
+  config[:value] = 2
+end
 
-    $ gem install settingable
+# These all are the same, and return the same value.
+MyLibrary::Settings.value
+MyLibrary::Settings[:value]
+MyLibrary::Settings["value"]
+MyLibrary::Settings.instance.value
+MyLibrary::Settings.instance[:value]
+MyLibrary::Settings.instance["value"]
+```
+
+If you attempt to access a setting value that isn't defined, even if
+you use the regular accessor (`#[]`), a `KeyError` will be raised.
+So, the module provides a `.default_settings` method, for you to
+provide default values for the settings.
+
+```Ruby
+module MyLibrary
+  class Settings
+    include Settingable::Settings
 
-## Copyright
+    default_settings foo: "bar"
+  end
+end
+```
 
-Copyright (c) 2015 Jeremy Rodi
+Now, check it out.
 
-See {file:LICENSE.txt} for details.
+```Ruby
+MyLibrary::Settings[:foo] # => "bar"
+MyLibrary::Settings[:bar] # ! KeyError
+```

data/lib/settingable/hash.rb

@@ -0,0 +1,107 @@
+# encoding: utf-8
+
+module Settingable
+  # A hash that raises an error on an access that fails.
+  class Hash < ::Hash
+    # Initialize the hash.  If a value is passed, the values are set
+    # on this hash.  Does not modify the value.
+    #
+    # @param body [Hash]
+    # @see #convert
+    def initialize(body = {})
+      body.each do |key, value|
+        self[key] = value
+      end
+    end
+
+    alias_method :old_key?, :key?
+
+    # Checks to determine if the given key is set in this hash.  It
+    # first converts the key to a Symbol, then performs the check.
+    #
+    # @param key [String, Symbol, Object]
+    # @return [Boolean]
+    def key?(key)
+      case key
+      when String then super(key.intern)
+      when Symbol then super(key)
+      else             super(key.to_s.intern)
+      end
+    end
+
+    alias_method :old_access, :[]
+    # Accesses the hash.  It raises an error if it can't find the
+    # key.  It attempts to convert the key into a Symbol.
+    #
+    # @param key [String, Symbol, Object] The key.
+    # @return [Object] The value.
+    # @raise KeyError If the key isn't mapped to a value.
+    def [](key)
+      case key
+      when String then fetch(key.intern)
+      when Symbol then fetch(key)
+      else             fetch(key.to_s.intern)
+      end
+    end
+
+    alias_method :old_set, :[]=
+    # Used to set a key to a value.  The key is first converted to a
+    # Symbol, and the value is coerced into a {Hash} if it is a
+    # `::Hash`.
+    #
+    # @param key [String, Symbol, Object]
+    # @param value [Hash, Object]
+    # @return [void]
+    # @see #convert
+    def []=(key, value)
+      case key
+      when String then super(key.intern, convert(value))
+      when Symbol then super(key, convert(value))
+      else             super(key.to_s.intern, convert(value))
+      end
+    end
+
+    # A blank object used as a canary for {#fetch}.
+    #
+    # @api private
+    BLANK_OBJECT = Object.new
+    private_constant :BLANK_OBJECT
+
+    alias_method :old_fetch, :fetch
+    # Performs a fetch.  If the key is in the hash, it returns its
+    # value.  If the key is not in the hash, and a value was passed,
+    # the value is returned.  If the key is not in the hash, and a
+    # block was passed, it yields.  Otherwise, it raises KeyError.
+    #
+    # @param key [Object] The key.
+    # @param value [Object] The default object.
+    # @yield [key]
+    # @return [Object]
+    # @raise KeyError If the key isn't in the hash and no default
+    #   was given.
+    def fetch(key, value = BLANK_OBJECT)
+      case
+      when old_key?(key)         then old_access(key)
+      when block_given?          then yield(key)
+      when value != BLANK_OBJECT then value
+      else
+        fail KeyError, "Key not found: #{key.inspect}"
+      end
+    end
+
+    private
+
+    # Converts the value to a {Settingable::Hash}, if it is a regular
+    # ruby hash.  Otherwise, it returns the value.
+    #
+    # @param value [Hash, Object]
+    # @return [Settingable::Hash, Object]
+    def convert(value)
+      if value.is_a?(::Hash)
+        Settingable::Hash.new(value)
+      else
+        value
+      end
+    end
+  end
+end

data/lib/settingable/settings.rb

@@ -9,15 +9,15 @@ module Settingable
     module ClassMethods
       extend Forwardable
 
-      def_delegators :settings, :[], :[]=, :fetch,
+      def_delegators :instance, :[], :[]=, :fetch,
                      :method_missing
-      def_delegator :settings, :build, :configure
+      def_delegator :instance, :build, :configure
 
       # Returns an instance of the included module.  Repeated calls
       # return the same instance.
       #
       # @return [Settings]
-      def settings
+      def instance
         @_settings ||= new
       end
 
@@ -46,14 +46,14 @@ module Settingable
     end
 
     extend Forwardable
-    def_delegators :@settings, :fetch
+    def_delegators :@settings, :fetch, :[], :[]=, :key?
 
     # Initialize the settings.  Merges the given settings to the default
     # settings.
     #
     # @param settings [Hash] The initial settings.
     def initialize(settings = {})
-      @settings = DeepMerge.deep_merge(self.class.default_settings, settings)
+      @settings = Settingable::Hash.new(merged_settings(settings))
     end
 
     # Builds the settings construct.  It yields itself, and then returns
@@ -66,23 +66,6 @@ module Settingable
       self
     end
 
-    # Sets a key to a value.
-    #
-    # @param key [Symbol, String] The key.
-    # @param value [Object] The value.
-    # @return [void]
-    def []=(key, value)
-      @settings[key.to_s.to_sym] = value
-    end
-
-    # Retrieves a key.  If it doesn't exist, it errors.
-    #
-    # @param key [Symbol, String] The key.
-    # @return [Object]
-    def [](key)
-      @settings.fetch(key.to_s.to_sym)
-    end
-
     # Method missing.  For set methods, it maps to the `:[]=` method; for
     # regular methods (i.e. not bang or ? methods), it maps to the `:[]`
     # method.
@@ -93,9 +76,35 @@ module Settingable
       map_method(method, args)
     end
 
+    # A hook method for ruby.  This should not be called directly.  It
+    # lets ruby know that we respond to certain methods.
+    #
+    # @param method [Symbol] The method to check.
+    # @return [Boolean]
+    def responds_to_missing?(method, _include_all = false)
+      !(method =~ /(\?|\!)\z/)
+    end
+
     private
 
-    # Maps the methods.
+    # Merges the given settings with the class defaults.  Performs a
+    # deep merge.
+    #
+    # @param provided [Hash]
+    # @return [Hash]
+    def merged_settings(provided)
+      DeepMerge.deep_merge(self.class.default_settings, provided)
+    end
+
+    # Maps the methods.  If the method is a setter, i.e. ends in `=`,
+    # it sets the value.  If arguments are provided to a non-setter
+    # method, it raises a NameError.
+    #
+    # @param method [Symbol]
+    # @param args [Array<Object>]
+    # @return [Object]
+    # @raise NameError If more than 1 argument is provided to a
+    #   setter, or arguments are provided to a non-setter method.
     def map_method(method, args)
       if method =~ /\A(.*)\=\z/ && args.length == 1
         self[$+] = args[0]

data/lib/settingable/version.rb

@@ -3,5 +3,5 @@
 # :nodoc:
 module Settingable
   # settingable version
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/settingable.rb

@@ -2,6 +2,7 @@
 
 require "settingable/version"
 require "settingable/deep_merge"
+require "settingable/hash"
 require "settingable/settings"
 
 # Contains the Setting module.

data/spec/settingable/hash_spec.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+
+RSpec.describe Settingable::Hash do
+  let(:body) { { foo: { bar: "baz" }, hello: "world" } }
+  subject { Settingable::Hash.new(body) }
+
+  describe "#initialize" do
+    it "converts hash values" do
+      expect(subject[:foo]).to be_a Settingable::Hash
+    end
+  end
+
+  describe "#[]" do
+    it "raises on an invalid key" do
+      expect { subject[:bar] }.to raise_error(KeyError)
+    end
+
+    it "allows access by other objects" do
+      expect(subject[:hello]).to eq "world"
+      expect(subject["hello"]).to eq "world"
+    end
+  end
+
+  describe "#[]=" do
+    it "converts hash values" do
+      subject[:hello] = { foo: { bar: "baz" } }
+      expect(subject[:hello]).to be_a(Settingable::Hash)
+      expect(subject[:hello][:foo]).to be_a(Settingable::Hash)
+    end
+
+    it "sets the symbol" do
+      subject["bar"] = "baz"
+      expect(subject[:bar]).to eq "baz"
+    end
+  end
+
+  describe "#key?" do
+    it "returns true for other objects" do
+      expect(subject.key?(:hello)).to be true
+      expect(subject.key?("hello")).to be true
+    end
+  end
+
+  describe "#fetch" do
+    let(:fake) { double("fake") }
+    it "returns the double on a bad key" do
+      expect(subject.fetch(:bar, fake)).to be fake
+    end
+
+    it "yields on a bad key" do
+      expect { |y| subject.fetch(:bar, &y) }.to yield_control
+    end
+
+    it "yields first on a bad key" do
+      expect { |y| subject.fetch(:bar, :baz, &y) }.to yield_control
+    end
+
+    it "raises on a bad key with no default" do
+      expect { subject.fetch(:bar) }.to raise_error(KeyError)
+    end
+  end
+end

data/spec/settingable/settings_spec.rb

@@ -11,7 +11,7 @@ class Configuration
 end
 
 RSpec.describe Settingable::Settings do
-  subject { Configuration.settings }
+  subject { Configuration.instance }
   before(:each) { Configuration.reset! }
 
   it "extends the base" do
@@ -20,10 +20,10 @@ RSpec.describe Settingable::Settings do
       .to include(Settingable::Settings::ClassMethods)
   end
 
-  describe ".settings" do
+  describe ".instance" do
     it "returns the same instance" do
-      expect(Configuration.settings).to be_a(Configuration)
-      expect(Configuration.settings).to be(Configuration.settings)
+      expect(Configuration.instance).to be_a(Configuration)
+      expect(Configuration.instance).to be(Configuration.instance)
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: settingable
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Jeremy Rodi
@@ -84,10 +84,12 @@ files:
 - Rakefile
 - lib/settingable.rb
 - lib/settingable/deep_merge.rb
+- lib/settingable/hash.rb
 - lib/settingable/settings.rb
 - lib/settingable/version.rb
 - settingable.gemspec
 - spec/settingable/deep_merge_spec.rb
+- spec/settingable/hash_spec.rb
 - spec/settingable/settings_spec.rb
 - spec/settingable_spec.rb
 - spec/spec_helper.rb
@@ -117,6 +119,7 @@ specification_version: 4
 summary: Handles configuring your gems.
 test_files:
 - spec/settingable/deep_merge_spec.rb
+- spec/settingable/hash_spec.rb
 - spec/settingable/settings_spec.rb
 - spec/settingable_spec.rb
 - spec/spec_helper.rb