configurations 2.0.0.pre → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
---- 
-SHA1: 
-  metadata.gz: e4dac5ba9d58bb68f5ff84dbd03433a9015f976a
-  data.tar.gz: 7ba636f43c643628e1281c2382dc73c4ee4b4a97
-SHA512: 
-  metadata.gz: e2813ce78bbd73297da31cf753832ae05e058bb5d75cdab01a73171302c58c7931979305f4d2dd267e7ab978573134d589ef57a72e6f75887221f791d961dc0f
-  data.tar.gz: 4b102d91d228b20f77097858c6753bd59e880cf060540a4115a5b3452d3bc930ad12804bb77f6fac25c3741cb67ce373c153e29524235709c5229d5b571acd57
+---
+SHA1:
+  metadata.gz: f9907568167e40b9014fea6fd1999980874e83a8
+  data.tar.gz: 848cd43a6bb4e9c41cf9aa6ff21d1b3966fb7238
+SHA512:
+  metadata.gz: a60a00a58aa9af53a443fa2781138c734248ac77b5c2f55724cb330eca8a173636445657e8b7f23a4e907fd319cd9eb651a26ad2216c9d80d9d98501f4e7e646
+  data.tar.gz: 8b0a6f40548e80e3ba7f21eb6674980b2877ff9f270ed02e0c8aadedea532c350270895ccf12108302c74a076967b14f84d5796669e87083e451b1e45ffaa9a8

data/.travis.yml

@@ -6,8 +6,10 @@ rvm:
   - 1.9.2
   - 1.9.3
   - 2.0.0
-  - 2.1.0
+  - 2.1.5
+  - 2.2.0
   - rbx
   - jruby-19mode
-  
+  - jruby-20mode
+
 script: CODECLIMATE_REPO_TOKEN=36cf84c73264d3c361003f66903eec8aa5fb2b3494496f3a9676630518ecc9f9 rake

data/License.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014 Beat Richartz
+Copyright (c) 2015 Beat Richartz
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -10,13 +10,13 @@ Configurations provides a unified approach to do configurations using the `MyGem
 
 or with Bundler
 
-`gem 'configurations', '~> 2.0.0.pre'`
+`gem 'configurations', '~> 2.0.0'`
 
 Configurations uses [Semver 2.0](http://semver.org/)
 
 ## Compatibility
 
-Compatible with MRI 1.9.2 - 2.1, Rubinius, jRuby
+Compatible with MRI 1.9.2 - 2.2, Rubinius 2.2, jRuby 1.7 and 9K
 
 ## Why?
 
@@ -61,7 +61,7 @@ Undefined properties on an arbitrary configuration will return `nil`
 MyGem.configuration.not_set #=> nil
 ```
 
-If you want to define the behaviour for not set properties yourself, use `not_configured`.
+If you want to define the behaviour for not set properties yourself, use `not_configured`. You can either define a catch-all `not_configured` which will be executed whenever you call a value that has not been configured and has no default:
 
 ```
 module MyGem
@@ -71,6 +71,15 @@ module MyGem
 end
 ```
 
+Or you can define finer-grained callbacks:
+
+```
+module MyGem
+  not_configured my: { nested: :prop } do |prop|
+	raise NoMethodError, "#{prop} must be configured"
+  end
+end
+```
 
 ### Second way: Restricted Configuration
 
@@ -114,7 +123,7 @@ If you want to define the behaviour for not set properties yourself, use `not_co
 
 ```
 module MyGem
-  not_configured do |prop|
+  not_configured :awesome, :nice do |prop| # omit the arguments to get a catch-all not_configured
 	warn :not_configured, "Please configure #{prop} or live in danger"
   end
 end
@@ -219,6 +228,13 @@ You get:
 MyGem.configuration.foobar('ARG') #=> 'FOOBARARG'
 ```
 
+configuration methods can also be installed on nested properties using hashes:
+
+```
+configuration_method foo: :bar do |arg|
+  foo + bar + arg
+end
+```
 
 ### Defaults:
 
@@ -239,7 +255,7 @@ MyGem.configuration.to_h #=> a Hash
 
 ### Configure with a hash where needed
 
-Sometimes your users will have a hash of configuration values which are not handy to press into the block form. In that case, they can use `from_h` inside the `configure` block to either read in the full or a nested configuration.
+Sometimes your users will have a hash of configuration values which are not handy to press into the block form. In that case, they can use `from_h` inside the `configure` block to either read in the full or a nested configuration. With a everything besides arbitrary configurations, `from_h` can also be used outside the block.
 
 ```
 yaml_hash = YAML.load_file('configuration.yml')
