//! The interface module provides functionality both for calling from an API and also running the code from `main`.

//!

#![allow(non_snake_case)]

#![allow(clippy::needless_return)]

use std::cell::RefCell;

use std::sync::LazyLock;

use crate::canonicalize::{as_text, create_mathml_element};

use crate::errors::*;

use phf::phf_map;

use regex::{Captures, Regex};

use sxd_document::dom::{Element, Document, ChildOfRoot, ChildOfElement, Attribute};

use sxd_document::parser;

use sxd_document::Package;

use crate::canonicalize::{as_element, name};

use crate::shim_filesystem::{find_all_dirs_shim, find_files_in_dir_that_ends_with_shim};

use log::{debug, error};

use crate::navigate::*;

use crate::pretty_print::mml_to_string;

use crate::xpath_functions::{is_leaf, IsNode};

use std::panic::{catch_unwind, AssertUnwindSafe};

/// Maximum depth to prevent stack overflow on deeply nested MathML

pub const MAX_DEPTH: usize = 512;

#[cfg(feature = "enable-logs")]

use std::sync::Once;

#[cfg(feature = "enable-logs")]

static INIT: Once = Once::new();

fn enable_logs() {

    #[cfg(feature = "enable-logs")]

    INIT.call_once(||{

        #[cfg(target_os = "android")]

        {

            use log::*;

            use android_logger::*;

            android_logger::init_once(

                Config::default()

                .with_max_level(LevelFilter::Trace)

                .with_tag("MathCat")

            );    

            trace!("Activated Android logger!");  

        }    

    });

}

// For getting a message from a panic

thread_local! {

    // Stores (Message, File, Line)

    static PANIC_INFO: RefCell<Option<(String, String, u32)>> = const { RefCell::new(None) };

}

/// Initialize the panic handler to catch panics and store the message, file, and line number in `PANIC_INFO`.

pub fn init_panic_handler() {

    use std::panic;

    panic::set_hook(Box::new(|info| 
{1

        let location = info.location()

            .map(|l| format!("{}:{}", l.file(), l.line()))

            .unwrap_or_else(|| 
"unknown"0
.
to_string0
());

        let payload = info.payload();

        let msg = if let Some(
s0
) = payload.downcast_ref::<&'static str>() {

            s.to_string()

        } else if let Some(s) = payload.downcast_ref::<String>() {

            s.clone()

        } else {

            "Unknown panic payload".to_string()

        };

        // Use try_with/try_borrow_mut to ensure the hook never panics itself

        let _ = PANIC_INFO.try_with(|cell| {

            if let Ok(mut slot) = cell.try_borrow_mut() {

                *slot = Some((msg, location, 0));

            
}0

        });

    }));

}

pub fn report_any_panic<T>(result: Result<Result<T, Error>, Box<dyn std::any::Any + Send>>) -> Result<T, Error> {

    match result {

        Ok(val) => val,

        Err(_) => {

            // Retrieve the smuggled info

            let details = PANIC_INFO.with(|cell| cell.borrow_mut().take());

            if let Some((msg, file, line)) = details {

                Err(anyhow::anyhow!(

                    "MathCAT crash! Please report the following information: '{}' at {}:{}",

                    msg, file, line

                ))

            } else {

                Err(anyhow::anyhow!("MathCAT crash! -- please report"))

            }

        }

    }

} 

// wrap up some common functionality between the call from 'main' and AT

fn cleanup_mathml(mathml: Element) -> Result<Element> {

    trim_element(mathml, false);

    let 
mathml4.91k
 = crate::canonicalize::canonicalize(mathml)
?1
;

    let mathml = add_ids(mathml);

    return Ok(mathml);

}

thread_local! {

    /// The current node being navigated (also spoken and brailled) is stored in `MATHML_INSTANCE`.

    pub static MATHML_INSTANCE: RefCell<Package> = init_mathml_instance();

}

fn init_mathml_instance() -> RefCell<Package> {

    let package = parser::parse("<math></math>")

        .expect("Internal error in 'init_mathml_instance;: didn't parse initializer string");

    return RefCell::new(package);

}

/// Set the Rules directory

/// IMPORTANT: this should be the very first call to MathCAT. If 'dir' is an empty string, the environment var 'MathCATRulesDir' is tried.

pub fn set_rules_dir(dir: impl AsRef<str>) -> Result<()> {

    enable_logs();

    init_panic_handler();

    let dir = dir.as_ref().to_string();

    let result = catch_unwind(AssertUnwindSafe(|| {

        use std::path::PathBuf;

        let dir_os = if dir.is_empty() {

            std::env::var_os("MathCATRulesDir").unwrap_or_default()

        } else {

            std::ffi::OsString::from(&dir)

        };

        let pref_manager = crate::prefs::PreferenceManager::get();

        pref_manager.borrow_mut().initialize(PathBuf::from(dir_os))

    }));

    return report_any_panic(result);

}

/// Returns the version number (from Cargo.toml) of the build

