fear 0.1.0 → 0.2.0

data/lib/fear/try.rb

@@ -1,16 +1,16 @@
 module Fear
-  # The `Try` represents a computation that may either result
-  # in an exception, or return a successfully computed value.
+  # 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+.
   #
-  # Instances of `Try`, are either an instance of `Success` or
-  # `Failure`.
-  #
-  # For example, `Try` can be used to perform division on a
+  # 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.
   #
   # @example
+  #   include Fear::Try::Mixin
+  #
   #   dividend = Try { Integer(params[:dividend]) }
   #   divisor = Try { Integer(params[:divisor]) }
   #   problem = dividend.flat_map { |x| divisor.map { |y| x / y }
@@ -22,89 +22,226 @@ module Fear
   #     puts "Info from the exception: #{problem.exception.message}"
   #   end
   #
-  # An important property of `Try` shown in the above example is its
-  # ability to `pipeline`, or chain, operations, catching exceptions
-  # along the way. The `flat_map` and `map` combinators in the above
+  # An important property of +Try+ shown in the above example is its
+  # ability to _pipeline_, or chain, operations, catching exceptions
+  # along the way. The +flat_map+ and +map+ combinators in the above
   # example each essentially pass off either their successfully completed
-  # value, wrapped in the `Success` type for it to be further operated
+  # value, wrapped in the +Success+ type for it to be further operated
   # upon by the next combinator in the chain, or the exception wrapped
-  # in the `Failure` type usually to be simply passed on down the chain.
-  # Combinators such as `rescue` and `recover` are designed to provide some
+  # in the +Failure+ type usually to be simply passed on down the chain.
+  # Combinators such as +recover_with+ and +recover+ are designed to provide some
   # 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.
