enshwick 1.0.0-alpha.6

//! Translations: a mod ships its texts per language in one TOML file, a
//! server owner may add to them or change them, and the game shows them for
//! the player's language.
//!
//! ```toml
//! [en]
//! "locker.name" = "Locker"
//!
//! [uk]
//! "locker.name" = "Шафка"
//! ```
//!
//! `en` is the fallback for every language without a text of its own. A file
//! `mod-configs/<id>.texts.toml` in the same form overrides or adds texts.

use std::collections::BTreeMap;

use rustc_hash::FxHashMap;

use crate::content::Id;
use crate::locks::Relock;
use crate::{Host, Load, Off};

/// The language the player reads the game in, for a mod's own texts in its
/// dialogs and windows; the fallback on a server.
///
/// The fallback, too, before the client's first text.
///
/// # Examples
///
/// ```
/// use enshwick::i18n::{Texts, language};
///
/// let texts = Texts::parse("[en]\ngreeting = \"Hello\"\n[uk]\ngreeting = \"Привіт\"\n")?;
/// let greeting = texts.fill("greeting", language(), &[]);
/// assert!(!greeting.is_empty());
/// # Ok::<(), enshwick::Off>(())
/// ```
#[must_use]
pub fn language() -> Language {
    crate::host().map_or(Language::FALLBACK, |host| host.language())
}

impl Host {
    /// The language the player reads the game in; see [`language`].
    ///
    /// # Examples
    ///
    /// ```
    /// if let Some(host) = enshwick::host() {
    ///     enshwick::info!("texts in {}", host.language().code());
    /// }
    /// ```
    #[must_use]
    pub fn language(&self) -> Language {
        let language = Language((self.api().language)(self.handle()));
        if language.code().is_empty() {
            Language::FALLBACK
        } else {
            language
        }
    }
}

/// The game's own text of tag `id` in the language the player reads the
/// game in, such as an item's or a survivor's name; a text missing there
/// comes in English, as the game shows it.
///
/// `id` is a text tag's game id, [`Guid::id`](crate::content::Guid::id) of
/// the tag an item's or a template's data names. The text is read from the
/// game's archive and stays valid for the process. `None` for a tag the
/// game lacks, and always on a server, whose archive holds no texts.
///
/// # Examples
///
/// ```
/// use enshwick::i18n::game_text;
///
/// if let Some(text) = game_text(0x8f21_95d5) {
///     enshwick::info!("the game calls it {text}");
/// }
/// ```
#[must_use]
pub fn game_text(id: u32) -> Option<&'static str> {
    game_text_in(id, language())
}

/// The game's own text of tag `id` in `language`, as [`game_text`] reads
/// it; [`Language::FALLBACK`] asks for English.
///
/// # Examples
///
/// ```
/// use enshwick::i18n::{Language, game_text_in};
///
/// let name = game_text_in(0x8f21_95d5, Language::UK_UA);
/// assert!(name.is_none() || name.is_some_and(|n| !n.is_empty()));
/// ```
#[must_use]
pub fn game_text_in(id: u32, language: Language) -> Option<&'static str> {
    crate::host()?.game_text(id, language)
}

impl Host {
    /// The game's own text of tag `id` in `language`; see [`game_text_in`].
    ///
    /// # Examples
    ///
    /// ```
    /// use enshwick::i18n::Language;
    ///
    /// if let Some(host) = enshwick::host() {
    ///     let _ = host.game_text(0x8f21_95d5, Language::DE_DE);
    /// }
    /// ```
    #[must_use]
    pub fn game_text(&self, id: u32, language: Language) -> Option<&'static str> {
        let api = self.api();
        let mut out = crate::abi::Str::EMPTY;
        if !(api.game_text)(self.handle(), id, language.0, &raw mut out).is_ok() {
            return None;
        }
        // SAFETY: the loader keeps the text for the life of the process.
        unsafe { out.as_str() }
    }
}

/// A game language, as the game numbers them.
///
/// # Examples
///
/// ```
/// use enshwick::i18n::Language;
///
/// assert_eq!(Language::from_code("uk"), Some(Language::UK_UA));
/// assert_eq!(Language::UK_UA.code(), "uk");
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Language(pub u32);

