qo 0.5.0 → 0.99.0

data/lib/qo/branches/else_branch.rb

@@ -0,0 +1,20 @@
+module Qo
+  module Branches
+    # A default branch to for when other conditions fail.
+    #
+    # ```ruby
+    # Qo.case(1) { |m|
+    #   m.else { |v| v + 2 }
+    # }
+    # # => 3
+    # ```
+    #
+    # @author baweaver
+    # @since 1.0.0
+    class ElseBranch < Branch
+      def initialize(destructure: false)
+        super(name: 'else', destructure: destructure, default: true)
+      end
+    end
+  end
+end

data/lib/qo/branches/error_branch.rb

@@ -0,0 +1,26 @@
+module Qo
+  module Branches
+    # A tuple branch that will be triggered when the first value is
+    # `:err`.
+    #
+    # ```ruby
+    # ResultPatternMatch.new { |m|
+    #   m.error { |v| "This is the error: #{v}" }
+    # }.call([:err, 'OH NO!'])
+    # # => "This is the error: OH NO!"
+    # ```
+    #
+    # @author baweaver
+    # @since 1.0.0
+    class ErrorBranch < Branch
+      def initialize(destructure: false)
+        super(
+          name: 'error',
+          destructure: destructure,
+          precondition: -> v { v.first == :err },
+          extractor: :last,
+        )
+      end
+    end
+  end
+end

data/lib/qo/branches/failure_branch.rb

@@ -0,0 +1,26 @@
+module Qo
+  module Branches
+    # A tuple branch that will be triggered when the first value is
+    # `:err`.
+    #
+    # ```ruby
+    # ResultPatternMatch.new { |m|
+    #   m.failure { |v| "This is the error: #{v}" }
+    # }.call([:err, 'OH NO!'])
+    # # => "This is the error: OH NO!"
+    # ```
+    #
+    # @author baweaver
+    # @since 1.0.0
+    class FailureBranch < Branch
+      def initialize(destructure: false)
+        super(
+          name: 'failure',
+          destructure: destructure,
+          precondition: -> v { v.first == :err },
+          extractor: :last,
+        )
+      end
+    end
+  end
+end

data/lib/qo/branches/monadic_else_branch.rb

@@ -0,0 +1,26 @@
+module Qo
+  module Branches
+    # Based on the `else` branch, except deals with monadic values by attempting
+    # to extract the `value` before yielding to the given function on a match:
+    #
+    # ```ruby
+    # Matcher.new.call(Some[1]) { |m|
+    #   m.else { |v| v + 2 }
+    # }
+    # # => 3
+    # ```
+    #
+    # @author baweaver
+    # @since 1.0.0
+    class MonadicElseBranch < Branch
+      def initialize(destructure: false, extractor: :value)
+        super(
+          name: 'else',
+          destructure: destructure,
+          extractor: extractor,
+          default: true,
+        )
+      end
+    end
+  end
+end

data/lib/qo/branches/monadic_when_branch.rb

@@ -0,0 +1,26 @@
+module Qo
+  module Branches
+    # Based on the `where` branch, except deals with monadic values by attempting
+    # to extract the `value` before yielding to the given function on a match:
+    #
+    # ```ruby
+    # Matcher.new.call(Some[1]) { |m|
+    #   m.where(Some) { |v| v + 2 }
+    # }
+    # # => 3
+    # ```
+    #
+    # @author baweaver
+    # @since 1.0.0
+    class MonadicWhenBranch < Branch
+      def initialize(destructure: false, extractor: :value)
+        super(
+          name: 'where',
+          destructure: destructure,
+          extractor: extractor,
+          default: false,
+        )
+      end
+    end
+  end
+end

data/lib/qo/branches/success_branch.rb

@@ -0,0 +1,26 @@
+module Qo
+  module Branches
+    # A tuple branch that will be triggered when the first value is
+    # `:ok`.
+    #
+    # ```ruby
+    # ResultPatternMatch.new { |m|
+    #   m.success { |v| v + 2 }
+    # }.call([:ok, 1])
+    # # => 3
+    # ```
+    #
+    # @author baweaver
+    # @since 1.0.0
+    class SuccessBranch < Branch
+      def initialize(destructure: false)
+        super(
+          name: 'success',
+          destructure: destructure,
+          precondition: -> v { v.first == :ok },
+          extractor: :last,
+        )
+      end
+    end
+  end
+end

data/lib/qo/branches/when_branch.rb

