org.eclipse.osgi.service.localization;version="1.1.0",

/*******************************************************************************

 * Copyright (c) 2010, 2011 IBM Corporation and others.

 * All rights reserved. This program and the accompanying materials

 * are made available under the terms of the Eclipse Public License v1.0

 * which accompanies this distribution, and is available at

 * http://www.eclipse.org/legal/epl-v10.html

 *

 * Contributors:

 *     IBM Corporation - initial API and implementation

 ******************************************************************************/

package org.eclipse.equinox.bidi;

import java.util.Locale;

import org.eclipse.equinox.bidi.custom.IBidiComplexProcessor;

import org.eclipse.equinox.bidi.internal.BidiComplexActivator;

/**

 *  This class defines certain details of the environment within which

 *  complex expressions are processed.

 *  <p>

 *  All public fields in this class are <code>final</code>, i.e. cannot be

 *  changed after creating an instance.

 *  <p>

 *  A <code>BidiComplexEnvironment</code> instance can be associated with a <code>BidiComplexHelper</code>

 *  instance either when creating the

 * {@link BidiComplexHelper#BidiComplexHelper(java.lang.String, BidiComplexEnvironment) BidiComplexHelper} instance

 *  or using the {@link BidiComplexHelper#setEnvironment setEnvironment} method.

 *

 *  <h2>Code Samples</h2>

 *  <p>Example 1 (set all environment parameters)

 *  <pre>

 *

 *    BidiComplexEnvironment myEnv = new BidiComplexEnvironment("he_IL", true, BidiComplexEnvironment.ORIENT_RTL);

 *    BidiComplexHelper myHelper = new BidiComplexHelper(IBidiComplexExpressionTypes.FILE, myEnv);

 *

 *  </pre>

 *  <p>Example 2 (change only the orientation)

 *  <pre>

 *

 *    BidiComplexEnvironment env1 = myHelper.getEnvironment();

 *    BidiComplexEnvironment env2 = new BidiComplexEnvironment(env1.language, env1.mirrored, BidiComplexEnvironment.ORIENT_UNKNOWN);

 *    myHelper.setEnvironment(env2);

 *

 *  </pre>

 *  <p>

 *  This class also provides a number of convenience methods related to the environment.

 *  <p>&nbsp;</p>

 *  @see BidiComplexHelper#BidiComplexHelper(String, BidiComplexEnvironment)

 *  @see BidiComplexHelper#BidiComplexHelper(IBidiComplexProcessor, BidiComplexEnvironment)

 *  @see BidiComplexHelper#getEnvironment BidiComplexHelper.getEnvironment

 *  @see BidiComplexHelper#setEnvironment BidiComplexHelper.setEnvironment

 *  @see IBidiComplexProcessor#init IBidiComplexProcessor.init

 *  @see IBidiComplexProcessor#updateEnvironment IBidiComplexProcessor.updateEnvironment

 *

 *  @author Matitiahu Allouche

 */

public class BidiComplexEnvironment {

	/**

	 *  Constant specifying that the orientation of the GUI component

	 *  where a complex expression will be displayed is LTR.

	 *  It can appear as <code>orientation</code> argument for

	 *  {@link BidiComplexEnvironment#BidiComplexEnvironment BidiComplexEnvironment constructor} and as value for the

	 *  {@link BidiComplexEnvironment#orientation} member of <code>BidiComplexEnvironment</code>.

	 */

	public static final int ORIENT_LTR = 0;

	/**

	 *  Constant specifying that the orientation of the GUI component

	 *  where a complex expression will be displayed is RTL.

	 *  It can appear as <code>orientation</code> argument for

	 *  {@link BidiComplexEnvironment#BidiComplexEnvironment BidiComplexEnvironment constructor} and as value for the

	 *  {@link BidiComplexEnvironment#orientation} member of <code>BidiComplexEnvironment</code>.

	 */

	public static final int ORIENT_RTL = 1;

	/**

	 *  Constant specifying that the orientation of the GUI component

	 *  where a complex expression will be displayed is contextual with

	 *  a default of LTR (if no strong character appears in the text).

	 *  It can appear as <code>orientation</code> argument for

	 *  {@link BidiComplexEnvironment#BidiComplexEnvironment BidiComplexEnvironment constructor} and as value for the

	 *  {@link BidiComplexEnvironment#orientation} member of <code>BidiComplexEnvironment</code>.

	 */

	public static final int ORIENT_CONTEXTUAL_LTR = 2;

	/**

	 *  Constant specifying that the orientation of the GUI component

	 *  where a complex expression will be displayed is contextual with

	 *  a default of RTL (if no strong character appears in the text).

	 *  It can appear as <code>orientation</code> argument for

	 *  {@link BidiComplexEnvironment#BidiComplexEnvironment BidiComplexEnvironment constructor} and as value for the

	 *  {@link BidiComplexEnvironment#orientation} member of <code>BidiComplexEnvironment</code>.

	 */

	public static final int ORIENT_CONTEXTUAL_RTL = 3;

	/**

	 *  Constant specifying that the orientation of the GUI component

	 *  where a complex expression will be displayed is not known.

	 *  Directional formatting characters must be added as prefix and

	 *  suffix whenever a <i>full</i> text is generated using

	 *  {@link BidiComplexHelper#leanToFullText leanToFullText}.

	 *  It can appear as <code>orientation</code> argument for

	 *  {@link BidiComplexEnvironment#BidiComplexEnvironment BidiComplexEnvironment constructor} and as value for the

	 *  {@link BidiComplexEnvironment#orientation} member of <code>BidiComplexEnvironment</code>.

	 */

	public static final int ORIENT_UNKNOWN = 4;

	/**

	 *  Constant specifying that whatever the orientation of the

	 *  GUI component where a complex expression will be displayed, no

	 *  directional formatting characters must be added as prefix or

	 *  suffix when a <i>full</i> text is generated using

	 *  {@link BidiComplexHelper#leanToFullText leanToFullText}.

	 *  It can appear as <code>orientation</code> argument for

	 *  {@link BidiComplexEnvironment#BidiComplexEnvironment BidiComplexEnvironment constructor} and as value for the

	 *  {@link BidiComplexEnvironment#orientation} member of <code>BidiComplexEnvironment</code>.

	 */

	public static final int ORIENT_IGNORE = 5;

	/**

	 *  Pre-defined <code>BidiComplexEnvironment</code> instance with values for a non-mirrored GUI

	 *  and a Left-to-Right presentation component.<br>

	 *  The language is set to <code>null</code>, which defaults to the language

	 *  of the current default locale.

	 */

	public static final BidiComplexEnvironment DEFAULT = new BidiComplexEnvironment(null, false, ORIENT_LTR);

	/**

	 *  This string is a 2-letters code representing a language as defined by

	 *  ISO-639. If left as <code>null</code>, it defaults to the language

	 *  of the current default locale.

	 */

	public final String language;

	/**

	 *  Flag specifying that complex expressions processed under this environment

	 *  should assume that the GUI is mirrored (globally going from right to left).

	 */

	public final boolean mirrored;