macro_rules! languages {
    ($($name:ident = $id:literal, $code:literal, $doc:literal;)*) => {
        impl Language {
            $(#[doc = $doc] pub const $name: Self = Self($id);)*

            /// Every language the game knows, the fallback first.
            pub const ALL: &[Self] = &[$(Self::$name),*];

            /// The language's code in text files, such as `uk` or `pt-br`.
            ///
            /// # Examples
            ///
            /// See [`Language`].
            #[must_use]
            pub const fn code(self) -> &'static str {
                match self.0 {
                    $($id => $code,)*
                    _ => "",
                }
            }

            /// The language with code `code`, ignoring case.
            ///
            /// # Examples
            ///
            /// See [`Language`].
            #[must_use]
            pub fn from_code(code: &str) -> Option<Self> {
                let code = code.to_ascii_lowercase();
                match code.as_str() {
                    $($code => Some(Self::$name),)*
                    _ => None,
                }
            }
        }
    };
}

languages! {
    FALLBACK = 0, "en", "English, and every language without a text of its own.";
    EN_US = 1, "en-us", "English (United States).";
    EN_GB = 2, "en-gb", "English (United Kingdom).";
    DE_DE = 3, "de", "German.";
    NL_NL = 4, "nl", "Dutch.";
    FR_FR = 5, "fr", "French.";
    IT_IT = 6, "it", "Italian.";
    ES_ES = 7, "es", "Spanish (Spain).";
    ES_MX = 8, "es-mx", "Spanish (Mexico).";
    RU_RU = 9, "ru", "Russian.";
    PL_PL = 10, "pl", "Polish.";
    JA_JP = 11, "ja", "Japanese.";
    ID_ID = 12, "id", "Indonesian.";
    KO_KR = 13, "ko", "Korean.";
    MS_MY = 14, "ms", "Malay.";
    PT_PT = 15, "pt", "Portuguese (Portugal).";
    PT_BR = 16, "pt-br", "Portuguese (Brazil).";
    TH_TH = 17, "th", "Thai.";
    TR_TR = 18, "tr", "Turkish.";
    VI_VN = 19, "vi", "Vietnamese.";
    ZH_CN = 20, "zh-cn", "Chinese (Simplified).";
    ZH_TW = 21, "zh-tw", "Chinese (Traditional).";
    FR_CA = 22, "fr-ca", "French (Canada).";
    ES_419 = 23, "es-419", "Spanish (Latin America).";
    BG_BG = 24, "bg", "Bulgarian.";
    CS_CZ = 25, "cs", "Czech.";
    DA_DK = 26, "da", "Danish.";
    FI_FI = 27, "fi", "Finnish.";
    EL_GR = 28, "el", "Greek.";
    HU_HU = 29, "hu", "Hungarian.";
    NO_NO = 30, "no", "Norwegian.";
    NB_NO = 31, "nb", "Norwegian (Bokmål).";
    RO_RO = 32, "ro", "Romanian.";
    SV_SE = 33, "sv", "Swedish.";
    UK_UA = 34, "uk", "Ukrainian.";
}

/// The key of the mod's own name in its texts: the Mods screen, the join
/// dialog and the status show it in the player's language, and the
/// manifest's `name` where the texts lack it.
///
/// # Examples
///
/// ```
/// use enshwick::i18n::{Language, MOD_NAME, Texts};
///
/// let texts = Texts::parse("[en]\n\"mod.name\" = \"Better Altars\"\n[uk]\n\"mod.name\" = \"Кращі олтарі\"\n")?;
/// assert_eq!(texts.get(MOD_NAME, Language::UK_UA), Some("Кращі олтарі"));
/// # Ok::<(), enshwick::Off>(())
/// ```
pub const MOD_NAME: &str = "mod.name";

/// The key of the sentence on what the mod does in its texts, shown as
/// [`MOD_NAME`] is, the manifest's `description` where the texts lack it.
///
/// # Examples
///
/// ```
/// assert_eq!(enshwick::i18n::MOD_DESCRIPTION, "mod.description");
/// ```
pub const MOD_DESCRIPTION: &str = "mod.description";

