OLD | NEW |
(Empty) | |
| 1 // Copyright (c) 2016, the Dart project authors. Please see the AUTHORS file |
| 2 // for details. All rights reserved. Use of this source code is governed by a |
| 3 // BSD-style license that can be found in the LICENSE file. |
| 4 |
| 5 import 'dart:async'; |
| 6 |
| 7 import 'result/capture_transformer.dart'; |
| 8 import 'result/error.dart'; |
| 9 import 'result/release_transformer.dart'; |
| 10 import 'result/value.dart'; |
| 11 import 'stream_sink_transformer.dart'; |
| 12 |
| 13 /// The result of a computation. |
| 14 /// |
| 15 /// Capturing a result (either a returned value or a thrown error) means |
| 16 /// converting it into a [Result] - either a [ValueResult] or an [ErrorResult]. |
| 17 /// |
| 18 /// This value can release itself by writing itself either to a [EventSink] or a |
| 19 /// [Completer], or by becoming a [Future]. |
| 20 abstract class Result<T> { |
| 21 /// A stream transformer that captures a stream of events into [Result]s. |
| 22 /// |
| 23 /// The result of the transformation is a stream of [Result] values and no |
| 24 /// error events. This is the transformer used by [captureStream]. |
| 25 static const StreamTransformer<Object, Result> captureStreamTransformer = |
| 26 const CaptureStreamTransformer(); |
| 27 |
| 28 /// A stream transformer that releases a stream of result events. |
| 29 /// |
| 30 /// The result of the transformation is a stream of values and error events. |
| 31 /// This is the transformer used by [releaseStream]. |
| 32 static const StreamTransformer<Object, Result> releaseStreamTransformer = |
| 33 const ReleaseStreamTransformer(); |
| 34 |
| 35 /// A sink transformer that captures events into [Result]s. |
| 36 /// |
| 37 /// The result of the transformation is a sink that only forwards [Result] |
| 38 /// values and no error events. |
| 39 static const StreamSinkTransformer<Object, Result> captureSinkTransformer = |
| 40 const StreamSinkTransformer.fromStreamTransformer( |
| 41 const CaptureStreamTransformer()); |
| 42 |
| 43 /// A sink transformer that releases result events. |
| 44 /// |
| 45 /// The result of the transformation is a sink that forwards of values and |
| 46 /// error events. |
| 47 static const StreamSinkTransformer<Object, Result> releaseSinkTransformer = |
| 48 const StreamSinkTransformer.fromStreamTransformer( |
| 49 const ReleaseStreamTransformer()); |
| 50 |
| 51 /// Create a `Result` with the result of calling [computation]. |
| 52 /// |
| 53 /// This generates either a [ValueResult] with the value returned by |
| 54 /// calling `computation`, or an [ErrorResult] with an error thrown by |
| 55 /// the call. |
| 56 factory Result(T computation()) { |
| 57 try { |
| 58 return new ValueResult(computation()); |
| 59 } catch (e, s) { |
| 60 return new ErrorResult(e, s); |
| 61 } |
| 62 } |
| 63 |
| 64 /// Create a `Result` holding a value. |
| 65 /// |
| 66 /// Alias for [ValueResult.ValueResult]. |
| 67 factory Result.value(T value) = ValueResult<T>; |
| 68 |
| 69 /// Create a `Result` holding an error. |
| 70 /// |
| 71 /// Alias for [ErrorResult.ErrorResult]. |
| 72 factory Result.error(Object error, [StackTrace stackTrace]) => |
| 73 new ErrorResult(error, stackTrace); |
| 74 |
| 75 // Helper functions. |
| 76 static _captureValue(value) => new ValueResult(value); |
| 77 static _captureError(error, stack) => new ErrorResult(error, stack); |
| 78 static _release(Result v) { |
| 79 if (v.isValue) return v.asValue.value; // Avoid wrapping in future. |
| 80 return v.asFuture; |
| 81 } |
| 82 |
| 83 /// Capture the result of a future into a `Result` future. |
| 84 /// |
| 85 /// The resulting future will never have an error. |
| 86 /// Errors have been converted to an [ErrorResult] value. |
| 87 static Future<Result> capture(Future future) { |
| 88 return future.then(_captureValue, onError: _captureError); |
| 89 } |
| 90 |
| 91 /// Release the result of a captured future. |
| 92 /// |
| 93 /// Converts the [Result] value of the given [future] to a value or error |
| 94 /// completion of the returned future. |
| 95 /// |
| 96 /// If [future] completes with an error, the returned future completes with |
| 97 /// the same error. |
| 98 static Future release(Future<Result> future) { |
| 99 return future.then(_release); |
| 100 } |
| 101 |
| 102 /// Capture the results of a stream into a stream of [Result] values. |
| 103 /// |
| 104 /// The returned stream will not have any error events. |
| 105 /// Errors from the source stream have been converted to [ErrorResult]s. |
| 106 /// |
| 107 /// Shorthand for transforming the stream using [captureStreamTransformer]. |
| 108 static Stream<Result> captureStream(Stream source) { |
| 109 return source.transform(captureStreamTransformer); |
| 110 } |
| 111 |
| 112 /// Release a stream of [result] values into a stream of the results. |
| 113 /// |
| 114 /// `Result` values of the source stream become value or error events in |
| 115 /// the returned stream as appropriate. |
| 116 /// Errors from the source stream become errors in the returned stream. |
| 117 /// |
| 118 /// Shorthand for transforming the stream using [releaseStreamTransformer]. |
| 119 static Stream releaseStream(Stream<Result> source) { |
| 120 return source.transform(releaseStreamTransformer); |
| 121 } |
| 122 |
| 123 /// Converts a result of a result to a single result. |
| 124 /// |
| 125 /// If the result is an error, or it is a `Result` value |
| 126 /// which is then an error, then a result with that error is returned. |
| 127 /// Otherwise both levels of results are value results, and a single |
| 128 /// result with the value is returned. |
| 129 static Result flatten(Result<Result> result) { |
| 130 if (result.isError) return result; |
| 131 return result.asValue.value; |
| 132 } |
| 133 |
| 134 /// Whether this result is a value result. |
| 135 /// |
| 136 /// Always the opposite of [isError]. |
| 137 bool get isValue; |
| 138 |
| 139 /// Whether this result is an error result. |
| 140 /// |
| 141 /// Always the opposite of [isValue]. |
| 142 bool get isError; |
| 143 |
| 144 /// If this is a value result, return itself. |
| 145 /// |
| 146 /// Otherwise return `null`. |
| 147 ValueResult<T> get asValue; |
| 148 |
| 149 /// If this is an error result, return itself. |
| 150 /// |
| 151 /// Otherwise return `null`. |
| 152 ErrorResult get asError; |
| 153 |
| 154 /// Complete a completer with this result. |
| 155 void complete(Completer<T> completer); |
| 156 |
| 157 /// Add this result to an [EventSink]. |
| 158 /// |
| 159 /// Calls the sink's `add` or `addError` method as appropriate. |
| 160 void addTo(EventSink<T> sink); |
| 161 |
| 162 /// Creates a future completed with this result as a value or an error. |
| 163 Future<T> get asFuture; |
| 164 } |
OLD | NEW |