Package org.daisy.dotify.api.translator

Interface ResolvableText

  • All Superinterfaces:
    FollowingText, PrecedingText
    All Known Subinterfaces:
    Segment
    All Known Implementing Classes:
    AnchorSegment, Evaluate, ExternalReferenceSegment, IdentifierSegment, LeaderSegment, MarkerReferenceSegment, MarkerSegment, NewLineSegment, PageNumberReference, Style, TextSegment
    public interface ResolvableText
extends FollowingText, PrecedingText

    Provides an interface for texts that may change during the translation process. This may for example happen when the resolvable text is a page number reference.

    Note that the value that is translated should always be the value returned by resolve(), because the following translatable may depend on the accurate history of what has already been translated. However, since the correctness of the result may be depending on when resolve() is called, it should not be called prematurely.

    In some cases it is useful to know beforehand if the content might change between calls to peek() or between the last call to peek() and the first call to resolve(). FollowingText.isStatic() makes it possible for an implementation to know if the content could change or not when processing AttributeWithContext on the translatable.

    Note that an implementation must still be able to handle both cases somehow and different strategies may be necessary depending on the circumstances.

    For example, a sequence of two ResolvableText items are translated separately. The first item is a static text containing two words. When the first item is translated the second item is accessible via the FollowingText interface. If the second item is also static it is possible to correctly determine if for example phrase markers (typically requiring at least three words) should be used by counting the words in the two items using resolve() on the first item and peek() on the second. However, if the second item is non-static, an implementation cannot know beforehand what it will return upon its first call to resolve(). If peek() on the second item returns the empty string, a translator implementation might prefer to use word markers for the first item and would consequently be forced to do the same for the second item if it turns out to be non-empty. Conversely, if peek() returns something, an implementation might choose to use phrase markers and run the risk of having to use phrase markers on something that isn't a phrase.

    Obviously, correct information should always be provided if possible, but no degree of similarity can really be guaranteed between peek() and resolve().

    • Method Detail

      • peek

        String peek()
        Peeks the value of this item. The returned string may be different from call to call.

        Note that after a call to resolve(), this method should consistently return the same result.

        Specified by:
        peek in interface FollowingText
        Returns:
        the value, never null

      • resolve

        String resolve()
        Resolves the item. Once the value has been resolved, it cannot change between calls in the same context. This applies to both peek() and resolve().
        Specified by:
        resolve in interface PrecedingText
        Returns:
        the value, never null

      • getLocale

        Optional<String> getLocale()

        Gets the locale for the text, if specified.

        Note that this method returns the language that the text is written in. It does not imply association with a particular translator or braille code.

        Returns:
        an optional containing the locale, never null

      • shouldHyphenate

        boolean shouldHyphenate()
        Returns true if the text should be hyphenated.
        Returns:
        true if the text should be hyphenated, false otherwise

      • shouldMarkCapitalLetters

        boolean shouldMarkCapitalLetters()
        Returns true if the text should mark capital letters.
        Returns:
        true if the capital letters should be marked, false otherwise