xmatch 0.2.0 → 0.2.1

data/README.markdown

@@ -1,7 +1,7 @@
 XMatch
 ==============
 
-XMatch is a Ruby library for comparing two XML documents and reporting on mismatches. An XML document will match another if:
+XMatch is a Ruby library for comparing two XML documents and reporting on matches and mismatches. An XML document will match another if:
 
 * elements have the same name
 * elements have the same number of children
@@ -14,24 +14,38 @@ XMatch uses Nokogiri for xml parsing.
 
 Matching XML
 ------------
-Given two XML documents as strings, XMatch is run by:
+Given two XML documents as strings (or Nokogiri Documents), XMatch is run by:
 
-	xml = Matcher::Xml.new(lhs)
-	xml.match(rhs)
+	matcher = Matcher::Xml.new(expected)
+	matcher.match(actual)
 
 A matcher provides access to the match information by xpath values:
 
-	xml.matches
-	xml.mismatches
+	matcher.matches
+	matcher.mismatches
 
 Custom matchers
 ---------------
-The actual values of some xml elements are hard to know in advance (timestamps and ids being typical examples). XMatch allows custom matchers to be applied
-to provide a good guess at a match in advance of the match being run. Custom matchers are predicates provided as Ruby Procs, identified by the xpath of the element they should be applied to.
+The actual values of some xml elements are hard to know in advance (timestamps and id's being typical examples). XMatch allows custom matchers to be applied
+to provide a good guess at a match in advance of the match being run. Custom matchers are predicates provided as Ruby Procs, identified by the xpath of the element they should be applied to. They can be applied to text and attribute values.
 
-	xml = Matcher::Xml.new("<bookstore id='1'></bookstore>")
-	xml.match_on("/bookstore/@id") { |actual| actual =~ /\d+/ }
-	xml.match("<bookstore id='2'></bookstore>") # ==> true
+	matcher = Matcher::Xml.new("<bookstore id='1'></bookstore>")
+	matcher.on("/bookstore/@id") { |actual| actual =~ /\d+/ }
+	matcher.match("<bookstore id='2'></bookstore>") # ==> true
+	
+An alternate syntax allows a pattern to be excluded from the match.  This is useful if values are mostly matching but differ by a pattern that cannot be known in advance (e.g. id's):
+
+    matcher = Matcher::Xml.new("<book>This is book 123</book>")
+	matcher.on("/book/text()", :excluding => /\d{3}$/)
+	matcher.match("<book>This is book 456</book>") # ==> true
+
+will exclude the first three digits from the actual match. A single capture group used in the pattern:
+
+	matcher = Matcher::Xml.new("<book>Book 123 is here</book>")
+	matcher.on("/book/text()", :excluding => /\.*s(\d{3,6})\s.*/)
+	matcher.match("<book>Book 123456 is here</book>") # ==> true
+	
+will exclude only the matching capture.
 
 Formatting match results
 ------------------------
@@ -50,4 +64,4 @@ XMatch is packaged as a Gem.  Install with:
 Copyright
 ---------
 
-Copyright (c) 2009 Peter Moran. See LICENSE for details.
+Copyright (c) 2010 Peter Moran. See LICENSE for details.

data/Rakefile

@@ -10,7 +10,6 @@ require "spec/rake/spectask"
 Spec::Rake::SpecTask.new(:spec) do |spec|
   spec.libs << 'lib' << 'spec'
   spec.spec_files = FileList['spec/**/*_spec.rb']
-  # spec.spec_opts << "-Du"
   spec.spec_opts << "--color"
 end
 

data/lib/matcher/nokogiri_extensions.rb

@@ -5,19 +5,16 @@ module Nokogiri
   module XML
 
     class Node
-      
+
+      def match?(other, matcher)
+        matching(other, matcher) ? true : false
+      end
+
       def matching(other, matcher)
         other_elem = other.at_xpath(path)
         matcher.record(self.path, false, Matcher::Xml::EXISTENCE, Matcher::Xml::NOT_FOUND) unless other_elem
         other_elem
       end
-    end
-
-    class Document
-
-      def match?(other, matcher)
-        matching(other, matcher)
-      end
 
     end
 
@@ -25,8 +22,7 @@ module Nokogiri
 
       def match?(other, matcher)
         @matcher = matcher
-        other_elem = matching(other, matcher)
-        return false unless other_elem
+        return false unless other_elem = matching(other, matcher)
         children_match?(other_elem) & attributes_match?(other_elem)
       end
 
@@ -54,14 +50,8 @@ module Nokogiri
     class Text
 
       def match?(other, matcher)
-        @matcher = matcher
-        other_elem = matching(other, matcher)
-        return false unless other_elem
-
-        custom_matcher = matcher.custom_matchers[path]
-        match = custom_matcher ? custom_matcher.call(other_elem.content) : (content == other_elem.content)
-        @matcher.record(self.path, match, content, other_elem.content)
-        match
+        return false unless other_elem = matching(other, matcher)
+        matcher.evaluate(path, content, other_elem.content)
       end
 
     end
@@ -69,13 +59,8 @@ module Nokogiri
     class Attr
 
       def match?(other, matcher)
-        other_elem = matching(other, matcher)
-        return false unless other_elem
-
-        custom_matcher = matcher.custom_matchers[path]
-        match = custom_matcher ? custom_matcher.call(other_elem.value) : (value == other_elem.value)
-        matcher.record(self.path, match, value, other_elem.value)
-        match
+        return false unless other_elem = matching(other, matcher)
+        matcher.evaluate(path, value, other_elem.value)
       end
 
     end

data/lib/matcher/version.rb

@@ -1,3 +1,3 @@
 module Representative
-  VERSION = "0.2.0".freeze
+  VERSION = "0.2.1".freeze
 end

data/lib/matcher/xml.rb

@@ -3,8 +3,11 @@ require 'ostruct'
 
 module Matcher
 
+  class MatchError < StandardError
+  end
+
   class Xml
-    
+
     NOT_FOUND = "[Not found]"
     EXISTENCE = "[Existence]"
     UNMATCHED = "[Unmatched]"
@@ -17,10 +20,15 @@ module Matcher
       @results = {}
     end
 
-    def match_on(path, &blk)
-      @custom_matchers[path] = blk
+    def match_on(path, options = {}, &blk)
+      raise ArgumentError.new("Using block AND options is not supported for custom matching") if blk && !options.empty?
+      excluding = options[:excluding]
+      raise ArgumentError.new "'excluding' option must be a regular expression" if excluding && !excluding.kind_of?(Regexp)
+      @custom_matchers[path] = blk || options
     end
 
+    alias_method :on, :match_on
+
     def match(actual)
       @results.clear
       @rhs = parse(actual)
@@ -29,7 +37,7 @@ module Matcher
 
     def record(path, result, expected, actual)
       # support 0 as true (for regex matches)
-      r = !result || result.nil? ? false : true
+      r = (!result || result.nil?) ? false : true
       was_custom_matched = @custom_matchers[path] ? true : false
       @results[path] = OpenStruct.new(:result => r, :expected => expected, :actual => actual, :was_custom_matched => was_custom_matched)
     end
@@ -39,17 +47,47 @@ module Matcher
       return "mismatched" if mismatches[path]
       "unmatched"
     end
-    
+
     def matches
       results_that_are(true)
     end
-    
+
     def mismatches
       results_that_are(false)
     end
 
+    def evaluate(path, expected, actual)
+      custom_matcher = custom_matchers[path]
+      match = custom_matcher ? evaluate_custom_matcher(custom_matcher, expected, actual) : expected == actual
+      record(path, match, expected, actual)
+      match
+    end
+
     private
-    
+
+      def evaluate_custom_matcher(custom_matcher, expected, actual)
+        custom_matcher.kind_of?(Hash) ? evaluate_as_regex(custom_matcher, expected, actual) : custom_matcher.call(actual)
+      end
+
+      def evaluate_as_regex(custom_matcher, expected, actual)
+        exclude_pattern = custom_matcher[:excluding]
+        match_data = expected.match(exclude_pattern)
+        return false unless match_data
+        
+        if match_data.captures.empty?
+          lhs = expected.sub(exclude_pattern, "")
+          rhs = actual.sub(exclude_pattern, "")
+        else
+          lhs_exclude = expected.match(exclude_pattern).captures.first
+          rhs_exclude = actual.match(exclude_pattern).captures.first
+          lhs = expected.sub(/#{lhs_exclude}/, "")
+          rhs = actual.sub(/#{rhs_exclude}/, "")
+        end
+
+        raise Matcher::MatchError.new("excluding option resulted in comparing empty values") if lhs.empty?
+        lhs == rhs
+      end
+
       def results_that_are(value)
         match_info = {}
         @results.each { |path, info| match_info[path] = info if info.result == value}

data/spec/matcher/xml_spec.rb

@@ -7,12 +7,13 @@ describe Matcher::Xml do
   def verify_mismatch(path, expected, actual, count = 1)
     match = @xml.match(@rhs)
     @xml.mismatches.should have(count).mismatch
-    @xml.mismatches[path].result.should be_false
-    @xml.mismatches[path].expected.should == expected.to_s
-    @xml.mismatches[path].actual.should == actual
+    mismatch = @xml.mismatches[path]
+    mismatch.result.should be_false
+    mismatch.expected.should == expected.to_s
+    mismatch.actual.should == actual
   end
 
-  context "attributes" do
+  context "when being created" do
 
     before(:each) do
       @xml = Matcher::Xml.new("<foo></foo>")
@@ -33,25 +34,26 @@ describe Matcher::Xml do
 
   end
 
-  before(:each) do
-    @lhs = <<-eos
-    <bookstore>
-    <book category="COOKING">
-    <title lang="en">Everyday Italian</title>
-    </book>
-    </bookstore>
-    eos
-    @xml = Matcher::Xml.new(@lhs)
-  end
 
   context "matching" do
 
+    before(:each) do
+      @lhs = <<-eos
+      <bookstore>
+      <book category="COOKING">
+      <title lang="en">Everyday Italian</title>
+      </book>
+      </bookstore>
+      eos
+      @xml = Matcher::Xml.new(@lhs)
+    end
+
     it "should be true when documents match" do
       Matcher::Xml.new(@lhs).match(@lhs.clone).should be_true
     end
 
     it "should provide empty mismatches on match" do
-      @xml.match(@lhs.clone).should be_true
+      @xml.match(@lhs.clone)
       @xml.mismatches.should be_empty
     end
 
@@ -68,7 +70,7 @@ describe Matcher::Xml do
       @xml.match(rhs).should be_true
     end
 
-    it "should be true when a string is matched with a document" do
+    it "should be true when a string is matched with a parsed document" do
       rhs = <<-eos
       <bookstore>
       <book category="COOKING">
@@ -82,7 +84,7 @@ describe Matcher::Xml do
       Matcher::Xml.new(@lhs).match(Nokogiri::XML(rhs)).should be_true
     end
 
-    context "elements" do
+    context "against elements" do
 
       it "should not match when rhs has an extra element" do
         @rhs = <<-eos
@@ -108,7 +110,7 @@ describe Matcher::Xml do
 
     end
 
-    context "names" do
+    context "against element names" do
 
       it "should not match when rhs has a different element name" do
         @rhs = <<-eos
@@ -123,7 +125,7 @@ describe Matcher::Xml do
 
     end
 
-    context "attributes" do
+    context "against attributes" do
 
       it "should not match when an attribute names don't match" do
         @rhs = <<-eos
@@ -182,9 +184,9 @@ describe Matcher::Xml do
 
     end
 
-    context "contents" do
+    context "against text element contents" do
 
-      it "should not match when inner text contents don't match" do
+      it "should not match when contents don't match" do
         @rhs = <<-eos
         <bookstore>
         <book category="COOKING">
@@ -197,18 +199,29 @@ describe Matcher::Xml do
 
     end
 
+    it "should provides all results empty by default" do
+      Matcher::Xml.new(@lhs).results.should be_empty
+    end
+
   end
 
-  context "mismatches" do
+  context "with mismatches" do
+
+    before(:each) do
+      @lhs = <<-eos
+      <bookstore>
+      <book category="COOKING">
+      <title lang="en">Everyday Italian</title>
+      </book>
+      </bookstore>
+      eos
+      @xml = Matcher::Xml.new(@lhs)
+    end
 
     it "should be empty to start with" do
       Matcher::Xml.new(@lhs).mismatches.should be_empty
     end
 
-    it "provides all results" do
-      Matcher::Xml.new(@lhs).results.should be_empty
-    end
-    
     it "should be reset when rematching" do
       rhs = <<-eos
       <bookstore>
@@ -237,9 +250,6 @@ describe Matcher::Xml do
     it "should contain parent's path when an attribute doesn't match" do
       lhs = <<-eos
       <bookstore>
-      <book category="COOKING">
-      <title lang="en">Everyday Italian</title>
-      </book>
       <book category="FOO">
       <title lang="en">Everyday French</title>
       </book>
@@ -249,9 +259,6 @@ describe Matcher::Xml do
 
       @rhs = <<-eos
       <bookstore>
-      <book category="COOKING">
-      <title lang="en">Everyday Italian</title>
-      </book>
       <book foo="bar">
       <title lang="en">Everyday French</title>
       </book>
@@ -259,90 +266,148 @@ describe Matcher::Xml do
       eos
 
       @xml = Matcher::Xml.new(lhs)
-      verify_mismatch("/bookstore/book[2]/@category", Matcher::Xml::EXISTENCE, Matcher::Xml::NOT_FOUND)
+      verify_mismatch("/bookstore/book/@category", Matcher::Xml::EXISTENCE, Matcher::Xml::NOT_FOUND)
     end
+  end
 
-    context 'matches' do
+  context 'with matches' do
 
-      it "should contain each match" do
-        lhs = "<bookstore><book>foo</book></bookstore>"
-        xml = Matcher::Xml.new(lhs)
-        xml.match(lhs)
-        xml.matches.should have(3).matches
-      end
-      
-      it "should have expected and actual results" do
-        lhs = "<bookstore><book>foo</book></bookstore>"
-        xml = Matcher::Xml.new(lhs)
-        xml.match(lhs).should be_true
-        match_info = xml.matches["/bookstore"]
-        match_info.expected.should == "1 children"
-        match_info.actual.should == "1 children"
-      end
+    before(:each) do
+      lhs = "<bookstore><book>foo</book></bookstore>"
+      @xml = Matcher::Xml.new(lhs)
+      @xml.match(lhs).should be_true
+    end
+
+    it "should contain each match" do
+      @xml.matches.should have(3).matches
+    end
 
+    it "should have expected and actual results" do
+      match_info = @xml.matches["/bookstore"]
+      match_info.expected.should == "1 children"
+      match_info.actual.should == "1 children"
     end
 
   end
 
-  context "match results" do
-    
+  context "retrieving match results" do
+
+    before(:each) do
+      @xml = Matcher::Xml.new("<bookstore></bookstore>")
+    end
+
     it "returns 'matched' for a path that matched correctly" do
-      xml = Matcher::Xml.new("<bookstore></bookstore>")
-      xml.match("<bookstore></bookstore>")
-      xml.result_for("/bookstore").should == "matched"
+      @xml.match("<bookstore></bookstore>")
+      @xml.result_for("/bookstore").should == "matched"
     end
 
     it "returns 'unmatched' for a path that was not found" do
-      xml = Matcher::Xml.new("<bookstore></bookstore>")
-      xml.match("<bookstorex></bookstorex>")
-      xml.result_for("/bookstore").should == "mismatched"
+      @xml.match("<bookstorex></bookstorex>")
+      @xml.result_for("/bookstore").should == "mismatched"
     end
-    
+
   end
-  
-  context "custom matchers" do
-    
-    it "can be provided" do
-      xml = Matcher::Xml.new("<bookstore id='1'></bookstore>", {"my path" => "my predicate"})
-      xml.custom_matchers.should have(1).matcher
-    end
-    
-    it "can be used on an attribute value" do
-      custom_matchers = { "/bookstore/@id" => lambda {|actual| actual == '2'} }
-      xml = Matcher::Xml.new("<bookstore id='1'></bookstore>", custom_matchers)
-      xml.match("<bookstore id='2'></bookstore>").should be_true
-    end
-    
-    it "can be used on an element value" do
-      custom_matchers = { "/bookstore/book/text()" => lambda {|actual| actual == 'bar'} }
-      xml = Matcher::Xml.new("<bookstore><book>foo</book></bookstore", custom_matchers)
-      xml.match("<bookstore><book>bar</book></bookstore").should be_true 
-    end
 
-    it "supports regex style matching" do
-      custom_matchers = { "/bookstore/book/text()" => lambda {|actual| actual =~ /bar/} }
-      xml = Matcher::Xml.new("<bookstore><book>foo</book></bookstore", custom_matchers)
-      xml.match("<bookstore><book>bar</book></bookstore").should be_true 
-      xml.mismatches.should be_empty
-      xml.matches.should have(3).matches
-    end
-    
-    it "can be matched on" do
-      xml = Matcher::Xml.new("<bookstore><book>foo</book></bookstore")
-      xml.match_on("/bookstore/book/text()") { |actual| actual =~ /bar/ }
-      xml.match("<bookstore><book>bar</book></bookstore").should be_true 
-      xml.mismatches.should be_empty
-      xml.matches.should have(3).matches
+  describe "with custom matchers" do
+
+    context "provided at create time" do
+
+      it "should be stored" do
+        Matcher::Xml.new("<bookstore</bookstore>", {"my path" => "my predicate"}).custom_matchers.should have(1).matcher
+      end
+
+      it "can be used on an attribute value" do
+        custom_matchers = { "/bookstore/@id" => lambda {|actual| actual == '2'} }
+        xml = Matcher::Xml.new("<bookstore id='1'></bookstore>", custom_matchers)
+        xml.match("<bookstore id='2'></bookstore>").should be_true
+      end
+
+      it "can be used on an element value" do
+        custom_matchers = { "/bookstore/book/text()" => lambda {|actual| actual == 'bar'} }
+        xml = Matcher::Xml.new("<bookstore><book>foo</book></bookstore", custom_matchers)
+        xml.match("<bookstore><book>bar</book></bookstore").should be_true
+      end
+
     end
 
-    it "tells if a custom matcher was used" do
-      xml = Matcher::Xml.new("<bookstore><book>foo</book></bookstore")
-      xml.match_on("/bookstore/book/text()") { |actual| actual =~ /bar/ }
-      xml.match("<bookstore><book>bar</book></bookstore").should be_true 
-      xml.matches["/bookstore/book/text()"].was_custom_matched.should be_true
-      xml.matches["/bookstore/book"].was_custom_matched.should be_false
+    context "using match_on" do
+
+      before(:each) do
+        @matcher = Matcher::Xml.new("<bookstore><book>foo text</book></bookstore")
+      end
+
+      it "supports match_on with a regex predicate" do
+        @matcher.match_on("/bookstore/book/text()") { |actual| actual =~ /bar/ }
+        @matcher.match("<bookstore><book>bar</book></bookstore").should be_true
+      end
+
+      it "supports match_on with an equality predicate" do
+        @matcher.match_on("/bookstore/book/text()") { |actual| actual == "foo text" }
+        @matcher.match("<bookstore><book>foo text</book></bookstore").should be_true
+      end
+
+      it "tells if a custom matcher was used" do
+        @matcher.match_on("/bookstore/book/text()") { |actual| actual =~ /bar/ }
+        @matcher.match("<bookstore><book>bar</book></bookstore")
+        @matcher.matches["/bookstore/book/text()"].was_custom_matched.should be_true
+        @matcher.matches["/bookstore/book"].was_custom_matched.should be_false
+      end
+
+      it "supports 'on' style" do
+        @matcher.on("/bookstore/book/text()") { |actual| actual =~ /bar/ }
+        @matcher.match("<bookstore><book>bar</book></bookstore").should be_true
+      end
+
+      context "with excluding option" do
+
+        [/^\w{3}/, /^.*\s/].each do |regex|
+          it "supports regex matching like #{regex}" do
+            @matcher.match("<bookstore><book>bar text</book></bookstore").should be_false
+            @matcher.on("/bookstore/book/text()", :excluding => regex)
+            @matcher.match("<bookstore><book>bar text</book></bookstore").should be_true
+          end
+        end
+
+        it "should support group excluding" do
+          matcher = Matcher::Xml.new("<book>This is book 123</book>")
+        	matcher.on("/book/text()", :excluding => /\d{3}$/)
+        	matcher.match("<book>This is book 456</book>").should be_true
+        end
+        
+        it "should support group excludes with a variable length" do
+        	matcher = Matcher::Xml.new("<book>Book 123 is here</book>")
+        	matcher.on("/book/text()", :excluding => /.*\s(\d{3,6})\s.*/)
+        	matcher.match("<book>Book 123456 is here</book>").should be_true
+        end
+        
+        it "handles a non captured group" do
+        	matcher = Matcher::Xml.new("<book>foo text</book>")
+        	matcher.on("/book/text()", :excluding => /(blah)/)
+        	matcher.match("<book>bar text</book>").should be_false
+        end
+
+        it "should raise an error if excluding would result in matching empty values" do
+          @matcher.on("/bookstore/book/text()", :excluding => /.*/)
+          lambda { @matcher.match("<bookstore><book>foo text</book></bookstore") }.should raise_error(Matcher::MatchError)
+        end
+
+        it "should fail a mismatching exclude" do
+          @matcher.on("/bookstore/book/text()", :excluding => /^\w{1}/)
+          @matcher.match("<bookstore><book>bar text</book></bookstore").should be_false
+        end
+        
+        it "throws an error when a non-regex value" do
+          lambda { @matcher.on("/bookstore/book/text()", :excluding => "foo") }.should raise_error(ArgumentError)
+        end
+
+        it "should not allow both a block and options" do
+          lambda { @matcher.on("foo", :excluding => /bar/) {|actual| actual =~ /foo/} }.should raise_error(ArgumentError)
+        end
+
+      end
+
     end
-    
+
   end
 
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: xmatch
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: false
   segments: 
   - 0
   - 2
-  - 0
-  version: 0.2.0
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Peter Moran
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-24 00:00:00 +11:00
+date: 2010-12-07 00:00:00 +11:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency