Debian Codegraph @

closure-library/closure/goog/i18n/bidi.js

raw
1 // Copyright 2007 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 Utility functions for supporting Bidi issues.
17 */
18
19
20 /**
21 * Namespace for bidi supporting functions.
22 */
23 goog.provide('goog.i18n.bidi');
24 goog.provide('goog.i18n.bidi.Dir');
25 goog.provide('goog.i18n.bidi.DirectionalString');
26 goog.provide('goog.i18n.bidi.Format');
27
28
29 /**
30 * @define {boolean} FORCE_RTL forces the {@link goog.i18n.bidi.IS_RTL} constant
31 * to say that the current locale is a RTL locale. This should only be used
32 * if you want to override the default behavior for deciding whether the
33 * current locale is RTL or not.
34 *
35 * {@see goog.i18n.bidi.IS_RTL}
36 */
37 goog.define('goog.i18n.bidi.FORCE_RTL', false);
38
39
40 /**
41 * Constant that defines whether or not the current locale is a RTL locale.
42 * If {@link goog.i18n.bidi.FORCE_RTL} is not true, this constant will default
43 * to check that {@link goog.LOCALE} is one of a few major RTL locales.
44 *
45 * <p>This is designed to be a maximally efficient compile-time constant. For
46 * example, for the default goog.LOCALE, compiling
47 * "if (goog.i18n.bidi.IS_RTL) alert('rtl') else {}" should produce no code. It
48 * is this design consideration that limits the implementation to only
49 * supporting a few major RTL locales, as opposed to the broader repertoire of
50 * something like goog.i18n.bidi.isRtlLanguage.
51 *
52 * <p>Since this constant refers to the directionality of the locale, it is up
53 * to the caller to determine if this constant should also be used for the
54 * direction of the UI.
55 *
56 * {@see goog.LOCALE}
57 *
58 * @type {boolean}
59 *
60 * TODO(user): write a test that checks that this is a compile-time constant.
61 */
62 goog.i18n.bidi.IS_RTL = goog.i18n.bidi.FORCE_RTL ||
63 ((goog.LOCALE.substring(0, 2).toLowerCase() == 'ar' ||
64 goog.LOCALE.substring(0, 2).toLowerCase() == 'fa' ||
65 goog.LOCALE.substring(0, 2).toLowerCase() == 'he' ||
66 goog.LOCALE.substring(0, 2).toLowerCase() == 'iw' ||
67 goog.LOCALE.substring(0, 2).toLowerCase() == 'ps' ||
68 goog.LOCALE.substring(0, 2).toLowerCase() == 'sd' ||
69 goog.LOCALE.substring(0, 2).toLowerCase() == 'ug' ||
70 goog.LOCALE.substring(0, 2).toLowerCase() == 'ur' ||
71 goog.LOCALE.substring(0, 2).toLowerCase() == 'yi') &&
72 (goog.LOCALE.length == 2 || goog.LOCALE.substring(2, 3) == '-' ||
73 goog.LOCALE.substring(2, 3) == '_')) ||
74 (goog.LOCALE.length >= 3 &&
75 goog.LOCALE.substring(0, 3).toLowerCase() == 'ckb' &&
76 (goog.LOCALE.length == 3 || goog.LOCALE.substring(3, 4) == '-' ||
77 goog.LOCALE.substring(3, 4) == '_'));
78
79
80 /**
81 * Unicode formatting characters and directionality string constants.
82 * @enum {string}
83 */
84 goog.i18n.bidi.Format = {
85 /** Unicode "Left-To-Right Embedding" (LRE) character. */
86 LRE: '\u202A',
87 /** Unicode "Right-To-Left Embedding" (RLE) character. */
88 RLE: '\u202B',
89 /** Unicode "Pop Directional Formatting" (PDF) character. */
90 PDF: '\u202C',
91 /** Unicode "Left-To-Right Mark" (LRM) character. */
92 LRM: '\u200E',
93 /** Unicode "Right-To-Left Mark" (RLM) character. */
94 RLM: '\u200F'
95 };
96
97
98 /**
99 * Directionality enum.
100 * @enum {number}
101 */
102 goog.i18n.bidi.Dir = {
103 /**
104 * Left-to-right.
105 */
106 LTR: 1,
107
108 /**
109 * Right-to-left.
110 */
111 RTL: -1,
112
113 /**
114 * Neither left-to-right nor right-to-left.
115 */
116 NEUTRAL: 0
117 };
118
119
120 /**
121 * 'right' string constant.
122 * @type {string}
123 */
124 goog.i18n.bidi.RIGHT = 'right';
125
126
127 /**
128 * 'left' string constant.
129 * @type {string}
130 */
131 goog.i18n.bidi.LEFT = 'left';
132
133
134 /**
135 * 'left' if locale is RTL, 'right' if not.
136 * @type {string}
137 */
138 goog.i18n.bidi.I18N_RIGHT =
139 goog.i18n.bidi.IS_RTL ? goog.i18n.bidi.LEFT : goog.i18n.bidi.RIGHT;
140
141
142 /**
143 * 'right' if locale is RTL, 'left' if not.
144 * @type {string}
145 */
146 goog.i18n.bidi.I18N_LEFT =
147 goog.i18n.bidi.IS_RTL ? goog.i18n.bidi.RIGHT : goog.i18n.bidi.LEFT;
148
149
150 /**
151 * Convert a directionality given in various formats to a goog.i18n.bidi.Dir
152 * constant. Useful for interaction with different standards of directionality
153 * representation.
154 *
155 * @param {goog.i18n.bidi.Dir|number|boolean|null} givenDir Directionality given
156 * in one of the following formats:
157 * 1. A goog.i18n.bidi.Dir constant.
158 * 2. A number (positive = LTR, negative = RTL, 0 = neutral).
159 * 3. A boolean (true = RTL, false = LTR).
160 * 4. A null for unknown directionality.
161 * @param {boolean=} opt_noNeutral Whether a givenDir of zero or
162 * goog.i18n.bidi.Dir.NEUTRAL should be treated as null, i.e. unknown, in
163 * order to preserve legacy behavior.
164 * @return {?goog.i18n.bidi.Dir} A goog.i18n.bidi.Dir constant matching the
165 * given directionality. If given null, returns null (i.e. unknown).
166 */
167 goog.i18n.bidi.toDir = function(givenDir, opt_noNeutral) {
168 if (typeof givenDir == 'number') {
169 // This includes the non-null goog.i18n.bidi.Dir case.
170 return givenDir > 0 ? goog.i18n.bidi.Dir.LTR : givenDir < 0 ?
171 goog.i18n.bidi.Dir.RTL :
172 opt_noNeutral ? null : goog.i18n.bidi.Dir.NEUTRAL;
173 } else if (givenDir == null) {
174 return null;
175 } else {
176 // Must be typeof givenDir == 'boolean'.
177 return givenDir ? goog.i18n.bidi.Dir.RTL : goog.i18n.bidi.Dir.LTR;
178 }
179 };
180
181
182 /**
183 * A practical pattern to identify strong LTR characters. This pattern is not
184 * theoretically correct according to the Unicode standard. It is simplified for
185 * performance and small code size.
186 * @type {string}
187 * @private
188 */
189 goog.i18n.bidi.ltrChars_ =
190 'A-Za-z\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u02B8\u0300-\u0590\u0800-\u1FFF' +
191 '\u200E\u2C00-\uFB1C\uFE00-\uFE6F\uFEFD-\uFFFF';
192
193
194 /**
195 * A practical pattern to identify strong RTL character. This pattern is not
196 * theoretically correct according to the Unicode standard. It is simplified
197 * for performance and small code size.
198 * @type {string}
199 * @private
200 */
201 goog.i18n.bidi.rtlChars_ =
202 '\u0591-\u06EF\u06FA-\u07FF\u200F\uFB1D-\uFDFF\uFE70-\uFEFC';
203
204
205 /**
206 * Simplified regular expression for an HTML tag (opening or closing) or an HTML
207 * escape. We might want to skip over such expressions when estimating the text
208 * directionality.
209 * @type {RegExp}
210 * @private
211 */
212 goog.i18n.bidi.htmlSkipReg_ = /<[^>]*>|&[^;]+;/g;
213
214
215 /**
216 * Returns the input text with spaces instead of HTML tags or HTML escapes, if
217 * opt_isStripNeeded is true. Else returns the input as is.
218 * Useful for text directionality estimation.
219 * Note: the function should not be used in other contexts; it is not 100%
220 * correct, but rather a good-enough implementation for directionality
221 * estimation purposes.
222 * @param {string} str The given string.
223 * @param {boolean=} opt_isStripNeeded Whether to perform the stripping.
224 * Default: false (to retain consistency with calling functions).
225 * @return {string} The given string cleaned of HTML tags / escapes.
226 * @private
227 */
228 goog.i18n.bidi.stripHtmlIfNeeded_ = function(str, opt_isStripNeeded) {
229 return opt_isStripNeeded ? str.replace(goog.i18n.bidi.htmlSkipReg_, '') : str;
230 };
231
232
233 /**
234 * Regular expression to check for RTL characters.
235 * @type {RegExp}
236 * @private
237 */
238 goog.i18n.bidi.rtlCharReg_ = new RegExp('[' + goog.i18n.bidi.rtlChars_ + ']');
239
240
241 /**
242 * Regular expression to check for LTR characters.
243 * @type {RegExp}
244 * @private
245 */
246 goog.i18n.bidi.ltrCharReg_ = new RegExp('[' + goog.i18n.bidi.ltrChars_ + ']');
247
248
249 /**
250 * Test whether the given string has any RTL characters in it.
251 * @param {string} str The given string that need to be tested.
252 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
253 * Default: false.
254 * @return {boolean} Whether the string contains RTL characters.
255 */
256 goog.i18n.bidi.hasAnyRtl = function(str, opt_isHtml) {
257 return goog.i18n.bidi.rtlCharReg_.test(
258 goog.i18n.bidi.stripHtmlIfNeeded_(str, opt_isHtml));
259 };
260
261
262 /**
263 * Test whether the given string has any RTL characters in it.
264 * @param {string} str The given string that need to be tested.
265 * @return {boolean} Whether the string contains RTL characters.
266 * @deprecated Use hasAnyRtl.
267 */
268 goog.i18n.bidi.hasRtlChar = goog.i18n.bidi.hasAnyRtl;
269
270
271 /**
272 * Test whether the given string has any LTR characters in it.
273 * @param {string} str The given string that need to be tested.
274 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
275 * Default: false.
276 * @return {boolean} Whether the string contains LTR characters.
277 */
278 goog.i18n.bidi.hasAnyLtr = function(str, opt_isHtml) {
279 return goog.i18n.bidi.ltrCharReg_.test(
280 goog.i18n.bidi.stripHtmlIfNeeded_(str, opt_isHtml));
281 };
282
283
284 /**
285 * Regular expression pattern to check if the first character in the string
286 * is LTR.
287 * @type {RegExp}
288 * @private
289 */
290 goog.i18n.bidi.ltrRe_ = new RegExp('^[' + goog.i18n.bidi.ltrChars_ + ']');
291
292
293 /**
294 * Regular expression pattern to check if the first character in the string
295 * is RTL.
296 * @type {RegExp}
297 * @private
298 */
299 goog.i18n.bidi.rtlRe_ = new RegExp('^[' + goog.i18n.bidi.rtlChars_ + ']');
300
301
302 /**
303 * Check if the first character in the string is RTL or not.
304 * @param {string} str The given string that need to be tested.
305 * @return {boolean} Whether the first character in str is an RTL char.
306 */
307 goog.i18n.bidi.isRtlChar = function(str) {
308 return goog.i18n.bidi.rtlRe_.test(str);
309 };
310
311
312 /**
313 * Check if the first character in the string is LTR or not.
314 * @param {string} str The given string that need to be tested.
315 * @return {boolean} Whether the first character in str is an LTR char.
316 */
317 goog.i18n.bidi.isLtrChar = function(str) {
318 return goog.i18n.bidi.ltrRe_.test(str);
319 };
320
321
322 /**
323 * Check if the first character in the string is neutral or not.
324 * @param {string} str The given string that need to be tested.
325 * @return {boolean} Whether the first character in str is a neutral char.
326 */
327 goog.i18n.bidi.isNeutralChar = function(str) {
328 return !goog.i18n.bidi.isLtrChar(str) && !goog.i18n.bidi.isRtlChar(str);
329 };
330
331
332 /**
333 * Regular expressions to check if a piece of text is of LTR directionality
334 * on first character with strong directionality.
335 * @type {RegExp}
336 * @private
337 */
338 goog.i18n.bidi.ltrDirCheckRe_ = new RegExp(
339 '^[^' + goog.i18n.bidi.rtlChars_ + ']*[' + goog.i18n.bidi.ltrChars_ + ']');
340
341
342 /**
343 * Regular expressions to check if a piece of text is of RTL directionality
344 * on first character with strong directionality.
345 * @type {RegExp}
346 * @private
347 */
348 goog.i18n.bidi.rtlDirCheckRe_ = new RegExp(
349 '^[^' + goog.i18n.bidi.ltrChars_ + ']*[' + goog.i18n.bidi.rtlChars_ + ']');
350
351
352 /**
353 * Check whether the first strongly directional character (if any) is RTL.
354 * @param {string} str String being checked.
355 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
356 * Default: false.
357 * @return {boolean} Whether RTL directionality is detected using the first
358 * strongly-directional character method.
359 */
360 goog.i18n.bidi.startsWithRtl = function(str, opt_isHtml) {
361 return goog.i18n.bidi.rtlDirCheckRe_.test(
362 goog.i18n.bidi.stripHtmlIfNeeded_(str, opt_isHtml));
363 };
364
365
366 /**
367 * Check whether the first strongly directional character (if any) is RTL.
368 * @param {string} str String being checked.
369 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
370 * Default: false.
371 * @return {boolean} Whether RTL directionality is detected using the first
372 * strongly-directional character method.
373 * @deprecated Use startsWithRtl.
374 */
375 goog.i18n.bidi.isRtlText = goog.i18n.bidi.startsWithRtl;
376
377
378 /**
379 * Check whether the first strongly directional character (if any) is LTR.
380 * @param {string} str String being checked.
381 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
382 * Default: false.
383 * @return {boolean} Whether LTR directionality is detected using the first
384 * strongly-directional character method.
385 */
386 goog.i18n.bidi.startsWithLtr = function(str, opt_isHtml) {
387 return goog.i18n.bidi.ltrDirCheckRe_.test(
388 goog.i18n.bidi.stripHtmlIfNeeded_(str, opt_isHtml));
389 };
390
391
392 /**
393 * Check whether the first strongly directional character (if any) is LTR.
394 * @param {string} str String being checked.
395 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
396 * Default: false.
397 * @return {boolean} Whether LTR directionality is detected using the first
398 * strongly-directional character method.
399 * @deprecated Use startsWithLtr.
400 */
401 goog.i18n.bidi.isLtrText = goog.i18n.bidi.startsWithLtr;
402
403
404 /**
405 * Regular expression to check if a string looks like something that must
406 * always be LTR even in RTL text, e.g. a URL. When estimating the
407 * directionality of text containing these, we treat these as weakly LTR,
408 * like numbers.
409 * @type {RegExp}
410 * @private
411 */
412 goog.i18n.bidi.isRequiredLtrRe_ = /^http:\/\/.*/;
413
414
415 /**
416 * Check whether the input string either contains no strongly directional
417 * characters or looks like a url.
418 * @param {string} str String being checked.
419 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
420 * Default: false.
421 * @return {boolean} Whether neutral directionality is detected.
422 */
423 goog.i18n.bidi.isNeutralText = function(str, opt_isHtml) {
424 str = goog.i18n.bidi.stripHtmlIfNeeded_(str, opt_isHtml);
425 return goog.i18n.bidi.isRequiredLtrRe_.test(str) ||
426 !goog.i18n.bidi.hasAnyLtr(str) && !goog.i18n.bidi.hasAnyRtl(str);
427 };
428
429
430 /**
431 * Regular expressions to check if the last strongly-directional character in a
432 * piece of text is LTR.
433 * @type {RegExp}
434 * @private
435 */
436 goog.i18n.bidi.ltrExitDirCheckRe_ = new RegExp(
437 '[' + goog.i18n.bidi.ltrChars_ + '][^' + goog.i18n.bidi.rtlChars_ + ']*$');
438
439
440 /**
441 * Regular expressions to check if the last strongly-directional character in a
442 * piece of text is RTL.
443 * @type {RegExp}
444 * @private
445 */
446 goog.i18n.bidi.rtlExitDirCheckRe_ = new RegExp(
447 '[' + goog.i18n.bidi.rtlChars_ + '][^' + goog.i18n.bidi.ltrChars_ + ']*$');
448
449
450 /**
451 * Check if the exit directionality a piece of text is LTR, i.e. if the last
452 * strongly-directional character in the string is LTR.
453 * @param {string} str String being checked.
454 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
455 * Default: false.
456 * @return {boolean} Whether LTR exit directionality was detected.
457 */
458 goog.i18n.bidi.endsWithLtr = function(str, opt_isHtml) {
459 return goog.i18n.bidi.ltrExitDirCheckRe_.test(
460 goog.i18n.bidi.stripHtmlIfNeeded_(str, opt_isHtml));
461 };
462
463
464 /**
465 * Check if the exit directionality a piece of text is LTR, i.e. if the last
466 * strongly-directional character in the string is LTR.
467 * @param {string} str String being checked.
468 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
469 * Default: false.
470 * @return {boolean} Whether LTR exit directionality was detected.
471 * @deprecated Use endsWithLtr.
472 */
473 goog.i18n.bidi.isLtrExitText = goog.i18n.bidi.endsWithLtr;
474
475
476 /**
477 * Check if the exit directionality a piece of text is RTL, i.e. if the last
478 * strongly-directional character in the string is RTL.
479 * @param {string} str String being checked.
480 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
481 * Default: false.
482 * @return {boolean} Whether RTL exit directionality was detected.
483 */
484 goog.i18n.bidi.endsWithRtl = function(str, opt_isHtml) {
485 return goog.i18n.bidi.rtlExitDirCheckRe_.test(
486 goog.i18n.bidi.stripHtmlIfNeeded_(str, opt_isHtml));
487 };
488
489
490 /**
491 * Check if the exit directionality a piece of text is RTL, i.e. if the last
492 * strongly-directional character in the string is RTL.
493 * @param {string} str String being checked.
494 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
495 * Default: false.
496 * @return {boolean} Whether RTL exit directionality was detected.
497 * @deprecated Use endsWithRtl.
498 */
499 goog.i18n.bidi.isRtlExitText = goog.i18n.bidi.endsWithRtl;
500
501
502 /**
503 * A regular expression for matching right-to-left language codes.
504 * See {@link #isRtlLanguage} for the design.
505 * @type {RegExp}
506 * @private
507 */
508 goog.i18n.bidi.rtlLocalesRe_ = new RegExp(
509 '^(ar|ckb|dv|he|iw|fa|nqo|ps|sd|ug|ur|yi|' +
510 '.*[-_](Arab|Hebr|Thaa|Nkoo|Tfng))' +
511 '(?!.*[-_](Latn|Cyrl)($|-|_))($|-|_)',
512 'i');
513
514
515 /**
516 * Check if a BCP 47 / III language code indicates an RTL language, i.e. either:
517 * - a language code explicitly specifying one of the right-to-left scripts,
518 * e.g. "az-Arab", or<p>
519 * - a language code specifying one of the languages normally written in a
520 * right-to-left script, e.g. "fa" (Farsi), except ones explicitly specifying
521 * Latin or Cyrillic script (which are the usual LTR alternatives).<p>
522 * The list of right-to-left scripts appears in the 100-199 range in
523 * http://www.unicode.org/iso15924/iso15924-num.html, of which Arabic and
524 * Hebrew are by far the most widely used. We also recognize Thaana, N'Ko, and
525 * Tifinagh, which also have significant modern usage. The rest (Syriac,
526 * Samaritan, Mandaic, etc.) seem to have extremely limited or no modern usage
527 * and are not recognized to save on code size.
528 * The languages usually written in a right-to-left script are taken as those
529 * with Suppress-Script: Hebr|Arab|Thaa|Nkoo|Tfng in
530 * http://www.iana.org/assignments/language-subtag-registry,
531 * as well as Central (or Sorani) Kurdish (ckb), Sindhi (sd) and Uyghur (ug).
532 * Other subtags of the language code, e.g. regions like EG (Egypt), are
533 * ignored.
534 * @param {string} lang BCP 47 (a.k.a III) language code.
535 * @return {boolean} Whether the language code is an RTL language.
536 */
537 goog.i18n.bidi.isRtlLanguage = function(lang) {
538 return goog.i18n.bidi.rtlLocalesRe_.test(lang);
539 };
540
541
542 /**
543 * Regular expression for bracket guard replacement in text.
544 * @type {RegExp}
545 * @private
546 */
547 goog.i18n.bidi.bracketGuardTextRe_ =
548 /(\(.*?\)+)|(\[.*?\]+)|(\{.*?\}+)|(<.*?>+)/g;
549
550
551 /**
552 * Apply bracket guard using LRM and RLM. This is to address the problem of
553 * messy bracket display frequently happens in RTL layout.
554 * This function works for plain text, not for HTML. In HTML, the opening
555 * bracket might be in a different context than the closing bracket (such as
556 * an attribute value).
557 * @param {string} s The string that need to be processed.
558 * @param {boolean=} opt_isRtlContext specifies default direction (usually
559 * direction of the UI).
560 * @return {string} The processed string, with all bracket guarded.
561 */
562 goog.i18n.bidi.guardBracketInText = function(s, opt_isRtlContext) {
563 var useRtl = opt_isRtlContext === undefined ? goog.i18n.bidi.hasAnyRtl(s) :
564 opt_isRtlContext;
565 var mark = useRtl ? goog.i18n.bidi.Format.RLM : goog.i18n.bidi.Format.LRM;
566 return s.replace(goog.i18n.bidi.bracketGuardTextRe_, mark + '$&' + mark);
567 };
568
569
570 /**
571 * Enforce the html snippet in RTL directionality regardless overall context.
572 * If the html piece was enclosed by tag, dir will be applied to existing
573 * tag, otherwise a span tag will be added as wrapper. For this reason, if
574 * html snippet start with with tag, this tag must enclose the whole piece. If
575 * the tag already has a dir specified, this new one will override existing
576 * one in behavior (tested on FF and IE).
577 * @param {string} html The string that need to be processed.
578 * @return {string} The processed string, with directionality enforced to RTL.
579 */
580 goog.i18n.bidi.enforceRtlInHtml = function(html) {
581 if (html.charAt(0) == '<') {
582 return html.replace(/<\w+/, '$& dir=rtl');
583 }
584 // '\n' is important for FF so that it won't incorrectly merge span groups
585 return '\n<span dir=rtl>' + html + '</span>';
586 };
587
588
589 /**
590 * Enforce RTL on both end of the given text piece using unicode BiDi formatting
591 * characters RLE and PDF.
592 * @param {string} text The piece of text that need to be wrapped.
593 * @return {string} The wrapped string after process.
594 */
595 goog.i18n.bidi.enforceRtlInText = function(text) {
596 return goog.i18n.bidi.Format.RLE + text + goog.i18n.bidi.Format.PDF;
597 };
598
599
600 /**
601 * Enforce the html snippet in RTL directionality regardless overall context.
602 * If the html piece was enclosed by tag, dir will be applied to existing
603 * tag, otherwise a span tag will be added as wrapper. For this reason, if
604 * html snippet start with with tag, this tag must enclose the whole piece. If
605 * the tag already has a dir specified, this new one will override existing
606 * one in behavior (tested on FF and IE).
607 * @param {string} html The string that need to be processed.
608 * @return {string} The processed string, with directionality enforced to RTL.
609 */
610 goog.i18n.bidi.enforceLtrInHtml = function(html) {
611 if (html.charAt(0) == '<') {
612 return html.replace(/<\w+/, '$& dir=ltr');
613 }
614 // '\n' is important for FF so that it won't incorrectly merge span groups
615 return '\n<span dir=ltr>' + html + '</span>';
616 };
617
618
619 /**
620 * Enforce LTR on both end of the given text piece using unicode BiDi formatting
621 * characters LRE and PDF.
622 * @param {string} text The piece of text that need to be wrapped.
623 * @return {string} The wrapped string after process.
624 */
625 goog.i18n.bidi.enforceLtrInText = function(text) {
626 return goog.i18n.bidi.Format.LRE + text + goog.i18n.bidi.Format.PDF;
627 };
628
629
630 /**
631 * Regular expression to find dimensions such as "padding: .3 0.4ex 5px 6;"
632 * @type {RegExp}
633 * @private
634 */
635 goog.i18n.bidi.dimensionsRe_ =
636 /:\s*([.\d][.\w]*)\s+([.\d][.\w]*)\s+([.\d][.\w]*)\s+([.\d][.\w]*)/g;
637
638
639 /**
640 * Regular expression for left.
641 * @type {RegExp}
642 * @private
643 */
644 goog.i18n.bidi.leftRe_ = /left/gi;
645
646
647 /**
648 * Regular expression for right.
649 * @type {RegExp}
650 * @private
651 */
652 goog.i18n.bidi.rightRe_ = /right/gi;
653
654
655 /**
656 * Placeholder regular expression for swapping.
657 * @type {RegExp}
658 * @private
659 */
660 goog.i18n.bidi.tempRe_ = /%%%%/g;
661
662
663 /**
664 * Swap location parameters and 'left'/'right' in CSS specification. The
665 * processed string will be suited for RTL layout. Though this function can
666 * cover most cases, there are always exceptions. It is suggested to put
667 * those exceptions in separate group of CSS string.
668 * @param {string} cssStr CSS spefication string.
669 * @return {string} Processed CSS specification string.
670 */
671 goog.i18n.bidi.mirrorCSS = function(cssStr) {
672 return cssStr
673 .
674 // reverse dimensions
675 replace(goog.i18n.bidi.dimensionsRe_, ':$1 $4 $3 $2')
676 .replace(goog.i18n.bidi.leftRe_, '%%%%')
677 . // swap left and right
678 replace(goog.i18n.bidi.rightRe_, goog.i18n.bidi.LEFT)
679 .replace(goog.i18n.bidi.tempRe_, goog.i18n.bidi.RIGHT);
680 };
681
682
683 /**
684 * Regular expression for hebrew double quote substitution, finding quote
685 * directly after hebrew characters.
686 * @type {RegExp}
687 * @private
688 */
689 goog.i18n.bidi.doubleQuoteSubstituteRe_ = /([\u0591-\u05f2])"/g;
690
691
692 /**
693 * Regular expression for hebrew single quote substitution, finding quote
694 * directly after hebrew characters.
695 * @type {RegExp}
696 * @private
697 */
698 goog.i18n.bidi.singleQuoteSubstituteRe_ = /([\u0591-\u05f2])'/g;
699
700
701 /**
702 * Replace the double and single quote directly after a Hebrew character with
703 * GERESH and GERSHAYIM. In such case, most likely that's user intention.
704 * @param {string} str String that need to be processed.
705 * @return {string} Processed string with double/single quote replaced.
706 */
707 goog.i18n.bidi.normalizeHebrewQuote = function(str) {
708 return str.replace(goog.i18n.bidi.doubleQuoteSubstituteRe_, '$1\u05f4')
709 .replace(goog.i18n.bidi.singleQuoteSubstituteRe_, '$1\u05f3');
710 };
711
712
713 /**
714 * Regular expression to split a string into "words" for directionality
715 * estimation based on relative word counts.
716 * @type {RegExp}
717 * @private
718 */
719 goog.i18n.bidi.wordSeparatorRe_ = /\s+/;
720
721
722 /**
723 * Regular expression to check if a string contains any numerals. Used to
724 * differentiate between completely neutral strings and those containing
725 * numbers, which are weakly LTR.
726 *
727 * Native Arabic digits (\u0660 - \u0669) are not included because although they
728 * do flow left-to-right inside a number, this is the case even if the overall
729 * directionality is RTL, and a mathematical expression using these digits is
730 * supposed to flow right-to-left overall, including unary plus and minus
731 * appearing to the right of a number, and this does depend on the overall
732 * directionality being RTL. The digits used in Farsi (\u06F0 - \u06F9), on the
733 * other hand, are included, since Farsi math (including unary plus and minus)
734 * does flow left-to-right.
735 *
736 * @type {RegExp}
737 * @private
738 */
739 goog.i18n.bidi.hasNumeralsRe_ = /[\d\u06f0-\u06f9]/;
740
741
742 /**
743 * This constant controls threshold of RTL directionality.
744 * @type {number}
745 * @private
746 */
747 goog.i18n.bidi.rtlDetectionThreshold_ = 0.40;
748
749
750 /**
751 * Estimates the directionality of a string based on relative word counts.
752 * If the number of RTL words is above a certain percentage of the total number
753 * of strongly directional words, returns RTL.
754 * Otherwise, if any words are strongly or weakly LTR, returns LTR.
755 * Otherwise, returns UNKNOWN, which is used to mean "neutral".
756 * Numbers are counted as weakly LTR.
757 * @param {string} str The string to be checked.
758 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
759 * Default: false.
760 * @return {goog.i18n.bidi.Dir} Estimated overall directionality of {@code str}.
761 */
762 goog.i18n.bidi.estimateDirection = function(str, opt_isHtml) {
763 var rtlCount = 0;
764 var totalCount = 0;
765 var hasWeaklyLtr = false;
766 var tokens = goog.i18n.bidi.stripHtmlIfNeeded_(str, opt_isHtml)
767 .split(goog.i18n.bidi.wordSeparatorRe_);
768 for (var i = 0; i < tokens.length; i++) {
769 var token = tokens[i];
770 if (goog.i18n.bidi.startsWithRtl(token)) {
771 rtlCount++;
772 totalCount++;
773 } else if (goog.i18n.bidi.isRequiredLtrRe_.test(token)) {
774 hasWeaklyLtr = true;
775 } else if (goog.i18n.bidi.hasAnyLtr(token)) {
776 totalCount++;
777 } else if (goog.i18n.bidi.hasNumeralsRe_.test(token)) {
778 hasWeaklyLtr = true;
779 }
780 }
781
782 return totalCount == 0 ?
783 (hasWeaklyLtr ? goog.i18n.bidi.Dir.LTR : goog.i18n.bidi.Dir.NEUTRAL) :
784 (rtlCount / totalCount > goog.i18n.bidi.rtlDetectionThreshold_ ?
785 goog.i18n.bidi.Dir.RTL :
786 goog.i18n.bidi.Dir.LTR);
787 };
788
789
790 /**
791 * Check the directionality of a piece of text, return true if the piece of
792 * text should be laid out in RTL direction.
793 * @param {string} str The piece of text that need to be detected.
794 * @param {boolean=} opt_isHtml Whether str is HTML / HTML-escaped.
795 * Default: false.
796 * @return {boolean} Whether this piece of text should be laid out in RTL.
797 */
798 goog.i18n.bidi.detectRtlDirectionality = function(str, opt_isHtml) {
799 return goog.i18n.bidi.estimateDirection(str, opt_isHtml) ==
800 goog.i18n.bidi.Dir.RTL;
801 };
802
803
804 /**
805 * Sets text input element's directionality and text alignment based on a
806 * given directionality. Does nothing if the given directionality is unknown or
807 * neutral.
808 * @param {Element} element Input field element to set directionality to.
809 * @param {goog.i18n.bidi.Dir|number|boolean|null} dir Desired directionality,
810 * given in one of the following formats:
811 * 1. A goog.i18n.bidi.Dir constant.
812 * 2. A number (positive = LRT, negative = RTL, 0 = neutral).
813 * 3. A boolean (true = RTL, false = LTR).
814 * 4. A null for unknown directionality.
815 */
816 goog.i18n.bidi.setElementDirAndAlign = function(element, dir) {
817 if (element) {
818 dir = goog.i18n.bidi.toDir(dir);
819 if (dir) {
820 element.style.textAlign = dir == goog.i18n.bidi.Dir.RTL ?
821 goog.i18n.bidi.RIGHT :
822 goog.i18n.bidi.LEFT;
823 element.dir = dir == goog.i18n.bidi.Dir.RTL ? 'rtl' : 'ltr';
824 }
825 }
826 };
827
828
829 /**
830 * Sets element dir based on estimated directionality of the given text.
831 * @param {!Element} element
832 * @param {string} text
833 */
834 goog.i18n.bidi.setElementDirByTextDirectionality = function(element, text) {
835 switch (goog.i18n.bidi.estimateDirection(text)) {
836 case (goog.i18n.bidi.Dir.LTR):
837 element.dir = 'ltr';
838 break;
839 case (goog.i18n.bidi.Dir.RTL):
840 element.dir = 'rtl';
841 break;
842 default:
843 // Default for no direction, inherit from document.
844 element.removeAttribute('dir');
845 }
846 };
847
848
849
850 /**
851 * Strings that have an (optional) known direction.
852 *
853 * Implementations of this interface are string-like objects that carry an
854 * attached direction, if known.
855 * @interface
856 */
857 goog.i18n.bidi.DirectionalString = function() {};
858
859
860 /**
861 * Interface marker of the DirectionalString interface.
862 *
863 * This property can be used to determine at runtime whether or not an object
864 * implements this interface. All implementations of this interface set this
865 * property to {@code true}.
866 * @type {boolean}
867 */
868 goog.i18n.bidi.DirectionalString.prototype
869 .implementsGoogI18nBidiDirectionalString;
870
871
872 /**
873 * Retrieves this object's known direction (if any).
874 * @return {?goog.i18n.bidi.Dir} The known direction. Null if unknown.
875 */
876 goog.i18n.bidi.DirectionalString.prototype.getDirection;