dry-initializer 3.0.2

data/benchmarks/with_coercion.rb

@@ -0,0 +1,71 @@
+Bundler.require(:benchmarks)
+
+require "dry-initializer"
+class DryTest
+  extend Dry::Initializer[undefined: false]
+
+  option :foo, proc(&:to_s)
+  option :bar, proc(&:to_s)
+end
+
+class DryTestUndefined
+  extend Dry::Initializer
+
+  option :foo, proc(&:to_s)
+  option :bar, proc(&:to_s)
+end
+
+class PlainRubyTest
+  attr_reader :foo, :bar
+
+  def initialize(options)
+    @foo = options[:foo].to_s
+    @bar = options[:bar].to_s
+  end
+end
+
+require "virtus"
+class VirtusTest
+  include Virtus.model
+
+  attribute :foo, String
+  attribute :bar, String
+end
+
+require "fast_attributes"
+class FastAttributesTest
+  extend FastAttributes
+
+  define_attributes initialize: true do
+    attribute :foo, String
+    attribute :bar, String
+  end
+end
+
+puts "Benchmark for instantiation with coercion"
+
+Benchmark.ips do |x|
+  x.config time: 15, warmup: 10
+
+  x.report("plain Ruby") do
+    PlainRubyTest.new foo: "FOO", bar: "BAR"
+  end
+
+  x.report("dry-initializer") do
+    DryTest.new foo: "FOO", bar: "BAR"
+  end
+
+  x.report("dry-initializer (with UNDEFINED)") do
+    DryTestUndefined.new foo: "FOO", bar: "BAR"
+  end
+
+  x.report("virtus") do
+    VirtusTest.new foo: "FOO", bar: "BAR"
+  end
+
+  x.report("fast_attributes") do
+    FastAttributesTest.new foo: "FOO", bar: "BAR"
+  end
+
+  x.compare!
+end

data/benchmarks/with_defaults.rb

@@ -0,0 +1,66 @@
+Bundler.require(:benchmarks)
+
+require "dry-initializer"
+class DryTest
+  extend Dry::Initializer[undefined: false]
+
+  option :foo, default: -> { "FOO" }
+  option :bar, default: -> { "BAR" }
+end
+
+class DryTestUndefined
+  extend Dry::Initializer
+
+  option :foo, default: -> { "FOO" }
+  option :bar, default: -> { "BAR" }
+end
+
+class PlainRubyTest
+  attr_reader :foo, :bar
+
+  def initialize(foo: "FOO", bar: "BAR")
+    @foo = foo
+    @bar = bar
+  end
+end
+
+require "kwattr"
+class KwattrTest
+  kwattr foo: "FOO", bar: "BAR"
+end
+
+require "active_attr"
+class ActiveAttrTest
+  include ActiveAttr::AttributeDefaults
+
+  attribute :foo, default: "FOO"
+  attribute :bar, default: "BAR"
+end
+
+puts "Benchmark for instantiation with default values"
+
+Benchmark.ips do |x|
+  x.config time: 15, warmup: 10
+
+  x.report("plain Ruby") do
+    PlainRubyTest.new
+  end
+
+  x.report("dry-initializer") do
+    DryTest.new
+  end
+
+  x.report("dry-initializer (with UNDEFINED)") do
+    DryTestUndefined.new
+  end
+
+  x.report("kwattr") do
+    KwattrTest.new
+  end
+
+  x.report("active_attr") do
+    ActiveAttrTest.new
+  end
+
+  x.compare!
+end

data/benchmarks/with_defaults_and_coercion.rb

@@ -0,0 +1,59 @@
+Bundler.require(:benchmarks)
+
+require "dry-initializer"
+class DryTest
+  extend Dry::Initializer[undefined: false]
+
+  option :foo, proc(&:to_s), default: -> { "FOO" }
+  option :bar, proc(&:to_s), default: -> { "BAR" }
+end
+
+class DryTestUndefined
+  extend Dry::Initializer
+
+  option :foo, proc(&:to_s), default: -> { "FOO" }
+  option :bar, proc(&:to_s), default: -> { "BAR" }
+end
+
+class PlainRubyTest
+  attr_reader :foo, :bar
+
+  def initialize(foo: "FOO", bar: "BAR")
+    @foo = foo
+    @bar = bar
+    raise TypeError unless String === @foo
+    raise TypeError unless String === @bar
+  end
+end
+
+require "virtus"
+class VirtusTest
+  include Virtus.model
+
+  attribute :foo, String, default: "FOO"
+  attribute :bar, String, default: "BAR"
+end
+
+puts "Benchmark for instantiation with type constraints and default values"
+
+Benchmark.ips do |x|
+  x.config time: 15, warmup: 10
+
+  x.report("plain Ruby") do
+    PlainRubyTest.new
+  end
+
+  x.report("dry-initializer") do
+    DryTest.new
+  end
+
+  x.report("dry-initializer (with UNDEFINED)") do
+    DryTest.new
+  end
+
+  x.report("virtus") do
+    VirtusTest.new
+  end
+
+  x.compare!
+end

