fear 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0a628e4319dcc4a672e6a632d6582fdcd9c8bd71
-  data.tar.gz: 3833ced7c33d30fe1111234549b924449a999032
+  metadata.gz: 1fa320f98cb5dc71a7b4e59d7a500c01b729f449
+  data.tar.gz: ea1935382f1bed41adab1264490f3346ff7d93c9
 SHA512:
-  metadata.gz: 56fb816f68a1a85bba4d8819e714c9669b7d2c9972d35a3b4e0c748e16698e2af16687a71cb8099d843800946da2d097fa71045b9c765f8779ef5863ca0a8021
-  data.tar.gz: efa4007136b4b74dbdedddfdfe3e9cd3ccfa5edd4d71d6cd6b554ac0b074298076cdbca2ca3b57a95c81fcf79d4974b9d89a059dd4c5f78855770e100a1134a9
+  metadata.gz: 49da39785143896e2c6ae73b86765fd7aefdac8603ecbf2bd2d4516cce164dd5946fb9041201f7738eca4fbe8c1e6d78760696a0717d5918c36a7dfe48bfc6ff
+  data.tar.gz: 66404d368eb7162f626a4f822b4d4cc0975888f764ffa2bbb31354227a04b795ba8ced9f0ee769880aa6831dc90759f24ea87769a39d88795d8485228e053896

data/.rubocop.yml

@@ -4,29 +4,5 @@ inherit_gem:
 Style/MethodName:
   Enabled: false
 
-# This configuration was generated by `rubocop --auto-gen-config`
-# on 2015-03-09 00:50:30 +0300 using RuboCop version 0.29.1.
-# The point is for the user to remove these configuration records
-# one by one as the offenses are removed from the code base.
-# Note that changes in the inspected code, or installation of new
-# versions of RuboCop, may require this file to be generated again.
-
-# Offense count: 1
-# Configuration parameters: CountComments.
-Metrics/ClassLength:
-  Enabled: false
-  Max: 133
-
-# Offense count: 1
-# Configuration parameters: CountComments.
-Metrics/ModuleLength:
-  Max: 130
-
-# Offense count: 9
 Style/Documentation:
   Enabled: false
-
-# Offense count: 2
-# Configuration parameters: Methods.
-Style/SingleLineBlockParams:
-  Enabled: false

data/README.md

@@ -1,7 +1,9 @@
 # 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)
 
-TODO: Write a gem description
+This gem provides `Option`, `Either`, and `Try` monads implemented an idiomatic way. 
+ It is highly inspired by scala's implementation. 
 
 ## Installation
 
