dry-monads 1.3.2 → 1.4.0

data/docsite/source/list.html.md

@@ -1,87 +0,0 @@
----
-title: List
-layout: gem-single
-name: dry-monads
----
-
-### `bind`
-
-Lifts a block/proc and runs it against each member of the list. The block must return a value coercible to a list. As in other monads if no block given the first argument will be treated as callable and used instead.
-
-```ruby
-require 'dry/monads/list'
-
-M = Dry::Monads
-
-M::List[1, 2].bind { |x| [x + 1] } # => List[2, 3]
-M::List[1, 2].bind(-> x { [x, x + 1] }) # => List[1, 2, 2, 3]
-
-M::List[1, nil].bind { |x| [x + 1] } # => error
-```
-
-### `fmap`
-
-Maps a block over the list. Acts as `Array#map`. As in other monads, if no block given the first argument will be treated as callable and used instead.
-
-```ruby
-require 'dry/monads/list'
-
-M = Dry::Monads
-
-M::List[1, 2].fmap { |x| x + 1 } # => List[2, 3]
-```
-
-### `value`
-
-You always can unwrap the result by calling `value`.
-
-```ruby
-require 'dry/monads/list'
-
-M = Dry::Monads
-
-M::List[1, 2].value # => [1, 2]
-```
-
-### Concatenation
-
-```ruby
-require 'dry/monads/list'
-
-M = Dry::Monads
-
-M::List[1, 2] + M::List[3, 4] # => List[1, 2, 3, 4]
-```
-
-### `head` and `tail`
-
-`head` returns the first element wrapped with a `Maybe`.
-
-```ruby
-require 'dry/monads/list'
-
-M = Dry::Monads
-
-M::List[1, 2, 3, 4].head # => Some(1)
-M::List[1, 2, 3, 4].tail # => List[2, 3, 4]
-```
-
-### `traverse`
-
-Traverses the list with a block (or without it). This method "flips" List structure with the given monad (obtained from the type).
-
-**Note that traversing requires the list to be typed.**
-
-```ruby
-require 'dry/monads/list'
-
-M = Dry::Monads
-
-M::List[M::Success(1), M::Success(2)].typed(M::Result).traverse # => Success([1, 2])
-M::List[M::Maybe(1), M::Maybe(nil), M::Maybe(3)].typed(M::Maybe).traverse # => None
-
-# also, you can use fmap with #traverse
-
-M::List[1, 2].fmap { |x| M::Success(x) }.typed(M::Result).traverse # => Success([1, 2])
-M::List[1, nil, 3].fmap { |x| M::Maybe(x) }.typed(M::Maybe).traverse # => None
-```

data/docsite/source/maybe.html.md

@@ -1,146 +0,0 @@
----
-title: Maybe
-layout: gem-single
-name: dry-monads
----
-
-The `Maybe` monad is used when a series of computations could return `nil` at any point.
-
-### `bind`
-
-Applies a block to a monadic value. If the value is `Some` then calls the block passing the unwrapped value as an argument. Returns itself if the value is `None`.
-
-```ruby
-extend Dry::Monads[:maybe]
-
-maybe_user = Maybe(user).bind do |u|
-  Maybe(u.address).bind do |a|
-    Maybe(a.street)
-  end
-end
-
-# If user with address exists
-# => Some("Street Address")
-# If user or address is nil
-# => None()
-
-# You also can pass a proc to #bind
-
-add_two = -> (x) { Maybe(x + 2) }
-
-Maybe(5).bind(add_two).bind(add_two) # => Some(9)
-Maybe(nil).bind(add_two).bind(add_two) # => None()
-
-```
-
-### `fmap`
-
-Similar to `bind` but works with blocks/methods that returns unwrapped values (i.e. not `Maybe` instances).
-
-```ruby
-extend Dry::Monads[:maybe]
-
-Maybe(10).fmap { |x| x + 5 }.fmap { |y| y * 2 }
-# => Some(30)
-```
-
-In 1.x `Maybe#fmap` coerces `nil` values returned from blocks to `None`. This behavior will be changed in 2.0. This will be done because implicit coercion violates the functor laws which in order can lead to a surpising (not in a good sense) behavior. If you expect a block to return `nil`, use `Maybe#maybe` added in 1.3.
-
-### `maybe`
-
-Almost identical to `Maybe#fmap` but maps `nil` to `None`. This is similar to how the `&.` operator works in Ruby but does wrapping:
-
-```ruby
-extend Dry::Monads[:maybe]
-
-Maybe(user).maybe(&:address).maybe(&:street)
-
-# If user with address exists
-# => Some("Street Address")
-# If user or address is nil
-# => None()
-```
-
-### `value!`
-
-You always can extract the result by calling `value!`. It will raise an error if you call it on `None`. You can use `value_or` for safe unwrapping.
-
-```ruby
-extend Dry::Monads[:maybe]
-
-Some(5).fmap(&:succ).value! # => 6
-
-None().fmap(&:succ).value!
-# => Dry::Monads::UnwrapError: value! was called on None
-
-```
-
-### `value_or`
-
-Has one argument, unwraps the value in case of `Some` or returns the argument value back in case of `None`. It's a safe and recommended way of extracting values.
-
-```ruby
-extend Dry::Monads[:maybe]
-
-add_two = -> (x) { Maybe(x + 2) }
-
-Maybe(5).bind(add_two).value_or(0) # => 7
-Maybe(nil).bind(add_two).value_or(0) # => 0
-
-Maybe(nil).bind(add_two).value_or { 0 } # => 0
-```
-
-### `or`
-
-The opposite of `bind`.
-
-```ruby
-extend Dry::Monads[:maybe]
-
-add_two = -> (x) { Maybe(x + 2) }
-
-Maybe(5).bind(add_two).or(Some(0)) # => Some(7)
-Maybe(nil).bind(add_two).or(Some(0)) # => Some(0)
-
-Maybe(nil).bind(add_two).or { Some(0) } # => Some(0)
-```
-
-### `and`
-
-Two values can be chained using `.and`:
-
-```ruby
-extend Dry::Monads[:maybe]
-
-Some(5).and(Some(10)) { |x, y| x + y } # => Some(15)
-Some(5).and(None) { |x, y| x + y }     # => None()
-None().and(Some(10)) { |x, y| x + y }  # => None()
-
-Some(5).and(Some(10)) # => Some([5, 10])
-Some(5).and(None())   # => None()
-```
-
-### `flatten`
-
-To remove one level of nesting:
-
-```ruby
-extend Dry::Monads[:maybe]
-
-Some(Some(10)).flatten # => Some(10)
-Some(None()).flatten   # => None()
-None().flatten         # => None()
-```
-
-### `to_result`
-
-Maybe values can be converted to Result objects:
-
-```ruby
-extend Dry::Monads[:maybe, :result]
-
-Some(10).to_result # => Success(10)
-None().to_result # => Failure()
-None().to_result(:error) # => Failure(:error)
-None().to_result { :block_value } # => Failure(:block_value)
-```

data/docsite/source/pattern-matching.html.md

@@ -1,68 +0,0 @@
----
-title: Pattern matching
-layout: gem-single
-name: dry-monads
----
-
-Ruby 2.7 introduces pattern matchings, it is nicely supported by dry-monads 1.3+.
-
-### Matching Result values
-
-```ruby
-# presumably you do it in a class with `include Dry::Monads[:result]`
-
-case value
-in Success(Integer => x)
-  # x is bound to an integer
-in Success[:created, user] # alternatively: Success([:created, user])
-  # user is bound to the second member
-in Success(Date | Time)
-  # date or time object
-in Success([1, *])
-  # any array starting with 1
-in Success(String => s) if s.size < 100
-  # only if `s` is short enough
-in Success({ counter: Integer })
-  # matches Success(counter: 50)
-  # doesn't match Success(counter: 50, extra: 50)
-in Success({ user: User, account: Account => user_account, ** })
-  # matches Success(user: User.new(...), account: Account.new(...), else: ...)
-  # user_account is bound to the value of the `:account` key
-in Success()
-  # corresponds to Success(Unit)
-in Success(_)
-  # general success
-in Failure[:user_not_found]
-  # Failure([:user_not_found])
-in Failure[error_code, *payload]
-  # ...
-end
-```
-
-In the sippet above, the patterns will be tried sequentially. If `value` doesn't match any pattern, an error will be thrown.
-
-### Matching Maybe
-
-```ruby
-case value
-in Some(Integer => x)
-  # x is an integer
-in Some(Float | String)
-  # ...
-in None
-  # ...
-end
-```
-
-### Matching List
-
-```ruby
-case value
-in List[Integer]
-  # any list of size 1 with an integer
-in List[1, 2, 3, *]
-  # list with size >= 3 starting with 1, 2, 3
-in List[]
-  # empty list
-end
-```

data/docsite/source/result.html.md