data/docsite/source/attributes.html.md

@@ -0,0 +1,106 @@
+---
+title: Attributes
+layout: gem-single
+name: dry-initializer
+---
+
+Sometimes you need to access all attributes assigned via params and options of the object constructor.
+
+We support 2 methods: `attributes` and `public_attributes` for this goal. Both methods are wrapped into container accessible via `.dry_types` container:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param  :name
+  option :email,   optional: true
+  option :telefon, optional: true, as: :phone
+end
+
+user = User.new "Andy", telefon: "71002003040"
+
+User.dry_initializer.attributes(user)
+# => { name: "Andy", phone: "71002003040" }
+```
+
+What the method does is extracts *variables assigned* to the object (and skips unassigned ones like the `email` above). It doesn't matter whether you send it via `params` or `option`; we look at the result of the instantiation, not at the interface.
+
+Method `public_attributes` works different. Let's look at the following example to see the difference:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param  :name
+  option :telefon,  optional: true, as: :phone
+  option :email,    optional: true
+  option :token,    optional: true, reader: :private
+  option :password, optional: true, reader: false
+end
+
+user = User.new "Andy", telefon: "71002003040", token: "foo", password: "bar"
+
+User.dry_initializer.attributes(user)
+# => { name: "Andy", phone: "71002003040", token: "foo", password: "bar" }
+
+User.dry_initializer.public_attributes(user)
+# => { name: "Andy", phone: "71002003040", email: nil }
+```
+
+Notice that `public_attribute` reads *public reader methods*, not variables. That's why it skips both the private `token`, and the `password` whose reader hasn't been defined.
+
+Another difference concerns unassigned values. Because the reader `user.email` returns `nil` (its `@email` variable contains `Dry::Initializer::UNDEFINED` constant), the `public_attributes` adds this value to the hash using the method.
+
+The third thing to mention is that you can override the reader, and it is the overriden method which will be used by `public_attributes`:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param  :name
+  option :password, optional: true
+
+  def password
+    super.hash.to_s
+  end
+end
+
+user = User.new "Joe", password: "foo"
+
+User.dry_initializer.attributes(user)
+# => { user: "Joe", password: "foo" }
+
+User.dry_initializer.public_attributes(user)
+# => { user: "Joe", password: "-1844874613000160009" }
+```
+
+This feature works for the "extend Dry::Initializer" syntax. But what about "include Dry::Initializer.define ..."? Now we don't pollute class namespace with new methods, that's why `.dry_initializer` is absent.
+
+To access config you can use a hack. Under the hood we define private instance method `#__dry_initializer_config__` which refers to the same container. So you can write:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+  param :name
+end
+
+user = User.new "Joe"
+
+user.send(:__dry_initializer_config__).attributes(user)
+# => { user: "Joe" }
+
+user.send(:__dry_initializer_config__).public_attributes(user)
+# => { user: "Joe" }
+```
+
+This is a hack because the `__dry_initializer_config__` is not a part of the gem's public interface; there's a possibility it can be changed or removed in the later releases.
+
+We'll try to be careful with it, and mark it as deprecated method in case of such a removal.

data/docsite/source/container-version.html.md

@@ -0,0 +1,39 @@
+---
+title: Container Version
+layout: gem-single
+name: dry-initializer
+---
+
+Instead of extending a class with the `Dry::Initializer`, you can include a container with the `initializer` method only. This method should be preferred when you don't need subclassing.
+
+```ruby
+require 'dry-initializer'
+
+class User
+  # notice `-> do .. end` syntax
+  include Dry::Initializer.define -> do
+    param  :name,  proc(&:to_s)
+    param  :role,  default: proc { 'customer' }
+    option :admin, default: proc { false }
+  end
+end
+```
+
+If you still need the DSL (`param` and `option`) to be inherited, use the direct extension:
+
+```ruby
+require 'dry-initializer'
+
+class BaseService
+  extend Dry::Initializer
+  alias_method :dependency, :param
+end
+
+class ShowUser < BaseService
+  dependency :user
+
+  def call
+    puts user&.name
+  end
+end
+```

data/docsite/source/index.html.md

@@ -0,0 +1,43 @@
+---
+title: Introduction & Usage
+description: DSL for defining initializer params and options
+layout: gem-single
+order: 8
+type: gem
+name: dry-initializer
+sections:
+  - container-version
+  - params-and-options
+  - options-tolerance
+  - optionals-and-defaults
+  - type-constraints
+  - readers
+  - inheritance
+  - skip-undefined
+  - attributes
+  - rails-support
+---
+
+`dry-initializer` is a simple mixin of class methods `params` and `options` for instances.
+
+## Synopsis
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param  :name,  proc(&:to_s)
+  param  :role,  default: proc { 'customer' }
+  option :admin, default: proc { false }
+  option :phone, optional: true
+end
+
+user = User.new 'Vladimir', 'admin', admin: true
+
+user.name  # => 'Vladimir'
+user.role  # => 'admin'
+user.admin # => true
+user.phone # => nil
+```

