dry-types 1.2.2 → 1.3.0

data/docsite/source/constraints.html.md

@@ -1,31 +0,0 @@
----
-title: Constraints
-layout: gem-single
-name: dry-types
----
-
-You can create constrained types that will use validation rules to check that the input is not violating any of the configured constraints. You can treat it as a lower level guarantee that you're not instantiating objects that are broken.
-
-All types support the constraints API, but not all constraints are suitable for a particular primitive, it's up to you to set up constraints that make sense.
-
-Under the hood it uses [`dry-logic`](/gems/dry-logic) and all of its predicates are supported.
-
-``` ruby
-string = Types::String.constrained(min_size: 3)
-
-string['foo']
-# => "foo"
-
-string['fo']
-# => Dry::Types::ConstraintError: "fo" violates constraints
-
-email = Types::String.constrained(
-  format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z/i
-)
-
-email["jane@doe.org"]
-# => "jane@doe.org"
-
-email["jane"]
-# => Dry::Types::ConstraintError: "jane" violates constraints
-```

data/docsite/source/custom-types.html.md

@@ -1,93 +0,0 @@
----
-title: Custom Types
-layout: gem-single
-name: dry-types
----
-
-There are a bunch of helpers for building your own types based on existing classes and values. These helpers are automatically defined if you're imported types in a module.
-
-### `Types.Instance`
-
-`Types.Instance` builds a type that checks if a value has the given class.
-
-```ruby
-range_type = Types.Instance(Range)
-range_type[1..2] # => 1..2
-```
-
-### `Types.Value`
-
-`Types.Value` builds a type that checks a value for equality (using `==`).
-
-```ruby
-valid = Types.Value('valid')
-valid['valid'] # => 'valid'
-valid['invalid']
-# => Dry::Types::ConstraintError: "invalid" violates constraints (eql?("valid", "invalid") failed)
-```
-
-### `Types.Constant`
-
-`Types.Constant` builds a type that checks a value for identity (using `equal?`).
-
-```ruby
-valid = Types.Constant(:valid)
-valid[:valid] # => :valid
-valid[:invalid]
-# => Dry::Types::ConstraintError: :invalid violates constraints (is?(:valid, :invalid) failed)
-```
-
-### `Types.Constructor`
-
-`Types.Constructor` builds a new constructor type for the given class. By default uses the `new` method as a constructor.
-
-```ruby
-user_type = Types.Constructor(User)
-
-# It is equivalent to User.new(name: 'John')
-user_type[name: 'John']
-
-# Using a block
-user_type = Types.Constructor(User) { |values| User.new(values) }
-```
-
-### `Types.Nominal`
-
-`Types.Nominal` wraps the given class with a simple definition without any behavior attached.
-
-```ruby
-int = Types.Nominal(Integer)
-int[1] # => 1
-
-# The type doesn't have any checks
-int['one'] # => 'one'
-```
-
-### `Types.Hash`
-
-`Types.Hash` builds a new hash schema.
-
-```ruby
-# In the full form
-Types::Hash.schema(name: Types::String, age: Types::Coercible::Integer)
-
-# Using Types.Hash()
-Types.Hash(:permissive, name: Types::String, age: Types::Coercible::Integer)
-```
-
-### `Types.Array`
-
-`Types.Array` is a shortcut for `Types::Array.of`
-
-```ruby
-ListOfStrings = Types.Array(Types::String)
-```
-
-### `Types.Interface`
-
-`Types.Interface` builds a type that checks a value responds to given methods.
-
-```ruby
-Callable = Types.Interface(:call)
-Contact = Types.Interface(:name, :phone)
-```

data/docsite/source/default-values.html.md

