# Class StructuredTextTypeHandler

java.lang.Object
org.eclipse.equinox.bidi.custom.StructuredTextTypeHandler

Direct Known Subclasses:
  `StructuredTextDelims, StructuredTextSingle`

public class StructuredTextTypeHandler extends Object
Generic handler to be used as superclass (base class) for specific structured text handlers.

Here are some guidelines about how to write structured text handlers.

- Handler instances may be accessed simultaneously by several threads. They should have no instance variables.
- This class provides common logic in code which can be invoked by any `structured text handler`. This common logic uses handler methods to query the characteristics of the specific handler:
  - the separators which separate the structured text into tokens. See `getSeparators(IStructuredTextExpert)`.
  - the direction which governs the display of tokens one after the other. See `getDirection(IStructuredTextExpert, String)`.
  - the number of special cases which need to be handled by code specific to that handler. See `getSpecialsCount(IStructuredTextExpert)`.
- Before starting deeper analysis of the submitted text, the common logic gives to the handler a chance to shorten the process by invoking its `skipProcessing(IStructuredTextExpert, String, StructuredTextCharTypes)` method.
- The common logic then analyzes the text to segment it into tokens according to the appearance of separators (as retrieved using `getSeparators(IStructuredTextExpert)`).
- If the handler indicated a positive number of special cases as return value from its `getSpecialsCount(IStructuredTextExpert)` method, the common logic will repeatedly invoke the handler's `indexOfSpecial(IStructuredTextExpert, String, StructuredTextCharTypes, StructuredTextOffsets, int, int)` method to let it signal the presence of special strings which may further delimit the source text.
- When such a special case is signaled by the handler, the common logic will call the handler's `processSpecial(IStructuredTextExpert, String, StructuredTextCharTypes, StructuredTextOffsets, int, int)` method to give it the opportunity to handle it as needed. Typical actions that the handler may perform are to add directional marks unconditionally (by calling `insertMark(String, StructuredTextCharTypes, StructuredTextOffsets, int)` or conditionally (by calling `processSeparator(String, StructuredTextCharTypes, StructuredTextOffsets, int)`).

## Constructor Summary

Constructors
Constructor
Description
`StructuredTextTypeHandler()`
Creates a new instance of the StructuredTextTypeHandler class.
`StructuredTextTypeHandler(String separators)`
Creates a new instance of the StructuredTextTypeHandler class.

## Method Summary

Modifier and Type
Method
Description
`int`
`getDirection(IStructuredTextExpert expert, String text)`
Indicates the base text direction appropriate for an instance of structured text.
`int`
`getDirection(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes)`
Indicates the base text direction appropriate for an instance of structured text.
`String`
`getSeparators(IStructuredTextExpert expert)`
Indicates the separators to use for the current handler.
`int`
`getSpecialsCount(IStructuredTextExpert expert)`
Indicates the number of special cases handled by the current handler.
`int`
`indexOfSpecial(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int caseNumber, int fromIndex)`
Locates occurrences of special strings within a structured text and returns their indexes one after the other in successive calls.
`static final void`
`insertMark(String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int offset)`
Specifies that a mark character must be added before the character at the specified position of the lean text when generating the full text.
`static final void`
`processSeparator(String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int separLocation)`
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 lean text preceding and following the separator itself.
`int`
`processSpecial(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int caseNumber, int separLocation)`
Handles special cases specific to this handler.
`boolean`
`skipProcessing(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes)`
Checks if there is a need for processing structured text.
`String`
`toString()`

### Methods inherited from class Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Constructor Details

### StructuredTextTypeHandler

public StructuredTextTypeHandler()
Creates a new instance of the StructuredTextTypeHandler class.

### StructuredTextTypeHandler

public StructuredTextTypeHandler(String separators)
Creates a new instance of the StructuredTextTypeHandler class.

Parameters:
  `separators` - string consisting of characters that split the text into fragments.

## Method Details

### indexOfSpecial

public int indexOfSpecial(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int caseNumber, int fromIndex)
Locates occurrences of special strings within a structured text and returns their indexes one after the other in successive calls.