	/** Specify the orientation (a.k.a. base direction) of the GUI

	 *  component in which the <i>full</i> text of the complex expression will

	 *  be displayed.<br>

	 *  The orientation must have one of the values

	 *  {@link #ORIENT_LTR ORIENT_LTR},

	 *  {@link #ORIENT_LTR ORIENT_RTL},

	 *  {@link #ORIENT_CONTEXTUAL_LTR ORIENT_CONTEXTUAL_LTR},

	 *  {@link #ORIENT_CONTEXTUAL_RTL ORIENT_CONTEXTUAL_RTL},

	 *  {@link #ORIENT_UNKNOWN ORIENT_UNKNOWN} or

	 *  {@link #ORIENT_IGNORE ORIENT_IGNORE}.

	  *  <p>

	 *  When the orientation is <code>ORIENT_LTR</code> and the complex

	 *  expression has a RTL base direction,

	 *  {@link BidiComplexHelper#leanToFullText leanToFullText}

	 *  adds RLE+RLM at the head of the <i>full</i> text and RLM+PDF at its

	 *  end.

	 *  <p>

	 *  When the orientation is <code>ORIENT_RTL</code> and the complex

	 *  expression has a LTR base direction,

	 *  {@link BidiComplexHelper#leanToFullText leanToFullText}

	 *  adds LRE+LRM at the head of the <i>full</i> text and LRM+PDF at its

	 *  end.

	 *  <p>

	 *  When the orientation is <code>ORIENT_CONTEXTUAL_LTR</code> or

	 *  <code>ORIENT_CONTEXTUAL_RTL</code> and the data content would resolve

	 *  to a RTL orientation while the complex expression has a LTR base

	 *  direction, {@link BidiComplexHelper#leanToFullText leanToFullText}

	 *  adds LRM at the head of the <i>full</i> text.

	 *  <p>

	 *  When the orientation is <code>ORIENT_CONTEXTUAL_LTR</code> or

	 *  <code>ORIENT_CONTEXTUAL_RTL</code> and the data content would resolve

	 *  to a LTR orientation while the complex expression has a RTL base

	 *  direction, {@link BidiComplexHelper#leanToFullText leanToFullText}

	 *  adds RLM at the head of the <i>full</i> text.

	 *  <p>

	 *  When the orientation is <code>ORIENT_UNKNOWN</code> and the complex

	 *  expression has a LTR base direction,

	 *  {@link BidiComplexHelper#leanToFullText leanToFullText}

	 *  adds LRE+LRM at the head of the <i>full</i> text and LRM+PDF at its

	 *  end.

	 *  <p>

	 *  When the orientation is <code>ORIENT_UNKNOWN</code> and the complex

	 *  expression has a RTL base direction,

	 *  {@link BidiComplexHelper#leanToFullText leanToFullText}

	 *  adds RLE+RLM at the head of the <i>full</i> text and RLM+PDF at its

	 *  end.

	 *  <p>

	 *  When the orientation is <code>ORIENT_IGNORE</code>,

	 *  {@link BidiComplexHelper#leanToFullText leanToFullText} does not add any directional

	 *  formatting characters as either prefix or suffix of the <i>full</i> text.

	 *  <p>

	 */

	public final int orientation;

	static Locale defaultLocale;

	static String defaultLanguage;

	static boolean defaultBidi;

	boolean bidiFlag;

	/**

	 *  Constructor

	 *

	 *  @param lang represents the language to be used in this environment.

	 *          It should be specified as a 2-letters code as defined by

	 *          ISO-639.<br>

	 *          If longer than 2 letters, the extra letters are ignored.<br>

	 *          If set to <code>null</code>, it defaults to the language

	 *          of the default locale.

	 *  @see #language

	 *

	 *  @param mirrored specifies if the GUI is mirrored.

	 *  @see #mirrored

	 *

	 *  @param orientation specifies the orientation of the component

	 *          which is to display the complex expression. It must be

	 *          one of the values

	 *          {@link #ORIENT_LTR ORIENT_LTR},

	 *          {@link #ORIENT_LTR ORIENT_RTL},

	 *          {@link #ORIENT_CONTEXTUAL_LTR ORIENT_CONTEXTUAL_LTR},

	 *          {@link #ORIENT_CONTEXTUAL_RTL ORIENT_CONTEXTUAL_RTL},

	 *          {@link #ORIENT_UNKNOWN ORIENT_UNKNOWN} or

	 *          {@link #ORIENT_IGNORE ORIENT_IGNORE}.<br>

	 *          If different, it defaults to {@link #ORIENT_UNKNOWN ORIENT_UNKNOWN}.

	 *  @see #orientation

	 */

	public BidiComplexEnvironment(String lang, boolean mirrored, int orientation) {

		if (lang == null) {

			language = null;

		} else {

			if (lang.length() > 2)

				language = lang.substring(0, 2);

			else

				language = lang;

			bidiFlag = isBidiLanguage(language);

		}

		this.mirrored = mirrored;

		this.orientation = orientation >= ORIENT_LTR && orientation <= ORIENT_IGNORE ? orientation : ORIENT_UNKNOWN;

	}

	/**

	 *  Check whether the current language uses a

	 *  bidi script (Arabic, Hebrew, Farsi or Urdu).

	 *

	 *  @return <code>true</code> if the current language uses a bidi script.

	 *          The language may have been set explicitly when creating the

	 *          <code>BidiComplexEnvironment</code> instance, or it may have defaulted to

	 *          the language of the current default locale.

	 *  @see #BidiComplexEnvironment BidiComplexEnvironment

	 */

	public boolean isBidi() {

		if (defaultLanguage != null && defaultLocale.equals(getDefaultLocale()))

			return defaultBidi;

		if (language == null) {

			defaultLocale = getDefaultLocale();

			defaultLanguage = defaultLocale.getLanguage();

			defaultBidi = isBidiLanguage(defaultLanguage);

			return defaultBidi;

		}

		return bidiFlag;

	}

	static boolean isBidiLanguage(String lang) {

		return "iw".equals(lang) || "he".equals(lang) || "ar".equals(lang) || "fa".equals(lang) || "ur".equals(lang); //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$ //$NON-NLS-4$ //$NON-NLS-5$

	}

	static String lineSep;

	/**

	 *  Retrieve the string which represents a line separator in this environment.

	 *

	 *  @return the string which is used as line separator (e.g. CRLF).

	 */

	public static String getLineSep() {

		// use bundle properties

		if (lineSep == null) {

			//          lineSep = System.getProperty("line.separator", "\n"); //$NON-NLS-1$//$NON-NLS-2$

			lineSep = getProperty("line.separator"); //$NON-NLS-1$/

		}

		return lineSep;

	}

	static String osName;

	static boolean flagOS;

	private static String getProperty(String key) {

		// use bundle properties

		//      osName = System.getProperty("os.name").toLowerCase(); //$NON-NLS-1$

		BidiComplexActivator bidiComplexActivator = BidiComplexActivator.getInstance();

		return bidiComplexActivator.getProperty(key);

	}

	private Locale getDefaultLocale() {

		BidiComplexActivator bidiComplexActivator = BidiComplexActivator.getInstance();

		return bidiComplexActivator.getDefaultLocale();

	}

	/**

	 *  Check if the current OS is supported by the complex expression packages.

	 *

	 *  @return <code>true</code> if the current OS is supported.

	 */

	public static boolean isSupportedOS() {

		if (osName == null) {

			// use bundle properties

			// osName = System.getProperty("os.name").toLowerCase(); //$NON-NLS-1$

			osName = getProperty("os.name").toLowerCase(); //$NON-NLS-1$/

			flagOS = osName.startsWith("windows") || osName.startsWith("linux"); //$NON-NLS-1$ //$NON-NLS-2$

		}

		return flagOS;

	}

}

/*******************************************************************************

 * Copyright (c) 2010, 2011 IBM Corporation and others.

 * All rights reserved. This program and the accompanying materials

 * are made available under the terms of the Eclipse Public License v1.0

 * which accompanies this distribution, and is available at

 * http://www.eclipse.org/legal/epl-v10.html

 *

 * Contributors:

 *     IBM Corporation - initial API and implementation

 ******************************************************************************/

package org.eclipse.equinox.bidi;

import org.eclipse.equinox.bidi.custom.IBidiComplexProcessor;

/**

 *  This class defines features of a complex expression processor.

 *  <p>

 *  All public fields in this class are <code>final</code>, i.e. cannot be

 *  changed after creating an instance.

 *  <p>

 *  A <code>BidiComplexFeatures</code> instance can be associated with a

 *  <code>BidiComplexHelper</code> instance using

 *  the {@link BidiComplexHelper#setFeatures setFeatures} method.

 *

 *  <h2>Code Samples</h2>

 *  <p>Example 1 (set all features)

 *  <pre>

 *

 *    BidiComplexFeatures myFeatures = new BidiComplexFeatures("+-=", 0, -1, -1, false, false);

 *    BidiComplexHelper myHelper = new BidiComplexHelper(IBidiComplexExpressionTypes.FILE, myEnv);

 *    myHelper.setFeatures(myFeatures);

 *

 *  </pre>

 *  <p>Example 2 (change only the operators)

 *  <pre>

 *

 *    BidiComplexFeatures f1 = myHelper.getFeatures();

 *    BidiComplexFeatures f2 = new BidiComplexFeatures("[]|()", f1.specialsCount,

 *                                     f1.dirArabic, f1.dirHebrew,

 *                                     f1.ignoreArabic, f1.ignoreHebrew);

 *    myHelper.setFeatures(f2);

 *

 *  </pre>

 *

 *  @see BidiComplexHelper#getFeatures BidiComplexHelper.getFeatures

 *  @see BidiComplexHelper#setFeatures BidiComplexHelper.setFeatures

 *  @see IBidiComplexProcessor#init IBidiComplexProcessor.init

 *  @see IBidiComplexProcessor#updateEnvironment IBidiComplexProcessor.updateEnvironment

 *

 *  @author Matitiahu Allouche

 */

