dry-initializer 0.11.0 → 2.5.0

data/lib/dry/initializer/config.rb

@@ -0,0 +1,172 @@
+module Dry::Initializer
+  #
+  # Gem-related configuration of some class
+  #
+  class Config
+    # @!attribute [r] null
+    # @return [Dry::Initializer::UNDEFINED, nil] value of unassigned variable
+
+    # @!attribute [r] extended_class
+    # @return [Class] the class whose config collected by current object
+
+    # @!attribute [r] parent
+    # @return [Dry::Initializer::Config] parent configuration
+
+    # @!attribute [r] definitions
+    # @return [Hash<Symbol, Dry::Initializer::Definition>]
+    #   hash of attribute definitions with their source names
+
+    attr_reader :null, :extended_class, :parent, :definitions
+
+    # @!attribute [r] mixin
+    # @return [Module] reference to the module to be included into class
+    def mixin
+      @mixin ||= Module.new.tap do |mod|
+        __dry_initializer__ = self
+        mod.extend(Mixin::Local)
+        mod.send :define_method, :__dry_initializer_config__ do
+          __dry_initializer__
+        end
+        mod.send :private, :__dry_initializer_config__
+      end
+    end
+
+    # List of configs of all subclasses of the [#extended_class]
+    # @return [Array<Dry::Initializer::Config>]
+    def children
+      @children ||= Set.new
+    end
+
+    # List of definitions for initializer params
+    # @return [Array<Dry::Initializer::Definition>]
+    def params
+      definitions.values.reject(&:option)
+    end
+
+    # List of definitions for initializer options
+    # @return [Array<Dry::Initializer::Definition>]
+    def options
+      definitions.values.select(&:option)
+    end
+
+    # Adds or redefines a parameter
+    # @param  [Symbol]       name
+    # @param  [#call, nil]   type (nil)
+    # @option opts [Proc]    :default
+    # @option opts [Boolean] :optional
+    # @option opts [Symbol]  :as
+    # @option opts [true, false, :protected, :public, :private] :reader
+    # @return [self] itself
+    def param(name, type = nil, **opts)
+      add_definition(false, name, type, opts)
+    end
+
+    # Adds or redefines an option of [#dry_initializer]
+    #
+    # @param  (see #param)
+    # @option (see #param)
+    # @return (see #param)
+    #
+    def option(name, type = nil, **opts)
+      add_definition(true, name, type, opts)
+    end
+
+    # The hash of public attributes for an instance of the [#extended_class]
+    # @param  [Dry::Initializer::Instance] instance
+    # @return [Hash<Symbol, Object>]
+    def public_attributes(instance)
+      definitions.values.each_with_object({}) do |item, obj|
+        key = item.target
+        next unless instance.respond_to? key
+        val = instance.send(key)
+        obj[key] = val unless null == val
+      end
+    end
+
+    # The hash of assigned attributes for an instance of the [#extended_class]
+    # @param  [Dry::Initializer::Instance] instance
+    # @return [Hash<Symbol, Object>]
+    def attributes(instance)
+      definitions.values.each_with_object({}) do |item, obj|
+        key = item.target
+        val = instance.send(:instance_variable_get, item.ivar)
+        obj[key] = val unless null == val
+      end
+    end
+
+    # Code of the `#__initialize__` method
+    # @return [String]
+    def code
+      Builders::Initializer[self]
+    end
+
+    # Finalizes config
+    # @return [self]
+    def finalize
+      @definitions = final_definitions
+      check_order_of_params
+      mixin.class_eval(code)
+      children.each(&:finalize)
+      self
+    end
+
+    # Human-readable representation of configured params and options
+    # @return [String]
+    def inch
+      line  =  Builders::Signature[self]
+      line  =  line.gsub("__dry_initializer_options__", "options")
+      lines =  ["@!method initialize(#{line})"]
+      lines += ["Initializes an instance of #{extended_class}"]
+      lines += definitions.values.map(&:inch)
+      lines += ["@return [#{extended_class}]"]
+      lines.join("\n")
+    end
+
+    private
+
+    def initialize(extended_class = nil, null: UNDEFINED)
+      @extended_class = extended_class.tap { |klass| klass&.include mixin }
+      sklass          = extended_class&.superclass
+      @parent         = sklass.dry_initializer if sklass.is_a? Dry::Initializer
+      @null           = null || parent&.null
+      @definitions    = {}
+      finalize
+    end
+
+    def add_definition(option, name, type, opts)
+      definition = Definition.new(option, null, name, type, Dispatchers[opts])
+      definitions[definition.source] = definition
+      finalize
+
+      mixin.class_eval definition.code
+    end
+
+    def final_definitions
+      parent_definitions = Hash(parent&.definitions&.dup)
+      definitions.each_with_object(parent_definitions) do |(key, val), obj|
+        obj[key] = check_type(obj[key], val)
+      end
+    end
+
+    def check_type(previous, current)
+      return current unless previous
+      return current if previous.option == current.option
+      raise SyntaxError,
+            "cannot reload #{previous} of #{extended_class.superclass}" \
+            " by #{current} of its subclass #{extended_class}"
+    end
+
+    def check_order_of_params
+      params.inject(nil) do |optional, current|
+        if current.optional
+          current
+        elsif optional
+          raise SyntaxError, "#{extended_class}: required #{current}" \
+                             " goes after optional #{optional}"
+        else
+          optional
+        end
+      end
+    end
+  end
+end