pub fn get_version() -> String {

    enable_logs();

    const VERSION: &str = env!("CARGO_PKG_VERSION");

    return VERSION.to_string();

}

/// This will override any previous MathML that was set.

/// This returns canonical MathML with 'id's set on any node that doesn't have an id.

/// The ids can be used for sync highlighting if the `Bookmark` API preference is true.

pub fn set_mathml(mathml_str: impl AsRef<str>) -> Result<String> {

    enable_logs();

    // if these are present when resent to MathJaX, MathJaX crashes (https://github.com/mathjax/MathJax/issues/2822)

    static MATHJAX_V2: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"class *= *['"]MJX-.*?['"]"#).unwrap());

    static MATHJAX_V3: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"class *= *['"]data-mjx-.*?['"]"#).unwrap());

    // Strip out processing instructions and comments -- these are not MathML and can cause DOS problems in the parser

    static PROCESSING_INSTRUCTION: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"<\?[\s\S]{1,2048}\?>"#).unwrap());

    static XML_COMMENT: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"(?s)"#).unwrap());

    // These have some length limits to avoid DOS attacks via long strings

    static NAMESPACE_DECL: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"xmlns:[[:alpha:]]{1,32}"#).unwrap());

    static PREFIX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"(</?)[[:alpha:]]{1,32}:"#).unwrap());

    static HTML_ENTITIES: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"&([a-zA-Z]{2,10});"#).unwrap());

    let result = catch_unwind(AssertUnwindSafe(|| {

        NAVIGATION_STATE.with(|nav_stack| {

            nav_stack.borrow_mut().reset();

        });

        // We need the main definitions files to be read in so canonicalize can work.

        // This call reads all of them for the current preferences, but that's ok since they will likely be used

        crate::speech::SPEECH_RULES.with(|rules| rules.borrow_mut().read_files())
?0
;

        let mathml_str = mathml_str.as_ref();

        // Safety guard: Reject strings > 1MB to prevent DoS/Stack issues

        if mathml_str.len() > 1024 * 1024 {

            bail!("MathML string of size {} bytes exceeds length limit of 1MB", mathml_str.len());

        }

        return MATHML_INSTANCE.with(|old_package| {

            static HTML_ENTITIES_MAPPING: phf::Map<&str, &str> = include!("entities.in");

            let mut error_message = "".to_string(); // can't return a result inside the replace_all, so we do this hack of setting the message and then returning the error

            let mathml_str = XML_COMMENT.replace_all(mathml_str, "");

            let mathml_str = PROCESSING_INSTRUCTION.replace_all(&mathml_str, "");

            // FIX: need to deal with character data and convert to something the parser knows

            let mathml_str = HTML_ENTITIES.replace_all(&mathml_str, |cap: &Captures| match 
HTML_ENTITIES_MAPPING96
.
get96
(&cap[1]) {

                    None => {

                        error_message = format!("No entity named '{}'", &cap[0]);

                        cap[0].to_string()

                    }

                    Some(&ch) => ch.to_string(),

                });

            if !error_message.is_empty() {

                // Clear stale state so subsequent API calls do not return previous user's data (security issue)

                old_package.replace(parser::parse("<math></math>").unwrap());

                bail!(error_message);

            }

            let mathml_str = MATHJAX_V2.replace_all(&mathml_str, "");

            let mathml_str = MATHJAX_V3.replace_all(&mathml_str, "");

            // the speech rules use the xpath "name" function and that includes the prefix

            // getting rid of the prefix properly probably involves a recursive replacement in the tree

            // if the prefix is used, it is almost certainly something like "m" or "mml", so this cheat will work.

            let mathml_str = NAMESPACE_DECL.replace(&mathml_str, "xmlns"); // do this before the PREFIX replace!

            let mathml_str = PREFIX.replace_all(&mathml_str, "$1");

            let new_package = parser::parse(&mathml_str);

            if let Err(
e1
) = new_package {

                // Clear stale state so subsequent API calls do not return previous user's data (security issue)

                old_package.replace(parser::parse("<math></math>").unwrap());

                bail!("Invalid MathML input:\n{}\nError is: {}", &mathml_str, &e.to_string());

            }

            let new_package = new_package.unwrap();

            let mathml = get_element(&new_package);

            let 
mathml4.88k
 = cleanup_mathml(mathml)
?1
;

            let mathml_string = mml_to_string(mathml);

            old_package.replace(new_package);

            return Ok(mathml_string);

        });

    }));

    return report_any_panic(result);

}

/// Get the spoken text of the MathML that was set.

/// The speech takes into account any AT or user preferences.

pub fn get_spoken_text() -> Result<String> {

    enable_logs();

    let result = catch_unwind(AssertUnwindSafe(|| {

        MATHML_INSTANCE.with(|package_instance| {

            let package_instance = package_instance.borrow();

            let mathml = get_element(&package_instance);

            let new_package = Package::new();

            let intent = crate::speech::intent_from_mathml(mathml, new_package.as_document())
?0
;

            debug!("Intent tree:\n{}", 
mml_to_string0
(
intent0
));

            let speech = crate::speech::speak_mathml(intent, "", 0)
?0
;

            return Ok(speech);

        })

    }));

    return report_any_panic(result);

}

/// Get the spoken text for an overview of the MathML that was set.

/// The speech takes into account any AT or user preferences.

/// Note: this implementation for is currently minimal and should not be used.

pub fn get_overview_text() -> Result<String> {

    enable_logs();

    let result = catch_unwind(AssertUnwindSafe(|| {

        MATHML_INSTANCE.with(|package_instance| {

            let package_instance = package_instance.borrow();

            let mathml = get_element(&package_instance);

            let speech = crate::speech::overview_mathml(mathml, "", 0)?;

            return Ok(speech);

        })

    }));

    return report_any_panic(result);

}

/// Get the value of the named preference.

/// None is returned if `name` is not a known preference.

pub fn get_preference(name: impl AsRef<str>) -> Result<String> {

    enable_logs();

    let name = name.as_ref().to_string();

    let result = catch_unwind(AssertUnwindSafe(|| {

        use crate::prefs::NO_PREFERENCE;

        crate::speech::SPEECH_RULES.with(|rules| {

            let rules = rules.borrow();

            let pref_manager = rules.pref_manager.borrow();

            let mut value = pref_manager.pref_to_string(&name);

            if value == NO_PREFERENCE {

                value = pref_manager.pref_to_string(&name);

            }

            if value == NO_PREFERENCE {

                bail!("No preference named '{}'", name);

            } else {

                return Ok(value);

            }

        })

    }));

    return report_any_panic(result);

}

/// Set a MathCAT preference. The preference name should be a known preference name.

/// The value should either be a string or a number (depending upon the preference being set)

/// The list of known user preferences is in the MathCAT user documentation.

/// Here are common preferences set by programs (not settable by the user):

/// * TTS -- SSML, SAPI5, None

/// * Pitch -- normalized at '1.0'

/// * Rate -- words per minute (should match current speech rate).

///   There is a separate "MathRate" that is user settable that causes a relative percentage change from this rate.

/// * Volume -- default 100

/// * Voice -- set a voice to use (not implemented)

/// * Gender -- set pick any voice of the given gender (not implemented)

/// * Bookmark -- set to `true` if a `mark`/`bookmark` should be part of the returned speech (used for sync highlighting)

///

/// Important: both the preference name and value are case-sensitive

///

/// This function can be called multiple times to set different values.

/// The values are persistent and extend beyond calls to [`set_mathml`].

/// A value can be overwritten by calling this function again with a different value.

///

/// Be careful setting preferences -- these potentially override user settings, so only preferences that really need setting should be set.

pub fn set_preference(name: impl AsRef<str>, value: impl AsRef<str>) -> Result<()> {

    enable_logs();

    let name = name.as_ref().to_string();

    let value = value.as_ref().to_string();

    let result = catch_unwind(AssertUnwindSafe(|| {

        set_preference_impl(&name, &value)

    }));

    return report_any_panic(result);

}

fn set_preference_impl(name: &str, value: &str) -> Result<()> {

    let mut value = value.to_string();

    if name == "Language" || 
name == "LanguageAuto"12.7k
 {

        // check the format

        if value != "Auto" {

            // could get es, es-419, or en-us-nyc ...  we only care about the first two parts so we clean it up a little

            let mut lang_country_split = value.split('-');

            let language = lang_country_split.next().unwrap_or("");

            let country = lang_country_split.next().unwrap_or("");

            if language.len() != 2 {

                bail!(

                    "Improper format for 'Language' preference '{}'. Should be of form 'en' or 'en-gb'",

                    value

                );

            }

            let mut new_lang_country = language.to_string(); // need a temp value because 'country' is borrowed from 'value' above

            if !country.is_empty() {

                new_lang_country.push('-');

                new_lang_country.push_str(country);

            }

            value = new_lang_country;

        }

        if name == "LanguageAuto" && 
value == "Auto"0
 {

            bail!("'LanguageAuto' can not have the value 'Auto'");

        }

    }

    crate::speech::SPEECH_RULES.with(|rules| -> Result<()> {

        if let Some(
error_string0
) = rules.borrow().get_error() {

            bail!("{}", error_string);

        }

        Ok(())

    })
?0
;

    // Do not hold a SpeechRules borrow while updating preferences: invalidation clears rule caches.

    let pref_manager = crate::prefs::PreferenceManager::get();

    let mut pref_manager = pref_manager.borrow_mut();

    if name == "LanguageAuto" {

        let language_pref = pref_manager.pref_to_string("Language");

        if language_pref != "Auto" {

            bail!(

                "'LanguageAuto' can only be used when 'Language' has the value 'Auto'; Language={}",

                language_pref

            );

        }

    }

    let lower_case_value = value.to_lowercase();

    if lower_case_value == "true" || 
lower_case_value == "false"17.6k
 {

        pref_manager.set_api_boolean_pref(name, value.to_lowercase() == "true");

    } else {

        match name {

            "Pitch" | "Rate" | "Volume" | "CapitalLetters_Pitch" | "MathRate" | "PauseFactor" => {

                pref_manager.set_api_float_pref(name, to_float(name, &value)?)

            }

            _ => {

                pref_manager.set_string_pref(name, &value)
?0
;

            }

        }

    };

    return Ok(());

}

