fear 0.9.0 → 1.2.0

data/lib/fear/option_api.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Fear
+  module OptionApi
+    # An +Option+ factory which creates +Some+ if the argument is
+    # not +nil+, and +None+ if it is +nil+.
+    # @param value [any]
+    # @return [Fear::Some, Fear::None]
+    #
+    # @example
+    #   Fear.option(nil) #=> #<Fear::None>
+    #   Fear.option(17) #=> #<Fear::Some get=17>
+    #
+    def option(value)
+      if value.nil?
+        none
+      else
+        some(value)
+      end
+    end
+
+    # @return [Fear::None]
+    # @example
+    #   Fear.none #=> #<Fear::None>
+    #
+    def none
+      Fear::None
+    end
+
+    # @param value [any]
+    # @return [Fear::Some]
+    # @example
+    #   Fear.some(17) #=> #<Fear::Some get=17>
+    #   Fear.some(nil) #=> #<Fear::Some get=nil>
+    #
+    def some(value)
+      Fear::Some.new(value)
+    end
+  end
+end

data/lib/fear/option_pattern_match.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Fear
+  # Option pattern matcher
+  #
+  # @example
+  #   pattern_match =
+  #     OptionPatternMatch.new
+  #       .some(Integer) { |x| x * 2 }
+  #       .some(String) { |x| x.to_i * 2 }
+  #       .none { 'NaN' }
+  #       .else { 'error '}
+  #
+  #   pattern_match.call(42) => 'NaN'
+  #
+  #  @example the same matcher may be defined using block syntax
+  #    OptionPatternMatch.new do |m|
+  #       m.some(Integer) { |x| x * 2 }
+  #       m.some(String) { |x| x.to_i * 2 }
+  #       m.none { 'NaN' }
+  #       m.else { 'error '}
+  #    end
+  #
+  # @note it has two optimized subclasses +Fear::SomePatternMatch+ and +Fear::NonePatternMatch+
+  # @api private
+  class OptionPatternMatch < Fear::PatternMatch
+    GET_METHOD = :get.to_proc
+    private_constant :GET_METHOD
+
+    # Match against Some
+    #
+    # @param conditions [<#==>]
+    # @return [Fear::OptionPatternMatch]
+    def some(*conditions, &effect)
+      branch = Fear.case(Fear::Some, &GET_METHOD).and_then(Fear.case(*conditions, &effect))
+      or_else(branch)
+    end
+
+    # Match against None
+    #
+    # @param effect [Proc]
+    # @return [Fear::OptionPatternMatch]
+    def none(&effect)
+      branch = Fear.case(Fear::None, &effect)
+      or_else(branch)
+    end
+  end
+end

data/lib/fear/partial_function.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+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
+  # @!method condition
+  #   describes the domain of partial function
+  #   @return [#===]
+  #   @abstract
+  # @!method function
+  #   @return [#call]
+  #   @abstract
+  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"
+
+    # 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+.
+    # @example
+    #   handle_even = Fear.case(:even?.to_proc) { |x| "#{x} is even" }
+    #   handle_odd = Fear.case(:odd?.to_proc) { |x| "#{x} is odd" }
+    #   handle_even_or_odd = handle_even.or_else(odd)
+    #   handle_even_or_odd.(42) #=> 42 is even
+    #   handle_even_or_odd.(42) #=> 21 is odd
+    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 [<#===>]
+      # @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 [<#===>]
+      # @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/and_then.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Fear
+  module PartialFunction
+    # Composite function produced by +PartialFunction#and_then+ method
+    # @api private
+    class AndThen
+      include PartialFunction
+
+      # @param partial_function [Fear::PartialFunction]
+      # @param function [Proc]
+      def initialize(partial_function, &function)
+        @partial_function = partial_function
+        @function = function
+      end
+      # @!attribute partial_function
+      #   @return [Fear::PartialFunction]
+      # @!attribute function
+      #   @return [Proc]
+      attr_reader :partial_function
+      attr_reader :function
+      private :partial_function
+      private :function
+
+      # @param arg [any]
+      # @return [any ]
+      def call(arg)
+        function.(partial_function.(arg))
+      end
+
+      # @param arg [any]
+      # @return [Boolean]
+      def defined_at?(arg)
+        partial_function.defined_at?(arg)
+      end
+
+      # @param arg [any]
+      # @yield [arg]
+      # @return [any]
+      def call_or_else(arg)
+        result = partial_function.call_or_else(arg) do
+          return yield(arg)
+        end
+        function.(result)
+      end
+    end
+
+    private_constant :AndThen
+  end
+end

data/lib/fear/partial_function/any.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Fear
+  module PartialFunction
+    # Any is an object which is always truthy
+    # @api private
+    class Any
+      class << self
+        # @param _other [any]
+        # @return [true]
+        def ===(_other)
+          true
+        end
+
+        # @param _other [any]
+        # @return [true]
+        def ==(_other)
+          true
+        end
+
+        # @return [Proc]
+        def to_proc
+          proc { true }
+        end
+      end
+    end
+  end
+end

data/lib/fear/partial_function/combined.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Fear
+  module PartialFunction
+    # Composite function produced by +PartialFunction#and_then+ method
+    # @api private
+    class Combined
+      include PartialFunction
+
+      # @param f1 [Fear::PartialFunction]
+      # @param f2 [Fear::PartialFunction]
+      def initialize(f1, f2)
+        @f1 = f1
+        @f2 = f2
+      end
+      # @!attribute f1
+      #   @return [Fear::PartialFunction]
+      # @!attribute f2
+      #   @return [Fear::PartialFunction]
+      attr_reader :f1, :f2
+      private :f1
+      private :f2
+
+      # @param arg [any]
+      # @return [any ]
+      def call(arg)
+        f2.(f1.(arg))
+      end
+
+      alias === call
+      alias [] call
+
+      # @param arg [any]
+      # @yieldparam arg [any]
+      # @return [any]
+      def call_or_else(arg)
+        result = f1.call_or_else(arg) { return yield(arg) }
+        f2.call_or_else(result) { |_| return yield(arg) }
+      end
+
+      # @param arg [any]
+      # @return [Boolean]
+      def defined_at?(arg)
+        result = f1.call_or_else(arg) do
+          return false
+        end
+        f2.defined_at?(result)
+      end
+    end
+
+    private_constant :AndThen
+  end
+end

data/lib/fear/partial_function/empty.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Fear
+  module PartialFunction
+    EMPTY = EmptyPartialFunction.new
+    EMPTY.freeze
+
+    public_constant :EMPTY
+  end
+end

data/lib/fear/partial_function/guard.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Fear
+  module PartialFunction
+    # Guard represents PartialFunction guardian
+    #
+    # @api private
+    class Guard
+      autoload :And, "fear/partial_function/guard/and"
+      autoload :And3, "fear/partial_function/guard/and3"
+      autoload :Or, "fear/partial_function/guard/or"
+
+      class << self
+        # Optimized version for combination of two guardians
+        # Two guarding is a very common situation. For example checking for Some, and checking
+        # a value withing container.
+        #
+        def and2(c1, c2)
+          Guard::And.new(c1, c2)
+        end
+
+        def and3(c1, c2, c3)
+          Guard::And3.new(c1, c2, c3)
+        end
+
+        def and1(c)
+          c
+        end
+
+        # @param conditions [<#===>]
+        # @return [Fear::PartialFunction::Guard]
+        def and(conditions)
+          case conditions.size
+          when 1 then and1(*conditions)
+          when 2 then and2(*conditions)
+          when 3 then and3(*conditions)
+          when 0 then Any
+          else
+            head, *tail = conditions
+            tail.reduce(new(head)) { |acc, condition| acc.and(new(condition)) }
+          end
+        end
+
+        # @param conditions [<#===>]
+        # @return [Fear::PartialFunction::Guard]
+        def or(conditions)
+          return Any if conditions.empty?
+
+          head, *tail = conditions
+          tail.reduce(new(head)) { |acc, condition| acc.or(new(condition)) }
+        end
+      end
+
+      # @param condition [#===]
+      def initialize(condition)
+        @condition = condition
+      end
+      attr_reader :condition
+      private :condition
+
+      # @param other [Fear::PartialFunction::Guard]
+      # @return [Fear::PartialFunction::Guard]
+      def and(other)
+        Guard::And.new(condition, other)
+      end
+
+      # @param other [Fear::PartialFunction::Guard]
+      # @return [Fear::PartialFunction::Guard]
+      def or(other)
+        Guard::Or.new(condition, other)
+      end
+
+      # @param arg [any]
+      # @return [Boolean]
+      def ===(arg)
+        condition === arg
+      end
+    end
+  end
+end