@@ -0,0 +1,21 @@
+module Qo
+  module Branches
+    class WhenBranch < Branch
+      # The traditional pattern matching branch, based off of `when` from
+      # Ruby's `case` statement:
+      #
+      # ```ruby
+      # Qo.case(1) { |m|
+      #   m.when(Integer) { |v| v + 2 }
+      # }
+      # # => 3
+      # ```
+      #
+      # @author baweaver
+      # @since 1.0.0
+      def initialize(destructure: false)
+        super(name: 'when', destructure: destructure, default: false)
+      end
+    end
+  end
+end

data/lib/qo/destructurers/destructurer.rb

@@ -0,0 +1,85 @@
+module Qo
+  module Destructurers
+    # Classic destructuring. This gives great value to the names of a function's
+    # arguments, transforming the way blocks are normally yielded to. Take for
+    # example this function:
+    #
+    # ```ruby
+    # Proc.new { |name, age| ... }
+    # ```
+    #
+    # The names of the arguments are `name` and `age`. Destructuring involves
+    # using these names to extract the values of an object before the function
+    # is called:
+    #
+    # 1. Get the names of the arguments
+    # 2. Map over those names to extract values from an object by sending them
+    #    as method calls
+    # 3. Call the function with the newly extracted values
+    #
+    # It's highly suggested to read through the "Destructuring in Ruby" article
+    # here:
+    #
+    # @see https://medium.com/rubyinside/destructuring-in-ruby-9e9bd2be0360
+    #
+    # @author baweaver
+    # @since 1.0.0
+    class Destructurer
+      # Creates a destructurer
+      #
+      # @param destructure: [Boolean]
+      #   Whether or not to destructure an object before calling a function
+      #
+      # @param &function [Proc]
+      #   Associated function to be called
+      #
+      # @return [Qo::Destructurers::Destructurer]
+      def initialize(destructure:, &function)
+        @destructure    = destructure
+        @function       = function || IDENTITY
+        @argument_names = argument_names
+      end
+
+      # Calls the destructurer to extract values from a target and call the
+      # function with those extracted values.
+      #
+      # @param target [Any]
+      #   Target to extract values from
+      #
+      # @return [Any]
+      #   Return of the given function
+      def call(target)
+        destructured_arguments = destructure? ? destructure_values(target) : target
+
+        @function.call(destructured_arguments)
+      end
+
+      # Whether or not this method will destructure a passed object
+      #
+      # @return [Boolean]
+      def destructure?
+        @destructure
+      end
+
+      # Destructures values from a target object
+      #
+      # @param target [Any]
+      #   Object to extract values from
+      #
+      # @return [Array[Any]]
+      #   Extracted values
+      def destructure_values(target)
+        target.is_a?(::Hash) ?
+          argument_names.map { |n| target[n] } :
+          argument_names.map { |n| target.respond_to?(n) && target.public_send(n) }
+      end
+
+      # Names of the function's arguments
+      #
+      # @return [Array[Symbol]]
+      def argument_names
+        @argument_names ||= @function.parameters.map(&:last)
+      end
+    end
+  end
+end

data/lib/qo/destructurers/destructurers.rb

@@ -0,0 +1,15 @@
+module Qo
+  # Classes that allow for the destructuring of values from an object, meant
+  # to emulate Javascript object destructuring. While this is a very powerful
+  # expressive feature, it can also slow down execution by a small amount, so
+  # use destructuring wisely.
+  #
+  # @see https://medium.com/rubyinside/destructuring-in-ruby-9e9bd2be0360
+  #
+  # @author baweaver
+  # @since 1.0.0
+  module Destructurers
+  end
+end
+
+require 'qo/destructurers/destructurer'

data/lib/qo/exceptions.rb

@@ -1,41 +1,12 @@
 module Qo
   # Defines common exception classes for use throughout the library
   #
+  # Currently there aren't any exceptions being used, but keeping this
+  # around for later use.
+  #
   # @author baweaver
   # @since 0.2.0
   #
   module Exceptions
-    # If no matchers in either Array or Hash style are provided.
-    #
-    # @author baweaver
-    # @since 0.2.0
-    #
-    class NoMatchersProvided < ArgumentError
-      def to_s
-        "No Qo matchers were provided!"
-      end
-    end
-
-    # If both Array and Hash style matchers are provided.
-    #
-    # @author baweaver
-    # @since 0.2.0
-    #
-    class MultipleMatchersProvided < ArgumentError
-      def to_s
-        "Cannot provide both array and keyword matchers!"
-      end
-    end
-
-    # In the case of a Pattern Match, we should only have one "else" clause
-    #
-    # @author baweaver
-    # @since 0.3.0
-    #
-    class MultipleElseClauses < ArgumentError
-      def to_s
-        "Cannot have more than one `else` clause in a Pattern Match."
-      end
-    end
   end
 end