@@ -252,7 +268,7 @@ end
 
 ### Some caveats
 
-The `to_h` from above is along with `method_missing`, `object_id` and `initialize` the only purposely defined API method which you can not overwrite with a configuration value.
+The `to_h` from above is along with `method_missing`, `object_id` and `initialize` and `singleton_class` the only purposely defined API 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 `Kernel` and `Object` method names are available.
 
 ## Contributing
@@ -263,4 +279,4 @@ Let's make this awesome. Write tests for your added stuff, bonus points for feat
 
 ### Copyright
 
-Copyright © 2014 Beat Richartz. See LICENSE.txt for further details.
+Copyright © 2015 Beat Richartz. See LICENSE.txt for further details.

data/Rakefile

@@ -4,5 +4,5 @@ task default: :test
 
 Rake::TestTask.new do |t|
   t.libs << 'test'
-  t.pattern = 'test/**/test_*.rb'
+  t.pattern = 'test/**/test*.rb'
 end

data/configurations.gemspec

@@ -5,13 +5,17 @@ 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.description       = <<-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.
+DESCRIPTION
   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.summary           = <<-SUMMARY
+Configurations with a configure block from arbitrary to type-restricted for your gem or other ruby code.
+SUMMARY
   s.files             = `git ls-files`.split("\n")
   s.test_files        = `git ls-files -- test/*`.split("\n")
 

data/lib/configurations.rb

@@ -1,10 +1,14 @@
 require_relative 'configurations/error'
+require_relative 'configurations/blank_object'
 require_relative 'configurations/configuration'
+require_relative 'configurations/arbitrary'
+require_relative 'configurations/strict'
 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
+# 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 2.0.0
 # @author Beat Richartz
 #
 module Configurations
@@ -12,5 +16,5 @@ module Configurations
 
   # Version number of Configurations
   #
-  VERSION = '2.0.0.pre'
+  VERSION = '2.0.0'
 end

data/lib/configurations/arbitrary.rb