@@ -1,91 +0,0 @@
----
-title: Default Values
-layout: gem-single
-name: dry-types
----
-
-A type with a default value will return the configured value when the input is not defined:
-
-``` ruby
-PostStatus = Types::String.default('draft')
-
-PostStatus[] # "draft"
-PostStatus["published"] # "published"
-PostStatus[true] # raises ConstraintError
-```
-
-It works with a callable value:
-
-``` ruby
-CallableDateTime = Types::DateTime.default { DateTime.now }
-
-CallableDateTime[]
-# => #<DateTime: 2017-05-06T00:43:06+03:00 ((2457879j,78186s,649279000n),+10800s,2299161j)>
-CallableDateTime[]
-# => #<DateTime: 2017-05-06T00:43:07+03:00 ((2457879j,78187s,635494000n),+10800s,2299161j)>
-```
-
-`Dry::Types::Undefined` can be passed explicitly as a missing value:
-
-```ruby
-PostStatus = Types::String.default('draft')
-
-PostStatus[Dry::Types::Undefined] # "draft"
-```
-
-It also receives the type constructor as an argument:
-
-```ruby
-CallableDateTime = Types::DateTime.constructor(&:to_datetime).default { |type| type[Time.now] }
-
-CallableDateTime[Time.now]
-# => #<DateTime: 2017-05-06T01:13:06+03:00 ((2457879j,79986s,63464000n),+10800s,2299161j)>
-CallableDateTime[Date.today]
-# => #<DateTime: 2017-05-06T00:00:00+00:00 ((2457880j,0s,0n),+0s,2299161j)>
-CallableDateTime[]
-# => #<DateTime: 2017-05-06T01:13:06+03:00 ((2457879j,79986s,63503000n),+10800s,2299161j)>
-```
-
-**Be careful:** types will return the **same instance** of the default value every time. This may cause problems if you mutate the returned value after receiving it:
-
-```ruby
-default_0 = PostStatus.()
-# => "draft"
-default_1 = PostStatus.()
-# => "draft"
-
-# Both variables point to the same string:
-default_0.object_id == default_1.object_id
-# => true
-
-# Mutating the string will change the default value of type:
-default_0 << '_mutated'
-PostStatus.(nil)
-# => "draft_mutated" # not "draft"
-```
-
-You can guard against these kind of errors by calling `freeze` when setting the default:
-
-```ruby
-PostStatus = Types::Params::String.default('draft'.freeze)
-default = PostStatus.()
-default << 'attempt to mutate default'
-# => RuntimeError: can't modify frozen string
-
-# If you really want to mutate it, call `dup` on it first:
-default = default.dup
-default << "this time it'll work"
-```
-
-**Warning on using with constrained types**: If the value passed to the `.default` block does not match the type constraints, this will not throw an exception, because it is not passed to the constructor and will be used as is.
-
-```ruby
-CallableDateTime = Types::DateTime.constructor(&:to_datetime).default { Time.now }
-
-CallableDateTime[Time.now]
-# => #<DateTime: 2017-05-06T00:50:09+03:00 ((2457879j,78609s,839588000n),+10800s,2299161j)>
-CallableDateTime[Date.today]
-# => #<DateTime: 2017-05-06T00:00:00+00:00 ((2457880j,0s,0n),+0s,2299161j)>
-CallableDateTime[]
-# => 2017-05-06 00:50:15 +0300
-```

data/docsite/source/enum.html.md

@@ -1,69 +0,0 @@
----
-title: Enum
-layout: gem-single
-name: dry-types
----
-
-In many cases you may want to define an enum. For example, in a blog application a post may have a finite list of statuses. Apart from accessing the current status value, it is useful to have all possible values accessible too. Furthermore, an enum can be a map from, e.g., strings to integers. This is useful for mapping externally-provided integer values to human-readable strings without explicit conversions, see examples.
-
-``` ruby
-require 'dry-types'
-require 'dry-struct'
-
-module Types
-  include Dry.Types()
-end
-
-class Post < Dry::Struct
-  Statuses = Types::String.enum('draft', 'published', 'archived')
-
-  attribute :title, Types::String
-  attribute :body, Types::String
-  attribute :status, Statuses
-end
-
-# enum values are frozen, let's be paranoid, doesn't hurt and have potential to
-# eliminate silly bugs
-Post::Statuses.values.frozen? # => true
-Post::Statuses.values.all?(&:frozen?) # => true
-
-Post::Statuses['draft'] # => "draft"
-
-# it'll raise if something silly was passed in
-Post::Statuses['something silly']
-# => Dry::Types::ConstraintError: "something silly" violates constraints
-
-# nil is considered as something silly too
-Post::Statuses[nil]
-# => Dry::Types::ConstraintError: nil violates constraints
-```
-
-Note that if you want to define an enum type with a default, you must call `.default` *before* calling `.enum`, not the other way around:
-
-```ruby
-# this is the correct usage:
-Dry::Types::String.default('red').enum('blue', 'green', 'red')
-
-# this will raise an error:
-Dry::Types::String.enum('blue', 'green', 'red').default('red')
-```
-
-### Mappings
-
-A classic example is mapping integers coming from somewhere (API/database/etc) to something more understandable:
-
-```ruby
-class Cell < Dry::Struct
-  attribute :state, Types::String.enum('locked' => 0, 'open' => 1)
-end
-
-
-Cell.new(state: 'locked')
-# => #<Cell state="locked">
-
-# Integers are accepted too
-Cell.new(state: 0)
-# => #<Cell state="locked">
-Cell.new(state: 1)
-# => #<Cell state="open">
-```

data/docsite/source/extensions.html.md

@@ -1,15 +0,0 @@
----
-title: Extensions
-layout: gem-single
-name: dry-types
-sections:
-  - maybe
-  - monads
----
-
-`dry-types` can be extended with extension. Those extensions are loaded with `Dry::Types.load_extensions`.
-
-Available extensions:
-
-- [Maybe](docs::extensions/maybe)
-- [Monads](docs::extensions/monads)

data/docsite/source/extensions/maybe.html.md