-  #
-  # @note all `Try` combinators will catch exceptions and return failure
-  # unless otherwise specified in the documentation.
-  #
-  # @example #or_else
-  #   Success(42).or_else { -1 }                 #=> Success(42)
-  #   Failure(ArgumentError.new).or_else { -1 }  #=> Success(-1)
-  #   Failure(ArgumentError.new).or_else { 1/0 } #=> Failure(ZeroDivisionError.new('divided by 0'))
-  #
-  # @example #flatten
-  #   Success(42).flatten                         #=> Success(42)
-  #   Success(Success(42)).flatten                #=> Success(42)
-  #   Success(Failure(ArgumentError.new)).flatten #=> Failure(ArgumentError.new)
-  #   Failure(ArgumentError.new).flatten { -1 }   #=> Failure(ArgumentError.new)
-  #
-  # @example #map
-  #   Success(42).map { |v| v/2 }                 #=> Success(21)
-  #   Failure(ArgumentError.new).map { |v| v/2 }  #=> Failure(ArgumentError.new)
-  #
-  # @example #select
-  #   Success(42).select { |v| v > 40 }
-  #     #=> Success(21)
-  #   Success(42).select { |v| v < 40 }
-  #     #=> Failure(NoSuchElementError.new("Predicate does not hold for 42"))
-  #   Failure(ArgumentError.new).select { |v| v < 40 }
-  #     #=> Failure(ArgumentError.new)
-  #
-  # @example #recover_with
-  #   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(RuntimeError)
-  #
-  # @example #recover
-  #   Success(42).recover { |e| e.massage }
-  #     #=> Success(42)
-  #   Failure(ArgumentError.new).recover { |e| e.massage }
-  #     #=> Success('ArgumentError')
-  #   Failure(ArgumentError.new).recover { |e| fail }
-  #     #=> Failure(RuntimeError)
+  # @note only non-fatal exceptions are caught by the combinators on +Try+.
+  #   Serious system errors, on the other hand, will be thrown.
+  #
+  # @note all +Try+ combinators will catch exceptions and return failure unless
+  #   otherwise specified in the documentation.
+  #
+  # @!method get_or_else(*args)
+  #   Returns the value from this +Success+ or evaluates the given
+  #   default argument if this is a +Failure+.
+  #   @overload get_or_else(&default)
+  #     @yieldreturn [any]
+  #     @return [any]
+  #     @example
+  #       Success(42).get_or_else { 24/2 }                #=> 42
+  #       Failure(ArgumentError.new).get_or_else { 24/2 } #=> 12
+  #   @overload get_or_else(default)
+  #     @return [any]
+  #     @example
+  #       Success(42).get_or_else(12)                #=> 42
+  #       Failure(ArgumentError.new).get_or_else(12) #=> 12
+  #
+  # @!method include?(other_value)
+  #   Returns +true+ if it has an element that is equal
+  #   (as determined by +==+) to +other_value+, +false+ otherwise.
+  #   @param [any]
+  #   @return [Boolean]
+  #   @example
+  #     Success(17).include?(17)                #=> true
+  #     Success(17).include?(7)                 #=> false
+  #     Failure(ArgumentError.new).include?(17) #=> false
+  #
+  # @!method each(&block)
+  #   Performs the given block if this is a +Success+.
+  #   @note if block raise an error, then this method may raise an exception.
+  #   @yieldparam [any] value
+  #   @yieldreturn [void]
+  #   @return [Try] itself
+  #   @example
+  #     Success(17).each do |value|
+  #       puts value
+  #     end #=> prints 17
+  #
+  #     Failure(ArgumentError.new).each do |value|
+  #       puts value
+  #     end #=> does nothing
+  #
+  # @!method map(&block)
+  #   Maps the given block to the value from this +Success+ or
+  #   returns this if this is a +Failure+.
+  #   @yieldparam [any] value
+  #   @yieldreturn [any]
+  #   @example
+  #     Success(42).map { |v| v/2 }                 #=> Success(21)
+  #     Failure(ArgumentError.new).map { |v| v/2 }  #=> Failure(ArgumentError.new)
+  #
+  # @!method flat_map(&block)
+  #   Returns the given block applied to the value from this +Success+
+  #   or returns this if this is a +Failure+.
+  #   @yieldparam [any] value
+  #   @yieldreturn [Try]
+  #   @return [Try]
+  #   @example
+  #     Success(42).flat_map { |v| Success(v/2) }
+  #       #=> Success(21)
+  #     Failure(ArgumentError.new).flat_map { |v| Success(v/2) }
+  #       #=> Failure(ArgumentError.new)
+  #
+  # @!method to_a
+  #   Returns an +Array+ containing the +Success+ value or an
+  #   empty +Array+ if this is a +Failure+.
+  #   @return [Array]
+  #   @example
+  #     Success(42).to_a                 #=> [21]
+  #     Failure(ArgumentError.new).to_a  #=> []
+  #
+  # @!method to_option
+  #   Returns an +Some+ containing the +Success+ value or a +None+ if
+  #   this is a +Failure+.
+  #   @return [Option]
+  #   @example
+  #     Success(42).to_option                 #=> Some(21)
+  #     Failure(ArgumentError.new).to_option  #=> None()
+  #
+  # @!method any?(&predicate)
+  #   Returns +false+ if +Failure+ or returns the result of the
+  #   application of the given predicate to the +Success+ value.
+  #   @yieldparam [any] value
+  #   @yieldreturn [Boolean]
+  #   @return [Boolean]
+  #   @example
+  #     Success(12).any?( |v| v > 10)                #=> true
+  #     Success(7).any?( |v| v > 10)                 #=> false
+  #     Failure(ArgumentError.new).any?( |v| v > 10) #=> false
+  #
+  # ---
+  #
+  # @!method success?
+  #   Returns +true+ if it is a +Success+, +false+ otherwise.
+  #   @return [Boolean]
+  #
+  # @!method failure?
+  #   Returns +true+ if it is a +Failure+, +false+ otherwise.
+  #   @return [Boolean]
+  #
+  # @!method get
+  #   Returns the value from this +Success+ or raise the exception
+  #   if this is a +Failure+.
+  #   @return [any]
+  #   @example
+  #     Success(42).get                 #=> 42
+  #     Failure(ArgumentError.new).get  #=> ArgumentError: ArgumentError
+  #
+  # @!method or_else(&default)
+  #   Returns this +Try+ if it's a +Success+ or the given default
+  #   argument if this is a +Failure+.
+  #   @return [Try]
+  #   @example
+  #     Success(42).or_else { -1 }                 #=> Success(42)
+  #     Failure(ArgumentError.new).or_else { -1 }  #=> Success(-1)
+  #     Failure(ArgumentError.new).or_else { 1/0 } #=> Failure(ZeroDivisionError.new('divided by 0'))
+  #
+  # @!method flatten
+  #   Transforms a nested +Try+, ie, a +Success+ of +Success+,
+  #   into an un-nested +Try+, ie, a +Success+.
+  #   @return [Try]
+  #   @example
+  #     Success(42).flatten                         #=> Success(42)
+  #     Success(Success(42)).flatten                #=> Success(42)
+  #     Success(Failure(ArgumentError.new)).flatten #=> Failure(ArgumentError.new)
+  #     Failure(ArgumentError.new).flatten { -1 }   #=> Failure(ArgumentError.new)
+  #
+  # @!method select(&predicate)
+  #   Converts this to a +Failure+ if the predicate is not satisfied.
+  #   @yieldparam [any] value
+  #   @yieldreturn [Boolean]
+  #   @return [Try]
+  #   @example
+  #     Success(42).select { |v| v > 40 }
+  #       #=> Success(21)
+  #     Success(42).select { |v| v < 40 }
+  #       #=> Failure(Fear::NoSuchElementError.new("Predicate does not hold for 42"))
+  #     Failure(ArgumentError.new).select { |v| v < 40 }
+  #       #=> Failure(ArgumentError.new)
+  #
+  # @!method recover_with(&block)
+  #   Applies the given block to exception. This is like +flat_map+
+  #   for the exception.
+  #   @yieldparam [Exception] exception
+  #   @yieldreturn [Try]
+  #   @return [Try]
+  #   @example
+  #     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(RuntimeError)
+  #
+  # @!method recover(&block)
+  #   Applies the given block to exception. This is like +map+ for the exception.
+  #   @yieldparam [Exception] exception
+  #   @yieldreturn [any]
+  #   @return [Try]
+  #   @example #recover
+  #     Success(42).recover { |e| e.massage }
+  #       #=> Success(42)
+  #     Failure(ArgumentError.new).recover { |e| e.massage }
+  #       #=> Success('ArgumentError')
+  #     Failure(ArgumentError.new).recover { |e| fail }
+  #       #=> Failure(RuntimeError)
+  #
+  # @!method to_either
+  #   Returns +Left+ with exception if this is a +Failure+, otherwise
+  #   returns +Right+ with +Success+ value.
+  #   @return [Right<any>, Left<StandardError>]
+  #   @example
+  #     Success(42).to_either                #=> Right(42)
+  #     Failure(ArgumentError.new).to_either #=> Left(ArgumentError.new)
   #
   # @author based on Twitter's original implementation.
   # @see https://github.com/scala/scala/blob/2.11.x/src/library/scala/util/Try.scala
   #
   module Try
