Add handle method to ErrorResult.

lib/result.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-/**
- * Capture asynchronous results into synchronous values, and release them again.
- *
- * Capturing a result (either a returned value or a thrown error)
- * means converting it into a [Result] -
- * either a [ValueResult] or an [ErrorResult].
- *
- * This value can release itself by writing itself either to a
- * [EventSink] or a [Completer], or by becoming a [Future].
- */
+/// Capture asynchronous results into synchronous values.
+///
+/// Capturing a result (either a returned value or a thrown error)
+/// means converting it into a [Result] -
+/// either a [ValueResult] or an [ErrorResult].
+///
+/// This value can release itself by writing itself either to a
+/// [EventSink] or a [Completer], or by becoming a [Future].
 library dart.pkg.async.results;
 
 import "dart:async";
 
-/**
- * The result of a computation.
- */
+/// The result of a computation.
 abstract class Result<T> {
-  /**
-   * Create a `Result` with the result of calling [computation].
-   *
-   * This generates either a [ValueResult] with the value returned by
-   * calling `computation`, or an [ErrorResult] with an error thrown by
-   * the call.
-   */
+  /// Create a `Result` with the result of calling [computation].
+  ///
+  /// This generates either a [ValueResult] with the value returned by
+  /// calling `computation`, or an [ErrorResult] with an error thrown by
+  /// the call.
   factory Result(T computation()) {
     try {
       return new ValueResult(computation());
     } catch (e, s) {
       return new ErrorResult(e, s);
     }
   }
 
-  /**
-   * Create a `Result` holding a value.
-   *
-   * Alias for [ValueResult.ValueResult].
-   */
+  /// Create a `Result` holding a value.
+  ///
+  /// Alias for [ValueResult.ValueResult].
   factory Result.value(T value) = ValueResult<T>;
 
-  /**
-   * Create a `Result` holding an error.
-   *
-   * Alias for [ErrorResult.ErrorResult].
-   */
+  /// Create a `Result` holding an error.
+  ///
+  /// Alias for [ErrorResult.ErrorResult].
   factory Result.error(Object error, [StackTrace stackTrace]) =>
       new ErrorResult(error, stackTrace);
 
   // Helper functions.
   static _captureValue(value) => new ValueResult(value);
   static _captureError(error, stack) => new ErrorResult(error, stack);
   static _release(Result v) {
     if (v.isValue) return v.asValue.value;  // Avoid wrapping in future.
     return v.asFuture;
   }
 
-  /**
-   * Capture the result of a future into a `Result` future.
-   *
-   * The resulting future will never have an error.
-   * Errors have been converted to an [ErrorResult] value.
-   */
+  /// Capture the result of a future into a `Result` future.
+  ///
+  /// The resulting future will never have an error.
+  /// Errors have been converted to an [ErrorResult] value.
   static Future<Result> capture(Future future) {
     return future.then(_captureValue, onError: _captureError);
   }
 
-  /**
-   * Release the result of a captured future.
-   *
-   * Converts the [Result] value of the given [future] to a value or error
-   * completion of the returned future.
-   *
-   * If [future] completes with an error, the returned future completes with
-   * the same error.
-   */
+  /// Release the result of a captured future.
+  ///
+  /// Converts the [Result] value of the given [future] to a value or error
+  /// completion of the returned future.
+  ///
+  /// If [future] completes with an error, the returned future completes with
+  /// the same error.
   static Future release(Future<Result> future) {
     return future.then(_release);
   }
 
-  /**
-   * Capture the results of a stream into a stream of [Result] values.
-   *
-   * The returned stream will not have any error events.
-   * Errors from the source stream have been converted to [ErrorResult]s.
-   *
-   * Shorthand for transforming the stream using [CaptureStreamTransformer].
-   */
+  /// Capture the results of a stream into a stream of [Result] values.
+  ///
+  /// The returned stream will not have any error events.
+  /// Errors from the source stream have been converted to [ErrorResult]s.
+  ///
+  /// Shorthand for transforming the stream using [CaptureStreamTransformer].
   static Stream<Result> captureStream(Stream source) {
     return source.transform(const CaptureStreamTransformer());
   }
 
-  /**
-   * Release a stream of [result] values into a stream of the results.
-   *
-   * `Result` values of the source stream become value or error events in
-   * the returned stream as appropriate.
-   * Errors from the source stream become errors in the returned stream.
-   *
-   * Shorthand for transforming the stream using [ReleaseStreamTransformer].
-   */
+  /// Release a stream of [result] values into a stream of the results.
+  ///
+  /// `Result` values of the source stream become value or error events in
+  /// the returned stream as appropriate.
+  /// Errors from the source stream become errors in the returned stream.
+  ///
+  /// Shorthand for transforming the stream using [ReleaseStreamTransformer].
   static Stream releaseStream(Stream<Result> source) {
     return source.transform(const ReleaseStreamTransformer());
   }
 
-  /**
-   * Converts a result of a result to a single result.
-   *
-   * If the result is an error, or it is a `Result` value
-   * which is then an error, then a result with that error is returned.
-   * Otherwise both levels of results are value results, and a single
-   * result with the value is returned.
-   */
+  /// Converts a result of a result to a single result.
+  ///
+  /// If the result is an error, or it is a `Result` value
+  /// which is then an error, then a result with that error is returned.
+  /// Otherwise both levels of results are value results, and a single
+  /// result with the value is returned.
   static Result flatten(Result<Result> result) {
     if (result.isError) return result;
     return result.asValue.value;
   }
 
-  /**
-   * Whether this result is a value result.
-   *
-   * Always the opposite of [isError].
-   */
+  /// Whether this result is a value result.
+  ///
+  /// Always the opposite of [isError].
   bool get isValue;
 
-  /**
-   * Whether this result is an error result.
-   *
-   * Always the opposite of [isValue].
-   */
+  /// Whether this result is an error result.
+  ///
+  /// Always the opposite of [isValue].
   bool get isError;
 
-  /**
-   * If this is a value result, return itself.
-   *
-   * Otherwise return `null`.
-   */
+  /// If this is a value result, return itself.
+  ///
+  /// Otherwise return `null`.
   ValueResult<T> get asValue;
 
-  /**
-   * If this is an error result, return itself.
-   *
-   * Otherwise return `null`.
-   */
+  /// If this is an error result, return itself.
+  ///
+  /// Otherwise return `null`.
   ErrorResult get asError;
 
-  /**
-   * Complete a completer with this result.
-   */
+  /// Complete a completer with this result.
   void complete(Completer<T> completer);
 
-  /**
-   * Add this result to a [StreamSink].
-   */
+  /// Add this result to an [EventSink].
+  ///
+  /// Calls the sink's `add` or `addError` method as appropriate.
   void addTo(EventSink<T> sink);
 
-  /**
-   * Creates a future completed with this result as a value or an error.
-   */
+  /// Creates a future completed with this result as a value or an error.
   Future<T> get asFuture;
 }
 
