dry-initializer 2.4.0 → 3.0.3

data/lib/dry/initializer/dispatchers.rb

@@ -1,44 +1,112 @@
-module Dry::Initializer
-  #
-  # @private
-  #
-  # Dispatchers allow adding syntax sugar to `.param` and `.option` methods.
+#
+# The module is responsible for __normalizing__ arguments
+# of `.param` and `.option`.
+#
+# What the module does is convert the source list of arguments
+# into the standard set of options:
+# - `:option`   -- whether an argument is an option (or param)
+# - `:source`   -- the name of source option
+# - `:target`   -- the target name of the reader
+# - `:reader`   -- if the reader's privacy (:public, :protected, :private, nil)
+# - `:ivar`     -- the target nane of the variable
+# - `:type`     -- the callable coercer of the source value
+# - `:optional` -- if the argument is optional
+# - `:default`  -- the proc returning the default value of the source value
+# - `:null`     -- the value to be set to unassigned optional argument
+#
+# It is this set is used to build [Dry::Initializer::Definition].
+#
+# @example
+#    # from `option :foo, [], as: :bar, optional: :true
+#    input = { name: :foo, as: :bar, type: [], optional: true }
+#
+#    Dry::Initializer::Dispatcher.call(input)
+#    # => {
+#    #      source:   "foo",
+#    #      target:   "bar",
+#    #      reader:   :public,
+#    #      ivar:     "@bar",
+#    #      type:  ->(v) { Array(v) } }, # simplified for brevity
+#    #      optional: true,
+#    #      default:  -> { Dry::Initializer::UNDEFINED },
+#    #    }
+#
+# # Settings
+#
+# The module uses global setting `null` to define what value
+# should be set to variables that kept unassigned. By default it
+# uses `Dry::Initializer::UNDEFINED`
+#
+# # Syntax Extensions
+#
+# The module supports syntax extensions. You can add any number
+# of custom dispatchers __on top__ of the stack of default dispatchers.
+# Every dispatcher should be a callable object that takes
+# the source set of options and converts it to another set of options.
+#
+# @example Add special dispatcher
+#
+#   # Define a dispatcher for key :integer
+#   dispatcher = proc do |integer: false, **opts|
+#     opts.merge(type: proc(&:to_i)) if integer
+#   end
+#
+#   # Register a dispatcher
+#   Dry::Initializer::Dispatchers << dispatcher
+#
+#   # Now you can use option `integer: true` instead of `type: proc(&:to_i)`
+#   class Foo
+#     extend Dry::Initializer
+#     param :id, integer: true
+#   end
+#
+module Dry::Initializer::Dispatchers
+  extend self
+
+  # @!attribute [rw] null Defines a value to be set to unassigned attributes
+  # @return [Object]
+  attr_accessor :null
+
   #
-  # Every dispatcher should convert the source hash of options into
-  # the resulting hash so that you can send additional keys to the helpers.
+  # Registers a new dispatcher
   #
-  # @example Add special dispatcher
+  # @param [#call] dispatcher
+  # @return [self] itself
   #
-  #   # Define a dispatcher for key :integer
-  #   dispatcher = proc do |opts|
-  #     opts.merge(type: proc(&:to_i)) if opts[:integer]
-  #   end
+  def <<(dispatcher)
+    @pipeline = [dispatcher] + pipeline
+    self
+  end
+
   #
-  #   # Register a dispatcher
-  #   Dry::Initializer::Dispatchers << dispatcher
+  # Normalizes the source set of options
   #
-  #   # Now you can use option `integer: true` instead of `type: proc(&:to_i)`
-  #   class Foo
-  #     extend Dry::Initializer
-  #     param :id, integer: true
-  #   end
+  # @param [Hash<Symbol, Object>] options
+  # @return [Hash<Symbol, Objct>] normalized set of options
   #
-  module Dispatchers
-    class << self
-      def <<(item)
-        list << item
-        self
-      end
+  def call(**options)
+    options = { null: null, **options }
+    pipeline.reduce(options) { |opts, dispatcher| dispatcher.call(**opts) }
+  end
 
-      def [](options)
-        list.inject(options) { |opts, item| item.call(opts) }
-      end
+  private
 
-      private
+  require_relative 'dispatchers/build_nested_type'
+  require_relative 'dispatchers/check_type'
+  require_relative 'dispatchers/prepare_default'
+  require_relative 'dispatchers/prepare_ivar'
+  require_relative 'dispatchers/prepare_optional'
+  require_relative 'dispatchers/prepare_reader'
+  require_relative 'dispatchers/prepare_source'
+  require_relative 'dispatchers/prepare_target'
+  require_relative 'dispatchers/unwrap_type'
+  require_relative 'dispatchers/wrap_type'
 