public class BidiComplexFeatures {

	/**

	 *  Constant specifying that the base direction of a complex expression is LTR.

	 *  The base direction may depend on whether the GUI is

	 *  {@link BidiComplexEnvironment#mirrored mirrored} and may

	 *  may be different for Arabic and for Hebrew.

	 *  This constant can appear as <code>dirArabic</code>

	 *  or <code>dirHebrew</code> argument for

	 *  {@link BidiComplexFeatures#BidiComplexFeatures BidiComplexFeatures constructor} and as value

	 *  for the {@link #dirArabic} or {@link #dirHebrew} members of

	 *  <code>BidiComplexFeatures</code>.

	 */

	public static final int DIR_LTR = 0;

	/**

	 *  Constant specifying that the base direction of a complex expression is RTL.

	 *  The base direction may depend on whether the GUI is

	 *  {@link BidiComplexEnvironment#mirrored mirrored} and may

	 *  may be different for Arabic and for Hebrew.

	 *  This constant can appear as <code>dirArabic</code>

	 *  or <code>dirHebrew</code> argument for

	 *  {@link BidiComplexFeatures#BidiComplexFeatures BidiComplexFeatures constructor} and as value

	 *  for the {@link #dirArabic} or {@link #dirHebrew} members of

	 *  <code>BidiComplexFeatures</code>.

	 */

	public static final int DIR_RTL = 1;

	/**

	 *  Pre-defined <code>BidiComplexFeatures</code> instance with values for no

	 *  operators, no special processing, all directions LTR

	 *  and support for neither Arabic nor Hebrew.<br>

	 *  Since there are no operators and no special processing, a complex

	 *  expression processor with such features would do nothing.<br>

	 *  It is more efficient to do nothing with a

	 *  {@link BidiComplexHelper#BidiComplexHelper() BidiComplexHelper}

	 *  instantiated with no arguments.

	 */

	public static final BidiComplexFeatures DEFAULT = new BidiComplexFeatures(null, 0, -1, -1, true, true);

	/**

	 *  String grouping one-character operators which

	 *  separate the text of the complex expression into tokens.

	 */

	public final String operators;

	/**

	 *  Number of special cases for the associated processor.

	 *  Special cases exist for some types of complex expression processors.

	 *  They are implemented by overriding methods

	 *  {@link IBidiComplexProcessor#indexOfSpecial indexOfSpecial} and

	 *  {@link IBidiComplexProcessor#processSpecial processSpecial}.

	 *  Examples of special cases are comments, literals, or anything which

	 *  is not identified by a one-character operator.

	 */

	public final int specialsCount;

	/**

	 *  Base direction of the complex expression for Arabic.

	 *  If a complex expression contains both Arabic and

	 *  Hebrew words, the first Arabic or Hebrew letter in the

	 *  expression determines which is the governing script).<br>

	 *  The value of this field must be one of

	 *  {@link #DIR_LTR} or {@link #DIR_RTL}.

	 *

	 *  @see #dirHebrew

	 */

	public final int dirArabic;

	/**

	 *  Base direction of the complex expression for Hebrew.

	 *  If a complex expression contains both Arabic and

	 *  Hebrew words, the first Arabic or Hebrew letter in the

	 *  expression determines which is the governing script).<br>

	 *  The value of this field must be one of

	 *  {@link #DIR_LTR} or {@link #DIR_RTL}.

	 *

	 *  @see #dirArabic

	 */

	public final int dirHebrew;

	/**

	 *  Flag indicating that Arabic letters will not be considered for

	 *  processing complex expressions. If both this flag and

	 *  {@link #ignoreHebrew} are set to <code>true</code>, the

	 *  processor will do nothing (but some overhead can be expected).

	 */

	public final boolean ignoreArabic;

	/**

	 *  Flag indicating that Hebrew letters will not be considered for

	 *  processing complex expressions. If both this flag and

	 *  {@link #ignoreArabic} are set to <code>true</code>, the

	 *  processor will do nothing (but some overhead can be expected).

	 */

	public final boolean ignoreHebrew;

	/**

	 *  Constructor

	 *

	 *  @param operators is a string where each character is a delimiter

	 *          which separates the complex expression into tokens.

	 *  @see #operators

	 *

	 *  @param specialsCount specifies the number of special cases handled

	 *          by the processor.

	 *  @see #specialsCount

	 *

	 *  @param dirArabic specifies the base direction of the complex expression

	 *          for Arabic. It must be {@link #DIR_LTR} or {@link #DIR_RTL}.

	 *          If it is not (for instance if it is a negative value), it

	 *          defaults to <code>DIR_LTR</code>.

	 *  @see #dirArabic

	 *

	 *  @param dirHebrew specifies the base direction of the complex expression

	 *          for Hebrew. It must be {@link #DIR_LTR} or {@link #DIR_RTL}.

	 *          If it is not (for instance if it is a negative value), it

	 *          defaults to <code>DIR_LTR</code>.

	 *  @see #dirHebrew

	 *

	 *  @param ignoreArabic indicates that Arabic letters will not be

	 *          considered for processing complex expressions.

	 *  @see #ignoreArabic

	 *

	 *  @param ignoreHebrew indicates that Hebrew letters will not be

	 *          considered for processing complex expressions.

	 *  @see #ignoreHebrew

	 */

	public BidiComplexFeatures(String operators, int specialsCount, int dirArabic, int dirHebrew, boolean ignoreArabic, boolean ignoreHebrew) {

		this.operators = operators == null ? "" : operators; //$NON-NLS-1$

		this.specialsCount = specialsCount;

		this.dirArabic = dirArabic == DIR_LTR || dirArabic == DIR_RTL ? dirArabic : DIR_LTR;

		this.dirHebrew = dirHebrew == DIR_LTR || dirHebrew == DIR_RTL ? dirHebrew : DIR_LTR;

		this.ignoreArabic = ignoreArabic;

		this.ignoreHebrew = ignoreHebrew;

	}

}

/*******************************************************************************

 * Copyright (c) 2010, 2011 IBM Corporation and others.

 * All rights reserved. This program and the accompanying materials

 * are made available under the terms of the Eclipse Public License v1.0

 * which accompanies this distribution, and is available at

 * http://www.eclipse.org/legal/epl-v10.html

 *

 * Contributors:

 *     IBM Corporation - initial API and implementation

 ******************************************************************************/

package org.eclipse.equinox.bidi;

import org.eclipse.equinox.bidi.custom.BidiComplexStringProcessor;

import org.eclipse.equinox.bidi.custom.IBidiComplexProcessor;

import org.eclipse.equinox.bidi.internal.BidiComplexImpl;

/**

 *  This class acts as a mediator between applications and complex

 *  expression processors.

 *  The purpose of complex expression processors is to add directional

 *  formatting characters to ensure correct display.

 *  This class shields applications from the

 *  intricacies of complex expression processors.

 *  <p>

 *  For a general introduction to complex expressions, see

 *  {@link <a href="package-summary.html">

 *  the package documentation</a>}.

 *

 *  <h2>Code Sample</h2>

 *

 *  <p>The following code shows how to instantiate a BidiComplexHelper adapted for a

 *  certain type of complex expression (directory and file paths), and how

 *  to obtain the <i>full</i> text corresponding to the <i>lean</i> text

 *  of such an expression.

 *

 *  <pre>

 *

 *    BidiComplexHelper helper = new BidiComplexHelper(IBidiComplexExpressionTypes.FILE);

 *    String leanText = "D:\\\u05d0\u05d1\\\u05d2\\\u05d3.ext";

 *    String fullText = helper.leanToFullText(leanText);

 *    System.out.println("full text = " + fullText);

 *

 *  </pre>

 *  This class provides a user-oriented API but does not provides

 *  an actual implementation. The real work is done by the class

 *  {@link BidiComplexImpl}. Users of the API need not be concerned by, and

 *  should not depend upon, details of the implementation by

 *  <code>BidiComplexImpl</code>.

 *

 *  @author Matitiahu Allouche

 *

 */