fn to_float(name: &str, value: &str) -> Result<f64> {

    return match value.parse::<f64>() {

        Ok(val) => Ok(val),

        Err(_) => bail!("SetPreference: preference'{}'s value '{}' must be a float", name, value),

    };

}

/// Get the braille associated with the MathML that was set by [`set_mathml`].

/// The braille returned depends upon the preference for the `code` preference (default `Nemeth`).

/// If 'nav_node_id' is given, it is highlighted based on the value of `BrailleNavHighlight` (default: `EndPoints`)

pub fn get_braille(nav_node_id: impl AsRef<str>) -> Result<String> {

    enable_logs();

    let nav_node_id = nav_node_id.as_ref().to_string();

    let result = catch_unwind(AssertUnwindSafe(|| {

        MATHML_INSTANCE.with(|package_instance| {

            let package_instance = package_instance.borrow();

            let mathml = get_element(&package_instance);

            let braille = crate::braille::braille_mathml(mathml, &nav_node_id)
?0
.0;

            return Ok(braille);

        })

    }));

    return report_any_panic(result);

}

/// Get the braille associated with the current navigation focus of the MathML that was set by [`set_mathml`].

/// The braille returned depends upon the preference for the `code` preference (default `Nemeth`).

/// The returned braille is brailled as if the current navigation focus is the entire expression to be brailled.

pub fn get_navigation_braille() -> Result<String> {

    enable_logs();

    let result = catch_unwind(AssertUnwindSafe(|| {

        MATHML_INSTANCE.with(|package_instance| {

            let package_instance = package_instance.borrow();

            let mathml = get_element(&package_instance);

            let new_package = Package::new(); // used if we need to create a new tree

            let new_doc = new_package.as_document();

            let nav_mathml = NAVIGATION_STATE.with(|nav_stack| {

                return match nav_stack.borrow_mut().get_navigation_mathml(mathml) {

                    Err(e) => Err(e),

                    Ok((found, offset)) => {

                        // get the MathML node and wrap it inside of a <math> element

                        // if the offset is given, we need to get the character it references

                        if offset == 0 {

                            if name(found) == "math" {

                                Ok(found)

                            } else {

                                let new_mathml = create_mathml_element(&new_doc, "math");

                                new_mathml.append_child(copy_mathml(found));

                                new_doc.root().append_child(new_mathml);

                                Ok(new_mathml)

                            }

                        } else if !is_leaf(found) {

                            bail!(

                                "Internal error: non-zero offset '{}' on a non-leaf element '{}'",

                                offset,

                                name(found)

                            );

                        } else if let Some(ch) = as_text(found).chars().nth(offset) {

                            let internal_mathml = create_mathml_element(&new_doc, name(found));

                            internal_mathml.set_text(&ch.to_string());

                            let new_mathml = create_mathml_element(&new_doc, "math");

                            new_mathml.append_child(internal_mathml);

                            new_doc.root().append_child(new_mathml);

                            Ok(new_mathml)

                        } else {

                            bail!(

                                "Internal error: offset '{}' on leaf element '{}' doesn't exist",

                                offset,

                                mml_to_string(found)

                            );

                        }

                    }

                };

            })?;

            let braille = crate::braille::braille_mathml(nav_mathml, "")?.0;

            return Ok(braille);

        })

    }));

    return report_any_panic(result);

}

/// Given a key code along with the modifier keys, the current node is moved accordingly (or value reported in some cases).

/// `key` is the [keycode](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode#constants_for_keycode_value) for the key (in JavaScript, `ev.key_code`)

/// The spoken text for the new current node is returned.

pub fn do_navigate_keypress(

    key: usize,

    shift_key: bool,

    control_key: bool,

    alt_key: bool,

    meta_key: bool,

) -> Result<String> {

    enable_logs();

    let result = catch_unwind(AssertUnwindSafe(|| {

        MATHML_INSTANCE.with(|package_instance| {

            let package_instance = package_instance.borrow();

            let mathml = get_element(&package_instance);

            return do_mathml_navigate_key_press(mathml, key, shift_key, control_key, alt_key, meta_key);

        })

    }));

    return report_any_panic(result);

}

/// Given a navigation command, the current node is moved accordingly.

/// This is a higher level interface than `do_navigate_keypress` for applications that want to interpret the keys themselves.

/// The valid commands are:

/// * Standard move commands:

///   `MovePrevious`, `MoveNext`, `MoveStart`, `MoveEnd`, `MoveLineStart`, `MoveLineEnd`

/// * Movement in a table or elementary math:

