fear 1.0.0 → 2.0.0

data/README.md

@@ -1,6 +1,8 @@
 # Fear
-[![Build Status](https://travis-ci.org/bolshakov/fear.svg?branch=master)](https://travis-ci.org/bolshakov/fear)
 [![Gem Version](https://badge.fury.io/rb/fear.svg)](https://badge.fury.io/rb/fear)
+![Specs](https://github.com/bolshakov/fear/workflows/Spec/badge.svg)
+[![Maintainability](https://api.codeclimate.com/v1/badges/01030620c59e9f40961b/maintainability)](https://codeclimate.com/github/bolshakov/fear/maintainability)
+[![Coverage Status](https://coveralls.io/repos/github/bolshakov/fear/badge.svg?branch=master)](https://coveralls.io/github/bolshakov/fear?branch=master)
 
 This gem provides `Option`, `Either`, and `Try` monads implemented an idiomatic way. 
  It is highly inspired by scala's implementation. 
@@ -23,11 +25,11 @@ Or install it yourself as:
 
 ## Usage
 
-* [Option](#option-documentation) 
-* [Try](#try-documentation)
-* [Either](#either-documentation)
-* [Future](#future-documentation)
-* [For composition](#for-composition)
+* [Option](#option-api-documentation) 
+* [Try](#try-api-documentation)
+* [Either](#either-api-documentation)
+* [Future](#future-api-documentation)
+* [For composition](#for-composition-api-documentation)
 * [Pattern Matching](#pattern-matching-api-documentation)
 
 ### Option ([API Documentation](https://www.rubydoc.info/github/bolshakov/fear/master/Fear/Option))
@@ -38,7 +40,7 @@ Represents optional (nullable) values. Instances of `Option` are either an insta
 The most idiomatic way to use an `Option` instance is to treat it as a collection
 
 ```ruby
-name = Fear.option(params[:name])
+name = Fear.option(params[:name]) 
 upper = name.map(&:strip).select { |n| n.length != 0 }.map(&:upcase)
 puts upper.get_or_else('')
 ```
@@ -49,9 +51,11 @@ having to check for the existence of a value.
 A less-idiomatic way to use `Option` values is via pattern matching
 
 ```ruby
-Fear.option(params[:name]).match do |m|
-  m.some { |name| name.strip.upcase }
-  m.none { 'No name value' }
+case Fear.option(params[:name])
+in Fear::Some(name) 
+  name.strip.upcase
+in Fear::None
+  'No name value'
 end
 ```
 
@@ -66,17 +70,15 @@ else
 end
 ```
 
-Alternatively, include `Fear::Option::Mixin` to use `Option()`, `Some()` and `None()` methods:
+Alternatively, you can use camel-case factory methods `Fear::Option()`, `Fear::Some()` and `Fear::None` methods:
 
 ```ruby
-include Fear::Option::Mixin 
-
-Option(42) #=> #<Fear::Some get=42>
-Option(nil) #=> #<Fear::None>
+Fear::Option(42) #=> #<Fear::Some get=42>
+Fear::Option(nil) #=> #<Fear::None>
 
-Some(42) #=> #<Fear::Some get=42>
-Some(nil) #=> #<Fear::Some get=nil>
-None() #=> #<Fear::None>
+Fear::Some(42) #=> #<Fear::Some get=42>
+Fear::Some(nil) #=> #<Fear::Some get=nil>
+Fear::None #=> #<Fear::None>
 ``` 
 
 #### Option#get_or_else
@@ -101,7 +103,7 @@ Fear.none.or_else { Fear.some(21) }   #=> Fear.some(21)
 Fear.none.or_else { None }     #=> None
 ```
 
-#### Option#inlude?
+#### Option#include?
 
 Checks if `Option` has an element that is equal (as determined by `==`) to given values.
 
@@ -143,9 +145,9 @@ Fear.none.flat_map { |v| Fear.some(v/2) }     #=> None
 Returns `false` if `None` or returns the result of the application of the given predicate to the `Some` value.
 
 ```ruby 
-Fear.some(12).any?( |v| v > 10)  #=> true
-Fear.some(7).any?( |v| v > 10)   #=> false
-Fear.none.any?( |v| v > 10)    #=> false
+Fear.some(12).any? { |v| v > 10 }  #=> true
+Fear.some(7).any? { |v| v > 10 }   #=> false
+Fear.none.any? { |v| v > 10 }    #=> false
 ```
 
 #### Option#select
@@ -153,12 +155,24 @@ Fear.none.any?( |v| v > 10)    #=> false
 Returns self if it is nonempty and applying the predicate to this `Option`'s value returns `true`. Otherwise, 
 return `None`.
 
-```ruby 
-Fear.some(42).select { |v| v > 40 } #=> Fear.success(21)
+```ruby
+Fear.some(42).select { |v| v > 40 } #=> Fear.some(42)
 Fear.some(42).select { |v| v < 40 } #=> None
 Fear.none.select { |v| v < 40 }   #=> None
 ```
 
+#### Option#filter_map
+
+Returns a new `Some` of truthy results (everything except `false` or `nil`) of
+running the block or `None` otherwise.
+
+```ruby
+Fear.some(42).filter_map { |v| v/2 if v.even? } #=> Fear.some(21)
+Fear.some(42).filter_map { |v| v/2 if v.odd? } #=> Fear.none
+Fear.some(42).filter_map { |v| false } #=> Fear.none
+Fear.none.filter_map { |v| v/2 }   #=> Fear.none
+```
+
 #### Option#reject
 
 Returns `Some` if applying the predicate to this `Option`'s value returns `false`. Otherwise, return `None`.
@@ -182,6 +196,37 @@ Fear.some(42).empty? #=> false
 Fear.none.empty?   #=> true
 ```
 
+#### Option#blank?
+
+Returns `true` if the `Option` is `None`, `false` otherwise.
+
+```ruby
+Fear.some(42).blank? #=> false
+Fear.none.blank?   #=> true
+```
+
+#### Option#present?
+
+Returns `false` if the `Option` is `None`, `true` otherwise.
+
+```ruby
+Fear.some(42).present? #=> true
+Fear.none.present?   #=> false
+```
+
+#### Option#zip
+
+Returns a `Fear::Some` formed from this Option and another Option by combining the corresponding elements in a pair. 
+If either of the two options is empty, `Fear::None` is returned.
+
+```ruby
+Fear.some("foo").zip(Fear.some("bar")) #=> Fear.some(["foo", "bar"])
+Fear.some("foo").zip(Fear.some("bar")) { |x, y| x + y } #=> Fear.some("foobar")
+Fear.some("foo").zip(Fear.none) #=> Fear.none
+Fear.none.zip(Fear.some("bar")) #=> Fear.none
+
+```
+
 @see https://github.com/scala/scala/blob/2.11.x/src/library/scala/Option.scala
  
 
@@ -201,19 +246,14 @@ dividend = Fear.try { Integer(params[:dividend]) }
 divisor = Fear.try { Integer(params[:divisor]) }
 problem = dividend.flat_map { |x| divisor.map { |y| x / y } }
 
-problem.match |m|
-  m.success do |result|
-    puts "Result of #{dividend.get} / #{divisor.get} is: #{result}"
-  end
-
-  m.failure(ZeroDivisionError) do
-    puts "Division by zero is not allowed"
-  end
-
-  m.failure do |exception|
-    puts "You entered something wrong. Try again"
-    puts "Info from the exception: #{exception.message}"
-  end
+case problem
+in Fear::Success(result)
+  puts "Result of #{dividend.get} / #{divisor.get} is: #{result}"
+in Fear::Failure(ZeroDivisionError)
+  puts "Division by zero is not allowed"
+in Fear::Failure(exception)
+  puts "You entered something wrong. Try again"
+  puts "Info from the exception: #{exception.message}"
 end
 ```
 
@@ -230,13 +270,11 @@ type of default behavior in the case of failure.
 *NOTE*: Only non-fatal exceptions are caught by the combinators on `Try`.
 Serious system errors, on the other hand, will be thrown.
 
-Alternatively, include `Fear::Try::Mixin` to use `Try()` method:
+Alternatively, include you can use camel-case factory method `Fear::Try()`:
 
 ```ruby
-include Fear::Try::Mixin 
-
-Try { 4/0 }  #=> #<Fear::Failure exception=...>
-Try { 4/2 }  #=> #<Fear::Success value=2>
+Fear::Try { 4/0 }  #=> #<Fear::Failure exception=...>
+Fear::Try { 4/2 }  #=> #<Fear::Success value=2>
 ```
 
 #### Try#get_or_else
@@ -291,7 +329,7 @@ Fear.failure(ArgumentError.new).flat_map { |v| Fear.success(v/2) } #=> Fear.fail
 Returns an `Some` containing the `Success` value or a `None` if this is a `Failure`.
 
 ```ruby
-Fear.success(42).to_option                 #=> Fear.some(21)
+Fear.success(42).to_option                 #=> Fear.some(42)
 Fear.failure(ArgumentError.new).to_option  #=> None
 ```
 
@@ -300,9 +338,9 @@ Fear.failure(ArgumentError.new).to_option  #=> None
 Returns `false` if `Failure` or returns the result of the application of the given predicate to the `Success` value.
 
 ```ruby
-Fear.success(12).any?( |v| v > 10)                #=> true
-Fear.success(7).any?( |v| v > 10)                 #=> false
-Fear.failure(ArgumentError.new).any?( |v| v > 10) #=> false
+Fear.success(12).any? { |v| v > 10 }                #=> true
+Fear.success(7).any? { |v| v > 10 }                 #=> false
+Fear.failure(ArgumentError.new).any? { |v| v > 10 } #=> false
 ```
 
 #### Try#success? and Try#failure?
@@ -352,7 +390,7 @@ Converts this to a `Failure` if the predicate is not satisfied.
 
 ```ruby
 Fear.success(42).select { |v| v > 40 }
-  #=> Fear.success(21)
+  #=> Fear.success(42)
 Fear.success(42).select { |v| v < 40 }
   #=> Fear.failure(Fear::NoSuchElementError.new("Predicate does not hold for 42"))
 Fear.failure(ArgumentError.new).select { |v| v < 40 }
@@ -414,7 +452,7 @@ Fear.success(42).to_either                #=> Fear.right(42)
 Fear.failure(ArgumentError.new).to_either #=> Fear.left(ArgumentError.new)
 ```
 
-### Either ([API Documentation](https://www.rubydoc.info/github/bolshakov/fear/master/Fear/Option))
+### Either ([API Documentation](https://www.rubydoc.info/github/bolshakov/fear/master/Fear/Either))
   
 Represents a value of one of two possible types (a disjoint union.)
 An instance of `Either` is either an instance of `Left` or `Right`.
@@ -436,14 +474,11 @@ rescue ArgumentError
   Fear.left(in)
 end
 
-result.match do |m|
-  m.right do |x|
-    "You passed me the Int: #{x}, which I will increment. #{x} + 1 = #{x+1}"
-  end
-
-  m.left do |x|
-    "You passed me the String: #{x}"
-  end
+case result
+in Fear::Right(x)
+  "You passed me the Int: #{x}, which I will increment. #{x} + 1 = #{x+1}"
+in Fear::Left(x)
+  "You passed me the String: #{x}"
 end
 ```
 
@@ -451,13 +486,11 @@ Either is right-biased, which means that `Right` is assumed to be the default ca
 operate on. If it is `Left`, operations like `#map`, `#flat_map`, ... return the `Left` value
 unchanged.
 
-Alternatively, include `Fear::Either::Mixin` to use `Left()`, and `Right()` methods:
+Alternatively, you can use camel-case factory methods `Fear::Left()`, and `Fear::Right()`:
 
 ```ruby
-include Fear::Either::Mixin 
-
-Left(42)  #=> #<Fear::Left value=42>
-Right(42)  #=> #<Fear::Right value=42>
+Fear::Left(42)  #=> #<Fear::Left value=42>
+Fear::Right(42)  #=> #<Fear::Right value=42>
 ```
 
 #### Either#get_or_else
@@ -524,7 +557,7 @@ Fear.left('undefined').flat_map { |v| Fear.right(v/2) } #=> Fear.left('undefined
 Returns an `Some` containing the `Right` value or a `None` if this is a `Left`.
 
 ```ruby
-Fear.right(42).to_option          #=> Fear.some(21)
+Fear.right(42).to_option          #=> Fear.some(42)
 Fear.left('undefined').to_option  #=> Fear::None
 ```
 
@@ -533,9 +566,9 @@ Fear.left('undefined').to_option  #=> Fear::None
 Returns `false` if `Left` or returns the result of the application of the given predicate to the `Right` value.
 
 ```ruby
-Fear.right(12).any?( |v| v > 10)         #=> true
-Fear.right(7).any?( |v| v > 10)          #=> false
-Fear.left('undefined').any?( |v| v > 10) #=> false
+Fear.right(12).any? { |v| v > 10 }         #=> true
+Fear.right(7).any? { |v| v > 10 }          #=> false
+Fear.left('undefined').any? { |v| v > 10 } #=> false
 ```
 
 #### Either#right?, Either#success?
@@ -625,7 +658,7 @@ Fear.left("flower").join_right        #=> Fear.left("flower")
 Fear.left(Fear.right("flower")).join_right #=> Fear.left(Fear.right("flower"))
 ```
 
-#### Either#join_right
+#### Either#join_left
 
 Joins an `Either` through `Left`. This method requires that the left side of this `Either` is itself an
 `Either` type. This method, and `join_right`, are analogous to `Option#flatten`
@@ -764,7 +797,7 @@ end #=> returns new future of Fear.success(0)
 
 If the future resolved to success or recovery matcher did not matched, it returns the future `Fear::Failure`.
 
-The second option is `Future#fallbock_to` method. It allows to fallback to result of another future in case of failure
+The second option is `Future#fallback_to` method. It allows to fallback to result of another future in case of failure
 
 ```ruby
 future = Fear.future { fail 'error' }
@@ -784,6 +817,20 @@ end.and_then do |m|
 end
 ```
 
+#### Testing future values
+
+Sometimes it may be helpful to await for future completion. You can await either future,
+or result. Don't forget to pass timeout in seconds:
+
+
+```ruby 
+future = Fear.future { 42 }
+
+Fear::Await.result(future, 3) #=> 42
+
+Fear::Await.ready(future, 3) #=> Fear::Future.successful(42)
+```
+
 ### For composition ([API Documentation](http://www.rubydoc.info/github/bolshakov/fear/master/Fear/ForApi))
 
 Provides syntactic sugar for composition of multiple monadic operations. 
@@ -922,144 +969,6 @@ matcher.(42) #=> "42 is a number"
 matcher.(10..20) #=> "10..20 is a Range"
 ``` 
 
-#### Pattern extraction 
-
-It's possible to use special syntax to match against an object and extract a variable form this object.
-To perform such extraction, `#xcase` method should be used. The following example should give you a sense 
-how extraction works.
-
-```ruby
-matcher = Fear.matcher do |m|
-  m.xcase('[1, *tail]') { |tail:| tail }
-end
-```
-
-It matches only on an array starting from `1` integer, and captures its tail:
-
-```ruby
-matcher.([1,2,3]) #=> [2,3]
-matcher.([2,3]) #=> raises MatchError
-``` 
-
-If you want to match against any value, use `_` 
-
-```ruby 
-matcher = Fear.matcher do |m|
-  m.xcase('[1, _, 3]') { .. }
-end
-```
-
-It matches against `[1, 2, 3]`, `[1, 'foo', 3]`, but not `[1, 2]`. It's also possible to capture several variables
-at the same time. Tho following example describes an array starting from `1`, and captures second and third elements.
-
-
-```ruby 
-matcher = Fear.matcher do |m|
-  m.xcase('[1, second, third]') { |second:, third: |.. }
-end
-``` 
-
-Matching on deeper structures is possible as well:
-
-```ruby 
-matcher = Fear.matcher do |m|
-  m.xcase('[["status", first_status], 4, *tail]') { |first_status:, tail: |.. }
-end
-``` 
-
-If you want to capture variable of specific type, there is a type matcher for that case:
-
-```ruby 
-matcher = Fear.matcher do |m|
-  m.xcase('[head : String, 2, *]') { |head: | head }
-end
-matcher.(['foo', 2]) #=> 'foo'
-matcher.(['foo', 3]) #=> MatchError
-matcher.([1, 2]) #=> MatchError
-``` 
-
-You can extract variables from more complex objects. Fear packed with extractors for monads and `Date` object:
-
-```ruby
-Fear.matcher do |m|
-  m.xcase('Date(year, 2, 29)', ->(year:) { year < 2000 }) do |year:|
-    "#{year} is a leap year before Millennium"
-  end
-  
-  m.xcase('Date(year, 2, 29)') do |year:|
-    "#{year} is a leap year after Millennium"
-  end
-  
-  m.case(Date) do |date|
-    "#{date.year} is not a leap year"
-  end
-end
-``` 
-
-This matcher extracts values from date object and match against them at the same time
-
-```ruby 
-matcher.(Date.new(1996,02,29)) #=> "1996 is a leap year before Millennium"
-matcher.(Date.new(2004,02,29)) #=> "1996 is a leap year after Millennium"
-matcher.(Date.new(2003,01,24)) #=> "2003 is not a leap year"
-```
-
-Nothing tricky here. The extractor object takes an object and tries to give back the arguments. It's like 
-constructor, but instead of construction an object, it deconstructs it. 
-
-An argument of an extractor may be also a pattern or even  introduce a new variable. 
-
-```ruby 
-matcher = Fear.matcher do |m|
-  m.xcase('Some([status : Integer, body : String])') do |status:, body:|
-    "#{body.bytesize} bytes received with code #{status}"
-  end 
-end
-
-matcher.(Fear.some([200, 'hello'])) #=> "5 bytes received with code 200"
-matcher.(Fear.some(['hello', 200])) #=> MatchError 
-```
-
-You can provide extractors for you own classes
-
-```ruby 
-Fear.register_extractor(User, Fear.case(User) { |user| [user.id, user.email] }.lift)
-# is the same as
-Fear.register_extractor(User, proc do |user|
-  if user.is_a?(User)
-    Fear.some([user.id, user.email])
-  else
-    Fear.none
-  end
-end)
-```
-
-Now extracting user's id and email is possible:
-
-
-```ruby 
-Fear.match(user) do |m|
-  m.xcase('User(id, email)') { |id:, email:| }
-end
-```
-
-Note, registered extractor should return either array of arguments, or boolean.
-
-#### Extracting struct
-
-There is predefined `Struct` extractor:
-
-```ruby
-Envelope = Struct.new(:id, :receiver, :sender, :message)
-
-Fear.matcher do |m|
-  m.xcase('envelope @ Envelope(id, _, sender, _)') do |id:, sender:, envelope:|
-    acknowledge(id, sender)
-    process(acknowledge)
-  end
-end
-```
-
 #### How to debug pattern extractors?
 
 You can build pattern manually and ask for failure reason:
@@ -1095,13 +1004,13 @@ factorial.(10) #=> 3628800
 Fibonacci number
 
 ```ruby
-fibonnaci = Fear.matcher do |m|
+fibonacci = Fear.matcher do |m|
   m.case(0) { 0 }
   m.case(1) { 1 }
-  m.case(->(n) { n > 1}) { |n| fibonnaci.(n - 1) + fibonnaci.(n - 2) }
+  m.case(->(n) { n > 1}) { |n| fibonacci.(n - 1) + fibonacci.(n - 2) }
 end
 
-fibonnaci.(10) #=> 55
+fibonacci.(10) #=> 55
 ```
 
 Binary tree set implemented using pattern matching https://gist.github.com/bolshakov/3c51bbf7be95066d55d6d1ac8c605a1d
@@ -1157,7 +1066,7 @@ matcher.(Fear.some(40)) #=> 'Nope'
 #### Under the hood 
 
 Pattern matcher is a combination of partial functions wrapped into nice DSL. Every partial function 
-defined on domain described with guard.
+defined on domain described with a guard.
 
 ```ruby
 pf = Fear.case(Integer) { |x| x / 2 }
@@ -1219,6 +1128,128 @@ handle.(12) #=> 'bigger than ten'
 handle.('one') #=> 1
 ```
 
+### Native pattern-matching 
+
+Starting from ruby 2.7 you can use native pattern matching capabilities:
+
+```ruby 
+case Fear.some(42)
+in Fear::Some(x)
+  x * 2
+in Fear::None 
+  'none'
+end #=> 84
+
+case Fear.some(41)
+in Fear::Some(x) if x.even?
+  x / 2
+in Fear::Some(x) if x.odd? && x > 0
+  x * 2
+in Fear::None
+  'none'
+end #=> 82
+
+case Fear.some(42)
+in Fear::Some(x) if x.odd?
+  x * 2 
+else 
+  'nothing'
+end #=> nothing
+```
+
+It's possible to pattern match against Fear::Either and Fear::Try as well:
+
+```ruby 
+case either 
+in Fear::Right(Integer | String => x)
+  "integer or string: #{x}"
+in Fear::Left(String => error_code) if error_code = :not_found 
+  'not found'
+end  
+```
+
+```ruby 
+case Fear.try { 10 / x } 
+in Fear::Failure(ZeroDivisionError)
+  # ..
+in Fear::Success(x) 
+  # ..
+end  
+```
+
+### Dry-Types integration
+
+#### Option
+
+    NOTE: Requires the dry-tyes gem to be loaded.
+
+Load the `:fear_option` extension in your application.
+
+```ruby
+require 'dry-types'
+require 'dry/types/fear'
+
+Dry::Types.load_extensions(:fear_option)
+
+module Types
+  include Dry.Types()
+end
+```
+
+Append .option to a Type to return a `Fear::Option` object:
+
+```ruby
+Types::Option::Strict::Integer[nil] 
+#=> Fear.none
+Types::Option::Coercible::String[nil] 
+#=> Fear.none
+Types::Option::Strict::Integer[123] 
+#=> Fear.some(123)
+Types::Option::Strict::String[123]
+#=> Fear.some(123)
+Types::Option::Coercible::Float['12.3'] 
+#=> Fear.some(12.3)
+```
+
+'Option' types can also accessed by calling '.option' on a regular type:
+
+```ruby
+Types::Strict::Integer.option # equivalent to Types::Option::Strict::Integer
+```
+
+
+You can define your own optional types:
+
+```ruby
+option_string = Types::Strict::String.option
+option_string[nil]
+# => Fear.none
+option_string[nil].map(&:upcase)
+# => Fear.none
+option_string['something']
+# => Fear.some('something')
+option_string['something'].map(&:upcase)
+# => Fear.some('SOMETHING')
+option_string['something'].map(&:upcase).get_or_else { 'NOTHING' }
+# => "SOMETHING"
+```
+
+You can use it with dry-struct as well:
+
+```ruby
+class User < Dry::Struct
+  attribute :name, Types::Coercible::String
+  attribute :age,  Types::Coercible::Integer.option
+end
+
+user = User.new(name: 'Bob', age: nil)
+user.name #=> "Bob"
+user.age #=> Fear.none 
+
+user = User.new(name: 'Bob', age: 42)
+user.age #=> Fear.some(42) 
+```
+
 ## Testing
 
 To simplify testing, you may use [fear-rspec](https://github.com/bolshakov/fear-rspec) gem. It