haqumei 0.8.0

use crate::utils::default_is_non_pause_symbol;

/// `Haqumei` の設定。
/// 詳細は、それぞれのフィールドのドキュメントを見てください。
#[derive(Debug, Clone, Copy)]
pub struct HaqumeiOptions {
    /// 入力テキストを [UnicodeNormalization] の指定された方法で正規化する。
    /// 「か + 濁点」などの結合文字を1文字の「が」に統合できます。
    ///
    /// デフォルトで無効になっています。
    pub normalize_unicode: UnicodeNormalization,

    /// この値が true の場合、発音表記 (`pron`) が文字表記 (`read`) によって上書きされます。
    ///
    /// これにより、長音の自動変換機能が無効化されます。 (e.g., "ジンセー" -> "ジンセイ")
    /// なお、助詞にもこの影響が及び、"は" は「ワ」ではなく「ハ」として、
    /// "へ" は「エ」ではなく「ヘ」として発音されます。
    ///
    /// すなわち、これを有効にした場合、`revert_long_vowels`, `revert_yotsugana` のフラグに関係なく、
    /// 読み (`read`) に強制的に置き換えられます。
    ///
    /// デフォルトで無効になっています。
    pub use_read_as_pron: bool,

    /// 辞書によって自動的に長音化された発音を、元のテキストに忠実な読みに復元するかどうか。
    ///
    /// `true` に設定すると、発音 (`pron`) に「ー」が含まれている単語について、
    /// 元のテキスト (`orig`) に「ー」が含まれていない場合のみ、発音を読み (`read`) の値で上書きします。
    /// (e.g., 「効果」 pron: コーカ -> コウカ / 「人生」 pron: ジンセー -> ジンセイ)
    ///
    /// 助詞 (は、へ、を) などの発音は「ー」を含まないため影響を受けず、
    /// そのまま音声合成に適した発音 (ワ、エ、オ) が維持されます。
    ///
    /// デフォルトで無効になっています。
    pub revert_long_vowels: bool,

    /// 現代仮名遣いにおいて発音上統合される四つ仮名 (ヅ・ヂ) を、
    /// 元のテキスト通りの表記に復元するかどうか。
    ///
    /// `true` に設定すると、発音 (`pron`) において「ズ」「ジ」に変換されたものを、
    /// 読み (`read`) に基づいて「ヅ」「ヂ」に復元します。
    /// (e.g., 「気づかず」 pron: キズカズ -> キヅカズ / 「鼻血」 pron: ハナジ -> ハナヂ)
    ///
    /// デフォルトで無効になっています。
    pub revert_yotsugana: bool,

    /// 形態素解析辞書の仕様により「イウ」と「ユウ」のどちらに解析されるか不定な
    /// 動詞「言う」 (およびその活用形や複合語) の読み・発音を、指定した方に強制的に統一します。
    ///
    /// 辞書には「言う」に対して「イウ」「ユウ」の両方が登録されており、
    /// 形態素解析のコスト計算によって出力が変動します。
    /// `Some` を指定することで、解析結果に関わらず意図した発音に固定できます。
    ///
    /// デフォルトは `None` (形態素解析辞書の出力結果をそのまま使用する) です。
    pub normalize_iu: Option<IuPronunciation>,

    /// - フィラーが acc > mora_size のときに、平版型 (acc = 0) にする
    /// - フィラー直後の形態素が名詞だったとき、その前のフィラーに結合しない (chain_flag = 0) ようにする
    ///
    /// デフォルトで有効になっています。
    pub modify_filler_accent: bool,

    /// Nani Predictor を使って、「何」 の読みを修正する。
    ///
    /// デフォルトで有効になっています。
    pub predict_nani: bool,

    /// Kanalizer を使って、英語の読みを予測する。
    ///
    /// デフォルトで有効になっています。
    pub predict_kana_english: bool,

    /// Unidic を使って、漢字の読みを修正する。
    /// 有効にした初回実行時には、辞書のダウンロードが発生します。
    ///
    /// デフォルトで無効になっています。
    pub use_unidic_yomi: bool,

    /// 長母音、重母音、撥音がアクセント核に来た場合に、
    /// ひとつ前のモーラにアクセント核がズレるルールを適用する。
    ///
    /// デフォルトで有効になっています。
    pub retreat_acc_nuc: bool,

