fear 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1fa320f98cb5dc71a7b4e59d7a500c01b729f449
-  data.tar.gz: ea1935382f1bed41adab1264490f3346ff7d93c9
+  metadata.gz: b856c96f41e1cab50482a618c021f32eccd16d97
+  data.tar.gz: 7e443f61c506e29e1578f64e7f2237664c1465ec
 SHA512:
-  metadata.gz: 49da39785143896e2c6ae73b86765fd7aefdac8603ecbf2bd2d4516cce164dd5946fb9041201f7738eca4fbe8c1e6d78760696a0717d5918c36a7dfe48bfc6ff
-  data.tar.gz: 66404d368eb7162f626a4f822b4d4cc0975888f764ffa2bbb31354227a04b795ba8ced9f0ee769880aa6831dc90759f24ea87769a39d88795d8485228e053896
+  metadata.gz: fef37c2dd16a69752985bd04d734ab27a69513e9db7a114c93dfb66116473d549e3a3106a0221e1f1e61ad0fa1192291cfb9e76eb7fbfc5af7297540d167610c
+  data.tar.gz: ff910daab541a9279e7838a971db37d9a37f6bdb220e6b17e985a9e3daaebd61cbba31167efc3e1d7b9201958310270b9788597ecc284b61f0f30bf20586e8f6

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/README.md

@@ -32,6 +32,8 @@ 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
+include Fear::Option::Mixin
+
 name = Option(params[:name])
 upper = name.map(&:strip).select { |n| n.length != 0 }.map(&:upcase)
 puts upper.get_or_else('')
@@ -53,6 +55,8 @@ without the need to do explicit exception-handling in all of the places
 that an exception might occur.
 
 ```ruby
+include Fear::Try::Mixin
+
 dividend = Try { Integer(params[:dividend]) }
 divisor = Try { Integer(params[:divisor]) }
 
@@ -83,6 +87,8 @@ For example, you could use `Either<String, Fixnum>` to select whether a
 received input is a `String` or an `Fixnum`.
 
 ```ruby
+include Fear::Either::Mixin
+
 input = Readline.readline('Type Either a string or an Int: ', true)
 result = begin
   Right(Integer(input))
