rspec-expectations 2.8.0 → 2.9.0.rc2

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+-
+README.md
+License.txt
+Changelog.md

data/.yardopts

@@ -0,0 +1,3 @@
+--no-private
+--exclude features
+--markup markdown

data/Changelog.md

@@ -0,0 +1,176 @@
+### 2.9.0.rc2 / 2012-03-12
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.8.0...v2.9.0.rc2)
+
+Enhancements
+
+* Move built-in matcher classes to RSpec::Matchers::BuiltIn to reduce pollution
+  of RSpec::Matchers (which is included in every example).
+* Autoload files with matcher classes to improve load time.
+
+Bug fixes
+
+* Align respond_to? and method_missing in DSL-defined matchers.
+* Clear out user-defined instance variables between invocations of DSL-defined
+  matchers.
+* Dup the instance of a DSL generated matcher so its state is not changed by
+  subsequent invocations.
+* Treat expected args consistently across positive and negative expectations
+  (thanks to Ralf Kistner for the heads up)
+
+### 2.8.0 / 2012-01-04
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.8.0.rc2...v2.8.0)
+
+Enhancements
+
+* Better diff output for Hash (Philippe Creux)
+* Eliminate Ruby warnings (Olek Janiszewski)
+
+### 2.8.0.rc2 / 2011-12-19
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.8.0.rc1...v2.8.0.rc2)
+
+No changes for this release. Just releasing with the other rspec gems.
+
+### 2.8.0.rc1 / 2011-11-06
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.7.0...v2.8.0.rc1)
+
+Enhancements
+
+* Use classes for the built-in matchers (they're faster).
+* Eliminate Ruby warnings (Matijs van Zuijlen)
+
+### 2.7.0 / 2011-10-16
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.6.0...v2.7.0)
+
+Enhancements
+
+* `HaveMatcher` converts argument using `to_i` (Alex Bepple & Pat Maddox)
+* Improved failure message for the `have_xxx` matcher (Myron Marston)
+* `HaveMatcher` supports `count` (Matthew Bellantoni)
+* Change matcher dups `Enumerable` before the action, supporting custom
+  `Enumerable` types like `CollectionProxy` in Rails (David Chelimsky)
+
+Bug fixes
+
+* Fix typo in `have(n).xyz` documentation (Jean Boussier)
+* fix `safe_sort` for ruby 1.9.2 (`Kernel` now defines `<=>` for Object) (Peter
+  van Hardenberg)
+
+### 2.6.0 / 2011-05-12
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.5.0...v2.6.0)
+
+Enhancements
+
+* `change` matcher accepts regexps (Robert Davis)
+* better descriptions for `have_xxx` matchers (Magnus Bergmark)
+* `range.should cover(*values)` (Anders Furseth)
+
+Bug fixes
+
+* Removed non-ascii characters that were choking rcov (Geoffrey Byers)
+* change matcher dups arrays and hashes so their before/after states can be
+  compared correctly.
+* Fix the order of inclusion of RSpec::Matchers in Test::Unit::TestCase and
+  MiniTest::Unit::TestCase to prevent a SystemStackError (Myron Marston)
+
+### 2.5.0 / 2011-02-05
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.4.0...v2.5.0)
+
+Enhancements
+
+* `should exist` works with `exist?` or `exists?` (Myron Marston)
+* `expect { ... }.not_to do_something` (in addition to `to_not`)
+
+Documentation
+
+* improved docs for raise_error matcher (James Almond)
+
+### 2.4.0 / 2011-01-02
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.3.0...v2.4.0)
+
+No functional changes in this release, which was made to align with the
+rspec-core-2.4.0 release.
+
+Enhancements
+
+* improved RDoc for change matcher (Jo Liss)
+
+### 2.3.0 / 2010-12-12
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.2.1...v2.3.0)
+
+Enhancements
+
+* diff strings when include matcher fails (Mike Sassak)
+
+### 2.2.0 / 2010-11-28
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.1.0...v2.2.0)
+
+### 2.1.0 / 2010-11-07
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.0.1...v2.1.0)
+
+Enhancements
+
+* `be_within(delta).of(expected)` matcher (Myron Marston)
+* Lots of new Cucumber features (Myron Marston)
+* Raise error if you try `should != expected` on Ruby-1.9 (Myron Marston)
+* Improved failure messages from `throw_symbol` (Myron Marston)
+
+Bug fixes
+
+* Eliminate hard dependency on `RSpec::Core` (Myron Marston)
+* `have_matcher` - use pluralize only when ActiveSupport inflections are indeed
+  defined (Josep M Bach)
+* throw_symbol matcher no longer swallows exceptions (Myron Marston)
+* fix matcher chaining to avoid name collisions (Myron Marston)
+
+### 2.0.0 / 2010-10-10
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.0.0.rc...v2.0.0)
+
+Enhancements
+
+* Add match_for_should_not method to matcher DSL (Myron Marston)
+
+Bug fixes
+
+* `respond_to` matcher works correctly with `should_not` with multiple methods
+  (Myron Marston)
+* `include` matcher works correctly with `should_not` with multiple values
+  (Myron Marston)
+
+### 2.0.0.rc / 2010-10-05
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.0.0.beta.22...v2.0.0.rc)
+
+Enhancements
+
+* `require 'rspec/expectations'` in a T::U or MiniUnit suite (Josep M. Bach)
+
+Bug fixes
+
+* change by 0 passes/fails correctly (Len Smith)
+* Add description to satisfy matcher
+
+### 2.0.0.beta.22 / 2010-09-12
+
+[full changelog](http://github.com/rspec/rspec-expectations/compare/v2.0.0.beta.20...v2.0.0.beta.22)
+
+Enhancements
+
+* diffing improvements
+    * diff multiline strings
+    * don't diff single line strings
+    * don't diff numbers (silly)
+    * diff regexp + multiline string
+
+Bug fixes
+    * `should[_not]` change now handles boolean values correctly

data/README.md

@@ -1,7 +1,7 @@
 # RSpec Expectations
 
-[RSpec::Expectations](../RSpec/Expectations) lets you express expected outcomes
-on an object in an example.
+RSpec::Expectations lets you express expected outcomes on an object in an
+example.
 
     account.balance.should eq(Money.new(37.42, :USD))
 
@@ -119,8 +119,6 @@ actual.should be_xxx         # passes if actual.xxx?
 actual.should have_xxx(:arg) # passes if actual.has_xxx?(:arg)
 ```
 
-See [RSpec::Matchers](../RSpec/Matchers) for more about predicate matchers.
-
 ### Ranges (Ruby >= 1.9 only)
 
 ```ruby
@@ -142,15 +140,6 @@ actual.should include(expected)
 "this string".should include("is str")
 ```
 
-## Learn more
-
-See [RSpec::Expectations](../RSpec/Expectations) for more information about
-`should` and `should_not` and how they work.
-
-See [RSpec::Matchers](../RSpec/Matchers) for more information about the
-built-in matchers that ship with rspec-expectations, and how to write your own
-custom matchers.
-
 ## Also see
 
 * [http://github.com/rspec/rspec](http://github.com/rspec/rspec)

data/features/custom_matchers/access_running_example.feature

@@ -49,5 +49,5 @@ Feature: access running example
     When I run `rspec ./example_spec.rb`
     Then the output should contain "1 example, 1 failure"
     And the output should contain "undefined local variable"
-    And the output should contain "RSpec::Matchers::Matcher"
+    And the output should contain "RSpec::Matchers::DSL::Matcher"
     And the output should not contain "ExampleGroup"

data/features/step_definitions/additional_cli_steps.rb

@@ -12,11 +12,11 @@ Then /^the output should contain all of these:$/ do |table|
 end
 
 Then /^the example(?:s)? should(?: all)? pass$/ do
-  Then %q{the output should contain "0 failures"}
-  Then %q{the exit status should be 0}
+  step %q{the output should contain "0 failures"}
+  step %q{the exit status should be 0}
 end
 
 Then /^the example should fail$/ do
-  Then %q{the output should contain "1 failure"}
-  Then %q{the exit status should not be 0}
+  step %q{the output should contain "1 failure"}
+  step %q{the exit status should not be 0}
 end

data/lib/rspec/expectations/fail_with.rb

@@ -35,11 +35,11 @@ module RSpec
     private
 
       def no_procs?(*args)
-        args.none? {|a| Proc === a}
+        args.flatten.none? {|a| Proc === a}
       end
 
       def all_strings?(*args)
-        args.all? {|a| String === a}
+        args.flatten.all? {|a| String === a}
       end
 
       def any_multiline_strings?(*args)
@@ -47,7 +47,7 @@ module RSpec
       end
 
       def no_numbers?(*args)
-        args.none? {|a| Numeric === a}
+        args.flatten.none? {|a| Numeric === a}
       end
     end
   end

data/lib/rspec/expectations/handler.rb

@@ -1,12 +1,10 @@
 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?
+        return ::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher.new(actual) if matcher.nil?
 
         match = matcher.matches?(actual, &block)
         return match if match
@@ -27,7 +25,7 @@ module RSpec
       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?
+        return ::RSpec::Matchers::BuiltIn::NegativeOperatorMatcher.new(actual) if matcher.nil?
         
         match = matcher.respond_to?(:does_not_match?) ?
                 !matcher.does_not_match?(actual, &block) :
@@ -39,7 +37,7 @@ module RSpec
                     matcher.negative_failure_message
 
         if matcher.respond_to?(:diffable?) && matcher.diffable?
-          ::RSpec::Expectations.fail_with message, matcher.expected.first, matcher.actual
+          ::RSpec::Expectations.fail_with message, matcher.expected, matcher.actual
         else
           ::RSpec::Expectations.fail_with message
         end

data/lib/rspec/expectations/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Expectations
     # @private
     module Version
-      STRING = '2.8.0'
+      STRING = '2.9.0.rc2'
     end
   end
 end

data/lib/rspec/matchers.rb

@@ -175,32 +175,398 @@ end
 
 require 'rspec/matchers/extensions/instance_eval_with_args'
 require 'rspec/matchers/pretty'
-require 'rspec/matchers/base_matcher'
+
+require 'rspec/matchers/built_in'
 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/be_within'
+
 require 'rspec/matchers/block_aliases'
-require 'rspec/matchers/change'
-require 'rspec/matchers/cover' if (1..2).respond_to? :cover?
-require 'rspec/matchers/eq'
-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/throw_symbol'
 require 'rspec/matchers/compatibility'
 require 'rspec/matchers/dsl'
+
+module RSpec
+  module Matchers
+
+    # Passes if actual is truthy (anything but false or nil)
+    def be_true
+      BuiltIn::BeTrue.new
+    end
+
+    # Passes if actual is falsy (false or nil)
+    def be_false
+      BuiltIn::BeFalse.new
+    end
+
+    # Passes if actual is nil
+    def be_nil
+      BuiltIn::BeNil.new
+    end
+
+    # @example
+    #   actual.should be_true
+    #   actual.should be_false
+    #   actual.should be_nil
+    #   actual.should be_[arbitrary_predicate](*args)
+    #   actual.should_not be_nil
+    #   actual.should_not be_[arbitrary_predicate](*args)
+    #
+    # Given true, false, or nil, will pass if actual value is true, false or
+    # nil (respectively). Given no args means the caller should satisfy an if
+    # condition (to be or not to be). 
+    #
+    # Predicates are any Ruby method that ends in a "?" and returns true or
+    # false.  Given be_ followed by arbitrary_predicate (without the "?"),
+    # RSpec will match convert that into a query against the target object.
+    #
+    # The arbitrary_predicate feature will handle any predicate prefixed with
+    # "be_an_" (e.g. be_an_instance_of), "be_a_" (e.g. be_a_kind_of) or "be_"
+    # (e.g. be_empty), letting you choose the prefix that best suits the
+    # predicate.
+    def be(*args)
+      args.empty? ?
+        Matchers::BuiltIn::Be.new : equal(*args)
+    end
+
+    # passes if target.kind_of?(klass)
+    def be_a(klass)
+      be_a_kind_of(klass)
+    end
+
+    alias_method :be_an, :be_a
+
+    # Passes if actual.instance_of?(expected)
+    #
+    # @example
+    #
+    #   5.should be_instance_of(Fixnum)
+    #   5.should_not be_instance_of(Numeric)
+    #   5.should_not be_instance_of(Float)
+    def be_an_instance_of(expected)
+      BuiltIn::BeAnInstanceOf.new(expected)
+    end
+    
+    alias_method :be_instance_of, :be_an_instance_of
+
+    # Passes if actual.kind_of?(expected)
+    #
+    # @example
+    #
+    #   5.should be_kind_of(Fixnum)
+    #   5.should be_kind_of(Numeric)
+    #   5.should_not be_kind_of(Float)
+    def be_a_kind_of(expected)
+      BuiltIn::BeAKindOf.new(expected)
+    end
+
+    alias_method :be_kind_of, :be_a_kind_of
+
+    # Passes if actual == expected +/- delta
+    #
+    # @example
+    #
+    #   result.should be_within(0.5).of(3.0)
+    #   result.should_not be_within(0.5).of(3.0)
+    def be_within(delta)
+      BuiltIn::BeWithin.new(delta)
+    end
+
+    # Applied to a proc, specifies that its execution will cause some value to
+    # change.
+    #
+    # @param [Object] receiver
+    # @param [Symbol] message the message to send the receiver
+    #
+    # You can either pass <tt>receiver</tt> and <tt>message</tt>, or a block,
+    # but not both.
+    #
+    # When passing a block, it must use the <tt>{ ... }</tt> format, not
+    # do/end, as <tt>{ ... }</tt> binds to the +change+ method, whereas do/end
+    # would errantly bind to the +should+ or +should_not+ method.
+    #
+    # @example
+    #
+    #   lambda {
+    #     team.add_player(player) 
+    #   }.should change(roster, :count)
+    #
+    #   lambda {
+    #     team.add_player(player) 
+    #   }.should change(roster, :count).by(1)
+    #
+    #   lambda {
+    #     team.add_player(player) 
+    #   }.should change(roster, :count).by_at_least(1)
+    #
+    #   lambda {
+    #     team.add_player(player)
+    #   }.should change(roster, :count).by_at_most(1)    
+    #
+    #   string = "string"
+    #   lambda {
+    #     string.reverse!
+    #   }.should change { string }.from("string").to("gnirts")
+    #
+    #   lambda {
+    #     person.happy_birthday
+    #   }.should change(person, :birthday).from(32).to(33)
+    #       
+    #   lambda {
+    #     employee.develop_great_new_social_networking_app
+    #   }.should change(employee, :title).from("Mail Clerk").to("CEO")
+    #
+    #   lambda {
+    #     doctor.leave_office
+    #   }.should change(doctor, :sign).from(/is in/).to(/is out/)
+    #
+    #   user = User.new(:type => "admin")
+    #   lambda {
+    #     user.symbolize_type
+    #   }.should change(user, :type).from(String).to(Symbol)
+    #
+    # == Notes
+    #
+    # Evaluates <tt>receiver.message</tt> or <tt>block</tt> before and after it
+    # evaluates the proc object (generated by the lambdas in the examples
+    # above).
+    #
+    # <tt>should_not change</tt> only supports the form with no subsequent
+    # calls to <tt>by</tt>, <tt>by_at_least</tt>, <tt>by_at_most</tt>,
+    # <tt>to</tt> or <tt>from</tt>.
+    def change(receiver=nil, message=nil, &block)
+      BuiltIn::Change.new(receiver, message, &block)
+    end
+
+    # Passes if actual covers expected. This works for
+    # Ranges. You can also pass in multiple args
+    # and it will only pass if all args are found in Range.
+    #
+    # @example
+    #   (1..10).should cover(5)
+    #   (1..10).should cover(4, 6)
+    #   (1..10).should cover(4, 6, 11) # will fail
+    #   (1..10).should_not cover(11)
+    #   (1..10).should_not cover(5)    # will fail
+    #
+    # ### Warning:: Ruby >= 1.9 only
+    def cover(*values)
+      BuiltIn::Cover.new(*values)
+    end if (1..2).respond_to?(:cover?)
+
+    # Passes if <tt>actual == expected</tt>.
+    #
+    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
+    #
+    # @example
+    #
+    #   5.should eq(5)
+    #   5.should_not eq(3)
+    def eq(expected)
+      BuiltIn::Eq.new(expected)
+    end
+
+    # Passes if +actual.eql?(expected)+
+    #
+    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
+    #
+    # @example
+    #
+    #   5.should eql(5)
+    #   5.should_not eql(3)
+    def eql(expected)
+      BuiltIn::Eql.new(expected)
+    end
+
+    # Passes if <tt>actual.equal?(expected)</tt> (object identity).
+    #
+    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
+    #
+    # @example
+    #
+    #   5.should equal(5) # Fixnums are equal
+    #   "5".should_not equal("5") # Strings that look the same are not the same object
+    def equal(expected)
+      BuiltIn::Equal.new(expected)
+    end
+
+    # Passes if `actual.exist?` or `actual.exists?`
+    #
+    # @example
+    #   File.should exist("path/to/file")
+    def exist(*args)
+      BuiltIn::Exist.new(*args)
+    end
+
+    # Passes if receiver is a collection with the submitted number of items OR
+    # if the receiver OWNS a collection with the submitted number of items.
+    #
+    # If the receiver OWNS the collection, you must use the name of the
+    # collection. So if a `Team` instance has a collection named `#players`,
+    # you must use that name to set the expectation.
+    #
+    # If the receiver IS the collection, you can use any name you like for
+    # `named_collection`. We'd recommend using either "elements", "members", or
+    # "items" as these are all standard ways of describing the things IN a
+    # collection.
+    #
+    # This also works for Strings, letting you set expectations about their
+    # lengths.
+    #
+    # @example
+    #
+    #   # Passes if team.players.size == 11
+    #   team.should have(11).players
+    #
+    #   # Passes if [1,2,3].length == 3
+    #   [1,2,3].should have(3).items #"items" is pure sugar
+    #
+    #   # Passes if ['a', 'b', 'c'].count == 3
+    #   [1,2,3].should have(3).items #"items" is pure sugar
+    #
+    #   # Passes if "this string".length == 11
+    #   "this string".should have(11).characters #"characters" is pure sugar
+    def have(n)
+      BuiltIn::Have.new(n)
+    end
+    alias :have_exactly :have
+
+    # Exactly like have() with >=.
+    #
+    # @example
+    #   "this".should have_at_least(3).letters
+    #
+    # ### Warning:
+    #
+    # `should_not have_at_least` is not supported
+    def have_at_least(n)
+      BuiltIn::Have.new(n, :at_least)
+    end
+
+    # Exactly like have() with <=.
+    #
+    # @example
+    #   should have_at_most(number).items
+    #
+    # ### Warning:
+    #
+    # `should_not have_at_most` is not supported
+    def have_at_most(n)
+      BuiltIn::Have.new(n, :at_most)
+    end
+
+    # Passes if actual includes expected. This works for
+    # collections and Strings. You can also pass in multiple args
+    # and it will only pass if all args are found in collection.
+    #
+    # @example
+    #
+    #   [1,2,3].should include(3)
+    #   [1,2,3].should include(2,3) #would pass
+    #   [1,2,3].should include(2,3,4) #would fail
+    #   [1,2,3].should_not include(4)
+    #   "spread".should include("read")
+    #   "spread".should_not include("red")
+    def include(*expected)
+      BuiltIn::Include.new(*expected)
+    end
+
+    # Given a Regexp or String, passes if actual.match(pattern)
+    #
+    # @example
+    #
+    #   email.should match(/^([^\s]+)((?:[-a-z0-9]+\.)+[a-z]{2,})$/i)
+    #   email.should match("@example.com")
+    def match(expected)
+      BuiltIn::Match.new(expected)
+    end
+
+    # With no args, matches if any error is raised.
+    # With a named error, matches only if that specific error is raised.
+    # With a named error and messsage specified as a String, matches only if both match.
+    # With a named error and messsage specified as a Regexp, matches only if both match.
+    # Pass an optional block to perform extra verifications on the exception matched
+    #
+    # @example
+    #
+    #   lambda { do_something_risky }.should raise_error
+    #   lambda { do_something_risky }.should raise_error(PoorRiskDecisionError)
+    #   lambda { do_something_risky }.should raise_error(PoorRiskDecisionError) { |error| error.data.should == 42 }
+    #   lambda { do_something_risky }.should raise_error(PoorRiskDecisionError, "that was too risky")
+    #   lambda { do_something_risky }.should raise_error(PoorRiskDecisionError, /oo ri/)
+    #
+    #   lambda { do_something_risky }.should_not raise_error
+    #   lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError)
+    #   lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError, "that was too risky")
+    #   lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError, /oo ri/)
+    def raise_error(error=Exception, message=nil, &block)
+      BuiltIn::RaiseError.new(error, message, &block)
+    end
+
+    alias_method :raise_exception, :raise_error
+
+    # Matches if the target object responds to all of the names
+    # provided. Names can be Strings or Symbols.
+    #
+    # @example
+    # 
+    def respond_to(*names)
+      BuiltIn::RespondTo.new(*names)
+    end
+
+    # Passes if the submitted block returns true. Yields target to the
+    # block.
+    #
+    # Generally speaking, this should be thought of as a last resort when
+    # you can't find any other way to specify the behaviour you wish to
+    # specify.
+    #
+    # If you do find yourself in such a situation, you could always write
+    # a custom matcher, which would likely make your specs more expressive.
+    #
+    # @example
+    #
+    #   5.should satisfy { |n|
+    #     n > 3
+    #   }
+    def satisfy(&block)
+      BuiltIn::Satisfy.new(&block)
+    end
+
+    # Given no argument, matches if a proc throws any Symbol.
+    #
+    # Given a Symbol, matches if the given proc throws the specified Symbol.
+    #
+    # Given a Symbol and an arg, matches if the given proc throws the
+    # specified Symbol with the specified arg.
+    #
+    # @example
+    #
+    #   lambda { do_something_risky }.should throw_symbol
+    #   lambda { do_something_risky }.should throw_symbol(:that_was_risky)
+    #   lambda { do_something_risky }.should throw_symbol(:that_was_risky, culprit)
+    #
+    #   lambda { do_something_risky }.should_not throw_symbol
+    #   lambda { do_something_risky }.should_not throw_symbol(:that_was_risky)
+    #   lambda { do_something_risky }.should_not throw_symbol(:that_was_risky, culprit)
+    def throw_symbol(expected_symbol=nil, expected_arg=nil)
+      BuiltIn::ThrowSymbol.new(expected_symbol, expected_arg)
+    end
+
+    # Passes if actual contains all of the expected regardless of order. 
+    # This works for collections. Pass in multiple args  and it will only 
+    # pass if all args are found in collection.
+    #
+    # NOTE: there is no should_not version of array.should =~ other_array
+    # 
+    # @example
+    #
+    #   [1,2,3].should   =~ [1,2,3]   # => would pass
+    #   [1,2,3].should   =~ [2,3,1]   # => would pass
+    #   [1,2,3,4].should =~ [1,2,3]   # => would fail
+    #   [1,2,2,3].should =~ [1,2,3]   # => would fail
+    #   [1,2,3].should   =~ [1,2,3,4] # => would fail
+    OperatorMatcher.register(Array, '=~', BuiltIn::MatchArray)
+  end
+end