config_mapper 1.4.1 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7de0e012b37758b972449905dd89e25fff9c5f78
-  data.tar.gz: ea363b40759c5fa82e7531c088486eb535dc30f3
+  metadata.gz: 071bbe40a32e09004ef7e5a12ddc9eb909b7e06a
+  data.tar.gz: c49eff8eda1e383a3e02f72aa6c7baca0f8810c6
 SHA512:
-  metadata.gz: c4fa80171dd00dfec8c0dfc7a6f561bfe400045e01713bf928136d21ab6fe3df3fe06c212620ab16c6d8b9b5e452e3217b5fa7be52fe90fbec8031724e0f1009
-  data.tar.gz: 2fcacd97d600bb870f84ef1c8c7c9b3c991ef383db9ee6965bffb63be81d6c15de6ca461e8b8acc90fb4fababcdd9d40a67bac2647bd4127c60bc4e97b8cc282
+  metadata.gz: 8f8f2fdbf001b744b04c2ceb39c64c5df448568ea4b4e915d12060f0571c6bc2a8ad0581b27a545403066881f79a98f3f1633de2239959d90558967e2392089e
+  data.tar.gz: 51f1cffdbbccc557e8a13b7c0882b5cdaefef07d167971a79c22ffe20fc5153c37ae77c8381045c04681715514dabb8ef24e0c9b2334fef454b55a5fc3a67c89

data/README.md

@@ -1,10 +1,26 @@
 # ConfigMapper
 
