qo 0.5.0 → 0.99.0

data/lib/qo/pattern_matchers/branching.rb

@@ -0,0 +1,52 @@
+module Qo
+  module PatternMatchers
+    # A module to allow the registration of braches to a pattern matcher.
+    #
+    # @author baweaver
+    # @since 1.0.0
+    #
+    module Branching
+      # On inclusion, extend the class including this module with branch
+      # registration methods.
+      #
+      # @param base [Class]
+      #   Class including this module, passed from `include`
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # Class methods to extend the including class with
+      #
+      # @author baweaver
+      # @since 1.0.0
+      module ClassMethods
+        # Registers a branch to a pattern matcher.
+        #
+        # This defines a method on the pattern matcher matching the `name` of
+        # the branch. If the name is `where`, the pattern matcher will now be
+        # given a method called `where` with which to match with.
+        #
+        # When called, this will either ammend a matcher to the list of matchers
+        # or set a default matcher if the branch happens to be a default.
+        #
+        # @param branch [Branch]
+        #   Branch object to register with a pattern matcher
+        def register_branch(branch)
+          define_method(branch.name) do |*conditions, **keyword_conditions, &function|
+            qo_matcher = Qo::Matchers::Matcher.new('and', conditions, keyword_conditions)
+
+            branch_matcher = branch.create_matcher(
+              qo_matcher, destructure: @destructure, &function
+            )
+
+            if branch.default?
+              @default = branch_matcher
+            else
+              @matchers << branch_matcher
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/qo/pattern_matchers/pattern_match.rb

@@ -0,0 +1,170 @@
+module Qo
+  module PatternMatchers
+    # Classic Pattern Match. This matcher uses `when` and `else` branches and
+    # is meant to be a more powerful variant of the case statement
+    #
+    # @author baweaver
+    # @since 0.2.0
+    class PatternMatch
+      include Branching
+
+      # The regular pattern matcher from classic Qo uses `when` and `else`
+      # branches, like a `case` statement
+      register_branch Qo::Branches::WhenBranch.new
+      register_branch Qo::Branches::ElseBranch.new
+
+      # Creates a new instance of a pattern matcher
+      #
+      # @param destructure: false [Boolean]
+      #   Whether or not to destructure values before yielding to a block
+      #
+      # @param &fn [Proc]
+      #   Function to be used to construct the pattern matcher's branches
+      #
+      # @return [Qo::PatternMatchers::PatternMatch]
+      def initialize(destructure: false, &fn)
+        @matchers    = []
+        @default     = nil
+        @destructure = destructure
+
+        yield(self) if block_given?
+      end
+
+      # Allows for the creation of an anonymous PatternMatcher based on this
+      # parent class. To be used by people wishing to make their own pattern
+      # matchers with variant branches and other features not included in the
+      # defaultly provided ones
+      #
+      # @param branches: [] [Array[Branch]]
+      #   Branches to be used with this new pattern matcher
+      #
+      # @return [Class]
+      #   Anonymous pattern matcher class to be bound to a constant or used
+      #   anonymously.
+      def self.create(branches: [])
+        Class.new(Qo::PatternMatchers::PatternMatch) do
+          branches.each { |branch| register_branch(branch.new) }
+        end
+      end
+
+      # Allows for the injection of a pattern matching function into a type class
+      # for direct access, rather than yielding an instance of that class to a
+      # pattern matcher.
+      #
+      # This is typically done for monadic types that need to `match`. When
+      # combined with extractor type branches it can be very handy for dealing
+      # with container types.
+      #
+      # @example
+      #
+      #   ```ruby
+      #   # Technically Some and None don't exist yet, so we have to "cheat" instead
+      #   # of just saying `Some` for the precondition
+      #   SomeBranch = Qo.create_branch(
+      #     name:        'some',
+      #     precondition: -> v { v.is_a?(Some) },
+      #     extractor:    :value
+      #   )
+      #
+      #   NoneBranch = Qo.create_branch(
+      #     name:        'none',
+      #     precondition: -> v { v.is_a?(None) },
+      #     extractor:    :value
+      #   )
+      #
+      #   SomePatternMatch = Qo.create_pattern_match(branches: [SomeBranch, NoneBranch])
+      #
+      #   class Some
+      #     include SomePatternMatch.mixin
+      #
+      #     attr_reader :value
+      #
+      #     def initialize(value) @value = value end
+      #
+      #     def fmap(&fn)
+      #       new_value = fn.call(value)
+      #       new_value ? Some.new(new_value) : None(value)
+      #     end
+      #   end
+      #
+      #   class None
+      #     include SomePatternMatch.mixin
+      #
+      #     attr_reader :value
+      #
+      #     def initialize(value) @value = value end
+      #     def fmap(&fn) None.new(value) end
+      #   end
+      #
+      #   Some.new(1)
+      #     .fmap { |v| v * 2 }
+      #     .match { |m|
+      #       m.some { |v| v + 100 }
+      #       m.none { "OHNO!" }
+      #     }
+      #   => 102
+      #
+      #   Some.new(1)
+      #     .fmap { |v| nil }
+      #     .match { |m|
+      #       m.some { |v| v + 100 }
+      #       m.none { "OHNO!" }
+      #     }
+      #   => "OHNO!"
+      #   ```
+      #
+      # @param destructure: false [Boolean]
+      #   Whether or not to destructure values before yielding to a block
+      #
+      # @param as: :match [Symbol]
+      #   Name to use as a method name bound to the including class
+      #
+      # @return [Module]
+      #   Module to be mixed into a class
+      def self.mixin(destructure: false, as: :match)
+        create_self = -> &function { new(destructure: destructure, &function) }
+
+        Module.new do
+          define_method(as) do |&function|
+            create_self.call(&function).call(self)
+          end
+        end
+      end
+
+      # Calls the pattern matcher, yielding the target value to the first
+      # matching branch it encounters.
+      #
+      # @param value [Any]
+      #   Value to match against
+      #
+      # @return [Any]
+      #   Result of the called branch
+      #
+      # @return [nil]
+      #   Returns nil if no branch is matched
+      def call(value)
+        @matchers.each do |matcher|
+          status, return_value = matcher.call(value)
+          return return_value if status
+        end
+
+        if @default
+          _, return_value = @default.call(value)
+          return_value
+        else
+          nil
+        end
+      end
+
+      alias === call
+      alias [] call
+
+      # Procified version of `call`
+      #
+      # @return [Proc[Any] => Any]
+      def to_proc
+        -> target { self.call(target) }
+      end
+    end
+  end
+end

