dry-initializer 3.0.3 → 3.0.4

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.

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

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

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