    /// 品詞「特殊・マス」の直前に接続する動詞にアクセント核がある場合、アクセント核を「ま」に移動させる。
    ///
    ///   書きます -> か\[きま\]す, 参ります -> ま\[いりま\]す
    ///   書いております -> \[か\]いております
    ///
    /// デフォルトで有効になっています。
    pub modify_acc_after_chaining: bool,

    /// 踊り字 (e.g., 々, ヽ, ヾ) の展開を有効にする。
    ///
    /// デフォルトで有効になっています。
    pub process_odoriji: bool,

    /// `*_detailed` API において、記号に対して `pau` を割り当てるべきか判定する関数を設定するフィールド。
    ///
    /// `true` を返した記号には `pau` が付与されません。
    /// 閉じ括弧に `pau` を割り当てたくないようなケースに使ってください。
    ///
    /// デフォルトでは、以下の表層形に `pau` が割り当てられません。
    /// `「` , `」` , `『` , `』` , ` (` , `) ` , `(` , `)` ,
    /// `【` , `】` , `［` , `］` , `[` , `]` , `〈` , `〉` ,
    /// `《` , `》` , `〔` , `〕` , `｛` , `｝` , `{` , `}` ,
    /// `"` , `'` , `”` , `“` , `’` , `‘`
    ///
    /// # Examples
    ///
    /// ```rust
    /// use haqumei::utils::default_is_non_pause_symbol;
    ///
    /// fn my_custom_pause_rule(s: &str) -> bool {
    ///     if s == "「" {
    ///         return false; // false を返すと pau が割り当てられる
    ///     }
    ///     // それ以外はデフォルトの挙動を継承
    ///     default_is_non_pause_symbol(s)
    /// }
    /// ```
    pub is_non_pause_symbol: fn(&str) -> bool,

    /// 実測データ (rtMRI等の直接的な調音観測) によって裏付けられている、
    /// 比較的信頼性の高い区別のみを上書きして有効化します。
    ///
    /// 以下のオプションが強制的に有効化されます。
    /// - `split_n_allophones = true`
    /// - `split_q_allophones = true`
    /// - `enable_final_glottal_stop = true`
    ///   (Fujimoto, Maekawa & Funatsu (2010) により、語中ジェミネートには
    ///   声門の緊縮がないことが実証されており、語末との区別自体は
    ///   比較的信頼性が高いと判断したため)
    ///
    /// これが `true` である時点で、上記 3 つのオプションは強制的に上書きされることに
    /// 注意してください。
    ///
    /// また、以下のオプションは有効化されません。
    /// 理由については、それぞれのドキュメントを参照してください。
    /// - `split_n_before_r = false`
    /// - `split_n_before_palatal_affricate = false`
    ///
    /// デフォルトで無効になっています。
    pub use_allophones: bool,

