configurations 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7415bb2455bde354b3e2db792f4ff3b0d39ed012
+  data.tar.gz: fc663b3bb7de0224af0e6112008e5752760c930e
+SHA512:
+  metadata.gz: 75dd7197ee0fead9848bd6896550d950487c8f8853e3c9177c7ccaae63821db9827a770ea023ffa1fc18e8b7b44852fc7efd48ed5432896b6ce131e9ab01233b
+  data.tar.gz: 0579d9eaf837f25f766f2dfc9e392d51d940604e490870d180147b380e0f37c8067f14f86e15588c72f85c080faeec5f9d67c764abb641381e854aae47aadb47

data/.gitignore

@@ -0,0 +1,4 @@
+.yardoc
+.bundle
+Gemfile.lock
+doc

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p481

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+branches:
+  only:
+    - master
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - rbx
+  - jruby-19mode
+  - jruby-20mode
+
+script: rake

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2014 Beat Richartz
+
+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/README.md

@@ -0,0 +1,147 @@
+# Configurations
+
+Configurations provides a unified approach to do configurations using the `MyGem.configure do ... end` idiom with the flexibility to do everything from arbitrary configurations to type asserted configurations for your gem or any other ruby code.
+
+## Install
+
+`gem install configurations`
+
+or with Bundler
+
+`gem 'configurations', '~> 1.0.0'`
+
+Configurations uses [Semver 2.0](http://semver.org/)
+
+## Why?
+
+There are various ways to do configurations, yet there seems to be a broad consensus on the `MyGem.configure do ... end` idiom.
+So instead of rolling your own, you can add this gem to your gem and get that functionality for free, plus some goodies you may want
+but do not have the time to write like type assertion or nested configurations.
+
+Less time copy pasting configuration code, more time writing exciting code for you.
+
+## Configure
+
+### First way: Arbitrary Configuration
+
+Go boom! with ease. This allows your gem / code users to set any value they like.
+
+```
+module MyGem
+  include Configurations
+end
+```
+
+Gives your users:
+
+```
+MyGem.configure do |c|
+  c.foo.bar.baz = 'fizz'
+  c.hi = 'Hello-o'
+  c.class = 'oooh wow' # Such flexible!
+end
+```
+
+Gives you:
+
+```
+MyGem.configuration.class #=> 'oooh wow'
+MyGem.configuration.foo.bar.baz #=> 'fizz'
+```
+
+### Second way: Restricted Configuration
+
+If you just want some properties to be configurable, consider this option
+
+```
+module MyGem
+  include Configurations
+  configurable :foo, bar: :baz, biz: %i(bi ba bu)
+end
+```
+
+Gives your users:
+
+```
+MyGem.configure do |c|
+  c.foo = 'FOO'
+  c.bar.baz = 'FIZZ'
+  c.biz.bi = 'BI'
+  c.biz.ba = 'BA'
+
+  # This would raise NoMethodError
+  # c.bar.biz
+end
+```
+
+Gives you:
+
+```
+MyGem.configuration.foo #=> 'FOO'
+MyGem.configuration.bar.baz #=> 'FIZZ'
+```
+
+### Third way: Type Restricted Configuration
+
+If you want to make sure your configurations only accept one type, consider this option
+
+```
+module MyGem
+  include Configurations
+  configurable String, :foo
+  configurable Array, bar: :baz
+end
+```
+
+Gives your users:
+
+```
+MyGem.configure do |c|
+  c.foo = 'FOO'
+  c.bar.baz = %w(hello)
+
+  # This would raise Configurations::ConfigurationError
+  # c.foo = :not_so_foo
+  # c.bar.baz = 'oh my cannot configure'
+end
+```
+
+Gives you:
+
+```
+MyGem.configuration.foo #=> 100% String
+MyGem.configuration.bar.baz #=> 100% Array
+```
+
+### Defaults:
+
+```
+module MyGem
+  include Configurations
+  configuration_defaults do |c|
+    c.foo.bar.baz = 'BAR'
+  end
+end
+```
+
+### Get a hash if you need it
+
+```
+MyGem.configuration.to_h #=> a Hash
+
+```
+
+### Some caveats
+
+The `to_h` from above is along with `method_missing` and `initialize` the only purposely defined method which you can not overwrite with a configuration value.
+Apart from these methods, you should be able to set pretty much any property name you like. `Configuration` inherits from `BasicObject`, so even standard Ruby method names are available.
+
+## Contributing
+
+YES!
+
+Let's make this awesome. Write tests for your added stuff, bonus points for feature branches. If you don't have to time to write a fix, raise an issue.
+
+### Copyright
+
+Copyright © 2014 Beat Richartz. See LICENSE.txt for further details.

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake/testtask'
+
+task default: :test
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/test_*.rb'
+end

data/configurations.gemspec

@@ -0,0 +1,21 @@
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require 'configurations'
+
+Gem::Specification.new do |s|
+  s.name              = 'configurations'
+  s.version           = Configurations::VERSION
+  s.authors           = ['Beat Richartz']
+  s.description       = 'Configurations provides a unified approach to do configurations with the flexibility to do everything from arbitrary configurations to type asserted configurations for your gem or any other ruby code.'
+  s.email             = 'attr_accessor@gmail.com'
+  s.homepage          = 'http://github.com/beatrichartz/configurations'
+  s.licenses          = %w(MIT)
+  s.require_paths     = %w(lib)
+  s.summary           = 'Configurations with a configure block from arbitrary to type-restricted for your gem or other ruby code.'
+
+  s.files             = `git ls-files`.split("\n")
+  s.test_files        = `git ls-files -- test/*`.split("\n")
+
+  s.add_development_dependency 'minitest', '~> 5.4'
+  s.add_development_dependency 'yard', '~> 0.8'
+  s.add_development_dependency 'rake', '~> 10'
+end

data/lib/configurations/configurable.rb

@@ -0,0 +1,67 @@
+module Configurations
+  # Module configurable provides the API of configurations
+  #
+  module Configurable
+    extend self
+
+    # Once included, Configurations installs three methods in the host module: configure, configuration_defaults and configurable
+    #
+    def included(base)
+      install_configure_in(base)
+      base.class_eval do
+        extend ClassMethods
+      end
+    end
+
+    # Installs #configure in base, and makes sure that it will instantiate configuration as a subclass of the host module
+    #
+    def install_configure_in(base)
+      base.class_eval <<-EOF
+        class << self
+          # The central configure method
+          # @params [Proc] block the block to configure host module with
+          #
+          def configure(&block)
+            @configuration = #{self}::Configuration.new(@configuration_defaults, @configurable, &block)
+          end
+        end
+      EOF
+    end
+
+    # Class methods that will get installed in the host module
+    #
+    module ClassMethods
+      # A reader for Configuration
+      #
+      attr_reader :configuration
+
+      # Configuration defaults can be used to set the defaults of any Configuration
+      # @param [Proc] block setting the default values of the configuration
+      #
+      def configuration_defaults(&block)
+        @configuration_defaults = block
+      end
+
+      # configurable can be used to set the properties which should be configurable, as well as a type which
+      # the given property should be asserted to
+      # @param [Class, Symbol, Hash] properties a type as a first argument to type assert (if any) or nested properties to allow for setting
+      #
+      def configurable(*properties)
+        type = properties.shift if properties.first.is_a?(Class)
+        @configurable ||= {}
+        @configurable.merge!(to_configurable_hash(properties, type))
+      end
+
+      private
+
+      # Instantiates a configurable hash from a property and a type
+      # @param [Symbol, Hash, Array] properties configurable properties, either single or nested
+      # @param [Class] type the type to assert, if any
+      # @return a hash with configurable values pointing to their types
+      #
+      def to_configurable_hash(properties, type)
+        Hash[properties.zip(Array(type) * properties.size)]
+      end
+    end
+  end
+end

data/lib/configurations/configuration.rb

@@ -0,0 +1,163 @@
+module Configurations
+  # Configuration is a blank object in order to allow configuration of various properties including keywords
+  #
+  class Configuration < BasicObject
+
+    # @!macro [attach] install_kernel_method
+    # @method $1
+    #
+    def self.install_kernel_method(method)
+      kernel_method = ::Kernel.instance_method(method)
+      define_method method do |*args, &block|
+        kernel_method.bind(self).call(*args, &block)
+      end
+    end
+
+    # Installs the type asserting is_a? method from Kernel
+    #
+    install_kernel_method(:is_a?)
+
+    # Installs the inspect method from Kernel
+    #
+    install_kernel_method(:inspect)
+
+    # Initialize a new configuration
+    # @param [Proc] configuration_defaults A proc yielding to a default configuration
+    # @param [Hash] configurable a hash of configurable properties and their asserted types if given
+    # @param [Proc] block a block to configure this configuration with
+    # @return [HostModule::Configuration] a configuration
+    #
+    def initialize(configuration_defaults, configurable, &block)
+      @_writeable = true
+      @configurable = configurable
+      @configuration = _configuration_hash
+
+      _evaluate_configurable!
+
+      self.instance_eval(&configuration_defaults) if configuration_defaults
+
+      if block
+        self.instance_eval(&block)
+        self._writeable = false
+      end
+    end
+
+    # Method missing gives access for reading and writing to the underlying configuration hash via dot notation
+    #
+    def method_missing(method, *args, &block)
+      property = method.to_s[0..-2].to_sym
+
+      if _is_writer?(method) && _configurable?(property)
+        _assert_type!(property, args.first)
+        @configuration[property] = args.first
+      elsif !_is_writer?(method) && @_writeable || _configured?(method)
+        @configuration[method]
+      else
+        super
+      end
+    end
+
+    # Respond to missing according to the method_missing implementation
+    #
+    def respond_to_missing?(method, include_private = false)
+      is_setter?(method) || @_writeable || _configured?(method) || super
+    end
+
+    # Set the configuration to writeable or read only. Access to writer methods is only allowed within the
+    # configure block, this method is used to invoke writability for subconfigurations.
+    # @param [Boolean] data true if the configuration should be writeable, false otherwise
+    #
+    def _writeable=(data)
+      @_writeable = data
+      @configuration.each do |k,v|
+        v._writeable = data if v.is_a?(Configuration)
+      end
+    end
+
+    # A convenience accessor to get a hash representation of the current state of the configuration
+    # @return [Hash] the configuration in hash form
+    #
+    def to_h
+      @configuration.inject({}) do |h, (k,v)|
+        h[k] = v.is_a?(Configuration) ? v.to_h : v
+
+        h
+      end
+    end
+
+    private
+
+    # @param [Symbol] property The property to test for configurability
+    # @return [Boolean] whether the given property is configurable
+    #
+    def _configurable?(property)
+      _arbitrarily_configurable? or @configurable.has_key?(property)
+    end
+
+    # @param [Symbol] property The property to test for
+    # @return [Boolean] whether the given property has been configured
+    #
+    def _configured?(property)
+      @configuration.has_key?(property)
+    end
+
+    # @return [Hash] A configuration hash instantiating subhashes if the key is configurable
+    #
+    def _configuration_hash
+      ::Hash.new do |h, k|
+        h[k] = Configuration.new(nil, @configurable) if _configurable?(k)
+      end
+    end
+
+    # Evaluates configurable properties and passes eventual hashes down to subconfigurations
+    #
+    def _evaluate_configurable!
+      return if _arbitrarily_configurable?
+
+      @configurable.each do |k, type|
+        if k.is_a?(::Hash)
+          k.each do |property, nested|
+            @configuration[property] = Configuration.new(nil, _to_configurable_hash(nested, type))
+          end
+        end
+      end
+    end
+
+    # @param [Symbol, Hash, Array] value configurable properties, either single or nested
+    # @param [Class] type the type to assert, if any
+    # @return a hash with configurable values pointing to their types
+    #
+    def _to_configurable_hash(value, type)
+      value = [value] unless value.is_a?(::Array)
+      ::Hash[value.zip([type].flatten*value.size)]
+    end
+
+    # Type assertion for configurable properties
+    # @param [Symbol] property the property to type test
+    # @param [Any] value the given value
+    # @raise [ConfigurationError] if the given value has the wrong type
+    #
+    def _assert_type!(property, value)
+      return if _arbitrarily_configurable?
+
+      expected_type = @configurable[property]
+      return if expected_type.nil?
+
+      ::Kernel.raise ConfigurationError, "Expected #{property} to be configured with #{expected_type}, but got #{value.class.inspect}", caller unless value.is_a?(expected_type)
+    end
+
+    # @return [Boolean] whether this configuration is arbitrarily configurable
+    #
+    def _arbitrarily_configurable?
+      @configurable.nil? or @configurable.empty?
+    end
+
+    # @param [Symbol] method the method to test for
+    # @return [Boolean] whether the given method is a writer
+    #
+    def _is_writer?(method)
+      method.to_s.end_with?('=')
+    end
+
+  end
+end

data/lib/configurations/error.rb

@@ -0,0 +1,5 @@
+module Configurations
+  # A configuration Error, raised when configuration gets misconfigured
+  #
+  ConfigurationError = Class.new(ArgumentError)
+end

data/lib/configurations.rb

@@ -0,0 +1,16 @@
+require_relative 'configurations/error'
+require_relative 'configurations/configuration'
+require_relative 'configurations/configurable'
+
+# Configurations provides a unified approach to do configurations with the flexibility to do everything
+# from arbitrary configurations to type asserted configurations for your gem or any other ruby code.
+# @version 1.0.0
+# @author Beat Richartz
+#
+module Configurations
+  extend Configurable
+
+  # Version number of Configurations
+  #
+  VERSION = '1.0.0'
+end

data/test/configurations/test_configuration.rb

@@ -0,0 +1,93 @@
+require 'test_helper'
+
+class TestConfiguration < Minitest::Test
+
+  ConfigurationTestModule = testmodule_for(Configurations)
+  ConfigurationTestModule.module_eval do
+    configuration_defaults do |c|
+      c.uh.this.is.neat = 'NEAT'
+      c.pah = 'PUH'
+      c.overwrite.this = ''
+      c.overwriteee = 'BLA'
+    end
+  end
+  def setup
+    ConfigurationTestModule.configure do |c|
+      c.basic = 'BASIC'
+      c.class = 'KEY'
+      c.overwriteee = 'YEAH'
+      c.overwrite.this = 'OVERWRITE'
+      c.github.repo = 'github.com/beatrichartz/configurations'
+      c.github.access_key = 'ABCDEF'
+      c.something.else.entirely.nested.deep.below = 'something'
+    end
+
+    @configuration = ConfigurationTestModule.configuration
+  end
+
+  def test_configuration_is_subclass_of_host_module
+    assert_equal true, ConfigurationTestModule.const_defined?(:Configuration)
+  end
+
+  def test_configuration_to_h
+    assert_equal(
+      {
+        uh:
+          {
+            this: { is: { neat: 'NEAT' } }
+          },
+        pah: 'PUH',
+        overwrite: {
+          this: 'OVERWRITE'
+        },
+        overwriteee: 'YEAH',
+        basic: 'BASIC',
+        class: 'KEY',
+        github: {
+          repo: 'github.com/beatrichartz/configurations',
+          access_key: 'ABCDEF'
+        },
+        something: { else: { entirely: { nested: { deep: { below: 'something' } } } } }
+      }, @configuration.to_h)
+  end
+
+  def test_defaults
+    assert_equal 'PUH', @configuration.pah
+  end
+
+  def test_defaults_overwrite
+    assert_equal 'YEAH', @configuration.overwriteee
+  end
+
+  def test_nested_defaults
+    assert_equal 'NEAT', @configuration.uh.this.is.neat
+  end
+
+  def test_nested_defaults_overwrite
+    assert_equal 'OVERWRITE', @configuration.overwrite.this
+  end
+
+  def test_configurable
+    assert_equal 'BASIC', @configuration.basic
+  end
+
+  def test_keywords_configurable
+    assert_equal 'KEY', @configuration.class
+  end
+
+  def test_nested_properties_with_same_key_configurable
+    assert_equal 'github.com/beatrichartz/configurations', @configuration.github.repo
+    assert_equal 'ABCDEF', @configuration.github.access_key
+  end
+
+  def test_deeply_nested_properties_configurable
+    assert_equal 'something', @configuration.something.else.entirely.nested.deep.below
+  end
+
+  def test_not_callable_with_undefined_property
+    assert_raises NoMethodError do
+      @configuration.somethings
+    end
+  end
+
+end

data/test/configurations/test_stricter_configuration.rb

@@ -0,0 +1,81 @@
+require 'test_helper'
+
+class TestStricterConfiguration < Minitest::Test
+
+  StrictConfigurationTestModule = testmodule_for(Configurations)
+  StrictConfigurationTestModule.module_eval do
+    configurable :property1, :property2
+    configurable String, :property3
+    configurable Symbol, property4: :property5, property6: [:property7, :property8]
+    configurable Array, property9: { property10: :property11 }
+  end
+
+  def setup
+    StrictConfigurationTestModule.configure do |c|
+      c.property1 = 'BASIC1'
+      c.property2 = 'BASIC2'
+      c.property3 = 'STRING'
+      c.property4.property5 = :something
+      c.property6.property7 = :anything
+      c.property6.property8 = :everything
+      c.property9.property10.property11 = %w(here I am)
+    end
+
+    @configuration = StrictConfigurationTestModule.configuration
+  end
+
+  def test_configurable_when_set_configurable
+    assert_equal 'BASIC1', @configuration.property1
+    assert_equal 'BASIC2', @configuration.property2
+  end
+
+  def test_configurable_when_set_nested_configurable
+    assert_equal :something, @configuration.property4.property5
+  end
+
+  def test_configurable_with_same_key_when_set_nested_configurable
+    assert_equal :anything, @configuration.property6.property7
+    assert_equal :everything, @configuration.property6.property8
+  end
+
+  def test_configurable_with_deeply_nested_property
+    assert_equal %w(here I am), @configuration.property9.property10.property11
+  end
+
+  def test_not_configurable_with_wrong_type
+    assert_raises Configurations::ConfigurationError do
+      StrictConfigurationTestModule.configure do |c|
+        c.property3 = {}
+      end
+    end
+  end
+
+  def test_not_configurable_with_undefined_property
+    assert_raises NoMethodError do
+      StrictConfigurationTestModule.configure do |c|
+        c.property4 = {}
+      end
+    end
+  end
+
+  def test_not_callable_with_undefined_property
+    assert_raises NoMethodError do
+      @configuration.property12
+    end
+  end
+
+  def test_not_configurable_with_undefined_nested_property
+    assert_raises NoMethodError do
+      StrictConfigurationTestModule.configure do |c|
+        c.property6.property9 = {}
+      end
+    end
+  end
+
+  def test_not_callable_with_undefined_nested_property
+    assert_raises NoMethodError do
+      @configuration.property6.property9
+    end
+  end
+
+end

data/test/support/testmodules.rb

@@ -0,0 +1,10 @@
+module TestModules
+
+  def testmodule_for(mod)
+    a = Module.new
+    a.module_eval { include mod }
+
+    a
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,18 @@
+require 'pathname'
+require 'minitest'
+
+PATH = Pathname.new(File.dirname(__FILE__))
+
+$LOAD_PATH.unshift PATH, File.expand_path('../../lib', __FILE__)
+
+Dir[PATH.join('support', '**', '*.rb')].each(&method(:require))
+
+Minitest::Test.class_eval do
+  extend TestModules
+end
+
+require 'minitest/autorun'
+require 'minitest/pride'
+require 'test/unit/assertions'
+
+require 'configurations'

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: configurations
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Beat Richartz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-08-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '5.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '5.4'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '10'
+description: Configurations provides a unified approach to do configurations with
+  the flexibility to do everything from arbitrary configurations to type asserted
+  configurations for your gem or any other ruby code.
+email: attr_accessor@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .ruby-version
+- .travis.yml
+- Gemfile
+- License.txt
+- README.md
+- Rakefile
+- configurations.gemspec
+- lib/configurations.rb
+- lib/configurations/configurable.rb
+- lib/configurations/configuration.rb
+- lib/configurations/error.rb
+- test/configurations/test_configuration.rb
+- test/configurations/test_stricter_configuration.rb
+- test/support/testmodules.rb
+- test/test_helper.rb
+homepage: http://github.com/beatrichartz/configurations
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.14
+signing_key: 
+specification_version: 4
+summary: Configurations with a configure block from arbitrary to type-restricted for
+  your gem or other ruby code.
+test_files:
+- test/configurations/test_configuration.rb
+- test/configurations/test_stricter_configuration.rb
+- test/support/testmodules.rb
+- test/test_helper.rb
+has_rdoc: