Add public-facing method and class that allows intercepting stream events.

Add public-facing method and class that allows intercepting stream events.

This allows intercepting events at the subscription level instead of creating
a new full stream and adding the events to that.

Also fix a number of typos and bugs detected by analyzer.

Committed: https://code.google.com/p/dart/source/detail?r=17746

[floitsch, 2013-01-28 14:45:09]

LGTM.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart
File sdk/lib/async/stream.dart (right):

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:45: * The default implementation of [isBroadcast] is
assuming this is a
The default implementation of [isBroadcast] returns `false`.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:219: * types of events for each incoming event.
Mention how pauses are handled.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:221: * An example that adds one to each of a stream of
integers:
Example is bad, since it could be implemented with "mappedBy".

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:222: *     intStream.transformEvents(new
StreamEventTransformer.from(
new line before the code.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:227: Stream transformEvents(StreamEventTransformer<T,
dynamic> transformer) {
As discussed. We should consider making this the default ".transform", and
rename the current transform to "chain".
But for backwards-compatibility we need to start this way anyways.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:287: future._setValue(true);
please add tests.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:937: * the events unmodified. This will not work for
data events if the types
... unmodified. In that case the generic type T needs to be assignable to S.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:952: factory StreamEventTransformer.from({
remove the ".from".

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:956: }) => new _StreamEventTransformerImpl<S,
T>(handleData,
too weird.
make it a "return".

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:964: * not throw.
what if it throws?
If we catch it, and propagate it as an error in the sink, then we might as well
"advertise" the behavior.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream_pipe....
File sdk/lib/async/stream_pipe.dart (right):

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream_pipe....
sdk/lib/async/stream_pipe.dart:92: * Basic implemnetation of the handler
features of a [StreamSubscription].
implementation.
I don't understand the sentence.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream_pipe....
sdk/lib/async/stream_pipe.dart:151: // Don't unsubscribe on incoming error, only
if we send an error forwards.
Took me way too long to understand the comment...
"The "unsubscribeOnError" flag is not forwarded to the source's subscription.
Only if an error is sent to the successors of this subscription is the stream
unsubscribed.
This allows the error-handler to intercept the error and correctly handle it
without being unsubscribed."

[Lasse Reichstein Nielsen, 2013-01-29 08:42:54]

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart
File sdk/lib/async/stream.dart (right):

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:45: * The default implementation of [isBroadcast] is
assuming this is a
On 2013/01/28 14:45:09, floitsch wrote:
> The default implementation of [isBroadcast] returns `false`.

Done.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:219: * types of events for each incoming event.
On 2013/01/28 14:45:09, floitsch wrote:
> Mention how pauses are handled.

Done.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:221: * An example that adds one to each of a stream of
integers:
On 2013/01/28 14:45:09, floitsch wrote:
> Example is bad, since it could be implemented with "mappedBy".

Done.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:222: *     intStream.transformEvents(new
StreamEventTransformer.from(
On 2013/01/28 14:45:09, floitsch wrote:
> new line before the code.

Done.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:227: Stream transformEvents(StreamEventTransformer<T,
dynamic> transformer) {
On 2013/01/28 14:45:09, floitsch wrote:
> As discussed. We should consider making this the default ".transform", and
> rename the current transform to "chain".
> But for backwards-compatibility we need to start this way anyways.

Done.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:937: * the events unmodified. This will not work for
data events if the types
On 2013/01/28 14:45:09, floitsch wrote:
> ... unmodified. In that case the generic type T needs to be assignable to S.

Done.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:952: factory StreamEventTransformer.from({
Not possible. That would conflict with the constructor above, which is needed
for classes extending StreamEventTransformer.

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:956: }) => new _StreamEventTransformerImpl<S,
T>(handleData,
On 2013/01/28 14:45:09, floitsch wrote:
> too weird.
> make it a "return".

Done. It's still weird :)

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream.dart#...
sdk/lib/async/stream.dart:964: * not throw.
We don't catch it. It'll be an uncaught error in the event firing of the
underlying stream, so it will be sent to the global error handler.
I've changed "should" to "must".

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream_pipe....
File sdk/lib/async/stream_pipe.dart (right):

https://codereview.chromium.org/11953103/diff/3001/sdk/lib/async/stream_pipe....
sdk/lib/async/stream_pipe.dart:92: * Basic implemnetation of the handler
features of a [StreamSubscription].
Rewritten.