-[![Gem Version](https://badge.fury.io/rb/config_mapper.png)](http://badge.fury.io/rb/config_mapper)
-[![Build Status](https://secure.travis-ci.org/mdub/config_mapper.png?branch=master)](http://travis-ci.org/mdub/config_mapper)
+[![Gem Version](https://badge.fury.io/rb/config_mapper.svg)](https://badge.fury.io/rb/config_mapper)
+[![Build Status](https://travis-ci.org/mdub/config_mapper.svg?branch=master)](https://travis-ci.org/mdub/config_mapper)
 
 ConfigMapper maps configuration data onto Ruby objects.
 
+<!-- TOC depthFrom:2 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->
+
+- [Usage](#usage)
+  - [Target object](#target-object)
+  - [Errors](#errors)
+- [ConfigStruct](#configstruct)
+  - [Attributes](#attributes)
+  - [Type validation/coercion](#type-validationcoercion)
+  - [Defaults](#defaults)
+  - [Semantic errors](#semantic-errors)
+- [License](#license)
+- [Contributing](#contributing)
+- [See also](#see-also)
+
+<!-- /TOC -->
+
 ## Usage
 
 Imagine you have some Ruby objects:
@@ -116,34 +132,65 @@ 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.
 
+### Attributes
+
+The `attribute` method is similar to `attr_accessor`, defining both reader and writer methods for the named attribute.   
+
 ```ruby
 require "config_mapper/config_struct"
 
 class State < ConfigMapper::ConfigStruct
 
-  component :position do
-    attribute :x
-    attribute :y
+  attribute :orientation
+
+end
+```
+
+### Type validation/coercion
+
+If you specify a block when declaring an attribute, it will be invoked as part of the attribute's writer-method, to validate values when they are set. It should expect a single argument, and raise `ArgumentError` to signal invalid input. As the return value will be used as the value of the attribute, it's also an opportunity coerce values into canonical form.
+
+```ruby
+class Server < ConfigMapper::ConfigStruct
+
+  attribute :host do |arg|
+    unless arg =~ /^\w+(\.\w+)+$/
+      raise ArgumentError, "invalid hostname: #{arg}"
+    end
+    arg
   end
 
-  attribute :orientation
+  attribute :port do |arg|
+    Integer(arg)
+  end
 
 end
 ```
 
-`ConfigStruct#config_errors` returns errors for each unset mandatory attribute.
+Alternatively, specify a "validator" as a second argument to `attribute`.  It should be an object that responds to `#call`, with the same semantics described above. Good choices include `Proc` or `Method` objects, or type-objects from the [dry-types](http://dry-rb.org/gems/dry-types/) project.
 
 ```ruby
-state = State.new
-state.position.x = 3
-state.position.y = 4
-state.config_errors
-#=> { ".orientation" => #<ConfigMapper::ConfigStruct::NoValueProvided: no value provided> }
+class Server < ConfigMapper::ConfigStruct
+
+  attribute :host, Types::Strict::String.constrained(format: /^\w+(\.\w+)+$/)
+  attribute :port, method(:Integer)
+
+end
 ```
 
-`#config_errors` can be overridden to provide custom semantic validation.
+For convenience, primitive Ruby types such as `Integer` and `Float` can be used as shorthand for their namesake type-coercion methods on `Kernel`:
 
-Attributes can be given default values. Specify a default value of `nil` to mark an attribute as optional, e.g.
+```ruby
+class Server < ConfigMapper::ConfigStruct
+
+  attribute :port, Integer
+
+end
+```
+
+### Defaults
+
+Attributes can be given default values, e.g.
 
 ```ruby
 class Address < ConfigMapper::ConfigStruct
@@ -153,25 +200,37 @@ class Address < ConfigMapper::ConfigStruct
 end
 ```
 
-If a block is provided when an `attribute` is declared, it is used to validate values when they are set, and/or coerce them to a canonical type.  The block should raise `ArgumentError` to indicate an invalid value.
+Specify a default value of `nil` to mark an attribute as optional. Attributes without a default are treated as "required".
 
-```ruby
-class Server < ConfigMapper::ConfigStruct
+### Sub-components
 
-  attribute :host do |arg|
-    unless arg =~ /^\w+(\.\w+)+$/
-      raise ArgumentError, "invalid hostname: #{arg}"
-    end
-    arg
-  end
+The `component` method defines a nested component object, itself a `ConfigStruct`.  
 
-  attribute :port do |arg|
-    Integer(arg)
+```ruby
+class State < ConfigMapper::ConfigStruct
+
+  component :position do
+    attribute :x
+    attribute :y
   end
 
 end
 ```
 
+### Semantic errors
+
+`ConfigStruct#config_errors` returns errors for each unset mandatory attribute.
+
+```ruby
+state = State.new
+state.position.x = 3
+state.position.y = 4
+state.config_errors
+#=> { ".orientation" => #<ConfigMapper::ConfigStruct::NoValueProvided: no value provided> }
+```
+
+`#config_errors` can be overridden to provide custom semantic validation.
+
 `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/lib/config_mapper/config_dict.rb

@@ -1,18 +1,45 @@
+require "config_mapper/factory"
+require "config_mapper/validator"
 require "forwardable"
 
 module ConfigMapper
 
   class ConfigDict
 
-    def initialize(entry_type, key_type = nil)
-      @entry_type = entry_type
-      @key_type = key_type
+    class Factory
+
+      def initialize(entry_factory, key_validator)
+        @entry_factory = ConfigMapper::Factory.resolve(entry_factory)
+        @key_validator = ConfigMapper::Validator.resolve(key_validator)
+      end
+
+      attr_reader :entry_factory
+      attr_reader :key_validator
+
+      def new
+        ConfigDict.new(@entry_factory, @key_validator)
+      end
+
+      def config_doc
+        return {} unless entry_factory.respond_to?(:config_doc)
+        {}.tap do |result|
+          entry_factory.config_doc.each do |path, doc|
+            result["[X]#{path}"] = doc
+          end
+        end
+      end
+
+    end
+
+    def initialize(entry_factory, key_validator = nil)
+      @entry_factory = entry_factory
+      @key_validator = key_validator
       @entries = {}
     end
 
     def [](key)
-      key = @key_type.call(key) if @key_type
-      @entries[key] ||= @entry_type.call
+      key = @key_validator.call(key) if @key_validator
+      @entries[key] ||= @entry_factory.new
     end
 
     def to_h
@@ -23,6 +50,18 @@ module ConfigMapper
       end
     end
 
+    def config_errors
+      {}.tap do |errors|
+        each do |key, value|
+          prefix = "[#{key.inspect}]"
+          next unless value.respond_to?(:config_errors)
+          value.config_errors.each do |path, path_errors|
+            errors["#{prefix}#{path}"] = path_errors
+          end
+        end
+      end
+    end
+
     extend Forwardable
 
     def_delegators :@entries, :each, :empty?, :key?, :keys, :map, :size

data/lib/config_mapper/config_struct.rb

@@ -1,5 +1,7 @@
 require "config_mapper"
 require "config_mapper/config_dict"
+require "config_mapper/factory"
+require "config_mapper/validator"
 
 module ConfigMapper
 
@@ -18,28 +20,31 @@ module ConfigMapper
       # validate the argument.
       #
       # @param name [Symbol] attribute name
-      # @options options [String] :default (nil) default value
+      # @param default default value
       # @yield type-coercion block
       #
-      def attribute(name, options = {})
-        name = name.to_sym
-        required = true
-        default_value = nil
-        if options.key?(:default)
-          default_value = options.fetch(:default).freeze
-          required = false if default_value.nil?
+      def attribute(name, type = nil, default: :no_default, description: nil, &type_block)
+
+        attribute = attribute!(name)
+        attribute.description = description
+
+        if default == :no_default
+          attribute.required = true
+        else
+          attribute.default = default.freeze
         end
-        attribute_initializers[name] = proc { default_value }
-        required_attributes << name if required
-        attr_reader(name)
-        define_method("#{name}=") do |value|
+
+        attribute.validator = Validator.resolve(type || type_block)
+
+        define_method("#{attribute.name}=") do |value|
           if value.nil?
-            raise NoValueProvided if required
+            raise NoValueProvided if attribute.required
           else
-            value = yield(value) if block_given?
+            value = attribute.validator.call(value) if attribute.validator
           end
-          instance_variable_set("@#{name}", value)
+          instance_variable_set("@#{attribute.name}", value)
         end
+
       end
 
       # Defines a sub-component.
@@ -48,17 +53,13 @@ module ConfigMapper
       # sub-components class.
       #
       # @param name [Symbol] component name
-      # @options options [String] :type (ConfigMapper::ConfigStruct)
-      #   component base-class
+      # @param type [Class] component base-class
       #
-      def component(name, options = {}, &block)
-        name = name.to_sym
-        declared_components << name
-        type = options.fetch(:type, ConfigStruct)
+      def component(name, type: ConfigStruct, description: nil, &block)
         type = Class.new(type, &block) if block
-        type = type.method(:new) if type.respond_to?(:new)
-        attribute_initializers[name] = type
-        attr_reader name
+        attribute = attribute!(name)
+        attribute.description = description
+        attribute.factory = type
       end
 
       # Defines an associative array of sub-components.
@@ -67,53 +68,53 @@ module ConfigMapper
       # 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
+      # @param type [Class] base-class for component values
+      # @param key_type [Proc] function used to validate keys
       #
-      def component_dict(name, options = {}, &block)
-        name = name.to_sym
-        declared_component_dicts << name
-        type = options.fetch(:type, ConfigStruct)
+      def component_dict(name, type: ConfigStruct, key_type: nil, description: nil, &block)
         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
+        component(name, type: ConfigDict::Factory.new(type, key_type), description: description)
       end
 
-      def required_attributes
-        @required_attributes ||= []
+      # Generate documentation, as Ruby data.
+      #
+      # Returns an entry for each configurable path, detailing
+      # `description`, `type`, and `default`.
+      #
+      # @return [Hash] documentation, keyed by path
+      #
+      def config_doc
+        each_attribute.sort_by(&:name).map(&:config_doc).inject({}, :merge)
       end
 
-      def attribute_initializers
-        @attribute_initializers ||= {}
+      def attributes
+        attributes_by_name.values
       end
 
-      def declared_components
-        @declared_components ||= []
+      def each_attribute(&action)
+        return enum_for(:each_attribute) unless action
+        ancestors.each do |klass|
+          next unless klass.respond_to?(:attributes)
+          klass.attributes.each(&action)
+        end
       end
 
-      def declared_component_dicts
-        @declared_component_dicts ||= []
+      private
+
+      def attributes_by_name
+        @attributes_by_name ||= {}
       end
 
-      def for_all(attribute, &action)
-        ancestors.each do |klass|
-          next unless klass.respond_to?(attribute)
-          klass.public_send(attribute).each(&action)
-        end
+      def attribute!(name)
+        attr_reader(name)
+        attributes_by_name[name] ||= Attribute.new(name)
       end
 
     end
 
     def initialize
-      self.class.for_all(:attribute_initializers) do |name, initializer|
-        instance_variable_set("@#{name}", initializer.call)
+      self.class.each_attribute do |attribute|
+        instance_variable_set("@#{attribute.name}", attribute.initial_value)
       end
     end
 
@@ -141,12 +142,12 @@ module ConfigMapper
     #
     def to_h
       {}.tap do |result|
-        self.class.for_all(:attribute_initializers) do |attr_name, _|
-          value = send(attr_name)
+        self.class.each_attribute do |attribute|
+          value = send(attribute.name)
           if value && value.respond_to?(:to_h) && !value.is_a?(Array)
             value = value.to_h
           end
-          result[attr_name.to_s] = value
+          result[attribute.name.to_s] = value
         end
       end
     end
@@ -155,13 +156,9 @@ module ConfigMapper
 
     def components
       {}.tap do |result|
-        self.class.for_all(:declared_components) do |name|
-          result[".#{name}"] = instance_variable_get("@#{name}")
-        end
-        self.class.for_all(:declared_component_dicts) do |name|
-          instance_variable_get("@#{name}").each do |key, value|
-            result[".#{name}[#{key.inspect}]"] = value
-          end
+        self.class.each_attribute do |a|
+          next unless a.factory
+          result[".#{a.name}"] = instance_variable_get("@#{a.name}")
         end
       end
     end
@@ -176,9 +173,9 @@ module ConfigMapper
 
     def missing_required_attribute_errors
       {}.tap do |errors|
-        self.class.for_all(:required_attributes) do |name|
-          if instance_variable_get("@#{name}").nil?
-            errors[".#{name}"] = NoValueProvided.new
+        self.class.each_attribute do |a|
+          if a.required && instance_variable_get("@#{a.name}").nil?
+            errors[".#{a.name}"] = NoValueProvided.new
           end
         end
       end
@@ -186,13 +183,61 @@ module ConfigMapper
 
     def component_config_errors
       {}.tap do |errors|
-        components.each do |component_name, component_value|
+        components.each do |component_path, component_value|
           next unless component_value.respond_to?(:config_errors)
-          component_value.config_errors.each do |key, value|
-            errors["#{component_name}#{key}"] = value
+          component_value.config_errors.each do |path, value|
+            errors["#{component_path}#{path}"] = value
+          end
+        end
+      end
+    end
+
+    class Attribute
+
+      def initialize(name)
+        @name = name.to_sym
+      end
+
+      attr_reader :name
+
+      attr_accessor :description
+      attr_accessor :factory
+      attr_accessor :validator
+      attr_accessor :default
+      attr_accessor :required
+
+      def initial_value
+        return factory.new if factory
+        default
+      end
+
+      def factory=(arg)
+        @factory = Factory.resolve(arg)
+      end
+
+      def config_doc
+        self_doc.merge(type_doc)
+      end
+
+      private
+
+      def self_doc
+        {
+          ".#{name}" => {}.tap do |doc|
+            doc["description"] = description if description
+            doc["default"] = default if default
+            doc["type"] = String(validator.name) if validator.respond_to?(:name)
           end
+        }
+      end
+
+      def type_doc
+        return {} unless factory.respond_to?(:config_doc)
+        factory.config_doc.each_with_object({}) do |(path, doc), result|
+          result[".#{name}#{path}"] = doc
         end
       end
+
     end
 
   end

data/lib/config_mapper/factory.rb

@@ -0,0 +1,25 @@
+module ConfigMapper
+
+  module Factory
+
+    def self.resolve(arg)
+      return arg if arg.respond_to?(:new)
+      return ProcFactory.new(arg) if arg.respond_to?(:call)
+      raise ArgumentError, "invalid factory"
+    end
+
+  end
+
+  class ProcFactory
+
+    def initialize(f)
+      @f = f
+    end
+
+    def new
+      @f.call
+    end
+
+  end
+
+end

data/lib/config_mapper/validator.rb

@@ -0,0 +1,16 @@
+module ConfigMapper
+
+  module Validator
+
+    def self.resolve(arg)
+      return arg if arg.respond_to?(:call)
+      if arg.respond_to?(:name)
+        # looks like a primitive class -- find the corresponding coercion method
+        return Kernel.method(arg.name)
+      end
+      arg
+    end
+
+  end
+
+end

data/lib/config_mapper/version.rb

@@ -1,5 +1,5 @@
 module ConfigMapper
 
-  VERSION = "1.4.1".freeze
+  VERSION = "1.5.0".freeze
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: config_mapper
 version: !ruby/object:Gem::Version
-  version: 1.4.1
+  version: 1.5.0
 platform: ruby
 authors:
 - Mike Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-07-04 00:00:00.000000000 Z
+date: 2017-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -65,8 +65,10 @@ files:
 - lib/config_mapper/collection_mapper.rb
 - lib/config_mapper/config_dict.rb
 - lib/config_mapper/config_struct.rb
+- lib/config_mapper/factory.rb
 - lib/config_mapper/mapper.rb
 - lib/config_mapper/object_mapper.rb
+- lib/config_mapper/validator.rb
 - lib/config_mapper/version.rb
 homepage: https://github.com/mdub/config_mapper
 licenses:
@@ -80,7 +82,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="