Skip to main content

louis/
lib.rs

1/*! Translate text to braille and back.
2
3louis-rs is a re-implementation of [liblouis](https://liblouis.io) in Rust. It reads
4liblouis's tables and passes its test suite, but shares no code with it.
5
6## Status
7
8The API follows semantic versioning: breaking changes come only with a new minor
9version (0.4 → 0.5), never with a patch release. Items hidden from this documentation
10are not covered.
11
12## Usage
13
14A [`Translator`] compiles a list of tables for one [`Direction`]; translating the other
15way takes a second translator. [`Translator::new`] looks the tables up in the
16directories listed in the `LOUIS_TABLE_PATH` environment variable, and
17[`Translator::with_search_path`] takes the directories as an argument.
18
19```no_run
20use louis::{Direction, Translator};
21
22let translator = Translator::new(&["en-us-g1.ctb"], Direction::Forward)?;
23assert_eq!(translator.translate("hello world"), "⠓⠑⠇⠇⠕⠀⠺⠕⠗⠇⠙");
24# Ok::<(), louis::Error>(())
25```
26
27[`Translator::from_table_source`] compiles a table held in memory, which cannot
28include other tables:
29
30```
31use louis::{Direction, Translator};
32
33let table = "space \\s 0\nlowercase a 1\nlowercase b 12\n";
34let forward = Translator::from_table_source(table, Direction::Forward)?;
35assert_eq!(forward.translate("ab ba"), "⠁⠃⠀⠃⠁");
36let backward = Translator::from_table_source(table, Direction::Backward)?;
37assert_eq!(backward.translate("⠁⠃⠀⠃⠁"), "ab ba");
38# Ok::<(), louis::Error>(())
39```
40
41Braille is read and written as Unicode braille. A [`BrailleEncoding`] writes the cells
42as other characters instead, such as ASCII braille. It is loaded from a liblouis display
43table (`.dis`):
44
45```no_run
46use louis::{BrailleEncoding, Direction, Translator};
47
48let brf = BrailleEncoding::new("en-us-brf.dis")?;
49let translator =
50    Translator::new(&["en-us-g2.ctb"], Direction::Forward)?.with_braille_encoding(&brf);
51assert_eq!(translator.translate("the"), "!");
52# Ok::<(), louis::Error>(())
53```
54
55[`Translator::translate_with_options`] also maps positions between input and output,
56and [`metadata`] finds tables by their metadata instead of their file name.
57
58*/
59
60mod braille_encoding;
61mod emphasis;
62mod hyphenation;
63pub mod metadata;
64mod parser;
65mod translator;
66
67use std::path::{Path, PathBuf};
68
69pub use braille_encoding::BrailleEncoding;
70pub use emphasis::{Emphasis, EmphasisSpan};
71pub use parser::{Direction, SyntaxError, TableError};
72use search_path::SearchPath;
73use translator::TranslationPipeline;
74pub use translator::{
75    CompileError, CompileErrorKind, TranslationMode, TranslationModes, TranslationOptions,
76};
77
78/// What the `louis` command line tool needs beyond the public API: rule tracing for `trace`,
79/// and the pipeline and display tables for `check-table` and the YAML test harness.
80/// Not part of the public API and not covered by semver; it changes whenever the CLI does.
81#[doc(hidden)]
82pub mod internals {
83    pub mod parser {
84        pub use crate::parser::{
85            AnchoredRule, Direction, EscapingContext, ParseError, TableError, expand_includes,
86            table, table_expanded_in, unescape,
87        };
88    }
89    pub mod translator {
90        pub use crate::translator::{
91            CompileError, DisplayTable, PositionMap, ResolvedTranslation, TranslationMode,
92            TranslationModes, TranslationOptions, TranslationPipeline, TranslationStage,
93        };
94    }
95}
96
97/// Why a [`Translator`] could not be built.
98#[derive(thiserror::Error, Debug)]
99#[non_exhaustive]
100pub enum Error {
101    /// The tables could not be read: each error names its table and, for a syntax error,
102    /// its line.
103    #[error("{}", table_errors(.0))]
104    Table(Vec<TableError>),
105    /// The tables were read, but a rule refers to something that no rule defines.
106    #[error(transparent)]
107    Compile(#[from] CompileError),
108}
109
110/// The first of `errors`, and how many more there are
111fn table_errors(errors: &[TableError]) -> String {
112    match errors {
113        [] => "cannot read the tables".to_string(),
114        [error] => error.to_string(),
115        [error, rest @ ..] => format!("{error} (and {} more)", rest.len()),
116    }
117}
118
119/// The result of [`Translator::translate_with_options`].
120///
121/// All positions are indices of characters (Unicode scalar values), not of bytes.
122#[derive(Debug, Default, Clone, PartialEq, Eq)]
123pub struct TranslationResult {
124    output: String,
125    emphasis: Option<Emphasis>,
126    output_positions: Vec<usize>,
127    input_positions: Vec<usize>,
128    cursor_position: Option<usize>,
129}
130
131impl TranslationResult {
132    /// The translated text.
133    pub fn output(&self) -> &str {
134        &self.output
135    }
136
137    /// Backward, the emphasis of the output, as the braille's emphasis indicators give it:
138    /// the typeform of a back-translation. Forward, where the emphasis is given with the
139    /// input, always `None`.
140    pub fn emphasis(&self) -> Option<&Emphasis> {
141        self.emphasis.as_ref()
142    }
143
144    /// For each input character, the position of its translation in the output.
145    pub fn output_positions(&self) -> &[usize] {
146        &self.output_positions
147    }
148
149    /// For each output character, the position of the input it was translated from.
150    pub fn input_positions(&self) -> &[usize] {
151        &self.input_positions
152    }
153
154    /// The cursor position given in the options, mapped to the output.
155    pub fn cursor_position(&self) -> Option<usize> {
156        self.cursor_position
157    }
158}
159
160/// Translates text to braille ([`Direction::Forward`]) or braille to text
161/// ([`Direction::Backward`]) with a set of compiled tables.
162#[derive(Debug)]
163pub struct Translator(TranslationPipeline);
164
165impl Translator {
166    /// Compile `tables` for translating in `direction`.
167    ///
168    /// Tables are looked up in the `LOUIS_TABLE_PATH` search path. Use
169    /// [`Self::with_search_path`] to supply the directories instead, which a host
170    /// application managing its own table locations will want.
171    ///
172    /// # Errors
173    ///
174    /// [`Error::Table`] if a table or one it includes cannot be found, read or parsed, and
175    /// [`Error::Compile`] if the rules cannot be compiled.
176    pub fn new<P: AsRef<Path>>(tables: &[P], direction: Direction) -> Result<Self, Error> {
177        Self::compile_tables(
178            tables,
179            direction,
180            &SearchPath::new_or("LOUIS_TABLE_PATH", "."),
181        )
182    }
183
184    /// Like [`Self::new`], but looking tables up in `search_path` instead of reading the
185    /// `LOUIS_TABLE_PATH` environment variable.
186    ///
187    /// # Errors
188    ///
189    /// As for [`Self::new`].
190    pub fn with_search_path<P: AsRef<Path>>(
191        tables: &[P],
192        direction: Direction,
193        search_path: impl IntoIterator<Item = impl Into<PathBuf>>,
194    ) -> Result<Self, Error> {
195        let search_path: Vec<PathBuf> = search_path.into_iter().map(Into::into).collect();
196        Self::compile_tables(tables, direction, &SearchPath::from(search_path))
197    }
198
199    fn compile_tables<P: AsRef<Path>>(
200        tables: &[P],
201        direction: Direction,
202        search_path: &SearchPath,
203    ) -> Result<Self, Error> {
204        let mut all_rules = Vec::new();
205
206        for table_path in tables {
207            let path = table_path.as_ref();
208            let rules = parser::table_expanded_in(path, search_path).map_err(Error::Table)?;
209            all_rules.extend(rules);
210        }
211
212        Ok(Self(TranslationPipeline::compile(&all_rules, direction)?))
213    }
214
215    /// Build a translator from raw liblouis table source held in memory.
216    ///
217    /// This parses only the inline table text. Unlike [`Self::new`], it does
218    /// not resolve `include` directives from the filesystem.
219    ///
220    /// # Errors
221    ///
222    /// [`Error::Table`] if the source cannot be parsed or contains an `include`, and
223    /// [`Error::Compile`] if the rules cannot be compiled.
224    pub fn from_table_source(table: &str, direction: Direction) -> Result<Self, Error> {
225        let rules = parser::table(table, None).map_err(Error::Table)?;
226        if rules
227            .iter()
228            .any(|rule| matches!(rule.rule, parser::Rule::Include { .. }))
229        {
230            return Err(Error::Table(vec![TableError::IncludesNotSupportedInMemory]));
231        }
232
233        Ok(Self(TranslationPipeline::compile(&rules, direction)?))
234    }
235
236    /// Read and write braille in `encoding` rather than as Unicode braille. An encoding
237    /// given before is replaced.
238    ///
239    /// This is what liblouis does with the display table at the start of a table list;
240    /// louis-rs takes it explicitly instead.
241    pub fn with_braille_encoding(self, encoding: &BrailleEncoding) -> Self {
242        let direction = self.0.direction();
243        Self(self.0.with_display(encoding.compile(direction)))
244    }
245
246    /// The emphasis classes the tables declare with `emphclass`, such as `italic` or
247    /// `bold`, in the order they declare them: the classes an [`EmphasisSpan`] can name.
248    pub fn emphasis_classes(&self) -> impl Iterator<Item = &str> {
249        self.0.emphasis_classes().iter().map(String::as_str)
250    }
251
252    /// Translate `input`.
253    pub fn translate(&self, input: &str) -> String {
254        self.0.translate(input)
255    }
256
257    /// Translate `input` with `options`, and say which input became which output.
258    pub fn translate_with_options(
259        &self,
260        input: &str,
261        options: &TranslationOptions,
262    ) -> TranslationResult {
263        let (output, positions, emphasis) = self.0.translate_with_details(input, options);
264        let cursor_position = options
265            .cursor_position()
266            .map(|cursor| positions.cursor(cursor));
267        let (output_positions, input_positions) = positions.into_parts();
268        TranslationResult {
269            output,
270            output_positions,
271            input_positions,
272            cursor_position,
273            emphasis,
274        }
275    }
276}
277
278#[cfg(test)]
279mod tests {
280    use super::*;
281
282    // a translator is meant to be shared between threads
283    #[test]
284    fn translator_is_send_and_sync() {
285        fn assert_send_sync<T: Send + Sync>() {}
286        assert_send_sync::<Translator>();
287    }
288
289    #[test]
290    fn translator_from_table_source() {
291        let table = "space \\s 0\nletter a 1\nletter b 12\n";
292        let translator = Translator::from_table_source(table, Direction::Forward).unwrap();
293        assert_eq!(translator.translate("ab"), "⠁⠃");
294    }
295
296    #[test]
297    fn back_translation_returns_the_emphasis() {
298        let table = "space \\s 0\nlowercase a 1\nlowercase b 12\nemphclass italic\n\
299                     emphletter italic 46-23\nbegemphword italic 46-2\nendemphword italic 46-3\n";
300        let translator = Translator::from_table_source(table, Direction::Backward).unwrap();
301        let emphasis = |braille| {
302            translator
303                .translate_with_options(braille, &TranslationOptions::default())
304                .emphasis()
305                .unwrap()
306                .clone()
307        };
308        // a letter, then a word up to its end indicator
309        assert_eq!(
310            emphasis("⠨⠆⠁⠃").spans(),
311            [EmphasisSpan::new("italic", 0..1)]
312        );
313        assert_eq!(
314            emphasis("⠃⠀⠨⠂⠁⠃⠨⠄⠁").spans(),
315            [EmphasisSpan::new("italic", 2..4)]
316        );
317        // a word without an end indicator ends at the space
318        assert_eq!(
319            emphasis("⠨⠂⠁⠃⠀⠁").spans(),
320            [EmphasisSpan::new("italic", 0..2)]
321        );
322        // forward, the emphasis comes with the input
323        let forward = Translator::from_table_source(table, Direction::Forward).unwrap();
324        assert!(
325            forward
326                .translate_with_options("ab", &TranslationOptions::default())
327                .emphasis()
328                .is_none()
329        );
330    }
331
332    #[test]
333    fn a_base_character_must_be_defined_in_some_direction() {
334        let error =
335            Translator::from_table_source("base uppercase A a", Direction::Forward).unwrap_err();
336        let Error::Compile(error) = error else {
337            panic!("expected a compile error, got {error:?}");
338        };
339        assert_eq!(
340            *error.kind(),
341            CompileErrorKind::BaseCharacterNotDefined {
342                base: 'a',
343                derived: 'A'
344            }
345        );
346        // table source in memory has no path, and the rule is on the first line
347        assert_eq!((error.path(), error.line()), (None, 1));
348        assert_eq!(
349            error.to_string(),
350            "line 1: base character 'a' of 'A' not defined"
351        );
352        // defined forward only: backward there is nothing to derive, which is fine
353        let table = "noback lowercase a 1\nbase uppercase A a\n";
354        for direction in [Direction::Forward, Direction::Backward] {
355            assert!(Translator::from_table_source(table, direction).is_ok());
356        }
357    }
358
359    #[test]
360    fn a_braille_encoding_writes_the_cells_both_ways() {
361        let table = "space \\s 0\nlowercase a 1\nlowercase b 12\n";
362        let encoding = BrailleEncoding::from_table_source("display a 1\ndisplay b 12\n").unwrap();
363        let forward = Translator::from_table_source(table, Direction::Forward)
364            .unwrap()
365            .with_braille_encoding(&encoding);
366        assert_eq!(forward.translate("ab ba"), "ab⠀ba");
367        let backward = Translator::from_table_source(table, Direction::Backward)
368            .unwrap()
369            .with_braille_encoding(&encoding);
370        assert_eq!(backward.translate("ab⠀ba"), "ab ba");
371        // a second encoding replaces the first, in either direction
372        let other = BrailleEncoding::from_table_source("display x 1\ndisplay y 12\n").unwrap();
373        assert_eq!(forward.with_braille_encoding(&other).translate("ab"), "xy");
374        assert_eq!(backward.with_braille_encoding(&other).translate("xy"), "ab");
375        // and without one, Unicode braille
376        let plain = Translator::from_table_source(table, Direction::Forward).unwrap();
377        assert_eq!(plain.translate("ab"), "⠁⠃");
378    }
379
380    #[test]
381    fn a_translator_lists_its_emphasis_classes() {
382        let table = "emphclass italic\nemphclass bold\nemphclass italic\nletter a 1\n";
383        let translator = Translator::from_table_source(table, Direction::Forward).unwrap();
384        assert_eq!(
385            translator.emphasis_classes().collect::<Vec<_>>(),
386            ["italic", "bold"]
387        );
388    }
389
390    #[test]
391    fn partial_input_has_no_word_end() {
392        let table = "space \\s 0\nlowercase a 1\nlowercase b 12\nlowercase y 13456\n\
393                     word about 1-12\njoinword by 356\n";
394        let translator = Translator::from_table_source(table, Direction::Backward).unwrap();
395        let partial = TranslationOptions::default()
396            .with_modes([TranslationMode::PartialTrans].into_iter().collect());
397        let translate = |braille, options: &TranslationOptions| {
398            translator
399                .translate_with_options(braille, options)
400                .output()
401                .to_string()
402        };
403        // the input could still become a longer word, so `word about` doesn't apply
404        assert_eq!(translate("⠁⠃", &TranslationOptions::default()), "about");
405        assert_eq!(translate("⠁⠃", &partial), "ab");
406        // a `joinword` applies, and puts its space back only once a word follows
407        assert_eq!(translate("⠴", &partial), "by");
408        assert_eq!(translate("⠴⠁", &partial), "by a");
409    }
410
411    #[test]
412    fn a_definition_after_a_base_rule_gives_the_dots() {
413        // nl-NL-g0.utb: a capital is its letter with a virtual dot, after a shared
414        // `base uppercase`; the `base` rule still makes it a capital
415        let table = "space \\s 0\nlowercase a 1\nlowercase v 1236\ncapsletter 46\n\
416                     base uppercase V v\nnoback letter V 12367\n";
417        let translator = Translator::from_table_source(table, Direction::Forward).unwrap();
418        assert_eq!(translator.translate("Va"), "⠨⡧⠁");
419    }
420
421    #[test]
422    fn no_contractions_spells_everything_out() {
423        let table = "space \\s 0\nlowercase a 1\nlowercase b 12\nlowercase c 14\n\
424                     word ab 1246\nalways bc 123456\nmatch - ca - 25\n";
425        let no_contractions = TranslationOptions::default()
426            .with_modes([TranslationMode::NoContractions].into_iter().collect());
427        let translate = |direction, input, options: &TranslationOptions| {
428            Translator::from_table_source(table, direction)
429                .unwrap()
430                .translate_with_options(input, options)
431                .output()
432                .to_string()
433        };
434        let forward =
435            |options: &TranslationOptions| translate(Direction::Forward, "ab bc ca", options);
436        assert_eq!(forward(&TranslationOptions::default()), "⠫⠀⠿⠀⠒");
437        // no `word`, `always` or `match` contraction
438        assert_eq!(forward(&no_contractions), "⠁⠃⠀⠃⠉⠀⠉⠁");
439        // liblouis ignores it backward
440        assert_eq!(translate(Direction::Backward, "⠫", &no_contractions), "ab");
441    }
442
443    #[test]
444    fn the_word_at_the_cursor_is_computer_braille() {
445        let table = "space \\s 0\nlowercase a 1\nlowercase b 12\nlowercase c 14\n\
446                     always abc 123456\ncomp6 a 2\ncomp6 b 23\ncomp6 c 25\n\
447                     begcomp 456-346\nendcomp 456-156\n";
448        let translator = Translator::from_table_source(table, Direction::Forward).unwrap();
449        let translate = |mode, cursor| {
450            let options = TranslationOptions::default()
451                .with_modes([mode].into_iter().collect())
452                .with_cursor_position(cursor);
453            translator
454                .translate_with_options("abc abc abc", &options)
455                .output()
456                .to_string()
457        };
458        // the whole word at the cursor, without begcomp and endcomp
459        assert_eq!(translate(TranslationMode::CompbrlAtCursor, 5), "⠿⠀⠂⠆⠒⠀⠿");
460        // only up to the cursor
461        assert_eq!(translate(TranslationMode::CompbrlLeftCursor, 6), "⠿⠀⠂⠆⠉⠀⠿");
462        // without the mode, the cursor changes nothing
463        assert_eq!(translate(TranslationMode::NoUndefined, 5), "⠿⠀⠿⠀⠿");
464    }
465
466    #[test]
467    fn a_table_error_says_what_and_where() {
468        let error =
469            Translator::from_table_source("letter a 1\nfoo b 2\nbar c 3\n", Direction::Forward)
470                .unwrap_err();
471        assert_eq!(
472            error.to_string(),
473            "line 2: opcode expected, got Some(\"foo\") (and 1 more)"
474        );
475    }
476
477    #[test]
478    fn translator_from_table_source_rejects_include() {
479        let error =
480            Translator::from_table_source("include en-us-g1.ctb", Direction::Forward).unwrap_err();
481        match error {
482            Error::Table(errors) => {
483                assert!(matches!(
484                    errors.as_slice(),
485                    [TableError::IncludesNotSupportedInMemory]
486                ));
487            }
488            other => panic!("unexpected error: {other:?}"),
489        }
490    }
491
492    const NUMBER_TABLE: &str =
493        "space \\s 0\nletter a 1\nlitdigit 4 145\nlitdigit 2 12\nnumsign 3456\n";
494
495    const CAPS_WORD_TABLE: &str = "space \\s 0\nlowercase a 1\nlowercase b 12\nlowercase c 14\nlowercase i 24\nlowercase m 134\nlowercase n 1345\nlowercase r 1235\nlowercase s 234\nlowercase t 2345\nbase uppercase A a\nbase uppercase B b\nbase uppercase C c\nbase uppercase I i\nbase uppercase M m\nbase uppercase N n\nbase uppercase R r\nbase uppercase S s\nbase uppercase T t\npunctuation ; 23\npunctuation - 36\npunctuation ' 3\nletsign 56\nbegcapsword 6-6\nendcapsword 56\nmidword bb 23\nalways 's 3-234\n";
496
497    #[test]
498    fn a_contraction_gets_its_letter_sign_only_where_it_applies() {
499        let table = "space \\s 0\nlowercase a 1\nlowercase b 12\nlowercase s 234\nbase uppercase A a\nletsign 56\ncapsletter 6\nword as 1356\ncontraction as\ncontraction ab\n";
500        let translator = Translator::from_table_source(table, Direction::Forward).unwrap();
501        // the earlier `word as` applies, so no letter sign
502        assert_eq!(translator.translate("as"), "⠵");
503        // the contraction applies, its letter sign before the capital
504        assert_eq!(translator.translate("ab"), "⠰⠁⠃");
505        assert_eq!(translator.translate("Ab"), "⠰⠠⠁⠃");
506    }
507
508    #[test]
509    fn a_capitalized_word_goes_on_while_letters_are_written() {
510        let translator =
511            Translator::from_table_source(CAPS_WORD_TABLE, Direction::Backward).unwrap();
512        // whatever rule writes them: ⠆ is the semicolon and the contraction "bb"
513        assert_eq!(translator.translate("⠠⠠⠗⠁⠆⠊⠞"), "RABBIT");
514        // a hyphen after a letter ends the word, but not one before the first letter
515        assert_eq!(translator.translate("⠠⠠⠁⠃⠤⠍⠁⠝"), "AB-man");
516        assert_eq!(translator.translate("⠠⠠⠤⠍⠁⠝"), "-MAN");
517        // it can end partway through what a rule writes
518        assert_eq!(translator.translate("⠠⠠⠍⠁⠝⠄⠎"), "MAN's");
519        // after a letter, ⠰ is `endcapsword`, not `letsign`
520        assert_eq!(translator.translate("⠠⠠⠁⠃⠰⠉"), "ABc");
521    }
522
523    #[test]
524    fn a_rule_after_one_of_two_classes_applies_after_either() {
525        // French `after conabr after bvoy endword ent 126`
526        let table = "space \\s 0\nlowercase a 1\nlowercase b 12\nlowercase c 14\nlowercase x 1346\nattribute one a\nattribute two b\nafter one after two always yy 1346\n";
527        let translator = Translator::from_table_source(table, Direction::Backward).unwrap();
528        assert_eq!(translator.translate("⠁⠭⠀⠃⠭⠀⠉⠭"), "ayy byy cx");
529    }
530
531    #[test]
532    fn digits_after_a_number_sign_are_not_read_as_a_contraction() {
533        let table = "space \\s 0\nletter a 1\nletter b 12\nlitdigit 1 1\nlitdigit 2 12\nnumsign 3456\nword about 1-12\n";
534        let translator = Translator::from_table_source(table, Direction::Backward).unwrap();
535        assert_eq!(translator.translate("⠼⠁⠃⠀⠁⠃"), "12 about");
536    }
537
538    #[test]
539    fn positions_with_number_sign() {
540        let translator = Translator::from_table_source(NUMBER_TABLE, Direction::Forward).unwrap();
541        let result = translator.translate_with_options(
542            "a 42",
543            &TranslationOptions::default().with_cursor_position(2),
544        );
545        assert_eq!(result.output(), "⠁⠀⠼⠙⠃");
546        assert_eq!(result.output_positions(), [0, 1, 2, 4]);
547        assert_eq!(result.input_positions(), [0, 1, 2, 2, 3]);
548        assert_eq!(result.cursor_position(), Some(2));
549    }
550
551    #[test]
552    fn cursor_past_the_end_maps_to_the_output_length() {
553        let translator = Translator::from_table_source(NUMBER_TABLE, Direction::Forward).unwrap();
554        let result = translator.translate_with_options(
555            "a 42",
556            &TranslationOptions::default().with_cursor_position(4),
557        );
558        assert_eq!(result.cursor_position(), Some(5));
559    }
560
561    #[test]
562    fn positions_without_cursor() {
563        let translator = Translator::from_table_source(NUMBER_TABLE, Direction::Forward).unwrap();
564        let result = translator.translate_with_options("a 42", &TranslationOptions::default());
565        assert_eq!(result.output(), translator.translate("a 42"));
566        assert_eq!(result.cursor_position(), None);
567    }
568
569    #[test]
570    fn positions_with_capital_sign() {
571        let table = "lowercase h 125\nlowercase i 24\nbase uppercase H h\ncapsletter 6\n";
572        let forward = Translator::from_table_source(table, Direction::Forward).unwrap();
573        let result = forward
574            .translate_with_options("Hi", &TranslationOptions::default().with_cursor_position(0));
575        assert_eq!(result.output(), "⠠⠓⠊");
576        assert_eq!(result.output_positions(), [0, 2]);
577        assert_eq!(result.input_positions(), [0, 0, 1]);
578        assert_eq!(result.cursor_position(), Some(0));
579
580        let backward = Translator::from_table_source(table, Direction::Backward).unwrap();
581        let result = backward.translate_with_options("⠠⠓⠊", &TranslationOptions::default());
582        assert_eq!(result.output(), "Hi");
583        assert_eq!(result.output_positions(), [0, 0, 1]);
584        // backward, a consumed cell is claimed by the character that follows it, so the "H"
585        // covers the capital sign as well ("prepend to next", as liblouis calls it)
586        assert_eq!(result.input_positions(), [0, 2]);
587    }
588
589    #[test]
590    fn positions_with_correction_insertion() {
591        let table = "letter f 124\nletter o 135\nletter b 12\nletter a 1\nletter r 1235\npunctuation , 6\npunctuation - 36\nnoback correct \"f,\"[]\"o\" \"-\"\n";
592        let translator = Translator::from_table_source(table, Direction::Forward).unwrap();
593        let result = translator.translate_with_options("f,oobar", &TranslationOptions::default());
594        assert_eq!(result.output(), "⠋⠠⠤⠕⠕⠃⠁⠗");
595        assert_eq!(result.output_positions(), [0, 1, 2, 4, 5, 6, 7]);
596        assert_eq!(result.input_positions(), [0, 1, 2, 2, 3, 4, 5, 6]);
597    }
598
599    #[test]
600    fn positions_with_pass2_deletion() {
601        let table = "letter f 124\nletter o 135\nletter x 1346\nnoback pass2 @1346 ?\n";
602        let translator = Translator::from_table_source(table, Direction::Forward).unwrap();
603        let result = translator.translate_with_options("xfoo", &TranslationOptions::default());
604        assert_eq!(result.output(), "⠋⠕⠕");
605        assert_eq!(result.output_positions(), [0, 0, 1, 2]);
606        assert_eq!(result.input_positions(), [1, 2, 3]);
607    }
608}