data/lib/qo/pattern_matchers/pattern_matchers.rb

@@ -0,0 +1,13 @@
+module Qo
+  # Classes for constructing pattern matchers, or defining your own
+  # should you want to.
+  #
+  # @author baweaver
+  # @since 1.0.0
+  module PatternMatchers
+  end
+end
+
+require 'qo/pattern_matchers/branching'
+require 'qo/pattern_matchers/pattern_match'
+require 'qo/pattern_matchers/result_pattern_match'

data/lib/qo/pattern_matchers/result_pattern_match.rb

@@ -0,0 +1,45 @@
+module Qo
+  module PatternMatchers
+    # Unlike the normal pattern matcher, this one works on tuple arrays containing
+    # a status and a result like `[:ok, result]` and `[:err, message]`.
+    #
+    # Note that each of these can still take conditionals much like a `where`
+    # branch for more fine grained control over what we're looking for.
+    #
+    # @example
+    #   ```ruby
+    #   matcher = Qo.result_match { |m|
+    #     m.success(String) { |v| "Hello #{v}"}
+    #     m.success         { |v| v + 10 }
+    #     m.failure         { |v| "Error: #{v}" }
+    #   }
+    #
+    #   matcher.call([:ok, 'there'])
+    #   # => "Hello there"
+    #
+    #   matcher.call([:ok, 4])
+    #   # => 14
+    #
+    #   matcher.call([:err, 'OH NO'])
+    #   # => "Error: OH NO"
+    #   ```
+    #
+    # @author baweaver
+    # @since 1.0.0
+    class ResultPatternMatch < PatternMatch
+      register_branch Qo::Branches::SuccessBranch.new
+      register_branch Qo::Branches::FailureBranch.new
+
+      # Creates a new result matcher
+      #
+      # @param destructure: false [Boolean]
+      #   Whether or not to destructure the value before yielding to
+      #   the first matched block
+      #
+      # @return [type] [description]
+      def initialize(destructure: false)
+        super(destructure: destructure)
+      end
+    end
+  end
+end

data/lib/qo/public_api.rb

@@ -73,15 +73,19 @@ module Qo
     #   })
     #   => [0, 6, 2]
     #
+    # @param destructure: [Boolean]
+    #   Whether or not to destructure an object before yielding it to the
+    #   given function.
+    #
     # @param fn [Proc]
     #   Body of the matcher, as shown in examples
     #
     # @return [Qo::PatternMatch]
     #   A function awaiting a value to match against
-    def match(&fn)
+    def match(destructure: false, &fn)
       return proc { false } unless block_given?
 
-      Qo::Matchers::PatternMatch.new(&fn)
+      Qo::PatternMatchers::PatternMatch.new(destructure: destructure, &fn)
     end
 
     # Similar to the common case statement of Ruby, except in that it behaves
@@ -105,16 +109,136 @@ module Qo
     # @param value [Any]
     #   Value to match against
     #
+    # @param destructure: [Boolean]
+    #   Whether or not to destructure an object before yielding it to the
+    #   given function.
+    #
     # @param &fn [Proc]
     #   Body of the matcher, as shown above
     #
     # @return [Any]
     #   The result of calling a pattern match with a provided value