///   `MoveCellPrevious`, `MoveCellNext`, `MoveCellUp`, `MoveCellDown`, `MoveColumnStart`, `MoveColumnEnd`

/// * Moving into children or out to parents:

///   `ZoomIn`, `ZoomOut`, `ZoomOutAll`, `ZoomInAll`

/// * Undo the last movement command:

///   `MoveLastLocation`

/// * Read commands (standard speech):

///   `ReadPrevious`, `ReadNext`, `ReadCurrent`, `ReadCellCurrent`, `ReadStart`, `ReadEnd`, `ReadLineStart`, `ReadLineEnd`

/// * Describe commands (overview):

///   `DescribePrevious`, `DescribeNext`, `DescribeCurrent`

/// * Location information:

///   `WhereAmI`, `WhereAmIAll`

/// * Change navigation modes (circle up/down):

///   `ToggleZoomLockUp`, `ToggleZoomLockDown`

/// * Speak the current navigation mode

///   `ToggleSpeakMode`

///

/// There are 10 place markers that can be set/read/described or moved to.

/// * Setting:

///   `SetPlacemarker0`, `SetPlacemarker1`, `SetPlacemarker2`, `SetPlacemarker3`, `SetPlacemarker4`, `SetPlacemarker5`, `SetPlacemarker6`, `SetPlacemarker7`, `SetPlacemarker8`, `SetPlacemarker9`

/// * Reading:

///   `Read0`, `Read1`, `Read2`, `Read3`, `Read4`, `Read5`, `Read6`, `Read7`, `Read8`, `Read9`

/// * Describing:

///   `Describe0`, `Describe1`, `Describe2`, `Describe3`, `Describe4`, `Describe5`, `Describe6`, `Describe7`, `Describe8`, `Describe9`

/// * Moving:

///   `MoveTo0`, `MoveTo1`, `MoveTo2`, `MoveTo3`, `MoveTo4`, `MoveTo5`, `MoveTo6`, `MoveTo7`, `MoveTo8`, `MoveTo9`

///

/// When done with Navigation, call with `Exit`

pub fn do_navigate_command(command: impl AsRef<str>) -> Result<String> {

    enable_logs();

    let command = command.as_ref().to_string();

    let result = catch_unwind(AssertUnwindSafe(|| {

        let cmd = NAV_COMMANDS.get_key(&command); // gets a &'static version of the command

        if cmd.is_none() {

            bail!("Unknown command in call to DoNavigateCommand()");

        };

        let cmd = *cmd.unwrap();

        MATHML_INSTANCE.with(|package_instance| {

            let package_instance = package_instance.borrow();

            let mathml = get_element(&package_instance);

            return do_navigate_command_string(mathml, cmd);

        })

    }));

    return report_any_panic(result);

}

/// Given an 'id' and an offset (for tokens), set the navigation node to that id.

/// An error is returned if the 'id' doesn't exist

pub fn set_navigation_node(id: impl AsRef<str>, offset: usize) -> Result<()> {

    enable_logs();

    let id = id.as_ref().to_string();

    let result = catch_unwind(AssertUnwindSafe(|| {

        MATHML_INSTANCE.with(|package_instance| {

            let package_instance = package_instance.borrow();

            let mathml = get_element(&package_instance);

            return set_navigation_node_from_id(mathml, &id, offset);

        })

    }));

    return report_any_panic(result);

}

/// Return the MathML associated with the current (navigation) node and the offset (0-based) from that mathml (not yet implemented)

/// The offset is needed for token elements that have multiple characters.

pub fn get_navigation_mathml() -> Result<(String, usize)> {

    enable_logs();

    let result = catch_unwind(AssertUnwindSafe(|| {

        MATHML_INSTANCE.with(|package_instance| {

            let package_instance = package_instance.borrow();

            let mathml = get_element(&package_instance);

            return NAVIGATION_STATE.with(|nav_stack| {

                return match nav_stack.borrow_mut().get_navigation_mathml(mathml) {

                    Err(e) => Err(e),

                    Ok((found, offset)) => Ok((mml_to_string(found), offset)),

                };

            });

        })

    }));

    return report_any_panic(result);

}

/// Return the `id` and `offset` (0-based) associated with the current (navigation) node.

/// `offset` (not yet implemented)

/// The offset is needed for token elements that have multiple characters.

pub fn get_navigation_mathml_id() -> Result<(String, usize)> {

    enable_logs();

    let result = catch_unwind(AssertUnwindSafe(|| {

        MATHML_INSTANCE.with(|package_instance| {

            let package_instance = package_instance.borrow();

            let mathml = get_element(&package_instance);

            return Ok(NAVIGATION_STATE.with(|nav_stack| {

                return nav_stack.borrow().get_navigation_mathml_id(mathml);

            }));

        })

    }));

    return report_any_panic(result);

}

/// Return the start and end braille character positions associated with the current (navigation) node.

