configurations 1.3.5 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 91fb60bb5d9360f44127b6fe04e9ee5a44fc8cc4
-  data.tar.gz: f6954851568a3a8dc02abb41867391ac9e83133d
+  metadata.gz: 2589e2f8682eac2622c16993dc89aab75f8d0835
+  data.tar.gz: 95c59f8d0f29f2c7cddb2a10dfbfdfa601c11989
 SHA512:
-  metadata.gz: e5e0337c82a36aecf0716baaad50605372f31048ae57cfcea910a5946e6e7a04b6345ce08b851fe08c9721b80ac958f9b15c94d7573a1f4b027ec3f0be7cafb9
-  data.tar.gz: 513d1a3804e612121dde365f0966edc22120b6d5ce7f17c8d173c14751d9de0967934111a05922afdf86770b16b1853b650b970bac3ce2f299bf83ace3c32ca3
+  metadata.gz: 7d59363609ad7d37bb56a596de502e59eaddbd60dc6e9138bd7f09650e768e6c61f8d22d81191dadf620ac0ce6fe40a2dcaac8ccd6d2971b1f0d6178a7cebc42
+  data.tar.gz: 45603cd9f38b71a9e1086c2b0486f29f089377de972c2b96dbaa7f57d819291f9c677104d8b4b5883b27c5aaff31e2c22031499c54a5b9c05a2ee0647ec1dff3

data/README.md

@@ -10,7 +10,7 @@ Configurations provides a unified approach to do configurations using the `MyGem
 
 or with Bundler
 
-`gem 'configurations', '~> 1.0.0'`
+`gem 'configurations', '~> 1.4.0'`
 
 Configurations uses [Semver 2.0](http://semver.org/)
 
@@ -204,6 +204,19 @@ end
 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.
+
+```
+yaml_hash = YAML.load_file('configuration.yml')
+
+MyGem.configure do |c|
+  c.foo = 'bar'
+  c.baz.from_h(yaml_hash)
+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.

data/lib/configurations.rb

@@ -12,5 +12,5 @@ module Configurations
 
   # Version number of Configurations
   #
-  VERSION = '1.3.5'
+  VERSION = '1.4.0'
 end

data/lib/configurations/configurable.rb

@@ -21,6 +21,10 @@ module Configurations
           # 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?
@@ -50,6 +54,14 @@ module Configurations
       # 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)
+      #   end
       #
       def configurable(*properties, &block)
         type = properties.shift if properties.first.is_a?(Class)
@@ -65,8 +77,12 @@ module Configurations
       end
 
       # configuration method can be used to retrieve properties from the configuration which use your gem's context
-      # @param [Class, Symbol, Hash] properties properties for retrieval
+      # @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
+      #   configuration_method :foobararg do |arg|
+      #     foo + bar + arg
+      #   end
       #
       def configuration_method(method, &block)
         raise ArgumentError, "#{method} can not be both a configurable property and a configuration method" if configurable?(method)

data/lib/configurations/configuration.rb

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 module Configurations
   # Configuration is a blank object in order to allow configuration of various properties including keywords
   #
@@ -14,7 +15,7 @@ module Configurations
             :instance_of?, :kind_of?, :tap, :send, :public_send, :respond_to?, :respond_to_missing?, :extend,
             :display, :method, :public_method, :define_singleton_method, :to_enum, :enum_for
     else
-      # @!macro [attach] install_kernel_method
+      # @macro [attach] install_kernel_method
       # @method $1
       #
       def self.install_kernel_method(method)
@@ -100,6 +101,23 @@ module Configurations
       end
     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
+    #
+    def from_h(h)
+      raise ArgumentError, 'can not dynamically assign values from a hash' unless @_writeable
+
+      h.each do |property, value|
+        if value.is_a?(::Hash) && _nested?(property)
+          @configuration[property].from_h(value)
+        elsif _configurable?(property)
+          _assign!(property, value)
+        end
+      end
+    end
+
     # @param [Symbol] property The property to test for configurability
     # @return [Boolean] whether the given property is configurable
     #
@@ -152,7 +170,7 @@ module Configurations
 
     # @param [Symbol, Hash, Array] property configurable properties, either single or nested
     # @param [Symbol, Hash, Array] value configurable properties, either single or nested
-    # @param [Hash] assertions if any
+    # @param [Hash] assertion assertion if any
     # @return a hash with configurable values pointing to their types
     #
     def _configurable_hash(property, value, assertion)
@@ -205,6 +223,13 @@ module Configurations
       @configurable and @configurable.has_key?(property) and @configurable[property].is_a?(::Hash) and @configurable[property].has_key?(evaluation)
     end
 
+    # @param [Symbol] property The property to test for
+    # @return [Boolean] whether this property is nested
+    #
+    def _nested?(property)
+      _arbitrarily_configurable? or @configuration.has_key?(property) and @configuration[property].is_a?(Configuration)
+    end
+
     # @param [Symbol] method the method to test for
     # @return [Boolean] whether the given method is a writer
     #

data/test/configurations/test_configuration.rb

@@ -40,25 +40,29 @@ class TestConfiguration < Minitest::Test
   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)
+    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_configuration_from_h
+    old_to_h = @configuration.to_h.dup
+    assert_equal(old_to_h, ConfigurationTestModule.configure{ |c| c.from_h(old_to_h) }.to_h)
   end
 
   def test_not_configurable_unless_block_given

data/test/configurations/test_stricter_configuration.rb

@@ -55,6 +55,38 @@ class TestStricterConfiguration < Minitest::Test
     end
   end
 
+  def test_strict_configuration_to_h
+    assert_equal({
+                   property4: {
+                     property5: :something,
+                     property12: 12
+                   },
+                   property6: {
+                     property7: :anything,
+                     property8: :everything,
+                     property14: 555
+                   }, 
+                   property9: {
+                     property10: {
+                       property11: {
+                         property12: %w(here I am), 
+                         property13: {
+                           hi: :bye
+                         }
+                       }
+                     }
+                   }, 
+                   property1: 'BASIC1',
+                   property2: 'BASIC2',
+                   property3: 'STRING'
+                 }, @configuration.to_h)
+  end
+
+  def test_strict_configuration_from_h
+    old_to_h = @configuration.to_h.dup
+    assert_equal(old_to_h, StrictConfigurationTestModule.configure{ |c| c.from_h(old_to_h) }.to_h)
+  end
+
   def test_configurable_with_same_key_when_set_nested_configurable
     assert_equal :anything, @configuration.property6.property7
     assert_equal :everything, @configuration.property6.property8

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: configurations
 version: !ruby/object:Gem::Version
-  version: 1.3.5
+  version: 1.4.0
 platform: ruby
 authors:
 - Beat Richartz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-18 00:00:00.000000000 Z
+date: 2014-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest