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.
  *
  * 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,

[Alan Knight, 2012/06/06 22:21:01]

Why are the triple quotes here needed?
Also, I think this would be clearer if put in context of how it's used. Right
now this looks like an expression that creates a string and then does nothing
with it.

[Bob Nystrom, 2012/06/06 22:22:48]

Do we expect the params to be SCREAMING_CAPS like this?

Also, if you add a blank line and indent the example 5 spaces (one to separate
it from the comment * and four for markdown), it will be a nice code block.

[Emily Fortuna, 2012/06/06 22:51:43]

Triple quotes so I don't have to quote and unquote each line, so the quote would
be multi-line. Technically this would add some extra whitespace in the message
but I figured for the example it was fine.

@Bob -- SCREAMING_CAPS borrowed from the examples in Closure and such and I just
hadn't changed them (see right hand side, which basically copies a lot of the
closure doc). No preference. I've changed it and made a code block.

+ *         {'0': 'no one at all',
+ *          '1': 'one other person',
+ *          'other': '$NUM_PEOPLE other people'})} in $PLACE.
  *
- * 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 format({'NUM_PEOPLE': 2, 'PLACE': 'Athens'}) would

[Bob Nystrom, 2012/06/06 22:22:48]

Use [: :] or backticks (markdown is backticks) to format inline code:
`format(...)`.

[Emily Fortuna, 2012/06/06 22:51:43]

Done.

+ * 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('IntlMessage');

[Bob Nystrom, 2012/06/06 22:22:48]

Our naming convention for libraries is lowercase_with_underscores, and usually
the name of the file, so "intl_message".

[Emily Fortuna, 2012/06/06 22:51:43]

Done.

 
-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).
+   * Constructor. Accepts a String [_message] that contains the message (that

[Bob Nystrom, 2012/06/06 22:22:48]

Remove "Constructor."

[Emily Fortuna, 2012/06/06 22:51:43]

Done.

+   * 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

[Bob Nystrom, 2012/06/06 22:22:48]

Use emphasis instead of all caps: "MUST" -> "*must*".

[Emily Fortuna, 2012/06/06 22:51:43]

Done.

+   * 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;
-  }
 }