libmathcat/
lib.rs

1#![cfg_attr(coverage, feature(coverage_attribute))]
2#![allow(clippy::needless_return)]
3#![allow(clippy::needless_option_as_deref)]
4
5//! A library for generating speech and braille from MathML
6//! 
7//! Typical usage is:
8//! 1. Set the rules directory [`set_rules_dir`]
9//! 2. Set whatever preferences are need with repeated calls to [`set_preference`].
10//! 3. Set MathML via [`set_mathml`]
11//!    A string representing the cleaned up MathML along with `id`s on each node is returned for highlighting if desired
12//! 4. Get the speech [`get_spoken_text`] or (Unicode) braille [`get_braille`].
13//!
14//! The expression can be navigated also.
15//! This is done in one of two ways:
16//! 1. Pass key strokes to allow a user to navigate the MathML by calling [`do_navigate_keypress`]; the speech is returned.
17//! 2. Pass the MathCAT navigation command directory by called [`do_navigate_command`]; the speech is return returned.
18//! 
19//! To get the MathML associated with the current navigation node, call [`get_navigation_mathml`].
20//! To just get the `id` and offset from the id of the current navigation node, call [`get_navigation_mathml_id`].
21///
22/// This module re-exports anyhow types. Use `bail!` for early returns and
23/// `context()`/`with_context()` on Result to add context (replacing old `chain_err()`).
24pub mod errors {
25    pub use anyhow::{anyhow, bail, Error, Result, Context};
26}
27
28pub mod interface;
29#[cfg(feature = "include-zip")]
30pub use shim_filesystem::ZIPPED_RULE_FILES;
31
32mod canonicalize;
33mod infer_intent;
34pub mod speech;
35mod braille;
36mod navigate;
37mod prefs;
38mod tts;
39mod xpath_functions;
40mod definitions;
41pub mod pretty_print;
42mod chemistry;
43
44pub mod shim_filesystem; // really just for override_file_for_debugging_rules, but the config seems to throw it off
45pub use interface::*;
46use crate::errors::{bail, Result};
47
48#[cfg(test)]
49pub fn init_logger() {
50    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("debug"))
51        .is_test(true)
52        .format_timestamp(None)
53        .format_module_path(false)
54        .format_indent(None)
55        .format_level(false)
56        .init();
57}
58
59/// Build Absolute path to rules dir for testing
60pub fn abs_rules_dir_path() -> String {
61    cfg_if::cfg_if! {
62    if #[cfg(feature = "include-zip")] {
63          return "Rules".to_string();
64    } else {
65        // Package root (see tests/common/mod.rs `abs_rules_dir_path` for rationale).
66        return std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
67            .join("Rules")
68            .to_str()
69            .expect("CARGO_MANIFEST_DIR and Rules path must be UTF-8")
70            .to_string();
71        }
72    }
73}
74
75pub fn are_strs_canonically_equal_with_locale(test: &str, target: &str, ignore_attrs: &[&str], block_separators: &str, decimal_separators: &str) -> Result<()> {
76    use crate::{interface::*, pretty_print::mml_to_string};
77    use sxd_document_no_unsafe::parser;
78    use crate::canonicalize::canonicalize;
79    use std::panic::{catch_unwind, AssertUnwindSafe};
80
81    crate::interface::init_panic_handler();
82    let result = catch_unwind(AssertUnwindSafe(|| {
83        // this forces initialization
84        crate::interface::set_rules_dir(abs_rules_dir_path()).unwrap();
85        set_preference("Language", "en").unwrap();
86        set_preference("BlockSeparators", block_separators).unwrap();
87        set_preference("DecimalSeparators", decimal_separators).unwrap();
88        crate::speech::SPEECH_RULES.with(|rules|  rules.borrow_mut().read_files().unwrap());
89
90        let package1 = &parser::parse(test).expect("Failed to parse test input");
91        let mathml = get_element(package1);
92        trim_element(mathml, false);
93        let mathml_test = canonicalize(mathml).unwrap();
94
95        let package2 = &parser::parse(target).expect("Failed to parse target input");
96        let mathml_target = get_element(package2);
97        trim_element(mathml_target, false);
98
99        match is_same_element(mathml_test, mathml_target, ignore_attrs) {
100            Ok(_) => Ok( () ),
101            Err(e) => {
102                bail!("{}\nResult:\n{}\nTarget:\n{}", e, mml_to_string(mathml_test), mml_to_string(mathml_target));
103            },
104        }
105    }));
106    match crate::interface::report_any_panic(result) {
107        Ok(()) => Ok(()),
108        Err(e) => {
109            Err(e)
110        }
111    }
112}
113
114/// sets locale to be US standard
115pub fn are_strs_canonically_equal(test: &str, target: &str, ignore_attrs: &[&str]) -> bool {
116    are_strs_canonically_equal_with_locale(test, target, ignore_attrs, ", \u{00A0}\u{202F}", ".").is_ok()
117}
118
119/// Like `are_strs_canonically_equal` but returns `Result` for use in `#[test]` functions that return `Result<()>`.
120pub fn are_strs_canonically_equal_result(test: &str, target: &str, ignore_attrs: &[&str]) -> Result<()> {
121    are_strs_canonically_equal_with_locale(test, target, ignore_attrs, ", \u{00A0}\u{202F}", ".")
122}
libmathcat/lib.rs

libmathcat/
lib.rs
