rspec 0.5.7 → 0.5.8

data/CHANGES

@@ -1,5 +1,14 @@
 = RSpec Changelog
 
+== Version 0.5.8
+This release features a new Test::Unit to RSpec translation tool.
+Also note that the RubyGem of the previous release (0.5.7) was corrupt.
+We're close to being able to translate all of RSpec's own Test::Unit
+tests and have them run successfully!
+
+* Updated test2spec documentation.
+* Replaced old test2rspec with a new test2spec, which is based on ParseTree and RubyInline.
+
 == Version 0.5.7
 This release changes examples and documentation to recommend underscores rather than dots,
 and addresses some bugfixes and changes to the spec commandline.

data/Rakefile

@@ -25,7 +25,7 @@ PKG_FILES = FileList[
   'test/**/*.rb', 
   'examples/**/*.rb', 
   'doc/**/*'
-].exclude('EXAMPLES.rd')
+]
 
 task :default => [:test]
 
@@ -51,12 +51,12 @@ task :doc do
 end
 
 desc 'Generate RDoc'
-rd = Rake::RDocTask.new("rdoc") do |rdoc|
+rd = Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'doc/output/rdoc'
-  rdoc.title    = "RSpec"
-  rdoc.options << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  rdoc.options << '--title' << 'RSpec' << '--line-numbers' << '--inline-source' << '--main' << 'README'
   rdoc.rdoc_files.include('README', 'CHANGES', 'EXAMPLES.rd', 'lib/**/*.rb')
 end
+task :rdoc => :examples_specdoc # We generate EXAMPLES.rd
 
 spec = Gem::Specification.new do |s|
   s.name = PKG_NAME
@@ -73,17 +73,14 @@ spec = Gem::Specification.new do |s|
   s.require_path = 'lib'
 
   s.has_rdoc = true
-  s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
-  s.rdoc_options <<
-    '--title' <<  'RSpec' <<
-    '--main' << 'README' <<
-    '--line-numbers'
+  s.rdoc_options = rd.options
+  s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$|^EXAMPLES.rd$/ }.to_a
   
   s.test_files = Dir.glob('test/*_test.rb')
   s.require_path = 'lib'
   s.autorequire = 'spec'
   s.bindir = "bin"
-  s.executables = ["spec", "test2rspec"]
+  s.executables = ["spec", "test2spec"]
   s.default_executable = "spec"
   s.author = "Steven Baker, Aslak Hellesoy, Dave Astels, David Chelimsky" 
   s.email = "rspec-devel@rubyforge.org"

data/bin/spec

