bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/IStructuredTextExpert.java

/*******************************************************************************
 * Copyright (c) 2010, 2011 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 ******************************************************************************/
package org.eclipse.equinox.bidi.advanced;

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

/**
 * Provides advanced methods for processing bidirectional text with 
 * a specific structure to ensure proper presentation.
 * For a general introduction to structured text, see the 
 * {@link org.eclipse.equinox.bidi
 * package documentation}.
 * For details about when the advanced methods are needed, see
 * {@link org.eclipse.equinox.bidi.advanced this
 * package documentation}.
 * <p>
 * Identifiers for several common handlers are included in 
 * {@link org.eclipse.equinox.bidi.StructuredTextTypeHandlerFactory}. For handlers 
 * supplied by other packages, a handler instance can be obtained using the
 * {@link org.eclipse.equinox.bidi.StructuredTextTypeHandlerFactory#getHandler}
 * method for the registered handlers, or by instantiating a private handler.
 * </p><p>
 * Most of the methods in this interface have a <code>text</code>
 * argument which may be just a part of a larger body of text.
 * When it is the case that the text is submitted in parts with
 * repeated calls, there may be a need to pass information from
 * one invocation to the next one. For instance, one invocation
 * may detect that a comment or a literal has been started but
 * has not been completed. In such cases, the state must be managed
 * by a {@link IStructuredTextExpert} instance obtained with the 
 * {@link StructuredTextExpertFactory#getStatefulExpert} method.
 * </p><p>
 * The <code>state</code> returned after processing a string
 * can be retrieved, set and reset using the {@link #getState()},
 * {@link #setState(Object)} and {@link #clearState()} methods.
 * </p><p>
 * When submitting the initial part of a text, the state should be
 * reset if it is not the first processing call for this 
 * {@link IStructuredTextExpert} instance.
 * </p><p>
 * Values returned by {@link #getState()} are opaque objects whose meaning
 * is internal to the relevant structured type handler. These values can only
 * be used in {@link #setState(Object)} calls to restore a state
 * previously obtained after processing a given part of a text before 
 * processing the next part of the text.
 * </p><p>
 * Note that if the user does not modify the state, the state returned by
 * a given processing call is automatically passed as initial state to the
 * next processing call, provided that the expert is a stateful one.
 * </p><p>
 * <b>Code Samples</b>
 * </p><p>
 * The following code shows how to transform a certain type of structured text
 * (directory and file paths) in order to obtain the <i>full</i>
 * text corresponding to the given <i>lean</i> text.</p>
 * <pre>
 *   IStructuredTextExpert expert = StructuredTextExpertFactory.getExpert(StructuredTextTypeHandlerFactory.FILE);
 *   String leanText = "D:\\\u05d0\u05d1\\\u05d2\\\u05d3.ext";
 *   String fullText = expert.leanToFullText(leanText);
 *   System.out.println("full text = " + fullText);
 * </pre>
 * <p>
 * The following code shows how to transform successive lines of Java
 * code in order to obtain the <i>full</i>
 * text corresponding to the <i>lean</i> text of each line.</p>
 * <pre>
 *   IStructuredTextExpert expert = StructuredTextExpertFactory.getStatefulExpert(StructuredTextTypeHandlerFactory.JAVA);
 *   String leanText = "int i = 3; // first Java statement";
 *   String fullText = expert.leanToFullText(leanText);
 *   System.out.println("full text = " + fullText);
 *   leanText = "i += 4; // next Java statement";
 *   fullText = expert.leanToFullText(leanText,);
 *   System.out.println("full text = " + fullText);
 * </pre>
 * 
 */
public interface IStructuredTextExpert {

	/**
	 *  Constant specifying that the base direction of a structured text is LTR.
	 *  The base direction may depend on whether the GUI is
	 *  {@link StructuredTextEnvironment#getMirrored mirrored} and
	 *  may be different for Arabic and for Hebrew.
	 *  This constant can appear as value returned by the
	 *  {@link #getTextDirection} method.
	 */
	public static final int DIR_LTR = 0;

	/**
	 *  Constant specifying that the base direction of a structured text is RTL.
	 *  The base direction may depend on whether the GUI is
	 *  {@link StructuredTextEnvironment#getMirrored mirrored} and may
	 *  may be different for Arabic and for Hebrew.
	 *  This constant can appear as value returned by the
	 *  {@link #getTextDirection} method.
	 */
	public static final int DIR_RTL = 1;

	/**
	 * Obtains the structured type handler associated with this 
	 * <code>IStructuredTextExpert</code> instance.
	 * 
	 * @return the type handler instance.
	 */
	public StructuredTextTypeHandler getTypeHandler();

	/**
	 * Obtains the environment associated with this 
	 * <code>IStructuredTextExpert</code> instance.
	 * @return the environment instance.
	 */
	public StructuredTextEnvironment getEnvironment();

	/** 
	 * Adds directional formatting characters to a structured text
	 * to ensure correct presentation.
	 * 
	 * @param text is the structured text string
	 *
	 * @return the structured text with directional formatting characters added to ensure 
	 * correct presentation.
	 */
	public String leanToFullText(String text);

	/**
	 * Given a <i>lean</i> string, computes the positions of each of its
	 * characters within the corresponding <i>full</i> string.
	 *
	 * @param text is the structured text string.
	 *
	 * @return an array of integers with one element for each of the
	 * characters in the <code>text</code> argument, equal to the offset
	 * of the corresponding character in the <i>full</i> string.
	 */
	public int[] leanToFullMap(String text);

