qo 0.5.0 → 0.99.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 02dea6ad061112d957032940212ab369e09b0ec1
-  data.tar.gz: '037591f1119e010e7faba94c51f1ed4678cafe45'
+SHA256:
+  metadata.gz: 58ef9c82490e44396774612fd230c2056cb45588536800816ed69033e700b8c6
+  data.tar.gz: 250b1a8d1e619a6f2910dc40637e5c06e5b51ac05eeb294a2285315232d7cdff
 SHA512:
-  metadata.gz: b01330722400077045a769eaaccc565ad2132f0413624b510f370754bfda109dac6ffcf1ea6cd2ce6987182d19cceb773bd04e67f49c990eef84f7a8774d53ea
-  data.tar.gz: df76eed79e30353032930972ef916a7788500753b4e0fd684cf42be4c8f2f2dded8493c9e43ed52e71c2023291952f1b2b6c319dfca0de9b9b64b951ed6dc1d7
+  metadata.gz: ea272d67050323df29d83d8a7c7f6f7528f1a58e39aeec146d6902c0abdf1db42bf1fd4577f255487efb0ce927b6d139d7d3b9d0e386b30c5c4f3486369abf6f
+  data.tar.gz: 05cff280a0d79b3cbeb5a7114d8c05d2c3ea1d317ea4b346ea9aa17785af7937333da79c75ebb839d1e047287a804e94d2112cec78b04d01c67689c9aab7ebe1

data/.travis.yml

@@ -1,7 +1,7 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.3.7
-  - 2.4.4
-  - 2.5.1
+  - 2.4.5
+  - 2.5.3
+  - 2.6.1
 before_install: gem install bundler -v 1.15.4

data/README.md

