bidi_utils.dart

// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

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.
 */
class TextDirection {
  static const LTR = const TextDirection._(
    'LTR', 'ltr', Bidi.LRM, Bidi.LRE, Bidi._LTR_CHARS);
  static const RTL = const TextDirection._(
    'RTL', 'rtl', Bidi.RLM, Bidi.RLE, Bidi._RTL_CHARS);
  
  factory TextDirection.estimate(String text, {bool isHtml: false}) => 
      Bidi.estimateDirectionOfText(text, isHtml: isHtml);
  
  /**
   * Textual representation of the directionality constant. One of
   * 'LTR' or 'RTL'.
   */
  final String value;

  /** Textual representation of the directionality when used in span tag. */
  final String spanText;

  /** Unicode mark character. */
  final String markChar;

  /** Unicode embedding character. */
  final String embeddingChar;
  
  TextDirection get opposite => value == 'LTR' ? RTL : LTR;
  
  final String _chars;

  const TextDirection._(this.value, this.spanText, this.markChar, this.embeddingChar, this._chars);
  
  /**
   * Determines if the first character in [text] with strong directionality is
   * this direction. If [isHtml] is true, the text is HTML or HTML-escaped.
   */
  bool starts(String text, {isHtml = false}) {
    return new RegExp('^[^${opposite._chars}]*[$_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.
   */
  bool ends(String text, {isHtml = false}) {
    return new RegExp('[$_chars][^${opposite._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.
   */
  bool appearsIn(String text, {isHtml = false}) {
    return new RegExp(r'[' '$_chars' r']').hasMatch(
        isHtml? stripHtmlIfNeeded(text) : text);
  }
  
  /**
   * Check if a BCP 47 / III [languageString] indicates a language of this
   * directionality.
   */
  bool hasLanguage(String language) {
    bool isRtl = Bidi.isRtlLanguage(language);
    return value == 'RTL' ? isRtl : !isRtl;
  }
  
  /**
   * Enforce the [html] snippet in this 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).
   */
  String enforceInHtml(String html) {
    return Bidi._enforceInHtmlHelper(html, spanText);
  }

  /**
   * Enforce RTL on both end of the given [text] using unicode BiDi formatting
   * characters RLE and PDF.
   */
  String enforceInText(String text) => '$embeddingChar$text$PDF';

}