@@ -107,6 +113,8 @@ It supports two such operations - `flat_map` and `map`. Any class providing them
 is supported by `For`.
 
 ```ruby
+include Fear::For::Mixin
+
 For(a: Some(2), b: Some(3)) do 
   a * b 
 end #=> Some(6)

data/fear.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.email         = ['abolshakov@spbtv.com']
   spec.summary       = "%q{Ruby port of some Scala's monads.}"
   spec.description   = "Ruby port of some Scala's monads."
-  spec.homepage      = 'https://github.com/bolshakov/functional'
+  spec.homepage      = 'https://github.com/bolshakov/fear'
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0")

data/lib/fear/either.rb

@@ -1,15 +1,15 @@
 module Fear
   # Represents a value of one of two possible types (a disjoint union.)
-  # An instance of `Either` is either an instance of `Left` or `Right`.
+  # 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.
+  # 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 Right.
   #
-  # For example, you could use `Either<String, Fixnum>` to select whether a
-  # received input is a `String` or an `Fixnum`.
+  # For example, you could use +Either<String, Fixnum>+ to select_or_else whether a
+  # received input is a +String+ or an +Fixnum+.
   #
   # @example
   #   in = Readline.readline('Type Either a string or an Int: ', true)
@@ -26,96 +26,198 @@ module Fear
   #     )
   #   )
   #
-  # 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
+  # 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:
   #
-  # @example #map
-  #   Right(12).map { |_| _ * 2) #=> Right(24)
-  #   Left(23).map { |_| _ * 2)  #=> Left(23)
-  #
-  # @example #get_or_else
-  #   Right(12).get_or_else(17) #=> 12
-  #   Left(12).get_or_else(17) #=> 17
-  #
-  #   Right(12).get_or_else { 17 } #=> 12
-  #   Left(12).get_or_else { 17 } #=> 17
-  #
-  # @example #include?
-  #   # Returns true because value of Right is "something" which equals "something".
-  #   Right("something").include?("something") #= true
-  #
-  #   # Returns false because value of Right is "something" which does not equal "anything".
-  #   Right("something").include?("anything") #=> false
-  #
-  #   # Returns false because there is no value for Right.
-  #   Left("something").include?("something") #=> false
-  #
-  # @example #each
-  #   Right(12).each { |x| puts x } # prints "12"
-  #   Left(12).each { |x| puts x } # doesn't print
-  #
-  # @example #map
-  #   Right('ruby').map(&:length) #=> Right(4)
-  #   Left('ruby').map(&:length) #=> Left('ruby')
-  #
-  # @example #flat_map
-  #   Right(12).flat_map { |x| Left('ruby') } #=> Left('ruby')
-  #   Left(12).flat_map { |x| Left('ruby') }  #=> Left(12)
-  #
-  # @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]
-  #   Left(12).to_a #=> []
-  #
-  # @example #to_option
-  #   Right(12).to_option #=> Some(12)
-  #   Left(12).to_option #=> None()
-  #
-  # @example #any?
-  #   Right(12).any? { |v| v > 10 } #=> true
-  #   Right(7).any? { |v| v > 10 }  #=> false
-  #   Left(12).any? { |v| v > 10 }  #=> false
-  #
-  # @example #swap
-  #   left = Left("left")
-  #   right = left.swap #=> Right("left")
-  #
-  # @example #reduce
-  #   result = possibly_failing_operation()
-  #   log(
-  #     result.reduce(
-  #       ->(ex) { "Operation failed with #{ex}" },
-  #       ->(v) { "Operation produced value: #{v}" },
+  # @!method get_or_else(*args)
+  #   Returns the value from this +Right+ or evaluates the given
+  #   default argument if this is a +Left+.
+  #   @overload get_or_else(&default)
+  #     @yieldreturn [any]
+  #     @return [any]
+  #     @example
+  #       Right(42).get_or_else { 24/2 }         #=> 42
+  #       Left('undefined').get_or_else { 24/2 } #=> 12
+  #   @overload get_or_else(default)
+  #     @return [any]
+  #     @example
+  #       Right(42).get_or_else(12)         #=> 42
+  #       Left('undefined').get_or_else(12) #=> 12
+  #
+  # @!method include?(other_value)
+  #   Returns +true+ if +Right+ has an element that is equal
+  #   (as determined by +==+) to +other_value+, +false+ otherwise.
+  #   @param [any]
+  #   @return [Boolean]
+  #   @example
+  #     Right(17).include?(17)         #=> true
+  #     Right(17).include?(7)          #=> false
+  #     Left('undefined').include?(17) #=> false
+  #
+  # @!method each(&block)
+  #   Performs the given block if this is a +Right+.
+  #   @yieldparam [any] value
+  #   @yieldreturn [void]
+  #   @return [Option] itself
+  #   @example
+  #     Right(17).each do |value|
+  #       puts value
+  #     end #=> prints 17
+  #
+  #     Left('undefined').each do |value|
+  #       puts value
+  #     end #=> does nothing
+  #
+  # @!method map(&block)
+  #   Maps the given block to the value from this +Right+ or
+  #   returns this if this is a +Left+.
+  #   @yieldparam [any] value
+  #   @yieldreturn [any]
+  #   @example
+  #     Right(42).map { |v| v/2 }          #=> Right(21)
+  #     Left('undefined').map { |v| v/2 }  #=> Left('undefined')
+  #
+  # @!method flat_map(&block)
+  #   Returns the given block applied to the value from this +Right+
+  #   or returns this if this is a +Left+.
+  #   @yieldparam [any] value
+  #   @yieldreturn [Option]
+  #   @return [Option]
+  #   @example
+  #     Right(42).flat_map { |v| Right(v/2) }         #=> Right(21)
+  #     Left('undefined').flat_map { |v| Right(v/2) } #=> Left('undefined')
+  #
+  # @!method to_a
+  #   Returns an +Array+ containing the +Right+ value or an
+  #   empty +Array+ if this is a +Left+.
+  #   @return [Array]
+  #   @example
+  #     Right(42).to_a          #=> [21]
+  #     Left('undefined').to_a  #=> []
+  #
+  # @!method to_option
+  #   Returns an +Some+ containing the +Right+ value or a +None+ if
+  #   this is a +Left+.
+  #   @return [Option]
+  #   @example
+  #     Right(42).to_option          #=> Some(21)
+  #     Left('undefined').to_option  #=> None()
+  #
+  # @!method any?(&predicate)
+  #   Returns +false+ if +Left+ or returns the result of the
+  #   application of the given predicate to the +Right+ value.
+  #   @yieldparam [any] value
+  #   @yieldreturn [Boolean]
+  #   @return [Boolean]
+  #   @example
+  #     Right(12).any?( |v| v > 10)         #=> true
+  #     Right(7).any?( |v| v > 10)          #=> false
+  #     Left('undefined').any?( |v| v > 10) #=> false
+  #
+  # -----
+  #
+  # @!method right?
+  #   Returns +true+ if this is a +Right+, +false+ otherwise.
+  #   @note this method is also aliased as +#success?+
+  #   @return [Boolean]
+  #   @example
+  #     Right(42).right?   #=> true
+  #     Left('err').right? #=> false
+  #
+  # @!method left?
+  #   Returns +true+ if this is a +Left+, +false+ otherwise.
+  #   @note this method is also aliased as +#failure?+
+  #   @return [Boolean]
+  #   @example
+  #     Right(42).left?   #=> false
+  #     Left('err').left? #=> true
+  #
+  # @!method select_or_else(default, &predicate)
+  #   Returns +Left+ of the default if the given predicate
+  #   does not hold for the right value, otherwise, returns +Right+.
+  #   @param default [Object, Proc]
+  #   @yieldparam value [Object]
+  #   @yieldreturn [Boolean]
+  #   @return [Either]
+  #   @example
+  #     Right(12).select_or_else(-1, &:even?)       #=> Right(12)
+  #     Right(7).select_or_else(-1, &:even?)        #=> Left(-1)
+  #     Left(12).select_or_else(-1, &:even?)        #=> Left(-1)
+  #     Left(12).select_or_else(-> { -1 }, &:even?) #=> Left(-1)
+  #
+  # @!method select(&predicate)
+  #   Returns +Left+ of value if the given predicate
+  #   does not hold for the right value, otherwise, returns +Right+.
+  #   @yieldparam value [Object]
+  #   @yieldreturn [Boolean]
+  #   @return [Either]
+  #   @example
+  #     Right(12).select(&:even?) #=> Right(12)
+  #     Right(7).select(&:even?)  #=> Left(7)
+  #     Left(12).select(&:even?)  #=> Left(12)
+  #     Left(7).select(&:even?)   #=> Left(7)
+  #
+  # @!method swap
+  #   If this is a +Left+, then return the left value in +Right+ or vice versa.
+  #   @return [Either]
+  #   @example
+  #     Left('left').swap   #=> Right('left')
+  #     Right('right').swap #=> Light('left')
+  #
+  # @!method reduce(reduce_left, reduce_right)
+  #   Applies +reduce_left+ if this is a +Left+ or +reduce_right+ if
+  #   this is a +Right+.
+  #   @param reduce_left [Proc] the Proc to apply if this is a +Left+
+  #   @param reduce_right [Proc] the Proc to apply if this is a +Right+
+  #   @return [any] the results of applying the Proc
+  #   @example
+  #     result = possibly_failing_operation()
+  #     log(
+  #       result.reduce(
+  #         ->(ex) { "Operation failed with #{ex}" },
+  #         ->(v) { "Operation produced value: #{v}" },
+  #       )
   #     )
-  #   )
   #
-  # @example #join_right
-  #   Right(Right(12)).join_right      #=> Right(12)
-  #   Right(Left("flower")).join_right #=> Left("flower")
-  #   Left("flower").join_right        #=> Left("flower")
-  #   Left(Right("flower")).join_right #=> Left(Right("flower"))
   #
-  # @example #join_left
-  #   Left(Right("flower")).join_left #=> Right("flower")
-  #   Left(Left(12)).join_left        #=> Left(12)
-  #   Right("daisy").join_left        #=> Right("daisy")
-  #   Right(Left("daisy")).join_left  #=> Right(Left("daisy"))
+  # @!method join_right
+  #   Joins an +Either+ through +Right+. This method requires
+  #   that the right side of this +Either+ is itself an
+  #   +Either+ type.
+  #   @note This method, and +join_left+, are analogous to +Option#flatten+
+  #   @return [Either]
+  #   @raise [TypeError] if it does not contain +Either+.
+  #   @example
+  #     Right(Right(12)).join_right      #=> Right(12)
+  #     Right(Left("flower")).join_right #=> Left("flower")
+  #     Left("flower").join_right        #=> Left("flower")
+  #     Left(Right("flower")).join_right #=> Left(Right("flower"))
+  #
+  # # @!method join_right
+  #   Joins an +Either+ through +Left+. This method requires
+  #   that the left side of this +Either+ is itself an
+  #   +Either+ type.
+  #   @note This method, and +join_right+, are analogous to +Option#flatten+
+  #   @return [Either]
+  #   @raise [TypeError] if it does not contain +Either+.
+  #   @example
+  #     Left(Right("flower")).join_left #=> Right("flower")
+  #     Left(Left(12)).join_left        #=> Left(12)
+  #     Right("daisy").join_left        #=> Right("daisy")
+  #     Right(Left("daisy")).join_left  #=> Right(Left("daisy"))
   #
   # @see https://github.com/scala/scala/blob/2.12.x/src/library/scala/util/Either.scala
   #
   module Either
     include Dry::Equalizer(:value)
 
+    # @private
     def left_class
       Left
     end
 
+    # @private
     def right_class
       Right
     end
@@ -124,23 +226,16 @@ 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
 
+    # Include this mixin to access convenient factory methods.
+    # @example
+    #   include Fear::Either::Mixin
+    #
+    #   Right('flower') #=> #<Fear::Right value='flower'>
+    #   Left('beaf')    #=> #<Fear::Legt value='beaf'>
+    #
     module Mixin
       # @param [any]
       # @return [Left]

data/lib/fear/failure.rb

@@ -4,6 +4,7 @@ module Fear
     include Dry::Equalizer(:value)
     include RightBiased::Left
 
+    # @param [StandardError]
     def initialize(exception)
       @value = exception
     end
@@ -11,10 +12,17 @@ module Fear
     attr_reader :value
     protected :value
 
+    # @return [Boolean]
     def success?
       false
     end
 
+    # @return [true]
+    def failure?
+      true
+    end
+
+    # @raise
     def get
       fail value
     end
@@ -36,13 +44,9 @@ module Fear
       self
     end
 
-    # Applies the given block to exception.
-    # This is like `flat_map` for the exception.
-    #
     # @yieldparam [Exception]
     # @yieldreturn [Try]
     # @return [Try]
-    #
     def recover_with
       yield(value).tap do |result|
         Utils.assert_type!(result, Success, Failure)
@@ -51,14 +55,18 @@ module Fear
       Failure.new(error)
     end
 
-    # Applies the given block to exception.
-    # This is like map for the exception.
+    # @yieldparam [Exception]
+    # @yieldreturn [any]
     # @return [Try]
-    #
     def recover
       Success.new(yield(value))
     rescue => error
       Failure.new(error)
     end
+
+    # @return [Left]
+    def to_either
+      Left.new(value)
+    end
   end
 end

data/lib/fear/for.rb

@@ -1,14 +1,15 @@
 module Fear
   # This class 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`.
