fear 0.10.0 → 0.11.0

data/lib/fear/partial_function.rb

@@ -0,0 +1,171 @@
+module Fear
+  # A partial function is a unary function defined on subset of all possible inputs.
+  # The method +defined_at?+ allows to test dynamically if an arg is in
+  # the domain of the function.
+  #
+  # Even if +defined_at?+ returns true for given arg, calling +call+ may
+  # still throw an exception, so the following code is legal:
+  #
+  #  @example
+  #    Fear.case(->(_) { true }) { 1/0 }
+  #
+  # It is the responsibility of the caller to call +defined_at?+ before
+  # calling +call+, because if +defined_at?+ is false, it is not guaranteed
+  # +call+ will throw an exception to indicate an error guard. If an
+  # exception is not thrown, evaluation may result in an arbitrary arg.
+  #
+  # The main distinction between +PartialFunction+ and +Proc+ is
+  # that the user of a +PartialFunction+ may choose to do something different
+  # with input that is declared to be outside its domain. For example:
+  #
+  # @example
+  #   sample = 1...10
+  #
+  #   is_even = Fear.case(->(arg) { arg % 2 == 0}) do |arg|
+  #     "#{arg} is even"
+  #   end
+  #
+  #   is_odd = Fear.case(->(arg) { arg % 2 == 1}) do |arg|
+  #     "#{arg} is odd"
+  #   end
+  #
+  # The method or_else allows chaining another partial function to handle
+  # input outside the declared domain
+  #
+  #    numbers = sample.map(is_even.or_else(is_odd).to_proc)
+  #
+  # @see https://github.com/scala/scala/commit/5050915eb620af3aa43d6ddaae6bbb83ad74900d
+  module PartialFunction
+    autoload :AndThen, 'fear/partial_function/and_then'
+    autoload :Any, 'fear/partial_function/any'
+    autoload :Combined, 'fear/partial_function/combined'
+    autoload :EMPTY, 'fear/partial_function/empty'
+    autoload :Guard, 'fear/partial_function/guard'
+    autoload :Lifted, 'fear/partial_function/lifted'
+    autoload :OrElse, 'fear/partial_function/or_else'
+
+    # @param condition [#call] describes the domain of partial function
+    # @param function [Proc] function definition
+    def initialize(condition, &function)
+      @condition = condition
+      @function = function
+    end
+    attr_reader :condition, :function
+    private :condition
+    private :function
+
+    # Checks if a value is contained in the function's domain.
+    #
+    # @param arg [any]
+    # @return [Boolean]
+    def defined_at?(arg)
+      condition === arg
+    end
+
+    # @!method call(arg)
+    # @param arg [any]
+    # @return [any] Calls this partial function with the given argument when it
+    #   is contained in the function domain.
+    # @raise [MatchError] when this partial function is not defined.
+    # @abstract
+
+    # Converts this partial function to other
+    #
+    # @return [Proc]
+    def to_proc
+      proc { |arg| call(arg) }
+    end
+
+    # Calls this partial function with the given argument when it is contained in the function domain.
+    # Calls fallback function where this partial function is not defined.
+    #
+    # @param arg [any]
+    # @yield [arg] if partial function not defined for this +arg+
+    #
+    # @note that expression +pf.call_or_else(arg, &fallback)+ is equivalent to
+    #   +pf.defined_at?(arg) ? pf.(arg) : fallback.(arg)+
+    #   except that +call_or_else+ method can be implemented more efficiently to avoid calling +defined_at?+ twice.
+    #
+    def call_or_else(arg)
+      if defined_at?(arg)
+        call(arg)
+      else
+        yield arg
+      end
+    end
+
+    # Composes this partial function with a fallback partial function which
+    # gets applied where this partial function is not defined.
+    #
+    # @param other [PartialFunction]
+    # @return [PartialFunction] a partial function which has as domain the union of the domains
+    #   of this partial function and +other+.
+    def or_else(other)
+      OrElse.new(self, other)
+    end
+
+    # @see or_else
+    def |(other)
+      or_else(other)
+    end
+
+    # Composes this partial function with a fallback partial function (or Proc) which
+    # gets applied where this partial function is not defined.
+    #
+    # @overload and_then(other)
+    #   @param other [Fear::PartialFunction]
+    #   @return [Fear::PartialFunction] a partial function with the same domain as this partial function, which maps
+    #     argument +x+ to +other.(self.call(x))+.
+    #   @note calling +#defined_at?+ on the resulting partial function may call the first
+    #     partial function and execute its side effect. It is highly recommended to call +#call_or_else+
+    #     instead of +#defined_at?+/+#call+ for efficiency.
+    # @overload and_then(other)
+    #   @param other [Proc]
+    #   @return [Fear::PartialFunction] a partial function with the same domain as this partial function, which maps
+    #     argument +x+ to +other.(self.call(x))+.
+    # @overload and_then(&other)
+    #   @param other [Proc]
+    #   @return [Fear::PartialFunction]
+    #
+    def and_then(other = Utils::UNDEFINED, &block)
+      Utils.with_block_or_argument('Fear::PartialFunction#and_then', other, block) do |fun|
+        if fun.is_a?(Fear::PartialFunction)
+          Combined.new(self, fun)
+        else
+          AndThen.new(self, &fun)
+        end
+      end
+    end
+
+    # @see and_then
+    def &(other)
+      and_then(other)
+    end
+
+    # Turns this partial function in Proc-like object, returning +Option+
+    # @return [#call]
+    def lift
+      Lifted.new(self)
+    end
+
+    class << self
+      # Creates partial function guarded by several condition.
+      # All guards should match.
+      # @param guards [<#===, symbol>]
+      # @param function [Proc]
+      # @return [Fear::PartialFunction]
+      def and(*guards, &function)
+        PartialFunctionClass.new(Guard.and(guards), &function)
+      end
+
+      # Creates partial function guarded by several condition.
+      # Any condition should match.
+      # @param guards [<#===, symbol>]
+      # @param function [Proc]
+      # @return [Fear::PartialFunction]
+      def or(*guards, &function)
+        PartialFunctionClass.new(Guard.or(guards), &function)
+      end
+    end
+  end
+end

