fear 0.9.0 → 1.2.0

data/lib/fear/partial_function/guard/and.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Fear
+  module PartialFunction
+    class Guard
+      # @api private
+      class And < Guard
+        # @param c1 [Fear::PartialFunction::Guard]
+        # @param c2 [Fear::PartialFunction::Guard]
+        def initialize(c1, c2)
+          @c1 = c1
+          @c2 = c2
+        end
+        attr_reader :c1, :c2
+        private :c1
+        private :c2
+
+        # @param other [Fear::PartialFunction::Guard]
+        # @return [Fear::PartialFunction::Guard]
+        def and(other)
+          Guard::And.new(self, other)
+        end
+
+        # @param other [Fear::PartialFunction::Guard]
+        # @return [Fear::PartialFunction::Guard]
+        def or(other)
+          Guard::Or.new(self, other)
+        end
+
+        # @param arg [any]
+        # @return [Boolean]
+        def ===(arg)
+          (c1 === arg) && (c2 === arg)
+        end
+      end
+    end
+  end
+end

data/lib/fear/partial_function/guard/and3.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Fear
+  module PartialFunction
+    class Guard
+      # @api private
+      class And3 < Guard
+        # @param c1 [#===]
+        # @param c2 [#===]
+        # @param c3 [#===]
+        def initialize(c1, c2, c3)
+          @c1 = c1
+          @c2 = c2
+          @c3 = c3
+        end
+        attr_reader :c1, :c2, :c3
+        private :c1
+        private :c2
+        private :c3
+
+        # @param other [Fear::PartialFunction::Guard]
+        # @return [Fear::PartialFunction::Guard]
+        def and(other)
+          Guard::And.new(self, other)
+        end
+
+        # @param other [Fear::PartialFunction::Guard]
+        # @return [Fear::PartialFunction::Guard]
+        def or(other)
+          Guard::Or.new(self, other)
+        end
+
+        # @param arg [any]
+        # @return [Boolean]
+        def ===(arg)
+          (c1 === arg) && (c2 === arg) && (c3 === arg)
+        end
+      end
+    end
+  end
+end

data/lib/fear/partial_function/guard/or.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Fear
+  module PartialFunction
+    class Guard
+      # @api private
+      class Or < Guard
+        # @param c1 [Fear::PartialFunction::Guard]
+        # @param c2 [Fear::PartialFunction::Guard]
+        def initialize(c1, c2)
+          @c1 = c1
+          @c2 = c2
+        end
+        attr_reader :c1, :c2
+        private :c1
+        private :c2
+
+        # @param other [Fear::PartialFunction::Guard]
+        # @return [Fear::PartialFunction::Guard]
+        def and(other)
+          Guard::And.new(self, other)
+        end
+
+        # @param other [Fear::PartialFunction::Guard]
+        # @return [Fear::PartialFunction::Guard]
+        def or(other)
+          Guard::Or.new(self, other)
+        end
+
+        # @param arg [any]
+        # @return [Boolean]
+        def ===(arg)
+          (c1 === arg) || (c2 === arg)
+        end
+      end
+    end
+  end
+end

data/lib/fear/partial_function/lifted.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Fear
+  module PartialFunction
+    # @api private
+    class Lifted
+      # @param pf [Fear::PartialFunction]
+      def initialize(pf)
+        @pf = pf
+      end
+      attr_reader :pf
+      private :pf
+
+      # @param arg [any]
+      # @return [Fear::Option]
+      def call(arg)
+        Some.new(pf.call_or_else(arg) { return Fear::None })
+      end
+    end
+
+    private_constant :Lifted
+  end
+end

data/lib/fear/partial_function/or_else.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Fear
+  module PartialFunction
+    # Composite function produced by +PartialFunction#or_else+ method
+    # @api private
+    class OrElse
+      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)
+        f1.call_or_else(arg, &f2)
+      end
+
+      alias === call
+      alias [] call
+
+      # @param other [Fear::PartialFunction]
+      # @return [Fear::PartialFunction]
+      def or_else(other)
+        OrElse.new(f1, f2.or_else(other))
+      end
+
+      # @see Fear::PartialFunction#and_then
+      def and_then(other = Utils::UNDEFINED, &block)
+        Utils.with_block_or_argument("Fear::PartialFunction::OrElse#and_then", other, block) do |fun|
+          OrElse.new(f1.and_then(&fun), f2.and_then(&fun))
+        end
+      end
+
+      # @param arg [any]
+      # @return [Boolean]
+      def defined_at?(arg)
+        f1.defined_at?(arg) || f2.defined_at?(arg)
+      end
+
+      # @param arg [any]
+      # @param fallback [Proc]
+      # @return [any]
+      def call_or_else(arg, &fallback)
+        f1.call_or_else(arg) do
+          return f2.call_or_else(arg, &fallback)
+        end
+      end
+    end
+
+    private_constant :OrElse
+  end
+end

data/lib/fear/partial_function_class.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Fear
+  # @api private
+  class PartialFunctionClass
+    include PartialFunction
+
+    # @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
+
+    # @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.(arg)
+      else
+        yield arg
+      end
+    end
+  end
+
+  private_constant :PartialFunctionClass
+end

data/lib/fear/pattern_match.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+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).(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
+
+    # @param pattern [String]
+    # @param guards [<#===>]
+    # @param effect [Proc]
+    # @return [Fear::PartialFunction]
+    # @see #case for details
+    # @see Fear.xcase for details
+    def xcase(pattern, *guards, &effect)
+      or_else(Fear.xcase(pattern, *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,137 @@
+# frozen_string_literal: true
+
+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" }
+    #     m.case(:even?.to_proc) { |x| "#{x} is even" }
+    #     m.case(:odd?.to_proc) { |x| "#{x} is odd" }
+    #
+    # It's also possible to pass several guardians. All should match to pass
+    #
+    #     m.case(Integer, :even?.to_proc) { |x| ... }
+    #     m.case(Integer, :odd?.to_proc) { |x| ... }
+    #
+    # If you want to perform pattern destruction, use +#xcase+ method
+    #
+    #     m.xcase('Date(year, 12, 31)') { |year:| "Last day of the year #{year}" }
+    #
+    # The pattern above ensures that it's 31 of December and extracts year to block named parameter
+    #
+    # 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::PatternMatch]
+    # @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?.to_proc) { |n| "#{n} is even number" }
+    #     m.case(Integer, :odd?.to_proc) { |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).(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?.to_proc) { |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 [<#===>]
+    # @param function [Proc]
+    # @return [Fear::PartialFunction]
+    def case(*guards, &function)
+      PartialFunction.and(*guards, &function)
+    end
+
+    # Creates partial function defined on domain described with guard
+    # and perform pattern extraction.
+    #
+    # @param pattern [String] pattern to match against
+    # @param guards [<#===>] other guards against extracted pattern
+    # @yieldparam hash [{Symbol => any}]
+    # @return [Fear::PartialFunction]
+    #
+    # @example
+    #   pf = Fear.xcase('['ok', Some(body)]') { |body:| ...  }
+    #   pf.defined_at?(['ok', Fear.some(body)]) #=> true
+    #   pf.defined_at?(['err', Fear.none]) #=> false
+    #
+    # @example pattern and guards. It matches against non-empty body
+    #
+    #   pf = Fear.xcase('['ok', Some(body)]', ->(body:) { !body.empty? }) { }
+    #
+    def xcase(pattern, *guards, &function)
+      warn "NOTE: Fear.xcase is deprecated and will be removed in a future version. Use `case .. in ..` instead."
+      Fear[pattern].and_then(self.case(*guards, &function))
+    end
+  end
+end