public class BidiComplexHelper {

	/**

	 *  Constant to use as <code>initState</code> argument when calling

	 *  {@link #leanToFullText(java.lang.String, int) leanToFullText} or

	 *  {@link #fullToLeanText(java.lang.String, int) fullToLeanText}

	 *  to indicate that there is no context of previous lines which

	 *  should be initialized before performing the operation.

	 */

	public static final int STATE_NOTHING_GOING = -1;

	private static final int[] EMPTY_INT_ARRAY = new int[0];

	/**

	 *  Reference to the {@link BidiComplexImpl} instance which accomplishes

	 *  most of the work. This member should be accessed only by

	 *  complex expression processors (implementing {@link IBidiComplexProcessor}).

	 */

	public BidiComplexImpl impl;

	/**

	 *  Create a <code>BidiComplexHelper</code> instance which does nothing tangible

	 *  but does it quickly. We will call it a <i>no-op helper</i>.

	 *  The {@link #BidiComplexHelper() no-op helper} does not modify text submitted to it, and can be

	 *  used when it is known that no complex expression processing

	 *  is needed, for instance because no bidi text is expected. With this

	 *  helper, the cost of invoking the complex expression API is minimal.

	 */

	public BidiComplexHelper() {

		// let impl stay null

	}

	/**

	 *  Create a <code>BidiComplexHelper</code> instance to process expressions

	 *  of type <code>type</code> with a

	 *  {@link BidiComplexEnvironment#DEFAULT DEFAULT} environment.

	 *

	 *  @param type represents the type of the complex expression. It must

	 *          be one of the values in {@link IBidiComplexExpressionTypes}, or a type

	 *          added in a plug-in extension.

	 *

	 *  @throws IllegalArgumentException if the <code>type</code> is not

	 *          supported.

	 */

	public BidiComplexHelper(String type) {

		this(type, null);

	}

	/**

	 *  Create a <code>BidiComplexHelper</code> instance to process expressions

	 *  of type <code>type</code> operating under the environment

	 *  {@link BidiComplexEnvironment environment}.

	 *

	 *  @param type represents the type of the complex expression. It must

	 *          be one of the values in {@link IBidiComplexExpressionTypes}, or a type

	 *          added in a plug-in extension.

	 *

	 *  @param environment represents the environment where the complex expression

	 *          will be displayed. It is better to specify the environment

	 *          when instantiating a <code>BidiComplexHelper</code> than to specify

	 *          it later using {@link #setEnvironment setEnvironment}.<br>

	 *          <code>null</code> can be specified here for a

	 *          {@link BidiComplexEnvironment#DEFAULT DEFAULT} environment.

	 *

	 *  @throws IllegalArgumentException if the <code>type</code> is not

	 *          supported.

	 */

	public BidiComplexHelper(String type, BidiComplexEnvironment environment) {

		IBidiComplexProcessor processor = BidiComplexStringProcessor.getProcessor(type);

		if (processor == null) {

			throw new IllegalArgumentException("Invalid processor type!"); //$NON-NLS-1$

		}

		impl = new BidiComplexImpl(this, processor, environment);

	}

	/**

	 *  Create a <code>BidiComplexHelper</code> instance to process complex

	 *  expressions by means of a given processor <code>myProcessor</code>,

	 *  operating under the environment {@link BidiComplexEnvironment environment}.

	 *

	 *  @param myProcessor is a complex expression processor.

	 *

	 *  @param environment represents the environment where the complex expression

	 *          will be displayed. It is better to specify the environment

	 *          when instantiating a <code>BidiComplexHelper</code> than to specify

	 *          it later using {@link #setEnvironment setEnvironment}.<br>

	 *          <code>null</code> can be specified here for a

	 *          {@link BidiComplexEnvironment#DEFAULT DEFAULT} environment.

	 */

	public BidiComplexHelper(IBidiComplexProcessor myProcessor, BidiComplexEnvironment environment) {

		impl = new BidiComplexImpl(this, myProcessor, environment);

	}

	/** Add directional formatting characters to a complex expression

	 *  to ensure correct presentation.

	 *

	 *  @param text is the text of the complex expression.

	 *

	 *  @return the complex expression with directional formatting

	 *          characters added at proper locations to ensure correct

	 *          presentation.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns <code>text</code>.

	 */

	public String leanToFullText(String text) {

		return leanToFullText(text, STATE_NOTHING_GOING);

	}

	/**

	 *  Add directional formatting characters to a complex expression

	 *  to ensure correct presentation.

	 *

	 *  @param  text is the text of the complex expression.

	 *

	 *  @param  initState specifies that the first parameter is the

	 *          continuation of text submitted in a previous call.

	 *          The <code>initState</code> of the present call must be

	 *          the final state obtained by calling

	 *          {@link #getFinalState() getFinalState}

	 *          after the previous call.

	 *          <br>If the present call is not a continuation of

	 *          text submitted in a previous call, the value

	 *          {@link #STATE_NOTHING_GOING} should be used as argument.

	 *

	 *  @return the complex expression with directional formatting

	 *          characters added at proper locations to ensure correct

	 *          presentation.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns <code>text</code>.

	 *

	 *  @see #getFinalState getFinalState

	 */

	public String leanToFullText(String text, int initState) {

		if (impl == null)

			return text;

		return impl.leanToFullText(text, initState);

	}

	/**

	 *  Given a complex expression, get the offsets of characters before

	 *  which directional formatting characters must be added in order to

	 *  ensure correct presentation.

	 *  Only LRMs (for an expression with LTR base direction) and RLMs (for

	 *  an expression with RTL base direction) are considered. Leading and

	 *  trailing LRE, RLE and PDF which might be prefixed or suffixed

	 *  depending on the {@link BidiComplexEnvironment#orientation orientation} of the

	 *  GUI component used for display are not reflected in this method.

	 *  <p>

	 *  This method assumes that a successful call to

	 *  {@link #leanToFullText leanToFullText} has been performed, and it

	 *  returns the offsets relevant for the last text submitted.

	 *

	 *  @return an array of offsets to the characters in the last submitted

	 *          complex expression before which directional marks must be

	 *          added to ensure correct presentation.

	 *          The offsets are sorted in ascending order.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns an array of 0 elements.

	 */

	public int[] leanBidiCharOffsets() {

		if (impl == null)

			return EMPTY_INT_ARRAY;

		return impl.leanBidiCharOffsets();

	}

	/**

	 *  Get the offsets of characters in the <i>full</i> text of a

	 *  complex expression corresponding to directional formatting

	 *  characters which have been added in order to ensure correct presentation.

	 *  LRMs (for an expression with LTR base direction), RLMs (for

	 *  an expression with RTL base direction) are considered as well as

	 *  leading and trailing LRE, RLE and PDF which might be prefixed or suffixed

	 *  depending on the {@link BidiComplexEnvironment#orientation orientation} of the

	 *  GUI component used for display.

	 *  <p>

	 *  This method assumes that a successful call to

	 *  {@link #leanToFullText leanToFullText} has been performed, and it

	 *  returns the offsets relevant for the last text submitted.

	 *

	 *  @return an array of offsets to the characters in the <i>full</i>

	 *          text of the last submitted complex expression which are

	 *          directional formatting characters added to ensure correct

	 *          presentation.

	 *          The offsets are sorted in ascending order.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns an array of 0 elements.

	 */

	public int[] fullBidiCharOffsets() {

		if (impl == null)

			return EMPTY_INT_ARRAY;

		return impl.fullBidiCharOffsets();

	}

	/**

	 *  Remove directional formatting characters which were added to a

	 *  complex expression to ensure correct presentation.

	 *

	 *  @param text is the text of the complex expression including

	 *         directional formatting characters.

	 *

	 *  @return the complex expression without directional formatting

	 *          characters which might have been added by processing it

	 *          with {@link #leanToFullText leanToFullText}.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns <code>text</code>

	 *

	 */

	public String fullToLeanText(String text) {

		return fullToLeanText(text, STATE_NOTHING_GOING);

	}

