MessageFormat fixup

lib/i18n/intl_message.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.
+
 /**
- * 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.
- *
  * Message/plural format library with locale support.
  *
- * Message format grammar:
  *
- *    messageFormatPattern := string ( "{" messageFormatElement "}" string )*
- *    messageFormatElement := argumentIndex [ "," elementFormat ]
- *    elementFormat := "plural" "," pluralStyle
- *                      | "select" "," selectStyle
- *    pluralStyle :=  pluralFormatPattern
- *    selectStyle :=  selectFormatPattern
- *    pluralFormatPattern := \\[ "offset" ":" offsetIndex ] pluralForms*
- *    selectFormatPattern := pluralForms*
- *    pluralForms := stringKey "{" ( "{" messageFormatElement "}"|string )* "}"
+ * _message example:
+ *    '''I see ${intl.plural(num_people,
+ *             {'0': 'no one at all',
+ *              '1': 'one other person',
+ *              'other': '$num_people other people'})} in $place.''''
  *
+ * Useage example:
+ *      msg(num_people, place) => new IntlMessage(
+            '''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'});
  *
- * Message example:
- *
- * I see {NUM_PEOPLE, plural, offset:1
- *         =0 {no one at all}
- *         =1 {{WHO}}
- *         one {{WHO} and one other person}
- *         other {{WHO} and # other people}}
- * in {PLACE}.
- *
- * Calling format({'NUM_PEOPLE': 2, 'WHO': 'Mark', 'PLACE': 'Athens'}) would
- * produce "I see Mark and one other person in Athens." as output.
+ * Calling `msg({'num_people': 2, 'place': 'Athens'});` would
+ * produce "I see 2 other people in Athens." as output.
+ * <!-- TODO(efortuna): documentation example involving the offset parameter.
+ * -->
  *
  * See tests/message_format_test.dart for more examples.
  */
 
-#library('MessageFormat');
+#library('intl_message');
 
-class MessageFormat {
+class IntlMessage {
+
+  /** String describing the use case for this message. */
+  String _messageDescription;
 
   /**
-   * String that is used to determin the particular case and gender needed to be
-   * returned. The format of this string follows the same pattern as in Closure,
-   * Java, and C++. This pattern is described at the beginning of this class
-   * definition. See tests/message_format_test.dart for more examples.
+   * String that contains the message to be displayed. It may contain
+   * placeholders in the form of string interpolated items (ie 'hello$foo') that
+   * will be substituted in to complete the message.
+   * See tests/message_format_test.dart for more examples.
    */
-  final String _messageFunction;
+  String _message;
 
   /**
-   * String indicating a language code with which the message is to be
-   * formatted (such as en-US).
+   * String indicating the locale code with which the message is to be
+   * formatted (such as en-CA).
    */
-  final String _locale;
+  String _languageCode;
+
+  /** Examples of the placeholders used in the message string. */
+  Map _messageExamples;
 
   /**
-   * Constructor. The constructor expects you do provide annotations in comments
-   * above your declaration of this constructor with an @desc describing the
-   * context for the useage of the function. You may also specify @ex to specify
-   * examples of inputs for each particular argument that the [_messageFunction]
-   * accepts. The String [_messageFunction] is used to determine the particular
-   * case and gender for the given instance. An optional [_locale] can be
-   * provided for specifics of the language locale to be used, otherwise, we
-   * will attempt to infer it (acceptable if Dart is running on the client, we
-   * can infer from the browser).
+   * Accepts a String [_message] that contains the message (that
+   * will be internationalized). A String [_messageDescription] describes the
+   * use case for this string in the program, and [examples] provides a map of
+   * examples for the items (if any) to be subsituted into [_message].
+   * It also optionally accepts a [_languageCode] to specify the particular
+   * language to return content in (necessary if the Dart code is not running in
+   * a browser). The values of [desc] and [examples] *must* be
+   * simple Strings available at compile time: no String interpolation or
+   * concatenation.
    */
-  //TODO(efortuna): _locale is not currently inferred.
-  const MessageFormat(this._messageFunction, [this._locale = 'en-US']);
+  IntlMessage(this._message, [final String desc='', final Map examples=const {},
+              final String locale='']) {
+    this._messageDescription = desc;
+    this._messageExamples = examples;
+    this._languageCode = locale;
+  }
 
-  /**
-   * Formats a message. By default, we treat '#' with special meaning
-   * representing the number (plural_variable - plural_offset). If [ignorePound]
-   * is true, then we do not treat '#' as a special character, and it is just
-   * treated literally. [namedParameters] is a map of String keys to String or
-   * int values to influence the formatting of the message or data in the
-   * message. For example, example, in the call to 
-   *     msg_formatter.format({'NUM_PEOPLE': 5, 'NAME': 'Angela'}),
-   * object \{'NUM_PEOPLE': 5, 'NAME': 'Angela'\} holds positional parameters.
-   * 1st parameter could mean 5 people, which could influence plural format,
-   * and 2nd parameter is just relevant data to be printed out in the proper
-   * position in the message.
-   * Returns the correctly formatted message in the desired language.
-   */
-  String format(Map<String, dynamic> messageParameters,
-                [bool ignorePound=false]) {
-    // TODO(efortuna): actually perform the translation here. For now, I'm just
-    // returning a description of the message to be returned.
-    return _messageDescription;
-  }
 }