2 $$ This is a Pump source file. Please use Pump to convert
3 $$ it to gmock-generated-matchers.h.
5 $var n = 10 $$ The maximum arity we support.
6 $$ }} This line fixes auto-indentation of the following code in Emacs.
7 // Copyright 2008, Google Inc.
8 // All rights reserved.
10 // Redistribution and use in source and binary forms, with or without
11 // modification, are permitted provided that the following conditions are
14 // * Redistributions of source code must retain the above copyright
15 // notice, this list of conditions and the following disclaimer.
16 // * Redistributions in binary form must reproduce the above
17 // copyright notice, this list of conditions and the following disclaimer
18 // in the documentation and/or other materials provided with the
20 // * Neither the name of Google Inc. nor the names of its
21 // contributors may be used to endorse or promote products derived from
22 // this software without specific prior written permission.
24 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
25 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
26 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
27 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
28 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
29 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
30 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
31 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
32 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
33 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
34 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 // Google Mock - a framework for writing C++ mock classes.
38 // This file implements some commonly used variadic matchers.
40 // GOOGLETEST_CM0002 DO NOT DELETE
42 #ifndef GMOCK_INCLUDE_GMOCK_GMOCK_GENERATED_MATCHERS_H_
43 #define GMOCK_INCLUDE_GMOCK_GMOCK_GENERATED_MATCHERS_H_
50 #include "gmock/gmock-matchers.h"
52 // The MATCHER* family of macros can be used in a namespace scope to
53 // define custom matchers easily.
60 // MATCHER(name, description_string) { statements; }
62 // defines a matcher with the given name that executes the statements,
63 // which must return a bool to indicate if the match succeeds. Inside
64 // the statements, you can refer to the value being matched by 'arg',
65 // and refer to its type by 'arg_type'.
67 // The description string documents what the matcher does, and is used
68 // to generate the failure message when the match fails. Since a
69 // MATCHER() is usually defined in a header file shared by multiple
70 // C++ source files, we require the description to be a C-string
71 // literal to avoid possible side effects. It can be empty, in which
72 // case we'll use the sequence of words in the matcher name as the
77 // MATCHER(IsEven, "") { return (arg % 2) == 0; }
79 // allows you to write
81 // // Expects mock_foo.Bar(n) to be called where n is even.
82 // EXPECT_CALL(mock_foo, Bar(IsEven()));
86 // // Verifies that the value of some_expression is even.
87 // EXPECT_THAT(some_expression, IsEven());
89 // If the above assertion fails, it will print something like:
91 // Value of: some_expression
95 // where the description "is even" is automatically calculated from the
96 // matcher name IsEven.
101 // Note that the type of the value being matched (arg_type) is
102 // determined by the context in which you use the matcher and is
103 // supplied to you by the compiler, so you don't need to worry about
104 // declaring it (nor can you). This allows the matcher to be
105 // polymorphic. For example, IsEven() can be used to match any type
106 // where the value of "(arg % 2) == 0" can be implicitly converted to
107 // a bool. In the "Bar(IsEven())" example above, if method Bar()
108 // takes an int, 'arg_type' will be int; if it takes an unsigned long,
109 // 'arg_type' will be unsigned long; and so on.
111 // Parameterizing Matchers
112 // =======================
114 // Sometimes you'll want to parameterize the matcher. For that you
115 // can use another macro:
117 // MATCHER_P(name, param_name, description_string) { statements; }
121 // MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; }
123 // will allow you to write:
125 // EXPECT_THAT(Blah("a"), HasAbsoluteValue(n));
127 // which may lead to this message (assuming n is 10):
129 // Value of: Blah("a")
130 // Expected: has absolute value 10
133 // Note that both the matcher description and its parameter are
134 // printed, making the message human-friendly.
136 // In the matcher definition body, you can write 'foo_type' to
137 // reference the type of a parameter named 'foo'. For example, in the
138 // body of MATCHER_P(HasAbsoluteValue, value) above, you can write
139 // 'value_type' to refer to the type of 'value'.
141 // We also provide MATCHER_P2, MATCHER_P3, ..., up to MATCHER_P$n to
142 // support multi-parameter matchers.
144 // Describing Parameterized Matchers
145 // =================================
147 // The last argument to MATCHER*() is a string-typed expression. The
148 // expression can reference all of the matcher's parameters and a
149 // special bool-typed variable named 'negation'. When 'negation' is
150 // false, the expression should evaluate to the matcher's description;
151 // otherwise it should evaluate to the description of the negation of
152 // the matcher. For example,
154 // using testing::PrintToString;
156 // MATCHER_P2(InClosedRange, low, hi,
157 // std::string(negation ? "is not" : "is") + " in range [" +
158 // PrintToString(low) + ", " + PrintToString(hi) + "]") {
159 // return low <= arg && arg <= hi;
162 // EXPECT_THAT(3, InClosedRange(4, 6));
163 // EXPECT_THAT(3, Not(InClosedRange(2, 4)));
165 // would generate two failures that contain the text:
167 // Expected: is in range [4, 6]
169 // Expected: is not in range [2, 4]
171 // If you specify "" as the description, the failure message will
172 // contain the sequence of words in the matcher name followed by the
173 // parameter values printed as a tuple. For example,
175 // MATCHER_P2(InClosedRange, low, hi, "") { ... }
177 // EXPECT_THAT(3, InClosedRange(4, 6));
178 // EXPECT_THAT(3, Not(InClosedRange(2, 4)));
180 // would generate two failures that contain the text:
182 // Expected: in closed range (4, 6)
184 // Expected: not (in closed range (2, 4))
186 // Types of Matcher Parameters
187 // ===========================
189 // For the purpose of typing, you can view
191 // MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... }
195 // template <typename p1_type, ..., typename pk_type>
196 // FooMatcherPk<p1_type, ..., pk_type>
197 // Foo(p1_type p1, ..., pk_type pk) { ... }
199 // When you write Foo(v1, ..., vk), the compiler infers the types of
200 // the parameters v1, ..., and vk for you. If you are not happy with
201 // the result of the type inference, you can specify the types by
202 // explicitly instantiating the template, as in Foo<long, bool>(5,
203 // false). As said earlier, you don't get to (or need to) specify
204 // 'arg_type' as that's determined by the context in which the matcher
205 // is used. You can assign the result of expression Foo(p1, ..., pk)
206 // to a variable of type FooMatcherPk<p1_type, ..., pk_type>. This
207 // can be useful when composing matchers.
209 // While you can instantiate a matcher template with reference types,
210 // passing the parameters by pointer usually makes your code more
211 // readable. If, however, you still want to pass a parameter by
212 // reference, be aware that in the failure message generated by the
213 // matcher you will see the value of the referenced object but not its
216 // Explaining Match Results
217 // ========================
219 // Sometimes the matcher description alone isn't enough to explain why
220 // the match has failed or succeeded. For example, when expecting a
221 // long string, it can be very helpful to also print the diff between
222 // the expected string and the actual one. To achieve that, you can
223 // optionally stream additional information to a special variable
224 // named result_listener, whose type is a pointer to class
225 // MatchResultListener:
227 // MATCHER_P(EqualsLongString, str, "") {
228 // if (arg == str) return true;
230 // *result_listener << "the difference: "
231 /// << DiffStrings(str, arg);
235 // Overloading Matchers
236 // ====================
238 // You can overload matchers with different numbers of parameters:
240 // MATCHER_P(Blah, a, description_string1) { ... }
241 // MATCHER_P2(Blah, a, b, description_string2) { ... }
246 // When defining a new matcher, you should also consider implementing
247 // MatcherInterface or using MakePolymorphicMatcher(). These
248 // approaches require more work than the MATCHER* macros, but also
249 // give you more control on the types of the value being matched and
250 // the matcher parameters, which may leads to better compiler error
251 // messages when the matcher is used wrong. They also allow
252 // overloading matchers based on parameter types (as opposed to just
253 // based on the number of parameters).
255 // MATCHER*() can only be used in a namespace scope as templates cannot be
256 // declared inside of a local class.
261 // To learn more about using these macros, please search for 'MATCHER'
263 // https://github.com/google/googletest/blob/master/googlemock/docs/cook_book.md
269 $var macro_name = [[$if i==0 [[MATCHER]] $elif i==1 [[MATCHER_P]]
270 $else [[MATCHER_P$i]]]]
271 $var class_name = [[name##Matcher[[$if i==0 [[]] $elif i==1 [[P]]
274 $var template = [[$if i==0 [[]] $else [[
276 template <$for j, [[typename p$j##_type]]>\
278 $var ctor_param_list = [[$for j, [[p$j##_type gmock_p$j]]]]
279 $var impl_ctor_param_list = [[$for j, [[p$j##_type gmock_p$j]]]]
280 $var impl_inits = [[$if i==0 [[]] $else [[ : $for j, [[p$j(::std::move(gmock_p$j))]]]]]]
281 $var inits = [[$if i==0 [[]] $else [[ : $for j, [[p$j(::std::move(gmock_p$j))]]]]]]
282 $var params = [[$for j, [[p$j]]]]
283 $var param_types = [[$if i==0 [[]] $else [[<$for j, [[p$j##_type]]>]]]]
284 $var param_types_and_names = [[$for j, [[p$j##_type p$j]]]]
285 $var param_field_decls = [[$for j
288 p$j##_type const p$j;\
290 $var param_field_decls2 = [[$for j
293 p$j##_type const p$j;\
296 #define $macro_name(name$for j [[, p$j]], description)\$template
299 template <typename arg_type>\
300 class gmock_Impl : public ::testing::MatcherInterface<\
301 GTEST_REFERENCE_TO_CONST_(arg_type)> {\
303 [[$if i==1 [[explicit ]]]]gmock_Impl($impl_ctor_param_list)\
305 virtual bool MatchAndExplain(\
306 GTEST_REFERENCE_TO_CONST_(arg_type) arg,\
307 ::testing::MatchResultListener* result_listener) const;\
308 virtual void DescribeTo(::std::ostream* gmock_os) const {\
309 *gmock_os << FormatDescription(false);\
311 virtual void DescribeNegationTo(::std::ostream* gmock_os) const {\
312 *gmock_os << FormatDescription(true);\
315 ::std::string FormatDescription(bool negation) const {\
316 ::std::string gmock_description = (description);\
317 if (!gmock_description.empty()) {\
318 return gmock_description;\
320 return ::testing::internal::FormatMatcherDescription(\
322 ::testing::internal::UniversalTersePrintTupleFieldsToStrings(\
323 ::std::tuple<$for j, [[p$j##_type]]>($for j, [[p$j]])));\
326 template <typename arg_type>\
327 operator ::testing::Matcher<arg_type>() const {\
328 return ::testing::Matcher<arg_type>(\
329 new gmock_Impl<arg_type>($params));\
331 [[$if i==1 [[explicit ]]]]$class_name($ctor_param_list)$inits {\
332 }\$param_field_decls2
335 inline $class_name$param_types name($param_types_and_names) {\
336 return $class_name$param_types($params);\
338 template <typename arg_type>\
339 bool $class_name$param_types::gmock_Impl<arg_type>::MatchAndExplain(\
340 GTEST_REFERENCE_TO_CONST_(arg_type) arg,\
341 ::testing::MatchResultListener* result_listener GTEST_ATTRIBUTE_UNUSED_)\
346 #endif // GMOCK_INCLUDE_GMOCK_GMOCK_GENERATED_MATCHERS_H_