pub fn get_braille_position() -> Result<(usize, usize)> {

    enable_logs();

    let result = catch_unwind(AssertUnwindSafe(|| {

        MATHML_INSTANCE.with(|package_instance| {

            let package_instance = package_instance.borrow();

            let mathml = get_element(&package_instance);

            let nav_node = get_navigation_mathml_id()
?0
;

            let (_, start, end) = crate::braille::braille_mathml(mathml, &nav_node.0)
?0
;

            return Ok((start, end));

        })

    }));

    return report_any_panic(result);

}

/// Given a 0-based braille position, return the smallest MathML node enclosing it.

/// This node might be a leaf with an offset.

pub fn get_navigation_node_from_braille_position(position: usize) -> Result<(String, usize)> {

    enable_logs();

    let result = catch_unwind(AssertUnwindSafe(|| {

        MATHML_INSTANCE.with(|package_instance| {

            let package_instance = package_instance.borrow();

            let mathml = get_element(&package_instance);

            return crate::braille::get_navigation_node_from_braille_position(mathml, position);

        })

    }));

    return report_any_panic(result);

}

pub fn get_supported_braille_codes() -> Result<Vec<String>> {

    enable_logs();

    let result = catch_unwind(AssertUnwindSafe(|| {

        let rules_dir = crate::prefs::PreferenceManager::get().borrow().get_rules_dir();

        let braille_dir = rules_dir.join("Braille");

        let mut braille_code_paths = Vec::new();

        find_all_dirs_shim(&braille_dir, &mut braille_code_paths);

        let mut braille_code_paths = braille_code_paths.iter()

                        .map(|path| path.strip_prefix(&braille_dir).unwrap().to_string_lossy().to_string())

                        .filter(|string_path| !string_path.is_empty() )

                        .collect::<Vec<String>>();

        braille_code_paths.sort();

        Ok(braille_code_paths)

    }));

    return report_any_panic(result);

 }

/// Returns a Vec of all supported languages ("en", "es", ...)

pub fn get_supported_languages() -> Result<Vec<String>> {

    enable_logs();

    let result = catch_unwind(AssertUnwindSafe(|| {

        let rules_dir = crate::prefs::PreferenceManager::get().borrow().get_rules_dir();

        let lang_dir = rules_dir.join("Languages");

        let mut lang_paths = Vec::new();

        find_all_dirs_shim(&lang_dir, &mut lang_paths);

        let mut language_paths = lang_paths.iter()

                        .
map1
(|path| path.strip_prefix(&lang_dir).unwrap()

                                                  .to_string_lossy()

                                                  .replace(std::path::MAIN_SEPARATOR, "-")

                                                  .to_string())

                        .
filter1
(|string_path| !string_path.is_empty() )

                        .collect::<Vec<String>>();

        // make sure the 'zz' test dir isn't included (build.rs removes it, but for debugging is there)

        
language_paths1
.
retain1
(|s| !s.starts_with("zz"));

        language_paths.sort();

        Ok(language_paths)

    }));

    return report_any_panic(result);

 }

 pub fn get_supported_speech_styles(lang: impl AsRef<str>) -> Result<Vec<String>> {

    enable_logs();

    let lang = lang.as_ref().to_string();

    let result = catch_unwind(AssertUnwindSafe(|| {

        let rules_dir = crate::prefs::PreferenceManager::get().borrow().get_rules_dir();

        let lang_dir = rules_dir.join("Languages").join(&lang);

        let mut speech_styles = find_files_in_dir_that_ends_with_shim(&lang_dir, "_Rules.yaml");

        for file_name in &mut speech_styles {

            file_name.truncate(file_name.len() - "_Rules.yaml".len())

        }

        speech_styles.sort();

        speech_styles.dedup(); // remove duplicates -- shouldn't be any, but just in case

        Ok(speech_styles)

    }));

    return report_any_panic(result);

 }

// utility functions

/// Copy (recursively) the (MathML) element and return the new one.

/// The Element type does not copy and modifying the structure of an element's child will modify the element, so we need a copy

/// Convert the returned error from set_mathml, etc., to a useful string for display

pub fn copy_mathml(mathml: Element) -> Element {

    return copy_mathml_recursive(mathml, 0);

}

fn copy_mathml_recursive(mathml: Element, depth: usize) -> Element {

    // Safety: Prevent stack overflow on deeply nested MathML

    if depth > MAX_DEPTH {

        // Return the element as a leaf if it's too deep to prevent crash

        return create_mathml_element(&mathml.document(), name(mathml));

    }

    // If it represents MathML, the 'Element' can only have Text and Element children along with attributes

    let children = mathml.children();

    let new_mathml = create_mathml_element(&mathml.document(), name(mathml));

    
mathml.attributes().iter()4.53k
.
for_each4.53k
(|attr| {

        new_mathml.set_attribute_value(attr.name(), attr.value());

    });

    // can't use is_leaf/as_text because this is also used with the intent tree

    if children.len() == 1 &&

       let Some(
text2.59k
) = children[0].text() {

        new_mathml.set_text(text.text());

        return new_mathml;

        }

    let mut new_children = Vec::with_capacity(children.len());

    for child in 
children1.93k
 {

        let child = as_element(child);

        let new_child = copy_mathml_recursive(child, depth + 1);

        new_children.push(new_child);

    }

    new_mathml.append_children(new_children);

    return new_mathml;

}