/// A mod's texts by language and key.
///
/// # Examples
///
/// ```
/// use enshwick::i18n::{Language, Texts};
///
/// let texts = Texts::parse("[en]\ngreeting = \"Hello\"\n[uk]\ngreeting = \"Привіт\"\n")?;
/// assert_eq!(texts.get("greeting", Language::UK_UA), Some("Привіт"));
/// assert_eq!(texts.get("greeting", Language::DE_DE), Some("Hello"));
/// # Ok::<(), enshwick::Off>(())
/// ```
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct Texts {
    by_language: FxHashMap<Language, BTreeMap<String, String>>,
}

impl Texts {
    /// Texts from TOML: a table per language code, keys to texts.
    ///
    /// # Errors
    ///
    /// [`Off`] for malformed TOML, an unknown language code or a value that
    /// is not text.
    ///
    /// # Examples
    ///
    /// See [`Texts`].
    pub fn parse(toml: &str) -> Result<Self, Off> {
        let tables: BTreeMap<String, BTreeMap<String, String>> =
            toml::from_str(toml).map_err(|e| Off::new(format!("texts: {}", e.message())))?;
        let mut texts = Self::default();
        for (code, entries) in tables {
            let language = Language::from_code(&code)
                .ok_or_else(|| Off::new(format!("texts: unknown language {code:?}")))?;
            texts
                .by_language
                .entry(language)
                .or_default()
                .extend(entries);
        }
        Ok(texts)
    }

    /// Adds `other`'s texts over these.
    ///
    /// # Examples
    ///
    /// ```
    /// use enshwick::i18n::{Language, Texts};
    ///
    /// let mut texts = Texts::parse("[en]\na = \"A\"\n")?;
    /// texts.merge(Texts::parse("[en]\na = \"B\"\n")?);
    /// assert_eq!(texts.get("a", Language::FALLBACK), Some("B"));
    /// # Ok::<(), enshwick::Off>(())
    /// ```
    pub fn merge(&mut self, other: Self) {
        for (language, entries) in other.by_language {
            self.by_language
                .entry(language)
                .or_default()
                .extend(entries);
        }
    }

    /// The text of `key` in `language`, else in English.
    ///
    /// # Examples
    ///
    /// See [`Texts`].
    #[must_use]
    pub fn get(&self, key: &str, language: Language) -> Option<&str> {
        let find = |language| {
            self.by_language
                .get(&language)
                .and_then(|entries| entries.get(key))
                .map(String::as_str)
        };
        find(language).or_else(|| find(Language::FALLBACK))
    }

    /// The text of `key` in `language` with each `{name}` in it replaced by
    /// the value `args` pairs with `name`; the key itself when no language
    /// has a text for it, so a missing text shows rather than vanishes.
    ///
    /// # Examples
    ///
    /// ```
    /// use enshwick::i18n::{Language, Texts};
    ///
    /// let texts = Texts::parse("[en]\nupdate = \"{name}: {from} to {to}\"\n")?;
    /// let line = texts.fill("update", Language::UK_UA, &[("name", "Lanterns"), ("from", "0.1.0"), ("to", "0.2.0")]);
    /// assert_eq!(line, "Lanterns: 0.1.0 to 0.2.0");
    /// assert_eq!(texts.fill("missing", Language::FALLBACK, &[]), "missing");
    /// # Ok::<(), enshwick::Off>(())
    /// ```
    #[must_use]
    pub fn fill(&self, key: &str, language: Language, args: &[(&str, &str)]) -> String {
        let text = self.get(key, language).unwrap_or(key);
        let mut out = String::with_capacity(text.len());
        let mut rest = text;
        while let Some(open) = rest.find('{') {
            out.push_str(&rest[..open]);
            let after = &rest[open + 1..];
            let value = after.find('}').and_then(|close| {
                let name = &after[..close];
                args.iter()
                    .find(|(arg, _)| *arg == name)
                    .map(|(_, value)| (*value, close))
            });
            if let Some((value, close)) = value {
                out.push_str(value);
                rest = &after[close + 1..];
            } else {
                out.push('{');
                rest = after;
            }
        }
        out.push_str(rest);
        out
    }