	/**

	 *  Remove directional formatting characters which were added to a

	 *  complex expression to ensure correct presentation.

	 *

	 *  @param text is the text of the complex expression including

	 *         directional formatting characters.

	 *

	 *  @param initState specifies that the first parameter is the

	 *         continuation of text submitted in a previous call.

	 *         The <code>initState</code> of the present call must be

	 *         the final state obtained by calling

	 *         {@link #getFinalState getFinalState} after the previous call.

	 *          <br>If the present call is not a continuation of

	 *          text submitted in a previous call, the value

	 *          {@link #STATE_NOTHING_GOING} should be used as argument.

	 *

	 *  @return the complex expression without directional formatting

	 *          characters which might have been added by processing it

	 *          with {@link #leanToFullText leanToFullText}.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns <code>text</code>

	 *

	 *  @see #getFinalState getFinalState

	 */

	public String fullToLeanText(String text, int initState) {

		if (impl == null)

			return text;

		return impl.fullToLeanText(text, initState);

	}

	/**

	 *  Retrieve the final state achieved in a previous call to

	 *  {@link #leanToFullText leanToFullText} or

	 *  {@link #fullToLeanText fullToLeanText}.

	 *  This state is an opaque value which is meaningful only

	 *  within calls to the same complex expression processor.

	 *  The only externalized value is

	 *  {@link #STATE_NOTHING_GOING} which means that

	 *  there is nothing to remember from the last call.

	 *  <p>

	 *  The state should be used only for complex expressions which come

	 *  in parts, like when spanning multiple lines. The user can make

	 *  a separate call to

	 *  <code>leanToFullText</code> or <code>fullToLeanText</code> for each

	 *  line in the expression. The final state value retrieved after the

	 *  call for one line should be used as the initial state in the call

	 *  which processes the next line.

	 *  <p>

	 *  If a line within a complex expression has already been processed by

	 *  <code>leanToFullText</code> and the <i>lean</i> version of that line has

	 *  not changed, and its initial state has not changed either, the user

	 *  can be sure that the <i>full</i> version of that line is also

	 *  identical to the result of the previous processing.

	 *

	 *  @see #leanToFullText(String text, int initState)

	 *  @see #fullToLeanText(String text, int initState)

	 *

	 *  @return the last final state.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns {@link #STATE_NOTHING_GOING}.

	 */

	public int getFinalState() {

		if (impl == null)

			return STATE_NOTHING_GOING;

		return impl.getFinalState();

	}

	/**

	 *  After transforming a <i>lean</i> string into a <i>full</i> string

	 *  using {@link #leanToFullText leanToFullText}, compute the index in the

	 *  <i>full</i> string of the character corresponding to the

	 *  character with the specified position in the <i>lean</i> string.

	 *

	 *  @param position is the index of a character in the <i>lean</i> string.

	 *          It must be a non-negative number smaller than the length

	 *          of the <i>lean</i> text.

	 *

	 *  @return the index of the corresponding character in the

	 *          <i>full</i> string.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns <code>position</code>.

	 */

	public int leanToFullPos(int position) {

		if (impl == null)

			return position;

		return impl.leanToFullPos(position);

	}

	/**

	 *  After transforming a <i>lean</i> string into a <i>full</i> string

	 *  using {@link #leanToFullText leanToFullText}, compute the index in the

	 *  <i>lean</i> string of the character corresponding to the

	 *  character with the specified position in the <i>full</i> string.

	 *

	 *  @param position is the index of a character in the <i>full</i> string.

	 *          It must be a non-negative number smaller than the length

	 *          of the <i>full</i> text.

	 *

	 *  @return the index of the corresponding character in the

	 *          <i>lean</i> string. If there is no corresponding

	 *          character in the <i>lean</i> string (because the

	 *          specified character is a directional formatting character

	 *          added when invoking {@link #leanToFullText leanToFullText}),

	 *          the value returned will be that corresponding to the

	 *          next character which is not a directional formatting

	 *          character.<br>

	 *          If <code>position</code> corresponds to a directional formatting

	 *          character beyond all characters of the original

	 *          <i>lean</i> text, the value returned is the length of the

	 *          <i>lean</i> text.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns <code>position</code>.

	 */

	public int fullToLeanPos(int position) {

		if (impl == null)

			return position;

		return impl.fullToLeanPos(position);

	}

	/**

	 *  Get the base direction of the complex expression last

	 *  submitted to {@link #leanToFullText leanToFullText}.

	 *  This base direction may depend on

	 *  whether the expression contains Arabic or Hebrew words

	 *  (if it contains both, the first Arabic or Hebrew letter in the

	 *  expression determines which is the governing script) and on

	 *  whether the GUI is {@link BidiComplexEnvironment#mirrored mirrored}.

	 *

	 *  @return the base direction of the last submitted complex

	 *          expression. It must be one of the values

	 *          {@link BidiComplexFeatures#DIR_LTR} or {@link BidiComplexFeatures#DIR_RTL}.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns <code>DIR_LTR</code>.

	 */

	public int getCurDirection() {

		if (impl == null)

			return BidiComplexFeatures.DIR_LTR;

		return impl.getCurDirection();

	}

	/**

	 *  Get the current environment under which the <code>BidiComplexHelper</code>

	 *  operates.

	 *  This environment may have been specified in the constructor or

	 *  specified later using {@link #setEnvironment setEnvironment}.<br>

	 *

	 *  @return the current environment.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns a {@link BidiComplexEnvironment#DEFAULT DEFAULT}

	 *          environment.

	 *

	 *  @see #setEnvironment setEnvironment

	 */

	public BidiComplexEnvironment getEnvironment() {

		if (impl == null)

			return BidiComplexEnvironment.DEFAULT;

		return impl.getEnvironment();

	}

	/**

	 *  Specify the environment under which the <code>BidiComplexHelper</code>

	 *  must operate.

	 *  <p>

	 *  <b>Note</b> that calling this method causes the processor

	 *  associated with this instance of <code>BidiComplexHelper</code>

	 *  to re-initialize its features. The effect of a previous call

	 *  to {@link #setFeatures(BidiComplexFeatures) setFeatures} is lost.<br>

	 *  The {@link #BidiComplexHelper() no-op helper} does nothing.

	 *

	 *  @see #getEnvironment getEnvironment

	 *  @see IBidiComplexProcessor#updateEnvironment IBidiComplexProcessor.updateEnvironment

	 */

	public void setEnvironment(BidiComplexEnvironment environment) {

		if (impl != null)

			impl.setEnvironment(environment);

	}

	/**

	 *  Get the current features of the processor associated with this

	 *  <code>BidiComplexHelper</code> instance.

	 *

	 *  @return the current features.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns {@link BidiComplexFeatures#DEFAULT DEFAULT}

	 *          features.

	 *

	 *  @see #setFeatures setFeatures

	 */

	public BidiComplexFeatures getFeatures() {

		if (impl == null)

			return BidiComplexFeatures.DEFAULT;

		return impl.getFeatures();

	}

	/**

	 *  Specify the features to be applied to the processor associated with this

	 *  <code>BidiComplexHelper</code> instance.

	 *  Note that the value of {@link BidiComplexFeatures#specialsCount specialsCount}

	 *  cannot be changed (the new value will be ignored).<br>

	 *  The {@link #BidiComplexHelper() no-op helper} does nothing.

	 *

	 *  @see #getFeatures getFeatures

	 */

	public void setFeatures(BidiComplexFeatures features) {

		if (impl != null)

			impl.setFeatures(features);

	}

	/**

	 *  This method can be called from within

	 *  {@link IBidiComplexProcessor#indexOfSpecial indexOfSpecial} or

	 *  {@link IBidiComplexProcessor#processSpecial processSpecial} in implementations

	 *  of {@link IBidiComplexProcessor} to retrieve the bidirectional class of

	 *  characters in the <i>lean</i> text.

	 *

	 *  @param index position of the character in the <i>lean</i> text.

	 *          It must be a non-negative number smaller than the length

	 *          of the <i>lean</i> text.

	 *

	 *  @return the bidirectional class of the character. It is one of the

	 *          values which can be returned by

	 *          <code>java.lang.Character#getDirectionality</code>.

	 *          However, it is recommended to use <code>getDirProp</code>

	 *          rather than <code>java.lang.Character.getDirectionality</code>

	 *          since <code>getDirProp</code> manages a cache of character

	 *          properties and so can be more efficient than calling the

	 *          java.lang.Character method.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} returns

	 *          <code>Character.DIRECTIONALITY_UNDEFINED</code>.

	 */

