fear 0.9.0 → 1.2.0

data/lib/fear.rb

@@ -1,27 +1,77 @@
-require 'dry-equalizer'
-require 'fear/version'
+# frozen_string_literal: true
+
+require "fear/either_api"
+require "fear/extractor_api"
+require "fear/for_api"
+require "fear/future_api"
+require "fear/option_api"
+require "fear/pattern_matching_api"
+require "fear/try_api"
+require "fear/version"
 
 module Fear
   Error = Class.new(StandardError)
+  public_constant :Error
+
   IllegalStateException = Class.new(Error)
+  public_constant :IllegalStateException
+
+  MatchError = Class.new(Error)
+  public_constant :MatchError
+
   NoSuchElementError = Class.new(Error)
+  public_constant :NoSuchElementError
+
+  PatternSyntaxError = Class.new(Error)
+  public_constant :PatternSyntaxError
+
+  extend EitherApi
+  extend ExtractorApi
+  extend ForApi
+  extend FutureApi
+  extend OptionApi
+  extend PatternMatchingApi
+  extend TryApi
+
+  autoload :EmptyPartialFunction, "fear/empty_partial_function"
+  autoload :PartialFunction, "fear/partial_function"
+  autoload :PartialFunctionClass, "fear/partial_function_class"
+  autoload :PatternMatch, "fear/pattern_match"
+  autoload :Extractor, "fear/extractor"
+
+  autoload :Unit, "fear/unit"
+  autoload :For, "fear/for"
+  autoload :RightBiased, "fear/right_biased"
+  autoload :Utils, "fear/utils"
+
+  autoload :None, "fear/none"
+  autoload :NoneClass, "fear/none"
+  autoload :NonePatternMatch, "fear/none_pattern_match"
+  autoload :Option, "fear/option"
+  autoload :OptionPatternMatch, "fear/option_pattern_match"
+  autoload :Some, "fear/some"
+  autoload :SomePatternMatch, "fear/some_pattern_match"
 
-  autoload :Done, 'fear/done'
-  autoload :For, 'fear/for'
-  autoload :RightBiased, 'fear/right_biased'
-  autoload :Utils, 'fear/utils'
+  autoload :Failure, "fear/failure"
+  autoload :FailurePatternMatch, "fear/failure_pattern_match"
+  autoload :Success, "fear/success"
+  autoload :SuccessPatternMatch, "fear/success_pattern_match"
+  autoload :Try, "fear/try"
+  autoload :TryPatternMatch, "fear/try_pattern_match"
 
-  autoload :Option, 'fear/option'
-  autoload :Some, 'fear/some'
-  autoload :None, 'fear/none'
+  autoload :Either, "fear/either"
+  autoload :EitherPatternMatch, "fear/either_pattern_match"
+  autoload :Left, "fear/left"
+  autoload :LeftPatternMatch, "fear/left_pattern_match"
+  autoload :Right, "fear/right"
+  autoload :RightPatternMatch, "fear/right_pattern_match"
 
-  autoload :Try, 'fear/try'
-  autoload :Success, 'fear/success'
-  autoload :Failure, 'fear/failure'
+  autoload :Await, "fear/await"
+  autoload :Awaitable, "fear/awaitable"
+  autoload :Future, "fear/future"
+  autoload :Promise, "fear/promise"
 
-  autoload :Either, 'fear/either'
-  autoload :Left, 'fear/left'
-  autoload :Right, 'fear/right'
+  autoload :Struct, "fear/struct"
 
   module Mixin
     include Either::Mixin

