+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 <typename Result, typename ArgumentTuple>

+ Result Perform(const ArgumentTuple& args) const {

+ return ++(*tr1::get<1>(args));

+ }

+};

+

+PolymorphicAction<IncrementArg1Action> 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<bool, int*>` |

+| `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<const char*, arg1_type>();

+

+ // 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<int>` |

+| `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value, int_value)` | `BazActionP2<bool, int>` |

+| ... | ... | ... |

+

+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. \ No newline at end of file