diff_matcher 2.3.3 → 2.4.0

data/.gitignore

@@ -1,3 +1,4 @@
 coverage
 pkg
 Gemfile.lock
+.rvmrc

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+### v2.4.0
+
+  Add class configuration of Difference from a block
+
 ### v2.3.3
 
   Allow HTML output using `:html_output=>true` option

data/README.md

@@ -4,27 +4,30 @@ DiffMatcher
 [![build status](http://travis-ci.org/playup/diff_matcher.png)](http://travis-ci.org/playup/diff_matcher)
 [![still maintained](http://stillmaintained.com/playupchris/diff_matcher.png)](http://stillmaintained.com/playupchris/diff_matcher)
 
-Generates a diff by matching against expected values, classes, regexes and/or procs.
+Generates a diff by matching against user-defined matchers written in ruby.
 
-DiffMatcher performs recursive matches on values contained in hashes, arrays and combinations thereof.
+DiffMatcher matches input data (eg. from a JSON API) against values,
+ranges, classes, regexes, procs, custom matchers and/or easily composed,
+nested combinations thereof to produce an easy to read diff string.
 
-Values in a containing object match when:
+Actual input values are matched against expected matchers in the following way:
 
 ``` ruby
 actual.is_a? expected  # when expected is a class
 expected.match actual  # when expected is a regexp
 expected.call actual   # when expected is a proc
 actual == expected     # when expected is anything else
+expected.diff actual   # when expected is a built-in DiffMatcher
 ```
 
-Example:
+Using these building blocks, more complicated nested matchers can be
+composed.
+eg.
 
 ``` ruby
-puts DiffMatcher::difference(
-  { :a=>{ :a1=>11          }, :b=>[ 21, 22 ], :c=>/\d/, :d=>Fixnum, :e=>lambda { |x| (4..6).include? x } },
-  { :a=>{ :a1=>10, :a2=>12 }, :b=>[ 21     ], :c=>'3' , :d=>4     , :e=>5                                },
-  :color_scheme=>:white_background
-)
+expected = { :a=>{ :a1=>11          }, :b=>[ 21, 22 ], :c=>/\d/, :d=>Fixnum, :e=>lambda { |x| (4..6).include? x } },
+actual   = { :a=>{ :a1=>10, :a2=>12 }, :b=>[ 21     ], :c=>'3' , :d=>4     , :e=>5                                },
+puts DiffMatcher::difference(expected, actual, :color_scheme=>:white_background)
 ```
 
 ![example output](https://raw.github.com/playup/diff_matcher/master/doc/diff_matcher.gif)
@@ -42,191 +45,234 @@ Usage
 ``` ruby
 require 'diff_matcher'
 
-DiffMatcher::difference(actual, expected, opts={})
+DiffMatcher::difference(expected, actual, opts={})
 ```
 
-When `expected` != `actual`
+#### Simple matchers
 
-``` ruby
-puts DiffMatcher::difference(1, 2)
-# => - 1+ 2
-# => Where, - 1 missing, + 1 additional
+Using plain ruby objects produces the following diffs:
+```
++-------------+--------+-------------+
+| expected    | actual | diff        |
++-------------+--------+-------------+
+| 1           | 2      | - 1+ 2      |
+| 1           | 1      |             |
+| String      | 1      | - String+ 1 |
+| String      | "1"    |             |
+| /[a-z]/     | 1      | -/[a-z]/+ 1 |
+| /[a-z]/     | "a"    |             |
+| 1..3        | 4      | - 1..3+ 4   |
+| 1..3        | 3      |             |
+| is_boolean  | true   |             |
++-------------+--------+-------------+
+
+Where:
+  is_boolean = lambda { |x| [FalseClass, TrueClass].include? x.class }
 ```
 
-When `expected` == `actual`
+When `actual` is missing one of the `expected` values
 
 ``` ruby
-p DiffMatcher::difference(1, 1)
-# => nil
+expected = [1, 2]
+puts DiffMatcher::difference(expected, [1])
+# => [
+# =>   1
+# => - 2
+# => ]
+# => Where, - 1 missing
 ```
 
-When `actual` is an instance of the `expected`
+When `actual` has additional values to the `expected`
 
 ``` ruby
-p DiffMatcher::difference(String, '1')
-# => nil
+expected = [1]
+puts DiffMatcher::difference(expected, [1, 2])
+# => [
+# =>   1
+# => + 2
+# => ]
+# => Where, + 1 additional
 ```
 
-When `actual` is a string that matches the `expected` regex
+
+#### More complicated matchers
+
+Sometimes you'll need to wrap plain ruby objects with DiffMatcher's
+built-in matchers, to provide extra matching abilities.
+
+When `expected` is a `Hash`, but has optional keys, wrap the `Hash` with
+a built-in `Matcher`
 
 ``` ruby
-p DiffMatcher::difference(/[a-z]/, "a")
-# => nil
+exp = {:name=>String, :age=>Fixnum}
+expected = DiffMatcher::Matcher.new(exp, :optional_keys=>[:age])
+puts DiffMatcher::difference(expected, {:name=>0})
+# => {
+# =>   :name=>- String+ 0
+# => }
+# => Where, - 1 missing, + 1 additional
 ```
 
-When `actual` is a fixnum that matches the `expected` range
+When multiple `expected` values can be matched against, simply wrap them
+in `Matcher`s and `||` them together
 
 ``` ruby
-p DiffMatcher::difference(1..3, 3)
-# => nil
+exp1 = Fixnum
+exp2 = Float
+expected = DiffMatcher::Matcher.new(exp1) || DiffMatcher::Matcher.new(exp2)
+puts DiffMatcher::difference(expected, "3")
+# => - Float+ "3"
+# => Where, - 1 missing, + 1 additional
 ```
 
-When `actual` is passed to an `expected` proc and it returns true
+Or to do the same thing using a shorter syntax
 
 ``` ruby
-is_boolean = lambda { |x| [FalseClass, TrueClass].include? x.class }
-p DiffMatcher::difference(is_boolean, true)
-# => nil
+exp1 = Fixnum
+exp2 = Float
+expected = DiffMatcher::Matcher[exp1, exp2]
+puts DiffMatcher::difference(expected, "3")
+# => - Float+ "3"
+# => Where, - 1 missing, + 1 additional
 ```
 
-When `actual` is missing one of the `expected` values
+When `actual` is an array of *unknown* size use an `AllMatcher` to match
+against *all* the elements in the array
 
 ``` ruby
-puts DiffMatcher::difference([1, 2], [1])
+exp = Fixnum
+expected = DiffMatcher::AllMatcher.new(exp)
+puts DiffMatcher::difference(expected, [1, 2, "3"])
 # => [
-# =>   1
-# => - 2
+# =>   : 1,
+# =>   : 2,
+# =>   - Fixnum+ "3"
 # => ]
-# => Where, - 1 missing
+# => Where, - 1 missing, + 1 additional, : 2 match_class
 ```
 
-When `actual` has additional values to the `expected`
+
+When `actual` is an array with a *limited* size use an `AllMatcher` to match
+against *all* the elements in the array adhering to the limits of `:min`
+and or `:max` or `:size` (where `:size` is a Fixnum or range of Fixnum).
 
 ``` ruby
-puts DiffMatcher::difference([1], [1, 2])
+exp = Fixnum
+expected = DiffMatcher::AllMatcher.new(exp, :min=>3)
+puts DiffMatcher::difference(expected, [1, 2])
 # => [
-# =>   1
-# => + 2
+# =>   : 1,
+# =>   : 2,
+# =>   - Fixnum
 # => ]
-# => Where, + 1 additional
+# => Where, - 1 missing, : 2 match_class
 ```
 
-
-When `expected` is a `Hash` with optional keys use a `Matcher`.
-
 ``` ruby
-puts DiffMatcher::difference(
-  DiffMatcher::Matcher.new({:name=>String, :age=>Fixnum}, :optional_keys=>[:age]),
-  {:name=>0}
-)
-{
-  :name=>- String+ 0
-}
-Where, - 1 missing, + 1 additional
+exp = Fixnum
+expected = DiffMatcher::AllMatcher.new(exp, :size=>3..5)
+puts DiffMatcher::difference(expected, [1, 2])
+# => [
+# =>   : 1,
+# =>   : 2,
+# =>   - Fixnum
+# => ]
+# => Where, - 1 missing, : 2 match_class
 ```
 
-
-When `expected` can take multiple forms use some `Matcher`s `||`ed together.
+When `actual` is an array of unknown size *and* `expected` can take
+multiple forms use a `Matcher` to `||` them together, then wrap that
+with an `AllMatcher` to match against *all* the elements in the array in
+any of the forms.
 
 ``` ruby
-puts DiffMatcher::difference(DiffMatcher::Matcher.new(Fixnum) || DiffMatcher.new(Float), "3")
-- Float+ "3"
-Where, - 1 missing, + 1 additional
+exp1 = Fixnum
+exp2 = Float
+expected = DiffMatcher::AllMatcher.new( DiffMatcher::Matcher[Fixnum, Float] )
+puts DiffMatcher::difference(expected, [1, 2.00, "3"])
+# => [
+# =>   | 1,
+# =>   | 2.0,
+# =>   - Float+ "3"
+# => ]
+# => Where, - 1 missing, + 1 additional, | 2 match_matcher
 ```
-(NB. `DiffMatcher::Matcher[Fixnum, Float]` can be used as a shortcut for 
-     `DiffMatcher::Matcher.new(Fixnum) || DiffMatcher.new(Float)`
-)
 
+### Matcher options
 
-When `actual` is an array of *unknown* size use an `AllMatcher` to match
-against *all* the elements in the array.
+Matcher options can be passed to `DiffMatcher::difference` or `DiffMatcher::Matcher#diff`
+or instances of `DiffMatcher::Matcher`
+
+First consider:
 
 ``` ruby
-puts DiffMatcher::difference(DiffMatcher::AllMatcher.new(Fixnum), [1, 2, "3"])
-[
-  : 1,
-  : 2,
-  - Fixnum+ "3"
-]
-Where, - 1 missing, + 1 additional, : 2 match_class
+expected = DiffMatcher::Matcher.new([1])
+puts expected.diff([1, 2])
+# => [
+# =>   1,
+# => + 2
+# => ]
 ```
 
+Using `:ignore_additional=>true` will now match even though `actual` has additional items.
 
-When `actual` is an array with a *limited* size use an `AllMatcher` to match
-against *all* the elements in the array adhering to the limits of `:min`
-and or `:max` or `:size` (where `:size` is a Fixnum or range of Fixnum).
+It can be used in the following ways:
 
 ``` ruby
-puts DiffMatcher::difference(DiffMatcher::AllMatcher.new(Fixnum, :min=>3), [1, 2])
-[
-  : 1,
-  : 2,
-  - Fixnum
-]
-Where, - 1 missing, : 2 match_class
+expected = DiffMatcher::Matcher.new([1])
+puts expected.diff([1, 2], :ignore_additional=>true)
+# => nil
 ```
 
+or
+
 ``` ruby
-puts DiffMatcher::difference(DiffMatcher::AllMatcher.new(Fixnum, :size=>3..5), [1, 2])
-[
-  : 1,
-  : 2,
-  - Fixnum
-]
-Where, - 1 missing, : 2 match_class
+expected = DiffMatcher::Matcher.new([1])
+puts DiffMatcher::difference(expected, [1, 2], :ignore_additional=>true)
+# => nil
 ```
 
-When `actual` is an array of unknown size *and* `expected` can take
-multiple forms use a `Matcher` inside of an `AllMatcher` to match
-against *all* the elements in the array in any of the forms.
+or
 
 ``` ruby
-puts DiffMatcher::difference(
-  DiffMatcher::AllMatcher.new(
-    DiffMatcher::Matcher[Fixnum, Float]
-  ),
-  [1, 2.00, "3"]
-)
-[
-  | 1,
-  | 2.0,
-  - Float+ "3"
-]
-Where, - 1 missing, + 1 additional, | 2 match_matcher
+expected = DiffMatcher::Matcher.new([1], :ignore_additional=>true)
+puts expected.diff([1, 2])
+# => nil
 ```
 
-### Options
-
-`:ignore_additional=>true` will match even if `actual` has additional items
+Now consider:
 
 ``` ruby
-p DiffMatcher::difference([1], [1, 2], :ignore_additional=>true)
-# => nil
+puts DiffMatcher::Matcher.new([Fixnum, 2]).diff([1])
+# => [
+# =>   : 1,
+# => - 2
+# => ]
 ```
 
-`:quiet=>true` shows only missing and additional items in the output
-
+Using `:quiet=>true` will only show missing and additional items in the output
 ``` ruby
-puts DiffMatcher::difference([Fixnum, 2], [1], :quiet=>true)
+puts DiffMatcher::Matcher.new([Fixnum, 2]).diff([1], :quiet=>true)
 # => [
 # => - 2
 # => ]
-# => Where, - 1 missing
 ```
 
-`:html_output=>true` will convert ansii escape codes to html spans
+`:html_output=>true` will convert ansii escape colour codes to html spans
 
 ``` ruby
 puts DiffMatcher::difference(1, 2, :html_output=>true)
-<pre>
-<span style="color:red">- <b>1</b></span><span style="color:yellow">+ <b>2</b></span>
-Where, <span style="color:red">- <b>1 missing</b></span>, <span style="color:yellow">+ <b>1 additional</b></span>
-</pre>
+# => <pre>
+# => <span style="color:red">- <b>1</b></span><span style="color:yellow">+ <b>2</b></span>
+# => Where, <span style="color:red">- <b>1 missing</b></span>, <span style="color:yellow">+ <b>1 additional</b></span>
+# => </pre>
 ```
 
 #### Prefixes
 
-The items shown in a difference are prefixed as follows:
+A difference string is similar in appereance to the `.inspect` of plain
+ruby objects, however the matched elements it contains are prefixed
+in the following way:
 
     missing       => "- "
     additional    => "+ "
@@ -376,13 +422,14 @@ Finished in 0.00601 seconds
 Contributing
 ---
 
-Fork, write some tests and send a pull request (bonus points for topic branches).
+Think up something DiffMatcher *can't* do!  :)
+Fork, write some tests and send a pull request (bonus points for topic branches), or just submit an issue.
 
 
 Status
 ---
 
-Our company is using this gem to test our JSON API which has got it to a stable v1.0.0 release.
+Our company is using this gem to test our JSON API which has got above and beyond a stable v1.0.0 release.
 
 There's a [pull request](http://github.com/rspec/rspec-expectations/pull/79) to use this gem in a `be_hash_matching` 
 [rspec matcher](https://www.relishapp.com/rspec/rspec-expectations).

data/diff_matcher.gemspec

@@ -11,16 +11,11 @@ Gem::Specification.new do |s|
   s.email         = "chris@playup.com"
   s.homepage      = "http://github.com/playup/diff_matcher"
 
-  s.summary       = %q{Generates a diff by matching against expected values, classes, regexes and/or procs.}
+  s.summary       = %q{Generates a diff by matching against user-defined matchers written in ruby.}
   s.description   = <<EOF
-DiffMatcher performs recursive matches on values contained in hashes, arrays and combinations thereof.
-
-Values in a containing object match when:
-
-    - actual == expected
-    - actual.is_a? expected  # when expected is a class
-    - expected.match actual  # when expected is a regexp
-    - expected.call actual   # when expected is a proc
+DiffMatcher matches input data (eg. from a JSON API) against values,
+ranges, classes, regexes, procs, custom matchers and/or easily composed,
+nested combinations thereof to produce an easy to read diff string.
 EOF
 
   s.files         = `git ls-files`.split("\n")

data/lib/diff_matcher/difference.rb

@@ -48,7 +48,6 @@ module DiffMatcher
     end
   end
 
-  class NotAnArray < Exception; end
   class AllMatcher < Matcher
     def expected(e, actual)
       opts = expected_opts(e)
@@ -109,9 +108,17 @@ module DiffMatcher
         @color_scheme = color_schemes[value]
       end
 
+      def color_enabled=(value)
+        @color_enabled = value
+      end
+
       def color_enabled
         @color_enabled.nil? ? !!@color_scheme : @color_enabled
       end
+
+      def configure(&block)
+        block.call(self)
+      end
     end
 
     def initialize(expected, actual, opts={})

data/lib/diff_matcher/version.rb

@@ -1,3 +1,3 @@
 module DiffMatcher
-  VERSION = "2.3.3"
+  VERSION = "2.4.0"
 end

data/spec/diff_matcher/difference_spec.rb

@@ -751,6 +751,27 @@ describe "DiffMatcher::difference(expected, actual, opts)" do
       end
     end
 
+    describe "it shows matches in color when color is configured in Difference" do
+      before do
+        DiffMatcher::Difference.configure do |config|
+          config.color_enabled = true
+        end
+      end
+
+      it_behaves_like "a diff matcher", expected, same, different,
+        <<-EOF
+        \e[0m[
+        \e[0m  \e[31m- \e[1m1\e[0m\e[35m+ \e[1m0\e[0m,
+        \e[0m  2,
+        \e[0m  \e[32m~ \e[0m"\e[32m(\e[1m3\e[0m\e[32m)\e[0m"\e[0m,
+        \e[0m  \e[34m: \e[1m4\e[0m,
+        \e[0m  \e[36m. \e[1m5\e[0m,
+        \e[0m  \e[36m{ \e[1m6\e[0m
+        \e[0m]
+        Where, \e[31m- \e[1m1 missing\e[0m, \e[35m+ \e[1m1 additional\e[0m, \e[32m~ \e[1m1 match_regexp\e[0m, \e[34m: \e[1m1 match_class\e[0m, \e[36m. \e[1m1 match_range\e[0m, \e[36m{ \e[1m1 match_proc\e[0m
+        EOF
+    end
+
     describe "it shows matches in html" do
       it_behaves_like "a diff matcher", expected, same, different,
         <<-EOF , :color_scheme => :white_background, :html_output=>true

metadata

@@ -1,27 +1,31 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: diff_matcher
-version: !ruby/object:Gem::Version
-  version: 2.3.3
+version: !ruby/object:Gem::Version 
   prerelease: 
+  version: 2.4.0
 platform: ruby
-authors:
+authors: 
 - Playup
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-08-03 00:00:00.000000000 +10:00
-default_executable: 
+
+date: 2012-08-05 00:00:00 Z
 dependencies: []
-description: ! "DiffMatcher performs recursive matches on values contained in hashes,
-  arrays and combinations thereof.\n\nValues in a containing object match when:\n\n
-  \   - actual == expected\n    - actual.is_a? expected  # when expected is a class\n
-  \   - expected.match actual  # when expected is a regexp\n    - expected.call actual
-  \  # when expected is a proc\n"
+
+description: |
+  DiffMatcher matches input data (eg. from a JSON API) against values,
+  ranges, classes, regexes, procs, custom matchers and/or easily composed,
+  nested combinations thereof to produce an easy to read diff string.
+
 email: chris@playup.com
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - .gitignore
 - .rspec
 - .travis.yml
@@ -40,33 +44,35 @@ files:
 - lib/diff_matcher/version.rb
 - spec/diff_matcher/difference_spec.rb
 - spec/spec_helper.rb
-has_rdoc: true
 homepage: http://github.com/playup/diff_matcher
 licenses: []
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-      segments:
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: -1395308355013142327
+      segments: 
       - 0
-      hash: 1047575201
-required_rubygems_version: !ruby/object:Gem::Requirement
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
 requirements: []
+
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.21
 signing_key: 
 specification_version: 3
-summary: Generates a diff by matching against expected values, classes, regexes and/or
-  procs.
+summary: Generates a diff by matching against user-defined matchers written in ruby.
 test_files: []
+