+    # @private
     def left_class
       Failure
     end
 
+    # @private
     def right_class
       Success
     end
 
-    # @return [true, false] `true` if the `Try` is a `Failure`,
-    #   `false` otherwise.
+    # Include this mixin to access convenient factory methods.
+    # @example
+    #   include Fear::Try::Mixin
+    #
+    #   Try { 4/2 } #=> #<Fear::Success value=2>
+    #   Try { 4/0 } #=> #<Fear::Failure value=#<ZeroDivisionError: divided by 0>>
+    #   Success(2)  #=> #<Fear::Success value=2>
     #
-    def failure?
-      !success?
-    end
-
     module Mixin
-      # Constructs a `Try` using the block. This
-      # method will ensure any non-fatal exception is caught and a
-      # `Failure` object is returned.
+      # Constructs a +Try+ using the block. This
+      # method will ensure any non-fatal exception )is caught and a
+      # +Failure+ object is returned.
       # @return [Try]
       #
       def Try
         Success.new(yield)
-      rescue StandardError => error
+      rescue => error
         Failure.new(error)
       end
 

data/lib/fear/utils.rb

@@ -1,4 +1,5 @@
 module Fear
+  # @private
   module Utils
     extend self
 

data/lib/fear/version.rb

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

data/spec/fear/failure_spec.rb

@@ -1,5 +1,6 @@
 RSpec.describe Fear::Failure do
-  let(:failure) { described_class.new(RuntimeError.new('error')) }
+  let(:exception) { RuntimeError.new('error') }
+  let(:failure) { described_class.new(exception) }
 
   it_behaves_like Fear::RightBiased::Left do
     let(:left) { failure }
@@ -75,4 +76,9 @@ RSpec.describe Fear::Failure do
       it { expect { recover.get }.to raise_error(RuntimeError, 'unexpected error') }
     end
   end
+
+  describe '#to_either' do
+    subject { failure.to_either }
+    it { is_expected.to eq(Fear::Left.new(exception)) }
+  end
 end

data/spec/fear/left_spec.rb

@@ -17,9 +17,9 @@ RSpec.describe Fear::Left do
     it { is_expected.to be_left }
   end
 
-  describe '#select' do
+  describe '#select_or_else' do
     subject do
-      left.select(default) { |v| v == 'value' }
+      left.select_or_else(default) { |v| v == 'value' }
     end
 
     context 'proc default' do
@@ -39,6 +39,16 @@ RSpec.describe Fear::Left do
     end
   end
 
+  describe '#select' do
+    subject do
+      left.select { |v| v == 'value' }
+    end
+
+    it 'return self' do
+      is_expected.to eq(left)
+    end
+  end
+
   describe '#swap' do
     subject { left.swap }
     it { is_expected.to eq(Right('value')) }

data/spec/fear/none_spec.rb

