fear 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9f6f57b15284f2ed3034bc697608d9c44e7401b1
-  data.tar.gz: 439fb988ae4fab755815100e092a65db332e960e
+  metadata.gz: f2a2b3d7163ba41625120e4681b75a845e5d9da9
+  data.tar.gz: 5d85fb64e778587e9f8f85695acb4f19602ae47e
 SHA512:
-  metadata.gz: 8409d00dd720c5dfbd623e73d72abd86ae5c90235e08dd646ad2e9c19b17c502d1a3d0f9a372ae23bb1af1e6cd9571cd425a6c7305e95256746031a6a634c71b
-  data.tar.gz: 051a50aa71c6fad65b52798ee303f59037c988365a449afa4653afab5f62d53443c31d0d731d07f09a39c564d330cd927243b701e7925aefa913f78ba7fd52fb
+  metadata.gz: 99ff3b3886920d253e835b6d1346ff7680f26650a01087cbd83629ec3ba3e7a152ef7714937c653639eef1689dcbac242c7a18cfd26db8d41155f5f4cc9bd80b
+  data.tar.gz: 7fcabd7b3cada123a3d2988c4cc4c19bf2af8195e10ff151a886f9a24e1b12dfa73061ca9bc323c056aee9f0be985886b74a02b23a2eeacc10d39e8da2735fb5

data/.rubocop.yml

@@ -1,11 +1,11 @@
-inherit_gem:
-  spbtv_code_style: .strict_rubocop.yml
-
 AllCops:
   Exclude:
   - 'gemfiles/**/*'
 
-Style/MethodName:
+Naming/MethodName:
+  Enabled: false
+
+Naming/UncommunicativeMethodParamName:
   Enabled: false
 
 Style/Documentation:
@@ -14,6 +14,32 @@ Style/Documentation:
 Style/CaseEquality:
   Enabled: false
 
+Style/AccessModifierDeclarations:
+  EnforcedStyle: inline
+
+Style/GuardClause:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+
+Style/NumericPredicate:
+  Enabled: false
+
 Metrics/BlockLength:
   Exclude:
     - spec/**/*
+    - Rakefile
+    - fear.gemspec
+
+Metrics/LineLength:
+  Max: 120

data/.travis.yml

@@ -1,4 +1,6 @@
 ---
+cache:
+  bundler: true
 language: ruby
 rvm:
 - 2.4.5
@@ -12,6 +14,3 @@ script:
 gemfile:
 - gemfiles/dry_equalizer_0.2.1.gemfile
 - gemfiles/dry_equalizer_0.1.0.gemfile
-addons:
-  code_climate:
-    repo_token: c326cca5984d0e32d2c6b5d9b985756ee9312f63fc6a9480fc9cfa55c454d68a

data/Appraisals

@@ -1,7 +1,7 @@
 require 'yaml'
 
-ruby_versions = %w(2.4.5 2.5.3 2.6.1)
-dry_equalizer_versions = %w(0.1.0 0.2.1)
+ruby_versions = %w[2.4.5 2.5.3 2.6.1]
+dry_equalizer_versions = %w[0.1.0 0.2.1]
 
 dry_equalizer_versions.each do |version|
   appraise "dry-equalizer-#{version}" do
