dry-initializer 3.0.1 → 3.0.2

data/CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Issue Guidelines
+
+## Reporting bugs
+
+If you found a bug, report an issue and describe what's the expected behavior versus what actually happens. If the bug causes a crash, attach a full backtrace. If possible, a reproduction script showing the problem is highly appreciated.
+
+## Reporting feature requests
+
+Report a feature request **only after discussing it first on [discourse.dry-rb.org](https://discourse.dry-rb.org)** where it was accepted. Please provide a concise description of the feature, don't link to a discussion thread, and instead summarize what was discussed.
+
+## Reporting questions, support requests, ideas, concerns etc.
+
+**PLEASE DON'T** - use [discourse.dry-rb.org](http://discourse.dry-rb.org) instead.
+
+# Pull Request Guidelines
+
+A Pull Request will only be accepted if it addresses a specific issue that was reported previously, or fixes typos, mistakes in documentation etc.
+
+Other requirements:
+
+1) Do not open a pull request if you can't provide tests along with it. If you have problems writing tests, ask for help in the related issue.
+2) Follow the style conventions of the surrounding code. In most cases, this is standard ruby style.
+3) Add API documentation if it's a new feature
+4) Update API documentation if it changes an existing feature
+5) Bonus points for sending a PR to [github.com/dry-rb/dry-rb.org](github.com/dry-rb/dry-rb.org) which updates user documentation and guides
+
+# Asking for help
+
+If these guidelines aren't helpful, and you're stuck, please post a message on [discourse.dry-rb.org](https://discourse.dry-rb.org) or join [our chat](https://dry-rb.zulipchat.com).

data/Gemfile

@@ -3,27 +3,36 @@ source "https://rubygems.org"
 # Specify your gem"s dependencies in dry-initializer.gemspec
 gemspec
 
-group :benchmarks do
-  if RUBY_VERSION < "2.4"
-    gem "activesupport", "< 5"
-  else
-    gem "activesupport"
-  end
+unless ENV['CI'].eql?('true')
+  group :benchmarks do
+    if RUBY_VERSION < "2.4"
+      gem "activesupport", "< 5"
+    else
+      gem "activesupport"
+    end
 
-  gem "active_attr"
-  gem "anima"
-  gem "attr_extras"
-  gem "benchmark-ips", "~> 2.5"
-  gem "concord"
-  gem "fast_attributes"
-  gem "kwattr"
-  gem "ruby-prof", platform: :mri
-  gem "value_struct"
-  gem "values"
-  gem "virtus"
+    gem "active_attr"
+    gem "anima"
+    gem "attr_extras"
+    gem "benchmark-ips", "~> 2.5"
+    gem "concord"
+    gem "fast_attributes"
+    gem "kwattr"
+    gem "ruby-prof", platform: :mri
+    gem "value_struct"
+    gem "values"
+    gem "virtus"
+  end
 end
 
 group :development, :test do
   gem "pry", platform: :mri
   gem "pry-byebug", platform: :mri
+  if RUBY_VERSION >= "2.4"
+    gem 'ossy', git: 'https://github.com/solnic/ossy.git', branch: 'master', platform: :mri
+  end
+end
+
+group :test do
+  gem 'simplecov', require: false
 end

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2019 dry-rb team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,20 +1,20 @@
-# dry-initializer [![Join the chat at https://gitter.im/dry-rb/chat](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dry-rb/chat)
+# dry-initializer [![Join the chat at https://dry-rb.zulipchat.com](https://img.shields.io/badge/dry--rb-join%20chat-%23346b7a.svg)][chat]
 
 [![Gem Version](https://badge.fury.io/rb/dry-initializer.svg)][gem]
-[![Build Status](https://travis-ci.org/dry-rb/dry-initializer.svg?branch=master)][travis]
+[![Build Status](https://github.com/dry-rb/dry-initializer/workflows/ci/badge.svg)][ci]
 [![Code Climate](https://codeclimate.com/github/dry-rb/dry-initializer/badges/gpa.svg)][codeclimate]
-[![Test Coverage](https://codeclimate.com/github/dry-rb/dry-initializer/badges/coverage.svg)][coveralls]
+[![Test Coverage](https://api.codeclimate.com/v1/badges/73cb64231f3fb2c86e26/test_coverage)][codeclimate]
 [![Inline docs](http://inch-ci.org/github/dry-rb/dry-initializer.svg?branch=master)][inchpages]
 
 [gem]: https://rubygems.org/gems/dry-initializer
-[travis]: https://travis-ci.org/dry-rb/dry-initializer
-[gemnasium]: https://gemnasium.com/dry-rb/dry-initializer
+[ci]: https://github.com/dry-rb/dry-initializer/actions?query=workflow%3Aci
 [codeclimate]: https://codeclimate.com/github/dry-rb/dry-initializer
 [coveralls]: https://coveralls.io/r/dry-rb/dry-initializer
 [inchpages]: http://inch-ci.org/github/dry-rb/dry-initializer
 [docs]: http://dry-rb.org/gems/dry-initializer/
 [benchmarks]: https://github.com/dry-rb/dry-initializer/wiki
 [license]: http://opensource.org/licenses/MIT
+[chat]: https://dry-rb.zulipchat.com
 
 DSL for building class initializer with params and options.
 
@@ -77,14 +77,13 @@ Tested under rubies [compatible to MRI 2.3+](.travis.yml).
 
 ## Contributing
 
-* [Fork the project](https://github.com/dry-rb/dry-initializer)
-* Create your feature branch (`git checkout -b my-new-feature`)
-* Add tests for it
-* Commit your changes (`git commit -am '[UPDATE] Add some feature'`)
-* Push to the branch (`git push origin my-new-feature`)
-* Create a new Pull Request
+- [Fork the project](https://github.com/dry-rb/dry-initializer)
+- Create your feature branch (`git checkout -b my-new-feature`)
+- Add tests for it
+- Commit your changes (`git commit -am '[UPDATE] Add some feature'`)
+- Push to the branch (`git push origin my-new-feature`)
+- Create a new Pull Request
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License][license].
-

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