    /// The texts as TOML, a table per language code, as [`Texts::parse`]
    /// reads them.
    ///
    /// # Examples
    ///
    /// ```
    /// use enshwick::i18n::Texts;
    ///
    /// let texts = Texts::parse("[uk]\ngreeting = \"Привіт\"\n")?;
    /// assert_eq!(Texts::parse(&texts.to_toml())?, texts);
    /// # Ok::<(), enshwick::Off>(())
    /// ```
    #[must_use]
    pub fn to_toml(&self) -> String {
        let tables: BTreeMap<&str, &BTreeMap<String, String>> = self
            .by_language
            .iter()
            .map(|(language, entries)| (language.code(), entries))
            .collect();
        toml::to_string(&tables).unwrap_or_default()
    }

    /// Every language with a text for `key`, and the text, in no set order.
    ///
    /// # Examples
    ///
    /// ```
    /// use enshwick::i18n::Texts;
    ///
    /// let texts = Texts::parse("[en]\ngreeting = \"Hello\"\n[uk]\ngreeting = \"Привіт\"\n")?;
    /// let mut all: Vec<&str> = texts.translations("greeting").map(|(_, text)| text).collect();
    /// all.sort_unstable();
    /// assert_eq!(all, ["Hello", "Привіт"]);
    /// # Ok::<(), enshwick::Off>(())
    /// ```
    pub fn translations<'a>(
        &'a self,
        key: &'a str,
    ) -> impl Iterator<Item = (Language, &'a str)> + 'a {
        self.by_language
            .iter()
            .filter_map(move |(&language, entries)| {
                entries.get(key).map(|t| (language, t.as_str()))
            })
    }

    /// Every language with texts of its own, in the order of
    /// [`Language::ALL`]: the set a test of the texts iterates, so a new
    /// language is a new table in the file and no change to the test.
    ///
    /// # Examples
    ///
    /// ```
    /// use enshwick::i18n::{Language, Texts};
    ///
    /// let texts = Texts::parse("[uk]\na = \"А\"\n[en]\na = \"A\"\n")?;
    /// let languages: Vec<Language> = texts.languages().collect();
    /// assert_eq!(languages, [Language::FALLBACK, Language::UK_UA]);
    /// # Ok::<(), enshwick::Off>(())
    /// ```
    pub fn languages(&self) -> impl Iterator<Item = Language> + '_ {
        Language::ALL
            .iter()
            .copied()
            .filter(|language| self.by_language.contains_key(language))
    }

    /// Each language paired with each key another language has a text for
    /// and it lacks, sorted by language as [`languages`](Self::languages)
    /// gives them, then by key; empty when every language has every text.
    ///
    /// # Examples
    ///
    /// ```
    /// use enshwick::i18n::{Language, Texts};
    ///
    /// let texts = Texts::parse("[en]\na = \"A\"\nb = \"B\"\n[uk]\na = \"А\"\n")?;
    /// assert_eq!(texts.untranslated(), [(Language::UK_UA, "b")]);
    /// # Ok::<(), enshwick::Off>(())
    /// ```
    #[must_use]
    pub fn untranslated(&self) -> Vec<(Language, &str)> {
        let keys: std::collections::BTreeSet<&str> = self
            .by_language
            .values()
            .flat_map(|entries| entries.keys().map(String::as_str))
            .collect();
        self.languages()
            .flat_map(|language| {
                let entries = &self.by_language[&language];
                keys.iter()
                    .filter(|key| !entries.contains_key(**key))
                    .map(move |&key| (language, key))
            })
            .collect()
    }
}

/// The texts each mod, or each data pack in the loader's copy of the
/// API, handed the loader so far.
static HANDED: crate::fresh::Fresh<std::sync::Mutex<Vec<(crate::abi::ModHandle, Texts)>>> =
    crate::fresh::Fresh::new();

