/usr/lib/ruby/vendor_ruby/rspec/matchers/matcher_protocol.rb is in ruby-rspec-expectations 3.4.0c3e0m1s1-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 | module RSpec
module Matchers
# rspec-expectations can work with any matcher object that implements this protocol.
#
# @note This class is not loaded at runtime by rspec-expectations. It exists
# purely to provide documentation for the matcher protocol.
class MatcherProtocol
# @!group Required Methods
# @!method matches?(actual)
# @param actual [Object] The object being matched against.
# @yield For an expression like `expect(x).to matcher do...end`, the `do/end`
# block binds to `to`. It passes that block, if there is one, on to this method.
# @return [Boolean] true if this matcher matches the provided object.
# @!method failure_message
# This will only be called if {#matches?} returns false.
# @return [String] Explanation for the failure.
# @!endgroup
# @!group Optional Methods
# @!method does_not_match?(actual)
# In a negative expectation such as `expect(x).not_to foo`, RSpec will
# call `foo.does_not_match?(x)` if this method is defined. If it's not
# defined it will fall back to using `!foo.matches?(x)`. This allows you
# to provide custom logic for the negative case.
#
# @param actual [Object] The object being matched against.
# @yield For an expression like `expect(x).not_to matcher do...end`, the `do/end`
# block binds to `not_to`. It passes that block, if there is one, on to this method.
# @return [Boolean] true if this matcher does not match the provided object.
# @!method failure_message_when_negated
# This will only be called when a negative match fails.
# @return [String] Explanation for the failure.
# @note This method is listed as optional because matchers do not have to
# support negation. But if your matcher does support negation, this is a
# required method -- otherwise, you'll get a `NoMethodError`.
# @!method description
# The description is used for two things:
#
# * When using RSpec's one-liner syntax
# (e.g. `it { is_expected.to matcher }`), the description
# is used to generate the example's doc string since you
# have not provided one.
# * In a composed matcher expression, the description is used
# as part of the failure message (and description) of the outer
# matcher.
#
# @return [String] Description of the matcher.
# @!method supports_block_expectations?
# Indicates that this matcher can be used in a block expectation expression,
# such as `expect { foo }.to raise_error`. Generally speaking, this is
# only needed for matchers which operate on a side effect of a block, rather
# than on a particular object.
# @return [Boolean] true if this matcher can be used in block expressions.
# @note If not defined, RSpec assumes a value of `false` for this method.
# @!method expects_call_stack_jump?
# Indicates that when this matcher is used in a block expectation
# expression, it expects the block to use a ruby construct that causes
# a call stack jump (such as raising an error or throwing a symbol).
#
# This is used internally for compound block expressions, as matchers
# which expect call stack jumps must be treated with care to work properly.
#
# @return [Boolean] true if the matcher expects a call stack jump
#
# @note This method is very rarely used or needed.
# @note If not defined, RSpec assumes a value of `false` for this method.
# @!method diffable?
# @return [Boolean] true if `actual` and `expected` can be diffed.
# Indicates that this matcher provides `actual` and `expected` attributes,
# and that the values returned by these can be usefully diffed, which can
# be included in the output.
# @!method actual
# @return [String, Object] If an object (rather than a string) is provided,
# RSpec will use the `pp` library to convert it to multi-line output in
# order to diff.
# The actual value for the purposes of a diff.
# @note This method is required if `diffable?` returns true.
# @!method expected
# @return [String, Object] If an object (rather than a string) is provided,
# RSpec will use the `pp` library to convert it to multi-line output in
# order to diff.
# The expected value for the purposes of a diff.
# @note This method is required if `diffable?` returns true.
# @!endgroup
end
end
end
|