@@ -0,0 +1,124 @@
+# coding: utf-8
+module Configurations
+  # Configuration is a blank object in order to allow configuration of
+  # various properties including keywords
+  #
+  class ArbitraryConfiguration < Configuration
+    # Initialize a new configuration
+    # @param [Hash] options The options to initialize a configuration with
+    # @option options [Hash] methods a hash of method names pointing to procs
+    # @option options [Proc] not_configured a proc to evaluate for
+    #   not_configured properties
+    # @param [Proc] block a block to configure this configuration with
+    # @yield [HostModule::Configuration] a configuration
+    # @return [HostModule::Configuration] a configuration
+    # @note An arbitrary configuration has to control its writeable state,
+    #   therefore configuration is only possible in the initialization block
+    #
+    def initialize(options = {}, &block)
+      self.__writeable__ = true
+      super
+      self.__writeable__ = false if block
+    end
+
+    # Method missing gives access for reading and writing to the underlying
+    # configuration hash via dot notation
+    #
+    def method_missing(method, *args, &block)
+      if __respond_to_writer?(method)
+        __assign!(method.to_s[0..-2].to_sym, args.first)
+      elsif __respond_to_method_for_write?(method)
+        @data[method]
+      elsif __respond_to_method_for_read?(method, *args, &block)
+        @data.fetch(method, &__not_configured_callback_for__(method))
+      else
+        super
+      end
+    end
+
+    # Respond to missing according to the method_missing implementation
+    #
+    def respond_to_missing?(method, include_private = false)
+      __respond_to_writer?(method) ||
+        __respond_to_method_for_read?(method, *args, &block) ||
+        __respond_to_method_for_write?(method) ||
+        super
+    end
+
+    # A convenience accessor to instantiate a configuration from a hash
+    # @param [Hash] h the hash to read into the configuration
+    # @return [Configuration] the configuration with values assigned
+    # @note can only be accessed during writeable state (in configure block).
+    #   Unassignable values are ignored
+    # @raise [ArgumentError] unless used in writeable state (in configure block)
+    #
+    def from_h(h)
+      unless @__writeable__
+        fail ::ArgumentError, 'can not dynamically assign values from a hash'
+      end
+
+      super
+    end
+
+    # @param [Symbol] property The property to test for configurability
+    # @return [Boolean] whether the given property is configurable
+    #
+    def __configurable?(_property)
+      true
+    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
+    # writeability for subconfigurations.
+    # @param [Boolean] data true if the configuration should be writeable, false
+    #   otherwise
+    #
+    def __writeable__=(data)
+      @__writeable__ = data
+      return if @data.nil?
+
+      @data.each do |_k, v|
+        v.__writeable__ = data if v.is_a?(__class__)
+      end
+    end
+
+    private
+
+    # @param [Symbol] property The property to test for
+    # @return [Boolean] whether the given property has been configured
+    #
+    def __configured?(_property)
+      true
+    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
+
+    # @param [Symbol] method the method to test for
+    # @return [Boolean] whether the configuration responds to the given property
+    #   as a method during writeable state
+    #
+    def __respond_to_method_for_write?(method)
+      !__is_writer?(method) && @__writeable__ && @data[method].is_a?(__class__)
+    end
+
+    # @param [Symbol] method the method to test for
+    # @return [Boolean] whether the configuration responds to the given property
+    #
+    def __respond_to_method_for_read?(method, *args, &block)
+      !__is_writer?(method) && args.empty? && block.nil?
+    end
+
+    # @param [Symbol] method the method to test for
+    # @return [Boolean] whether the method is a writer and is used in writeable
+    #   state
+    #
+    def __respond_to_writer?(method)
+      @__writeable__ && __is_writer?(method)
+    end
+  end
+end

data/lib/configurations/blank_object.rb

@@ -0,0 +1,60 @@
+module Configurations
+  # Create a blank object with some kernel methods
+  #
+  class BlankObject < ::BasicObject
+    # The instance methods to keep on the blank object.
+    #
+    KEEP_METHODS = [
+      :equal?,
+      :object_id,
+      :__id__,
+      :__send__,
+      :method_missing
+    ].freeze
+
+    # The kernel methods to alias to an internal name
+    #
+    ALIAS_KERNEL_METHODS = {
+      __class__: :class,
+      __instance_eval__: :instance_eval,
+      __define_singleton_method__: :define_singleton_method
+    }.freeze
+
+    # The kernel methods to keep on the blank object
+    #
+    KEEP_KERNEL_METHODS  = [
+      :respond_to?,
+      :is_a?,
+      :inspect,
+      :object_id,
+      # rbx needs the singleton class to access singleton methods
+      :singleton_class,
+      *ALIAS_KERNEL_METHODS.keys
+    ].freeze
+
+    # Undefines every instance method except the kept methods
+    #
+    (instance_methods - KEEP_METHODS).each do |method|
+      undef_method method
+    end
+
+    # @return [Module] A Kernel module with only the methods
+    #   defined in KEEP_KERNEL_METHODS
+    #
+    def self.blank_kernel
+      kernel = ::Kernel.dup
+
+      ALIAS_KERNEL_METHODS.each do |new_name, old_name|
+        kernel.module_eval { alias_method new_name, old_name }
+      end
+
+      (kernel.instance_methods - KEEP_KERNEL_METHODS).each do |method|
+        kernel.module_eval { undef_method method }
+      end
+
+      kernel
+    end
+
+    include blank_kernel
+  end
+end

data/lib/configurations/configurable.rb

@@ -4,7 +4,8 @@ module Configurations
   module Configurable
     extend self
 
-    # Once included, Configurations installs three methods in the host module: configure, configuration_defaults and configurable
+    # Once included, Configurations installs three methods in the host module:
+    # configure, configuration_defaults and configurable
     #
     def included(base)
       install_configure_in(base)
