dry-configurable 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38b75c91290021054add38bdd9e3313f17aa133e219330a9b02a83227abd101c
-  data.tar.gz: 4b808bd3880c35e2e80a702e4577f2b2da35ef2b31667f4314accc3cf0c20470
+  metadata.gz: 0b1292743d03212bcca735f18e876046b27cb3859a561a9b714704627542a324
+  data.tar.gz: 5d9f334008b7d055bbcbadf21feb61dbef8888ed01cc877e54cd7f5959b46f48
 SHA512:
-  metadata.gz: efdd98ed5f60acf8090296954942f01c21702c29fa60c1edea21e0fbbb185955963b268191cb042ee33cc4651f4350419e7cbc2b7125c36103dce2733d137fa4
-  data.tar.gz: 21d278a4f9f4a90d530145408585c30e004ce2830d5777a408bd9ea83bdfd5cba2ce58f1a1ca46f1212d0e8d5967891a25467f39e59a8af20291cf5ca1beff3f
+  metadata.gz: 1b9bbe538bd93cc27e87e7e97a83bd1f98757d776d215028b88bb8d8b085a2114c53b7f4e3ad1d77ae70b21d99652a7bbe65d978106f897e784374456cb615db
+  data.tar.gz: 9fdeb06faf9888965037a364560c10364342731e7c825d56d4fd1cdeeb929992e201ef1f6fb3b14d4fb68ee037588e3a064a8f2236588d0417599e55df7a6a89

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 <!--- DO NOT EDIT THIS FILE - IT'S AUTOMATICALLY GENERATED VIA DEVTOOLS --->
 