data/lib/dry/initializer/definition.rb

@@ -0,0 +1,116 @@
+module Dry::Initializer
+  #
+  # @private
+  # @abstract
+  #
+  # Base class for parameter or option definitions
+  # Defines methods to add corresponding reader to the class,
+  # and build value of instance attribute.
+  #
+  class Definition
+    attr_reader :option, :null, :source, :target, :ivar,
+                :type, :optional, :default, :reader,
+                :desc
+
+    def options
+      {
+        as:       target,
+        type:     type,
+        optional: optional,
+        default:  default,
+        reader:   reader,
+        desc:     desc
+      }.reject { |_, value| value.nil? }
+    end
+
+    def name
+      @name ||= (option ? "option" : "parameter") << " '#{source}'"
+    end
+    alias to_s    name
+    alias to_str  name
+    alias inspect name
+
+    def ==(other)
+      other.instance_of?(self.class) && (other.source == source)
+    end
+
+    def code
+      Builders::Reader[self]
+    end
+
+    def inch
+      @inch ||= (option ? "@option" : "@param ").tap do |text|
+        text << " [Object]"
+        text << (option ? " :#{source}" : " #{source}")
+        text << (optional ? " (optional)" : " (required)")
+        text << " #{desc}" if desc
+      end
+    end
+
+    private
+
+    def initialize(option, null, source, coercer = nil, **options)
+      @option   = !!option
+      @null     = null
+      @source   = source.to_sym
+      @target   = check_target options.fetch(:as, source).to_sym
+      @ivar     = :"@#{target}"
+      @type     = check_type(coercer || options[:type])
+      @reader   = prepare_reader options.fetch(:reader, true)
+      @default  = check_default options[:default]
+      @optional = options.fetch(:optional, @default)
+      @desc     = options[:desc]&.to_s&.capitalize
+    end
+
+    def check_source(value)
+      if RESERVED.include? value
+        raise ArgumentError, "Name #{value} is reserved by dry-initializer gem"
+      end
+
+      unless option || value[ATTRIBUTE]
+        raise ArgumentError, "Invalid parameter name :'#{value}'"
+      end
+
+      value
+    end
+
+    def check_target(value)
+      return value if value[ATTRIBUTE]
+      raise ArgumentError, "Invalid variable name :'#{value}'"
+    end
+
+    def check_type(value)
+      return if value.nil?
+      arity =   value.arity               if value.is_a? Proc
+      arity ||= value.method(:call).arity if value.respond_to? :call
+      return value if [1, 2].include? arity.to_i.abs
+      raise TypeError,
+            "type of #{inspect} should respond to #call with 1..2 arguments"
+    end
+
+    def check_default(value)
+      return if value.nil?
+      return value if value.is_a?(Proc) && value.arity < 1
+      raise TypeError,
+            "default value of #{inspect} should be a proc without params"
+    end
+
+    def prepare_reader(value)
+      case value.to_s
+      when "", "false" then false
+      when "private"   then :private
+      when "protected" then :protected
+      else :public
+      end
+    end
+
+    ATTRIBUTE = /\A\w+\z/
+    RESERVED  = %i[
+      __dry_initializer_options__
+      __dry_initializer_config__
+      __dry_initializer_value__
+      __dry_initializer_definition__
+      __dry_initializer_initializer__
+    ].freeze
+  end
+end

