Convert Intl to use /// doc comments throughout.
-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=111860835
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9334025..7bc0061 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
* Support @@locale in ARB files as well as the older _locale
* Print a message when generating from ARB files if we guess the locale
from the file name when there's no explicit @@locale or _locale in the file.
+ * Switch all the source to use line comments.
## 0.12.5
* Parse Eras in DateFormat.
diff --git a/bin/extract_to_arb.dart b/bin/extract_to_arb.dart
index a79023b..18b18f1 100644
--- a/bin/extract_to_arb.dart
+++ b/bin/extract_to_arb.dart
@@ -3,11 +3,9 @@
// 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 script uses the extract_messages.dart library to find the Intl.message
- * calls in the target dart files and produces ARB format output. See
- * https://code.google.com/p/arb/wiki/ApplicationResourceBundleSpecification
- */
+/// This script uses the extract_messages.dart library to find the Intl.message
+/// calls in the target dart files and produces ARB format output. See
+/// https://code.google.com/p/arb/wiki/ApplicationResourceBundleSpecification
library extract_to_arb;
import 'dart:convert';
@@ -57,21 +55,17 @@
}
}
-/**
- * This is a placeholder for transforming a parameter substitution from
- * the translation file format into a Dart interpolation. In our case we
- * store it to the file in Dart interpolation syntax, so the transformation
- * is trivial.
- */
+/// This is a placeholder for transforming a parameter substitution from
+/// the translation file format into a Dart interpolation. In our case we
+/// store it to the file in Dart interpolation syntax, so the transformation
+/// is trivial.
String leaveTheInterpolationsInDartForm(MainMessage msg, chunk) {
if (chunk is String) return chunk;
if (chunk is int) return "\$${msg.arguments[chunk]}";
return chunk.toCode();
}
-/**
- * Convert the [MainMessage] to a trivial JSON format.
- */
+/// Convert the [MainMessage] to a trivial JSON format.
Map toARB(MainMessage message) {
if (message.messagePieces.isEmpty) return null;
var out = {};
@@ -103,10 +97,8 @@
result[arg] = extraInfo;
}
-/**
- * Return a version of the message string with
- * with ICU parameters "{variable}" rather than Dart interpolations "$variable".
- */
+/// Return a version of the message string with with ICU parameters "{variable}"
+/// rather than Dart interpolations "$variable".
String icuForm(MainMessage message) =>
message.expanded(turnInterpolationIntoICUForm);
diff --git a/bin/generate_from_arb.dart b/bin/generate_from_arb.dart
index dd81485..338067a 100644
--- a/bin/generate_from_arb.dart
+++ b/bin/generate_from_arb.dart
@@ -3,20 +3,19 @@
// 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 main program that takes as input a source Dart file and a number
- * of ARB files representing translations of messages from the corresponding
- * Dart file. See extract_to_arb.dart and make_hardcoded_translation.dart.
- *
- * If the ARB file has an @@locale or _locale value, that will be used as
- * the locale. If not, we will try to figure out the locale from the end of
- * the file name, e.g. foo_en_GB.arb will be assumed to be in en_GB locale.
- *
- * This produces a series of files named
- * "messages_<locale>.dart" containing messages for a particular locale
- * and a main import file named "messages_all.dart" which has imports all of
- * them and provides an initializeMessages function.
- */
+/// A main program that takes as input a source Dart file and a number
+/// of ARB files representing translations of messages from the corresponding
+/// Dart file. See extract_to_arb.dart and make_hardcoded_translation.dart.
+///
+/// If the ARB file has an @@locale or _locale value, that will be used as
+/// the locale. If not, we will try to figure out the locale from the end of
+/// the file name, e.g. foo_en_GB.arb will be assumed to be in en_GB locale.
+///
+/// This produces a series of files named
+/// "messages_<locale>.dart" containing messages for a particular locale
+/// and a main import file named "messages_all.dart" which has imports all of
+/// them and provides an initializeMessages function.
+
library generate_from_arb;
import 'dart:convert';
@@ -28,10 +27,8 @@
import 'package:path/path.dart' as path;
import 'package:args/args.dart';
-/**
- * Keeps track of all the messages we have processed so far, keyed by message
- * name.
- */
+/// Keeps track of all the messages we have processed so far, keyed by message
+/// name.
Map<String, List<MainMessage>> messages;
main(List<String> args) {
@@ -85,13 +82,11 @@
mainImportFile.writeAsStringSync(generateMainImportFile());
}
-/**
- * Create the file of generated code for a particular locale. We read the ARB
- * data and create [BasicTranslatedMessage] instances from everything,
- * excluding only the special _locale attribute that we use to indicate the
- * locale. If that attribute is missing, we try to get the locale from the last
- * section of the file name.
- */
+/// Create the file of generated code for a particular locale. We read the ARB
+/// data and create [BasicTranslatedMessage] instances from everything,
+/// excluding only the special _locale attribute that we use to indicate the
+/// locale. If that attribute is missing, we try to get the locale from the last
+/// section of the file name.
void generateLocaleFile(File file, String targetDir) {
var src = file.readAsStringSync();
var data = JSON.decode(src);
@@ -120,12 +115,10 @@
generateIndividualMessageFile(locale, translations, targetDir);
}
-/**
- * Regenerate the original IntlMessage objects from the given [data]. For
- * things that are messages, we expect [id] not to start with "@" and
- * [data] to be a String. For metadata we expect [id] to start with "@"
- * and [data] to be a Map or null. For metadata we return null.
- */
+/// Regenerate the original IntlMessage objects from the given [data]. For
+/// things that are messages, we expect [id] not to start with "@" and
+/// [data] to be a String. For metadata we expect [id] to start with "@"
+/// and [data] to be a Map or null. For metadata we return null.
BasicTranslatedMessage recreateIntlObjects(String id, data) {
if (id.startsWith("@")) return null;
if (data == null) return null;
@@ -137,10 +130,8 @@
return new BasicTranslatedMessage(id, parsed);
}
-/**
- * A TranslatedMessage that just uses the name as the id and knows how to look
- * up its original messages in our [messages].
- */
+/// A TranslatedMessage that just uses the name as the id and knows how to look
+/// up its original messages in our [messages].
class BasicTranslatedMessage extends TranslatedMessage {
BasicTranslatedMessage(String name, translated) : super(name, translated);
diff --git a/example/basic/basic_example.dart b/example/basic/basic_example.dart
index 25f9cb0..a58f614 100644
--- a/example/basic/basic_example.dart
+++ b/example/basic/basic_example.dart
@@ -2,18 +2,16 @@
// 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 provides a basic example of internationalization usage. It uses the
- * local variant of all the facilities, meaning that libraries with the
- * data for all the locales are directly imported by the program. Once lazy
- * loading is available, we expect this to be the preferred mode, with
- * the initialization code actually loading the specific libraries needed.
- *
- * This defines messages for an English locale directly in the program and
- * has separate libraries that define German and Thai messages that say more or
- * less the same thing, and prints the message with the date and time in it
- * formatted appropriately for the locale.
- */
+/// This provides a basic example of internationalization usage. It uses the
+/// local variant of all the facilities, meaning that libraries with the
+/// data for all the locales are directly imported by the program. Once lazy
+/// loading is available, we expect this to be the preferred mode, with
+/// the initialization code actually loading the specific libraries needed.
+///
+/// This defines messages for an English locale directly in the program and
+/// has separate libraries that define German and Thai messages that say more or
+/// less the same thing, and prints the message with the date and time in it
+/// formatted appropriately for the locale.
library intl_basic_example;
@@ -22,12 +20,10 @@
import 'package:intl/intl.dart';
import 'messages_all.dart';
-/**
- * In order to use this both as an example and as a test case, we pass in
- * the function for what we're going to do with the output. For a simple
- * example we just pass in [print] and for tests we pass in a function that
- * adds it a list to be verified.
- */
+/// In order to use this both as an example and as a test case, we pass in
+/// the function for what we're going to do with the output. For a simple
+/// example we just pass in [print] and for tests we pass in a function that
+/// adds it a list to be verified.
Function doThisWithTheOutput;
void setup(Function program, Function output) {
diff --git a/example/basic/basic_example_runner.dart b/example/basic/basic_example_runner.dart
index 805d4f7..2c67c7b 100644
--- a/example/basic/basic_example_runner.dart
+++ b/example/basic/basic_example_runner.dart
@@ -2,10 +2,8 @@
// 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 is just a shell that runs the code in basic_example.dart, leaving
- * that as a library that can also be run by tests.
- */
+/// This is just a shell that runs the code in basic_example.dart, leaving
+/// that as a library that can also be run by tests.
import 'basic_example.dart';
diff --git a/example/basic/messages_all.dart b/example/basic/messages_all.dart
index 88942b3..a2fb844 100644
--- a/example/basic/messages_all.dart
+++ b/example/basic/messages_all.dart
@@ -2,11 +2,9 @@
// 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 imports all of the different message libraries and provides an
- * [initializeMessages] function that sets up the lookup for a particular
- * library.
- */
+/// This imports all of the different message libraries and provides an
+/// [initializeMessages] function that sets up the lookup for a particular
+/// library.
library messages_all;
import 'dart:async';
diff --git a/example/basic/messages_de.dart b/example/basic/messages_de.dart
index dea00ac..ce80108 100644
--- a/example/basic/messages_de.dart
+++ b/example/basic/messages_de.dart
@@ -2,11 +2,9 @@
// 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 is a library that provides messages for a German locale. All the
- * messages from the main program should be duplicated here with the same
- * function name.
- */
+/// This is a library that provides messages for a German locale. All the
+/// messages from the main program should be duplicated here with the same
+/// function name.
library messages_de;
import 'package:intl/intl.dart';
diff --git a/example/basic/messages_th_th.dart b/example/basic/messages_th_th.dart
index c5f3187..c478981 100644
--- a/example/basic/messages_th_th.dart
+++ b/example/basic/messages_th_th.dart
@@ -2,11 +2,9 @@
// 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 is a library that provides messages for a German locale. All the
- * messages from the main program should be duplicated here with the same
- * function name.
- */
+/// This is a library that provides messages for a German locale. All the
+/// messages from the main program should be duplicated here with the same
+/// function name.
library messages_th_TH;
import 'package:intl/intl.dart';
diff --git a/lib/date_symbol_data_file.dart b/lib/date_symbol_data_file.dart
index c1b5ea4..c6c5f86 100644
--- a/lib/date_symbol_data_file.dart
+++ b/lib/date_symbol_data_file.dart
@@ -2,10 +2,8 @@
// 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 file should be imported, along with date_format.dart in order to read
- * locale data from files in the file system.
- */
+/// This file should be imported, along with date_format.dart in order to read
+/// locale data from files in the file system.
library date_symbol_data_file;
@@ -21,12 +19,10 @@
export 'src/data/dates/locale_list.dart';
-/**
- * This should be called for at least one [locale] before any date formatting
- * methods are called. It sets up the lookup for date symbols using [path].
- * The [path] parameter should end with a directory separator appropriate
- * for the platform.
- */
+/// This should be called for at least one [locale] before any date formatting
+/// methods are called. It sets up the lookup for date symbols using [path].
+/// The [path] parameter should end with a directory separator appropriate
+/// for the platform.
Future initializeDateFormatting(String locale, String filePath) {
var reader = new FileDataReader(path.join(filePath, 'symbols'));
initializeDateSymbols(() => new LazyLocaleData(
@@ -40,6 +36,6 @@
});
}
-/** Defines how new date symbol entries are created. */
+/// Defines how new date symbol entries are created.
DateSymbols _createDateSymbol(Map map) =>
new DateSymbols.deserializeFromMap(map);
diff --git a/lib/date_symbol_data_http_request.dart b/lib/date_symbol_data_http_request.dart
index 5e206f6..deea536 100644
--- a/lib/date_symbol_data_http_request.dart
+++ b/lib/date_symbol_data_http_request.dart
@@ -2,10 +2,8 @@
// 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 file should be imported, along with date_format.dart in order to read
- * locale data via http requests to a web server..
- */
+/// This file should be imported, along with date_format.dart in order to read
+/// locale data via http requests to a web server..
library date_symbol_data_http_request;
import 'dart:async';
@@ -19,12 +17,10 @@
export 'src/data/dates/locale_list.dart';
-/**
- * This should be called for at least one [locale] before any date formatting
- * methods are called. It sets up the lookup for date symbols using [url].
- * The [url] parameter should end with a "/". For example,
- * "http://localhost:8000/dates/"
- */
+/// This should be called for at least one [locale] before any date formatting
+/// methods are called. It sets up the lookup for date symbols using [url].
+/// The [url] parameter should end with a "/". For example,
+/// "http://localhost:8000/dates/"
Future initializeDateFormatting(String locale, String url) {
var reader = new HttpRequestDataReader('${url}symbols/');
initializeDateSymbols(() => new LazyLocaleData(
@@ -40,6 +36,6 @@
});
}
-/** Defines how new date symbol entries are created. */
+/// Defines how new date symbol entries are created.
DateSymbols _createDateSymbol(Map map) =>
new DateSymbols.deserializeFromMap(map);
diff --git a/lib/date_symbol_data_local.dart b/lib/date_symbol_data_local.dart
index 3af061a..460a5e9 100644
--- a/lib/date_symbol_data_local.dart
+++ b/lib/date_symbol_data_local.dart
@@ -4,19 +4,17 @@
// is governed by a
// BSD-style license that can be found in the LICENSE file.
-/**
- * Date/time formatting symbols for all locales.
- *
- * DO NOT EDIT. This file is autogenerated by script. See
- * 'http://go/generate_datetime_constants.py' using the --for_dart
- * flag.
- * File generated from CLDR ver. 28
- *
- * Before checkin, this file could have been manually edited. This is
- * to incorporate changes before we could correct CLDR. All manual
- * modification must be documented in this section, and should be
- * removed after those changes land to CLDR.
- */
+/// Date/time formatting symbols for all locales.
+///
+/// DO NOT EDIT. This file is autogenerated by script. See
+/// 'http://go/generate_datetime_constants.py' using the --for_dart
+/// flag.
+/// File generated from CLDR ver. 28
+///
+/// Before checkin, this file could have been manually edited. This is
+/// to incorporate changes before we could correct CLDR. All manual
+/// modification must be documented in this section, and should be
+/// removed after those changes land to CLDR.
library date_symbol_data_local;
import "date_symbols.dart";
@@ -24,23 +22,19 @@
import "date_time_patterns.dart";
import "dart:async";
-/**
- * This should be called for at least one [locale] before any date
- * formatting methods are called. It sets up the lookup for date
- * symbols. Both the [locale] and [ignored] parameter are ignored, as
- * the data for all locales is directly available.
- */
+/// This should be called for at least one [locale] before any date
+/// formatting methods are called. It sets up the lookup for date
+/// symbols. Both the [locale] and [ignored] parameter are ignored, as
+/// the data for all locales is directly available.
Future initializeDateFormatting(String locale, String ignored) {
initializeDateSymbols(dateTimeSymbolMap);
initializeDatePatterns(dateTimePatternMap);
return new Future.value(null);
}
-/**
- * Returns a Map from locale names to the DateSymbols instance for
- * that locale. Internal use only. Call initializeDateFormatting
- * instead.
- */
+/// Returns a Map from locale names to the DateSymbols instance for
+/// that locale. Internal use only. Call initializeDateFormatting
+/// instead.
Map dateTimeSymbolMap() => {
// Date/time formatting symbols for locale en_ISO.
"en_ISO": new DateSymbols(
diff --git a/lib/date_symbols.dart b/lib/date_symbols.dart
index bbded50..66b2fe7 100644
--- a/lib/date_symbols.dart
+++ b/lib/date_symbols.dart
@@ -3,15 +3,13 @@
// BSD-style license that can be found in the LICENSE file.
library date_symbols;
-/**
- * This holds onto information about how a particular locale formats dates. It
- * contains mostly strings, e.g. what the names of months or weekdays are,
- * but also indicates things like the first day of the week. We expect the data
- * for instances of these to be generated out of ICU or a similar reference
- * source. This is used in conjunction with the date_time_patterns, which
- * defines for a particular locale the different named formats that will
- * make use of this data.
- */
+/// This holds onto information about how a particular locale formats dates. It
+/// contains mostly strings, e.g. what the names of months or weekdays are,
+/// but also indicates things like the first day of the week. We expect the data
+/// for instances of these to be generated out of ICU or a similar reference
+/// source. This is used in conjunction with the date_time_patterns, which
+/// defines for a particular locale the different named formats that will
+/// make use of this data.
class DateSymbols {
String NAME;
List<String> ERAS,
@@ -114,10 +112,8 @@
toString() => NAME;
}
-/**
- * We hard-code the locale data for en_US here so that there's at least one
- * locale always available.
- */
+/// We hard-code the locale data for en_US here so that there's at least one
+/// locale always available.
var en_USSymbols = new DateSymbols(
NAME: "en_US",
ERAS: const ['BC', 'AD'],
diff --git a/lib/date_time_patterns.dart b/lib/date_time_patterns.dart
index bc586ef..9b0c4eb 100644
--- a/lib/date_time_patterns.dart
+++ b/lib/date_time_patterns.dart
@@ -2,25 +2,20 @@
// 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.
-/**
- * Date/time formatting symbols for a large subset of locales.
- *
- * DO NOT EDIT. This file is autogenerated from ICU data. See
- * 'http://go/generate_datetime_pattern_dart.cc' (Google internal)
- * File generated from CLDR ver. 28.0
- */
+/// Date/time formatting symbols for a large subset of locales.
+///
+/// DO NOT EDIT. This file is autogenerated from ICU data. See
+/// 'http://go/generate_datetime_pattern_dart.cc' (Google internal)
+/// File generated from CLDR ver. 28.0
library date_time_patterns;
-/**
- * Returns a Map from locale names to another Map that goes from skeletons
- * to the locale-specific formatting patterns.
- * Internal use only. Call initializeDateFormatting instead.
- **/
+/// Returns a Map from locale names to another Map that goes from skeletons
+/// to the locale-specific formatting patterns.
+/// Internal use only. Call initializeDateFormatting instead.
+/// */
Map dateTimePatternMap() => const {
- /**
- * Extended set of localized date/time patterns for locale af.
- */
+/// Extended set of localized date/time patterns for locale af.
'af': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -68,9 +63,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale am.
- */
+ /// Extended set of localized date/time patterns for locale am.
'am': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -118,9 +111,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ar.
- */
+ /// Extended set of localized date/time patterns for locale ar.
'ar': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -168,9 +159,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale az.
- */
+ /// Extended set of localized date/time patterns for locale az.
'az': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -218,9 +207,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale be.
- */
+ /// Extended set of localized date/time patterns for locale be.
'be': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -268,9 +255,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale bg.
- */
+ /// Extended set of localized date/time patterns for locale bg.
'bg': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -318,9 +303,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale bn.
- */
+ /// Extended set of localized date/time patterns for locale bn.
'bn': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -368,9 +351,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale br.
- */
+ /// Extended set of localized date/time patterns for locale br.
'br': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -418,9 +399,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale bs.
- */
+ /// Extended set of localized date/time patterns for locale bs.
'bs': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -468,9 +447,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ca.
- */
+ /// Extended set of localized date/time patterns for locale ca.
'ca': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -518,9 +495,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale chr.
- */
+ /// Extended set of localized date/time patterns for locale chr.
'chr': const {
'd': 'd', // DAY
'E': 'EEE', // ABBR_WEEKDAY
@@ -568,9 +543,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale cs.
- */
+ /// Extended set of localized date/time patterns for locale cs.
'cs': const {
'd': 'd.', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -618,9 +591,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale cy.
- */
+ /// Extended set of localized date/time patterns for locale cy.
'cy': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -668,9 +639,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale da.
- */
+ /// Extended set of localized date/time patterns for locale da.
'da': const {
'd': 'd.', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -718,9 +687,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale de.
- */
+ /// Extended set of localized date/time patterns for locale de.
'de': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -768,9 +735,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale de_AT.
- */
+ /// Extended set of localized date/time patterns for locale de_AT.
'de_AT': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -818,9 +783,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale de_CH.
- */
+ /// Extended set of localized date/time patterns for locale de_CH.
'de_CH': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -868,9 +831,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale el.
- */
+ /// Extended set of localized date/time patterns for locale el.
'el': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -918,9 +879,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale en.
- */
+ /// Extended set of localized date/time patterns for locale en.
'en': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -968,9 +927,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale en_AU.
- */
+ /// Extended set of localized date/time patterns for locale en_AU.
'en_AU': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1018,9 +975,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale en_CA.
- */
+ /// Extended set of localized date/time patterns for locale en_CA.
'en_CA': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1068,9 +1023,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale en_GB.
- */
+ /// Extended set of localized date/time patterns for locale en_GB.
'en_GB': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1118,9 +1071,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale en_IE.
- */
+ /// Extended set of localized date/time patterns for locale en_IE.
'en_IE': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1168,9 +1119,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale en_IN.
- */
+ /// Extended set of localized date/time patterns for locale en_IN.
'en_IN': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1218,9 +1167,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale en_SG.
- */
+ /// Extended set of localized date/time patterns for locale en_SG.
'en_SG': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1268,9 +1215,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale en_US.
- */
+ /// Extended set of localized date/time patterns for locale en_US.
'en_US': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1318,9 +1263,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale en_ZA.
- */
+ /// Extended set of localized date/time patterns for locale en_ZA.
'en_ZA': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1368,9 +1311,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale es.
- */
+ /// Extended set of localized date/time patterns for locale es.
'es': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1418,9 +1359,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale es_419.
- */
+ /// Extended set of localized date/time patterns for locale es_419.
'es_419': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1468,9 +1407,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale es_ES.
- */
+ /// Extended set of localized date/time patterns for locale es_ES.
'es_ES': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1518,9 +1455,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale es_MX.
- */
+ /// Extended set of localized date/time patterns for locale es_MX.
'es_MX': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1568,9 +1503,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale es_US.
- */
+ /// Extended set of localized date/time patterns for locale es_US.
'es_US': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1618,9 +1551,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale et.
- */
+ /// Extended set of localized date/time patterns for locale et.
'et': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1668,9 +1599,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale eu.
- */
+ /// Extended set of localized date/time patterns for locale eu.
'eu': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1718,9 +1647,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale fa.
- */
+ /// Extended set of localized date/time patterns for locale fa.
'fa': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1768,9 +1695,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale fi.
- */
+ /// Extended set of localized date/time patterns for locale fi.
'fi': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1818,9 +1743,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale fil.
- */
+ /// Extended set of localized date/time patterns for locale fil.
'fil': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -1868,9 +1791,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale fr.
- */
+ /// Extended set of localized date/time patterns for locale fr.
'fr': const {
'd': 'd', // DAY
'E': 'EEE', // ABBR_WEEKDAY
@@ -1918,9 +1839,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale fr_CA.
- */
+ /// Extended set of localized date/time patterns for locale fr_CA.
'fr_CA': const {
'd': 'd', // DAY
'E': 'EEE', // ABBR_WEEKDAY
@@ -1968,9 +1887,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ga.
- */
+ /// Extended set of localized date/time patterns for locale ga.
'ga': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2018,9 +1935,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale gl.
- */
+ /// Extended set of localized date/time patterns for locale gl.
'gl': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2068,9 +1983,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale gsw.
- */
+ /// Extended set of localized date/time patterns for locale gsw.
'gsw': const {
'd': 'd', // DAY
'E': 'EEE', // ABBR_WEEKDAY
@@ -2118,9 +2031,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale gu.
- */
+ /// Extended set of localized date/time patterns for locale gu.
'gu': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2168,9 +2079,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale haw.
- */
+ /// Extended set of localized date/time patterns for locale haw.
'haw': const {
'd': 'd', // DAY
'E': 'EEE', // ABBR_WEEKDAY
@@ -2218,9 +2127,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale he.
- */
+ /// Extended set of localized date/time patterns for locale he.
'he': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2268,9 +2175,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale hi.
- */
+ /// Extended set of localized date/time patterns for locale hi.
'hi': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2318,9 +2223,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale hr.
- */
+ /// Extended set of localized date/time patterns for locale hr.
'hr': const {
'd': 'd.', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2368,9 +2271,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale hu.
- */
+ /// Extended set of localized date/time patterns for locale hu.
'hu': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2418,9 +2319,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale hy.
- */
+ /// Extended set of localized date/time patterns for locale hy.
'hy': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2468,9 +2367,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale id.
- */
+ /// Extended set of localized date/time patterns for locale id.
'id': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2518,9 +2415,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale in.
- */
+ /// Extended set of localized date/time patterns for locale in.
'in': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2568,9 +2463,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale is.
- */
+ /// Extended set of localized date/time patterns for locale is.
'is': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2618,9 +2511,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale it.
- */
+ /// Extended set of localized date/time patterns for locale it.
'it': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2668,9 +2559,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale iw.
- */
+ /// Extended set of localized date/time patterns for locale iw.
'iw': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2718,9 +2607,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ja.
- */
+ /// Extended set of localized date/time patterns for locale ja.
'ja': const {
'd': 'd日', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2768,9 +2655,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ka.
- */
+ /// Extended set of localized date/time patterns for locale ka.
'ka': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2818,9 +2703,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale kk.
- */
+ /// Extended set of localized date/time patterns for locale kk.
'kk': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2868,9 +2751,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale km.
- */
+ /// Extended set of localized date/time patterns for locale km.
'km': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2918,9 +2799,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale kn.
- */
+ /// Extended set of localized date/time patterns for locale kn.
'kn': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -2968,9 +2847,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ko.
- */
+ /// Extended set of localized date/time patterns for locale ko.
'ko': const {
'd': 'd일', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3018,9 +2895,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ky.
- */
+ /// Extended set of localized date/time patterns for locale ky.
'ky': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3068,9 +2943,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ln.
- */
+ /// Extended set of localized date/time patterns for locale ln.
'ln': const {
'd': 'd', // DAY
'E': 'EEE', // ABBR_WEEKDAY
@@ -3118,9 +2991,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale lo.
- */
+ /// Extended set of localized date/time patterns for locale lo.
'lo': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3168,9 +3039,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale lt.
- */
+ /// Extended set of localized date/time patterns for locale lt.
'lt': const {
'd': 'dd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3218,9 +3087,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale lv.
- */
+ /// Extended set of localized date/time patterns for locale lv.
'lv': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3268,9 +3135,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale mk.
- */
+ /// Extended set of localized date/time patterns for locale mk.
'mk': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3318,9 +3183,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ml.
- */
+ /// Extended set of localized date/time patterns for locale ml.
'ml': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3368,9 +3231,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale mn.
- */
+ /// Extended set of localized date/time patterns for locale mn.
'mn': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3418,9 +3279,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale mo.
- */
+ /// Extended set of localized date/time patterns for locale mo.
'mo': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3468,9 +3327,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale mr.
- */
+ /// Extended set of localized date/time patterns for locale mr.
'mr': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3518,9 +3375,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ms.
- */
+ /// Extended set of localized date/time patterns for locale ms.
'ms': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3568,9 +3423,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale mt.
- */
+ /// Extended set of localized date/time patterns for locale mt.
'mt': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3618,9 +3471,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale my.
- */
+ /// Extended set of localized date/time patterns for locale my.
'my': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3668,9 +3519,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale nb.
- */
+ /// Extended set of localized date/time patterns for locale nb.
'nb': const {
'd': 'd.', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3718,9 +3567,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ne.
- */
+ /// Extended set of localized date/time patterns for locale ne.
'ne': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3768,9 +3615,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale nl.
- */
+ /// Extended set of localized date/time patterns for locale nl.
'nl': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3818,9 +3663,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale no.
- */
+ /// Extended set of localized date/time patterns for locale no.
'no': const {
'd': 'd.', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3868,9 +3711,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale no_NO.
- */
+ /// Extended set of localized date/time patterns for locale no_NO.
'no_NO': const {
'd': 'd.', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -3918,9 +3759,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale or.
- */
+ /// Extended set of localized date/time patterns for locale or.
'or': const {
'd': 'd', // DAY
'E': 'EEE', // ABBR_WEEKDAY
@@ -3968,9 +3807,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale pa.
- */
+ /// Extended set of localized date/time patterns for locale pa.
'pa': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4018,9 +3855,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale pl.
- */
+ /// Extended set of localized date/time patterns for locale pl.
'pl': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4068,9 +3903,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale pt.
- */
+ /// Extended set of localized date/time patterns for locale pt.
'pt': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4118,9 +3951,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale pt_BR.
- */
+ /// Extended set of localized date/time patterns for locale pt_BR.
'pt_BR': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4168,9 +3999,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale pt_PT.
- */
+ /// Extended set of localized date/time patterns for locale pt_PT.
'pt_PT': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4218,9 +4047,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ro.
- */
+ /// Extended set of localized date/time patterns for locale ro.
'ro': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4268,9 +4095,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ru.
- */
+ /// Extended set of localized date/time patterns for locale ru.
'ru': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4318,9 +4143,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale sh.
- */
+ /// Extended set of localized date/time patterns for locale sh.
'sh': const {
'd': 'd', // DAY
'E': 'EEE', // ABBR_WEEKDAY
@@ -4368,9 +4191,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale si.
- */
+ /// Extended set of localized date/time patterns for locale si.
'si': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4418,9 +4239,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale sk.
- */
+ /// Extended set of localized date/time patterns for locale sk.
'sk': const {
'd': 'd.', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4468,9 +4287,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale sl.
- */
+ /// Extended set of localized date/time patterns for locale sl.
'sl': const {
'd': 'd.', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4518,9 +4335,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale sq.
- */
+ /// Extended set of localized date/time patterns for locale sq.
'sq': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4568,9 +4383,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale sr.
- */
+ /// Extended set of localized date/time patterns for locale sr.
'sr': const {
'd': 'd', // DAY
'E': 'EEE', // ABBR_WEEKDAY
@@ -4618,9 +4431,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale sr_Latn.
- */
+ /// Extended set of localized date/time patterns for locale sr_Latn.
'sr_Latn': const {
'd': 'd', // DAY
'E': 'EEE', // ABBR_WEEKDAY
@@ -4668,9 +4479,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale sv.
- */
+ /// Extended set of localized date/time patterns for locale sv.
'sv': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4718,9 +4527,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale sw.
- */
+ /// Extended set of localized date/time patterns for locale sw.
'sw': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4768,9 +4575,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ta.
- */
+ /// Extended set of localized date/time patterns for locale ta.
'ta': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4818,9 +4623,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale te.
- */
+ /// Extended set of localized date/time patterns for locale te.
'te': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4868,9 +4671,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale th.
- */
+ /// Extended set of localized date/time patterns for locale th.
'th': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4918,9 +4719,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale tl.
- */
+ /// Extended set of localized date/time patterns for locale tl.
'tl': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -4968,9 +4767,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale tr.
- */
+ /// Extended set of localized date/time patterns for locale tr.
'tr': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -5018,9 +4815,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale uk.
- */
+ /// Extended set of localized date/time patterns for locale uk.
'uk': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -5068,9 +4863,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale ur.
- */
+ /// Extended set of localized date/time patterns for locale ur.
'ur': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -5118,9 +4911,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale uz.
- */
+ /// Extended set of localized date/time patterns for locale uz.
'uz': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -5168,9 +4959,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale vi.
- */
+ /// Extended set of localized date/time patterns for locale vi.
'vi': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -5219,9 +5008,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale zh.
- */
+ /// Extended set of localized date/time patterns for locale zh.
'zh': const {
'd': 'd日', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -5269,9 +5056,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale zh_CN.
- */
+ /// Extended set of localized date/time patterns for locale zh_CN.
'zh_CN': const {
'd': 'd日', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -5319,9 +5104,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale zh_HK.
- */
+ /// Extended set of localized date/time patterns for locale zh_HK.
'zh_HK': const {
'd': 'd日', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -5369,9 +5152,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale zh_TW.
- */
+ /// Extended set of localized date/time patterns for locale zh_TW.
'zh_TW': const {
'd': 'd日', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -5419,9 +5200,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale zu.
- */
+ /// Extended set of localized date/time patterns for locale zu.
'zu': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
@@ -5469,9 +5248,7 @@
'ZZZZ': 'ZZZZ' // ABBR_UTC_TZ
},
- /**
- * Extended set of localized date/time patterns for locale en_ISO.
- */
+ /// Extended set of localized date/time patterns for locale en_ISO.
'en_ISO': const {
'd': 'd', // DAY
'E': 'ccc', // ABBR_WEEKDAY
diff --git a/lib/extract_messages.dart b/lib/extract_messages.dart
index 326c51c..a2a8809 100644
--- a/lib/extract_messages.dart
+++ b/lib/extract_messages.dart
@@ -2,23 +2,21 @@
// 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 is for use in extracting messages from a Dart program
- * using the Intl.message() mechanism and writing them to a file for
- * translation. This provides only the stub of a mechanism, because it
- * doesn't define how the file should be written. It provides an
- * [IntlMessage] class that holds the extracted data and [parseString]
- * and [parseFile] methods which
- * can extract messages that conform to the expected pattern:
- * (parameters) => Intl.message("Message $parameters", desc: ...);
- * It uses the analyzer package to do the parsing, so may
- * break if there are changes to the API that it provides.
- * An example can be found in test/message_extraction/extract_to_json.dart
- *
- * Note that this does not understand how to follow part directives, so it
- * has to explicitly be given all the files that it needs. A typical use case
- * is to run it on all .dart files in a directory.
- */
+/// This is for use in extracting messages from a Dart program
+/// using the Intl.message() mechanism and writing them to a file for
+/// translation. This provides only the stub of a mechanism, because it
+/// doesn't define how the file should be written. It provides an
+/// [IntlMessage] class that holds the extracted data and [parseString]
+/// and [parseFile] methods which
+/// can extract messages that conform to the expected pattern:
+/// (parameters) => Intl.message("Message $parameters", desc: ...);
+/// It uses the analyzer package to do the parsing, so may
+/// break if there are changes to the API that it provides.
+/// An example can be found in test/message_extraction/extract_to_json.dart
+///
+/// Note that this does not understand how to follow part directives, so it
+/// has to explicitly be given all the files that it needs. A typical use case
+/// is to run it on all .dart files in a directory.
library extract_messages;
import 'dart:io';
@@ -26,41 +24,32 @@
import 'package:analyzer/analyzer.dart';
import 'package:intl/src/intl_message.dart';
-/**
- * If this is true, print warnings for skipped messages. Otherwise, warnings
- * are suppressed.
- */
+/// If this is true, print warnings for skipped messages. Otherwise, warnings
+/// are suppressed.
bool suppressWarnings = false;
-/**
- * If this is true, then treat all warnings as errors.
- */
+/// If this is true, then treat all warnings as errors.
bool warningsAreErrors = false;
-/**
- * This accumulates a list of all warnings/errors we have found. These are
- * saved as strings right now, so all that can really be done is print and
- * count them.
- */
+/// This accumulates a list of all warnings/errors we have found. These are
+/// saved as strings right now, so all that can really be done is print and
+/// count them.
List<String> warnings = [];
-/** Were there any warnings or errors in extracting messages. */
+/// Were there any warnings or errors in extracting messages.
bool get hasWarnings => warnings.isNotEmpty;
-/** Are plural and gender expressions required to be at the top level
- * of an expression, or are they allowed to be embedded in string literals.
- *
- * For example, the following expression
- * 'There are ${Intl.plural(...)} items'.
- * is legal if [allowEmbeddedPluralsAndGenders] is true, but illegal
- * if [allowEmbeddedPluralsAndGenders] is false.
- */
+/// Are plural and gender expressions required to be at the top level
+/// of an expression, or are they allowed to be embedded in string literals.
+///
+/// For example, the following expression
+/// 'There are ${Intl.plural(...)} items'.
+/// is legal if [allowEmbeddedPluralsAndGenders] is true, but illegal
+/// if [allowEmbeddedPluralsAndGenders] is false.
bool allowEmbeddedPluralsAndGenders = true;
-/**
- * Parse the source of the Dart program file [file] and return a Map from
- * message names to [IntlMessage] instances.
- */
+/// Parse the source of the Dart program file [file] and return a Map from
+/// message names to [IntlMessage] instances.
Map<String, MainMessage> parseFile(File file) {
try {
_root = parseDartFile(file.path);
@@ -75,18 +64,14 @@
return visitor.messages;
}
-/**
- * The root of the compilation unit, and the first node we visit. We hold
- * on to this for error reporting, as it can give us line numbers of other
- * nodes.
- */
+/// The root of the compilation unit, and the first node we visit. We hold
+/// on to this for error reporting, as it can give us line numbers of other
+/// nodes.
CompilationUnit _root;
-/**
- * An arbitrary string describing where the source code came from. Most
- * obviously, this could be a file path. We use this when reporting
- * invalid messages.
- */
+/// An arbitrary string describing where the source code came from. Most
+/// obviously, this could be a file path. We use this when reporting
+/// invalid messages.
String _origin;
String _reportErrorLocation(AstNode node) {
@@ -100,29 +85,23 @@
return result.toString();
}
-/**
- * This visits the program source nodes looking for Intl.message uses
- * that conform to its pattern and then creating the corresponding
- * IntlMessage objects. We have to find both the enclosing function, and
- * the Intl.message invocation.
- */
+/// This visits the program source nodes looking for Intl.message uses
+/// that conform to its pattern and then creating the corresponding
+/// IntlMessage objects. We have to find both the enclosing function, and
+/// the Intl.message invocation.
class MessageFindingVisitor extends GeneralizingAstVisitor {
MessageFindingVisitor();
- /**
- * Accumulates the messages we have found, keyed by name.
- */
+ /// Accumulates the messages we have found, keyed by name.
final Map<String, MainMessage> messages = new Map<String, MainMessage>();
- /**
- * We keep track of the data from the last MethodDeclaration,
- * FunctionDeclaration or FunctionExpression that we saw on the way down,
- * as that will be the nearest parent of the Intl.message invocation.
- */
+ /// We keep track of the data from the last MethodDeclaration,
+ /// FunctionDeclaration or FunctionExpression that we saw on the way down,
+ /// as that will be the nearest parent of the Intl.message invocation.
FormalParameterList parameters;
String name;
- /** Return true if [node] matches the pattern we expect for Intl.message() */
+ /// Return true if [node] matches the pattern we expect for Intl.message()
bool looksLikeIntlMessage(MethodInvocation node) {
const validNames = const ["message", "plural", "gender", "select"];
if (!validNames.contains(node.methodName.name)) return false;
@@ -146,10 +125,8 @@
}
}
- /**
- * Returns a String describing why the node is invalid, or null if no
- * reason is found, so it's presumed valid.
- */
+ /// Returns a String describing why the node is invalid, or null if no
+ /// reason is found, so it's presumed valid.
String checkValidity(MethodInvocation node) {
// The containing function cannot have named parameters.
if (parameters.parameters.any((each) => each.kind == ParameterKind.NAMED)) {
@@ -160,10 +137,8 @@
return instance.checkValidity(node, arguments, name, parameters);
}
- /**
- * Record the parameters of the function or method declaration we last
- * encountered before seeing the Intl.message call.
- */
+ /// Record the parameters of the function or method declaration we last
+ /// encountered before seeing the Intl.message call.
void visitMethodDeclaration(MethodDeclaration node) {
parameters = node.parameters;
if (parameters == null) {
@@ -173,10 +148,8 @@
super.visitMethodDeclaration(node);
}
- /**
- * Record the parameters of the function or method declaration we last
- * encountered before seeing the Intl.message call.
- */
+ /// Record the parameters of the function or method declaration we last
+ /// encountered before seeing the Intl.message call.
void visitFunctionDeclaration(FunctionDeclaration node) {
parameters = node.functionExpression.parameters;
if (parameters == null) {
@@ -186,24 +159,20 @@
super.visitFunctionDeclaration(node);
}
- /**
- * Examine method invocations to see if they look like calls to Intl.message.
- * If we've found one, stop recursing. This is important because we can have
- * Intl.message(...Intl.plural...) and we don't want to treat the inner
- * plural as if it was an outermost message.
- */
+ /// Examine method invocations to see if they look like calls to Intl.message.
+ /// If we've found one, stop recursing. This is important because we can have
+ /// Intl.message(...Intl.plural...) and we don't want to treat the inner
+ /// plural as if it was an outermost message.
void visitMethodInvocation(MethodInvocation node) {
if (!addIntlMessage(node)) {
super.visitMethodInvocation(node);
}
}
- /**
- * Check that the node looks like an Intl.message invocation, and create
- * the [IntlMessage] object from it and store it in [messages]. Return true
- * if we successfully extracted a message and should stop looking. Return
- * false if we didn't, so should continue recursing.
- */
+ /// Check that the node looks like an Intl.message invocation, and create
+ /// the [IntlMessage] object from it and store it in [messages]. Return true
+ /// if we successfully extracted a message and should stop looking. Return
+ /// false if we didn't, so should continue recursing.
bool addIntlMessage(MethodInvocation node) {
if (!looksLikeIntlMessage(node)) return false;
var reason = checkValidity(node);
@@ -228,13 +197,11 @@
return true;
}
- /**
- * Create a MainMessage from [node] using the name and
- * parameters of the last function/method declaration we encountered,
- * and the values we get by calling [extract]. We set those values
- * by calling [setAttribute]. This is the common parts between
- * [messageFromIntlMessageCall] and [messageFromDirectPluralOrGenderCall].
- */
+ /// Create a MainMessage from [node] using the name and
+ /// parameters of the last function/method declaration we encountered,
+ /// and the values we get by calling [extract]. We set those values
+ /// by calling [setAttribute]. This is the common parts between
+ /// [messageFromIntlMessageCall] and [messageFromDirectPluralOrGenderCall].
MainMessage _messageFromNode(
MethodInvocation node, Function extract, Function setAttribute) {
var message = new MainMessage();
@@ -258,11 +225,9 @@
return message;
}
- /**
- * Create a MainMessage from [node] using the name and
- * parameters of the last function/method declaration we encountered
- * and the parameters to the Intl.message call.
- */
+ /// Create a MainMessage from [node] using the name and
+ /// parameters of the last function/method declaration we encountered
+ /// and the parameters to the Intl.message call.
MainMessage messageFromIntlMessageCall(MethodInvocation node) {
MainMessage extractFromIntlCall(MainMessage message, List arguments) {
try {
@@ -296,11 +261,9 @@
return _messageFromNode(node, extractFromIntlCall, setValue);
}
- /**
- * Create a MainMessage from [node] using the name and
- * parameters of the last function/method declaration we encountered
- * and the parameters to the Intl.plural or Intl.gender call.
- */
+ /// Create a MainMessage from [node] using the name and
+ /// parameters of the last function/method declaration we encountered
+ /// and the parameters to the Intl.plural or Intl.gender call.
MainMessage messageFromDirectPluralOrGenderCall(MethodInvocation node) {
MainMessage extractFromPluralOrGender(MainMessage message, _) {
var visitor = new PluralAndGenderVisitor(message.messagePieces, message);
@@ -317,16 +280,14 @@
}
}
-/**
- * Given an interpolation, find all of its chunks, validate that they are only
- * simple variable substitutions or else Intl.plural/gender calls,
- * and keep track of the pieces of text so that other parts
- * of the program can deal with the simple string sections and the generated
- * parts separately. Note that this is a SimpleAstVisitor, so it only
- * traverses one level of children rather than automatically recursing. If we
- * find a plural or gender, which requires recursion, we do it with a separate
- * special-purpose visitor.
- */
+/// Given an interpolation, find all of its chunks, validate that they are only
+/// simple variable substitutions or else Intl.plural/gender calls,
+/// and keep track of the pieces of text so that other parts
+/// of the program can deal with the simple string sections and the generated
+/// parts separately. Note that this is a SimpleAstVisitor, so it only
+/// traverses one level of children rather than automatically recursing. If we
+/// find a plural or gender, which requires recursion, we do it with a separate
+/// special-purpose visitor.
class InterpolationVisitor extends SimpleAstVisitor {
final Message message;
@@ -387,25 +348,19 @@
List get arguments => message.arguments;
}
-/**
- * A visitor to extract information from Intl.plural/gender sends. Note that
- * this is a SimpleAstVisitor, so it doesn't automatically recurse. So this
- * needs to be called where we expect a plural or gender immediately below.
- */
+/// A visitor to extract information from Intl.plural/gender sends. Note that
+/// this is a SimpleAstVisitor, so it doesn't automatically recurse. So this
+/// needs to be called where we expect a plural or gender immediately below.
class PluralAndGenderVisitor extends SimpleAstVisitor {
- /**
- * A plural or gender always exists in the context of a parent message,
- * which could in turn also be a plural or gender.
- */
+ /// A plural or gender always exists in the context of a parent message,
+ /// which could in turn also be a plural or gender.
final ComplexMessage parent;
- /**
- * The pieces of the message. We are given an initial version of this
- * from our parent and we add to it as we find additional information.
- */
+ /// The pieces of the message. We are given an initial version of this
+ /// from our parent and we add to it as we find additional information.
List pieces;
- /** This will be set to true if we find a plural or gender. */
+ /// This will be set to true if we find a plural or gender.
bool foundPluralOrGender = false;
PluralAndGenderVisitor(this.pieces, this.parent) : super();
@@ -426,7 +381,7 @@
super.visitMethodInvocation(node);
}
- /** Return true if [node] matches the pattern for plural or gender message.*/
+ /// Return true if [node] matches the pattern for plural or gender message.
bool looksLikePluralOrGender(MethodInvocation node) {
if (!["plural", "gender", "select"].contains(node.methodName.name)) {
return false;
@@ -436,20 +391,16 @@
return target.token.toString() == "Intl";
}
- /**
- * Returns a String describing why the node is invalid, or null if no
- * reason is found, so it's presumed valid.
- */
+ /// Returns a String describing why the node is invalid, or null if no
+ /// reason is found, so it's presumed valid.
String checkValidity(MethodInvocation node) {
// TODO(alanknight): Add reasonable validity checks.
return null;
}
- /**
- * Create a MainMessage from [node] using the name and
- * parameters of the last function/method declaration we encountered
- * and the parameters to the Intl.message call.
- */
+ /// Create a MainMessage from [node] using the name and
+ /// parameters of the last function/method declaration we encountered
+ /// and the parameters to the Intl.message call.
Message messageFromMethodInvocation(MethodInvocation node) {
var message;
switch (node.methodName.name) {
@@ -502,18 +453,12 @@
}
}
-/**
- * Exception thrown when we cannot process a message properly.
- */
+/// Exception thrown when we cannot process a message properly.
class IntlMessageExtractionException implements Exception {
- /**
- * A message describing the error.
- */
+ /// A message describing the error.
final String message;
- /**
- * Creates a new exception with an optional error [message].
- */
+ /// Creates a new exception with an optional error [message].
const IntlMessageExtractionException([this.message = ""]);
String toString() => "IntlMessageExtractionException: $message";
diff --git a/lib/generate_localized.dart b/lib/generate_localized.dart
index 9bb4876..5dded05 100644
--- a/lib/generate_localized.dart
+++ b/lib/generate_localized.dart
@@ -2,15 +2,13 @@
// 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 provides utilities for generating localized versions of
- * messages. It does not stand alone, but expects to be given
- * TranslatedMessage objects and generate code for a particular locale
- * based on them.
- *
- * An example of usage can be found
- * in test/message_extract/generate_from_json.dart
- */
+/// This provides utilities for generating localized versions of
+/// messages. It does not stand alone, but expects to be given
+/// TranslatedMessage objects and generate code for a particular locale
+/// based on them.
+///
+/// An example of usage can be found
+/// in test/message_extract/generate_from_json.dart
library generate_localized;
import 'intl.dart';
@@ -18,74 +16,54 @@
import 'dart:io';
import 'package:path/path.dart' as path;
-/**
- * If the import path following package: is something else, modify the
- * [intlImportPath] variable to change the import directives in the generated
- * code.
- */
+/// If the import path following package: is something else, modify the
+/// [intlImportPath] variable to change the import directives in the generated
+/// code.
var intlImportPath = 'intl';
-/**
- * If the path to the generated files is something other than the current
- * directory, update the [generatedImportPath] variable to change the import
- * directives in the generated code.
- */
+/// If the path to the generated files is something other than the current
+/// directory, update the [generatedImportPath] variable to change the import
+/// directives in the generated code.
var generatedImportPath = '';
-/**
- * Given a base file, return the file prefixed with the path to import it.
- * By default, that is in the current directory, but if [generatedImportPath]
- * has been set, then use that as a prefix.
- */
+/// Given a base file, return the file prefixed with the path to import it.
+/// By default, that is in the current directory, but if [generatedImportPath]
+/// has been set, then use that as a prefix.
String importForGeneratedFile(String file) =>
generatedImportPath.isEmpty ? file : "$generatedImportPath/$file";
-/**
- * A list of all the locales for which we have translations. Code that does
- * the reading of translations should add to this.
- */
+/// A list of all the locales for which we have translations. Code that does
+/// the reading of translations should add to this.
List<String> allLocales = [];
-/**
- * If we have more than one set of messages to generate in a particular
- * directory we may want to prefix some to distinguish them.
- */
+/// If we have more than one set of messages to generate in a particular
+/// directory we may want to prefix some to distinguish them.
String generatedFilePrefix = '';
-/**
- * Should we use deferred loading for the generated libraries.
- */
+/// Should we use deferred loading for the generated libraries.
bool useDeferredLoading = true;
-/**
- * This represents a message and its translation. We assume that the translation
- * has some identifier that allows us to figure out the original message it
- * corresponds to, and that it may want to transform the translated text in
- * some way, e.g. to turn whatever format the translation uses for variables
- * into a Dart string interpolation. Specific translation
- * mechanisms are expected to subclass this.
- */
+/// This represents a message and its translation. We assume that the
+/// translation has some identifier that allows us to figure out the original
+/// message it corresponds to, and that it may want to transform the translated
+/// text in some way, e.g. to turn whatever format the translation uses for
+/// variables into a Dart string interpolation. Specific translation mechanisms
+/// are expected to subclass this.
abstract class TranslatedMessage {
- /**
- * The identifier for this message. In the simplest case, this is the name
- * parameter from the Intl.message call,
- * but it can be any identifier that this program and the output of the
- * translation can agree on as identifying a message.
- */
+ /// The identifier for this message. In the simplest case, this is the name
+ /// parameter from the Intl.message call,
+ /// but it can be any identifier that this program and the output of the
+ /// translation can agree on as identifying a message.
final String id;
- /** Our translated version of all the [originalMessages]. */
+ /// Our translated version of all the [originalMessages].
final Message translated;
- /**
- * The original messages that we are a translation of. There can
- * be more than one original message for the same translation.
- */
+ /// The original messages that we are a translation of. There can
+ /// be more than one original message for the same translation.
List<MainMessage> originalMessages;
- /**
- * For backward compatibility, we still have the originalMessage API.
- */
+ /// For backward compatibility, we still have the originalMessage API.
MainMessage get originalMessage => originalMessages.first;
set originalMessage(MainMessage m) => originalMessages = [m];
@@ -96,16 +74,12 @@
toString() => id.toString();
}
-/**
- * We can't use a hyphen in a Dart library name, so convert the locale
- * separator to an underscore.
- */
+/// We can't use a hyphen in a Dart library name, so convert the locale
+/// separator to an underscore.
String _libraryName(String x) => 'messages_' + x.replaceAll('-', '_');
-/**
- * Generate a file <[generated_file_prefix]>_messages_<[locale]>.dart
- * for the [translations] in [locale] and put it in [targetDir].
- */
+/// Generate a file <[generated_file_prefix]>_messages_<[locale]>.dart
+/// for the [translations] in [locale] and put it in [targetDir].
void generateIndividualMessageFile(String basicLocale,
Iterable<TranslatedMessage> translations, String targetDir) {
var result = new StringBuffer();
@@ -158,14 +132,13 @@
bool _hasArguments(MainMessage message) => message.arguments.length != 0;
-/**
- * Simple messages are printed directly in the map of message names to
- * functions as a call that returns a lambda. e.g.
- *
- * "foo" : simpleMessage("This is foo"),
- *
- * This is helpful for the compiler.
- **/
+/// Simple messages are printed directly in the map of message names to
+/// functions as a call that returns a lambda. e.g.
+///
+/// "foo" : simpleMessage("This is foo"),
+///
+/// This is helpful for the compiler.
+/// */
String _mapReference(MainMessage original, String locale) {
if (!_hasArguments(original)) {
// No parameters, can be printed simply.
@@ -176,18 +149,14 @@
}
}
-/**
- * This returns the mostly constant string used in
- * [generateIndividualMessageFile] for the beginning of the file,
- * parameterized by [locale].
- */
+/// This returns the mostly constant string used in
+/// [generateIndividualMessageFile] for the beginning of the file,
+/// parameterized by [locale].
String prologue(String locale) => """
-/**
- * DO NOT EDIT. This is code generated via package:intl/generate_localized.dart
- * This is a library that provides messages for a $locale locale. All the
- * messages from the main program should be duplicated here with the same
- * function name.
- */
+/// DO NOT EDIT. This is code generated via package:intl/generate_localized.dart
+/// This is a library that provides messages for a $locale locale. All the
+/// messages from the main program should be duplicated here with the same
+/// function name.
import 'package:$intlImportPath/intl.dart';
import 'package:$intlImportPath/message_lookup_by_library.dart';
@@ -199,10 +168,8 @@
get localeName => '$locale';
""";
-/**
- * This section generates the messages_all.dart file based on the list of
- * [allLocales].
- */
+/// This section generates the messages_all.dart file based on the list of
+/// [allLocales].
String generateMainImportFile() {
var output = new StringBuffer();
output.write(mainPrologue);
@@ -234,16 +201,12 @@
return output.toString();
}
-/**
- * Constant string used in [generateMainImportFile] for the beginning of the
- * file.
- */
+/// Constant string used in [generateMainImportFile] for the beginning of the
+/// file.
var mainPrologue = """
-/**
- * DO NOT EDIT. This is code generated via package:intl/generate_localized.dart
- * This is a library that looks up messages for specific locales by
- * delegating to the appropriate library.
- */
+/// DO NOT EDIT. This is code generated via package:intl/generate_localized.dart
+/// This is a library that looks up messages for specific locales by
+/// delegating to the appropriate library.
import 'dart:async';
import 'package:$intlImportPath/message_lookup_by_library.dart';
@@ -252,15 +215,13 @@
""";
-/**
- * Constant string used in [generateMainImportFile] as the end of the file.
- */
+/// Constant string used in [generateMainImportFile] as the end of the file.
const closing = """
default: return null;
}
}
-/** User programs should call this before using [localeName] for messages.*/
+/// User programs should call this before using [localeName] for messages.
Future initializeMessages(String localeName) {
initializeInternalMessageLookup(() => new CompositeMessageLookup());
var lib = _deferredLibraries[Intl.canonicalizedLocale(localeName)];
diff --git a/lib/intl.dart b/lib/intl.dart
index 0e131a9..459b4f8 100644
--- a/lib/intl.dart
+++ b/lib/intl.dart
@@ -2,22 +2,20 @@
// 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.
- *
- * This is part of the [intl package]
- * (https://pub.dartlang.org/packages/intl).
- *
- * For things that require locale or other data, there are multiple different
- * ways of making that data available, which may require importing different
- * libraries. See the class comments for more details.
- *
- * There is also a simple example application that can be found in the
- * [example/basic](https://github.com/dart-lang/intl/tree/master/example/basic)
- * directory.
- */
+/// 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.
+///
+/// This is part of the [intl package]
+/// (https://pub.dartlang.org/packages/intl).
+///
+/// For things that require locale or other data, there are multiple different
+/// ways of making that data available, which may require importing different
+/// libraries. See the class comments for more details.
+///
+/// There is also a simple example application that can be found in the
+/// [example/basic](https://github.com/dart-lang/intl/tree/master/example/basic)
+/// directory.
library intl;
import 'dart:async';
@@ -38,66 +36,60 @@
part 'src/intl/date_format_helpers.dart';
part 'src/intl/number_format.dart';
-/**
- * The Intl class provides a common entry point for internationalization
- * related tasks. An Intl instance can be created for a particular locale
- * and used to create a date format via `anIntl.date()`. Static methods
- * on this class are also used in message formatting.
- *
- * Examples:
- * today(date) => Intl.message(
- * "Today's date is $date",
- * name: 'today',
- * args: [date],
- * desc: 'Indicate the current date',
- * examples: const {'date' : 'June 8, 2012'});
- * print(today(new DateTime.now().toString());
- *
- * howManyPeople(numberOfPeople, place) => Intl.plural(
- * zero: 'I see no one at all',
- * one: 'I see one other person',
- * other: 'I see $numberOfPeople other people')} in $place.''',
- * name: 'msg',
- * args: [numberOfPeople, place],
- * desc: 'Description of how many people are seen in a place.',
- * examples: const {'numberOfPeople': 3, 'place': 'London'});
- *
- * Calling `howManyPeople(2, 'Athens');` would
- * produce "I see 2 other people in Athens." as output in the default locale.
- * If run in a different locale it would produce appropriately translated
- * output.
- *
- * For more detailed information on messages and localizing them see
- * the main [package documentation](https://pub.dartlang.org/packages/intl)
- *
- * You can set the default locale.
- * Intl.defaultLocale = "pt_BR";
- *
- * To temporarily use a locale other than the default, use the `withLocale`
- * function.
- * var todayString = new DateFormat("pt_BR").format(new DateTime.now());
- * print(withLocale("pt_BR", () => today(todayString));
- *
- * See `tests/message_format_test.dart` for more examples.
- */
+/// The Intl class provides a common entry point for internationalization
+/// related tasks. An Intl instance can be created for a particular locale
+/// and used to create a date format via `anIntl.date()`. Static methods
+/// on this class are also used in message formatting.
+///
+/// Examples:
+/// today(date) => Intl.message(
+/// "Today's date is $date",
+/// name: 'today',
+/// args: [date],
+/// desc: 'Indicate the current date',
+/// examples: const {'date' : 'June 8, 2012'});
+/// print(today(new DateTime.now().toString());
+///
+/// howManyPeople(numberOfPeople, place) => Intl.plural(
+/// zero: 'I see no one at all',
+/// one: 'I see one other person',
+/// other: 'I see $numberOfPeople other people')} in $place.''',
+/// name: 'msg',
+/// args: [numberOfPeople, place],
+/// desc: 'Description of how many people are seen in a place.',
+/// examples: const {'numberOfPeople': 3, 'place': 'London'});
+///
+/// Calling `howManyPeople(2, 'Athens');` would
+/// produce "I see 2 other people in Athens." as output in the default locale.
+/// If run in a different locale it would produce appropriately translated
+/// output.
+///
+/// For more detailed information on messages and localizing them see
+/// the main [package documentation](https://pub.dartlang.org/packages/intl)
+///
+/// You can set the default locale.
+/// Intl.defaultLocale = "pt_BR";
+///
+/// To temporarily use a locale other than the default, use the `withLocale`
+/// function.
+/// var todayString = new DateFormat("pt_BR").format(new DateTime.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).
- */
+ /// String indicating the locale code with which the message is to be
+ /// formatted (such as en-CA).
String _locale;
- /**
- * The default locale. This defaults to being set from systemLocale, but
- * can also be set explicitly, and will then apply to any new instances where
- * the locale isn't specified. Note that a locale parameter to
- * [Intl.withLocale]
- * will supercede this value while that operation is active. Using
- * [Intl.withLocale] may be preferable if you are using different locales
- * in the same application.
- */
+ /// The default locale. This defaults to being set from systemLocale, but
+ /// can also be set explicitly, and will then apply to any new instances where
+ /// the locale isn't specified. Note that a locale parameter to
+ /// [Intl.withLocale]
+ /// will supercede this value while that operation is active. Using
+ /// [Intl.withLocale] may be preferable if you are using different locales
+ /// in the same application.
static String get defaultLocale {
var zoneLocale = Zone.current[#Intl.locale];
return zoneLocale == null ? _defaultLocale : zoneLocale;
@@ -105,104 +97,95 @@
static set defaultLocale(String newLocale) => _defaultLocale = newLocale;
static String _defaultLocale;
- /**
- * The system's locale, as obtained from the window.navigator.language
- * or other operating system mechanism. Note that due to system limitations
- * this is not automatically set, and must be set by importing one of
- * intl_browser.dart or intl_standalone.dart and calling findSystemLocale().
- */
+ /// The system's locale, as obtained from the window.navigator.language
+ /// or other operating system mechanism. Note that due to system limitations
+ /// this is not automatically set, and must be set by importing one of
+ /// intl_browser.dart or intl_standalone.dart and calling findSystemLocale().
static String systemLocale = 'en_US';
- /**
- * Return a new date format using the specified [pattern].
- * If [desiredLocale] is not specified, then we default to [locale].
- */
+ /// Return a new date format using the specified [pattern].
+ /// If [desiredLocale] is not specified, then we default to [locale].
DateFormat date([String pattern, String desiredLocale]) {
var actualLocale = (desiredLocale == null) ? locale : desiredLocale;
return new DateFormat(pattern, actualLocale);
}
- /**
- * Constructor optionally [aLocale] 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/client
- * preferences).
- */
+ /// Constructor optionally [aLocale] 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/client
+ /// preferences).
Intl([String aLocale]) {
_locale = aLocale != null ? aLocale : getCurrentLocale();
}
- /**
- * Use this for a message that will be translated for different locales. The
- * expected usage is that this is inside an enclosing function that only
- * returns the value of this call and provides a scope for the variables that
- * will be substituted in the message.
- *
- * The [message_str] is the string to be translated, which may be interpolated
- * based on one or more variables. The [name] of the message must
- * match the enclosing function name. For methods, it can also be
- * className_methodName. So for a method hello in class Simple, the name
- * can be either "hello" or "Simple_hello". The name must also be globally
- * unique in the program, so the second form can make it easier to distinguish
- * messages with the same name but in different classes.
- * The [args] repeats the arguments of the enclosing
- * function, [desc] provides a description of usage,
- * [examples] is a Map of exmaples for each interpolated variable. For example
- * hello(yourName) => Intl.message(
- * "Hello, $yourName",
- * name: "hello",
- * args: [yourName],
- * desc: "Say hello",
- * examples = const {"yourName": "Sparky"}.
- * The source code will be processed via the analyzer to extract out the
- * message data, so only a subset of valid Dart code is accepted. In
- * particular, everything must be literal and cannot refer to variables
- * outside the scope of the enclosing function. The [examples] map must
- * be a valid const literal map. Similarly, the [desc] argument must
- * be a single, simple string. These two arguments will not be used at runtime
- * but will be extracted from
- * the source code and used as additional data for translators. For more
- * information see the "Messages" section of the main [package documentation]
- * (https://pub.dartlang.org/packages/intl).
- *
- * The [name] and [args] arguments are required, and are used at runtime
- * to look up the localized version and pass the appropriate arguments to it.
- * We may in the future modify the code during compilation to make manually
- * passing those arguments unnecessary.
- */
+ /// Use this for a message that will be translated for different locales. The
+ /// expected usage is that this is inside an enclosing function that only
+ /// returns the value of this call and provides a scope for the variables that
+ /// will be substituted in the message.
+ ///
+ /// The [message_str] is the string to be translated, which may be
+ /// interpolated based on one or more variables. The [name] of the message
+ /// must match the enclosing function name. For methods, it can also be
+ /// className_methodName. So for a method hello in class Simple, the name can
+ /// be either "hello" or "Simple_hello". The name must also be globally unique
+ /// in the program, so the second form can make it easier to distinguish
+ /// messages with the same name but in different classes.
+ ///
+ /// The [args] repeats the arguments of the enclosing
+ /// function, [desc] provides a description of usage,
+ /// [examples] is a Map of exmaples for each interpolated variable.
+ /// For example
+ ///
+ /// hello(yourName) => Intl.message(
+ /// "Hello, $yourName",
+ /// name: "hello",
+ /// args: [yourName],
+ /// desc: "Say hello",
+ /// examples = const {"yourName": "Sparky"}.
+ ///
+ /// The source code will be processed via the analyzer to extract out the
+ /// message data, so only a subset of valid Dart code is accepted. In
+ /// particular, everything must be literal and cannot refer to variables
+ /// outside the scope of the enclosing function. The [examples] map must be a
+ /// valid const literal map. Similarly, the [desc] argument must be a single,
+ /// simple string. These two arguments will not be used at runtime but will be
+ /// extracted from the source code and used as additional data for
+ /// translators. For more information see the "Messages" section of the main
+ /// [package documentation] (https://pub.dartlang.org/packages/intl).
+ ///
+ /// The [name] and [args] arguments are required, and are used at runtime
+ /// to look up the localized version and pass the appropriate arguments to it.
+ /// We may in the future modify the code during compilation to make manually
+ /// passing those arguments unnecessary.
static String message(String message_str, {String desc: '',
Map<String, String> examples: const {}, String locale, String name,
List<String> args, String meaning}) =>
_message(message_str, locale, name, args);
- /** Omit the compile-time only parameters so dart2js can see to drop them. */
+ /// Omit the compile-time only parameters so dart2js can see to drop them.
static _message(String message_str, String locale, String name, List args) {
return messageLookup.lookupMessage(message_str, locale, name, args);
}
- /**
- * Return the locale for this instance. If none was set, the locale will
- * be the default.
- */
+ /// Return the locale for this instance. If none was set, the locale will
+ /// be the default.
String get locale => _locale;
- /**
- * 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.
- *
- * There is a special case that if a locale named "fallback" is present
- * and has been initialized, this will return that name. This can be useful
- * for messages where you don't want to just use the text from the original
- * source code, but wish to have a universal fallback translation.
- *
- * Note that null is interpreted as meaning the default locale, so if
- * [newLocale] is null it will be returned.
- */
+ /// 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.
+ ///
+ /// There is a special case that if a locale named "fallback" is present
+ /// and has been initialized, this will return that name. This can be useful
+ /// for messages where you don't want to just use the text from the original
+ /// source code, but wish to have a universal fallback translation.
+ ///
+ /// Note that null is interpreted as meaning the default locale, so if
+ /// [newLocale] is null it will be returned.
static String verifiedLocale(String newLocale, Function localeExists,
{Function onFailure: _throwLocaleError}) {
// TODO(alanknight): Previously we kept a single verified locale on the Intl
@@ -226,26 +209,22 @@
return onFailure(newLocale);
}
- /**
- * The default action if a locale isn't found in verifiedLocale. Throw
- * an exception indicating the locale isn't correct.
- */
+ /// 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' */
+ /// 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 the name [aLocale] turned into xx_YY where it might possibly be
- * in the wrong case or with a hyphen instead of an underscore. If
- * [aLocale] is null, for example, if you tried to get it from IE,
- * return the current system locale.
- */
+ /// Return the name [aLocale] turned into xx_YY where it might possibly be
+ /// in the wrong case or with a hyphen instead of an underscore. If
+ /// [aLocale] is null, for example, if you tried to get it from IE,
+ /// return the current system locale.
static String canonicalizedLocale(String aLocale) {
// Locales of length < 5 are presumably two-letter forms, or else malformed.
// We return them unmodified and if correct they will be found.
@@ -264,12 +243,10 @@
return '${aLocale[0]}${aLocale[1]}_$region';
}
- /**
- * Format a message differently depending on [howMany]. Normally used
- * as part of an `Intl.message` text that is to be translated.
- * Selects the correct plural form from
- * the provided alternatives. The [other] named argument is mandatory.
- */
+ /// Format a message differently depending on [howMany]. Normally used
+ /// as part of an `Intl.message` text that is to be translated.
+ /// Selects the correct plural form from
+ /// the provided alternatives. The [other] named argument is mandatory.
static String plural(int howMany, {zero, one, two, few, many, other,
String desc, Map<String, String> examples, String locale, String name,
List<String> args, String meaning}) {
@@ -305,10 +282,8 @@
throw new ArgumentError("Invalid plural usage for $howMany");
}
- /**
- * Format a message differently depending on [targetGender]. Normally used as
- * part of an Intl.message message that is to be translated.
- */
+ /// Format a message differently depending on [targetGender]. Normally used as
+ /// part of an Intl.message message that is to be translated.
static String gender(String targetGender, {String male, String female,
String other, String desc, Map<String, String> examples, String locale,
String name, List<String> args, String meaning}) {
@@ -334,12 +309,10 @@
}
}
- /**
- * Format a message differently depending on [choice]. We look up the value
- * of [choice] in [cases] and return the result, or an empty string if
- * it is not found. Normally used as part
- * of an Intl.message message that is to be translated.
- */
+ /// Format a message differently depending on [choice]. We look up the value
+ /// of [choice] in [cases] and return the result, or an empty string if
+ /// it is not found. Normally used as part
+ /// of an Intl.message message that is to be translated.
static String select(String choice, Map<String, String> cases, {String desc,
Map<String, String> examples, String locale, String name,
List<String> args, String meaning}) {
@@ -358,41 +331,37 @@
return other;
}
- /**
- * Run [function] with the default locale set to [locale] and
- * return the result.
- *
- * This is run in a zone, so async operations invoked
- * from within [function] will still have the locale set.
- *
- * In simple usage [function] might be a single
- * `Intl.message()` call or number/date formatting operation. But it can
- * also be an arbitrary function that calls multiple Intl operations.
- *
- * For example
- *
- * Intl.withLocale("fr", () => new NumberFormat.format(123456));
- *
- * or
- *
- * hello(name) => Intl.message(
- * "Hello $name.",
- * name: 'hello',
- * args: [name],
- * desc: 'Say Hello');
- * Intl.withLocale("zh", new Timer(new Duration(milliseconds:10),
- * () => print(hello("World")));
- */
+ /// Run [function] with the default locale set to [locale] and
+ /// return the result.
+ ///
+ /// This is run in a zone, so async operations invoked
+ /// from within [function] will still have the locale set.
+ ///
+ /// In simple usage [function] might be a single
+ /// `Intl.message()` call or number/date formatting operation. But it can
+ /// also be an arbitrary function that calls multiple Intl operations.
+ ///
+ /// For example
+ ///
+ /// Intl.withLocale("fr", () => new NumberFormat.format(123456));
+ ///
+ /// or
+ ///
+ /// hello(name) => Intl.message(
+ /// "Hello $name.",
+ /// name: 'hello',
+ /// args: [name],
+ /// desc: 'Say Hello');
+ /// Intl.withLocale("zh", new Timer(new Duration(milliseconds:10),
+ /// () => print(hello("World")));
static withLocale(String locale, function()) {
var canonical = Intl.canonicalizedLocale(locale);
return runZoned(function, zoneValues: {#Intl.locale: canonical});
}
- /**
- * 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.
- */
+ /// 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;
diff --git a/lib/intl_browser.dart b/lib/intl_browser.dart
index 995b2c1..e38e9f0 100644
--- a/lib/intl_browser.dart
+++ b/lib/intl_browser.dart
@@ -2,12 +2,10 @@
// 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 provides facilities for Internationalization that are only available
- * when running in the web browser. You should import only one of this or
- * intl_standalone.dart. Right now the only thing provided here is the
- * ability to find the default locale from the browser.
- */
+/// This provides facilities for Internationalization that are only available
+/// when running in the web browser. You should import only one of this or
+/// intl_standalone.dart. Right now the only thing provided here is the
+/// ability to find the default locale from the browser.
library intl_browser;
@@ -20,11 +18,9 @@
// seems to be no graceful way to do this at all. Either mirror access on
// dart2js or the ability to do spawnUri in the browser would be promising
// as ways to get rid of this requirement.
-/**
- * Find the system locale, accessed as window.navigator.language, and
- * set it as the default for internationalization operations in the
- * [Intl.systemLocale] variable.
- */
+/// Find the system locale, accessed as window.navigator.language, and
+/// set it as the default for internationalization operations in the
+/// [Intl.systemLocale] variable.
Future<String> findSystemLocale() {
Intl.systemLocale = Intl.canonicalizedLocale(window.navigator.language);
return new Future.value(Intl.systemLocale);
diff --git a/lib/intl_standalone.dart b/lib/intl_standalone.dart
index c69378d..03bff78 100644
--- a/lib/intl_standalone.dart
+++ b/lib/intl_standalone.dart
@@ -2,12 +2,10 @@
// 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 provides facilities for Internationalization that are only available
- * when running standalone. You should import only one of this or
- * intl_browser.dart. Right now the only thing provided here is finding
- * the operating system locale.
- */
+/// This provides facilities for Internationalization that are only available
+/// when running standalone. You should import only one of this or
+/// intl_browser.dart. Right now the only thing provided here is finding
+/// the operating system locale.
library intl_standalone;
@@ -20,18 +18,16 @@
// seems to be no graceful way to do this at all. Either mirror access on
// dart2js or the ability to do spawnUri in the browser would be promising
// as ways to get rid of this requirement.
-/**
- * Find the system locale, accessed via the appropriate system APIs, and
- * set it as the default for internationalization operations in
- * the [Intl.systemLocale] variable. To find it, we
- * check the "LANG" environment variable on *nix, use the "systeminfo"
- * command on Windows, and on the Mac check the environment variable "LANG",
- * and if it's not found, use "defaults read -g AppleLocale". This
- * is not an ideal way of getting a single system locale, even if that
- * concept really made sense, but it's a reasonable first approximation that's
- * not too difficult to get. If it can't find the locale information, it will
- * not modify [Intl.systemLocale] and the Future will complete with null.
- */
+/// Find the system locale, accessed via the appropriate system APIs, and
+/// set it as the default for internationalization operations in
+/// the [Intl.systemLocale] variable. To find it, we
+/// check the "LANG" environment variable on *nix, use the "systeminfo"
+/// command on Windows, and on the Mac check the environment variable "LANG",
+/// and if it's not found, use "defaults read -g AppleLocale". This
+/// is not an ideal way of getting a single system locale, even if that
+/// concept really made sense, but it's a reasonable first approximation that's
+/// not too difficult to get. If it can't find the locale information, it will
+/// not modify [Intl.systemLocale] and the Future will complete with null.
Future<String> findSystemLocale() {
// On *nix systems we expect this is an environment variable, which is the
// easiest thing to check. On a Mac the environment variable may be present
@@ -46,20 +42,16 @@
return new Future.value();
}
-/**
- * Regular expression to match the expected output of reading the defaults
- * database for AppleLanguages on Mac systems.
- * e.g. {
- * en,
- * "pt-PT",
- * ...
- */
+/// Regular expression to match the expected output of reading the defaults
+/// database for AppleLanguages on Mac systems.
+/// e.g. {
+/// en,
+/// "pt-PT",
+/// ...
RegExp _appleDefaultsRegex = new RegExp(r'((\w\w)_\w+)');
-/**
- * Check to see if we have a "LANG" environment variable we can use and return
- * it if found. Otherwise return null;
- */
+/// Check to see if we have a "LANG" environment variable we can use and return
+/// it if found. Otherwise return null;
String _checkEnvironmentVariable() {
try {
return Platform.environment['LANG'];
@@ -67,21 +59,17 @@
return null;
}
-/**
- * Run the "defaults read -g AppleLocale" command and return the output in
- * a future.
- */
+/// Run the "defaults read -g AppleLocale" command and return the output in
+/// a future.
Future _getAppleDefaults() {
var p = Process.run('defaults', ['read', '-g', 'AppleLocale']);
var myResult = p.then((result) => _checkResult(result, _appleDefaultsRegex));
return myResult;
}
-/**
- * Given [result], find its text and extract the locale from it using
- * [regex], and set it as the system locale. If the process didn't run correctly
- * then don't set the variable and return a future that completes with null.
- */
+/// Given [result], find its text and extract the locale from it using [regex],
+/// and set it as the system locale. If the process didn't run correctly then
+/// don't set the variable and return a future that completes with null.
Future<String> _checkResult(ProcessResult result, RegExp regex) {
if (result.exitCode != 0) return new Future.value();
var match = regex.firstMatch(result.stdout);
@@ -91,9 +79,7 @@
return new Future.value(locale);
}
-/**
- * Set [Intl.systemLocale] to be the canonicalizedLocale of [aLocale].
- */
+/// Set [Intl.systemLocale] to be the canonicalizedLocale of [aLocale].
Future<String> _setLocale(aLocale) {
Intl.systemLocale = Intl.canonicalizedLocale(aLocale);
return new Future.value(Intl.systemLocale);
diff --git a/lib/message_lookup_by_library.dart b/lib/message_lookup_by_library.dart
index c6ca92e..3c714e7 100644
--- a/lib/message_lookup_by_library.dart
+++ b/lib/message_lookup_by_library.dart
@@ -2,36 +2,31 @@
// 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. This can have different
- * implementations based on the mechanism for finding the localized versions
- * of messages. This version expects them to be in a library named e.g.
- * 'messages_en_US'. The prefix is set in the "initializeMessages" call, which
- * must be made for a locale before any lookups can be done.
- *
- * See Intl class comment or `tests/message_format_test.dart` for more examples.
- */
+/// Message/plural format library with locale support. This can have different
+/// implementations based on the mechanism for finding the localized versions of
+/// messages. This version expects them to be in a library named e.g.
+/// 'messages_en_US'. The prefix is set in the "initializeMessages" call, which
+/// must be made for a locale before any lookups can be done.
+///
+/// See Intl class comment or `tests/message_format_test.dart` for more
+/// examples.
library message_lookup_by_library;
import 'intl.dart';
-/**
- * This is a message lookup mechanism that delegates to one of a collection
- * of individual [MessageLookupByLibrary] instances.
- */
+/// This is a message lookup mechanism that delegates to one of a collection
+/// of individual [MessageLookupByLibrary] instances.
class CompositeMessageLookup {
- /** A map from locale names to the corresponding lookups. */
+ /// A map from locale names to the corresponding lookups.
Map<String, MessageLookupByLibrary> availableMessages = new Map();
- /** Return true if we have a message lookup for [localeName]. */
+ /// Return true if we have a message lookup for [localeName].
bool localeExists(localeName) => availableMessages.containsKey(localeName);
- /**
- * Look up the message with the given [name] and [locale] and return
- * the translated version with the values in [args] interpolated.
- * If nothing is found, return [message_str]. The [desc] and [examples]
- * parameters are ignored
- */
+ /// Look up the message with the given [name] and [locale] and return
+ /// the translated version with the values in [args] interpolated.
+ /// If nothing is found, return [message_str]. The [desc] and [examples]
+ /// parameters are ignored
String lookupMessage(String message_str, String locale,
String name, List args) {
var actualLocale = (locale == null) ? Intl.getCurrentLocale() : locale;
@@ -45,11 +40,9 @@
lookupMessage(message_str, locale, name, args);
}
- /**
- * If we do not already have a locale for [localeName] then
- * [findLocale] will be called and the result stored as the lookup
- * mechanism for that locale.
- */
+ /// If we do not already have a locale for [localeName] then
+ /// [findLocale] will be called and the result stored as the lookup
+ /// mechanism for that locale.
addLocale(String localeName, Function findLocale) {
if (localeExists(localeName)) return;
var canonical = Intl.canonicalizedLocale(localeName);
@@ -61,57 +54,49 @@
}
}
-/**
- * This provides an abstract class for messages looked up in generated code.
- * Each locale will have a separate subclass of this class with its set of
- * messages. See generate_localized.dart.
- */
+/// This provides an abstract class for messages looked up in generated code.
+/// Each locale will have a separate subclass of this class with its set of
+/// messages. See generate_localized.dart.
abstract class MessageLookupByLibrary {
- /**
- * Return the localized version of a message. We are passed the original
- * version of the message, which consists of a
- * [message_str] that will be translated, and which may be interpolated
- * based on one or more variables, a [desc] providing a description of usage
- * for the [message_str], and a map of [examples] for each data element to be
- * substituted into the message.
- *
- * For example, if message="Hello, $name", then
- * examples = {'name': 'Sparky'}. If not using the user's default locale, or
- * if the locale is not easily detectable, explicitly pass [locale].
- *
- * The values of [desc] and [examples] are not used at run-time but are only
- * made available to the translators, so they MUST be simple Strings available
- * at compile time: no String interpolation or concatenation.
- * The expected usage of this is inside a function that takes as parameters
- * the variables used in the interpolated string.
- *
- * Ultimately, the information about the enclosing function and its arguments
- * will be extracted automatically but for the time being it must be passed
- * explicitly in the [name] and [args] arguments.
- */
+ /// Return the localized version of a message. We are passed the original
+ /// version of the message, which consists of a
+ /// [message_str] that will be translated, and which may be interpolated
+ /// based on one or more variables, a [desc] providing a description of usage
+ /// for the [message_str], and a map of [examples] for each data element to be
+ /// substituted into the message.
+ ///
+ /// For example, if message="Hello, $name", then
+ /// examples = {'name': 'Sparky'}. If not using the user's default locale, or
+ /// if the locale is not easily detectable, explicitly pass [locale].
+ ///
+ /// The values of [desc] and [examples] are not used at run-time but are only
+ /// made available to the translators, so they MUST be simple Strings
+ /// available at compile time: no String interpolation or concatenation. The
+ /// expected usage of this is inside a function that takes as parameters the
+ /// variables used in the interpolated string.
+ ///
+ /// Ultimately, the information about the enclosing function and its arguments
+ /// will be extracted automatically but for the time being it must be passed
+ /// explicitly in the [name] and [args] arguments.
String lookupMessage(String message_str, String locale, String name, List args) {
if (name == null) return message_str;
var function = this[name];
return function == null ? message_str : Function.apply(function, args);
}
- /** Return our message with the given name */
+ /// Return our message with the given name
operator [](String messageName) => messages[messageName];
- /**
- * Subclasses should override this to return a list of their message
- * functions.
- */
+ /// Subclasses should override this to return a list of their message
+ /// functions.
Map<String, Function> get messages;
- /** Subclasses should override this to return their locale, e.g. 'en_US' */
+ /// Subclasses should override this to return their locale, e.g. 'en_US'
String get localeName;
toString() => localeName;
- /**
- * Return a function that returns the given string.
- * An optimization for dart2js, used from the generated code.
- */
+ /// Return a function that returns the given string.
+ /// An optimization for dart2js, used from the generated code.
static simpleMessage(translatedString) => () => translatedString;
}
diff --git a/lib/number_symbols.dart b/lib/number_symbols.dart
index 3eece39..c741171 100644
--- a/lib/number_symbols.dart
+++ b/lib/number_symbols.dart
@@ -3,12 +3,10 @@
// BSD-style license that can be found in the LICENSE file.
library number_symbols;
-/**
- * This holds onto information about how a particular locale formats numbers. It
- * contains strings for things like the decimal separator, digit to use for "0"
- * and infinity. We expect the data for instances to be generated out of ICU
- * or a similar reference source.
- */
+/// This holds onto information about how a particular locale formats
+/// numbers. It contains strings for things like the decimal separator, digit to
+/// use for "0" and infinity. We expect the data for instances to be generated
+/// out of ICU or a similar reference source.
class NumberSymbols {
final String NAME;
final String DECIMAL_SEP,
diff --git a/lib/src/data/dates/locale_list.dart b/lib/src/data/dates/locale_list.dart
index 4f953ef..061c097 100644
--- a/lib/src/data/dates/locale_list.dart
+++ b/lib/src/data/dates/locale_list.dart
@@ -110,4 +110,4 @@
"zh_CN",
"zh_HK",
"zh_TW",
- "zu"];
\ No newline at end of file
+ "zu"];
diff --git a/lib/src/date_format_internal.dart b/lib/src/date_format_internal.dart
index ddb7aad..e9d2531 100644
--- a/lib/src/date_format_internal.dart
+++ b/lib/src/date_format_internal.dart
@@ -2,15 +2,13 @@
// 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 contains internal implementation details of the date formatting code
- * which are exposed as public functions because they must be called by other
- * libraries in order to configure the source for the locale data. We don't want
- * them exposed as public API functions in the date formatting library, so they
- * are put in a separate library here. These are for internal use only. User
- * code should import one of the `date_symbol_data...` libraries and call the
- * `initializeDateFormatting` method exposed there.
- */
+/// This contains internal implementation details of the date formatting code
+/// which are exposed as public functions because they must be called by other
+/// libraries in order to configure the source for the locale data. We don't
+/// want them exposed as public API functions in the date formatting library, so
+/// they are put in a separate library here. These are for internal use
+/// only. User code should import one of the `date_symbol_data...` libraries and
+/// call the `initializeDateFormatting` method exposed there.
library date_format_internal;
@@ -18,44 +16,36 @@
import 'intl_helpers.dart';
import '../date_symbols.dart';
-/**
- * This holds the symbols to be used for date/time formatting, indexed
- * by locale. Note that it will be set differently during initialization,
- * depending on what implementation we are using. By default, it is initialized
- * to an instance of UninitializedLocaleData, so any attempt to use it will
- * result in an informative error message.
- */
+/// This holds the symbols to be used for date/time formatting, indexed
+/// by locale. Note that it will be set differently during initialization,
+/// depending on what implementation we are using. By default, it is initialized
+/// to an instance of UninitializedLocaleData, so any attempt to use it will
+/// result in an informative error message.
var dateTimeSymbols = new UninitializedLocaleData(
'initializeDateFormatting(<locale>)', en_USSymbols);
-/**
- * This holds the patterns used for date/time formatting, indexed
- * by locale. Note that it will be set differently during initialization,
- * depending on what implementation we are using. By default, it is initialized
- * to an instance of UninitializedLocaleData, so any attempt to use it will
- * result in an informative error message.
- */
+/// This holds the patterns used for date/time formatting, indexed
+/// by locale. Note that it will be set differently during initialization,
+/// depending on what implementation we are using. By default, it is initialized
+/// to an instance of UninitializedLocaleData, so any attempt to use it will
+/// result in an informative error message.
var dateTimePatterns = new UninitializedLocaleData(
'initializeDateFormatting(<locale>)', en_USPatterns);
-/**
- * Initialize the symbols dictionary. This should be passed a function that
- * creates and returns the symbol data. We take a function so that if
- * initializing the data is an expensive operation it need only be done once,
- * no matter how many times this method is called.
- */
+/// Initialize the symbols dictionary. This should be passed a function that
+/// creates and returns the symbol data. We take a function so that if
+/// initializing the data is an expensive operation it need only be done once,
+/// no matter how many times this method is called.
void initializeDateSymbols(Function symbols) {
if (dateTimeSymbols is UninitializedLocaleData) {
dateTimeSymbols = symbols();
}
}
-/**
- * Initialize the patterns dictionary. This should be passed a function that
- * creates and returns the pattern data. We take a function so that if
- * initializing the data is an expensive operation it need only be done once,
- * no matter how many times this method is called.
- */
+/// Initialize the patterns dictionary. This should be passed a function that
+/// creates and returns the pattern data. We take a function so that if
+/// initializing the data is an expensive operation it need only be done once,
+/// no matter how many times this method is called.
void initializeDatePatterns(Function patterns) {
if (dateTimePatterns is UninitializedLocaleData) {
dateTimePatterns = patterns();
diff --git a/lib/src/file_data_reader.dart b/lib/src/file_data_reader.dart
index 61c42e2..8e152f3 100644
--- a/lib/src/file_data_reader.dart
+++ b/lib/src/file_data_reader.dart
@@ -2,10 +2,8 @@
// 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 contains a reader that accesses data from local files, so it can't
- * be run in the browser.
- */
+/// This contains a reader that accesses data from local files, so it can't
+/// be run in the browser.
library file_data_reader;
diff --git a/lib/src/http_request_data_reader.dart b/lib/src/http_request_data_reader.dart
index cbe214d..7b0407e 100644
--- a/lib/src/http_request_data_reader.dart
+++ b/lib/src/http_request_data_reader.dart
@@ -2,10 +2,8 @@
// 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 contains a reader that accesses data using the HttpRequest
- * facility, and thus works only in the web browser.
- */
+/// This contains a reader that accesses data using the HttpRequest
+/// facility, and thus works only in the web browser.
library http_request_data_reader;
@@ -15,7 +13,7 @@
class HttpRequestDataReader implements LocaleDataReader {
- /** The base url from which we read the data. */
+ /// The base url from which we read the data.
String url;
HttpRequestDataReader(this.url);
diff --git a/lib/src/icu_parser.dart b/lib/src/icu_parser.dart
index 15c47b4..8603a3b 100644
--- a/lib/src/icu_parser.dart
+++ b/lib/src/icu_parser.dart
@@ -2,21 +2,17 @@
// 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.
-/**
- * Contains a parser for ICU format plural/gender/select format for localized
- * messages. See extract_to_arb.dart and make_hardcoded_translation.dart.
- */
+/// Contains a parser for ICU format plural/gender/select format for localized
+/// messages. See extract_to_arb.dart and make_hardcoded_translation.dart.
library icu_parser;
import 'package:intl/src/intl_message.dart';
import 'package:petitparser/petitparser.dart';
-/**
- * This defines a grammar for ICU MessageFormat syntax. Usage is
- * new IcuParser.message.parse(<string>).value;
- * The "parse" method will return a Success or Failure object which responds
- * to "value".
- */
+/// This defines a grammar for ICU MessageFormat syntax. Usage is
+/// new IcuParser.message.parse(<string>).value;
+/// The "parse" method will return a Success or Failure object which responds
+/// to "value".
class IcuParser {
get openCurly => char("{");
@@ -36,10 +32,8 @@
get id => (letter() & (word() | char("_")).star()).flatten().trim();
get comma => char(",").trim();
- /**
- * Given a list of possible keywords, return a rule that accepts any of them.
- * e.g., given ["male", "female", "other"], accept any of them.
- */
+ /// Given a list of possible keywords, return a rule that accepts any of them.
+ /// e.g., given ["male", "female", "other"], accept any of them.
asKeywords(list) => list.map(string).reduce((a, b) => a | b).flatten().trim();
get pluralKeyword => asKeywords(
@@ -83,17 +77,13 @@
get parameter => (openCurly & id & closeCurly)
.map((param) => new VariableSubstitution.named(param[1], null));
- /**
- * The primary entry point for parsing. Accepts a string and produces
- * a parsed representation of it as a Message.
- */
+ /// The primary entry point for parsing. Accepts a string and produces
+ /// a parsed representation of it as a Message.
get message => (pluralOrGenderOrSelect | empty)
.map((chunk) => Message.from(chunk, null));
- /**
- * Represents an ordinary message, i.e. not a plural/gender/select, although
- * it may have parameters.
- */
+ /// Represents an ordinary message, i.e. not a plural/gender/select, although
+ /// it may have parameters.
get nonIcuMessage =>
(simpleText | empty).map((chunk) => Message.from(chunk, null));
diff --git a/lib/src/intl/bidi_formatter.dart b/lib/src/intl/bidi_formatter.dart
index 9f9495c..87f955a 100644
--- a/lib/src/intl/bidi_formatter.dart
+++ b/lib/src/intl/bidi_formatter.dart
@@ -4,73 +4,67 @@
part of intl;
-/**
- * Bidi stands for Bi-directional text.
- * According to [Wikipedia](http://en.wikipedia.org/wiki/Bi-directional_text):
- * Bi-directional text is text containing text in both text directionalities,
- * both right-to-left (RTL) and left-to-right (LTR). It generally involves text
- * containing different types of alphabets, but may also refer to boustrophedon,
- * which is changing text directionality in each row.
- *
- * Utility class for formatting display text in a potentially
- * opposite-directionality context without garbling layout issues.
- * Mostly a very "slimmed-down" and dart-ified port of the Closure Birectional
- * formatting libary. If there is a utility in the Closure library (or ICU, or
- * elsewhere) that you would like this formatter to make available, please
- * contact the Dart team.
- *
- * Provides the following functionality:
- *
- * 1. *BiDi Wrapping*
- * When text in one language is mixed into a document in another, opposite-
- * directionality language, e.g. when an English business name is embedded in a
- * Hebrew web page, both the inserted string and the text following it may be
- * displayed incorrectly unless the inserted string is explicitly separated
- * from the surrounding text in a "wrapper" that declares its directionality at
- * the start and then resets it back at the end. This wrapping can be done in
- * HTML mark-up (e.g. a 'span dir=rtl' tag) or - only in contexts where mark-up
- * can not be used - in Unicode BiDi formatting codes (LRE|RLE and PDF).
- * Providing such wrapping services is the basic purpose of the BiDi formatter.
- *
- * 2. *Directionality estimation*
- * How does one know whether a string about to be inserted into surrounding
- * text has the same directionality? Well, in many cases, one knows that this
- * must be the case when writing the code doing the insertion, e.g. when a
- * localized message is inserted into a localized page. In such cases there is
- * no need to involve the BiDi formatter at all. In the remaining cases, e.g.
- * when the string is user-entered or comes from a database, the language of
- * the string (and thus its directionality) is not known a priori, and must be
- * estimated at run-time. The BiDi formatter does this automatically.
- *
- * 3. *Escaping*
- * When wrapping plain text - i.e. text that is not already HTML or HTML-
- * escaped - in HTML mark-up, the text must first be HTML-escaped to prevent XSS
- * attacks and other nasty business. This of course is always true, but the
- * escaping cannot be done after the string has already been wrapped in
- * mark-up, so the BiDi formatter also serves as a last chance and includes
- * escaping services.
- *
- * Thus, in a single call, the formatter will escape the input string as
- * specified, determine its directionality, and wrap it as necessary. It is
- * then up to the caller to insert the return value in the output.
- */
+/// Bidi stands for Bi-directional text. According to
+/// [Wikipedia](http://en.wikipedia.org/wiki/Bi-directional_text):
+/// Bi-directional text is text containing text in both text directionalities,
+/// both right-to-left (RTL) and left-to-right (LTR). It generally involves text
+/// containing different types of alphabets, but may also refer to
+/// boustrophedon, which is changing text directionality in each row.
+///
+/// Utility class for formatting display text in a potentially
+/// opposite-directionality context without garbling layout issues. Mostly a
+/// very "slimmed-down" and dart-ified port of the Closure Birectional
+/// formatting libary. If there is a utility in the Closure library (or ICU, or
+/// elsewhere) that you would like this formatter to make available, please
+/// contact the Dart team.
+///
+/// Provides the following functionality:
+///
+/// 1. *BiDi Wrapping*
+/// When text in one language is mixed into a document in another, opposite-
+/// directionality language, e.g. when an English business name is embedded in a
+/// Hebrew web page, both the inserted string and the text following it may be
+/// displayed incorrectly unless the inserted string is explicitly separated
+/// from the surrounding text in a "wrapper" that declares its directionality at
+/// the start and then resets it back at the end. This wrapping can be done in
+/// HTML mark-up (e.g. a 'span dir=rtl' tag) or - only in contexts where mark-up
+/// can not be used - in Unicode BiDi formatting codes (LRE|RLE and PDF).
+/// Providing such wrapping services is the basic purpose of the BiDi formatter.
+///
+/// 2. *Directionality estimation*
+/// How does one know whether a string about to be inserted into surrounding
+/// text has the same directionality? Well, in many cases, one knows that this
+/// must be the case when writing the code doing the insertion, e.g. when a
+/// localized message is inserted into a localized page. In such cases there is
+/// no need to involve the BiDi formatter at all. In the remaining cases, e.g.
+/// when the string is user-entered or comes from a database, the language of
+/// the string (and thus its directionality) is not known a priori, and must be
+/// estimated at run-time. The BiDi formatter does this automatically.
+///
+/// 3. *Escaping*
+/// When wrapping plain text - i.e. text that is not already HTML or HTML-
+/// escaped - in HTML mark-up, the text must first be HTML-escaped to prevent
+/// XSS attacks and other nasty business. This of course is always true, but the
+/// escaping cannot be done after the string has already been wrapped in
+/// mark-up, so the BiDi formatter also serves as a last chance and includes
+/// escaping services.
+///
+/// Thus, in a single call, the formatter will escape the input string as
+/// specified, determine its directionality, and wrap it as necessary. It is
+/// then up to the caller to insert the return value in the output.
class BidiFormatter {
- /** The direction of the surrounding text (the context). */
+ /// The direction of the surrounding text (the context).
TextDirection contextDirection;
- /**
- * Indicates if we should always wrap the formatted text in a <span<,.
- */
+ /// Indicates if we should always wrap the formatted text in a <span<,.
bool _alwaysSpan;
- /**
- * Create a formatting object with a direction. If [alwaysSpan] is true we
- * should always use a `span` tag, even when the input directionality is
- * neutral or matches the context, so that the DOM structure of the output
- * does not depend on the combination of directionalities.
- */
+ /// Create a formatting object with a direction. If [alwaysSpan] is true we
+ /// should always use a `span` tag, even when the input directionality is
+ /// neutral or matches the context, so that the DOM structure of the output
+ /// does not depend on the combination of directionalities.
BidiFormatter.LTR([alwaysSpan = false])
: contextDirection = TextDirection.LTR,
_alwaysSpan = alwaysSpan;
@@ -81,25 +75,24 @@
: contextDirection = TextDirection.UNKNOWN,
_alwaysSpan = alwaysSpan;
- /** Is true if the known context direction for this formatter is RTL. */
+ /// Is true if the known context direction for this formatter is RTL.
bool get isRTL => contextDirection == TextDirection.RTL;
- /**
- * Formats a string of a given (or estimated, if not provided)
- * [direction] for use in HTML output of the context directionality, so
- * an opposite-directionality string is neither garbled nor garbles what
- * follows it.
- * If the input string's directionality doesn't match the context
- * directionality, we wrap it with a `span` tag and add a `dir` attribute
- * (either "dir=rtl" or "dir=ltr").
- * If alwaysSpan was true when constructing the formatter, the input is always
- * wrapped with `span` tag, skipping the dir attribute when it's not needed.
- *
- * If [resetDir] is true and the overall directionality or the exit
- * directionality of [text] is opposite to the context directionality,
- * a trailing unicode BiDi mark matching the context directionality is
- * appended (LRM or RLM). If [isHtml] is false, we HTML-escape the [text].
- */
+ /// Formats a string of a given (or estimated, if not provided) [direction]
+ /// for use in HTML output of the context directionality, so an
+ /// opposite-directionality string is neither garbled nor garbles what follows
+ /// it.
+ ///
+ ///If the input string's directionality doesn't match the context
+ /// directionality, we wrap it with a `span` tag and add a `dir` attribute
+ /// (either "dir=rtl" or "dir=ltr"). If alwaysSpan was true when constructing
+ /// the formatter, the input is always wrapped with `span` tag, skipping the
+ /// dir attribute when it's not needed.
+ ///
+ /// If [resetDir] is true and the overall directionality or the exit
+ /// directionality of [text] is opposite to the context directionality,
+ /// a trailing unicode BiDi mark matching the context directionality is
+ /// appended (LRM or RLM). If [isHtml] is false, we HTML-escape the [text].
String wrapWithSpan(String text,
{bool isHtml: false, bool resetDir: true, TextDirection direction}) {
if (direction == null) direction = estimateDirection(text, isHtml: isHtml);
@@ -118,25 +111,23 @@
return result + (resetDir ? _resetDir(text, direction, isHtml) : '');
}
- /**
- * Format [text] of a known (if specified) or estimated [direction] for use
- * in *plain-text* output of the context directionality, so an
- * opposite-directionality text is neither garbled nor garbles what follows
- * it. Unlike wrapWithSpan, this makes use of unicode BiDi formatting
- * characters instead of spans for wrapping. The returned string would be
- * RLE+text+PDF for RTL text, or LRE+text+PDF for LTR text.
- *
- * If [resetDir] is true, and if the overall directionality or the exit
- * directionality of text are opposite to the context directionality,
- * a trailing unicode BiDi mark matching the context directionality is
- * appended (LRM or RLM).
- *
- * In HTML, the *only* valid use of this function is inside of elements that
- * do not allow markup, e.g. an 'option' tag.
- * This function does *not* do HTML-escaping regardless of the value of
- * [isHtml]. [isHtml] is used to designate if the text contains HTML (escaped
- * or unescaped).
- */
+ /// Format [text] of a known (if specified) or estimated [direction] for use
+ /// in *plain-text* output of the context directionality, so an
+ /// opposite-directionality text is neither garbled nor garbles what follows
+ /// it. Unlike wrapWithSpan, this makes use of unicode BiDi formatting
+ /// characters instead of spans for wrapping. The returned string would be
+ /// RLE+text+PDF for RTL text, or LRE+text+PDF for LTR text.
+ ///
+ /// If [resetDir] is true, and if the overall directionality or the exit
+ /// directionality of text are opposite to the context directionality,
+ /// a trailing unicode BiDi mark matching the context directionality is
+ /// appended (LRM or RLM).
+ ///
+ /// In HTML, the *only* valid use of this function is inside of elements that
+ /// do not allow markup, e.g. an 'option' tag.
+ /// This function does *not* do HTML-escaping regardless of the value of
+ /// [isHtml]. [isHtml] is used to designate if the text contains HTML (escaped
+ /// or unescaped).
String wrapWithUnicode(String text,
{bool isHtml: false, bool resetDir: true, TextDirection direction}) {
if (direction == null) direction = estimateDirection(text, isHtml: isHtml);
@@ -148,24 +139,20 @@
return result + (resetDir ? _resetDir(text, direction, isHtml) : '');
}
- /**
- * Estimates the directionality of [text] using the best known
- * general-purpose method (using relative word counts). A
- * TextDirection.UNKNOWN return value indicates completely neutral input.
- * [isHtml] is true if [text] HTML or HTML-escaped.
- */
+ /// Estimates the directionality of [text] using the best known
+ /// general-purpose method (using relative word counts). A
+ /// TextDirection.UNKNOWN return value indicates completely neutral input.
+ /// [isHtml] is true if [text] HTML or HTML-escaped.
TextDirection estimateDirection(String text, {bool isHtml: false}) {
return Bidi.estimateDirectionOfText(text, isHtml: isHtml); //TODO~!!!
}
- /**
- * Returns a unicode BiDi mark matching the surrounding context's [direction]
- * (not necessarily the direction of [text]). The function returns an LRM or
- * RLM if the overall directionality or the exit directionality of [text] is
- * opposite the context directionality. Otherwise
- * return the empty string. [isHtml] is true if [text] is HTML or
- * HTML-escaped.
- */
+ /// Returns a unicode BiDi mark matching the surrounding context's [direction]
+ /// (not necessarily the direction of [text]). The function returns an LRM or
+ /// RLM if the overall directionality or the exit directionality of [text] is
+ /// opposite the context directionality. Otherwise
+ /// return the empty string. [isHtml] is true if [text] is HTML or
+ /// HTML-escaped.
String _resetDir(String text, TextDirection direction, bool isHtml) {
// endsWithRtl and endsWithLtr are called only if needed (short-circuit).
if ((contextDirection == TextDirection.LTR &&
diff --git a/lib/src/intl/bidi_utils.dart b/lib/src/intl/bidi_utils.dart
index 378e0cc..0a00ad3 100644
--- a/lib/src/intl/bidi_utils.dart
+++ b/lib/src/intl/bidi_utils.dart
@@ -4,24 +4,22 @@
part of intl;
-/**
- * Bidi stands for Bi-directional text.
- * According to http://en.wikipedia.org/wiki/Bi-directional_text:
- * Bi-directional text is text containing text in both text directionalities,
- * both right-to-left (RTL) and left-to-right (LTR). It generally involves text
- * containing different types of alphabets, but may also refer to boustrophedon,
- * which is changing text directionality in each row.
- *
- * This file provides some utility classes for determining directionality of
- * text, switching CSS layout from LTR to RTL, and other normalizing utilities
- * needed when switching between RTL and LTR formatting.
- *
- * It defines the TextDirection class which is used to represent directionality
- * of text,
- * In most cases, it is preferable to use bidi_formatter.dart, which provides
- * bidi functionality in the given directional context, instead of using
- * bidi_utils.dart directly.
- */
+/// Bidi stands for Bi-directional text. According to
+/// http://en.wikipedia.org/wiki/Bi-directional_text: Bi-directional text is
+/// text containing text in both text directionalities, both right-to-left (RTL)
+/// and left-to-right (LTR). It generally involves text containing different
+/// types of alphabets, but may also refer to boustrophedon, which is changing
+/// text directionality in each row.
+///
+/// This file provides some utility classes for determining directionality of
+/// text, switching CSS layout from LTR to RTL, and other normalizing utilities
+/// needed when switching between RTL and LTR formatting.
+///
+/// It defines the TextDirection class which is used to represent directionality
+/// of text,
+/// In most cases, it is preferable to use bidi_formatter.dart, which provides
+/// bidi functionality in the given directional context, instead of using
+/// bidi_utils.dart directly.
class TextDirection {
static const LTR = const TextDirection._('LTR', 'ltr');
static const RTL = const TextDirection._('RTL', 'rtl');
@@ -30,71 +28,61 @@
// text falls back on the more common ltr direction.
static const UNKNOWN = const TextDirection._('UNKNOWN', 'ltr');
- /**
- * Textual representation of the directionality constant. One of
- * 'LTR', 'RTL', or 'UNKNOWN'.
- */
+ /// Textual representation of the directionality constant. One of
+ /// 'LTR', 'RTL', or 'UNKNOWN'.
final String value;
- /** Textual representation of the directionality when used in span tag. */
+ /// Textual representation of the directionality when used in span tag.
final String spanText;
const TextDirection._(this.value, this.spanText);
- /**
- * Returns true if [otherDirection] is known to be different from this
- * direction.
- */
+ /// Returns true if [otherDirection] is known to be different from this
+ /// direction.
bool isDirectionChange(TextDirection otherDirection) =>
otherDirection != TextDirection.UNKNOWN && this != otherDirection;
}
-/**
- * This provides utility methods for working with bidirectional text. All
- * of the methods are static, and are organized into a class primarily to
- * group them together for documentation and discoverability.
- */
+/// This provides utility methods for working with bidirectional text. All
+/// of the methods are static, and are organized into a class primarily to
+/// group them together for documentation and discoverability.
class Bidi {
- /** Unicode "Left-To-Right Embedding" (LRE) character. */
+ /// Unicode "Left-To-Right Embedding" (LRE) character.
static const LRE = '\u202A';
- /** Unicode "Right-To-Left Embedding" (RLE) character. */
+ /// Unicode "Right-To-Left Embedding" (RLE) character.
static const RLE = '\u202B';
- /** Unicode "Pop Directional Formatting" (PDF) character. */
+ /// Unicode "Pop Directional Formatting" (PDF) character.
static const PDF = '\u202C';
- /** Unicode "Left-To-Right Mark" (LRM) character. */
+ /// Unicode "Left-To-Right Mark" (LRM) character.
static const LRM = '\u200E';
- /** Unicode "Right-To-Left Mark" (RLM) character. */
+ /// Unicode "Right-To-Left Mark" (RLM) character.
static const RLM = '\u200F';
- /** Constant to define the threshold of RTL directionality. */
+ /// Constant to define the threshold of RTL directionality.
static num _RTL_DETECTION_THRESHOLD = 0.40;
- /**
- * Practical patterns to identify strong LTR and RTL characters, respectively.
- * These patterns are not completely correct according to the Unicode
- * standard. They are simplified for performance and small code size.
- */
+ /// Practical patterns to identify strong LTR and RTL characters,
+ /// respectively. These patterns are not completely correct according to the
+ /// Unicode standard. They are simplified for performance and small code size.
static const String _LTR_CHARS =
r'A-Za-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02B8\u0300-\u0590'
r'\u0800-\u1FFF\u2C00-\uFB1C\uFDFE-\uFE6F\uFEFD-\uFFFF';
static const String _RTL_CHARS = r'\u0591-\u07FF\uFB1D-\uFDFD\uFE70-\uFEFC';
- /**
- * Returns the input [text] with spaces instead of HTML tags or HTML escapes,
- * which is helpful for text directionality estimation.
- * Note: This function should not be used in other contexts.
- * It does not deal well with many things: comments, script,
- * elements, style elements, dir attribute,`>` in quoted attribute values,
- * etc. But it does handle well enough the most common use cases.
- * Since the worst that can happen as a result of these shortcomings is that
- * the wrong directionality will be estimated, we have not invested in
- * improving this.
- */
+ /// Returns the input [text] with spaces instead of HTML tags or HTML escapes,
+ /// which is helpful for text directionality estimation.
+ /// Note: This function should not be used in other contexts.
+ /// It does not deal well with many things: comments, script,
+ /// elements, style elements, dir attribute,`>` in quoted attribute values,
+ /// etc. But it does handle well enough the most common use cases.
+ /// Since the worst that can happen as a result of these shortcomings is that
+ /// the wrong directionality will be estimated, we have not invested in
+ /// improving this.
static String stripHtmlIfNeeded(String text) {
// The regular expression is simplified for an HTML tag (opening or
// closing) or an HTML escape. We might want to skip over such expressions
@@ -102,135 +90,112 @@
return text.replaceAll(new RegExp(r'<[^>]*>|&[^;]+;'), ' ');
}
- /**
- * Determines if the first character in [text] with strong directionality is
- * LTR. If [isHtml] is true, the text is HTML or HTML-escaped.
- */
+ /// Determines if the first character in [text] with strong directionality is
+ /// LTR. If [isHtml] is true, the text is HTML or HTML-escaped.
static bool startsWithLtr(String text, [isHtml = false]) {
return new RegExp('^[^$_RTL_CHARS]*[$_LTR_CHARS]')
.hasMatch(isHtml ? stripHtmlIfNeeded(text) : text);
}
- /**
- * Determines if the first character in [text] with strong directionality is
- * RTL. If [isHtml] is true, the text is HTML or HTML-escaped.
- */
+ /// Determines if the first character in [text] with strong directionality is
+ /// RTL. If [isHtml] is true, the text is HTML or HTML-escaped.
static bool startsWithRtl(String text, [isHtml = false]) {
return new RegExp('^[^$_LTR_CHARS]*[$_RTL_CHARS]')
.hasMatch(isHtml ? stripHtmlIfNeeded(text) : text);
}
- /**
- * Determines if the exit directionality (ie, the last strongly-directional
- * character in [text] is LTR. If [isHtml] is true, the text is HTML or
- * HTML-escaped.
- */
+ /// Determines if the exit directionality (ie, the last strongly-directional
+ /// character in [text] is LTR. If [isHtml] is true, the text is HTML or
+ /// HTML-escaped.
static bool endsWithLtr(String text, [isHtml = false]) {
return new RegExp('[$_LTR_CHARS][^$_RTL_CHARS]*\$')
.hasMatch(isHtml ? stripHtmlIfNeeded(text) : text);
}
- /**
- * Determines if the exit directionality (ie, the last strongly-directional
- * character in [text] is RTL. If [isHtml] is true, the text is HTML or
- * HTML-escaped.
- */
+ /// Determines if the exit directionality (ie, the last strongly-directional
+ /// character in [text] is RTL. If [isHtml] is true, the text is HTML or
+ /// HTML-escaped.
static bool endsWithRtl(String text, [isHtml = false]) {
return new RegExp('[$_RTL_CHARS][^$_LTR_CHARS]*\$')
.hasMatch(isHtml ? stripHtmlIfNeeded(text) : text);
}
- /**
- * Determines if the given [text] has any LTR characters in it.
- * If [isHtml] is true, the text is HTML or HTML-escaped.
- */
+ /// Determines if the given [text] has any LTR characters in it.
+ /// If [isHtml] is true, the text is HTML or HTML-escaped.
static bool hasAnyLtr(String text, [isHtml = false]) {
return new RegExp(r'[' '$_LTR_CHARS' r']')
.hasMatch(isHtml ? stripHtmlIfNeeded(text) : text);
}
- /**
- * Determines if the given [text] has any RTL characters in it.
- * If [isHtml] is true, the text is HTML or HTML-escaped.
- */
+ /// Determines if the given [text] has any RTL characters in it.
+ /// If [isHtml] is true, the text is HTML or HTML-escaped.
static bool hasAnyRtl(String text, [isHtml = false]) {
return new RegExp(r'[' '$_RTL_CHARS' r']')
.hasMatch(isHtml ? stripHtmlIfNeeded(text) : text);
}
- /**
- * Check if a BCP 47 / III [languageString] indicates an RTL language.
- *
- * i.e. either:
- * - a language code explicitly specifying one of the right-to-left scripts,
- * e.g. "az-Arab", or
- * - a language code specifying one of the languages normally written in a
- * right-to-left script, e.g. "fa" (Farsi), except ones explicitly
- * specifying Latin or Cyrillic script (which are the usual LTR
- * alternatives).
- *
- * The list of right-to-left scripts appears in the 100-199 range in
- * http://www.unicode.org/iso15924/iso15924-num.html, of which Arabic and
- * Hebrew are by far the most widely used. We also recognize Thaana, N'Ko, and
- * Tifinagh, which also have significant modern usage. The rest (Syriac,
- * Samaritan, Mandaic, etc.) seem to have extremely limited or no modern usage
- * and are not recognized.
- * The languages usually written in a right-to-left script are taken as those
- * with Suppress-Script: Hebr|Arab|Thaa|Nkoo|Tfng in
- * http://www.iana.org/assignments/language-subtag-registry,
- * as well as Sindhi (sd) and Uyghur (ug).
- * The presence of other subtags of the language code, e.g. regions like EG
- * (Egypt), is ignored.
- */
+ /// Check if a BCP 47 / III [languageString] indicates an RTL language.
+ ///
+ /// i.e. either:
+ /// - a language code explicitly specifying one of the right-to-left scripts,
+ /// e.g. "az-Arab", or
+ /// - a language code specifying one of the languages normally written in a
+ /// right-to-left script, e.g. "fa" (Farsi), except ones explicitly
+ /// specifying Latin or Cyrillic script (which are the usual LTR
+ /// alternatives).
+ ///
+ /// The list of right-to-left scripts appears in the 100-199 range in
+ /// http://www.unicode.org/iso15924/iso15924-num.html, of which Arabic and
+ /// Hebrew are by far the most widely used. We also recognize Thaana, N'Ko,
+ /// and Tifinagh, which also have significant modern usage. The rest (Syriac,
+ /// Samaritan, Mandaic, etc.) seem to have extremely limited or no modern
+ /// usage and are not recognized. The languages usually written in a
+ /// right-to-left script are taken as those with Suppress-Script:
+ /// Hebr|Arab|Thaa|Nkoo|Tfng in
+ /// http://www.iana.org/assignments/language-subtag-registry, as well as
+ /// Sindhi (sd) and Uyghur (ug). The presence of other subtags of the
+ /// language code, e.g. regions like EG (Egypt), is ignored.
static bool isRtlLanguage(String languageString) {
return new RegExp(r'^(ar|dv|he|iw|fa|nqo|ps|sd|ug|ur|yi|.*[-_]'
r'(Arab|Hebr|Thaa|Nkoo|Tfng))(?!.*[-_](Latn|Cyrl)($|-|_))'
r'($|-|_)', caseSensitive: false).hasMatch(languageString);
}
- /**
- * Enforce the [html] snippet in RTL directionality regardless of overall
- * context. If the html piece was enclosed by a tag, the direction will be
- * applied to existing tag, otherwise a span tag will be added as wrapper.
- * For this reason, if html snippet start with with tag, this tag must enclose
- * the whole piece. If the tag already has a direction specified, this new one
- * will override existing one in behavior (should work on Chrome, FF, and IE
- * since this was ported directly from the Closure version).
- */
+ /// Enforce the [html] snippet in RTL directionality regardless of overall
+ /// context. If the html piece was enclosed by a tag, the direction will be
+ /// applied to existing tag, otherwise a span tag will be added as wrapper.
+ /// For this reason, if html snippet start with with tag, this tag must
+ /// enclose the whole piece. If the tag already has a direction specified,
+ /// this new one will override existing one in behavior (should work on
+ /// Chrome, FF, and IE since this was ported directly from the Closure
+ /// version).
static String enforceRtlInHtml(String html) =>
_enforceInHtmlHelper(html, 'rtl');
- /**
- * Enforce RTL on both end of the given [text] using unicode BiDi formatting
- * characters RLE and PDF.
- */
+ /// Enforce RTL on both end of the given [text] using unicode BiDi formatting
+ /// characters RLE and PDF.
static String enforceRtlInText(String text) => '$RLE$text$PDF';
- /**
- * Enforce the [html] snippet in LTR directionality regardless of overall
- * context. If the html piece was enclosed by a tag, the direction will be
- * applied to existing tag, otherwise a span tag will be added as wrapper.
- * For this reason, if html snippet start with with tag, this tag must enclose
- * the whole piece. If the tag already has a direction specified, this new one
- * will override existing one in behavior (tested on FF and IE).
- */
+ /// Enforce the [html] snippet in LTR directionality regardless of overall
+ /// context. If the html piece was enclosed by a tag, the direction will be
+ /// applied to existing tag, otherwise a span tag will be added as wrapper.
+ /// For this reason, if html snippet start with with tag, this tag must
+ /// enclose the whole piece. If the tag already has a direction specified,
+ /// this new one will override existing one in behavior (tested on FF and IE).
static String enforceLtrInHtml(String html) =>
_enforceInHtmlHelper(html, 'ltr');
- /**
- * Enforce LTR on both end of the given [text] using unicode BiDi formatting
- * characters LRE and PDF.
- */
+ /// Enforce LTR on both end of the given [text] using unicode BiDi formatting
+ /// characters LRE and PDF.
static String enforceLtrInText(String text) => '$LRE$text$PDF';
- /**
- * Enforce the [html] snippet in the desired [direction] regardless of overall
- * context. If the html piece was enclosed by a tag, the direction will be
- * applied to existing tag, otherwise a span tag will be added as wrapper.
- * For this reason, if html snippet start with with tag, this tag must enclose
- * the whole piece. If the tag already has a direction specified, this new one
- * will override existing one in behavior (tested on FF and IE).
- */
+ /// Enforce the [html] snippet in the desired [direction] regardless of
+ /// overall context. If the html piece was enclosed by a tag, the direction
+ /// will be applied to existing tag, otherwise a span tag will be added as
+ /// wrapper. For this reason, if html snippet start with with tag, this tag
+ /// must enclose the whole piece. If the tag already has a direction
+ /// specified, this new one will override existing one in behavior (tested on
+ /// FF and IE).
static String _enforceInHtmlHelper(String html, String direction) {
if (html.startsWith('<')) {
StringBuffer buffer = new StringBuffer();
@@ -248,12 +213,10 @@
return '\n<span dir=$direction>$html</span>';
}
- /**
- * Apply bracket guard to [str] using html span tag. This is to address the
- * problem of messy bracket display that frequently happens in RTL layout.
- * If [isRtlContext] is true, then we explicitly want to wrap in a span of RTL
- * directionality, regardless of the estimated directionality.
- */
+ /// Apply bracket guard to [str] using html span tag. This is to address the
+ /// problem of messy bracket display that frequently happens in RTL layout.
+ /// If [isRtlContext] is true, then we explicitly want to wrap in a span of
+ /// RTL directionality, regardless of the estimated directionality.
static String guardBracketInHtml(String str, [bool isRtlContext]) {
var useRtl = isRtlContext == null ? hasAnyRtl(str) : isRtlContext;
RegExp matchingBrackets =
@@ -262,14 +225,12 @@
'<span dir=${useRtl? "rtl" : "ltr"}>', '</span>');
}
- /**
- * Apply bracket guard to [str] using LRM and RLM. This is to address the
- * problem of messy bracket display that frequently happens in RTL layout.
- * This version works for both plain text and html, but in some cases is not
- * as good as guardBracketInHtml.
- * If [isRtlContext] is true, then we explicitly want to wrap in a span of RTL
- * directionality, regardless of the estimated directionality.
- */
+ /// Apply bracket guard to [str] using LRM and RLM. This is to address the
+ /// problem of messy bracket display that frequently happens in RTL layout.
+ /// This version works for both plain text and html, but in some cases is not
+ /// as good as guardBracketInHtml. If [isRtlContext] is true, then we
+ /// explicitly want to wrap in a span of RTL directionality, regardless of the
+ /// estimated directionality.
static String guardBracketInText(String str, [bool isRtlContext]) {
var useRtl = isRtlContext == null ? hasAnyRtl(str) : isRtlContext;
var mark = useRtl ? RLM : LRM;
@@ -277,15 +238,12 @@
new RegExp(r'(\(.*?\)+)|(\[.*?\]+)|(\{.*?\}+)|(<.*?>+)'), mark, mark);
}
- /**
- * (Mostly) reimplements the $& functionality of "replace" in JavaScript.
- * Given a [str] and the [regexp] to match with, optionally supply a string to
- * be inserted [before] the match and/or [after]. For example,
- * `_guardBracketHelper('firetruck', new RegExp('truck'), 'hydrant', '!')`
- * would return 'firehydrant!'.
- */
- // TODO(efortuna): Get rid of this once this is implemented in Dart.
- // See Issue 2979.
+ /// (Mostly) reimplements the $& functionality of "replace" in JavaScript.
+ /// Given a [str] and the [regexp] to match with, optionally supply a string
+ /// to be inserted [before] the match and/or [after]. For example,
+ /// `_guardBracketHelper('firetruck', new RegExp('truck'), 'hydrant', '!')`
+ /// would return 'firehydrant!'. // TODO(efortuna): Get rid of this once this
+ /// is implemented in Dart. // See Issue 2979.
static String _guardBracketHelper(String str, RegExp regexp,
[String before, String after]) {
var buffer = new StringBuffer();
@@ -301,18 +259,16 @@
return (buffer..write(str.substring(startIndex))).toString();
}
- /**
- * Estimates the directionality of [text] using the best known
- * general-purpose method (using relative word counts). A
- * TextDirection.UNKNOWN return value indicates completely neutral input.
- * [isHtml] is true if [text] HTML or HTML-escaped.
- *
- * If the number of RTL words is above a certain percentage of the total
- * number of strongly directional words, returns RTL.
- * Otherwise, if any words are strongly or weakly LTR, returns LTR.
- * Otherwise, returns UNKNOWN, which is used to mean `neutral`.
- * Numbers and URLs are counted as weakly LTR.
- */
+ /// Estimates the directionality of [text] using the best known
+ /// general-purpose method (using relative word counts). A
+ /// TextDirection.UNKNOWN return value indicates completely neutral input.
+ /// [isHtml] is true if [text] HTML or HTML-escaped.
+ ///
+ /// If the number of RTL words is above a certain percentage of the total
+ /// number of strongly directional words, returns RTL.
+ /// Otherwise, if any words are strongly or weakly LTR, returns LTR.
+ /// Otherwise, returns UNKNOWN, which is used to mean `neutral`.
+ /// Numbers and URLs are counted as weakly LTR.
static TextDirection estimateDirectionOfText(String text,
{bool isHtml: false}) {
text = isHtml ? stripHtmlIfNeeded(text) : text;
@@ -346,10 +302,8 @@
}
}
- /**
- * Replace the double and single quote directly after a Hebrew character in
- * [str] with GERESH and GERSHAYIM. This is most likely the user's intention.
- */
+ /// Replace the double and single quote directly after a Hebrew character in
+ /// [str] with GERESH and GERSHAYIM. This is most likely the user's intention.
static String normalizeHebrewQuote(String str) {
StringBuffer buf = new StringBuffer();
if (str.length > 0) {
@@ -371,11 +325,9 @@
return buf.toString();
}
- /**
- * Check the estimated directionality of [str], return true if the piece of
- * text should be laid out in RTL direction. If [isHtml] is true, the string
- * is HTML or HTML-escaped.
- */
+ /// Check the estimated directionality of [str], return true if the piece of
+ /// text should be laid out in RTL direction. If [isHtml] is true, the string
+ /// is HTML or HTML-escaped.
static bool detectRtlDirectionality(String str, {bool isHtml: false}) =>
estimateDirectionOfText(str, isHtml: isHtml) == TextDirection.RTL;
}
diff --git a/lib/src/intl/date_format.dart b/lib/src/intl/date_format.dart
index 3921957..f50bead 100644
--- a/lib/src/intl/date_format.dart
+++ b/lib/src/intl/date_format.dart
@@ -6,223 +6,219 @@
// TODO(efortuna): Customized pattern system -- suggested by i18n needs
// feedback on appropriateness.
-/**
- * DateFormat is for formatting and parsing dates in a locale-sensitive
- * manner.
- *
- * It allows the user to choose from a set of standard date time formats as well
- * as specify a customized pattern under certain locales. Date elements that
- * vary across locales include month name, week name, field order, etc.
- * We also allow the user to use any customized pattern to parse or format
- * date-time strings under certain locales. Date elements that vary across
- * locales include month name, weekname, field, order, etc.
- *
- * Formatting dates in the default "en_US" format does not require any
- * initialization. e.g.
- * print(new DateFormat.yMMMd().format(new Date.now()));
- *
- * But for other locales, the formatting data for the locale must be
- * obtained. This can currently be done
- * in one of three ways, determined by which library you import. In all cases,
- * the "initializeDateFormatting" method must be called and will return a future
- * that is complete once the locale data is available. The result of the future
- * isn't important, but the data for that locale is available to the date
- * formatting and parsing once it completes.
- *
- * The easiest option is that the data may be available locally, imported in a
- * library that contains data for all the locales.
- * import 'package:intl/date_symbol_data_local.dart';
- * initializeDateFormatting("fr_FR", null).then((_) => runMyCode());
- *
- * If we are running outside of a browser, we may want to read the data
- * from files in the file system.
- * import 'package:intl/date_symbol_data_file.dart';
- * initializeDateFormatting("de_DE", null).then((_) => runMyCode());
- *
- * If we are running in a browser, we may want to read the data from the
- * server using the XmlHttpRequest mechanism.
- * import 'package:intl/date_symbol_data_http_request.dart';
- * initializeDateFormatting("pt_BR", null).then((_) => runMyCode());
- *
- * The code in example/basic/basic_example.dart shows a full example of
- * using this mechanism.
- *
- * Once we have the locale data, we need to specify the particular format.
- * This library uses the ICU/JDK date/time pattern specification both for
- * complete format specifications and also the abbreviated "skeleton" form
- * which can also adapt to different locales and is preferred where available.
- *
- * Skeletons: These can be specified either as the ICU constant name or as the
- * skeleton to which it resolves. The supported set of skeletons is as follows.
- * For each skeleton there is a named constructor that can be used to create it.
- * It's also possible to pass the skeleton as a string, but the constructor
- * is preferred.
- *
- * ICU Name Skeleton
- * -------- --------
- * DAY d
- * ABBR_WEEKDAY E
- * WEEKDAY EEEE
- * ABBR_STANDALONE_MONTH LLL
- * STANDALONE_MONTH LLLL
- * NUM_MONTH M
- * NUM_MONTH_DAY Md
- * NUM_MONTH_WEEKDAY_DAY MEd
- * ABBR_MONTH MMM
- * ABBR_MONTH_DAY MMMd
- * ABBR_MONTH_WEEKDAY_DAY MMMEd
- * MONTH MMMM
- * MONTH_DAY MMMMd
- * MONTH_WEEKDAY_DAY MMMMEEEEd
- * ABBR_QUARTER QQQ
- * QUARTER QQQQ
- * YEAR y
- * YEAR_NUM_MONTH yM
- * YEAR_NUM_MONTH_DAY yMd
- * YEAR_NUM_MONTH_WEEKDAY_DAY yMEd
- * YEAR_ABBR_MONTH yMMM
- * YEAR_ABBR_MONTH_DAY yMMMd
- * YEAR_ABBR_MONTH_WEEKDAY_DAY yMMMEd
- * YEAR_MONTH yMMMM
- * YEAR_MONTH_DAY yMMMMd
- * YEAR_MONTH_WEEKDAY_DAY yMMMMEEEEd
- * YEAR_ABBR_QUARTER yQQQ
- * YEAR_QUARTER yQQQQ
- * HOUR24 H
- * HOUR24_MINUTE Hm
- * HOUR24_MINUTE_SECOND Hms
- * HOUR j
- * HOUR_MINUTE jm
- * HOUR_MINUTE_SECOND jms
- * HOUR_MINUTE_GENERIC_TZ jmv
- * HOUR_MINUTE_TZ jmz
- * HOUR_GENERIC_TZ jv
- * HOUR_TZ jz
- * MINUTE m
- * MINUTE_SECOND ms
- * SECOND s
- *
- * Examples Using the US Locale:
- *
- * Pattern Result
- * ---------------- -------
- * new DateFormat.yMd() -> 7/10/1996
- * new DateFormat("yMd") -> 7/10/1996
- * new DateFormat.yMMMMd("en_US") -> July 10, 1996
- * new DateFormat.jm() -> 5:08 PM
- * new DateFormat.yMd().add_jm() -> 7/10/1996 5:08 PM
- * new DateFormat.Hm() -> 17:08 // force 24 hour time
- *
- * Explicit Pattern Syntax: Formats can also be specified with a pattern string.
- * This can be used for formats that don't have a skeleton available, but these
- * will not adapt to different locales. For example, in an explicit pattern the
- * letters "H" and "h" are available for 24 hour and 12 hour time formats
- * respectively. But there isn't a way in an explicit pattern to get the
- * behaviour of the "j" skeleton, which prints 24 hour or 12 hour time according
- * to the conventions of the locale, and also includes am/pm markers where
- * appropriate. So it is preferable to use the skeletons.
- *
- * The following characters are available in explicit patterns:
- *
- * Symbol Meaning Presentation Example
- * ------ ------- ------------ -------
- * G era designator (Text) AD
- * y year (Number) 1996
- * M month in year (Text & Number) July & 07
- * L standalone month (Text & Number) July & 07
- * d day in month (Number) 10
- * c standalone day (Number) 10
- * h hour in am/pm (1~12) (Number) 12
- * H hour in day (0~23) (Number) 0
- * m minute in hour (Number) 30
- * s second in minute (Number) 55
- * S fractional second (Number) 978
- * E day of week (Text) Tuesday
- * D day in year (Number) 189
- * a am/pm marker (Text) PM
- * k hour in day (1~24) (Number) 24
- * K hour in am/pm (0~11) (Number) 0
- * z time zone (Text) Pacific Standard Time
- * Z time zone (RFC 822) (Number) -0800
- * v time zone (generic) (Text) Pacific Time
- * Q quarter (Text) Q3
- * ' escape for text (Delimiter) 'Date='
- * '' single quote (Literal) 'o''clock'
- *
- * The count of pattern letters determine the format.
- *
- * **Text**:
- * * 5 pattern letters--use narrow form for standalone. Otherwise does not apply
- * * 4 or more pattern letters--use full form,
- * * 3 pattern letters--use short or abbreviated form if one exists
- * * less than 3--use numeric form if one exists
- *
- * **Number**: the minimum number of digits. Shorter numbers are zero-padded to
- * this amount (e.g. if "m" produces "6", "mm" produces "06"). Year is handled
- * specially; that is, if the count of 'y' is 2, the Year will be truncated to
- * 2 digits. (e.g., if "yyyy" produces "1997", "yy" produces "97".) Unlike other
- * fields, fractional seconds are padded on the right with zero.
- *
- * **(Text & Number)**: 3 or over, use text, otherwise use number.
- *
- * Any characters not in the pattern will be treated as quoted text. For
- * instance, characters like ':', '.', ' ', '#' and '@' will appear in the
- * resulting text even though they are not enclosed in single quotes. In our
- * current pattern usage, not all letters have meanings. But those unused
- * letters are strongly discouraged to be used as quoted text without quotes,
- * because we may use other letters as pattern characters in the future.
- *
- * Examples Using the US Locale:
- *
- * Format Pattern Result
- * -------------- -------
- * "yyyy.MM.dd G 'at' HH:mm:ss vvvv" 1996.07.10 AD at 15:08:56 Pacific Time
- * "EEE, MMM d, ''yy" Wed, July 10, '96
- * "h:mm a" 12:08 PM
- * "hh 'o''clock' a, zzzz" 12 o'clock PM, Pacific Daylight Time
- * "K:mm a, vvv" 0:00 PM, PT
- * "yyyyy.MMMMM.dd GGG hh:mm aaa" 01996.July.10 AD 12:08 PM
- *
- * When parsing a date string using the abbreviated year pattern ("yy"),
- * DateFormat must interpret the abbreviated year relative to some
- * century. It does this by adjusting dates to be within 80 years before and 20
- * years after the time the parse function is called. For example, using a
- * pattern of "MM/dd/yy" and a DateParse instance created on Jan 1, 1997,
- * the string "01/11/12" would be interpreted as Jan 11, 2012 while the string
- * "05/04/64" would be interpreted as May 4, 1964. During parsing, only
- * strings consisting of exactly two digits, as defined by {@link
- * java.lang.Character#isDigit(char)}, will be parsed into the default
- * century. Any other numeric string, such as a one digit string, a three or
- * more digit string will be interpreted as its face value.
- *
- * If the year pattern does not have exactly two 'y' characters, the year is
- * interpreted literally, regardless of the number of digits. So using the
- * pattern "MM/dd/yyyy", "01/11/12" parses to Jan 11, 12 A.D.
- */
+/// DateFormat is for formatting and parsing dates in a locale-sensitive
+/// manner.
+///
+/// It allows the user to choose from a set of standard date time formats as
+/// well as specify a customized pattern under certain locales. Date elements
+/// that vary across locales include month name, week name, field order, etc.
+/// We also allow the user to use any customized pattern to parse or format
+/// date-time strings under certain locales. Date elements that vary across
+/// locales include month name, weekname, field, order, etc.
+///
+/// Formatting dates in the default "en_US" format does not require any
+/// initialization. e.g.
+/// print(new DateFormat.yMMMd().format(new Date.now()));
+///
+/// But for other locales, the formatting data for the locale must be
+/// obtained. This can currently be done in one of three ways, determined by
+/// which library you import. In all cases, the "initializeDateFormatting"
+/// method must be called and will return a future that is complete once the
+/// locale data is available. The result of the future isn't important, but the
+/// data for that locale is available to the date formatting and parsing once it
+/// completes.
+///
+/// The easiest option is that the data may be available locally, imported in a
+/// library that contains data for all the locales.
+/// import 'package:intl/date_symbol_data_local.dart';
+/// initializeDateFormatting("fr_FR", null).then((_) => runMyCode());
+///
+/// If we are running outside of a browser, we may want to read the data
+/// from files in the file system.
+/// import 'package:intl/date_symbol_data_file.dart';
+/// initializeDateFormatting("de_DE", null).then((_) => runMyCode());
+///
+/// If we are running in a browser, we may want to read the data from the
+/// server using the XmlHttpRequest mechanism.
+/// import 'package:intl/date_symbol_data_http_request.dart';
+/// initializeDateFormatting("pt_BR", null).then((_) => runMyCode());
+///
+/// The code in example/basic/basic_example.dart shows a full example of
+/// using this mechanism.
+///
+/// Once we have the locale data, we need to specify the particular format.
+/// This library uses the ICU/JDK date/time pattern specification both for
+/// complete format specifications and also the abbreviated "skeleton" form
+/// which can also adapt to different locales and is preferred where available.
+///
+/// Skeletons: These can be specified either as the ICU constant name or as the
+/// skeleton to which it resolves. The supported set of skeletons is as follows.
+/// For each skeleton there is a named constructor that can be used to create
+/// it. It's also possible to pass the skeleton as a string, but the
+/// constructor is preferred.
+///
+/// ICU Name Skeleton
+/// -------- --------
+/// DAY d
+/// ABBR_WEEKDAY E
+/// WEEKDAY EEEE
+/// ABBR_STANDALONE_MONTH LLL
+/// STANDALONE_MONTH LLLL
+/// NUM_MONTH M
+/// NUM_MONTH_DAY Md
+/// NUM_MONTH_WEEKDAY_DAY MEd
+/// ABBR_MONTH MMM
+/// ABBR_MONTH_DAY MMMd
+/// ABBR_MONTH_WEEKDAY_DAY MMMEd
+/// MONTH MMMM
+/// MONTH_DAY MMMMd
+/// MONTH_WEEKDAY_DAY MMMMEEEEd
+/// ABBR_QUARTER QQQ
+/// QUARTER QQQQ
+/// YEAR y
+/// YEAR_NUM_MONTH yM
+/// YEAR_NUM_MONTH_DAY yMd
+/// YEAR_NUM_MONTH_WEEKDAY_DAY yMEd
+/// YEAR_ABBR_MONTH yMMM
+/// YEAR_ABBR_MONTH_DAY yMMMd
+/// YEAR_ABBR_MONTH_WEEKDAY_DAY yMMMEd
+/// YEAR_MONTH yMMMM
+/// YEAR_MONTH_DAY yMMMMd
+/// YEAR_MONTH_WEEKDAY_DAY yMMMMEEEEd
+/// YEAR_ABBR_QUARTER yQQQ
+/// YEAR_QUARTER yQQQQ
+/// HOUR24 H
+/// HOUR24_MINUTE Hm
+/// HOUR24_MINUTE_SECOND Hms
+/// HOUR j
+/// HOUR_MINUTE jm
+/// HOUR_MINUTE_SECOND jms
+/// HOUR_MINUTE_GENERIC_TZ jmv
+/// HOUR_MINUTE_TZ jmz
+/// HOUR_GENERIC_TZ jv
+/// HOUR_TZ jz
+/// MINUTE m
+/// MINUTE_SECOND ms
+/// SECOND s
+///
+/// Examples Using the US Locale:
+///
+/// Pattern Result
+/// ---------------- -------
+/// new DateFormat.yMd() -> 7/10/1996
+/// new DateFormat("yMd") -> 7/10/1996
+/// new DateFormat.yMMMMd("en_US") -> July 10, 1996
+/// new DateFormat.jm() -> 5:08 PM
+/// new DateFormat.yMd().add_jm() -> 7/10/1996 5:08 PM
+/// new DateFormat.Hm() -> 17:08 // force 24 hour time
+///
+/// Explicit Pattern Syntax: Formats can also be specified with a pattern
+/// string. This can be used for formats that don't have a skeleton available,
+/// but these will not adapt to different locales. For example, in an explicit
+/// pattern the letters "H" and "h" are available for 24 hour and 12 hour time
+/// formats respectively. But there isn't a way in an explicit pattern to get
+/// the behaviour of the "j" skeleton, which prints 24 hour or 12 hour time
+/// according to the conventions of the locale, and also includes am/pm markers
+/// where appropriate. So it is preferable to use the skeletons.
+///
+/// The following characters are available in explicit patterns:
+///
+/// Symbol Meaning Presentation Example
+/// ------ ------- ------------ -------
+/// G era designator (Text) AD
+/// y year (Number) 1996
+/// M month in year (Text & Number) July & 07
+/// L standalone month (Text & Number) July & 07
+/// d day in month (Number) 10
+/// c standalone day (Number) 10
+/// h hour in am/pm (1~12) (Number) 12
+/// H hour in day (0~23) (Number) 0
+/// m minute in hour (Number) 30
+/// s second in minute (Number) 55
+/// S fractional second (Number) 978
+/// E day of week (Text) Tuesday
+/// D day in year (Number) 189
+/// a am/pm marker (Text) PM
+/// k hour in day (1~24) (Number) 24
+/// K hour in am/pm (0~11) (Number) 0
+/// z time zone (Text) Pacific Standard Time
+/// Z time zone (RFC 822) (Number) -0800
+/// v time zone (generic) (Text) Pacific Time
+/// Q quarter (Text) Q3
+/// ' escape for text (Delimiter) 'Date='
+/// '' single quote (Literal) 'o''clock'
+///
+/// The count of pattern letters determine the format.
+///
+/// **Text**:
+/// * 5 pattern letters--use narrow form for standalone. Otherwise not used.
+/// * 4 or more pattern letters--use full form,
+/// * 3 pattern letters--use short or abbreviated form if one exists
+/// * less than 3--use numeric form if one exists
+///
+/// **Number**: the minimum number of digits. Shorter numbers are zero-padded to
+/// this amount (e.g. if "m" produces "6", "mm" produces "06"). Year is handled
+/// specially; that is, if the count of 'y' is 2, the Year will be truncated to
+/// 2 digits. (e.g., if "yyyy" produces "1997", "yy" produces "97".) Unlike
+/// other fields, fractional seconds are padded on the right with zero.
+///
+/// **(Text & Number)**: 3 or over, use text, otherwise use number.
+///
+/// Any characters not in the pattern will be treated as quoted text. For
+/// instance, characters like ':', '.', ' ', '#' and '@' will appear in the
+/// resulting text even though they are not enclosed in single quotes. In our
+/// current pattern usage, not all letters have meanings. But those unused
+/// letters are strongly discouraged to be used as quoted text without quotes,
+/// because we may use other letters as pattern characters in the future.
+///
+/// Examples Using the US Locale:
+///
+/// Format Pattern Result
+/// -------------- -------
+/// "yyyy.MM.dd G 'at' HH:mm:ss vvvv" 1996.07.10 AD at 15:08:56 Pacific Time
+/// "EEE, MMM d, ''yy" Wed, July 10, '96
+/// "h:mm a" 12:08 PM
+/// "hh 'o''clock' a, zzzz" 12 o'clock PM, Pacific Daylight Time
+/// "K:mm a, vvv" 0:00 PM, PT
+/// "yyyyy.MMMMM.dd GGG hh:mm aaa" 01996.July.10 AD 12:08 PM
+///
+/// When parsing a date string using the abbreviated year pattern ("yy"),
+/// DateFormat must interpret the abbreviated year relative to some
+/// century. It does this by adjusting dates to be within 80 years before and 20
+/// years after the time the parse function is called. For example, using a
+/// pattern of "MM/dd/yy" and a DateParse instance created on Jan 1, 1997,
+/// the string "01/11/12" would be interpreted as Jan 11, 2012 while the string
+/// "05/04/64" would be interpreted as May 4, 1964. During parsing, only
+/// strings consisting of exactly two digits, as defined by {@link
+/// java.lang.Character#isDigit(char)}, will be parsed into the default
+/// century. Any other numeric string, such as a one digit string, a three or
+/// more digit string will be interpreted as its face value.
+///
+/// If the year pattern does not have exactly two 'y' characters, the year is
+/// interpreted literally, regardless of the number of digits. So using the
+/// pattern "MM/dd/yyyy", "01/11/12" parses to Jan 11, 12 A.D.
class DateFormat {
- /**
- * Creates a new DateFormat, using the format specified by [newPattern]. For
- * forms that match one of our predefined skeletons, we look up the
- * corresponding pattern in [locale] (or in the default locale if none is
- * specified) and use the resulting full format string. This is the
- * preferred usage, but if [newPattern] does not match one of the skeletons,
- * then it is used as a format directly, but will not be adapted to suit
- * the locale.
- *
- * For example, in an en_US locale, specifying the skeleton
- * new DateFormat.yMEd();
- * or the explicit
- * new DateFormat('EEE, M/d/y');
- * would produce the same result, a date of the form
- * Wed, 6/27/2012
- * The first version would produce a different format string if used in
- * another locale, but the second format would always be the same.
- *
- * If [locale] does not exist in our set of supported locales then an
- * [ArgumentError] is thrown.
- */
+ /// Creates a new DateFormat, using the format specified by [newPattern]. For
+ /// forms that match one of our predefined skeletons, we look up the
+ /// corresponding pattern in [locale] (or in the default locale if none is
+ /// specified) and use the resulting full format string. This is the
+ /// preferred usage, but if [newPattern] does not match one of the skeletons,
+ /// then it is used as a format directly, but will not be adapted to suit
+ /// the locale.
+ ///
+ /// For example, in an en_US locale, specifying the skeleton
+ /// new DateFormat.yMEd();
+ /// or the explicit
+ /// new DateFormat('EEE, M/d/y');
+ /// would produce the same result, a date of the form
+ /// Wed, 6/27/2012
+ /// The first version would produce a different format string if used in
+ /// another locale, but the second format would always be the same.
+ ///
+ /// If [locale] does not exist in our set of supported locales then an
+ /// [ArgumentError] is thrown.
DateFormat([String newPattern, String locale]) {
// TODO(alanknight): It should be possible to specify multiple skeletons eg
// date, time, timezone all separately. Adding many or named parameters to
@@ -233,10 +229,8 @@
addPattern(newPattern);
}
- /**
- * Return a string representing [date] formatted according to our locale
- * and internal format.
- */
+ /// Return a string representing [date] formatted according to our locale
+ /// and internal format.
String format(DateTime date) {
// TODO(efortuna): read optional TimeZone argument (or similar)?
var result = new StringBuffer();
@@ -244,66 +238,58 @@
return result.toString();
}
- /**
- * NOT YET IMPLEMENTED.
- *
- * Returns a date string indicating how long ago (3 hours, 2 minutes)
- * something has happened or how long in the future something will happen
- * given a [reference] DateTime relative to the current time.
- */
+ /// NOT YET IMPLEMENTED.
+ ///
+ /// Returns a date string indicating how long ago (3 hours, 2 minutes)
+ /// something has happened or how long in the future something will happen
+ /// given a [reference] DateTime relative to the current time.
String formatDuration(DateTime reference) => '';
- /**
- * NOT YET IMPLEMENTED.
- *
- * Formats a string indicating how long ago (negative [duration]) or how far
- * in the future (positive [duration]) some time is with respect to a
- * reference [date].
- */
+ /// NOT YET IMPLEMENTED.
+ ///
+ /// Formats a string indicating how long ago (negative [duration]) or how far
+ /// in the future (positive [duration]) some time is with respect to a
+ /// reference [date].
String formatDurationFrom(Duration duration, DateTime date) => '';
- /**
- * Given user input, attempt to parse the [inputString] into the anticipated
- * format, treating it as being in the local timezone. If [inputString] does
- * not match our format, throws a [FormatException]. This will accept dates
- * whose values are not strictly valid, or strings with additional characters
- * (including whitespace) after a valid date. For stricter parsing, use
- * [parseStrict].
- */
+ /// Given user input, attempt to parse the [inputString] into the anticipated
+ /// format, treating it as being in the local timezone. If [inputString] does
+ /// not match our format, throws a [FormatException]. This will accept dates
+ /// whose values are not strictly valid, or strings with additional characters
+ /// (including whitespace) after a valid date. For stricter parsing, use
+ /// [parseStrict].
DateTime parse(String inputString, [utc = false]) =>
_parse(inputString, utc: utc, strict: false);
- /**
- * Given user input, attempt to parse the [inputString] "loosely" into the
- * anticipated format, accepting some variations from the strict format.
- *
- * If [inputString]
- * is accepted by [parseStrict], just return the result. If not, attempt to
- * parse it, but accepting either upper or
- * lower case, allowing delimiters to be missing and replaced or
- * supplemented with whitespace,
- * and allowing arbitrary amounts of whitespace wherever whitespace is
- * permitted. Note that this does not allow trailing characters, the way
- * [parse] does. It also does not allow leading whitespace on delimiters,
- * and does not allow alternative names for months or weekdays other than
- * those the format knows about. The restrictions are quite arbitrary and
- * it's not known how well they'll work for locales that aren't English-like.
- *
- * If [inputString] does not parse, this throws a
- * [FormatException].
- *
- * For example, this will accept
- *
- * new DateFormat.yMMMd("en_US").parseLoose("SEp 3 2014");
- * new DateFormat.yMd("en_US").parseLoose("09 03/2014");
- *
- * It will NOT accept
- *
- * // "Sept" is not a valid month name.
- * new DateFormat.yMMMd("en_US").parseLoose("Sept 3, 2014");
- * // Delimiters can't have leading whitespace.
- * new DateFormat.yMd("en_US").parseLoose("09 / 03 / 2014");
- */
+ /// Given user input, attempt to parse the [inputString] "loosely" into the
+ /// anticipated format, accepting some variations from the strict format.
+ ///
+ /// If [inputString]
+ /// is accepted by [parseStrict], just return the result. If not, attempt to
+ /// parse it, but accepting either upper or
+ /// lower case, allowing delimiters to be missing and replaced or
+ /// supplemented with whitespace,
+ /// and allowing arbitrary amounts of whitespace wherever whitespace is
+ /// permitted. Note that this does not allow trailing characters, the way
+ /// [parse] does. It also does not allow leading whitespace on delimiters,
+ /// and does not allow alternative names for months or weekdays other than
+ /// those the format knows about. The restrictions are quite arbitrary and
+ /// it's not known how well they'll work for locales that aren't English-like.
+ ///
+ /// If [inputString] does not parse, this throws a
+ /// [FormatException].
+ ///
+ /// For example, this will accept
+ ///
+ /// new DateFormat.yMMMd("en_US").parseLoose("SEp 3 2014");
+ /// new DateFormat.yMd("en_US").parseLoose("09 03/2014");
+ ///
+ /// It will NOT accept
+ ///
+ /// // "Sept" is not a valid month name.
+ /// new DateFormat.yMMMd("en_US").parseLoose("Sept 3, 2014");
+ /// // Delimiters can't have leading whitespace.
+ /// new DateFormat.yMd("en_US").parseLoose("09 / 03 / 2014");
DateTime parseLoose(String inputString, [utc = false]) {
try {
return _parse(inputString, utc: utc, strict: true);
@@ -325,15 +311,13 @@
return dateFields.asDate();
}
- /**
- * Given user input, attempt to parse the [inputString] into the anticipated
- * format, treating it as being in the local timezone. If [inputString] does
- * not match our format, throws a [FormatException]. This will reject dates
- * whose values are not strictly valid, even if the
- * DateTime constructor will accept them. It will also rejct strings with
- * additional characters (including whitespace) after a valid date. For
- * looser parsing, use [parse].
- */
+ /// Given user input, attempt to parse the [inputString] into the anticipated
+ /// format, treating it as being in the local timezone. If [inputString] does
+ /// not match our format, throws a [FormatException]. This will reject dates
+ /// whose values are not strictly valid, even if the
+ /// DateTime constructor will accept them. It will also rejct strings with
+ /// additional characters (including whitespace) after a valid date. For
+ /// looser parsing, use [parse].
DateTime parseStrict(String inputString, [utc = false]) =>
_parse(inputString, utc: utc, strict: true);
@@ -352,51 +336,41 @@
return dateFields.asDate();
}
- /**
- * Given user input, attempt to parse the [inputString] into the anticipated
- * format, treating it as being in UTC.
- *
- * The canonical Dart style name
- * is [parseUtc], but [parseUTC] is retained
- * for backward-compatibility.
- */
+ /// Given user input, attempt to parse the [inputString] into the anticipated
+ /// format, treating it as being in UTC.
+ ///
+ /// The canonical Dart style name
+ /// is [parseUtc], but [parseUTC] is retained
+ /// for backward-compatibility.
DateTime parseUTC(String inputString) => parse(inputString, true);
- /**
- * Given user input, attempt to parse the [inputString] into the anticipated
- * format, treating it as being in UTC.
- *
- * The canonical Dart style name
- * is [parseUtc], but [parseUTC] is retained
- * for backward-compatibility.
- */
+ /// Given user input, attempt to parse the [inputString] into the anticipated
+ /// format, treating it as being in UTC.
+ ///
+ /// The canonical Dart style name
+ /// is [parseUtc], but [parseUTC] is retained
+ /// for backward-compatibility.
DateTime parseUtc(String inputString) => parse(inputString, true);
- /**
- * Return the locale code in which we operate, e.g. 'en_US' or 'pt'.
- */
+ /// Return the locale code in which we operate, e.g. 'en_US' or 'pt'.
String get locale => _locale;
- /**
- * Returns a list of all locales for which we have date formatting
- * information.
- */
+ /// Returns a list of all locales for which we have date formatting
+ /// information.
static List<String> allLocalesWithSymbols() => dateTimeSymbols.keys.toList();
- /**
- * The named constructors for this class are all conveniences for creating
- * instances using one of the known "skeleton" formats, and having code
- * completion support for discovering those formats.
- * So,
- * new DateFormat.yMd("en_US")
- * is equivalent to
- * new DateFormat("yMd", "en_US")
- * To create a compound format you can use these constructors in combination
- * with the add_ methods below. e.g.
- * new DateFormat.yMd().add_Hms();
- * If the optional [locale] is omitted, the format will be created using the
- * default locale in [Intl.systemLocale].
- */
+ /// The named constructors for this class are all conveniences for creating
+ /// instances using one of the known "skeleton" formats, and having code
+ /// completion support for discovering those formats.
+ /// So,
+ /// new DateFormat.yMd("en_US")
+ /// is equivalent to
+ /// new DateFormat("yMd", "en_US")
+ /// To create a compound format you can use these constructors in combination
+ /// with the add_ methods below. e.g.
+ /// new DateFormat.yMd().add_Hms();
+ /// If the optional [locale] is omitted, the format will be created using the
+ /// default locale in [Intl.systemLocale].
DateFormat.d([locale]) : this("d", locale);
DateFormat.E([locale]) : this("E", locale);
DateFormat.EEEE([locale]) : this("EEEE", locale);
@@ -439,13 +413,11 @@
DateFormat.ms([locale]) : this("ms", locale);
DateFormat.s([locale]) : this("s", locale);
- /**
- * The "add_*" methods append a particular skeleton to the format, or set
- * it as the only format if none was previously set. These are primarily
- * useful for creating compound formats. For example
- * new DateFormat.yMd().add_Hms();
- * would create a date format that prints both the date and the time.
- */
+ /// The "add_*" methods append a particular skeleton to the format, or set
+ /// it as the only format if none was previously set. These are primarily
+ /// useful for creating compound formats. For example
+ /// new DateFormat.yMd().add_Hms();
+ /// would create a date format that prints both the date and the time.
DateFormat add_d() => addPattern("d");
DateFormat add_E() => addPattern("E");
DateFormat add_EEEE() => addPattern("EEEE");
@@ -488,10 +460,8 @@
DateFormat add_ms() => addPattern("ms");
DateFormat add_s() => addPattern("s");
- /**
- * For each of the skeleton formats we also allow the use of the corresponding
- * ICU constant names.
- */
+ /// For each of the skeleton formats we also allow the use of the
+ /// corresponding ICU constant names.
static const String ABBR_MONTH = 'MMM';
static const String DAY = 'd';
static const String ABBR_WEEKDAY = 'E';
@@ -534,26 +504,20 @@
static const String MINUTE_SECOND = 'ms';
static const String SECOND = 's';
- /** The locale in which we operate, e.g. 'en_US', or 'pt'. */
+ /// The locale in which we operate, e.g. 'en_US', or 'pt'.
String _locale;
- /**
- * The full template string. This may have been specified directly, or
- * it may have been derived from a skeleton and the locale information
- * on how to interpret that skeleton.
- */
+ /// The full template string. This may have been specified directly, or
+ /// it may have been derived from a skeleton and the locale information
+ /// on how to interpret that skeleton.
String _pattern;
- /**
- * We parse the format string into individual [_DateFormatField] objects
- * that are used to do the actual formatting and parsing. Do not use
- * this variable directly, use the getter [_formatFields].
- */
+ /// We parse the format string into individual [_DateFormatField] objects
+ /// that are used to do the actual formatting and parsing. Do not use
+ /// this variable directly, use the getter [_formatFields].
List<_DateFormatField> _formatFieldsPrivate;
- /**
- * Getter for [_formatFieldsPrivate] that lazily initializes it.
- */
+ /// Getter for [_formatFieldsPrivate] that lazily initializes it.
get _formatFields {
if (_formatFieldsPrivate == null) {
if (_pattern == null) _useDefaultPattern();
@@ -562,19 +526,15 @@
return _formatFieldsPrivate;
}
- /**
- * We are being asked to do formatting without having set any pattern.
- * Use a default.
- */
+ /// We are being asked to do formatting without having set any pattern.
+ /// Use a default.
_useDefaultPattern() {
add_yMMMMd();
add_jms();
}
- /**
- * A series of regular expressions used to parse a format string into its
- * component fields.
- */
+ /// A series of regular expressions used to parse a format string into its
+ /// component fields.
static List<RegExp> _matchers = [
// Quoted String - anything between single quotes, with escaping
// of single quotes by doubling them.
@@ -590,22 +550,18 @@
new RegExp("^[^\'GyMkSEahKHcLQdDmsvzZ]+")
];
- /**
- * Set our pattern, appending it to any existing patterns. Also adds a single
- * space to separate the two.
- */
+ /// Set our pattern, appending it to any existing patterns. Also adds a single
+ /// space to separate the two.
_appendPattern(String inputPattern, [String separator = ' ']) {
_pattern =
_pattern == null ? inputPattern : "$_pattern$separator$inputPattern";
}
- /**
- * Add [inputPattern] to this instance as a pattern. If there was a previous
- * pattern, then this appends to it, separating the two by [separator].
- * [inputPattern] is first looked up in our list of known skeletons.
- * If it's found there, then use the corresponding pattern for this locale.
- * If it's not, then treat [inputPattern] as an explicit pattern.
- */
+ /// Add [inputPattern] to this instance as a pattern. If there was a previous
+ /// pattern, then this appends to it, separating the two by [separator].
+ /// [inputPattern] is first looked up in our list of known skeletons.
+ /// If it's found there, then use the corresponding pattern for this locale.
+ /// If it's not, then treat [inputPattern] as an explicit pattern.
DateFormat addPattern(String inputPattern, [String separator = ' ']) {
// TODO(alanknight): This is an expensive operation. Caching recently used
// formats, or possibly introducing an entire "locale" object that would
@@ -621,25 +577,21 @@
return this;
}
- /** Return the pattern that we use to format dates.*/
+ /// Return the pattern that we use to format dates.
get pattern => _pattern;
- /** Return the skeletons for our current locale. */
+ /// Return the skeletons for our current locale.
Map get _availableSkeletons => dateTimePatterns[locale];
- /**
- * Return the [DateSymbol] information for the locale. This can be useful
- * to find lists like the names of weekdays or months in a locale, but
- * the structure of this data may change, and it's generally better to go
- * through the [format] and [parse] APIs. If the locale isn't present, or
- * is uninitialized, returns null;
- */
+ /// Return the [DateSymbol] information for the locale. This can be useful
+ /// to find lists like the names of weekdays or months in a locale, but
+ /// the structure of this data may change, and it's generally better to go
+ /// through the [format] and [parse] APIs. If the locale isn't present, or
+ /// is uninitialized, returns null;
DateSymbols get dateSymbols => dateTimeSymbols[_locale];
- /**
- * Return true if the locale exists, or if it is null. The null case
- * is interpreted to mean that we use the default locale.
- */
+ /// Return true if the locale exists, or if it is null. The null case
+ /// is interpreted to mean that we use the default locale.
static bool localeExists(localeName) {
if (localeName == null) return false;
return dateTimeSymbols.containsKey(localeName);
@@ -651,13 +603,13 @@
(pattern, parent) => new _DateFormatLiteralField(pattern, parent)
];
- /** Parse the template pattern and return a list of field objects.*/
+ /// Parse the template pattern and return a list of field objects.
List parsePattern(String pattern) {
if (pattern == null) return null;
return _parsePatternHelper(pattern).reversed.toList();
}
- /** Recursive helper for parsing the template pattern. */
+ /// Recursive helper for parsing the template pattern.
List _parsePatternHelper(String pattern) {
if (pattern.isEmpty) return [];
@@ -670,7 +622,7 @@
return parsed;
}
- /** Find elements in a string that are patterns for specific fields.*/
+ /// Find elements in a string that are patterns for specific fields.
_DateFormatField _match(String pattern) {
for (var i = 0; i < _matchers.length; i++) {
var regex = _matchers[i];
diff --git a/lib/src/intl/date_format_field.dart b/lib/src/intl/date_format_field.dart
index 63c2d1a..aa241bc 100644
--- a/lib/src/intl/date_format_field.dart
+++ b/lib/src/intl/date_format_field.dart
@@ -4,49 +4,43 @@
part of intl;
-/**
- * This is a private class internal to DateFormat which is used for formatting
- * particular fields in a template. e.g. if the format is hh:mm:ss then the
- * fields would be "hh", ":", "mm", ":", and "ss". Each type of field knows
- * how to format that portion of a date.
- */
+/// This is a private class internal to DateFormat which is used for formatting
+/// particular fields in a template. e.g. if the format is hh:mm:ss then the
+/// fields would be "hh", ":", "mm", ":", and "ss". Each type of field knows
+/// how to format that portion of a date.
abstract class _DateFormatField {
- /** The format string that defines us, e.g. "hh" */
+ /// The format string that defines us, e.g. "hh"
String pattern;
- /** The DateFormat that we are part of.*/
+ /// The DateFormat that we are part of.
DateFormat parent;
_DateFormatField(this.pattern, this.parent);
- /**
- * Return the width of [pattern]. Different widths represent different
- * formatting options. See the comment for DateFormat for details.
- */
+ /// Return the width of [pattern]. Different widths represent different
+ /// formatting options. See the comment for DateFormat for details.
int get width => pattern.length;
String fullPattern() => pattern;
String toString() => pattern;
- /** Format date according to our specification and return the result. */
+ /// Format date according to our specification and return the result.
String format(DateTime date) {
// Default implementation in the superclass, works for both types of
// literal patterns, and is overridden by _DateFormatPatternField.
return pattern;
}
- /** Abstract method for subclasses to implementing parsing for their format.*/
+ /// Abstract method for subclasses to implementing parsing for their format.
void parse(_Stream input, _DateBuilder dateFields);
- /**
- * Abstract method for subclasses to implementing 'loose' parsing for
- * their format, accepting input case-insensitively, and allowing some
- * delimiters to be skipped.
- */
+ /// Abstract method for subclasses to implementing 'loose' parsing for
+ /// their format, accepting input case-insensitively, and allowing some
+ /// delimiters to be skipped.
void parseLoose(_Stream input, _DateBuilder dateFields);
- /** Parse a literal field. We just look for the exact input. */
+ /// Parse a literal field. We just look for the exact input.
void parseLiteral(_Stream input) {
var found = input.read(width);
if (found != pattern) {
@@ -54,10 +48,8 @@
}
}
- /**
- * Parse a literal field. We accept either an exact match, or an arbitrary
- * amount of whitespace.
- */
+ /// Parse a literal field. We accept either an exact match, or an arbitrary
+ /// amount of whitespace.
void parseLiteralLoose(_Stream input) {
var found = input.peek(width);
if (found == pattern) {
@@ -68,18 +60,16 @@
}
}
- /** Throw a format exception with an error message indicating the position.*/
+ /// Throw a format exception with an error message indicating the position.
void throwFormatException(_Stream stream) {
throw new FormatException("Trying to read $this from ${stream.contents} "
"at position ${stream.index}");
}
}
-/**
- * Represents a literal field - a sequence of characters that doesn't
- * change according to the date's data. As such, the implementation
- * is extremely simple.
- */
+/// Represents a literal field - a sequence of characters that doesn't
+/// change according to the date's data. As such, the implementation
+/// is extremely simple.
class _DateFormatLiteralField extends _DateFormatField {
_DateFormatLiteralField(pattern, parent) : super(pattern, parent);
@@ -91,10 +81,8 @@
parseLiteralLoose(input);
}
-/**
- * Represents a literal field with quoted characters in it. This is
- * only slightly more complex than a _DateFormatLiteralField.
- */
+/// Represents a literal field with quoted characters in it. This is
+/// only slightly more complex than a _DateFormatLiteralField.
class _DateFormatQuotedField extends _DateFormatField {
String _fullPattern;
@@ -123,19 +111,15 @@
}
}
-/**
- * A field that parses "loosely", meaning that we'll accept input that is
- * missing delimiters, has upper/lower case mixed up, and might not strictly
- * conform to the pattern, e.g. the pattern calls for Sep we might accept
- * sep, september, sEPTember. Doesn't affect numeric fields.
- */
+/// A field that parses "loosely", meaning that we'll accept input that is
+/// missing delimiters, has upper/lower case mixed up, and might not strictly
+/// conform to the pattern, e.g. the pattern calls for Sep we might accept
+/// sep, september, sEPTember. Doesn't affect numeric fields.
class _LoosePatternField extends _DateFormatPatternField {
_LoosePatternField(String pattern, parent) : super(pattern, parent);
- /**
- * Parse from a list of possibilities, but case-insensitively.
- * Assumes that input is lower case.
- */
+ /// Parse from a list of possibilities, but case-insensitively.
+ /// Assumes that input is lower case.
int parseEnumeratedString(_Stream input, List possibilities) {
var lowercasePossibilities =
possibilities.map((x) => x.toLowerCase()).toList();
@@ -146,10 +130,8 @@
}
}
- /**
- * Parse a month name, case-insensitively, and set it in [dateFields].
- * Assumes that [input] is lower case.
- */
+ /// Parse a month name, case-insensitively, and set it in [dateFields].
+ /// Assumes that [input] is lower case.
void parseMonth(input, dateFields) {
if (width <= 2) {
handleNumericField(input, dateFields.setMonth);
@@ -165,10 +147,8 @@
}
}
- /**
- * Parse a standalone day name, case-insensitively.
- * Assumes that input is lower case. Doesn't do anything
- */
+ /// Parse a standalone day name, case-insensitively.
+ /// Assumes that input is lower case. Doesn't do anything
void parseStandaloneDay(input) {
// This is ignored, but we still have to skip over it the correct amount.
if (width <= 2) {
@@ -187,10 +167,8 @@
}
}
- /**
- * Parse a standalone month name, case-insensitively.
- * Assumes that input is lower case. Doesn't do anything
- */
+ /// Parse a standalone month name, case-insensitively.
+ /// Assumes that input is lower case. Doesn't do anything
void parseStandaloneMonth(input, dateFields) {
if (width <= 2) {
handleNumericField(input, (x) => x);
@@ -209,10 +187,8 @@
}
}
- /**
- * Parse a day of the week name, case-insensitively.
- * Assumes that input is lower case. Doesn't do anything
- */
+ /// Parse a day of the week name, case-insensitively.
+ /// Assumes that input is lower case. Doesn't do anything
void parseDayOfWeek(_Stream input) {
// This is IGNORED, but we still have to skip over it the correct amount.
if (width <= 2) {
@@ -237,32 +213,26 @@
class _DateFormatPatternField extends _DateFormatField {
_DateFormatPatternField(pattern, parent) : super(pattern, parent);
- /** Format date according to our specification and return the result. */
+ /// Format date according to our specification and return the result.
String format(DateTime date) {
return formatField(date);
}
- /**
- * Parse the date according to our specification and put the result
- * into the correct place in dateFields.
- */
+ /// Parse the date according to our specification and put the result
+ /// into the correct place in dateFields.
void parse(_Stream input, _DateBuilder dateFields) {
parseField(input, dateFields);
}
- /**
- * Parse the date according to our specification and put the result
- * into the correct place in dateFields. Allow looser parsing, accepting
- * case-insensitive input and skipped delimiters.
- */
+ /// Parse the date according to our specification and put the result
+ /// into the correct place in dateFields. Allow looser parsing, accepting
+ /// case-insensitive input and skipped delimiters.
void parseLoose(_Stream input, _DateBuilder dateFields) {
new _LoosePatternField(pattern, parent).parse(input, dateFields);
}
- /**
- * Parse a field representing part of a date pattern. Note that we do not
- * return a value, but rather build up the result in [builder].
- */
+ /// Parse a field representing part of a date pattern. Note that we do not
+ /// return a value, but rather build up the result in [builder].
void parseField(_Stream input, _DateBuilder builder) {
try {
switch (pattern[0]) {
@@ -331,7 +301,7 @@
}
}
- /** Formatting logic if we are of type FIELD */
+ /// Formatting logic if we are of type FIELD
String formatField(DateTime date) {
switch (pattern[0]) {
case 'a':
@@ -379,7 +349,7 @@
}
}
- /** Return the symbols for our current locale. */
+ /// Return the symbols for our current locale.
DateSymbols get symbols => dateTimeSymbols[parent.locale];
formatEra(DateTime date) {
@@ -396,29 +366,25 @@
return width == 2 ? padTo(2, year % 100) : padTo(width, year);
}
- /**
- * We are given [input] as a stream from which we want to read a date. We
- * can't dynamically build up a date, so we are given a list [dateFields] of
- * the constructor arguments and an [position] at which to set it
- * (year,month,day,hour,minute,second,fractionalSecond)
- * then after all parsing is done we construct a date from the arguments.
- * This method handles reading any of the numeric fields. The [offset]
- * argument allows us to compensate for zero-based versus one-based values.
- */
+ /// We are given [input] as a stream from which we want to read a date. We
+ /// can't dynamically build up a date, so we are given a list [dateFields] of
+ /// the constructor arguments and an [position] at which to set it
+ /// (year,month,day,hour,minute,second,fractionalSecond)
+ /// then after all parsing is done we construct a date from the arguments.
+ /// This method handles reading any of the numeric fields. The [offset]
+ /// argument allows us to compensate for zero-based versus one-based values.
void handleNumericField(_Stream input, Function setter, [int offset = 0]) {
var result = input.nextInteger();
if (result == null) throwFormatException(input);
setter(result + offset);
}
- /**
- * We are given [input] as a stream from which we want to read a date. We
- * can't dynamically build up a date, so we are given a list [dateFields] of
- * the constructor arguments and an [position] at which to set it
- * (year,month,day,hour,minute,second,fractionalSecond)
- * then after all parsing is done we construct a date from the arguments.
- * This method handles reading any of string fields from an enumerated set.
- */
+ /// We are given [input] as a stream from which we want to read a date. We
+ /// can't dynamically build up a date, so we are given a list [dateFields] of
+ /// the constructor arguments and an [position] at which to set it
+ /// (year,month,day,hour,minute,second,fractionalSecond)
+ /// then after all parsing is done we construct a date from the arguments.
+ /// This method handles reading any of string fields from an enumerated set.
int parseEnumeratedString(_Stream input, List possibilities) {
var results = new _Stream(possibilities)
.findIndexes((each) => input.peek(each.length) == each);
@@ -587,25 +553,21 @@
String formatDayOfYear(DateTime date) => padTo(width, dayNumberInYear(date));
- /** Return the ordinal day, i.e. the day number in the year. */
+ /// Return the ordinal day, i.e. the day number in the year.
int dayNumberInYear(DateTime date) {
if (date.month == 1) return date.day;
if (date.month == 2) return date.day + 31;
return ordinalDayFromMarchFirst(date) + 59 + (isLeapYear(date) ? 1 : 0);
}
- /**
- * Return the day of the year counting March 1st as 1, after which the
- * number of days per month is constant, so it's easier to calculate.
- * Formula from http://en.wikipedia.org/wiki/Ordinal_date
- */
+ /// Return the day of the year counting March 1st as 1, after which the
+ /// number of days per month is constant, so it's easier to calculate.
+ /// Formula from http://en.wikipedia.org/wiki/Ordinal_date
int ordinalDayFromMarchFirst(DateTime date) =>
((30.6 * date.month) - 91.4).floor() + date.day;
- /**
- * Return true if this is a leap year. Rely on [DateTime] to do the
- * underlying calculation, even though it doesn't expose the test to us.
- */
+ /// Return true if this is a leap year. Rely on [DateTime] to do the
+ /// underlying calculation, even though it doesn't expose the test to us.
bool isLeapYear(DateTime date) {
var feb29 = new DateTime(date.year, 2, 29);
return feb29.month == 2;
@@ -649,10 +611,8 @@
throw new UnimplementedError();
}
- /**
- * Return a string representation of the object padded to the left with
- * zeros. Primarily useful for numbers.
- */
+ /// Return a string representation of the object padded to the left with
+ /// zeros. Primarily useful for numbers.
static String padTo(int width, Object toBePrinted) =>
'$toBePrinted'.padLeft(width, '0');
}
diff --git a/lib/src/intl/date_format_helpers.dart b/lib/src/intl/date_format_helpers.dart
index 6a6e68c..b64a2ac 100644
--- a/lib/src/intl/date_format_helpers.dart
+++ b/lib/src/intl/date_format_helpers.dart
@@ -4,10 +4,8 @@
part of intl;
-/**
- * A class for holding onto the data for a date so that it can be built
- * up incrementally.
- */
+/// A class for holding onto the data for a date so that it can be built
+/// up incrementally.
class _DateBuilder {
// Default the date values to the EPOCH so that there's a valid date
// in case the format doesn't set them.
@@ -47,11 +45,9 @@
get hour24 => pm ? hour + 12 : hour;
- /**
- * Verify that we correspond to a valid date. This will reject out of
- * range values, even if the DateTime constructor would accept them. An
- * invalid message will result in throwing a [FormatException].
- */
+ /// Verify that we correspond to a valid date. This will reject out of
+ /// range values, even if the DateTime constructor would accept them. An
+ /// invalid message will result in throwing a [FormatException].
verify(String s) {
_verify(month, 1, 12, "month", s);
_verify(hour24, 0, 23, "hour", s);
@@ -76,10 +72,8 @@
}
}
- /**
- * Return a date built using our values. If no date portion is set,
- * use the "Epoch" of January 1, 1970.
- */
+ /// Return a date built using our values. If no date portion is set,
+ /// use the "Epoch" of January 1, 1970.
DateTime asDate({retry: true}) {
// TODO(alanknight): Validate the date, especially for things which
// can crash the VM, e.g. large month values.
@@ -101,11 +95,9 @@
}
}
-/**
- * A simple and not particularly general stream class to make parsing
- * dates from strings simpler. It is general enough to operate on either
- * lists or strings.
- */
+/// A simple and not particularly general stream class to make parsing
+/// dates from strings simpler. It is general enough to operate on either
+/// lists or strings.
// TODO(alanknight): With the improvements to the collection libraries
// since this was written we might be able to get rid of it entirely
// in favor of e.g. aString.split('') giving us an iterable of one-character
@@ -121,29 +113,23 @@
next() => contents[index++];
- /**
- * Return the next [howMany] items, or as many as there are remaining.
- * Advance the stream by that many positions.
- */
+ /// Return the next [howMany] items, or as many as there are remaining.
+ /// Advance the stream by that many positions.
read([int howMany = 1]) {
var result = peek(howMany);
index += howMany;
return result;
}
- /**
- * Does the input start with the given string, if we start from the
- * current position.
- */
+ /// Does the input start with the given string, if we start from the
+ /// current position.
bool startsWith(String pattern) {
if (contents is String) return contents.startsWith(pattern, index);
return pattern == peek(pattern.length);
}
- /**
- * Return the next [howMany] items, or as many as there are remaining.
- * Does not modify the stream position.
- */
+ /// Return the next [howMany] items, or as many as there are remaining.
+ /// Does not modify the stream position.
peek([int howMany = 1]) {
var result;
if (contents is String) {
@@ -155,13 +141,11 @@
return result;
}
- /** Return the remaining contents of the stream */
+ /// Return the remaining contents of the stream
rest() => peek(contents.length - index);
- /**
- * Find the index of the first element for which [f] returns true.
- * Advances the stream to that position.
- */
+ /// Find the index of the first element for which [f] returns true.
+ /// Advances the stream to that position.
int findIndex(Function f) {
while (!atEnd()) {
if (f(next())) return index - 1;
@@ -169,10 +153,8 @@
return null;
}
- /**
- * Find the indexes of all the elements for which [f] returns true.
- * Leaves the stream positioned at the end.
- */
+ /// Find the indexes of all the elements for which [f] returns true.
+ /// Leaves the stream positioned at the end.
List findIndexes(Function f) {
var results = [];
while (!atEnd()) {
@@ -181,10 +163,8 @@
return results;
}
- /**
- * Assuming that the contents are characters, read as many digits as we
- * can see and then return the corresponding integer. Advance the stream.
- */
+ /// Assuming that the contents are characters, read as many digits as we
+ /// can see and then return the corresponding integer. Advance the stream.
var digitMatcher = new RegExp(r'\d+');
int nextInteger() {
var string = digitMatcher.stringMatch(rest());
diff --git a/lib/src/intl/number_format.dart b/lib/src/intl/number_format.dart
index 57fa07d..5af03d4 100644
--- a/lib/src/intl/number_format.dart
+++ b/lib/src/intl/number_format.dart
@@ -4,63 +4,56 @@
part of intl;
-/**
- * Provides the ability to format a number in a locale-specific way. The
- * format is specified as a pattern using a subset of the ICU formatting
- * patterns.
- *
- * - `0` A single digit
- * - `#` A single digit, omitted if the value is zero
- * - `.` Decimal separator
- * - `-` Minus sign
- * - `,` Grouping separator
- * - `E` Separates mantissa and expontent
- * - `+` - Before an exponent, indicates it should be prefixed with a plus sign.
- * - `%` - In prefix or suffix, multiply by 100 and show as percentage
- * - `‰ (\u2030)` In prefix or suffix, multiply by 1000 and show as per mille
- * - `¤ (\u00A4)` Currency sign, replaced by currency name
- * - `'` Used to quote special characters
- * - `;` Used to separate the positive and negative patterns if both are present
- *
- * For example,
- * var f = new NumberFormat("###.0#", "en_US");
- * print(f.format(12.345));
- * ==> 12.34
- * If the locale is not specified, it will default to the current locale. If
- * the format is not specified it will print in a basic format with at least
- * one integer digit and three fraction digits.
- *
- * There are also standard patterns available via the special constructors. e.g.
- * var percent = new NumberFormat.percentFormat("ar");
- * var eurosInUSFormat = new NumberFormat.currencyPattern("en_US", "€");
- * There are four such constructors: decimalFormat, percentFormat,
- * scientificFormat and currencyFormat. However, at the moment,
- * scientificFormat prints only as equivalent to "#E0" and does not take
- * into account significant digits. The currencyFormat will default to the
- * three-letter name of the currency if no explicit name/symbol is provided.
- */
+/// Provides the ability to format a number in a locale-specific way. The
+/// format is specified as a pattern using a subset of the ICU formatting
+/// patterns.
+///
+/// - `0` A single digit
+/// - `#` A single digit, omitted if the value is zero
+/// - `.` Decimal separator
+/// - `-` Minus sign
+/// - `,` Grouping separator
+/// - `E` Separates mantissa and expontent
+/// - `+` - Before an exponent, to say it should be prefixed with a plus sign.
+/// - `%` - In prefix or suffix, multiply by 100 and show as percentage
+/// - `‰ (\u2030)` In prefix or suffix, multiply by 1000 and show as per mille
+/// - `¤ (\u00A4)` Currency sign, replaced by currency name
+/// - `'` Used to quote special characters
+/// - `;` Used to separate the positive and negative patterns (if both present)
+///
+/// For example,
+/// var f = new NumberFormat("###.0#", "en_US");
+/// print(f.format(12.345));
+/// ==> 12.34
+/// If the locale is not specified, it will default to the current locale. If
+/// the format is not specified it will print in a basic format with at least
+/// one integer digit and three fraction digits.
+///
+/// There are also standard patterns available via the special constructors.
+/// e.g.
+/// var percent = new NumberFormat.percentFormat("ar");
+/// var eurosInUSFormat = new NumberFormat.currencyPattern("en_US", "€");
+/// There are four such constructors: decimalFormat, percentFormat,
+/// scientificFormat and currencyFormat. However, at the moment,
+/// scientificFormat prints only as equivalent to "#E0" and does not take
+/// into account significant digits. The currencyFormat will default to the
+/// three-letter name of the currency if no explicit name/symbol is provided.
class NumberFormat {
- /** Variables to determine how number printing behaves. */
+ /// Variables to determine how number printing behaves.
// TODO(alanknight): If these remain as variables and are set based on the
// pattern, can we make them final?
String _negativePrefix = '-';
String _positivePrefix = '';
String _negativeSuffix = '';
String _positiveSuffix = '';
- /**
- * How many numbers in a group when using punctuation to group digits in
- * large numbers. e.g. in en_US: "1,000,000" has a grouping size of 3 digits
- * between commas.
- */
+ /// How many numbers in a group when using punctuation to group digits in
+ /// large numbers. e.g. in en_US: "1,000,000" has a grouping size of 3 digits
+ /// between commas.
int _groupingSize = 3;
- /**
- * In some formats the last grouping size may be different than previous
- * ones, e.g. Hindi.
- */
+ /// In some formats the last grouping size may be different than previous
+ /// ones, e.g. Hindi.
int _finalGroupingSize = 3;
- /**
- * Set to true if the format has explicitly set the grouping size.
- */
+ /// Set to true if the format has explicitly set the grouping size.
bool _groupingSizeSetExplicitly = false;
bool _decimalSeparatorAlwaysShown = false;
bool _useSignForPositiveExponent = false;
@@ -72,10 +65,8 @@
int minimumFractionDigits = 0;
int minimumExponentDigits = 0;
- /**
- * For percent and permille, what are we multiplying by in order to
- * get the printed value, e.g. 100 for percent.
- */
+ /// For percent and permille, what are we multiplying by in order to
+ /// get the printed value, e.g. 100 for percent.
int get _multiplier => _internalMultiplier;
set _multiplier(int x) {
_internalMultiplier = x;
@@ -84,65 +75,55 @@
int _internalMultiplier = 1;
- /** How many digits are there in the [_multiplier]. */
+ /// How many digits are there in the [_multiplier].
int _multiplierDigits = 0;
- /**
- * Stores the pattern used to create this format. This isn't used, but
- * is helpful in debugging.
- */
+ /// Stores the pattern used to create this format. This isn't used, but
+ /// is helpful in debugging.
String _pattern;
- /** The locale in which we print numbers. */
+ /// The locale in which we print numbers.
final String _locale;
- /** Caches the symbols used for our locale. */
+ /// Caches the symbols used for our locale.
NumberSymbols _symbols;
- /** The name (or symbol) of the currency to print. */
+ /// The name (or symbol) of the currency to print.
String currencyName;
- /**
- * Transient internal state in which to build up the result of the format
- * operation. We can have this be just an instance variable because Dart is
- * single-threaded and unless we do an asynchronous operation in the process
- * of formatting then there will only ever be one number being formatted
- * at a time. In languages with threads we'd need to pass this on the stack.
- */
+ /// Transient internal state in which to build up the result of the format
+ /// operation. We can have this be just an instance variable because Dart is
+ /// single-threaded and unless we do an asynchronous operation in the process
+ /// of formatting then there will only ever be one number being formatted
+ /// at a time. In languages with threads we'd need to pass this on the stack.
final StringBuffer _buffer = new StringBuffer();
- /**
- * Create a number format that prints using [newPattern] as it applies in
- * [locale].
- */
+ /// Create a number format that prints using [newPattern] as it applies in
+ /// [locale].
factory NumberFormat([String newPattern, String locale]) =>
new NumberFormat._forPattern(locale, (x) => newPattern);
- /** Create a number format that prints as DECIMAL_PATTERN. */
+ /// Create a number format that prints as DECIMAL_PATTERN.
NumberFormat.decimalPattern([String locale])
: this._forPattern(locale, (x) => x.DECIMAL_PATTERN);
- /** Create a number format that prints as PERCENT_PATTERN. */
+ /// Create a number format that prints as PERCENT_PATTERN.
NumberFormat.percentPattern([String locale])
: this._forPattern(locale, (x) => x.PERCENT_PATTERN);
- /** Create a number format that prints as SCIENTIFIC_PATTERN. */
+ /// Create a number format that prints as SCIENTIFIC_PATTERN.
NumberFormat.scientificPattern([String locale])
: this._forPattern(locale, (x) => x.SCIENTIFIC_PATTERN);
- /**
- * Create a number format that prints as CURRENCY_PATTERN. If provided,
- * use [nameOrSymbol] in place of the default currency name. e.g.
- * var eurosInCurrentLocale = new NumberFormat
- * .currencyPattern(Intl.defaultLocale, "€");
- */
+ /// Create a number format that prints as CURRENCY_PATTERN. If provided,
+ /// use [nameOrSymbol] in place of the default currency name. e.g.
+ /// var eurosInCurrentLocale = new NumberFormat
+ /// .currencyPattern(Intl.defaultLocale, "€");
NumberFormat.currencyPattern([String locale, String nameOrSymbol])
: this._forPattern(locale, (x) => x.CURRENCY_PATTERN, nameOrSymbol);
- /**
- * Create a number format that prints in a pattern we get from
- * the [getPattern] function using the locale [locale].
- */
+ /// Create a number format that prints in a pattern we get from
+ /// the [getPattern] function using the locale [locale].
NumberFormat._forPattern(String locale, Function getPattern,
[this.currencyName])
: _locale = Intl.verifiedLocale(locale, localeExists) {
@@ -153,29 +134,21 @@
_setPattern(getPattern(_symbols));
}
- /**
- * Return the locale code in which we operate, e.g. 'en_US' or 'pt'.
- */
+ /// Return the locale code in which we operate, e.g. 'en_US' or 'pt'.
String get locale => _locale;
- /**
- * Return true if the locale exists, or if it is null. The null case
- * is interpreted to mean that we use the default locale.
- */
+ /// Return true if the locale exists, or if it is null. The null case
+ /// is interpreted to mean that we use the default locale.
static bool localeExists(localeName) {
if (localeName == null) return false;
return numberFormatSymbols.containsKey(localeName);
}
- /**
- * Return the symbols which are used in our locale. Cache them to avoid
- * repeated lookup.
- */
+ /// Return the symbols which are used in our locale. Cache them to avoid
+ /// repeated lookup.
NumberSymbols get symbols => _symbols;
- /**
- * Format [number] according to our pattern and return the formatted string.
- */
+ /// Format [number] according to our pattern and return the formatted string.
String format(number) {
if (_isNaN(number)) return symbols.NAN;
if (_isInfinite(number)) return "${_signPrefix(number)}${symbols.INFINITY}";
@@ -189,15 +162,11 @@
return result;
}
- /**
- * Parse the number represented by the string. If it's not
- * parseable, throws a [FormatException].
- */
+ /// Parse the number represented by the string. If it's not
+ /// parseable, throws a [FormatException].
num parse(String text) => new _NumberParser(this, text).value;
- /**
- * Format the main part of the number in the form dictated by the pattern.
- */
+ /// Format the main part of the number in the form dictated by the pattern.
void _formatNumber(number) {
if (_useExponentialNotation) {
_formatExponential(number);
@@ -206,7 +175,7 @@
}
}
- /** Format the number in exponential notation. */
+ /// Format the number in exponential notation.
void _formatExponential(num number) {
if (number == 0.0) {
_formatFixed(number);
@@ -242,9 +211,7 @@
_formatExponent(exponent);
}
- /**
- * Format the exponent portion, e.g. in "1.3e-5" the "e-5".
- */
+ /// Format the exponent portion, e.g. in "1.3e-5" the "e-5".
void _formatExponent(num exponent) {
_add(symbols.EXP_SYMBOL);
if (exponent < 0) {
@@ -256,23 +223,19 @@
_pad(minimumExponentDigits, exponent.toString());
}
- /** Used to test if we have exceeded Javascript integer limits. */
+ /// Used to test if we have exceeded Javascript integer limits.
final _maxInt = pow(2, 52);
- /**
- * Helpers to check numbers that don't conform to the [num] interface,
- * e.g. Int64
- */
+ /// Helpers to check numbers that don't conform to the [num] interface,
+ /// e.g. Int64
_isInfinite(number) => number is num ? number.isInfinite : false;
_isNaN(number) => number is num ? number.isNaN : false;
- /**
- * Helper to get the floor of a number which might not be num. This should
- * only ever be called with an argument which is positive, or whose abs()
- * is negative. The second case is the maximum negative value on a
- * fixed-length integer. Since they are integers, they are also their own
- * floor.
- */
+ /// Helper to get the floor of a number which might not be num. This should
+ /// only ever be called with an argument which is positive, or whose abs()
+ /// is negative. The second case is the maximum negative value on a
+ /// fixed-length integer. Since they are integers, they are also their own
+ /// floor.
_floor(number) {
if (number.isNegative && !(number.abs().isNegative)) {
throw new ArgumentError(
@@ -281,7 +244,7 @@
return (number is num) ? number.floor() : number ~/ 1;
}
- /** Helper to round a number which might not be num.*/
+ /// Helper to round a number which might not be num.
_round(number) {
if (number is num) {
return number.round();
@@ -296,9 +259,7 @@
}
}
- /**
- * Format the basic number portion, including the fractional digits.
- */
+ /// Format the basic number portion, including the fractional digits.
void _formatFixed(number) {
var integerPart;
int fractionPart;
@@ -353,10 +314,8 @@
_formatFractionPart((fractionPart + power).toString());
}
- /**
- * Compute the raw integer digits which will then be printed with
- * grouping and translated to localized digits.
- */
+ /// Compute the raw integer digits which will then be printed with
+ /// grouping and translated to localized digits.
String _integerDigits(integerPart, extraIntegerDigits) {
// If the int part is larger than 2^52 and we're on Javascript (so it's
// really a float) it will lose precision, so pad out the rest of it
@@ -376,11 +335,9 @@
return "${intDigits}${paddedExtra}${paddingDigits}";
}
- /**
- * The digit string of the integer part. This is the empty string if the
- * integer part is zero and otherwise is the toString() of the integer
- * part, stripping off any minus sign.
- */
+ /// The digit string of the integer part. This is the empty string if the
+ /// integer part is zero and otherwise is the toString() of the integer
+ /// part, stripping off any minus sign.
String _mainIntegerDigits(integer) {
if (integer == 0) return '';
var digits = integer.toString();
@@ -390,9 +347,7 @@
return digits.startsWith('-') ? digits.substring(1) : digits;
}
- /**
- * Format the part after the decimal place in a fixed point number.
- */
+ /// Format the part after the decimal place in a fixed point number.
void _formatFractionPart(String fractionPart) {
var fractionCodes = fractionPart.codeUnits;
var fractionLength = fractionPart.length;
@@ -405,25 +360,22 @@
}
}
- /** Print the decimal separator if appropriate. */
+ /// Print the decimal separator if appropriate.
void _decimalSeparator(bool fractionPresent) {
if (_decimalSeparatorAlwaysShown || fractionPresent) {
_add(symbols.DECIMAL_SEP);
}
}
- /**
- * Return true if we have a main integer part which is printable, either
- * because we have digits left of the decimal point (this may include digits
- * which have been moved left because of percent or permille formatting),
- * or because the minimum number of printable digits is greater than 1.
- */
+ /// Return true if we have a main integer part which is printable, either
+ /// because we have digits left of the decimal point (this may include digits
+ /// which have been moved left because of percent or permille formatting),
+ /// or because the minimum number of printable digits is greater than 1.
bool _hasIntegerDigits(String digits) =>
digits.isNotEmpty || minimumIntegerDigits > 0;
- /** A group of methods that provide support for writing digits and other
- * required characters into [_buffer] easily.
- */
+ /// A group of methods that provide support for writing digits and other
+ /// required characters into [_buffer] easily.
void _add(String x) {
_buffer.write(x);
}
@@ -436,7 +388,7 @@
_buffer.writeCharCode(_localeZero + x - _zero);
}
- /** Print padding up to [numberOfDigits] above what's included in [basic]. */
+ /// Print padding up to [numberOfDigits] above what's included in [basic].
void _pad(int numberOfDigits, [String basic = '']) {
for (var i = 0; i < numberOfDigits - basic.length; i++) {
_add(symbols.ZERO_DIGIT);
@@ -446,14 +398,12 @@
}
}
- /**
- * We are printing the digits of the number from left to right. We may need
- * to print a thousands separator or other grouping character as appropriate
- * to the locale. So we find how many places we are from the end of the number
- * by subtracting our current [position] from the [totalLength] and printing
- * the separator character every [_groupingSize] digits, with the final
- * grouping possibly being of a different size, [_finalGroupingSize].
- */
+ /// We are printing the digits of the number from left to right. We may need
+ /// to print a thousands separator or other grouping character as appropriate
+ /// to the locale. So we find how many places we are from the end of the number
+ /// by subtracting our current [position] from the [totalLength] and printing
+ /// the separator character every [_groupingSize] digits, with the final
+ /// grouping possibly being of a different size, [_finalGroupingSize].
void _group(int totalLength, int position) {
var distanceFromEnd = totalLength - position;
if (distanceFromEnd <= 1 || _groupingSize <= 0) return;
@@ -465,26 +415,22 @@
}
}
- /** Returns the code point for the character '0'. */
+ /// Returns the code point for the character '0'.
final _zero = '0'.codeUnits.first;
- /** Returns the code point for the locale's zero digit. */
+ /// Returns the code point for the locale's zero digit.
// Note that there is a slight risk of a locale's zero digit not fitting
// into a single code unit, but it seems very unlikely, and if it did,
// there's a pretty good chance that our assumptions about being able to do
// arithmetic on it would also be invalid.
get _localeZero => symbols.ZERO_DIGIT.codeUnits.first;
- /**
- * Returns the prefix for [x] based on whether it's positive or negative.
- * In en_US this would be '' and '-' respectively.
- */
+ /// Returns the prefix for [x] based on whether it's positive or negative.
+ /// In en_US this would be '' and '-' respectively.
String _signPrefix(x) => x.isNegative ? _negativePrefix : _positivePrefix;
- /**
- * Returns the suffix for [x] based on wether it's positive or negative.
- * In en_US there are no suffixes for positive or negative.
- */
+ /// Returns the suffix for [x] based on wether it's positive or negative.
+ /// In en_US there are no suffixes for positive or negative.
String _signSuffix(x) => x.isNegative ? _negativeSuffix : _positiveSuffix;
void _setPattern(String newPattern) {
@@ -498,63 +444,51 @@
String toString() => "NumberFormat($_locale, $_pattern)";
}
-/**
- * A one-time object for parsing a particular numeric string. One-time here
- * means an instance can only parse one string. This is implemented by
- * transforming from a locale-specific format to one that the system can parse,
- * then calls the system parsing methods on it.
- */
+/// A one-time object for parsing a particular numeric string. One-time here
+/// means an instance can only parse one string. This is implemented by
+/// transforming from a locale-specific format to one that the system can parse,
+/// then calls the system parsing methods on it.
class _NumberParser {
- /** The format for which we are parsing. */
+ /// The format for which we are parsing.
final NumberFormat format;
- /** The text we are parsing. */
+ /// The text we are parsing.
final String text;
- /** What we use to iterate over the input text. */
+ /// What we use to iterate over the input text.
final _Stream input;
- /**
- * The result of parsing [text] according to [format]. Automatically
- * populated in the constructor.
- */
+ /// The result of parsing [text] according to [format]. Automatically
+ /// populated in the constructor.
num value;
- /** The symbols used by our format. */
+ /// The symbols used by our format.
NumberSymbols get symbols => format.symbols;
- /** Where we accumulate the normalized representation of the number. */
+ /// Where we accumulate the normalized representation of the number.
final StringBuffer _normalized = new StringBuffer();
- /**
- * Did we see something that indicates this is, or at least might be,
- * a positive number.
- */
+ /// Did we see something that indicates this is, or at least might be,
+ /// a positive number.
bool gotPositive = false;
- /**
- * Did we see something that indicates this is, or at least might be,
- * a negative number.
- */
+ /// Did we see something that indicates this is, or at least might be,
+ /// a negative number.
bool gotNegative = false;
- /**
- * Did we see the required positive suffix at the end. Should
- * match [gotPositive].
- */
+ /// Did we see the required positive suffix at the end. Should
+ /// match [gotPositive].
bool gotPositiveSuffix = false;
- /**
- * Did we see the required negative suffix at the end. Should
- * match [gotNegative].
- */
+ /// Did we see the required negative suffix at the end. Should
+ /// match [gotNegative].
bool gotNegativeSuffix = false;
- /** Should we stop parsing before hitting the end of the string. */
+ /// Should we stop parsing before hitting the end of the string.
bool done = false;
- /** Have we already skipped over any required prefixes. */
+ /// Have we already skipped over any required prefixes.
bool prefixesSkipped = false;
- /** If the number is percent or permill, what do we divide by at the end. */
+ /// If the number is percent or permill, what do we divide by at the end.
int scale = 1;
String get _positivePrefix => format._positivePrefix;
@@ -564,22 +498,18 @@
int get _zero => format._zero;
int get _localeZero => format._localeZero;
- /**
- * Create a new [_NumberParser] on which we can call parse().
- */
+ /// Create a new [_NumberParser] on which we can call parse().
_NumberParser(this.format, text)
: this.text = text,
this.input = new _Stream(text) {
value = parse();
}
- /**
- * The strings we might replace with functions that return the replacement
- * values. They are functions because we might need to check something
- * in the context. Note that the ordering is important here. For example,
- * [symbols.PERCENT] might be " %", and we must handle that before we
- * look at an individual space.
- */
+ /// The strings we might replace with functions that return the replacement
+ /// values. They are functions because we might need to check something
+ /// in the context. Note that the ordering is important here. For example,
+ /// [symbols.PERCENT] might be " %", and we must handle that before we
+ /// look at an individual space.
Map<String, Function> get replacements => _replacements == null
? _replacements = _initializeReplacements()
: _replacements;
@@ -607,28 +537,23 @@
invalidFormat() =>
throw new FormatException("Invalid number: ${input.contents}");
- /**
- * Replace a space in the number with the normalized form. If space is not
- * a significant character (normally grouping) then it's just invalid. If it
- * is the grouping character, then it's only valid if it's followed by a
- * digit. e.g. '$12 345.00'
- */
+ /// Replace a space in the number with the normalized form. If space is not
+ /// a significant character (normally grouping) then it's just invalid. If it
+ /// is the grouping character, then it's only valid if it's followed by a
+ /// digit. e.g. '$12 345.00'
handleSpace() =>
groupingIsNotASpaceOrElseItIsSpaceFollowedByADigit ? '' : invalidFormat();
- /**
- * Determine if a space is a valid character in the number. See [handleSpace].
- */
+ /// Determine if a space is a valid character in the number. See
+ /// [handleSpace].
bool get groupingIsNotASpaceOrElseItIsSpaceFollowedByADigit {
if (symbols.GROUP_SEP != '\u00a0' || symbols.GROUP_SEP != ' ') return true;
var peeked = input.peek(symbols.GROUP_SEP.length + 1);
return asDigit(peeked[peeked.length - 1]) != null;
}
- /**
- * Turn [char] into a number representing a digit, or null if it doesn't
- * represent a digit in this locale.
- */
+ /// Turn [char] into a number representing a digit, or null if it doesn't
+ /// represent a digit in this locale.
int asDigit(String char) {
var charCode = char.codeUnitAt(0);
var digitValue = charCode - _localeZero;
@@ -639,10 +564,8 @@
}
}
- /**
- * Check to see if the input begins with either the positive or negative
- * prefixes. Set the [gotPositive] and [gotNegative] variables accordingly.
- */
+ /// Check to see if the input begins with either the positive or negative
+ /// prefixes. Set the [gotPositive] and [gotNegative] variables accordingly.
void checkPrefixes({bool skip: false}) {
bool checkPrefix(String prefix, skip) {
var matched = prefix.isNotEmpty && input.startsWith(prefix);
@@ -667,22 +590,18 @@
}
}
- /**
- * If the rest of our input is either the positive or negative suffix,
- * set [gotPositiveSuffix] or [gotNegativeSuffix] accordingly.
- */
+ /// If the rest of our input is either the positive or negative suffix,
+ /// set [gotPositiveSuffix] or [gotNegativeSuffix] accordingly.
void checkSuffixes() {
var remainder = input.rest();
if (remainder == _positiveSuffix) gotPositiveSuffix = true;
if (remainder == _negativeSuffix) gotNegativeSuffix = true;
}
- /**
- * We've encountered a character that's not a digit. Go through our
- * replacement rules looking for how to handle it. If we see something
- * that's not a digit and doesn't have a replacement, then we're done
- * and the number is probably invalid.
- */
+ /// We've encountered a character that's not a digit. Go through our
+ /// replacement rules looking for how to handle it. If we see something
+ /// that's not a digit and doesn't have a replacement, then we're done
+ /// and the number is probably invalid.
void processNonDigit() {
for (var key in replacements.keys) {
if (input.startsWith(key)) {
@@ -702,10 +621,8 @@
}
}
- /**
- * Parse [text] and return the resulting number. Throws [FormatException]
- * if we can't parse it.
- */
+ /// Parse [text] and return the resulting number. Throws [FormatException]
+ /// if we can't parse it.
num parse() {
if (text == symbols.NAN) return double.NAN;
if (text == "$_positivePrefix${symbols.INFINITY}$_positiveSuffix") {
@@ -725,14 +642,12 @@
return parsed;
}
- /** The number is invalid, throw a [FormatException]. */
+ /// The number is invalid, throw a [FormatException].
void invalidNumber() =>
throw new FormatException("Invalid Number: ${input.contents}");
- /**
- * Parse the number portion of the input, i.e. not any prefixes or suffixes,
- * and assuming NaN and Infinity are already handled.
- */
+ /// Parse the number portion of the input, i.e. not any prefixes or suffixes,
+ /// and assuming NaN and Infinity are already handled.
num parseNumber(_Stream input) {
while (!done && !input.atEnd()) {
int digit = asDigit(input.peek());
@@ -752,17 +667,13 @@
}
}
-/**
- * Private class that parses the numeric formatting pattern and sets the
- * variables in [format] to appropriate values. Instances of this are
- * transient and store parsing state in instance variables, so can only be used
- * to parse a single pattern.
- */
+/// Private class that parses the numeric formatting pattern and sets the
+/// variables in [format] to appropriate values. Instances of this are
+/// transient and store parsing state in instance variables, so can only be used
+/// to parse a single pattern.
class _NumberFormatParser {
- /**
- * The special characters in the pattern language. All others are treated
- * as literals.
- */
+ /// The special characters in the pattern language. All others are treated
+ /// as literals.
static const _PATTERN_SEPARATOR = ';';
static const _QUOTE = "'";
static const _PATTERN_DIGIT = '#';
@@ -777,28 +688,26 @@
static const _PATTERN_EXPONENT = 'E';
static const _PATTERN_PLUS = '+';
- /** The format whose state we are setting. */
+ /// The format whose state we are setting.
final NumberFormat format;
- /** The pattern we are parsing. */
+ /// The pattern we are parsing.
final _StringIterator pattern;
- /** We can be passed a specific currency symbol, regardless of the locale. */
+ /// We can be passed a specific currency symbol, regardless of the locale.
String currencyName;
- /**
- * Create a new [_NumberFormatParser] for a particular [NumberFormat] and
- * [input] pattern.
- */
+ /// Create a new [_NumberFormatParser] for a particular [NumberFormat] and
+ /// [input] pattern.
_NumberFormatParser(this.format, input, this.currencyName)
: pattern = _iterator(input) {
pattern.moveNext();
}
- /** The [NumberSymbols] for the locale in which our [format] prints. */
+ /// The [NumberSymbols] for the locale in which our [format] prints.
NumberSymbols get symbols => format.symbols;
- /** Parse the input pattern and set the values. */
+ /// Parse the input pattern and set the values.
void parse() {
format._positivePrefix = _parseAffix();
var trunk = _parseTrunk();
@@ -825,16 +734,12 @@
}
}
- /**
- * Variable used in parsing prefixes and suffixes to keep track of
- * whether or not we are in a quoted region.
- */
+ /// Variable used in parsing prefixes and suffixes to keep track of
+ /// whether or not we are in a quoted region.
bool inQuote = false;
- /**
- * Parse a prefix or suffix and return the prefix/suffix string. Note that
- * this also may modify the state of [format].
- */
+ /// Parse a prefix or suffix and return the prefix/suffix string. Note that
+ /// this also may modify the state of [format].
String _parseAffix() {
var affix = new StringBuffer();
inQuote = false;
@@ -842,11 +747,9 @@
return affix.toString();
}
- /**
- * Parse an individual character as part of a prefix or suffix. Return true
- * if we should continue to look for more affix characters, and false if
- * we have reached the end.
- */
+ /// Parse an individual character as part of a prefix or suffix. Return true
+ /// if we should continue to look for more affix characters, and false if
+ /// we have reached the end.
bool parseCharacterAffix(StringBuffer affix) {
var ch = pattern.current;
if (ch == null) return false;
@@ -896,17 +799,15 @@
return true;
}
- /** Variables used in [_parseTrunk] and [parseTrunkCharacter]. */
+ /// Variables used in [_parseTrunk] and [parseTrunkCharacter].
var decimalPos = -1;
var digitLeftCount = 0;
var zeroDigitCount = 0;
var digitRightCount = 0;
var groupingCount = -1;
- /**
- * Parse the "trunk" portion of the pattern, the piece that doesn't include
- * positive or negative prefixes or suffixes.
- */
+ /// Parse the "trunk" portion of the pattern, the piece that doesn't include
+ /// positive or negative prefixes or suffixes.
String _parseTrunk() {
var loop = true;
var trunk = new StringBuffer();
@@ -969,11 +870,9 @@
return trunk.toString();
}
- /**
- * Parse an individual character of the trunk. Return true if we should
- * continue to look for additional trunk characters or false if we have
- * reached the end.
- */
+ /// Parse an individual character of the trunk. Return true if we should
+ /// continue to look for additional trunk characters or false if we have
+ /// reached the end.
bool parseTrunkCharacter(trunk) {
var ch = pattern.current;
switch (ch) {
@@ -1051,31 +950,23 @@
}
}
-/**
- * Returns an [Iterable] on the string as a list of substrings.
- */
+/// Returns an [Iterable] on the string as a list of substrings.
Iterable _iterable(String s) => new _StringIterable(s);
-/**
- * Return an iterator on the string as a list of substrings.
- */
+/// Return an iterator on the string as a list of substrings.
Iterator _iterator(String s) => new _StringIterator(s);
// TODO(nweiz): remove this when issue 3780 is fixed.
-/**
- * Provides an Iterable that wraps [_iterator] so it can be used in a `for`
- * loop.
- */
+/// Provides an Iterable that wraps [_iterator] so it can be used in a `for`
+/// loop.
class _StringIterable extends IterableBase<String> {
final Iterator<String> iterator;
_StringIterable(String s) : iterator = _iterator(s);
}
-/**
- * Provides an iterator over a string as a list of substrings, and also
- * gives us a lookahead of one via the [peek] method.
- */
+/// Provides an iterator over a string as a list of substrings, and also
+/// gives us a lookahead of one via the [peek] method.
class _StringIterator implements Iterator<String> {
final String input;
int nextIndex = 0;
diff --git a/lib/src/intl_helpers.dart b/lib/src/intl_helpers.dart
index bf085a7..a5b138f 100644
--- a/lib/src/intl_helpers.dart
+++ b/lib/src/intl_helpers.dart
@@ -2,20 +2,16 @@
// 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 library for general helper code associated with the intl library
- * rather than confined to specific parts of it.
- */
+/// A library for general helper code associated with the intl library
+/// rather than confined to specific parts of it.
library intl_helpers;
import 'dart:async';
-/**
- * This is used as a marker for a locale data map that hasn't been initialized,
- * and will throw an exception on any usage that isn't the fallback
- * patterns/symbols provided.
- */
+/// This is used as a marker for a locale data map that hasn't been initialized,
+/// and will throw an exception on any usage that isn't the fallback
+/// patterns/symbols provided.
class UninitializedLocaleData<F> {
final String message;
final F fallbackData;
@@ -43,26 +39,20 @@
toString() => "LocaleDataException: $message";
}
-/**
- * An abstract superclass for data readers to keep the type system happy.
- */
+/// An abstract superclass for data readers to keep the type system happy.
abstract class LocaleDataReader {
Future read(String locale);
}
-/**
- * The internal mechanism for looking up messages. We expect this to be set
- * by the implementing package so that we're not dependent on its
- * implementation.
- */
+/// The internal mechanism for looking up messages. We expect this to be set
+/// by the implementing package so that we're not dependent on its
+/// implementation.
var messageLookup =
const UninitializedLocaleData('initializeMessages(<locale>)', null);
-/**
- * Initialize the message lookup mechanism. This is for internal use only.
- * User applications should import `message_lookup_by_library.dart` and call
- * `initializeMessages`
- */
+/// Initialize the message lookup mechanism. This is for internal use only.
+/// User applications should import `message_lookup_by_library.dart` and call
+/// `initializeMessages`
void initializeInternalMessageLookup(Function lookupFunction) {
if (messageLookup is UninitializedLocaleData) {
messageLookup = lookupFunction();
diff --git a/lib/src/intl_message.dart b/lib/src/intl_message.dart
index 3d25967..8800a98 100644
--- a/lib/src/intl_message.dart
+++ b/lib/src/intl_message.dart
@@ -2,75 +2,63 @@
// 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 provides classes to represent the internal structure of the
- * arguments to `Intl.message`. It is used when parsing sources to extract
- * messages or to generate code for message substitution. Normal programs
- * using Intl would not import this library.
- *
- * While it's written
- * in a somewhat abstract way, it has some assumptions about ICU-style
- * message syntax for parameter substitutions, choices, selects, etc.
- *
- * For example, if we have the message
- * plurals(num) => Intl.message("""${Intl.plural(num,
- * zero : 'Is zero plural?',
- * one : 'This is singular.',
- * other : 'This is plural ($num).')
- * }""",
- * name: "plurals", args: [num], desc: "Basic plurals");
- * That is represented as a MainMessage which has only one message component, a
- * Plural, but also has a name, list of arguments, and a description.
- * The Plural has three different clauses. The `zero` clause is
- * a LiteralString containing 'Is zero plural?'. The `other` clause is a
- * CompositeMessage containing three pieces, a LiteralString for
- * 'This is plural (', a VariableSubstitution for `num`. amd a LiteralString
- * for '.)'.
- *
- * This representation isn't used at runtime. Rather, we read some format
- * from a translation file, parse it into these objects, and they are then
- * used to generate the code representation above.
- */
+/// This provides classes to represent the internal structure of the
+/// arguments to `Intl.message`. It is used when parsing sources to extract
+/// messages or to generate code for message substitution. Normal programs
+/// using Intl would not import this library.
+///
+/// While it's written
+/// in a somewhat abstract way, it has some assumptions about ICU-style
+/// message syntax for parameter substitutions, choices, selects, etc.
+///
+/// For example, if we have the message
+/// plurals(num) => Intl.message("""${Intl.plural(num,
+/// zero : 'Is zero plural?',
+/// one : 'This is singular.',
+/// other : 'This is plural ($num).')
+/// }""",
+/// name: "plurals", args: [num], desc: "Basic plurals");
+/// That is represented as a MainMessage which has only one message component, a
+/// Plural, but also has a name, list of arguments, and a description.
+/// The Plural has three different clauses. The `zero` clause is
+/// a LiteralString containing 'Is zero plural?'. The `other` clause is a
+/// CompositeMessage containing three pieces, a LiteralString for
+/// 'This is plural (', a VariableSubstitution for `num`. amd a LiteralString
+/// for '.)'.
+///
+/// This representation isn't used at runtime. Rather, we read some format
+/// from a translation file, parse it into these objects, and they are then
+/// used to generate the code representation above.
library intl_message;
import 'package:analyzer/analyzer.dart';
-/** A default function for the [Message.expanded] method. */
+/// A default function for the [Message.expanded] method.
_nullTransform(msg, chunk) => chunk;
-/**
- * An abstract superclass for Intl.message/plural/gender calls in the
- * program's source text. We
- * assemble these into objects that can be used to write out some translation
- * format and can also print themselves into code.
- */
+/// An abstract superclass for Intl.message/plural/gender calls in the
+/// program's source text. We
+/// assemble these into objects that can be used to write out some translation
+/// format and can also print themselves into code.
abstract class Message {
- /**
- * All [Message]s except a [MainMessage] are contained inside some parent,
- * terminating at an Intl.message call which supplies the arguments we
- * use for variable substitutions.
- */
+ /// All [Message]s except a [MainMessage] are contained inside some parent,
+ /// terminating at an Intl.message call which supplies the arguments we
+ /// use for variable substitutions.
Message parent;
Message(this.parent);
- /**
- * We find the arguments from the top-level [MainMessage] and use those to
- * do variable substitutions. [MainMessage] overrides this to return
- * the actual arguments.
- */
+ /// We find the arguments from the top-level [MainMessage] and use those to
+ /// do variable substitutions. [MainMessage] overrides this to return
+ /// the actual arguments.
get arguments => parent == null ? const [] : parent.arguments;
- /**
- * We find the examples from the top-level [MainMessage] and use those
- * when writing out variables. [MainMessage] overrides this to return
- * the actual examples.
- */
+ /// We find the examples from the top-level [MainMessage] and use those
+ /// when writing out variables. [MainMessage] overrides this to return
+ /// the actual examples.
get examples => parent == null ? const [] : parent.examples;
- /**
- * The name of the top-level [MainMessage].
- */
+ /// The name of the top-level [MainMessage].
String get name => parent == null ? '<unnamed>' : parent.name;
static final _evaluator = new ConstantEvaluator();
@@ -133,13 +121,11 @@
return null;
}
- /**
- * Turn a value, typically read from a translation file or created out of an
- * AST for a source program, into the appropriate
- * subclass. We expect to get literal Strings, variable substitutions
- * represented by integers, things that are already MessageChunks and
- * lists of the same.
- */
+ /// Turn a value, typically read from a translation file or created out of an
+ /// AST for a source program, into the appropriate
+ /// subclass. We expect to get literal Strings, variable substitutions
+ /// represented by integers, things that are already MessageChunks and
+ /// lists of the same.
static Message from(value, Message parent) {
if (value is String) return new LiteralString(value, parent);
if (value is int) return new VariableSubstitution(value, parent);
@@ -155,18 +141,14 @@
return value;
}
- /**
- * Return a string representation of this message for use in generated Dart
- * code.
- */
+ /// Return a string representation of this message for use in generated Dart
+ /// code.
String toCode();
- /**
- * Escape the string for use in generated Dart code and validate that it
- * doesn't doesn't contain any illegal interpolations. We only allow
- * simple variables ("$foo", but not "${foo}") and Intl.gender/plural
- * calls.
- */
+ /// Escape the string for use in generated Dart code and validate that it
+ /// doesn't doesn't contain any illegal interpolations. We only allow
+ /// simple variables ("$foo", but not "${foo}") and Intl.gender/plural
+ /// calls.
String escapeAndValidateString(String value) {
const escapes = const {
r"\": r"\\",
@@ -201,54 +183,42 @@
return escaped.replaceAllMapped("\$", escapeInvalidMatches);
}
- /**
- * Expand this string out into a printed form. The function [f] will be
- * applied to any sub-messages, allowing this to be used to generate a form
- * suitable for a wide variety of translation file formats.
- */
+ /// Expand this string out into a printed form. The function [f] will be
+ /// applied to any sub-messages, allowing this to be used to generate a form
+ /// suitable for a wide variety of translation file formats.
String expanded([Function f]);
}
-/**
- * Abstract class for messages with internal structure, representing the
- * main Intl.message call, plurals, and genders.
- */
+/// Abstract class for messages with internal structure, representing the
+/// main Intl.message call, plurals, and genders.
abstract class ComplexMessage extends Message {
ComplexMessage(parent) : super(parent);
- /**
- * When we create these from strings or from AST nodes, we want to look up and
- * set their attributes by string names, so we override the indexing operators
- * so that they behave like maps with respect to those attribute names.
- */
+ /// When we create these from strings or from AST nodes, we want to look up
+ /// and set their attributes by string names, so we override the indexing
+ /// operators so that they behave like maps with respect to those attribute
+ /// names.
operator [](x);
- /**
- * When we create these from strings or from AST nodes, we want to look up and
- * set their attributes by string names, so we override the indexing operators
- * so that they behave like maps with respect to those attribute names.
- */
+ /// When we create these from strings or from AST nodes, we want to look up
+ /// and set their attributes by string names, so we override the indexing
+ /// operators so that they behave like maps with respect to those attribute
+ /// names.
operator []=(x, y);
List<String> get attributeNames;
- /**
- * Return the name of the message type, as it will be generated into an
- * ICU-type format. e.g. choice, select
- */
+ /// Return the name of the message type, as it will be generated into an
+ /// ICU-type format. e.g. choice, select
String get icuMessageName;
- /**
- * Return the message name we would use for this when doing Dart code
- * generation, e.g. "Intl.plural".
- */
+ /// Return the message name we would use for this when doing Dart code
+ /// generation, e.g. "Intl.plural".
String get dartMessageName;
}
-/**
- * This represents a message chunk that is a list of multiple sub-pieces,
- * each of which is in turn a [Message].
- */
+/// This represents a message chunk that is a list of multiple sub-pieces,
+/// each of which is in turn a [Message].
class CompositeMessage extends Message {
List<Message> pieces;
@@ -262,7 +232,7 @@
pieces.map((chunk) => f(this, chunk)).join("");
}
-/** Represents a simple constant string with no dynamic elements. */
+/// Represents a simple constant string with no dynamic elements.
class LiteralString extends Message {
String string;
LiteralString(this.string, Message parent) : super(parent);
@@ -271,26 +241,22 @@
String expanded([Function f = _nullTransform]) => f(this, string);
}
-/**
- * Represents an interpolation of a variable value in a message. We expect
- * this to be specified as an [index] into the list of variables, or else
- * as the name of a variable that exists in [arguments] and we will
- * compute the variable name or the index based on the value of the other.
- */
+/// Represents an interpolation of a variable value in a message. We expect
+/// this to be specified as an [index] into the list of variables, or else
+/// as the name of a variable that exists in [arguments] and we will
+/// compute the variable name or the index based on the value of the other.
class VariableSubstitution extends Message {
VariableSubstitution(this._index, Message parent) : super(parent);
- /**
- * Create a substitution based on the name rather than the index. The name
- * may have been used as all upper-case in the translation tool, so we
- * save it separately and look it up case-insensitively once the parent
- * (and its arguments) are definitely available.
- */
+ /// Create a substitution based on the name rather than the index. The name
+ /// may have been used as all upper-case in the translation tool, so we
+ /// save it separately and look it up case-insensitively once the parent
+ /// (and its arguments) are definitely available.
VariableSubstitution.named(String name, Message parent) : super(parent) {
_variableNameUpper = name.toUpperCase();
}
- /** The index in the list of parameters of the containing function. */
+ /// The index in the list of parameters of the containing function.
int _index;
int get index {
if (_index != null) return _index;
@@ -310,16 +276,12 @@
return _index;
}
- /**
- * The variable name we get from parsing. This may be an all uppercase version
- * of the Dart argument name.
- */
+ /// The variable name we get from parsing. This may be an all uppercase
+ /// version of the Dart argument name.
String _variableNameUpper;
- /**
- * The name of the variable in the parameter list of the containing function.
- * Used when generating code for the interpolation.
- */
+ /// The name of the variable in the parameter list of the containing function.
+ /// Used when generating code for the interpolation.
String get variableName =>
_variableName == null ? _variableName = arguments[index] : _variableName;
String _variableName;
@@ -334,14 +296,12 @@
class MainMessage extends ComplexMessage {
MainMessage() : super(null);
- /**
- * All the pieces of the message. When we go to print, these will
- * all be expanded appropriately. The exact form depends on what we're
- * printing it for See [expanded], [toCode].
- */
+ /// All the pieces of the message. When we go to print, these will
+ /// all be expanded appropriately. The exact form depends on what we're
+ /// printing it for See [expanded], [toCode].
List<Message> messagePieces = [];
- /** Verify that this looks like a correct Intl.message invocation. */
+ /// Verify that this looks like a correct Intl.message invocation.
String checkValidity(MethodInvocation node, List arguments, String outerName,
FormalParameterList outerArgs) {
if (arguments.first is! StringLiteral) {
@@ -357,44 +317,34 @@
}
}
- /** The description provided in the Intl.message call. */
+ /// The description provided in the Intl.message call.
String description;
- /** The examples from the Intl.message call */
+ /// The examples from the Intl.message call
Map<String, dynamic> examples;
- /**
- * A field to disambiguate two messages that might have exactly the
- * same text. The two messages will also need different names, but
- * this can be used by machine translation tools to distinguish them.
- */
+ /// A field to disambiguate two messages that might have exactly the
+ /// same text. The two messages will also need different names, but
+ /// this can be used by machine translation tools to distinguish them.
String meaning;
- /**
- * The name, which may come from the function name, from the arguments
- * to Intl.message, or we may just re-use the message.
- */
+ /// The name, which may come from the function name, from the arguments
+ /// to Intl.message, or we may just re-use the message.
String _name;
- /**
- * A placeholder for any other identifier that the translation format
- * may want to use.
- */
+ /// A placeholder for any other identifier that the translation format
+ /// may want to use.
String id;
- /** The arguments list from the Intl.message call. */
+ /// The arguments list from the Intl.message call.
List arguments;
- /**
- * When generating code, we store translations for each locale
- * associated with the original message.
- */
+ /// When generating code, we store translations for each locale
+ /// associated with the original message.
Map<String, String> translations = new Map();
- /**
- * If the message was not given a name, we use the entire message string as
- * the name.
- */
+ /// If the message was not given a name, we use the entire message string as
+ /// the name.
String get name => _name == null ? computeName() : _name;
set name(String newName) {
_name = newName;
@@ -402,20 +352,16 @@
String computeName() => name = expanded((msg, chunk) => "");
- /**
- * Return the full message, with any interpolation expressions transformed
- * by [f] and all the results concatenated. The chunk argument to [f] may be
- * either a String, an int or an object representing a more complex
- * message entity.
- * See [messagePieces].
- */
+ /// Return the full message, with any interpolation expressions transformed
+ /// by [f] and all the results concatenated. The chunk argument to [f] may be
+ /// either a String, an int or an object representing a more complex
+ /// message entity.
+ /// See [messagePieces].
String expanded([Function f = _nullTransform]) =>
messagePieces.map((chunk) => f(this, chunk)).join("");
- /**
- * Record the translation for this message in the given locale, after
- * suitably escaping it.
- */
+ /// Record the translation for this message in the given locale, after
+ /// suitably escaping it.
void addTranslation(String locale, Message translated) {
translated.parent = this;
translations[locale] = translated.toCode();
@@ -424,10 +370,8 @@
toCode() =>
throw new UnsupportedError("MainMessage.toCode requires a locale");
- /**
- * Generate code for this message, expecting it to be part of a map
- * keyed by name with values the function that calls Intl.message.
- */
+ /// Generate code for this message, expecting it to be part of a map
+ /// keyed by name with values the function that calls Intl.message.
String toCodeForLocale(String locale) {
var out = new StringBuffer()
..write('static $name(')
@@ -438,10 +382,8 @@
return out.toString();
}
- /**
- * The AST node will have the attribute names as strings, so we translate
- * between those and the fields of the class.
- */
+ /// The AST node will have the attribute names as strings, so we translate
+ /// between those and the fields of the class.
void operator []=(attributeName, value) {
switch (attributeName) {
case "desc":
@@ -465,10 +407,8 @@
}
}
- /**
- * The AST node will have the attribute names as strings, so we translate
- * between those and the fields of the class.
- */
+ /// The AST node will have the attribute names as strings, so we translate
+ /// between those and the fields of the class.
operator [](attributeName) {
switch (attributeName) {
case "desc":
@@ -493,25 +433,21 @@
get dartMessageName => "message";
- /** The parameters that the Intl.message call may provide. */
+ /// The parameters that the Intl.message call may provide.
get attributeNames => const ["name", "desc", "examples", "args", "meaning"];
String toString() =>
"Intl.message(${expanded()}, $name, $description, $examples, $arguments)";
}
-/**
- * An abstract class to represent sub-sections of a message, primarily
- * plurals and genders.
- */
+/// An abstract class to represent sub-sections of a message, primarily
+/// plurals and genders.
abstract class SubMessage extends ComplexMessage {
SubMessage() : super(null);
- /**
- * Creates the sub-message, given a list of [clauses] in the sort of form
- * that we're likely to get them from parsing a translation file format,
- * as a list of [key, value] where value may in turn be a list.
- */
+ /// Creates the sub-message, given a list of [clauses] in the sort of form
+ /// that we're likely to get them from parsing a translation file format,
+ /// as a list of [key, value] where value may in turn be a list.
SubMessage.from(this.mainArgument, List clauses, parent) : super(parent) {
for (var clause in clauses) {
this[clause.first] = (clause.last is List) ? clause.last : [clause.last];
@@ -520,16 +456,12 @@
toString() => expanded();
- /**
- * The name of the main argument, which is expected to have the value
- * which is one of [attributeNames] and is used to decide which clause to use.
- */
+ /// The name of the main argument, which is expected to have the value which
+ /// is one of [attributeNames] and is used to decide which clause to use.
String mainArgument;
- /**
- * Return the arguments that affect this SubMessage as a map of
- * argument names and values.
- */
+ /// Return the arguments that affect this SubMessage as a map of
+ /// argument names and values.
Map argumentsOfInterestFor(MethodInvocation node) {
var basicArguments = node.argumentList.arguments;
var others = basicArguments.where((each) => each is NamedExpression);
@@ -538,11 +470,9 @@
value: (node) => node.expression);
}
- /**
- * Return the list of attribute names to use when generating code. This
- * may be different from [attributeNames] if there are multiple aliases
- * that map to the same clause.
- */
+ /// Return the list of attribute names to use when generating code. This
+ /// may be different from [attributeNames] if there are multiple aliases
+ /// that map to the same clause.
List<String> get codeAttributeNames;
String expanded([Function transform = _nullTransform]) {
@@ -569,19 +499,15 @@
}
}
-/**
- * Represents a message send of [Intl.gender] inside a message that is to
- * be internationalized. This corresponds to an ICU message syntax "select"
- * with "male", "female", and "other" as the possible options.
- */
+/// Represents a message send of [Intl.gender] inside a message that is to
+/// be internationalized. This corresponds to an ICU message syntax "select"
+/// with "male", "female", and "other" as the possible options.
class Gender extends SubMessage {
Gender();
- /**
- * Create a new Gender providing [mainArgument] and the list of possible
- * clauses. Each clause is expected to be a list whose first element is a
- * variable name and whose second element is either a [String] or
- * a list of strings and [Message] or [VariableSubstitution].
- */
+ /// Create a new Gender providing [mainArgument] and the list of possible
+ /// clauses. Each clause is expected to be a list whose first element is a
+ /// variable name and whose second element is either a [String] or
+ /// a list of strings and [Message] or [VariableSubstitution].
Gender.from(String mainArgument, List clauses, Message parent)
: super.from(mainArgument, clauses, parent);
@@ -595,10 +521,8 @@
get attributeNames => ["female", "male", "other"];
get codeAttributeNames => attributeNames;
- /**
- * The node will have the attribute names as strings, so we translate
- * between those and the fields of the class.
- */
+ /// The node will have the attribute names as strings, so we translate
+ /// between those and the fields of the class.
void operator []=(attributeName, rawValue) {
var value = Message.from(rawValue, this);
switch (attributeName) {
@@ -648,10 +572,8 @@
get attributeNames => ["=0", "=1", "=2", "few", "many", "other"];
get codeAttributeNames => ["zero", "one", "two", "few", "many", "other"];
- /**
- * The node will have the attribute names as strings, so we translate
- * between those and the fields of the class.
- */
+ /// The node will have the attribute names as strings, so we translate
+ /// between those and the fields of the class.
void operator []=(String attributeName, rawValue) {
var value = Message.from(rawValue, this);
switch (attributeName) {
@@ -713,19 +635,15 @@
}
}
-/**
- * Represents a message send of [Intl.select] inside a message that is to
- * be internationalized. This corresponds to an ICU message syntax "select"
- * with arbitrary options.
- */
+/// Represents a message send of [Intl.select] inside a message that is to
+/// be internationalized. This corresponds to an ICU message syntax "select"
+/// with arbitrary options.
class Select extends SubMessage {
Select();
- /**
- * Create a new [Select] providing [mainArgument] and the list of possible
- * clauses. Each clause is expected to be a list whose first element is a
- * variable name and whose second element is either a String or
- * a list of strings and [Message]s or [VariableSubstitution]s.
- */
+ /// Create a new [Select] providing [mainArgument] and the list of possible
+ /// clauses. Each clause is expected to be a list whose first element is a
+ /// variable name and whose second element is either a String or
+ /// a list of strings and [Message]s or [VariableSubstitution]s.
Select.from(String mainArgument, List clauses, Message parent)
: super.from(mainArgument, clauses, parent);
@@ -747,22 +665,18 @@
return exact == null ? cases["other"] : exact;
}
- /**
- * Return the arguments that we care about for the select. In this
- * case they will all be passed in as a Map rather than as the named
- * arguments used in Plural/Gender.
- */
+ /// Return the arguments that we care about for the select. In this
+ /// case they will all be passed in as a Map rather than as the named
+ /// arguments used in Plural/Gender.
Map argumentsOfInterestFor(MethodInvocation node) {
var casesArgument = node.argumentList.arguments[1];
return new Map.fromIterable(casesArgument.entries,
key: (node) => node.key.value, value: (node) => node.value);
}
- /**
- * Write out the generated representation of this message. This differs
- * from Plural/Gender in that it prints a literal map rather than
- * named arguments.
- */
+ /// Write out the generated representation of this message. This differs
+ /// from Plural/Gender in that it prints a literal map rather than
+ /// named arguments.
String toCode() {
var out = new StringBuffer();
out.write('\${');
diff --git a/lib/src/lazy_locale_data.dart b/lib/src/lazy_locale_data.dart
index 9be1c0d..07d46f7 100644
--- a/lib/src/lazy_locale_data.dart
+++ b/lib/src/lazy_locale_data.dart
@@ -2,11 +2,9 @@
// 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 defines a class for loading locale data incrementally from
- * an external source as JSON. The external sources expected are either
- * local files or via HTTP request.
- */
+/// This defines a class for loading locale data incrementally from
+/// an external source as JSON. The external sources expected are either
+/// local files or via HTTP request.
library lazy_locale_data;
@@ -14,11 +12,9 @@
import 'dart:convert';
import 'intl_helpers.dart';
-/**
- * This implements the very basic map-type operations which are used
- * in locale lookup, and looks them up based on a URL that defines
- * the external source.
- */
+/// This implements the very basic map-type operations which are used
+/// in locale lookup, and looks them up based on a URL that defines
+/// the external source.
class LazyLocaleData {
/// This holds the data we have loaded.
Map map;
@@ -26,52 +22,41 @@
/// The object that actually does the data reading.
LocaleDataReader _reader;
- /**
- * In order to avoid a potentially remote call to see if a locale
- * is available, we hold a complete list of all the available
- * locales.
- */
+ /// In order to avoid a potentially remote call to see if a locale
+ /// is available, we hold a complete list of all the available
+ /// locales.
List availableLocales;
- /**
- * Given a piece of remote data, apply [_creationFunction] to it to
- * convert it into the right form. Typically this means converting it
- * from a Map into an object form.
- */
+ /// Given a piece of remote data, apply [_creationFunction] to it to
+ /// convert it into the right form. Typically this means converting it
+ /// from a Map into an object form.
Function _creationFunction;
- /**
- * The set of available locales.
- */
+ /// The set of available locales.
Set availableLocaleSet;
- /**
- * The constructor. The [_reader] specifies where the data comes
- * from. The [_creationFunction] creates the appropriate data type
- * from the remote data (which typically comes in as a Map). The
- * [keys] lists the set of remotely available locale names so we know which
- * things can be fetched without having to check remotely.
- */
+ /// The constructor. The [_reader] specifies where the data comes
+ /// from. The [_creationFunction] creates the appropriate data type
+ /// from the remote data (which typically comes in as a Map). The
+ /// [keys] lists the set of remotely available locale names so we know which
+ /// things can be fetched without having to check remotely.
LazyLocaleData(this._reader, this._creationFunction, List keys) {
map = new Map();
availableLocales = keys;
availableLocaleSet = new Set.from(availableLocales);
}
- /**
- * Tests if we have data for the locale available. Note that this returns
- * true even if the data is known to be available remotely but not yet loaded.
- */
+ /// Tests if we have data for the locale available. Note that this returns
+ /// true even if the data is known to be available remotely but not yet
+ /// loaded.
bool containsKey(String locale) => availableLocaleSet.contains(locale);
- /** Returns the list of keys/locale names. */
+ /// Returns the list of keys/locale names.
List get keys => availableLocales;
- /**
- * Returns the data stored for [localeName]. If no data has been loaded
- * for [localeName], throws an exception. If no data is available for
- * [localeName] then throw an exception with a different message.
- */
+ /// Returns the data stored for [localeName]. If no data has been loaded
+ /// for [localeName], throws an exception. If no data is available for
+ /// [localeName] then throw an exception with a different message.
operator [](String localeName) {
if (containsKey(localeName)) {
var data = map[localeName];
@@ -87,18 +72,14 @@
}
}
- /**
- * Throw an exception indicating that the locale has no data available,
- * either locally or remotely.
- */
+ /// Throw an exception indicating that the locale has no data available,
+ /// either locally or remotely.
unsupportedLocale(localeName) {
throw new LocaleDataException('Locale $localeName has no data available');
}
- /**
- * Initialize for locale. Internal use only. As a user, call
- * initializeDateFormatting instead.
- */
+ /// Initialize for locale. Internal use only. As a user, call
+ /// initializeDateFormatting instead.
Future initLocale(String localeName) {
var data = _reader.read(localeName);
return jsonData(data).then((input) {
@@ -106,10 +87,8 @@
});
}
- /**
- * Given a Future [input] whose value is expected to be a string in JSON form,
- * return another future that parses the JSON into a usable format.
- */
+ /// Given a Future [input] whose value is expected to be a string in JSON
+ /// form, return another future that parses the JSON into a usable format.
Future jsonData(Future input) {
return input.then((response) => JSON.decode(response));
}
diff --git a/test/bidi_format_test.dart b/test/bidi_format_test.dart
index 1656411..5b48dd6 100644
--- a/test/bidi_format_test.dart
+++ b/test/bidi_format_test.dart
@@ -7,9 +7,7 @@
import 'package:intl/intl.dart';
import 'package:unittest/unittest.dart';
-/**
- * Tests the bidirectional text formatting library.
- */
+/// Tests the bidirectional text formatting library.
main() {
var LTR = TextDirection.LTR;
var RTL = TextDirection.RTL;
diff --git a/test/bidi_utils_test.dart b/test/bidi_utils_test.dart
index 23ac723..c9c1aaf 100644
--- a/test/bidi_utils_test.dart
+++ b/test/bidi_utils_test.dart
@@ -7,9 +7,7 @@
import 'package:intl/intl.dart';
import 'package:unittest/unittest.dart';
-/**
- * Tests the bidi utilities library.
- */
+/// Tests the bidi utilities library.
main() {
var LRE = '\u202A';
var RLE = '\u202B';
diff --git a/test/data_directory.dart b/test/data_directory.dart
index 70aa385..2b6e94a 100644
--- a/test/data_directory.dart
+++ b/test/data_directory.dart
@@ -2,15 +2,13 @@
// 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 utility function for test and tools that compensates (at least for very
- * simple cases) for file-dependent programs being run from different
- * directories. The important cases are
- * - running in the directory that contains the test itself, i.e.
- * test/ or a sub-directory.
- * - running in root of this package, which is where the editor and bots will
- * run things by default
- */
+/// A utility function for test and tools that compensates (at least for very
+/// simple cases) for file-dependent programs being run from different
+/// directories. The important cases are
+/// - running in the directory that contains the test itself, i.e.
+/// test/ or a sub-directory.
+/// - running in root of this package, which is where the editor and bots will
+/// run things by default
library data_directory;
import "dart:io";
diff --git a/test/date_time_format_file_even_test.dart b/test/date_time_format_file_even_test.dart
index b6f8202..6360e47 100644
--- a/test/date_time_format_file_even_test.dart
+++ b/test/date_time_format_file_even_test.dart
@@ -2,11 +2,9 @@
// 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.
-/**
- * Tests date formatting and parsing using locale data read from the
- * local file system. This tests one half the locales, since testing all
- * of them takes long enough that it may cause timeouts in the test bots.
- */
+/// Tests date formatting and parsing using locale data read from the
+/// local file system. This tests one half the locales, since testing all
+/// of them takes long enough that it may cause timeouts in the test bots.
library date_time_format_file_test_2;
diff --git a/test/date_time_format_file_odd_test.dart b/test/date_time_format_file_odd_test.dart
index 79d6d11..4f4996a 100644
--- a/test/date_time_format_file_odd_test.dart
+++ b/test/date_time_format_file_odd_test.dart
@@ -2,11 +2,9 @@
// 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.
-/**
- * Tests date formatting and parsing using locale data read from the
- * local file system. This tests one half the locales, since testing all
- * of them takes long enough that it may cause timeouts in the test bots.
- */
+/// Tests date formatting and parsing using locale data read from the
+/// local file system. This tests one half the locales, since testing all
+/// of them takes long enough that it may cause timeouts in the test bots.
library date_time_format_file_test_1;
diff --git a/test/date_time_format_http_request_test.dart b/test/date_time_format_http_request_test.dart
index 9412be0..f907fb5 100644
--- a/test/date_time_format_http_request_test.dart
+++ b/test/date_time_format_http_request_test.dart
@@ -2,10 +2,8 @@
// or details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
-/**
- * Test date formatting and parsing using locale data read via an http request
- * to a server.
- */
+/// Test date formatting and parsing using locale data read via an http request
+/// to a server.
library date_time_format_http_request_test;
diff --git a/test/date_time_format_local_even_test.dart b/test/date_time_format_local_even_test.dart
index 4115a53..cbeee35 100644
--- a/test/date_time_format_local_even_test.dart
+++ b/test/date_time_format_local_even_test.dart
@@ -2,12 +2,10 @@
// 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.
-/**
- * Test date formatting and parsing using locale data which is available
- * directly in the program as a constant. This tests one half the locales,
- * since testing all of them takes long enough that it may cause timeouts in
- * the test bots.
- */
+/// Test date formatting and parsing using locale data which is available
+/// directly in the program as a constant. This tests one half the locales,
+/// since testing all of them takes long enough that it may cause timeouts in
+/// the test bots.
library date_time_format_test_2;
diff --git a/test/date_time_format_local_odd_test.dart b/test/date_time_format_local_odd_test.dart
index a6c94f2..5102bcc 100644
--- a/test/date_time_format_local_odd_test.dart
+++ b/test/date_time_format_local_odd_test.dart
@@ -2,12 +2,10 @@
// 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.
-/**
- * Test date formatting and parsing using locale data which is available
- * directly in the program as a constant. This tests one half the locales,
- * since testing all of them takes long enough that it may cause timeouts in
- * the test bots.
- */
+/// Test date formatting and parsing using locale data which is available
+/// directly in the program as a constant. This tests one half the locales,
+/// since testing all of them takes long enough that it may cause timeouts in
+/// the test bots.
library date_time_format_test_1;
diff --git a/test/date_time_format_test_core.dart b/test/date_time_format_test_core.dart
index c0c3140..63ffaab 100644
--- a/test/date_time_format_test_core.dart
+++ b/test/date_time_format_test_core.dart
@@ -2,11 +2,9 @@
// 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.
-/**
- * Tests the DateFormat library in dart. This file contains core tests that
- * are run regardless of where the locale data is found, so it doesn't expect to
- * be run on its own, but rather to be imported and run from another test file.
- */
+/// Tests the DateFormat library in dart. This file contains core tests that are
+/// run regardless of where the locale data is found, so it doesn't expect to be
+/// run on its own, but rather to be imported and run from another test file.
library date_time_format_tests;
@@ -119,12 +117,10 @@
// ABBR_UTC_TZ
];
-/**
- * Exercise all of the formats we have explicitly defined on a particular
- * locale. [expectedResults] is a map from ICU format names to the
- * expected result of formatting [date] according to that format in
- * [localeName].
- */
+/// Exercise all of the formats we have explicitly defined on a particular
+/// locale. [expectedResults] is a map from ICU format names to the
+/// expected result of formatting [date] according to that format in
+/// [localeName].
testLocale(String localeName, Map expectedResults, DateTime date) {
var intl = new Intl(localeName);
for (int i = 0; i < formatsToTest.length; i++) {
@@ -169,7 +165,7 @@
}
}
-/** A shortcut for returning all the locales we have available.*/
+/// A shortcut for returning all the locales we have available.
List<String> allLocales() => DateFormat.allLocalesWithSymbols();
Function _subsetFunc;
@@ -364,11 +360,9 @@
}
});
- /**
- * Generate a map from day numbers in the given [year] (where Jan 1 == 1)
- * to a Date object. If [year] is a leap year, then pass 1 for
- * [leapDay], otherwise pass 0.
- */
+ /// Generate a map from day numbers in the given [year] (where Jan 1 == 1)
+ /// to a Date object. If [year] is a leap year, then pass 1 for
+ /// [leapDay], otherwise pass 0.
Map<int, DateTime> generateDates(int year, int leapDay) =>
new Iterable.generate(365 + leapDay, (n) => n + 1).map((day) {
var result = new DateTime(year, 1, day);
diff --git a/test/date_time_format_test_data.dart b/test/date_time_format_test_data.dart
index a83092c..733c3d4 100644
--- a/test/date_time_format_test_data.dart
+++ b/test/date_time_format_test_data.dart
@@ -2,11 +2,9 @@
// 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.
-/**
- * Test data for one particular date formatted for a small number of locales.
- * Provides at least a basic check on formatting, including formatting with
- * non-ASCII characters and some different orderings.
- */
+/// Test data for one particular date formatted for a small number of locales.
+/// Provides at least a basic check on formatting, including formatting with
+/// non-ASCII characters and some different orderings.
// TODO(alanknight): Test more locales and a wider variety of test data,
// possibly by generating test data out of ICU.
diff --git a/test/date_time_format_test_stub.dart b/test/date_time_format_test_stub.dart
index e8141f6..9bc355f 100644
--- a/test/date_time_format_test_stub.dart
+++ b/test/date_time_format_test_stub.dart
@@ -2,10 +2,8 @@
// 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.
-/**
- * Test date formatting and parsing using locale data which is available
- * directly in the program as a constant.
- */
+/// Test date formatting and parsing using locale data which is available
+/// directly in the program as a constant.
library date_time_format_test;
@@ -18,26 +16,20 @@
typedef Future InitializeDateFormattingFunc(String locale, String filePath);
-/**
- * Return only the odd-numbered locales. A simple way to divide the list into
- * two roughly equal parts.
- */
+/// Return only the odd-numbered locales. A simple way to divide the list into
+/// two roughly equal parts.
List<String> oddLocales() {
int i = 1;
return allLocales().where((x) => (i++).isOdd).toList();
}
-/**
- * Return a set of a few locales to run just the tests on a small sample.
- */
+/// Return a set of a few locales to run just the tests on a small sample.
List smallSetOfLocales() {
return allLocales().sublist(0, 10);
}
-/**
- * Return only the even-numbered locales. A simple way to divide the list into
- * two roughly equal parts.
- */
+/// Return only the even-numbered locales. A simple way to divide the list into
+/// two roughly equal parts.
List<String> evenLocales() {
int i = 1;
return allLocales().where((x) => !((i++).isOdd)).toList();
diff --git a/test/date_time_format_uninitialized_test.dart b/test/date_time_format_uninitialized_test.dart
index d460c47..49c081b 100644
--- a/test/date_time_format_uninitialized_test.dart
+++ b/test/date_time_format_uninitialized_test.dart
@@ -2,10 +2,8 @@
// 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.
-/**
- * Tests date formatting and parsing using locale data read from the
- * local file system.
- */
+/// Tests date formatting and parsing using locale data read from the
+/// local file system.
library date_time_format_file_test;
import 'date_time_format_test_core.dart';
diff --git a/test/intl_message_basic_example_test.dart b/test/intl_message_basic_example_test.dart
index 6b4a4d3..b8265b7 100644
--- a/test/intl_message_basic_example_test.dart
+++ b/test/intl_message_basic_example_test.dart
@@ -2,9 +2,8 @@
// 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.
-/**
- * Tests internationalization of messages using the basic example as a template.
- */
+/// Tests internationalization of messages using the basic example as a
+/// template.
library intl_message_test_2;
import '../example/basic/basic_example.dart';
diff --git a/test/message_extraction/examples_parsing_test.dart b/test/message_extraction/examples_parsing_test.dart
index 55be5bd..97cd1de 100644
--- a/test/message_extraction/examples_parsing_test.dart
+++ b/test/message_extraction/examples_parsing_test.dart
@@ -2,10 +2,8 @@
// 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.
-/**
- * Test for parsing the examples argument from an Intl.message call. Very
- * minimal so far.
- */
+/// Test for parsing the examples argument from an Intl.message call. Very
+/// minimal so far.
import 'package:unittest/unittest.dart';
import 'package:intl/extract_messages.dart';
import '../data_directory.dart';
diff --git a/test/message_extraction/make_hardcoded_translation.dart b/test/message_extraction/make_hardcoded_translation.dart
index 90bcfc4..a813c18 100644
--- a/test/message_extraction/make_hardcoded_translation.dart
+++ b/test/message_extraction/make_hardcoded_translation.dart
@@ -3,19 +3,17 @@
// 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 simulates a translation process, reading the messages generated
- * from extract_message.dart for the files sample_with_messages.dart and
- * part_of_sample_with_messages.dart and writing out hard-coded translations for
- * German and French locales.
- */
+/// This simulates a translation process, reading the messages generated from
+/// extract_message.dart for the files sample_with_messages.dart and
+/// part_of_sample_with_messages.dart and writing out hard-coded translations
+/// for German and French locales.
import 'dart:convert';
import 'dart:io';
import 'package:path/path.dart' as path;
import 'package:args/args.dart';
-/** A list of the French translations that we will produce. */
+/// A list of the French translations that we will produce.
var french = {
"types": r"{a}, {b}, {c}",
"multiLine": "Cette message prend plusiers lignes.",
@@ -76,7 +74,7 @@
"}}"
};
-/** A list of the German translations that we will produce. */
+/// A list of the German translations that we will produce.
var german = {
"types": r"{a}, {b}, {c}",
"multiLine": "Dieser String erstreckt sich über mehrere Zeilen erstrecken.",
@@ -135,13 +133,11 @@
"}"
};
-/** The output directory for translated files. */
+/// The output directory for translated files.
String targetDir;
-/**
- * Generate a translated json version from [originals] in [locale] looking
- * up the translations in [translations].
- */
+/// Generate a translated json version from [originals] in [locale] looking
+/// up the translations in [translations].
void translate(Map originals, String locale, Map translations) {
var translated = {"_locale": locale};
originals.forEach((name, text) {
diff --git a/test/message_extraction/message_extraction_no_deferred_test.dart b/test/message_extraction/message_extraction_no_deferred_test.dart
index 5c7cea4..68936f1 100644
--- a/test/message_extraction/message_extraction_no_deferred_test.dart
+++ b/test/message_extraction/message_extraction_no_deferred_test.dart
@@ -2,10 +2,9 @@
// 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 test for message extraction and code generation not using deferred
- * loading for the generated code.
- */
+
+/// A test for message extraction and code generation not using deferred
+/// loading for the generated code.
library message_extraction_no_deferred_test;
import 'message_extraction_test.dart' as mainTest;
diff --git a/test/message_extraction/message_extraction_test.dart b/test/message_extraction/message_extraction_test.dart
index 6b7de6b..79afb74 100644
--- a/test/message_extraction/message_extraction_test.dart
+++ b/test/message_extraction/message_extraction_test.dart
@@ -13,22 +13,20 @@
final dart = Platform.executable;
-/** Should we use deferred loading. */
+/// Should we use deferred loading.
bool useDeferredLoading = true;
String get _deferredLoadPrefix => useDeferredLoading ? '' : 'no-';
String get deferredLoadArg => '--${_deferredLoadPrefix}use-deferred-loading';
-/** The VM arguments we were given, most important package-root. */
+/// The VM arguments we were given, most important package-root.
final vmArgs = Platform.executableArguments;
-/**
- * For testing we move the files into a temporary directory so as not to leave
- * generated files around after a failed test. For debugging, we omit that
- * step if [useLocalDirectory] is true. The place we move them to is saved as
- * [tempDir].
- */
+/// For testing we move the files into a temporary directory so as not to leave
+/// generated files around after a failed test. For debugging, we omit that
+/// step if [useLocalDirectory] is true. The place we move them to is saved as
+/// [tempDir].
String get tempDir => _tempDir == null ? _tempDir = _createTempDir() : _tempDir;
var _tempDir;
_createTempDir() => useLocalDirectory
@@ -37,23 +35,19 @@
var useLocalDirectory = false;
-/**
- * Translate a relative file path into this test directory. This is
- * applied to all the arguments of [run]. It will ignore a string that
- * is an absolute path or begins with "--", because some of the arguments
- * might be command-line options.
- */
+/// Translate a relative file path into this test directory. This is
+/// applied to all the arguments of [run]. It will ignore a string that
+/// is an absolute path or begins with "--", because some of the arguments
+/// might be command-line options.
String asTestDirPath([String s]) {
if (s == null || s.startsWith("--") || path.isAbsolute(s)) return s;
return path.join(intlDirectory, 'test', 'message_extraction', s);
}
-/**
- * Translate a relative file path into our temp directory. This is
- * applied to all the arguments of [run]. It will ignore a string that
- * is an absolute path or begins with "--", because some of the arguments
- * might be command-line options.
- */
+/// Translate a relative file path into our temp directory. This is
+/// applied to all the arguments of [run]. It will ignore a string that
+/// is an absolute path or begins with "--", because some of the arguments
+/// might be command-line options.
String asTempDirPath([String s]) {
if (s == null || s.startsWith("--") || path.isAbsolute(s)) return s;
return path.join(tempDir, s);
@@ -107,11 +101,9 @@
}
}
-/**
- * Run the process with the given list of filenames, which we assume
- * are in dir() and need to be qualified in case that's not our working
- * directory.
- */
+/// Run the process with the given list of filenames, which we assume
+/// are in dir() and need to be qualified in case that's not our working
+/// directory.
Future<ProcessResult> run(
ProcessResult previousResult, List<String> filenames) {
// If there's a failure in one of the sub-programs, print its output.
diff --git a/test/message_extraction/sample_with_messages.dart b/test/message_extraction/sample_with_messages.dart
index bed0456..3d365b9 100644
--- a/test/message_extraction/sample_with_messages.dart
+++ b/test/message_extraction/sample_with_messages.dart
@@ -2,11 +2,9 @@
// 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 is a program with various [Intl.message] messages. It just prints
- * all of them, and is used for testing of message extraction, translation,
- * and code generation.
- */
+/// This is a program with various [Intl.message] messages. It just prints
+/// all of them, and is used for testing of message extraction, translation,
+/// and code generation.
library sample;
import "package:intl/intl.dart";
@@ -20,16 +18,21 @@
message1() => Intl.message("This is a message", name: 'message1', desc: 'foo');
message2(x) => Intl.message("Another message with parameter $x",
- name: 'mess' 'age2', desc: 'Description ' '2', args: [x], examples: {'x': 3});
+ name: 'mess' 'age2',
+ desc: 'Description ' '2',
+ args: [x],
+ examples: {'x': 3});
// A string with multiple adjacent strings concatenated together, verify
// that the parser handles this properly.
-multiLine() => Intl.message("This "
+multiLine() => Intl.message(
+ "This "
"string "
"extends "
"across "
"multiple "
- "lines.", name: "multiLine");
+ "lines.",
+ name: "multiLine");
// Have types on the enclosing function's arguments.
types(int a, String b, List c) =>
@@ -42,9 +45,9 @@
// Test interpolation with curly braces around the expression, but it must
// still be just a variable reference.
-trickyInterpolation(s) => Intl.message(
- "Interpolation is tricky when it ends a sentence like ${s}.",
- name: 'trickyInterpolation', args: [s]);
+trickyInterpolation(s) =>
+ Intl.message("Interpolation is tricky when it ends a sentence like ${s}.",
+ name: 'trickyInterpolation', args: [s]);
get leadingQuotes => Intl.message("\"So-called\"", name: 'leadingQuotes');
@@ -94,17 +97,25 @@
invalidOuterGender(g) => Intl.gender(g, other: 'o');
// A general select
-outerSelect(currency, amount) => Intl.select(currency, {
- "CDN": "$amount Canadian dollars",
- "other": "$amount some currency or other."
-}, name: "outerSelect", args: [currency, amount]);
+outerSelect(currency, amount) => Intl.select(
+ currency,
+ {
+ "CDN": "$amount Canadian dollars",
+ "other": "$amount some currency or other."
+ },
+ name: "outerSelect",
+ args: [currency, amount]);
// A select with a plural inside the expressions.
-nestedSelect(currency, amount) => Intl.select(currency, {
- "CDN": """${Intl.plural(amount, one: '$amount Canadian dollar',
+nestedSelect(currency, amount) => Intl.select(
+ currency,
+ {
+ "CDN": """${Intl.plural(amount, one: '$amount Canadian dollar',
other: '$amount Canadian dollars')}""",
- "other": "Whatever",
-}, name: "nestedSelect", args: [currency, amount]);
+ "other": "Whatever",
+ },
+ name: "nestedSelect",
+ args: [currency, amount]);
// A trivial nested plural/gender where both are done directly rather than
// in interpolations.
@@ -133,7 +144,6 @@
desc: "The action of renting, as in rent a car");
printStuff(Intl locale) {
-
// Use a name that's not a literal so this will get skipped. Then we have
// a name that's not in the original but we include it in the French
// translation. Because it's not in the original it shouldn't get included
@@ -151,7 +161,9 @@
message3(a, b, c) => Intl.message(
"Characters that need escaping, e.g slashes \\ dollars \${ (curly braces "
"are ok) and xml reserved characters <& and quotes \" "
- "parameters $a, $b, and $c", name: 'message3', args: [a, b, c]);
+ "parameters $a, $b, and $c",
+ name: 'message3',
+ args: [a, b, c]);
var messageVariable = message3;
printOut("-------------------------------------------");
@@ -235,7 +247,8 @@
var f1 = initializeMessages(fr.locale)
// Since English has the one message which is always translated, we
// can't print it until French is ready.
- .then((_) => printStuff(english)).then((_) => printStuff(fr));
+ .then((_) => printStuff(english))
+ .then((_) => printStuff(fr));
var f2 = initializeMessages('de-de').then((_) => printStuff(de));
return Future.wait([f1, f2]);
}
diff --git a/test/number_closure_test.dart b/test/number_closure_test.dart
index 8f4410c..b7c422a 100644
--- a/test/number_closure_test.dart
+++ b/test/number_closure_test.dart
@@ -1,9 +1,7 @@
// 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.
-/**
- * Tests based on the closure number formatting tests.
- */
+/// Tests based on the closure number formatting tests.
library number_closure_test;
import 'dart:async';
@@ -27,10 +25,8 @@
test("testLocaleSwitchAsync", testLocaleSwitchAsync);
}
-/**
- * Test two large numbers for equality, assuming that there may be some
- * loss of precision in the less significant digits.
- */
+/// Test two large numbers for equality, assuming that there may be some
+/// loss of precision in the less significant digits.
veryBigNumberCompare(str1, str2) {
return str1.length == str2.length &&
str1.substring(0, 8) == str2.substring(0, 8);
diff --git a/test/number_format_test.dart b/test/number_format_test.dart
index 54c9114..df41c41 100644
--- a/test/number_format_test.dart
+++ b/test/number_format_test.dart
@@ -1,8 +1,6 @@
-/**
- * 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.
library number_format_test;
@@ -12,9 +10,7 @@
import 'number_test_data.dart';
import 'dart:math';
-/**
- * Tests the Numeric formatting library in dart.
- */
+/// Tests the Numeric formatting library in dart.
var testNumbersWeCanReadBack = {
"-1": -1,
"-2": -2.0,
@@ -38,7 +34,7 @@
"-∞": double.NEGATIVE_INFINITY,
};
-/** Test numbers that we can't parse because we lose precision in formatting.*/
+/// Test numbers that we can't parse because we lose precision in formatting.
var testNumbersWeCannotReadBack = {
"3.142": PI,
"-1.234": -1.2342,
@@ -47,7 +43,7 @@
"1.235": 1.2348
};
-/** Test numbers that won't work in Javascript because they're too big. */
+/// Test numbers that won't work in Javascript because they're too big.
var testNumbersOnlyForTheVM = {
"10,000,000,000,000,000,000,000,000,000,000":
10000000000000000000000000000000,
diff --git a/test/number_test_data.dart b/test/number_test_data.dart
index eb8a778..f3bd6e0 100644
--- a/test/number_test_data.dart
+++ b/test/number_test_data.dart
@@ -2,12 +2,10 @@
// 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.
-/**
- * Test data for numeric formatting from a large set of locales.
- *
- * DO NOT EDIT. This file is autogenerated from ICU data.
- * File generated from CLDR ver. 28.0
- */
+/// Test data for numeric formatting from a large set of locales.
+///
+/// DO NOT EDIT. This file is autogenerated from ICU data.
+/// File generated from CLDR ver. 28.0
library number_test_data;
diff --git a/tool/generate_locale_data_files.dart b/tool/generate_locale_data_files.dart
index e6b49d7..569b60d 100644
--- a/tool/generate_locale_data_files.dart
+++ b/tool/generate_locale_data_files.dart
@@ -2,15 +2,13 @@
// 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 utility program to take locale data represented as a Dart map whose keys
- * are locale names and write it into individual JSON files named by locale.
- * This should be run any time the locale data changes.
- *
- * The files are written under "data/dates", in two subdirectories, "symbols"
- * and "patterns". In "data/dates" it will also generate "locale_list.dart",
- * which is sourced by the date_symbol_data... files.
- */
+/// A utility program to take locale data represented as a Dart map whose keys
+/// are locale names and write it into individual JSON files named by locale.
+/// This should be run any time the locale data changes.
+///
+/// The files are written under "data/dates", in two subdirectories, "symbols"
+/// and "patterns". In "data/dates" it will also generate "locale_list.dart",
+/// which is sourced by the date_symbol_data... files.
import '../lib/date_symbol_data_local.dart';
import '../lib/date_time_patterns.dart';
