iw5-mod/deps/rapidjson/thirdparty/gtest/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.