diff options
Diffstat (limited to 'bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom')
5 files changed, 323 insertions, 500 deletions
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/ISTextProcessor.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/ISTextProcessor.java deleted file mode 100644 index 8177c2b74..000000000 --- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/ISTextProcessor.java +++ /dev/null @@ -1,170 +0,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.custom; - -import org.eclipse.equinox.bidi.STextEngine; -import org.eclipse.equinox.bidi.STextEnvironment; - -/** - * Interface for all structured text processors. - * For guidelines about implementation, see - * {@link STextProcessor}. - * - * @author Matitiahu Allouche - */ -public interface ISTextProcessor { - - /** - * return the - * {@link STextFeatures} characterizing the processor. - * - * @param env the current environment, which may affect the behavior of - * the processor. This parameter may be specified as - * <code>null</code>, in which case the - * {@link STextEnvironment#DEFAULT DEFAULT} - * environment should be assumed. - * - * @return the features in use for this processor. - */ - public abstract STextFeatures getFeatures(STextEnvironment env); - - /** - * Locate occurrences of special strings within a structured text - * and return their indexes one after the other in successive calls. - * <p> - * This method is called repeatedly from the code implementing - * {@link STextEngine#leanToFullText leanToFullText} if the - * number of special cases appearing in the associated <code>features</code> - * parameter is greater than zero. - * <p> - * The code implementing this method may use the following methods - * in {@link STextProcessor}: - * <ul> - * <li>{@link STextProcessor#getDirProp getDirProp}</li> - * <li>{@link STextProcessor#setDirProp setDirProp}</li> - * <li>{@link STextProcessor#insertMark insertMark}</li> - * <li>{@link STextProcessor#processSeparator processSeparator}</li> - * </ul> - * - * @param features is the {@link STextFeatures} instance - * currently associated with this processor. - * - * @param text is the structured text string before - * addition of any directional formatting characters. - * - * @param dirProps is a parameter received by <code>indexOfSpecial</code> - * uniquely to be used as argument for calls to methods which - * need it. - * - * @param offsets is a parameter received by <code>indexOfSpecial</code> - * uniquely to be used as argument for calls to methods which - * need it. - * - * @param caseNumber number of the special case to locate. - * This number varies from 1 to the number of special cases - * in the features associated with this processor. - * The meaning of this number is internal to the class - * implementing <code>indexOfSpecial</code>. - * - * @param fromIndex the index within <code>text</code> to start - * the search from. - * - * @return the position where the start of the special case was located. - * The method must return the first occurrence of whatever - * identifies the start of the special case starting from - * <code>fromIndex</code>. The method does not have to check if - * this occurrence appears within the scope of another special - * case (e.g. a comment starting delimiter within the scope of - * a literal or vice-versa). - * <br>If no occurrence is found, the method must return -1. - */ - public int indexOfSpecial(STextFeatures features, String text, byte[] dirProps, int[] offsets, int caseNumber, int fromIndex); - - /** - * This method handles special cases specific to this processor. - * It is called by {@link STextEngine#leanToFullText leanToFullText} - * when a special case occurrence is located by - * {@link #indexOfSpecial indexOfSpecial}. - * <p> - * The code implementing this method may use the following methods - * in {@link STextProcessor}: - * <ul> - * <li>{@link STextProcessor#getDirProp getDirProp}</li> - * <li>{@link STextProcessor#setDirProp setDirProp}</li> - * <li>{@link STextProcessor#insertMark insertMark}</li> - * <li>{@link STextProcessor#processSeparator processSeparator}</li> - * </ul> - * <p> - * If a special processing cannot be completed within a current call to - * <code>processSpecial</code> (for instance, a comment has been started - * in the current line but its end appears in a following line), - * <code>processSpecial</code> should specify a final state by - * putting its value in the first element of the <code>state</code> - * parameter. - * The meaning of this state is internal to the processor. - * On a later call to - * {@link STextEngine#leanToFullText leanToFullText} - * specifying that state value, <code>processSpecial</code> will be - * called with that value for parameter <code>caseNumber</code> and - * <code>-1</code> for parameter <code>separLocation</code> and should - * perform whatever initializations are required depending on the state. - * - * @param features is the {@link STextFeatures} instance - * currently associated with this processor. - * - * @param text is the structured text string before - * addition of any directional formatting characters. - * - * @param dirProps is a parameter received by <code>processSpecial</code> - * uniquely to be used as argument for calls to methods which - * need it. - * - * @param offsets is a parameter received by <code>processSpecial</code> - * uniquely to be used as argument for calls to methods which - * need it. - * - * @param state is an integer array with at least one element. - * If the processor needs to signal the occurrence of a - * special case which must be passed to the next call to - * <code>leanToFullText</code> (for instance, a comment or a - * literal started but not closed in the current - * <code>text</code>), it must put a value in the first element - * of the <code>state</code> parameter. - * This value must be a number between 1 and the number of - * special cases appearing in the features associated with - * this processor. This number is passed back to the caller - * and should be specified as <code>state</code> argument - * in the next call to <code>leanToFullText</code> together - * with the continuation text. - * The meaning of this number is internal to the processor. - * - * @param caseNumber number of the special case to handle. - * - * @param separLocation the position returned by - * {@link #indexOfSpecial indexOfSpecial}. In calls to - * {@link STextEngine#leanToFullText leanToFullText} and other - * methods of {@link STextEngine} specifying a non-null - * <code>state</code> parameter, <code>processSpecial</code> is - * called when initializing the processing with the value of - * <code>caseNumber</code> equal to the value returned in the - * first element of <code>state</code> and the value of - * <code>separLocation</code> equal to <code>-1</code>. - * - * @return the position after the scope of the special case ends. - * For instance, the position after the end of a comment, - * the position after the end of a literal. - * <br>A value greater or equal to the length of <code>text</code> - * means that there is no further occurrence of this case in the - * current structured text. - */ - public int processSpecial(STextFeatures features, String text, byte[] dirProps, int[] offsets, int[] state, int caseNumber, int separLocation); - -} diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextFeatures.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextFeatures.java deleted file mode 100644 index 9d7c1a13e..000000000 --- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextFeatures.java +++ /dev/null @@ -1,250 +0,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.custom; - -import org.eclipse.equinox.bidi.STextEnvironment; - -/** - * This class defines features of a structured text processor. - * <p> - * All public fields in this class are <code>final</code>, i.e. cannot be - * changed after creating an instance. - * - * <h2>Code Sample</h2> - * <p>Example 1 (set all features) - * <pre> - * - * STextFeatures f1 = new STextFeatures("+-=", 0, -1, -1, false, false); - * - * </pre> - * <p>Example 2 (change only the separators) - * <pre> - * - * STextFeatures f2 = new STextFeatures("[]|()", f1.getSpecialsCount(), - * f1.getDirArabic(), f1.getDirHebrew(), - * f1.getIgnoreArabic(), f1.getIgnoreHebrew()); - * - * </pre> - * - * @see ISTextProcessor#getFeatures - * - * @author Matitiahu Allouche - */ -public class STextFeatures { - - /** - * Constant specifying that the base direction of a structured text is LTR. - * The base direction may depend on whether the GUI is - * {@link STextEnvironment#getMirrored 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 the - * {@link STextFeatures#STextFeatures STextFeatures constructor} - * and as value returned by {@link #getDirArabic} or {@link #getDirHebrew} - * methods. - */ - 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 STextEnvironment#getMirrored 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 the - * {@link STextFeatures#STextFeatures STextFeatures constructor} - * and as value returned by {@link #getDirArabic} or {@link #getDirHebrew} - * methods. - */ - public static final int DIR_RTL = 1; - - /** - * Pre-defined <code>STextFeatures</code> instance with values for no - * separators, no special processing, all directions LTR - * and support for neither Arabic nor Hebrew.<br> - * Since there are no separators and no special processing, a structured text - * processor with such features would do nothing.<br> - * It is more efficient to do nothing with a <code>null</code> processor. - */ - public static final STextFeatures DEFAULT = new STextFeatures(null, 0, -1, -1, true, true); - - /** - * String grouping one-character separators which - * separate the structured text into tokens. - */ - final String separators; - - /** - * Number of special cases for the associated processor. - * Special cases exist for some types of structured text processors. - * They are implemented by overriding methods - * {@link ISTextProcessor#indexOfSpecial indexOfSpecial} and - * {@link ISTextProcessor#processSpecial processSpecial}. - * Examples of special cases are comments, literals, or anything which - * is not identified by a one-character separator. - */ - final int specialsCount; - - /** - * Base direction of the structured text for Arabic. - * If a structured text contains both Arabic and - * Hebrew words, the first Arabic or Hebrew letter in the - * text 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 - */ - final int dirArabic; - - /** - * Base direction of the structured text for Hebrew. - * If a structured text contains both Arabic and - * Hebrew words, the first Arabic or Hebrew letter in the - * text 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 - */ - final int dirHebrew; - - /** - * Flag indicating that Arabic letters will not be considered for - * processing structured text. If both this flag and - * ignoreHebrew are set to <code>true</code>, the - * processor will do nothing (but some overhead can be expected). - */ - final boolean ignoreArabic; - - /** - * Flag indicating that Hebrew letters will not be considered for - * processing structured text. If both this flag and - * ignoreArabic are set to <code>true</code>, the - * processor will do nothing (but some overhead can be expected). - */ - final boolean ignoreHebrew; - - /** - * Constructor - * - * @param separators is a string where each character is a separator - * which separates the structured text into tokens. - * @see #getSeparators - * - * @param specialsCount specifies the number of special cases handled - * by the processor. This value must be identical to the - * number of special cases handled by the processor with which - * this <code>STextFeatures</code> instance is associated. - * @see #getSpecialsCount - * - * @param dirArabic specifies the base direction of the structured text - * 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 #getDirArabic - * - * @param dirHebrew specifies the base direction of the structured text - * 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 #getDirHebrew - * - * @param ignoreArabic indicates that Arabic letters will not be - * considered for processing structured text. - * If both this flag and <code>ignoreHebrew</code> - * are set to <code>true</code>, the processor will do - * nothing (but some overhead can be expected). - * @see #getIgnoreArabic - * - * @param ignoreHebrew indicates that Hebrew letters will not be - * considered for processing structured text. - * If both this flag and <code>ignoreArabic</code> - * are set to <code>true</code>, the processor will do - * nothing (but some overhead can be expected). - * @see #getIgnoreHebrew - */ - public STextFeatures(String separators, int specialsCount, int dirArabic, int dirHebrew, boolean ignoreArabic, boolean ignoreHebrew) { - - this.separators = separators == null ? "" : separators; //$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; - } - - /** - * @return a string grouping one-character separators which separate - * the structured text into tokens. - */ - public String getSeparators() { - return separators; - } - - /** - * @return the number of special cases for the associated processor. - * Special cases exist for some types of structured text - * processors. They are implemented by overriding methods - * {@link ISTextProcessor#indexOfSpecial indexOfSpecial} and - * {@link ISTextProcessor#processSpecial processSpecial}. - * Examples of special cases are comments, literals, or - * anything which is not identified by a one-character separator. - */ - public int getSpecialsCount() { - return specialsCount; - } - - /** - * @return the base direction of the structured text for Arabic. - * If a structured text contains both Arabic and - * Hebrew words, the first Arabic or Hebrew letter in the - * text determines which is the governing script.<br> - * The value of this field is one of - * {@link #DIR_LTR} or {@link #DIR_RTL}. - * - * @see #getDirHebrew - */ - public int getDirArabic() { - return dirArabic; - } - - /** - * @return the base direction of the structured text for Hebrew. - * If a structured text contains both Arabic and - * Hebrew words, the first Arabic or Hebrew letter in the - * text determines which is the governing script.<br> - * The value of this field is one of - * {@link #DIR_LTR} or {@link #DIR_RTL}. - * - * @see #getDirArabic - */ - public int getDirHebrew() { - return dirHebrew; - } - - /** - * @return a flag indicating that Arabic letters will not be considered - * for processing structured text. - */ - public boolean getIgnoreArabic() { - return ignoreArabic; - } - - /** - * Flag indicating that Hebrew letters will not be considered for - * processing structured text. - */ - public boolean getIgnoreHebrew() { - return ignoreHebrew; - } - -} diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextProcessor.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextProcessor.java index f552dbc22..8401d9c97 100644 --- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextProcessor.java +++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextProcessor.java @@ -15,7 +15,7 @@ import org.eclipse.equinox.bidi.STextEnvironment; import org.eclipse.equinox.bidi.internal.STextImpl; /** - * Generic processor which can be used as superclass (base class) + * Generic processor to be used as superclass (base class) * for specific structured text processors. * <p> * Here are some guidelines about how to write structured text @@ -23,89 +23,220 @@ import org.eclipse.equinox.bidi.internal.STextImpl; * <ul> * <li>Processor instances may be accessed simultaneously by * several threads. They should have no instance variables.</li> - * <li>Each use of a processor is associated with a set of - * {@link STextFeatures features}. - * All processors must have a default set of features which may be - * queried with the {@link #getFeatures getFeatures} method. - * These default features may be overridden by specifying a - * <code>features</code> argument when calling a method. - * See for instance - * {@link STextEngine#leanToFullText leanToFullText}. - * <li>The behavior of a processor is governed by 3 factors, all included - * in associated {@link STextFeatures features} data. + * <li>All the user methods in {@link STextEngine} implement a logic + * common to all processors, located in {@link STextImpl}. + * These methods all have a first argument which is a processor + * instance. + * The common logic uses processor methods to query the + * characteristics of the specific processor: * <ul> - * <li>The separators specified in its - * {@link STextFeatures features} determine how submitted - * structured text is split into tokens.</li> - * <li>The tokens are displayed one after the other according - * to the appropriate direction, which can be different for - * Arabic and for Hebrew.</li> - * <li>The number of special cases which need to be handled by - * code specific to that processor.</li> + * <li>the separators which separate the structured text into + * tokens. See {@link #getSeparators getSeparators}.</li> + * <li>the direction which governs the display of tokens + * one after the other. See {@link #getDirection getDirection}.</li> + * <li>the number of special cases which need to be handled by + * code specific to that processor. + * See {@link #getSpecialsCount getSpecialsCount}.</li> * </ul></li> + * <li>Before starting deeper analysis of the submitted text, the common + * logic gives to the processor a chance to shorten the processus by + * invoking its {@link #skipProcessing skipProcessing} method.</li> + * <li>The common logic then analyzes the text to segment it into tokens + * according to the appearance of separators (as retrieved using + * {@link #getSeparators getSeparators}).</li> + * <li>If the processor indicated a positive number of special cases as + * return value from its {@link #getSpecialsCount getSpecialsCount} + * method, the common logic will repeatedly invoke the processor's + * {@link #indexOfSpecial indexOfSpecial} method to let it signal the + * presence of special strings which may further delimit the source text.</li> + * <li>When such a special case is signalled by the processor, the common + * logic will call the processor's {@link #processSpecial processSpecial} + * method to give it the opportunity to handle it as needed. Typical + * actions that the processor may perform are to add directional marks + * inconditionally (by calling {@link #insertMark insertMark} or + * conditionally (by calling {@link #processSeparator processSeparator}).</li> * </ul> * - * @see STextFeatures#getSeparators - * @see STextFeatures#getDirArabic - * @see STextFeatures#getDirHebrew - * @see STextFeatures#getSpecialsCount - * * @author Matitiahu Allouche */ -public class STextProcessor implements ISTextProcessor { +public abstract class STextProcessor { /** - * In <code>STextProcessor</code> this method returns a - * {@link STextFeatures#DEFAULT DEFAULT} value which - * directs the processor to do nothing. + * Locate occurrences of special strings within a structured text + * and return their indexes one after the other in successive calls. + * <p> + * This method is called repeatedly from the code implementing + * {@link STextEngine#leanToFullText leanToFullText} if the + * number of special cases returned by {@link #getSpecialsCount getSpecialsCount} + * is greater than zero. + * <p> + * The code implementing this method may use the following methods: + * <ul> + * <li>{@link #getDirProp getDirProp}</li> + * <li>{@link #setDirProp setDirProp}</li> + * <li>{@link #insertMark insertMark}</li> + * <li>{@link #processSeparator processSeparator}</li> + * <li>{@link #getDirection getDirection}</li> + * <li>{@link #getSeparators getSeparators}</li> + * <li>{@link #getSpecialsCount getSpecialsCount}</li> + * </ul> * - * <p>A processor which extends this class must override this method - * and return a STextFeatures instance representing its specific - * features. + * @param environment the current environment, which may affect the behavior of + * the processor. This parameter may be specified as + * <code>null</code>, in which case the + * {@link STextEnvironment#DEFAULT DEFAULT} + * environment should be assumed. * - * @see ISTextProcessor#getFeatures the corresponding interface method - */ - public STextFeatures getFeatures(STextEnvironment environment) { - throw new IllegalStateException("A processor must have a getFeatures() method."); //$NON-NLS-1$ - } - - /** - * In <code>STextProcessor</code> this method throws an + * @param text is the structured text string before + * addition of any directional formatting characters. + * + * @param dirProps is a parameter received by <code>indexOfSpecial</code> + * uniquely to be used as argument for calls to methods which + * need it. + * + * @param offsets is a parameter received by <code>indexOfSpecial</code> + * uniquely to be used as argument for calls to methods which + * need it. + * + * @param caseNumber number of the special case to locate. + * This number varies from 1 to the number of special cases + * returned by {@link #getSpecialsCount getSpecialsCount} + * for this processor. + * The meaning of this number is internal to the class + * implementing <code>indexOfSpecial</code>. + * + * @param fromIndex the index within <code>text</code> to start + * the search from. + * + * @return the position where the start of the special case + * corresponding to <code>caseNumber</code> was located. + * The method must return the first occurrence of whatever + * identifies the start of the special case starting from + * <code>fromIndex</code>. The method does not have to check if + * this occurrence appears within the scope of another special + * case (e.g. a comment starting delimiter within the scope of + * a literal or vice-versa). + * <br>If no occurrence is found, the method must return -1. + * + * @throws IllegalStateException + * + * <p>If not overridden, this method throws an * <code>IllegalStateException</code>. This is appropriate behavior * (and does not need to be overridden) for processors whose * number of special cases is zero, which means that * <code>indexOfSpecial</code> should never be called for them. * * <p>A processor handling special cases must override this method. - * - * @see ISTextProcessor#indexOfSpecial the corresponding interface method */ - public int indexOfSpecial(STextFeatures features, String text, byte[] dirProps, int[] offsets, int caseNumber, int fromIndex) { + public int indexOfSpecial(STextEnvironment environment, String text, byte[] dirProps, int[] offsets, int caseNumber, int fromIndex) { // This method must be overridden by all subclasses with special cases. - throw new IllegalStateException("A processor must have an indexOfSpecial() method."); //$NON-NLS-1$ + throw new IllegalStateException("A processor with specialsCount > 0 must have an indexOfSpecial() method."); //$NON-NLS-1$ } /** - * In <code>STextProcessor</code> this method throws an + * This method handles special cases specific to this processor. + * It is called by {@link STextEngine#leanToFullText leanToFullText} + * when a special case occurrence is located by + * {@link #indexOfSpecial indexOfSpecial}. + * <p> + * The code implementing this method may use the following methods: + * <ul> + * <li>{@link #getDirProp getDirProp}</li> + * <li>{@link #setDirProp setDirProp}</li> + * <li>{@link #insertMark insertMark}</li> + * <li>{@link #processSeparator processSeparator}</li> + * <li>{@link #getDirection getDirection}</li> + * <li>{@link #getSeparators getSeparators}</li> + * <li>{@link #getSpecialsCount getSpecialsCount}</li> + * </ul> + * <p> + * If a special processing cannot be completed within a current call to + * <code>processSpecial</code> (for instance, a comment has been started + * in the current line but its end appears in a following line), + * <code>processSpecial</code> should specify a final state by + * putting its value in the first element of the <code>state</code> + * parameter. + * The meaning of this state is internal to the processor. + * On a later call to + * {@link STextEngine#leanToFullText leanToFullText} + * specifying that state value, <code>processSpecial</code> will be + * called with that value for parameter <code>caseNumber</code> and + * <code>-1</code> for parameter <code>separLocation</code> and should + * perform whatever initializations are required depending on the state. + * + * @param environment the current environment, which may affect the behavior of + * the processor. This parameter may be specified as + * <code>null</code>, in which case the + * {@link STextEnvironment#DEFAULT DEFAULT} + * environment should be assumed. + * + * @param text is the structured text string before + * addition of any directional formatting characters. + * + * @param dirProps is a parameter received by <code>processSpecial</code> + * uniquely to be used as argument for calls to methods which + * need it. + * + * @param offsets is a parameter received by <code>processSpecial</code> + * uniquely to be used as argument for calls to methods which + * need it. + * + * @param state is an integer array with at least one element. + * If the processor needs to signal the occurrence of a + * special case which must be passed to the next call to + * <code>leanToFullText</code> (for instance, a comment or a + * literal started but not closed in the current + * <code>text</code>), it must put a value in the first element + * of the <code>state</code> parameter. + * This number must be >= 1 and less or equal to the number of special + * cases returned by {@link #getSpecialsCount getSpecialsCount} + * by this processor. + * This number is passed back to the caller + * and should be specified as <code>state</code> argument + * in the next call to <code>leanToFullText</code> together + * with the continuation text. + * The meaning of this number is internal to the processor. + * + * @param caseNumber number of the special case to handle. + * + * @param separLocation the position returned by + * {@link #indexOfSpecial indexOfSpecial}. In calls to + * {@link STextEngine#leanToFullText leanToFullText} and other + * methods of {@link STextEngine} specifying a non-null + * <code>state</code> parameter, <code>processSpecial</code> is + * called when initializing the processing with the value of + * <code>caseNumber</code> equal to the value returned in the + * first element of <code>state</code> and the value of + * <code>separLocation</code> equal to <code>-1</code>. + * + * @return the position after the scope of the special case ends. + * For instance, the position after the end of a comment, + * the position after the end of a literal. + * <br>A value greater or equal to the length of <code>text</code> + * means that there is no further occurrence of this case in the + * current structured text. + * + * @throws IllegalStateException + * + * <p>If not overridden, this method throws an * <code>IllegalStateException</code>. This is appropriate behavior * (and does not need to be overridden) for processors whose * number of special cases is zero, which means that * <code>processSpecial</code> should never be called for them. * - * <p>A processor handling special cases must override this method. - * - * @see ISTextProcessor#processSpecial the corresponding interface method + * <p>A processor handling special cases (with a number of + * special cases greater than zero) must override this method. */ - public int processSpecial(STextFeatures features, String text, byte[] dirProps, int[] offsets, int[] state, int caseNumber, int separLocation) { + public int processSpecial(STextEnvironment environment, String text, byte[] dirProps, int[] offsets, int[] state, int caseNumber, int separLocation) { // This method must be overridden by all subclasses with any special case. - throw new IllegalStateException("A processor must have a processSpecial() method."); //$NON-NLS-1$ + throw new IllegalStateException("A processor with specialsCount > 0 must have a processSpecial() method."); //$NON-NLS-1$ } /** * This method can be called from within - * {@link ISTextProcessor#indexOfSpecial indexOfSpecial} or - * {@link ISTextProcessor#processSpecial processSpecial} in - * implementations of {@link ISTextProcessor} to retrieve the + * {@link #indexOfSpecial indexOfSpecial} or + * {@link #processSpecial processSpecial} in extensions of + * <code>STextProcessor</code> to retrieve the * bidirectional class of characters in the <i>lean</i> text. * * @param text is the structured text string received as @@ -130,15 +261,15 @@ public class STextProcessor implements ISTextProcessor { * properties and so can be more efficient than calling the * java.lang.Character method. */ - public static byte getDirProp(String text, byte[] dirProps, int index) { + public static final byte getDirProp(String text, byte[] dirProps, int index) { return STextImpl.getDirProp(text, dirProps, index); } /** * This method can be called from within - * {@link ISTextProcessor#indexOfSpecial indexOfSpecial} or - * {@link ISTextProcessor#processSpecial processSpecial} in - * implementations of {@link ISTextProcessor} to set or + * {@link #indexOfSpecial indexOfSpecial} or + * {@link #processSpecial processSpecial} in extensions of + * <code>STextProcessor</code> to set or * override the bidirectional class of characters in the <i>lean</i> text. * * @param dirProps is a parameter received by <code>indexOfSpecial</code> @@ -150,19 +281,19 @@ public class STextProcessor implements ISTextProcessor { * 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 + * @param dirProp bidirectional class of the character. It must be + * one of the values which can be returned by * <code>java.lang.Character.getDirectionality</code>. */ - public static void setDirProp(byte[] dirProps, int index, byte dirProp) { + public static final void setDirProp(byte[] dirProps, int index, byte dirProp) { STextImpl.setDirProp(dirProps, index, dirProp); } /** * This method can be called from within - * {@link ISTextProcessor#indexOfSpecial indexOfSpecial} or - * {@link ISTextProcessor#processSpecial processSpecial} in - * implementations of {@link ISTextProcessor} + * {@link #indexOfSpecial indexOfSpecial} or + * {@link #processSpecial processSpecial} in extensions of + * <code>STextProcessor</code> * 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 structured text @@ -191,24 +322,25 @@ public class STextProcessor implements ISTextProcessor { * For the benefit of efficiency, it is better to insert * multiple marks in ascending order of the offsets. */ - public static void insertMark(String text, byte[] dirProps, int[] offsets, int offset) { + public static final void insertMark(String text, byte[] dirProps, int[] offsets, int offset) { STextImpl.insertMark(text, dirProps, offsets, offset); } /** * This method can be called from within - * {@link ISTextProcessor#indexOfSpecial indexOfSpecial} or - * {@link ISTextProcessor#processSpecial processSpecial} in - * implementations of {@link ISTextProcessor} to add a - * directional mark before a + * {@link #indexOfSpecial indexOfSpecial} or + * {@link #processSpecial processSpecial} in extensions of + * <code>STextProcessor</code> to add a directional mark before a * separator if needed for correct display, depending on the * base direction of the text and on the class of the * characters in the <i>lean</i> text preceding and following * the separator itself. * - * @param features is the {@link STextFeatures} instance - * received as parameter to <code>indexOfSpecial</code> or - * <code>processSpecial</code>. + * <p>The logic implemented in this method considers the text before + * <code>separLocation</code> and the text following it. If, and only if, + * a directional mark is needed to insure that the two parts of text + * will be laid out according to the base direction, a mark will be + * added when generating the <i>full</i> text. * * @param text is the structured text string received as * parameter to <code>indexOfSpecial</code> or @@ -228,8 +360,124 @@ public class STextProcessor implements ISTextProcessor { * It must be a non-negative number smaller than the length * of the <i>lean</i> text. */ - public static void processSeparator(STextFeatures features, String text, byte[] dirProps, int[] offsets, int separLocation) { - STextImpl.processSeparator(features, text, dirProps, offsets, separLocation); + public static final void processSeparator(String text, byte[] dirProps, int[] offsets, int separLocation) { + STextImpl.processSeparator(text, dirProps, offsets, separLocation); + } + + /** + * Indicate the separators to use for the current processor. + * This methode is invoked before starting the processing. + * + * @param environment the current environment, which may affect the behavior of + * the processor. This parameter may be specified as + * <code>null</code>, in which case the + * {@link STextEnvironment#DEFAULT DEFAULT} + * environment should be assumed. + * + * @param text is the structured text string to process. + * + * @param dirProps is a parameter received uniquely to be used as argument + * for calls to <code>getDirProp</code> and other methods used + * by processors. + * + * @return a string grouping one-character separators which separate + * the structured text into tokens. + * + * <p>If not overridden, this method returns an empty string; + */ + public String getSeparators(STextEnvironment environment, String text, byte[] dirProps) { + return ""; //$NON-NLS-1$ + } + + /** + * Indicate the base text direction appropriate for an instance + * of structured text. + * This methode is invoked before starting the processing. + * + * @param environment the current environment, which may affect the behavior of + * the processor. This parameter may be specified as + * <code>null</code>, in which case the + * {@link STextEnvironment#DEFAULT DEFAULT} + * environment should be assumed. + * + * @param text is the structured text string to process. + * + * @param dirProps is a parameter received uniquely to be used as argument + * for calls to <code>getDirProp</code> and other methods used + * by processors. + * + * @return the base direction of the structured text. This direction + * may not be the same depending on the environment and on + * whether the structured text contains Arabic or Hebrew + * letters.<br> + * The value returned is either + * {@link STextEngine#DIR_LTR DIR_LTR} or {@link STextEngine#DIR_RTL DIR_RTL}. + * + * <p>If not overridden, this method returns <code>DIR_LTR</code>. + */ + public int getDirection(STextEnvironment environment, String text, byte[] dirProps) { + return STextEngine.DIR_LTR; + } + + /** + * Indicate the number of special cases handled by the current processor. + * This methode is invoked before starting the processing. + * If the number returned is zero, + * {@link #indexOfSpecial indexOfSpecial} and + * {@link #processSpecial processSpecial} will not be invoked. + * + * @param environment the current environment, which may affect the behavior of + * the processor. This parameter may be specified as + * <code>null</code>, in which case the + * {@link STextEnvironment#DEFAULT DEFAULT} + * environment should be assumed. + * + * @param text is the structured text string to process. + * + * @param dirProps is a parameter received uniquely to be used as argument + * for calls to <code>getDirProp</code> and other methods used + * by processors. + * + * @return the number of special cases for the associated processor. + * Special cases exist for some types of structured text + * processors. They are implemented by overriding methods + * {@link STextProcessor#indexOfSpecial indexOfSpecial} and + * {@link STextProcessor#processSpecial processSpecial}. + * Examples of special cases are comments, literals, or + * anything which is not identified by a one-character separator. + * + * <p>If not overridden, this method returns <code>zero</code>. + */ + public int getSpecialsCount(STextEnvironment environment, String text, byte[] dirProps) { + return 0; + } + + /** + * Check if there is a need for processing structured text. + * This methode is invoked before starting the processing. If the + * processor returns <code>true</code>, no directional formatting + * characters are added to the <i>lean</i> text and the processing + * is shortened. + * + * @param environment the current environment, which may affect the behavior of + * the processor. This parameter may be specified as + * <code>null</code>, in which case the + * {@link STextEnvironment#DEFAULT DEFAULT} + * environment should be assumed. + * + * @param text is the structured text string to process. + * + * @param dirProps is a parameter received uniquely to be used as argument + * for calls to <code>getDirProp</code> and other methods used + * by processors. + * + * @return a flag indicating if there is no need to process the structured + * text to add directional formatting characters. + * + * <p>If not overridden, this method returns <code>false</code>. + */ + public boolean skipProcessing(STextEnvironment environment, String text, byte[] dirProps) { + return false; } } diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextStringProcessor.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextStringProcessor.java index dc87dc7f7..04e9479be 100644 --- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextStringProcessor.java +++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextStringProcessor.java @@ -34,7 +34,7 @@ public class STextStringProcessor { * @return a reference to an instance of a processor of the * required type. If the type is unknown, return <code>null</code>. */ - static public ISTextProcessor getProcessor(String type) { + static public STextProcessor getProcessor(String type) { return STextTypesCollector.getInstance().getProcessor(type); } } diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html index 9bbe97828..382a50212 100644 --- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html +++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html @@ -5,18 +5,13 @@ </head> <body bgcolor="white"> -This package provides an interface and classes for +This package provides classes for developing structured text processors. <ul> - <li>{@link <a href="ISTextProcessor.html">ISTextProcessor</a>} - is an interface specifying which methods a processor must provide.</li> <li>{@link <a href="STextProcessor.html">STextProcessor</a>} - is a generic processor which can be used as superclass for specific + is a generic processor to be used as superclass for specific processors.</li> - <li>{@link <a href="STextFeatures.html">STextFeatures</a>} - allows managing some factors which affect - a structured text processor's behavior</li> <li>{@link <a href="STextStringProcessor.html">STextStringProcessor</a>} is a class which allows retrieval of the defined processor types and of the corresponding processors.</li> |