@@ -1,57 +0,0 @@
----
-title: Maybe
-layout: gem-single
-name: dry-types
----
-
-The [dry-monads gem](/gems/dry-monads/) provides approach to handling optional values by returning a [_Monad_](/gems/dry-monads/) object. This allows you to pass your type to a `Maybe(x)` block that only executes if `x` returns `Some` or `None`.
-
-> NOTE: Requires the [dry-monads gem](/gems/dry-monads/) to be loaded.
-1. Load the `:maybe` extension in your application.
-
-```ruby
-require 'dry-types'
-
-Dry::Types.load_extensions(:maybe)
-module Types
-  include Dry.Types()
-end
-```
-
-2. Append `.maybe` to a _Type_ to return a _Monad_ object  
-
-```ruby
-x = Types::Maybe::Strict::Integer[nil]
-Maybe(x) { puts(x) }
-x = Types::Maybe::Coercible::String[nil]
-Maybe(x) { puts(x) }
-x = Types::Maybe::Strict::Integer[123]
-Maybe(x) { puts(x) }
-x = Types::Maybe::Strict::String[123]
-Maybe(x) { puts(x) }
-```
-
-```ruby
-Types::Maybe::Strict::Integer[nil] # None
-Types::Maybe::Strict::Integer[123] # Some(123)
-Types::Maybe::Coercible::Float[nil] # None
-Types::Maybe::Coercible::Float['12.3'] # Some(12.3)
-# 'Maybe' types can also accessed by calling '.maybe' on a regular type:
-Types::Strict::Integer.maybe # equivalent to Types::Maybe::Strict::Integer
-```
-
-You can define your own optional types:
-
-``` ruby
-maybe_string = Types::Strict::String.maybe
-maybe_string[nil]
-# => None
-maybe_string[nil].fmap(&:upcase)
-# => None
-maybe_string['something']
-# => Some('something')
-maybe_string['something'].fmap(&:upcase)
-# => Some('SOMETHING')
-maybe_string['something'].fmap(&:upcase).value_or('NOTHING')
-# => "SOMETHING"
-```

data/docsite/source/extensions/monads.html.md

@@ -1,61 +0,0 @@
----
-title: Monads
-layout: gem-single
-name: dry-types
----
-
-The monads extension makes `Dry::Types::Result` objects compatible with `dry-monads`.
-
-To enable the extension:
-
-```ruby
-require 'dry/types'
-Dry::Types.load_extensions(:monads)
-```
-
-After loading the extension, you can leverage monad API:
-
-```ruby
-Types = Dry.Types()
-
-result = Types::String.try('Jane')
-result.class #=> Dry::Types::Result::Success
-monad = result.to_monad
-monad.class #=> Dry::Monads::Result::Success
-monad.value!  # => 'Jane'
-result = Types::String.try(nil)
-result.class #=> Dry::Types::Result::Failure
-monad = result.to_monad
-monad.class #=> Dry::Monads::Result::Failure
-monad.failure  # => [#<Dry::Types::ConstraintError>, nil]
-Types::String.try(nil)
-  .to_monad
-  .fmap { |result| puts "passed: #{result.inspect}" }
-  .or   { |error, input| puts "input '#{input.inspect}' failed with error: #{error.to_s}" }
-```
-
-This can be useful when used with `dry-monads` and the [`do` notation](/gems/dry-monads/1.0/do-notation/):
-
-```ruby
-require 'dry/types'
-Types = Dry.Types()
-Dry::Types.load_extensions(:monads)
-
-class AddTen
-  include Dry::Monads[:result, :do]
-
-  def call(input)
-    integer = yield Types::Coercible::Integer.try(input)
-
-    Success(integer + 10)
-  end
-end
-
-add_ten = AddTen.new
-
-add_ten.call(10)
-# => Success(20)
-
-add_ten.call('integer')
-# => Failure([#<Dry::Types::CoercionError: invalid value for Integer(): "integer">, "integer"])
-```

data/docsite/source/getting-started.html.md

@@ -1,57 +0,0 @@
----
-title: Getting Started
-layout: gem-single
-name: dry-types
----
-
-### Using `Dry::Types` in Your Application
-
-1. Make `Dry::Types` available to the application by creating a namespace that includes `Dry::Types`:
-
-    ```ruby
-    module Types
-     include Dry.Types()
-    end
-    ```
-   
-2. Reload the environment, & type `Types::Coercible::String` in the ruby console to confirm it worked:
-
-    ``` ruby
-    Types::Coercible::String
-    # => #<Dry::Types::Constructor type=#<Dry::Types::Definition primitive=String options={}>>
-    ```
-
-### Creating Your First Type
-
-1. Define a struct's types by passing the name & type to the `attribute` method:
-
-    ```ruby
-    class User < Dry::Struct
-      attribute :name, Types::String
-    end
-    ```
-
-2. Define [Custom Types](docs::custom-types) in the `Types` module, then pass the name & type to `attribute`:
-
-    ```ruby
-    module Types
-      include Dry.Types()
-    
-      Email = String.constrained(format: /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z]+)*\.[a-z]+\z/i)
-      Age = Integer.constrained(gt: 18)
-    end
-    class User < Dry::Struct
-      attribute :name, Types::String
-      attribute :email, Types::Email
-      attribute :age, Types::Age
-    end
-    ```
-
-3. Use a `Dry::Struct` as a type:
-
-    ```ruby
-    class Message < Dry::Struct
-      attribute :body, Types::String
-      attribute :to, User
-    end
-    ```