	public byte getDirProp(int index) {

		if (impl == null)

			return Character.DIRECTIONALITY_UNDEFINED;

		return impl.getDirProp(index);

	}

	/**

	 *  This method can be called from within

	 *  {@link IBidiComplexProcessor#indexOfSpecial indexOfSpecial} or

	 *  {@link IBidiComplexProcessor#processSpecial processSpecial} in implementations

	 *  of {@link IBidiComplexProcessor} to set or override the bidirectional

	 *  class of characters in the <i>lean</i> text.

	 *

	 *  @param index position of the character in the <i>lean</i> text.

	 *          It must be a non-negative number smaller than the length

	 *          of the <i>lean</i> text.

	 *

	 *  @param  dirProp bidirectional class of the character. It is one of the

	 *          values which can be returned by

	 *          <code>java.lang.Character.getDirectionality</code>.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} does nothing.

	 */

	public void setDirProp(int index, byte dirProp) {

		if (impl != null)

			impl.getDirProp(index);

	}

	/**

	 *  This method can be called from within

	 *  {@link IBidiComplexProcessor#indexOfSpecial indexOfSpecial} or

	 *  {@link IBidiComplexProcessor#processSpecial processSpecial} in implementations

	 *  of {@link IBidiComplexProcessor}

	 *  to specify that a mark character must be added before the character

	 *  at the specified position of the <i>lean</i> text when generating the

	 *  <i>full</i> text. The mark character will be LRM for complex expressions

	 *  with a LTR base direction, and RLM for complex expressions with RTL

	 *  base direction. The mark character is not added physically by this

	 *  method, but its position is noted and will be used when generating

	 *  the <i>full</i> text.

	 *

	 *  @param  offset position of the character in the <i>lean</i> text.

	 *          It must be a non-negative number smaller than the length

	 *          of the <i>lean</i> text.

	 *          For the benefit of efficiency, it is better to insert

	 *          multiple marks in ascending order of the offsets.<br>

	 *          The {@link #BidiComplexHelper() no-op helper} does nothing.

	 */

	public void insertMark(int offset) {

		if (impl != null)

			impl.insertMark(offset);

	}

	/**

	 *  This method can be called from within

	 *  {@link IBidiComplexProcessor#indexOfSpecial indexOfSpecial} or

	 *  {@link IBidiComplexProcessor#processSpecial processSpecial} in

	 *  implementations of {@link IBidiComplexProcessor} to add a

	 *  directional mark before an

	 *  operator if needed for correct display, depending on the

	 *  base direction of the expression and on the class of the

	 *  characters in the <i>lean</i> text preceding and following

	 *  the operator itself.<br>

	 *  The {@link #BidiComplexHelper() no-op helper} does nothing.

	 *

	 *  @param  operLocation offset of the operator in the <i>lean</i> text.

	 *          It must be a non-negative number smaller than the length

	 *          of the <i>lean</i> text.

	 */

	public void processOperator(int operLocation) {

		if (impl != null)

			impl.processOperator(operLocation);

	}

	/**

	 *  This method can be called from within

	 *  {@link IBidiComplexProcessor#indexOfSpecial indexOfSpecial} or

	 *  {@link IBidiComplexProcessor#processSpecial processSpecial} in

	 *  implementations of {@link IBidiComplexProcessor} to

	 *  set the final state which should be used for the next call to

	 *  {@link #leanToFullText(java.lang.String, int)}.<br>

	 *  The {@link #BidiComplexHelper() no-op helper} does nothing.

	 */

	public void setFinalState(int newState) {

		if (impl != null)

			impl.setFinalState(newState);

	}

}

/*******************************************************************************

 * Copyright (c) 2010, 2011 IBM Corporation and others.

 * All rights reserved. This program and the accompanying materials

 * are made available under the terms of the Eclipse Public License v1.0

 * which accompanies this distribution, and is available at

 * http://www.eclipse.org/legal/epl-v10.html

 *

 * Contributors:

 *     IBM Corporation - initial API and implementation

 ******************************************************************************/

package org.eclipse.equinox.bidi;

import java.lang.ref.SoftReference;

import org.eclipse.equinox.bidi.custom.BidiComplexStringProcessor;

/**

 * This class records strings which are complex expressions. Several static

 * methods in this class allow to record such strings in a pool, and to find if

 * a given string is member of the pool.

 * <p>

 * Instances of this class are the records which are members of the pool.

 * <p>

 * The pool is managed as a cyclic list, each new element overrides the oldest

 * element in the list.

 */

public class BidiComplexStringRecord {

	/**

	 * Number of entries in the pool of recorded strings

	 */

	public static final int POOLSIZE = 100;

	// maximum index allowed

	private static final int MAXINDEX = POOLSIZE - 1;

	// index of the last entered record

	private static int last = MAXINDEX;

	// the pool

	private static BidiComplexStringRecord[] records = new BidiComplexStringRecord[POOLSIZE];

	// complex expression types

	private static final String[] types = BidiComplexStringProcessor.getKnownTypes();

	// maximum type index allowed

	private static int MAXTYPE = types.length - 1;

	// reference to the recorded string

	private SoftReference strRef;

	// hash code of the recorded string

	private int hash;

	// reference to the triplets of the recorded string

	private SoftReference triRef;

	/**

	 * Constructor.

	 * 

	 * @param string

	 *            the string to record

	 * 

	 * @param triplets

	 *            array of short integers, the number of elements in the array

	 *            must be a multiple of 3, so that the array is made of one or

	 *            more triplets of short integers.

	 *            <p>

	 *            The first element in each triplet is the beginning index of a

	 *            susbstring of <code>string</code> which is a complex

	 *            expression.

	 *            <p>

	 *            The second element in each triplet is the ending index of a

	 *            susbstring of <code>string</code> which is a complex

	 *            expression. This index points to one position beyond the last

	 *            character of the substring.

	 *            <p>

	 *            The third element in each triplet is the numeric type of the

	 *            complex expression.<br>

	 *            The type of a complex expression must be one of the string

	 *            values listed in {@link IBidiComplexExpressionTypes}.<br>

	 *            The corresponding numeric type must be obtained using the

	 *            method {@link #typeStringToShort typeStringToShort}.

	 */

	public BidiComplexStringRecord(String string, short[] triplets) {

		if (string == null || triplets == null || (triplets.length % 3) != 0)

			throw new IllegalArgumentException();

		for (int i = 2; i < triplets.length; i += 3)

			if (triplets[i] < 0 || triplets[i] > MAXTYPE)

				throw new IllegalArgumentException();

		strRef = new SoftReference(string);

		triRef = new SoftReference(triplets);

		hash = string.hashCode();

	}

	/**

	 * Get the numeric type of a complex expression given its string type.

	 * 

	 * @param type

	 *            type of complex expression as string. It must be one of the

	 *            strings listed in {@link IBidiComplexExpressionTypes}.

	 * 

	 * @return a value which is the corresponding numeric type. If

	 *         <code>type</code> is invalid, the method returns <code>-1</code>.

	 */

	public static short typeStringToShort(String type) {

		for (int i = 0; i < types.length; i++)

			if (types[i].equals(type))

				return (short) i;

		return -1;

	}

	/**

	 * Get the string type of a complex expression given its numeric type.

	 * 

	 * @param shType

	 *            the numeric type of a complex expression. It should be a value

	 *            obtained using {@link #typeStringToShort typeStringToShort}.

	 * 

	 * @return the corresponding string type. If <code>shType</code> is invalid,

	 *         the method returns <code>null</code>.

	 */

	public static String typeShortToString(short shType) {

		if (shType < 0 || shType > MAXTYPE)

			return null;

		return types[shType];

	}

	/**

	 * /** Add a record to the pool.

	 * 

	 * @param record

	 *            a BidiComplexStringRecord instance

	 */

	public static synchronized void add(BidiComplexStringRecord record) {

		if (last < MAXINDEX)

			last++;

		else

			last = 0;

		records[last] = record;

	}

	/**

	 * Check if a string is recorded and retrieve its triplets.

	 * 

	 * @param string

	 *            the string to check

	 * 

	 * @return <code>null</code> if the string is not recorded in the pool;

	 *         otherwise, return the triplets associated with this string.

	 */