@@ -7,16 +7,19 @@ RSpec.describe Fear::None do
 
   subject(:none) { None() }
 
-  specify '#get fails with exception' do
-    expect do
-      none.get
-    end.to raise_error(NoMethodError)
+  describe '#get' do
+    subject { proc { none.get } }
+    it { is_expected.to raise_error(Fear::NoSuchElementError) }
   end
 
-  specify '#or_nil returns nil' do
-    result = none.or_nil
+  describe '#or_nil' do
+    subject { none.or_nil }
+    it { is_expected.to eq(nil) }
+  end
 
-    expect(result).to eq nil
+  describe '#empty?' do
+    subject { none.empty? }
+    it { is_expected.to eq(true) }
   end
 
   describe '#select' do

data/spec/fear/option_spec.rb

@@ -1,32 +1,15 @@
 RSpec.describe Fear::Option do
   include Fear::Option::Mixin
 
-  describe 'Option()' do
-    it 'returns Some if value is not nil' do
-      option = Option(double)
-
-      expect(option).to be_kind_of(Fear::Some)
-    end
-
-    it 'returns None if value is nil' do
-      option = Option(nil)
-
-      expect(option).to be_kind_of(Fear::None)
-    end
-  end
-
-  let(:some) { Some(42) }
-  let(:none) { None() }
-
-  describe '#empty?' do
-    context 'Some' do
-      subject { some.empty? }
-      it { is_expected.to eq(false) }
+  describe '#Option()' do
+    context 'value is nil' do
+      subject { Option(nil) }
+      it { is_expected.to eq(None()) }
     end
 
-    context 'None' do
-      subject { none.empty? }
-      it { is_expected.to eq(true) }
+    context 'value is not nil' do
+      subject { Option(42) }
+      it { is_expected.to eq(Some(42)) }
     end
   end
 end

data/spec/fear/right_spec.rb

@@ -15,8 +15,8 @@ RSpec.describe Fear::Right do
     it { is_expected.not_to be_left }
   end
 
-  describe '#select' do
-    subject { right.select(default, &predicate) }
+  describe '#select_or_else' do
+    subject { right.select_or_else(default, &predicate) }
 
     context 'predicate evaluates to true' do
       let(:predicate) { ->(v) { v == 'value' } }
@@ -37,6 +37,20 @@ RSpec.describe Fear::Right do
     end
   end
 
+  describe '#select' do
+    subject { right.select(&predicate) }
+
+    context 'predicate evaluates to true' do
+      let(:predicate) { ->(v) { v == 'value' } }
+      it { is_expected.to eq(right) }
+    end
+
+    context 'predicate evaluates to false' do
+      let(:predicate) { ->(v) { v != 'value' } }
+      it { is_expected.to eq(Fear::Left.new('value')) }
+    end
+  end
+
   describe '#swap' do
     subject { right.swap }
     it { is_expected.to eq(Fear::Left.new('value')) }

data/spec/fear/some_spec.rb

@@ -5,8 +5,7 @@ RSpec.describe Fear::Some do
     let(:right) { described_class.new('value') }
   end
 
-  subject(:some) { Some(value) }
-  let(:value) { 42 }
+  subject(:some) { Some(42) }
 
   describe '#select' do
     subject { some.select(&predicate) }
@@ -36,13 +35,18 @@ RSpec.describe Fear::Some do
     end
   end
 
-  specify '#get returns value' do
-    expect(some.get).to eq value
+  describe '#get' do
+    subject { some.get }
+    it { is_expected.to eq(42) }
   end
 
-  specify '#or_nil returns value' do
-    result = some.or_nil
+  describe '#or_nil' do
+    subject { some.or_nil }
+    it { is_expected.to eq(42) }
+  end
 
-    expect(result).to eq value
+  describe '#empty?' do
+    subject { some.empty? }
+    it { is_expected.to eq(false) }
   end
 end

data/spec/fear/success_spec.rb

@@ -80,4 +80,9 @@ RSpec.describe Fear::Success do
     subject { success.recover { |v| v * 2 } }
     it { is_expected.to eq(success) }
   end
+
+  describe '#to_either' do
+    subject { success.to_either }
+    it { is_expected.to eq(Fear::Right.new('value')) }
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fear
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tema Bolshakov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-09 00:00:00.000000000 Z
+date: 2016-12-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-equalizer
@@ -105,6 +105,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -136,7 +137,7 @@ files:
 - spec/fear/success_spec.rb
 - spec/fear/utils_spec.rb
 - spec/spec_helper.rb
-homepage: https://github.com/bolshakov/functional
+homepage: https://github.com/bolshakov/fear
 licenses:
 - MIT
 metadata: {}