@@ -13,29 +14,25 @@ module Configurations
       end
     end
 
-    # Installs #configure in base, and makes sure that it will instantiate configuration as a subclass of the host module
+    # 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
-          # @raise [ArgumentError] error when not given a block
-          # @example Configure a configuration
-          #   MyGem.configure do |c|
-          #     c.foo = :bar
-          #   end
-          #
-          def configure(&block)
-            raise ArgumentError, 'can not configure without a block' unless block_given?
-            @configuration = #{base.name}::Configuration.new(
-                                                              defaults: @configuration_defaults,
-                                                              methods: @configuration_methods,
-                                                              configurable: @configurable,
-                                                              not_configured: @not_configured_callback,
-                                                              &block
-                                                            )
-          end
+        # The central configure method
+        # @params [Proc] block the block to configure host module with
+        # @raise [ArgumentError] error when not given a block
+        # @example Configure a configuration
+        #   MyGem.configure do |c|
+        #     c.foo = :bar
+        #   end
+        #
+        def self.configure(&block)
+          fail ArgumentError, "configure needs a block" unless block_given?
+          @configuration = #{base.name}.const_get(configuration_type).new(
+                                                          configuration_options,
+                                                          &block
+                                                        )
         end
       EOF
     end
@@ -46,70 +43,121 @@ module Configurations
       # A reader for Configuration
       #
       def configuration
-        @configuration ||= @configuration_defaults && configure { }
+        @configuration ||= @configuration_defaults && configure {}
       end
 
-      # Configuration defaults can be used to set the defaults of any 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
-      # @param [Proc] block a block with arity 2 to evaluate when a property is set. It will be given: property name and value
+      # 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
+      # @param [Proc] block a block with arity 2 to evaluate when a property
+      #   is set. It will be given: property name and value
       # @example Define a configurable property
       #   configurable :foo
       # @example Define a type asserted, nested property for type String
       #   configurable String, bar: :baz
       # @example Define a custom assertion for a property
       #   configurable biz: %i(bi bu) do |value|
-      #     raise ArgumentError, 'must be one of a, b, c' unless %w(a b c).include?(value)
+      #     unless %w(a b c).include?(value)
+      #       fail ArgumentError, 'must be one of a, b, c'
+      #     end
       #   end
       #
       def configurable(*properties, &block)
         type = properties.shift if properties.first.is_a?(Class)
+
         @configurable ||= {}
         @configurable.merge! to_configurable_hash(properties, type, &block)
       end
 
       # returns whether a property is set to be configurable
       # @param [Symbol] property the property to ask status for
+      # @return [Boolean] whether the property is configurable
       #
       def configurable?(property)
-        @configurable.is_a?(Hash) && @configurable.has_key?(property)
+        @configurable.is_a?(Hash) && @configurable.key?(property)
       end
 
-      # configuration method can be used to retrieve properties from the configuration which use your gem's context
+      # configuration method can be used to retrieve properties
+      # from the configuration
+      # which use your gem's context
       # @param [Class, Symbol, Hash] method the method to define
       # @param [Proc] block the block to evaluate
-      # @example Define a configuration method 'foobararg' returning configuration properties 'foo' and 'bar' plus an argument
+      # @example Define a configuration method 'foobararg'
       #   configuration_method :foobararg do |arg|
       #     foo + bar + arg
       #   end
+      # @example Define a configuration method on a nested property
+      #   configuration_method foo: { bar: :arg } do
+      #     baz + biz
+      #   end
       #
       def configuration_method(method, &block)
-        raise ArgumentError, "can not be both a configurable property and a configuration method" if configurable?(method)
+        fail ArgumentError, "can't be configuration property and a method" if configurable?(method)
+
         @configuration_methods ||= {}
-        @configuration_methods.merge! method => block
+        method_hash = if method.is_a?(Hash)
+                        ingest_configuration_block!(method, &block)
+                      else
+                        { method => block }
+                      end
+
+        @configuration_methods.merge! method_hash
       end
 