data/lib/dry/initializer/dispatchers.rb

@@ -0,0 +1,44 @@
+module Dry::Initializer
+  #
+  # @private
+  #
+  # Dispatchers allow adding syntax sugar to `.param` and `.option` methods.
+  #
+  # Every dispatcher should convert the source hash of options into
+  # the resulting hash so that you can send additional keys to the helpers.
+  #
+  # @example Add special dispatcher
+  #
+  #   # Define a dispatcher for key :integer
+  #   dispatcher = proc do |opts|
+  #     opts.merge(type: proc(&:to_i)) if opts[: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 Dispatchers
+    class << self
+      def <<(item)
+        list << item
+        self
+      end
+
+      def [](options)
+        list.inject(options) { |opts, item| item.call(opts) }
+      end
+
+      private
+
+      def list
+        @list ||= []
+      end
+    end
+  end
+end

data/lib/dry/initializer/dsl.rb

@@ -0,0 +1,43 @@
+module Dry::Initializer
+  # Module-level DSL
+  module DSL
+    # Setting for null (undefined value)
+    # @return [nil, Dry::Initializer::UNDEFINED]
+    attr_reader :null
+
+    # Returns a version of the module with custom settings
+    # @option settings [Boolean] :undefined
+    #   If unassigned params and options should be treated different from nil
+    # @return [Dry::Initializer]
+    def [](undefined: true, **)
+      null = (undefined == false) ? nil : UNDEFINED
+      Module.new.tap do |mod|
+        mod.extend DSL
+        mod.include self
+        mod.send(:instance_variable_set, :@null, null)
+      end
+    end
+
+    # Returns mixin module to be included to target class by hand
+    # @return [Module]
+    # @yield proc defining params and options
+    def define(procedure = nil, &block)
+      config = Config.new(null: null)
+      config.instance_exec(&(procedure || block))
+      config.mixin.include Mixin::Root
+      config.mixin
+    end
+
+    private
+
+    def extended(klass)
+      config = Config.new(klass, null: null)
+      klass.send :instance_variable_set, :@dry_initializer, config
+      klass.include Mixin::Root
+    end
+
+    def self.extended(mod)
+      mod.instance_variable_set :@null, UNDEFINED
+    end
+  end
+end

data/lib/dry/initializer/mixin/local.rb

@@ -0,0 +1,19 @@
+module Dry::Initializer::Mixin
+  # @private
+  module Local
+    attr_reader :klass
+
+    def inspect
+      "Dry::Initializer::Mixin::Local[#{klass}]"
+    end
+    alias to_s   inspect
+    alias to_str inspect
+
+    private
+
+    def included(klass)
+      @klass = klass
+      super
+    end
+  end
+end

data/lib/dry/initializer/mixin/root.rb

@@ -0,0 +1,10 @@
+module Dry::Initializer::Mixin
+  # @private
+  module Root
+    private
+
+    def initialize(*args)
+      __dry_initializer_initialize__(*args)
+    end
+  end
+end

data/lib/dry/initializer/mixin.rb

@@ -1,77 +1,15 @@
 module Dry::Initializer
-  # Class-level DSL for the initializer
+  # @private
   module Mixin
