1   package org.daisy.pipeline.braille.common;
2   
3   import java.util.Collections;
4   import java.util.Map;
5   
6   import org.daisy.dotify.api.translator.BrailleTranslatorResult;
7   import org.daisy.pipeline.braille.css.CSSStyledText;
8   
9   public interface BrailleTranslator extends Transform {
10  
11  	/**
12  	 * Get info about the braille translator. E.g. for a Liblouis implementation, this will contain
13  	 * table metadata.
14  	 */
15  	public default Map<String,String> getInfo() {
16  		return Collections.emptyMap();
17  	}
18  
19  	/**
20  	 * Return a new {@link BrailleTranslator} that uses the given {@link Hyphenator} to perform
21  	 * hyphenation.
22  	 *
23  	 * The returned object should be selectable based on its identifier from the same {@link
24  	 * BrailleTranslatorProvider} that provided this {@link BrailleTranslator}.
25  	 */
26  	public BrailleTranslator withHyphenator(Hyphenator hyphenator) throws UnsupportedOperationException;
27  	
28  	public FromStyledTextToBraille fromStyledTextToBraille() throws UnsupportedOperationException;
29  	
30  	public LineBreakingFromStyledText lineBreakingFromStyledText() throws UnsupportedOperationException;
31  	
32  	/* ------------------------- */
33  	/* fromStyledTextToBraille() */
34  	/* ------------------------- */
35  	
36  	public interface FromStyledTextToBraille {
37  		
38  		/**
39  		 * Transform a sequence of {@link CSSStyledText} to braille.
40  		 *
41  		 * @param styledText The {@link CSSStyledText} must not be modified.
42  		 * @return a new sequence of {@link CSSStyledText} that contain the braille and the
43  		 *         unprocessed or new styles. Styles must be new objects.
44  		 */
45  		default public Iterable<CSSStyledText> transform(Iterable<CSSStyledText> styledText) throws TransformationException {
46  			return transform(styledText, 0, -1);
47  		}
48  		
49  		/**
50  		 * Transform the part of the input sequence between index <code>from</code> (included) and
51  		 * index <code>to</code> (not included). If <code>to</code> is a negative number it means
52  		 * transform up until the last segment.
53  		 */
54  		public Iterable<CSSStyledText> transform(Iterable<CSSStyledText> styledText, int from, int to) throws TransformationException;
55  	}
56  	
57  	/* ---------------------------- */
58  	/* lineBreakingFromStyledText() */
59  	/* ---------------------------- */
60  	
61  	public interface LineBreakingFromStyledText {
62  		
63  		/**
64  		 * Transform a sequence of {@link CSSStyledText} to braille, in the form of a {@link
65  		 * LineIterator}, which is an interface for laying out text into lines.
66  		 *
67  		 * @param styledText The {@link CSSStyledText} must not be modified.
68  		 */
69  		default public LineIterator transform(Iterable<CSSStyledText> styledText) throws TransformationException {
70  			return transform(styledText, 0, -1);
71  		}
72  		
73  		/**
74  		 * Transform the part of the input sequence between index <code>from</code> (included) and
75  		 * index <code>to</code> (not included). If <code>to</code> is a negative number it means
76  		 * transform up until the last segment.
77  		 */
78  		public LineIterator transform(Iterable<CSSStyledText> styledTextWithContext, int from, int to) throws TransformationException;
79  	}
80  	
81  	/* ------------ */
82  	/* LineIterator */
83  	/* ------------ */
84  	
85  	public interface LineIterator extends BrailleTranslatorResult {
86  	}
87  	
88  }