data/lib/fear/partial_function_class.rb

@@ -0,0 +1,26 @@
+module Fear
+  # @api private
+  class PartialFunctionClass
+    include PartialFunction
+
+    # @param arg [any]
+    # @return [any] Calls this partial function with the given argument when it
+    #   is contained in the function domain.
+    # @raise [MatchError] when this partial function is not defined.
+    def call(arg)
+      call_or_else(arg, &PartialFunction::EMPTY)
+    end
+
+    # @param arg [any]
+    # @yield [arg] if function not defined
+    def call_or_else(arg)
+      if defined_at?(arg)
+        function.call(arg)
+      else
+        yield arg
+      end
+    end
+  end
+
+  private_constant :PartialFunctionClass
+end

data/lib/fear/pattern_match.rb

@@ -0,0 +1,102 @@
+module Fear
+  # Pattern match builder. Provides DSL for building pattern matcher
+  # Pattern match is just a combination of partial functions
+  #
+  #     matcher = Fear.matcher do |m|
+  #       m.case(Integer) { |x| x * 2 }
+  #       m.case(String) { |x| x.to_i(10) * 2 }
+  #     end
+  #     matcher.is_a?(Fear::PartialFunction) #=> true
+  #     matcher.defined_at?(4) #=> true
+  #     matcher.defined_at?('4') #=> true
+  #     matcher.defined_at?(nil) #=> false
+  #
+  # The previous example is the same as:
+  #
+  #     Fear.case(Integer) { |x| x * ) }
+  #       .or_else(
+  #         Fear.case(String) { |x| x.to_i(10) * 2 }
+  #       )
+  #
+  # You can provide +else+ branch, so partial function will be defined
+  # on any input:
+  #
+  #     matcher = Fear.matcher do |m|
+  #       m.else { 'Match' }
+  #     end
+  #     matcher.call(42) #=> 'Match'
+  #
+  # @see Fear.matcher public interface for building matchers
+  # @api Fear
+  # @note Use this class only to build custom pattern match classes. See +Fear::OptionPatternMatch+ as an example.
+  class PatternMatch
+    class << self
+      alias __new__ new
+
+      # @return [Fear::PartialFunction]
+      def new
+        builder = __new__(PartialFunction::EMPTY)
+        yield builder
+        builder.result
+      end
+
+      # Creates anonymous module to add `#mathing` behaviour to a class
+      #
+      # @example
+      #   class User
+      #     include Fear::PatternMatch.mixin
+      #   end
+      #
+      #   user.match do |m\
+      #     m.case(:admin?) { |u| ... }
+      #     m.else { |u| ... }
+      #   end
+      #
+      # @param as [Symbol, String] (:match) method name
+      # @return [Module]
+      def mixin(as: :match)
+        matcher_class = self
+
+        Module.new do
+          define_method(as) do |&matchers|
+            matcher_class.new(&matchers).call(self)
+          end
+        end
+      end
+    end
+
+    # @param result [Fear::EmptyPartialFunction]
+    def initialize(result)
+      @result = result
+    end
+    attr_accessor :result
+    private :result=
+
+    # @see Fear::PartialFunction#else
+    def else(&effect)
+      or_else(Fear.case(&effect))
+    end
+
+    # This method is syntactic sugar for `PartialFunction#or_else`, but rather than passing
+    # another partial function as an argument, you pass arguments to build such partial function.
+    # @example This two examples produces the same result
+    #   other = Fear.case(Integer) { |x| x * 2 }
+    #   this.or_else(other)
+    #
+    #   this.case(Integer) { |x| x * 2 }
+    #
+    # @param guards [<#===>]
+    # @param effect [Proc]
+    # @return [Fear::PartialFunction]
+    # @see #or_else for details
+    def case(*guards, &effect)
+      or_else(Fear.case(*guards, &effect))
+    end
+
+    # @see Fear::PartialFunction#or_else
+    def or_else(other)
+      self.result = result.or_else(other)
+      self
+    end
+  end
+end