This method is called repeatedly if the number of special cases returned by `getSpecialsCount(IStructuredTextExpert)` is greater than zero.

A handler handling special cases must override this method.

Parameters:
  `expert` - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current `environment`.
  `text` - the structured text string before addition of any directional formatting characters.
  `charTypes` - an object whose methods can be useful to the handler.
  `offsets` - an object whose methods can be useful to the handler.
  `caseNumber` - number of the special case to locate. This number varies from 1 to the number of special cases returned by `getSpecialsCount(IStructuredTextExpert)` for this handler. The meaning of this number is internal to the class implementing `indexOfSpecial`.
  `fromIndex` - the index within `text` to start the search from.
Returns:
  the position where the start of the special case corresponding to `caseNumber` was located. The method must return the first occurrence of whatever identifies the start of the special case starting from `fromIndex`. The method does not have to check if this occurrence appears within the scope of another special case (e.g. a comment starting delimiter within the scope of a literal or vice-versa).
  If no occurrence is found, the method must return -1.
Throws:
  `IllegalStateException` - If not overridden, this method throws an `IllegalStateException`. This is appropriate behavior (and does not need to be overridden) for handlers whose number of special cases is zero, which means that `indexOfSpecial` should never be called for them.

### processSpecial

public int processSpecial(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int caseNumber, int separLocation)
Handles special cases specific to this handler. It is called when a special case occurrence is located by `indexOfSpecial(IStructuredTextExpert, String, StructuredTextCharTypes, StructuredTextOffsets, int, int)`.

If a special processing cannot be completed within a current call to `processSpecial` (for instance, a comment has been started in the current line but its end appears in a following line), `processSpecial` should specify a final state by calling `IStructuredTextExpert.setState(Object)`. The meaning of this state is internal to the handler.

On a later call, `processSpecial` will be called with `-1` for parameter `separLocation`. It should then retrieve the last state by calling `IStructuredTextExpert.getState()` and clear the state by calling `IStructuredTextExpert.clearState()`. After that, it should perform whatever initializations are required depending on the last state.

A handler handling special cases (with a number of special cases greater than zero) must override this method.

Parameters:
  `expert` - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current `environment`.
  `text` - the structured text string before addition of any directional formatting characters.
  `charTypes` - an object whose methods can be useful to the handler.
  `offsets` - an object whose methods can be useful to the handler.
  `caseNumber` - number of the special case to handle.
  `separLocation` - the position returned by `indexOfSpecial(IStructuredTextExpert, String, StructuredTextCharTypes, StructuredTextOffsets, int, int)`. After calls to `IStructuredTextExpert.leanToFullText(String)` and other methods of `IStructuredTextExpert` which set a non-null final state, `processSpecial` is called when initializing the processing with value of `separLocation` equal to `-1`.
Returns:
  the position after the scope of the special case ends. For instance, the position after the end of a comment, the position after the end of a literal.
  A value greater or equal to the length of `text` means that there is no further occurrence of this case in the current structured text.
Throws:
  `IllegalStateException` - If not overridden, this method throws an `IllegalStateException`. This is appropriate behavior (and does not need to be overridden) for handlers whose number of special cases is zero, which means that `processSpecial` should never be called for them.

### insertMark

public static final void insertMark(String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int offset)
Specifies that a mark character must be added before the character at the specified position of the lean text when generating the full text. This method can be called from within `indexOfSpecial(IStructuredTextExpert, String, StructuredTextCharTypes, StructuredTextOffsets, int, int)` or `processSpecial(IStructuredTextExpert, String, StructuredTextCharTypes, StructuredTextOffsets, int, int)` in extensions of `StructuredTextTypeHandler`. 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 the full text.

Parameters:
  `text` - is the structured text string received as parameter to `indexOfSpecial` or `processSpecial`.
  `charTypes` - is a parameter received by `indexOfSpecial` or `processSpecial`.
  `offsets` - is a parameter received by `indexOfSpecial` or `processSpecial`.
  `offset` - position of the character in the lean text. It must be a non-negative number smaller than the length of the lean text. For the benefit of efficiency, it is better to insert multiple marks in ascending order of the offsets.