data/docsite/source/inheritance.html.md

@@ -0,0 +1,43 @@
+---
+title: Inheritance
+layout: gem-single
+name: dry-initializer
+---
+
+Subclassing preserves all definitions being made inside a superclass.
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param :name
+end
+
+class Employee < User
+  param :position
+end
+
+employee = Employee.new('John', 'supercargo')
+employee.name     # => 'John'
+employee.position # => 'supercargo'
+
+employee = Employee.new # => fails because type
+```
+
+You can override params and options.
+Such overriding leaves initial order of params (positional arguments) unchanged:
+
+```ruby
+class Employee < User
+  param :position, optional: true
+  param :name,     default:  proc { 'Unknown' }
+end
+
+user = User.new         # => Boom! because User#name is required
+employee = Employee.new # passes because who cares on employee's name
+
+employee.name
+# => 'Unknown' because it is the name that positioned first like in User
+```

data/docsite/source/optionals-and-defaults.html.md

@@ -0,0 +1,130 @@
+---
+title: Optional Attributes and Default Values
+layout: gem-single
+name: dry-initializer
+---
+
+By default both params and options are mandatory. Use `:default` key to make them optional:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param  :name,  default: proc { 'Unknown user' }
+  option :email, default: proc { 'unknown@example.com' }
+  option :phone, optional: true
+end
+
+user = User.new
+user.name  # => 'Unknown user'
+user.email # => 'unknown@example.com'
+user.phone # => Dry::Initializer::UNDEFINED
+
+user = User.new 'Vladimir', email: 'vladimir@example.com', phone: '71234567788'
+user.name  # => 'Vladimir'
+user.email # => 'vladimir@example.com'
+user.phone # => '71234567788'
+```
+
+You cannot define required **parameter** after optional one. The following example raises `SyntaxError` exception:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param :name, default: proc { 'Unknown name' }
+  param :email # => #<SyntaxError ...>
+end
+```
+
+You should assign `nil` value explicitly. Otherwise an instance variable it will be left undefined. In both cases attribute reader method will return `nil`.
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param  :name
+  option :email, optional: true
+end
+
+user = User.new 'Andrew'
+user.email # => nil
+user.instance_variable_get :@email
+# => Dry::Initializer::UNDEFINED
+
+user = User.new 'Andrew', email: nil
+user.email # => nil
+user.instance_variable_get :@email
+# => nil
+```
+
+You can also set `nil` as a default value:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param  :name
+  option :email, default: proc { nil }
+end
+
+user = User.new 'Andrew'
+user.email # => nil
+user.instance_variable_get :@email
+# => nil
+```
+
+You **must** wrap default values into procs.
+
+If you need to **assign** proc as a default value, wrap it to another one:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param :name_proc, default: proc { proc { 'Unknown user' } }
+end
+
+user = User.new
+user.name_proc.call # => 'Unknown user'
+```
+
+Proc will be executed in a scope of new instance. You can refer to other arguments:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param :name
+  param :email, default: proc { "#{name.downcase}@example.com" }
+end
+
+user = User.new 'Andrew'
+user.email # => 'andrew@example.com'
+```
+
+**Warning**: when using lambdas instead of procs, don't forget an argument, required by [instance_eval][instance_eval] (you can skip in in a proc).
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+
+  param :name, default: -> (obj) { 'Dude' }
+end
+```
+
+[instance_eval]: http://ruby-doc.org/core-2.2.0/BasicObject.html#method-i-instance_eval