data/lib/fear/pattern_matching_api.rb

@@ -0,0 +1,110 @@
+module Fear
+  # @api private
+  module PatternMatchingApi
+    # Creates pattern match. Use `case` method to
+    # define matching branches. Branch consist of a
+    # guardian, which describes domain of the
+    # branch and function to apply to matching value.
+    #
+    # @example This mather apply different functions to Integers and to Strings
+    #   matcher = Fear.matcher do |m|
+    #     m.case(Integer) { |n| "#{n} is a number" }
+    #     m.case(String) { |n| "#{n} is a string" }
+    #   end
+    #
+    #   matcher.(42) #=> "42 is a number"
+    #   matcher.("Foo") #=> "Foo is a string"
+    #
+    # if you pass something other than Integer or string, it will raise `Fear::MatchError`:
+    #
+    #     matcher.(10..20) #=> raises Fear::MatchError
+    #
+    # to avoid raising `MatchError`, you can use `else` method. It defines a branch matching
+    # on any value.
+    #
+    #     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.(10..20) #=> "10..20 is a Range"
+    #
+    # You can use anything as a guardian if it responds to `#===` method:
+    #
+    #     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
+    #
+    #     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
+    #
+    #     m.case(Integer, :even?) { |x| ... }
+    #     m.case(Integer, :odd?) { |x| ... }
+    #
+    # Since matcher returns +Fear::PartialFunction+, you can combine matchers using
+    # partial function API:
+    #
+    #     failures = Fear.matcher do |m|
+    #       m.case('not_found') { ... }
+    #       m.case('network_error') { ... }
+    #     end
+    #
+    #     success = Fear.matcher do |m|
+    #       m.case('ok') { ... }
+    #     end
+    #
+    #     response = failures.or_else(success)
+    #
+    # @yieldparam matcher [Fear::PartialFunction]
+    # @return [Fear::PartialFunction]
+    # @see Fear::OptionPatternMatch for example of custom matcher
+    def matcher(&block)
+      PatternMatch.new(&block)
+    end
+
+    # Pattern match against given value
+    #
+    # @example
+    #   Fear.match(42) do |m|
+    #     m.case(Integer, :even?) { |n| "#{n} is even number" }
+    #     m.case(Integer, :odd?) { |n| "#{n} is odd number" }
+    #     m.case(Strings) { |n| "#{n} is a string" }
+    #     m.else { 'unknown' }
+    #   end #=> "42 is even number"
+    #
+    # @param value [any]
+    # @yieldparam matcher [Fear::PartialFunction]
+    # @return [any]
+    def match(value, &block)
+      matcher(&block).call(value)
+    end
+
+    # Creates partial function defined on domain described with guards
+    #
+    # @example
+    #   pf = Fear.case(Integer) { |x| x / 2 }
+    #   pf.defined_at?(4) #=> true
+    #   pf.defined_at?('Foo') #=> false
+    #
+    # @example multiple guards combined using logical "and"
+    #   pf = Fear.case(Integer, :even?) { |x| x / 2 }
+    #   pf.defined_at?(4) #=> true
+    #   pf.defined_at?(3) #=> false
+    #
+    # @note to make more complex matches, you are encouraged to use Qo gem.
+    # @see Qo https://github.com/baweaver/qo
+    # @example
+    #   Fear.case(Qo[age: 20..30]) { |_| 'old enough' }
+    #
+    # @param guards [<#===, symbol>]
+    # @param function [Proc]
+    # @return [Fear::PartialFunction]
+    def case(*guards, &function)
+      PartialFunction.and(*guards, &function)
+    end
+  end
+end