### processSeparator

public static final void processSeparator(String text, StructuredTextCharTypes charTypes, StructuredTextOffsets offsets, int separLocation)
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 lean text preceding and following the separator itself. This method can be called from within `indexOfSpecial(IStructuredTextExpert, String, StructuredTextCharTypes, StructuredTextOffsets, int, int)` or `processSpecial(IStructuredTextExpert, String, StructuredTextCharTypes, StructuredTextOffsets, int, int)` in extensions of `StructuredTextTypeHandler`.

The logic implemented in this method considers the text before `separLocation` and the text following it. If, and only if, a directional mark is needed to insure that the two parts of text will be laid out according to the base direction, a mark will be added when generating the full text.

Parameters:
  `text` - is the structured text string received as parameter to `indexOfSpecial` or `processSpecial`.
  `charTypes` - is a parameter received by `indexOfSpecial` or `processSpecial`.
  `offsets` - is a parameter received by `indexOfSpecial` or `processSpecial`.
  `separLocation` - offset of the separator in the lean text. It must be a non-negative number smaller than the length of the lean text.

### getSeparators

public String getSeparators(IStructuredTextExpert expert)
Indicates the separators to use for the current handler. This method is invoked before starting the processing.

If no separators are specified, this method returns an empty string.

Parameters:
  `expert` - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current `environment`.
Returns:
  a string grouping one-character separators which separate the structured text into tokens.

### getDirection

public int getDirection(IStructuredTextExpert expert, String text)
Indicates the base text direction appropriate for an instance of structured text. This method is invoked before starting the processing.

If not overridden, this method returns `DIR_LTR`.

Parameters:
  `expert` - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current `environment`.
  `text` - the structured text string to process.
Returns:
  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.
  The value returned is either `DIR_LTR` or `DIR_RTL`.

### getDirection

public int getDirection(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes)
Indicates the base text direction appropriate for an instance of structured text. This method is invoked before starting the processing.

If not overridden, this method returns `DIR_LTR`.

Parameters:
  `expert` - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current `environment`.
  `text` - is the structured text string to process.
  `charTypes` - is a parameter received by `indexOfSpecial` or `processSpecial`.
Returns:
  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.
  The value returned is either `DIR_LTR` or `DIR_RTL`.

### getSpecialsCount

public int getSpecialsCount(IStructuredTextExpert expert)
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, `indexOfSpecial(IStructuredTextExpert, String, StructuredTextCharTypes, StructuredTextOffsets, int, int)` and `processSpecial(IStructuredTextExpert, String, StructuredTextCharTypes, StructuredTextOffsets, int, int)` will not be invoked.

If not overridden, this method returns `zero`.

Parameters:
  `expert` - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current `environment`.
Returns:
  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 `indexOfSpecial(IStructuredTextExpert, String, StructuredTextCharTypes, StructuredTextOffsets, int, int)` and `processSpecial(IStructuredTextExpert, String, StructuredTextCharTypes, StructuredTextOffsets, int, int)`. Examples of special cases are comments, literals, or anything which is not identified by a one-character separator.

### skipProcessing

public boolean skipProcessing(IStructuredTextExpert expert, String text, StructuredTextCharTypes charTypes)
Checks if there is a need for processing structured text. This method is invoked before starting the processing. If the handler returns `true`, no directional formatting characters are added to the lean text and the processing is shortened.

If not overridden, this method returns `false`.

Parameters:
  `expert` - IStructuredTextExpert instance through which this handler is invoked. The handler can use IStructuredTextExpert methods to query items stored in the expert instance, like the current `environment`.
  `text` - is the structured text string to process.
  `charTypes` - is a parameter received by `indexOfSpecial` or `processSpecial`.
Returns:
  a flag indicating if there is no need to process the structured text to add directional formatting characters.

### toString

public String toString()

Overrides:
  `toString` in class `Object`