dry-initializer 1.4.1 → 2.0.0

data/lib/dry/initializer/config.rb

@@ -0,0 +1,161 @@
+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]   coercer (nil)
+    # @option opts [#call]   :type
+    # @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 val == null
+      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 val == null
+      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
+
+    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, 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,93 @@
+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
+
+    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
+
+    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)
+    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.respond_to?(:call) ? value.method(:call).arity : 0
+      return value unless arity.zero? || arity > 1
+      raise TypeError,
+            "type of #{inspect} should respond to #call with one argument"
+    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/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

@@ -0,0 +1,15 @@
+module Dry::Initializer
+  # @private
+  module 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
+
+    require_relative "mixin/root"
+    require_relative "mixin/local"
+  end
+end

data/lib/dry/initializer.rb

@@ -1,55 +1,59 @@
+require "set"
+
+# Namespace for gems in a dry-rb community
 module Dry
+  #
+  # DSL for declaring params and options of class initializers
+  #
   module Initializer
-    require_relative "initializer/exceptions/default_value_error"
-    require_relative "initializer/exceptions/type_constraint_error"
-    require_relative "initializer/exceptions/params_order_error"
-
-    require_relative "initializer/attribute"
-    require_relative "initializer/param"
-    require_relative "initializer/option"
-    require_relative "initializer/builder"
-    require_relative "initializer/instance_dsl"
-    require_relative "initializer/class_dsl"
-
-    # rubocop: disable Style/ConstantName
-    Mixin = self # for compatibility to versions below 0.12
-    # rubocop: enable Style/ConstantName
-
-    UNDEFINED = Object.new.tap do |obj|
-      obj.define_singleton_method(:inspect) { "Dry::Initializer::UNDEFINED" }
-    end.freeze
-
-    extend Dry::Initializer::ClassDSL
-
-    def param(*args)
-      __initializer_builder__.param(*args).call(__initializer_mixin__)
+    # 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"
+
+    # Adds methods [.[]] and [.define]
+    extend DSL
+
+    # Gem-related configuration
+    # @return [Dry::Initializer::Config]
+    def dry_initializer
+      @dry_initializer ||= Config.new(self)
     end
 
-    def option(*args)
-      __initializer_builder__.option(*args).call(__initializer_mixin__)
+    # Adds or redefines a parameter of [#dry_initializer]
+    # @param  [Symbol]       name
+    # @param  [#call, nil]   coercer (nil)
+    # @option opts [#call]   :type
+    # @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, opts)
+      self
     end
 
-    private
-
-    def __initializer_mixin__
-      @__initializer_mixin__ ||= Module.new
+    # 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, opts)
+      self
     end
 
-    def __initializer_builder__(**settings)
-      @__initializer_builder__ ||= Dry::Initializer::Builder.new(settings)
-    end
+    private
 
     def inherited(klass)
-      builder = @__initializer_builder__.dup
-      mixin   = Module.new
-
-      klass.instance_variable_set :@__initializer_builder__, builder
-      klass.instance_variable_set :@__initializer_mixin__,   mixin
-
-      builder.call(mixin)
-      klass.include mixin
-
       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
+]

data/spec/{options_var_spec.rb → attributes_spec.rb}

@@ -1,4 +1,6 @@
-describe "@__options__" do
+describe Dry::Initializer, "dry_initializer.attributes" do
+  subject { instance.class.dry_initializer.attributes(instance) }
+
   context "when class has params" do
     before do
       class Test::Foo
@@ -9,11 +11,10 @@ describe "@__options__" do
       end
     end
 
-    it "collects coerced params with default values" do
-      subject = Test::Foo.new(:FOO)
+    let(:instance) { Test::Foo.new(:FOO) }
 
-      expect(subject.instance_variable_get(:@__options__))
-        .to eq({ foo: "FOO", bar: 1 })
+    it "collects coerced params with default values" do
+      expect(subject).to eq({ foo: "FOO", bar: 1 })
     end
   end
 
@@ -28,11 +29,10 @@ describe "@__options__" do
       end
     end
 
-    it "collects coerced and renamed options with default values" do
-      subject = Test::Foo.new(foo: :FOO, qux: :QUX)
+    let(:instance) { Test::Foo.new(foo: :FOO, qux: :QUX) }
 
-      expect(subject.instance_variable_get(:@__options__))
-        .to eq({ foo: :FOO, bar: 1, quxx: "QUX" })
+    it "collects coerced and renamed options with default values" do
+      expect(subject).to eq({ foo: :FOO, bar: 1, quxx: "QUX" })
     end
   end
 end

data/spec/custom_initializer_spec.rb

@@ -1,7 +1,7 @@
 describe "custom initializer" do
   before do
     class Test::Foo
-      extend Dry::Initializer::Mixin
+      extend Dry::Initializer
 
       param :bar
 

data/spec/default_values_spec.rb

@@ -1,7 +1,7 @@
 describe "default values" do
   before do
     class Test::Foo
-      extend Dry::Initializer::Mixin
+      extend Dry::Initializer
 
       param  :foo, default: proc { :FOO }
       param  :bar, default: proc { :BAR }
@@ -52,14 +52,14 @@ describe "default values" do
   describe "when the last param has a default and there are no options" do
     before do
       class Test::Bar
-        extend Dry::Initializer::Mixin
+        extend Dry::Initializer
 
-        param  :foo
-        param  :bar, default: proc { {} }
+        param :foo
+        param :bar, default: proc { {} }
       end
     end
 
-    it "instantiate arguments" do
+    it "instantiates arguments" do
       subject = Test::Bar.new(1, 2)
 
       expect(subject.foo).to eql 1
@@ -73,7 +73,7 @@ describe "default values" do
       expect(subject.bar).to eql({})
     end
 
-    it "instantiate arguments also if the last is an hash" do
+    it "instantiates arguments also if the last is an hash" do
       subject = Test::Bar.new(1, { baz: 2, qux: 3 })
 
       expect(subject.foo).to eql 1