data/lib/fear/right.rb

@@ -2,6 +2,12 @@ module Fear
   class Right
     include Either
     include RightBiased::Right
+    include RightPatternMatch.mixin
+
+    # @api private
+    def right_value
+      value
+    end
 
     # @return [true]
     def right?
@@ -50,7 +56,7 @@ module Fear
 
     # @param reduce_right [Proc]
     # @return [any]
-    def reduce(_, reduce_right)
+    def reduce(_reduce_left, reduce_right)
       reduce_right.call(value)
     end
 

data/lib/fear/right_biased.rb

@@ -85,11 +85,6 @@ module Fear
         yield(value)
       end
 
-      # @return [Array] containing value
-      def to_a
-        [value]
-      end
-
       # @return [Option] containing value
       def to_option
         Some.new(value)
@@ -136,7 +131,7 @@ module Fear
       # @param [any]
       # @return [false]
       #
-      def include?(_)
+      def include?(_value)
         false
       end
 
@@ -164,14 +159,9 @@ module Fear
         self
       end
 
-      # @return [Array] empty array
-      def to_a
-        []
-      end
-
       # @return [None]
       def to_option
-        None.new
+        None
       end
 
       # @return [false]

data/lib/fear/right_pattern_match.rb

@@ -0,0 +1,9 @@
+module Fear
+  # @api private
+  class RightPatternMatch < EitherPatternMatch
+    def left(*)
+      self
+    end
+    alias failure left
+  end
+end

data/lib/fear/some.rb

@@ -3,10 +3,13 @@ module Fear
     include Option
     include Dry::Equalizer(:get)
     include RightBiased::Right
+    include SomePatternMatch.mixin
 
     attr_reader :value
     protected :value
 
+    # FIXME: nice inspect
+
     def initialize(value)
       @value = value
     end
@@ -31,14 +34,14 @@ module Fear
       if yield(value)
         self
       else
-        None.new
+        None
       end
     end
 
     # @return [Option]
     def reject
       if yield(value)
-        None.new
+        None
       else
         self
       end

