dry-matcher 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7b7b475f9c2a102c0da7f6cf3422b8553e0f5d2f
-  data.tar.gz: 5c618057052448e4986233291fcadbe794c4b687
+  metadata.gz: 6d10419e259ad298f3f7406069c3abedaf6d0b3a
+  data.tar.gz: 73c64df0c8dcdbfa5729e1788af55c59c464d1ca
 SHA512:
-  metadata.gz: 93a241b0c7fd705e703f6f3b021cbcf19b3ef1f88eeb45605dfcb815daf670ab547e9f306178c8fa8859c0d190de3c13c99d4d6a9a319ee09f84328d744630b5
-  data.tar.gz: 0e3cc0b1df1587600fe864336d84fcbecf94432c363a279c0f0382c96dbd0542ddf0b1d9c5ba63d321e1bc450e44724e13db5dcb561f9ec227dbd154e33f1dda
+  metadata.gz: 7fe5b016af423a72b690fea03bc18f310fca34d580665345096a283cf937ee26c27bac3f0de69d2a279308700b1ddc85e478e70bb8518a194ae79ae2ac692f3b
+  data.tar.gz: 669f02bcb69d4f0c57fb38bdd0534561cf1924c4e2ecdf7cc4bf40fe928e7af585f3b5ee8c7d91799475e3b37565f609b1620c1d192538da3fb96987d42c797b

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+# 0.6.0 / 2016-12-19
+
+## Added
+
+- API documentation for most methods (alsemyonov in [#8](https://github.com/dry-rb/dry-matcher/pull/8))
+
+## Changed
+
+- Matches must now be exhaustive - when matching against a value, at least one match block must be provided for each of a matcher's cases (timriley in [#7](https://github.com/dry-rb/dry-matcher/pull/7))
+- `Dry::Matcher::Case` objects can now be created without a `resolve:` proc. In this case, a default will be provided that passes the result value through (timriley in [#9](https://github.com/dry-rb/dry-matcher/pull/9))
+
+[Compare v0.5.1...v0.6.0](https://github.com/dry-rb/dry-result_matcher/compare/v0.5.1...v0.6.0)
+
+# 0.5.1 / 2016-07-06
+
+## Fixed
+
+- Fixed handling of calls to non-existent cases within a matcher block (timriley)
+
+[Compare v0.5.0...v0.5.1](https://github.com/dry-rb/dry-result_matcher/compare/v0.5.0...v0.5.1)
+
 # 0.5.0 / 2016-06-30
 
 ## Added
@@ -59,6 +80,8 @@
     ```
 - The previous `Dry::ResultMatcher.match` behaviour (for matching `Either` monads) has been moved to `Dry::Matcher::EitherMatcher.call`
 
+[Compare v0.4.0...v0.5.0](https://github.com/dry-rb/dry-result_matcher/compare/v0.4.0...v0.5.0)
+
 # 0.4.0 / 2016-06-08
 
 ## Added

data/Gemfile

@@ -3,7 +3,8 @@ source "https://rubygems.org"
 gemspec
 
 group :test do
-  gem "codeclimate-test-reporter", "~> 0.5.0"
+  gem "simplecov"
+  gem "codeclimate-test-reporter"
   gem "dry-monads", "~> 0.0.2"
 end
 

data/Rakefile

@@ -4,3 +4,7 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new
 
 task default: :spec
+
+require 'yard'
+require 'yard/rake/yardoc_task'
+YARD::Rake::YardocTask.new(:doc)

data/lib/dry/matcher.rb

@@ -2,7 +2,30 @@ require "dry/matcher/case"
 require "dry/matcher/evaluator"
 
 module Dry
+  # @see http://dry-rb.org/gems/dry-matcher
   class Matcher
+    # Generates a module containing pattern matching for methods listed in
+    # `match_methods` argument with behavior defined by `with` matcher
+    #
+    # @param [<Symbol>] match_methods
+    # @param [Dry::Matcher] with
+    # @return [Module]
+    #
+    # @example Usage with `dry-monads`
+    #   class MonadicOperation
+    #     include Dry::Matcher.for(:call, with: Dry::Matcher::EitherMatcher)
+    #
+    #     def call
+    #       Dry::Monads::Either::Right.new('Success')
+    #     end
+    #   end
+    #
+    #   operation = MonadicOperation.new
+    #
+    #   operation.call do |m|
+    #     m.success { |v| "#{v} was successful!"}
+    #     m.failure { |v| "#{v} has failed!"}
+    #   end #=> "Success was successful"
     def self.for(*match_methods, with:)
       matcher = with
 
@@ -29,12 +52,33 @@ module Dry
       end
     end
 
+    # @return [Hash{Symbol => Case}]
     attr_reader :cases
 
+    # @param [Hash{Symbol => Case}] cases
     def initialize(cases = {})
       @cases = cases
     end
 
+    # Evaluate {#cases}' matchers and returns a result of block given to
+    # corresponding case matcher
+    #
+    # @param [Object] result value that would be tested for matches with given {#cases}
+    # @param [Object] block
+    # @yieldparam [Evaluator] m
+    # @return [Object] value returned from the block given to method called
+    #   after matched pattern
+    #
+    # @example Usage with `dry-monads`
+    #   require 'dry-monads'
+    #   require 'dry/matcher/either_matcher'
+    #
+    #   value = Dry::Monads::Either::Left.new('failure!')
+    #
+    #   Dry::Matcher::EitherMatcher.(value) do |m|
+    #     m.success { |v| "Yay: #{v}" }
+    #     m.failure { |v| "Boo: #{v}" }
+    #   end #=> "Boo: failure!"
     def call(result, &block)
       Evaluator.new(result, cases).call(&block)
     end

data/lib/dry/matcher/case.rb

@@ -1,15 +1,33 @@
 module Dry
   class Matcher
+    # {Case} object contains logic for pattern matching and resolving result
+    # from matched pattern
     class Case
-      def initialize(match:, resolve:)
+      DEFAULT_RESOLVE = -> result { result }
+
+      # @param match [#call] callable used to test given pattern against value
+      # @param resolve [#call] callable used to resolve value into a result
+      def initialize(match:, resolve: DEFAULT_RESOLVE)
         @match = match
         @resolve = resolve
       end
 
+      # Tests whether `value` (with optional `*pattern`) matches pattern using
+      # callable given to {#initialize} as `match:` argument
+      #
+      # @param [Object] value
+      # @param [<Object>] pattern optional pattern given after the `value` to
+      #   `match:` callable
+      # @return [Boolean]
       def matches?(value, *pattern)
         @match.(value, *pattern)
       end
 
+      # Resolves result from `value` using callable given to {#initialize}
+      # as `resolve:` argument
+      #
+      # @param [Object] value
+      # @return [Object] result resolved from given `value`
       def resolve(value)
         @resolve.(value)
       end

data/lib/dry/matcher/either_matcher.rb

@@ -2,6 +2,52 @@ require "dry/matcher"
 
 module Dry
   class Matcher
+    # Built-in {Matcher} ready to use with `Either` or `Try` monads from
+    # [dry-monads](/gems/dry-monads) or any other compatible gems.
+    #
+    # Provides {Case}s for two matchers:
+    # * `:success` matches `Dry::Monads::Either::Right`
+    #   and `Dry::Monads::Try::Success` (or any other monad that responds to
+    #   `#to_either` returning either monad that is `#right?`)
+    # * `:failure` matches `Dry::Monads::Either::Left` and
+    #   `Dry::Monads::Try::Failure` (or any other monad that responds to
+    #   `#to_either` returning either monad that is `#left?`)
+    #
+    # @return [Dry::Matcher]
+    #
+    # @example Usage with `dry-monads`
+    #   require 'dry-monads'
+    #   require 'dry/matcher/either_matcher'
+    #
+    #   value = Dry::Monads::Either::Right.new('success!')
+    #
+    #   Dry::Matcher::EitherMatcher.(value) do |m|
+    #     m.success do |v|
+    #       "Yay: #{v}"
+    #     end
+    #
+    #     m.failure do |v|
+    #       "Boo: #{v}"
+    #     end
+    #   end #=> "Yay: success!"
+    #
+    # @example Usage with custom monad
+    #   require 'dry/matcher/either_matcher'
+    #
+    #   class CustomBooleanMonad
+    #     def initialize(value); @value = value; end
+    #     attr_reader :value
+    #     alias_method :right?, :value
+    #     def left?; !right?; end
+    #     def to_either; self; end
+    #   end
+    #
+    #   value = CustomBooleanMonad.new(nil)
+    #
+    #   Dry::Matcher::EitherMatcher.(value) do |m|
+    #     m.success { |v| "#{v.inspect} is truthy" }
+    #     m.failure { |v| "#{v.inspect} is falsey" }
+    #   end # => "nil is falsey"
     EitherMatcher = Dry::Matcher.new(
       success: Case.new(
         match: -> result, *pattern {

data/lib/dry/matcher/evaluator.rb

@@ -1,30 +1,67 @@
 module Dry
   class Matcher
+    NonExhaustiveMatchError = Class.new(StandardError)
+
+    # {Evaluator} is used in {Dry::Matcher#call Dry::Matcher#call} block to handle different {Case}s
     class Evaluator < BasicObject
+      # @param [Object] result
+      # @param [Hash{Symbol => Case}] cases
       def initialize(result, cases)
         @cases = cases
         @result = result
+
+        @unhandled_cases = @cases.keys.map(&:to_sym)
         @matched = false
         @output = nil
       end
 
       def call
         yield self
+
+        ensure_exhaustive_match
+
         @output
       end
 
+      # Checks whether `cases` given to {#initialize} contains one called `name`
+      # @param [String] name
+      # @param [Boolean] include_private
+      # @return [Boolean]
       def respond_to_missing?(name, include_private = false)
-        @cases.key?(name) || super
+        @cases.key?(name)
       end
 
+      # Handles method `name` called after one of the keys in `cases` hash given
+      # to {#initialize}
+      #
+      # @param [String] name name of the case given to {#initialize} in `cases`
+      #   argument
+      # @param [Array] args pattern that would be tested for match and used to
+      #   resolve result
+      # @param [#call] block callable that will processes resolved value
+      #   from matched pattern
+      # @yieldparam [Object] v resolved value
+      # @return [Object] result of calling `block` on value resolved from `args`
+      #   if `args` pattern was matched by the given case called `name`
+      # @raise [NoMethodError] if there was no case called `name` given to
+      #   {#initialize} in `cases` hash
       def method_missing(name, *args, &block)
         return super unless @cases.key?(name)
 
+        @unhandled_cases.delete name
         handle_case @cases[name], *args, &block
       end
 
       private
 
+      def ensure_exhaustive_match
+        if @unhandled_cases.any?
+          ::Kernel.raise NonExhaustiveMatchError, "cases +#{@unhandled_cases.join(', ')}+ not handled"
+        end
+      end
+
+      # @param [Case] kase
+      # @param [Array] pattern
       def handle_case(kase, *pattern)
         return @output if @matched
 

data/lib/dry/matcher/version.rb

@@ -1,5 +1,5 @@
 module Dry
   class Matcher
-    VERSION = "0.5.0".freeze
+    VERSION = "0.6.0".freeze
   end
 end

data/spec/examples.txt

@@ -1,14 +1,18 @@
 example_id                                            | status | run_time        |
 ----------------------------------------------------- | ------ | --------------- |
-./spec/integration/class_enhancement_spec.rb[1:1:1:1] | passed | 0.00016 seconds |
-./spec/integration/class_enhancement_spec.rb[1:1:2:1] | passed | 0.00013 seconds |
-./spec/integration/class_enhancement_spec.rb[1:2:1:1] | passed | 0.00022 seconds |
-./spec/integration/class_enhancement_spec.rb[1:2:2:1] | passed | 0.00141 seconds |
-./spec/integration/either_matcher_spec.rb[1:1:1:1]    | passed | 0.00008 seconds |
-./spec/integration/either_matcher_spec.rb[1:1:2:1]    | passed | 0.00008 seconds |
-./spec/integration/either_matcher_spec.rb[1:1:3:1:1]  | passed | 0.00015 seconds |
-./spec/integration/either_matcher_spec.rb[1:1:3:2:1]  | passed | 0.00016 seconds |
-./spec/integration/matcher_spec.rb[1:1:1]             | passed | 0.00013 seconds |
-./spec/integration/matcher_spec.rb[1:1:2]             | passed | 0.00012 seconds |
-./spec/integration/matcher_spec.rb[1:1:3:1]           | passed | 0.00015 seconds |
-./spec/integration/matcher_spec.rb[1:1:3:2]           | passed | 0.00224 seconds |
+./spec/integration/class_enhancement_spec.rb[1:1:1:1] | passed | 0.00015 seconds |
+./spec/integration/class_enhancement_spec.rb[1:1:2:1] | passed | 0.00014 seconds |
+./spec/integration/class_enhancement_spec.rb[1:2:1:1] | passed | 0.00088 seconds |
+./spec/integration/class_enhancement_spec.rb[1:2:2:1] | passed | 0.00013 seconds |
+./spec/integration/either_matcher_spec.rb[1:1:1:1]    | passed | 0.00011 seconds |
+./spec/integration/either_matcher_spec.rb[1:1:2:1]    | passed | 0.0001 seconds  |
+./spec/integration/either_matcher_spec.rb[1:1:3:1:1]  | passed | 0.00016 seconds |
+./spec/integration/either_matcher_spec.rb[1:1:3:2:1]  | passed | 0.00015 seconds |
+./spec/integration/matcher_spec.rb[1:1:1]             | passed | 0.00016 seconds |
+./spec/integration/matcher_spec.rb[1:1:2]             | passed | 0.00015 seconds |
+./spec/integration/matcher_spec.rb[1:1:3]             | passed | 0.00159 seconds |
+./spec/integration/matcher_spec.rb[1:1:4:1]           | passed | 0.00018 seconds |
+./spec/integration/matcher_spec.rb[1:1:4:2]           | passed | 0.00185 seconds |
+./spec/unit/case_spec.rb[1:1:1]                       | passed | 0.00054 seconds |
+./spec/unit/case_spec.rb[1:2:1]                       | passed | 0.00048 seconds |
+./spec/unit/case_spec.rb[1:2:2]                       | passed | 0.00008 seconds |

data/spec/integration/matcher_spec.rb

@@ -45,7 +45,24 @@ RSpec.describe Dry::Matcher do
       expect(call_match(input)).to eq "Failure: No!"
     end
 
+    it "requires an exhaustive match" do
+      input = Dry::Monads::Right("Yes!")
+
+      expect {
+        matcher.(input) do |m|
+          m.success { |v| "Success: #{v}" }
+        end
+      }.to raise_error Dry::Matcher::NonExhaustiveMatchError
+    end
+
     context "with patterns" do
+      let(:success_case) {
+        Dry::Matcher::Case.new(
+          match: -> result { result.first == :ok },
+          resolve: -> result { result.last },
+        )
+      }
+
       let(:failure_case) {
         Dry::Matcher::Case.new(
           match: -> result, failure_type {
@@ -57,6 +74,8 @@ RSpec.describe Dry::Matcher do
 
       def call_match(input)
         matcher.(input) do |m|
+          m.success
+
           m.failure :my_error do |v|
             "Pattern-matched failure: #{v}"
           end

data/spec/spec_helper.rb

@@ -1,12 +1,9 @@
-if RUBY_ENGINE == "ruby"
-  require "codeclimate-test-reporter"
-  CodeClimate::TestReporter.start
-
-  SimpleCov.start do
-    add_filter "/spec/"
-  end
+if RUBY_ENGINE == "ruby" && RUBY_VERSION >= "2.3"
+  require "simplecov"
+  SimpleCov.start
 end
 
+
 begin
   require "byebug"
 rescue LoadError; end

data/spec/unit/case_spec.rb

@@ -0,0 +1,22 @@
+RSpec.describe Dry::Matcher::Case do
+  describe "#matches?" do
+    it "calls the match proc with the value" do
+      kase = described_class.new(match: -> value { value.even? })
+      expect(kase.matches?(2)).to be true
+      expect(kase.matches?(1)).to be false
+    end
+  end
+
+  describe "#resolve" do
+    it "calls the resolve proc with the value" do
+      kase = described_class.new(match: -> * { true }, resolve: resolve = -> value { value.to_s })
+
+      expect(kase.resolve(123)).to eq "123"
+    end
+
+    it "defaults to passing through the value" do
+      kase = described_class.new(match: -> * { true })
+      expect(kase.resolve(123)).to eq 123
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dry-matcher
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Tim Riley
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-30 00:00:00.000000000 Z
+date: 2016-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -103,6 +103,7 @@ files:
 - spec/integration/either_matcher_spec.rb
 - spec/integration/matcher_spec.rb
 - spec/spec_helper.rb
+- spec/unit/case_spec.rb
 homepage: http://dry-rb.org/gems/dry-matcher
 licenses:
 - MIT