@@ -482,11 +482,11 @@ people_objects.map(&Qo.match { |m|
 
 So we just truncated everyone's name that was longer than three characters.
 
-### 6 - Helper functions
+### 5 - Helper functions
 
 There are a few functions added for convenience, and it should be noted that because all Qo matchers respond to `===` that they can be used as helpers as well.
 
-#### 6.1 - Dig
+#### 5.1 - Dig
 
 Dig is used to get in deep at a nested hash value. It takes a dot-path and a `===` respondent matcher:
 
@@ -500,7 +500,7 @@ Qo.dig('a.b.c', Qo.or(1..5, 15..25)) === {a: {b: {c: 20}}}
 
 To be fair that means anything that can respond to `===`, including classes and other such things.
 
-#### 6.2 - Count By
+#### 5.2 - Count By
 
 This ends up coming up a lot, especially around querying, so let's get a way to count by!
 
@@ -523,15 +523,95 @@ Qo.count_by([1,2,3,2,2,2,1], &:even?)
 
 This feature may be added to Ruby 2.6+: https://bugs.ruby-lang.org/issues/11076
 
-### 5 - Hacky Fun Time
+### 6 - Custom Pattern Matchers
+
+With the release of Qo 1.0.0 we introduced the idea of custom branches and pattern matchers for more advanced
+users of the library.
+
+Consider a Monadic type like `Some` and `None`:
+
+```ruby
+# Technically Some and None don't exist yet, so we have to "cheat" instead
+# of just saying `Some` for the precondition
+#
+# We start by defining two branches that match against a Some type and a None
+# type, extracting the value on match before yielding to their associated
+# functions
+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
+)
+
+# Now we create a new pattern matching class with those branches. Note that
+# there's nothing stopping you from making as many branches as you want,
+# except that it may get confusing after a while.
+SomePatternMatch = Qo.create_pattern_match(branches: [
+  SomeBranch,
+  NoneBranch
+])
+
+class Some
+  # There's also a provided mixin that gives an `match` method that
+  # works exactly like a pattern match without having to use it explicitly
+  include SomePatternMatch.mixin
+
+  attr_reader :value
+
+  def initialize(value) @value = value end
+  def self.[](value)    new(value)     end
+
+  def fmap(&fn)
+    new_value = fn.call(value)
+    new_value ? Some[new_value] : None[value]
+  end
+end
+
+class None
+  include SomePatternMatch.mixin
+
+  attr_reader :value
+
+  def initialize(value) @value = value end
+  def self.[](value)    new(value)     end
+
+  def fmap(&fn) None[value] end
+end
+
+# So now we can pattern match with `some` and `none` branches using the `match`
+# method that was mixed into both types.
+Some[1]
+  .fmap { |v| v * 2 }
+  .match { |m|
+    m.some { |v| v + 100 }
+    m.none { "OHNO!" }
+  }
+=> 102
+
+Some[1]
+  .fmap { |v| nil }
+  .match { |m|
+    m.some { |v| v + 100 }
+    m.none { "OHNO!" }
+  }
+=> "OHNO!"
+```
+
+### 7 - Hacky Fun Time
 
 These examples will grow over the next few weeks as I think of more fun things to do with Qo. PRs welcome if you find fun uses!
 
-#### 5.1 - JSON and HTTP
+#### 7.1 - JSON and HTTP
 
 > Note that Qo does not support deep querying of hashes (yet)
 
-##### 5.1.1 - JSON Placeholder
+##### 7.1.1 - JSON Placeholder
 
 Qo tries to be clever though, it assumes Symbol keys first and then String keys, so how about some JSON?:
 
@@ -602,9 +682,26 @@ m.when(Net::HTTPSuccess, body: /Qo/)
 You could put as many checks as you want in there, or use different Qo matchers
 nested to get even further in.
 
-#### 5.2 - Opsy Stuff
+Now if we wanted to add more power and create an HTTP matcher:
+
+```ruby
+HTTP_Matcher = Qo.create_pattern_match(branches: [
+  Qo.create_branch(name: 'success', precondition: Net::HTTPSuccess),
+  Qo.create_branch(name: 'error', precondition: Net::HTTPError),
+  Qo::Braches::ElseBranch
+])
+
+def get_url(url)
+  Net::HTTP.get_response(URI(url)).then(&HTTP_Matcher.match { |m|
+    m.success { |response| response.body.size },
+    m.else    { |response| raise response.message }
+  })
+end
+```
+
+#### 7.2 - Opsy Stuff
 
-##### 5.2.1 - NMap
+##### 7.2.1 - NMap
 
 What about NMap for our Opsy friends? Well, simulated, but still fun.
 
@@ -616,7 +713,7 @@ hosts.select(&Qo[IPAddr.new('192.168.1.1/8')])
 => [["192.168.1.1", "(Router)"], ["192.168.1.2", "(My Computer)"]]
 ```
 
-##### 5.2.2 - `df`
+##### 7.2.2 - `df`
 
 The nice thing about Unix style commands is that they use headers, which means CSV can get a hold of them for some good formatting. It's also smart enough to deal with space separators that may vary in length:
 

data/Rakefile

@@ -149,7 +149,7 @@ end
 
 task :perf_pattern_match do
   # Going to redefine the way that success and fail happen in here.
-  return false
+  # return false
 
   require 'dry-matcher'
 
@@ -170,13 +170,13 @@ task :perf_pattern_match do
   # Build the matcher
   matcher = Dry::Matcher.new(success: success_case, failure: failure_case)
 
-  qo_m = Qo.match { |m|
+  qo_m = Qo.result_match { |m|
     m.success(Any) { |v| v }
     m.failure(Any) { "ERR!" }
   }
 
   qo_m_case = proc { |target|
-    Qo.case(target) { |m|
+    Qo.result_case(target) { |m|
       m.success(Any) { |v| v }
       m.failure(Any) { "ERR!" }
     }

data/lib/qo.rb

@@ -3,27 +3,29 @@ require 'any'
 
 require "qo/version"
 
-# Matchers
-require 'qo/matchers/base_matcher'
-require 'qo/matchers/array_matcher'
-require 'qo/matchers/hash_matcher'
-require 'qo/matchers/guard_block_matcher'
-
-# Meta Matchers
-require 'qo/matchers/pattern_match'
-
-# Helpers
-require 'qo/helpers'
-
 # Public API
 require 'qo/exceptions'
 require 'qo/public_api'
 
 module Qo
-  # Identity function that returns its argument directly
-  IDENTITY = -> v { v }
+  # Identity function that returns its argument directly. Argument name is
+  # important, as it will extract the literal identity of the object in
+  # the case of a non-destructured match, and the object itself in the
+  # case of a destructured one.
+  IDENTITY = -> itself { itself }
 
   extend Qo::Exceptions
-  extend Qo::Helpers
   extend Qo::PublicApi
 end
+
+# Destructurers
+require 'qo/destructurers/destructurers'
+
+# Matchers
+require 'qo/matchers/matcher'
+
+# Branches
+require 'qo/branches/branches'
+
+# Pattern Matchers
+require 'qo/pattern_matchers/pattern_matchers'

data/lib/qo/branches/branch.rb

@@ -0,0 +1,191 @@
+module Qo
+  module Branches
+    # ### Branches
+    #
+    # A branch is a particular branch of a pattern match. The default branches
+    # emulate a `case` statement. Consider a `case` statement like this:
+    #
+    # ```ruby
+    # case value
+    # when condition then first_return
+    # else second_return
+    # end
+    # ```
+    #
+    # With a Qo branch you would see something like this:
+    #
+    # ```ruby
+    # Qo.match { |m|
+    #   m.when(condition) { first_return }
+    #   m.else { second_return }
+    # }
+    # ```
+    #
+    # The `when` and `else` are the names the branch was "registered" with in
+    # `Qo::PatternMatchers::Branching`. The name becomes the method name that
+    # the associated matcher uses.
+    #
+    # ### Order of Execution
+    #
+    # A branch will execute in the following order:
+    #
+    # ```
+    # value -> precondition ? -> condition ? -> extractor -> destructurer
+    # ```
+    #
+    # Preconditions allow for things like type checks or any static condition
+    # that will remain constant across all matches. Think of them as abstracting
+    # a single condition to guard before the branch continues.
+    #
+    # Conditions are typical Qo matchers, as documented in the README. Upon a
+    # match, the branch will be considered matched and continue on to calling
+    # the associated block function.
+    #
+    # Extractors are used to pull a value out of a container type, such as
+    # `value` for monadic types or `last` for response array tuples.
+    #
+    # Lastly, if given, Destructurers will destructure an object. That means
+    # that the associated function now places great significance on the
+    # names of the arguments as they'll be used to extract values from the
+    # object that would have normally been returned.
+    #
+    # Destructuring can be a complicated topic, see the following article to
+    # find out more on how this works or see the README for examples:
+    #
+    # https://medium.com/rubyinside/destructuring-in-ruby-9e9bd2be0360
+    #
+    # ### Match Tuples
+    #
+    # Branches will respond with a tuple of (status, value). A status of false
+    # indicates a non-match, and a status or true indicates a match. This is done
+    # to ensure that truly `false` or `nil` returns are not swallowed by a
+    # match.
+    #
+    # A Pattern Match will use these statuses to find the first matching branch.
+    #
+    # @author baweaver
+    # @since 1.0.0
+    class Branch
+      # Representation of an unmatched value. These values are wrapped in array
+      # tuples to preserve legitimate `false` and `nil` values by indicating
+      # the status of the match in the first position and the returned value in
+      # the second.
+      UNMATCHED = [false, nil]
+
+      # Name of the branch, see the initializer for more information
+      attr_reader :name
+
+      # Creates an instance of a Branch
+      #
+      # @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 [Qo::Branches::Branch]
+      def initialize(name:, precondition: Any, extractor: IDENTITY, destructure: false, default: false)
+        @name         = name
+        @precondition = precondition.is_a?(Symbol) ? precondition.to_proc : precondition
+        @extractor    = extractor.is_a?(Symbol)    ? extractor.to_proc    : extractor
+        @destructure  = destructure
+        @default      = default
+      end
+
+      # A dynamic creator for new branch types to be made on the fly in programs.
+      # This exists to make new types of pattern matches to suit your own needs.
+      #
+      # Prefer the public API to using this method directly, `Qo.create_branch`,
+      # mostly because it's less typing.
+      #
+      # @see `.initialize` for parameter documentation
+      #
+      # @return [Class]
+      #   new Class to be bound to a constant name, or used anonymously
+      def self.create(name:, precondition: Any, extractor: IDENTITY, destructure: false, default: false)
+        attributes = {
+          name:         name,
+          precondition: precondition,
+          extractor:    extractor,
+          destructure:  destructure,
+          default:      default
+        }
+
+        Class.new(Qo::Branches::Branch) do
+          define_method(:initialize) { super(**attributes) }
+        end
+      end
+
+      # Whether or not this is a default branch
+      #
+      # @return [Boolean]
+      def default?
+        @default
+      end
+
+      # Uses the current configuration of the branch to create a matcher to
+      # be used in a pattern match. The returned proc can be passed a value
+      # that will return back a tuple of `(status, value)` to indicate whether
+      # or not a match was made with this branch.
+      #
+      # @param conditions [#===]
+      #   A set of conditions to run against, typically a `Qo.and` matcher but
+      #   could be anything that happens to respond to `===`.
+      #
+      # @param destructure: false [Boolean]
+      #   Whether or not to run the extracted value through a destructure before
+      #   yielding it to the associated block.
+      #
+      # @param &function [Proc]
+      #   Function to be called if a matcher matches.
+      #
+      # @return [Proc[Any]] [description]
+      def create_matcher(conditions, destructure: @destructure, &function)
+        function ||= IDENTITY
+
+        destructurer = Destructurers::Destructurer.new(
+          destructure: destructure, &function
+        )
+
+        Proc.new { |value|
+          extracted_value = @extractor.call(value)
+
+          # If it's a default branch, return true, as conditions are redundant
+          next [true, destructurer.call(extracted_value)] if @default
+
+          if @precondition === value && conditions === extracted_value
+            [true, destructurer.call(extracted_value)]
+          else
+            UNMATCHED
+          end
+        }
+      end
+    end
+  end
+end

data/lib/qo/branches/branches.rb

@@ -0,0 +1,37 @@
+module Qo
+  # In Qo, a Branch is one of the callable branches in a pattern match. Most
+  # commonly you'll see this expressed in a `where` or `else` branch, named
+  # as such to emulate a `case` statement:
+  #
+  # ```ruby
+  # Qo.match { |m|
+  #   m.when(conditions) { code executed when matched }
+  #   m.else { code executed otherwise }
+  # }
+  # ```
+  #
+  # More documentation on the creation of branches is available in `Branch`
+  #
+  # @see Qo::Branches::Branch
+  #
+  # @author baweaver
+  # @since 1.0.0
+  module Branches
+  end
+end
+
+# Base branch type which defines the interface
+require 'qo/branches/branch'
+
+# The branches you're probably used to with `where` and `else`
+require 'qo/branches/when_branch'
+require 'qo/branches/else_branch'
+
+# Result type matchers for tuples like `[:ok, value]`
+require 'qo/branches/success_branch'
+require 'qo/branches/error_branch'
+require 'qo/branches/failure_branch'
+
+# Monadic matchers to extract values from items
+require 'qo/branches/monadic_when_branch'
+require 'qo/branches/monadic_else_branch'