    /// 撥音「ン」を後続音素の環境に応じて異音 (allophone) に分岐させるかどうか。
    /// false の場合は従来通り `Nn`(`"N"`) のみを出力します。
    ///
    /// # 詳細
    /// 有効にした場合、後続音素の調音部位に応じて以下の音素に解決されます：
    /// - 両唇音 (p, b, m) の前: `Nm` `[m]`
    ///   (例：サンマ -> s a `[Nm]` m a / テンプラ -> t e `[Nm]` p u r a)
    /// - 軟口蓋音 (k, g) の前: `Ng` `[ŋ]`
    ///   (例：サンカ -> s a `[Ng]` k a / マンガ -> m a `[Ng]` g a)
    /// - 語末または発話境界の前: `Nq` `[ɴ]`
    ///   (例：ホン -> h o `[Nq]`)
    /// - 上記以外の破裂・破擦・鼻・流音 (t, d, ts, n, z, および任意で ch, j, r) の前: `Nd` `[n]`
    ///   (例：サンタ -> s a `[Nd]` t a / カンジ -> k a `[Nd]` j i)
    ///
    /// ※ 母音、半母音 (y, w)、無声摩擦音 (s, sh, h, f)、有声摩擦音 (v) の前では、
    /// 口腔閉鎖を伴わない「鼻音化母音」として現れるのが多いため、
    /// 分岐せず従来通り `Nn` を出力します。
    ///
    /// # この環境 (s, h, j, w 前) をさらにオプション化していない理由
    ///
    /// Maekawa (2023, JIPA 53(1): 189-212) の実測では、この環境
    /// (`[ç]` (hの口蓋化異音、hi・hyaなど)、`[j]` (半母音 y)、`[s]` の前) において、
    /// 少数のトークンが実際に鼻音閉鎖を伴って発音されることも報告されています。
    /// しかし、これは後続音素という環境だけでは決まらない、トークンごとの
    /// 自由変異 (おそらく話速・くだけ具合等に依存する確率的な変異) であり、
    /// 特定の環境で体系的に閉鎖が生じるわけではありません。
    ///
    /// 「この環境では常に鼻音閉鎖として解決する」という決定論的なフラグを
    /// 追加すると、実際には多数派ではない振る舞いを全トークンに強制する
    /// ことになり、現状の「常に `Nn` のまま」よりもむしろ実態から離れて
    /// しまいます。z/dz の破擦化 (Maekawa 2010) やガ行鼻濁音と同様、
    /// 「環境で決まる離散的な異音」ではなく「トークンごとに揺れる確率的な
    /// 変異」に分類されるため、本ライブラリでは一貫してこの種の現象を
    /// 専用ラベルに切り出さず、音響モデルに委ねる設計判断を取っています。
    ///
    /// なお、Maekawa (2023) 自身も結論部において、語末 /N/ の変異を
    /// "直前母音によって調音位置を書き換える離散的な異音規則" として説明
    /// するべきではないと明言しており (/N/ の調音位置の分布が相当に重なり
    /// 合っているため)、本ライブラリの設計判断と一致しています。さらに、
    /// 同論文の統計分析 (反復対比による GLMM検定) では、隣接する母音水準
    /// のうち i-e 間および u-a 間には有意差がある一方、e-u 間および a-o 間
    /// には有意差が見られませんでした。つまり統計的に意味のある区分は、
    /// 前舌 (i, e) / 後舌 (u, a, o) という伝統的な2分法ではなく、
    /// 「{i} / {e, u} / {a, o}」という3水準のグルーピングに近いことを
    /// 示しています。
    ///
    /// # 設計上の注意 (チ前 / r前の統合について)
    ///
    /// 伝統的な記述 (Vance 2008 等) にある「チの前の硬口蓋化的な性質」や
    /// 「rの前の調音点のわずかなずれ (`[n̺]` や `[n̠]` 等)」は、リアルタイムMRI
    /// による実測データ (Maekawa 2023; JIPA 53(1):189-212) において、r
    /// および ch (`[tɕ]`) が他の歯茎音 (t, d, ts, n, z) と同一クラスタ
    /// (Alveolar) として観察されており、物理的な調音位置の差が検出できない
    /// ため、デフォルトでは `Nd` に統合されます (`split_n_before_r` /
    /// `split_n_before_palatal_affricate` で個別に分離可能)。
    /// なお j (`[dʑ]`) については、同論文の当該クラスタ分類に明示的な記載が
    /// なく、Alveolarへの統合を直接支持する実測根拠は確認できていません。
    /// chと同じ統合先 (`Npl`) を共有させているのは、音韻的な対応関係 (チ・
    /// ジが共に同じ口蓋化の系列をなすという伝統的扱い) に基づく簡略化で
    /// あり、jについてはこの章で述べたrtMRIの直接的裏付けがない点に注意
    /// してください。
    ///
    /// また、語末の `Nq` を直前母音の前後性によって離散的に二値化する規則
    /// も、実際には連続的な調音位置の変動であることが示されているため、
    /// 本オプションでは単一の `Nq` として出力します。
    ///
    /// デフォルトで無効になっています。
    pub split_n_allophones: bool,

