Support transforming the exception in Future.transform().

lib/core/future.dart

 // Copyright (c) 2011, 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.
 
 /**
  * A [Future] is used to obtain a value sometime in the future.  Receivers of a
  * [Future] can obtain the value by passing a callback to [then]. For example:
  *
  *     Future<int> future = getFutureFromSomewhere();
  *     future.then((value) {
@@ skipping 105 matching lines @@
     * will receive it.
     *
     * If an exception occurs (received by this future, thrown by
     * [transformation], or received by the future returned by [transformation])
     * then the returned future will receive the exception.
     *
     * You must not add exception handlers to [this] future prior to calling
     * chain, and any you add afterwards will not be invoked.
     */
    Future chain(Future transformation(T value));
+
+  /**
+   * A future representing [transformation] applied to this future's exception.
+   * This can be used to "catch" an exception coming from `this` and translate
+   * it to a more appropriate exception which will then be sent to the
+   * returned future.
+   *
+   * If this future gets a value, it simply completes to that same value. If an
+   * exception occurs, then [transformation] will be called with the exception
+   * value.
+   *
+   * If [transformation] itself throws an exception, then the returned future
+   * completes with that exception. If it returns `true`, then the exception is
+   * considered handled and is not propagated to the returned future. If it
+   * returns anything else, the original exception will be propagated.

[Siggi Cherem (dart-lang), 2012/09/04 20:17:52]

thinking about the control flow of this and how similar it is to try-catch -
maybe the return value should be propagated as the result of the future?

[Bob Nystrom, 2012/09/04 21:14:43]

Works for me. Done.

+   */
+  Future transformException(bool transformation(Object exception));

[nweiz, 2012/09/04 20:26:14]

It seems like this should just be the default behavior of handleException.

[Bob Nystrom, 2012/09/04 21:14:43]

I'm trying to keep this change as minimally invasive as possible, so I don't
want to change the behavior of existing methods. How about I ignore this for now
and after M1 we look at a revamp?

[nweiz, 2012/09/04 21:35:35]

Sure, seems fine.

 }
 
 
 /**
  * A [Completer] is used to produce [Future]s and supply their value when it
  * becomes available.
  *
  * A service that provides values to callers, and wants to return [Future]s can
  * use a [Completer] as follows:
  *
@@ skipping 83 matching lines @@
       future.handleException((exception) {
         if (!result.isComplete) {
           completer.completeException(exception, future.stackTrace);
         }
         return true;
       });
     }
     return result;
   }
 }