flexmock 1.2.0 → 1.3.0

data/Gemfile

@@ -5,4 +5,7 @@ gem 'rake', ">= 0.9.2.2"
 
 group 'dev' do
   gem 'rdoc'
+  gem 'flog'
+  gem 'flay'
+  gem 'ghpreview'
 end

data/Gemfile.lock

@@ -1,11 +1,56 @@
 GEM
   remote: http://rubygems.org/
   specs:
+    activesupport (3.2.11)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    blankslate (3.1.2)
+    charlock_holmes (0.6.9)
     diff-lcs (1.1.3)
+    escape_utils (0.2.4)
+    ffi (1.0.11)
+    flay (2.0.1)
+      ruby_parser (~> 3.0)
+      sexp_processor (~> 4.0)
+    flog (3.2.2)
+      ruby_parser (~> 3.1, > 3.1.0)
+      sexp_processor (~> 4.0)
+    gemoji (1.4.0)
+    ghpreview (0.0.6)
+      github-linguist (= 2.1)
+      html-pipeline (= 0.0.6)
+      httpclient
+      listen
+      rb-fsevent
+    github-linguist (2.1.0)
+      charlock_holmes (~> 0.6.6)
+      escape_utils (~> 0.2.3)
+      mime-types (~> 1.18)
+      pygments.rb (~> 0.2.13)
+    github-markdown (0.5.3)
+    html-pipeline (0.0.6)
+      activesupport (>= 2)
+      escape_utils (~> 0.2)
+      gemoji (~> 1.0)
+      github-linguist (~> 2.1)
+      github-markdown (~> 0.5)
+      nokogiri (~> 1.4)
+      rinku (~> 1.7)
+      sanitize (~> 2.0)
+    httpclient (2.3.2)
+    i18n (0.6.1)
     json (1.7.5)
+    listen (0.7.2)
+    mime-types (1.19)
+    multi_json (1.5.0)
+    nokogiri (1.5.6)
+    pygments.rb (0.2.13)
+      rubypython (~> 0.5.3)
     rake (0.9.2.2)
+    rb-fsevent (0.9.3)
     rdoc (3.12)
       json (~> 1.4)
+    rinku (1.7.2)
     rspec (2.11.0)
       rspec-core (~> 2.11.0)
       rspec-expectations (~> 2.11.0)
@@ -14,11 +59,23 @@ GEM
     rspec-expectations (2.11.2)
       diff-lcs (~> 1.1.3)
     rspec-mocks (2.11.2)
+    ruby_parser (3.1.1)
+      sexp_processor (~> 4.1)
+    rubypython (0.5.3)
+      blankslate (>= 2.1.2.3)
+      ffi (~> 1.0.7)
+    sanitize (2.0.3)
+      nokogiri (>= 1.4.4, < 1.6)
+      nokogiri (>= 1.4.4, < 1.6)
+    sexp_processor (4.1.4)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  flay
+  flog
+  ghpreview
   rake (>= 0.9.2.2)
   rdoc
   rspec (>= 2.0)

data/{README.rdoc → README.md}

@@ -1,34 +1,37 @@
-= Flex Mock -- Making Mocking Easy
+# Flex Mock -- Making Mocking Easy
 
 FlexMock is a simple, but flexible, mock object library for Ruby unit
 testing.
 
-Version :: 1.2.0
+Version: 1.3.0
 
-= Links
+# Links
 
-<b>Documents</b>                    :: http://flexmock.rubyforge.org
-<b>RubyGems</b>                     :: Install with: <b>gem install flexmock</b>
-<b>Source</b>                       :: https://github.com/jimweirich/flexmock
-<b>Bug Reports / Issue Tracking</b> :: https://github.com/jimweirich/flexmock/issues
-<b>Continuous Integration</b>       :: http://travis-ci.org/#!/jimweirich/flexmock
+* **Documents** -- http://flexmock.rubyforge.org
+* **RubyGems**   -- Install with: `gem install flexmock`
+* **Source** -- https://github.com/jimweirich/flexmock
+* **Bug Reports / Issue Tracking** -- https://github.com/jimweirich/flexmock/issues
+* **Continuous Integration** -- http://travis-ci.org/#!/jimweirich/flexmock
 
-== Installation
+## Installation
 
 You can install FlexMock with the following command.
 
+```
  $ gem install flexmock
+```
 
-== Simple Example
+## Simple Example
 
 We have a data acquisition class (<code>TemperatureSampler</code>)
 that reads a temperature sensor and returns an average of 3 readings.
 We don't have a _real_ temperature to use for testing, so we mock one
 up with a mock object that responds to the
-<code>read_temperature</code> message.
+`read_temperature` message.
 
 Here's the complete example:
 
+```ruby
   require 'test/unit'
   require 'flexmock/test_unit'
 
@@ -55,20 +58,23 @@ Here's the complete example:
       assert_equal 12, sampler.average_temp
     end
   end
+```
 