    /// `split_n_allophones == true` のとき、流音 r/ry の前の撥音「ン」を、
    /// `Nd` (`[n]`) からさらに分離して専用の `Nr` `[n̠]` (後部歯茎鼻音) として
    /// 出力するかどうか。false の場合は r/ry の前も `Nd` に統合されます。
    /// `split_n_allophones == false` のときは無視されます (`Nn` のまま)。
    ///
    /// # 詳細
    ///
    /// 有効にした場合：
    /// - r, ry の前: `Nr` `[n̠]`
    ///   (例：サンライ -> s a `[Nr]` r a i)
    ///
    /// 無効 (デフォルト) の場合：
    /// - r, ry の前: `Nd` `[n]`
    ///   (例：サンライ -> s a `[Nd]` r a i)
    ///
    /// # `Nr` が分離されている理由
    ///
    /// 伝統的・印象論的な記述では、r の前の撥音は t/d/n の前とは調音点が
    /// わずかに異なるとされますが、その説明は論者によって異なります。
    /// Vance (2008: 97) は尖端歯茎 `[n̺]` としており、これは t/d/n の前
    /// (舌の "面" で作る lamino-alveolar) とは異なり、舌先 (apex) で作る
    /// という構えの違いとしての区別であって、調音点自体を前後に
    /// ずらす記述ではありません。一方で、Okada (1999: 118) は後部歯茎 `[n̠]`
    /// としており、調音点自体を後方にずらす記述です。
    ///
    /// しかし、直接的な観測データである Maekawa (2023, JIPA 53(1):
    /// 189-212) の rtMRI 計測では、語中撥音の後続子音による分類において
    /// r は t, d, ts, tɕ, n, z と同一の "Alveolar" クラスタにまとめられて
    /// おり、他の歯茎音と物理的に分離した閉鎖位置を示していません。
    ///
    /// なお、「rの前では調音点が後方にずれる」という伝統的記述の前提である
    /// 「/r/が後部歯茎音である」という記述自体も、rtMRI実測
    /// (Maekawa, ICPhS 2023) によって否定されています。同研究では、
    /// 日本語/r/の167サンプル全件が tap 調音であり (flap は観測されず)、
    /// 調音位置も後部歯茎ではなく歯茎域 (/s/ と同等範囲) に収まることが
    /// 確認されています。さらに/r/の正確な調音位置は固定的でなく、
    /// 隣接母音によって多くのケースで決定されるという、/r/ 自体の調音的な未指定
    /// 性も報告されており、「rの前の/N/が安定した後部歯茎的調音点を持つ」
    /// という前提はさらに弱いと考えられます。
    ///
    /// つまりこの区別は、聴覚印象としては複数の論者により報告はされている
    /// ものの、現時点で直接的な観測の裏付けを欠いています。本ライブラリ
    /// では信頼度の低いオプションとして無効をデフォルトとしつつ、伝統的な
    /// 記述や既存の狭い音声表記資料との対応を取りたい用途のために選択
    /// 可能な形で残しています。
    ///
    /// デフォルトで無効になっています。
    pub split_n_before_r: bool,

    /// `split_n_allophones == true` のとき、破擦音 ch, j の前の撥音「ン」を、
    /// `Nd` (`[n]`) からさらに分離して専用の `Npl` `[ɲ]` (硬口蓋鼻音) として
    /// 出力するかどうか。false の場合は ch, j の前も `Nd` に統合されます。
    /// `split_n_allophones == false` のときは無視されます (`Nn` のまま)。
    ///
    /// # 詳細
    ///
    /// 有効にした場合：
    /// - ch, j の前: `Npl` `[ɲ]`
    ///   (例：サンチョウ -> s a `[Npl]` ch o u / カンジ -> k a `[Npl]` j i)
    ///
    /// 無効 (デフォルト) の場合：
    /// - ch, j の前: `Nd` `[n]`
    ///   (例：サンチョウ -> s a `[Nd]` ch o u / カンジ -> k a `[Nd]` j i)
    ///
    /// # `Npl` が分離されている理由
    ///
    /// `split_n_before_r` と同様の理由で、伝統的な記述では、チ・ジ
    /// (`[tɕ]`, `[dʑ]`) の前の撥音を歯茎音グループから明確に分けて硬口蓋
    /// (歯茎硬口蓋) 鼻音 `[ɲ]` として扱うことが広く行われています。
    /// 例えば Vance (2008: 96, 99) は、より狭い表記でこれを `[ɲ̟]` として
    /// 記述しています。
    ///
    /// しかし、直接的な Maekawa (2023, JIPA 53(1): 189-212) の rtMRI
    /// 計測では、後続子音 `[tɕ]` (ch) は他の歯茎音 (t, d, ts, n, r, z) と
    /// 同じ "Alveolar" に分類されており、物理的に分離した閉鎖位置として
    /// は観測されていません。なお j (`[dʑ]`) については、同論文の当該
    /// クラスタ分類に明示的な記載がなく、rtMRI による直接の検証情報は
    /// ありません。本オプションが ch と j を同じ `Npl` に統合しているのは、
    /// 「チ・ジは共に同じ口蓋化の系列をなす」という伝統的な音韻的対応
    /// 関係に基づく類推であり、j 側の扱いについては chほど強い実測的
    /// 裏付けがない点に留意してください。
    ///
    /// 聴覚印象上の口蓋化と、実際の閉鎖位置の物理的な差は必ずしも一致
    /// しないため、本ライブラリでは信頼性の低いオプションとして無効を
    /// デフォルトにしつつ、伝統的な記述との対応を取りたい用途のために
    /// 選択可能な形で残しています。
    ///
    /// デフォルトで無効になっています。
    pub split_n_before_palatal_affricate: bool,

