This page discusses the design of new Google Mock features. # Macros for Defining Actions # ## Problem ## Due to the lack of closures in C++, it currently requires some non-trivial effort to define a custom action in Google Mock. For example, suppose you want to "increment the value pointed to by the second argument of the mock function and return it", you could write: ``` int IncrementArg1(Unused, int* p, Unused) { return ++(*p); } ... WillOnce(Invoke(IncrementArg1)); ``` There are several things unsatisfactory about this approach: * 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. * The defined action is usable only in mock functions that takes exactly 3 arguments - an unnecessary restriction. * To use the action, one has to say `Invoke(IncrementArg1)`, which isn't as nice as `IncrementArg1()`. The latter two problems can be overcome using `MakePolymorphicAction()`, but it requires much more boilerplate code: ``` class IncrementArg1Action { public: template Result Perform(const ArgumentTuple& args) const { return ++(*tr1::get<1>(args)); } }; PolymorphicAction IncrementArg1() { return MakePolymorphicAction(IncrementArg1Action()); } ... WillOnce(IncrementArg1()); ``` Our goal is to allow defining custom actions with the least amount of boiler-plate C++ requires. ## Solution ## We propose to introduce a new macro: ``` ACTION(name) { statements; } ``` Using this in a namespace scope will define an action with the given name that executes the statements. Inside the statements, you can refer to the K-th (0-based) argument of the mock function as `argK`. For example: ``` ACTION(IncrementArg1) { return ++(*arg1); } ``` allows you to write ``` ... WillOnce(IncrementArg1()); ``` Note that you don't need to specify the types of the mock function arguments, as brevity is a top design goal here. Rest assured that your code is still type-safe though: you'll get a compiler error if `*arg1` doesn't support the `++` operator, or if the type of `++(*arg1)` isn't compatible with the mock function's return type. Another example: ``` ACTION(Foo) { (*arg2)(5); Blah(); *arg1 = 0; return arg0; } ``` defines an action `Foo()` that invokes argument #2 (a function pointer) with 5, calls function `Blah()`, sets the value pointed to by argument #1 to 0, and returns argument #0. For more convenience and flexibility, you can also use the following pre-defined symbols in the body of `ACTION`: | `argK_type` | The type of the K-th (0-based) argument of the mock function | |:------------|:-------------------------------------------------------------| | `args` | All arguments of the mock function as a tuple | | `args_type` | The type of all arguments of the mock function as a tuple | | `return_type` | The return type of the mock function | | `function_type` | The type of the mock function | For example, when using an `ACTION` as a stub action for mock function: ``` int DoSomething(bool flag, int* ptr); ``` we have: | **Pre-defined Symbol** | **Is Bound To** | |:-----------------------|:----------------| | `arg0` | the value of `flag` | | `arg0_type` | the type `bool` | | `arg1` | the value of `ptr` | | `arg1_type` | the type `int*` | | `args` | the tuple `(flag, ptr)` | | `args_type` | the type `std::tr1::tuple` | | `return_type` | the type `int` | | `function_type` | the type `int(bool, int*)` | ## Parameterized actions ## Sometimes you'll want to parameterize the action. For that we propose another macro ``` ACTION_P(name, param) { statements; } ``` For example, ``` ACTION_P(Add, n) { return arg0 + n; } ``` will allow you to write ``` // Returns argument #0 + 5. ... WillOnce(Add(5)); ``` For convenience, we use the term _arguments_ for the values used to invoke the mock function, and the term _parameters_ for the values used to instantiate an action. Note that you don't need to provide the type of the parameter either. Suppose the parameter is named `param`, you can also use the Google-Mock-defined symbol `param_type` to refer to the type of the parameter as inferred by the compiler. We will also provide `ACTION_P2`, `ACTION_P3`, and etc to support multi-parameter actions. For example, ``` ACTION_P2(ReturnDistanceTo, x, y) { double dx = arg0 - x; double dy = arg1 - y; return sqrt(dx*dx + dy*dy); } ``` lets you write ``` ... WillOnce(ReturnDistanceTo(5.0, 26.5)); ``` You can view `ACTION` as a degenerated parameterized action where the number of parameters is 0. ## Advanced Usages ## ### Overloading Actions ### You can easily define actions overloaded on the number of parameters: ``` ACTION_P(Plus, a) { ... } ACTION_P2(Plus, a, b) { ... } ``` ### Restricting the Type of an Argument or Parameter ### For maximum brevity and reusability, the `ACTION*` macros don't let you specify the types of the mock function arguments and the action parameters. Instead, we let the compiler infer the types for us. Sometimes, however, we may want to be more explicit about the types. There are several tricks to do that. For example: ``` ACTION(Foo) { // Makes sure arg0 can be converted to int. int n = arg0; ... use n instead of arg0 here ... } ACTION_P(Bar, param) { // Makes sure the type of arg1 is const char*. ::testing::StaticAssertTypeEq(); // Makes sure param can be converted to bool. bool flag = param; } ``` where `StaticAssertTypeEq` is a compile-time assertion we plan to add to Google Test (the name is chosen to match `static_assert` in C++0x). ### Using the ACTION Object's Type ### If you are writing a function that returns an `ACTION` object, you'll need to know its type. The type depends on the macro used to define the action and the parameter types. The rule is relatively simple: | **Given Definition** | **Expression** | **Has Type** | |:---------------------|:---------------|:-------------| | `ACTION(Foo)` | `Foo()` | `FooAction` | | `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP` | | `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value, int_value)` | `BazActionP2` | | ... | ... | ... | Note that we have to pick different suffixes (`Action`, `ActionP`, `ActionP2`, and etc) for actions with different numbers of parameters, or the action definitions cannot be overloaded on the number of parameters. ## When to Use ## While the new macros are very convenient, please also consider other means of implementing actions (e.g. via `ActionInterface` or `MakePolymorphicAction()`), especially if you need to use the defined action a lot. While the other approaches require more work, they give you more control on the types of the mock function arguments and the action parameters, which in general leads to better compiler error messages that pay off in the long run. They also allow overloading actions based on parameter types, as opposed to just the number of parameters. ## Related Work ## As you may have realized, the `ACTION*` macros resemble closures (also known as lambda expressions or anonymous functions). Indeed, both of them seek to lower the syntactic overhead for defining a function. C++0x will support lambdas, but they are not part of C++ right now. Some non-standard libraries (most notably BLL or Boost Lambda Library) try to alleviate this problem. However, they are not a good choice for defining actions as: * 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. * They are not trivial to learn. * 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. * 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. * 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. `ACTION*` avoid all these problems. ## Future Improvements ## There may be a need for composing `ACTION*` definitions (i.e. invoking another `ACTION` inside the definition of one `ACTION*`). We are not sure we want it yet, as one can get a similar effect by putting `ACTION` definitions in function templates and composing the function templates. We'll revisit this based on user feedback. The reason we don't allow `ACTION*()` inside a function body is that the current C++ standard doesn't allow function-local types to be used to instantiate templates. The upcoming C++0x standard will lift this restriction. Once this feature is widely supported by compilers, we can revisit the implementation and add support for using `ACTION*()` inside a function. C++0x will also support lambda expressions. When they become available, we may want to support using lambdas as actions. # Macros for Defining Matchers # Once the macros for defining actions are implemented, we plan to do the same for matchers: ``` MATCHER(name) { statements; } ``` where you can refer to the value being matched as `arg`. For example, given: ``` MATCHER(IsPositive) { return arg > 0; } ``` you can use `IsPositive()` as a matcher that matches a value iff it is greater than 0. We will also add `MATCHER_P`, `MATCHER_P2`, and etc for parameterized matchers.