-You can find an extended example of FlexMock in {Google
-Example}[http://flexmock.rubyforge.org/files/doc/GoogleExample_rdoc.html].
+You can find an extended example of FlexMock in
+[Google Example](http://flexmock.rubyforge.org/files/doc/GoogleExample_rdoc.html
+"Example").
 
-== Test::Unit Integration
+## Test::Unit Integration
 
 FlexMock integrates nicely with Test::Unit. Just require the
 'flexmock/test_unit' file at the top of your test file. The
-<code>flexmock</code> method will be available for mock creation, and
+`flexmock` method will be available for mock creation, and
 any created mocks will be automatically validated and closed at the
 end of the individual test.
 
 Your test case will look something like this:
 
+```ruby
   require 'flexmock/test_unit'
 
   class TestDog < Test::Unit::TestCase
@@ -77,19 +83,21 @@ Your test case will look something like this:
       assert_equal :happy, tail_mock.wag
     end
   end
+```
 
-<b>NOTE:</b> If you don't want to automatically extend every TestCase
+**NOTE:** If you don't want to automatically extend every TestCase
 with the flexmock methods and overhead, then require the 'flexmock'
 file and explicitly include the FlexMock::TestCase module in each test
 case class where you wish to use mock objects. FlexMock versions prior
 to 0.6.0 required the explicit include.
 
-== RSpec Integration
+## RSpec Integration
 
 FlexMock also supports integration with the RSpec behavior
 specification framework.  Starting with version 0.9.0 of RSpec, you
 will be able to say:
 
+```ruby
   RSpec.configure do |config|
     config.mock_with :flexmock
   end
@@ -100,21 +108,24 @@ will be able to say:
       m.foo.should === :bar
     end
   end
+```
 
-<b>NOTE:</b> <em>Older versions of RSpec used the Spec::Runner for
+**NOTE:** _Older versions of RSpec used the Spec::Runner for
 configuration. If you are running with a very old RSpec, you may need
-the following:</em>
+the following:_
 
+```ruby
   # Configuration for RSpec prior to RSpec 2.x
   Spec::Runner.configure do |config|
     config.mock_with :flexmock
   end
+```
 
-== Quick Reference
+## Quick Reference
 
-=== Creating Mock Objects
+### Creating Mock Objects
 
-The <code>flexmock</code> method is used to create mocks in various
+The `flexmock` method is used to create mocks in various
 configurations. Here's a quick rundown of the most common options. See
 FlexMock::MockContainer#flexmock for more details.
 
@@ -134,7 +145,7 @@ FlexMock::MockContainer#flexmock for more details.
   You can combine the mock name and an expectation hash in the same
   call to flexmock.
 
-* <b>mock = flexmock("joe", :on, User)</b>
+* <b>mock = flexmock("joe", :on, <em>User</em>)</b>
 
   This defines a mock that is based on the User class (the class is
   called the mock's "base class"). Mocks with base classes prevent you
@@ -142,29 +153,28 @@ FlexMock::MockContainer#flexmock for more details.
   the base class. This helps prevent tests from becoming stale with
   incorrectly mocked objects when the method names change.
 
-  Use the <code>explicitly</code> modifier to
-  <code>should_receive</code> to override base class restrictions.
+  Use the `explicitly` modifier to `should_receive` to override base
+  class restrictions.
 
-* <b>partial_mock = flexmock(real_object)</b>
+* <b>partial_mock = flexmock(<em>real_object</em>)</b>
 
-  If you you give <code>flexmock</code> a real object in the argument
-  list, it will treat that real object as a base for a partial mock
-  object. The return value <code>partial_mock</code> may be used to
-  set expectations. The real_object should be used in the reference
-  portion of the test.
+  If you you give `flexmock` a real object in the argument list, it
+  will treat that real object as a base for a partial mock object. The
+  return value `partial_mock` may be used to set expectations. The
+  real_object should be used in the reference portion of the test.
 
-* <b>partial_mock = flexmock(real_object, "name", :foo => :baz)</b>
+* <b>partial_mock = flexmock(<em>real_object</em>, "name", :foo => :baz)</b>
 
   Names and expectation hashes may be used with partial mocks as well.
 
-* <b>partial_mock = flexmock(:base, real_string_object)</b>
+* <b>partial_mock = flexmock(:base, <em>real_string_object</em>)</b>
 
   Since Strings (and Symbols for that matter) are used for mock names,
   FlexMock will not recognize them as the base for a partial mock. To
   force a string to be used as a partial mock base, proceed the string
   object in the calling sequence with :base.
 
-* <b>partial_mock = flexmock(:safe, real_object) { |mock| mock.should_receive(...) }</b>
+* <b>partial_mock = flexmock(:safe, <em>real_object</em>) { |mock| mock.should_receive(...) }</b>
 
   When mocking real objects (i.e. "partial mocks"), FlexMock will add
   a handful of mock related methods to the actual object (see below
@@ -174,9 +184,9 @@ FlexMock::MockContainer#flexmock for more details.
 
   FlexMock offers a "safe" mode for partial mocks that does not add
   these methods. Indicate safe mode by passing the symbol :safe as the
-  first argument of flexmock. A block <em>is required</em> when using
-  safe mode (the partial_mock returned in safe mode does not have a
-  <code>should_receive</code> method).
+  first argument of flexmock. A block _is required_ when using safe
+  mode (the partial_mock returned in safe mode does not have a
+  `should_receive` method).
 
   The methods added to partial mocks in non-safe mode are:
 
@@ -190,19 +200,19 @@ FlexMock::MockContainer#flexmock for more details.
 
 * <b>mock = flexmock(...) { |mock| mock.should_receive(...) }</b>
 
-  If a block is given to any of the <code>flexmock</code> forms, the
-  mock object will be passed to the block as an argument. Code in the
-  block can set the desired expectations for the mock object.
+  If a block is given to any of the `flexmock` forms, the mock object
+  will be passed to the block as an argument. Code in the block can
+  set the desired expectations for the mock object.
 
-* <b>mock_model = flexmock(:model, YourModel, ...) { |mock| mock.should_receive(...) }</b>
+* <b>mock_model = flexmock(:model, <em>YourModel</em>, ...) { |mock| mock.should_receive(...) }</b>
 
-  When given :model, flexmock() will return a pure mock (not a partial
-  mock) that will have some ActiveRecord specific methods defined.
-  YourModel should be the class of an ActiveRecord model.  These
-  predefined methods make it a bit easier to mock out ActiveRecord
-  model objects in a Rails application.  Other that the predefined
-  mocked methods, the mock returned is a standard FlexMock mock
-  object.
+  When given `:model`, `flexmock()` will return a pure mock (not a
+  partial mock) that will have some ActiveRecord specific methods
+  defined. YourModel should be the class of an ActiveRecord model.
+  These predefined methods make it a bit easier to mock out
+  ActiveRecord model objects in a Rails application. Other that the
+  predefined mocked methods, the mock returned is a standard FlexMock
+  mock object.
 
   The predefined mocked methods are:
 
@@ -215,44 +225,48 @@ FlexMock::MockContainer#flexmock for more details.
   * kind_of?(class) -- returns true if class is YourModel or one of its ancestors
   * class -- returns YourModel.
 
-* <b>mock = flexmock(... :spy_on, class_object, ...)</b>
+* <b>mock = flexmock(... :on, <em>class_object</em>, ...)</b>
 
-<b>NOTE:</b> Versions of FlexMock prior to 0.6.0 used
-<code>flexstub</code> to create partial mocks. The
-<code>flexmock</code> method now assumes all the functionality that
-was spread out between two different methods. <code>flexstub</code> is
-still available for backward compatibility.
+**NOTE:** Versions of FlexMock prior to 0.6.0 used `flexstub` to
+create partial mocks. The `flexmock` method now assumes all the
+functionality that was spread out between two different methods.
+`flexstub` is deprecated, but still available for backward
+compatibility.
 
-=== Expectation Declarators
+### Expectation Declarators
 
 Once a mock is created, you need to define what that mock should
 expect to see. Expectation declarators are used to specify these
 expectations placed upon received method calls. A basic expectation,
-created with the <code>should_receive</code> method, just establishes
-the fact that a method may (or may not) be called on the mock object.
+created with the `should_receive` method, just establishes the fact
+that a method may (or may not) be called on the mock object.
 Refinements to that expectation may be additionally declared. FlexMock
 always starts with the most general expectation and adds constraints
 to that.
 
 For example, the following code:
 
+```ruby
     mock.should_receive(:average).and_return(12)
+```
 
 Means that the mock will now accept method calls to an
-<code>average</code> method. The expectation will accept any arguments
+`average` method. The expectation will accept any arguments
 and may be called any number of times (including zero times). Strictly
-speaking, the <code>and_return</code> part of the declaration isn't
+speaking, the `and_return` part of the declaration isn't
 exactly a constraint, but it does specify what value the mock will
 return when the expectation is matched.
 
 If you want to be more specific, you need to add additional
 constraints to your expectation. Here are some examples:
 
+```ruby
     mock.should_receive(:average).with(12).once
 
     mock.should_receive(:average).with(Integer).
         at_least.twice.at_most.times(10).
         and_return { rand }
+```
 
 Expectation are always matched in order of declaration. That means if
 you have a general expectation before a more specific expectation, the
@@ -261,8 +275,10 @@ effectively hiding the second expectation.
 
 For example:
 
+```ruby
     mock.should_receive(:average)              # Matches any call to average
     mock.should_receive(:average).with(1).once # Fails because it never matches
+```
 
 In the example, the second expectation will never be triggered because
 all calls to average will be handled by the first expectation. Since
@@ -272,15 +288,17 @@ fail.
 Reversing the order of the expections so that the more specific
 expectation comes first will fix that problem.
 
-If an expectation has a count requirement (e.g. <code>once</code> or
-<code>times</code>), then once it has matched its expected number of
-times, it will let other expectations have a chance to match.
+If an expectation has a count requirement (e.g. `once` or `times`),
+then once it has matched its expected number of times, it will let
+other expectations have a chance to match.
 
 For example:
 
+```ruby
     mock.should_receive(:average).once.and_return(1)
     mock.should_receive(:average).once.and_return(2)
     mock.should_receive(:average).and_return(3)
+```
 
 In the example, the first time average is called, the first
 expectation is matched an average will return 1. The second time
@@ -290,21 +308,20 @@ will be used.
 
 Occasionally it is useful define a set of expecations in a setup
 method of a test and override those expectations in specific tests. If
-you mark an expectation with the <code>by_default</code> marker, that
-expectation will be used only if there are no non-default expectations
-on that method name. See "by_default" below.
+you mark an expectation with the `by_default` marker, that expectation
+will be used only if there are no non-default expectations on that
+method name. See "by_default" below.
 
-=== Expectation Criteria
+### Expectation Criteria
 
 The following methods may be used to create and refine expectations on
 a mock object. See theFlexMock::Expectation for more details.
 
 * <b>should_receive(<em>method_name</em>)</b>
 
-  Declares that a message named <em>method_name</em> will be sent to
-  the mock object. Constraints on this expected message (called
-  expectations) may be chained to the <code>should_receive</code>
-  call.
+  Declares that a message named _method_name_ will be sent to the mock
+  object. Constraints on this expected message (called expectations)
+  may be chained to the `should_receive` call.
 
 * <b>should_receive(<em>method_name1</em>, <em>method_name2</em>, ...)</b>
 
@@ -317,11 +334,10 @@ a mock object. See theFlexMock::Expectation for more details.
 
 * <b>should_receive(...).explicitly</b>
 
-  If a mock has a base class, use the <code>explicitly</code> modifier
-  to override the restriction on method names imposed by the base
-  class. The <code>explicitly</code> modifier must come immediately
-  after the <code>should_receive</code> call and before any other
-  expectation declarators.
+  If a mock has a base class, use the `explicitly` modifier to
+  override the restriction on method names imposed by the base class.
+  The `explicitly` modifier must come immediately after the
+  `should_receive` call and before any other expectation declarators.
 
   If a mock does not have a base class, this method has no effect.
 
@@ -329,18 +345,18 @@ a mock object. See theFlexMock::Expectation for more details.
 
   Creates a mock recording object that will translate received method
   calls into mock expectations. The recorder is passed to a block
-  supplied with the <code>should_expect</code> method. See examples
+  supplied with the `should_expect` method. See examples
   below.
 
 * <b>with(<em>arglist</em>)</b>
 
   Declares that this expectation matches messages that match the given
-  argument list. The <code>===</code> operator is used on a argument by
-  argument basis to determine matching. This means that most literal
-  values match literally, class values match any instance of a class
-  and regular expression match any matching string (after a
-  <code>to_s</code> conversion). See argument validators (below) for
-  details on argument validation options.
+  argument list. The `===` operator is used on a argument by argument
+  basis to determine matching. This means that most literal values
+  match literally, class values match any instance of a class and
+  regular expression match any matching string (after a `to_s`
+  conversion). See argument validators (below) for details on argument
+  validation options.
 
 * <b>with_any_args</b>
 
@@ -354,41 +370,41 @@ a mock object. See theFlexMock::Expectation for more details.
 * <b>zero_or_more_times</b>
 
   Declares that the expected message is may be sent zero or more times
-  (default, equivalent to <code>at_least.never</code>).
+  (default, equivalent to `at_least.never`).
 
 * <b>once</b>
 
-  Declares that the expected message is only sent once.
-  <code>at_least</code> / <code>at_most</code> modifiers are allowed.
+  Declares that the expected message is only sent once. `at_least` /
+  `at_most` modifiers are allowed.
 
 * <b>twice</b>
 
-  Declares that the expected message is only sent twice. <code>at_least</code> /
-  <code>at_most</code> modifiers are allowed.
+  Declares that the expected message is only sent twice. `at_least` /
+  `at_most` modifiers are allowed.
 
 * <b>never</b>
 
-  Declares that the expected message is never sent. <code>at_least</code> /
-  <code>at_most</code> modifiers are allowed.
+  Declares that the expected message is never sent. `at_least` /
+  `at_most` modifiers are allowed.
 
 * <b>times(<em>n</em>)</b>
 
-  Declares that the expected message is sent <em>n</em> times.
-  <code>at_least</code> / <code>at_most</code> modifiers are allowed.
+  Declares that the expected message is sent _n_ times. `at_least` /
+  `at_most` modifiers are allowed.
 
 * <b>at_least</b>
 
   Modifies the immediately following message count constraint so that
   it means the message is sent at least that number of times. E.g.
-  <code>at_least.once</code> means the message is sent at least once
-  during the test, but may be sent more often. Both <code>at_least</code>
-  and <code>at_most</code> may be specified on the same expectation.
+  `at_least.once` means the message is sent at least once during the
+  test, but may be sent more often. Both `at_least` and `at_most` may
+  be specified on the same expectation.
 
 * <b>at_most</b>
 
-  Similar to <code>at_least</code>, but puts an upper limit on the number
-  of messages. Both <code>at_least</code> and <code>at_most</code> may be
-  specified on the same expectation.
+  Similar to `at_least`, but puts an upper limit on the number of
+  messages. Both `at_least` and `at_most` may be specified on the same
+  expectation.
 
 * <b>ordered</b>
 
@@ -409,18 +425,19 @@ a mock object. See theFlexMock::Expectation for more details.
   outside the group must be received either before or after all of the
   grouped messages.
 
-  For example, in the following, messages <code>flip</code> and
-  <code>flop</code> may be received in any order (because they are in
-  the same group), but must occur strictly after <code>start</code>
-  but before <code>end</code>. The message <code>any_time</code> may
-  be received at any time because it is not ordered.
+  For example, in the following, messages `flip` and `flop` may be
+  received in any order (because they are in the same group), but must
+  occur strictly after `start` but before `end`. The message
+  `any_time` may be received at any time because it is not ordered.
 
+```ruby
     m = flexmock()
     m.should_receive(:any_time)
     m.should_receive(:start).ordered
     m.should_receive(:flip).ordered(:flip_flop_group)
     m.should_receive(:flop).ordered(:flip_flop_group)
     m.should_receive(:end).ordered
+```
 
   Normally ordering is performed only against calls in the same mock
   object.  If the "globally" adjective is used, then ordering is
@@ -446,12 +463,11 @@ a mock object. See theFlexMock::Expectation for more details.
   for various methods in the setup of a test suite, and then override
   only the methods that need special handling in any given test.
 
-=== Expectation Actions
+### Expectation Actions
 
-Action expectations are used to specify what the mock should
-<em>do</em> when the expectation is matched. The actions themselves do
-not take part in determining whether a given expectation matches or
-not.
+Action expectations are used to specify what the mock should _do_ when
+the expectation is matched. The actions themselves do not take part in
+determining whether a given expectation matches or not.
 
 * <b>and_return(<em>value</em>)</b>
 
@@ -464,7 +480,7 @@ not.
   series. The last value will be repeatably returned if the number of
   matching calls exceeds the number of values.
 
-* <b>and_return { |<em>args</em>, ...|  <em>code</em> ... } </b>
+* <b>and_return { |<em>args</em>, ...|  <em>code</em> ... }</b>
 
   Declares that the expected message will return the yielded value of
   the block. The block will receive all the arguments in the message.
@@ -473,7 +489,7 @@ not.
 
 * <b>returns( ... )</b>
 
-  Alias for <code>and_return</code>.
+  Alias for `and_return`.
 
 * <b>and_return_undefined</b>
 
@@ -482,20 +498,19 @@ not.
 
 * <b>returns_undefined</b>
 
-  Alias for <code>and_returns_undefined</code>
+  Alias for `and_returns_undefined`
 
-* <b>and_raise(<em>exception</em>, <em>*args</em>)</b>
+* <b>and_raise(_exception_, _*args_)</b>
 
   Declares that the expected message will raise the specified
-  exception. If <code>exception</code> is an exception class, then the
-  raised exception will be constructed from the class with
-  <code>new</code> given the supplied arguments. If
-  <code>exception</code> is an instance of an exception class, then it
-  will be raised directly.
+  exception. If `exception` is an exception class, then the raised
+  exception will be constructed from the class with `new` given the
+  supplied arguments. If `exception` is an instance of an exception
+  class, then it will be raised directly.
 
 * <b>raises( ... )</b>
 
-  Alias for <code>and_raise</code>.
+  Alias for `and_raise`.
 
 * <b>and_throw(<em>symbol</em>)</b>
 * <b>and_throw(<em>symbol</em>, <em>value</em>)</b>
@@ -506,86 +521,95 @@ not.
 
 * <b>throws( ... )</b>
 
-  Alias for <code>and_throw</code>.
+  Alias for `and_throw`.
 
 * <b>and_yield(<em>values</em>, ...)</b>
 
   Declares that the mocked method will receive a block, and the mock
   will call that block with the values given. Not providing a block
-  will be an error. Providing more than one <code>and_yield</code>
-  clause one a single expectation will mean that subsquent mock method
-  calls will yield the values provided by the additional
-  <code>and_yield</code> clause.
+  will be an error. Providing more than one `and_yield` clause one a
+  single expectation will mean that subsquent mock method calls will
+  yield the values provided by the additional `and_yield` clause.
 
 * <b>yields( ... )</b>
 
-  Alias for <code>and_yield( ... )</code>.
+  Alias for `and_yield( ... )`.
 
 * <b>pass_thru</b>
-* <b>pass_thru { |value| .... }</b>
+* <b>pass_thru { |<em>value</em>| .... }</b>
 
   Declares that the expected message will allow the method to be
   passed to the original method definition in the partial mock object.
-  <code>pass_thru</code> is also allowed on regular mocks, but since
-  there is no original method to be called, pass_thru will always
-  return the undefined object.
+  `pass_thru` is also allowed on regular mocks, but since there is no
+  original method to be called, pass_thru will always return the
+  undefined object.
 
-  If a block is supplied to pass_thru, the value returned from the
+  If a block is supplied to `pass_thru`, the value returned from the
   original method will be passed to the block and the value of the
   block will be returned. This allows you to mock methods on the
   returned value.
 
+```ruby
     Dog.should_receive(:new).pass_thru { |dog|
       flexmock(dog, :wag => true)
     }
+```
 
-=== Other Expectation Methods
+### Other Expectation Methods
 
 * <b>mock</b>
 
   Expectation constraints always return the expectation so that the
   constraints can be chained. If you wish to do a one-liner and assign
-  the mock to a variable, the <code>mock</code> method on an
-  expectation will return the original mock object.
+  the mock to a variable, the `mock` method on an expectation will
+  return the original mock object.
 
+```ruby
     m = flexmock.should_receive(:hello).once.and_return("World").mock
+```
 
-  <b>NOTE:</b> <em>Using <b>mock</b> when specifying a Demeter mock
+  **NOTE:** _Using **mock** when specifying a Demeter mock
   chain will return the last mock of the chain, which might not be
-  what you expect.</em>
+  what you expect._
 
-=== Argument Validation
+### Argument Validation
 
-The values passed to the <code>with</code> declarator determine the
-criteria for matching expectations. The first expectation found that
-matches the arguments in a mock method call will be used to validate
-that mock method call.
+The values passed to the `with` declarator determine the criteria for
+matching expectations. The first expectation found that matches the
+arguments in a mock method call will be used to validate that mock
+method call.
 
 The following rules are used for argument matching:
 
-* A <code>with</code> parameter that is a class object will match any
+* A `with` parameter that is a class object will match any
   actual argument that is an instance of that class.
 
   Examples:
 
+```ruby
      with(Integer)     will match    f(3)
+```
 
 * A regular expression will match any actual argument that matches the
   regular expression. Non-string actual arguments are converted to
-  strings via <code>to_s</code> before applying the regular
+  strings via `to_s` before applying the regular
   expression.
 
   Examples:
 
+```ruby
     with(/^src/)      will match    f("src_object")
     with(/^3\./)      will match    f(3.1415972)
+```
 
 * Most other objects will match based on equal values.
 
   Examples:
 
+```ruby
       with(3)         will match    f(3)
       with("hello")   will match    f("hello")
+```
 
 * If you wish to override the default matching behavior and force
   matching by equality, you can use the FlexMock.eq convenience
@@ -595,79 +619,97 @@ The following rules are used for argument matching:
 
   Examples:
 
+```ruby
       with(eq(Integer))             will match       f(Integer)
       with(eq(Integer))             will NOT match   f(3)
+```
 
-  <b>Note:</b> If you do not use the FlexMock::TestCase Test Unit
+  **Note:** <em>If you do not use the FlexMock::TestCase Test Unit
   integration module, or the FlexMock::ArgumentTypes module, you will
-  have to fully qualify the <code>eq</code> method. This is true of
-  all the special argument matches (<code>eq</code>, <code>on</code>,
-  <code>any</code>, <code>hsh</code> and <code>ducktype</code>).
+  have to fully qualify the `eq` method. This is true of all the
+  special argument matches (`eq`, `on`, `any`, `hsh` and
+  `ducktype`).</em>
 
+```ruby
       with(FlexMock.eq(Integer))
       with(FlexMock.on { code })
       with(FlexMock.any)
       with(FlexMock.hsh(:tag => 3))
       with(FlexMock.ducktype(:wag, :bark))
+```
 
 * If you wish to match a hash on _some_ of its values, the
-  FlexMock.hsh(...) method will work.  Only specify the hash values
+  `FlexMock.hsh(...)` method will work. Only specify the hash values
   you are interested in, the others will be ignored.
 
+```ruby
       with(hsh(:run => true))  will match    f(:run => true, :stop => false)
+```
 
 * If you wish to match any object that responds to a certain set of
-  methods, use the FlexMock.ducktype method.
+  methods, use the `FlexMock.ducktype` method.
 
+
+```ruby
       with(ducktype(:to_str))     will match   f("string")
       with(ducktype(:wag, :bark)) will match   f(dog)
                                   (assuming dog implements wag and bark)
+```
 
-* If you wish to match _anything_, then use the <code>FlexMock.any</code>
-  method in the with argument list.
+* If you wish to match _anything_, then use the `FlexMock.any` method
+  in the with argument list.
 
   Examples (assumes either the FlexMock::TestCase or FlexMock::ArgumentTypes
   mix-ins has been included):
 
+```ruby
       with(any)             will match       f(3)
       with(any)             will match       f("hello")
       with(any)             will match       f(Integer)
       with(any)             will match       f(nil)
+```
 
 * If you wish to specify a complex matching criteria, use the
-  <code>FlexMock.on(&block)</code> with the logic contained in the block.
+  `FlexMock.on(&block)` with the logic contained in the block.
 
-  Examples (assumes FlexMock::ArgumentTypes has been included):
+  Examples (assumes `FlexMock::ArgumentTypes` has been included):
 
+```ruby
       with(on { |arg| (arg % 2) == 0 } )
+```
 
   will match any even integer.
 
 * If you wish to match a method call where a block is given, add
-  <code>Proc</code> as the last argument to <code>with</code>.
+  `Proc` as the last argument to `with`.
 
   Example:
 
+```ruby
       m.should_receive(:foo).with(Integer,Proc).and_return(:got_block)
       m.should_receive(:foo).with(Integer).and_return(:no_block)
+```
 
   will cause the mock to return the following:
 
+```ruby
      m.foo(1) { } => returns :got_block
      m.foo(1)     => returns :no_block
+```
 
-=== Creating Partial Mocks
+### Creating Partial Mocks
 
 Sometimes it is useful to mock the behavior of one or two methods in
 an existing object without changing the behavior of the rest of the
-object. If you pass a real object to the <code>flexmock</code> method,
-it will allow you to use that real object in your test and will just
-mock out the one or two methods that you specify.
+object. If you pass a real object to the `flexmock` method, it will
+allow you to use that real object in your test and will just mock out
+the one or two methods that you specify.
 
 For example, suppose that a Dog object uses a Woofer object to bark.
 The code for Dog looks like this (we will leave the code for Woofer to
 your imagination):
 
+```ruby
   class Dog
     def initialize
       @woofer = Woofer.new
@@ -679,16 +721,18 @@ your imagination):
       :happy
     end
   end
+```
 
 Now we want to test Dog, but using a real Woofer object in the test is
 a real pain (why? ... well because Woofer plays a sound file of a dog
 barking, and that's really annoying during testing).
 
 So, how can we create a Dog object with mocked Woofer? All we need to
-do is allow FlexMock to replace the <code>bark</code> method.
+do is allow FlexMock to replace the `bark` method.
 
 Here's the test code:
 
+```ruby
   class TestDogBarking < Test::Unit::TestCase
     include FlexMock::TestCase
 
@@ -704,29 +748,31 @@ Here's the test code:
       assert_equal :happy, @dog.wag    # Normal Method
     end
   end
+```
 
 The nice thing about this technique is that after the test is over,
 the mocked out methods are returned to their normal state. Outside the
 test everything is back to normal.
 
-<b>NOTE:</b> In previous versions of FlexMock, partial mocking was
-called "stubs" and the <code>flexstub</code> method was used to create
-the partial mocks. Although partial mocks were often used as stubs,
-the terminology was not quite correct. The current version of FlexMock
-uses the <code>flexmock</code> method to create both regular stubs and
-partial stubs. A version of the <code>flexstub</code> method is
-included for backwards compatibility. See Martin Fowler's article
-<em>Mocks Aren't Stubs</em>
-(http://www.martinfowler.com/articles/mocksArentStubs.html) for a
-better understanding of the difference between mocks and stubs.
+**NOTE:** <em>In previous versions of FlexMock, partial mocking was
+called "stubs" and the `flexstub` method was used to create the
+partial mocks. Although partial mocks were often used as stubs, the
+terminology was not quite correct. The current version of FlexMock
+uses the `flexmock` method to create both regular stubs and partial
+stubs. A version of the `flexstub` method is included for backwards
+compatibility. See Martin Fowler's article
+[_Mocks Aren't Stubs_](http://www.martinfowler.com/articles/mocksArentStubs.html
+"Mocks Aren't Stubs") for a better understanding of the difference
+between mocks and stubs.</em>
 
-This partial mocking technique was inspired by the <code>Stuba</code>
-library in the <code>Mocha</code> project.
+This partial mocking technique was inspired by the `Stuba` library in
+the `Mocha` project.
 
-=== Spies
+### Spies
 
 FlexMock supports spy-like mocks as well as the traditional mocks.
 
+```ruby
   # In Test::Unit / MiniTest
   class TestDogBarking < Test::Unit::TestCase
     def test_dog
@@ -744,11 +790,13 @@ FlexMock supports spy-like mocks as well as the traditional mocks.
       dog.should have_received(:bark).with("loud")
     end
   end
+```
 
 Since spies are verified after the code under test is run, they fit
 very nicely with the Given/When/Then technique of specification. Here
 is the above RSpec example using the rspec-given gem:
 
+```ruby
   require 'rspec/given'
 
   describe Dog do
@@ -759,51 +807,84 @@ is the above RSpec example using the rspec-given gem:
       Then { dog.should have_received(:bark).with("loud") }
     end
   end
+```
 
-*NOTE:* You can only spy on methods that are mocked or stubbed. That's
-not a problem with regular mocks, but normal methods on partial
-objects will not be recorded.
+*NOTE:* <em>You can only spy on methods that are mocked or stubbed.
+That's not a problem with regular mocks, but normal methods on partial
+objects will not be recorded.</em>
 
 You can get around this limitation by stubbing the method in question
-on the normal mock, and then specifying <code>pass_thru</code>.
-Assuming <code>:bark</code> is a normal method on a Dog object, then
-the following allows for spying on <code>:bark</code>.
+on the normal mock, and then specifying `pass_thru`. Assuming `:bark`
+is a normal method on a Dog object, then the following allows for
+spying on `:bark`.
 
+```ruby
    dog = Dog.new
    flexmock(dog).should_receive(:bark).pass_thru
    # ...
    dog.should have_received(:bark)
+```
 
-==== Asserting Spy Methods are Called (Test::Unit / MiniTest)
+#### Asserting Spy Methods are Called (Test::Unit / MiniTest)
 
 FlexMock provied a custom assertion method for use with Test::Unit and
 MiniTest for asserting that mocked methods are actually called.
 
 * <b>assert_spy_called <em>mock</em>, <em>options_hash</em>, <em>method_name</em>, <em>args...</em></b>
 
-  This will assert that the method called <em>method_name</em> has
-  been called at least once on the given mock object. If arguments are
+  This will assert that the method called _method_name_ has been
+  called at least once on the given mock object. If arguments are
   given, then the method must be called with actual argument that
   match the given argument matchers.
 
   All the argument matchers defined in the "Argument Validation"
-  section above are allowed in the <code>assert_spy_called</code>
+  section above are allowed in the `assert_spy_called`
   method.
 
-  The <code>options</code> hash is optional. If omitted, all options
-  will have their default values.
+  The `options` hash is optional. If omitted, all options will have
+  their default values. See below for spy option definitions.
 
 * <b>assert_spy_not_called <em>mock</em>, <em>options_hash</em>, <em>method_name</em>, <em>args...</em></b>
 
-  Same as <code>assert_spy_called</code>, except with the sense of the
+  Same as `assert_spy_called`, except with the sense of the
   test reversed.
 
+*Spy Options*
+
+* <b>times: <em>n</em></b>
+
+  Specify the number of times a matching method should have been
+  invoked. `nil` (or omitted) means any number of times.
+
+* <b>with_block: <em>true/false/nil</em>
+
+  Is a block required on the invocation? `true` means the method must
+  be invoked with a block. `false` means the method must have been
+  invoked without a block. `nil` means that the presence of a block
+  does not matter. Default is `nil`.
+
+* <b>and: [<em>proc1</em>, <em>proc2...</em>]</b>
+
+  Additional validations to be run on each matching method call. The
+  list of arguments for each call is passed to the procs. This allows
+  additional validations on supplied arguments. Default is no
+  additional validations.
+
+* <b>on: <em>n</em>
+
+  Only apply the additional validations on the <em>n</em>'th
+  invocation of the matching method. Default is apply additional
+  validations to all invocations.
+
 *Examples:*
 
+```ruby
     dog = flexmock(:on, Dog)
 
     dog.wag(:tail)
     dog.wag(:head)
+    dog.bark(5)
+    dog.bark(6)
 
     assert_spy_called dog, :wag, :tail
     assert_spy_called dog, :wag, :head
@@ -812,36 +893,61 @@ MiniTest for asserting that mocked methods are actually called.
     assert_spy_not_called dog, :bark
     assert_spy_not_called dog, {times: 3}, :wag
 
-==== RSpec Matcher for Spying
+    is_even = proc { |n| assert_equal 0, n%2 }
+    assert_spy_called dog, { and: is_even, on: 2 }, :bark, Integer
+```
+
+#### RSpec Matcher for Spying
 
 FlexMock also provides an RSpec matcher that can be used to specify
 spy behavior.
 
-* <b>mock.should have_received(<em>method_name</em>).with(<em>args...</em>).times(<em>n</em>)</b>
+* <b>mock.should have_received(<em>method_name</em>).<em>modifier1</em>.<em>modifier2</em>...</b>
 
-  Specifies that the method named <em>method_name</em> should have
+  Specifies that the method named _method_name_ should have
   been received by the mock object with the given arguments.
 
-  The <code>with</code> and <code>times</code> clauses are optional.
+  Just like `should_receive`, `have_received` will accept a number of
+  modifiers that modify its behavior.
 
-  If a <code>with</code> clause is given, only messages with matching
-  arguments are considered. <em>args</em> can be any of the argument
-  matches mentioned in the "Argument Validation" section above. If
-  <code>with</code> is not given, then the arguments are not
-  considered when finding matching calls.
+*Modifiers for `have_received`*
 
-  If a <code>times</code> clause is given, then there must be exactly
-  <code>n</code> calls for that method name on the mock. If the
-  <code>times</code> clause is not given, then there must be at least
-  one call matching the method name (and arguments if they are
-  considered).
+* <b>with(<em>args</em>)
 
-  <code>never</code> is an alias for <code>times(0)</code>,
-  <code>once</code> is an alias for <code>times(1)</code>, and
-  <code>twice</code> is an alias for <code>times(2)</code>.
+  If a `with` modifier is given, only messages with matching arguments
+  are considered. _args_ can be any of the argument matches mentioned
+  in the "Argument Validation" section above. If `with` is not given,
+  then the arguments are not considered when finding matching calls.
+
+* <b>times(<em>n</em>)</b>
+
+  If a `times` modifier is given, then there must be exactly `n` calls
+  for that method name on the mock. If the `times` clause is not
+  given, then there must be at least one call matching the method name
+  (and arguments if they are considered).
+
+  * `never` is an alias for `times(0)`,
+  * `once` is an alias for `times(1)`, and
+  * `twice` is an alias for `times(2)`.
+
+* <b>and { |args| <em>code</em> }</b>
+
+  If an `and` modifier is given, then the supplied block will be run as
+  additional validations on any matching call.  Arguments to the
+  matching call will be supplied to the block. If multiple `and`
+  modifiers are given, all the blocks will be run.  The additional
+  validations are run on all the matching calls unless an `on`
+  modifier is supplied.
+
+* <b>on(<em>n</em>)</b>
+
+  If an `on` modifier is given, then the additional validations
+  supplied by `and` will only be run on the <em>n</em>'th invocation
+  of the matching method.
 
 *Examples:*
 
+```ruby
     dog = flexmock(:on, Dog)
 
     dog.wag(:tail)
@@ -854,22 +960,33 @@ spy behavior.
     dog.should_not have_received(:bark)
     dog.should_not have_received(:wag).times(3)
 
-=== Mocking Class Object
+    dog.bark(3)
+    dog.bark(6)
+    dog.should have_received(:bark).with(Integer).and { |arg|
+      (arg % 3).should == 0
+    }
+    dog.should have_received(:bark).with(Integer).and { |arg|
+      arg.should == 6
+    }.on(2)
+
+```
 
-In the previous example we mocked out the <code>bark</code> method of
-a Dog object to avoid invoking the Woofer object. Perhaps a better
-technique would be to mock the Woofer object directly. But Dog uses
-Woofer explicitly so we cannot just pass in a mock object for Dog to
-use.
+### Mocking Class Object
 
-But wait, we can add mock behavior to any existing object, and classes are
-objects in Ruby. So why don't we just mock out the Woofer class object to
-return mocks for us.
+In the previous example we mocked out the `bark` method of a Dog
+object to avoid invoking the Woofer object. Perhaps a better technique
+would be to mock the Woofer object directly. But Dog uses Woofer
+explicitly so we cannot just pass in a mock object for Dog to use.
 
+But wait, we can add mock behavior to any existing object, and classes
+are objects in Ruby. So why don't we just mock out the Woofer class
+object to return mocks for us.
+
+```ruby
   class TestDogBarking < Test::Unit::TestCase
     include FlexMock::TestCase
 
-    # Setup the tests by mocking the <code>new</code> method of
+    # Setup the tests by mocking the `new` method of
     # Woofer and return a mock woofer.
     def setup
       flexmock(Woofer).should_receive(:new).
@@ -882,13 +999,15 @@ return mocks for us.
                                       # returned by Woofer.new
     end
   end
+```
 
-=== Mocking Behavior in All Instances Created by a Class Object
+### Mocking Behavior in All Instances Created by a Class Object
 
 Sometimes returning a single mock object is not enough. Occasionally you want
-to mock <em>every</em> instance object created by a class. FlexMock makes this
+to mock _every_ instance object created by a class. FlexMock makes this
 very easy.
 
+```ruby
   class TestDogBarking < Test::Unit::TestCase
     include FlexMock::TestCase
 
@@ -903,40 +1022,46 @@ very easy.
       assert_equal :grrrr, Dog.new.bark  # are mocked.
     end
   end
+```
 
-Note that FlexMock adds the mock expectations after the original
-<code>new</code> method has completed. If the original version of
-<code>new</code> yields the newly created instance to a block, that
-block will get an non-mocked version of the object.
+Note that FlexMock adds the mock expectations after the original `new`
+method has completed. If the original version of `new` yields the
+newly created instance to a block, that block will get an non-mocked
+version of the object.
 
-Note that <code>new_instances</code> will accept a block if you wish
-to mock several methods at the same time. E.g.
+Note that `new_instances` will accept a block if you wish to mock
+several methods at the same time. E.g.
 
+```ruby
       flexmock(Woofer).new_instances do |m|
         m.should_receive(:woof).twice.and_return(:grrr)
         m.should_receive(:wag).at_least.once.and_return(:happy)
       end
+```
 
-=== Default Expectations on Mocks
+### Default Expectations on Mocks
 
 Sometimes you want to setup a bunch of default expectations that are
 pretty much for a number of different tests.  Then in the individual
 tests, you would like to override the default behavior on just that
 one method you are testing at the moment.  You can do that by using
-the <code>by_default</code> modifier.
+the `by_default` modifier.
 
 In your test setup you might have:
 
+```ruby
   def setup
     @mock_dog = flexmock("Fido")
     @mock_dog.should_receive(:tail => :a_tail, :bark => "woof").by_default
   end
+```
 
-The behaviors for :tail and :bark are good for most of the tests, but
-perhaps you wish to verify that :bark is called exactly once in a
-given test.  Since :bark by default has no count expectations, you can
-override the default in the given test.
+The behaviors for `:tail` and `:bark` are good for most of the tests,
+but perhaps you wish to verify that `:bark` is called exactly once in
+a given test. Since :bark by default has no count expectations, you
+can override the default in the given test.
 
+```ruby
   def test_something_where_bark_must_be_called_once
     @mock_dog.should_receive(:bark => "woof").once
 
@@ -946,12 +1071,13 @@ override the default in the given test.
     # However, the default for :tail (which returns :a_tail)
     # is still active.
   end
+```
 
 By setting defaults, your individual tests don't have to concern
 themselves with details of all the default setup.  But the details of
 the overrides are right there in the body of the test.
 
-=== Mocking Law of Demeter Violations
+### Mocking Law of Demeter Violations
 
 The Law of Demeter says that you should only invoke methods on objects
 to which you have a direct connection, e.g. parameters, instance
@@ -959,12 +1085,15 @@ variables, and local variables.  You can usually detect Law of Demeter
 violations by the excessive number of periods in an expression.  For
 example:
 
+```ruby
      car.chassis.axle.universal_joint.cog.turn
+```
 
 The Law of Demeter has a very big impact on mocking.  If you need to
 mock the "turn" method on "cog", you first have to mock chassis, axle,
 and universal_joint.
 
+```ruby
     # Manually mocking a Law of Demeter violation
     cog = flexmock("cog")
     cog.should_receive(:turn).once.and_return(:ok)
@@ -972,6 +1101,7 @@ and universal_joint.
     axle = flexmock("axle", :universal_joint => joint)
     chassis = flexmock("chassis", :axle => axle)
     car = flexmock("car", :chassis => chassis)
+```
 
 Yuck!
 
@@ -983,66 +1113,65 @@ allow you to easily mock Demeter method chains.
 
 Here's an example of Demeter chain mocking:
 
+```ruby
     # Demeter chain mocking using the short form.
     car = flexmock("car")
     car.should_receive( "chassis.axle.universal_joint.cog.turn" => :ok).once
+```
 
 You can also use the long form:
 
+```ruby
     # Demeter chain mocking using the long form.
     car = flexmock("car")
     car.should_receive("chassis.axle.universal_joint.cog.turn").once.
       and_return(:ok)
+```
 
-That's it.  Anywhere FlexMock accepts a method name for mocking, you
+That's it. Anywhere FlexMock accepts a method name for mocking, you
 can use a demeter chain and FlexMock will attempt to do the right
 thing.
 
 But beware, there are a few limitations.
 
 The all the methods in the chain, except for the last one, will mocked
-to return a mock object.  That mock object, in turn, will be mocked so
+to return a mock object. That mock object, in turn, will be mocked so
 as to respond to the next method in the chain, returning the following
-mock.  And so on. If you try to manually mock out any of the chained
+mock. And so on. If you try to manually mock out any of the chained
 methods, you could easily interfer with the mocking specified by the
-Demeter chain.  FlexMock will attempt to catch problems when it can,
+Demeter chain. FlexMock will attempt to catch problems when it can,
 but there are certainly scenarios where it cannot detect the problem
 beforehand.
 
-== Examples
+## Examples
 
 Refer to the following documents for examples of using FlexMock:
 
-* {RSpec Examples}[link:doc/examples/rspec_examples_spec_rdoc.html]
-* {Test::Unit / MiniTest Examples}[link:doc/examples/test_unit_examples_test_rdoc.html]
-
-*NOTE:* <em>If the above links are not working, you probably need to
-read the documents from the {documentation
-site}[http://flexmock.rubyforge.org]</em>
+* [RSpec Examples](https://github.com/jimweirich/flexmock/blob/master/doc/examples/rspec_examples_spec.rb)
+* [Test::Unit / MiniTest Examples](https://github.com/jimweirich/flexmock/blob/master/doc/examples/test_unit_examples_test.rb)
 
-== License
+## License
 
-Copyright 2003-2012 by Jim Weirich (jim.weirich@gmail.com).
+Copyright 2003-2013 by Jim Weirich (jim.weirich@gmail.com).
 All rights reserved.
 
 Permission is granted for use, copying, modification, distribution,
 and distribution of modified versions of this work as long as the
 above copyright notice is included.
 
-= Other stuff
+# Other stuff
 
-Author::   Jim Weirich <jim.weirich@gmail.com>
-Requires:: Ruby 1.9.2 or later (also works with Ruby 1.8.7)
+* **Author** -- Jim Weirich <jim.weirich@gmail.com>
+* **Requires** -- Ruby 1.9.2 or later (also works with Ruby 1.8.7)
 
-== See Also
+## See Also
 
 If you like the spy capability of FlexMock, you should check out the
-rspec-given gem (http://rubygems.org/gems/rspec-given) that allows you
+[rspec-given gem](http://rubygems.org/gems/rspec-given) that allows you
 to use Given/When/Then statements in you specifications.
 
-== Warranty
+## Warranty
 
-This software is provided "as is" and without any express or
-implied warranties, including, without limitation, the implied
-warranties of merchantibility and fitness for a particular
-purpose.
+This software is provided "as is" and without any express or implied
+warranties, including, without limitation, the implied warranties of
+merchantibility and fitness for a particular purpose.