impl Load<'_> {
    /// The mod's texts: `embedded`, usually `include_str!("texts.toml")`,
    /// with `mod-configs/<id>.texts.toml` over it when the server has one.
    /// The loader keeps them too, to label the mod's settings on the Mods
    /// screen: `config.<field>` (or the field's `text` key) for a row,
    /// `<key>.doc` for its description and `<key>.<choice>` for a choice.
    ///
    /// # Errors
    ///
    /// [`Off`] when either file is malformed.
    ///
    /// # Examples
    ///
    /// ```
    /// fn init(load: &mut enshwick::Load<'_>) -> Result<(), enshwick::Off> {
    ///     let texts = load.texts("[en]\n\"locker.name\" = \"Locker\"\n")?;
    ///     let _ = texts;
    ///     Ok(())
    /// }
    /// ```
    pub fn texts(&mut self, embedded: &str) -> Result<Texts, Off> {
        let mut texts = Texts::parse(embedded)?;
        let data = self.data_dir()?;
        // `<game>/mod-data/<id>` beside `<game>/mod-configs/`.
        let overrides = data
            .file_name()
            .zip(data.parent().and_then(std::path::Path::parent))
            .map(|(id, game)| {
                game.join("mod-configs")
                    .join(format!("{}.texts.toml", id.to_string_lossy()))
            });
        if let Some(path) = overrides {
            match std::fs::read_to_string(&path) {
                Ok(text) => texts.merge(
                    Texts::parse(&text)
                        .map_err(|off| Off::new(format!("{}: {off}", path.display())))?,
                ),
                Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
                // Such as a file saved as UTF-16 or in a code page.
                Err(error) => return Err(Off::new(format!("{}: {error}", path.display()))),
            }
        }
        let api = self.host().api();
        // The loader keeps the last texts it was given, so it gets all
        // of this mod's, a pack's added to the mod's own.
        let me = self.host().handle();
        let mut handed = HANDED.get_or_init(std::sync::Mutex::default).relock();
        let all = if let Some((_, kept)) = handed.iter_mut().find(|(owner, _)| *owner == me) {
            kept.merge(texts.clone());
            kept.to_toml()
        } else {
            handed.push((me, texts.clone()));
            texts.to_toml()
        };
        let _kept = (api.texts)(me, crate::abi::Str::new(&all));

        Ok(texts)
    }

    /// Gives each game tag the translations of its key, for every language
    /// that has one: `(key, tag)` pairs, such as an item's name tag, each
    /// tag the mod's own content id.
    ///
    /// # Errors
    ///
    /// [`Off`] when the loader refuses a tag's id (see [`Load::declare`]) or
    /// a key has no text at all.
    ///
    /// # Examples
    ///
    /// ```
    /// use enshwick::content::Id;
    ///
    /// const LOCKER_NAME: Id = Id::new("you.lockers:locker.name");
    ///
    /// fn init(load: &mut enshwick::Load<'_>) -> Result<(), enshwick::Off> {
    ///     let texts = load.texts("[en]\n\"locker.name\" = \"Locker\"\n[uk]\n\"locker.name\" = \"Шафка\"\n")?;
    ///     load.add_texts(&texts, &[("locker.name", LOCKER_NAME)])
    /// }
    /// ```
    pub fn add_texts(&mut self, texts: &Texts, tags: &[(&str, Id)]) -> Result<(), Off> {
        for &(key, tag) in tags {
            let tag = self.declare(tag)?;
            let mut any = false;
            for (language, text) in texts.translations(key) {
                self.add_text(tag, language, text)?;
                any = true;
            }
            if !any {
                return Err(Off::new(format!("texts: no text for {key:?}")));
            }
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn every_language_round_trips_through_its_code() {
        for &language in Language::ALL {
            assert_eq!(Language::from_code(language.code()), Some(language));
        }
        assert_eq!(Language::from_code("PT-BR"), Some(Language::PT_BR));
        assert_eq!(Language::from_code("xx"), None);
    }

    #[test]
    fn placeholders_take_their_values_and_others_stay() {
        let texts =
            Texts::parse("[en]\na = \"{x} and {y} and {unknown} and {\"\n[uk]\na = \"{y}, {x}\"\n")
                .unwrap();
        let args = [("x", "1"), ("y", "{x}")];
        assert_eq!(
            texts.fill("a", Language::FALLBACK, &args),
            "1 and {x} and {unknown} and {"
        );
        assert_eq!(texts.fill("a", Language::UK_UA, &args), "{x}, 1");
    }

    #[test]
    fn unknown_languages_and_non_text_values_are_errors() {
        assert!(Texts::parse("[xx]\na = \"b\"\n").is_err());
        assert!(Texts::parse("[en]\na = 1\n").is_err());
    }
}