    /// 語中における促音「ッ」を、後続子音の性質に応じて専用の異音
    /// (`ClP`/`ClT`/`ClK`/`ClS`/`ClV`) に分岐させるかどうか。
    /// (語末・感嘆表現の「ッ」は対象外です。[HaqumeiOptions::enable_final_glottal_stop] を参照してください)
    /// false の場合は従来通り `Cl` のみを出力します。
    ///
    /// # 詳細
    ///
    /// 有効にした場合、以下の音素に解決されます：
    /// - 無声破裂音・破擦音の前: `ClP` (p前), `ClT` (t, ts, ch前), `ClK` (k前)
    ///   - 無音の閉鎖区間として発音される
    ///     (例：キップ -> k i `[clp]` p u / キッテ -> k i `[clt]` t e / ガッコウ -> g a `[clk]` k o o)
    /// - 摩擦が継続する音 (s, sh, f, h、および有声摩擦音 v) の前: `ClS`
    ///   - 無音ではなく摩擦エネルギーが1モーラ分継続する
    ///     (例：ハッサイ -> h a `[cls]` s a i / ザッシ -> z a `[cls]` sh i)
    /// - 有声閉鎖・破擦音 (b, d, g, z, j) の前: `ClV`
    ///   - 閉鎖中も声帯振動が継続する。主に外来語、または和語の一部強調形
    ///     (「すごい→すっごい」等) に限られる
    ///     (例：バッグ -> b a `[clv]` g u / ベッド -> b e `[clv]` d o)
    ///
    /// # `v` の分類について
    ///
    /// 唯一の有声摩擦音である `v` は、`ClV` (有声閉鎖) ではなく `ClS`
    /// (摩擦継続) に分類しています。促音が「無音区間になるか、音響エネルギー
    /// が継続するか」を決めるのは声帯振動の有無ではなく、閉鎖か摩擦かで
    /// 判断するべきだとしているからです。
    /// `ClV` という名称が示す「閉鎖」を、そもそも口腔閉鎖を持たない
    /// `v` に当てるのは整合しません。
    ///
    /// なお `z` は同じ有声阻害音ですが、撥音・促音の
    /// 後では破擦音 `[dz]` として発音される傾向が強い (例：グッズ `[guddzu]`)
    /// ため、閉鎖を持つ阻害音として `ClV` に残しています。
    ///
    /// "ッヴ" 自体は実例をほぼ確認できないほど稀な組み合わせであり、
    /// 一貫性を優先したものであって実証的な裏付けはありません。
    ///
    /// デフォルトで無効になっています。
    pub split_q_allophones: bool,