@@ -11,6 +11,9 @@ end
 
 Dir.glob('gemfiles/*.gemfile').tap do |gemfiles|
   travis = ::YAML.dump(
+    'cache' => {
+      'bundler' => true,
+    },
     'language' => 'ruby',
     'rvm' => ruby_versions,
     'before_script' => [
@@ -21,13 +24,6 @@ Dir.glob('gemfiles/*.gemfile').tap do |gemfiles|
       'bundle exec rubocop --fail-level C',
     ],
     'gemfile' => gemfiles,
-    'addons' => {
-      'code_climate' => {
-        'repo_token' => 'c326cca5984d0e32d2c6b5d9b985756ee9312f63fc6a9480fc9cfa55c454d68a'
-      }
-    }
-
-
   )
 
   ::File.open('.travis.yml', 'w+') do |file|

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.11.0
+
+* Implement pattern matching and partial functions. See [README](https://github.com/bolshakov/fear#pattern-matching-api-documentation) (([@bolshakov][]))
+* `#to_a` method removed ([@bolshakov][])
+* `For` syntax changed. See [diff](https://github.com/bolshakov/fear/pull/22/files#diff-04c6e90faac2675aa89e2176d2eec7d8) ([@bolshakov][])
+* `Fear::None` is singleton object now and could not be instantiated ([@bolshakov][])
+
+  You have to change all `Fear::None.new` invocations to `Fear::None`.
+
 ## 0.10.0
 
 * Test against last supported ruby versions: 2.4.5, 2.5.3, 2.6.1 ([@bolshakov][])

data/Gemfile

@@ -4,3 +4,5 @@ source 'https://rubygems.org'
 gemspec
 
 # gem 'codeclimate-test-reporter', group: :test, require: nil
+
+gem 'qo', github: 'baweaver/qo'

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2015-2017 Tema Bolshakov
+Copyright (c) 2015-2019 Tema Bolshakov
 
 MIT License
 

data/README.md

@@ -1,7 +1,5 @@
 # Fear
 [![Build Status](https://travis-ci.org/bolshakov/fear.svg?branch=master)](https://travis-ci.org/bolshakov/fear)
-[![Maintainability](https://api.codeclimate.com/v1/badges/dbdcfb770918c425e5e4/maintainability)](https://codeclimate.com/github/bolshakov/functional/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/dbdcfb770918c425e5e4/test_coverage)](https://codeclimate.com/github/bolshakov/functional/test_coverage)
 [![Gem Version](https://badge.fury.io/rb/fear.svg)](https://badge.fury.io/rb/fear)
 
 This gem provides `Option`, `Either`, and `Try` monads implemented an idiomatic way. 
@@ -29,7 +27,7 @@ Or install it yourself as:
 * [Try](#try-documentation)
 * [Either](#either-documentation)
 * [For composition](#for-composition)
-* [Pattern Matching](#pattern-matching)
+* [Pattern Matching](#pattern-matching-api-documentation)
 
 ### Option ([Documentation](http://www.rubydoc.info/github/bolshakov/fear/master/Fear/Option))
 
@@ -50,12 +48,9 @@ having to check for the existence of a value.
 A less-idiomatic way to use `Option` values is via pattern matching
 
 ```ruby
-name = Option(params[:name])
-case name
-when Some
- puts name.strip.upcase
-when None
- puts 'No name value'
+Option(params[:name]).match do |m|
+  m.some { |name| name.strip.upcase }
+  m.none { 'No name value' }
 end
 ```
 
@@ -76,10 +71,10 @@ Returns the value from this `Some` or evaluates the given default argument if th
 
 ```ruby
 Some(42).get_or_else { 24/2 } #=> 42
-None().get_or_else { 24/2 }   #=> 12
+None.get_or_else { 24/2 }   #=> 12
 
 Some(42).get_or_else(12)  #=> 42
-None().get_or_else(12)    #=> 12
+None.get_or_else(12)    #=> 12
 ```
 
 #### Option#or_else
@@ -88,8 +83,8 @@ returns self `Some` or the given alternative if this is a `None`.
 
 ```ruby
 Some(42).or_else { Some(21) } #=> Some(42)
-None().or_else { Some(21) }   #=> Some(21)
-None().or_else { None() }     #=> None()
+None.or_else { Some(21) }   #=> Some(21)
+None.or_else { None }     #=> None
 ```
 
 #### Option#inlude?
@@ -99,7 +94,7 @@ Checks if `Option` has an element that is equal (as determined by `==`) to given
 ```ruby
 Some(17).include?(17) #=> true
 Some(17).include?(7)  #=> false
-None().include?(17)   #=> false
+None.include?(17)   #=> false
 ```
 
 #### Option#each
@@ -108,7 +103,7 @@ Performs the given block if this is a `Some`.
 
 ```ruby
 Some(17).each { |value| puts value } #=> prints 17
-None().each { |value| puts value } #=> does nothing
+None.each { |value| puts value } #=> does nothing
 ```
 
 #### Option#map 
@@ -117,7 +112,7 @@ Maps the given block to the value from this `Some` or returns self if this is a
 
 ```ruby
 Some(42).map { |v| v/2 } #=> Some(21)
-None().map { |v| v/2 }   #=> None()
+None.map { |v| v/2 }   #=> None
 ```
 
 #### Option#flat_map
@@ -126,16 +121,7 @@ Returns the given block applied to the value from this `Some` or returns self if
 
 ```ruby
 Some(42).flat_map { |v| Some(v/2) }   #=> Some(21)
-None().flat_map { |v| Some(v/2) }     #=> None()
-```
-
-#### Option#to_a
-
-Returns an `Array` containing the `Some` value or an empty `Array` if this is a `None`
-
-```ruby
-Some(42).to_a #=> [21]
-None().to_a   #=> []
+None.flat_map { |v| Some(v/2) }     #=> None
 ```
 
 #### Option#any?
@@ -145,7 +131,7 @@ Returns `false` if `None` or returns the result of the application of the given
 ```ruby 
 Some(12).any?( |v| v > 10)  #=> true
 Some(7).any?( |v| v > 10)   #=> false
-None().any?( |v| v > 10)    #=> false
+None.any?( |v| v > 10)    #=> false
 ```
 
 #### Option#select
@@ -155,8 +141,8 @@ return `None`.
 
 ```ruby 
 Some(42).select { |v| v > 40 } #=> Success(21)
-Some(42).select { |v| v < 40 } #=> None()
-None().select { |v| v < 40 }   #=> None()
+Some(42).select { |v| v < 40 } #=> None
+None.select { |v| v < 40 }   #=> None
 ```
 
 #### Option#reject
@@ -166,7 +152,7 @@ Returns `Some` if applying the predicate to this `Option`'s value returns `false
 ```ruby 
 Some(42).reject { |v| v > 40 } #=> None
 Some(42).reject { |v| v < 40 } #=> Some(42)
-None().reject { |v| v < 40 }   #=> None
+None.reject { |v| v < 40 }   #=> None
 ```
 
 #### Option#get
@@ -179,7 +165,7 @@ Returns `true` if the `Option` is `None`, `false` otherwise.
 
 ```ruby
 Some(42).empty? #=> false
-None().empty?   #=> true
+None.empty?   #=> true
 ```
 
 @see https://github.com/scala/scala/blob/2.11.x/src/library/scala/Option.scala
@@ -203,11 +189,19 @@ dividend = Try { Integer(params[:dividend]) }
 divisor = Try { Integer(params[:divisor]) }
 problem = dividend.flat_map { |x| divisor.map { |y| x / y } }
 
-if problem.success?
-  puts "Result of #{dividend.get} / #{divisor.get} is: #{problem.get}"
-else
-  puts "You must've divided by zero or entered something wrong. Try again"
-  puts "Info from the exception: #{problem.exception.message}"
+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
 end
 ```
 
@@ -271,22 +265,13 @@ Success(42).flat_map { |v| Success(v/2) } #=> Success(21)
 Failure(ArgumentError.new).flat_map { |v| Success(v/2) } #=> Failure(ArgumentError.new)
 ```
 
-#### Try#to_a
-
-Returns an `Array` containing the `Success` value or an empty `Array` if this is a `Failure`.
-
-```ruby
-Success(42).to_a                 #=> [21]
-Failure(ArgumentError.new).to_a  #=> []
-```
-
 #### Try#to_option
 
 Returns an `Some` containing the `Success` value or a `None` if this is a `Failure`.
 
 ```ruby
 Success(42).to_option                 #=> Some(21)
-Failure(ArgumentError.new).to_option  #=> None()
+Failure(ArgumentError.new).to_option  #=> None
 ```
 
 #### Try#any?
@@ -362,7 +347,7 @@ Success(42).recover_with { |e| Success(e.massage) }
   #=> Success(42)
 Failure(ArgumentError.new).recover_with { |e| Success(e.massage) }
   #=> Success('ArgumentError')
-Failure(ArgumentError.new).recover_with { |e| fail }
+Failure(ArgumentError.new).recover_with { |e| raise }
   #=> Failure(RuntimeError)
 ```
 
@@ -375,7 +360,7 @@ Success(42).recover { |e| e.massage }
   #=> Success(42)
 Failure(ArgumentError.new).recover { |e| e.massage }
   #=> Success('ArgumentError')
-Failure(ArgumentError.new).recover { |e| fail }
+Failure(ArgumentError.new).recover { |e| raise }
   #=> Failure(RuntimeError)
 ```
 
@@ -410,12 +395,15 @@ rescue ArgumentError
   Left(in)
 end
 
-puts(
-  result.reduce(
-    -> (x) { "You passed me the String: #{x}" },
-    -> (x) { "You passed me the Int: #{x}, which I will increment. #{x} + 1 = #{x+1}" }
-  )
-)
+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
+end
 ```
 
 Either is right-biased, which means that `Right` is assumed to be the default case to
@@ -481,22 +469,13 @@ Right(42).flat_map { |v| Right(v/2) }         #=> Right(21)
 Left('undefined').flat_map { |v| Right(v/2) } #=> Left('undefined')
 ```
 
-#### Either#to_a
-
-Returns an `Array` containing the `Right` value or an empty `Array` if this is a `Left`.
-
-```ruby
-Right(42).to_a          #=> [21]
-Left('undefined').to_a  #=> []
-```
-
 #### Either#to_option
 
 Returns an `Some` containing the `Right` value or a `None` if this is a `Left`.
 
 ```ruby
 Right(42).to_option          #=> Some(21)
-Left('undefined').to_option  #=> None()
+Left('undefined').to_option  #=> None
 ```
 
 #### Either#any?
@@ -615,23 +594,32 @@ It supports two such operations - `flat_map` and `map`. Any class providing them
 is supported by `For`.
 
 ```ruby
-For(a: Some(2), b: Some(3)) { a * b } #=> Some(6)
+For(Some(2), Some(3)) do |a, b|
+  a * b
+end #=> Some(6)
 ```
 
 If one of operands is None, the result is None
 
 ```ruby
-For(a: Some(2), b: None()) { a * b } #=> None()
-For(a: None(), b: Some(2)) { a * b } #=> None()
+For(Some(2), None) do |a, b| 
+  a * b 
+end #=> None
+
+For(None, Some(2)) do |a, b| 
+  a * b 
+end #=> None
 ```
 
 Lets look at first example:
 
 ```ruby
-For(a: Some(2), b: Some(3)) { a * b }
+For(Some(2), None) do |a, b| 
+  a * b 
+end #=> None
 ```
 
-would be translated to:
+it is translated to:
 
 ```ruby
 Some(2).flat_map do |a|
@@ -644,7 +632,7 @@ end
 It works with arrays as well
 
 ```ruby
-For(a: [1, 2], b: [2, 3], c: [3, 4]) { a * b * c }
+For([1, 2], [2, 3], [3, 4]) { |a, b, c| a * b * c }
   #=> [6, 8, 9, 12, 12, 16, 18, 24]
 
 ```
@@ -665,8 +653,9 @@ If you pass lambda as a variable value, it would be evaluated
 only on demand.
 
 ```ruby
-For(a: -> { None() }, b: -> { fail 'kaboom' } ) { a * b }
-  #=> None()
+For(proc { None }, proc { raise 'kaboom' } ) do |a, b|
+  a * b
+end #=> None
 ```
 
 It does not fail since `b` is not evaluated.
@@ -675,28 +664,209 @@ You can refer to previously defined variables from within lambdas.
 ```ruby
 maybe_user = find_user('Paul') #=> <#Option value=<#User ...>>
 
-For(user: maybe_user, birthday: -> { user.birthday }) do
+For(maybe_user, ->(user) { user.birthday }) do |user, birthday|
   "#{user.name} was born on #{birthday}"
 end #=> Some('Paul was born on 1987-06-17')
 ```
 
-### Pattern Matching
+### Pattern Matching (API Documentation)
+
+Pattern matcher is a combination of partial functions wrapped into nice DSL. Every partial function 
+defined on domain described with guard.
+
+```ruby
+pf = Fear.case(Integer) { |x| x / 2 }
+pf.defined_at?(4) #=> true
+pf.defined_at?('Foo') #=> false
+pf.call('Foo') #=> raises Fear::MatchError
+pf.call_or_else('Foo') { 'not a number' } #=> 'not a number'
+pf.call_or_else(4) { 'not a number' } #=> 2
+pf.lift.call('Foo') #=> Fear::None
+pf.lift.call(4) #=> Fear::Some(2)
+```
+
+It uses `#===` method under the hood, so you can pass:
 
-`Option`, `Either`, and `Try` contains enhanced version of `#===` method. It performs matching not 
-only on container itself, but on enclosed value as well. I'm writing all the options in a one 
-case statement in sake of simplicity.
+* Class to check kind of an object.
+* Lambda to evaluate it against an object.
+* Any literal, like `4`, `"Foobar"`, etc.
+* Symbol -- it is converted to lambda using `#to_proc` method.
+* Qo matcher -- `m.case(Qo[name: 'John']) { .... }`
  
+Partial functions may be combined with each other:
+
+```ruby
+is_even = Fear.case(->(arg) { arg % 2 == 0}) { |arg| "#{arg} is even" }
+is_odd = Fear.case(->(arg) { arg % 2 == 1}) { |arg| "#{arg} is odd" }
+
+(10..20).map(&is_even.or_else(is_odd))
+
+to_integer = Fear.case(String, &:to_i)
+integer_two_times = Fear.case(Integer) { |x| x * 2 }
+
+two_times = to_integer.and_then(integer_two_times).or_else(integer_two_times)
+two_times.(4) #=> 8
+two_times.('42') #=> 84
+```
+
+To create custom pattern match use `Fear.match` method and `case` builder to define
+branches. For instance this matcher applies different functions to Integers and Strings
+
+```ruby 
+Fear.match(value) do |m|
+  m.case(Integer) { |n| "#{n} is a number" }
+  m.case(String) { |n| "#{n} is a string" }
+end
+```
+
+if you pass something other than Integer or string, it will raise `Fear::MatchError` error.
+To avoid raising `MatchError`, you can use `else` method. It defines a branch matching
+on any value.
+
+```ruby 
+Fear.match(10..20) do |m|
+  m.case(Integer) { |n| "#{n} is a number" }
+  m.case(String) { |n| "#{n} is a string" }
+  m.else  { |n| "#{n} is a #{n.class}" }
+end #=> "10..20 is a Range"
+```
+
+You can use anything as a guardian if it responds to `#===` method:
+
 ```ruby
-case Some(42)
-when Some(42)                #=> matches
-when Some(41)                #=> does not match
-when Some(Fixnum)            #=> matches
-when Some(String)            #=> does not match
-when Some((40..43))          #=> matches
-when Some(-> (x) { x > 40 }) #=> matches
-end  
+m.case(20..40) { |m| "#{m} is within range" }
+m.case(->(x) { x > 10}) { |m| "#{m} is greater than 10" }
 ```
 
+If you pass a Symbol, it will be converted to proc using `#to_proc` method
+
+```ruby 
+m.case(:even?) { |x| "#{x} is even" }
+m.case(:odd?) { |x| "#{x} is odd" }
+```
+
+It's also possible to pass several guardians. All should match to pass
+
+```ruby 
+m.case(Integer, :even?) { |x| ... }
+m.case(Integer, :odd?) { |x| ... }
+```
+
+It's also possible to create matcher and use it several times:
+
+```ruby
+matcher = Fear.matcher do |m|
+  m.case(Integer) { |n| "#{n} is a number" }
+  m.case(String) { |n| "#{n} is a string" }
+  m.else  { |n| "#{n} is a #{n.class}" }
+end 
+
+matcher.(42) #=> "42 is a number"
+matcher.(10..20) #=> "10..20 is a Range"
+``` 
+
+Since matcher is just a syntactic sugar for partial functions, you can combine matchers with partial
+functions and each other. 
+
+```ruby
+handle_numbers = Fear.case(Integer, &:itself).and_then(
+  Fear.matcher do |m|
+    m.case(0) { 'zero' }
+    m.case(->(n) { n < 10 }) { 'smaller than ten' }  
+    m.case(->(n) { n > 10 }) { 'bigger than ten' }
+  end
+)
+
+handle_strings = Fear.case(String, &:itself).and_then(
+  Fear.matcher do |m|
+    m.case('zero') { 0 }
+    m.case('one') { 1 }
+    m.else { 'unexpected' }
+  end
+)
+
+handle = handle_numbers.or_else(handle_strings)
+handle.(0) #=> 'zero'
+handle.(12) #=> 'bigger than ten'
+handle.('one') #=> 1
+```
+
+#### More examples
+
+Factorial using pattern matching
+
+```ruby
+factorial = Fear.matcher do |m|
+  m.case(->(n) { n <= 1} ) { 1 }
+  m.else { |n| n * factorial.(n - 1) }
+end
+
+factorial.(10) #=> 3628800
+```
+
+Fibonacci number
+
+```ruby
+fibonnaci = 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.else { raise 'should be positive' }
+end
+
+fibonnaci.(10) #=> 55
+```
+
+Binary tree set implemented using pattern matching https://gist.github.com/bolshakov/3c51bbf7be95066d55d6d1ac8c605a1d
+
+#### Monads pattern matching 
+
+You can use `Option#match`, `Either#match`, and `Try#match` method. It performs matching not 
+only on container itself, but on enclosed value as well. 
+
+Pattern match against an `Option`
+
+```ruby
+Some(42).match do |m|
+  m.some { |x| x * 2 }
+  m.none { 'none' }
+end #=> 84
+```
+
+pattern match on enclosed value
+
+```ruby
+Some(41).match do |m|
+  m.some(:even?) { |x| x / 2 }
+  m.some(:odd?, ->(v) { v > 0 }) { |x| x * 2 }
+  m.none { 'none' }
+end #=> 82
+``` 
+
+it raises `Fear::MatchError` error if nothing matched. To avoid exception, you can pass `#else` branch
+
+```ruby
+Some(42).match do |m|
+  m.some(:odd?) { |x| x * 2 }
+  m.else { 'nothing' }
+end #=> nothing
+```
+
+Pattern matching works the similar way for `Either` and `Try` monads.
+
+In sake of performance, you may want to generate pattern matching function and reuse it multiple times:
+
+```ruby
+matcher = Option.matcher do |m|
+  m.some(42) { 'Yep' }
+  m.some { 'Nope' }
+  m.none { 'Error' } 
+end
+
+matcher.(Some(42)) #=> 'Yep'
+matcher.(Some(40)) #=> 'Nope'
+``` 
+
 ## Testing
 
 To simplify testing, you may use [fear-rspec](https://github.com/bolshakov/fear-rspec) gem. It