-    # Declares a plain argument
-    #
-    # @param [#to_sym] name
-    #
-    # @option options [Object]  :default The default value
-    # @option options [#call]   :type    The type constraings via `dry-types`
-    # @option options [Boolean] :reader (true) Whether to define attr_reader
-    #
-    # @return [self] itself
-    #
-    def param(name, type = nil, **options)
-      options[:type]   = type if type
-      options[:option] = false
-      @__initializer_builder__ = __initializer_builder__.define(name, **options)
-      __initializer_builder__.call(__initializer_mixin__)
-    end
-
-    # Declares a named argument
-    #
-    # @param  (see #param)
-    # @option (see #param)
-    # @return (see #param)
-    #
-    def option(name, type = nil, **options)
-      options[:type]   = type if type
-      options[:option] = true
-      @__initializer_builder__ = __initializer_builder__.define(name, **options)
-      __initializer_builder__.call(__initializer_mixin__)
-    end
-
-    # Adds new plugin to the builder
-    #
-    # @param  [Dry::Initializer::Plugins::Base] plugin
-    # @return [self] itself
-    #
-    def register_initializer_plugin(plugin)
-      @__initializer_builder__ = __initializer_builder__.register(plugin)
-      __initializer_builder__.call(__initializer_mixin__)
-    end
-
-    private
-
-    def __initializer_mixin__
-      @__initializer_mixin__ ||= Module.new do
-        def initialize(*args)
-          __initialize__(*args)
-        end
-      end
-    end
-
-    def __initializer_builder__
-      @__initializer_builder__ ||= Builder.new
-    end
-
-    def inherited(klass)
-      new_builder = __initializer_builder__.dup
-      klass.instance_variable_set :@__initializer_builder__, new_builder
-
-      new_mixin = Module.new
-      new_builder.call(new_mixin)
-      klass.instance_variable_set :@__initializer_mixin__, new_mixin
-      klass.include new_mixin
-
+    extend  DSL              # @deprecated
+    include Dry::Initializer # @deprecated
+    def self.extended(klass) # @deprecated
+      warn "[DEPRECATED] Use Dry::Initializer instead of its alias" \
+           " Dry::Initializer::Mixin. The later will be removed in v2.1.0"
       super
     end
 
-    def self.extended(klass)
-      super
-      mixin = klass.send(:__initializer_mixin__)
-      klass.send(:__initializer_builder__).call(mixin)
-      klass.include mixin
-    end
+    require_relative "mixin/root"
+    require_relative "mixin/local"
   end
 end

data/lib/dry/initializer.rb

@@ -1,22 +1,59 @@
+require "set"
+
+# Namespace for gems in a dry-rb community
 module Dry
-  # Declares arguments of the initializer (params and options)
   #
-  # @api public
+  # DSL for declaring params and options of class initializers
   #
   module Initializer
-    require_relative "initializer/errors"
-    require_relative "initializer/plugins"
-    require_relative "initializer/signature"
-    require_relative "initializer/builder"
+    # Singleton for unassigned values
+    UNDEFINED = Object.new.freeze
+
+    require_relative "initializer/dsl"
+    require_relative "initializer/definition"
+    require_relative "initializer/builders"
+    require_relative "initializer/config"
     require_relative "initializer/mixin"
+    require_relative "initializer/dispatchers"
 
-    UNDEFINED = Object.new.freeze
+    # Adds methods [.[]] and [.define]
+    extend DSL
+
+    # Gem-related configuration
+    # @return [Dry::Initializer::Config]
+    def dry_initializer
+      @dry_initializer ||= Config.new(self)
+    end
+
+    # Adds or redefines a parameter of [#dry_initializer]
+    # @param  [Symbol]       name
+    # @param  [#call, nil]   type (nil)
+    # @option opts [Proc]    :default
+    # @option opts [Boolean] :optional
+    # @option opts [Symbol]  :as
+    # @option opts [true, false, :protected, :public, :private] :reader
+    # @return [self] itself
+    def param(name, type = nil, **opts)
+      dry_initializer.param(name, type, Dispatchers[opts])
+      self
+    end
+
+    # Adds or redefines an option of [#dry_initializer]
+    # @param  (see #param)
+    # @option (see #param)
+    # @return (see #param)
+    def option(name, type = nil, **opts)
+      dry_initializer.option(name, type, Dispatchers[opts])
+      self
+    end
+
+    private
 