-      def list
-        @list ||= []
-      end
-    end
+  def pipeline
+    @pipeline ||= [
+      PrepareSource, PrepareTarget, PrepareIvar, PrepareReader,
+      PrepareDefault, PrepareOptional,
+      UnwrapType, CheckType, BuildNestedType, WrapType
+    ]
   end
 end

data/lib/dry/initializer/dispatchers/build_nested_type.rb

@@ -0,0 +1,59 @@
+#
+# Prepare nested data type from a block
+#
+# @example
+#   option :foo do
+#     option :bar
+#     option :qux
+#   end
+#
+module Dry::Initializer::Dispatchers::BuildNestedType
+  extend self
+
+  # rubocop: disable Metrics/ParameterLists
+  def call(parent:, source:, target:, type: nil, block: nil, **options)
+    check_certainty!(source, type, block)
+    check_name!(target, block)
+    type ||= build_nested_type(parent, target, block)
+    { parent: parent, source: source, target: target, type: type, **options }
+  end
+  # rubocop: enable Metrics/ParameterLists
+
+  private
+
+  def check_certainty!(source, type, block)
+    return unless block
+    return unless type
+
+    raise ArgumentError, <<~MESSAGE
+      You should define coercer of values of argument '#{source}'
+      either though the parameter/option, or via nested block, but not the both.
+    MESSAGE
+  end
+
+  def check_name!(name, block)
+    return unless block
+    return unless name[/^_|__|_$/]
+
+    raise ArgumentError, <<~MESSAGE
+      The name of the argument '#{name}' cannot be used for nested struct.
+      A proper name can use underscores _ to divide alphanumeric parts only.
+    MESSAGE
+  end
+
+  def build_nested_type(parent, name, block)
+    return unless block
+
+    klass_name = full_name(parent, name)
+    build_struct(klass_name, block)
+  end
+
+  def full_name(parent, name)
+    "::#{parent.name}::#{name.to_s.split("_").compact.map(&:capitalize).join}"
+  end
+
+  def build_struct(klass_name, block)
+    eval "class #{klass_name} < Dry::Initializer::Struct; end"
+    const_get(klass_name).tap { |klass| klass.class_eval(&block) }
+  end
+end

data/lib/dry/initializer/dispatchers/check_type.rb

@@ -0,0 +1,43 @@
+#
+# Checks whether an unwrapped type is valid
+#
+module Dry::Initializer::Dispatchers::CheckType
+  extend self
+
+  def call(source:, type: nil, wrap: 0, **options)
+    check_if_callable! source, type
+    check_arity! source, type, wrap
+
+    { source: source, type: type, wrap: wrap, **options }
+  end
+
+  private
+
+  def check_if_callable!(source, type)
+    return if type.nil?
+    return if type.respond_to?(:call)
+
+    raise ArgumentError,
+          "The type of the argument '#{source}' should be callable"
+  end
+
+  def check_arity!(_source, type, wrap)
+    return if type.nil?
+    return if wrap.zero?
+    return if type.method(:call).arity.abs == 1
+
+    raise ArgumentError, <<~MESSAGE
+      The dry_intitializer supports wrapped types with one argument only.
+      You cannot use array types with element coercers having several arguments.
+
+      For example, this definitions are correct:
+        option :foo, [proc(&:to_s)]
+        option :bar, type: [[]]
+        option :baz, ->(a, b) { [a, b] }
+
+      While this is not:
+        option :foo, [->(a, b) { [a, b] }]
+    MESSAGE
+  end
+  # rubocop: enable Metrics/MethodLength
+end

data/lib/dry/initializer/dispatchers/prepare_default.rb

@@ -0,0 +1,40 @@
+#
+# Prepares the `:default` option
+#
+# It must respond to `.call` without arguments
+#
+module Dry::Initializer::Dispatchers::PrepareDefault
+  extend self
+
+  def call(default: nil, optional: nil, **options)
+    default = callable! default
+    check_arity! default
+
+    { default: default, optional: (optional | default), **options }
+  end
+
+  private
+
+  def callable!(default)
+    return unless default
+    return default if default.respond_to?(:call)
+    return callable(default.to_proc) if default.respond_to?(:to_proc)
+
+    invalid!(default)
+  end
+
+  def check_arity!(default)
+    return unless default
+
+    arity = default.method(:call).arity.to_i
+    return unless arity.positive?
+
+    invalid!(default)
+  end
+
+  def invalid!(default)
+    raise TypeError, "The #{default.inspect} should be" \
+                     ' either convertable to proc with no arguments,' \
+                     ' or respond to #call without arguments.'
+  end
+end

data/lib/dry/initializer/dispatchers/prepare_ivar.rb