@@ -5,7 +5,7 @@ $context_runner = ::Spec::Runner::OptionParser.create_context_runner(ARGV, false
 
 # If ARGV is a glob, it will actually each over each one of the matching files.
 ARGV.each do |file_or_dir|
-	if File.lstat(file_or_dir).directory? then
+	if File.directory?(file_or_dir)
 		Dir["#{file_or_dir}/**/*.rb"].each do |file| 
 		  require "#{file}"
 		end

data/bin/test2spec

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+
+require 'test/unit'
+require 'test/unit/ui/console/testrunner'
+require 'test/unit/ui/testrunnerutilities'
+require 'test/unit/ui/testrunnermediator'
+require 'test/unit/autorunner'
+require 'optparse'
+
+$LOAD_PATH.push File.dirname(__FILE__) + '/../lib'
+
+require 'rubygems'
+require 'spec/tool/translation_test_runner'
+require 'spec/version'
+
+$test2spec_options = {
+  :collision => :ask
+}
+
+opts = OptionParser.new do |opts|
+  opts.banner = "Usage: test2spec [options] (FILE|DIRECTORY|GLOB)+"
+  opts.separator ""
+
+  opts.on("-s", "--specdir DIRECTORY", "Directory where specs will be written") do |dir|
+    $test2spec_options[:specdir] = dir
+  end
+
+  opts.on("-c", "--chmod MODIFIERS", Integer, "Change file modifiers on written files (POSIX only)") do |mods|
+    $test2spec_options[:chmod] = mods
+  end
+
+  opts.on("--svn", "Add written files to subversion") do
+    $test2spec_options[:svn] = true
+  end
+
+  opts.on("-f", "--force", "Forcefully overwrite existing specs") do
+    $test2spec_options[:collision] = :force
+  end
+
+  opts.on("-v", "--version", "Show version") do
+    puts "test2spec #{Spec::VERSION::DESCRIPTION}"
+    exit
+  end
+
+  opts.on("-d", "--dry-run", "Don't write anything - just verify that translation works") do
+    options.dry_run = true
+  end
+
+  opts.on_tail("-h", "--help", "You're looking at it") do
+    puts opts
+    exit
+  end
+end
+
+opts.parse! ARGV
+
+if($test2spec_options[:specdir].nil?)
+  STDERR.puts "ERROR: --specdir must be specified"
+  puts opts
+  exit 1
+end
+
+if(ARGV.empty?)
+  STDERR.puts "ERROR: At least one directory, file or glob must be specified"
+  puts opts
+  exit 1
+end
+
+module Test
+  module Unit
+    class AutoRunner
+      def initialize(standalone)
+        @standalone = standalone
+        @runner = proc { |r| Spec::Tool::TranslationTestRunner }
+        @collector = COLLECTORS[(standalone ? :dir : :objectspace)]
+        @filters = []
+        @to_run = []
+        yield(self) if(block_given?)
+      end
+    end
+  end
+end
+
+# If ARGV is a glob, it will actually each over each one of the matching files.
+ARGV.each do |arg|
+	if File.directory?(arg)
+		Dir["#{arg}/**/*.rb"].each do |file| 
+		  require "#{file}"
+		end
+	else
+		require arg
+	end
+end

data/doc/src/default.template

@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="{lang:}">
   <head>
     <title>{title: }</title>
-    <link href="{relocatable: default.css}" rel="stylesheet" />
+    <link href="{relocatable: default.css}" rel="stylesheet" type="text/css" media="screen"/>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   </head>
 <body>

data/doc/src/documentation/index.page

@@ -14,21 +14,21 @@ h3. General
 h4. Arbitrary Block
 
 <ruby>
-target.should_satisfysatisfy {|arg| ...}
-target.should_satisfynot.satisfy {|arg| ...}
+target.should_satisfy {|arg| ...}
+target.should_not_satisfy {|arg| ...}
 </ruby>
 
 The supplied block is evaluated, passing <code>target</code> as the sole argument. If the block evaluates to <code>false</code>, <code>ExpectationNotMetError</code> is raised.
 
 <ruby>
-target.should_satisfysatisfy {|arg| arg > 0}
+target.should_satisfy {|arg| arg > 0}
 </ruby>
 
 h4. Equality
 
 <ruby>
-target.should_satisfyequal <value>
-target.should_satisfynot.equal <value>
+target.should_equal <value>
+target.should_not_equal <value>
 </ruby>
 
 The target object is compared to <code>value</code> using ==. If the result is <code>false</code>, <code>ExpectationNotMetError</code> is raised.
@@ -36,21 +36,21 @@ The target object is compared to <code>value</code> using ==. If the result is <
 h4. Floating Point Comparison
 
 <ruby>
-target.should_satisfybe.close <value>, <tolerance>
-target.should_satisfynot.be.close <value>, <tolerance>
+target.should_be_close <value>, <tolerance>
+target.should_not_be_close <value>, <tolerance>
 </ruby>
 
 The target object is compared to <code>value</code>. If they differ by more that <code>tolerance</code>, <code>ExpectationNotMetError</code> is raised. In the negated case, <code>ExpectationNotMetError</code> is raised if they differ by less than <code>tolerance</code>.
 
 <ruby>
-target.should_satisfybe.close 27.35, 0.05
+target.should_be_close 27.35, 0.05
 </ruby>
 
 h4. Identity
 
 <ruby>
-target.should_satisfybe <value>
-target.should_satisfynot.be <value>
+target.should_be <value>
+target.should_not_be <value>
 </ruby>
 
 The target object is compared to <code>value</code> using <code>equal?</code>. If the result is <code>false</code>, <code>ExpectationNotMetError</code> is raised.
@@ -58,10 +58,10 @@ The target object is compared to <code>value</code> using <code>equal?</code>. I
 h4. Arbitrary Predicate
 
 <ruby>
-target.should_satisfypredicate [optional args]
-target.should_satisfybe.predicate [optional args]
-target.should_satisfynot.predicate [optional args]
-target.should_satisfynot.be.predicate [optional args]
+target.should_predicate [optional args]
+target.should_be_predicate [optional args]
+target.should_not_predicate [optional args]
+target.should_not_be_predicate [optional args]
 </ruby>
 
 The message <code>predicate?</code> is sent to <code>target</code> with any supplied arguments. If the result is <code>false</code>, <code>ExpectationNotMetError</code> is raised.
@@ -69,15 +69,15 @@ The message <code>predicate?</code> is sent to <code>target</code> with any supp
 For example:
 
 <ruby>
-container.should_satisfyinclude('a') => container.include?('a')
-container.should_satisfybe.empty => container.empty?
+container.should_include('a') => container.include?('a')
+container.should_be_empty => container.empty?
 </ruby>
 
 h4. Pattern Matching
 
 <ruby>
-target.should_satisfymatch <regex>
-target.should_satisfynot.match <regex>
+target.should_match <regex>
+target.should_not_match <regex>
 </ruby>
 
 The <code>target</code> is matched against <code>regex</code>. An <code>ExpectationNotMetError</code> is raised if the match fails.
@@ -87,8 +87,8 @@ h3. Class/Type
 h4. Direct Instance
 
 <ruby>
-target.should_satisfybe.an.instance.of <class>
-target.should_satisfynot.be.an.instance.of <class>
+target.should_be_an_instance_of <class>
+target.should_not_be_an_instance_of <class>
 </ruby>
 
 An <code>ExpectationNotMetError</code> is raised if <code>target</code> is not or is, respectively, an direct instance of <code>class</code>. As expected this correlates to <code>target.instance_of?  class</code>.
@@ -96,8 +96,8 @@ An <code>ExpectationNotMetError</code> is raised if <code>target</code> is not o
 h4. Ancestor Class
 
 <ruby>
-target.should_satisfybe.a.kind.of <class>
-target.should_satisfynot.be.a.kind.of <class>
+target.should_be_a_kind_of <class>
+target.should_not_be_a_kind_of <class>
 </ruby>
 
 As above, but uses <code>target.kind_of? class</code>: checking whether <code>class</code> is the direct class of <code>target</code>, or an ancestor of <code>target</code>'s direct class.
@@ -105,8 +105,8 @@ As above, but uses <code>target.kind_of? class</code>: checking whether <code>cl
 h4. Type
 
 <ruby>
-target.should_satisfyrespond.to <symbol>
-target.should_satisfynot.respond.to <symbol>
+target.should_respond_to <symbol>
+target.should_not_respond_to <symbol>
 </ruby>
 
 Uses <code>target.respond_to?(symbol)</code> to check whether <code>symbol</code> is the name of a message that <code>target</code> understands.
@@ -116,21 +116,21 @@ h3. Procs
 h4. Raising
 
 <ruby>
-proc.should_satisfyraise <exception>
-proc.should_satisfynot.raise <exception>
+proc.should_raise <exception>
+proc.should_not_raise <exception>
 </ruby>
 
 Checks that <code>proc</code> causes the named exception to be raised or not. The latter is actually one of two cases: some other exception is raised, or no exception is raised. Typically the <code>proc</code> is created in place using <code>lambda</code>. For example:
 
 <ruby>
-lambda { 3 / 0 }.should_satisfyraise ZeroDivisionError
+lambda { 3 / 0 }.should_raise ZeroDivisionError
 </ruby>
 
 There is a more general form as well.
 
 <ruby>
-proc.should_satisfyraise
-proc.should_satisfynot.raise
+proc.should_raise
+proc.should_not_raise
 </ruby>
 
 These forms don't worry about what exception is raised (or not). All they are concerned with is that some except was raised, or that no exception was.
@@ -138,14 +138,14 @@ These forms don't worry about what exception is raised (or not). All they are co
 h4. Throwing
 
 <ruby>
-proc.should_satisfythrow <symbol>
-proc.should_satisfynot.throw <symbol>
+proc.should_throw <symbol>
+proc.should_not_throw <symbol>
 </ruby>
 
 Similar to the above, but checks that <code>symbol</code> is thrown from within <code>proc</code>, or not. The latter is actually one of two cases: some other symbol is thrown, or no symbol is thrown.
 
 <ruby>
-proc.should_satisfynot.throw
+proc.should_not_throw
 </ruby>
 
 This form is more specific.  It checks that no symbol is thrown from within <code>proc</code>.
@@ -155,8 +155,8 @@ h3. Collections
 h4. Containment
 
 <ruby>
-target.should_satisfyinclude <object>
-target.should_satisfynot.include <object>
+target.should_include <object>
+target.should_not_include <object>
 </ruby>
 
 This is simply a specific case of the arbitrary predicate form. It uses <code>target.include?(object)</code> and raises an <code>ExpectationNotMetError</code> if that returns false. 
@@ -166,7 +166,7 @@ The remaining collection forms are a little more involved. They rely on two thin
 h4. Exact Size
 
 <ruby>
-target.should_satisfyhave(<number>).things
+target.should_have(<number>).things
 </ruby>
 
 The <code>things</code> of <code>target</code> has a length/size of exactly <code>number</code>. 
@@ -174,7 +174,7 @@ The <code>things</code> of <code>target</code> has a length/size of exactly <cod
 h4. Lower Bound
 
 <ruby>
-target.should_satisfyhave.at.least(<number>).things
+target.should_have_at_least(<number>).things
 </ruby>
 
 The <code>things</code> of <code>target</code> has a length/size of no less than <code>number</code>.
@@ -182,7 +182,7 @@ The <code>things</code> of <code>target</code> has a length/size of no less than
 h4. Upper Bound
 
 <ruby>
-target.should_satisfyhave.at.most(<number>).things
+target.should_have_at_most(<number>).things
 </ruby>
 
 The <code>things</code> of <code>target</code> has a length/size of no more than <code>number</code>.

data/doc/src/documentation/mocks.page

@@ -4,7 +4,7 @@ inMenu: true
 ---
 h2. Mock API
 
-RSpec contains a full featured Mock Objects framework.
+RSpec contains a tightly integrated, powerful Mock Object framework.
 
 h3. Creating a mock
 
@@ -12,13 +12,17 @@ h3. Creating a mock
 my_mock = mock(<name>)
 </ruby>
 
-This creates a new mock with the given <code>name</code> (a string) and registers it. When the specification finishes, all registered mocks are verified.
+This creates a new mock with the given <code>name</code> (a string) and registers it. 
+When the specification finishes, all registered mocks are verified.
 
 <ruby>
 my_mock = mock(<name>, <options>)
 </ruby>
 
-As above, but allows you to specific options to tweak the mock's behaviour. The <code>options</code> argument is a hash. Currently the only supported option is <code>:null_object</code>. Setting this to true instructs the mock to ignore (quietly consume) any messages it hasn't been told to expect.  I.e.:
+As above, but allows you to specific options to tweak the mock's behaviour. The 
+<code>options</code> argument is a hash. Currently the only supported option is 
+<code>:null_object</code>. Setting this to true instructs the mock to ignore 
+(quietly consume) any messages it hasn't been told to expect - and return itself.  I.e.:
 
 <ruby>
 my_mock = mock("blah", :null_object => true)
@@ -27,59 +31,52 @@ my_mock = mock("blah", :null_object => true)
 h3. Expecting Messages
 
 <ruby>
-my_mock.should_receivereceive(<message>)
+my_mock.should_receive(<message>)
 </ruby>
 
-The <code>message</code> argument is a symbol that is the name of a message that you want the mock to expect.
-
-h3. Arbitrary Handling of Received Messages
-
-You can supply a block to a message expectation. When the message is received
-by the mock, the block is evaluated, and passed any arguments. The result is
-the return value of the message. For example:
-
-<ruby>
-my_mock.should_receivereceive(:random_call) {| a | a.should_receivebe true}
-</ruby>
-
-This allows arbitrary argument validation and result computation.  It's handy and kind of cool to be able to do this, but I advise against it.  Mocks should not be functional.  they should be completely declarative.  That said, it's sometimes useful to give them some minimal behaviour.
+The <code>message</code> argument is a symbol that is the name of a message 
+that you want the mock to expect.
 
 h3. Expecting Arguments
 
 <ruby>
-my_mock.should_receivereceive(:msg).with(<args>)
+my_mock.should_receive(:msg).with(<args>)
 </ruby>
 
 for example: 
 
 <ruby>
-my_mock.should_receivereceive(:msg).with(1, 2, 3)
+my_mock.should_receive(:msg).with(1, 2, 3)
 </ruby>
 
-The <code>args</code> argument is a series of arguments (e.g. 1, 2, 3) that are expected to be passed as arguments to the associated message.
+The <code>args</code> argument is a series of arguments (e.g. 1, 2, 3) that are 
+expected to be passed as arguments to the associated message.
 
 <ruby>
-my_mock.should_receivereceive(:msg).with(:no_args)
+my_mock.should_receive(:msg).with(:no_args)
 </ruby>
 
 The message (<code>msg</code>) is expected to be passed no arguments.
 
 <ruby>
-my_mock.should_receivereceive(:msg).with(:any_args)
+my_mock.should_receive(:msg).with(:any_args)
 </ruby>
 
-Any arguments (and any number of arguments) are to be accepted. This includes cases where no arguments are provided. *This is the default when no <code>with()</code> clause is specified.*  Even so, sometimes you want to be explicit about it.
+Any arguments (and any number of arguments) are to be accepted. This includes 
+cases where no arguments are provided. *This is the default when no <code>with()</code> 
+clause is specified.*  Even so, sometimes you want to be explicit about it.
 
 h3. Argument Constraints
 
-Constraints can be placed on individual arguments which are looser than value equivalence (as above).
+Constraints can be placed on individual arguments which are looser than value 
+equivalence (as above).
 
 h4. :anything
 
 accepts any value for this argument, e.g.:
 
 <ruby>
-my_mock.should_receivereceive(:msg).with(1, :anything, "A")
+my_mock.should_receive(:msg).with(1, :anything, "A")
 </ruby>
 
 h4. :numeric
@@ -87,7 +84,7 @@ h4. :numeric
 accepts any numeric value for this argument, e.g.:
 
 <ruby>
-my_mock.should_receivereceive(:msg).with(a, :numeric, "b")
+my_mock.should_receive(:msg).with(a, :numeric, "b")
 </ruby>
 
 h4. :boolean
@@ -95,7 +92,7 @@ h4. :boolean
 accepts a boolean value for this argument, e.g.:
 
 <ruby>
-my_mock.should_receivereceive(:msg).with(a, :boolean, "b")
+my_mock.should_receive(:msg).with(a, :boolean, "b")
 </ruby>
 
 h4. :string
@@ -103,7 +100,7 @@ h4. :string
 accepts any string for this argument, e.g.:
 
 <ruby>
-my_mock.should_receivereceive(:msg).with(a, :string, "b")
+my_mock.should_receive(:msg).with(a, :string, "b")
 </ruby>
 	
 h4. duck_type(message(s))
@@ -112,55 +109,57 @@ accepts any object that responds to the prescribed message(s), e.g.:
 
 <ruby>
 #accepts a Fixnum for the second arg
-my_mock.should_receivereceive(:msg).with(a, duck_type(:abs, :div), "b") 
+my_mock.should_receive(:msg).with(a, duck_type(:abs, :div), "b") 
 </ruby>
 
 h3. Receive Counts
 
 <ruby>
-my_mock.should_receivereceive(:msg).never
+my_mock.should_receive(:msg).never
 </ruby>
 
 An exception is raised if the message is ever received.
+This is equivalent to not specifying the reception of :msg,
+but it's more declarative and useful for humans.
 
 <ruby>
-my_mock.should_receivereceive(:msg).any.number.of.times
+my_mock.should_receive(:msg).any_number_of_times
 </ruby>
 
 The message can be received 0 or more times.
 
 <ruby>
-my_mock.should_receivereceive(:msg).once
+my_mock.should_receive(:msg).once
 </ruby>
 
 An exception is raised if the message is never received, or it is received more than once.
 
 <ruby>
-my_mock.should_receivereceive(:msg).twice
+my_mock.should_receive(:msg).twice
 </ruby>
 
 An exception is raised if the message is received anything but two times.
 
 <ruby>
-my_mock.should_receivereceive(:msg).exactly(n).times
+my_mock.should_receive(:msg).exactly(n).times
 </ruby>
 
 An exception is raised if the message is received anything but <code>n</code> times.
 
 <ruby>
-my_mock.should_receivereceive(:msg).at.least(:once)
+my_mock.should_receive(:msg).at_least(:once)
 </ruby>
 
 An exception is raised if the message is never received.
 
 <ruby>
-my_mock.should_receivereceive(:msg).at.least(:twice)
+my_mock.should_receive(:msg).at_least(:twice)
 </ruby>
 
 An exception is raised if the message is never received or is received only once.
 
 <ruby>
-my_mock.should_receivereceive(:msg).at.least(n).times
+my_mock.should_receive(:msg).at_least(n).times
 </ruby>
 
 An exception is raised if the message is received fewer than <code>n</code> times.
@@ -170,7 +169,7 @@ h3. Return Values
 h4. Single return value
 
 <ruby>
-my_mock.should_receivereceive(:msg).once.and.return(<value>)
+my_mock.should_receive(:msg).once_and_return(<value>)
 </ruby>
 
 Each time the expected message is received, <code>value</code> will be returned as the result.
@@ -178,45 +177,51 @@ Each time the expected message is received, <code>value</code> will be returned
 h4. Consequtive return values
 
 <ruby>
-and.return([<value-1>, <value-2>, ..., <value-n>])
+and_return([<value-1>, <value-2>, ..., <value-n>])
 </ruby>
 
-When the expected message is received, <code>value-i</code> will be returned as the result for the ith reception of the message. After the message has been received <code>i</code> times, <code>value-n</code> is returned for all
+When the expected message is received, <code>value-i</code> will be returned as the result 
+for the ith reception of the message. After the message has been received <code>i</code> times, 
+<code>value-n</code> is returned for all
 subsequent receives.  
 
-*Note:* if you wish to have a single return value that is an array, you must use this form, with one item that is the array to return.  Otherwise your array will be interpreted as a series of return values.  For example:
+*Note:* if you wish to have a single return value that is an array, you must use this form, with 
+one item that is the array to return.  Otherwise your array will be interpreted as a series of return values.  
+For example:
 
 <ruby>  
-and.return([[1, 2, 3]])
+and_return([[1, 2, 3]])
 </ruby>
 
 h4. Computed return value
 
 <ruby>
-my_mock.should_receivereceive(:msg).once.and.return {...} 
+my_mock.should_receive(:msg).once_and_return {...} 
 </ruby>
 
 When the expected message is received, the result of evaluating the supplied
 block will be returned as the result. The block is passed any arguments passed
-as arguments of the message. This capability can be used to compute return values based on the arguments.  For example:
+as arguments of the message. This capability can be used to compute return 
+values based on the arguments.  For example:
 
 <ruby>
-my_mock.should_receivereceive(:msg).with(:numeric, :numeric) once.and.return {|a, b| a + b}
+my_mock.should_receive(:msg).with(:numeric, :numeric) once_and_return {|a, b| a + b}
 </ruby>
 
 h3. Raising and Throwing
 
 <ruby>
-my_mock.should_receivereceive(:msg).once.and.raise(<exception>)
-my_mock.should_receivereceive(:msg).once.and.throw(<symbol>) 
+my_mock.should_receive(:msg).once_and_raise(<exception>)
+my_mock.should_receive(:msg).once_and_throw(<symbol>) 
 </ruby>
 
-These instruct the mock to raise an exception or throw a symbol, respectively, instead of returning a value.
+These instruct the mock to raise an exception or throw a symbol, respectively, 
+instead of returning a value.
 
 h3. Yielding
 
 <ruby>
-my_mock.should_receivereceive(:msg).once.and.yield([<value-1>, <value-2>, ..., <value-n>])
+my_mock.should_receive(:msg).once_and_yield([<value-1>, <value-2>, ..., <value-n>])
 </ruby>
 
 When the expected message is received, the mock will yield the values to the passed block.
@@ -229,8 +234,8 @@ It shouldn't be the case very often, but it can be handy at times.
 Labeling expectations as being ordered is done by the <code>ordered</code> call:
 
 <ruby>
-my_mock.should_receivereceive(:flip).once.ordered
-my_mock.should_receivereceive(:flop).once.ordered
+my_mock.should_receive(:flip).once.ordered
+my_mock.should_receive(:flop).once.ordered
 </ruby>
 
 If the send of <code>flop</code> is seen before <code>flip</code> the specification will fail.
@@ -238,22 +243,45 @@ If the send of <code>flop</code> is seen before <code>flip</code> the specificat
 Of course, chains of ordered expectations can be set up:
 
 <ruby>
-my_mock.should_receivereceive(:one).ordered
-my_mock.should_receivereceive(:two).ordered
-my_mock.should_receivereceive(:three).ordered
+my_mock.should_receive(:one).ordered
+my_mock.should_receive(:two).ordered
+my_mock.should_receive(:three).ordered
 </ruby>
 
 The expected order is the order in which the expectations are declared.
 
-Order-independant expectations can be set anywhere in the expectation sequence, in any order.  Only the order of expectations tagged with the <code>ordered</code> call is significant.  Likewise, calls to order-independant methods can be made in any order, even interspersed with calls to order-dependant methods.  For example:
+Order-independent expectations can be set anywhere in the expectation sequence, in any order.  
+Only the order of expectations tagged with the <code>ordered</code> call is significant.  
+Likewise, calls to order-independent methods can be made in any order, even interspersed with 
+calls to order-dependent methods.  For example:
 
 <ruby>
-  my_mock.should_receivereceive(:zero)
-  my_mock.should_receivereceive(:one).ordered
-  my_mock.should_receivereceive(:two).ordered
-  my_mock.should_receivereceive(:one_and_a_half)
+  my_mock.should_receive(:zero)
+  my_mock.should_receive(:one).ordered
+  my_mock.should_receive(:two).ordered
+  my_mock.should_receive(:one_and_a_half)
+
+  # This will pass:
   my_mock.one
   my_mock.one_and_a_half
   my_mock.zero
   my_mock.two
-</ruby>
+</ruby>
+
+h3. Arbitrary Handling of Received Messages
+
+You can supply a block to a message expectation. When the message is received
+by the mock, the block is passed any arguments and evaluated. The result is
+the return value of the block. For example:
+
+<ruby>
+my_mock.should_receive(:msg) { |a, b| 
+  a.should_be true
+  b.should_not_contain('mice')
+  "Chunky bacon!"
+}
+</ruby>
+
+This allows arbitrary argument validation and result computation.  It's handy and kind of cool to be able to 
+do this, but it is advised to not use this form in most situations.  Mocks should not be functional.  
+They should be completely declarative.  That said, it's sometimes useful to give them some minimal behaviour.