data/lib/fear/await.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Fear
+  # You're strongly discouraged to use this module since it may lead to deadlocks,
+  # and reduced performance. Although, blocking may be useful in some cases (e.g. in tests)
+  #
+  # @see https://stackoverflow.com/questions/38155159/why-doesnt-scalas-future-have-a-get-getmaxduration-method-forcing-us-to
+  module Await
+    # Blocks until +Fear::Awaitable+ reached completed state and returns itself
+    # or raises +TimeoutError+
+    #
+    # @param awaitable [Fear::Awaitable]
+    # @param at_most [Fixnum] timeout in seconds
+    # @return [Fear::Awaitable]
+    # @raise [Timeout::Error]
+    #
+    module_function def ready(awaitable, at_most)
+      awaitable.__ready__(at_most)
+    end
+
+    # Blocks until +Fear::Awaitable+ reached completed state and returns its value
+    # or raises +TimeoutError+
+    #
+    # @param awaitable [Fear::Awaitable]
+    # @param at_most [Fixnum] timeout in seconds
+    # @return [any]
+    # @raise [Timeout::Error]
+    #
+    module_function def result(awaitable, at_most)
+      awaitable.__result__(at_most)
+    end
+  end
+end

data/lib/fear/awaitable.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Fear
+  # An object which may eventually be completed and awaited using blocking methods.
+  #
+  # @abstract
+  # @api private
+  # @see Fear::Await
+  module Awaitable
+    # Await +completed+ state of this +Awaitable+
+    #
+    # @param _at_most [Fixnum] maximum timeout in seconds
+    # @return [Fear::Awaitable]
+    # @raise [Timeout::Error]
+    def __ready__(_at_most)
+      raise NotImplementedError
+    end
+
+    # Await and return the result of this +Awaitable+
+    #
+    # @param _at_most [Fixnum] maximum timeout in seconds
+    # @return [any]
+    # @raise [Timeout::Error]
+    def __result__(_at_most)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/fear/either.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 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+.
@@ -14,17 +16,20 @@ module Fear
   # @example
   #   in = Readline.readline('Type Either a string or an Int: ', true)
   #   result = begin
-  #     Right(Integer(in))
+  #     Fear.right(Integer(in))
   #   rescue ArgumentError
-  #     Left(in)
+  #     Fear.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
   # operate on. If it is +Left+, operations like +#map+, +#flat_map+, ... return the +Left+ value
@@ -37,21 +42,21 @@ module Fear
   #     @yieldreturn [any]
   #     @return [any]
   #     @example
-  #       Right(42).get_or_else { 24/2 }         #=> 42
-  #       Left('undefined').get_or_else { 24/2 } #=> 12
+  #       Fear.right(42).get_or_else { 24/2 }         #=> 42
+  #       Fear.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
+  #       Fear.right(42).get_or_else(12)         #=> 42
+  #       Fear.left('undefined').get_or_else(12) #=> 12
   #
   # @!method or_else(&alternative)
   #   Returns this +Right+ or the given alternative if this is a +Left+.
   #   @return [Either]
   #   @example
-  #     Right(42).or_else { Right(21) }           #=> Right(42)
-  #     Left('unknown').or_else { Right(21) }     #=> Right(21)
-  #     Left('unknown').or_else { Left('empty') } #=> Left('empty')
+  #     Fear.right(42).or_else { Fear.right(21) }           #=> Fear.right(42)
+  #     Fear.left('unknown').or_else { Fear.right(21) }     #=> Fear.right(21)
+  #     Fear.left('unknown').or_else { Fear.left('empty') } #=> Fear.left('empty')
   #
   # @!method include?(other_value)
   #   Returns +true+ if +Right+ has an element that is equal
@@ -59,9 +64,9 @@ module Fear
   #   @param [any]
   #   @return [Boolean]
   #   @example
-  #     Right(17).include?(17)         #=> true
-  #     Right(17).include?(7)          #=> false
-  #     Left('undefined').include?(17) #=> false
+  #     Fear.right(17).include?(17)         #=> true
+  #     Fear.right(17).include?(7)          #=> false
+  #     Fear.left('undefined').include?(17) #=> false
   #
   # @!method each(&block)
   #   Performs the given block if this is a +Right+.
@@ -69,11 +74,11 @@ module Fear
   #   @yieldreturn [void]
   #   @return [Option] itself
   #   @example