@@ -21,7 +23,136 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Option
+
+Represents optional values. Instances of `Option` are either an instance of 
+`Some` or the object `None`.
+
+The most idiomatic way to use an `Option` instance is to treat it
+as a collection and use `map`, `flat_map`, `select`, or `each`:
+
+```ruby
+name = Option(params[:name])
+upper = name.map(&:strip).select { |n| n.length != 0 }.map(&:upcase)
+puts upper.get_or_else('')
+```
+
+This allows for sophisticated chaining of `Option` values without
+having to check for the existence of a value.
+
+See full documentation [Fear::Option](http://www.rubydoc.info/github/bolshakov/fear/master/Fear/Option)
+
+### Try
+
+The `Try` represents a computation that may either result in an exception, 
+or return a successfully computed value.  Instances of `Try`, are either 
+an instance of `Success` or `Failure`.
+
+For example, `Try` can be used to perform division on a user-defined input, 
+without the need to do explicit exception-handling in all of the places 
+that an exception might occur.
+
+```ruby
+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}"
+end
+```
+
+See full documentation [Fear::Try](http://www.rubydoc.info/github/bolshakov/fear/master/Fear/Try)
+
+### 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`.
+
+A common use of `Either` is as an alternative to `Option` for dealing
+with possible missing values.  In this usage, `None` is replaced
+with a `Left` which can contain useful information.
+`Right` takes the place of `Some`. Convention dictates
+that `Left` is used for failure and `Right` is used for success.
+
+For example, you could use `Either<String, Fixnum>` to select whether a
+received input is a `String` or an `Fixnum`.
+
+```ruby
+input = Readline.readline('Type Either a string or an Int: ', true)
+result = begin
+  Right(Integer(input))
+rescue ArgumentError
+  Left(input)
+end
+
+puts(
+  result.reduce(
+    -> (x) { "You passed me the Int: #{x}, which I will increment. #{x} + 1 = #{x+1}" },
+    -> (x) { "You passed me the String: #{x}" }
+  )
+)
+```
+  
+See full documentation [Fear::Either](http://www.rubydoc.info/github/bolshakov/fear/master/Fear/Either)
+  
+### For composition
+
+Provides syntactic sugar for composition of multiple monadic operations. 
+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)) do 
+  a * b 
+end #=> Some(6)
+```
+
+It would be translated to 
+
+```ruby
+Some(2).flat_map do |a|
+  Some(3).map do |b|
+    a * b
+  end
+end
+```
+
+If one of operands is None, the result is None
+
+```ruby
+For(a: Some(2), b: None()) do
+  a * b
+end  #=> None()
+
+For(a: None(), b: Some(2)) do 
+  a * b 
+end #=> None()
+```
+
+`For` works with arrays as well
+
+```ruby
+For(a: [1, 2], b: [2, 3], c: [3, 4]) do 
+  a * b * c
+end #=> [6, 8, 9, 12, 12, 16, 18, 24]
+```
+ 
+would be translated to:
+
+```ruby
+[1, 2].flat_map do |a|
+  [2, 3].flat_map do |b|
+    [3, 4].map do |c|
+      a * b * c
+    end
+  end
+end
+```
 
 ## Contributing
 

data/lib/fear/either.rb

@@ -8,7 +8,7 @@ module Fear
   # `Right` takes the place of `Some`. Convention dictates
   # that `Left` is used for failure and `Right` is used for success.
   #
-  # For example, you could use `Either<String, Fixnum>` to detect whether a
+  # For example, you could use `Either<String, Fixnum>` to select whether a
   # received input is a `String` or an `Fixnum`.
   #
   # @example
@@ -26,7 +26,7 @@ module Fear
   #     )
   #   )
   #
-  # `Either` is right-biased, which means that `Right` is assumed to be the default case to
+  # Either is right-biased, which means that `Right` is assumed to be the default case to
   # operate on. If it is `Left`, operations like `#map`, `#flat_map`, ... return the `Left` value
   # unchanged:
   #
@@ -63,11 +63,11 @@ module Fear
   #   Right(12).flat_map { |x| Left('ruby') } #=> Left('ruby')
   #   Left(12).flat_map { |x| Left('ruby') }  #=> Left(12)
   #
-  # @example #detect
-  #   Right(12).detect(-1, &:even?) #=> Right(12))
-  #   Right(7).detect(-1, &:even?) #=> Left(-1)
-  #   Left(12).detect(-1, &:even?) #=> Left(-1)
-  #   Left(12).detect(-> { -1 }, &:even?) #=> Left(-1)
+  # @example #select
+  #   Right(12).select(-1, &:even?) #=> Right(12))
+  #   Right(7).select(-1, &:even?) #=> Left(-1)
+  #   Left(12).select(-1, &:even?) #=> Left(-1)
+  #   Left(12).select(-> { -1 }, &:even?) #=> Left(-1)
   #
   # @example #to_a
   #   Right(12).to_a #=> [12]
@@ -111,7 +111,6 @@ module Fear
   #
   module Either
     include Dry::Equalizer(:value)
-    include Fear
 
     def left_class
       Left
@@ -125,6 +124,20 @@ module Fear
       @value = value
     end
 
+    # @return [Boolean]
+    def right?
+      is_a?(Right)
+    end
+
+    alias success? right?
+
+    # @return [Boolean]
+    def left?
+      !right?
+    end
+
+    alias failure? left?
+
     attr_reader :value
     protected :value
 

data/lib/fear/failure.rb

@@ -32,8 +32,7 @@ module Fear
     end
 
     # @return [Failure] self
-    # TODO: rename to select
-    def detect
+    def select
       self
     end
 

data/lib/fear/left.rb

@@ -8,7 +8,7 @@ module Fear
     # @param default [Proc, any]
     # @return [Either]
     #
-    def detect(default)
+    def select(default)
       Left.new(Utils.return_or_call_proc(default))
     end
 

data/lib/fear/none.rb

@@ -8,7 +8,7 @@ module Fear
     #
     # @return [None]
     #
-    def detect(*)
+    def select(*)
       self
     end
 

data/lib/fear/option.rb

@@ -2,20 +2,15 @@ module Fear
   # Represents optional values. Instances of `Option`
   # are either an instance of `Some` or the object `None`.
   #
-  # The most idiomatic way to use an `Option` instance is to treat it
-  # as a collection or monad and use `map`, `flat_map`, `detect`, or `each`:
-  #
-  # @example
+  # @example The most idiomatic way to use an `Option` instance is to treat it as a collection
   #   name = Option(params[:name])
-  #   upper = name.map(&:strip).detect { |n| n.length != 0 }.map(&:upcase)
+  #   upper = name.map(&:strip).select { |n| n.length != 0 }.map(&:upcase)
   #   puts upper.get_or_else('')
   #
   # This allows for sophisticated chaining of `Option` values without
   # having to check for the existence of a value.
   #
-  # A less-idiomatic way to use `Option` values is via pattern matching:
-  #
-  # @example
+  # @example A less-idiomatic way to use `Option` values is via pattern matching
   #   name = Option(params[:name])
   #   case name
   #   when Some
@@ -24,9 +19,7 @@ module Fear
   #     puts 'No name value'
   #   end
   #
-  # or manually checking for non emptiness:
-  #
-  # @example
+  # @example or manually checking for non emptiness
   #   name = Option(params[:name])
   #   if name.empty?
   #     puts 'No name value'
@@ -34,17 +27,17 @@ module Fear
   #     puts name.strip.upcase
   #   end
   #
-  # @example #detect
-  #   User.find(params[:id]).detect do |user|
+  # @example #select
+  #   User.find(params[:id]).select do |user|
   #     user.posts.count > 0
   #   end #=> Some(User)
   #
-  #   User.find(params[:id]).detect do |user|
+  #   User.find(params[:id]).select do |user|
   #     user.posts.count > 0
   #   end #=> None
   #
   #   User.find(params[:id])
-  #     .detect(&:confirmed?)
+  #     .select(&:confirmed?)
   #     .map(&:posts)
   #     .inject(0, &:count)
   #

data/lib/fear/right.rb

@@ -9,7 +9,7 @@ module Fear
     # @param default [Proc, any]
     # @return [Either]
     #
-    def detect(default)
+    def select(default)
       if yield(value)
         self
       else

data/lib/fear/right_biased.rb

@@ -17,7 +17,7 @@ module Fear
       end
 
       # Ensures that returned value either left, or right.
-      def detect(*)
+      def select(*)
         super.tap do |result|
           Utils.assert_type!(result, left_class, right_class)
         end

data/lib/fear/some.rb

@@ -20,7 +20,7 @@ module Fear
     #   applying the `predicate` to this option's value
     #   returns true. Otherwise, return `None`.
     #
-    def detect
+    def select
       if yield(value)
         self
       else

data/lib/fear/success.rb

@@ -42,7 +42,7 @@ module Fear
     # @yieldreturn [Boolean]
     # @return [Try]
     #
-    def detect
+    def select
       if yield(value)
         self
       else

data/lib/fear/try.rb

@@ -11,8 +11,8 @@ module Fear
   # might occur.
   #
   # @example
-  #   dividend = Try { params[:dividend].to_i }
-  #   divisor = Try { params[:divisor].to_i }
+  #   dividend = Try { Integer(params[:dividend]) }
+  #   divisor = Try { Integer(params[:divisor]) }
   #   problem = dividend.flat_map { |x| divisor.map { |y| x / y }
   #
   #   if problem.success?
@@ -53,12 +53,12 @@ module Fear
   #   Success(42).map { |v| v/2 }                 #=> Success(21)
   #   Failure(ArgumentError.new).map { |v| v/2 }  #=> Failure(ArgumentError.new)
   #
-  # @example #detect
-  #   Success(42).detect { |v| v > 40 }
+  # @example #select
+  #   Success(42).select { |v| v > 40 }
   #     #=> Success(21)
-  #   Success(42).detect { |v| v < 40 }
+  #   Success(42).select { |v| v < 40 }
   #     #=> Failure(NoSuchElementError.new("Predicate does not hold for 42"))
-  #   Failure(ArgumentError.new).detect { |v| v < 40 }
+  #   Failure(ArgumentError.new).select { |v| v < 40 }
   #     #=> Failure(ArgumentError.new)
   #
   # @example #recover_with

data/lib/fear/version.rb

@@ -1,3 +1,3 @@
 module Fear
-  VERSION = '0.0.1'.freeze
+  VERSION = '0.1.0'.freeze
 end

data/spec/fear/failure_spec.rb

@@ -33,8 +33,8 @@ RSpec.describe Fear::Failure do
     it { is_expected.to eq(failure) }
   end
 
-  describe '#detect' do
-    subject { failure.detect { |v| v == 'value' } }
+  describe '#select' do
+    subject { failure.select { |v| v == 'value' } }
     it { is_expected.to eq(failure) }
   end
 

data/spec/fear/left_spec.rb

@@ -5,9 +5,21 @@ RSpec.describe Fear::Left do
     let(:left) { described_class.new('value') }
   end
 
-  describe '#detect' do
+  let(:left) { described_class.new('value') }
+
+  describe '#right?' do
+    subject { left }
+    it { is_expected.not_to be_right }
+  end
+
+  describe '#left?' do
+    subject { left }
+    it { is_expected.to be_left }
+  end
+
+  describe '#select' do
     subject do
-      described_class.new('value').detect(default) { |v| v == 'value' }
+      left.select(default) { |v| v == 'value' }
     end
 
     context 'proc default' do
@@ -28,13 +40,13 @@ RSpec.describe Fear::Left do
   end
 
   describe '#swap' do
-    subject { described_class.new('value').swap }
+    subject { left.swap }
     it { is_expected.to eq(Right('value')) }
   end
 
   describe '#reduce' do
     subject do
-      described_class.new('value').reduce(
+      left.reduce(
         ->(left) { "Left: #{left}" },
         ->(right) { "Right: #{right}" },
       )
@@ -69,7 +81,7 @@ RSpec.describe Fear::Left do
     end
 
     context 'value is not Either' do
-      subject { proc { described_class.new('error').join_left } }
+      subject { proc { left.join_left } }
 
       it 'fails with type error' do
         is_expected.to raise_error(TypeError)

data/spec/fear/none_spec.rb

@@ -19,8 +19,8 @@ RSpec.describe Fear::None do
     expect(result).to eq nil
   end
 
-  describe '#detect' do
-    subject { none.detect { |value| value > 42 } }
+  describe '#select' do
+    subject { none.select { |value| value > 42 } }
 
     it 'always return None' do
       is_expected.to eq(None())

data/spec/fear/right_spec.rb

@@ -5,8 +5,18 @@ RSpec.describe Fear::Right do
 
   let(:right) { described_class.new('value') }
 
-  describe '#detect' do
-    subject { right.detect(default, &predicate) }
+  describe '#right?' do
+    subject { right }
+    it { is_expected.to be_right }
+  end
+
+  describe '#left?' do
+    subject { right }
+    it { is_expected.not_to be_left }
+  end
+
+  describe '#select' do
+    subject { right.select(default, &predicate) }
 
     context 'predicate evaluates to true' do
       let(:predicate) { ->(v) { v == 'value' } }
@@ -28,13 +38,13 @@ RSpec.describe Fear::Right do
   end
 
   describe '#swap' do
-    subject { described_class.new('value').swap }
+    subject { right.swap }
     it { is_expected.to eq(Fear::Left.new('value')) }
   end
 
   describe '#reduce' do
     subject do
-      described_class.new('value').reduce(
+      right.reduce(
         ->(left) { "Left: #{left}" },
         ->(right) { "Right: #{right}" },
       )

data/spec/fear/some_spec.rb

@@ -8,8 +8,8 @@ RSpec.describe Fear::Some do
   subject(:some) { Some(value) }
   let(:value) { 42 }
 
-  describe '#detect' do
-    subject { some.detect(&predicate) }
+  describe '#select' do
+    subject { some.select(&predicate) }
 
     context 'predicate evaluates to true' do
       let(:predicate) { ->(v) { v > 40 } }

data/spec/fear/success_spec.rb

@@ -54,19 +54,19 @@ RSpec.describe Fear::Success do
     end
   end
 
-  describe '#detect' do
+  describe '#select' do
     context 'predicate holds for value' do
-      subject { success.detect { |v| v == 'value' } }
+      subject { success.select { |v| v == 'value' } }
       it { is_expected.to eq(success) }
     end
 
     context 'predicate does not hold for value' do
-      subject { proc { success.detect { |v| v != 'value' }.get } }
+      subject { proc { success.select { |v| v != 'value' }.get } }
       it { is_expected.to raise_error(Fear::NoSuchElementError, 'Predicate does not hold for `value`') }
     end
 
     context 'predicate fails with error' do
-      subject { proc { success.detect { fail 'foo' }.get } }
+      subject { proc { success.select { fail 'foo' }.get } }
       it { is_expected.to raise_error(RuntimeError, 'foo') }
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fear
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Tema Bolshakov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-08 00:00:00.000000000 Z
+date: 2016-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-equalizer