+  # operations - +flat_map+ and +map+. Any class providing them
+  # is supported by +For+.
   #
-  # @example Option
-  #   For(a: Some(2), b: Some(3)) { a * b } #=> Some(6)
-  #   # If one of operands is None, the result is None
-  #   For(a: Some(2), b: None()) { a * b } #=> None()
-  #   For(a: None(), b: Some(2)) { a * b } #=> None()
+  #     For(a: Some(2), b: Some(3)) { a * b } #=> Some(6)
+  #
+  # If one of operands is None, the result is None
+  #
+  #     For(a: Some(2), b: None()) { a * b } #=> None()
+  #     For(a: None(), b: Some(2)) { a * b } #=> None()
   #
   # Lets look at first example:
   #
@@ -71,6 +72,7 @@ module Fear
       @variables = variables
     end
     attr_reader :variables
+    private :variables
 
     def call(&block)
       variable_name_and_monad, *tail = *variables
@@ -92,6 +94,19 @@ module Fear
       end
     end
 
+    # Include this mixin to access convenient factory method for +For+.
+    # @example
+    #   include Fear::For::Mixin
+    #
+    #   For(a: Some(2), b: Some(3)) { a * b }   #=> Some(6)
+    #   For(a: Some(2), b: None()) { a * b }    #=> None()
+    #
+    #   For(a: Right(2), b: Right(3)) { a * b } #=> Right(6)
+    #   For(a: Right(2), b: Left(3)) { a * b }  #=> Left(3)
+    #
+    #   For(a: Success(2), b: Success(3)) { a * b }    #=> Success(3)
+    #   For(a: Success(2), b: Failure(...)) { a * b }  #=> Failure(...)
+    #
     module Mixin
       # @param locals [Hash{Symbol => {#map, #flat_map}}]
       # @return [{#map, #flat_map}]