-    def self.define(proc = nil, &block)
-      Module.new do |container|
-        container.extend Mixin
-        container.instance_exec(&(proc || block))
-      end
+    def inherited(klass)
+      super
+      config = Config.new(klass, null: dry_initializer.null)
+      klass.send(:instance_variable_set, :@dry_initializer, config)
+      dry_initializer.children << config
     end
   end
 end

data/lib/tasks/benchmark.rake

@@ -0,0 +1,41 @@
+namespace :benchmark do
+  desc "Runs benchmarks for plain params"
+  task :plain_params do
+    system "ruby benchmarks/plain_params.rb"
+  end
+
+  desc "Runs benchmarks for plain options"
+  task :plain_options do
+    system "ruby benchmarks/plain_options.rb"
+  end
+
+  desc "Runs benchmarks for value coercion"
+  task :with_coercion do
+    system "ruby benchmarks/with_coercion.rb"
+  end
+
+  desc "Runs benchmarks with defaults"
+  task :with_defaults do
+    system "ruby benchmarks/with_defaults.rb"
+  end
+
+  desc "Runs benchmarks with defaults and coercion"
+  task :with_defaults_and_coercion do
+    system "ruby benchmarks/with_defaults_and_coercion.rb"
+  end
+
+  desc "Runs benchmarks for several defaults"
+  task :compare_several_defaults do
+    system "ruby benchmarks/with_several_defaults.rb"
+  end
+end
+
+desc "Runs all benchmarks"
+task benchmark: %i[
+  benchmark:plain_params
+  benchmark:plain_options
+  benchmark:with_coercion
+  benchmark:with_defaults
+  benchmark:with_defaults_and_coercion
+  benchmark:compare_several_defaults
+]

data/lib/tasks/profile.rake

@@ -0,0 +1,78 @@
+namespace :profile do
+  def profile(name, execution, &definition)
+    require "dry-initializer"
+    require "ruby-prof"
+    require "fileutils"
+
+    definition.call
+    result = RubyProf.profile do
+      1_000.times { execution.call }
+    end
+
+    FileUtils.mkdir_p "./tmp"
+
+    FileUtils.touch "./tmp/#{name}.dot"
+    File.open("./tmp/#{name}.dot", "w+") do |output|
+      RubyProf::DotPrinter.new(result).print(output, min_percent: 0)
+    end
+
+    FileUtils.touch "./tmp/#{name}.html"
+    File.open("./tmp/#{name}.html", "w+") do |output|
+      RubyProf::CallStackPrinter.new(result).print(output, min_percent: 0)
+    end
+
+    system "dot -Tpng ./tmp/#{name}.dot > ./tmp/#{name}.png"
+  end
+
+  desc "Profiles initialization with required param and option"
+  task :required do
+    profile("required", -> { User.new :Andy, email: "andy@example.com" }) do
+      class User
+        extend Dry::Initializer
+        param  :name
+        option :email
+      end
+    end
+  end
+
+  desc "Profiles initialization with default param and option"
+  task :defaults do
+    profile("defaults", -> { User.new }) do
+      class User
+        extend Dry::Initializer
+        param  :name,  default: -> { :Andy }
+        option :email, default: -> { "andy@example.com" }
+      end
+    end
+  end
+
+  desc "Profiles initialization with coerced param and option"
+  task :coercion do
+    profile("coercion", -> { User.new :Andy, email: :"andy@example.com" }) do
+      class User
+        extend Dry::Initializer
+        param  :name,  proc(&:to_s)
+        option :email, proc(&:to_s)
+      end
+    end
+  end
+
+  desc "Profiles initialization with coerced defaults of param and option"
+  task :default_coercion do
+    profile("default_coercion", -> { User.new }) do
+      class User
+        extend Dry::Initializer
+        param  :name,  proc(&:to_s), default: -> { :Andy }
+        option :email, proc(&:to_s), default: -> { :"andy@example.com" }
+      end
+    end
+  end
+end
+
+desc "Makes all profiling at once"
+task profile: %i[
+  profile:required
+  profile:defaults
+  profile:coercion
+  profile:default_coercion
+]