	/**
	 * Given a <i>lean</i> string, computes the offsets of characters
	 * before which directional formatting characters must be added
	 * in order to ensure correct presentation.
	 * <p>
	 * Only LRMs (for a string with LTR base direction) and RLMs (for
	 * a string with RTL base direction) are considered. Leading and
	 * trailing LRE, RLE and PDF which might be prefixed or suffixed
	 * depending on the {@link StructuredTextEnvironment#getOrientation orientation} of the
	 * GUI component used for display are not reflected in this method.
	 * </p>
	 * @param text is the structured text string
	 *
	 * @return an array of offsets to the characters in the <code>text</code> argument 
	 * before which directional marks must be added to ensure correct presentation.
	 * The offsets are sorted in ascending order.
	 */
	public int[] leanBidiCharOffsets(String text);

	/**
	 * Removes directional formatting characters which were added to a
	 * structured text string to ensure correct presentation.
	 *
	 * @param text is the structured text string including directional formatting characters.
	 *
	 * @return the structured text string without directional formatting characters 
	 * which might have been added by processing it with {@link #leanToFullText}.
	 *
	 */
	public String fullToLeanText(String text);

	/**
	 * Given a <i>full</i> string, computes the positions of each of its
	 * characters within the corresponding <i>lean</i> string.
	 *
	 * @param  text is the structured text string including directional formatting characters.
	 *
	 * @return an array of integers with one element for each of the
	 * characters in the <code>text</code> argument, equal to the offset
	 * 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}), 
	 * the value returned for this character is -1.
	 */
	public int[] fullToLeanMap(String text);

	/**
	 * Given a <i>full</i> string, returns the offsets of characters
	 * which are directional formatting characters that have been added
	 * in order to ensure correct presentation.
	 * <p>
	 * LRMs (for a string with LTR base direction), RLMs (for a string 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 StructuredTextEnvironment#getOrientation orientation} 
	 * of the GUI component used for display.
	 * </p>
	 * @param  text is the structured text string including directional formatting characters
	 *
	 * @return an array of offsets to the characters in the <code>text</code> argument which 
	 * are directional formatting characters added to ensure correct presentation. The offsets 
	 * are sorted in ascending order.
	 */
	public int[] fullBidiCharOffsets(String text);

	/** 
	 * Adds directional marks to the given text before the characters 
	 * specified in the given array of offsets. It can be used to add a prefix and/or 
	 * a suffix of directional formatting characters.
	 * <p>
	 * The directional marks will be LRMs for structured text strings with LTR base 
	 * direction and RLMs for strings with RTL base direction.
	 * </p><p> 
	 * If necessary, leading and trailing directional formatting characters
	 * (LRE, RLE and PDF) can be added depending on the value of the 
	 * <code>affix</code> argument.</p>
	 * <ul>
	 *   <li>A value of 1 means that one LRM or RLM must be prefixed, depending  
	 *       on the direction. This is useful when the GUI component presenting
	 *       this text has a contextual orientation.</li>
	 *   <li>A value of 2 means that LRE+LRM or RLE+RLM must be prefixed, 
	 *       depending on the direction, and LRM+PDF or RLM+PDF must be
	 *       suffixed, depending on the direction.
	 *       This is useful if the GUI component presenting this text needs to
	 *       have the text orientation explicitly specified.</li>
	 *   <li>A value of 0 means that no prefix or suffix are needed.</li>
	 * </ul>
	 * @see IStructuredTextExpert#leanBidiCharOffsets(String)
	 * 
	 * @param  text the structured text string
	 * @param  offsets an array of offsets to characters in <code>text</code>
	 *         before which an LRM or RLM will be inserted.
	 *         The array must be sorted in ascending order without duplicates.
	 *         This argument may be <code>null</code> if there are no marks to add.
	 * @param  direction the base direction of the structured text.
	 *         It must be one of the values {@link #DIR_LTR}, or
	 *         {@link #DIR_RTL}.
	 * @param  affixLength specifies the length of prefix and suffix 
	 *         which should be added to the result.<br>
	 *         0 means no prefix or suffix<br>
	 *         1 means one LRM or RLM as prefix and no suffix<br>
	 *         2 means 2 characters in both prefix and suffix.
	 *         
	 * @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 String insertMarks(String text, int[] offsets, int direction, int affixLength);

	/**
	 * Get the base direction of a structured text. This base direction may depend on
	 * whether the text contains Arabic or Hebrew words. If the text contains both, 
	 * the first Arabic or Hebrew letter in the text determines which is the governing script.
	 *
	 * @param  text is the structured text string.
	 *
	 * @return the base direction of the structured text, {@link #DIR_LTR} or {@link #DIR_RTL}
	 */
	public int getTextDirection(String text);

	//////////////////////////////////////////////////////////////////////
	// Expert's state handling - can be used only for non-shared experts
	//////////////////////////////////////////////////////////////////////
	/**
	 * Sets the state for the next text processing call.
	 * This method does nothing if the expert instance is not a stateful one.
	 * 
	 * @param state an object returned by a previous call to {@link #getState}.
	 */
	public void setState(Object state);

	/**
	 * Gets the state established by the last text processing call.
	 * This is <code>null</code> if the expert instance is not a stateful one,
	 * or if the last text processing call had nothing to pass to the next call.
	 * 
	 * @return the last established state.
	 */
	public Object getState();

	/**
	 * Resets the state to initial.
	 * This method does nothing if the expert instance is not a stateful one.
	 */
	public void clearState();
}