	public static short[] getTriplets(String string) {

		if (records[0] == null) // no records at all

			return null;

		if (string == null || string.length() < 1)

			return null;

		BidiComplexStringRecord rec;

		String str;

		short[] tri;

		int myLast = last;

		int hash = string.hashCode();

		for (int i = myLast; i >= 0; i--) {

			rec = records[i];

			if (hash == rec.hash && (tri = (short[]) rec.triRef.get()) != null && (str = (String) rec.strRef.get()) != null && string.equals(str)) {

				return tri;

			}

		}

		if (records[MAXINDEX] == null) // never recorded past myLast

			return null;

		for (int i = MAXINDEX; i > myLast; i--) {

			rec = records[i];

			if (hash == rec.hash && (tri = (short[]) rec.triRef.get()) != null && (str = (String) rec.strRef.get()) != null && string.equals(str)) {

				return tri;

			}

		}

		return null;

	}

	/**

	 * Clear the pool. All elements of the pool are erased and any associated

	 * memory is freed.

	 * 

	 */

	public static synchronized void clear() {

		for (int i = 0; i <= MAXINDEX; i++) {

			BidiComplexStringRecord sr = records[i];

			if (sr == null)

				break;

			sr.hash = 0;

			sr.strRef.clear();

			sr.triRef.clear();

			records[i] = null;

		}

		last = MAXINDEX;

	}

}

/*******************************************************************************

 * Copyright (c) 2010, 2011 IBM Corporation and others.

 * All rights reserved. This program and the accompanying materials

 * are made available under the terms of the Eclipse Public License v1.0

 * which accompanies this distribution, and is available at

 * http://www.eclipse.org/legal/epl-v10.html

 *

 * Contributors:

 *     IBM Corporation - initial API and implementation

 ******************************************************************************/

package org.eclipse.equinox.bidi;

import org.eclipse.equinox.bidi.custom.BidiComplexProcessor;

/**

 *  This class provides a number of convenience functions facilitating the

 *  processing of complex expressions.

 *

 *  @noextend This class is not intended to be subclassed by clients.

 *  @noinstantiate This class is not intended to be instantiated by clients.

 *

 *  @author Matitiahu Allouche

 */

final public class BidiComplexUtil {

	/**

	 *  prevent instantiation

	 */

	private BidiComplexUtil() {

		// empty

	}

	/** This is a convenience method which can add directional marks in a given

	 *  text before the characters specified in the given array of offsets,

	 *  and can add a prefix and/or a suffix of directional formatting characters.

	 *  This can be used for instance after obtaining offsets by calling

	 *  {@link BidiComplexHelper#leanBidiCharOffsets() leanBidiCharOffsets} in order to

	 *  produce a <i>full</i> text corresponding to the source text.

	 *  The directional formatting characters that will be added at the given

	 *  offsets will be LRMs for expressions with LTR base direction and

	 *  RLMs for expressions with RTL base direction. Leading and

	 *  trailing LRE, RLE and PDF which might be needed as prefix or suffix

	 *  depending on the orientation of the GUI component used for display

	 *  may be added depending on argument <code>affix</code>.

	 *

	 *  @param  text is the text of the complex expression.

	 *

	 *  @param  offsets is an array of offsets to characters in <code>text</code>

	 *          before which an LRM or RLM will be inserted.

	 *          Members of the array must be non-negative numbers smaller

	 *          than the length of <code>text</code>.

	 *          The array must be sorted in ascending order without duplicates.

	 *          This argument may be null if there are no marks to add.

	 *

	 *  @param  direction specifies the base direction of the complex expression.

	 *          It must be one of the values {@link BidiComplexFeatures#DIR_LTR} or

	 *          {@link BidiComplexFeatures#DIR_RTL}.

	 *

	 *  @param  affix specifies if a prefix and a suffix should be added to

	 *          the result to make sure that the <code>direction</code>

	 *          specified as third argument is honored even if the expression

	 *          is displayed in a GUI component with a different orientation.

	 *

	 *  @return a string corresponding to the source <code>text</code> with

	 *          directional marks (LRMs or RLMs) added at the specified offsets,

	 *          and directional formatting characters (LRE, RLE, PDF) added

	 *          as prefix and suffix if so required.

	 */

	public static String insertMarks(String text, int[] offsets, int direction, boolean affix) {

		int textLen = text.length();

		if (textLen == 0)

			return ""; //$NON-NLS-1$

		String curPrefix, curSuffix, full;

		char curMark, c;

		char[] fullChars;

		if (direction == BidiComplexFeatures.DIR_LTR) {

			curMark = LRM;

			curPrefix = "\u202a\u200e"; /* LRE+LRM *///$NON-NLS-1$

			curSuffix = "\u200e\u202c"; /* LRM+PDF *///$NON-NLS-1$

		} else {

			curMark = RLM;

			curPrefix = "\u202b\u200f"; /* RLE+RLM *///$NON-NLS-1$

			curSuffix = "\u200f\u202c"; /* RLM+PDF *///$NON-NLS-1$

		}

		// add marks at offsets

		if ((offsets != null) && (offsets.length > 0)) {

			int offLen = offsets.length;

			fullChars = new char[textLen + offLen];

			int added = 0;

			for (int i = 0, j = 0; i < textLen; i++) {

				c = text.charAt(i);

				if ((j < offLen) && (i == offsets[j])) {

					fullChars[i + added] = curMark;

					added++;

					j++;

				}

				fullChars[i + added] = c;

			}

			full = new String(fullChars);

		} else {

			full = text;

		}

		if (affix)

			return curPrefix + full + curSuffix;

		return full;

	}

	/*************************************************************************/

	/*                                                                       */

	/*  The following code is provided for compatibility with TextProcessor  */

	/*                                                                       */

	/*************************************************************************/

	//  The default set of delimiters to use to segment a string.

	private static final String defaultDelimiters = ".:/\\"; //$NON-NLS-1$

	// left to right mark

	private static final char LRM = '\u200e';

	// left to right mark

	private static final char RLM = '\u200f';

	// left to right embedding

	private static final char LRE = '\u202a';

	// right to left embedding

	private static final char RLE = '\u202b';

	// pop directional format

	private static final char PDF = '\u202c';

	static boolean isProcessingNeeded() {

		if (!BidiComplexEnvironment.isSupportedOS())

			return false;

		return BidiComplexEnvironment.DEFAULT.isBidi();

	}

	/**

	 *  Process the given text and return a string with appropriate

	 *  directional formatting characters if the locale is a bidi locale.

	 *  This is equivalent to calling

	 *  {@link #process(String str, String delimiters)} with the default

	 *  set of delimiters (dot, colon, slash, backslash).

	 *

	 *  @param  str the text to be processed.

	 *

	 *  @return the processed string.

	 */

	public static String process(String str) {

		return process(str, defaultDelimiters);

	}

	/**

	 *  Process a string that has a particular semantic meaning to render

	 *  it correctly on bidi locales. This is done by adding directional

	 *  formatting characters so that presentation using the Unicode

	 *  Bidirectional Algorithm will provide the expected result.

	 *  The text is segmented according to the provided delimiters.

	 *  Each segment has the Unicode Bidi Algorithm applied to it,

	 *  but as a whole, the string is oriented left to right.

	 *  <p>

	 *  For example, a file path such as <tt>d:\myfolder\FOLDER\MYFILE.java</tt>

	 *  (where capital letters indicate RTL text) should render as

	 *  <tt>d:\myfolder\REDLOF\ELIFYM.java</tt>.</p>

	 *  <p>

	 *  NOTE: this method inserts directional formatting characters into the

	 *  text. Methods like <code>String.equals(String)</code> and

	 *  <code>String.length()</code> called on the resulting string will not

	 *  return the same values as would be returned for the original string.</p>

	 *

	 *  @param  str the text to process.

	 *

	 *  @param  delimiters delimiters by which the string will be segmented.

	 *          If <code>null</code>, the default delimiters are used

	 *          (dot, colon, slash, backslash).

	 *

	 *  @return the processed string.

	 *          If <code>str</code> is <code>null</code>,

	 *          or of length 0, or if the current locale is not a bidi one,

	 *          return the original string.

	 */