@@ -1,190 +0,0 @@
----
-title: Result
-layout: gem-single
-name: dry-monads
----
-
-The `Result` monad is useful to express a series of computations that might
-return an error object with additional information.
-
-The `Result` mixin has two type constructors: `Success` and `Failure`. The `Success`
-can be thought of as "everything went success" and the `Failure` is used when
-"something has gone wrong".
-
-### `bind`
-
-Use `bind` for composing several possibly-failing operations:
-
-```ruby
-require 'dry/monads'
-
-class AssociateUser
-  include Dry::Monads[:result]
-
-  def call(user_id:, address_id:)
-    find_user(user_id).bind do |user|
-      find_address(address_id).fmap do |address|
-        user.update(address_id: address.id)
-      end
-    end
-  end
-
-  private
-
-  def find_user(id)
-    user = User.find_by(id: id)
-
-    if user
-      Success(user)
-    else
-      Failure(:user_not_found)
-    end
-  end
-
-  def find_address(id)
-    address = Address.find_by(id: id)
-
-    if address
-      Success(address)
-    else
-      Failure(:address_not_found)
-    end
-  end
-end
-
-AssociateUser.new.(user_id: 1, address_id: 2)
-```
-
-### `fmap`
-
-An example of using `fmap` with `Success` and `Failure`.
-
-```ruby
-extend Dry::Monads[:result]
-
-result = if foo > bar
-  Success(10)
-else
-  Failure("wrong")
-end.fmap { |x| x * 2 }
-
-# If everything went success
-result # => Success(20)
-# If it did not
-result # => Failure("wrong")
-
-# #fmap accepts a proc, just like #bind
-
-upcase = :upcase.to_proc
-
-Success('hello').fmap(upcase) # => Success("HELLO")
-```
-
-### `value_or`
-
-`value_or` is a safe and recommended way of extracting values.
-
-```ruby
-extend Dry::Monads[:result]
-
-Success(10).value_or(0) # => 10
-Failure('Error').value_or(0) # => 0
-```
-
-### `value!`
-
-If you're 100% sure you're dealing with a `Success` case you might use `value!` for extracting the value without providing a default. Beware, this will raise an exception if you call it on `Failure`.
-
-```ruby
-extend Dry::Monads[:result]
-
-Success(10).value! # => 10
-Failure('Error').value!
-# => Dry::Monads::UnwrapError: value! was called on Failure
-```
-
-### `or`
-
-An example of using `or` with `Success` and `Failure`.
-
-```ruby
-extend Dry::Monads[:result]
-
-Success(10).or(Success(99)) # => Success(10)
-Failure("error").or(Failure("new error")) # => Failure("new error")
-Failure("error").or { |err| Failure("new #{err}") } # => Failure("new error")
-```
-
-### `failure`
-
-Use `failure` for unwrapping the value from a `Failure` instance.
-
-```ruby
-extend Dry::Monads[:result]
-
-Failure('Error').failure # => "Error"
-```
-
-### `to_maybe`
-
-Sometimes it's useful to turn a `Result` into a `Maybe`.
-
-```ruby
-extend Dry::Monads[:result, :maybe]
-
-result = if foo > bar
-  Success(10)
-else
-  Failure("wrong")
-end.to_maybe
-
-# If everything went success
-result # => Some(10)
-# If it did not
-result # => None()
-```
-
-### `failure?` and `success?`
-
-You can explicitly check the type by calling `failure?` or `success?` on a monadic value.
-
-### `either`
-
-`either` maps a `Result` to some type by taking two callables, for `Success` and `Failure` cases respectively:
-
-```ruby
-Success(1).either(-> x { x + 1 }, -> x { x + 2 }) # => 2
-Failure(1).either(-> x { x + 1 }, -> x { x + 2 }) # => 3
-```
-
-
-### Adding constraints to `Failure` values.
-You can add type constraints to values passed to `Failure`. This will raise an exception if value doesn't meet the constraints:
-
-```ruby
-require 'dry-types'
-
-module Types
-  include Dry.Types()
-end
-
-class Operation
-  Error = Types.Instance(RangeError)
-  include Dry::Monads::Result(Error)
-
-  def call(value)
-    case value
-    when 0..1
-      Success(:success)
-    when -Float::INFINITY..0, 1..Float::INFINITY
-      Failure(RangeError.new('Error'))
-    else
-      Failure(TypeError.new('Type error'))
-    end
-  end
-end
-
-Operation.new.call(0.5) # => Success(:success)
-Operation.new.call(5) # => Failure(#<RangeError: Error>)
-Operation.new.call("5") # => Dry::Monads::InvalidFailureTypeError: Cannot create Failure from #<TypeError: Type error>, it doesn't meet the constraints
-```