-      # not_configured defines the behaviour when a property has not been configured
-      # This can be useful for presence validations of certain properties
-      # or behaviour for undefined properties deviating from the original behaviour
-      # @param [Proc] block the block to evaluate
+      # not_configured defines the behaviour when a property has not been
+      # configured. This can be useful for presence validations of certain
+      # properties or behaviour for undefined properties deviating from the
+      # original behaviour.
+      # @param [Array, Symbol, Hash] properties the properties to install
+      #   the callback on. If omitted, the callback will be installed on
+      #   all properties that have no specific callbacks
+      # @param [Proc] block the block to evaluate when a property
+      #   has not been configured
       # @yield [Symbol] the property that has not been configured
+      # @example Define a specific not_configured callback
+      #   not_configured :property1, property2: :property3 do |property|
+      #     raise ArgumentError, "#{property} should be configured"
+      #   end
+      # @example Define a catch-all not_configured callback
+      #   not_configured do |property|
+      #     raise StandardError, "You did not configure #{property}"
+      #   end
+      #
+      def not_configured(*properties, &block)
+        @not_configured ||= {}
+
+        if properties.empty?
+          @not_configured.default_proc = ->(h, k) { h[k] = block }
+        else
+          nested_merge_not_configured_hash(*properties, &block)
+        end
+      end
+
+      # @return the class name of the configuration class to use
       #
-      def not_configured(&block)
-        @not_configured_callback = block
+      def configuration_type
+        if @configurable.nil? || @configurable.empty?
+          :ArbitraryConfiguration
+        else
+          :StrictConfiguration
+        end
       end
 
       private
 
       # Instantiates a configurable hash from a property and a type
-      # @param [Symbol, Hash, Array] properties configurable properties, either single or nested
+      # @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
       #
@@ -118,8 +166,71 @@ module Configurations
         assertion_hash.merge! block: block if block_given?
         assertion_hash.merge! type: type if type
 
-        assertions = ([assertion_hash] * properties.size)
-        Hash[properties.zip(assertions)]
+        zip_to_hash(assertion_hash, *properties)
+      end
+
+      # Makes all values of hash point to block
+      # @param [Hash] hash the hash to modify
+      # @param [Proc] block the block to point to
+      # @return a hash with all previous values being keys pointing to block
+      #
+      def ingest_configuration_block!(hash, &block)
+        hash.each do |k, v|
+          value = if v.is_a?(Hash)
+                    ingest_configuration_block!(v, &block)
+                  else
+                    zip_to_hash(block, *Array(v))
+                  end
+
+          hash.merge! k => value
+        end
+      end
+
+      # @return a hash of configuration options with no nil values
+      #
+      def configuration_options
+        {
+          defaults: @configuration_defaults,
+          methods: @configuration_methods,
+          configurable: @configurable,
+          not_configured: @not_configured
+        }.delete_if { |_, value| value.nil? }
+      end
+
+      # merges the properties given into a not_configured hash
+      # @param [Symbol, Hash, Array] properties the properties to merge
+      # @param [Proc] block the block to point the properties to when
+      #  not configured
+      #
+      def nested_merge_not_configured_hash(*properties, &block)
+        nested = properties.last.is_a?(Hash) ? properties.pop : {}
+        nested = ingest_configuration_block!(nested, &block)
+        props = zip_to_hash(block, *properties)
+
+        @not_configured.merge! nested, &method(:configuration_deep_merge)
+        @not_configured.merge! props, &method(:configuration_deep_merge)
+      end
+
+      # Solves merge conflicts when merging
+      # @param [Symbol] key the key that conflicts
+      # @param [Anything] oldval the value of the left side of the merge
+      # @param [Anything] newval the value of the right side of the merge
+      # @return a mergable value with conflicts solved
+      #
+      def configuration_deep_merge(_key, oldval, newval)
+        if oldval.is_a?(Hash) && newval.is_a?(Hash)
+          oldval.merge(newval, &method(:configuration_deep_merge))
+        else
+          Array(oldval) + Array(newval)
+        end
+      end
+
+      # Zip a value with keys to a hash so all keys point to the value
+      # @param [Anything] value the value to point to
+      # @param [Array] keys the keys to install
+      #
+      def zip_to_hash(value, *keys)
+        Hash[keys.zip([value] * keys.size)]
       end
     end
   end