-/**
- * A result representing a returned value.
- */
+/// A result representing a returned value.
 class ValueResult<T> implements Result<T> {
-  /** The returned value that this result represents. */
   final T value;
-  /** Create a value result with the given [value]. */
   ValueResult(this.value);
   bool get isValue => true;
   bool get isError => false;
   ValueResult<T> get asValue => this;
   ErrorResult get asError => null;
   void complete(Completer<T> completer) {
     completer.complete(value);
   }
   void addTo(EventSink<T> sink) {
     sink.add(value);
   }
   Future<T> get asFuture => new Future.value(value);
 }
 
-/**
- * A result representing a thrown error.
- */
+/// A result representing a thrown error.
 class ErrorResult implements Result {
-  /** The thrown object that this result represents. */
   final error;
-  /** The stack trace, if any, associated with the throw. */
   final StackTrace stackTrace;
-  /** Create an error result with the given [error] and [stackTrace]. */
   ErrorResult(this.error, this.stackTrace);
   bool get isValue => false;
   bool get isError => true;
   ValueResult get asValue => null;
   ErrorResult get asError => this;
   void complete(Completer completer) {
     completer.completeError(error, stackTrace);
   }
   void addTo(EventSink sink) {
     sink.addError(error, stackTrace);
   }
   Future get asFuture => new Future.error(error, stackTrace);
+
+  /// Calls an error handler with the error and stacktrace.
+  ///
+  /// An async error handler function is either a function expecting two
+  /// arguments, which will be called with the error and the stack trace,
+  /// or it has to be a function expecting only one argument,
+  /// which will be called with only the error.
+  void handle(Function errorHandler) {
+    if (errorHandler is ZoneBinaryCallback) {
+      errorHandler(error, stackTrace);
+    } else {
+      errorHandler(error);
+    }
+  }
 }
 
