config_mapper 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a927800ba901de2ba648d012936b19b591d24c5e
-  data.tar.gz: c93aace56fd8a8a9662f547ef72e5c5f1d0a9396
+  metadata.gz: b3eceb23aa75978730fec0b82c9a01185852d056
+  data.tar.gz: 155083970129df5b800a6085957a21c98e869f1e
 SHA512:
-  metadata.gz: 5da46b8fb08d97ccfe985cb2a0da607de151f2d70167c0edd03c66a5771d9e5e24fda1a2183e58552103aa451d9016c8d45991ba87d1c3a47fc0b3e1e7b0e8e1
-  data.tar.gz: 3b40a4cc5c9049f681bbeaf17cacad8817dffd48c53b5ec46314a1e49f0410053f335feee942357b8265dbbb660468751f2de1657994af68bca3b4514399faaf
+  metadata.gz: 4c959618d4f898cc3e49c3512042c043b5b5a4b26cb7a9287e6620832fc53be5de77950fc7e7d551695c203ef8a8235a361e20db5f5d557bad0834f2e63075c1
+  data.tar.gz: 128a784d48f8933c27c83d55e754889b43f9eb6e61451ca6a4e23162e88175a6b53ad8e1a8cb27f156bac796767e6715d08b07c82f632b50433825b172842837

data/Gemfile

@@ -1,4 +1,9 @@
 source "https://rubygems.org"
 
+group :development do
+  gem "guard-rspec", :require => false
+  gem "rubocop", :require => false
+end
+
 # Specify your gem's dependencies in config_mapper.gemspec
 gemspec

data/Guardfile

@@ -0,0 +1,43 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, :cmd => "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+end

data/README.md

@@ -20,7 +20,7 @@ end
 class State
 
   def initialize
-	@position = Position.new
+    @position = Position.new
   end
 
   attr_reader :position
@@ -37,8 +37,8 @@ and wish to populate/modify it, based on plain data:
 config_data = {
   "orientation" => "North",
   "position" => {
-	"x" => 2,
-	"y" => 4
+    "x" => 2,
+    "y" => 4
   }
 }
 ```
@@ -48,7 +48,7 @@ ConfigMapper will help you out:
 ```ruby
 require 'config_mapper'
 
-errors = ConfigMapper.set(config_data, state)
+errors = ConfigMapper.configure_with(config_data, state)
 state.orientation              #=> "North"
 state.position.x               #=> 2
 ```
@@ -63,16 +63,38 @@ config_data = {
   "mary" => { "x" => 3, "y" => 5 }
 }
 
-ConfigMapper.set(config_data, positions)
+ConfigMapper.configure_with(config_data, positions)
 positions["fred"].x            #=> 2
 positions["mary"].y            #=> 5
 ```
 
+### Target object
+
+Given
+
+```ruby
+ConfigMapper.configure_with(config_data, target)
+```
+
+the `target` object is expected provide accessor-methods corresponding
+to the attributes that you want to make configurable.  For example, with:
+
+```ruby
+config_data = {
+  "orientation" => "North",
+  "position" => { "x" => 2, "y" => 4 }
+}
+```
+
+it should have a `orientiation=` method, and a `position` method that
+returns a `Position` object, which should in turn have `x=` and `y=`
+methods.
+
+ConfigMapper cannot and will not _create_ objects for you.
+
 ### Errors
 
