Subversion Repositories s80186

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.