data/lib/fear/left.rb

@@ -3,46 +3,47 @@ module Fear
     include Either
     include RightBiased::Left
 
-    # Returns `Left` or `default`.
-    #
+    # @return [false]
+    def right?
+      false
+    end
+    alias success? right?
+
+    # @return [true]
+    def left?
+      true
+    end
+    alias failure? left?
+
     # @param default [Proc, any]
     # @return [Either]
-    #
-    def select(default)
+    def select_or_else(default)
       Left.new(Utils.return_or_call_proc(default))
     end
 
+    # @return [Left]
+    def select
+      self
+    end
+
     # @return [Right] value in `Right`
-    #
     def swap
       Right.new(value)
     end
 
-    # @param reduce_left [Proc] the function to apply if this is a `Left`
-    # @return [any] Applies `reduce_left` to the value.
-    #
+    # @param reduce_left [Proc]
+    # @return [any]
     def reduce(reduce_left, _)
       reduce_left.call(value)
     end
 
-    # Joins an `Either` through `Right`.
-    #
     # @return [self]
-    #
     def join_right
       self
     end
 
-    # 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`
-    #
     # @return [Either]
-    # @raise [TypeError] if it does not contain `Either`.
-    #
+    # @raise [TypeError]
     def join_left
       value.tap do |v|
         Utils.assert_type!(v, Either)

data/lib/fear/none.rb

@@ -4,18 +4,27 @@ module Fear
     include Dry::Equalizer()
     include RightBiased::Left
 
-    # Ignores the given block and return self.
-    #
+    # @raise [NoSuchElementError]
+    def get
+      fail NoSuchElementError
+    end
+
+    # @return [nil]
+    def or_nil
+      nil
+    end
+
+    # @return [true]
+    def empty?
+      true
+    end
+
     # @return [None]
-    #
     def select(*)
       self
     end
 
-    # Ignores the given block and return self.
-    #
     # @return [None]
-    #
     def reject(*)
       self
     end