@@ -0,0 +1,12 @@
+#
+# Prepares the variable name of a parameter or an option.
+#
+module Dry::Initializer::Dispatchers::PrepareIvar
+  module_function
+
+  def call(target:, **options)
+    ivar = "@#{target}".delete('?').to_sym
+
+    { target: target, ivar: ivar, **options }
+  end
+end

data/lib/dry/initializer/dispatchers/prepare_optional.rb

@@ -0,0 +1,13 @@
+#
+# Defines whether an argument is optional
+#
+module Dry::Initializer::Dispatchers::PrepareOptional
+  module_function
+
+  def call(optional: nil, default: nil, required: nil, **options)
+    optional ||= default
+    optional &&= !required
+
+    { optional: !!optional, default: default, **options }
+  end
+end

data/lib/dry/initializer/dispatchers/prepare_reader.rb

@@ -0,0 +1,30 @@
+#
+# Checks the reader privacy
+#
+module Dry::Initializer::Dispatchers::PrepareReader
+  extend self
+
+  def call(target: nil, reader: :public, **options)
+    reader = case reader.to_s
+             when 'false', ''                      then nil
+             when 'true'                           then :public
+             when 'public', 'private', 'protected' then reader.to_sym
+             else invalid_reader!(target, reader)
+             end
+
+    { target: target, reader: reader, **options }
+  end
+
+  private
+
+  def invalid_reader!(target, _reader)
+    raise ArgumentError, <<~MESSAGE
+      Invalid setting for the ##{target} reader's privacy.
+      Use the one of the following values for the `:reader` option:
+      - 'public' (true) for the public reader (default)
+      - 'private' for the private reader
+      - 'protected' for the protected reader
+      - nil (false) if no reader should be defined
+    MESSAGE
+  end
+end

data/lib/dry/initializer/dispatchers/prepare_source.rb

@@ -0,0 +1,28 @@
+#
+# The dispatcher verifies a correctness of the source name
+# of param or option, taken as a `:source` option.
+#
+# We allow any stringified name for the source.
+# For example, this syntax is correct because we accept any key
+# in the original hash of arguments, but give them proper names:
+#
+# ```ruby
+# class Foo
+#   extend Dry::Initializer
+#
+#   option "", as: :first
+#   option 1,  as: :second
+# end
+#
+# foo = Foo.new("": 42, 1: 666)
+# foo.first  # => 42
+# foo.second # => 666
+# ```
+#
+module Dry::Initializer::Dispatchers::PrepareSource
+  module_function
+
+  def call(source:, **options)
+    { source: source.to_s.to_sym, **options }
+  end
+end

data/lib/dry/initializer/dispatchers/prepare_target.rb

@@ -0,0 +1,44 @@
+#
+# Prepares the target name of a parameter or an option.
+#
+# Unlike source, the target must satisfy requirements for Ruby variable names.
+# It also shouldn't be in conflict with names used by the gem.
+#
+module Dry::Initializer::Dispatchers::PrepareTarget
+  extend self
+
+  # List of variable names reserved by the gem
+  RESERVED = %i[
+    __dry_initializer_options__
+    __dry_initializer_config__
+    __dry_initializer_value__
+    __dry_initializer_definition__
+    __dry_initializer_initializer__
+  ].freeze
+
+  def call(source:, target: nil, as: nil, **options)
+    target ||= as || source
+    target = target.to_s.to_sym.downcase
+
+    check_ruby_name!(target)
+    check_reserved_names!(target)
+
+    { source: source, target: target, **options }
+  end
+
+  private
+
+  def check_ruby_name!(target)
+    return if target[/\A[[:alpha:]_][[:alnum:]_]*\??\z/u]
+
+    raise ArgumentError,
+          "The name `#{target}` is not allowed for Ruby methods"
+  end
+
+  def check_reserved_names!(target)
+    return unless RESERVED.include?(target)
+
+    raise ArgumentError,
+          "The method name `#{target}` is reserved by the dry-initializer gem"
+  end
+end

data/lib/dry/initializer/dispatchers/unwrap_type.rb

@@ -0,0 +1,22 @@
+#
+# Looks at the `:type` option and counts how many nested arrays
+# it contains around either nil or a callable value.
+#
+# The counted number is preserved in the `:wrap` virtual option
+# used by the [WrapType] dispatcher.
+#
+module Dry::Initializer::Dispatchers::UnwrapType
+  extend self
+
+  def call(type: nil, wrap: 0, **options)
+    type, wrap = unwrap(type, 0)
+
+    { type: type, wrap: wrap, **options }
+  end
+
+  private
+
+  def unwrap(type, count)
+    type.is_a?(Array) ? unwrap(type.first, count + 1) : [type, count]
+  end
+end