diff options
Diffstat (limited to 'googlemock/docs/DesignDoc.md')
| -rw-r--r-- | googlemock/docs/DesignDoc.md | 56 |
1 files changed, 29 insertions, 27 deletions
diff --git a/googlemock/docs/DesignDoc.md b/googlemock/docs/DesignDoc.md index 3f515c3..4cddc9d 100644 --- a/googlemock/docs/DesignDoc.md +++ b/googlemock/docs/DesignDoc.md @@ -11,7 +11,7 @@ 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: -``` +```cpp int IncrementArg1(Unused, int* p, Unused) { return ++(*p); } @@ -28,7 +28,7 @@ There are several things unsatisfactory about this approach: The latter two problems can be overcome using `MakePolymorphicAction()`, but it requires much more boilerplate code: -``` +```cpp class IncrementArg1Action { public: template <typename Result, typename ArgumentTuple> @@ -50,7 +50,7 @@ boiler-plate C++ requires. ## Solution ## We propose to introduce a new macro: -``` +```cpp ACTION(name) { statements; } ``` @@ -58,11 +58,11 @@ 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: -``` +```cpp ACTION(IncrementArg1) { return ++(*arg1); } ``` allows you to write -``` +```cpp ... WillOnce(IncrementArg1()); ``` @@ -73,7 +73,7 @@ your code is still type-safe though: you'll get a compiler error if `++(*arg1)` isn't compatible with the mock function's return type. Another example: -``` +```cpp ACTION(Foo) { (*arg2)(5); Blah(); @@ -88,18 +88,20 @@ with 5, calls function `Blah()`, sets the value pointed to by argument 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 | +| Argument | Description | +|:----------------|:-------------------------------------------------------------| +| `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: -``` +```cpp int DoSomething(bool flag, int* ptr); ``` we have: + | **Pre-defined Symbol** | **Is Bound To** | |:-----------------------|:----------------| | `arg0` | the value of `flag` | @@ -115,16 +117,16 @@ we have: Sometimes you'll want to parameterize the action. For that we propose another macro -``` +```cpp ACTION_P(name, param) { statements; } ``` For example, -``` +```cpp ACTION_P(Add, n) { return arg0 + n; } ``` will allow you to write -``` +```cpp // Returns argument #0 + 5. ... WillOnce(Add(5)); ``` @@ -140,7 +142,7 @@ parameter as inferred by the compiler. We will also provide `ACTION_P2`, `ACTION_P3`, and etc to support multi-parameter actions. For example, -``` +```cpp ACTION_P2(ReturnDistanceTo, x, y) { double dx = arg0 - x; double dy = arg1 - y; @@ -148,7 +150,7 @@ ACTION_P2(ReturnDistanceTo, x, y) { } ``` lets you write -``` +```cpp ... WillOnce(ReturnDistanceTo(5.0, 26.5)); ``` @@ -160,7 +162,7 @@ number of parameters is 0. ### Overloading Actions ### You can easily define actions overloaded on the number of parameters: -``` +```cpp ACTION_P(Plus, a) { ... } ACTION_P2(Plus, a, b) { ... } ``` @@ -173,7 +175,7 @@ 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: -``` +```cpp ACTION(Foo) { // Makes sure arg0 can be converted to int. int n = arg0; @@ -196,12 +198,12 @@ Google Test (the name is chosen to match `static_assert` in C++0x). 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>` | +| **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, @@ -262,14 +264,14 @@ available, we may want to support using lambdas as actions. Once the macros for defining actions are implemented, we plan to do the same for matchers: -``` +```cpp MATCHER(name) { statements; } ``` where you can refer to the value being matched as `arg`. For example, given: -``` +```cpp MATCHER(IsPositive) { return arg > 0; } ``` @@ -277,4 +279,4 @@ 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 +matchers. |