data/lib/fear/some_pattern_match.rb

@@ -0,0 +1,11 @@
+module Fear
+  # @api private
+  class SomePatternMatch < OptionPatternMatch
+    # @return [Fear::OptionPatternMatch]
+    def none
+      self
+    end
+  end
+
+  private_constant :SomePatternMatch
+end

data/lib/fear/success.rb

@@ -3,6 +3,7 @@ module Fear
     include Try
     include Dry::Equalizer(:value)
     include RightBiased::Right
+    include SuccessPatternMatch.mixin
 
     attr_reader :value
     protected :value
@@ -48,9 +49,9 @@ module Fear
       if yield(value)
         self
       else
-        fail NoSuchElementError, "Predicate does not hold for `#{value}`"
+        raise NoSuchElementError, "Predicate does not hold for `#{value}`"
       end
-    rescue => error
+    rescue StandardError => error
       Failure.new(error)
     end
 
@@ -67,14 +68,14 @@ module Fear
     # @return [Try]
     def map
       super
-    rescue => error
+    rescue StandardError => error
       Failure.new(error)
     end
 
     # @return [Try]
     def flat_map
       super
-    rescue => error
+    rescue StandardError => error
       Failure.new(error)
     end
 

data/lib/fear/success_pattern_match.rb

@@ -0,0 +1,10 @@
+module Fear
+  # @api private
+  class SuccessPatternMatch < Fear::TryPatternMatch
+    # @param conditions [<#==>]
+    # @return [Fear::TryPatternMatch]
+    def failure(*_conditions)
+      self
+    end
+  end
+end

data/lib/fear/try.rb

@@ -15,11 +15,19 @@ module Fear
   #   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
   #
   # An important property of +Try+ shown in the above example is its
@@ -99,14 +107,6 @@ module Fear
   #     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+.
@@ -186,7 +186,7 @@ module Fear
   #       #=> 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)
   #
   # @!method recover(&block)
@@ -199,7 +199,7 @@ module Fear
   #       #=> 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)
   #
   # @!method to_either
@@ -210,6 +210,23 @@ module Fear
   #     Success(42).to_either                #=> Right(42)
   #     Failure(ArgumentError.new).to_either #=> Left(ArgumentError.new)
   #
+  # @!method match(&matcher)
+  #   Pattern match against this +Try+
+  #   @yield matcher [Fear::TryPatternMatch]
+  #   @example
+  #     Try { ... }.match do |m|
+  #       m.success(Integer) do |x|
+  #        x * 2
+  #       end
+  #
+  #       m.success(String) do |x|
+  #         x.to_i * 2
+  #       end
+  #
+  #       m.failure(ZeroDivisionError) { 'not allowed to divide by 0' }
+  #       m.else { 'something unexpected' }
+  #     end
+  #
   # @author based on Twitter's original implementation.
   # @see https://github.com/scala/scala/blob/2.11.x/src/library/scala/util/Try.scala
   #
@@ -224,6 +241,29 @@ module Fear
       Success
     end
 
+    class << self
+      # Build pattern matcher to be used later, despite off
+      # +Try#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 =
+      #     Try.matcher do |m|
+      #       m.success(Integer, ->(x) { x > 2 }) { |x| x * 2 }
+      #       m.success(String) { |x| x.to_i * 2 }
+      #       m.failure(ActiveRecord::RecordNotFound) { :err }
+      #       m.else { 'error '}
+      #     end
+      #   matcher.call(try)
+      #
+      # @yieldparam [Fear::TryPatternMatch]
+      # @return [Fear::PartialFunction]
+      def matcher(&matcher)
+        TryPatternMatch.new(&matcher)
+      end
+    end
+
     # Include this mixin to access convenient factory methods.
     # @example
     #   include Fear::Try::Mixin
@@ -240,7 +280,7 @@ module Fear
       #
       def Try
         Success.new(yield)
-      rescue => error
+      rescue StandardError => error
         Failure.new(error)
       end