dry-types 1.2.2 → 1.5.1

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
-    ```

data/docsite/source/hash-schemas.html.md

@@ -1,169 +0,0 @@
----
-title: Hash Schemas
-layout: gem-single
-name: dry-types
----
-
-It is possible to define a type for a hash with a known set of keys and corresponding value types. Let's say you want to describe a hash containing the name and the age of a user:
-
-```ruby
-# using simple kernel coercions
-user_hash = Types::Hash.schema(name: Types::String, age: Types::Coercible::Integer)
-
-user_hash[name: 'Jane', age: '21']
-# => { name: 'Jane', age: 21 }
-# :name left untouched and :age was coerced to Integer
-```
-
-If a value doesn't conform to the type, an error is raised:
-
-```ruby
-user_hash[name: :Jane, age: '21']
-# => Dry::Types::SchemaError: :Jane (Symbol) has invalid type
-#    for :name violates constraints (type?(String, :Jane) failed)
-```
-
-All keys are required by default:
-
-```ruby
-user_hash[name: 'Jane']
-# => Dry::Types::MissingKeyError: :age is missing in Hash input
-```
-
-Extra keys are omitted by default:
-
-```ruby
-user_hash[name: 'Jane', age: '21', city: 'London']
-# => { name: 'Jane', age: 21 }
-```
-
-### Default values
-
-Default types are **only** evaluated if the corresponding key is missing in the input:
-
-```ruby
-user_hash = Types::Hash.schema(
-  name: Types::String,
-  age: Types::Integer.default(18)
-)
-user_hash[name: 'Jane']
-# => { name: 'Jane', age: 18 }
-
-# nil violates the constraint
-user_hash[name: 'Jane', age: nil]
-# => Dry::Types::SchemaError: nil (NilClass) has invalid type
-#    for :age violates constraints (type?(Integer, nil) failed)
-```
-
-In order to evaluate default types on `nil`, wrap your type with a constructor and map `nil` to `Dry::Types::Undefined`:
-
-```ruby
-user_hash = Types::Hash.schema(
-  name: Types::String,
-  age: Types::Integer.
-         default(18).
-         constructor { |value|
-           value.nil? ? Dry::Types::Undefined : value
-         }
-)
-
-user_hash[name: 'Jane', age: nil]
-# => { name: 'Jane', age: 18 }
-```
-
-The process of converting types to constructors like that can be automated, see "Type transformations" below.
-
-### Optional keys
-
-By default, all keys are required to present in the input. You can mark a key as optional by adding `?` to its name:
-
-```ruby
-user_hash = Types::Hash.schema(name: Types::String, age?: Types::Integer)
-
-user_hash[name: 'Jane']
-# => { name: 'Jane' }
-```
-
-### Extra keys
-
-All keys not declared in the schema are silently ignored. This behavior can be changed by calling `.strict` on the schema:
-
-```ruby
-user_hash = Types::Hash.schema(name: Types::String).strict
-user_hash[name: 'Jane', age: 21]
-# => Dry::Types::UnknownKeysError: unexpected keys [:age] in Hash input
-```
-
-### Transforming input keys
-
-Keys are supposed to be symbols but you can attach a key tranformation to a schema, e.g. for converting strings into symbols:
-
-```ruby
-user_hash = Types::Hash.schema(name: Types::String).with_key_transform(&:to_sym)
-user_hash['name' => 'Jane']
-
-# => { name: 'Jane' }
-```
-
-### Inheritance
-
-Hash schemas can be inherited in a sense you can define a new schema based on an existing one. Declared keys will be merged, key and type transformations will be preserved. The `strict` option is also passed to the new schema if present.
-
-```ruby
-# Building an empty base schema
-StrictSymbolizingHash = Types::Hash.schema({}).strict.with_key_transform(&:to_sym)
-
-user_hash = StrictSymbolizingHash.schema(
-  name: Types::String
-)
-
-user_hash['name' => 'Jane']
-# => { name: 'Jane' }
-
-user_hash['name' => 'Jane', 'city' => 'London']
-# => Dry::Types::UnknownKeysError: unexpected keys [:city] in Hash input
-```
-
-### Transforming types
-
-A schema can transform types with a block. For example, the following code makes all keys optional:
-
-```ruby
-user_hash = Types::Hash.with_type_transform { |type| type.required(false) }.schema(
-  name: Types::String,
-  age: Types::Integer
-)
-
-user_hash[name: 'Jane']
-# => { name: 'Jane' }
-user_hash[{}]
-# => {}
-```
-
-Type transformations work perfectly with inheritance, you don't have to define same rules more than once:
-
-```ruby
-SymbolizeAndOptionalSchema = Types::Hash
-  .schema({})
-  .with_key_transform(&:to_sym)
-  .with_type_transform { |type| type.required(false) }
-
-user_hash = SymbolizeAndOptionalSchema.schema(
-  name: Types::String,
-  age: Types::Integer
-)
-
-user_hash['name' => 'Jane']
-```
-
-You can check key name by calling `.name` on the type argument:
-
-```ruby
-Types::Hash.with_type_transform do |key|
-  if key.name.to_s.end_with?('_at')
-    key.constructor { |v| Time.iso8601(v) }
-  else
-    key
-  end
-end
-```

data/docsite/source/index.html.md

@@ -1,156 +0,0 @@
----
-title: Introduction
-layout: gem-single
-type: gem
-name: dry-types
-sections:
-  - getting-started
-  - built-in-types
-  - optional-values
-  - default-values
-  - sum
-  - constraints
-  - hash-schemas
-  - array-with-member
-  - enum
-  - map
-  - custom-types
-  - extensions
----
-
-`dry-types` is a simple and extendable type system for Ruby; useful for value coercions, applying constraints, defining complex structs or value objects and more. It was created as a successor to [Virtus](https://github.com/solnic/virtus).
-
-### Example usage
-
-```ruby
-require 'dry-types'
-require 'dry-struct'
-
-module Types
-  include Dry.Types()
-end
-
-User = Dry.Struct(name: Types::String, age: Types::Integer)
-
-User.new(name: 'Bob', age: 35)
-# => #<User name="Bob" age=35>
-```
-
-See [Built-in Types](docs::built-in-types/) for a full list of available types.
-
-By themselves, the basic type definitions like `Types::String` and `Types::Integer` don't do anything except provide documentation about which type an attribute is expected to have. However, there are many more advanced possibilities:
-
-- `Strict` types will raise an error if passed an attribute of the wrong type:
-
-```ruby
-class User < Dry::Struct
-  attribute :name, Types::Strict::String
-  attribute :age,  Types::Strict::Integer
-end
-
-User.new(name: 'Bob', age: '18')
-# => Dry::Struct::Error: [User.new] "18" (String) has invalid type for :age
-```
-
-- `Coercible` types will attempt to convert an attribute to the correct class
-  using Ruby's built-in coercion methods:
-
-```ruby
-class User < Dry::Struct
-  attribute :name, Types::Coercible::String
-  attribute :age,  Types::Coercible::Integer
-end
-
-User.new(name: 'Bob', age: '18')
-# => #<User name="Bob" age=18>
-User.new(name: 'Bob', age: 'not coercible')
-# => ArgumentError: invalid value for Integer(): "not coercible"
-```
-
-- Use `.optional` to denote that an attribute can be `nil` (see [Optional Values](docs::optional-values)):
-
-```ruby
-class User < Dry::Struct
-  attribute :name, Types::String
-  attribute :age,  Types::Integer.optional
-end
-
-User.new(name: 'Bob', age: nil)
-# => #<User name="Bob" age=nil>
-# name is not optional:
-User.new(name: nil, age: 18)
-# => Dry::Struct::Error: [User.new] nil (NilClass) has invalid type for :name
-# keys must still be present:
-User.new(name: 'Bob')
-# => Dry::Struct::Error: [User.new] :age is missing in Hash input
-```
-
-- Add custom constraints (see [Constraints](docs::constraints.html)):
-
-```ruby
-class User < Dry::Struct
-  attribute :name, Types::Strict::String
-  attribute :age,  Types::Strict::Integer.constrained(gteq: 18)
-end
-
-User.new(name: 'Bob', age: 17)
-# => Dry::Struct::Error: [User.new] 17 (Fixnum) has invalid type for :age
-```
-
-- Add custom metadata to a type:
-
-```ruby
-class User < Dry::Struct
-  attribute :name, Types::String
-  attribute :age,  Types::Integer.meta(info: 'extra info about age')
-end
-```
-
-- Pass values directly to `Dry::Types` without creating an object using `[]`:
-
-```ruby
-Types::Strict::String["foo"]
-# => "foo"
-Types::Strict::String["10000"]
-# => "10000"
-Types::Coercible::String[10000]
-# => "10000"
-Types::Strict::String[10000]
-# Dry::Types::ConstraintError: 1000 violates constraints
-```
-
-### Features
-
-* Support for [constrained types](docs::constraints)
-* Support for [optional values](docs::optional-values)
-* Support for [default values](docs::default-values)
-* Support for [sum types](docs::sum)
-* Support for [enums](docs::enum)
-* Support for [hash type with type schemas](docs::hash-schemas)
-* Support for [array type with members](docs::array-with-member)
-* Support for arbitrary meta information
-* Support for typed struct objects via [dry-struct](/gems/dry-struct)
-* Types are [categorized](docs::built-in-types), which is especially important for optimized and dedicated coercion logic
-* Types are composable and reusable objects
-* No const-missing magic and complicated const lookups
-* Roughly 6-10 x faster than Virtus
-
-### Use cases
-
-`dry-types` is suitable for many use-cases, for example:
-
-  * Value coercions
-  * Processing arrays
-  * Processing hashes with explicit schemas
-  * Defining various domain-specific information shared between multiple parts of your application
-  * Annotating objects
-
-### Other gems using dry-types
-
-`dry-types` is often used as a low-level abstraction. The following gems use it already:
-
-* [dry-struct](/gems/dry-struct)
-* [dry-initializer](/gems/dry-initializer)
-* [Hanami](http://hanamirb.org)
-* [rom-rb](http://rom-rb.org)
-* [Trailblazer](http://trailblazer.to)