msime_engine/session/options.rs
1//! The public option and snapshot values of `Session` (`include/metasequoia/session.h`). Shared by the session, the nine-key session, the host facade and the golden harness.
2
3use std::path::PathBuf;
4
5use crate::helpcode::SharedKeymap;
6use crate::paths::RuntimePaths;
7use crate::punctuation::PunctuationMarks;
8use crate::types::{
9 CandidateSource, CommandTableEntry, EnglishInputOptions, FrequencyAdjustmentOptions,
10 FuzzyPinyinOptions, LocalInputMode, LocalModeOptions, MentionEntry, MixedExpressiveOptions,
11 PluginCommand, QuickPhraseEntry, SchemeSet, SchemeType, SentenceAssociationOptions,
12 ShuangpinCustomTable, ShuangpinHelpcodeModes, ShuangpinProfileKind, WordItem, WubiInputOptions,
13 DEFAULT_FIRST_PAGE_ROWS,
14};
15use crate::vietnamese::{InputMethod as VietnameseInputMethod, ToneStyle as VietnameseToneStyle};
16
17/// Everything a session is built with. `learning_undo` is gone with the feature.
18#[derive(Debug, Clone, PartialEq)]
19pub struct SessionOptions {
20 pub paths: RuntimePaths,
21 pub scheme: SchemeType,
22 /// 会话允许运行的方案，缺省全部。`scheme` 和之后的 `switch_scheme` 都必须在其中；只为其中的方案构造 provider（见 [`SchemeSet`]）。
23 pub enabled_schemes: SchemeSet,
24 pub shuangpin_profile: ShuangpinProfileKind,
25 /// `shuangpin_profile` 为 `Custom` 时的键位表。没有它或它不合法时，会话里有双拼就建不起来（`INVALID_CUSTOM_SHUANGPIN_PROFILE`），没有双拼就按小鹤；内置方案不读它。
26 pub shuangpin_custom_profile: Option<ShuangpinCustomTable>,
27 /// Shuangpin preedit shows the typed keys rather than the decoded quanpin.
28 pub shuangpin_preedit_uses_raw: bool,
29 /// How the Vietnamese scheme spells marks: Telex letters or VNI digits.
30 pub vietnamese_input_method: VietnameseInputMethod,
31 /// Where the Vietnamese scheme puts the tone on `oa`, `oe` and `uy`.
32 pub vietnamese_tone_style: VietnameseToneStyle,
33 /// 韩语实体键盘布局，缺省两套式。
34 pub korean_layout: crate::KoreanLayout,
35 /// Where `msime-cantonese.db` is; empty when the host has none. Read only when Cantonese is activated, which fails without it.
36 pub cantonese_dictionary: PathBuf,
37 /// 独立粤语双拼入口强制按两键码解释，普通粤拼入口仍按现有规则自动识别。
38 pub force_cantonese_shuangpin: bool,
39 /// Where `msime-zhuyin.db` is; empty when the host has none. Read only when Zhuyin is activated, which fails without it.
40 pub zhuyin_dictionary: PathBuf,
41 /// Where `msime-stroke.db` is; empty when the host has none. Read only when Stroke is activated, which fails without it.
42 pub stroke_dictionary: PathBuf,
43 /// `msime-japanese.dat` 的位置；为空时读资源目录里的那份。文件缺失时日文只给假名行。
44 pub japanese_dictionary: PathBuf,
45 pub helpcode_schema: String,
46 /// 辅助码前导标点；None 保留现有 Shift 加字母。
47 pub helpcode_trigger_key: Option<u8>,
48 /// 宿主给的辅助码表；有它时直接装上它，不再按 `helpcode_schema` 读表（名字仍然要合法）。`Session::set_helpcode_table` 可以实时替换。
49 pub helpcode_table: Option<SharedKeymap>,
50 /// 内置辅助码表缺失时使用的随包资源根目录。
51 pub helpcode_fallback_resources: Option<PathBuf>,
52 /// `autocorrect_type` bits; 0 keeps the user's spelling. Either of transposition and neighbor also enables missing and extra letters, and on inputs of three or more complete syllables offers a sentence that reads one syllable as a typo. Committing the raw letters while a correction is offered turns correction off for that exact input.
53 pub autocorrect_types: u32,
54 pub helpcode: bool,
55 /// 一码辅助码严格筛选，默认关闭以保持原有重排行为。
56 pub strict_quanpin_helpcode: bool,
57 /// 双拼辅助码的触发方式（Windows `[helpcode]` 组的双拼专属键）；只在双拼方案下生效。
58 pub shuangpin_helpcode_modes: ShuangpinHelpcodeModes,
59 pub chinese_punctuation: bool,
60 pub paired_punctuation: bool,
61 /// 0 follows the mode, 1 forces Chinese, 2 forces ASCII.
62 pub punctuation_lock: i32,
63 /// 中文标点下引号键和方头括号键出哪一组字，缺省是弯引号、实心括号。
64 pub punctuation_marks: PunctuationMarks,
65 pub learning: bool,
66 /// 回车上屏英文拼写时是否把它学进英文词库（Windows `input.enter_learns_english_word`，出厂为开）。
67 pub learn_english_on_enter: bool,
68 /// Hand back every whole-sentence reading instead of only the best. A host that sets this must reorder and crop them itself.
69 pub sentence_alternatives: bool,
70 /// 宿主的每页候选数（`candidate_page_size`）：全长组的精确同音词够这么多行就不再并入更长的补全词。0 到请求里会归一成 1。
71 pub first_page_rows: usize,
72 /// 只出单字：中文方案的候选去掉含汉字的词和整句、只留单个汉字（见 [`SchemeType::filters_to_single_characters`]），选一个字后剩下的拼写接着组字。
73 pub single_character_only: bool,
74 /// 移动光标后编辑光标后的部分（默认关）：全拼、双拼的组字光标停在中间时，光标前的原文固定为它当前的最佳转换，候选是光标后那段原文的候选，首选前面接上固定的部分；选中一条只消耗它的音节，固定部分和已选部分一起留到组字结束。规则见 `session/caret_edit.rs`。
75 pub caret_edit_suffix: bool,
76 pub fuzzy_pinyin: FuzzyPinyinOptions,
77 pub frequency: FrequencyAdjustmentOptions,
78 pub local_modes: LocalModeOptions,
79 /// 候选混输总开关（Windows `utility.mixed_candidates`）：关掉后英文、emoji、颜文字、符号、日文混输行、行内日期时间和快捷短语都不再混进普通候选；各分成员（`english.mixed_candidates`、`expressive.*`、`local_modes.*`）原值保留，重新打开即恢复。本地模式本身（T、K、M 等）不受影响。
80 pub mixed_candidates: bool,
81 pub english: EnglishInputOptions,
82 pub expressive: MixedExpressiveOptions,
83 /// 日文混输（实验选项，默认关）：全拼、双拼组字时，整段输入像日文罗马字就混进一行日文转换（来源 `MixedJapanese`），见 `ImeSession::mixed_japanese_conversion`。需要会话带日文（`enabled_schemes` 含 `JapaneseRomaji`）和日文模型；开着时建会话就在后台预热模型。
84 pub japanese_mixing: bool,
85 /// 连续多语言输入所选的语言；默认空集合关闭，少于两种不生成混合行。
86 pub multilingual_languages: Vec<crate::multilingual::Language>,
87 pub wubi: WubiInputOptions,
88 /// Learn word sequences and pick pairs; also needs `learning`.
89 pub personal_context: bool,
90 /// 上屏后联想；独立于整句候选，默认关闭。
91 pub next_word_prediction: bool,
92 pub sentence_association: SentenceAssociationOptions,
93 /// Committed text the neural sentence models condition on; `Session::set_rescoring_context` updates it live.
94 pub rescoring_context: String,
95 /// The `/` mode's commands beyond the built-in ones; `Session::set_command_table` replaces it live.
96 pub command_table: Vec<CommandTableEntry>,
97 /// 脚本插件在 `/` 模式里的指令（只在桌面非空）；`Session::set_plugin_commands` 可以实时替换。
98 pub plugin_commands: Vec<PluginCommand>,
99 /// The `@` mode's names and places; `Session::set_mention_entries` replaces it live.
100 pub mention_entries: Vec<MentionEntry>,
101 /// K 模式在数据库行之后追加的宿主短语；`Session::set_quick_phrase_table` 可以实时替换。
102 pub quick_phrase_table: Vec<QuickPhraseEntry>,
103 /// 普通候选是否追加编码匹配的快捷短语。仅 macOS 桌面宿主打开；其他宿主保留独立 K 模式。
104 pub quick_phrase_candidates: bool,
105 /// 快捷短语参与调频：追加进普通候选的整组短语有自己的槽位（`quick_phrase_slots` 日志表），越过它选普通候选让整组后退（最多退到首页末位），选中组内短语让整组前移。关掉时组固定在默认位置（首页最后几格，普通候选不满一页时接在它们之后，见 `default_quick_phrase_slot`），槽位记录保留但不读。
106 pub quick_phrase_frequency: bool,
107 /// 宿主会把候选转成繁体输出：拆字（`C`）行按转换后的字形去重，免得一屏出现两个相同的繁体字。
108 pub chaizi_traditional_output: bool,
109}
110
111impl SessionOptions {
112 /// 引擎库唯一的一套默认值，建在给定路径上。大部分沿用参照实现（session.h:12-54）：全拼、小鹤、学习开、个人上下文开、中文标点和成对标点开、频率按 `FrequencyAdjustmentOptions::default()`。与参照实现不同的只有辅助码：默认关，表名默认 `wubi86`。随仓库的七张辅助码表里只有 `wubi86` 写明了来源与许可（`resources/helpcodes/NOTICE-wubi86.md`），参照实现默认的 `lantian` 和产品默认的 `ziranma` 都没有再分发授权（`resources/helpcodes/NOTICE.md`），引擎库默认不读它们；要辅助码的嵌入方自己打开并选表。
113 ///
114 /// 产品不靠这套默认值：host 门面（`host::options::session_options`）逐字段给出产品取值，golden 基准在 `tests/golden_support` 里按参照实现补回辅助码。
115 pub fn new(paths: RuntimePaths) -> Self {
116 Self {
117 paths,
118 scheme: SchemeType::Quanpin,
119 enabled_schemes: SchemeSet::ALL,
120 shuangpin_profile: ShuangpinProfileKind::Xiaohe,
121 shuangpin_custom_profile: None,
122 shuangpin_preedit_uses_raw: true,
123 vietnamese_input_method: VietnameseInputMethod::Telex,
124 vietnamese_tone_style: VietnameseToneStyle::Modern,
125 korean_layout: crate::KoreanLayout::Dubeolsik,
126 cantonese_dictionary: PathBuf::new(),
127 force_cantonese_shuangpin: false,
128 zhuyin_dictionary: PathBuf::new(),
129 stroke_dictionary: PathBuf::new(),
130 japanese_dictionary: PathBuf::new(),
131 helpcode_schema: "wubi86".to_owned(),
132 helpcode_trigger_key: None,
133 helpcode_table: None,
134 helpcode_fallback_resources: None,
135 autocorrect_types: 0,
136 helpcode: false,
137 strict_quanpin_helpcode: false,
138 shuangpin_helpcode_modes: ShuangpinHelpcodeModes::default(),
139 chinese_punctuation: true,
140 paired_punctuation: true,
141 punctuation_lock: 0,
142 punctuation_marks: PunctuationMarks::default(),
143 learning: true,
144 learn_english_on_enter: true,
145 sentence_alternatives: false,
146 first_page_rows: DEFAULT_FIRST_PAGE_ROWS,
147 single_character_only: false,
148 caret_edit_suffix: false,
149 fuzzy_pinyin: FuzzyPinyinOptions::default(),
150 frequency: FrequencyAdjustmentOptions::default(),
151 local_modes: LocalModeOptions::default(),
152 mixed_candidates: true,
153 english: EnglishInputOptions::default(),
154 expressive: MixedExpressiveOptions::default(),
155 japanese_mixing: false,
156 multilingual_languages: Vec::new(),
157 wubi: WubiInputOptions::default(),
158 personal_context: true,
159 next_word_prediction: false,
160 sentence_association: SentenceAssociationOptions::default(),
161 rescoring_context: String::new(),
162 command_table: Vec::new(),
163 plugin_commands: Vec::new(),
164 mention_entries: Vec::new(),
165 quick_phrase_table: Vec::new(),
166 quick_phrase_candidates: false,
167 quick_phrase_frequency: true,
168 chaizi_traditional_output: false,
169 }
170 }
171}
172
173/// A value copy of the composition; safe to hand to another thread. `candidate_sources`, `candidate_annotations` and `candidate_answers_key` are aligned with `candidates`.
174#[derive(Debug, Clone, PartialEq, Default)]
175pub struct SessionSnapshot {
176 /// 非组字的上屏后联想，只接受显式选择，不由空格、回车或失焦提交。
177 pub prediction: bool,
178 pub scheme: SchemeType,
179 pub local_mode: LocalInputMode,
180 /// The non-letter characters `character` takes in this state: the active local mode's `spelling_symbols` (拆字按光标处列出部件分隔符 `'` 和微软双拼的韵母 `;`), or while nothing is composed the keys that open the `/` and `@` modes. A host or runtime that would send one of these as punctuation sends it as a character instead.
181 pub spelling_symbols: String,
182 pub preedit: String,
183 pub raw_segmentation: String,
184 pub normalized_segmentation: String,
185 pub candidates: Vec<WordItem>,
186 pub dedicated_english: bool,
187 /// The ASCII source text; `caret_position` is a byte offset into it.
188 pub editing_text: String,
189 pub caret_position: usize,
190 pub nine_key_spellings: Vec<String>,
191 /// 九键组字时的读音行：首选候选覆盖的数字显示成它的拼音，其余数字按 `preedit` 原样显示（`xi'an`、`yi'c`、`ni'hao'9`）；首选不是拼音候选时为空。只用于显示，`preedit` 仍是数字。
192 pub nine_key_reading: String,
193 /// 九宫格候选只留单字（`set_nine_key_filter`）。
194 pub nine_key_single_character: bool,
195 /// 九宫格候选按笔画筛选时所选的笔顺前缀（`hspnz`），否则为空。
196 pub nine_key_strokes: String,
197 /// The candidates came from the wubi mixed-pinyin fallback, not the wubi table.
198 pub answered_by_pinyin_fallback: bool,
199 pub wubi_unique_four_code: bool,
200 pub shuangpin_profile: String,
201 pub candidate_sources: Vec<CandidateSource>,
202 /// 当前唯一的连续混合行所携带的语言边界；没有该行时为空，不随普通候选重排而错位。
203 pub multilingual_conversion: Option<crate::multilingual::Conversion>,
204 /// Helpcodes or correction hints.
205 pub candidate_annotations: Vec<String>,
206 /// Whether each candidate answers the whole key rather than a prefix of it or a completion past it.
207 pub candidate_answers_key: Vec<bool>,
208 /// The scheme's openable candidate list is showing (the Korean Hanja list). Hosts read this instead of inferring it from the scheme and a non-empty list.
209 pub candidate_list_open: bool,
210 /// 整句改字时改好的整句，否则为空。宿主在它非空时把它画在行内代替拼音。
211 pub conversion: String,
212 /// 整句改字的光标和光标处那一段，按 `conversion` 的字（Unicode 标量）计：光标在第 `.0` 个字之前，`.0..1` 是候选所替换的那一段；光标在句末时两者都等于字数。不在改字时为 `(0, 0)`。
213 pub conversion_focus: (usize, usize),
214 /// 光标后编辑（`SessionOptions::caret_edit_suffix`）正在生效：候选是光标后那段的，首选前面接着 `caret_edit_prefix`。宿主据此显示模式提示。
215 pub caret_edit_suffix: bool,
216 /// 光标后编辑里首选前面固定的那段文字（已经交出去的部分加上光标前那段的最佳转换）。`candidates` 仍是光标后那段的行，首选显示为这段文字接上 `candidates[0].word`，宿主可以把这几个字画淡；选中首选时上屏的是光标前那段的转换接上这一行。模式不生效时为空。
217 pub caret_edit_prefix: String,
218}