/*******************************************************************************
 * 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();
}
