Debian Codegraph @

closure-library/closure/goog/labs/i18n/listformat.js

raw
1 // Copyright 2013 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview List format and gender decision library with locale support.
17 *
18 * ListFormat takes an array or a var_arg of objects and generates a user
19 * friendly list in a locale-sensitive way (i.e. "red, green, and blue").
20 *
21 * GenderInfo can be used to determine the gender of a list of items,
22 * depending on the gender of all items in the list.
23 *
24 * In English, lists of items don't really have gender, and in fact few things
25 * have gender. But the idea is this:
26 * - for a list of "male items" (think "John, Steve") you use "they"
27 * - for "Marry, Ann" (all female) you might have a "feminine" form of "they"
28 * - and yet another form for mixed lists ("John, Marry") or undetermined
29 * (when you don't know the gender of the items, or when they are neuter)
30 *
31 * For example in Greek "they" will be translated as "αυτοί" for masculin,
32 * "αυτές" for feminin, and "αυτά" for neutral/undetermined.
33 * (it is in fact more complicated than that, as weak/strong forms and case
34 * also matter, see http://en.wiktionary.org/wiki/Appendix:Greek_pronouns)
35 *
36 */
37
38 goog.provide('goog.labs.i18n.GenderInfo');
39 goog.provide('goog.labs.i18n.GenderInfo.Gender');
40 goog.provide('goog.labs.i18n.ListFormat');
41
42 goog.require('goog.asserts');
43 goog.require('goog.labs.i18n.ListFormatSymbols');
44
45
46
47 /**
48 * ListFormat provides a method to format a list/array of objects to a string,
49 * in a user friendly way and in a locale sensitive manner.
50 * If the objects are not strings, toString is called to convert them.
51 * The constructor initializes the object based on the locale data from
52 * the current goog.labs.i18n.ListFormatSymbols.
53 *
54 * Similar to the ICU4J class com.ibm.icu.text.ListFormatter:
55 * http://icu-project.org/apiref/icu4j/com/ibm/icu/text/ListFormatter.html
56 * @constructor
57 * @final
58 */
59 goog.labs.i18n.ListFormat = function() {
60 /**
61 * String for lists of exactly two items, containing {0} for the first,
62 * and {1} for the second.
63 * For instance '{0} and {1}' will give 'black and white'.
64 * @private {string}
65 *
66 * Example: for "black and white" the pattern is "{0} and {1}"
67 * While for a longer list we have "cyan, magenta, yellow, and black"
68 * Think "{0} start {1} middle {2} middle {3} end {4}"
69 * The last pattern is "{0}, and {1}." Note the comma before "and".
70 * So the "Two" pattern can be different than Start/Middle/End ones.
71 */
72 this.listTwoPattern_ = goog.labs.i18n.ListFormatSymbols.LIST_TWO;
73
74 /**
75 * String for the start of a list items, containing {0} for the first,
76 * and {1} for the rest.
77 * @private {string}
78 */
79 this.listStartPattern_ = goog.labs.i18n.ListFormatSymbols.LIST_START;
80
81 /**
82 * String for the start of a list items, containing {0} for the first part
83 * of the list, and {1} for the rest of the list.
84 * @private {string}
85 */
86 this.listMiddlePattern_ = goog.labs.i18n.ListFormatSymbols.LIST_MIDDLE;
87
88 /**
89 * String for the end of a list items, containing {0} for the first part
90 * of the list, and {1} for the last item.
91 *
92 * This is how start/middle/end come together:
93 * start = '{0}, {1}' middle = '{0}, {1}', end = '{0}, and {1}'
94 * will result in the typical English list: 'one, two, three, and four'
95 * There are languages where the patterns are more complex than
96 * '{1} someText {1}' and the start pattern is different than the middle one.
97 *
98 * @private {string}
99 */
100 this.listEndPattern_ = goog.labs.i18n.ListFormatSymbols.LIST_END;
101 };
102
103
104 /**
105 * Replaces the {0} and {1} placeholders in a pattern with the first and
106 * the second parameter respectively, and returns the result.
107 * It is a helper function for goog.labs.i18n.ListFormat.format.
108 *
109 * @param {string} pattern used for formatting.
110 * @param {string} first object to add to list.
111 * @param {string} second object to add to list.
112 * @return {string} The formatted list string.
113 * @private
114 */
115 goog.labs.i18n.ListFormat.prototype.patternBasedJoinTwoStrings_ = function(
116 pattern, first, second) {
117 return pattern.replace('{0}', first).replace('{1}', second);
118 };
119
120
121 /**
122 * Formats an array of strings into a string.
123 * It is a user facing, locale-aware list (i.e. 'red, green, and blue').
124 *
125 * @param {!Array<string|number>} items Items to format.
126 * @return {string} The items formatted into a string, as a list.
127 */
128 goog.labs.i18n.ListFormat.prototype.format = function(items) {
129 var count = items.length;
130 switch (count) {
131 case 0:
132 return '';
133 case 1:
134 return String(items[0]);
135 case 2:
136 return this.patternBasedJoinTwoStrings_(
137 this.listTwoPattern_, String(items[0]), String(items[1]));
138 }
139
140 var result = this.patternBasedJoinTwoStrings_(
141 this.listStartPattern_, String(items[0]), String(items[1]));
142
143 for (var i = 2; i < count - 1; ++i) {
144 result = this.patternBasedJoinTwoStrings_(
145 this.listMiddlePattern_, result, String(items[i]));
146 }
147
148 return this.patternBasedJoinTwoStrings_(
149 this.listEndPattern_, result, String(items[count - 1]));
150 };
151
152
153
154 /**
155 * GenderInfo provides a method to determine the gender of a list/array
156 * of objects when one knows the gender of each item of the list.
157 * It does this in a locale sensitive manner.
158 * The constructor initializes the object based on the locale data from
159 * the current goog.labs.i18n.ListFormatSymbols.
160 *
161 * Similar to the ICU4J class com.icu.util.GenderInfo:
162 * http://icu-project.org/apiref/icu4j/com/ibm/icu/util/GenderInfo.html
163 * @constructor
164 * @final
165 */
166 goog.labs.i18n.GenderInfo = function() {
167 /**
168 * Stores the language-aware mode of determining the gender of a list.
169 * @private {goog.labs.i18n.GenderInfo.ListGenderStyle_}
170 */
171 this.listGenderStyle_ = goog.labs.i18n.ListFormatSymbols.GENDER_STYLE;
172 };
173
174
175 /**
176 * Enumeration for the possible ways to generate list genders.
177 * Indicates the category for the locale.
178 * This only affects gender for lists more than one. For lists of 1 item,
179 * the gender of the list always equals the gender of that sole item.
180 * This is for internal use, matching ICU.
181 * @enum {number}
182 * @private
183 */
184 goog.labs.i18n.GenderInfo.ListGenderStyle_ = {
185 NEUTRAL: 0,
186 MIXED_NEUTRAL: 1,
187 MALE_TAINTS: 2
188 };
189
190
191 /**
192 * Enumeration for the possible gender values.
193 * Gender: OTHER means either the information is unavailable,
194 * or the person has declined to state MALE or FEMALE.
195 * @enum {number}
196 */
197 goog.labs.i18n.GenderInfo.Gender = {
198 MALE: 0,
199 FEMALE: 1,
200 OTHER: 2
201 };
202
203
204 /**
205 * Determines the overal gender of a list based on the gender of all the list
206 * items, in a locale-aware way.
207 * @param {!Array<!goog.labs.i18n.GenderInfo.Gender>} genders An array of
208 * genders, will give the gender of the list.
209 * @return {goog.labs.i18n.GenderInfo.Gender} Get the gender of the list.
210 */
211 goog.labs.i18n.GenderInfo.prototype.getListGender = function(genders) {
212 var Gender = goog.labs.i18n.GenderInfo.Gender;
213
214 var count = genders.length;
215 if (count == 0) {
216 return Gender.OTHER; // degenerate case
217 }
218 if (count == 1) {
219 return genders[0]; // degenerate case
220 }
221
222 switch (this.listGenderStyle_) {
223 case goog.labs.i18n.GenderInfo.ListGenderStyle_.NEUTRAL:
224 return Gender.OTHER;
225 case goog.labs.i18n.GenderInfo.ListGenderStyle_.MIXED_NEUTRAL:
226 var hasFemale = false;
227 var hasMale = false;
228 for (var i = 0; i < count; ++i) {
229 switch (genders[i]) {
230 case Gender.FEMALE:
231 if (hasMale) {
232 return Gender.OTHER;
233 }
234 hasFemale = true;
235 break;
236 case Gender.MALE:
237 if (hasFemale) {
238 return Gender.OTHER;
239 }
240 hasMale = true;
241 break;
242 case Gender.OTHER:
243 return Gender.OTHER;
244 default: // Should never happen, but just in case
245 goog.asserts.assert(
246 false, 'Invalid genders[' + i + '] = ' + genders[i]);
247 return Gender.OTHER;
248 }
249 }
250 return hasMale ? Gender.MALE : Gender.FEMALE;
251 case goog.labs.i18n.GenderInfo.ListGenderStyle_.MALE_TAINTS:
252 for (var i = 0; i < count; ++i) {
253 if (genders[i] != Gender.FEMALE) {
254 return Gender.MALE;
255 }
256 }
257 return Gender.FEMALE;
258 default:
259 return Gender.OTHER;
260 }
261 };