	public static String process(String str, String delimiters) {

		if ((str == null) || (str.length() <= 1) || !isProcessingNeeded())

			return str;

		// do not process a string that has already been processed.

		if (str.charAt(0) == LRE && str.charAt(str.length() - 1) == PDF)

			return str;

		// do not process a string if all the following conditions are true:

		//  a) it has no RTL characters

		//  b) it starts with a LTR character

		//  c) it ends with a LTR character or a digit

		boolean isStringBidi = false;

		int strLength = str.length();

		char c;

		for (int i = 0; i < strLength; i++) {

			c = str.charAt(i);

			if (((c >= 0x05d0) && (c <= 0x07b1)) || ((c >= 0xfb1d) && (c <= 0xfefc))) {

				isStringBidi = true;

				break;

			}

		}

		while (!isStringBidi) {

			if (!Character.isLetter(str.charAt(0)))

				break;

			c = str.charAt(strLength - 1);

			if (!Character.isDigit(c) && !Character.isLetter(c))

				break;

			return str;

		}

		if (delimiters == null)

			delimiters = defaultDelimiters;

		// make sure that LRE/PDF are added around the string

		BidiComplexEnvironment env = new BidiComplexEnvironment(null, false, BidiComplexEnvironment.ORIENT_UNKNOWN);

		BidiComplexHelper helper = new BidiComplexHelper(new BidiComplexProcessor(), env);

		helper.setFeatures(new BidiComplexFeatures(delimiters, 0, -1, -1, false, false));

		return helper.leanToFullText(str);

	}

	/**

	 *  Process a string that has a particular semantic meaning to render

	 *  it correctly on bidi locales. This is done by adding directional

	 *  formatting characters so that presentation using the Unicode

	 *  Bidirectional Algorithm will provide the expected result..

	 *  The text is segmented according to the syntax specified in the

	 *  <code>type</code> argument.

	 *  Each segment has the Unicode Bidi Algorithm applied to it, but the

	 *  order of the segments is governed by the type of the complex expression.

	 *  <p>

	 *  For example, a file path such as <tt>d:\myfolder\FOLDER\MYFILE.java</tt>

	 *  (where capital letters indicate RTL text) should render as

	 *  <tt>d:\myfolder\REDLOF\ELIFYM.java</tt>.</p>

	 *  <p>

	 *  NOTE: this method inserts directional formatting characters into the

	 *  text. Methods like <code>String.equals(String)</code> and

	 *  <code>String.length()</code> called on the resulting string will not

	 *  return the same values as would be returned for the original string.</p>

	 *

	 *  @param  str the text to process.

	 *

	 *  @param  type specifies the type of the complex expression. It must

	 *          be one of the values in {@link IBidiComplexExpressionTypes} or a value.

	 *          added by a plug-in extension.

	 *

	 *  @return the processed string.

	 *          If <code>str</code> is <code>null</code>,

	 *          or of length 0, or if the current locale is not a bidi one,

	 *          return the original string.

	 */

	public static String processTyped(String str, String type) {

		if ((str == null) || (str.length() <= 1) || !isProcessingNeeded())

			return str;

		// do not process a string that has already been processed.

		char c = str.charAt(0);

		if (((c == LRE) || (c == RLE)) && str.charAt(str.length() - 1) == PDF)

			return str;

		// make sure that LRE/PDF are added around the string

		BidiComplexEnvironment env = new BidiComplexEnvironment(null, false, BidiComplexEnvironment.ORIENT_UNKNOWN);

		BidiComplexHelper helper = new BidiComplexHelper(type, env);

		return helper.leanToFullText(str);

	}

	/**

	 *  Remove directional formatting characters in the given string that

	 *  were inserted by one of the {@link #process process} methods.

	 *

	 *  @param  str string with directional characters to remove.

	 *

	 *  @return string with no directional formatting characters.

	 */

	public static String deprocess(String str) {

		if ((str == null) || (str.length() <= 1) || !isProcessingNeeded())

			return str;

		StringBuffer buf = new StringBuffer();

		int strLen = str.length();

		for (int i = 0; i < strLen; i++) {

			char c = str.charAt(i);

			switch (c) {

				case LRM :

					continue;

				case LRE :

					continue;

				case PDF :

					continue;

				default :

					buf.append(c);

			}

		}

		return buf.toString();

	}

	/**

	 *  Remove directional formatting characters in the given string that

	 *  were inserted by the {@link #processTyped processTyped} method.

	 *

	 *  @param  str string with directional characters to remove.

	 *

	 *  @param  type type of the complex expression as specified when

	 *          calling {@link #processTyped processTyped}.

	 *

	 *  @return string with no directional formatting characters.

	 */

	public static String deprocess(String str, String type) {

		if ((str == null) || (str.length() <= 1) || !isProcessingNeeded())

			return str;

		// make sure that LRE/PDF are added around the string

		BidiComplexEnvironment env = new BidiComplexEnvironment(null, false, BidiComplexEnvironment.ORIENT_UNKNOWN);

		BidiComplexHelper helper = new BidiComplexHelper(type, env);

		return helper.fullToLeanText(str);

	}

}

/*******************************************************************************

 * Copyright (c) 2010, 2011 IBM Corporation and others.

 * All rights reserved. This program and the accompanying materials

 * are made available under the terms of the Eclipse Public License v1.0

 * which accompanies this distribution, and is available at

 * http://www.eclipse.org/legal/epl-v10.html

 *

 * Contributors:

 *     IBM Corporation - initial API and implementation

 ******************************************************************************/

package org.eclipse.equinox.bidi;

/**

 * Bidirectional processors supplied in this bundle.

 *

 * @noextend This interface is not intended to be extended by clients.

 */

public interface IBidiComplexExpressionTypes {

	/**

	 * Constant indicating a type of complex expression processor adapted

	 * to processing property file statements. It expects the following

	 * string format:

	 * <pre>

	 *  name=value

	 * </pre>

	 */

	public String PROPERTY = "property"; //$NON-NLS-1$

	/**

	 * Constant indicating a type of complex expression processor adapted

	 * to processing compound names.

	 * This type covers names made of one or more parts separated by underscores:

	 * <pre>

	 *  part1_part2_part3

	 * </pre>

	 */

	public String UNDERSCORE = "underscore"; //$NON-NLS-1$

	/**

	 * Constant indicating a type of complex expression processor adapted

	 * to processing comma-delimited lists, such as:

	 * <pre>

	 *  part1,part2,part3

	 * </pre>

	 */

	public String COMMA_DELIMITED = "comma"; //$NON-NLS-1$

	/**

	 * Constant indicating a type of complex expression processor adapted

	 * to processing expressions with the following string format:

	 * <pre>

	 *  system(user)

	 * </pre>

	 */

	public String SYSTEM_USER = "system"; //$NON-NLS-1$

	/**

	 * Constant indicating a type of complex expression processor adapted

	 * to processing directory and file paths.

	 */

	public String FILE = "file"; //$NON-NLS-1$

	/**

	 *  Constant indicating a type of complex expression processor adapted

	 *  to processing e-mail addresses.

	 */

	public String EMAIL = "email"; //$NON-NLS-1$

	/**

	 *  Constant indicating a type of complex expression processor adapted

	 *  to processing URLs.

	 */

	public String URL = "url"; //$NON-NLS-1$

	/**

	 *  Constant indicating a type of complex expression processor adapted

	 *  to processing regular expressions, possibly spanning more than one

	 *  line.

	 */

	public String REGEXP = "regex"; //$NON-NLS-1$

	/**

	 *  Constant indicating a type of complex expression processor adapted

	 *  to processing XPath expressions.

	 */

	public String XPATH = "xpath"; //$NON-NLS-1$

	/**

	 *  Constant indicating a type of complex expression processor adapted

	 *  to processing Java code, possibly spanning more than one line.

	 */

	public String JAVA = "java"; //$NON-NLS-1$

	/**

	 *  Constant indicating a type of complex expression processor adapted

	 *  to processing SQL statements, possibly spanning more than one line.

	 */

	public String SQL = "sql"; //$NON-NLS-1$

	/**

	 *  Constant indicating a type of complex expression processor adapted

	 *  to processing arithmetic expressions with a RTL base direction.

	 */

	public String RTL_ARITHMETIC = "math"; //$NON-NLS-1$

}