1This page discusses the design of new Google Mock features. 2 3 4 5# Macros for Defining Actions # 6 7## Problem ## 8 9Due to the lack of closures in C++, it currently requires some 10non-trivial effort to define a custom action in Google Mock. For 11example, suppose you want to "increment the value pointed to by the 12second argument of the mock function and return it", you could write: 13 14``` 15int IncrementArg1(Unused, int* p, Unused) { 16 return ++(*p); 17} 18 19... WillOnce(Invoke(IncrementArg1)); 20``` 21 22There are several things unsatisfactory about this approach: 23 24 * Even though the action only cares about the second argument of the mock function, its definition needs to list other arguments as dummies. This is tedious. 25 * The defined action is usable only in mock functions that takes exactly 3 arguments - an unnecessary restriction. 26 * To use the action, one has to say `Invoke(IncrementArg1)`, which isn't as nice as `IncrementArg1()`. 27 28The latter two problems can be overcome using `MakePolymorphicAction()`, 29but it requires much more boilerplate code: 30 31``` 32class IncrementArg1Action { 33 public: 34 template <typename Result, typename ArgumentTuple> 35 Result Perform(const ArgumentTuple& args) const { 36 return ++(*tr1::get<1>(args)); 37 } 38}; 39 40PolymorphicAction<IncrementArg1Action> IncrementArg1() { 41 return MakePolymorphicAction(IncrementArg1Action()); 42} 43 44... WillOnce(IncrementArg1()); 45``` 46 47Our goal is to allow defining custom actions with the least amount of 48boiler-plate C++ requires. 49 50## Solution ## 51 52We propose to introduce a new macro: 53``` 54ACTION(name) { statements; } 55``` 56 57Using this in a namespace scope will define an action with the given 58name that executes the statements. Inside the statements, you can 59refer to the K-th (0-based) argument of the mock function as `argK`. 60For example: 61``` 62ACTION(IncrementArg1) { return ++(*arg1); } 63``` 64allows you to write 65``` 66... WillOnce(IncrementArg1()); 67``` 68 69Note that you don't need to specify the types of the mock function 70arguments, as brevity is a top design goal here. Rest assured that 71your code is still type-safe though: you'll get a compiler error if 72`*arg1` doesn't support the `++` operator, or if the type of 73`++(*arg1)` isn't compatible with the mock function's return type. 74 75Another example: 76``` 77ACTION(Foo) { 78 (*arg2)(5); 79 Blah(); 80 *arg1 = 0; 81 return arg0; 82} 83``` 84defines an action `Foo()` that invokes argument #2 (a function pointer) 85with 5, calls function `Blah()`, sets the value pointed to by argument 86#1 to 0, and returns argument #0. 87 88For more convenience and flexibility, you can also use the following 89pre-defined symbols in the body of `ACTION`: 90 91| `argK_type` | The type of the K-th (0-based) argument of the mock function | 92|:------------|:-------------------------------------------------------------| 93| `args` | All arguments of the mock function as a tuple | 94| `args_type` | The type of all arguments of the mock function as a tuple | 95| `return_type` | The return type of the mock function | 96| `function_type` | The type of the mock function | 97 98For example, when using an `ACTION` as a stub action for mock function: 99``` 100int DoSomething(bool flag, int* ptr); 101``` 102we have: 103| **Pre-defined Symbol** | **Is Bound To** | 104|:-----------------------|:----------------| 105| `arg0` | the value of `flag` | 106| `arg0_type` | the type `bool` | 107| `arg1` | the value of `ptr` | 108| `arg1_type` | the type `int*` | 109| `args` | the tuple `(flag, ptr)` | 110| `args_type` | the type `std::tr1::tuple<bool, int*>` | 111| `return_type` | the type `int` | 112| `function_type` | the type `int(bool, int*)` | 113 114## Parameterized actions ## 115 116Sometimes you'll want to parameterize the action. For that we propose 117another macro 118``` 119ACTION_P(name, param) { statements; } 120``` 121 122For example, 123``` 124ACTION_P(Add, n) { return arg0 + n; } 125``` 126will allow you to write 127``` 128// Returns argument #0 + 5. 129... WillOnce(Add(5)); 130``` 131 132For convenience, we use the term _arguments_ for the values used to 133invoke the mock function, and the term _parameters_ for the values 134used to instantiate an action. 135 136Note that you don't need to provide the type of the parameter either. 137Suppose the parameter is named `param`, you can also use the 138Google-Mock-defined symbol `param_type` to refer to the type of the 139parameter as inferred by the compiler. 140 141We will also provide `ACTION_P2`, `ACTION_P3`, and etc to support 142multi-parameter actions. For example, 143``` 144ACTION_P2(ReturnDistanceTo, x, y) { 145 double dx = arg0 - x; 146 double dy = arg1 - y; 147 return sqrt(dx*dx + dy*dy); 148} 149``` 150lets you write 151``` 152... WillOnce(ReturnDistanceTo(5.0, 26.5)); 153``` 154 155You can view `ACTION` as a degenerated parameterized action where the 156number of parameters is 0. 157 158## Advanced Usages ## 159 160### Overloading Actions ### 161 162You can easily define actions overloaded on the number of parameters: 163``` 164ACTION_P(Plus, a) { ... } 165ACTION_P2(Plus, a, b) { ... } 166``` 167 168### Restricting the Type of an Argument or Parameter ### 169 170For maximum brevity and reusability, the `ACTION*` macros don't let 171you specify the types of the mock function arguments and the action 172parameters. Instead, we let the compiler infer the types for us. 173 174Sometimes, however, we may want to be more explicit about the types. 175There are several tricks to do that. For example: 176``` 177ACTION(Foo) { 178 // Makes sure arg0 can be converted to int. 179 int n = arg0; 180 ... use n instead of arg0 here ... 181} 182 183ACTION_P(Bar, param) { 184 // Makes sure the type of arg1 is const char*. 185 ::testing::StaticAssertTypeEq<const char*, arg1_type>(); 186 187 // Makes sure param can be converted to bool. 188 bool flag = param; 189} 190``` 191where `StaticAssertTypeEq` is a compile-time assertion we plan to add to 192Google Test (the name is chosen to match `static_assert` in C++0x). 193 194### Using the ACTION Object's Type ### 195 196If you are writing a function that returns an `ACTION` object, you'll 197need to know its type. The type depends on the macro used to define 198the action and the parameter types. The rule is relatively simple: 199| **Given Definition** | **Expression** | **Has Type** | 200|:---------------------|:---------------|:-------------| 201| `ACTION(Foo)` | `Foo()` | `FooAction` | 202| `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP<int>` | 203| `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value, int_value)` | `BazActionP2<bool, int>` | 204| ... | ... | ... | 205 206Note that we have to pick different suffixes (`Action`, `ActionP`, 207`ActionP2`, and etc) for actions with different numbers of parameters, 208or the action definitions cannot be overloaded on the number of 209parameters. 210 211## When to Use ## 212 213While the new macros are very convenient, please also consider other 214means of implementing actions (e.g. via `ActionInterface` or 215`MakePolymorphicAction()`), especially if you need to use the defined 216action a lot. While the other approaches require more work, they give 217you more control on the types of the mock function arguments and the 218action parameters, which in general leads to better compiler error 219messages that pay off in the long run. They also allow overloading 220actions based on parameter types, as opposed to just the number of 221parameters. 222 223## Related Work ## 224 225As you may have realized, the `ACTION*` macros resemble closures (also 226known as lambda expressions or anonymous functions). Indeed, both of 227them seek to lower the syntactic overhead for defining a function. 228 229C++0x will support lambdas, but they are not part of C++ right now. 230Some non-standard libraries (most notably BLL or Boost Lambda Library) 231try to alleviate this problem. However, they are not a good choice 232for defining actions as: 233 234 * They are non-standard and not widely installed. Google Mock only depends on standard libraries and `tr1::tuple`, which is part of the new C++ standard and comes with gcc 4+. We want to keep it that way. 235 * They are not trivial to learn. 236 * They will become obsolete when C++0x's lambda feature is widely supported. We don't want to make our users use a dying library. 237 * Since they are based on operators, they are rather ad hoc: you cannot use statements, and you cannot pass the lambda arguments to a function, for example. 238 * They have subtle semantics that easily confuses new users. For example, in expression `_1++ + foo++`, `foo` will be incremented only once where the expression is evaluated, while `_1` will be incremented every time the unnamed function is invoked. This is far from intuitive. 239 240`ACTION*` avoid all these problems. 241 242## Future Improvements ## 243 244There may be a need for composing `ACTION*` definitions (i.e. invoking 245another `ACTION` inside the definition of one `ACTION*`). We are not 246sure we want it yet, as one can get a similar effect by putting 247`ACTION` definitions in function templates and composing the function 248templates. We'll revisit this based on user feedback. 249 250The reason we don't allow `ACTION*()` inside a function body is that 251the current C++ standard doesn't allow function-local types to be used 252to instantiate templates. The upcoming C++0x standard will lift this 253restriction. Once this feature is widely supported by compilers, we 254can revisit the implementation and add support for using `ACTION*()` 255inside a function. 256 257C++0x will also support lambda expressions. When they become 258available, we may want to support using lambdas as actions. 259 260# Macros for Defining Matchers # 261 262Once the macros for defining actions are implemented, we plan to do 263the same for matchers: 264 265``` 266MATCHER(name) { statements; } 267``` 268 269where you can refer to the value being matched as `arg`. For example, 270given: 271 272``` 273MATCHER(IsPositive) { return arg > 0; } 274``` 275 276you can use `IsPositive()` as a matcher that matches a value iff it is 277greater than 0. 278 279We will also add `MATCHER_P`, `MATCHER_P2`, and etc for parameterized 280matchers.