1mod 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#[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#[derive(thiserror::Error, Debug)]
99#[non_exhaustive]
100pub enum Error {
101 #[error("{}", table_errors(.0))]
104 Table(Vec<TableError>),
105 #[error(transparent)]
107 Compile(#[from] CompileError),
108}
109
110fn 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#[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 pub fn output(&self) -> &str {
134 &self.output
135 }
136
137 pub fn emphasis(&self) -> Option<&Emphasis> {
141 self.emphasis.as_ref()
142 }
143
144 pub fn output_positions(&self) -> &[usize] {
146 &self.output_positions
147 }
148
149 pub fn input_positions(&self) -> &[usize] {
151 &self.input_positions
152 }
153
154 pub fn cursor_position(&self) -> Option<usize> {
156 self.cursor_position
157 }
158}
159
160#[derive(Debug)]
163pub struct Translator(TranslationPipeline);
164
165impl Translator {
166 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 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 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 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 pub fn emphasis_classes(&self) -> impl Iterator<Item = &str> {
249 self.0.emphasis_classes().iter().map(String::as_str)
250 }
251
252 pub fn translate(&self, input: &str) -> String {
254 self.0.translate(input)
255 }
256
257 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 #[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 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 assert_eq!(
319 emphasis("⠨⠂⠁⠃⠀⠁").spans(),
320 [EmphasisSpan::new("italic", 0..2)]
321 );
322 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 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 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 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 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 assert_eq!(translate("⠁⠃", &TranslationOptions::default()), "about");
405 assert_eq!(translate("⠁⠃", &partial), "ab");
406 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 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 assert_eq!(forward(&no_contractions), "⠁⠃⠀⠃⠉⠀⠉⠁");
439 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 assert_eq!(translate(TranslationMode::CompbrlAtCursor, 5), "⠿⠀⠂⠆⠒⠀⠿");
460 assert_eq!(translate(TranslationMode::CompbrlLeftCursor, 6), "⠿⠀⠂⠆⠉⠀⠿");
462 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 assert_eq!(translator.translate("as"), "⠵");
503 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 assert_eq!(translator.translate("⠠⠠⠗⠁⠆⠊⠞"), "RABBIT");
514 assert_eq!(translator.translate("⠠⠠⠁⠃⠤⠍⠁⠝"), "AB-man");
516 assert_eq!(translator.translate("⠠⠠⠤⠍⠁⠝"), "-MAN");
517 assert_eq!(translator.translate("⠠⠠⠍⠁⠝⠄⠎"), "MAN's");
519 assert_eq!(translator.translate("⠠⠠⠁⠃⠰⠉"), "ABc");
521 }
522
523 #[test]
524 fn a_rule_after_one_of_two_classes_applies_after_either() {
525 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 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}