org.daisy.pipeline.braille.common.Hyphenator Maven / Gradle / Ivy

Go to download
package org.daisy.pipeline.braille.common;

import java.util.Collections;
import java.util.Locale;

import org.daisy.braille.css.SimpleInlineStyle;
import org.daisy.pipeline.braille.css.CSSStyledText;

/**
 * Hyphenation means morphological breaking within words. However this class is
 * not only responsible for providing hyphenation opportunities, but all soft wrap
 * opportunities (including but not restricted to those defined by the Unicode line
 * breaking rules [UAX14]).
 */
public interface Hyphenator extends Transform {
	
	/**
	 * Indicate all soft wrap opportunities by inserting soft hyphens and zero width
	 * spaces. Don't add new soft wrap opportunities to words that already have a soft
	 * hyphen or zero width space in them. Soft wrap opportunities at white space may also
	 * be omitted. Apart from the insertion of these special characters no other
	 * transformations are allowed. This means that non-standard hyphenation can not be
	 * supported through this interface.
	 */
	public FullHyphenator asFullHyphenator() throws UnsupportedOperationException;
	
	/**
	 * Break the input into lines of a preferred and maximal length. Transformations such
	 * as non-standard hyphenation are allowed.
	 *
	 * A {@link LineBreaker} is not required to do any special white space processing, but
	 * it may.
	 *
	 * If the {@link FullHyphenator} returned by {@link #asFullHyphenator()} throws a {@link
	 * NonStandardHyphenationException}, the {@link #asLineBreaker()} method must not throw a {@link
	 * UnsupportedOperationException}.
	 */
	public LineBreaker asLineBreaker() throws UnsupportedOperationException;
	
	/* ------------------ */
	/* asFullHyphenator() */
	/* ------------------ */
	
	public interface FullHyphenator {
		
		public Iterable transform(Iterable text) throws NonStandardHyphenationException;
		
		/**
		 * This method is intended to be overridden with a more optimal implementation.
		 */
		public default String transform(String text, SimpleInlineStyle style, Locale language)
				throws NonStandardHyphenationException {
			return transform(Collections.singleton(new CSSStyledText(text, style, language)))
			       .iterator().next().getText();
		}
	}
	
	/* --------------- */
	/* asLineBreaker() */
	/* --------------- */
	
	public interface LineBreaker {
		
		public LineIterator transform(String input, Locale language);
		
	}
	
	/**
	 * Thrown by {@link FullHyphenator} if non-standard breaks are present.
	 */
	@SuppressWarnings("serial")
	public class NonStandardHyphenationException extends RuntimeException {

		public NonStandardHyphenationException() {
			super();
		}

		public NonStandardHyphenationException(Throwable cause) {
			super(cause);
		}
	}

	/* ------------ */
	/* LineIterator */
	/* ------------ */
	
	public interface LineIterator {
		
		/**
		 * Returns true if there is remaining text to make a new line of.
		 */
		public boolean hasNext();
		
		/**
		 * Get the next line of text, with a length as close as possible to, but not
		 * exceding `limit` characters, breaking a word if needed. The line does not
		 * include a possible hyphen character (see {@link lineHasHyphen()}). `limit` must
		 * be greater than 0. If `force` is true, may not return an empty string. If
		 * `allowHyphens` is false, breaking words is not permitted unless `force` is true
		 * and an empty string would otherwise be returned. Must throw an exception if
		 * there is no remaining text to make a new line of.
		 */
		public String nextLine(int limit, boolean force, boolean allowHyphens);
		public String nextLine(int limit, boolean force);
		
		/**
		 * Whether or not a hyphen character should be inserted at the end of
		 * the current line to indicate a word break. Must throw an exception
		 * if `nextLine` hasn't been called yet.
		 */
		public boolean lineHasHyphen();
		
		public String remainder();
		
		/**
		 * Set a checkpoint to which the iterator can be `reset` later.
		 */
		public void mark();
		
		/**
		 * Roll back to a checkpoint previously set with `mark`, or to the
		 * beginning if `mark` hasn't been called yet.
		 */
		public void reset();
		
	}
}