data/lib/qo/matchers/matcher.rb

@@ -0,0 +1,298 @@
+module Qo
+  module Matchers
+    # Matcher used to determine whether a value matches a certain set of
+    # conditions
+    #
+    # @author baweaver
+    # @since 1.0.0
+    #
+    class Matcher
+      # Creates a new matcher
+      #
+      # @param type [String]
+      #   Type of the matcher: any, all, or none. Used to determine how a
+      #   match is determined
+      #
+      # @param array_matchers = [] [Array[Any]]
+      #   Conditions given as an array
+      #
+      # @param keyword_matchers = {} [Hash[Any, Any]]
+      #   Conditions given as keywords
+      #
+      # @return [Qo::Matchers::Matcher]
+      def initialize(type, array_matchers = [], keyword_matchers = {})
+        @type = type
+        @array_matchers = array_matchers
+        @keyword_matchers = keyword_matchers
+      end
+
+      # Proc-ified version of `call`
+      #
+      # @return [Proc[Any] => Boolean]
+      def to_proc
+        -> target { self.call(target) }
+      end
+
+      # Calls the matcher on a given target value
+      #
+      # @param target [Any]
+      #   Target to match against
+      #
+      # @return [Boolean]
+      #   Whether or not the target matched
+      def call(target)
+        combined_check(array_call(target), keyword_call(target))
+      end
+
+      alias_method :===, :call
+      alias_method :[],  :call
+      alias_method :match?,  :call
+
+      # Used to match against a matcher made from Keyword Arguments (a Hash)
+      #
+      # @param matchers [Hash[Any, #===]]
+      #   Any key mapping to any value that responds to `===`. Notedly more
+      #   satisfying when `===` does something fun.
+      #
+      # @return [Boolean]
+      #   Result of the match
+      private def keyword_call(target)
+        return true if @keyword_matchers == target
+
+        match_fn = target.is_a?(::Hash) ?
+          Proc.new { |match_key, matcher| match_hash_value?(target, match_key, matcher)   } :
+          Proc.new { |match_key, matcher| match_object_value?(target, match_key, matcher) }
+
+        match_with(@keyword_matchers, &match_fn)
+      end
+
+      # Runs the matcher directly.
+      #
+      # If the target is an Array, it will be matched via index
+      #
+      # If the target is an Object, it will be matched via public send
+      #
+      # @param target [Any]
+      #   Target to match against
+      #
+      # @return [Boolean]
+      #   Result of the match
+      private def array_call(target)
+        return true if @array_matchers == target
+
+        if target.is_a?(::Array)
+          return false unless target.size == @array_matchers.size
+
+          match_with(@array_matchers.each_with_index) { |matcher, i|
+            match_value?(target[i], matcher)
+          }
+        else
+          match_with(@array_matchers) { |matcher|
+            match_value?(target, matcher)
+          }
+        end
+      end
+
+      # Wraps a case equality statement to make it a bit easier to read. The
+      # typical left bias of `===` can be confusing reading down a page, so
+      # more of a clarity thing than anything. Also makes for nicer stack traces.
+      #
+      # @param target  [Any]
+      #   Target to match against
+      #
+      # @param matcher [#===]
+      #   Anything that responds to ===, preferably in a unique and entertaining way.
+      #
+      # @return [Boolean]
+      private def case_match?(target, matcher)
+        matcher === target
+      end
+
+      # Guarded version of `public_send` meant to stamp out more
+      # obscure errors when running against non-matching types.
+      #
+      # @param target  [Any]
+      #   Object to send to
+      #
+      # @param matcher [#to_sym]
+      #   Anything that can be coerced into a method name
+      #
+      # @return [Any]
+      #   Response of sending to the method, or false if failed
+      private def method_send(target, matcher)
+        matcher.respond_to?(:to_sym) &&
+        target.respond_to?(matcher.to_sym) &&
+        target.public_send(matcher)
+      end
+
+      # Predicate variant of `method_send` with the same guard concerns
+      #
+      # @param target [Any]
+      #   Object to send to
+      #
+      # @param matcher [#to_sym]
+      #   Anything that can be coerced into a method name
+      #
+      # @return [Boolean]
+      #   Success status of predicate
+      private def method_matches?(target, matcher)
+        !!method_send(target, matcher)
+      end
+
+      # Defines what it means for a value to match a matcher
+      #
+      # @param target [Any]
+      #   Target to match against
+      #
+      # @param matcher [Any]
+      #   Any matcher to run against, most frequently responds to ===
+      #
+      # @return [Boolean]
+      #   Match status
+      private def match_value?(target, matcher)
+        case_match?(target, matcher) ||
+        method_matches?(target, matcher)
+      end
+
+      # Checks if a hash value matches a given matcher
+      #
+      # @param target [Any]
+      #   Target of the match
+      #
+      # @param match_key [Symbol]
+      #   Key of the hash to reference
+      #
+      # @param matcher [#===]
+      #   Any matcher responding to ===
+      #
+      # @return [Boolean]
+      #   Match status
+      private def match_hash_value?(target, match_key, matcher)
+        return false unless target.key?(match_key)
+
+        return hash_recurse(target[match_key], matcher) if target.is_a?(Hash) && matcher.is_a?(Hash)
+
+        hash_case_match?(target, match_key, matcher) ||
+        hash_method_predicate_match?(target, match_key, matcher)
+      end
+
+      # Checks if an object property matches a given matcher
+      #
+      # @param target [Any]
+      #   Target of the match
+      #
+      # @param match_property [Symbol]
+      #   Property of the object to reference
+      #
+      # @param matcher [#===]
+      #   Any matcher responding to ===
+      #
+      # @return [Boolean] Match status
+      private def match_object_value?(target, match_property, matcher)
+        return false unless target.respond_to?(match_property)
+
+        hash_method_case_match?(target, match_property, matcher)
+      end
+
+      # Double wraps case match in order to ensure that we try against both Symbol
+      # and String variants of the keys, as this is a very common mixup in Ruby.
+      #
+      # @param target [Hash]
+      #   Target of the match
+      #
+      # @param match_key [Symbol]
+      #   Key to match against
+      #
+      # @param matcher [#===]
+      #   Matcher
+      #
+      # @return [Boolean]
+      private def hash_case_match?(target, match_key, matcher)
+        return true if case_match?(target[match_key], matcher)
+        return false unless target.keys.first.is_a?(String)
+
+        match_key.respond_to?(:to_s) &&
+        target.key?(match_key.to_s) &&
+        case_match?(target[match_key.to_s], matcher)
+      end
+
+      # Attempts to run a matcher as a predicate method against the target
+      #
+      # @param target [Hash]
+      #   Target of the match
+      #
+      # @param match_key [Symbol]
+      #   Method to call
+      #
+      # @param match_predicate [Symbol]
+      #   Matcher
+      #
+      # @return [Boolean]
+      private def hash_method_predicate_match?(target, match_key, match_predicate)
+        method_matches?(target[match_key], match_predicate)
+      end
+
+      # Attempts to run a case match against a method call derived from a hash
+      # key, and checks the result.
+      #
+      # @param target [Hash]
+      #   Target of the match
+      #
+      # @param match_property [Symbol]
+      #   Method to call
+      #
+      # @param matcher [#===]
+      #   Matcher
+      #
+      # @return [Boolean]
+      private def hash_method_case_match?(target, match_property, matcher)
+        case_match?(method_send(target, match_property), matcher)
+      end
+
+      # Recurses on nested hashes.
+      #
+      # @param target [Hash]
+      #   Target to recurse into
+      #
+      # @param matcher [Hash]
+      #   Matcher to use to recurse with
+      #
+      # @return [Boolean]
+      private def hash_recurse(target, matcher)
+        Qo::Matchers::Matcher.new(@type, [], matcher).call(target)
+      end
+
+      # Runs the relevant match method against the given collection with the
+      # given matcher function.
+      #
+      # @param collection [Enumerable] Any collection that can be enumerated over
+      # @param fn         [Proc]       Function to match with
+      #
+      # @return [Boolean] Result of the match
+      private def match_with(collection, &fn)
+        case @type
+        when 'and' then collection.all?(&fn)
+        when 'or'  then collection.any?(&fn)
+        when 'not' then collection.none?(&fn)
+        else false
+        end
+      end
+
+      # When combining array and keyword type matchers, depending on how
+      # we're matching we may need to combine them slightly differently.
+      #
+      # @param *checks [Array]
+      #   The checks we're combining
+      #
+      # @return [Boolean]
+      #   Whether or not there's a match
+      private def combined_check(*checks)
+        case @type
+        when 'and', 'not' then checks.all?
+        when 'or'         then checks.any?
+        else false
+        end
+      end
+    end
+  end
+end