Convenience method for `generates()->returns()`

[jmalloc]

I'm not sure if we already discussed this or not - but a really common pattern under Recoil / PHP 7 is to use generates()->returns() where you simply want a stubbed coroutine to return a specific value.

Perhaps we could add a second parameter to generates(), which is the return value for PHP 7 generators:

generates($values = array(), $returnValue = null)

So usage is imply:

$stub->generates([], new Thing());

Thoughts?

[ezzatron]

At the moment, generates() with multiple values is equivalent to calling it multiple times. This is very useful for the current incarnation of Recoil, where this is a real thing:

$stub->generates([Recoil::return_('a')], [Recoil::return_('b')]);

And is also parallel to other similar methods, e.g. returns('a', 'b') and throws($exceptionA, $exceptionB). We could implement a special method like generatesReturn() or something, but it's not immediately appealing.

[jmalloc]

Ah, yes of course, and generatesReturn() is not much more concise than the current behaviour, so fair enough. I'd say it's not worth polluting the stub interface for this, but two things that are worth noting:

• The examples you gave are exactly what I'm doing with the PHP 7 version, so they would be replaced with something like $stub->generates()->returns('a', 'b') ... I think?
• This is now the most common case for generator mocking when it comes to coroutines - which makes sense, it's directly equivalent of the regular returns().

Maybe we can revisit it once you're using Recoil+PHP 7, it's certainly not a big deal. I'll close for now.

[ezzatron]

Reopening for discussion. As discussed externally, this kind of interface currrently seems like the best solution:

$stub->generates(
    ['yieldA', 'yieldB'], 'returnA', // first generator
    ['yieldC', 'yieldD'], 'returnB'  // second generator
);

However, this doesn't account for a similar idea with throwing exceptions as the generators "response" / end event.

I can think of a few options:

1. Don't provide a solution for throwing.
2. Throw if the "return" value is an exception, and require the user to use more advanced syntax in the edge-case of actually returning an exception.
3. Have "magic" keys in the yielded values that allow for throwing / returning, i.e. $stub->generates(['_return'=> $value]) or $stub->generates(['_throw'=> $exception]).

[ezzatron]

@jmalloc thoughts?

[jmalloc]

I was initially leaning towards (1), but I could be swayed to (2) by a stiff breeze.

The usual caveats apply to squishy input, but because this is only a convenience function and you can always use the extended form if you don't know what kind of value you'll be returning for some reason.