rspec-expectations 2.0.0.a1

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/License.txt

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2005-2009 The RSpec Development Team
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,8 @@
+# RSpec Expectations
+
+See README.markdown at [http://github.com/rspec/meta](http://github.com/rspec/meta)
+
+#### Also see
+
+* [http://github.com/rspec/core](http://github.com/rspec/core)
+* [http://github.com/rspec/mocks](http://github.com/rspec/mocks)

data/Rakefile

@@ -0,0 +1,43 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rspec-expectations"
+    gem.summary = "rspec expectations (should[_not] and matchers)"
+    gem.email = "dchelimsky@gmail.com;chad.humphries@gmail.com"
+    gem.homepage = "http://github.com/rspec/expectations"
+    gem.authors = ["David Chelimsky", "Chad Humphries"]    
+    gem.add_development_dependency('rspec-core', '>= 2.0.0.a1')
+    gem.add_development_dependency('rspec-mocks', '>= 2.0.0.a1')
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+$:.unshift File.join(File.dirname(__FILE__), "/../core/lib")
+require 'rspec/core/rake_task'
+Rspec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = "spec/**/*_spec.rb"
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rspec-expectations #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+

data/VERSION

@@ -0,0 +1 @@
+2.0.0.a1

data/VERSION.yml

@@ -0,0 +1,5 @@
+--- 
+:patch: 0
+:major: 2
+:minor: 0
+:build: a1

data/lib/rspec/expectations.rb

@@ -0,0 +1,36 @@
+require 'rspec/matchers'
+require 'rspec/expectations/differs/default'
+require 'rspec/expectations/fail_with'
+require 'rspec/expectations/errors'
+require 'rspec/expectations/extensions'
+require 'rspec/expectations/handler'
+
+module Rspec
+  
+  # Rspec::Expectations lets you set expectations on your objects.
+  #
+  #   result.should == 37
+  #   team.should have(11).players_on_the_field
+  #
+  # == How Expectations work.
+  #
+  # Rspec::Expectations adds two methods to Object:
+  #
+  #   should(matcher=nil)
+  #   should_not(matcher=nil)
+  #
+  # Both methods take an optional Expression Matcher (See Rspec::Matchers).
+  #
+  # When +should+ receives an Expression Matcher, it calls <tt>matches?(self)</tt>. If
+  # it returns +true+, the spec passes and execution continues. If it returns
+  # +false+, then the spec fails with the message returned by <tt>matcher.failure_message</tt>.
+  #
+  # Similarly, when +should_not+ receives a matcher, it calls <tt>matches?(self)</tt>. If
+  # it returns +false+, the spec passes and execution continues. If it returns
+  # +true+, then the spec fails with the message returned by <tt>matcher.negative_failure_message</tt>.
+  #
+  # RSpec ships with a standard set of useful matchers, and writing your own
+  # matchers is quite simple. See Rspec::Matchers for details.
+  module Expectations
+  end
+end

data/lib/rspec/expectations/differs/default.rb

@@ -0,0 +1,62 @@
+require File.join(File.dirname(__FILE__), "/load-diff-lcs")
+require 'pp'
+
+module Rspec
+  module Expectations
+    module Differs
+      unless defined?(Default)
+        class Default
+          def initialize(options)
+            @options = options
+          end
+
+          # This is snagged from diff/lcs/ldiff.rb (which is a commandline tool)
+          def diff_as_string(data_new, data_old)
+            data_old = data_old.split(/\n/).map! { |e| e.chomp }
+            data_new = data_new.split(/\n/).map! { |e| e.chomp }
+            output = ""
+            diffs = Diff::LCS.diff(data_old, data_new)
+            return output if diffs.empty?
+            oldhunk = hunk = nil  
+            file_length_difference = 0
+            diffs.each do |piece|
+              begin
+                hunk = Diff::LCS::Hunk.new(data_old, data_new, piece, context_lines,
+                                           file_length_difference)
+                file_length_difference = hunk.file_length_difference      
+                next unless oldhunk      
+                # Hunks may overlap, which is why we need to be careful when our
+                # diff includes lines of context. Otherwise, we might print
+                # redundant lines.
+                if (context_lines > 0) and hunk.overlaps?(oldhunk)
+                  hunk.unshift(oldhunk)
+                else
+                  output << oldhunk.diff(format)
+                end
+              ensure
+                oldhunk = hunk
+                output << "\n"
+              end
+            end  
+            #Handle the last remaining hunk
+            output << oldhunk.diff(format) << "\n"
+          end  
+
+          def diff_as_object(target,expected)
+            diff_as_string(PP.pp(target,""), PP.pp(expected,""))
+          end
+
+          protected
+          def format
+            @options.diff_format
+          end
+
+          def context_lines
+            @options.context_lines
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/rspec/expectations/differs/load-diff-lcs.rb

@@ -0,0 +1,12 @@
+begin
+  require 'diff/lcs'
+rescue LoadError
+  begin
+    require 'rubygems' unless ENV['NO_RUBYGEMS']
+    require 'diff/lcs'
+  rescue LoadError
+    raise "You must gem install diff-lcs to use diffing"
+  end
+end
+
+require 'diff/lcs/hunk'

data/lib/rspec/expectations/errors.rb

@@ -0,0 +1,12 @@
+module Rspec
+  module Expectations
+    # If Test::Unit is loaed, we'll use its error as baseclass, so that Test::Unit
+    # will report unmet RSpec expectations as failures rather than errors.
+    superclass = ['Test::Unit::AssertionFailedError', '::StandardError'].map do |c|
+      eval(c) rescue nil
+    end.compact.first
+    
+    class ExpectationNotMetError < superclass
+    end
+  end
+end

data/lib/rspec/expectations/extensions.rb

@@ -0,0 +1 @@
+require 'rspec/expectations/extensions/kernel'

data/lib/rspec/expectations/extensions/kernel.rb

@@ -0,0 +1,52 @@
+module Kernel
+  # :call-seq:
+  #   should(matcher)
+  #   should == expected
+  #   should === expected
+  #   should =~ expected
+  #
+  #   receiver.should(matcher)
+  #     => Passes if matcher.matches?(receiver)
+  #
+  #   receiver.should == expected #any value
+  #     => Passes if (receiver == expected)
+  #
+  #   receiver.should === expected #any value
+  #     => Passes if (receiver === expected)
+  #
+  #   receiver.should =~ regexp
+  #     => Passes if (receiver =~ regexp)
+  #
+  # See Rspec::Matchers for more information about matchers
+  #
+  # == Warning
+  #
+  # NOTE that this does NOT support receiver.should != expected.
+  # Instead, use receiver.should_not == expected
+  def should(matcher=nil, message=nil, &block)
+    Rspec::Expectations::PositiveExpectationHandler.handle_matcher(self, matcher, message, &block)
+  end
+  
+  # :call-seq:
+  #   should_not(matcher)
+  #   should_not == expected
+  #   should_not === expected
+  #   should_not =~ expected
+  #
+  #   receiver.should_not(matcher)
+  #     => Passes unless matcher.matches?(receiver)
+  #
+  #   receiver.should_not == expected
+  #     => Passes unless (receiver == expected)
+  #
+  #   receiver.should_not === expected
+  #     => Passes unless (receiver === expected)
+  #
+  #   receiver.should_not =~ regexp
+  #     => Passes unless (receiver =~ regexp)
+  #
+  # See Rspec::Matchers for more information about matchers
+  def should_not(matcher=nil, message=nil, &block)
+    Rspec::Expectations::NegativeExpectationHandler.handle_matcher(self, matcher, message, &block)
+  end
+end

data/lib/rspec/expectations/fail_with.rb

@@ -0,0 +1,43 @@
+module Rspec
+  module Expectations
+    class << self
+      attr_accessor :differ
+      
+      # raises a Rspec::Expectations::ExpectationNotMetError with message
+      #
+      # When a differ has been assigned and fail_with is passed
+      # <code>expected</code> and <code>target</code>, passes them
+      # to the differ to append a diff message to the failure message.
+      def fail_with(message, expected=nil, target=nil) # :nodoc:
+        if message.nil?
+          raise ArgumentError, "Failure message is nil. Does your matcher define the " +
+                               "appropriate failure_message_for_* method to return a string?"
+        end
+        if (Array === message) & (message.length == 3)
+          ::Rspec::Core.warn(<<-NOTICE
+
+*****************************************************************
+DEPRECATION WARNING: you are using deprecated behaviour that will
+be removed from a future version of RSpec.
+
+* Support for matchers that return arrays from failure message
+methods is deprecated.
+* Instead, the matcher should return a string, and expose methods
+for the expected() and actual() values.
+*****************************************************************
+NOTICE
+          )
+          message, expected, target = message[0], message[1], message[2]
+        end
+        unless (differ.nil? || expected.nil? || target.nil?)
+          if expected.is_a?(String)
+            message << "\nDiff:" << self.differ.diff_as_string(target.to_s, expected)
+          elsif !target.is_a?(Proc)
+            message << "\nDiff:" << self.differ.diff_as_object(target, expected)
+          end
+        end
+        Kernel::raise(Rspec::Expectations::ExpectationNotMetError.new(message))
+      end
+    end
+  end
+end

data/lib/rspec/expectations/handler.rb

@@ -0,0 +1,50 @@
+module Rspec
+  module Expectations
+    class InvalidMatcherError < ArgumentError; end        
+    
+    class PositiveExpectationHandler        
+      def self.handle_matcher(actual, matcher, message=nil, &block)
+        ::Rspec::Matchers.last_should = :should
+        ::Rspec::Matchers.last_matcher = matcher
+        return ::Rspec::Matchers::PositiveOperatorMatcher.new(actual) if matcher.nil?
+
+        match = matcher.matches?(actual, &block)
+        return match if match
+        
+        message ||= matcher.respond_to?(:failure_message_for_should) ?
+                    matcher.failure_message_for_should :
+                    matcher.failure_message
+        
+        if matcher.respond_to?(:diffable?) && matcher.diffable?
+          ::Rspec::Expectations.fail_with message, matcher.expected.first, matcher.actual
+        else
+          ::Rspec::Expectations.fail_with message
+        end
+      end
+    end
+
+    class NegativeExpectationHandler
+      def self.handle_matcher(actual, matcher, message=nil, &block)
+        ::Rspec::Matchers.last_should = :should_not
+        ::Rspec::Matchers.last_matcher = matcher
+        return ::Rspec::Matchers::NegativeOperatorMatcher.new(actual) if matcher.nil?
+        
+        match = matcher.respond_to?(:does_not_match?) ?
+                !matcher.does_not_match?(actual, &block) :
+                matcher.matches?(actual, &block)
+        return match unless match
+        
+        message ||= matcher.respond_to?(:failure_message_for_should_not) ?
+                    matcher.failure_message_for_should_not :
+                    matcher.negative_failure_message
+
+        if matcher.respond_to?(:diffable?) && matcher.diffable?
+          ::Rspec::Expectations.fail_with message, matcher.expected.first, matcher.actual
+        else
+          ::Rspec::Expectations.fail_with message
+        end
+      end
+    end
+  end
+end
+

data/lib/rspec/matchers.rb

@@ -0,0 +1,195 @@
+require 'rspec/matchers/extensions/instance_exec'
+require 'rspec/matchers/pretty'
+require 'rspec/matchers/matcher'
+require 'rspec/matchers/operator_matcher'
+require 'rspec/matchers/be'
+require 'rspec/matchers/be_close'
+require 'rspec/matchers/be_instance_of'
+require 'rspec/matchers/be_kind_of'
+require 'rspec/matchers/change'
+require 'rspec/matchers/eql'
+require 'rspec/matchers/equal'
+require 'rspec/matchers/errors'
+require 'rspec/matchers/exist'
+require 'rspec/matchers/generated_descriptions'
+require 'rspec/matchers/has'
+require 'rspec/matchers/have'
+require 'rspec/matchers/include'
+require 'rspec/matchers/match'
+require 'rspec/matchers/match_array'
+require 'rspec/matchers/method_missing'
+require 'rspec/matchers/raise_error'
+require 'rspec/matchers/respond_to'
+require 'rspec/matchers/satisfy'
+require 'rspec/matchers/simple_matcher'
+require 'rspec/matchers/throw_symbol'
+require 'rspec/matchers/wrap_expectation'
+require 'rspec/matchers/compatibility'
+require 'rspec/matchers/dsl'
+
+module Rspec
+
+  # RSpec ships with a number of useful Expression Matchers. An Expression Matcher
+  # is any object that responds to the following methods:
+  #
+  #   matches?(actual)
+  #   failure_message_for_should
+  #
+  # These methods are also part of the matcher protocol, but are optional:
+  #
+  #   does_not_match?(actual)
+  #   failure_message_for_should_not
+  #   description #optional
+  #
+  # These methods are from older versions of the protocol. They are still supported,
+  # but are not recommended:
+  #
+  #   failure_message          (use failure_message_for_should instead)
+  #   negative_failure_message (use failure_message_for_should_not instead)
+  #
+  # See Rspec::Expectations to learn how to use these as Expectation Matchers.
+  #
+  # == Predicates
+  #
+  # In addition to those Expression Matchers that are defined explicitly, RSpec will
+  # create custom Matchers on the fly for any arbitrary predicate, giving your specs
+  # a much more natural language feel. 
+  #
+  # A Ruby predicate is a method that ends with a "?" and returns true or false.
+  # Common examples are +empty?+, +nil?+, and +instance_of?+.
+  #
+  # All you need to do is write +should be_+ followed by the predicate without
+  # the question mark, and RSpec will figure it out from there. For example:
+  #
+  #   [].should be_empty => [].empty? #passes
+  #   [].should_not be_empty => [].empty? #fails
+  #
+  # In addtion to prefixing the predicate matchers with "be_", you can also use "be_a_"
+  # and "be_an_", making your specs read much more naturally:
+  #
+  #   "a string".should be_an_instance_of(String) =>"a string".instance_of?(String) #passes
+  #
+  #   3.should be_a_kind_of(Fixnum) => 3.kind_of?(Numeric) #passes
+  #   3.should be_a_kind_of(Numeric) => 3.kind_of?(Numeric) #passes
+  #   3.should be_an_instance_of(Fixnum) => 3.instance_of?(Fixnum) #passes
+  #   3.should_not be_instance_of(Numeric) => 3.instance_of?(Numeric) #fails
+  #
+  # RSpec will also create custom matchers for predicates like +has_key?+. To
+  # use this feature, just state that the object should have_key(:key) and RSpec will
+  # call has_key?(:key) on the target. For example:
+  #
+  #   {:a => "A"}.should have_key(:a) => {:a => "A"}.has_key?(:a) #passes
+  #   {:a => "A"}.should have_key(:b) => {:a => "A"}.has_key?(:b) #fails
+  #
+  # You can use this feature to invoke any predicate that begins with "has_", whether it is
+  # part of the Ruby libraries (like +Hash#has_key?+) or a method you wrote on your own class.
+  #
+  # == Custom Matchers
+  #
+  # When you find that none of the stock Expectation Matchers provide a natural
+  # feeling expectation, you can very easily write your own using RSpec's matcher
+  # DSL or writing one from scratch.
+  #
+  # === Matcher DSL
+  #
+  # Imagine that you are writing a game in which players can be in various
+  # zones on a virtual board. To specify that bob should be in zone 4, you
+  # could say:
+  #
+  #   bob.current_zone.should eql(Zone.new("4"))
+  #
+  # But you might find it more expressive to say:
+  #
+  #   bob.should be_in_zone("4")
+  #
+  # and/or
+  #
+  #   bob.should_not be_in_zone("3")
+  #
+  # You can create such a matcher like so:
+  #
+  #   Rspec::Matchers.define :be_in_zone do |zone|
+  #     match do |player|
+  #       player.in_zone?(zone)
+  #     end
+  #   end
+  #
+  # This will generate a <tt>be_in_zone</tt> method that returns a matcher
+  # with logical default messages for failures. You can override the failure
+  # messages and the generated description as follows:
+  #
+  #   Rspec::Matchers.define :be_in_zone do |zone|
+  #     match do |player|
+  #       player.in_zone?(zone)
+  #     end
+  #     failure_message_for_should do |player|
+  #       # generate and return the appropriate string.
+  #     end
+  #     failure_message_for_should_not do |player|
+  #       # generate and return the appropriate string.
+  #     end
+  #     description do
+  #       # generate and return the appropriate string.
+  #     end
+  #   end
+  #
+  # Each of the message-generation methods has access to the block arguments
+  # passed to the <tt>create</tt> method (in this case, <tt>zone</tt>). The
+  # failure message methods (<tt>failure_message_for_should</tt> and
+  # <tt>failure_message_for_should_not</tt>) are passed the actual value (the
+  # receiver of <tt>should</tt> or <tt>should_not</tt>).
+  #
+  # === Custom Matcher from scratch
+  #
+  # You could also write a custom matcher from scratch, as follows:
+  #
+  #   class BeInZone
+  #     def initialize(expected)
+  #       @expected = expected
+  #     end
+  #     def matches?(target)
+  #       @target = target
+  #       @target.current_zone.eql?(Zone.new(@expected))
+  #     end
+  #     def failure_message_for_should
+  #       "expected #{@target.inspect} to be in Zone #{@expected}"
+  #     end
+  #     def failure_message_for_should_not
+  #       "expected #{@target.inspect} not to be in Zone #{@expected}"
+  #     end
+  #   end
+  #
+  # ... and a method like this:
+  #
+  #   def be_in_zone(expected)
+  #     BeInZone.new(expected)
+  #   end
+  #
+  # And then expose the method to your specs. This is normally done
+  # by including the method and the class in a module, which is then
+  # included in your spec:
+  #
+  #   module CustomGameMatchers
+  #     class BeInZone
+  #       ...
+  #     end
+  #
+  #     def be_in_zone(expected)
+  #       ...
+  #     end
+  #   end
+  #
+  #   describe "Player behaviour" do
+  #     include CustomGameMatchers
+  #     ...
+  #   end
+  #
+  # or you can include in globally in a spec_helper.rb file <tt>require</tt>d
+  # from your spec file(s):
+  #
+  #   Rspec::Runner.configure do |config|
+  #     config.include(CustomGameMatchers)
+  #   end
+  #
+  module Matchers; end
+end