-    def case(value, &fn)
-      Qo::Matchers::PatternMatch.new(&fn).call(value)
+    def case(value, destructure: false, &fn)
+      Qo::PatternMatchers::PatternMatch.new(destructure: destructure, &fn).call(value)
+    end
+
+    # Similar to `match`, except it uses a `ResultPatternMatch` which instead
+    # responds to tuple types:
+    #
+    # @example
+    #
+    #   ```ruby
+    #   pm = Qo.result_match { |m|
+    #     m.success { |v| v + 10 }
+    #     m.failure { |v| "Error: #{v}" }
+    #   }
+    #
+    #   pm.call([:ok, 3])
+    #   # => 13
+    #
+    #   pm.call([:err, "No Good"])
+    #   # => "Error: No Good"
+    #   ```
+    #
+    # @param destructure: [Boolean]
+    #   Whether or not to destructure an object before yielding it to the
+    #   given function.
+    #
+    # @param &fn [Proc]
+    #   Body of the matcher, as shown above
+    #
+    # @see match
+    #
+    # @return [Proc[Any] => Any]
+    #   Proc awaiting a value to match against.
+    def result_match(destructure: false, &fn)
+      return proc { false } unless block_given?
+
+      Qo::PatternMatchers::ResultPatternMatch.new(destructure: destructure, &fn)
     end
 
-    # Abstraction for creating a matcher, allowing for common error handling scenarios.
+    # Similar to `case`, except it uses a `ResultPatternMatch` instead.
+    #
+    # @see match
+    # @see result_match
+    # @see case
+    #
+    # @param target [Any]
+    #   Target to match against
+    #
+    # @param destructure: [Boolean]
+    #   Whether or not to destructure an object before yielding it to the
+    #   given function.
+    #
+    # @param &fn [Proc]
+    #   Body of the matcher, as shown above
+    #
+    # @return [Any]
+    #   Result of the match
+    def result_case(target, destructure: false, &fn)
+      Qo::PatternMatchers::ResultPatternMatch
+        .new(destructure: destructure, &fn)
+        .call(target)
+    end
+
+    # Dynamically creates a new branch to be used with custom pattern matchers.
+    #
+    # @param name: [String]
+    #   Name of the branch. This is what binds to the pattern match as a method,
+    #   meaning a name of `where` will result in calling it as `m.where`.
+    #
+    # @param precondition: Any [Symbol, #===]
+    #   A precondition to the branch being considered true. This is done for
+    #   static conditions like a certain type or perhaps checking a tuple type
+    #   like `[:ok, value]`.
+    #
+    #   If a `Symbol` is given, Qo will coerce it into a proc. This is done to
+    #   make a nicer shorthand for creating a branch.
+    #
+    # @param extractor: IDENTITY [Proc, Symbol]
+    #   How to pull the value out of a target object when a branch matches before
+    #   calling the associated function. For a monadic type this might be something
+    #   like extracting the value before yielding to the given block.
+    #
+    #   If a `Symbol` is given, Qo will coerce it into a proc. This is done to
+    #   make a nicer shorthand for creating a branch.
+    #
+    # @param destructure: false
+    #   Whether or not to destructure the given object before yielding to the
+    #   associated block. This means that the given block now places great
+    #   importance on the argument names, as they'll be used to extract values
+    #   from the associated object by that same method name, or key name in the
+    #   case of hashes.
+    #
+    # @param default: false [Boolean]
+    #   Whether this branch is considered to be a default condition. This is
+    #   done to ensure that a branch runs last after all other conditions have
+    #   failed. An example of this would be an `else` branch.
+    #
+    # @return [Class]
+    #   Anonymous branch class to be bound to a constant or used directly
+    def create_branch(name:, precondition: Any, extractor: IDENTITY, destructure: false, default: false)
+      Qo::Branches::Branch.create(
+        name:         name,
+        precondition: precondition,
+        extractor:    extractor,
+        destructure:  destructure,
+        default:      default
+      )
+    end
+
+    # Creates a new type of pattern matcher from a set of branches
+    #
+    # @param branches: [Array[Branch]]
+    #   An array of branches that this pattern matcher will respond to
+    #
+    # @return [Class]
+    #   Anonymous pattern matcher to be bound to a constant or used directly
+    def create_pattern_match(branches:)
+      Qo::PatternMatchers::PatternMatch.create(branches: branches)
+    end
+
+    # Abstraction for creating a matcher.
     #
     # @param type [String]
     #   Type of matcher
@@ -127,9 +251,7 @@ module Qo
     #
     # @return [Qo::Matcher]
     private def create_matcher(type, array_matchers, keyword_matchers)
-      raise MultipleMatchersProvided if !array_matchers.empty? && !keyword_matchers.empty?
-
-      Qo::Matchers::BaseMatcher.new(type, array_matchers, keyword_matchers)
+      Qo::Matchers::Matcher.new(type, array_matchers, keyword_matchers)
     end
   end
 end