dry-initializer 2.4.0 → 3.0.3

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

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

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

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

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

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

data/docsite/source/skip-undefined.html.md

@@ -0,0 +1,59 @@
+---
+title: Skip Undefined
+layout: gem-single
+name: dry-initializer
+---
+
+The initializer uses special constant `Dry::Initializer::UNDEFINED` to distinguish variables that are set to `nil` from those that are not set at all.
+
+When no value was provided, the constant is assigned to a variable, but hidden in a reader.
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+  option :email, optional: true
+end
+
+user = User.new
+
+user.email
+# => nil
+
+user.instance_variable_get :@email
+# => Dry::Initializer::UNDEFINED
+```
+
+This gives you full control of the real state of the attributes. However, all that checks cost about >30% of instantiation time, and make attribute readers 2 times slower.
+
+To avoid the overhead in cases you don't care about the differences between `nil` and undefined, you can use a light version of the module. Add `[undefined: false]` config to either `extend` or `include` line of code:
+
+```ruby
+extend Dry::Initializer[undefined: false]
+```
+
+```ruby
+include Dry::Initializer[undefined: false] -> do
+  # ...
+end
+```
+
+This time you should expect `nil` every time no value was given to an optional attribute:
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer[undefined: false]
+  option :email, optional: true
+end
+
+user = User.new
+
+user.email
+# => nil
+
+user.instance_variable_get :@email
+# => nil
+```

data/docsite/source/type-constraints.html.md

@@ -0,0 +1,160 @@
+---
+title: Type Constraints
+layout: gem-single
+name: dry-initializer
+---
+
+## Base Syntax
+
+Use `:type` key in a `param` or `option` declarations to add type coercer.
+
+```ruby
+require 'dry-initializer'
+
+class User
+  extend Dry::Initializer
+  param :name, type: proc(&:to_s)
+end
+
+user = User.new :Andrew
+user.name # => "Andrew"
+```
+
+Any object that responds to `#call` with 1 argument can be used as a type. Common examples are `proc(&:to_s)` for strings, `method(:Array)` (for arrays) or `Array.method(:wrap)` in Rails, `->(v) { !!v }` (for booleans), etc.
+
+## Dry Types as coercers
+
+Another important example is the usage of `dry-types` as type constraints:
+
+```ruby
+require 'dry-initializer'
+require 'dry-types'
+
+class User
+  extend Dry::Initializer
+  param :name, type: Dry::Types['strict.string']
+end
+
+user = User.new :Andrew # => #<TypeError ...>
+```
+
+## Positional Argument
+
+Instead of `:type` option you can send a constraint/coercer as the second argument:
+
+```ruby
+require 'dry-initializer'
+require 'dry-types'
+
+class User
+  extend Dry::Initializer
+  param :name,  Dry::Types['coercible.string']
+  param :email, proc(&:to_s)
+end
+```
+
+## Array Types
+
+As mentioned above, the `:type` option takes a callable object... with one important exception.
+
+You can use arrays for values that should be wrapped to array:
+
+```ruby
+class User
+  extend Dry::Initializer
+
+  option :name,   proc(&:to_s)
+  option :emails, [proc(&:to_s)]
+end
+
+user = User.new name: "joe", emails: :"joe@example.com"
+user.emails # => ["joe@example.com"]
+
+user = User.new name: "jane", emails: [:"jane@example.com", :"jane@example.org"]
+user.emails # => ["jane@example.com", "jane@example.org"]
+```
+
+You can wrap the coercer into several arrays as well:
+
+```ruby
+class User
+  extend Dry::Initializer
+
+  option :emails, [[proc(&:to_s)]]
+end
+
+user = User.new name: "joe", emails: "joe@example.com"
+user.emails # => [["joe@example.com"]]
+```
+
+Eventually, you can use an empty array as a coercer. In that case we just wrap the source value(s) into array, not modifying the items:
+
+```ruby
+class Article
+  extend Dry::Initializer
+
+  option :tags, []
+end
+
+article = Article.new(tags: 1)
+article.tags # => [1]
+```
+
+## Nested Options
+
+Sometimes you need to describe a structure with nested options. In this case you can use a block with `options` inside.
+
+```ruby
+class User
+  extend Dry::Initializer
+
+  option :name, proc(&:to_s)
+
+  option :emails, [] do
+    option :address,     proc(&:to_s)
+    option :description, proc(&:to_s)
+  end
+end
+
+user = User.new name: "joe",
+                emails: { address: "joe@example.com", description: "Job email" }
+
+user.emails.class         # => Array
+user.emails.first.class   # => User::Emails
+user.emails.first.address # => "joe@example.com"
+
+user.emails.to_h # => [{ address: "joe@example.com", description: "Job email" }]
+```
+
+Notice how we mixed array wrapper with a nested type.
+
+The only syntax restriction here is that you cannot use a positional `param` _inside_ the block.
+
+## Back References
+
+Sometimes you need to refer back to the initialized instance. In this case use a second argument to explicitly give the instance to a coercer:
+
+```ruby
+class Location < String
+  attr_reader :parameter # refers back to its parameter
+
+  def initialize(name, parameter)
+    super(name)
+    @parameter = parameter
+  end
+end
+
+class Parameter
+  extend Dry::Initializer
+  param :name
+  param :location, ->(value, param) { Location.new(value, param) }
+end
+
+offset = Parameter.new "offset", location: "query"
+offset.name     # => "offset"
+offset.location # => "query"
+offset.location.parameter == offset # true
+```
+
+[dry-types]: https://github.com/dry-rb/dry-types
+[dry-types-docs]: http://dry-rb.org/gems/dry-types/