Make verifiedLocale work differently depending on what it's verifying for

pkg/intl/lib/intl.dart

 // Copyright (c) 2012, 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.
 
 /**
  * This library provides internationalization and localization. This includes
  * message formatting and replacement, date and number formatting and parsing,
  * and utilities for working with Bidirectional text.
  *
  * For things that require locale or other data, there are multiple different
@@ skipping 22 matching lines @@
  * and used to create a date format via `anIntl.date()`. Static methods
  * on this class are also used in message formatting.
  *
  * Message example:
  *     '''I see ${Intl.plural(num_people,
  *               {'0': 'no one at all',
  *                '1': 'one other person',
  *                'other': '$num_people other people'})} in $place.''''
  *
  * Usage examples:
- *      today(date) => intl.message(
+ *      today(date) => Intl.message(
  *          "Today's date is $date",
  *          desc: 'Indicate the current date',
  *          examples: {'date' : 'June 8, 2012'});
  *      print(today(new Date.now());
  *
- *      msg(num_people, place) => intl.message(
+ *      msg({num_people, place}) => Intl.message(
  *           '''I see ${Intl.plural(num_people,
  *             {'0': 'no one at all',
  *              '1': 'one other person',
  *              'other': '$num_people other people'})} in $place.'''',
  *          desc: 'Description of how many people are seen as program start.',
  *          examples: {'num_people': 3, 'place': 'London'});
  *
  * Calling `msg({'num_people': 2, 'place': 'Athens'});` would
- * produce "I see 2 other people in Athens." as output.
+ * produce "I see 2 other people in Athens." as output in the default locale.
+ *
+ * To use a locale other than the default, use the `withLocale` function.
+ *       var todayString = new DateFormat("pt_BR").format(new Date.now());
+ *       print(withLocale("pt_BR", () => today(todayString));
  *
  * See `tests/message_format_test.dart` for more examples.
  */
  //TODO(efortuna): documentation example involving the offset parameter?
 
 class Intl {
   /**
    * String indicating the locale code with which the message is to be
    * formatted (such as en-CA).
    */
@@ skipping 78 matching lines @@
   /**
    * Given [newLocale] return a locale that we have data for that is similar
    * to it, if possible.
    * If [newLocale] is found directly, return it. If it can't be found, look up
    * based on just the language (e.g. 'en_CA' -> 'en'). Also accepts '-'
    * as a separator and changes it into '_' for lookup, and changes the
    * country to uppercase.
    * Note that null is interpreted as meaning the default locale, so if
    * [newLocale] is null it will be returned.
    */
-  static String verifiedLocale(String newLocale) {
-    // TODO(alanknight): This is specific to DateFormat, and only used there
-    // now. This should be moved, renamed, or generalized.
+  static String verifiedLocale(String newLocale, bool localeExists(String),
+                               [Function onFailure = _throwLocaleError]) {
+    // TODO(alanknight): Previously we kept a single verified locale on the Intl
+    // object, but with different verification for different uses, that's more
+    // difficult. As a result, we call this more often. Consider keeping
+    // verified locales for each purpose if it turns out to be a performance
+    // issue.
     if (newLocale == null) return systemLocale;
-    if (_localeExists(newLocale)) {
+    if (localeExists(newLocale)) {
       return newLocale;
     }
-    for (var each in [canonicalizedLocale(newLocale), _shortLocale(newLocale)]) {
-      if (_localeExists(each)) {
+    for (var each in
+        [canonicalizedLocale(newLocale), _shortLocale(newLocale)]) {
+      if (localeExists(each)) {
         return each;
       }
     }
-    throw new ArgumentError("Invalid locale '$newLocale'");
+    return onFailure(newLocale);
+  }
+
+  /**
+   * The default action if a locale isn't found in verifiedLocale. Throw
+   * an exception indicating the locale isn't correct.
+   */
+  static String _throwLocaleError(String localeName) {
+    throw new ArgumentError("Invalid locale '$localeName'");
   }
 
   /** Return the short version of a locale name, e.g. 'en_US' => 'en' */
   static String _shortLocale(String aLocale) {
     if (aLocale.length < 2) return aLocale;
     return aLocale.substring(0, 2).toLowerCase();
   }
 
   /**
    * Return a locale name turned into xx_YY where it might possibly be
@@ skipping 18 matching lines @@
    * Support method for message formatting. Select the correct plural form from
    * [cases] given [howMany].
    */
   static String plural(var howMany, Map cases, [num offset=0]) {
     // TODO(efortuna): Deal with "few" and "many" cases, offset, and others!
     return select(howMany.toString(), cases);
   }
 
   /**
    * Format the given function with a specific [locale], given a
-   * [msg_function] that takes no parameters and returns a String. We
-   * basically delay calling the message function proper until after the proper
-   * locale has been set.
+   * [message_function] that takes no parameters. The [message_function] can be
+   * a simple message function that just returns the result of `Intl.message()`
+   * it can be a wrapper around a message function that takes arguments, or it
+   * can be something more complex that manipulates multiple message
+   * functions.
+   *
+   * In either case, the purpose of this is to delay calling [message_function]
+   * until the proper locale has been set. This returns the result of calling
+   * [msg_function], which could be of an arbitrary type.
    */
-  static String withLocale(String locale, Function msg_function) {
+  static dynamic withLocale(String locale, message_function()) {
     // We have to do this silliness because Locale is not known at compile time,
-    // but must be a static variable.
+    // but must be a static variable in order to be visible to the Intl.message
+    // invocation.
     if (_defaultLocale == null) _defaultLocale = systemLocale;
     var oldLocale = _defaultLocale;
     _defaultLocale = locale;
-    var result = msg_function();
+    var result = message_function();
     _defaultLocale = oldLocale;
     return result;
   }
 
   /**
    * Support method for message formatting. Select the correct exact (gender,
    * usually) form from [cases] given the user [choice].
    */
   static String select(String choice, Map cases) {
     if (cases.containsKey(choice)) {
       return cases[choice];
     } else if (cases.containsKey('other')){
       return cases['other'];
     } else {
       return '';
     }
   }
 
   /**
    * Accessor for the current locale. This should always == the default locale,
    * unless for some reason this gets called inside a message that resets the
    * locale.
    */
   static String getCurrentLocale() {
     if (_defaultLocale == null) _defaultLocale = systemLocale;
     return _defaultLocale;
   }
 }