-  #     Right(17).each do |value|
+  #     Fear.right(17).each do |value|
   #       puts value
   #     end #=> prints 17
   #
-  #     Left('undefined').each do |value|
+  #     Fear.left('undefined').each do |value|
   #       puts value
   #     end #=> does nothing
   #
@@ -83,8 +88,8 @@ module Fear
   #   @yieldparam [any] value
   #   @yieldreturn [any]
   #   @example
-  #     Right(42).map { |v| v/2 }          #=> Right(21)
-  #     Left('undefined').map { |v| v/2 }  #=> Left('undefined')
+  #     Fear.right(42).map { |v| v/2 }          #=> Fear.right(21)
+  #     Fear.left('undefined').map { |v| v/2 }  #=> Fear.left('undefined')
   #
   # @!method flat_map(&block)
   #   Returns the given block applied to the value from this +Right+
@@ -93,24 +98,16 @@ module Fear
   #   @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  #=> []
+  #     Fear.right(42).flat_map { |v| Fear.right(v/2) }         #=> Fear.right(21)
+  #     Fear.left('undefined').flat_map { |v| Fear.right(v/2) } #=> Fear.left('undefined')
   #
   # @!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()
+  #     Fear.right(42).to_option          #=> Fear.some(21)
+  #     Fear.left('undefined').to_option  #=> Fear.none()
   #
   # @!method any?(&predicate)
   #   Returns +false+ if +Left+ or returns the result of the
@@ -119,9 +116,9 @@ module Fear
   #   @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
+  #     Fear.right(12).any?( |v| v > 10)         #=> true
+  #     Fear.right(7).any?( |v| v > 10)          #=> false
+  #     Fear.left('undefined').any?( |v| v > 10) #=> false
   #
   # -----
   #
@@ -130,16 +127,16 @@ module Fear
   #   @note this method is also aliased as +#success?+
   #   @return [Boolean]
   #   @example
-  #     Right(42).right?   #=> true
-  #     Left('err').right? #=> false
+  #     Fear.right(42).right?   #=> true
+  #     Fear.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
+  #     Fear.right(42).left?   #=> false
+  #     Fear.left('err').left? #=> true
   #
   # @!method select_or_else(default, &predicate)
   #   Returns +Left+ of the default if the given predicate
@@ -149,10 +146,10 @@ module Fear
   #   @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(12)
-  #     Left(12).select_or_else(-> { -1 }, &:even?) #=> Left(12)
+  #     Fear.right(12).select_or_else(-1, &:even?)       #=> Fear.right(12)
+  #     Fear.right(7).select_or_else(-1, &:even?)        #=> Fear.left(-1)
+  #     Fear.left(12).select_or_else(-1, &:even?)        #=> Fear.left(12)
+  #     Fear.left(12).select_or_else(-> { -1 }, &:even?) #=> Fear.left(12)
   #
   # @!method select(&predicate)
   #   Returns +Left+ of value if the given predicate
@@ -161,10 +158,10 @@ module Fear
   #   @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)
+  #     Fear.right(12).select(&:even?) #=> Fear.right(12)
+  #     Fear.right(7).select(&:even?)  #=> Fear.left(7)
+  #     Fear.left(12).select(&:even?)  #=> Fear.left(12)
+  #     Fear.left(7).select(&:even?)   #=> Fear.left(7)
   #
   # @!method reject(&predicate)
   #   Returns +Left+ of value if the given predicate holds for the
@@ -173,17 +170,17 @@ module Fear
   #   @yieldreturn [Boolean]
   #   @return [Either]
   #   @example
