dry-initializer 3.0.2 → 3.1.1

data/benchmarks/with_defaults_and_coercion.rb

@@ -1,59 +0,0 @@
-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

@@ -1,106 +0,0 @@
----
-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

@@ -1,39 +0,0 @@
----
-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

@@ -1,43 +0,0 @@
----
-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

@@ -1,43 +0,0 @@
----
-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

@@ -1,130 +0,0 @@
----
-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

data/docsite/source/options-tolerance.html.md

@@ -1,27 +0,0 @@
----
-title: Tolerance to Unknown Options
-layout: gem-single
-name: dry-initializer
----
-
-By default the initializer is strict for params (positional arguments), expecting them to be defined explicitly.
-
-```ruby
-require 'dry-initializer'
-
-class User
-  extend Dry::Initializer
-end
-
-user = User.new 'Joe' # raises ArgumentError
-```
-
-At the same time it is tolerant to unknown options. All unknown options are accepted, but ignored:
-
-```ruby
-# It accepts undefined options...
-user = User.new name: 'Joe'
-
-# ...but ignores them
-user.respond_to? :name # => false
-```

data/docsite/source/params-and-options.html.md

@@ -1,74 +0,0 @@
----
-title: Params and Options
-layout: gem-single
-name: dry-initializer
----
-
-Use `param` to define plain argument:
-
-```ruby
-require 'dry-initializer'
-
-class User
-  extend  Dry::Initializer
-
-  param :name
-  param :email
-end
-
-user = User.new 'Andrew', 'andrew@email.com'
-user.name  # => 'Andrew'
-user.email # => 'andrew@email.com'
-```
-
-Use `option` to define named (hash) argument:
-
-```ruby
-require 'dry-initializer'
-
-class User
-  extend Dry::Initializer
-
-  option :name
-  option :email
-end
-
-user = User.new email: 'andrew@email.com', name: 'Andrew'
-user.name  # => 'Andrew'
-user.email # => 'andrew@email.com'
-```
-
-Options can be renamed using `:as` key:
-
-```ruby
-require 'dry-initializer'
-
-class User
-  extend Dry::Initializer
-
-  option :name, as: :username
-end
-
-user = User.new name: "Joe"
-user.username                         # => "Joe"
-user.instance_variable_get :@username # => "Joe"
-user.instance_variable_get :@name     # => nil
-user.respond_to? :name                # => false
-```
-
-You can also define several ways of initializing the same argument via different options:
-
-```ruby
-require 'dry-initializer'
-
-class User
-  extend Dry::Initializer
-
-  option :phone
-  option :telephone, as: :phone
-  option :name, optional: true
-end
-
-User.new(phone: '1234567890').phone     # => '1234567890'
-User.new(telephone: '1234567890').phone # => '1234567890'
-```

data/docsite/source/rails-support.html.md

@@ -1,101 +0,0 @@
----
-title: Rails Support
-layout: gem-single
-name: dry-initializer
----
-
-Rails plugin is implemented in a separate [dry-initializer-rails](https://github.com/nepalez/dry-initializer-rails) gem.
-
-It provides coercion of assigned values to corresponding ActiveRecord instances.
-
-### Base Example
-
-Add the `:model` setting to `param` or `option`:
-
-```ruby
-require 'dry-initializer-rails'
-
-class CreateOrder
-  extend Dry::Initializer
-
-  # Params and options
-  param  :customer, model: 'Customer' # use either a name
-  option :product,  model: Product    # or a class
-
-  def call
-    Order.create customer: customer, product: product
-  end
-end
-```
-
-Now you can assign values as pre-initialized model instances:
-
-```ruby
-customer = Customer.find(1)
-product  = Product.find(2)
-
-order = CreateOrder.new(customer, product: product).call
-order.customer # => <Customer @id=1 ...>
-order.product  # => <Product @id=2 ...>
-```
-
-...or their ids:
-
-```ruby
-order = CreateOrder.new(1, product: 2).call
-order.customer # => <Customer @id=1 ...>
-order.product  # => <Product @id=2 ...>
-```
-
-The instance is envoked using method `find_by(id: ...)`.
-With wrong ids `nil` values are assigned to corresponding params and options:
-
-```ruby
-order = CreateOrder.new(0, product: 0).call
-order.customer # => nil
-order.product  # => nil
-```
-
-### Custom Keys
-
-You can specify custom `key` for searching model instance:
-
-```ruby
-require 'dry-initializer-rails'
-
-class CreateOrder
-  extend Dry::Initializer
-
-  param  :customer, model: 'User', find_by: 'name'
-  option :product,  model: Item,   find_by: :name
-end
-```
-
-This time you can send names (not ids) to the initializer:
-
-```ruby
-order = CreateOrder.new('Andrew', product: 'the_thing_no_123').call
-
-order.customer # => <User @name='Andrew' ...>
-order.product  # => <Item @name='the_thing_no_123' ...>
-```
-
-### Container Syntax
-
-If you prefer [container syntax](docs::container-version), extend plugin inside the block:
-
-```ruby
-require 'dry-initializer-rails'
-
-class CreateOrder
-  include Dry::Initializer.define -> do
-    # ... params/options declarations
-  end
-end
-```
-
-### Types vs Models
-
-[Type constraints](docs::type-constraints) are checked before the coercion.
-
-When mixing `:type` and `:model` settings for the same param/option, you should use [sum types](/gems/dry-types/1.2/sum) that accept both model instances and their attributes.

data/docsite/source/readers.html.md

@@ -1,43 +0,0 @@
----
-title: Readers
-layout: gem-single
-name: dry-initializer
----
-
-By default public attribute reader is defined for every param and option.
-
-You can define private or protected reader instead:
-
-```ruby
-require 'dry-initializer'
-
-class User
-  extend Dry::Initializer
-
-  param :name,  reader: :private   # the same as adding `private :name`
-  param :email, reader: :protected # the same as adding `protected :email`
-end
-```
-
-To skip any reader, use `reader: false`:
-
-```ruby
-require 'dry-initializer'
-
-class User
-  extend Dry::Initializer
-
-  param :name
-  param :email, reader: false
-end
-
-user = User.new 'Luke', 'luke@example.com'
-user.name  # => 'Luke'
-
-user.email                         # => #<NoMethodError ...>
-user.instance_variable_get :@email # => 'luke@example.com'
-```
-
-Notice that any other value except for `false`, `:protected` and `:private` provides a public reader.
-
-No writers are defined. Define them using pure ruby `attr_writer` when necessary.