-/**
- * A stream transformer that captures a stream of events into [Result]s.
- *
- * The result of the transformation is a stream of [Result] values and
- * no error events.
- */
+/// A stream transformer that captures a stream of events into [Result]s.
+///
+/// The result of the transformation is a stream of [Result] values and
+/// no error events.
 class CaptureStreamTransformer<T> implements StreamTransformer<T, Result<T>> {
   const CaptureStreamTransformer();
 
   Stream<Result<T>> bind(Stream<T> source) {
     return new Stream<Result<T>>.eventTransformed(source, _createSink);
   }
 
   static EventSink _createSink(EventSink<Result> sink) {
     return new CaptureSink(sink);
   }
 }
 
-/**
- * A stream transformer that releases a stream of result events.
- *
- * The result of the transformation is a stream of values and
- * error events.
- */
+/// A stream transformer that releases a stream of result events.
+///
+/// The result of the transformation is a stream of values and
+/// error events.
 class ReleaseStreamTransformer<T> implements StreamTransformer<Result<T>, T> {
   const ReleaseStreamTransformer();
 
   Stream<T> bind(Stream<Result<T>> source) {
     return new Stream<T>.eventTransformed(source, _createSink);
   }
 
   static EventSink<Result> _createSink(EventSink sink) {
     return new ReleaseSink(sink);
   }
 }
 
-/**
- * An event sink wrapper that captures the incoming events.
- *
- * Wraps an [EventSink] that expects [Result] values.
- * Accepts any value and error result,
- * and passes them to the wrapped sink as [Result] values.
- *
- * The wrapped sink will never receive an error event.
- */
+/// An event sink wrapper that captures the incoming events.
+///
+/// Wraps an [EventSink] that expects [Result] values.
+/// Accepts any value and error result,
+/// and passes them to the wrapped sink as [Result] values.
+///
+/// The wrapped sink will never receive an error event.
 class CaptureSink<T> implements EventSink<T> {
   final EventSink _sink;
 
   CaptureSink(EventSink<Result<T>> sink) : _sink = sink;
   void add(T value) { _sink.add(new ValueResult(value)); }
   void addError(Object error, [StackTrace stackTrace]) {
     _sink.add(new ErrorResult(error, stackTrace));
   }
   void close() { _sink.close(); }
 }
 
-/**
- * An event sink wrapper that releases the incoming result events.
- *
- * Wraps an output [EventSink] that expects any result.
- * Accepts [Result] values, and puts the result value or error into the
- * corresponding output sink add method.
- */
+/// An event sink wrapper that releases the incoming result events.
+///
+/// Wraps an output [EventSink] that expects any result.
+/// Accepts [Result] values, and puts the result value or error into the
+/// corresponding output sink add method.
 class ReleaseSink<T> implements EventSink<Result<T>> {
   final EventSink _sink;
   ReleaseSink(EventSink<T> sink) : _sink = sink;
   void add(Result<T> result) {
     if (result.isValue) {
       _sink.add(result.asValue.value);
     } else {
       ErrorResult error = result.asError;
       _sink.addError(error.error, error.stackTrace);
     }
   }
   void addError(Object error, [StackTrace stackTrace]) {
     // Errors may be added by intermediate processing, even if it is never
     // added by CaptureSink.
     _sink.addError(error, stackTrace);
   }
 
   void close() { _sink.close(); }
 }