pub fn errors_to_string(e: &Error) -> String {

    enable_logs();

    let mut result = format!("{e}\n");

    for cause in e.chain().skip(1) { // skips original error

        result += &format!("caused by: {cause}\n");

    }

    result

}

fn add_ids(mathml: Element) -> Element {

    use std::time::SystemTime;

    let time = if cfg!(target_family = "wasm") {

        fastrand::usize(..)

    } else {

        SystemTime::now()

            .duration_since(SystemTime::UNIX_EPOCH)

            .unwrap()

            .as_millis() as usize

    };

    let mut time_part = radix_fmt::radix(time, 36).to_string();

    if time_part.len() < 3 {

        time_part.push_str("a2c");      // needs to be at least three chars

    }

    let mut random_part = radix_fmt::radix(fastrand::u32(..), 36).to_string();

    if random_part.len() < 4 {

        random_part.push_str("a1b2");      // needs to be at least four chars

    }

    let prefix = "M".to_string() + &time_part[time_part.len() - 3..] + &random_part[random_part.len() - 4..] + "-"; // begin with letter

    add_ids_to_all(mathml, &prefix, 0);

    return mathml;

    fn add_ids_to_all(mathml: Element, id_prefix: &str, count: usize) -> usize {

        let mut count = count;

        if mathml.attribute("id").is_none() {

            mathml.set_attribute_value("id", (id_prefix.to_string() + &count.to_string()).as_str());

            mathml.set_attribute_value("data-id-added", "true");

            count += 1;

        
}707
;

        if crate::xpath_functions::is_leaf(mathml) {

            return count;

        }

        for child in 
mathml22.0k
.
children22.0k
() {

            let child = as_element(child);

            count = add_ids_to_all(child, id_prefix, count);

        }

        return count;

    }

}

pub fn get_element(package: &Package) -> Element<'_> {

    enable_logs();

    let doc = package.as_document();

    let mut result = None;

    for root_child in doc.root().children() {

        if let ChildOfRoot::Element(e) = root_child {

            assert!(result.is_none());

            result = Some(e);

        }

    }

    return result.unwrap();

}

/// Get the intent after setting the MathML

/// Used in testing

#[allow(dead_code)]

pub fn get_intent<'a>(mathml: Element<'a>, doc: Document<'a>) -> Result<Element<'a>> {

    crate::speech::SPEECH_RULES.with(|rules|  rules.borrow_mut().read_files().unwrap());

    let mathml = cleanup_mathml(mathml)
?0
;

    return crate::speech::intent_from_mathml(mathml, doc);

}

#[allow(dead_code)]

fn trim_doc(doc: &Document) {

    for root_child in doc.root().children() {

        if let ChildOfRoot::Element(e) = root_child {

            trim_element(e, false);

        } else {

            doc.root().remove_child(root_child); // comment or processing instruction

        }

    }

}

/// Not really meant to be public -- used by tests in some packages