-  #     Right(12).reject(&:even?) #=> Left(12)
-  #     Right(7).reject(&:even?)  #=> Right(7)
-  #     Left(12).reject(&:even?)  #=> Left(12)
-  #     Left(7).reject(&:even?)   #=> Left(7)
+  #     Fear.right(12).reject(&:even?) #=> Fear.left(12)
+  #     Fear.right(7).reject(&:even?)  #=> Fear.right(7)
+  #     Fear.left(12).reject(&:even?)  #=> Fear.left(12)
+  #     Fear.left(7).reject(&:even?)   #=> Fear.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')
+  #     Fear.left('left').swap   #=> Fear.right('left')
+  #     Fear.right('right').swap #=> Fear.left('left')
   #
   # @!method reduce(reduce_left, reduce_right)
   #   Applies +reduce_left+ if this is a +Left+ or +reduce_right+ if
@@ -209,10 +206,10 @@ module Fear
   #   @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"))
+  #     Fear.right(Fear.right(12)).join_right      #=> Fear.right(12)
+  #     Fear.right(Fear.left("flower")).join_right #=> Fear.left("flower")
+  #     Fear.left("flower").join_right             #=> Fear.left("flower")
+  #     Fear.left(Fear.right("flower")).join_right #=> Fear.left(Fear.right("flower"))
   #
   # @!method join_right
   #   Joins an +Either+ through +Left+. This method requires
@@ -222,16 +219,31 @@ module Fear
   #   @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"))
+  #     Fear.left(Fear.right("flower")).join_left   #=> Fear.right("flower")
+  #     Fear.left(Fear.left(12)).join_left          #=> Fear.left(12)
+  #     Fear.right("daisy").join_left               #=> Fear.right("daisy")
+  #     Fear.right(Fear.left("daisy")).join_left    #=> Fear.right(Fear.left("daisy"))
+  #
+  # @!method match(&matcher)
+  #   Pattern match against this +Either+
+  #   @yield matcher [Fear::EitherPatternMatch]
+  #   @example
+  #     either.match do |m|
+  #       m.right(Integer) do |x|
+  #        x * 2
+  #       end
+  #
+  #       m.right(String) do |x|
+  #         x.to_i * 2
+  #       end
+  #
+  #       m.left { |x| x }
+  #       m.else { 'something unexpected' }
+  #     end
   #
   # @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
@@ -249,6 +261,48 @@ module Fear
     attr_reader :value
     protected :value
 
+    # @param other [Any]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(self.class) && value == other.value
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} value=#{value.inspect}>"
+    end
+
+    # @return [String]
+    alias to_s inspect
+
+    # @return [<any>]
+    def deconstruct
+      [value]
+    end
+
+    class << self
+      # Build pattern matcher to be used later, despite off
+      # +Either#match+ method, id doesn't apply matcher immanently,
+      # but build it instead. Unusually in sake of efficiency it's better
+      # to statically build matcher and reuse it later.
+      #
+      # @example
+      #   matcher =
+      #     Either.matcher do |m|
+      #       m.right(Integer, ->(x) { x > 2 }) { |x| x * 2 }
+      #       m.right(String) { |x| x.to_i * 2 }
+      #       m.left(String) { :err }
+      #       m.else { 'error '}
+      #     end
+      #   matcher.call(Fear.right(42))
+      #
+      # @yieldparam [Fear::EitherPatternMatch]
+      # @return [Fear::PartialFunction]
+      def matcher(&matcher)
+        EitherPatternMatch.new(&matcher)
+      end
+    end
+
     # Include this mixin to access convenient factory methods.
     # @example
     #   include Fear::Either::Mixin
@@ -257,16 +311,22 @@ module Fear
     #   Left('beaf')    #=> #<Fear::Legt value='beaf'>
     #
     module Mixin
-      # @param [any]
-      # @return [Left]
+      # @param value [any]
+      # @return [Fear::Left]
+      # @example
+      #   Left(42) #=> #<Fear::Left value=42>
+      #
       def Left(value)
-        Left.new(value)
+        Fear.left(value)
       end
 
-      # @param [any]
-      # @return [Right]
+      # @param value [any]
+      # @return [Fear::Right]
+      # @example
+      #   Right(42) #=> #<Fear::Right value=42>
+      #
       def Right(value)
-        Right.new(value)
+        Fear.right(value)
       end
     end
   end