+## 0.13.0 2021-09-12
+
+
+### Added
+
+- Added flags to determine whether to warn on the API usage deprecated in this release (see "Changed" section below). Set these to `false` to suppress the warnings. (#124 by @timriley)
+
+  ```ruby
+  Dry::Configurable.warn_on_setting_constructor_block = false
+  Dry::Configurable.warn_on_setting_positional_default = false
+  ```
+
+### Fixed
+
+- Fixed `ArgumentError` for classes including `Dry::Configurable` whose `initializer` has required kwargs. (#113 by @timriley)
+
+### Changed
+
+- Deprecated the setting constructor provided as a block. Provide it via the `constructor:` keyword argument instead. (#111 by @waiting-for-dev & @timriley)
+
+  ```ruby
+  setting :path, constructor: -> path { Pathname(path) }
+  ```
+- Deprecated the setting default provided as the second positional argument. Provide it via the `default:` keyword argument instead. (#112 and #121 by @waiting-for-dev & @timriley)
+
+  ```ruby
+  setting :path, default: "some/default/path"
+  ```
+- [BREAKING] Removed implicit `to_hash` conversion from `Config`. (#114 by @timriley)
+
+[Compare v0.12.1...v0.13.0](https://github.com/dry-rb/dry-configurable/compare/v0.12.1...v0.13.0)
+
 ## 0.12.1 2021-02-15
 
 

data/README.md

@@ -1,3 +1,4 @@
+<!--- this file is synced from dry-rb/template-gem project -->
 [gem]: https://rubygems.org/gems/dry-configurable
 [actions]: https://github.com/dry-rb/dry-configurable/actions
 [codacy]: https://www.codacy.com/gh/dry-rb/dry-configurable
@@ -7,22 +8,22 @@
 # dry-configurable [![Join the chat at https://dry-rb.zulipchat.com](https://img.shields.io/badge/dry--rb-join%20chat-%23346b7a.svg)][chat]
 
 [![Gem Version](https://badge.fury.io/rb/dry-configurable.svg)][gem]
-[![CI Status](https://github.com/dry-rb/dry-configurable/workflows/ci/badge.svg)][actions]
+[![CI Status](https://github.com/dry-rb/dry-configurable/workflows/CI/badge.svg)][actions]
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/0276a97990e04eb0ac722b3e7f3620b5)][codacy]
 [![Codacy Badge](https://api.codacy.com/project/badge/Coverage/0276a97990e04eb0ac722b3e7f3620b5)][codacy]
 [![Inline docs](http://inch-ci.org/github/dry-rb/dry-configurable.svg?branch=master)][inchpages]
 
 ## Links
 
-* [User documentation](http://dry-rb.org/gems/dry-configurable)
+* [User documentation](https://dry-rb.org/gems/dry-configurable)
 * [API documentation](http://rubydoc.info/gems/dry-configurable)
 
 ## Supported Ruby versions
 
 This library officially supports the following Ruby versions:
 
-* MRI >= `2.5`
-* jruby >= `9.2`
+* MRI `>= 2.6.0`
+* ~~jruby~~ `>= 9.3` (we are waiting for [2.6 support](https://github.com/jruby/jruby/issues/6161))
 
 ## License
 

data/dry-configurable.gemspec

@@ -1,35 +1,36 @@
 # frozen_string_literal: true
-# this file is managed by dry-rb/devtools project
 
-lib = File.expand_path('lib', __dir__)
+# this file is synced from dry-rb/template-gem project
+
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'dry/configurable/version'
+require "dry/configurable/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = 'dry-configurable'
+  spec.name          = "dry-configurable"
   spec.authors       = ["Andy Holland"]
   spec.email         = ["andyholland1991@aol.com"]
-  spec.license       = 'MIT'
+  spec.license       = "MIT"
   spec.version       = Dry::Configurable::VERSION.dup
 
   spec.summary       = "A mixin to add configuration functionality to your classes"
   spec.description   = spec.summary
-  spec.homepage      = 'https://dry-rb.org/gems/dry-configurable'
+  spec.homepage      = "https://dry-rb.org/gems/dry-configurable"
   spec.files         = Dir["CHANGELOG.md", "LICENSE", "README.md", "dry-configurable.gemspec", "lib/**/*"]
-  spec.bindir        = 'bin'
+  spec.bindir        = "bin"
   spec.executables   = []
-  spec.require_paths = ['lib']
+  spec.require_paths = ["lib"]
 
-  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
-  spec.metadata['changelog_uri']     = 'https://github.com/dry-rb/dry-configurable/blob/master/CHANGELOG.md'
-  spec.metadata['source_code_uri']   = 'https://github.com/dry-rb/dry-configurable'
-  spec.metadata['bug_tracker_uri']   = 'https://github.com/dry-rb/dry-configurable/issues'
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["changelog_uri"]     = "https://github.com/dry-rb/dry-configurable/blob/master/CHANGELOG.md"
+  spec.metadata["source_code_uri"]   = "https://github.com/dry-rb/dry-configurable"
+  spec.metadata["bug_tracker_uri"]   = "https://github.com/dry-rb/dry-configurable/issues"
 
-  spec.required_ruby_version = ">= 2.5.0"
+  spec.required_ruby_version = ">= 2.6.0"
 
   # to update dependencies edit project.yml
   spec.add_runtime_dependency "concurrent-ruby", "~> 1.0"
-  spec.add_runtime_dependency "dry-core", "~> 0.5", ">= 0.5.0"
+  spec.add_runtime_dependency "dry-core", "~> 0.6"
 
   spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake"

data/lib/dry/configurable/class_methods.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require 'set'
+require "set"
 
-require 'dry/configurable/constants'
-require 'dry/configurable/dsl'
-require 'dry/configurable/methods'
-require 'dry/configurable/settings'
+require "dry/configurable/constants"
+require "dry/configurable/dsl"
+require "dry/configurable/methods"
+require "dry/configurable/settings"
 
 module Dry
   module Configurable
@@ -18,25 +18,27 @@ module Dry
 
         parent_settings = (respond_to?(:config) ? config._settings : _settings)
 
-        klass.instance_variable_set('@_settings', parent_settings)
+        klass.instance_variable_set("@_settings", parent_settings)
       end
 
       # Add a setting to the configuration
       #
-      # @param [Mixed] key
+      # @param [Mixed] name
       #   The accessor key for the configuration value
       # @param [Mixed] default
-      #   The default config value
-      #
+      #   Default value for the setting
+      # @param [#call] constructor
+      #   Transformation given value will go through
+      # @param [Boolean] reader
+      #   Whether a reader accessor must be created
       # @yield
-      #   If a block is given, it will be evaluated in the context of
-      #   a new configuration class, and bound as the default value
+      #   A block can be given to add nested settings.
       #
       # @return [Dry::Configurable::Config]
       #
       # @api public
-      def setting(*args, &block)
-        setting = __config_dsl__.setting(*args, &block)
+      def setting(*args, **options, &block)
+        setting = __config_dsl__.setting(*args, **options, &block)
 
         _settings << setting
 
@@ -74,7 +76,7 @@ module Dry
 
       # @api private
       def __config_dsl__
-        @dsl ||= DSL.new
+        @__config_dsl__ ||= DSL.new
       end
 
       # @api private

data/lib/dry/configurable/compiler.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'dry/configurable/setting'
-require 'dry/configurable/settings'
+require "dry/configurable/setting"
+require "dry/configurable/settings"
 
 module Dry
   module Configurable
@@ -23,16 +23,10 @@ module Dry
         public_send(:"visit_#{type}", rest)
       end
 
-      # @api private
-      def visit_constructor(node)
-        setting, constructor = node
-        visit(setting).with(constructor: constructor)
-      end
-
       # @api private
       def visit_setting(node)
-        name, default, opts = node
-        Setting.new(name, **opts, default: default)
+        name, opts = node
+        Setting.new(name, **opts)
       end
 
       # @api private

data/lib/dry/configurable/config.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require 'concurrent/map'
+require "concurrent/map"
 
-require 'dry/core/equalizer'
+require "dry/core/equalizer"
 
-require 'dry/configurable/constants'
-require 'dry/configurable/errors'
+require "dry/configurable/constants"
+require "dry/configurable/errors"
 
 module Dry
   module Configurable
@@ -79,7 +79,6 @@ module Dry
           .to_h
       end
       alias_method :to_h, :values
-      alias_method :to_hash, :values
 
       # @api private
       def finalize!
@@ -106,7 +105,7 @@ module Dry
         super unless setting
 
         if setting.writer?(meth)
-          raise FrozenConfig, 'Cannot modify frozen config' if frozen?
+          raise FrozenConfig, "Cannot modify frozen config" if frozen?
 
           _settings << setting.with(input: args[0])
         else
@@ -116,7 +115,7 @@ module Dry
 
       # @api private
       def resolve(meth)
-        _resolved.fetch(meth) { _resolved[meth] = meth.to_s.tr('=', '').to_sym }
+        _resolved.fetch(meth) { _resolved[meth] = meth.to_s.tr("=", "").to_sym }
       end
 
       # @api private

data/lib/dry/configurable/constants.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'dry/core/constants'
+require "dry/core/constants"
 
 module Dry
   # Shared constants

data/lib/dry/configurable/dsl.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
-require 'dry/configurable/constants'
-require 'dry/configurable/setting'
-require 'dry/configurable/settings'
-require 'dry/configurable/compiler'
-require 'dry/configurable/dsl/args'
+require "dry/configurable/constants"
+require "dry/configurable/flags"
+require "dry/configurable/setting"
+require "dry/configurable/settings"
+require "dry/configurable/compiler"
+require "dry/core/deprecations"
 
 module Dry
   module Configurable
@@ -27,36 +28,137 @@ module Dry
         instance_exec(&block) if block
       end
 
-      # Register a new setting node and compile it into a setting object
+      # Registers a new setting node and compile it into a setting object
       #
       # @see ClassMethods.setting
-      # @api public
+      # @api private
       # @return Setting
-      def setting(name, *args, &block)
+      def setting(name, default = Undefined, **options, &block) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         unless VALID_NAME.match?(name.to_s)
           raise ArgumentError, "#{name} is not a valid setting name"
         end
 
-        args = Args.new(args)
+        if default != Undefined
+          if Dry::Configurable.warn_on_setting_positional_default
+            Dry::Core::Deprecations.announce(
+              "default value as positional argument to settings",
+              "Provide a `default:` keyword argument instead",
+              tag: "dry-configurable",
+              uplevel: 2
+            )
+          end
 
-        args.ensure_valid_options
+          options = options.merge(default: default)
+        end
 
-        default, opts = args
+        if RUBY_VERSION < "3.0" &&
+           default == Undefined &&
+           (valid_opts, invalid_opts = valid_and_invalid_options(options)) &&
+           invalid_opts.any? &&
+           valid_opts.none?
+          # In Ruby 2.6 and 2.7, when a hash is given as the second positional argument
+          # (i.e. the hash is intended to be the setting's default value), and there are
+          # no other keyword arguments given, the hash is assigned to the `options`
+          # variable instead of `default`.
+          #
+          # For example, for this setting:
+          #
+          #   setting :hash_setting, {my_hash: true}
+          #
+          # We'll have a `default` of `Undefined` and an `options` of `{my_hash: true}`
+          #
+          # If any additional keyword arguments are provided, e.g.:
+          #
+          #   setting :hash_setting, {my_hash: true}, reader: true
+          #
+          # Then we'll have a `default` of `{my_hash: true}` and an `options` of `{reader:
+          # true}`, which is what we want.
+          #
+          # To work around that first case and ensure our (deprecated) backwards
+          # compatibility holds for Ruby 2.6 and 2.7, we extract all invalid options from
+          # `options`, and if there are no remaining valid options (i.e. if there were no
+          # keyword arguments given), then we can infer the invalid options to be a
+          # default hash value for the setting.
+          #
+          # This approach also preserves the behavior of raising an ArgumentError when a
+          # distinct hash is _not_ intentionally provided as the second positional
+          # argument (i.e. it's not enclosed in braces), and instead invalid keyword
+          # arguments are given alongside valid ones. So this setting:
+          #
+          #   setting :some_setting, invalid_option: true, reader: true
+          #
+          # Would raise an ArgumentError as expected.
+          #
+          # However, the one case we can't catch here is when invalid options are supplied
+          # without hash literal braces, but there are no other keyword arguments
+          # supplied. In this case, a setting like:
+          #
+          #   setting :hash_setting, my_hash: true
+          #
+          # Is parsed identically to the first case described above:
+          #
+          #   setting :hash_setting, {my_hash: true}
+          #
+          # So in both of these cases, the default value will become `{my_hash: true}`. We
+          # consider this unlikely to be a problem in practice, since users are not likely
+          # to be providing invalid options to `setting` and expecting them to be ignored.
+          # Additionally, the deprecation messages will make the new behavior obvious, and
+          # encourage the users to upgrade their setting definitions.
 
-        node = [:setting, [name.to_sym, default, opts == default ? EMPTY_HASH : opts]]
+          if Dry::Configurable.warn_on_setting_positional_default
+            Dry::Core::Deprecations.announce(
+              "default value as positional argument to settings",
+              "Provide a `default:` keyword argument instead",
+              tag: "dry-configurable",
+              uplevel: 2
+            )
+          end
 
-        if block
-          if block.arity.zero?
-            ast << [:nested, [node, DSL.new(&block).ast]]
-          else
-            ast << [:constructor, [node, block]]
+          options = {default: invalid_opts}
+        end
+
+        if block && !block.arity.zero?
+          if Dry::Configurable.warn_on_setting_constructor_block
+            Dry::Core::Deprecations.announce(
+              "passing a constructor as a block",
+              "Provide a `constructor:` keyword argument instead",
+              tag: "dry-configurable",
+              uplevel: 2
+            )
           end
+
+          options = options.merge(constructor: block)
+          block = nil
+        end
+
+        ensure_valid_options(options)
+
+        node = [:setting, [name.to_sym, options]]
+
+        if block
+          ast << [:nested, [node, DSL.new(&block).ast]]
         else
           ast << node
         end
 
         compiler.visit(ast.last)
       end
+
+      private
+
+      def ensure_valid_options(options)
+        return if options.none?
+
+        invalid_keys = options.keys - Setting::OPTIONS
+
+        raise ArgumentError, "Invalid options: #{invalid_keys.inspect}" unless invalid_keys.empty?
+      end
+
+      # Returns a tuple of valid and invalid options hashes derived from the options hash
+      # given to the setting
+      def valid_and_invalid_options(options)
+        options.partition { |k, _| Setting::OPTIONS.include?(k) }.map(&:to_h)
+      end
     end
   end
 end

data/lib/dry/configurable/flags.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "dry/core/class_attributes"
+
+module Dry
+  module Configurable
+    extend Core::ClassAttributes
+
+    # Set to false to suppress deprecation warning when a setting default is provided as a
+    # positional argument
+    defines :warn_on_setting_positional_default
+    warn_on_setting_positional_default true
+
+    # Set to false to suppress deprecation warning when a setting constructor is provided
+    # as a block
+    defines :warn_on_setting_constructor_block
+    warn_on_setting_constructor_block true
+  end
+end

data/lib/dry/configurable/instance_methods.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'dry/configurable/config'
-require 'dry/configurable/methods'
+require "dry/configurable/config"
+require "dry/configurable/methods"
 
 module Dry
   module Configurable
@@ -15,6 +15,7 @@ module Dry
         @config = Config.new(self.class._settings.dup)
         super
       end
+      ruby2_keywords(:initialize) if respond_to?(:ruby2_keywords, true)
     end
 
     # Instance-level API when `Dry::Configurable` is included in a class

data/lib/dry/configurable/methods.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'dry/configurable/errors'
+require "dry/configurable/errors"
 
 module Dry
   module Configurable
@@ -10,7 +10,7 @@ module Dry
     module Methods
       # @api public
       def configure(&block)
-        raise FrozenConfig, 'Cannot modify frozen config' if frozen?
+        raise FrozenConfig, "Cannot modify frozen config" if frozen?
 
         yield(config) if block
         self

data/lib/dry/configurable/setting.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require 'set'
+require "set"
 
-require 'dry/core/equalizer'
+require "dry/core/equalizer"
 
-require 'dry/configurable/constants'
-require 'dry/configurable/config'
+require "dry/configurable/constants"
+require "dry/configurable/config"
 
 module Dry
   module Configurable

data/lib/dry/configurable/settings.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require 'concurrent/map'
+require "concurrent/map"
 
-require 'dry/core/equalizer'
-require 'dry/configurable/constants'
+require "dry/core/equalizer"
+require "dry/configurable/constants"
 
 module Dry
   module Configurable

data/lib/dry/configurable/version.rb

@@ -3,6 +3,6 @@
 module Dry
   module Configurable
     # @api public
-    VERSION = '0.12.1'
+    VERSION = "0.13.0"
   end
 end

data/lib/dry/configurable.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
-require 'concurrent/array'
+require "concurrent/array"
 
-require 'dry/configurable/constants'
-require 'dry/configurable/class_methods'
-require 'dry/configurable/instance_methods'
-require 'dry/configurable/config'
-require 'dry/configurable/setting'
-require 'dry/configurable/errors'
+require "dry/configurable/constants"
+require "dry/configurable/class_methods"
+require "dry/configurable/instance_methods"
+require "dry/configurable/config"
+require "dry/configurable/setting"
+require "dry/configurable/errors"
 
 module Dry
   # A simple configuration mixin

data/lib/dry-configurable.rb

@@ -1,3 +1,3 @@
 # frozen_string_literal: true
 
-require 'dry/configurable'
+require "dry/configurable"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dry-configurable
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Andy Holland
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-02-15 00:00:00.000000000 Z
+date: 2021-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -30,20 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.5.0
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.5'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.5.0
+        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -104,8 +98,8 @@ files:
 - lib/dry/configurable/config.rb
 - lib/dry/configurable/constants.rb
 - lib/dry/configurable/dsl.rb
-- lib/dry/configurable/dsl/args.rb
 - lib/dry/configurable/errors.rb
+- lib/dry/configurable/flags.rb
 - lib/dry/configurable/instance_methods.rb
 - lib/dry/configurable/methods.rb
 - lib/dry/configurable/setting.rb
@@ -128,14 +122,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: A mixin to add configuration functionality to your classes

data/lib/dry/configurable/dsl/args.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-require 'dry/configurable/constants'
-require 'dry/configurable/setting'
-
-module Dry
-  module Configurable
-    class DSL
-      # @api private
-      class Args
-        # @api private
-        attr_reader :args
-
-        # @api private
-        attr_reader :size
-
-        # @api private
-        attr_reader :opts
-
-        # @api private
-        def initialize(args)
-          @args = args
-          @size = args.size
-          @opts = Setting::OPTIONS
-        end
-
-        # @api private
-        def ensure_valid_options
-          return unless options
-
-          keys = options.keys - opts
-          raise ArgumentError, "Invalid options: #{keys.inspect}" unless keys.empty?
-        end
-
-        # @api private
-        def to_ary
-          [default, options || EMPTY_HASH]
-        end
-
-        # @api private
-        def default
-          if size.equal?(1) && options.nil?
-            args[0]
-          elsif size > 1 && options
-            args[0]
-          else
-            Undefined
-          end
-        end
-
-        # @api private
-        def options
-          args.detect { |arg| arg.is_a?(Hash) && (opts & arg.keys).any? }
-        end
-      end
-    end
-  end
-end