pub fn trim_element(e: Element, allow_structure_in_leaves: bool) {

    // "<mtext>this is text</mtext" results in 3 text children

    // these are combined into one child as it makes code downstream simpler

    // space, tab, newline, carriage return all get collapsed to a single space

    const WHITESPACE: &[char] = &[' ', '\u{0009}', '\u{000A}','\u{000C}', '\u{000D}'];

    static WHITESPACE_MATCH: LazyLock<Regex> = LazyLock::new(|| Regex::new(r#"[ \u{0009}\u{000A}\u{00C}\u{000D}]+"#).unwrap());

    if is_leaf(e) && (
!allow_structure_in_leaves34.7k
 || 
IsNode::is_mathml230
(
e230
)) {

        // Assume it is HTML inside of the leaf -- turn the HTML into a string

        make_leaf_element(e);

        return;

    }

    let mut single_text = "".to_string();

    for child in 
e20.7k
.
children20.7k
() {

        match child {

            ChildOfElement::Element(c) => {

                trim_element(c, allow_structure_in_leaves);

            }

            ChildOfElement::Text(t) => {

                single_text += t.text();

                e.remove_child(child);

            }

            _ => {

                e.remove_child(child);

            }

        }

    }

    // CSS considers only space, tab, linefeed, and carriage return as collapsable whitespace

    if !(is_leaf(e) || name(e) == "intent-literal" || single_text.is_empty()) {

        // intent-literal comes from testing intent

        // FIX: we have a problem -- what should happen???

        // FIX: For now, just keep the children and ignore the text and log an error -- shouldn't panic/crash

        if !single_text.trim_matches(WHITESPACE).is_empty() {

            error!(

                "trim_element: both element and textual children which shouldn't happen -- ignoring text '{single_text}'"

            );

        }

        return;

    }

    if e.children().is_empty() && 
!single_text.is_empty()276
 {

        // debug!("Combining text in {}: '{}' -> '{}'", e.name().local_part(), single_text, trimmed_text);

        e.set_text(&WHITESPACE_MATCH.replace_all(&single_text, " "));

    }

    fn make_leaf_element(mathml_leaf: Element) {

        // MathML leaves like <mn> really shouldn't have non-textual content, but you could have embedded HTML

        // Here, we convert them to leaves by grabbing up all the text and making that the content

        // Potentially, we leave them and let (default) rules do something, but it makes other parts of the code

        //   messier because checking the text of a leaf becomes Option<&str> rather than just &str

        let children = mathml_leaf.children();

        if children.is_empty() {

            return;

        }

        if rewrite_and_flatten_embedded_mathml(mathml_leaf) {

            return;

        }

        // gather up the text

        let mut text = "".to_string();

        for child in 
children34.2k
 {

            let child_text = match child {

                ChildOfElement::Element(child) => {

                    if name(child) == "mglyph" {

                        child.attribute_value("alt").unwrap_or("").to_string()

                    } else {

                        gather_text(child)

                    }

                }

                ChildOfElement::Text(t) => {

                    // debug!("ChildOfElement::Text: '{}'", t.text());

                    t.text().to_string()

                }

                _ => "".to_string(),

            };

            if !child_text.is_empty() {

                text += &child_text;

            
}223

        }

        // get rid of the old children and replace with the text we just built

        mathml_leaf.clear_children();

        mathml_leaf.set_text(WHITESPACE_MATCH.replace_all(&text, " ").trim_matches(WHITESPACE));

        // debug!("make_leaf_element: text is '{}'", crate::canonicalize::as_text(mathml_leaf));

        /// gather up all the contents of the element and return them with a leading space

        fn gather_text(html: Element) -> String {

            let mut text = "".to_string(); // since we are throwing out the element tag, add a space between the contents

            for child in html.children() {

                match child {

                    ChildOfElement::Element(child) => {

                        text += &gather_text(child);

                    }

                    ChildOfElement::Text(t) => text += t.text(),

                    _ => (),

                }

            }

            // debug!("gather_text: '{}'", text);

            return text;

        }

    }

    fn rewrite_and_flatten_embedded_mathml(mathml_leaf: Element) -> bool {

        // first see if it can or needs to be rewritten

        // this is likely rare, so we do a check and if true, to a second pass building the result

        let mut needs_rewrite = false;

        for child in 
mathml_leaf34.2k
.
children34.2k
() {

            if let Some(
element8
) = child.element() {

                if name(element) != "math" {

                    return false; // something other than MathML as a child -- can't rewrite

                }

                needs_rewrite = true;

            }

        };

        if !needs_rewrite {

            return false;

        }

        // now do the rewrite, flatting out the mathml and returning an mrow with the children

        let leaf_name = name(mathml_leaf);

        let doc = mathml_leaf.document();

        let mut new_children = Vec::new();

        let mut is_last_mtext = false;

        for child in 
mathml_leaf1
.
children1
() {

            if let Some(
element1
) = child.element() {

                trim_element(element, true);

                new_children.append(&mut element.children());   // don't want 'math' wrapper

                is_last_mtext = false;

            } else if let Some(text) = child.text() {

                // combine adjacent text nodes into single nodes

                if is_last_mtext {

                    let last_child = new_children.last_mut().unwrap().element().unwrap();

                    let new_text = as_text(last_child).to_string() + text.text();

                    last_child.set_text(&new_text);

                } else {

                    let new_leaf_node = create_mathml_element(&doc, leaf_name);

                    new_leaf_node.set_text(text.text());

                    new_children.push(ChildOfElement::Element(new_leaf_node));

                    is_last_mtext = true;

                }

            }

        };

        // clean up whitespace in text nodes

        for child in 
&mut new_children1
 {    

            if let Some(element) = child.element() && is_leaf(element) {

                let text = as_text(element);

                let cleaned_text = WHITESPACE_MATCH.replace_all(text, " ").trim_matches(WHITESPACE).to_string();

                element.set_text(&cleaned_text);

            
}1

        }

        crate::canonicalize::set_mathml_name(mathml_leaf, "mrow");

        mathml_leaf.clear_children();

        mathml_leaf.append_children(new_children);

        // debug!("rewrite_and_flatten_embedded_mathml: flattened\n'{}'", mml_to_string(mathml_leaf));

        return true;

    }

}

// used for testing trim

/// returns Ok() if two Documents are equal or some info where they differ in the Err

#[allow(dead_code)]

fn is_same_doc(doc1: &Document, doc2: &Document) -> Result<()> {

    // assume 'e' doesn't have element children until proven otherwise

    // this means we keep Text children until we are proven they aren't needed

    if doc1.root().children().len() != doc2.root().children().len() {

        bail!(

            "Children of docs have {} != {} children",

            doc1.root().children().len(),

            doc2.root().children().len()

        );

    }

    for (i, (c1, c2)) in doc1

        .root()

        .children()