    /// 語末や感嘆表現における、後続子音を伴わない促音「ッ」 (「あっ！」
    /// 「うっ」等) を、単なる無音やフレーズ境界ではなく、専用の声門閉鎖音
    /// `ClQ` `[ʔ]` として検出・出力するかどうか。false の場合は従来通り `Cl`
    /// のみを出力します。`split_q_allophones` の値とは独立に動作します。
    ///
    /// # 詳細
    ///
    /// 語中の促音 (ジェミネート) とは異なり、語末の「ッ」は後続音素が
    /// 存在しないため、本オプションを有効にしない限り、音響モデル側で
    /// 「意図的な声門閉鎖」であることを周辺のコンテキストから判別・予測
    /// することができません。セリフや感情表現における「息の急激な停止
    /// (1モーラ分の声門閉鎖と、それに伴う開放)」を音響モデルに明示的に
    /// 学習させるために有用な、独立したオプションです。
    ///
    /// なお `ClQ` が表すのは、直前母音の末尾に生じる連続的な音質変化
    /// ではなく、**離散的な無音区間＋声門破裂`[ʔ]`** です。
    /// 混同しないよう注意する必要があります。
    ///
    /// # 語中ジェミネートと明確に区別する根拠
    ///
    /// 高速度デジタルビデオ撮影と光電声門図 (PGG) を用いた
    /// Fujimoto, Maekawa & Funatsu (2010, INTERSPEECH) の観測
    /// (東京方言の男性話者1名による予備的研究) により、後続に阻害音がある通常の語中
    /// 促音 (ジェミネート) の発音中には、声門の明確な収縮・緊張は見られない
    /// ことが報告されています。(むしろ促音全般において、対応する単音より
    /// わずかに声門が広く開く傾向が観測されており、これは声門化とは逆方向の現象です)
    ///
    /// なお、閉鎖音や破擦音の促音においては、声門の開閉そのものには収縮が見られない
    /// ものの、光電声門図で「開大の軌跡に中断が生じる」「直前母音の声帯振動がより速く
    /// 停止する」という微細な差異が検出されています。これは口腔内の閉鎖動作の
    /// 速さ・強さの違いを反映している可能性が指摘されています (なお、この中断現象は
    /// 摩擦音が後続する促音では観測されていません)。
    ///
    /// したがって「ッ」という同一の表記であっても、語中 (口腔内の閉鎖・
    /// 摩擦) と語末 (声門閉鎖) ではまったく異なる発声器官のジェスチャーが
    /// 用いられており、これを明示的に分けることには一定の音声学的妥当性が
    /// あります。逆に言えば、本オプションが無効な場合、`Cl` というラベルは
    /// 「語中の声門化を伴わない閉鎖」と「語末の声門破裂」という、物理的に
    /// 別種のジェスチャーを一つのシンボルに混在させたまま出力することに
    /// なる点に留意してください。
    ///
    /// デフォルトで無効になっています。
    pub enable_final_glottal_stop: bool,
}

impl Default for HaqumeiOptions {
    fn default() -> Self {
        Self {
            normalize_unicode: UnicodeNormalization::None,
            use_read_as_pron: false,
            revert_long_vowels: false,
            revert_yotsugana: false,
            normalize_iu: None,
            modify_filler_accent: true,
            predict_nani: true,
            predict_kana_english: true,
            use_unidic_yomi: false,
            retreat_acc_nuc: true,
            modify_acc_after_chaining: true,
            process_odoriji: true,
            is_non_pause_symbol: default_is_non_pause_symbol,
            use_allophones: false,
            split_n_allophones: false,
            split_n_before_r: false,
            split_n_before_palatal_affricate: false,
            split_q_allophones: false,
            enable_final_glottal_stop: false,
        }
    }
}

/// 入力テキストをどのように正規化するかを指定します。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum UnicodeNormalization {
    /// 正規化を行わない (デフォルト)
    #[default]
    None,
    /// NFC (正準等価性による合成: 結合文字の合体のみ)
    Nfc,
    /// NFKC (互換等価性による分解と合成: 半角カナ -> 全角カナ、全角英数 -> 半角英数など)
    Nfkc,
}

/// 動詞「言う」およびその派生語の発音・読みをどのように正規化するかを指定します。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum IuPronunciation {
    /// すべての「言う」「いう」を「イウ」に統一します。
    Iu,
    /// すべての「言う」「いう」を「ユウ」に統一します。
    Yuu,
    /// 漢字表記 (`言う`, `云う`) が含まれる場合のみ「イウ」に統一し、
    /// 平仮名表記 (`いう`, `そういう`) は辞書の解析結果をそのまま使用します。
    KanjiIu,
    /// 漢字表記 (`言う`, `云う`) が含まれる場合のみ「ユウ」に統一し、
    /// 平仮名表記 (`いう`, `そういう`) は辞書の解析結果をそのまま使用します。
    KanjiYuu,
}