-`ConfigMapper.set` returns a Hash of errors encountered while mapping data
-onto objects.  The errors are Exceptions (typically ArgumentError or NoMethodError),
-keyed by a Array representing the path to the offending data.  e.g.
+`ConfigMapper.configure_with` returns a Hash of errors encountered while mapping data onto objects.  The errors are Exceptions (typically ArgumentError or NoMethodError), keyed by the path to the offending data.  e.g.
 
 ```ruby
 config_data = {
@@ -81,8 +103,72 @@ config_data = {
   }
 }
 
-errors = ConfigMapper.set(config_data, state)
-errors    #=> { ["position", "bogus"] => #<NoMethodError> }
+errors = ConfigMapper.configure_with(config_data, state)
+errors    #=> { ".position.bogus" => #<NoMethodError> }
+```
+
+## ConfigStruct
+
+ConfigMapper works pretty well with plain old Ruby objects, but we
+provide a base-class, `ConfigMapper::ConfigStruct`, with a DSL that
+makes it even easier to declare configuration data-structures.
+
+```ruby
+require "config_mapper/config_struct"
+
+class State < ConfigMapper::ConfigStruct
+
+  component :position do
+    attribute(:x) { |arg| Integer(arg) }
+    attribute(:y) { |arg| Integer(arg) }
+  end
+
+  attribute :orientation
+
+end
+```
+
+By default, declared attributes are assumed to be mandatory. The
+`ConfigStruct#config_errors` method returns errors for each unset mandatory
+attribute.
+
+```ruby
+state = State.new
+state.position.x = 3
+state.position.y = 4
+state.config_errors
+#=> { ".orientation" => "no value provided" }
+```
+
+`#config_errors` can be overridden to provide custom semantic validation.
+
+Attributes can be given default values. Provide an explicit `nil` default to
+mark an attribute as optional, e.g.
+
+```ruby
+class Address < ConfigMapper::ConfigStruct
+
+  attribute :host
+  attribute :port, :default => 80
+  attribute :path, :default => nil
+
+end
+```
+
+`ConfigStruct#configure_with` maps data into the object, and combines mapping errors and
+semantic errors (returned by `#config_errors`) into a single Hash:
+
+```ruby
+data = {
+  "position" => { "x" => 3, "y" => "fore" },
+  "bogus" => "foobar"
+}
+state.configure_with(data)
+#=> {
+#=>   ".orientation" => "no value provided",
+#=>   ".position.y" => #<ArgumentError: invalid value for Integer(): "fore">,
+#=>   ".bogus" => #<NoMethodError: undefined method `bogus=' for #<State:0x007fc8e9b12a60>>
+#=> }
 ```
 
 ## License
@@ -92,3 +178,8 @@ The gem is available as open source under the terms of the [MIT License](http://
 ## Contributing
 
 It's on GitHub; you know the drill.
+
+## See also
+
+* [ConfigHound](https://github.com/mdub/config_hound) is a great way to
+  load raw config-data, before throwing it to ConfigMapper.

data/lib/config_mapper/config_struct.rb

@@ -0,0 +1,189 @@
+require "config_mapper"
+require "forwardable"
+
+module ConfigMapper
+
+  # A set of configurable attributes.
+  #
+  class ConfigStruct
+
+    class << self
+
+      # Defines reader and writer methods for the specified attribute.
+      #
+      # A `:default` value may be specified; otherwise, the attribute is
+      # considered mandatory.
+      #
+      # If a block is provided, it will invoked in the writer-method to
+      # validate the argument.
+      #
+      # @param name [Symbol] attribute name
+      # @options options [String] :default (nil) default value
+      # @yield type-coercion block
+      #
+      def attribute(name, options = {}, &coerce_block)
+        name = name.to_sym
+        if options.key?(:default)
+          default_value = options.fetch(:default).freeze
+          attribute_initializers[name] = proc { default_value }
+        else
+          required_attributes << name
+        end
+        attr_reader(name)
+        if coerce_block
+          define_method("#{name}=") do |arg|
+            instance_variable_set("@#{name}", coerce_block.call(arg))
+          end
+        else
+          attr_writer(name)
+        end
+      end
+
+      # Defines a sub-component.
+      #
+      # If a block is be provided, it will be `class_eval`ed to define the
+      # sub-components class.
+      #
+      # @param name [Symbol] component name
+      # @options options [String] :type (ConfigMapper::ConfigStruct)
+      #   component base-class
+      #
+      def component(name, options = {}, &block)
+        name = name.to_sym
+        declared_components << name
+        type = options.fetch(:type, ConfigStruct)
+        type = Class.new(type, &block) if block
+        type = type.method(:new) if type.respond_to?(:new)
+        attribute_initializers[name] = type
+        attr_reader name
+      end
+
+      # Defines an associative array of sub-components.
+      #
+      # If a block is be provided, it will be `class_eval`ed to define the
+      # sub-components class.
+      #
+      # @param name [Symbol] dictionary attribute name
+      # @options options [Proc] :key_type
+      #   function used to validate keys
+      # @options options [String] :type (ConfigMapper::ConfigStruct)
+      #   base-class for sub-component values
+      #
+      def component_dict(name, options = {}, &block)
+        name = name.to_sym
+        declared_component_dicts << name
+        type = options.fetch(:type, ConfigStruct)
+        type = Class.new(type, &block) if block
+        type = type.method(:new) if type.respond_to?(:new)
+        key_type = options[:key_type]
+        key_type = key_type.method(:new) if key_type.respond_to?(:new)
+        attribute_initializers[name] = lambda do
+          ConfigDict.new(type, key_type)
+        end
+        attr_reader name
+      end
+
+      def required_attributes
+        @required_attributes ||= []
+      end
+
+      def attribute_initializers
+        @attribute_initializers ||= {}
+      end
+
+      def declared_components
+        @declared_components ||= []
+      end
+
+      def declared_component_dicts
+        @declared_component_dicts ||= []
+      end
+
+    end
+
+    def initialize
+      self.class.attribute_initializers.each do |name, initializer|
+        instance_variable_set("@#{name}", initializer.call)
+      end
+    end
+
+    def immediate_config_errors
+      missing_required_attribute_errors
+    end
+
+    def config_errors
+      immediate_config_errors.merge(component_config_errors)
+    end
+
+    # Configure with data.
+    #
+    # @param attribute_values [Hash] attribute values
+    # @return [Hash] errors encountered, keyed by attribute path
+    #
+    def configure_with(attribute_values)
+      errors = ConfigMapper.configure_with(attribute_values, self)
+      config_errors.merge(errors)
+    end
+
+    private
+
+    def components
+      {}.tap do |result|
+        self.class.declared_components.each do |name|
+          result[".#{name}"] = instance_variable_get("@#{name}")
+        end
+        self.class.declared_component_dicts.each do |name|
+          instance_variable_get("@#{name}").each do |key, value|
+            result[".#{name}[#{key.inspect}]"] = value
+          end
+        end
+      end
+    end
+
+    NOT_SET = "no value provided".freeze
+
+    def missing_required_attribute_errors
+      {}.tap do |errors|
+        self.class.required_attributes.each do |name|
+          unless instance_variable_defined?("@#{name}")
+            errors[".#{name}"] = NOT_SET
+          end
+        end
+      end
+    end
+
+    def component_config_errors
+      {}.tap do |errors|
+        components.each do |component_name, component_value|
+          next unless component_value.respond_to?(:config_errors)
+          component_value.config_errors.each do |key, value|
+            errors["#{component_name}#{key}"] = value
+          end
+        end
+      end
+    end
+
+  end
+
+  class ConfigDict
+
+    def initialize(entry_type, key_type = nil)
+      @entry_type = entry_type
+      @key_type = key_type
+      @entries = {}
+    end
+
+    def [](key)
+      key = @key_type.call(key) if @key_type
+      @entries[key] ||= @entry_type.call
+    end
+
+    extend Forwardable
+
+    def_delegators :@entries, :each, :empty?, :keys, :map, :size
+
+    include Enumerable
+
+  end
+
+end

data/lib/config_mapper/hash_target.rb

@@ -0,0 +1,27 @@
+require "config_mapper/target"
+
+module ConfigMapper
+
+  # Configuration proxy for a Hash.
+  #
+  class HashTarget < Target
+
+    def initialize(hash)
+      @hash = hash
+    end
+
+    def path(key)
+      "[#{key.inspect}]"
+    end
+
+    def get(key)
+      @hash[key]
+    end
+
+    def set(key, value)
+      @hash[key] = value
+    end
+
+  end
+
+end

data/lib/config_mapper/object_target.rb

@@ -0,0 +1,27 @@
+require "config_mapper/target"
+
+module ConfigMapper
+
+  # Configuration proxy for an Object.
+  #
+  class ObjectTarget < Target
+
+    def initialize(object)
+      @object = object
+    end
+
+    def path(key)
+      ".#{key}"
+    end
+
+    def get(key)
+      @object.public_send(key)
+    end
+
+    def set(key, value)
+      @object.public_send("#{key}=", value)
+    end
+
+  end
+
+end

data/lib/config_mapper/target.rb

@@ -0,0 +1,39 @@
+module ConfigMapper
+
+  # Something that accepts configuration.
+  #
+  class Target
+
+    # Map configuration data onto the target.
+    #
+    # @return [Hash] exceptions encountered
+    #
+    def with(data)
+      errors = {}
+      data.each do |key, value|
+        configure_attribute(key, value, errors)
+      end
+      errors
+    end
+
+    private
+
+    # Set a single attribute.
+    #
+    def configure_attribute(key, value, errors)
+      attribute_path = path(key)
+      if value.is_a?(Hash) && !get(key).nil?
+        nested_errors = ConfigMapper.configure_with(value, get(key))
+        nested_errors.each do |nested_path, error|
+          errors["#{attribute_path}#{nested_path}"] = error
+        end
+      else
+        set(key, value)
+      end
+    rescue NoMethodError, ArgumentError => e
+      errors[attribute_path] = e
+    end
+
+  end
+
+end

data/lib/config_mapper/version.rb

@@ -1,5 +1,5 @@
 module ConfigMapper
 
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 
 end

data/lib/config_mapper.rb

@@ -1,23 +1,39 @@
-require "config_mapper/attribute_sink"
+require "config_mapper/hash_target"
+require "config_mapper/object_target"
 
 # Supports marshalling of plain-old data (e.g. loaded from
 # YAML files) onto strongly-typed objects.
 #
 module ConfigMapper
 
-  # Attempt to set attributes on a target object.
-  #
-  # For simple, scalar values, set the attribute by calling the
-  # named writer-method on the target object.
-  #
-  # For Hash values, set attributes of the named sub-component.
-  #
-  # @return [Hash] exceptions encountered
-  #
-  def self.set(data, target)
-    mapper = AttributeSink.new(target)
-    mapper.set_attributes(data)
-    mapper.errors
+  class << self
+
+    # Set attributes of a target object based on configuration data.
+    #
+    # For simple, scalar values, set the attribute by calling the
+    # named writer-method on the target object.
+    #
+    # For Hash values, set attributes of the named sub-component.
+    #
+    # @param data configuration data
+    # @param [Object, Hash] target the object to configure
+    #
+    # @return [Hash] exceptions encountered
+    #
+    def configure_with(data, target)
+      target(target).with(data)
+    end
+
+    alias_method :set, :configure_with
+
+    def target(target)
+      if target.is_a?(Hash)
+        HashTarget.new(target)
+      else
+        ObjectTarget.new(target)
+      end
+    end
+
   end
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: config_mapper
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Mike Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-04 00:00:00.000000000 Z
+date: 2016-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -64,14 +64,16 @@ files:
 - ".rubocop.yml"
 - ".travis.yml"
 - Gemfile
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - config_mapper.gemspec
 - lib/config_mapper.rb
-- lib/config_mapper/attribute_sink.rb
-- lib/config_mapper/error_proxy.rb
-- lib/config_mapper/object_as_hash.rb
+- lib/config_mapper/config_struct.rb
+- lib/config_mapper/hash_target.rb
+- lib/config_mapper/object_target.rb
+- lib/config_mapper/target.rb
 - lib/config_mapper/version.rb
 homepage: https://github.com/mdub/config_mapper
 licenses:
@@ -93,7 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.5.0
 signing_key: 
 specification_version: 4
 summary: Maps config data onto plain old objects

data/lib/config_mapper/attribute_sink.rb

@@ -1,42 +0,0 @@
-require "config_mapper/error_proxy"
-require "config_mapper/object_as_hash"
-
-module ConfigMapper
-
-  # Sets attributes on an object, collecting errors
-  #
-  class AttributeSink
-
-    def initialize(target, errors = {})
-      @target = ObjectAsHash[target]
-      @errors = errors
-    end
-
-    attr_reader :target
-    attr_reader :errors
-
-    # Set multiple attributes from a Hash.
-    #
-    def set_attributes(data)
-      data.each do |key, value|
-        set_attribute(key, value)
-      end
-    end
-
-    # Set a single attribute.
-    #
-    def set_attribute(key, value)
-      if value.is_a?(Hash) && !target[key].nil?
-        nested_errors = ErrorProxy.new(errors, [key])
-        nested_mapper = self.class.new(target[key], nested_errors)
-        nested_mapper.set_attributes(value)
-      else
-        target[key] = value
-      end
-    rescue NoMethodError, ArgumentError => e
-      errors[[key]] = e
-    end
-
-  end
-
-end

data/lib/config_mapper/error_proxy.rb

@@ -1,23 +0,0 @@
-module ConfigMapper
-
-  # Wraps a Hash of errors, injecting prefixes
-  #
-  class ErrorProxy
-
-    def initialize(errors, prefix)
-      @errors = errors
-      @prefix = prefix
-    end
-
-    def []=(key, value)
-      errors[prefix + key] = value
-    end
-
-    private
-
-    attr_reader :errors
-    attr_reader :prefix
-
-  end
-
-end

data/lib/config_mapper/object_as_hash.rb

@@ -1,29 +0,0 @@
-module ConfigMapper
-
-  # Wrap an object to make it look more like a Hash.
-  #
-  class ObjectAsHash
-
-    def self.[](target)
-      if target.is_a?(Hash)
-        target
-      else
-        ObjectAsHash.new(target)
-      end
-    end
-
-    def initialize(target)
-      @target = target
-    end
-
-    def [](key)
-      @target.public_send(key)
-    end
-
-    def []=(key, value)
-      @target.public_send("#{key}=", value)
-    end
-
-  end
-
-end