diff options
Diffstat (limited to 'include/gmock/gmock-generated-matchers.h.pump')
| -rw-r--r-- | include/gmock/gmock-generated-matchers.h.pump | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/include/gmock/gmock-generated-matchers.h.pump b/include/gmock/gmock-generated-matchers.h.pump index b45028a..2a457aa 100644 --- a/include/gmock/gmock-generated-matchers.h.pump +++ b/include/gmock/gmock-generated-matchers.h.pump @@ -47,6 +47,14 @@ $var n = 10 $$ The maximum arity we support. namespace testing { namespace internal { +// Generates a non-fatal failure iff 'description' is not a valid +// matcher description. +inline void ValidateMatcherDescription(const char* description) { + EXPECT_STREQ("", description) + << "The description string in a MATCHER*() macro must be \"\" " + "at this moment. We will implement custom description string soon."; +} + // Implements ElementsAre() and ElementsAreArray(). template <typename Container> class ElementsAreMatcherImpl : public MatcherInterface<Container> { @@ -300,4 +308,206 @@ ElementsAreArray(const T (&array)[N]) { } // namespace testing +// The MATCHER* family of macros can be used in a namespace scope to +// define custom matchers easily. The syntax: +// +// MATCHER(name, description_string) { statements; } +// +// will define a matcher with the given name that executes the +// statements, which must return a bool to indicate if the match +// succeeds. For now, the description_string must be "", but we'll +// allow other values soon. Inside the statements, you can refer to +// the value being matched by 'arg', and refer to its type by +// 'arg_type'. For example: +// +// MATCHER(IsEven, "") { return (arg % 2) == 0; } +// +// allows you to write +// +// // Expects mock_foo.Bar(n) to be called where n is even. +// EXPECT_CALL(mock_foo, Bar(IsEven())); +// +// or, +// +// // Verifies that the value of some_expression is even. +// EXPECT_THAT(some_expression, IsEven()); +// +// If the above assertion fails, it will print something like: +// +// Value of: some_expression +// Expected: is even +// Actual: 7 +// +// where the description "is even" is automatically calculated from the +// matcher name IsEven. +// +// Note that the type of the value being matched (arg_type) is +// determined by the context in which you use the matcher and is +// supplied to you by the compiler, so you don't need to worry about +// declaring it (nor can you). This allows the matcher to be +// polymorphic. For example, IsEven() can be used to match any type +// where the value of "(arg % 2) == 0" can be implicitly converted to +// a bool. In the "Bar(IsEven())" example above, if method Bar() +// takes an int, 'arg_type' will be int; if it takes an unsigned long, +// 'arg_type' will be unsigned long; and so on. +// +// Sometimes you'll want to parameterize the matcher. For that you +// can use another macro: +// +// MATCHER_P(name, param_name, description_string) { statements; } +// +// For example: +// +// MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; } +// +// will allow you to write: +// +// EXPECT_THAT(Blah("a"), HasAbsoluteValue(n)); +// +// which may lead to this message (assuming n is 10): +// +// Value of: Blah("a") +// Expected: has absolute value 10 +// Actual: -9 +// +// Note that both the matcher description and its parameter are +// printed, making the message human-friendly. +// +// In the matcher definition body, you can write 'foo_type' to +// reference the type of a parameter named 'foo'. For example, in the +// body of MATCHER_P(HasAbsoluteValue, value) above, you can write +// 'value_type' to refer to the type of 'value'. +// +// We also provide MATCHER_P2, MATCHER_P3, ..., up to MATCHER_P$n to +// support multi-parameter matchers. +// +// For the purpose of typing, you can view +// +// MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... } +// +// as shorthand for +// +// template <typename p1_type, ..., typename pk_type> +// FooMatcherPk<p1_type, ..., pk_type> +// Foo(p1_type p1, ..., pk_type pk) { ... } +// +// When you write Foo(v1, ..., vk), the compiler infers the types of +// the parameters v1, ..., and vk for you. If you are not happy with +// the result of the type inference, you can specify the types by +// explicitly instantiating the template, as in Foo<long, bool>(5, +// false). As said earlier, you don't get to (or need to) specify +// 'arg_type' as that's determined by the context in which the matcher +// is used. You can assign the result of expression Foo(p1, ..., pk) +// to a variable of type FooMatcherPk<p1_type, ..., pk_type>. This +// can be useful when composing matchers. +// +// While you can instantiate a matcher template with reference types, +// passing the parameters by pointer usually makes your code more +// readable. If, however, you still want to pass a parameter by +// reference, be aware that in the failure message generated by the +// matcher you will see the value of the referenced object but not its +// address. +// +// You can overload matchers with different numbers of parameters: +// +// MATCHER_P(Blah, a, description_string1) { ... } +// MATCHER_P2(Blah, a, b, description_string2) { ... } +// +// While it's tempting to always use the MATCHER* macros when defining +// a new matcher, you should also consider implementing +// MatcherInterface or using MakePolymorphicMatcher() instead, +// especially if you need to use the matcher a lot. While these +// approaches require more work, they give you more control on the +// types of the value being matched and the matcher parameters, which +// in general leads to better compiler error messages that pay off in +// the long run. They also allow overloading matchers based on +// parameter types (as opposed to just based on the number of +// parameters). +// +// CAVEAT: +// +// MATCHER*() can only be used in a namespace scope. The reason is +// that C++ doesn't yet allow function-local types to be used to +// instantiate templates. The up-coming C++0x standard will fix this. +// Once that's done, we'll consider supporting using MATCHER*() inside +// a function. +// +// MORE INFORMATION: +// +// To learn more about using these macros, please search for 'MATCHER' +// on http://code.google.com/p/googlemock/wiki/CookBook. + +$range i 0..n +$for i + +[[ +$var macro_name = [[$if i==0 [[MATCHER]] $elif i==1 [[MATCHER_P]] + $else [[MATCHER_P$i]]]] +$var class_name = [[name##Matcher[[$if i==0 [[]] $elif i==1 [[P]] + $else [[P$i]]]]]] +$range j 0..i-1 +$var template = [[$if i==0 [[]] $else [[ + + template <$for j, [[typename p$j##_type]]>\ +]]]] +$var ctor_param_list = [[$for j, [[p$j##_type gmock_p$j]]]] +$var inits = [[$if i==0 [[]] $else [[ : $for j, [[p$j(gmock_p$j)]]]]]] +$var params = [[$for j, [[p$j]]]] +$var param_types = [[$if i==0 [[]] $else [[<$for j, [[p$j##_type]]>]]]] +$var param_types_and_names = [[$for j, [[p$j##_type p$j]]]] +$var param_field_decls = [[$for j +[[ + + p$j##_type p$j;\ +]]]] +$var param_field_decls2 = [[$for j +[[ + + p$j##_type p$j;\ +]]]] + +#define $macro_name(name$for j [[, p$j]], description)\$template + class $class_name {\ + public:\ + template <typename arg_type>\ + class gmock_Impl : public ::testing::MatcherInterface<arg_type> {\ + public:\ + [[$if i==1 [[explicit ]]]]gmock_Impl($ctor_param_list)$inits {}\ + virtual bool Matches(arg_type arg) const;\ + virtual void DescribeTo(::std::ostream* os) const {\ + *os << ::testing::internal::ConvertIdentifierNameToWords(#name);\ +[[$if i==1 [[ *os << " ";\ + ::testing::internal::UniversalPrint(p0, os);\ + +]] $elif i>=2 [[ *os << " (";\ + ::testing::internal::UniversalPrint(p0, os);\ +$range k 1..i-1 +$for k [[ + + *os << ", ";\ + ::testing::internal::UniversalPrint(p$k, os);\ +]] + + *os << ")";\ + +]]]] + }\$param_field_decls + };\ + template <typename arg_type>\ + operator ::testing::Matcher<arg_type>() const {\ + return ::testing::Matcher<arg_type>(new gmock_Impl<arg_type>($params));\ + }\ + $class_name($ctor_param_list)$inits {\ + ::testing::internal::ValidateMatcherDescription(description);\ + }\$param_field_decls2 + };\$template + inline $class_name$param_types name($param_types_and_names) {\ + return $class_name$param_types($params);\ + }\$template + template <typename arg_type>\ + bool $class_name$param_types::\ + gmock_Impl<arg_type>::Matches(arg_type arg) const +]] + + #endif // GMOCK_INCLUDE_GMOCK_GMOCK_GENERATED_MATCHERS_H_ |