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