Skip to main content

Crate louis

Crate louis 

Source
Expand description

Translate text to braille and back.

louis-rs is a re-implementation of liblouis in Rust. It reads liblouis’s tables and passes its test suite, but shares no code with it.

§Status

The API follows semantic versioning: breaking changes come only with a new minor version (0.4 → 0.5), never with a patch release. Items hidden from this documentation are not covered.

§Usage

A Translator compiles a list of tables for one Direction; translating the other way takes a second translator. Translator::new looks the tables up in the directories listed in the LOUIS_TABLE_PATH environment variable, and Translator::with_search_path takes the directories as an argument.

use louis::{Direction, Translator};

let translator = Translator::new(&["en-us-g1.ctb"], Direction::Forward)?;
assert_eq!(translator.translate("hello world"), "⠓⠑⠇⠇⠕⠀⠺⠕⠗⠇⠙");

Translator::from_table_source compiles a table held in memory, which cannot include other tables:

use louis::{Direction, Translator};

let table = "space \\s 0\nlowercase a 1\nlowercase b 12\n";
let forward = Translator::from_table_source(table, Direction::Forward)?;
assert_eq!(forward.translate("ab ba"), "⠁⠃⠀⠃⠁");
let backward = Translator::from_table_source(table, Direction::Backward)?;
assert_eq!(backward.translate("⠁⠃⠀⠃⠁"), "ab ba");

Braille is read and written as Unicode braille. A BrailleEncoding writes the cells as other characters instead, such as ASCII braille. It is loaded from a liblouis display table (.dis):

use louis::{BrailleEncoding, Direction, Translator};

let brf = BrailleEncoding::new("en-us-brf.dis")?;
let translator =
    Translator::new(&["en-us-g2.ctb"], Direction::Forward)?.with_braille_encoding(&brf);
assert_eq!(translator.translate("the"), "!");

Translator::translate_with_options also maps positions between input and output, and metadata finds tables by their metadata instead of their file name.

Modules§

metadata
Find tables by the #+key: value metadata they carry, instead of by file name.

Structs§

BrailleEncoding
Which characters stand for the braille cells, such as ASCII braille or a national encoding. Without one, braille is read and written as Unicode braille (U+2800 to U+28FF).
CompileError
An error in compiling the rules of a table.
Emphasis
The emphasis of a text: which EmphasisSpans it has, liblouis’s typeform.
EmphasisSpan
An emphasis class active over a contiguous range of characters.
SyntaxError
What is wrong with a line of a table, or with a hyphenation table. Its message says what; the details are not public API, as they follow the parser’s internals.
TranslationModes
A set of TranslationModes.
TranslationOptions
Per-call options for a translation.
TranslationResult
The result of Translator::translate_with_options.
Translator
Translates text to braille (Direction::Forward) or braille to text (Direction::Backward) with a set of compiled tables.

Enums§

CompileErrorKind
What is wrong with a rule that failed to compile, see CompileError.
Direction
Which way a translation goes: from text to braille, or from braille back to text.
Error
Why a Translator could not be built.
TableError
An error that occurred during reading of a liblouis braille table
TranslationMode
Flags that modify the behaviour of the translator.