aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMatitiahu Allouche2011-08-26 10:00:48 (EDT)
committerOleg Besedin2011-08-26 10:00:48 (EDT)
commit7c4edd7341a40fb56c6cdd8ffef1ffec15307c02 (patch)
tree898440e599a280dd73826eb9bb65549065b6a2ee
parent4dec850b19bd8f7d6393ce24e82763b13bf5048c (diff)
downloadrt.equinox.bundles-7c4edd7341a40fb56c6cdd8ffef1ffec15307c02.zip
rt.equinox.bundles-7c4edd7341a40fb56c6cdd8ffef1ffec15307c02.tar.gz
rt.equinox.bundles-7c4edd7341a40fb56c6cdd8ffef1ffec15307c02.tar.bz2
Bug 183164 - [Implementation for] Display of Complex Expressions
Containing Bidirectional Text
-rw-r--r--bundles/org.eclipse.equinox.bidi.tests/src/org/eclipse/equinox/bidi/internal/tests/STextMethodsTest.java16
-rw-r--r--bundles/org.eclipse.equinox.bidi.tests/src/org/eclipse/equinox/bidi/internal/tests/STextSomeMoreTest.java6
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java64
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextStringRecord.java70
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java39
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java201
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java6
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java107
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html31
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java53
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java34
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java212
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/package.html16
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextActivator.java3
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java7
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelimsEsc.java5
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java8
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextSingle.java6
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java3
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextJava.java13
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextRegex.java12
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextSql.java16
-rw-r--r--bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html105
23 files changed, 581 insertions, 452 deletions
diff --git a/bundles/org.eclipse.equinox.bidi.tests/src/org/eclipse/equinox/bidi/internal/tests/STextMethodsTest.java b/bundles/org.eclipse.equinox.bidi.tests/src/org/eclipse/equinox/bidi/internal/tests/STextMethodsTest.java
index a816c6f..41e92fa 100644
--- a/bundles/org.eclipse.equinox.bidi.tests/src/org/eclipse/equinox/bidi/internal/tests/STextMethodsTest.java
+++ b/bundles/org.eclipse.equinox.bidi.tests/src/org/eclipse/equinox/bidi/internal/tests/STextMethodsTest.java
@@ -132,9 +132,9 @@ public class STextMethodsTest extends STextTestBase {
private void doTestOrient(STextTypeHandler handler, String label, String data, String resLTR, String resRTL, String resCon) {
String full, lean;
- ISTextExpert expertLTR = STextExpertFactory.getExpert(handler, envLTR);
- ISTextExpert expertRTL = STextExpertFactory.getExpert(handler, envRTL);
- ISTextExpert expertCRL = STextExpertFactory.getExpert(handler, envCRL);
+ ISTextExpert expertLTR = STextExpertFactory.getStatefulExpert(handler, envLTR);
+ ISTextExpert expertRTL = STextExpertFactory.getStatefulExpert(handler, envRTL);
+ ISTextExpert expertCRL = STextExpertFactory.getStatefulExpert(handler, envCRL);
lean = toUT16(data);
full = expertLTR.leanToFullText(lean);
@@ -205,17 +205,17 @@ public class STextMethodsTest extends STextTestBase {
private void doTestDirection() {
String data, lean, full, model;
int dirA, dirH;
- ISTextExpert expertRL = STextExpertFactory.getExpert(testMyCommaRL, envLTR);
+ ISTextExpert expertRL = STextExpertFactory.getStatefulExpert(testMyCommaRL, envLTR);
dirA = expertRL.getTextDirection(toUT16("###"));
dirH = expertRL.getTextDirection(toUT16("ABC"));
assertTrue("TestDirection #1", dirA == RTL && dirH == LTR);
- ISTextExpert expertRR = STextExpertFactory.getExpert(testMyCommaRR, envLTR);
+ ISTextExpert expertRR = STextExpertFactory.getStatefulExpert(testMyCommaRR, envLTR);
dirA = expertRR.getTextDirection(toUT16("###"));
dirH = expertRR.getTextDirection(toUT16("ABC"));
assertTrue("TestDirection #2", dirA == RTL && dirH == RTL);
- ISTextExpert expertLL = STextExpertFactory.getExpert(testMyCommaLL, envLTR);
+ ISTextExpert expertLL = STextExpertFactory.getStatefulExpert(testMyCommaLL, envLTR);
lean = toUT16("ABC,#DEF,HOST,com");
full = expertLL.leanToFullText(lean);
assertEquals("TestDirection #9 full", "ABC@,#DEF@,HOST,com", toPseudo(full));
@@ -226,7 +226,7 @@ public class STextMethodsTest extends STextTestBase {
assertEquals("TestDirection #10 full", "ABC@,DEF@,HOST,com", toPseudo(full));
STextEnvironment environment = new STextEnvironment(null, true, STextEnvironment.ORIENT_LTR);
- ISTextExpert expert = STextExpertFactory.getExpert(testMyCommaRL, environment);
+ ISTextExpert expert = STextExpertFactory.getStatefulExpert(testMyCommaRL, environment);
dirA = expert.getTextDirection(toUT16("###"));
dirH = expert.getTextDirection(toUT16("ABC"));
assertTrue("TestDirection #10.5", dirA == RTL && dirH == LTR);
@@ -268,7 +268,7 @@ public class STextMethodsTest extends STextTestBase {
data = "ABc,|#DEF,HOST,com";
lean = toUT16(data);
- expert = STextExpertFactory.getExpert(testMyCommaRL, envRTLMIR);
+ expert = STextExpertFactory.getStatefulExpert(testMyCommaRL, envRTLMIR);
full = expert.leanToFullText(lean);
model = "ABc,|#DEF,HOST,com";
assertEquals("TestDirection #17 full", model, toPseudo(full));
diff --git a/bundles/org.eclipse.equinox.bidi.tests/src/org/eclipse/equinox/bidi/internal/tests/STextSomeMoreTest.java b/bundles/org.eclipse.equinox.bidi.tests/src/org/eclipse/equinox/bidi/internal/tests/STextSomeMoreTest.java
index 3c8b7e5..b221679 100644
--- a/bundles/org.eclipse.equinox.bidi.tests/src/org/eclipse/equinox/bidi/internal/tests/STextSomeMoreTest.java
+++ b/bundles/org.eclipse.equinox.bidi.tests/src/org/eclipse/equinox/bidi/internal/tests/STextSomeMoreTest.java
@@ -77,12 +77,12 @@ public class STextSomeMoreTest extends STextTestBase {
assertTrue(env2.isProcessingNeeded());
STextTypeHandler handler1 = new TestHandler1();
- ISTextExpert expert1 = STextExpertFactory.getExpert(handler1, env1);
+ ISTextExpert expert1 = STextExpertFactory.getStatefulExpert(handler1, env1);
String full = expert1.leanToFullText("abcd");
assertEquals("@a@b@c@d", toPseudo(full));
STextTypeHandler handler2 = new TestHandler2();
- ISTextExpert expert2 = STextExpertFactory.getExpert(handler2, env1);
+ ISTextExpert expert2 = STextExpertFactory.getStatefulExpert(handler2, env1);
boolean catchFlag = false;
try {
full = expert2.leanToFullText("abcd");
@@ -92,7 +92,7 @@ public class STextSomeMoreTest extends STextTestBase {
assertTrue("Catch missing indexOfSpecial", catchFlag);
STextTypeHandler handler3 = new TestHandler3();
- ISTextExpert expert3 = STextExpertFactory.getExpert(handler3, env1);
+ ISTextExpert expert3 = STextExpertFactory.getStatefulExpert(handler3, env1);
catchFlag = false;
try {
full = expert3.leanToFullText("abcd");
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java
index fcfe7f5..b57a33d 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextProcessor.java
@@ -14,7 +14,7 @@ import org.eclipse.equinox.bidi.advanced.*;
import org.eclipse.equinox.bidi.custom.STextTypeHandler;
/**
- * This class provides a number of convenience functions facilitating the
+ * Provides a number of convenience functions facilitating the
* processing of structured text.
*
* @noextend This class is not intended to be subclassed by clients.
@@ -25,7 +25,8 @@ import org.eclipse.equinox.bidi.custom.STextTypeHandler;
public final class STextProcessor {
/**
- * The default set of separators used to segment a string: dot, colon, slash, backslash.
+ * The default set of separators used to segment a string: dot,
+ * colon, slash, backslash.
*/
private static final String defaultSeparators = ".:/\\"; //$NON-NLS-1$
@@ -49,7 +50,7 @@ public final class STextProcessor {
}
/**
- * Process the given text and return a string with appropriate
+ * Processes the given text and returns a string with appropriate
* directional formatting characters. This is equivalent to calling
* {@link #process(String str, String separators)} with the default
* set of separators.
@@ -64,20 +65,25 @@ public final class STextProcessor {
* (where capital letters indicate RTL text) should render as
* <tt>d:\myfolder\REDLOF\ELIFYM.java</tt>.
* </p>
- * @param str the text to be processed
- * @return the processed string
+ *
+ * @param str the text to be processed.
+ *
+ * @return the processed string.
*/
public static String process(String str) {
return process(str, defaultSeparators);
}
/**
- * Process a string that has a particular semantic meaning to render
- * it correctly on bidi locales.
+ * Processes a string that has a particular semantic meaning to render
+ * it correctly on bidi locales.
+ *
* @see #process(String)
- * @param str the text to process
- * @param separators separators by which the string will be segmented
- * @return the processed string
+ *
+ * @param str the text to process.
+ * @param separators characters by which the string will be segmented.
+ *
+ * @return the processed string.
*/
public static String process(String str, String separators) {
if ((str == null) || (str.length() <= 1))
@@ -118,16 +124,23 @@ public final class STextProcessor {
// make sure that LRE/PDF are added around the string
STextTypeHandler handler = new STextTypeHandler(separators);
- ISTextExpert expert = STextExpertFactory.getExpert(handler, env);
+ ISTextExpert expert = STextExpertFactory.getStatefulExpert(handler, env);
return expert.leanToFullText(str);
}
/**
* Processes a string that has a particular semantic meaning to render
- * it correctly on bidi locales.
+ * it correctly on bidi locales.
+ *
* @see #process(String)
- * @param str the text to process
- * @param handler a handler instance appropriate for the type of the structured text
+ *
+ * @param str the text to process.
+ * @param textType an identifier for the handler instance appropriate
+ * for the type of the structured text.
+ * It may be one of the identifiers defined in
+ * {@link STextTypeHandlerFactory} or a type handler identifier
+ * specified in a plug-in.
+ *
* @return the processed string
*/
public static String processTyped(String str, String textType) {
@@ -149,8 +162,10 @@ public final class STextProcessor {
/**
* Removes directional formatting characters in the given string.
- * @param str string with directional characters to remove
- * @return string without directional formatting characters
+ *
+ * @param str string with directional characters to remove.
+ *
+ * @return string without directional formatting characters.
*/
public static String deprocess(String str) {
if ((str == null) || (str.length() <= 1))
@@ -179,9 +194,16 @@ public final class STextProcessor {
/**
* Removes directional formatting characters in the given string.
- * @param str string with directional characters to remove
- * @param handler appropriate for the structured text
- * @return string without directional formatting characters
+ *
+ * @param str string with directional characters to remove.
+ *
+ * @param textType an identifier for the handler instance appropriate
+ * for the type of the structured text.
+ * It may be one of the identifiers defined in
+ * {@link STextTypeHandlerFactory} or a type handler identifier
+ * specified in a plug-in.
+ *
+ * @return string without directional formatting characters.
*/
public static String deprocessTyped(String str, String textType) {
if ((str == null) || (str.length() <= 1))
@@ -196,10 +218,10 @@ public final class STextProcessor {
}
/**
- * Return the string containing all the default separator characters to be
+ * Returns a string containing all the default separator characters to be
* used to segment a given string.
*
- * @return string containing all separators
+ * @return string containing all separators.
*/
public static String getDefaultSeparators() {
return defaultSeparators;
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextStringRecord.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextStringRecord.java
index 60d48d8..ab22794 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextStringRecord.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextStringRecord.java
@@ -13,7 +13,7 @@ package org.eclipse.equinox.bidi;
import java.lang.ref.SoftReference;
/**
- * This class records strings which contain structured text. Several static
+ * Records strings which contain structured text. 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>
@@ -73,7 +73,7 @@ public class STextStringRecord {
}
/**
- * Record a string in the pool. The caller must specify the number
+ * Records a string in the pool. The caller must specify the number
* of segments in the record (at least 1), and the handler, starting
* and ending offsets for the first segment.
*
@@ -82,10 +82,11 @@ public class STextStringRecord {
* @param segmentCount number of segments allowed in this string.
* This number must be >= 1.
*
- * @param handler the handler appropriate to handle the type
- * of structured text present in the first segment.
- * It may be one of the pre-defined handler instances, or it may be an instance
- * created by a plug-in or by the application.
+ * @param handlerID identifier for the handler appropriate to handle
+ * the type of structured text present in the first segment.
+ * It may be one of the predefined identifiers in
+ * {@link STextTypeHandlerFactory}, or it may be an identifier
+ * for a type handler created by a plug-in or by the application.
*
* @param start offset in the string of the starting character of the first
* segment. It must be >= 0 and less than the length of the string.
@@ -95,7 +96,7 @@ public class STextStringRecord {
* not greater than the length of the string.
*
* @return an instance of STextRecordString which represents this record.
- * This instance may be used to specify additional segment with
+ * This instance may be used to specify additional segments with
* {@link #addSegment addSegment}.
*
* @throws IllegalArgumentException if <code>string</code> is null or
@@ -137,12 +138,13 @@ public class STextStringRecord {
}
/**
- * Add a second or further segment to a record.
+ * Adds a second or further segment to a record.
*
- * @param handler the handler appropriate to handle the type
- * of structured text present in this segment.
- * It may be one of the pre-defined handler instances, or it may be an instance
- * created by a plug-in or by the application.
+ * @param handlerID identifier for the handler appropriate to handle
+ * the type of structured text present in the first segment.
+ * It may be one of the predefined identifiers in
+ * {@link STextTypeHandlerFactory}, or it may be an identifier
+ * for a type handler created by a plug-in or by the application.
*
* @param start offset in the string of the starting character of the
* segment. It must be >= 0 and less than the length of the string.
@@ -151,7 +153,7 @@ public class STextStringRecord {
* greater than the <code>start</code> argument and not greater
* than the length of the string.
*
- * @throws IllegalArgumentException if <code>handler</code> is null,
+ * @throws IllegalArgumentException if <code>handlerID</code> is null,
* or if <code>start</code> or <code>limit</code> have invalid
* values.
* @throws IllegalStateException if the current segment exceeds the
@@ -161,7 +163,7 @@ public class STextStringRecord {
*/
public void addSegment(String handlerID, int start, int limit) {
if (handlerID == null)
- throw new IllegalArgumentException("The handler argument must not be null!"); //$NON-NLS-1$
+ throw new IllegalArgumentException("The handlerID argument must not be null!"); //$NON-NLS-1$
if (start < 0 || start >= string.length())
throw new IllegalArgumentException("The start position must be at least 0 and less than the length of the string!"); //$NON-NLS-1$
if (limit <= start || limit > string.length())
@@ -175,16 +177,16 @@ public class STextStringRecord {
}
/**
- * Check if a string is recorded and retrieve its record.
+ * Checks if a string is recorded and retrieve its record.
*
* @param string the string to check.
*
* @return <code>null</code> if the string is not recorded in the pool;
- * otherwise, return the STextStringRecord instance which
- * records this string.<br>
+ * otherwise, return the <code>STextStringRecord</code> instance
+ * which records this string.<br>
* Once a record has been found, the number of its segments can
* be retrieved using {@link #getSegmentCount getSegmentCount},
- * its handler can
+ * its handler ID can
* be retrieved using {@link #getHandler getHandler},
* its starting offset can
* be retrieved using {@link #getStart getStart},
@@ -223,7 +225,8 @@ public class STextStringRecord {
}
/**
- * Retrieve the number of segments in a record.
+ * Retrieves the number of segments in a record.
+ *
* @return the number of segments in the current record
*/
public int getSegmentCount() {
@@ -236,21 +239,18 @@ public class STextStringRecord {
}
/**
- * Retrieve the handler of a given segment.
+ * Retrieves the handler ID of a given segment.
*
* @param segmentNumber number of the segment about which information
* is required. It must be >= 0 and less than the number of
- * segments specified by <code>segmentCount</code>
- * in the call to {@link #addRecord addRecord} which created
- * the STextStringRecord instance.
+ * segments returned by {@link #getSegmentCount}.
*
- * @return the handler to handle the structured text in the segment
+ * @return the handler ID of the handler appropriate to
+ * process the structured text in the segment
* specified by <code>segmentNumber</code>.
*
* @throws IllegalArgumentException if <code>segmentNumber</code>
* has an invalid value.
- *
- * @see #getSegmentCount
*/
public String getHandler(int segmentNumber) {
checkSegmentNumber(segmentNumber);
@@ -258,21 +258,17 @@ public class STextStringRecord {
}
/**
- * Retrieve the starting offset of a given segment.
+ * Retrieves the starting offset of a given segment.
*
* @param segmentNumber number of the segment about which information
* is required. It must be >= 0 and less than the number of
- * segments specified by <code>segmentCount</code>
- * in the call to {@link #addRecord addRecord} which created
- * the STextStringRecord instance.
+ * segments returned by {@link #getSegmentCount}.
*
* @return the starting offset within the string of the segment
* specified by <code>segmentNumber</code>.
*
* @throws IllegalArgumentException if <code>segmentNumber</code>
* has an invalid value.
- *
- * @see #getSegmentCount
*/
public int getStart(int segmentNumber) {
checkSegmentNumber(segmentNumber);
@@ -280,21 +276,17 @@ public class STextStringRecord {
}
/**
- * Retrieve the ending offset of a given segment.
+ * Retrieves the ending offset of a given segment.
*
* @param segmentNumber number of the segment about which information
* is required. It must be >= 0 and less than the number of
- * segments specified by <code>segmentCount</code>
- * in the call to {@link #addRecord addRecord} which created
- * the STextStringRecord instance.
+ * segments returned by {@link #getSegmentCount}.
*
* @return the offset of the position following the segment
* specified by <code>segmentNumber</code>.
*
* @throws IllegalArgumentException if <code>segmentNumber</code>
* has an invalid value.
- *
- * @see #getSegmentCount
*/
public int getLimit(int segmentNumber) {
checkSegmentNumber(segmentNumber);
@@ -302,7 +294,7 @@ public class STextStringRecord {
}
/**
- * Clear the pool. All elements of the pool are erased and any associated
+ * Clears the pool. All elements of the pool are erased and any associated
* memory is freed.
*/
public static synchronized void clear() {
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java
index 5889e9b..9a3eba2 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/STextTypeHandlerFactory.java
@@ -14,14 +14,14 @@ import org.eclipse.equinox.bidi.custom.STextTypeHandler;
import org.eclipse.equinox.bidi.internal.STextTypesCollector;
/**
- * This class provides access to registered structured text handlers.
+ * Provides access to registered structured text handlers.
*
* @noinstantiate This class is not intended to be instantiated by clients.
*/
final public class STextTypeHandlerFactory {
/**
- * Structured text handler for property file statements. It expects the following format:
+ * Structured text handler identifier for property file statements. It expects the following format:
* <pre>
* name=value
* </pre>
@@ -29,7 +29,7 @@ final public class STextTypeHandlerFactory {
public static final String PROPERTY = "property"; //$NON-NLS-1$
/**
- * Structured text handler for compound names. It expects text to be made of one or more
+ * Structured text handler identifier for compound names. It expects text to be made of one or more
* parts separated by underscores:
* <pre>
* part1_part2_part3
@@ -38,7 +38,7 @@ final public class STextTypeHandlerFactory {
public static final String UNDERSCORE = "underscore"; //$NON-NLS-1$
/**
- * Structured text handler for comma-delimited lists, such as:
+ * Structured text handler identifier for comma-delimited lists, such as:
* <pre>
* part1,part2,part3
* </pre>
@@ -46,7 +46,7 @@ final public class STextTypeHandlerFactory {
public static final String COMMA_DELIMITED = "comma"; //$NON-NLS-1$
/**
- * Structured text handler for strings with the following format:
+ * Structured text handler identifier for strings with the following format:
* <pre>
* system(user)
* </pre>
@@ -54,42 +54,46 @@ final public class STextTypeHandlerFactory {
public static final String SYSTEM_USER = "system"; //$NON-NLS-1$
/**
- * Structured text handler for directory and file paths.
+ * Structured text handler identifier for directory and file paths.
*/
public static final String FILE = "file"; //$NON-NLS-1$
/**
- * Structured text handler for e-mail addresses.
+ * Structured text handler identifier for e-mail addresses.
*/
public static final String EMAIL = "email"; //$NON-NLS-1$
/**
- * Structured text handler for URLs.
+ * Structured text handler identifier for URLs.
*/
public static final String URL = "url"; //$NON-NLS-1$
/**
- * Structured text handler for regular expressions, possibly spanning multiple lines.
+ * Structured text handler identifier for regular expressions,
+ * possibly spanning multiple lines.
*/
public static final String REGEXP = "regex"; //$NON-NLS-1$
/**
- * Structured text handler for XPath expressions.
+ * Structured text handler identifier for XPath expressions.
*/
public static final String XPATH = "xpath"; //$NON-NLS-1$
/**
- * Structured text handler for Java code, possibly spanning multiple lines.
+ * Structured text handler identifier for Java code,
+ * possibly spanning multiple lines.
*/
public static final String JAVA = "java"; //$NON-NLS-1$
/**
- * Structured text handler for SQL statements, possibly spanning multiple lines.
+ * Structured text handler identifier for SQL statements,
+ * possibly spanning multiple lines.
*/
public static final String SQL = "sql"; //$NON-NLS-1$
/**
- * Structured text handler for arithmetic expressions, possibly with a RTL base direction.
+ * Structured text handler identifier for arithmetic expressions,
+ * possibly with a RTL base direction.
*/
public static final String RTL_ARITHMETIC = "math"; //$NON-NLS-1$
@@ -101,9 +105,12 @@ final public class STextTypeHandlerFactory {
}
/**
- * Obtain a structured text handler of a given type.
- * @param id string identifying handler
- * @return a handler of the required type, or <code>null</code> if the type is unknown
+ * Obtains a structured text handler of a given type.
+ *
+ * @param id the string identifying a structured text handler.
+ *
+ * @return a handler of the required type, or <code>null</code>
+ * if the type is unknown.
*/
static public STextTypeHandler getHandler(String id) {
return STextTypesCollector.getInstance().getHandler(id);
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java
index 535e275..dbb5fb0 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/ISTextExpert.java
@@ -13,40 +13,44 @@ package org.eclipse.equinox.bidi.advanced;
import org.eclipse.equinox.bidi.custom.STextTypeHandler;
/**
+ * Advanced API for processing structured text.
* For a general introduction to structured text, see
- * {@link <a href="package-summary.html"> the package documentation</a>}.
+ * {@link <a href="../package-summary.html">the org.eclipse.equinox.bidi
+ * package documentation</a>}.
* <p>
- * Several common handlers are included in <b>STextEngine</b>. For handlers
+ * Identifiers for several common handlers are included in
+ * {@link org.eclipse.equinox.bidi.STextTypeHandlerFactory}. For handlers
* supplied by other packages, a handler instance can be obtained using the
* {@link org.eclipse.equinox.bidi.STextTypeHandlerFactory#getHandler}
* method for the registered handlers, or by instantiating a private handler.
* </p><p>
- * Most of the methods in this class have a <code>text</code>
+ * 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, a <code>state</code>
- * argument must be used.
+ * has not been completed. In such cases, the state must be managed
+ * by a <code>ISTextExpert</code> instance obtained with the
+ * {@link STextExpertFactory#getStatefulExpert getStateful} method.
* </p><p>
- * The <code>state</code> argument must be an array of integers
- * with at least one element. Only the first element is used by
- * the methods of this class.
+ * 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 the text, the first element
- * of <code>state</code> must contain the value {@link #STATE_INITIAL}
- * or any value <= 0.
+ * When submitting the initial part of a text, the state should be
+ * reset if it is not the first processing call for this
+ * <code>ISTextExpert</code> instance.
* </p><p>
- * After calling a method with a non-null <code>state</code> argument,
- * a value is returned in the first element of <code>state</code>. This
- * value should be passed unmodified to the method when calling it again
- * with the text which is the continuation of the text submitted in the
- * last call.
+ * 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) setState} 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>
- * When the text submitted to a method is not a continuation and is not
- * expected to have a continuation , e.g. it is processed all by itself,
- * the <code>state</code> argument should be specified as <code>null</code>.
+ * 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>
@@ -54,8 +58,9 @@ import org.eclipse.equinox.bidi.custom.STextTypeHandler;
* (directory and file paths) in order to obtain the <i>full</i>
* text corresponding to the given <i>lean</i> text.
* <pre>
+ * ISTextExpert expert = STextExpertFactory.getExpert(STextTypeHandlerFactory.FILE);
* String leanText = "D:\\\u05d0\u05d1\\\u05d2\\\u05d3.ext";
- * String fullText = STextEngine.leanToFullText(STextEngine.PROC_FILE, null, leanText, null);
+ * String fullText = expert.leanToFullText(leanText);
* System.out.println("full text = " + fullText);
* </pre>
* </p><p>
@@ -63,12 +68,12 @@ import org.eclipse.equinox.bidi.custom.STextTypeHandler;
* code in order to obtain the <i>full</i>
* text corresponding to the <i>lean</i> text of each line.
* <pre>
- * Object state = STextState.createState();
+ * ISTextExpert expert = STextExpertFactory.getStatefulExpert(STextTypeHandlerFactory.JAVA);
* String leanText = "int i = 3; // first Java statement";
- * String fullText = STextEngine.leanToFullText(STextEngine.PROC_JAVA, null, leanText, state);
+ * String fullText = expert.leanToFullText(leanText);
* System.out.println("full text = " + fullText);
* leanText = "i += 4; // next Java statement";
- * fullText = STextEngine.leanToFullText(STextEngine.PROC_JAVA, null, leanText, state);
+ * fullText = expert.leanToFullText(leanText,);
* System.out.println("full text = " + fullText);
* </pre>
* </p>
@@ -80,10 +85,10 @@ public interface ISTextExpert {
/**
* 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
+ * {@link STextEnvironment#getMirrored mirrored} and
* may be different for Arabic and for Hebrew.
* This constant can appear as value returned by the
- * {@link #getCurDirection getCurDirection} method.
+ * {@link #getTextDirection getTextDirection} method.
*/
public static final int DIR_LTR = 0;
@@ -93,60 +98,49 @@ public interface ISTextExpert {
* {@link STextEnvironment#getMirrored mirrored} and may
* may be different for Arabic and for Hebrew.
* This constant can appear as value returned by the
- * {@link #getCurDirection getCurDirection} method.
+ * {@link #getTextDirection getTextDirection} method.
*/
public static final int DIR_RTL = 1;
+ /**
+ * Obtains the structured type handler associated with this
+ * <code>ISTextExpert</code> instance.
+ * @return the type handler instance.
+ */
public STextTypeHandler getTypeHandler();
+ /**
+ * Obtains the environment associated with this
+ * <code>ISTextExpert</code> instance.
+ * @return the environment instance.
+ */
public STextEnvironment getEnvironment();
/**
- * Add directional formatting characters to a structured text
+ * Adds directional formatting characters to a structured text
* to ensure correct presentation.
*
- * @param handler the handler applicable to the text. If <code>null</code>,
- * the method returns unmodified text.
- *
- * @param environment a bidi environment. If <code>null</code>, the default environment
- * is used.
- *
* @param text is the structured text string
*
- * @param state can be used to specify that the <code>text</code> argument is
- * the continuation of text submitted in a previous call and/or to receive information
- * to pass to continuation calls. If all calls to this method are independent from one another,
- * this argument should be specified as <code>null</code>.
- *
* @return the structured text with directional formatting characters added to ensure
* correct presentation.
*/
public String leanToFullText(String text);
/**
- * Given a <i>lean</i> string, compute the positions of each of its
+ * Given a <i>lean</i> string, computes the positions of each of its
* characters within the corresponding <i>full</i> string.
*
- * @param handler designates a handler instance. If <code>null</code>, this
- * method returns an identity map.
- *
- * @param environment specifies an environment whose characteristics may affect
- * the handler's behavior. If <code>null</code>, the default environment is used.
- *
* @param text is the structured text string.
*
- * @param state can be used to specify that the <code>text</code> argument is
- * the continuation of text submitted in a previous call and/or to receive information
- * to pass to continuation calls. If all calls to this method are independent from one another,
- * this argument should be specified as <code>null</code>.
- *
- * @return an array which specifies offsets of the <code>text</code> characters
- * in the <i>full</i> 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, compute the offsets of characters
+ * 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>
@@ -156,18 +150,8 @@ public interface ISTextExpert {
* depending on the {@link STextEnvironment#getOrientation orientation} of the
* GUI component used for display are not reflected in this method.
* </p>
- * @param handler designates a handler instance
- *
- * @param environment specifies an environment whose characteristics may affect
- * the handler's behavior. If <code>null</code>, the default environment is used.
- *
* @param text is the structured text string
*
- * @param state can be used to specify that the <code>text</code> argument is
- * the continuation of text submitted in a previous call and/or to receive information
- * to pass to continuation calls. If all calls to this method are independent from one another,
- * this argument should be specified as <code>null</code>.
- *
* @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.
@@ -175,21 +159,11 @@ public interface ISTextExpert {
public int[] leanBidiCharOffsets(String text);
/**
- * Remove directional formatting characters which were added to a
+ * Removes directional formatting characters which were added to a
* structured text string to ensure correct presentation.
*
- * @param handler designates a handler instance
- *
- * @param environment specifies an environment whose characteristics may affect
- * the handler's behavior. If <code>null</code>, the default environment is used.
- *
* @param text is the structured text string including directional formatting characters.
*
- * @param state can be used to specify that the <code>text</code> argument is
- * the continuation of text submitted in a previous call and/or to receive information
- * to pass to continuation calls. If all calls to this method are independent from one another,
- * this argument should be specified as <code>null</code>.
- *
* @return the structured text string without directional formatting characters
* which might have been added by processing it with {@link #leanToFullText}.
*
@@ -197,31 +171,23 @@ public interface ISTextExpert {
public String fullToLeanText(String text);
/**
- * Given a <i>full</i> string, compute the positions of each of its
+ * Given a <i>full</i> string, computes the positions of each of its
* characters within the corresponding <i>lean</i> string.
*
- * @param handler designates a handler instance
- *
- * @param environment specifies an environment whose characteristics may affect
- * the handler's behavior. If <code>null</code>, the default environment is used.
- *
* @param text is the structured text string including directional formatting characters.
*
- * @param state can be used to specify that the <code>text</code> argument is
- * the continuation of text submitted in a previous call and/or to receive information
- * to pass to continuation calls. If all calls to this method are independent from one another,
- * this argument should be specified as <code>null</code>.
- *
- * @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.
+ * @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, return the offsets of characters
+ * 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>
@@ -230,18 +196,8 @@ public interface ISTextExpert {
* or suffixed depending on the {@link STextEnvironment#getOrientation orientation}
* of the GUI component used for display.
* </p>
- * @param handler designates a handler instance
- *
- * @param environment specifies an environment whose characteristics may affect
- * the handler's behavior. If <code>null</code>, the default environment is used.
- *
* @param text is the structured text string including directional formatting characters
*
- * @param state can be used to specify that the <code>text</code> argument is
- * the continuation of text submitted in a previous call and/or to receive information
- * to pass to continuation calls. If all calls to this method are independent from one another,
- * this argument should be specified as <code>null</code>.
- *
* @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.
@@ -249,15 +205,16 @@ public interface ISTextExpert {
public int[] fullBidiCharOffsets(String text);
/**
- * This method adds directional marks to the given text before the characters
+ * 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 markers (LRE, RLE and PDF) can
- * be added depending on the value of the <code>affix</code> argument.
+ * 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>
* @see ISTextExpert#leanBidiCharOffsets(String)
*
@@ -269,8 +226,12 @@ public interface ISTextExpert {
* @param direction the base direction of the structured text.
* It must be one of the values {@link #DIR_LTR}, or
* {@link #DIR_RTL}.
- * @param affix specifies if a prefix and a suffix should be added to
- * the result
+ * @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
@@ -283,29 +244,33 @@ public interface ISTextExpert {
* 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 handler designates a handler instance
- *
- * @param environment specifies an environment whose characteristics may affect
- * the handler's behavior. If <code>null</code>, the default environment is used.
- *
- * @param text is the structured text string
+ * @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
-
- // TBD is there a case where we get a shared expert and setting state is a "must"?
- // Javadoc note: shared experts will ignore this
+ //////////////////////////////////////////////////////////////////////
+ /**
+ * 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);
- // Javadoc note: may return null. Will return null for shared experts
+ /**
+ * 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 has nothing to pass to the next call.
+ * @return the last established state.
+ */
public Object getState();
/**
- * Resets state to initial.
+ * Resets the state to initial.
+ * This method does nothing if the expert instance is not a stateful one.
*/
public void clearState();
}
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java
index 6e21116..474fb00 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextEnvironment.java
@@ -13,8 +13,8 @@ package org.eclipse.equinox.bidi.advanced;
import org.eclipse.equinox.bidi.internal.STextActivator;
/**
- * This class describes environment within which structured text strings are
- * processed. It includes, for example:
+ * Describes the environment within which structured text strings are
+ * processed. It includes:
* <ul>
* <li>locale,</li>
* <li>desired orientation,</li>
@@ -162,7 +162,7 @@ public class STextEnvironment {
/**
* Checks if bidi processing is needed in this environment.
- * @return <code>true</code> if bidi processing is needed in this environment
+ * @return <code>true</code> if bidi processing is needed in this environment.
*/
public boolean isProcessingNeeded() {
if (processingNeeded == null) {
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java
index 9d66c84..1c567b7 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/STextExpertFactory.java
@@ -17,6 +17,23 @@ import org.eclipse.equinox.bidi.STextTypeHandlerFactory;
import org.eclipse.equinox.bidi.custom.STextTypeHandler;
import org.eclipse.equinox.bidi.internal.STextImpl;
+/**
+ * Obtains ISTextExpert instances.
+ * There are two kinds of {@link ISTextExpert} instances (called "experts"):
+ * <ul>
+ * <li>stateful, obtained by calling {@link #getStatefulExpert getStatefulExpert}.</li>
+ * <li>not stateful, obtained by calling {@link #getExpert getExpert}.</li>
+ * </ul>
+ * <p>Only the stateful kind can remember the state established by a call to
+ * a text processing method and transmit it as initial state in the next call
+ * to a text processing method.
+ * <p>
+ * Using a stateful expert is more resource intensive, thus not stateful
+ * experts should be used when feasible.
+ *
+ * @author Matitiahu Allouche
+ *
+ */
final public class STextExpertFactory {
/**
@@ -34,6 +51,13 @@ final public class STextExpertFactory {
// prevents instantiation
}
+ /**
+ * Obtains a ISTextExpert instance for processing structured text with
+ * a default type handler segmenting the text according to default separators.
+ * This expert instance does not handle states.
+ * @return the ISTextExpert instance.
+ * @see STextProcessor#getDefaultSeparators()
+ */
static public ISTextExpert getExpert() {
if (defaultExpert == null) {
STextTypeHandler handler = new STextTypeHandler(defaultSeparators);
@@ -42,6 +66,18 @@ final public class STextExpertFactory {
return defaultExpert;
}
+ /**
+ * Obtains a ISTextExpert instance for processing structured text with
+ * the specified type handler.
+ * This expert instance does not handle states.
+ *
+ * @param type the identifier for the required type handler. This identifier
+ * may be one of those listed in {@link STextTypeHandlerFactory}
+ * or it may be have been registered by a plug-in.
+ * @return the ISTextExpert instance.
+ * @throws IllegalArgumentException if <code>type</code> is not a known type
+ * identifier.
+ */
static public ISTextExpert getExpert(String type) {
ISTextExpert expert;
synchronized (sharedDefaultExperts) {
@@ -49,7 +85,7 @@ final public class STextExpertFactory {
if (expert == null) {
STextTypeHandler handler = STextTypeHandlerFactory.getHandler(type);
if (handler == null)
- return null;
+ throw new IllegalArgumentException("Invalid type argument"); //$NON-NLS-1$
expert = new STextImpl(handler, STextEnvironment.DEFAULT, false);
sharedDefaultExperts.put(type, expert);
}
@@ -57,6 +93,23 @@ final public class STextExpertFactory {
return expert;
}
+ /**
+ * Obtains a ISTextExpert instance for processing structured text with
+ * the specified type handler and the specified environment.
+ * This expert instance does not handle states.
+ *
+ * @param type the identifier for the required type handler. This identifier
+ * may be one of those listed in {@link STextTypeHandlerFactory}
+ * or it may be have been registered by a plug-in.
+ * @param environment the current environment, which may affect the behavior of
+ * the expert. This parameter may be specified as
+ * <code>null</code>, in which case the
+ * {@link STextEnvironment#DEFAULT DEFAULT}
+ * environment should be assumed.
+ * @return the ISTextExpert instance.
+ * @throws IllegalArgumentException if <code>type</code> is not a known type
+ * identifier.
+ */
static public ISTextExpert getExpert(String type, STextEnvironment environment) {
ISTextExpert expert;
if (environment == null)
@@ -71,7 +124,7 @@ final public class STextExpertFactory {
if (expert == null) {
STextTypeHandler handler = STextTypeHandlerFactory.getHandler(type);
if (handler == null)
- return null;
+ throw new IllegalArgumentException("Invalid type argument"); //$NON-NLS-1$
expert = new STextImpl(handler, environment, false);
experts.put(type, expert);
}
@@ -79,20 +132,66 @@ final public class STextExpertFactory {
return expert;
}
- static public ISTextExpert getExpert(STextTypeHandler handler, STextEnvironment environment) {
+ /**
+ * Obtains a ISTextExpert instance for processing structured text with
+ * the specified type handler and the specified environment.
+ * This expert instance can handle states.
+ *
+ * @param handler the type handler instance. It may have been obtained using
+ * {@link STextTypeHandlerFactory#getHandler(String)} or
+ * by instantiating a type handler.
+ * @param environment the current environment, which may affect the behavior of
+ * the expert. This parameter may be specified as
+ * <code>null</code>, in which case the
+ * {@link STextEnvironment#DEFAULT DEFAULT}
+ * environment should be assumed.
+ * @return the ISTextExpert instance.
+ * @throws IllegalArgumentException if <code>type</code> is not a known type
+ * identifier.
+ */
+ static public ISTextExpert getStatefulExpert(STextTypeHandler handler, STextEnvironment environment) {
if (environment == null)
environment = STextEnvironment.DEFAULT;
return new STextImpl(handler, environment, true);
}
+ /**
+ * Obtains a ISTextExpert instance for processing structured text with
+ * the specified type handler.
+ * This expert instance can handle states.
+ *
+ * @param type the identifier for the required type handler. This identifier
+ * may be one of those listed in {@link STextTypeHandlerFactory}
+ * or it may be have been registered by a plug-in.
+ * @return the ISTextExpert instance.
+ * @throws IllegalArgumentException if <code>type</code> is not a known type
+ * identifier.
+ */
static public ISTextExpert getStatefulExpert(String type) {
return getStatefulExpert(type, STextEnvironment.DEFAULT);
}
+ /**
+ * Obtains a ISTextExpert instance for processing structured text with
+ * the specified type handler and the specified environment.
+ * This expert instance can handle states.
+ *
+ * @param type the identifier for the required type handler. This identifier
+ * may be one of those listed in {@link STextTypeHandlerFactory}
+ * or it may be have been registered by a plug-in.
+ * @param environment the current environment, which may affect the behavior of
+ * the expert. This parameter may be specified as
+ * <code>null</code>, in which case the
+ * {@link STextEnvironment#DEFAULT DEFAULT}
+ * environment should be assumed.
+ * @return the ISTextExpert instance.
+ * @throws IllegalArgumentException if <code>type</code> is not a known type
+ * identifier.
+ */
static public ISTextExpert getStatefulExpert(String type, STextEnvironment environment) {
STextTypeHandler handler = STextTypeHandlerFactory.getHandler(type);
if (handler == null)
- return null;
+ throw new IllegalArgumentException("Invalid type argument"); //$NON-NLS-1$
if (environment == null)
environment = STextEnvironment.DEFAULT;
return new STextImpl(handler, environment, true);
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html
new file mode 100644
index 0000000..32abee9
--- /dev/null
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/advanced/package.html
@@ -0,0 +1,31 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<html>
+<head>
+<META name="Author" content="Matitiahu Allouche">
+</head>
+<body bgcolor="white">
+
+This package provides classes for users who need finer control
+on structured text handling.
+<br>
+Note that the basic functions are provided in package
+{@link <a href="../package-summary.html">
+org.eclipse.equinox.bidi</a>} and its
+{@link <a href="../STextProcessor.html">STextProcessor</a>} class.
+<p>
+In particular, the user should use the methods in the
+{@link <a href="ISTextExpert.html">ISTextExpert</a>} class
+in the following cases:</p>
+<ul>
+ <li>The structured type handler to use is not one of those
+ predefined in {@link <a href="../STextTypeHandlerFactory.html">
+ STextTypeHandlerFactory</a>}.</li>
+ <li>A non-default {@link <a href="STextEnvironment.html">
+ environment</a>} needs to be specified.</li>
+ <li>A call to a method processing a piece of text may create a state
+ which affects the processing of the next piece of text.</li>
+ <li>The user needs to manage the offsets where directional formatting
+ characters are inserted in the text.</li>
+</ul>
+</body>
+</html>
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java
index 6857a59..43d0078 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextCharTypes.java
@@ -14,7 +14,7 @@ import org.eclipse.equinox.bidi.advanced.ISTextExpert;
import org.eclipse.equinox.bidi.advanced.STextEnvironment;
/**
- * The class determines bidirectional types of characters in a string.
+ * Determines bidirectional types of characters in a string.
*/
public class STextCharTypes {
@@ -50,14 +50,10 @@ public class STextCharTypes {
/**
* Constructor
*
- * @param handler is the handler handling this occurrence of
- * structured text.
- *
- * @param environment the current environment, which may affect the behavior of
- * the handler. This parameter may be specified as
- * <code>null</code>, in which case the
- * {@link STextEnvironment#DEFAULT DEFAULT}
- * environment should be assumed.
+ * @param expert ISTextExpert instance through which this handler
+ * is invoked. The handler can use ISTextExpert methods to
+ * query items stored in the expert instance, like the current
+ * {@link STextEnvironment environment}.
*
* @param text is the text whose characters are analyzed.
*/
@@ -69,6 +65,18 @@ public class STextCharTypes {
types = new byte[text.length()];
}
+ /**
+ * Indicates the base text direction appropriate for an instance of
+ * structured text.
+ *
+ * @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 ISTextExpert#DIR_LTR DIR_LTR} or
+ * {@link ISTextExpert#DIR_RTL DIR_RTL}.
+ */
public int getDirection() {
if (direction < 0)
direction = handler.getDirection(expert, text, this);
@@ -84,8 +92,8 @@ public class STextCharTypes {
}
/**
- * Returns directionality of the character in the original string at
- * the specified index.
+ * Gets the directionality of the character in the original string
+ * at the specified index.
*
* @param index position of the character in the <i>lean</i> text
*
@@ -111,9 +119,9 @@ public class STextCharTypes {
}
/**
- * Force a bidi type on a character.
+ * Forces a bidi type on a character.
*
- * @param index is the index of the character whose bidi type is set.
+ * @param index position of the character whose bidi type is set.
*
* @param charType bidirectional type of the character. It must be
* one of the values which can be returned by
@@ -124,21 +132,17 @@ public class STextCharTypes {
}
/**
- * Get the orientation of the component in which the text will
+ * Gets the orientation of the component in which the text will
* be displayed.
*
- * @param envir is the current environment, which may affect the behavior of
- * the handler. This parameter may be specified as
- * <code>null</code>, in which case the
- * {@link STextEnvironment#DEFAULT DEFAULT}
- * environment should be assumed.
- *
* @return the orientation as either
- * {@link STextEnvironment#ORIENT_LTR} or
- * {@link STextEnvironment#ORIENT_RTL}.
+ * {@link STextEnvironment#ORIENT_LTR},
+ * {@link STextEnvironment#ORIENT_RTL},
+ * {@link STextEnvironment#ORIENT_UNKNOWN} or
+ * {@link STextEnvironment#ORIENT_IGNORE}.
*/
- public int resolveOrientation(STextEnvironment envir) {
- int orient = envir.getOrientation();
+ public int resolveOrientation() {
+ int orient = environment.getOrientation();
if ((orient & STextEnvironment.ORIENT_CONTEXTUAL) == 0) { // absolute orientation
return orient;
}
@@ -161,4 +165,5 @@ public class STextCharTypes {
}
return orient;
}
+
}
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java
index dd1075d..64e2c0b 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextOffsets.java
@@ -10,6 +10,13 @@
******************************************************************************/
package org.eclipse.equinox.bidi.custom;
+/**
+ * Provides various services related to managing the array of
+ * offsets where directional formatting characters will be inserted.
+ *
+ * @author Matitiahu Allouche
+ *
+ */
public class STextOffsets {
private static final byte L = Character.DIRECTIONALITY_LEFT_TO_RIGHT;
@@ -35,13 +42,17 @@ public class STextOffsets {
}
/**
- * Store the prefix length
+ * Stores the prefix length
+ *
+ * @param prefLen value assigned to the prefix length
*/
public void setPrefixLength(int prefLen) {
prefixLength = prefLen;
}
/**
+ * Gets the number of used entries in the offsets array.
+ *
* @return the number of used entries in the offsets array.
*/
public int getCount() {
@@ -49,15 +60,17 @@ public class STextOffsets {
}
/**
- * Mark that all entries in the offsets array are unused.
+ * Marks that all entries in the offsets array are unused.
*/
public void clear() {
count = 0;
}
/**
- * Get the value of a specified entry in the offsets array.
- * @param index is the index of the entry of interest.
+ * Gets the value of a specified entry in the offsets array.
+ *
+ * @param index the index of the entry of interest.
+ *
* @return the value of the specified entry.
*/
public int getOffset(int index) {
@@ -65,10 +78,13 @@ public class STextOffsets {
}
/**
- * Insert an offset value in the offset array so that the array
+ * Inserts an offset value in the offset array so that the array
* stays in ascending order.
- * @param procData is a group of data accessible to handlers.
- * @param offset is the value to insert.
+ *
+ * @param charTypes an object whose methods can be useful to the
+ * handler.
+ *
+ * @param offset the value to insert.
*/
public void insertOffset(STextCharTypes charTypes, int offset) {
if (count >= offsets.length) {
@@ -114,7 +130,8 @@ public class STextOffsets {
}
/**
- * Get all and only the used offset entries.
+ * Gets all and only the used offset entries.
+ *
* @return the current used entries of the offsets array.
*/
public int[] getOffsets() {
@@ -124,4 +141,5 @@ public class STextOffsets {
System.arraycopy(offsets, 0, array, 0, count);
return array;
}
+
}
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java
index 2a53fa7..64d8668 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/custom/STextTypeHandler.java
@@ -68,37 +68,34 @@ public class STextTypeHandler {
/**
* Creates a new instance of the STextTypeHandler class.
- * @param separators string consisting of characters that split the text into fragments
+ * @param separators string consisting of characters that split the text into fragments.
*/
public STextTypeHandler(String separators) {
this.separators = separators;
}
/**
- * Locate occurrences of special strings within a structured text
- * and return their indexes one after the other in successive calls.
+ * Locates occurrences of special strings within a structured text
+ * and returns their indexes one after the other in successive calls.
* <p>
* This method is called repeatedly if the number of special cases
* returned by {@link #getSpecialsCount} is greater than zero.
* </p><p>
* A handler handling special cases must override this method.
* </p>
- * @param environment the current environment, which may affect the behavior of
- * the handler. This parameter may be specified as
- * <code>null</code>, in which case the
- * {@link STextEnvironment#DEFAULT DEFAULT}
- * environment should be assumed.
+ * @param expert ISTextExpert instance through which this handler
+ * is invoked. The handler can use ISTextExpert methods to
+ * query items stored in the expert instance, like the current
+ * {@link STextEnvironment environment}.
*
- * @param text is the structured text string before
+ * @param text the structured text string before
* addition of any directional formatting characters.
*
- * @param charTypes is a parameter received by <code>indexOfSpecial</code>
- * uniquely to be used as argument for calls to methods which
- * need it.
+ * @param charTypes an object whose methods can be useful to the
+ * handler.
*
- * @param offsets is a parameter received by <code>indexOfSpecial</code>
- * uniquely to be used as argument for calls to methods which
- * need it.
+ * @param offsets an object whose methods can be useful to the
+ * handler.
*
* @param caseNumber number of the special case to locate.
* This number varies from 1 to the number of special cases
@@ -132,68 +129,49 @@ public class STextTypeHandler {
}
/**
- * This method handles special cases specific to this handler.
+ * Handles special cases specific to this handler.
* It is called when a special case occurrence
* is located by {@link #indexOfSpecial}.
* <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.
+ * <code>processSpecial</code> should specify a final state by calling
+ * {@link ISTextExpert#setState(Object)}.
* The meaning of this state is internal to the handler.
- * On a later call, <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.
+ * <p>
+ * On a later call, <code>processSpecial</code> will be called with
+ * <code>-1</code> for parameter <code>separLocation</code>. It should then
+ * retrieve the last state by calling {@link ISTextExpert#getState()} and
+ * clear the state by calling {@link ISTextExpert#clearState()}. After that,
+ * it should perform whatever initializations are required
+ * depending on the last state.
* </p><p>
* A handler handling special cases (with a number of
* special cases greater than zero) must override this method.
* </p>
- * @param environment the current environment, which may affect the behavior of
- * the handler. This parameter may be specified as
- * <code>null</code>, in which case the
- * {@link STextEnvironment#DEFAULT DEFAULT}
- * environment should be assumed.
+ * @param expert ISTextExpert instance through which this handler
+ * is invoked. The handler can use ISTextExpert methods to
+ * query items stored in the expert instance, like the current
+ * {@link STextEnvironment environment}.
*
- * @param text is the structured text string before
+ * @param text the structured text string before
* addition of any directional formatting characters.
*
- * @param charTypes 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 handler 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 handler.
- * 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 handler.
+ * @param charTypes an object whose methods can be useful to the
+ * handler.
+ *
+ * @param offsets an object whose methods can be useful to the
+ * handler.
*
* @param caseNumber number of the special case to handle.
*
* @param separLocation the position returned by
- * {@link #indexOfSpecial indexOfSpecial}. In calls to
+ * {@link #indexOfSpecial indexOfSpecial}. After calls to
* {@link ISTextExpert#leanToFullText leanToFullText} and other
- * methods of {@link ISTextExpert} 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
+ * methods of {@link ISTextExpert} which set a non-null
+ * final state, <code>processSpecial</code> is
+ * called when initializing the processing with value of
* <code>separLocation</code> equal to <code>-1</code>.
*
* @return the position after the scope of the special case ends.
@@ -215,11 +193,11 @@ public class STextTypeHandler {
}
/**
- * This method can be called from within {@link #indexOfSpecial} or
- * {@link #processSpecial} in extensions of <code>STextTypeHandler</code>
- * to specify that a mark character must be added before the character
+ * Specifies 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
+ * <i>full</i> text. This method can be called from within {@link #indexOfSpecial}
+ * or {@link #processSpecial} in extensions of <code>STextTypeHandler</code>.
+ * The mark character will be LRM for structured text
* with a LTR base direction, and RLM for structured text 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
@@ -230,14 +208,10 @@ public class STextTypeHandler {
* <code>processSpecial</code>.
*
* @param charTypes is a parameter received by <code>indexOfSpecial</code>
- * or <code>processSpecial</code>, uniquely to be used as argument
- * for calls to <code>insertMark</code> and other methods used
- * by handlers.
+ * or <code>processSpecial</code>.
*
* @param offsets is a parameter received by <code>indexOfSpecial</code>
- * or <code>processSpecial</code>, uniquely to be used as argument
- * for calls to <code>insertMark</code> and other methods used
- * by handlers.
+ * or <code>processSpecial</code>.
*
* @param offset position of the character in the <i>lean</i> text.
* It must be a non-negative number smaller than the length
@@ -250,11 +224,12 @@ public class STextTypeHandler {
}
/**
- * This method can be called from within {@link #indexOfSpecial} or
- * {@link #processSpecial} in extensions of <code>STextTypeHandler</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.
+ * Adds 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. This method
+ * can be called from within {@link #indexOfSpecial} or
+ * {@link #processSpecial} in extensions of <code>STextTypeHandler</code>.
* <p>
* The logic implemented in this method considers the text before
* <code>separLocation</code> and the text following it. If, and only if,
@@ -267,14 +242,10 @@ public class STextTypeHandler {
* <code>processSpecial</code>.
*
* @param charTypes is a parameter received by <code>indexOfSpecial</code>
- * or <code>processSpecial</code>, uniquely to be used as argument
- * for calls to <code>processSeparator</code> and other methods used
- * by handlers.
+ * or <code>processSpecial</code>.
*
* @param offsets is a parameter received by <code>indexOfSpecial</code>
- * or <code>processSpecial</code>, uniquely to be used as argument
- * for calls to <code>processSeparator</code> and other methods used
- * by handlers.
+ * or <code>processSpecial</code>.
*
* @param separLocation offset of the separator in the <i>lean</i> text.
* It must be a non-negative number smaller than the length
@@ -285,16 +256,15 @@ public class STextTypeHandler {
}
/**
- * Indicate the separators to use for the current handler.
+ * Indicates the separators to use for the current handler.
* This method is invoked before starting the processing.
* <p>
* If no separators are specified, this method returns an empty string.
* </p>
- * @param environment the current environment, which may affect the behavior of
- * the handler. This parameter may be specified as
- * <code>null</code>, in which case the
- * {@link STextEnvironment#DEFAULT DEFAULT}
- * environment should be assumed.
+ * @param expert ISTextExpert instance through which this handler
+ * is invoked. The handler can use ISTextExpert methods to
+ * query items stored in the expert instance, like the current
+ * {@link STextEnvironment environment}.
*
* @return a string grouping one-character separators which separate
* the structured text into tokens.
@@ -304,47 +274,45 @@ public class STextTypeHandler {
}
/**
- * Indicate the base text direction appropriate for an instance of structured text.
- * This method is invoked before starting the processing.
+ * Indicates the base text direction appropriate for an instance of
+ * structured text. This method is invoked before starting the processing.
* <p>
- * If not overridden, this method returns <code>DIR_LTR</code>.
+ * If not overridden, this method returns {@link ISTextExpert#DIR_LTR DIR_LTR}.
* </p>
- * @param environment the current environment, which may affect the behavior of
- * the handler. This parameter may be specified as
- * <code>null</code>, in which case the
- * {@link STextEnvironment#DEFAULT DEFAULT}
- * environment should be assumed.
+ * @param expert ISTextExpert instance through which this handler
+ * is invoked. The handler can use ISTextExpert methods to
+ * query items stored in the expert instance, like the current
+ * {@link STextEnvironment environment}.
*
- * @param text is the structured text string to process.
+ * @param text the structured text string to process.
*
* @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 ISTextExpert#DIR_LTR DIR_LTR} or {@link ISTextExpert#DIR_RTL DIR_RTL}.
+ * {@link ISTextExpert#DIR_LTR DIR_LTR} or
+ * {@link ISTextExpert#DIR_RTL DIR_RTL}.
*/
public int getDirection(ISTextExpert expert, String text) {
return ISTextExpert.DIR_LTR;
}
/**
- * Indicate the base text direction appropriate for an instance of structured text.
- * This method is invoked before starting the processing.
+ * Indicates the base text direction appropriate for an instance of
+ * structured text. This method is invoked before starting the processing.
* <p>
- * If not overridden, this method returns <code>DIR_LTR</code>.
+ * If not overridden, this method returns {@link ISTextExpert#DIR_LTR DIR_LTR}.
* </p>
- * @param environment the current environment, which may affect the behavior of
- * the handler. This parameter may be specified as
- * <code>null</code>, in which case the
- * {@link STextEnvironment#DEFAULT DEFAULT}
- * environment should be assumed.
+ * @param expert ISTextExpert instance through which this handler
+ * is invoked. The handler can use ISTextExpert methods to
+ * query items stored in the expert instance, like the current
+ * {@link STextEnvironment environment}.
*
* @param text is the structured text string to process.
*
- * @param charTypes is a parameter received uniquely to be used as argument
- * for calls to <code>getCharType</code> and other methods used
- * by handlers.
+ * @param charTypes is a parameter received by <code>indexOfSpecial</code>
+ * or <code>processSpecial</code>.
*
* @return the base direction of the structured text. This direction
* may not be the same depending on the environment and on
@@ -358,23 +326,23 @@ public class STextTypeHandler {
}
/**
- * Indicate the number of special cases handled by the current handler.
+ * Indicates the number of special cases handled by the current handler.
* This method is invoked before starting the processing.
- * If the number returned is zero, {@link #indexOfSpecial} and
- * {@link #processSpecial} will not be invoked.
+ * If the number returned is zero, {@link #indexOfSpecial indexOfSpecial}
+ * and {@link #processSpecial processSpecial} will not be invoked.
* <p>
* If not overridden, this method returns <code>zero</code>.
* </p>
- * @param environment the current environment, which may affect the behavior of
- * the handler. This parameter may be specified as
- * <code>null</code>, in which case the
- * {@link STextEnvironment#DEFAULT DEFAULT}
- * environment should be assumed.
+ * @param expert ISTextExpert instance through which this handler
+ * is invoked. The handler can use ISTextExpert methods to
+ * query items stored in the expert instance, like the current
+ * {@link STextEnvironment environment}.
*
* @return the number of special cases for the associated handler.
* Special cases exist for some types of structured text
* handlers. They are implemented by overriding methods
- * {@link STextTypeHandler#indexOfSpecial} and {@link STextTypeHandler#processSpecial}.
+ * {@link STextTypeHandler#indexOfSpecial indexOfSpecial} and
+ * {@link STextTypeHandler#processSpecial processSpecial}.
* Examples of special cases are comments, literals, or
* anything which is not identified by a one-character separator.
*
@@ -392,17 +360,15 @@ public class STextTypeHandler {
* <p>
* If not overridden, this method returns <code>false</code>.
* </p>
- * @param environment the current environment, which may affect the behavior of
- * the handler. This parameter may be specified as
- * <code>null</code>, in which case the
- * {@link STextEnvironment#DEFAULT DEFAULT}
- * environment should be assumed.
+ * @param expert ISTextExpert instance through which this handler
+ * is invoked. The handler can use ISTextExpert methods to
+ * query items stored in the expert instance, like the current
+ * {@link STextEnvironment environment}.
*
* @param text is the structured text string to process.
*
- * @param charTypes is a parameter received uniquely to be used as argument
- * for calls to <code>getCharType</code> and other methods used
- * by handlers.
+ * @param charTypes is a parameter received by <code>indexOfSpecial</code>
+ * or <code>processSpecial</code>.
*
* @return a flag indicating if there is no need to process the structured
* text to add directional formatting characters.
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 382a502..5f7ead0 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
@@ -4,22 +4,12 @@
<META name="Author" content="Matitiahu Allouche">
</head>
<body bgcolor="white">
-
+<p>
This package provides classes for
-developing structured text processors.
-
-<ul>
- <li>{@link <a href="STextProcessor.html">STextProcessor</a>}
- is a generic processor to be used as superclass for specific
- processors.</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>
-</ul>
-
+developing structured text type handlers.
+</p><p>
This package is to be used together with package
{@link <a href="..\package-summary.html">
org.eclipse.equinox.bidi</a>}.
-
</body>
</html>
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextActivator.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextActivator.java
index effe1a7..f364fe2 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextActivator.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextActivator.java
@@ -17,6 +17,9 @@ import org.eclipse.osgi.service.localization.LocaleProvider;
import org.osgi.framework.*;
import org.osgi.util.tracker.ServiceTracker;
+/**
+ * Provides services related to OSGI bundles.
+ */
public class STextActivator implements BundleActivator {
private ServiceTracker logTracker = null;
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java
index d9562bf..d71fcdd 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelims.java
@@ -33,7 +33,7 @@ public abstract class STextDelims extends STextTypeHandler {
}
/**
- * This method locates occurrences of start delimiters.
+ * Locates occurrences of start delimiters.
*
* @return the position starting from offset <code>fromIndex</code>
* in <code>text</code> of the first occurrence of the
@@ -49,9 +49,8 @@ public abstract class STextDelims extends STextTypeHandler {
}
/**
- * This method handles the text between start and end delimiters
- * as a token.
- * It inserts a directional mark if needed at position
+ * Handles the text between start and end delimiters as a token.
+ * This methoed inserts a directional mark if needed at position
* <code>separLocation</code> which corresponds to a start delimiter,
* and skips until after the matching end delimiter.
*
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelimsEsc.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelimsEsc.java
index 67b5baf..85f170a 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelimsEsc.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextDelimsEsc.java
@@ -42,9 +42,8 @@ public abstract class STextDelimsEsc extends STextDelims {
}
/**
- * This method handles the text between start and end delimiters
- * as a token.
- * It inserts a directional mark if needed at position
+ * Handles the text between start and end delimiters as a token.
+ * This method inserts a directional mark if needed at position
* <code>separLocation</code> which corresponds to a start delimiter,
* and skips until after the matching end delimiter,
* ignoring possibly escaped end delimiters.
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java
index de6a2a7..4285ba6 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextImpl.java
@@ -14,6 +14,12 @@ import org.eclipse.equinox.bidi.advanced.ISTextExpert;
import org.eclipse.equinox.bidi.advanced.STextEnvironment;
import org.eclipse.equinox.bidi.custom.*;
+/**
+ * Implementation for ISTextExpert.
+ *
+ * @author Matitiahu Allouche
+ *
+ */
public class STextImpl implements ISTextExpert {
static final String EMPTY_STRING = ""; //$NON-NLS-1$
@@ -304,7 +310,7 @@ public class STextImpl implements ISTextExpert {
if (orientation == STextEnvironment.ORIENT_IGNORE)
prefixLength = 0;
else {
- int resolvedOrientation = charTypes.resolveOrientation(environment);
+ int resolvedOrientation = charTypes.resolveOrientation();
if (orientation != STextEnvironment.ORIENT_UNKNOWN && resolvedOrientation == direction)
prefixLength = 0;
else if ((orientation & STextEnvironment.ORIENT_CONTEXTUAL) != 0)
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextSingle.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextSingle.java
index accaf57..a1bc6ed 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextSingle.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextSingle.java
@@ -36,7 +36,7 @@ public class STextSingle extends STextTypeHandler {
}
/**
- * This method locates occurrences of the separator.
+ * Locates occurrences of the separator.
*
* @see #getSeparators getSeparators
*/
@@ -45,7 +45,7 @@ public class STextSingle extends STextTypeHandler {
}
/**
- * This method inserts a mark before the separator if needed and
+ * Inserts a mark before the separator if needed and
* skips to the end of the source string.
*
* @return the length of <code>text</code>.
@@ -56,7 +56,7 @@ public class STextSingle extends STextTypeHandler {
}
/**
- * This method returns 1 as number of special cases handled by this handler.
+ * Returns 1 as number of special cases handled by this handler.
*
* @return 1.
*/
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java
index f97f51e..4b94cac 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/STextTypesCollector.java
@@ -15,6 +15,9 @@ import java.util.Map;
import org.eclipse.core.runtime.*;
import org.eclipse.equinox.bidi.custom.STextTypeHandler;
+/**
+ * Provides services related to registered structured text handlers.
+ */
public class STextTypesCollector implements IRegistryEventListener {
private static final String EXT_POINT = "org.eclipse.equinox.bidi.bidiTypes"; //$NON-NLS-1$
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextJava.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextJava.java
index 7efdfd1..e987291 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextJava.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextJava.java
@@ -15,21 +15,20 @@ import org.eclipse.equinox.bidi.custom.*;
import org.eclipse.equinox.bidi.internal.STextActivator;
/**
- * <code>STextJava</code> is a handler for structured text
- * composed of Java statements. Such a structured text may span
- * multiple lines.
+ * Handler for structured text composed of Java statements.
+ * Such a structured text may span multiple lines.
* <p>
* In applications like an editor where parts of the text might be modified
* while other parts are not, the user may want to call
* {@link ISTextExpert#leanToFullText}
* separately on each line and save the initial state of each line (this is
* the final state of the previous line which can be retrieved using
- * the value returned in the first element of the <code>state</code> argument).
+ * {@link ISTextExpert#getState()}).
* If both the content
* of a line and its initial state have not changed, the user can be sure that
* the last <i>full</i> text computed for this line has not changed either.
*
- * @see ISTextExpert#leanToFullText explanation of state in leanToFullText
+ * @see ISTextExpert explanation of state
*
* @author Matitiahu Allouche
*/
@@ -50,7 +49,7 @@ public class STextJava extends STextTypeHandler {
}
/**
- * This method looks for occurrences of 4 special strings:
+ * Locates occurrences of 4 special strings:
* <ol>
* <li>spaces</li>
* <li>literals starting with quotation mark</li>
@@ -74,7 +73,7 @@ public class STextJava extends STextTypeHandler {
}
/**
- * This method processes the 4 special cases as follows.
+ * Processes the 4 special cases as follows.
* <ol>
* <li>skip the run of spaces</li>
* <li>look for a matching quotation mark and skip until after it</li>
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextRegex.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextRegex.java
index e484934..3368839 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextRegex.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextRegex.java
@@ -15,7 +15,7 @@ import org.eclipse.equinox.bidi.advanced.STextEnvironment;
import org.eclipse.equinox.bidi.custom.*;
/**
- * <code>STextRegex</code> is a handler for regular expressions.
+ * Handler for regular expressions.
* Such expressions may span multiple lines.
* <p>
* In applications like an editor where parts of the text might be modified
@@ -23,12 +23,12 @@ import org.eclipse.equinox.bidi.custom.*;
* {@link ISTextExpert#leanToFullText}
* separately on each line and save the initial state of each line (this is
* the final state of the previous line which can be retrieved using
- * the value returned in the first element of the <code>state</code> argument).
+ * {@link ISTextExpert#getState()}.
* If both the content
* of a line and its initial state have not changed, the user can be sure that
* the last <i>full</i> text computed for this line has not changed either.
*
- * @see ISTextExpert#leanToFullText explanation of state in leanToFullText
+ * @see ISTextExpert explanation of state
*
* @author Matitiahu Allouche
*/
@@ -66,7 +66,7 @@ public class STextRegex extends STextTypeHandler {
private static final Integer STATE_QUOTED_SEQUENCE = new Integer(17);
/**
- * This method retrieves the number of special cases handled by this handler.
+ * Retrieves the number of special cases handled by this handler.
*
* @return the number of special cases for this handler.
*/
@@ -75,7 +75,7 @@ public class STextRegex extends STextTypeHandler {
}
/**
- * This method locates occurrences of the syntactic strings and of
+ * Locates occurrences of the syntactic strings and of
* R, AL, EN, AN characters.
*/
public int indexOfSpecial(ISTextExpert expert, String text, STextCharTypes charTypes, STextOffsets offsets, int caseNumber, int fromIndex) {
@@ -144,7 +144,7 @@ public class STextRegex extends STextTypeHandler {
}
/**
- * This method process the special cases.
+ * Processes the special cases.
*/
public int processSpecial(ISTextExpert expert, String text, STextCharTypes charTypes, STextOffsets offsets, int caseNumber, int separLocation) {
int location;
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextSql.java b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextSql.java
index 0ea92a7..4ab4276 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextSql.java
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/internal/consumable/STextSql.java
@@ -15,21 +15,20 @@ import org.eclipse.equinox.bidi.custom.*;
import org.eclipse.equinox.bidi.internal.STextActivator;
/**
- * <code>STextSql</code> is a handler for structured text
- * composed of SQL statements. Such a structured text may span
- * multiple lines.
+ * Handler for structured text composed of SQL statements.
+ * Such a structured text may span multiple lines.
* <p>
* In applications like an editor where parts of the text might be modified
* while other parts are not, the user may want to call
* {@link ISTextExpert#leanToFullText}
* separately on each line and save the initial state of each line (this is
- * the final state of the previous line which can be retrieved from the
- * value returned in the first element of the <code>state</code> argument).
+ * the final state of the previous line which can be retrieved by calling
+ * {@link ISTextExpert#getState()}.
* If both the content
* of a line and its initial state have not changed, the user can be sure that
* the last <i>full</i> text computed for this line has not changed either.
*
- * @see ISTextExpert#leanToFullText explanation of state in leanToFullText
+ * @see ISTextExpert explanation of state
*
* @author Matitiahu Allouche
*/
@@ -51,7 +50,7 @@ public class STextSql extends STextTypeHandler {
}
/**
- * This method looks for occurrences of 5 special strings:
+ * Locates occurrences of 5 special strings:
* <ol>
* <li>spaces</li>
* <li>literals starting with apostrophe</li>
@@ -78,7 +77,7 @@ public class STextSql extends STextTypeHandler {
}
/**
- * This method processes the 5 special cases as follows.
+ * Processes the 5 special cases as follows.
* <ol>
* <li>skip the run of spaces</li>
* <li>look for a matching apostrophe and skip until after it</li>
@@ -153,4 +152,5 @@ public class STextSql extends STextTypeHandler {
// we should never get here
return text.length();
}
+
}
diff --git a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html
index 611dee1..665718d 100644
--- a/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html
+++ b/bundles/org.eclipse.equinox.bidi/src/org/eclipse/equinox/bidi/package.html
@@ -9,10 +9,10 @@ This package provides classes for
processing structured text.
<p>
There are various types of structured text. Each type should
-be handled by a specific <i>processor</i>. A number of standard
-processors are supplied in the associated package
-{@link <a href="internal\consumable\package-summary.html">
-org.eclipse.equinox.bidi.internal.consumable</a>}.
+be handled by a specific <i>type handler</i>. A number of standard
+type handlers are supplied in the associated package
+<a href="internal/consumable/package-summary.html">
+org.eclipse.equinox.bidi.internal.consumable</a>.
<h2>Introduction to Structured Text</h2>
<p>
@@ -28,10 +28,10 @@ should be reflected in the display order. The general algorithm, which
has no awareness of these special cases, often gives incorrect results
when displaying such structured text.
</p><p>
-The general idea in handling structured text is to add directional
-formatting characters at proper locations in the text to supplement the
-standard algorithm, so that the final result is correctly displayed
-using the UBA.
+The general idea in handling structured text in this package is to add
+directional formatting characters at proper locations in the text to
+supplement the standard algorithm, so that the final result is correctly
+displayed using the UBA.
</p><p>
A class which handles structured text is thus essentially a
transformation engine which receives text without directional formatting
@@ -45,11 +45,12 @@ called <b><i>lean</i></b> text while the text with added directional
formatting characters is called <b><i>full</i></b> text.
</p><p>
The class {@link
-<a href="STextEngine.html"><b>STextEngine</b></a>}
+<a href="STextProcessor.html"><b>STextProcessor</b></a>}
is the main tool for processing structured text. It facilitates
handling several types of structured text, each type being handled
by a specific
-{@link <a href="custom\STextProcessor.html"><b><i>processor</i></b></a>} :</p>
+{@link <a href="custom/STextTypeHandler.html">
+<b><i>type handler</i></b></a>} :</p>
<ul>
<li>property (name=value)</li>
<li>compound name (xxx_yy_zzzz)</li>
@@ -65,51 +66,75 @@ by a specific
<li>RTL arithmetic expressions</li>
</ul>
<p>
-For each of these types, a static instance is defined in <b>STextEngine</b>.
-These pre-defined instances can be used as argument in the methods of
-<b>STextEngine</b>.
+For each of these types, an identifier is defined in
+{@link <a href="STextTypeHandlerFactory.html">
+<b><i>STextTypeHandlerFactory</i></b></a>} :</p>
+These identifiers can be used as argument in some methods of
+<b>STextProcessor</b> to specify the type of handler to apply.
</p><p>
-Other classes in this package may be used to
-complement and facilitate the action of
-{@link <a href="STextEngine.html">STextEngine</a>}:
+Another class in this package may be used to
+complement the action of
+{@link <a href="STextProcessor.html">STextProcessor</a>}:
<ul>
- <li>{@link <a href="STextEnvironment.html">STextEnvironment</a>}
- regroups details about the environment</li>.
- <li>{@link <a href="STextUtil.html">STextUtil</a>}
- provides a number of convenience methods to process some common types of
- structured text. When using methods in this class, there is no need
- to use other classes of this package. However, the other classes allow
- more precise control and possibly better performance.</li>
<li>{@link <a href="STextStringRecord.html">STextStringRecord</a>}
allows to record strings which are structured text with the
- type of the appropriate processor,
+ type of the appropriate handler,
so that another module can check if a given string has been recorded
- as a structured text string and run its processor.</li>
+ as a structured text string and run its type handler.</li>
</ul>
<p>
-{@link <a href="STextEngine.html">STextEngine</a>} and the
-other classes mentioned above are intended for users who
-need to process structured text for which there already exist
-processors.
+The classes included in this package are intended for users who
+need to process structured text in the most straightforward
+manner, when the following conditions are satisfied:
+<ul>
+ <li>There exists an appropriate handler for the type of the
+ structured text.</li>
+ <li>There is no need to specify non-default conditions related
+ to the {@link <a href="advanced/STextEnvironment.html">
+ environment</a>}.</li>
+ <li>The only operations needed are to transform <i>lean</i> text
+ into <i>full</i> text or vice versa.</li>
+ <li>There is no interdependence between the processing of a
+ given string and the processing of preceding or
+ succeeding strings.</li>
+</ul>
+<p>
+When their needs go beyond the conditions above,
+users can use classes in the
+{@link <a href="advanced/package-summary.html">
+org.eclipse.equinox.bidi.advanced</a>} package:
+<ul>
+ <li>{@link <a href="advanced/ISTextExpert.html">ISTextExpert</a>}
+ provides more sophisticated methods for processing the
+ structured text.</li>
+ <li>{@link <a href="advanced/STextEnvironment.html">STextEnvironment</a>}
+ specifies properties of the environment.</li>
+ <li>{@link <a href="advanced/STextExpertFactory.html">STextExpertFactory</a>}
+ associates a type handler with an environment and provides
+ a <code>STextExpert</code> instance for the user.
+</ul>
<p>
-Developers who want to develop new processors to support types of structured text
-not currently supported can use the following components of the
-package {@link <a href="custom\package-summary.html">
+Developers who want to develop new handlers to support types of
+structured text not currently supported can use the following components
+of the package {@link <a href="custom/package-summary.html">
org.eclipse.equinox.bidi.custom</a>}:
<ul>
- <li>{@link <a href="custom\STextProcessor.html">STextProcessor</a>}
- is a generic processor to be used as superclass for specific
- processors.</li>
- <li>{@link <a href="custom\STextStringProcessor.html">STextStringProcessor</a>}
- allows retrieval of the defined processor types and of the
- corresponding processors.</li>
+ <li>{@link <a href="custom/STextTypeHandler.html">STextTypeHandler</a>}
+ is a generic handler to be used as superclass for specific
+ handlers.</li>
+ <li>{@link <a href="custom/STextCharTypes.html">STextCharTypes</a>}
+ provides services related to the bidi classification of characters.</li>
+ <li>{@link <a href="custom/STextOffsets.html">STextOffsets</a>}
+ provides services related to managing an array of offsets to locations
+ where directional formatting characters should be added in the source
+ string.</li>
</ul>
<p>
There are two other packages associated with the current one:
<ul>
- <li>{@link <a href="internal\package-summary.html">
+ <li>{@link <a href="internal/package-summary.html">
org.eclipse.equinox.bidi.internal</a>}</li>
- <li>{@link <a href="internal\consumable\package-summary.html">
+ <li>{@link <a href="internal/consumable/package-summary.html">
org.eclipse.equinox.bidi.internal.consumable</a>}</li>
</ul>
The tools in the first package can serve as example of how to develop