keyboard/qmk/lib/googletest/googlemock/docs/DesignDoc.md

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.